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.

Merge batch 11-03 az: #2608 #2632 #2661 #2657 (#2664)

0xken15438a8580a88c
diff --git a/backend/integration/superTabActivity.test.ts b/backend/integration/superTabActivity.test.ts
index 050393880..37306cd44 100644
--- a/backend/integration/superTabActivity.test.ts
+++ b/backend/integration/superTabActivity.test.ts
@@ -139,6 +139,22 @@ describe('Activity: replies to a person\'s messages', () => {
expect((await items(s.tabId)).map(i => i.messageId)).toEqual([outsiderReply, peerReply])
})
+ it('stops new reply Activity while the thread is unfollowed and resumes after following again', async () => {
+ const s = await scene()
+ const root = await send(s.tabId, s.web, 'Owner root')
+ const first = await send(s.tabId, s.web, 'Peer answers', peer, root)
+ expect((await items(s.tabId)).map(i => i.messageId)).toEqual([first])
+
+ expect((await call('POST', `/api/super-tabs/${s.tabId}/conversations/${s.web}/threads/${root}/follow`, owner, { follow: false })).status).toBe(200)
+ const whileUnfollowed = await send(s.tabId, s.web, 'Peer answers while unfollowed', peer, root)
+ expect((await items(s.tabId)).map(i => i.messageId)).toEqual([first])
+
+ expect((await call('POST', `/api/super-tabs/${s.tabId}/conversations/${s.web}/threads/${root}/follow`, owner, { follow: true })).status).toBe(200)
+ const afterFollowing = await send(s.tabId, s.web, 'Peer answers after following', peer, root)
+ expect((await items(s.tabId)).map(i => i.messageId)).toEqual([afterFollowing, first])
+ expect((await items(s.tabId)).some(i => i.messageId === whileUnfollowed)).toBe(false)
+ })
+
it('lists nothing for a top-level message, or for a message of another person\'s chat', async () => {
const s = await scene()
await send(s.tabId, s.web, 'Top level by peer', peer)
diff --git a/backend/integration/superTabCacheDelta.test.ts b/backend/integration/superTabCacheDelta.test.ts
index 066f384cb..498f4346e 100644
--- a/backend/integration/superTabCacheDelta.test.ts
+++ b/backend/integration/superTabCacheDelta.test.ts
@@ -10,10 +10,10 @@ import type { AuthUser } from '../src/lib/ssoAuth.js'
import { SuperTabStore } from '../src/superTabs/store.js'
import { configureSwarmStamps, swarmTransaction, SwarmCache } from '../src/superTabs/cache.js'
import { MemoryStamps } from '../src/superTabs/cache.test-support.js'
-import { cacheDigest } from '../src/superTabs/cachePatch.js'
+import { cacheDigest, startsOfRule } from '../src/superTabs/cachePatch.js'
import * as parts from '../src/superTabs/parts/index.js'
-import { guardedWrite } from '../src/superTabs/parts/write.js'
-import { DIRECT, readDelta, readLastChangedAt, readParts, type ReadNamed } from '../src/superTabs/cachedReads.js'
+import { guardedWrite, startFinished } from '../src/superTabs/parts/write.js'
+import { DIRECT, deriveLight, readChanged, readDelta, readLastChangedAt, readLight, readParts, type ReadNamed } from '../src/superTabs/cachedReads.js'
import { migrateSwarm } from '../src/superTabs/migration/migrate.js'
import { stableId, type SuperTabState } from '../src/superTabs/model.js'
import { writeLegacySwarm } from '../scripts/swarm-parts/legacy.js'
@@ -74,6 +74,7 @@ const liveOf = <T>(list: parts.Part<T>[]) => list.filter(p => !p.deleted)
describe('the patched cache answers as reads with no cache do', () => {
it('patched entries equal fresh loads after every write', { timeout: 120_000 }, async () => {
+ const sceneStart = Date.now() - 60_000
const { tabId, web, secret } = await scene()
const delta = vi.fn(readDelta(db))
const cache = new SwarmCache(stamps, { delta })
@@ -126,6 +127,28 @@ describe('the patched cache answers as reads with no cache do', () => {
expect(cacheDigest(fresh), `loadActive ${step} ${JSON.stringify(named)}`).toBe(cacheDigest(active))
}
expect(await readLastChangedAt(db, await cache.at([tabId]), tabId)).toBe(await readLastChangedAt(db, DIRECT, tabId))
+ // Spec 2026-11-02 poll cost, Part 1: the change feed, the light base, each machine's host state and the starts of
+ // listed agents, through the patching cache, against direct loads.
+ const view = await cache.at([tabId])
+ expect(cacheDigest(await readChanged(db, view, tabId, sceneStart)), `feed ${step}`).toBe(cacheDigest(await readChanged(db, DIRECT, tabId, sceneStart)))
+ expect(cacheDigest(await readLight(db, view, tabId, { groups: 'working' })), `light ${step}`)
+ .toBe(cacheDigest(await readLight(db, DIRECT, tabId, { groups: 'working' })))
+ const all = await parts.loadAll(db, tabId)
+ for (const machineId of new Set(liveOf(all.agents).map(a => (a.data as { machineId: string }).machineId))) {
+ const agentIds = liveOf(all.agents).filter(a => (a.data as { machineId: string }).machineId === machineId).map(a => a.key)
+ const starts = liveOf(all.starts).filter(s => !startFinished(s.data!) && s.data!.request.machineId === machineId)
+ const groupIds = [...new Set(starts.map(s => s.data!.request.conversationId))]
+ const projectIds = [...new Set(liveOf(all.groups).filter(g => groupIds.includes(g.key)).map(g => g.data!.projectId ?? 'lead'))]
+ const fresh = await db.$transaction(tx => parts.loadLight(tx, tabId, { groups: 'working', agentIds, groupIds, projectIds, machines: false }))
+ // Machines come from their own entry (read/host.ts tabState); the light load leaves them empty.
+ expect(cacheDigest({ ...await deriveLight(db, view, tabId, { groups: 'working', machineId }), machines: [] }), `host state ${machineId} ${step}`)
+ .toBe(cacheDigest(fresh))
+ }
+ const listed = [...new Set(liveOf(all.starts).filter(s => !!s.data!.harnessId).map(s => stableId(s.data!.request.machineId, s.data!.harnessId!)))].sort()
+ if (listed.length) {
+ const named = await view.get(tabId, `startsOf:${JSON.stringify(listed)}`, 'main', () => parts.loadStartsOfAgents(db, tabId, listed), startsOfRule(listed))
+ expect(cacheDigest(named), `startsOf ${step}`).toBe(cacheDigest(await parts.loadStartsOfAgents(db, tabId, listed)))
+ }
}
await check('start')
diff --git a/backend/integration/superTabHotReads.test.ts b/backend/integration/superTabHotReads.test.ts
index 5eecf41c5..540aabb37 100644
--- a/backend/integration/superTabHotReads.test.ts
+++ b/backend/integration/superTabHotReads.test.ts
@@ -285,12 +285,19 @@ describe('hot reads read only what they return (roadmap 2.7)', () => {
})
it('the Lead\'s poll reads only the Swarm\'s open deliveries, not each agent\'s closed ones', () => {
- const rows = reads(entries, 'SuperTabDelivery', ['tabId', 'status'], ['agentId', 'messageId', 'assignmentId', 'conversationId'])
+ // Prisma sends the open statuses as an $or; the claimed-only read ending deliveries makes is the next test's.
+ const rows = reads(entries, 'SuperTabDelivery', ['tabId', 'status', 'or'], ['agentId', 'messageId', 'assignmentId', 'conversationId'])
expect(rows).toHaveLength(1)
// One key past the last of each open status at most: never one per agent.
expect(rows[0]!.keysExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(rows[0]!.nreturned! + 3)
})
+ it('ending deliveries finds the machines to tell from the Swarm\'s claimed ones alone', () => {
+ const rows = reads(entries, 'SuperTabDelivery', ['tabId', 'status'], ['or', 'agentId', 'messageId', 'assignmentId', 'conversationId'])
+ expect(rows.length).toBeGreaterThan(0)
+ for (const row of rows) expect(row.keysExamined, JSON.stringify(plan(rows))).toBeLessThanOrEqual(row.nreturned! + 1)
+ })
+
it('ending work reads only its own open deliveries, never the Swarm\'s others', () => {
const rows = reads(entries, 'SuperTabDelivery', ['tabId', 'assignmentId', 'status'])
expect(rows.length).toBeGreaterThan(0)
diff --git a/backend/integration/superTabLiveness.test.ts b/backend/integration/superTabLiveness.test.ts
index c3d62b0f1..b52f11bdf 100644
--- a/backend/integration/superTabLiveness.test.ts
+++ b/backend/integration/superTabLiveness.test.ts
@@ -1518,6 +1518,17 @@ describe('the delivery poll of an agent with a held delivery', () => {
expect(rows.map(r => [r.id, r.status, r.holdReason])).toEqual([[row.id, 'claimed', 'team_waiting_user']])
})
+ // Spec 2026-11-02 poll cost, Part 3.4: a host asks about its journal's entries; the answer is the delivery's own row.
+ it('answers a receipt from its row and the machine, loading no Swarm parts', async () => {
+ const counted = counting()
+ const f = await swarm({ client: counted.client })
+ const sent = await f.execute({ type: 'message.send', conversationId: f.group, text: 'Status?', replyTo: null, recipientIds: [f.worker] })
+ const row = (await f.timed.deliveries(host, f.tab, f.worker)).find(r => r.messageId === sent.result.messageId)!
+ counted.ops.length = 0
+ expect(await f.timed.deliveryReceipt(host, f.tab, f.worker, row.id)).toEqual({ id: row.id, status: 'queued' })
+ expect(counted.ops.filter(op => /^Swarm(Head|Member|Agent|Group|Machine|Start|Progress)\./.test(op))).toEqual([])
+ })
+
it('answers a worker\'s held delivery from the same reads', async () => {
const counted = counting()
const f = await swarm({ client: counted.client })
@@ -1794,6 +1805,103 @@ describe('the push for a new delivery', () => {
expect(waiting).toEqual([{ machineId: 'lead-host', tabId: f.tab, agentId: f.lead }])
})
+ // Spec 2026-11-02 poll cost, Part 3.2: a held delivery is read only every 30 s, so ending it must say so at once.
+ // Final review, Important 4: a host holds a claimed delivery locally for 30 s before it says `hold`.
+ it('tells the machine when a claimed delivery, not yet held, is answered by its agent', async () => {
+ const { waiting, hooks } = announcing()
+ const f = await swarm({ hooks })
+ const sent = await f.execute({ type: 'message.send', conversationId: f.group, text: 'Status?', replyTo: null, recipientIds: [f.worker] })
+ const row = (await f.timed.deliveries(host, f.tab, f.worker)).find(r => r.messageId === sent.result.messageId)!
+ await f.timed.delivery(host, f.tab, f.worker, row.id, { type: 'claim', claimId: 'claim-1' })
+ waiting.length = 0
+ await f.execute({ type: 'message.send', conversationId: f.group, text: 'Done.', replyTo: sent.result.messageId as string, recipientIds: [] }, host, f.worker)
+ expect(waiting).toContainEqual({ machineId: 'test-host', tabId: f.tab, agentId: f.worker })
+ })
+
+ // Cleo, reviewing #2632: each agent reply answers a delivery, and each machine told reads that agent's list.
+ describe('ending deliveries tells only the machines holding what ended', () => {
+ const claimedFor = async (f: Awaited<ReturnType<typeof swarm>>, agentId: string, text: string, claimId: string) => {
+ const sent = await f.execute({ type: 'message.send', conversationId: f.group, text, replyTo: null, recipientIds: [agentId] })
+ const row = (await f.timed.deliveries(host, f.tab, agentId)).find(r => r.messageId === sent.result.messageId)!
+ await f.timed.delivery(host, f.tab, agentId, row.id, { type: 'claim', claimId })
+ return sent.result.messageId as string
+ }
+
+ it('an agent answering one delivery tells its own machine, not another agent\'s holding a claim', async () => {
+ const { waiting, hooks } = announcing()
+ const f = await swarm({ hooks })
+ const forWorker = await claimedFor(f, f.worker, 'For the worker', 'claim-worker')
+ await claimedFor(f, f.lead, 'For the lead', 'claim-lead')
+ waiting.length = 0
+ await f.execute({ type: 'message.send', conversationId: f.group, text: 'Done.', replyTo: forWorker, recipientIds: [] }, host, f.worker)
+ expect(waiting).toContainEqual({ machineId: 'test-host', tabId: f.tab, agentId: f.worker })
+ // The reply is itself a new delivery for the Lead, told once for it: not told again for the claim it holds.
+ expect(waiting.filter(w => w.agentId === f.lead)).toHaveLength(1)
+ })
+
+ /** A conversation with no task in it, so its agent may leave and it may be archived, with a claimed delivery of the worker's. */
+ const asideWithClaim = async (f: Awaited<ReturnType<typeof swarm>>) => {
+ const other = (await f.execute({ type: 'conversation.create', title: 'Aside', brief: 'On the side', checks: [] })).result.conversationId as string
+ await f.execute({ type: 'conversation.agent', conversationId: other, agentId: f.worker, present: true, lead: false })
+ const aside = await f.execute({ type: 'message.send', conversationId: other, text: 'Aside', replyTo: null, recipientIds: [f.worker] })
+ const row = (await f.timed.deliveries(host, f.tab, f.worker)).find(r => r.messageId === aside.result.messageId)!
+ await f.timed.delivery(host, f.tab, f.worker, row.id, { type: 'claim', claimId: 'claim-worker' })
+ return other
+ }
+
+ it('an agent leaving a conversation tells its machine, not another\'s', async () => {
+ const { waiting, hooks } = announcing()
+ const f = await swarm({ hooks })
+ const other = await asideWithClaim(f)
+ await claimedFor(f, f.lead, 'For the lead', 'claim-lead')
+ waiting.length = 0
+ await f.execute({ type: 'conversation.agent', conversationId: other, agentId: f.worker, present: false, lead: false })
+ expect(waiting).toContainEqual({ machineId: 'test-host', tabId: f.tab, agentId: f.worker })
+ expect(waiting).not.toContainEqual({ machineId: 'lead-host', tabId: f.tab, agentId: f.lead })
+ })
+
+ it('a conversation archived tells those holding its deliveries, not one holding another conversation\'s', async () => {
+ const { waiting, hooks } = announcing()
+ const f = await swarm({ hooks })
+ const other = await asideWithClaim(f)
+ await claimedFor(f, f.lead, 'For the lead', 'claim-lead')
+ waiting.length = 0
+ await f.execute({ type: 'conversation.archive', conversationId: other, archived: true })
+ expect(waiting).toContainEqual({ machineId: 'test-host', tabId: f.tab, agentId: f.worker })
+ expect(waiting).not.toContainEqual({ machineId: 'lead-host', tabId: f.tab, agentId: f.lead })
+ })
+
+ it('nothing ended tells nobody', async () => {
+ const { waiting, hooks } = announcing()
+ const f = await swarm({ hooks })
+ const other = (await f.execute({ type: 'conversation.create', title: 'Empty', brief: 'On the side', checks: [] })).result.conversationId as string
+ await f.execute({ type: 'conversation.agent', conversationId: other, agentId: f.worker, present: true, lead: false })
+ await claimedFor(f, f.lead, 'For the lead', 'claim-lead')
+ waiting.length = 0
+ await f.execute({ type: 'conversation.agent', conversationId: other, agentId: f.worker, present: false, lead: false })
+ expect(waiting).toEqual([])
+ })
+ })
+
+ it('tells the machine when a held delivery is answered by its agent', async () => {
+ const { waiting, hooks } = announcing()
+ const f = await swarm({ hooks })
+ const sent = await f.execute({ type: 'message.send', conversationId: f.group, text: 'Status?', replyTo: null, recipientIds: [f.worker] })
+ const row = (await f.timed.deliveries(host, f.tab, f.worker)).find(r => r.messageId === sent.result.messageId)!
+ await f.timed.delivery(host, f.tab, f.worker, row.id, { type: 'claim', claimId: 'claim-1' })
+ await f.timed.delivery(host, f.tab, f.worker, row.id, { type: 'hold', claimId: 'claim-1', reason: 'team_waiting_draft' })
+ waiting.length = 0
+ await f.execute({ type: 'message.send', conversationId: f.group, text: 'Done.', replyTo: sent.result.messageId as string, recipientIds: [] }, host, f.worker)
+ expect(waiting).toContainEqual({ machineId: 'test-host', tabId: f.tab, agentId: f.worker })
+ })
+
+ it('tells the machine when a terminal request waits for its agent', async () => {
+ const heard: Array<{ machineId: string; tabId: string; agentId: string }> = []
+ const f = await swarm({ hooks: { terminalWaiting: w => { heard.push(w) } } })
+ await f.execute({ type: 'agent.screen', agentId: f.worker, scrollback: 50 })
+ expect(heard).toEqual([{ machineId: 'test-host', tabId: f.tab, agentId: f.worker }])
+ })
+
it('announces the update request the Lead\'s own poll writes for it', async () => {
const { waiting, hooks } = announcing()
const f = await swarm({ hooks })
diff --git a/backend/src/lib/bus.ts b/backend/src/lib/bus.ts
index 48b977577..8840cf829 100644
--- a/backend/src/lib/bus.ts
+++ b/backend/src/lib/bus.ts
@@ -866,7 +866,8 @@ export function subscribeDeviceMachineListChanged(userId: string, cb: (msg: Devi
// Per-MACHINE Swarm deliveries: a delivery committed for one of this machine's agents (superTabs/store.ts deliveriesWaiting),
// on some REST worker; the worker holding that machine's adapter socket tells its host (lib/swarmDeliveryPushes.ts).
-export interface SwarmDeliveriesMsg { tabId: string; agentId: string }
+/** `terminal`: a terminal request waits, not a delivery (lib/swarmDeliveryPushes.ts announceSwarmTerminal). */
+export interface SwarmDeliveriesMsg { tabId: string; agentId: string; terminal?: true }
const swarmDeliveriesChannel = (machineId: string): string => `swarm-deliveries:${machineId}`
diff --git a/backend/src/lib/deliveryCalls.test.ts b/backend/src/lib/deliveryCalls.test.ts
new file mode 100644
index 000000000..43ac9eb85
--- /dev/null
+++ b/backend/src/lib/deliveryCalls.test.ts
@@ -0,0 +1,29 @@
+import { afterEach, expect, it, vi } from 'vitest'
+import { noteClaim, recordDeliveryCall, startDeliveryCalls } from './deliveryCalls.js'
+
+afterEach(() => vi.useRealTimers())
+
+it('counts re-claims, receipt 403/404 and holds by reason, and logs nothing in an empty window (spec 2026-11-02 poll cost, Part 0)', () => {
+ vi.useFakeTimers()
+ const log = vi.fn()
+ const stop = startDeliveryCalls({ everyMs: 60_000, log })
+ vi.advanceTimersByTime(60_000)
+ expect(log).not.toHaveBeenCalled()
+ recordDeliveryCall('reclaim'); recordDeliveryCall('reclaim')
+ recordDeliveryCall('receipt403'); recordDeliveryCall('receipt404')
+ recordDeliveryCall('hold', 'team_waiting_user'); recordDeliveryCall('hold', 'team_waiting_user'); recordDeliveryCall('hold', 'dialog')
+ vi.advanceTimersByTime(60_000)
+ expect(log).toHaveBeenCalledWith('delivery calls', { windowMs: 60_000, reclaims: 2, receipt403: 1, receipt404: 1,
+ holds: { team_waiting_user: 2, dialog: 1 } })
+ stop()
+})
+
+it('a claim of the same delivery within 10 s counts as a re-claim, a later one does not', () => {
+ vi.useFakeTimers()
+ const log = vi.fn()
+ const stop = startDeliveryCalls({ everyMs: 60_000, log })
+ noteClaim('d1', 1_000); noteClaim('d1', 2_000); noteClaim('d1', 13_000); noteClaim('d2', 13_500)
+ vi.advanceTimersByTime(60_000)
+ expect(log.mock.calls[0]![1]).toMatchObject({ reclaims: 1 })
+ stop()
+})
diff --git a/backend/src/lib/deliveryCalls.ts b/backend/src/lib/deliveryCalls.ts
new file mode 100644
index 000000000..8f5d724d9
--- /dev/null
+++ b/backend/src/lib/deliveryCalls.ts
@@ -0,0 +1,42 @@
+/**
+ * How daemons call the delivery routes, logged every minute as `delivery calls` (spec 2026-11-02 poll cost, Part 0): claims
+ * of a delivery its host claimed again within 10 s (a held delivery re-claimed each second, cli host.ts), receipt reads
+ * refused with 403 or 404 (a journal entry asked about forever), and holds by reason. Counts only, never an id.
+ */
+import { logger } from '../utils/logger.js'
+
+type Event = 'reclaim' | 'receipt403' | 'receipt404' | 'hold'
+let counts = { reclaims: 0, receipt403: 0, receipt404: 0, holds: {} as Record<string, number> }
+const empty = () => ({ reclaims: 0, receipt403: 0, receipt404: 0, holds: {} as Record<string, number> })
+
+export function recordDeliveryCall(event: Event, reason?: string): void {
+ if (event === 'reclaim') counts.reclaims++
+ else if (event === 'receipt403') counts.receipt403++
+ else if (event === 'receipt404') counts.receipt404++
+ else counts.holds[reason ?? 'other'] = (counts.holds[reason ?? 'other'] ?? 0) + 1
+}
+
+/** Each delivery's last claim on this process, so a host claiming the same delivery again within RECLAIM_MS counts as a
+ * re-claim. Bounded: the oldest are forgotten first. */
+const RECLAIM_MS = 10_000, CLAIMS_KEPT = 10_000
+const lastClaims = new Map<string, number>()
+export function noteClaim(deliveryId: string, now: number): void {
+ const last = lastClaims.get(deliveryId)
+ if (last !== undefined && now - last < RECLAIM_MS) counts.reclaims++
+ lastClaims.delete(deliveryId)
+ lastClaims.set(deliveryId, now)
+ if (lastClaims.size > CLAIMS_KEPT) lastClaims.delete(lastClaims.keys().next().value!)
+}
+
+export function startDeliveryCalls({ everyMs = 60_000, log = (message: string, context: Record<string, unknown>) => logger.info(message, context) }:
+ { everyMs?: number; log?: (message: string, context: Record<string, unknown>) => void } = {}): () => void {
+ let since = Date.now()
+ const timer = setInterval(() => {
+ const now = Date.now(), window = counts
+ counts = empty()
+ if (window.reclaims || window.receipt403 || window.receipt404 || Object.keys(window.holds).length) log('delivery calls', { windowMs: now - since, ...window })
+ since = now
+ }, everyMs)
+ timer.unref()
+ return () => clearInterval(timer)
+}
diff --git a/backend/src/lib/routeLatency.test.ts b/backend/src/lib/routeLatency.test.ts
index cad93b4f9..c9e64a4f6 100644
--- a/backend/src/lib/routeLatency.test.ts
+++ b/backend/src/lib/routeLatency.test.ts
@@ -1,6 +1,6 @@
import Fastify from 'fastify'
import { expect, it } from 'vitest'
-import { createRouteLatency, registerRouteLatency } from './routeLatency.js'
+import { createRouteLatency, markNothingNew, registerRouteLatency } from './routeLatency.js'
type Logged = { message: string; context: Record<string, unknown> }
type Route = { n: number; p50: number; p95: number; max: number }
@@ -81,3 +81,27 @@ it('counts each route by kind of client, from its user agent and whether it read
expect(JSON.stringify(logs)).not.toMatch(/agent-secret|curl|Chrome/)
await app.close()
})
+
+it('a reply marked nothing-new counts as empty, and bytes are summed per route (spec 2026-11-02 poll cost, Part 0)', async () => {
+ const logs: Logged[] = []
+ const app = Fastify()
+ const l = registerRouteLatency(app, { pod: 'p', log: (message, context) => logs.push({ message, context }) })
+ app.get('/poll/:id', async (request) => {
+ if ((request.params as { id: string }).id === 'none') markNothingNew(request)
+ return { rows: (request.params as { id: string }).id === 'none' ? [] : ['abc'] }
+ })
+ await app.inject('/poll/none'); await app.inject('/poll/none'); await app.inject('/poll/some')
+ l.flush()
+ const route = (logs[0]!.context.routes as Record<string, { n: number; empty?: number; bytes?: number }>)['GET /poll/:id']!
+ expect(route.n).toBe(3)
+ expect(route.empty).toBe(2)
+ expect(route.bytes).toBe(2 * '{"rows":[]}'.length + '{"rows":["abc"]}'.length)
+ await app.close()
+})
+
+it('leaves empty and bytes out of a route that has none', () => {
+ const { l, routes } = latency()
+ l.record('GET /a', 1)
+ l.flush()
+ expect(routes()['GET /a']).toEqual({ n: 1, p50: 1, p95: 1, max: 1 })
+})
diff --git a/backend/src/lib/routeLatency.ts b/backend/src/lib/routeLatency.ts
index def7155b7..2c53d21f6 100644
--- a/backend/src/lib/routeLatency.ts
+++ b/backend/src/lib/routeLatency.ts
@@ -1,6 +1,6 @@
import { hostname } from 'node:os'
import { performance } from 'node:perf_hooks'
-import type { FastifyInstance } from 'fastify'
+import type { FastifyInstance, FastifyRequest } from 'fastify'
import { logger } from '../utils/logger.js'
/**
@@ -10,7 +10,15 @@ import { logger } from '../utils/logger.js'
* percentiles; its count and max cover every request.
*/
-type Window = { n: number; max: number; samples: number[]; clients: Record<string, number> }
+type Window = { n: number; max: number; samples: number[]; clients: Record<string, number>; empty: number; bytes: number }
+
+/** A reply that carried nothing new for its reader (an empty poll), and each reply's size: what polling costs for nothing
+ * (spec 2026-11-02 poll cost, Part 0). */
+export type ReplyFacts = { empty?: boolean; bytes?: number }
+
+const nothingNew = new WeakSet<object>(), replyBytes = new WeakMap<object, number>()
+/** Says this request's reply carries nothing new for its reader: a poll that found no change. */
+export function markNothingNew(request: FastifyRequest): void { nothingNew.add(request) }
/** Who sent a request, from what every client sends anyway (2026-10-31: who reads Swarm messages so often was unknown):
* the web build's browser, the Desktop and phone apps' Dart client, the CLI daemon's Node client, and a read as an agent
@@ -37,7 +45,7 @@ export type RouteLatencyOptions = {
log?: (message: string, context: Record<string, unknown>) => void
}
-export type RouteLatency = { record(route: string, ms: number, client?: ClientKind): void; flush(): void }
+export type RouteLatency = { record(route: string, ms: number, client?: ClientKind, facts?: ReplyFacts): void; flush(): void }
const OTHER = 'other'
@@ -49,15 +57,17 @@ export function createRouteLatency({ pod = `${hostname()}:${process.pid}`, maxSa
log = (m, c) => logger.info(m, c) }: RouteLatencyOptions = {}): RouteLatency {
let routes = new Map<string, Window>(), started = performance.now()
- const record = (route: string, ms: number, client?: ClientKind) => {
+ const record = (route: string, ms: number, client?: ClientKind, facts: ReplyFacts = {}) => {
let window = routes.get(route)
if (!window) {
const key = routes.size >= maxRoutes - 1 ? OTHER : route
window = routes.get(key)
- if (!window) routes.set(key, window = { n: 0, max: 0, samples: [], clients: {} })
+ if (!window) routes.set(key, window = { n: 0, max: 0, samples: [], clients: {}, empty: 0, bytes: 0 })
}
window.n++
if (client) window.clients[client] = (window.clients[client] ?? 0) + 1
+ if (facts.empty) window.empty++
+ if (facts.bytes) window.bytes += facts.bytes
if (ms > window.max) window.max = ms
if (window.samples.length < maxSamples) window.samples.push(ms)
else {
@@ -71,7 +81,7 @@ export function createRouteLatency({ pod = `${hostname()}:${process.pid}`, maxSa
const sorted = w.samples.sort((a, b) => a - b)
const mean = sorted.reduce((total, ms) => total + ms, 0) / (sorted.length || 1)
return { route, totalMs: mean * w.n, stats: { n: w.n, p50: round(percentile(sorted, 50)), p95: round(percentile(sorted, 95)), max: round(w.max),
- ...(Object.keys(w.clients).length ? { clients: w.clients } : {}) } }
+ ...(Object.keys(w.clients).length ? { clients: w.clients } : {}), ...(w.empty ? { empty: w.empty } : {}), ...(w.bytes ? { bytes: w.bytes } : {}) } }
}).sort((a, b) => b.totalMs - a.totalMs).slice(0, top)
log('route latency', { pod, windowMs: Math.round(performance.now() - started), requests: [...routes.values()].reduce((total, w) => total + w.n, 0),
routes: Object.fromEntries(rows.map(r => [r.route, r.stats])) })
@@ -84,9 +94,15 @@ export function createRouteLatency({ pod = `${hostname()}:${process.pid}`, maxSa
/** Records every response's time under its route pattern. Returns the recorder, for a flush on shutdown. */
export function registerRouteLatency(app: FastifyInstance, options: RouteLatencyOptions = {}): RouteLatency {
const latency = createRouteLatency(options)
+ app.addHook('onSend', (request, _reply, payload, done) => {
+ const bytes = typeof payload === 'string' ? Buffer.byteLength(payload) : Buffer.isBuffer(payload) ? payload.length : 0
+ if (bytes) replyBytes.set(request, bytes)
+ done(null, payload)
+ })
app.addHook('onResponse', (request, reply, done) => {
const asAgent = typeof (request.query as Record<string, unknown> | undefined)?.asAgentId === 'string'
- latency.record(`${request.method} ${request.routeOptions.url ?? 'unrouted'}`, reply.elapsedTime, clientKind(request.headers['user-agent'], asAgent))
+ latency.record(`${request.method} ${request.routeOptions.url ?? 'unrouted'}`, reply.elapsedTime, clientKind(request.headers['user-agent'], asAgent),
+ { empty: nothingNew.has(request), bytes: replyBytes.get(request) })
done()
})
return latency
diff --git a/backend/src/lib/swarmDeliveryPushes.test.ts b/backend/src/lib/swarmDeliveryPushes.test.ts
index bc762ff92..1a26e337d 100644
--- a/backend/src/lib/swarmDeliveryPushes.test.ts
+++ b/backend/src/lib/swarmDeliveryPushes.test.ts
@@ -19,7 +19,7 @@ vi.mock('./bus.js', () => ({
publishSwarmDeliveries: async (machineId: string, msg: unknown) => { bus.publish(machineId, JSON.parse(JSON.stringify(msg))); return 1 },
}))
-import { announceSwarmDeliveries, relaySwarmDeliveries } from './swarmDeliveryPushes.js'
+import { announceSwarmDeliveries, announceSwarmTerminal, relaySwarmDeliveries } from './swarmDeliveryPushes.js'
const pushes = (send: ReturnType<typeof vi.fn>) => send.mock.calls.map(([frame]) => frame)
const told = (payload: object) => ({ t: 'down', connId: '', frame: { type: 'super_tab_deliveries', payload } })
@@ -63,6 +63,28 @@ describe('Swarm delivery pushes on a daemon socket', () => {
expect(pushes(send)).toEqual([])
})
+ // Spec 2026-11-02 poll cost, Part 4.2: a terminal request waiting for this machine, as a `__` control frame an older
+ // daemon drops (cli gateway backendControl); the newer one picks it up at once instead of every 3 s.
+ it('carries a terminal request the store announces to its machine as __terminal_waiting', async () => {
+ const a = vi.fn(), b = vi.fn()
+ await relaySwarmDeliveries('machine-a', a)
+ await relaySwarmDeliveries('machine-b', b)
+ a.mockClear(); b.mockClear()
+ announceSwarmTerminal({ machineId: 'machine-a', tabId: 'tab-1', agentId: 'agent-1' })
+ await vi.waitFor(() => expect(pushes(a)).toEqual([{ t: 'down', connId: '', frame: { type: '__terminal_waiting', payload: { tabId: 'tab-1', agentId: 'agent-1' } } }]))
+ expect(pushes(b)).toEqual([])
+ })
+
+ it('a frame an older daemon sees is a __ control frame or a delivery push it already reads', async () => {
+ const send = vi.fn()
+ await relaySwarmDeliveries('machine-a', send)
+ send.mockClear()
+ announceSwarmDeliveries({ machineId: 'machine-a', tabId: 'tab-1', agentId: 'agent-1' })
+ announceSwarmTerminal({ machineId: 'machine-a', tabId: 'tab-1', agentId: 'agent-1' })
+ await vi.waitFor(() => expect(pushes(send)).toHaveLength(2))
+ expect(pushes(send).map(f => (f as { frame: { type: string } }).frame.type).every(type => type === 'super_tab_deliveries' || type.startsWith('__'))).toBe(true)
+ })
+
it('passes on nothing but a Swarm and an agent', async () => {
const send = vi.fn()
await relaySwarmDeliveries('machine-a', send)
diff --git a/backend/src/lib/swarmDeliveryPushes.ts b/backend/src/lib/swarmDeliveryPushes.ts
index 0e028e9e4..00ee1aa01 100644
--- a/backend/src/lib/swarmDeliveryPushes.ts
+++ b/backend/src/lib/swarmDeliveryPushes.ts
@@ -25,8 +25,11 @@ export async function relaySwarmDeliveries(machineId: string, send: (frame: unkn
let unsubscribe: () => void
try {
unsubscribe = await subscribeSwarmDeliveries(machineId, msg => {
- const { tabId, agentId } = (msg && typeof msg === 'object' ? msg : {}) as Record<string, unknown>
- if (typeof tabId === 'string' && typeof agentId === 'string') tell({ tabId, agentId })
+ const { tabId, agentId, terminal } = (msg && typeof msg === 'object' ? msg : {}) as Record<string, unknown>
+ if (typeof tabId !== 'string' || typeof agentId !== 'string') return
+ // A terminal request waiting for this machine (announceSwarmTerminal): a `__` control frame, which an older daemon drops.
+ if (terminal === true) send({ t: 'down', connId: '', frame: { type: '__terminal_waiting', payload: { tabId, agentId } } })
+ else tell({ tabId, agentId })
})
} catch (error) {
// Not told that the server pushes, the host keeps reading each second: nothing waits longer, only the saving is lost.
@@ -46,3 +49,10 @@ export async function relaySwarmDeliveries(machineId: string, send: (frame: unkn
export function announceSwarmDeliveries({ machineId, tabId, agentId }: DeliveriesWaiting): void {
void publishSwarmDeliveries(machineId, { tabId, agentId })
}
+
+/** The store's `terminalWaiting`: a terminal request for one of this machine's agents, on the same channel as deliveries, so
+ * the daemon picks it up at once rather than on its next poll (spec 2026-11-02 poll cost, Part 4.2). Dropped when Redis is
+ * away; the daemon's fallback poll still finds it within the 10 s pickup deadline. */
+export function announceSwarmTerminal({ machineId, tabId, agentId }: DeliveriesWaiting): void {
+ void publishSwarmDeliveries(machineId, { tabId, agentId, terminal: true })
+}
diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.ts
index 8db0c33cd..d203e3205 100644
--- a/backend/src/routes/superTabs.ts
+++ b/backend/src/routes/superTabs.ts
@@ -1,4 +1,4 @@
-import type { FastifyInstance, FastifyReply } from 'fastify'
+import type { FastifyInstance, FastifyReply, FastifyRequest } from 'fastify'
import { z, ZodError } from 'zod'
import { prisma } from '../lib/prisma.js'
import { env } from '../config/env.js'
@@ -38,6 +38,18 @@ import { isTeamSession, TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE } from '../li
import type { AuthUser } from '../lib/ssoAuth.js'
import { DEFAULT_DAYS, MAX_DAYS } from '../superTabs/costs/read.js'
import { WORKSPACE_ACCESS_REVOKED } from '../superTabs/workspaceStore.js'
+import { markNothingNew } from '../lib/routeLatency.js'
+
+/** Runs a poll and marks its reply nothing-new for `route latency` when `empty` says so (spec 2026-11-02 poll cost, Part 0). */
+const noting = <T>(req: FastifyRequest, run: () => Promise<T>, empty: (result: T) => boolean) => async (): Promise<T> => {
+ const result = await run()
+ if (empty(result)) markNothingNew(req)
+ return result
+}
+/** A change read that found nothing: no reload, no head, and every list of changed parts empty. */
+const nothingChanged = (changes: object): boolean =>
+ (changes as { reload?: unknown }).reload === false && (changes as { head?: unknown }).head == null
+ && Object.values(changes).every(value => !Array.isArray(value) || value.length === 0)
const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)
const tabParams = z.object({ tabId: id })
@@ -230,7 +242,7 @@ const updateRequired = (_req: unknown, reply: FastifyReply) => sendError(reply,
/** The store this server runs on. Loaded only here: importing the bus opens its Redis connections. */
async function productionStore(github: GitHubTokens | null): Promise<SuperTabStore> {
- const [bus, { announceSwarmDeliveries }, { announceSwarmHostChanges }, { announceSwarmChanges }, { tellSessionViewers }] = await Promise.all([
+ const [bus, { announceSwarmDeliveries, announceSwarmTerminal }, { announceSwarmHostChanges }, { announceSwarmChanges }, { tellSessionViewers }] = await Promise.all([
import('../lib/bus.js'), import('../lib/swarmDeliveryPushes.js'), import('../lib/swarmHostPushes.js'), import('../lib/swarmClientPushes.js'),
import('./harnessLinks.js')])
return new SuperTabStore(prisma, Date.now, attachmentsFromEnv(env),
@@ -245,7 +257,7 @@ async function productionStore(github: GitHubTokens | null): Promise<SuperTabSto
polls: redisPollMemory(bus.pub),
// What each machine's full report saw, so its heartbeats skip the Swarm load, and one sweep clock per Swarm (DB 2.5).
reports: redisReportMemory(bus.pub),
- deliveriesWaiting: announceSwarmDeliveries,
+ deliveriesWaiting: announceSwarmDeliveries, terminalWaiting: announceSwarmTerminal,
// And each machine whose host read a commit changed, so hosts read their Swarm changes only when told (WS Phase 2a).
hostsChanged: announceSwarmHostChanges,
// And each person in the Swarm, so their apps read it when told instead of every 3–15 s (WS Phase 2a).
@@ -461,7 +473,7 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
(req, reply) => respond(reply, () => store.join(req.user!, req.params.tabId, req.body)))
app.get('/api/super-tabs/hosts/:machineId', updateRequired)
app.post<{ Params: z.infer<typeof hostParams> }>('/api/super-tabs/hosts/:machineId/terminal', { preHandler: validateParams(hostParams) },
- (req, reply) => respond(reply, () => store.hostTerminal(req.user!, req.params.machineId)))
+ (req, reply) => respond(reply, noting(req, () => store.hostTerminal(req.user!, req.params.machineId), picked => !picked.length)))
// Long-polls about 20 seconds; a request still waiting then answers `pending` and is read again.
app.get<{ Params: z.infer<typeof terminalParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId/terminal/:requestId',
{ preHandler: [validateParams(terminalParams), validateQuery(agentQuery)] },
@@ -475,7 +487,7 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
(req, reply) => respond(reply, () => reads.firstLoad(req.user!, req.params.tabId, req.query.asAgentId)))
app.get<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof changesQuery> }>('/api/super-tabs/:tabId/changes',
{ preHandler: [validateParams(tabParams), validateQuery(changesQuery)] },
- (req, reply) => respond(reply, () => reads.changes(req.user!, req.params.tabId, req.query.cursor, req.query.asAgentId)))
+ (req, reply) => respond(reply, noting(req, () => reads.changes(req.user!, req.params.tabId, req.query.cursor, req.query.asAgentId), nothingChanged)))
// A person's unread threads and each chat's latest message (read/inbox.ts): read when the change feed moves, never on a timer.
app.get<{ Params: z.infer<typeof tabParams>; Querystring: z.infer<typeof noQuery> }>('/api/super-tabs/:tabId/inbox',
{ preHandler: [validateParams(tabParams), validateQuery(noQuery)] }, async (req, reply) => {
@@ -606,7 +618,8 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
(req, reply) => respond(reply, () => store.start(req.user!, req.params.tabId, req.params.startId, req.query.asAgentId)))
app.get<{ Params: z.infer<typeof messageParams>; Querystring: z.infer<typeof messageQuery> }>('/api/super-tabs/:tabId/conversations/:conversationId/messages',
{ preHandler: [validateParams(messageParams), validateQuery(messageQuery)] },
- (req, reply) => respond(reply, () => store.messages(req.user!, req.params.tabId, req.params.conversationId, req.query, req.query.asAgentId)))
+ (req, reply) => respond(reply, noting(req, () => store.messages(req.user!, req.params.tabId, req.params.conversationId, req.query, req.query.asAgentId),
+ page => req.query.after !== undefined && !page.messages.length)))
// A fresh short-lived link to one file of one message, for whoever may read that message now (superTabs/fileLinks.ts).
app.get<{ Params: z.infer<typeof fileParams>; Querystring: z.infer<typeof agentQuery> }>('/api/super-tabs/:tabId/conversations/:conversationId/messages/:messageId/attachments/:attachmentId',
{ preHandler: [validateParams(fileParams), validateQuery(agentQuery)] },
@@ -658,7 +671,7 @@ export async function superTabRoutes(app: FastifyInstance, options: { store?: Su
(req, reply) => respond(reply, () => store.routeDecision(req.user!, req.params.tabId, req.params.decisionId, req.query.asAgentId)))
app.get<{ Params: z.infer<typeof deliveryParams> }>('/api/super-tabs/:tabId/agents/:agentId/deliveries',
{ preHandler: validateParams(deliveryParams) },
- (req, reply) => respond(reply, () => store.deliveries(req.user!, req.params.tabId, req.params.agentId)))
+ (req, reply) => respond(reply, noting(req, () => store.deliveries(req.user!, req.params.tabId, req.params.agentId), open => !open.length)))
app.post<{ Params: z.infer<typeof deliveryActionParams>; Body: z.infer<typeof deliveryAction> }>('/api/super-tabs/:tabId/agents/:agentId/deliveries/:deliveryId',
{ bodyLimit: HOT_BODY_LIMIT, preHandler: [validateParams(deliveryActionParams), validateBody(deliveryAction)] },
(req, reply) => respond(reply, () => store.delivery(req.user!, req.params.tabId, req.params.agentId, req.params.deliveryId, req.body)))
diff --git a/backend/src/server.ts b/backend/src/server.ts
index 58b9a0002..687637186 100644
--- a/backend/src/server.ts
+++ b/backend/src/server.ts
@@ -25,6 +25,7 @@ import { prisma } from './lib/prisma.js'
import { backendReadinessChecks, createReadiness, drainBeforeClosing, processDrain } from './lib/readiness.js'
import { configureSwarmStamps } from './superTabs/cache.js'
import { startCacheStats } from './superTabs/cacheStats.js'
+import { startDeliveryCalls } from './lib/deliveryCalls.js'
import { readDelta } from './superTabs/cachedReads.js'
import { watchGroupIndexes } from './superTabs/parts/indexed.js'
import { startMessageReadStats } from './superTabs/messageReadStats.js'
@@ -151,6 +152,8 @@ async function start(): Promise<void> {
const stopQueryStats = startQueryStats()
// Every minute, how often Swarm transactions ran again and commands loaded twice (superTabs/retryStats.ts, DB 2.1).
const stopRetryStats = startRetryStats()
+ // Every minute: re-claims, refused receipt reads and holds, what the daemons' delivery loop costs (spec 2026-11-02 poll cost).
+ const stopDeliveryCalls = startDeliveryCalls()
// Every minute: how the Swarm read cache served reads (hit, patched, loaded in full and why) and what its checks found.
const stopCacheStats = startCacheStats()
const stopRouteLatency = startRouteLatency(registerRouteLatency(app))
@@ -243,6 +246,7 @@ async function start(): Promise<void> {
// The last partial minute of these logs, once the drain and the usage flush have run their queries.
stopQueryStats()
stopRetryStats()
+ stopDeliveryCalls()
stopCacheStats()
stopRouteLatency()
stopMachineReportLog()
diff --git a/backend/src/superTabs/activity.ts b/backend/src/superTabs/activity.ts
index fffe6308c..0ff0e4cbc 100644
--- a/backend/src/superTabs/activity.ts
+++ b/backend/src/superTabs/activity.ts
@@ -52,13 +52,22 @@ export async function writeReplyActivity(tx: Tx, tabId: string, messages: Messag
// By id through its index, as a plain $in (parts/indexed.ts): Prisma's `in` plans slowly.
const found = new Map((await readBy(tx, 'SuperTabMessage', 'id', [{ $match: { _id: { $in: ids }, tabId } }, { $project: { conversationId: 1, author: 1 } }]))
.map(r => [r._id as string, { conversationId: r.conversationId as string, author: r.author }]))
- const data = replies.flatMap(m => {
+ const recipients = replies.map(m => {
const people = new Set([m.thread!, m.replyTo].flatMap(target => {
const row = target ? found.get(target) : undefined
const by = row?.author as { kind?: string; id?: string } | undefined
return row && row.conversationId === m.conversationId && by?.kind === 'person' && by.id && !own(m.author, by.id) ? [by.id] : []
}))
- return [...people].map(personId => ({ id: stableId(tabId, 'reply', m.id, personId), tabId, personId, kind: 'reply', conversationId: m.conversationId,
+ return { message: m, people }
+ })
+ const markIds = [...new Set(recipients.flatMap(({ message, people }) => [...people].map(personId =>
+ stableId(tabId, message.conversationId, message.thread!, personId))))]
+ const marks = markIds.length ? await tx.superTabThreadMark.aggregateRaw({ pipeline: [
+ { $match: { _id: { $in: markIds } } }, { $project: { _id: 1, follow: 1 } },
+ ] }) as unknown as Array<{ _id: string; follow?: boolean | null }> : []
+ const unfollowed = new Set(marks.filter(mark => mark.follow === false).map(mark => mark._id))
+ const data = recipients.flatMap(({ message: m, people }) => {
+ return [...people].filter(personId => !unfollowed.has(stableId(tabId, m.conversationId, m.thread!, personId))).map(personId => ({ id: stableId(tabId, 'reply', m.id, personId), tabId, personId, kind: 'reply', conversationId: m.conversationId,
messageId: m.id, threadId: m.thread!, actorKind: m.author.kind, actorId: m.author.id, emoji: null, createdAt: new Date(now), readAt: null,
...sequences.has(m.id) ? { sequence: sequences.get(m.id)! } : {}, ...m.alsoInChat ? { alsoInChat: true } : {} }))
})
diff --git a/backend/src/superTabs/cache.test.ts b/backend/src/superTabs/cache.test.ts
index 36e53d297..edf898f27 100644
--- a/backend/src/superTabs/cache.test.ts
+++ b/backend/src/superTabs/cache.test.ts
@@ -1,7 +1,7 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
import { configureSwarmStamps, freeze, noteChange, readStamps, sizeOf, stampOwed, swarmTransaction, SwarmCache } from './cache.js'
import { MemoryStamps } from './cache.test-support.js'
-import { machinesRule, type PatchRule } from './cachePatch.js'
+import { feedRule, machinesRule, type PatchRule } from './cachePatch.js'
import { logger } from '../utils/logger.js'
import type { MachineData, Part, PartKind } from './parts/index.js'
import type { SwarmDelta } from './parts/load.js'
@@ -574,6 +574,25 @@ describe('the verify sample (spec 2026-11-02, "Checking it on prod")', () => {
} finally { warn.mockRestore() }
})
+ // Final review, Important 2: a feed loaded for another reader starts at another `from`; only what both cover compares.
+ it('a feed loaded from another starting point is not a mismatch', async () => {
+ const stamps = new MemoryStamps()
+ const cache = new SwarmCache(stamps, { verifyRate: 1, random: () => 0, delta: async () => ({ parts: [machine('m1', 2, { a: 2 })], head: null }) })
+ let from = 100
+ const load = vi.fn(async () => ({ from: from += 50, parts: [machine('m1', from > 200 ? 2 : 1, { a: from > 200 ? 2 : 1 })] }))
+ const read = async () => (await cache.at(['t1'])).get('t1', 'feed', 'all', load, feedRule)
+ await read()
+ await stamps.bump('t1', ['machine'])
+ from = 200
+ const warn = vi.spyOn(logger, 'warn')
+ try {
+ await read()
+ await vi.waitFor(() => expect(load).toHaveBeenCalledTimes(2))
+ await new Promise(resolve => setTimeout(resolve, 10))
+ expect(warn).not.toHaveBeenCalled()
+ } finally { warn.mockRestore() }
+ })
+
it('one check at a time per process', async () => {
let release: () => void = () => {}
const gate = new Promise<void>(resolve => { release = resolve })
diff --git a/backend/src/superTabs/cache.ts b/backend/src/superTabs/cache.ts
index f5d284bfe..dda26399a 100644
--- a/backend/src/superTabs/cache.ts
+++ b/backend/src/superTabs/cache.ts
@@ -142,6 +142,9 @@ export class SwarmCache {
get size() { return { entries: this.entries.size, bytes: this.bytes } }
+ /** Whether a bump patches what is held (a delta reader is configured) rather than dropping it. */
+ get patching(): boolean { return !!this.delta }
+
/** One read's view of these Swarms: their stamps, read once, before anything is loaded. */
async at(tabIds: readonly string[]): Promise<CacheView> {
const at = this.now()
@@ -226,7 +229,7 @@ export class SwarmCache {
if (next === 'reload') return reload('epoch')
this.keep(tabId, name, { tabId, stamp, scope, at: read.at, fullAt: entry.fullAt, bytes: 0, value: next, stale: false, patch: patch as PatchRule<unknown> })
recordCache(name, 'patch', { parts: delta.parts.length, bytes: sizeOf(delta.parts) })
- this.verify(tabId, name, scope, stamp, load, next, patch.kinds)
+ this.verify(tabId, name, scope, stamp, load, next, patch)
return next
})()
this.loading.set(flight, patching)
@@ -275,7 +278,7 @@ export class SwarmCache {
* and is logged with the part keys that differ, never their data.
*/
private verify<T>(tabId: string, name: string, scope: StampScope | 'all', stamp: Stamp, load: () => Promise<T>, patched: T,
- kinds: readonly PartKind[]): void {
+ patch: PatchRule<T>): void {
if (this.verifying || !(this.random() < this.verifyRate)) return
this.verifying = true
const unmoved = (now: Stamp | undefined) => !!now && now.main === stamp.main && (scope === 'main' || now.machine === stamp.machine)
@@ -285,11 +288,12 @@ export class SwarmCache {
const after = (await this.stamps.read([tabId])).get(tabId)
if (!unmoved(before) || !unmoved(after)) return
recordCache(name, 'verify')
- if (cacheDigest(fresh) === cacheDigest(patched)) return
+ const [mine, theirs] = patch.comparable ? patch.comparable(patched, fresh) : [patched, fresh]
+ if (cacheDigest(mine) === cacheDigest(theirs)) return
const k = key(tabId, name)
if (this.entries.get(k)?.value === patched) this.drop1(k)
recordCache(name, 'mismatch')
- logger.warn('swarm cache verify mismatch', { entry: name.split(':', 1)[0], tabId, kinds: [...kinds], keys: differingKeys(patched, fresh) })
+ logger.warn('swarm cache verify mismatch', { entry: name.split(':', 1)[0], tabId, kinds: [...patch.kinds], keys: differingKeys(mine, theirs) })
})().catch(() => { /* A check that cannot run says nothing; the 10-minute full load stays the net. */ })
.finally(() => { this.verifying = false })
}
@@ -341,6 +345,10 @@ export class CacheView {
get available(): boolean { return this.stamps !== null }
+ /** Whether entries are patched from deltas (cache.ts SwarmCache.patching): only then is a value built from the held base
+ * cheaper than its own load, since a base dropped on every bump would load in full each time. */
+ get patching(): boolean { return this.stamps !== null && !!this.cache?.patching }
+
/** This Swarm's main stamp as the view read it, or none without stamps or a cache. */
mainStamp(tabId: string): number | undefined {
return this.cache ? this.stamps?.get(tabId)?.main : undefined
diff --git a/backend/src/superTabs/cachePatch.test.ts b/backend/src/superTabs/cachePatch.test.ts
index 9b88250b9..0c460e337 100644
--- a/backend/src/superTabs/cachePatch.test.ts
+++ b/backend/src/superTabs/cachePatch.test.ts
@@ -1,5 +1,6 @@
import { describe, expect, it } from 'vitest'
-import { baseRule, cacheDigest, dormantAgentRule, dormantProjectRule, dormantRule, finishedStartsRule, groupRule, machinesRule } from './cachePatch.js'
+import { stableId } from './model.js'
+import { baseRule, cacheDigest, dormantAgentRule, feedRule, startsOfRule, dormantProjectRule, dormantRule, finishedStartsRule, groupRule, machinesRule } from './cachePatch.js'
import type { Part, PartKind, SwarmParts } from './parts/index.js'
import type { SwarmDelta } from './parts/load.js'
@@ -138,3 +139,41 @@ describe('dormant selections', () => {
expect(dormantAgentRule('a8').apply([], delta([sleep]))).toEqual([])
})
})
+
+describe('feedRule (spec 2026-11-02 poll cost, Part 1.1)', () => {
+ it('keeps tombstones, dormant groups and readAt, takes the newer version', () => {
+ const held = { from: 500, parts: [part('group', 'g1', 1, { a: 1 }), part('machine', 'm1', 1, {}, { readAt: 900 })] }
+ const next = feedRule.apply(held, delta([
+ part('group', 'g1', 2, { a: 2 }),
+ part('group', 'g2', 3, {}, { dormant: true }),
+ part('agent', 'a9', 4, {}, { deleted: true }),
+ part('machine', 'm1', 2, {}, { readAt: 2_000 }),
+ part('group', 'g1', 1, { stale: true }),
+ ])) as { from: number; parts: Part[] }
+ expect(next.from).toBe(500)
+ expect(next.parts.map(p => [p.kind, p.key, p.version]).sort()).toEqual([['agent', 'a9', 4], ['group', 'g1', 2], ['group', 'g2', 3], ['machine', 'm1', 2]])
+ expect(next.parts.find(p => p.key === 'a9')!.deleted).toBe(true)
+ expect(next.parts.find(p => p.key === 'g2')!.dormant).toBe(true)
+ expect(next.parts.find(p => p.key === 'm1')!.readAt).toBe(2_000)
+ })
+
+ it('returns what it holds when nothing is newer', () => {
+ const held = { from: 0, parts: [part('group', 'g1', 5, {})] }
+ expect(feedRule.apply(held, delta([part('group', 'g1', 5, {})]))).toBe(held)
+ })
+})
+
+describe('startsOfRule (spec 2026-11-02 poll cost, Part 1.4)', () => {
+ const start = (key: string, version: number, harnessId: string | null, extra: Partial<Part> = {}) =>
+ part('start', key, version, { id: key, harnessId, request: { machineId: 'm1', conversationId: 'c' } }, extra)
+ const agentOf = (harness: string) => stableId('m1', harness)
+
+ it('follows starts in and out of the agent list', () => {
+ const rule = startsOfRule([agentOf('h1')])
+ const held = [start('s1', 1, 'h1')]
+ expect((rule.apply(held, delta([start('s2', 1, 'h1')])) as Part[]).map(s => s.key)).toEqual(['s1', 's2'])
+ expect(rule.apply(held, delta([start('s1', 2, 'h1', { deleted: true })]))).toEqual([])
+ expect(rule.apply(held, delta([start('s1', 2, 'h9')]))).toEqual([])
+ expect(rule.apply(held, delta([start('s3', 1, 'h7')]))).toBe(held)
+ })
+})
diff --git a/backend/src/superTabs/cachePatch.ts b/backend/src/superTabs/cachePatch.ts
index ed4190702..ebeb38f6b 100644
--- a/backend/src/superTabs/cachePatch.ts
+++ b/backend/src/superTabs/cachePatch.ts
@@ -9,16 +9,19 @@
* lists that share every part that did not change (the cache freezes what is new).
*/
import { createHash } from 'node:crypto'
-import { type GroupData, type MachineData, type Part, type PartKind, type SwarmParts } from './parts/index.js'
+import { PART_KINDS, type GroupData, type MachineData, type Part, type PartKind, type SwarmParts } from './parts/index.js'
import type { SwarmDelta } from './parts/load.js'
import { startFinished } from './parts/write.js'
-import type { AgentStart } from './model.js'
+import { stableId, type AgentStart } from './model.js'
export interface PatchRule<T> {
/** The part kinds whose changes this entry holds: a refresh reads only those. */
kinds: readonly PartKind[]
/** The held value with the delta applied, or 'reload' when the delta cannot be applied and the entry loads again. */
apply(held: T, delta: SwarmDelta): T | 'reload'
+ /** What of a patched value and a fresh load the verify sample compares (cache.ts verify), when not the whole: a fresh load
+ * can cover a different window than the held value (the feed). */
+ comparable?(patched: T, fresh: T): [unknown, unknown]
}
/** A changed part as a load would have given it: a change read adds `readAt`, which no load carries. */
@@ -89,6 +92,40 @@ export const finishedStartsRule: PatchRule<Part<AgentStart>[]> = {
apply: (held, delta) => applyByKey(held, delta.parts, 'start', p => live(p) && finished(p)),
}
+/** The `feed` entry (cachedReads.ts readChanged): every part changed after `from`, as `loadChanged` reads them, tombstones,
+ * dormant groups and machines' `readAt` included. Its full reloads were 610 MB per 20 minutes on prod (2026-11-02). */
+export const feedRule: PatchRule<{ from: number; parts: Part[] }> = {
+ kinds: PART_KINDS,
+ apply(held, delta) {
+ let next: Map<string, Part> | null = null
+ const id = (part: Part) => `${part.kind}\u0000${part.key}`
+ for (const part of delta.parts) {
+ const current = (next ?? null)?.get(id(part)) ?? held.parts.find(p => p.kind === part.kind && p.key === part.key)
+ if (current && part.version <= current.version) continue
+ next ??= new Map(held.parts.map(p => [id(p), p]))
+ next.set(id(part), part)
+ }
+ return next ? { from: held.from, parts: [...next.values()] } : held
+ },
+ // The check's own load starts where its reader's cursor does: only the parts both windows cover compare (final review).
+ comparable(patched, fresh) {
+ const from = Math.max(patched.from, fresh.from)
+ const covered = (parts: Part[]) => parts.filter(p => Math.max(p.changedAt, p.readAt ?? 0) > from)
+ return [covered(patched.parts), covered(fresh.parts)]
+ },
+}
+
+/** A `startsOf:{agents}` entry (read/service.ts pollStarts): the live starts of these agents, an agent being its machine and
+ * harness (`stableId`). A start whose agent left the list goes, as does a tombstone. */
+export function startsOfRule(agents: readonly string[]): PatchRule<Part<AgentStart>[]> {
+ const listed = new Set(agents)
+ const ofListed = (p: Part) => {
+ const start = p.data as AgentStart | null
+ return !!start?.harnessId && listed.has(stableId(start.request.machineId, start.harnessId))
+ }
+ return { kinds: ['start'], apply: (held, delta) => applyByKey(held, delta.parts, 'start', p => live(p) && ofListed(p)) }
+}
+
/** The `dormant` entry: every live dormant group. */
export const dormantRule: PatchRule<Part<GroupData>[]> = {
kinds: ['group'],
diff --git a/backend/src/superTabs/cachedReads.test.ts b/backend/src/superTabs/cachedReads.test.ts
index cc5f67fa1..a0b3ef11b 100644
--- a/backend/src/superTabs/cachedReads.test.ts
+++ b/backend/src/superTabs/cachedReads.test.ts
@@ -1,9 +1,9 @@
import { describe, expect, it, vi } from 'vitest'
import { stableId, type AgentStart } from './model.js'
import type { Part } from './parts/index.js'
-import { namedStarts, readChanged, readDelta, readLastChangedAt, readLastChangedAts, readLight, readLightGroups, readMachines, readParts } from './cachedReads.js'
+import { deriveLight, namedStarts, readChanged, readDelta, readLastChangedAt, readLastChangedAts, readLight, readLightGroups, readMachines, readParts } from './cachedReads.js'
import { CacheView } from './cache.js'
-import { baseRule, dormantRule, machinesRule } from './cachePatch.js'
+import { baseRule, dormantRule, feedRule, machinesRule } from './cachePatch.js'
/** A start, finished once it has a harness. `untouchable`: reading its request throws, so a test sees the read hash its
* agent (stableId, a sha256 of the request's machine and the harness). */
@@ -111,7 +111,7 @@ describe('which entries a refresh patches (spec 2026-11-02, Phase 1)', () => {
expect(rules.get('lastChangedAt')).toBeUndefined()
expect(rules.get('light:')).toBeUndefined()
expect(rules.get('light-group:g2')).toBeUndefined()
- expect(rules.get('feed')).toBeUndefined()
+ expect(rules.get('feed')).toBe(feedRule)
})
})
@@ -177,3 +177,69 @@ describe('the delta a refresh reads', () => {
expect(aggregateRaw).toHaveBeenCalledTimes(2)
})
})
+
+describe('light and host state derived from held entries (spec 2026-11-02 poll cost, Part 1.2)', () => {
+ const g = (key: string, data: Record<string, unknown>, dormant = false) => ({ kind: 'group', key, version: 1, changedAt: 1, ordinal: 1,
+ ...dormant ? { dormant: true } : {}, data: { id: key, agentIds: [], archived: false, title: key, ...data } })
+ const base = { tabId: 't', head: { kind: 'head', key: 'head', version: 1, changedAt: 1, ordinal: 0, data: { projects: [{ id: 'p1', leadConversationId: 'lead1' }], invitations: [] } },
+ members: [], agents: [{ kind: 'agent', key: 'a1', version: 1, changedAt: 1, ordinal: 1, data: { id: 'a1', machineId: 'm1', projectId: 'p1', workDecision: 'stop' } },
+ { kind: 'agent', key: 'a2', version: 1, changedAt: 1, ordinal: 1, data: { id: 'a2', machineId: 'm2', projectId: 'p1', workDecision: 'stop' } }],
+ groups: [g('run', { agentIds: ['a2'], assignment: { id: 'w', agentId: 'a2', status: 'working', execution: { machineId: 'm2', harnessId: 'h', machineOwnerId: 'o' } } }),
+ g('idle', { agentIds: ['a1'] })],
+ machines: [], starts: [], progress: [], sequenceBase: 0, visibilityEpoch: 0, groupCounter: 0 }
+ // Any touch of the database fails the test: a derived read must come from what the cache holds.
+ const db = new Proxy({}, { get: (_t, key) => { throw new Error(`read the database: ${String(key)}`) } }) as never
+ function stub(extra: Record<string, unknown> = {}, patching = true) {
+ const view = new CacheView(null, null), names: string[] = []
+ Object.defineProperty(view, 'available', { get: () => true })
+ Object.defineProperty(view, 'patching', { get: () => patching })
+ vi.spyOn(view, 'get').mockImplementation(async (_tabId, name) => {
+ names.push(name)
+ if (name === 'parts') return base
+ if (name === 'machines') return []
+ if (name in extra) return extra[name]
+ if (name.startsWith('light-group:')) return null
+ if (name.startsWith('dormant:agent:')) return []
+ throw new Error(`unexpected entry ${name}`)
+ })
+ return { view, names }
+ }
+
+ it('the light base derives from the held base and reads no Swarm collection', async () => {
+ const { view } = stub({ 'light-group:lead1': g('lead1', { brief: '' }, true) })
+ const light = await deriveLight(db, view, 't', { groups: 'working' })
+ expect(light.groups.map(x => x.key).sort()).toEqual(['lead1', 'run'])
+ expect(light.groups.find(x => x.key === 'run')!.data!.brief).toBe('')
+ })
+
+ it('host state takes the machine\'s agents\' dormant conversations from dormant:agent entries', async () => {
+ const { view, names } = stub({ 'dormant:agent:a1': [g('old', { agentIds: ['a1'] }, true)] })
+ const light = await deriveLight(db, view, 't', { groups: 'working', machineId: 'm1' })
+ expect(names).toContain('dormant:agent:a1')
+ expect(light.groups.map(x => x.key).sort()).toEqual(['idle', 'old', 'run'])
+ })
+
+ it('readLight derives on a cache miss instead of reading Mongo', async () => {
+ const { view } = stub({ 'light-group:lead1': null })
+ const get = vi.mocked(view.get)
+ const fallback = get.getMockImplementation()!
+ get.mockImplementation(async (tabId, name, scope, load, patch) => name.startsWith('light:') ? load() : fallback(tabId, name, scope, load, patch))
+ const light = await readLight(db, view, 't', { groups: 'working' })
+ expect(light.groups.map(x => x.key)).toEqual(['run'])
+ })
+
+ it('a cache that does not patch reads the light base as before: deriving it would load the whole base on every bump', async () => {
+ const { view } = stub({}, false)
+ const get = vi.mocked(view.get)
+ const fallback = get.getMockImplementation()!
+ get.mockImplementation(async (tabId, name, scope, load, patch) => name.startsWith('light:') ? load() : fallback(tabId, name, scope, load, patch))
+ await expect(readLight(db, view, 't', { groups: 'working' })).rejects.toThrow('read the database: $transaction')
+ })
+
+ it('a machine whose agents all left derives no conversation of theirs', async () => {
+ const { view, names } = stub()
+ const light = await deriveLight(db, view, 't', { groups: 'working', machineId: 'gone' })
+ expect(names.filter(n => n.startsWith('dormant:agent:'))).toEqual([])
+ expect(light.groups.map(x => x.key)).toEqual(['run'])
+ })
+})
diff --git a/backend/src/superTabs/cachedReads.ts b/backend/src/superTabs/cachedReads.ts
index 7acdd01e4..ad2457240 100644
--- a/backend/src/superTabs/cachedReads.ts
+++ b/backend/src/superTabs/cachedReads.ts
@@ -7,10 +7,11 @@
import type { Prisma, PrismaClient } from '@prisma/client'
import { stableId, type AgentStart } from './model.js'
import { CacheView } from './cache.js'
-import { baseRule, dormantAgentRule, dormantProjectRule, dormantRule, finishedStartsRule, groupRule, machinesRule } from './cachePatch.js'
+import { baseRule, dormantAgentRule, dormantProjectRule, dormantRule, feedRule, finishedStartsRule, groupRule, machinesRule } from './cachePatch.js'
import * as store from './parts/index.js'
import type { GroupData, Part, PartKind, SwarmParts, SwarmDelta } from './parts/index.js'
import { retryTransient } from './retry.js'
+import { lightKeys, lightSelect, projectLightGroup, type LightOptions as SelectOptions } from './parts/lightSelect.js'
import { retryStaleIndex } from './parts/indexed.js'
type Db = Pick<PrismaClient, '$transaction'> & Prisma.TransactionClient
@@ -116,12 +117,41 @@ export async function readLight(db: Db, view: CacheView, tabId: string, opts: Om
const name = `light:${JSON.stringify([opts.groups ?? 'active', !!opts.includeRecentStarts, ...(['groupIds', 'agentIds', 'projectIds'] as const)
.map(key => [...opts[key] ?? []].sort())])}`
const [light, machines] = await Promise.all([
- view.get(tabId, name, 'main', () => retryTransient(() => retryStaleIndex(() => db.$transaction(tx => store.loadLight(tx, tabId, { ...opts, machines: false }))))),
+ // With a cache that patches, built from the entries it holds (deriveLight); otherwise, or for recent finished starts, which
+ // the base does not hold, read as before: a base dropped on every bump would cost more than this read.
+ view.get(tabId, name, 'main', () => view.patching && !opts.includeRecentStarts ? deriveLight(db, view, tabId, opts)
+ : retryTransient(() => retryStaleIndex(() => db.$transaction(tx => store.loadLight(tx, tabId, { ...opts, machines: false }))))),
readMachines(db, view, tabId),
])
return { ...light, machines }
}
+/**
+ * `loadLight`'s selection built from entries the cache already holds and patches (spec 2026-11-02 poll cost, Part 1.2): the
+ * base's awake conversations, `light-group:{id}` for a named one the base lacks, and, for a machine's host state
+ * (`machineId`, read/host.ts hostParts), its agents' dormant conversations from `dormant:agent:{id}` plus its starts'
+ * conversations and their projects. Reads Mongo only for entries that miss.
+ */
+export async function deriveLight(db: Db, view: CacheView, tabId: string, opts: SelectOptions & { machineId?: string }): Promise<Omit<SwarmParts, 'machines'>> {
+ const [active] = await base(db, view, tabId)
+ const machineId = opts.machineId
+ const starts = machineId ? active.starts.filter(s => s.data!.request.machineId === machineId) : active.starts
+ const agentIds = machineId ? active.agents.filter(a => (a.data as { machineId?: string }).machineId === machineId).map(a => a.key) : opts.agentIds ?? []
+ const groupIds = machineId ? [...new Set(starts.map(s => s.data!.request.conversationId))] : opts.groupIds ?? []
+ const awake = active.groups.map(projectLightGroup)
+ const held = new Set(awake.map(g => g.key))
+ const named = lightKeys(active.head, active.starts, { ...opts, groupIds }).filter(id => !held.has(id))
+ const [byId, ...dormant] = await Promise.all([readLightGroups(db, view, tabId, named),
+ ...agentIds.map(id => view.get(tabId, `dormant:agent:${id}`, 'main',
+ () => store.loadGroups(db, tabId, 'agents', { agentIds: { $in: [id] }, dormant: true }), dormantAgentRule(id)))])
+ const candidates = new Map(awake.map(g => [g.key, g]))
+ for (const g of [...byId, ...dormant.flat().map(projectLightGroup)]) if (!candidates.has(g.key)) candidates.set(g.key, g)
+ // A machine's host state also lists every conversation of a project it has a start in (read/host.ts hostParts).
+ const projectIds = machineId ? [...new Set(groupIds.flatMap(id => { const g = candidates.get(id); return g ? [g.data!.projectId ?? 'lead'] : [] }))]
+ : opts.projectIds ?? []
+ return lightSelect({ ...active, groups: [...candidates.values()] }, { groups: opts.groups, groupIds, agentIds, projectIds })
+}
+
/** Light conversations by id (parts/light.ts loadLightGroups), dormant ones too, in the order named: each held at the
* Swarm's main stamp, an id no live conversation has held as none. A read's misses are one query, as readLastChangedAts
* batches them; without stamps every id is read, still in one query. */
@@ -163,6 +193,6 @@ export async function readChanged(db: Db, view: CacheView, tabId: string, since:
const feed = await view.get(tabId, 'feed', 'all', async () => {
const from = since - FEED_SLACK_MS
return { from, parts: (await store.loadChanged(db, [tabId], new Date(from))).get(tabId) ?? [] }
- })
+ }, feedRule)
return since >= feed.from ? feed.parts.filter(p => Math.max(p.changedAt, p.readAt ?? 0) > since) : direct()
}
diff --git a/backend/src/superTabs/native.ts b/backend/src/superTabs/native.ts
index 8baf0d37a..f34b3e585 100644
--- a/backend/src/superTabs/native.ts
+++ b/backend/src/superTabs/native.ts
@@ -11,7 +11,7 @@ import { CANCELLABLE_DELIVERY } from './pageReads.js'
import { cloneData } from './cloneData.js'
import { numberMessages, type Touch } from './parts/commit.js'
import { redactCredentials } from './credentials.js'
-import type { DeliveriesWaiting } from './store.js'
+import type { DeliveriesEnding, DeliveriesWaiting } from './store.js'
const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)
export const openNativeSchema = z.object({ operationId: id, conversationId: id, agentId: id }).strict()
@@ -271,15 +271,17 @@ export class SuperTabNativeStore {
* again at every use). Most commands change no access and read nothing here: rebuilding every viewer and every member
* outside every private conversation on each command kept prod Mongo busy (2026-10-28). Returns those who lost sight of
* an agent (watchersLost), for the observers to check again. */
-export async function revokeNativeContexts(tx: Transaction, before: SuperTabState, after: SuperTabState) {
+/** `ending` (store.ts endDeliveries) runs the cancel of the revoked contexts' waiting deliveries, so a host holding one hears. */
+export async function revokeNativeContexts(tx: Transaction, before: SuperTabState, after: SuperTabState,
+ ending: (holds: DeliveriesEnding, end: () => Promise<{ count: number }>) => Promise<{ count: number }> = (_, end) => end()) {
const { conditions, watchersLost } = revokeConditions(before, after)
if (conditions.length) {
const where = { tabId: before.id, revoked: false, OR: conditions }
const revoked = await tx.superTabNativeContext.findMany({ where, select: { id: true } })
await tx.superTabNativeContext.updateMany({ where, data: { revoked: true } })
- if (revoked.length) await tx.superTabDelivery.updateMany({ where: { tabId: before.id,
+ if (revoked.length) await ending({ matches: row => revoked.some(r => r.id === row.nativeContextId) }, () => tx.superTabDelivery.updateMany({ where: { tabId: before.id,
nativeContextId: { in: revoked.map(r => r.id) }, status: { in: [...CANCELLABLE_DELIVERY] } },
- data: { status: 'cancelled', holdReason: null, holdSince: null } })
+ data: { status: 'cancelled', holdReason: null, holdSince: null } }))
}
return watchersLost
}
diff --git a/backend/src/superTabs/parts/light.ts b/backend/src/superTabs/parts/light.ts
index b89a6909d..4f4d1b596 100644
--- a/backend/src/superTabs/parts/light.ts
+++ b/backend/src/superTabs/parts/light.ts
@@ -45,7 +45,7 @@ export function ms(value: unknown): number {
return Number((date as { $numberLong?: string }).$numberLong)
}
-function lightGroup(row: Record<string, unknown>): Part<GroupData> {
+export function lightGroup(row: Record<string, unknown>): Part<GroupData> {
const raw = (row.data ?? {}) as Partial<GroupData> & { task?: { owns?: string[] } }
// A conversation with no work has nothing to project there; never read it as having work.
// Finished work comes without its machine or result: placeholders keep the shape, and nothing reads them.
diff --git a/backend/src/superTabs/parts/lightSelect.test.ts b/backend/src/superTabs/parts/lightSelect.test.ts
new file mode 100644
index 000000000..10dd3b297
--- /dev/null
+++ b/backend/src/superTabs/parts/lightSelect.test.ts
@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+import type { Agent, AgentStart } from '../model.js'
+import { lightSelect, projectLightGroup, type LightCandidates } from './lightSelect.js'
+import type { GroupData, HeadData, Part } from './types.js'
+
+const group = (key: string, data: Partial<GroupData>, dormant = false): Part<GroupData> => ({ kind: 'group', key, version: 1, changedAt: 1, ordinal: 1,
+ ...dormant ? { dormant: true as const } : {}, data: { id: key, agentIds: [], archived: false, title: `T ${key}`, brief: 'long brief', checks: [{ x: 1 }], ...data } as unknown as GroupData })
+const running = (agentId: string) => ({ id: `w-${agentId}`, agentId, status: 'working', execution: { machineId: 'm1', harnessId: 'h1', machineOwnerId: 'o' }, result: null })
+const agent = (key: string, data: Partial<Agent> = {}): Part<Agent> => ({ kind: 'agent', key, version: 1, changedAt: 1, ordinal: 1, data: { id: key, projectId: 'p1', ...data } as Agent })
+
+describe('projectLightGroup (spec 2026-11-02 poll cost, Part 1.2)', () => {
+ it('keeps running work\'s title, owned paths and execution, and drops the brief and checks', () => {
+ const light = projectLightGroup(group('g1', { assignment: running('a1') as never, task: { goal: 'g', changes: 'c', constraints: 'k', owns: ['src/x'] } as never }))
+ expect(light.data!.title).toBe('T g1')
+ expect(light.data!.task!.owns).toEqual(['src/x'])
+ expect(light.data!.assignment!.execution.machineId).toBe('m1')
+ expect(light.data!.brief).toBe('')
+ expect(light.data!.checks).toEqual([])
+ })
+
+ it('drops finished work\'s title and execution, keeps who and how it ended, and the dormant flag', () => {
+ const light = projectLightGroup(group('g2', { assignment: { ...running('a1'), status: 'done', lost: true } as never }, true))
+ expect(light.data!.title).toBe('')
+ expect(light.data!.assignment).toMatchObject({ id: 'w-a1', agentId: 'a1', status: 'done', lost: true, execution: { machineId: '' } })
+ expect(light.dormant).toBe(true)
+ })
+
+ it('makes the empty parent documents Mongo\'s computed projection makes, running or not', () => {
+ // LIGHT_GROUP computes `data.task.owns` with $cond/$$REMOVE: Mongo creates `task: {}` even when it removes the value.
+ expect(projectLightGroup(group('lead', {})).data!.task).toEqual({})
+ expect(projectLightGroup(group('run', { assignment: running('a1') as never })).data!.task).toEqual({})
+ })
+
+ it('a conversation with no work has none', () => {
+ expect(projectLightGroup(group('g3', {})).data!.assignment).toBeNull()
+ })
+})
+
+describe('lightSelect', () => {
+ const head = { kind: 'head', key: 'head', version: 1, changedAt: 1, ordinal: 0,
+ data: { projects: [{ id: 'p1', leadConversationId: 'lead1' }], invitations: [{ conversationId: 'invited' }] } } as unknown as Part<HeadData>
+ const start = { kind: 'start', key: 's1', version: 1, changedAt: 1, ordinal: 1, data: { id: 's1', request: { conversationId: 'started', machineId: 'm1' } } } as unknown as Part<AgentStart>
+ const candidates = (groups: Part<GroupData>[], agents: Part<Agent>[] = []): LightCandidates =>
+ ({ tabId: 't', head, members: [], agents, starts: [start], groups: groups.map(projectLightGroup), sequenceBase: 0, visibilityEpoch: 0, groupCounter: 0 })
+
+ it('working: the Lead conversation, running work, start- and invitation-named ones, and nothing else idle', () => {
+ const picked = lightSelect(candidates([group('lead1', {}, true), group('run', { assignment: running('a9') as never }), group('started', {}),
+ group('invited', {}), group('idle', { agentIds: ['a9'] })], [agent('a9', { workDecision: 'stop' } as never)]), { groups: 'working' })
+ expect(picked.groups.map(g => g.key).sort()).toEqual(['invited', 'lead1', 'run', 'started'])
+ })
+
+ it('working: an undecided worker\'s awake conversations, and a legacy agent\'s', () => {
+ const picked = lightSelect(candidates([group('mine', { agentIds: ['u1'] }), group('old', { agentIds: ['l1'] }), group('asleep', { agentIds: ['u1'] }, true)],
+ [agent('u1'), agent('l1', { projectId: undefined, workDecision: 'stop' } as never)]), { groups: 'working' })
+ expect(picked.groups.map(g => g.key).sort()).toEqual(['mine', 'old'])
+ })
+
+ it('named agents take their dormant conversations too; named projects only their awake ones', () => {
+ const picked = lightSelect(candidates([group('a-dormant', { agentIds: ['x'] }, true), group('p-awake', { projectId: 'p2' }), group('p-dormant', { projectId: 'p2' }, true),
+ group('no-project', {})]), { groups: 'working', agentIds: ['x'], projectIds: ['p2', 'lead'] })
+ expect(picked.groups.map(g => g.key).sort()).toEqual(['a-dormant', 'no-project', 'p-awake'])
+ })
+
+ it('active: every awake conversation', () => {
+ const picked = lightSelect(candidates([group('a', {}), group('b', {}, true)]), { groups: 'active' })
+ expect(picked.groups.map(g => g.key)).toEqual(['a'])
+ })
+})
diff --git a/backend/src/superTabs/parts/lightSelect.ts b/backend/src/superTabs/parts/lightSelect.ts
new file mode 100644
index 000000000..201b415db
--- /dev/null
+++ b/backend/src/superTabs/parts/lightSelect.ts
@@ -0,0 +1,90 @@
+/**
+ * The light Swarm (parts/light.ts loadLight) built in memory from parts already held, instead of read from Mongo on every
+ * bump: `light` and `host:state:{m}` were 440 MB of whole reloads per 20 minutes on prod (spec 2026-11-02 poll cost,
+ * Part 1.2). `projectLightGroup` is `loadLight`'s projection applied to a whole conversation; `lightSelect` is its
+ * selection over candidates that include every awake conversation. integration/superTabCacheDelta.test.ts holds both equal
+ * to `loadLight` after every kind of write.
+ */
+import { activeWork, agentRole, type Agent, type AgentStart } from '../model.js'
+import { GROUP_FIELDS, lightGroup } from './light.js'
+import type { GroupData, HeadData, Part, SwarmParts } from './types.js'
+
+/** What Mongo's `$project` of LIGHT_GROUP keeps of a conversation's data: the `always` fields, and the `whenRunning` ones
+ * while its work runs. An included path under a value that is not an object is left out, as Mongo leaves it; a computed
+ * `whenRunning` path always makes its parent documents, even when it removes the value (`task: {}`). */
+function projectedData(data: GroupData): Record<string, unknown> {
+ const running = activeWork(data)
+ const out: Record<string, unknown> = {}
+ for (const path of GROUP_FIELDS.whenRunning) {
+ let to = out
+ for (const step of path.split('.').slice(0, -1)) to = (to[step] ??= {}) as Record<string, unknown>
+ }
+ for (const path of [...GROUP_FIELDS.always, ...running ? GROUP_FIELDS.whenRunning : []]) {
+ const steps = path.split('.')
+ let from: unknown = data, to = out
+ for (const [i, step] of steps.entries()) {
+ if (!from || typeof from !== 'object' || Array.isArray(from)) break
+ const value = (from as Record<string, unknown>)[step]
+ if (value === undefined) break
+ if (i === steps.length - 1) { to[step] = value; break }
+ if (!value || typeof value !== 'object' || Array.isArray(value)) break
+ to = (to[step] ??= {}) as Record<string, unknown>
+ from = value
+ }
+ }
+ return out
+}
+
+/** A whole conversation as `loadLight` returns it (light.ts lightGroup over Mongo's projection). */
+export function projectLightGroup(group: Part<GroupData>): Part<GroupData> {
+ return lightGroup({ key: group.key, version: group.version, changedAt: group.changedAt, ordinal: group.ordinal,
+ ...group.dormant ? { dormant: true } : {}, data: projectedData(group.data!) })
+}
+
+/** What `lightSelect` chooses from. `groups`: light conversations (projected), every awake one, plus the dormant ones a
+ * selection names (by id, or as a named agent's). */
+export interface LightCandidates {
+ tabId: string; head: Part<HeadData>; members: Part[]; agents: Part<Agent>[]; starts: Part<AgentStart>[]; groups: Part<GroupData>[]
+ sequenceBase: number; visibilityEpoch: number; groupCounter: number
+}
+export interface LightOptions { groups?: 'active' | 'working'; groupIds?: string[]; agentIds?: string[]; projectIds?: string[] }
+
+/** The conversations a selection names by id: with 'working', the Lead conversations and those an unfinished start or an
+ * invitation names (light.ts loadLight), and `groupIds`. A dormant one among them is a candidate only when given. */
+export function lightKeys(head: Part<HeadData>, starts: Part<AgentStart>[], opts: LightOptions): string[] {
+ const { projects, invitations } = head.data!
+ return [...new Set([...opts.groups === 'working' ? [...projects ? projects.map(p => p.leadConversationId) : ['lead'],
+ ...starts.map(s => s.data!.request.conversationId), ...invitations.map(i => i.conversationId)] : [], ...opts.groupIds ?? []])]
+}
+
+/** `loadLight(opts)` without machines (they come from their own entry), chosen from `c`. */
+export function lightSelect(c: LightCandidates, opts: LightOptions): Omit<SwarmParts, 'machines'> {
+ const working = opts.groups === 'working'
+ const keys = new Set(lightKeys(c.head, c.starts, opts))
+ const agents = new Set(opts.agentIds ?? []), projectIds = new Set(opts.projectIds ?? [])
+ // A conversation stored with no project is the first project's (model.ts groupProject), as loadLight's null match reads it.
+ const inProject = (g: Part<GroupData>) => g.data!.projectId ? projectIds.has(g.data!.projectId) : projectIds.has('lead')
+ const awake = (g: Part<GroupData>) => !g.dormant
+ const selected = new Map<string, Part<GroupData>>()
+ for (const g of c.groups) {
+ if ((working ? activeWork(g.data!) : awake(g)) || keys.has(g.key) || g.data!.agentIds.some(id => agents.has(id)) || (awake(g) && inProject(g))) {
+ selected.set(g.key, g)
+ }
+ }
+ if (working) {
+ // As light.ts undecidedWork: busy is the Lead of a selected conversation or the worker of its active work.
+ const busy = new Set([...selected.values()].flatMap(g => [...g.data!.leadId ? [g.data!.leadId] : [],
+ ...activeWork(g.data!) ? [g.data!.assignment!.agentId] : []]))
+ const undecided = new Set(c.agents.filter(a => !a.data!.workDecision && agentRole(a.data!) !== 'reviewer' && !busy.has(a.key)).map(a => a.key))
+ const legacy = new Set(c.agents.filter(a => !a.data!.projectId).map(a => a.key))
+ for (const g of c.groups) {
+ if (selected.has(g.key) || !awake(g)) continue
+ const d = g.data!
+ const ofUndecided = (d.assignment?.agentId && undecided.has(d.assignment.agentId)) || (d.leadId && undecided.has(d.leadId))
+ || d.agentIds.some(id => undecided.has(id))
+ if (ofUndecided || d.agentIds.some(id => legacy.has(id))) selected.set(g.key, g)
+ }
+ }
+ return { tabId: c.tabId, head: c.head, members: c.members, agents: c.agents, groups: [...selected.values()], starts: c.starts, progress: [],
+ sequenceBase: c.sequenceBase, visibilityEpoch: c.visibilityEpoch, groupCounter: c.groupCounter } as Omit<SwarmParts, 'machines'>
+}
diff --git a/backend/src/superTabs/read/host.ts b/backend/src/superTabs/read/host.ts
index 9a56b7141..cc65b7fc5 100644
--- a/backend/src/superTabs/read/host.ts
+++ b/backend/src/superTabs/read/host.ts
@@ -11,7 +11,7 @@ import { machineBillingAllowsDataPlane } from '../../lib/billingState.js'
import { fail, type SuperTabState } from '../model.js'
import { GrantReads, TEAM_HOST_ONLY, TEAM_HOST_ONLY_MESSAGE, teamByRecord, type SuperTabStore } from '../store.js'
import type { CacheView } from '../cache.js'
-import { readLastChangedAts, readMachines } from '../cachedReads.js'
+import { readLastChangedAts, readMachines, deriveLight } from '../cachedReads.js'
import { retryTransient } from '../retry.js'
import * as parts from '../parts/index.js'
import type { MachineData, Part } from '../parts/index.js'
@@ -118,8 +118,10 @@ export class HostReads {
* host still settles a queued start whose group went quiet). */
private async tabState(tx: Transaction, cached: CacheView, tabId: string, machineId: string): Promise<SuperTabState> {
const [light, machines] = await Promise.all([cached.get(tabId, `host:state:${machineId}`, 'main',
- // On a miss, one snapshot of what the host's rows are built from, tried again when a lock it waits for is held (retry.ts).
- () => retryTransient(() => retryStaleIndex(() => this.db.$transaction(t => this.hostParts(t, tabId, machineId))))),
+ // With a cache that patches, built from the entries it holds (cachedReads.ts deriveLight, spec 2026-11-02 poll cost);
+ // otherwise one snapshot of what the host's rows are built from, tried again when a lock it waits for is held (retry.ts).
+ () => cached.patching ? deriveLight(this.db, cached, tabId, { groups: 'working', machineId })
+ : retryTransient(() => retryStaleIndex(() => this.db.$transaction(t => this.hostParts(t, tabId, machineId))))),
readMachines(tx, cached, tabId)])
return parts.reassemble({ ...light, machines }, { share: true })
}
diff --git a/backend/src/superTabs/read/service.ts b/backend/src/superTabs/read/service.ts
index f6ebcd641..ce519b04f 100644
--- a/backend/src/superTabs/read/service.ts
+++ b/backend/src/superTabs/read/service.ts
@@ -2,6 +2,7 @@
* The read API by parts (design section 4; shapes in contract.ts). Every read takes its time `T0` before any query and
* makes the next cursor from it, so a write that commits late, inside the overlap, is still seen by the next poll.
*/
+import { startsOfRule } from '../cachePatch.js'
import type { PrismaClient } from '@prisma/client'
import type { AuthUser } from '../../lib/ssoAuth.js'
import { isTeamSession, TEAM_SESSION_LIMITED, TEAM_SESSION_MESSAGE } from '../../lib/teamSession.js'
@@ -124,7 +125,9 @@ export class SwarmReads {
return [...seen.runningHarnessIds, ...seen.stoppedHarnessIds, ...Object.keys(seen.harnessProgress ?? {}), ...(seen.stoppedReservations ?? []).map(r => r.harnessId)]
.map(harnessId => stableId(pool.machineId, harnessId))
}))].filter(id => !covered.has(id)).sort()
- const named = listed.length ? await cached.get(tabId, `startsOf:${JSON.stringify(listed)}`, 'main', () => parts.loadStartsOfAgents(tx, tabId, listed)) : []
+ // Patched from each change (cachePatch.ts startsOfRule, spec 2026-11-02 poll cost), not loaded again after every bump.
+ const named = listed.length ? await cached.get(tabId, `startsOf:${JSON.stringify(listed)}`, 'main', () => parts.loadStartsOfAgents(tx, tabId, listed),
+ startsOfRule(listed)) : []
const taken = new Set([...held, ...fresh.map(s => s.key)])
return [...fresh, ...named.filter(s => !taken.has(s.key))]
}
diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.ts
index ff70f697f..e52fe6fe3 100644
--- a/backend/src/superTabs/store.ts
+++ b/backend/src/superTabs/store.ts
@@ -27,6 +27,7 @@ import { FileLinks } from './fileLinks.js'
import { randomBytes } from 'node:crypto'
import type { Readable } from 'node:stream'
import { logger } from '../utils/logger.js'
+import { noteClaim, recordDeliveryCall } from '../lib/deliveryCalls.js'
import { retryTransient } from './retry.js'
import { recordReload } from './retryStats.js'
import { buddyChatId, swarmBuddyChatId, type ChosenBuddyName } from './buddies.js'
@@ -329,6 +330,8 @@ export interface SuperTabStoreHooks {
/** A delivery now waits for this agent, committed: its machine's daemon socket tells its host to read it at once
* (lib/swarmDeliveryPushes.ts). Called after the write commits; it must not throw. */
deliveriesWaiting?: (waiting: DeliveriesWaiting) => void
+ /** A terminal request waits for this machine (spec 2026-11-02 poll cost, Part 4.2), once its write commits. */
+ terminalWaiting?: (waiting: DeliveriesWaiting) => void
/** A commit changed what these machines' hosts read (parts/commit.ts hostsToTell): each machine's daemon socket tells its
* host to read its Swarm changes now (lib/swarmHostPushes.ts). Called after the write commits; it must not throw. */
hostsChanged?: (change: HostsChanged) => void
@@ -348,6 +351,14 @@ export interface SwarmChanged { tabId: string; userIds: string[]; lastChangedAt:
/** Which machines' hosts should read a Swarm's changes, and the commit's time. */
export interface HostsChanged { tabId: string; machineIds: string[]; lastChangedAt: number }
+/** Which claimed deliveries an `end` ends ([SuperTabStore.endDeliveries]): plain equalities that narrow the read, and a match for
+ * what the caller's filter says with `in`. */
+export interface DeliveriesEnding {
+ where?: { id?: string; agentId?: string; messageId?: string; assignmentId?: string }
+ matches?: (row: { agentId: string; conversationId: string; assignmentId: string | null; nativeContextId: string | null;
+ authorKind: string; authorId: string; authorGeneration: string }) => boolean
+}
+
/** Which agent, of which Swarm, on which machine, has a delivery to read. */
export interface DeliveriesWaiting { machineId: string; tabId: string; agentId: string }
@@ -1569,7 +1580,7 @@ export class SuperTabStore {
if (command.type === 'project.sharing' && command.visibility === 'private') {
await makeProjectPrivate(tx, effects.state, command.projectId)
}
- const watchersLost = await revokeNativeContexts(tx, original, effects.state)
+ const watchersLost = await revokeNativeContexts(tx, original, effects.state, (holds, end) => this.endDeliveries(tx, tabId, holds, end))
// Rule (b) for claims (design D10): a change to who a conversation's deliveries may reach writes those delivery rows,
// so a claim of one conflicts with it. An archived conversation, or one its receiver left, ends them: kept for a
// reopening, 6 of the 9 deliveries prod watch found stuck for days on 2026-10-28 waited in archived groups, unread.
@@ -1581,17 +1592,27 @@ export class SuperTabStore {
const archivedSteps = unreadable && command.type !== 'conversation.agent' ? effects.state.conversations.filter(c => c.reviewOf === command.conversationId
&& c.archived && !original.conversations.find(o => o.id === c.id)?.archived).map(c => c.id) : []
// One plain match per conversation: an `in` on this hot collection is sent as $expr, which no index bounds (hotFilters).
- for (const conversationId of unreadable ? [command.conversationId, ...archivedSteps] : []) {
- await tx.superTabDelivery.updateMany({ where: { tabId, conversationId, status: { in: [...CANCELLABLE_DELIVERY] },
- ...(command.type === 'conversation.agent' ? { agentId: command.agentId } : {}) },
- data: { status: 'cancelled', holdReason: null, holdSince: null } })
+ if (unreadable) {
+ const conversationIds = [command.conversationId, ...archivedSteps]
+ await this.endDeliveries(tx, tabId, {
+ ...(command.type === 'conversation.agent' ? { where: { agentId: command.agentId } } : {}),
+ matches: row => conversationIds.includes(row.conversationId),
+ }, async () => {
+ let count = 0
+ for (const conversationId of conversationIds) {
+ count += (await tx.superTabDelivery.updateMany({ where: { tabId, conversationId, status: { in: [...CANCELLABLE_DELIVERY] },
+ ...(command.type === 'conversation.agent' ? { agentId: command.agentId } : {}) },
+ data: { status: 'cancelled', holdReason: null, holdSince: null } })).count
+ }
+ return { count }
+ })
}
const removedGroups = original.conversations.filter(c => !effects.state.conversations.some(n => n.id === c.id))
if (removedGroups.length) {
// Keep immutable history and operation receipts for audit/replay; all
// reads require a live conversation. No removed group can deliver work.
- await tx.superTabDelivery.updateMany({ where: { tabId, conversationId: { in: removedGroups.map(c => c.id) },
- status: { in: [...CANCELLABLE_DELIVERY] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } })
+ await this.endDeliveries(tx, tabId, { matches: row => removedGroups.some(c => c.id === row.conversationId) }, () => tx.superTabDelivery.updateMany({ where: { tabId, conversationId: { in: removedGroups.map(c => c.id) },
+ status: { in: [...CANCELLABLE_DELIVERY] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } }))
}
// Each conversation numbers its own messages. Only a change of a work group's state wakes its coordinator, read through
// its latest message; an ordinary message never does (Dee, 2026-10-31).
@@ -1762,17 +1783,18 @@ export class SuperTabStore {
// delivery was finally typed. An agent's reply settles that agent's own deliveries of the message.
if (command.type === 'message.send' && command.replyTo && actor.kind === 'agent') {
// A notice gathered for the digest and answered before it (read in its chat): the digest does not name it again.
- await tx.superTabDelivery.updateMany({ where: { tabId, messageId: command.replyTo, agentId: actor.agentId,
+ const replyTo = command.replyTo, agentId = actor.agentId
+ await this.endDeliveries(tx, tabId, { where: { messageId: replyTo, agentId } }, () => tx.superTabDelivery.updateMany({ where: { tabId, messageId: replyTo, agentId,
status: { in: ['queued', 'claimed', 'uncertain', 'delivered', 'confirmed', 'gathered'] } },
- data: { status: 'answered', answeredAt: new Date(context.now), holdReason: null, holdSince: null } })
+ data: { status: 'answered', answeredAt: new Date(context.now), holdReason: null, holdSince: null } }))
}
if (command.type === 'project.report' && actor.kind === 'agent') {
// Judged on the progress after this report summarized what it names.
const progress = projectsOf(effects.state).find(p => p.id === command.projectId)?.progress
if (progress?.requestMessageId && answersRequest(progress, command.throughRevision)) {
- await tx.superTabDelivery.updateMany({ where: { tabId, agentId: actor.agentId, messageId: progress.requestMessageId,
+ await this.endDeliveries(tx, tabId, { where: { agentId: actor.agentId, messageId: progress.requestMessageId } }, () => tx.superTabDelivery.updateMany({ where: { tabId, agentId: actor.agentId, messageId: progress.requestMessageId,
status: { in: ['queued', 'claimed', 'uncertain', 'delivered', 'confirmed'] } },
- data: { status: 'answered', answeredAt: new Date(context.now), holdReason: null, holdSince: null } })
+ data: { status: 'answered', answeredAt: new Date(context.now), holdReason: null, holdSince: null } }))
}
}
const revoked = [
@@ -1785,8 +1807,10 @@ export class SuperTabStore {
// A gathered row whose sender went stays for its digest, which judges it: a Done outlives the agent that sent it (review of #2560).
...revoked.map(sender => ({ ...sender, status: { not: 'gathered' } })), ...(effects.cancelledAgents.length ? [{ agentId: { in: effects.cancelledAgents } }] : []),
]
- if (cancelled.length) await tx.superTabDelivery.updateMany({ where: { tabId,
- status: { in: [...CANCELLABLE_DELIVERY] }, OR: cancelled }, data: { status: 'cancelled', holdReason: null, holdSince: null } })
+ if (cancelled.length) await this.endDeliveries(tx, tabId, { matches: row => effects.cancelledAgents.includes(row.agentId)
+ || revoked.some(s => s.authorKind === row.authorKind && s.authorId === row.authorId && s.authorGeneration === row.authorGeneration) },
+ () => tx.superTabDelivery.updateMany({ where: { tabId,
+ status: { in: [...CANCELLABLE_DELIVERY] }, OR: cancelled }, data: { status: 'cancelled', holdReason: null, holdSince: null } }))
await this.requeueFormerLeads(tx, tabId, original, effects.state)
for (const attempt of effects.previousAttempts) {
await tx.superTabAttempt.create({ data: { id: attempt.assignment.id, tabId, conversationId: attempt.conversationId, snapshot: json(attempt) } })
@@ -2213,6 +2237,8 @@ export class SuperTabStore {
if (effect.op === 'request') {
const { op: _op, id, ...request } = effect
await tx.superTabTerminalRequest.create({ data: { id, tabId, ...request, createdAt: new Date(now) } })
+ const told = this.hooks.terminalWaiting
+ if (told) afterCommit(tx, () => told({ machineId: request.machineId, tabId, agentId: request.agentId }))
return
}
// The deadline holds whether or not the sender has asked for the answer yet.
@@ -2353,8 +2379,8 @@ export class SuperTabStore {
if (!assignmentIds.length) return
const assignmentId = { in: assignmentIds }
await tx.superTabRun.deleteMany({ where: { tabId, assignmentId } })
- await tx.superTabDelivery.updateMany({ where: { tabId, assignmentId, status: { in: [...CANCELLABLE_DELIVERY] } },
- data: { status: 'cancelled', holdReason: null, holdSince: null } })
+ await this.endDeliveries(tx, tabId, { matches: row => row.assignmentId !== null && assignmentIds.includes(row.assignmentId) }, () => tx.superTabDelivery.updateMany({ where: { tabId, assignmentId, status: { in: [...CANCELLABLE_DELIVERY] } },
+ data: { status: 'cancelled', holdReason: null, holdSince: null } }))
}
/** Run records an older server left in this Swarm for work that is no longer active here (see endRuns). Only this Swarm's,
@@ -2447,6 +2473,30 @@ export class SuperTabStore {
for (const delivery of deliveries) this.announce(tx, { machineId: delivery.machineId, tabId, agentId: delivery.agentId })
}
+ /**
+ * Ends deliveries (cancelled, answered) by `end`, and tells the machines whose agents had one claimed: a host holds a
+ * claimed delivery its pane refused (and says `hold` only after 30 s), and reads that agent's list only every 30 s (cli
+ * superTabs/host.ts), so without this it could type a message for that long after it was answered or withdrawn (spec
+ * 2026-11-02 poll cost, Part 3.2; final review). Only the machines holding what ends: each one told reads that agent's list,
+ * and every agent reply answers a delivery (review of #2632). One equality read per call of the claimed rows, which are few;
+ * [holds] says which of them `end` ends, as its filter does: plain equalities narrow the read, and anything an `in` would say
+ * is matched here, as `in` on this collection is what the hot-filter lint forbids. `end` stays a named `updateMany` at each
+ * caller, so that lint (hotFilters.test.ts) still sees it.
+ */
+ async endDeliveries(tx: Transaction, tabId: string, holds: DeliveriesEnding, end: () => Promise<{ count: number }>): Promise<{ count: number }> {
+ const rows = await tx.superTabDelivery.findMany({ where: { tabId, status: 'claimed', ...holds.where },
+ select: { machineId: true, agentId: true, conversationId: true, assignmentId: true, nativeContextId: true, authorKind: true, authorId: true, authorGeneration: true } })
+ const claimed = holds.matches ? rows.filter(holds.matches) : rows
+ const ended = await end()
+ if (ended.count) {
+ for (const key of new Set(claimed.map(row => `${row.machineId}\u0000${row.agentId}`))) {
+ const [machineId, agentId] = key.split('\u0000') as [string, string]
+ this.announce(tx, { machineId, tabId, agentId })
+ }
+ }
+ return ended
+ }
+
/** Once `tx` commits, never for an attempt that failed or was retried: told earlier, a host could read before the delivery
* is visible, and wait 30 s for its next read. */
private announce(tx: Transaction, waiting: DeliveriesWaiting): void {
@@ -3373,12 +3423,23 @@ export class SuperTabStore {
/** A withdrawn host can retire its own journal without regaining shared
* conversation access. Machine ownership is captured when input is created. */
async deliveryReceipt(user: AuthUser, tabId: string, agentId: string, deliveryId: string) {
+ return this.receiptOf(user, tabId, agentId, deliveryId).catch(error => {
+ // A host asking again and again about an entry refused for good (cli host.ts checkReceipts, spec 2026-11-02 poll cost).
+ if (error instanceof SuperTabError && (error.status === 403 || error.status === 404)) recordDeliveryCall(error.status === 403 ? 'receipt403' : 'receipt404')
+ throw error
+ })
+ }
+
+ private async receiptOf(user: AuthUser, tabId: string, agentId: string, deliveryId: string) {
return transaction(this.db, async tx => {
- const { state } = await this.load(tx, user, tabId)
+ // The Swarm must still be there and readable; its parts are read only for a row that does not name its owner (spec
+ // 2026-11-02 poll cost, Part 3.4: hosts ask about their journal every few seconds, and each answer loaded the Swarm).
+ const swarmRow = await this.row(tx, user, tabId)
// A host back after weeks offline asks about a delivery compacted since (deliveryCompaction.ts): answered from its receipt.
const row = await tx.superTabDelivery.findFirst({ where: { id: deliveryId, tabId, agentId } }) ?? await compactedDelivery(tx, tabId, agentId, deliveryId)
if (!row) fail('NOT_FOUND', 'This delivery is unavailable.', 404)
- const previous = state.agents.find(a => a.id === agentId && a.membershipGeneration === row.membershipGeneration)
+ const previous = row.machineOwnerId ? undefined
+ : (await loadRow(tx, swarmRow)).state.agents.find(a => a.id === agentId && a.membershipGeneration === row.membershipGeneration)
const owner = row.machineOwnerId ?? previous?.machineOwnerId
if (owner !== user.sub) fail('FORBIDDEN', 'Only the recorded execution host can read this receipt.', 403)
await this.hostFor(tx, user, row.machineId)
@@ -3394,6 +3455,8 @@ export class SuperTabStore {
action: { type: 'claim'; claimId: string } | { type: 'ack'; claimId: string; receipt: string; uncertain: boolean }
| { type: 'hold'; claimId: string; reason: HoldReason }) {
const reached = { authorized: false }
+ if (action.type === 'claim') noteClaim(deliveryId, this.now())
+ else if (action.type === 'hold') recordDeliveryCall('hold', action.reason)
try {
const answer = await this.deliver(user, tabId, agentId, deliveryId, action, reached)
// The claimed message's files as links of this claim, signed after its transaction (fileLinks.ts): a claim again, as the host
@@ -3695,10 +3758,15 @@ export class SuperTabStore {
// As a person's archive does (execute): a claim of a delivery here conflicts with this write.
// Its finished steps archive here too (execute does the same): a cancelled one stays open, to hear why. One plain match per
// conversation: an `in` on this hot collection is sent as $expr, which no index bounds (hotFilters).
- for (const conversationId of [groupId, ...stepsOf(state, group.id).filter(step => step.archived && !heldBefore.has(step.id)).map(step => step.id)]) {
- await tx.superTabDelivery.updateMany({ where: { tabId, conversationId, status: { in: [...CANCELLABLE_DELIVERY] } },
- data: { status: 'cancelled', holdReason: null, holdSince: null } })
- }
+ const endedIds = [groupId, ...stepsOf(state, group.id).filter(step => step.archived && !heldBefore.has(step.id)).map(step => step.id)]
+ await this.endDeliveries(tx, tabId, { matches: row => endedIds.includes(row.conversationId) }, async () => {
+ let count = 0
+ for (const conversationId of endedIds) {
+ count += (await tx.superTabDelivery.updateMany({ where: { tabId, conversationId, status: { in: [...CANCELLABLE_DELIVERY] } },
+ data: { status: 'cancelled', holdReason: null, holdSince: null } })).count
+ }
+ return { count }
+ })
// A review's close also writes the work it reviews (review of #2322): a Ready for review committed since the load linked
// a new pull request and saw this review still open, so it opened none. The touch makes one of the two writes retry,
// and the retry sees the other: this one declines (a pull request not read), or that one opens a new review.
@@ -3741,8 +3809,8 @@ export class SuperTabStore {
const unchanged = delivery.holdSince ? { claimId: delivery.claimId, holdReason: delivery.holdReason, holdSince: delivery.holdSince }
: { updatedAt: delivery.updatedAt }
const quiet = reachable && delivery.status === 'claimed' && !delivery.holdSince
- settled += (await tx.superTabDelivery.updateMany({ where: { id: delivery.id, tabId, status: delivery.status, ...unchanged },
- data: { status: 'cancelled', ...quiet ? { holdReason: QUIET_CLAIM } : {} } })).count
+ settled += (await this.endDeliveries(tx, tabId, { where: { id: delivery.id } }, () => tx.superTabDelivery.updateMany({ where: { id: delivery.id, tabId, status: delivery.status, ...unchanged },
+ data: { status: 'cancelled', ...quiet ? { holdReason: QUIET_CLAIM } : {} } }))).count
}
return settled
})
@@ -3774,8 +3842,8 @@ export class SuperTabStore {
finishWorker(state, assignment.agentId)
assignment.result = 'The execution host confirmed that this harness stopped.'
await tx.superTabRun.deleteMany({ where: { tabId, assignmentId } })
- await tx.superTabDelivery.updateMany({ where: { tabId, assignmentId,
- status: { in: [...CANCELLABLE_DELIVERY] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } })
+ await this.endDeliveries(tx, tabId, { where: { assignmentId } }, () => tx.superTabDelivery.updateMany({ where: { tabId, assignmentId,
+ status: { in: [...CANCELLABLE_DELIVERY] } }, data: { status: 'cancelled', holdReason: null, holdSince: null } }))
await closeAssignment(tx, tabId, assignmentId, 'stopped', this.now())
// No agent command closes this attempt, so nobody was told: in the two-account E2E of 2026-10-19
// the Lead learned of a stopped worker only by re-reading status. Say it in the group, as the
diff --git a/backend/src/worker.ts b/backend/src/worker.ts
index 71a21d542..74ac8cd8f 100644
--- a/backend/src/worker.ts
+++ b/backend/src/worker.ts
@@ -24,7 +24,7 @@ import { startDeliveryCompaction } from './superTabs/deliveryCompaction.js'
import { startThreadBackfill } from './superTabs/threadBackfill.js'
import { appPullRequests, markFinishedGroups, startSwarmArchive, unknownPullRequests } from './superTabs/archive.js'
import { SuperTabStore } from './superTabs/store.js'
-import { announceSwarmDeliveries } from './lib/swarmDeliveryPushes.js'
+import { announceSwarmDeliveries, announceSwarmTerminal } from './lib/swarmDeliveryPushes.js'
import { announceSwarmHostChanges } from './lib/swarmHostPushes.js'
import { announceSwarmChanges } from './lib/swarmClientPushes.js'
import { GitHubApp, githubAppConfig } from './github/app.js'
@@ -112,7 +112,7 @@ async function start(): Promise<void> {
configureSwarmStamps(redisSwarmStamps(), { reads: false })
// Archive notes and Workspace removals write messages too: their recipients' hosts hear of them at once, and of the
// groups they changed.
- const swarms = new SuperTabStore(prisma, Date.now, null, { deliveriesWaiting: announceSwarmDeliveries, hostsChanged: announceSwarmHostChanges,
+ const swarms = new SuperTabStore(prisma, Date.now, null, { deliveriesWaiting: announceSwarmDeliveries, terminalWaiting: announceSwarmTerminal, hostsChanged: announceSwarmHostChanges,
swarmChanged: announceSwarmChanges })
// Decisions still waiting in work that was over before #2454 closed them where work ends: they counted toward the open
// limit and came back on a reopen (store.ts withdrawEndedDecisions). Remove in the release after the one that runs it.
diff --git a/cli/e2e/productUsage.e2e.ts b/cli/e2e/productUsage.e2e.ts
index d86eebd78..d1564bec9 100644
--- a/cli/e2e/productUsage.e2e.ts
+++ b/cli/e2e/productUsage.e2e.ts
@@ -71,11 +71,12 @@ it('reports only local counters from a real turn, and the account switch stops t
expect(sum('request_app_resume_reason_saved_state_missing')).toBe(1)
const wire = JSON.stringify(backend.productUsage.reports)
for (const privateValue of ['PRIVATE_', creationId, machine.machineId, machine.computerId, machine.token, agentId, cwd, 'userMessage', 'payload']) expect(wire).not.toContain(privateValue)
+ // Counted before the choice: the collector reads it as soon as it is made, which may be before this request answers.
+ const checksBefore = backend.seen.filter(x => x === 'GET /api/product-usage/settings').length
expect((await fetch(settings, { method: 'POST', headers: d.localHeaders({ 'content-type': 'application/json', 'x-adapter-local': '1' }), body: '{"enabled":false}' })).status).toBe(200)
const reportsBefore = backend.productUsage.reports.length
- const checksBefore = backend.seen.filter(x => x === 'GET /api/product-usage/settings').length
await turn()
- await until('collector observes the off choice', () => backend!.seen.filter(x => x === 'GET /api/product-usage/settings').length > checksBefore || null, 75000)
+ await until('collector observes the off choice', () => backend!.seen.filter(x => x === 'GET /api/product-usage/settings').length > checksBefore || null, 15000)
expect(backend.productUsage.reports).toHaveLength(reportsBefore)
expect(d.coresStarted()).toBe(1)
}, 240000)
diff --git a/cli/src/backendSocket.spec.ts b/cli/src/backendSocket.spec.ts
index 92dadc337..80d0e55a5 100644
--- a/cli/src/backendSocket.spec.ts
+++ b/cli/src/backendSocket.spec.ts
@@ -2875,6 +2875,30 @@ describe('desk_changed relay', () => {
await socket.stop()
})
+ // Spec 2026-11-02-poll-cost Part 4.2: the server says a Lead's terminal request waits for this machine.
+ it('hands the backend\'s __terminal_waiting to the Swarm host, never to the windows, and only the backend\'s', async () => {
+ const socket = relaySocket('token')
+ const heard: unknown[] = []
+ const frames: Array<Record<string, unknown>> = []
+ socket.onAccountNotice = (notice) => { heard.push(notice) }
+ socket.registerLocalClient('local:swarm', { sendFrame: (frame) => { frames.push(frame); return true }, sendBinary: () => true })
+ socket.connect()
+ const ws = wsMock.instances[0]
+ ws.open()
+ ws.message({ t: 'down', connId: '', frame: { type: '__terminal_waiting', payload: { tabId: 'tab-1', agentId: 'agent-1' } } })
+ // One that names no agent is no request.
+ ws.message({ t: 'down', connId: '', frame: { type: '__terminal_waiting', payload: { tabId: 'tab-1' } } })
+ await vi.waitFor(() => expect(heard).toEqual([{ type: '__terminal_waiting', tabId: 'tab-1', agentId: 'agent-1' }]))
+ // A client relayed with its own connId, or a local one, is not the backend.
+ ws.message({ t: 'down', connId: 'web-1', frame: { type: '__terminal_waiting', payload: { tabId: 'tab-1', agentId: 'agent-2' } } })
+ socket.handleLocalFrame('local:swarm', { type: '__terminal_waiting', payload: { tabId: 'tab-1', agentId: 'agent-3' } })
+ await new Promise((r) => setTimeout(r, 20))
+ expect(heard).toHaveLength(1)
+ expect(frames.filter((f) => f.type === '__terminal_waiting')).toEqual([])
+ await socket.unregisterLocalClient('local:swarm')
+ await socket.stop()
+ })
+
it('hands the backend\'s zoo_changed to the window as its own frame, and only the backend\'s', async () => {
const socket = relaySocket('token')
const frames: Array<Record<string, unknown>> = []
diff --git a/cli/src/backendSocket.ts b/cli/src/backendSocket.ts
index 43a4edd2e..dcb612505 100644
--- a/cli/src/backendSocket.ts
+++ b/cli/src/backendSocket.ts
@@ -476,7 +476,7 @@ export class BackendSocket {
notice: (notice: BackendNotice) => {
this.onAccountNotice?.(notice)
// Only the Swarm host acts on these (superTabs/host.ts): the windows have nothing to re-read.
- if (notice.type === 'super_tab_deliveries' || notice.type === 'swarm_host_changed') return
+ if (notice.type === 'super_tab_deliveries' || notice.type === 'swarm_host_changed' || notice.type === '__terminal_waiting') return
if (notice.type === 'machines_changed' && notice.reason === 'harness_shares') { this.sharesNotice.tell(); return }
// A Swarm changed: its id, time and parts, or nothing for the server's word that it pushes (desktop swarm_pushes.dart).
if (notice.type === 'swarm_changed') {
diff --git a/cli/src/cloud/bridge.socket.spec.ts b/cli/src/cloud/bridge.socket.spec.ts
index 38645872f..10a29b784 100644
--- a/cli/src/cloud/bridge.socket.spec.ts
+++ b/cli/src/cloud/bridge.socket.spec.ts
@@ -3,8 +3,10 @@ import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:f
import { createServer, type Server } from 'node:http'
import type { AddressInfo } from 'node:net'
import { dirname, join } from 'node:path'
-import { bridgeKey, bridgeSocketPath, harnessKey, retireBridgeKey, rotateHarnessKey, KEY_GRACE_MS } from '../lib/connectors/agents.js'
-import { serveBridgeSocket } from '../lib/connectors/bridge.js'
+import { randomBytes } from 'node:crypto'
+import { bridgeKey, bridgePipeRecord, bridgeSocketPath, harnessKey, retireBridgeKey, rotateHarnessKey, KEY_GRACE_MS } from '../lib/connectors/agents.js'
+import { serveBridgePipe, serveBridgeSocket } from '../lib/connectors/bridge.js'
+import { writePrivate } from '../lib/connectors/store.js'
import type { LocalSocketServer } from '../lib/localSocket.js'
import { Store } from '../lib/connectors/store.js'
import { fakeCore } from '../testing/fakeCore.js'
@@ -233,3 +235,62 @@ describe('the keys that crossed the port', () => {
expect(vault.file('bridge.json').keyRetiresAt).toBeUndefined()
})
})
+
+// Task #2162 (Reed's review of #2605): on Windows Harness's own route went to the port, which the Team account can hold from boot,
+// and took its answers. It goes over the bridge's pipe, which proves itself (serveBridgePipe). A socket named as a pipe stands for it.
+describe('Harness\'s own route on Windows: the bridge\'s pipe', () => {
+ const pipePath = (): string => {
+ mkdirSync(join(home, 'p'), { recursive: true })
+ return join(home, 'p', `harness-${randomBytes(16).toString('hex')}`)
+ }
+
+ it('list, API and MCP calls all go over the pipe; a holder of the port hears nothing', async () => {
+ const hold = await holder()
+ vi.stubEnv('HARNESS_CONNECTIONS_PORT', String(hold.port))
+ closers.push(() => vi.unstubAllEnvs())
+ const api = await service((url) => ({ body: JSON.stringify({ url }) }))
+ const mcp = await service((_url, body) => {
+ const message = JSON.parse(body) as { id?: number; method: string }
+ return { body: JSON.stringify({ jsonrpc: '2.0', id: message.id, result: message.method === 'tools/list' ? { tools: [{ name: 'a' }] } : { protocolVersion: '2025-06-18' } }) }
+ })
+ vault.save('devin', { access_token: 't', source: 'custom', transport: 'none', api_entry: { origin: api } } as never)
+ vault.save('fo', { access_token: 't', source: 'dcr', mcp_entry: { url: `${mcp}/mcp`, headers: {} } })
+ const listening = await serveBridgePipe(vault, pipePath())
+ closers.push(() => listening.close())
+ const route = bridgeRoute(vault, 'win32')
+ expect(route.base).toMatch(/^http:\/\/connections\.invalid\//)
+ const bridge = connectionsBridge(() => route)
+ expect((await bridge.connections()).map(c => c.code).sort()).toEqual(['devin', 'fo'])
+ expect((await bridge.api('devin', 'GET', '/v3/self')).status).toBe(200)
+ const client = new McpClient(bridge.mcpUrl('fo'), 'Fo', bridge.fetch)
+ expect((await client.tools()).map(t => t.name)).toEqual(['a'])
+ expect(hold.heard).toEqual([])
+ })
+
+ it('with no live pipe says Connections is not running, and sends nothing to the port', async () => {
+ const hold = await holder()
+ vi.stubEnv('HARNESS_CONNECTIONS_PORT', String(hold.port))
+ closers.push(() => vi.unstubAllEnvs())
+ await expect(connectionsBridge(() => bridgeRoute(vault, 'win32')).connections()).rejects.toThrow()
+ const listening = await serveBridgePipe(vault, pipePath())
+ await listening.close()
+ // The record outlives a bridge that stopped; its process must still run for it to be dialled.
+ writePrivate(bridgePipeRecord(vault), { ...vault.file('bridge-pipe.json'), pid: 2 ** 22 + 1 })
+ await expect(connectionsBridge(() => bridgeRoute(vault, 'win32')).connections()).rejects.toThrow()
+ expect(hold.heard).toEqual([])
+ })
+
+ it('takes no answer that does not prove the token: a pipe made under the bridge\'s name lists nothing for Harness', async () => {
+ const path = pipePath(), heard: string[] = []
+ const squatter = createServer((request, response) => {
+ heard.push(request.url ?? '')
+ response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ connections: [{ code: 'fake' }] }))
+ })
+ await new Promise<void>(ready => squatter.listen(path, ready))
+ closers.push(() => new Promise(done => { squatter.closeAllConnections(); squatter.close(done) }))
+ writePrivate(bridgePipeRecord(vault), { pipe: path, pid: process.pid, token: randomBytes(32).toString('hex') })
+ await expect(connectionsBridge(() => bridgeRoute(vault, 'win32')).connections()).rejects.toThrow()
+ expect(heard).toHaveLength(1)
+ })
+})
+
diff --git a/cli/src/cloud/bridge.ts b/cli/src/cloud/bridge.ts
index 4bbb0f0d1..c9ba65282 100644
--- a/cli/src/cloud/bridge.ts
+++ b/cli/src/cloud/bridge.ts
@@ -3,8 +3,8 @@
* connection's credential, so this service holds none (services/AGENTS.md, "Do not hold credentials").
* A connection is found by where it points (Fo's MCP server, Devin's API), not by what the person named it.
*/
-import { bridgePort, bridgeSocketPath, harnessKey } from '../lib/connectors/agents.js'
-import { fetchOverSocket } from '../lib/localTransport.js'
+import { bridgePort, bridgeSocketPath, harnessKey, readBridgePipe } from '../lib/connectors/agents.js'
+import { fetchOverPipe, fetchOverSocket } from '../lib/localTransport.js'
import { Store } from '../lib/connectors/store.js'
import { CLOUD_AGENTS, type CloudAgentId } from '../lib/cloudAgents.js'
import { CloudError } from './types.js'
@@ -26,15 +26,17 @@ export interface BridgeRoute { base: string; fetch: typeof fetch }
/**
* Through Harness's own key (agents.ts `harnessKey`), never the one in the agents' configurations, and over the bridge's 0600 socket
- * where it can have one: whoever holds a port hears what is sent to it (audit H1). With the socket gone Connections is down, and
- * nothing goes to the port. The address's host is then only a name, one that resolves nowhere (RFC 6761), so the key cannot leave if the
+ * where it can have one, or on Windows its pipe: whoever holds a port hears what is sent to it and can answer it (audit H1; on
+ * Windows the Team account from boot, task #2162). The pipe is read for each request, dialled only while the bridge's process runs,
+ * and its answer must prove the token (agents.ts `readBridgePipe`). With the socket or pipe gone Connections is down, and nothing
+ * goes to the port. The address's host is then only a name, one that resolves nowhere (RFC 6761), so the key cannot leave if the
* address ever reached plain `fetch`.
*/
-export function bridgeRoute(vault: Store = new Store()): BridgeRoute {
- const socket = bridgeSocketPath(vault)
- return socket
- ? { base: `http://connections.invalid/${harnessKey(vault)}`, fetch: fetchOverSocket(socket) }
- : { base: `http://127.0.0.1:${bridgePort(process.env, vault)}/${harnessKey(vault)}`, fetch: (input, init) => fetch(input, init) }
+export function bridgeRoute(vault: Store = new Store(), platform: NodeJS.Platform = process.platform): BridgeRoute {
+ const socket = bridgeSocketPath(vault, platform)
+ if (socket) return { base: `http://connections.invalid/${harnessKey(vault)}`, fetch: fetchOverSocket(socket) }
+ if (platform === 'win32') return { base: `http://connections.invalid/${harnessKey(vault)}`, fetch: fetchOverPipe(() => readBridgePipe(vault)) }
+ return { base: `http://127.0.0.1:${bridgePort(process.env, vault)}/${harnessKey(vault)}`, fetch: (input, init) => fetch(input, init) }
}
export function connectionsBridge(target: () => string | BridgeRoute = () => bridgeRoute()): Bridge {
diff --git a/cli/src/core/api.ts b/cli/src/core/api.ts
index 51c1d135e..20b1c07f3 100644
--- a/cli/src/core/api.ts
+++ b/cli/src/core/api.ts
@@ -1595,6 +1595,9 @@ export type BackendNotice =
/** Work waits for an agent of this machine's (backend lib/adapterWs.ts): its Swarm host reads that agent's deliveries now.
* Naming none, the server says it pushes them, and every list is read once (superTabs/host.ts PUSH_LEASE_MS). */
| { type: 'super_tab_deliveries'; tabId?: string; agentId?: string }
+ /** A Lead's terminal request waits for an agent of this machine (backend lib/swarmDeliveryPushes.ts): its Swarm host picks
+ * it up now rather than at its next poll (superTabs/terminal.ts). The backend's `__` frame, kept by name. */
+ | { type: '__terminal_waiting'; tabId: string; agentId: string }
/** A commit changed what this machine's Swarm host reads (backend lib/swarmHostPushes.ts): it reads its changes now. Naming
* none, the server says it pushes them, and the host reads only when told (superTabs/hostFeed.ts HOST_PUSH_LEASE_MS). */
| { type: 'swarm_host_changed'; tabId?: string; lastChangedAt?: number }
diff --git a/cli/src/core/experiments.spec.ts b/cli/src/core/experiments.spec.ts
index b693ac607..1e0d99cfd 100644
--- a/cli/src/core/experiments.spec.ts
+++ b/cli/src/core/experiments.spec.ts
@@ -187,6 +187,27 @@ describe('the account\'s agent experiments, kept for this computer', () => {
expect(t.backend).toHaveBeenCalledTimes(3)
})
+ // Spec 2026-11-02-poll-cost Part 4.5: every desk operation (a tab moved, renamed, opened) made every daemon read the
+ // experiments again (prod 2026-11-02: 127 a minute). A change to them publishes revision 0 (backend
+ // routes/experimentalSettings.ts); a desk operation publishes the desk's own revision.
+ it('a desk operation\'s desk_changed reads no experiments, a revision-0 one does', async () => {
+ vi.useFakeTimers()
+ const t = setup({ everyMs: null })
+ answer(account({}))
+ t.sync.start()
+ await vi.advanceTimersByTimeAsync(0)
+ expect(t.backend).toHaveBeenCalledTimes(1)
+ t.notice({ type: 'desk_changed', revision: 7 })
+ await vi.advanceTimersByTimeAsync(0)
+ expect(t.backend).toHaveBeenCalledTimes(1)
+ answer(account({ agent_messages: true }))
+ t.notice({ type: 'desk_changed', revision: 0 })
+ await vi.advanceTimersByTimeAsync(0)
+ expect(t.backend).toHaveBeenCalledTimes(2)
+ expect(kept()).toEqual({ ...OFF, agentMessages: true })
+ t.sync.stop()
+ })
+
it('reads them again every five minutes when not told otherwise', async () => {
vi.useFakeTimers()
const t = setup({ everyMs: null })
diff --git a/cli/src/core/experiments.ts b/cli/src/core/experiments.ts
index a90e5ed87..e42339098 100644
--- a/cli/src/core/experiments.ts
+++ b/cli/src/core/experiments.ts
@@ -63,7 +63,7 @@ const ACCOUNT_UNAVAILABLE = 'Harness could not reach your account to change this
/**
* The account's three agent experiments (lib/agentSettings.ts), kept for this computer: the copy in the data folder is
* what every launch, `harness new` and Agent Messages read, and this is its only writer. It reads the account's
- * experiments as the core starts, at every `desk_changed` (a change to them publishes one: backend
+ * experiments as the core starts, at a `desk_changed` of revision 0 (a change to them publishes one: backend
* routes/experimentalSettings.ts), every AGENT_SETTINGS_SYNC_MS besides, and in every answer the windows get through
* this daemon (`/api/experimental-settings`), so a switch turned here holds here at once. Signed out it reads nothing,
* and the copy reads as the defaults.
@@ -132,7 +132,10 @@ export function createAgentSettingsSync(deps: {
return {
start(): void {
if (timer) return
- unsubscribe = deps.onNotice((notice) => { if (notice.type === 'desk_changed') void request() })
+ // Only the experiments' own change, which publishes revision 0 (backend routes/experimentalSettings.ts): a desk operation
+ // publishes the desk's revision, and every one of them made every daemon read these again (spec 2026-11-02-poll-cost
+ // Part 4.5, 127 reads a minute in prod).
+ unsubscribe = deps.onNotice((notice) => { if (notice.type === 'desk_changed' && notice.revision === 0) void request() })
timer = setInterval(() => { void request() }, deps.everyMs ?? AGENT_SETTINGS_SYNC_MS)
timer.unref()
void request()
diff --git a/cli/src/core/main.ts b/cli/src/core/main.ts
index 87ed4349f..4607c94b4 100644
--- a/cli/src/core/main.ts
+++ b/cli/src/core/main.ts
@@ -1547,6 +1547,11 @@ async function runForeground(session: AuthSession | null): Promise<void> {
if (notice.type === 'machines_changed' && outOfProcess.has('sharedMachines')) {
serviceLinks.notify('sharedMachines', { type: 'service_event', payload: { kind: 'notice', notice } })
}
+ // The devices' fleet reads the machine list on `machines_changed` (services/fleet.ts); in its own process it hears it
+ // only through this (services/devicesProcess.ts), in the core's through `account.onNotice`.
+ if (notice.type === 'machines_changed' && outOfProcess.has('devices')) {
+ serviceLinks.notify('devices', { type: 'service_event', payload: { kind: 'notice', notice } })
+ }
}
// What shared machines in their own process reach through the core: this machine's sharing on the
// backend, signed in here, and the gateway's trust stores (core/sharedMachinesQueries.ts).
diff --git a/cli/src/device/machineList.spec.ts b/cli/src/device/machineList.spec.ts
index c842e2308..212a8ad6c 100644
--- a/cli/src/device/machineList.spec.ts
+++ b/cli/src/device/machineList.spec.ts
@@ -149,6 +149,70 @@ describe('MachineListCache', () => {
// The desktop app reads this same endpoint through the daemon, so an outage must leave it with the last
// known list rather than nothing — see `machinesListWithFallback` in cli.ts.
+// Spec 2026-11-02-poll-cost Part 4.4: the fleet's own refresh may be served a list read within 45 s, and any read joins one
+// already in flight; a window's read (maxAgeMs 0) still reads, so it sees a rename or a new machine at once.
+describe('MachineListCache.refresh', () => {
+ it('serves a list younger than maxAgeMs, reads with none, and joins a read in flight', async () => {
+ vi.useFakeTimers({ now: 1_000_000 })
+ try {
+ const fetch = vi.fn(ok([row()]))
+ const cache = new MachineListCache(fetch, () => 'z', () => {}, DIR(), () => OWNER)
+ await cache.refresh()
+ vi.advanceTimersByTime(44_999)
+ expect(await cache.refresh({ maxAgeMs: 45_000 })).toEqual({ status: 200, body: { machines: [row()] } })
+ expect(fetch).toHaveBeenCalledTimes(1)
+ vi.advanceTimersByTime(1)
+ await cache.refresh({ maxAgeMs: 45_000 })
+ expect(fetch).toHaveBeenCalledTimes(2)
+ await cache.refresh({ maxAgeMs: 0 })
+ await cache.refresh()
+ expect(fetch).toHaveBeenCalledTimes(4)
+ const [a, b] = await Promise.all([cache.refresh(), cache.refresh({ maxAgeMs: 0 })])
+ expect(fetch).toHaveBeenCalledTimes(5)
+ expect(a).toBe(b)
+ } finally { vi.useRealTimers() }
+ })
+
+ // Final review: a read that began before a rename answers with the old name; asked for after it, read again.
+ it('a read that must be fresh does not take one that began before it was asked for', async () => {
+ vi.useFakeTimers({ now: 1_000_000 })
+ try {
+ let release!: () => void
+ const answers = [async () => { await new Promise<void>(resolve => { release = resolve }); return { status: 200, body: { machines: [row()] } } },
+ async () => ({ status: 200, body: { machines: [{ ...row(), name: 'Renamed' }] } })]
+ const fetch = vi.fn(() => answers.shift()!())
+ const cache = new MachineListCache(fetch, () => 'z', () => {}, DIR(), () => OWNER)
+ const earlier = cache.refresh()
+ vi.advanceTimersByTime(10)
+ const fresh = cache.refresh({ maxAgeMs: 0 })
+ release()
+ await earlier
+ expect((await fresh)!.body).toEqual({ machines: [{ ...row(), name: 'Renamed' }] })
+ expect(fetch).toHaveBeenCalledTimes(2)
+ } finally { vi.useRealTimers() }
+ })
+
+ it('serves nothing held once a read failed, nor a list another account read', async () => {
+ vi.useFakeTimers({ now: 1_000_000 })
+ try {
+ let owner = OWNER
+ let answer: () => Promise<{ status: number; body: Record<string, unknown> }> = ok([row()])
+ const fetch = vi.fn(() => answer())
+ const cache = new MachineListCache(fetch, () => 'z', () => {}, DIR(), () => owner)
+ await cache.refresh()
+ answer = async () => { throw new Error('offline') }
+ await cache.refresh()
+ expect(await cache.refresh({ maxAgeMs: 45_000 })).toBeNull()
+ expect(fetch).toHaveBeenCalledTimes(3)
+ answer = ok([row()])
+ await cache.refresh()
+ owner = 'machine-of-user-b'
+ await cache.refresh({ maxAgeMs: 45_000 })
+ expect(fetch).toHaveBeenCalledTimes(5)
+ } finally { vi.useRealTimers() }
+ })
+})
+
describe('MachineListCache last-known-good body', () => {
it('keeps the successful response verbatim, so a fallback cannot change the wire shape', async () => {
const dir = DIR()
diff --git a/cli/src/device/machineList.ts b/cli/src/device/machineList.ts
index 90436245e..cc2196a35 100644
--- a/cli/src/device/machineList.ts
+++ b/cli/src/device/machineList.ts
@@ -74,6 +74,8 @@ export class MachineListCache {
private lastWrittenContent = ''
private lastWrittenAt = 0
private readonly listeners = new Set<(body: Record<string, unknown> | null) => void>()
+ /** The read in flight, which every refresh meanwhile shares. */
+ private reading: Promise<{ status: number; body: Record<string, unknown> } | null> | null = null
constructor(
private readonly fetchMachines: () => Promise<{ status: number; body: Record<string, unknown> }>,
@@ -136,8 +138,32 @@ export class MachineListCache {
* Never throws. A daemon that cannot reach the backend still has one machine that works perfectly — the
* one on the other end of the cable — so an outage downgrades `source` and keeps the last known rows
* rather than emptying the wheel.
+ *
+ * `maxAgeMs`: a list this session read that recently is answered as it is (spec 2026-11-02-poll-cost Part 4.4: the
+ * fleet's own refresh, every daemon with a dial reading every minute). None, the default, always reads: a window that
+ * re-reads after a rename or `machines_changed` must see it. Either way a read already in flight is shared.
*/
- async refresh(): Promise<{ status: number; body: Record<string, unknown> } | null> {
+ async refresh(options: { maxAgeMs?: number } = {}): Promise<{ status: number; body: Record<string, unknown> } | null> {
+ const asked = Date.now()
+ if (this.source === 'backend' && this.lastBody && this.bodyOwner === this.owner() && asked - this.fetchedAt < (options.maxAgeMs ?? 0)) {
+ return { status: 200, body: this.lastBody }
+ }
+ // A read that must be fresh (no maxAgeMs: after a rename or `machines_changed`) never takes one that began before it was
+ // asked for, which may hold the old list (final review); it waits for that one and reads again.
+ if (this.reading && !options.maxAgeMs && this.readingSince < asked) {
+ await this.reading.catch(() => null)
+ if (this.reading && this.readingSince >= asked) return this.reading
+ }
+ if (!this.reading) {
+ this.readingSince = Date.now()
+ this.reading = this.read().finally(() => { this.reading = null })
+ }
+ return this.reading
+ }
+ /** When the read in flight began. */
+ private readingSince = 0
+
+ private async read(): Promise<{ status: number; body: Record<string, unknown> } | null> {
const owner = this.owner()
let res: { status: number; body: Record<string, unknown> }
try {
diff --git a/cli/src/gateway/gateway.ts b/cli/src/gateway/gateway.ts
index 184ff624f..57539ee45 100644
--- a/cli/src/gateway/gateway.ts
+++ b/cli/src/gateway/gateway.ts
@@ -712,6 +712,13 @@ export class RelayGateway implements GatewayPort {
await this.core.disconnected(connId)
return
}
+ // A Lead's terminal request waits for an agent of this machine (spec 2026-11-02-poll-cost Part 4.2): the Swarm host picks
+ // it up now. A `__` frame, so a daemon from before it drops it below; one naming no agent is no request.
+ if (type === '__terminal_waiting') {
+ const p = (typeof frame.payload === 'object' && frame.payload !== null ? frame.payload : {}) as Record<string, unknown>
+ if (typeof p.tabId === 'string' && typeof p.agentId === 'string') this.core.notice({ type, tabId: p.tabId, agentId: p.agentId })
+ return
+ }
// Other backend-hub internal control frames (__clients_dirty) — not for us; drop silently.
if (type.startsWith('__')) return
diff --git a/cli/src/gateway/productUsage.spec.ts b/cli/src/gateway/productUsage.spec.ts
index f40510620..94f4d21a2 100644
--- a/cli/src/gateway/productUsage.spec.ts
+++ b/cli/src/gateway/productUsage.spec.ts
@@ -674,14 +674,89 @@ describe('when reports go', () => {
it('spreads the later ticks across 45 to 75 seconds', async () => {
const values = [0, 0, 0.5, 0.99999]
- start(() => values.shift() ?? 0)
+ // Each tick samples the gateway's resources, at most once in 45 s (gateway/productHealth.ts): what shows a tick here.
+ const sampled: number[] = []
+ usage = createProductUsage({ file, now: () => Date.now(), request, random: () => values.shift() ?? 0,
+ context: { surface: 'cli', release: '0.4.0', platform: 'macos', channel: 'production' },
+ sample: () => { sampled.push(Date.now()); return { rss: 1 } }, write: async (target, data) => { writeFileSync(target, data) } })
+ await usage.sync(false)
+ await vi.advanceTimersByTimeAsync(200_000)
+ // The gateway's own read, then a tick 10 s on (the first report's, under the 45 s floor), then 45, 60 and 74.999 s apart.
+ expect(sampled).toEqual([at(0), at(55_000), at(115_000), at(189_999)])
+ })
+
+ // Spec 2026-11-02-poll-cost Part 4.1: each gateway read the choice and reported at every tick, 45 to 75 s apart (prod
+ // 2026-11-02: 330 settings GETs and 284 report POSTs a minute), though the report already carries the choice's revision.
+ it('settings are read at start, on a local choice, hourly, and on CHOICE_CHANGED only', async () => {
+ start(() => 0.5)
const reads: number[] = []
const answer = request.getMockImplementation()!
request.mockImplementation(async (method, path, body) => { if (method === 'GET') reads.push(Date.now()); return answer(method, path, body) })
+ await usage.sync(false); usage.counter('search_requests')
+ // Ticks every 60 s from 35 s: the first at or after the hour is at 3,635 s.
+ await vi.advanceTimersByTimeAsync(3_640_000)
+ expect(reads).toEqual([at(0), at(3_635_000)])
+ // This computer's own read (`sync`): at once.
+ await usage.sync()
+ expect(reads).toHaveLength(3)
+ // A report refused because the choice changed elsewhere (the tick at 3,695 s): read at the next tick.
+ usage.counter('search_requests')
+ answers = [{ status: 200, body: { data: { accepted: false, reason: 'CHOICE_CHANGED' } } }]
+ await vi.advanceTimersByTimeAsync(55_000)
+ const refused = posts.at(-1)!
+ expect(refused).toBe(at(3_695_000))
+ expect(reads.filter(time => time > refused)).toEqual([])
+ await vi.advanceTimersByTimeAsync(60_000)
+ expect(reads.filter(time => time > refused)).toEqual([refused + 60_000])
+ })
+
+ // The choice made on this computer (Settings here, through the core's proxy) is read at once, not at the next hourly read.
+ it('reads a choice made on this computer at once, and stops counting if it is off', async () => {
+ start(() => 0.5)
await usage.sync(false)
- await vi.advanceTimersByTimeAsync(200_000)
- // The gateway's own read, then a tick 10 s on (the first report's), then 45, 60 and 74.999 s apart.
- expect(reads).toEqual([at(0), at(10_000), at(55_000), at(115_000), at(189_999)])
+ const reads: number[] = []
+ request.mockImplementation(async (method: string, _path: string, body?: unknown) => {
+ if (method === 'GET') { reads.push(Date.now()); return { status: 200, body: { data: { enabled: false, revision: 1 } } } }
+ posts.push(Date.now()); sent.push(structuredClone(body))
+ return { status: 200, body: { data: { accepted: true } } }
+ })
+ await usage.choiceChanged()
+ expect(reads).toEqual([T0])
+ usage.counter('search_requests')
+ await vi.advanceTimersByTimeAsync(600_000)
+ expect(posts).toEqual([])
+ })
+
+ it('reads a choice made on this computer after a report already on its way, never instead of reading', async () => {
+ start(() => 0.5)
+ await usage.sync(false); usage.counter('search_requests')
+ const reads: number[] = []
+ let release = (): void => {}
+ const held = new Promise<void>(resolve => { release = resolve })
+ request.mockImplementation(async (method: string, _path: string, body?: unknown) => {
+ if (method === 'GET') { reads.push(Date.now()); return { status: 200, body: { data: { enabled: false, revision: 1 } } } }
+ posts.push(Date.now()); sent.push(structuredClone(body))
+ await held
+ return { status: 200, body: { data: { accepted: true } } }
+ })
+ await vi.advanceTimersByTimeAsync(35_000)
+ expect(posts).toEqual([at(35_000)])
+ const changed = usage.choiceChanged()
+ await vi.advanceTimersByTimeAsync(0)
+ expect(reads).toEqual([])
+ release()
+ await changed
+ expect(reads).toHaveLength(1)
+ })
+
+ it('reports go every 5 minutes', async () => {
+ start(() => 0.5)
+ await usage.sync(false)
+ for (let minute = 0; minute < 20; minute++) { usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(60_000) }
+ // Ticks every 60 s from 35 s; the first report at the first tick, each next at the first tick 5 minutes on.
+ expect(posts).toEqual([at(35_000), at(335_000), at(635_000), at(935_000)])
+ // From the queue on disk: what the ticks between them counted goes in the next report, none lost.
+ expect(totals().search_requests).toBe(16)
})
it('backs off a busy backend, longer each time and at most half an hour, counting each attempt as before', async () => {
@@ -689,14 +764,14 @@ describe('when reports go', () => {
await usage.sync(false); usage.counter('search_requests')
answers = Array.from({ length: 12 }, () => ({ status: 429, body: { error: { code: 'USAGE_BUSY' } } }))
await vi.advanceTimersByTimeAsync(3 * 3600_000)
- // Ticks every 60 s here (0.5 of 45 to 75) and half of a ceiling that doubles from two minutes to the half
- // hour: twelve refusals in 2.3 hours, where a report each minute made 135 attempts.
- const gaps = posts.slice(1, 13).map((t, i) => t - posts[i])
- expect(gaps).toEqual([60_000, 120_000, 240_000, 480_000, ...Array(8).fill(900_000)])
- // Answered again: a report each tick, and each refused attempt counted once.
+ // Ticks every 60 s here (0.5 of 45 to 75), reports at most every 5 minutes, and half of a ceiling that doubles from two
+ // minutes to the half hour: twelve refusals in 2.2 hours, where a report each minute made 135 attempts.
+ const gaps = posts.slice(1, 12).map((t, i) => t - posts[i])
+ expect(gaps).toEqual([300_000, 300_000, 300_000, 480_000, ...Array(7).fill(900_000)])
+ // Answered again: a report every 5 minutes, and each refused attempt counted once.
const attempts = posts.length
- usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(60_000)
- usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(60_000)
+ usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(300_000)
+ usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(300_000)
expect(posts.length).toBe(attempts + 2)
expect(totals().health_cli_report_rejected).toBe(12)
expect(totals().health_cli_report_failure_rate_limited).toBe(12)
@@ -706,25 +781,33 @@ describe('when reports go', () => {
start(() => 0.5)
await usage.sync(false); usage.counter('search_requests')
answers = [{ status, body: { error: { code } } }, { status, body: { error: { code } } }]
- await vi.advanceTimersByTimeAsync(35_000 + 60_000 + 60_000)
- expect(posts).toEqual([at(35_000), at(95_000)])
+ await vi.advanceTimersByTimeAsync(35_000 + 300_000 + 60_000)
+ expect(posts).toEqual([at(35_000), at(335_000)])
})
it('backs off a report whose request threw, and not one the backend refused as invalid', async () => {
start(() => 0.5)
await usage.sync(false); usage.counter('search_requests')
- const choice = async () => ({ status: 200, body: { data: { enabled: true, revision: 0 } } })
- const thrown = async () => { posts.push(Date.now()); throw new Error('PRIVATE_CANARY') }
- request.mockImplementationOnce(choice).mockImplementationOnce(thrown).mockImplementationOnce(choice).mockImplementationOnce(thrown)
- await vi.advanceTimersByTimeAsync(95_000)
- expect(posts).toEqual([at(35_000), at(95_000)])
- // Two in a row: up to four minutes, here two, so the tick at 155 s sends nothing.
+ const reads: number[] = []
+ let throws = 2
+ request.mockImplementation(async (method: string, _path: string, body?: unknown) => {
+ if (method === 'GET') { reads.push(Date.now()); return { status: 200, body: { data: { enabled: true, revision: 0 } } } }
+ posts.push(Date.now())
+ if (throws-- > 0) throw new Error('PRIVATE_CANARY')
+ sent.push(structuredClone(body))
+ return answers.shift() ?? { status: 200, body: { data: { accepted: true } } }
+ })
+ await vi.advanceTimersByTimeAsync(335_000)
+ // A request that threw says nothing of the choice: it is read again at the next tick.
+ expect(posts).toEqual([at(35_000), at(335_000)])
+ expect(reads).toEqual([at(95_000)])
+ // Two in a row: up to four minutes, here two, inside the 5 minutes anyway.
answers = [{ status: 400, body: {} }]
- await vi.advanceTimersByTimeAsync(120_000)
- expect(posts).toEqual([at(35_000), at(95_000), at(215_000)])
- // The backend's answer, if a refusal: the next report goes at the next tick.
- usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(60_000)
- expect(posts).toEqual([at(35_000), at(95_000), at(215_000), at(275_000)])
+ await vi.advanceTimersByTimeAsync(300_000)
+ expect(posts).toEqual([at(35_000), at(335_000), at(635_000)])
+ // The backend's answer, if a refusal: the next report goes 5 minutes on.
+ usage.counter('search_requests'); await vi.advanceTimersByTimeAsync(300_000)
+ expect(posts).toEqual([at(35_000), at(335_000), at(635_000), at(935_000)])
expect(JSON.stringify(sent)).not.toContain('PRIVATE_CANARY')
})
@@ -752,16 +835,16 @@ describe('when reports go', () => {
answers = [{ status: 429, body: { success: false, error: { code: 'USAGE_WRITE_CONFLICT' } }, retryAfterMs: 90_000 }]
await vi.advanceTimersByTimeAsync(10_000)
expect(posts).toEqual([at(10_000)])
- // Ticks every 45 s here; the one at 55 s is inside the 90 s asked, the one at 100 s is not.
- await vi.advanceTimersByTimeAsync(90_000 - 1)
+ // Ticks every 45 s here; the 90 s asked are inside the 5 minutes between reports, so the tick at 325 s sends it.
+ await vi.advanceTimersByTimeAsync(315_000 - 1)
expect(posts).toHaveLength(1)
await vi.advanceTimersByTimeAsync(1)
- expect(posts).toEqual([at(10_000), at(100_000)])
+ expect(posts).toEqual([at(10_000), at(325_000)])
// Not lost: the same receipt and counts again, which the backend's receipt makes count once.
expect(sent[1]).toEqual(sent[0])
expect(JSON.parse(readFileSync(file, 'utf8')).pending).toBeNull()
// The refusal's own counts go in the next report.
- await vi.advanceTimersByTimeAsync(45_000)
+ await vi.advanceTimersByTimeAsync(315_000)
expect(posts).toHaveLength(3)
expect(totals().health_cli_report_failure_write_conflict).toBe(1)
expect(totals().health_cli_report_failure_rate_limited).toBeUndefined()
diff --git a/cli/src/gateway/productUsage.ts b/cli/src/gateway/productUsage.ts
index 85151ff12..119b55701 100644
--- a/cli/src/gateway/productUsage.ts
+++ b/cli/src/gateway/productUsage.ts
@@ -25,6 +25,13 @@ const listed = (code: unknown): LaunchErrorCode => typeof code === 'string' && l
// fleet spreads out again; the mean interval stays a minute.
const FIRST_REPORT_MS: readonly [number, number] = [10_000, 60_000]
const TICK_MS: readonly [number, number] = [45_000, 75_000]
+// Spec 2026-11-02-poll-cost Part 4.1: every tick read the choice and reported (prod 2026-11-02: 330 settings GETs and 284
+// report POSTs a minute). The ticks stay, for the counts kept on this computer (the resource samples need them 45 s apart),
+// but the choice is read at start, when it is made on this computer (`choiceChanged`), after a failed read or request, and then hourly: a report
+// carries its revision, so one sent after an opt-out elsewhere is refused (CHOICE_CHANGED) and the choice read at the next
+// tick. Reports go at most every 5 minutes, from the queue kept on disk.
+const SETTINGS_EVERY_MS = 3_600_000
+const REPORT_EVERY_MS = 300_000
// A refusal that says the backend is busy or down (429, 5xx, a timeout) waits longer each time it repeats: full
// jitter under a doubling ceiling, at most half an hour, and never sooner than its Retry-After.
const BACKOFF_BASE_MS = 60_000
@@ -111,6 +118,8 @@ export function createProductUsage(deps: ProductUsageDeps) {
writers.set(deps.file, writer)
// A report waits until `postAt` after a busy or failing backend; `backoffs` counts those refusals in a row.
let postAt = 0, backoffs = 0
+ // When the ticks next read the choice and next report (SETTINGS_EVERY_MS, REPORT_EVERY_MS).
+ let settingsAt = 0, reportAt = 0
// hn's counters: those it observed before the first choice read, held in RAM until that is known
// (hn is often opened at the daemon's start), and the UTC day a backend from before `tui` refused
// them. Neither is persisted; a restart tries again.
@@ -291,23 +300,27 @@ export function createProductUsage(deps: ProductUsageDeps) {
function unit(): number { const r = random(); return Number.isFinite(r) && r >= 0 && r < 1 ? r : 0.5 }
/** A delay in [low, high) milliseconds, at random: the fleet's reports spread out across it. */
const between = ([low, high]: readonly [number, number]): number => low + Math.floor(unit() * (high - low))
- /** [post]: send a report now. The gateway's first read of the choice does not, so collection starts at once
- * and the report waits for the first tick; every tick reads the choice and posts unless backing off. */
- async function syncOnce(post: boolean): Promise<void> {
+ /** [read]: read the choice first; [post]: send a report now. The gateway's first read of the choice does not
+ * report, so collection starts at once and the report waits for the first tick; a tick reads the choice when it is
+ * due (SETTINGS_EVERY_MS) and reports when one is due (REPORT_EVERY_MS) unless backing off. */
+ async function syncOnce(read: boolean, post: boolean): Promise<void> {
let posting = false
try {
- const response = await deps.request('GET', '/api/product-usage/settings')
- if (stopped) return
- const body = response.body.data as ProductUsageChoice | undefined
- if (response.status !== 200 || typeof body?.enabled !== 'boolean'
- || !Number.isSafeInteger(body.revision) || body.revision < 0) { enabled = false; forget(); health.clearObservations(); return }
- await choice(body)
- if (!choiceKnown) {
- // Counted only now that sharing is known to be on; discarded when it is off.
- choiceKnown = true
- const held = tuiHeld
- tuiHeld = []
- if (enabled && !tuiRefused()) for (const metric of held) add(metric)
+ if (read) {
+ const response = await deps.request('GET', '/api/product-usage/settings')
+ if (stopped) return
+ const body = response.body.data as ProductUsageChoice | undefined
+ if (response.status !== 200 || typeof body?.enabled !== 'boolean'
+ || !Number.isSafeInteger(body.revision) || body.revision < 0) { enabled = false; forget(); health.clearObservations(); return }
+ await choice(body)
+ settingsAt = now() + SETTINGS_EVERY_MS
+ if (!choiceKnown) {
+ // Counted only now that sharing is known to be on; discarded when it is off.
+ choiceKnown = true
+ const held = tuiHeld
+ tuiHeld = []
+ if (enabled && !tuiRefused()) for (const metric of held) add(metric)
+ }
}
if (!enabled) return
if (context) {
@@ -347,6 +360,7 @@ export function createProductUsage(deps: ProductUsageDeps) {
const report = state.pending
if (!report) return
posting = true
+ reportAt = now() + REPORT_EVERY_MS
const answer = await deps.request('POST', '/api/product-usage/report', report)
if (stopped) return
// Busy, failing or out of time (429, 5xx; a timeout is a 504): the next report waits. Anything else is an
@@ -355,7 +369,7 @@ export function createProductUsage(deps: ProductUsageDeps) {
else { backoffs = 0; postAt = 0 }
const result = answer.body.data as { accepted?: boolean; reason?: string } | undefined
if (answer.status === 200 && result?.accepted === true) { state.pending = null; await persist() }
- else if (result?.reason === 'CHOICE_CHANGED') { enabled = false; state = fresh(-1); forget(); health.reset(); await persist() }
+ else if (result?.reason === 'CHOICE_CHANGED') { enabled = false; settingsAt = 0; state = fresh(-1); forget(); health.reset(); await persist() }
else if (result?.reason === 'EXPIRED') { state.pending = null; add('health_cli_report_expired'); await persist() }
else if (answer.status === 400 && Object.keys(report.counters).length && Object.keys(report.counters).every(isTuiMetric)) {
// A backend from before `tui` knows none of hn's names. That is not a failed delivery, so it
@@ -371,15 +385,23 @@ export function createProductUsage(deps: ProductUsageDeps) {
} catch {
if (posting) backOff()
if (enabled) add('health_cli_report_failed')
- enabled = false; forget(); health.clearObservations() /* No error text or request body in logs. */
+ // Off until the choice is read again, at the next tick.
+ enabled = false; settingsAt = 0; forget(); health.clearObservations() /* No error text or request body in logs. */
}
}
/** Read the choice and, with [post] (the default), send a report now. */
- const sync = (post = true): Promise<void> => syncing ??= syncOnce(post).finally(() => { syncing = null })
+ const sync = (post = true): Promise<void> => syncing ??= syncOnce(true, post).finally(() => { syncing = null })
+ const tick = (): Promise<void> => syncing ??= syncOnce(now() >= settingsAt, now() >= postAt && now() >= reportAt).finally(() => { syncing = null })
+ /** The choice was just made on this computer: read it now, without a report. After whatever is already on its way,
+ * since a read in that run may have come back before the choice was made. */
+ const choiceChanged = async (): Promise<void> => {
+ while (syncing) await syncing
+ if (!stopped) await sync(false)
+ }
let timer: ReturnType<typeof setTimeout> | undefined
const schedule = (ms: number): void => {
if (stopped) return
- timer = setTimeout(() => { void sync(now() >= postAt).finally(() => schedule(between(TICK_MS))) }, ms)
+ timer = setTimeout(() => { void tick().finally(() => schedule(between(TICK_MS))) }, ms)
timer.unref?.()
}
schedule(between(FIRST_REPORT_MS))
@@ -406,6 +428,7 @@ export function createProductUsage(deps: ProductUsageDeps) {
return {
sync,
+ choiceChanged,
counter(metric: ProductUsageMetric): void {
if (stopped || !metricSet.has(metric)) return
if (isTuiMetric(metric)) {
diff --git a/cli/src/gateway/start.ts b/cli/src/gateway/start.ts
index 8f28af5cc..6767868c7 100644
--- a/cli/src/gateway/start.ts
+++ b/cli/src/gateway/start.ts
@@ -444,7 +444,12 @@ export function startGateway(host: GatewayHost): StartedGateway {
.map((m) => m.pub)
const ops: GatewayOps = {
- backend: accountHttp.backend,
+ backend: (async (method: string, path: string, body?: unknown) => {
+ const answer = await accountHttp.backend(method, path, body)
+ // Whatever the answer: a request that timed out may still have changed the choice.
+ if (method === 'POST' && path === '/api/product-usage/settings') void usage?.choiceChanged()
+ return answer
+ }) as GatewayOps['backend'],
machines: accountHttp.machines,
mintGridName: accountHttp.mintGridName,
status: async () => ({ fingerprint: gateway.fingerprint(), pairs: gateway.listPairs(), pending: gateway.pendingPair() as Record<string, unknown> | null }),
diff --git a/cli/src/lib/connectors/agents.ts b/cli/src/lib/connectors/agents.ts
index 62a01350d..5bfe1cd2f 100644
--- a/cli/src/lib/connectors/agents.ts
+++ b/cli/src/lib/connectors/agents.ts
@@ -1,6 +1,6 @@
/**
* Connected services, given to each agent as an MCP server on the local bridge. Agent configs hold only the command of a stdio
- * shim to the bridge's 0600 socket (mcpShimSource.ts), or where no socket can be (Windows, a folder too long for one) a 127.0.0.1
+ * shim to the bridge's 0600 socket or, on Windows, its proven pipe (mcpShimSource.ts), or where neither can be (a folder too long for a socket) a 127.0.0.1
* address with this user's capability in it; the bridge adds the credential to each request (Grid's design). A renewed token
* needs no config change, and an agent already running keeps working.
*
@@ -18,6 +18,9 @@ import { MCP_SHIM_SOURCE } from './mcpShimSource.js'
import { CODE, locked, writePrivate, type Store } from './store.js'
import { transport } from './rest.js'
import { socketPathIn } from '../localSocket.js'
+import { isPipePath } from '../windows/pipeAuth.js'
+import type { PipeTarget } from '../windows/pipeClient.js'
+import { BRIDGE_PIPE_FILE } from './bridge.js'
const validPort = (port: unknown): port is number => typeof port === 'number' && Number.isInteger(port) && port >= 0 && port < 65536
@@ -110,6 +113,34 @@ export function bridgeSocketPath(vault: Store, platform: NodeJS.Platform = proce
return platform === 'win32' ? null : socketPathIn(vault.root, 'bridge.sock')
}
+/** Where the bridge records its pipe on Windows (bridge.ts `serveBridgePipe`): the shim and Harness's own route read it. */
+export function bridgePipeRecord(vault: Store): string {
+ return join(vault.root, BRIDGE_PIPE_FILE)
+}
+
+/**
+ * Whether this account's process [pid] runs. The bridge is this account's, so a pid that answers EPERM is another account's
+ * process, one that took the pid since the bridge exited and could have made a pipe of its name: no bridge.
+ */
+function ownProcessRuns(pid: number): boolean {
+ try { process.kill(pid, 0); return true } catch { return false }
+}
+
+/**
+ * The bridge's pipe and token on Windows, or null when there is nothing to dial: no record, a name that is not a local Harness
+ * pipe (`isPipePath`: never another computer's), a token that is not 32 bytes, or a recorded process that no longer runs as
+ * this account. Read for each request, so a bridge that restarted under a new name is followed.
+ */
+export function readBridgePipe(vault: Store, runs: (pid: number) => boolean = ownProcessRuns, platform: NodeJS.Platform = process.platform): PipeTarget | null {
+ let record: Record<string, unknown>
+ try { record = vault.file(BRIDGE_PIPE_FILE) } catch { return null }
+ const { pipe, pid, token } = record
+ if (typeof pipe !== 'string' || !isPipePath(pipe, platform)) return null
+ if (typeof token !== 'string' || !/^[0-9a-f]{64}$/.test(token)) return null
+ if (typeof pid !== 'number' || !Number.isSafeInteger(pid) || pid <= 0 || !runs(pid)) return null
+ return { pipe, token: Buffer.from(token, 'hex') }
+}
+
/** How an MCP client reaches one connection. */
export type McpEntry = { url: string } | { command: string; args: string[] }
@@ -311,13 +342,16 @@ function recordedProfiles(record: Record<string, unknown>, env: NodeJS.ProcessEn
type Targets = { agents: Agent[]; gone?: string[]; release?: Agent[]; remember?: string[] }
/** Give the agents in [list] exactly the connections that have MCP tools (their own, or REST served as MCP). */
-function project(vault: Store, env: NodeJS.ProcessEnv, list: (record: Record<string, unknown>) => Targets, waitMs?: number): Record<string, string[]> {
+function project(vault: Store, env: NodeJS.ProcessEnv, list: (record: Record<string, unknown>) => Targets, waitMs?: number,
+ platform: NodeJS.Platform = process.platform): Record<string, string[]> {
const codes = Object.entries(vault.tokens()).filter(([code, token]) => transport(token) !== 'none' && CODE.test(code)).map(([code]) => code)
- const socket = bridgeSocketPath(vault)
- const shim = codes.length && socket ? writeShim(vault) : ''
- const key = codes.length && !socket ? bridgeKey(vault) : ''
- const wanted = Object.fromEntries(codes.map((code): [string, McpEntry] => [code, socket
- ? { command: managedNodePath(), args: [shim, '--socket', socket, code] }
+ // On Windows the bridge's pipe, named in its record (task #2162); elsewhere its socket; the port only where neither can be.
+ const socket = bridgeSocketPath(vault, platform)
+ const local: string[] | null = socket ? ['--socket', socket] : platform === 'win32' ? ['--pipe', bridgePipeRecord(vault)] : null
+ const shim = codes.length && local ? writeShim(vault) : ''
+ const key = codes.length && !local ? bridgeKey(vault) : ''
+ const wanted = Object.fromEntries(codes.map((code): [string, McpEntry] => [code, local
+ ? { command: managedNodePath(), args: [shim, ...local, code] }
: { url: bridgeUrl(key, code, bridgePort(env, vault)) }]))
return locked(vault.root, () => {
const record = vault.file('projections.json') as Record<string, unknown>
@@ -349,12 +383,12 @@ function project(vault: Store, env: NodeJS.ProcessEnv, list: (record: Record<str
* Give every installed agent exactly the connections that have MCP tools, in its default home and in each profile home an agent
* was launched under (syncProfileHome), so a connection made or removed later reaches a running profile's config too.
*/
-export function sync(vault: Store, env: NodeJS.ProcessEnv = process.env, list?: Agent[]): Record<string, string[]> {
+export function sync(vault: Store, env: NodeJS.ProcessEnv = process.env, list?: Agent[], platform: NodeJS.Platform = process.platform): Record<string, string[]> {
return project(vault, env, record => {
if (list) return { agents: list }
const profiles = recordedProfiles(record, env)
return { agents: [...agents(env), ...profiles.agents], gone: profiles.gone, release: profiles.release }
- })
+ }, undefined, platform)
}
/**
diff --git a/cli/src/lib/connectors/bridge.ts b/cli/src/lib/connectors/bridge.ts
index a38c4eda4..a4c42fdd7 100644
--- a/cli/src/lib/connectors/bridge.ts
+++ b/cli/src/lib/connectors/bridge.ts
@@ -4,26 +4,27 @@
* the answer back (event streams included). A service reached by REST (no MCP server the grant can use) is
* answered here instead, its REST tools served as MCP (rest.ts). Runs in the daemon (services/connectors.ts).
*
- * MCP clients come through a stdio shim (mcpShimSource.ts) to a second listener on a 0600 socket (serveBridgeSocket), so no tool call
- * goes to a port another account can hold. The port stays for clients still running on it, Windows, and a folder too long for
- * a socket.
+ * MCP clients come through a stdio shim (mcpShimSource.ts) to a second listener on a 0600 socket (serveBridgeSocket), or on Windows
+ * a pipe that proves a token both ways (serveBridgePipe), so no tool call goes to a port another account can hold. The port stays
+ * for clients still running on it and a folder too long for a socket.
*
* Two more addresses serve Harness's own cloud agents (services/cloud.ts), over the socket where one can be, which hold no credential either:
* - `/<key>/connections`: what is connected, by address and with no secret, so the service finds the
* connection that signs in Fo or Devin by where it points rather than by what the person named it;
* - `/<key>/<code>/api/<path>`: one request to a key-only connection's own API (`api_entry`), with its key.
*/
-import { timingSafeEqual } from 'node:crypto'
+import { randomBytes, timingSafeEqual } from 'node:crypto'
import { chmodSync, mkdirSync } from 'node:fs'
import { createServer, type IncomingMessage, type RequestListener, type Server, type ServerResponse } from 'node:http'
-import { dirname } from 'node:path'
+import { dirname, join } from 'node:path'
import { Readable } from 'node:stream'
import { listenLocalSocket, type LocalSocketServer } from '../localSocket.js'
import { label } from './catalog.js'
-import { bearer, needsRefresh, refreshable, type Store, type Token } from './store.js'
+import { bearer, locked, needsRefresh, refreshable, writePrivate, type Store, type Token } from './store.js'
import { refresh } from './renew.js'
import { answer as answerRest, transport } from './rest.js'
import { peerIsThisAccount, type PeerAccount } from '../peerAccount.js'
+import { newPipePath } from '../windows/pipeAuth.js'
/** Headers an MCP client sends that the service must see. Authorization never comes from the agent. */
const FORWARD = ['accept', 'content-type', 'mcp-session-id', 'mcp-protocol-version', 'last-event-id']
@@ -73,16 +74,44 @@ export function createBridge(vault: Store, options: BridgeOptions): Server {
return createServer(bridgeHandler(vault, options))
}
-/** The bridge on its 0600 socket: for MCP clients, their MCP servers only, as an agent's key reaches; for Harness's own key, what it reaches. */
+/** On the socket or the pipe: for MCP clients, their MCP servers only, as an agent's key reaches; for Harness's own key, what it reaches. */
+function localOptions(vault: Store): BridgeOptions {
+ return { key: () => SOCKET_KEY,
+ // Harness's own calls (cloud/bridge.ts) come here too: its key never crosses the port where this listener can be.
+ // An unreadable key refuses Harness's calls only: agents' MCP calls never needed this file.
+ harnessKey: () => { try { return String(vault.file('harness-key.json').key ?? '') } catch { return '' } }, socket: true }
+}
+
+/** The bridge on its 0600 socket. */
export async function serveBridgeSocket(vault: Store, path: string): Promise<LocalSocketServer> {
// The socket's privacy rests on this folder too, which may be older than this code.
mkdirSync(dirname(path), { recursive: true, mode: 0o700 })
chmodSync(dirname(path), 0o700)
- const listening = await listenLocalSocket(bridgeHandler(vault, { key: () => SOCKET_KEY,
- // Harness's own calls (cloud/bridge.ts) come here too: its key never crosses the port where this socket can be.
- // An unreadable key refuses Harness's calls only: agents' MCP calls never needed this file.
- harnessKey: () => { try { return String(vault.file('harness-key.json').key ?? '') } catch { return '' } }, socket: true }), path)
+ const listening = await listenLocalSocket(bridgeHandler(vault, localOptions(vault)), path)
+ listening.server.unref()
+ return listening
+}
+
+/** The record of the bridge's pipe in the vault's private folder (agents.ts `readBridgePipe`, the shim). */
+export const BRIDGE_PIPE_FILE = 'bridge-pipe.json'
+
+/**
+ * The bridge on Windows (task #2162): a pipe of a new name, `\\.\pipe\harness-<id>`, whose every request must prove a token new
+ * at each start, and whose every answer proves it back (lib/windows/pipeAuth.ts, as the daemon's own pipe does). Node cannot set a
+ * pipe's DACL, so reaching it is no credential, and once this process is gone any account can make a pipe of the name. The pipe,
+ * this process and the token are recorded in [BRIDGE_PIPE_FILE], private to this account in its profile, once it listens.
+ */
+export async function serveBridgePipe(vault: Store, path: string = newPipePath()): Promise<LocalSocketServer> {
+ const token = randomBytes(32)
+ const listening = await listenLocalSocket(bridgeHandler(vault, localOptions(vault)), path, { token })
listening.server.unref()
+ try {
+ locked(vault.root, () => { writePrivate(join(vault.root, BRIDGE_PIPE_FILE), { pipe: path, pid: process.pid, token: token.toString('hex') }) })
+ } catch (error) {
+ // Unrecorded, nothing can reach it: listening on would only hold the name.
+ listening.closeSync()
+ throw error
+ }
return listening
}
diff --git a/cli/src/lib/connectors/bridgePipe.spec.ts b/cli/src/lib/connectors/bridgePipe.spec.ts
new file mode 100644
index 000000000..c42a92b4e
--- /dev/null
+++ b/cli/src/lib/connectors/bridgePipe.spec.ts
@@ -0,0 +1,135 @@
+/**
+ * The bridge's pipe on Windows (task #2162, from Reed's review of #2605): MCP clients and Harness's own calls reach the bridge
+ * over a pipe whose every request proves a token and whose every answer proves it back, never over the port another account
+ * can hold from boot. A Unix socket named `harness-<id>` stands for the pipe here, as in the daemon pipe's specs.
+ */
+import { spawnSync } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs'
+import { createServer, request as httpRequest, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { join } from 'node:path'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+import { pipeRequest } from '../windows/pipeClient.js'
+import { bridgePipeRecord, readBridgePipe } from './agents.js'
+import { serveBridgePipe } from './bridge.js'
+import { Store, writePrivate } from './store.js'
+
+let home: string, vault: Store
+const closers: Array<() => unknown> = []
+beforeEach(() => {
+ // Short: a socket has to fit.
+ home = mkdtempSync(join('/tmp', 'bp-'))
+ vault = new Store(join(home, 'c'), { HOME: home })
+})
+afterEach(async () => { for (const close of closers.splice(0)) await close(); rmSync(home, { recursive: true, force: true }) })
+
+const pipePath = (): string => {
+ mkdirSync(join(home, 'p'), { recursive: true })
+ return join(home, 'p', `harness-${randomBytes(16).toString('hex')}`)
+}
+
+async function upstream(): Promise<{ url: string; heard: string[] }> {
+ const heard: string[] = []
+ const server: Server = createServer((request, response) => {
+ let raw = ''
+ request.on('data', part => { raw += part })
+ request.on('end', () => {
+ heard.push(raw)
+ response.writeHead(200, { 'content-type': 'application/json' }).end(JSON.stringify({ jsonrpc: '2.0', id: 1, result: { ok: true } }))
+ })
+ })
+ await new Promise<void>(ready => server.listen(0, '127.0.0.1', ready))
+ closers.push(() => new Promise(done => { server.closeAllConnections(); server.close(done) }))
+ return { url: `http://127.0.0.1:${(server.address() as AddressInfo).port}/mcp`, heard }
+}
+
+const served = async (): Promise<string> => {
+ const path = pipePath()
+ const listening = await serveBridgePipe(vault, path)
+ closers.push(() => listening.close())
+ return path
+}
+
+describe('the bridge\'s pipe', () => {
+ it('refuses a request that does not prove the token: it reaches no connection', async () => {
+ const fake = await upstream()
+ vault.save('linear', { access_token: 't', source: 'dcr', mcp_entry: { url: fake.url, headers: {} } })
+ const path = await served()
+ const status = await new Promise<number>((resolve, reject) => {
+ const request = httpRequest({ socketPath: path, method: 'POST', path: '/local/linear/mcp', headers: { 'content-type': 'application/json' } },
+ (answer) => { answer.resume(); resolve(answer.statusCode ?? 0) })
+ request.on('error', reject)
+ request.end('{"jsonrpc":"2.0","id":1,"method":"tools/call"}')
+ })
+ expect(status).toBe(401)
+ expect(fake.heard).toEqual([])
+ })
+
+ it('takes a request that proves the token to the connection, and its answer proves the token back', async () => {
+ const fake = await upstream()
+ vault.save('linear', { access_token: 't', source: 'dcr', mcp_entry: { url: fake.url, headers: {} } })
+ await served()
+ const target = readBridgePipe(vault)!
+ // pipeRequest refuses an answer without the proof: this one is the bridge's.
+ const answer = await pipeRequest(target, { method: 'POST', path: '/local/linear/mcp',
+ headers: { 'content-type': 'application/json', accept: 'application/json' }, body: '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' })
+ expect(answer.status).toBe(200)
+ expect(fake.heard).toEqual(['{"jsonrpc":"2.0","id":1,"method":"tools/list"}'])
+ })
+
+ it('records the pipe, the process serving it and the token, in the vault\'s private folder', async () => {
+ const path = await served()
+ const record = vault.file('bridge-pipe.json')
+ expect(bridgePipeRecord(vault)).toBe(join(vault.root, 'bridge-pipe.json'))
+ expect(record).toEqual({ pipe: path, pid: process.pid, token: expect.stringMatching(/^[0-9a-f]{64}$/) })
+ expect(readBridgePipe(vault)).toEqual({ pipe: path, token: Buffer.from(String(record.token), 'hex') })
+ })
+
+ it('a new token each start: what was heard of one opens nothing at the next', async () => {
+ await served()
+ const first = vault.file('bridge-pipe.json').token
+ await served()
+ expect(vault.file('bridge-pipe.json').token).not.toBe(first)
+ })
+})
+
+describe('reading the bridge\'s pipe', () => {
+ const write = (record: Record<string, unknown>): void => {
+ writePrivate(bridgePipeRecord(vault), { pipe: pipePath(), pid: process.pid, token: 'ab'.repeat(32), ...record })
+ }
+
+ it('is nothing with no record', () => {
+ expect(readBridgePipe(vault)).toBeNull()
+ })
+
+ it('is nothing once the process that served it is gone: any account can make a pipe of its name then', () => {
+ const exited = spawnSync(process.execPath, ['-e', '']).pid!
+ write({ pid: exited })
+ expect(readBridgePipe(vault)).toBeNull()
+ })
+
+ it('is nothing when that process id is another account\'s now: one that took it since', () => {
+ write({})
+ // What process.kill(pid, 0) throws for another account's process.
+ expect(readBridgePipe(vault, () => false)).toBeNull()
+ expect(readBridgePipe(vault, () => true)).not.toBeNull()
+ })
+
+ it('is nothing for a name that is not a Harness pipe, a short token or no pid', () => {
+ for (const record of [{ pipe: join(home, 'elsewhere') }, { token: 'ab' }, { token: 'zz'.repeat(32) }, { pid: 0 }, { pid: '1' }]) {
+ write(record)
+ expect(readBridgePipe(vault), JSON.stringify(record)).toBeNull()
+ }
+ })
+
+ it('on Windows is only a local pipe: never a file, nor another computer\'s pipe, which would carry this user\'s NTLM sign-in', () => {
+ const id = 'a'.repeat(32), runs = () => true
+ write({ pipe: `\\\\.\\pipe\\harness-${id}` })
+ expect(readBridgePipe(vault, runs, 'win32')).not.toBeNull()
+ for (const pipe of [`\\\\host\\pipe\\harness-${id}`, pipePath(), `\\\\.\\pipe\\harness-${id}x`]) {
+ write({ pipe })
+ expect(readBridgePipe(vault, runs, 'win32'), pipe).toBeNull()
+ }
+ })
+})
diff --git a/cli/src/lib/connectors/mcpShim.spec.ts b/cli/src/lib/connectors/mcpShim.spec.ts
index 89d4ef195..efb047452 100644
--- a/cli/src/lib/connectors/mcpShim.spec.ts
+++ b/cli/src/lib/connectors/mcpShim.spec.ts
@@ -2,14 +2,15 @@
* MCP clients reach the bridge through a stdio shim, over a 0600 socket (follow-up of audit H1): whoever holds the bridge's old
* port hears no tool call, however the daemon is doing.
*/
-import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { spawn, spawnSync, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { randomBytes } from 'node:crypto'
import { createServer, request as httpRequest, type Server } from 'node:http'
-import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { chmodSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
import { join } from 'node:path'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { managedNodePath } from '../nodeRuntime.js'
-import { bridgeSocketPath, sync } from './agents.js'
-import { serveBridgeSocket } from './bridge.js'
+import { bridgePipeRecord, bridgeSocketPath, sync } from './agents.js'
+import { serveBridgePipe, serveBridgeSocket } from './bridge.js'
import { MCP_SHIM_SOURCE } from './mcpShimSource.js'
import { Store, writePrivate } from './store.js'
@@ -57,17 +58,17 @@ async function holder(): Promise<{ port: number; heard: string[] }> {
return { port: await listen(server), heard }
}
-/** The shim as a real process, as a client runs it from its entry. */
-function shimProcess(code: string, socket: string, grace = 5000): ChildProcessWithoutNullStreams {
+/** The shim as a real process, as a client runs it from its entry: to the socket, or with `--pipe` to the pipe its record names. */
+function shimProcess(code: string, socket: string, grace = 5000, flag = '--socket'): ChildProcessWithoutNullStreams {
const shim = join(vault.root, 'mcp-shim.mjs')
mkdirSync(vault.root, { recursive: true })
writeFileSync(shim, MCP_SHIM_SOURCE)
- return spawn(process.execPath, [shim, '--socket', socket, code, '--grace-ms', String(grace)])
+ return spawn(process.execPath, [shim, flag, socket, code, '--grace-ms', String(grace)])
}
/** Speak to the shim as an MCP client: newline-delimited JSON-RPC over its stdin and stdout. */
-function client(code: string, socket: string): { send(message: unknown): void; end(): void; lines: unknown[]; done: Promise<number | null> } {
- const child = shimProcess(code, socket), lines: unknown[] = []
+function client(code: string, socket: string, flag = '--socket'): { send(message: unknown): void; end(): void; lines: unknown[]; done: Promise<number | null> } {
+ const child = shimProcess(code, socket, 5000, flag), lines: unknown[] = []
let held = ''
child.stdout.on('data', chunk => {
held += String(chunk)
@@ -418,6 +419,111 @@ describe.skipIf(process.platform === 'win32')('the MCP clients\' way to the brid
})
})
+// Task #2162 (Reed's review of #2605): on Windows the shim had no socket to reach, so agents' entries named the port, which the
+// Team account can hold from boot to read every tool call and answer it falsely. There the shim reaches the bridge's pipe, which
+// proves itself (bridge.ts serveBridgePipe). A Unix socket named `harness-<id>` stands for the pipe here.
+describe.skipIf(process.platform === 'win32')('the MCP clients\' way to the bridge on Windows: its pipe', () => {
+ const pipePath = (): string => {
+ mkdirSync(join(home, 'p'), { recursive: true })
+ return join(home, 'p', `harness-${randomBytes(16).toString('hex')}`)
+ }
+ const onPipe = async (): Promise<string> => {
+ const listening = await serveBridgePipe(vault, pipePath())
+ closers.push(() => listening.closeSync())
+ return listening.path
+ }
+
+ it('a holder of the old port receives no tool call, and tools still work through the pipe', async () => {
+ const fake = await upstream(), port = await holder()
+ env.HARNESS_CONNECTIONS_PORT = String(port.port)
+ vault.save('linear', { access_token: 'secret-linear', source: 'dcr', mcp_entry: { url: fake.url, headers: { authorization: 'Bearer secret-linear' } } })
+ await onPipe()
+ const shim = client('linear', bridgePipeRecord(vault), '--pipe')
+ shim.send({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} })
+ shim.send({ jsonrpc: '2.0', method: 'notifications/initialized' })
+ shim.send({ jsonrpc: '2.0', id: 2, method: 'tools/call', params: { name: 'x' } })
+ shim.end()
+ await shim.done
+ expect(port.heard).toEqual([])
+ expect(fake.heard.map(h => h.method)).toEqual(['initialize', 'notifications/initialized', 'tools/call'])
+ expect(fake.heard[2]).toMatchObject({ session: 'session-1', auth: 'Bearer secret-linear' })
+ expect(shim.lines).toEqual([
+ { jsonrpc: '2.0', id: 1, result: { protocolVersion: '2025-06-18' } },
+ { jsonrpc: '2.0', method: 'notifications/progress', params: { progress: 1 } },
+ { jsonrpc: '2.0', id: 2, result: { content: 'done' } },
+ ])
+ })
+
+ it('the entries on Windows name the shim and the pipe\'s record, with no port and no key', () => {
+ env.HARNESS_CONNECTIONS_PORT = '51793'
+ vault.save('linear', { access_token: 'secret-linear', source: 'dcr', mcp_entry: { url: 'https://mcp.linear.app/mcp', headers: {} } })
+ writeJson(join(home, '.claude.json'))
+ sync(vault, { ...env, CLAUDE_CONFIG_DIR: home }, undefined, 'win32')
+ const entry = claudeEntry('linear')
+ expect(entry).toMatchObject({ type: 'stdio', command: managedNodePath() })
+ expect(entry.args).toEqual([join(vault.root, 'mcp-shim.mjs'), '--pipe', bridgePipeRecord(vault), 'linear'])
+ const text = readFileSync(join(home, '.claude.json'), 'utf8')
+ expect(text).not.toContain('51793')
+ expect(text).not.toContain('127.0.0.1')
+ expect(vault.file('bridge.json').key).toBeUndefined()
+ })
+
+ it('with the bridge\'s process gone, says Harness is not running and sends nothing: any account can make a pipe of its name then', async () => {
+ const fake = await upstream()
+ vault.save('linear', { access_token: 't', source: 'dcr', mcp_entry: { url: fake.url, headers: {} } })
+ await onPipe()
+ writePrivate(bridgePipeRecord(vault), { ...vault.file('bridge-pipe.json'), pid: spawnSync(process.execPath, ['-e', '']).pid })
+ const shim = client('linear', bridgePipeRecord(vault), '--pipe')
+ shim.send({ jsonrpc: '2.0', id: 3, method: 'tools/call', params: {} })
+ shim.end()
+ await shim.done
+ expect(fake.heard).toEqual([])
+ expect(shim.lines).toEqual([{ jsonrpc: '2.0', id: 3, error: { code: -32001, message: expect.stringContaining('Harness is not running') } }])
+ })
+
+ it('with no record, says Harness is not running', async () => {
+ const shim = client('linear', bridgePipeRecord(vault), '--pipe')
+ shim.send({ jsonrpc: '2.0', id: 4, method: 'tools/list' })
+ shim.end()
+ await shim.done
+ expect(shim.lines).toEqual([{ jsonrpc: '2.0', id: 4, error: { code: -32001, message: expect.stringContaining('Harness is not running') } }])
+ })
+
+ it('does not follow a record that is a link: it could name a pipe this account never made', async () => {
+ const fake = await upstream()
+ vault.save('linear', { access_token: 't', source: 'dcr', mcp_entry: { url: fake.url, headers: {} } })
+ await onPipe()
+ const real = join(home, 'elsewhere.json')
+ writeFileSync(real, readFileSync(bridgePipeRecord(vault)), { mode: 0o600 })
+ rmSync(bridgePipeRecord(vault))
+ symlinkSync(real, bridgePipeRecord(vault))
+ const shim = client('linear', bridgePipeRecord(vault), '--pipe')
+ shim.send({ jsonrpc: '2.0', id: 5, method: 'tools/list' })
+ shim.end()
+ await shim.done
+ expect(fake.heard).toEqual([])
+ expect(shim.lines).toEqual([{ jsonrpc: '2.0', id: 5, error: { code: -32001, message: expect.any(String) } }])
+ })
+
+ it('takes no answer that does not prove the token: a pipe made under the bridge\'s name answers nothing to the client', async () => {
+ const path = pipePath(), heard: string[] = []
+ const squatter = createServer((request, response) => {
+ heard.push(request.url ?? '')
+ response.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify({ jsonrpc: '2.0', id: 6, result: { content: 'false answer' } }))
+ })
+ await new Promise<void>(ready => squatter.listen(path, ready))
+ closers.push(() => { squatter.closeAllConnections(); squatter.close() })
+ writePrivate(bridgePipeRecord(vault), { pipe: path, pid: process.pid, token: randomBytes(32).toString('hex') })
+ const shim = client('linear', bridgePipeRecord(vault), '--pipe')
+ shim.send({ jsonrpc: '2.0', id: 6, method: 'tools/call', params: {} })
+ shim.end()
+ await shim.done
+ expect(heard).toHaveLength(1)
+ expect(JSON.stringify(shim.lines)).not.toContain('false answer')
+ expect(shim.lines).toEqual([{ jsonrpc: '2.0', id: 6, error: { code: -32001, message: expect.stringContaining('Something other than Harness') } }])
+ })
+})
+
function writeJson(path: string, text = '{}'): void {
mkdirSync(join(path, '..'), { recursive: true })
writeFileSync(path, text)
diff --git a/cli/src/lib/connectors/mcpShimSource.ts b/cli/src/lib/connectors/mcpShimSource.ts
index 6a3b80053..2e5b100ef 100644
--- a/cli/src/lib/connectors/mcpShimSource.ts
+++ b/cli/src/lib/connectors/mcpShimSource.ts
@@ -11,15 +11,22 @@
* connection per agent. And the updater ships only cli.js and notify.mjs, so a third file there would need its manifest changed.
* Node's built-ins only: nothing else is beside it.
*
+ * On Windows there is no socket: the shim reaches the bridge's pipe (bridge.ts serveBridgePipe, task #2162), named in a record in
+ * the vault's private folder (`--pipe <record>`). Node cannot set a pipe's DACL, so reaching it proves nothing, and once the bridge
+ * is gone any account can make a pipe of its name: the shim dials it only while the recorded process runs as this account, proves
+ * the record's token without sending it, and relays no answer that does not prove the token back (lib/windows/pipeAuth.ts).
+ *
* The client's stream is newline-delimited JSON-RPC (MCP's stdio transport). Each message becomes one POST of MCP's HTTP transport,
* whose answer is JSON or an event stream. `initialize` goes first and alone: its answer names the session the rest carry. A
* service's own unprompted stream (GET) is not opened, so `notifications/*_changed` are not relayed.
*/
+import { PIPE_AUTH_HEADER, PIPE_PROOF_HEADER } from '../windows/pipeAuth.js'
import { SOCKET_KEY } from './bridge.js'
export const MCP_SHIM_SOURCE = String.raw`#!/usr/bin/env node
// Written by Harness (lib/connectors/mcpShimSource.ts); it is replaced at each daemon start.
-import { lstatSync } from 'node:fs'
+import { createHmac, randomBytes, timingSafeEqual } from 'node:crypto'
+import { closeSync, fstatSync, lstatSync, openSync, readFileSync } from 'node:fs'
import { request as httpRequest } from 'node:http'
import { dirname } from 'node:path'
import { createInterface } from 'node:readline'
@@ -27,9 +34,12 @@ import { createInterface } from 'node:readline'
const NOT_RUNNING = 'Harness is not running on this computer, so this connection cannot be reached. Start it and try again.'
const UNREADABLE = "The connection's answer could not be read. Try again."
const NOT_PRIVATE = "Harness's connection socket is not private to this account, so it was not used. Restart Harness."
+const UNPROVEN = "Something other than Harness answered on its connection pipe, so its answer was not used. Restart Harness."
const [flag, socket, code, graceFlag, grace] = process.argv.slice(2)
-if (flag !== '--socket' || !socket || !code) { console.error('usage: mcp-shim --socket PATH CODE'); process.exit(2) }
+// --pipe names the bridge's pipe record on Windows (lib/connectors/bridge.ts serveBridgePipe), --socket its 0600 socket elsewhere.
+const piped = flag === '--pipe'
+if ((flag !== '--socket' && !piped) || !socket || !code) { console.error('usage: mcp-shim --socket PATH CODE | --pipe RECORD CODE'); process.exit(2) }
// How long open requests get once the client has gone, so a hung stream does not leave a process behind.
const graceMs = graceFlag === '--grace-ms' ? Number(grace) : 5000
const path = '/${SOCKET_KEY}/' + encodeURIComponent(code) + '/mcp'
@@ -46,6 +56,42 @@ function socketState() {
}
}
+// Mirrors LOCAL_PIPE_RE and isPipePath in lib/windows/pipeAuth.ts: on Windows a pipe on this computer named harness-<id>, never
+// another computer's (an SMB connection that can carry this user's sign-in); elsewhere only the tests make one, a socket so named.
+const PIPE_RE = process.platform === 'win32' ? /^\\\\\.\\pipe\\harness-([0-9a-f]{32})$/ : /(?:^|\/)harness-([0-9a-f]{32})$/
+
+// The bridge's pipe, read from its record for each request so a bridge that restarted under a new name is followed; null when
+// there is nothing to dial. The record must be a plain file (not a link), the very one opened, and private to this account where
+// the system says so. The bridge is this account's, so a pid that is gone or answers EPERM (another account's process, one that
+// took the pid since) means no bridge: a pipe of its name may be anyone's.
+function pipeTarget() {
+ let fd = null
+ try {
+ const seen = lstatSync(socket, { bigint: true })
+ if (!seen.isFile() || seen.size > 4096n) return null
+ fd = openSync(socket, 'r')
+ const opened = fstatSync(fd, { bigint: true })
+ if (!opened.isFile() || opened.dev !== seen.dev || opened.ino !== seen.ino) return null
+ const uid = process.getuid?.()
+ if (process.platform !== 'win32' && ((opened.mode & 0o077n) !== 0n || (uid !== undefined && opened.uid !== BigInt(uid)))) return null
+ const record = JSON.parse(readFileSync(fd, 'utf8'))
+ const id = typeof record?.pipe === 'string' ? PIPE_RE.exec(record.pipe)?.[1] : null
+ if (!id || typeof record.token !== 'string' || !/^[0-9a-f]{64}$/.test(record.token)) return null
+ if (!Number.isSafeInteger(record.pid) || record.pid <= 0) return null
+ try { process.kill(record.pid, 0) } catch { return null }
+ return { pipe: record.pipe, id, token: Buffer.from(record.token, 'hex') }
+ } catch {
+ return null
+ } finally {
+ if (fd !== null) closeSync(fd)
+ }
+}
+const mac = (token, separator, nonce) => createHmac('sha256', token).update(Buffer.of(separator)).update(nonce, 'utf8').digest('hex')
+const proven = (proof, token, nonce) => {
+ if (typeof proof !== 'string' || !/^[0-9a-f]{64}$/.test(proof)) return false
+ return timingSafeEqual(Buffer.from(proof, 'hex'), Buffer.from(mac(token, 0x00, nonce), 'hex'))
+}
+
// A client that went away closes this stream: nothing more to say, and no reason to fall over saying it.
process.stdout.on('error', () => {})
let closing = false
@@ -104,13 +150,27 @@ const relay = (answer, sent, quiet) => new Promise((resolve, reject) => {
const post = (raw, sent, quiet = false, retried = false) => new Promise((resolve) => {
const asked = sent.method !== undefined && sent.id !== undefined
const failed = (reason) => { if (asked && !quiet) refuse(sent.id, -32001, reason); resolve(0) }
- const state = socketState()
- if (state !== 'private') { failed(state === 'absent' ? NOT_RUNNING : NOT_PRIVATE); return }
- const request = httpRequest({ socketPath: socket, method: 'POST', path,
+ let target = null, nonce = null
+ if (piped) {
+ target = pipeTarget()
+ if (!target) { failed(NOT_RUNNING); return }
+ nonce = target.id + randomBytes(16).toString('hex')
+ } else {
+ const state = socketState()
+ if (state !== 'private') { failed(state === 'absent' ? NOT_RUNNING : NOT_PRIVATE); return }
+ }
+ const request = httpRequest({ socketPath: target ? target.pipe : socket, method: 'POST', path,
headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream',
- ...(session ? { 'mcp-session-id': session } : {}), ...(version ? { 'mcp-protocol-version': version } : {}) } },
+ ...(session ? { 'mcp-session-id': session } : {}), ...(version ? { 'mcp-protocol-version': version } : {}),
+ ...(target ? { '${PIPE_AUTH_HEADER}': nonce + '.' + mac(target.token, 0x01, nonce) } : {}) } },
(answer) => {
open.delete(request)
+ // Before anything of it is read: an answer that is not the bridge's never reaches the client.
+ if (target && !proven(answer.headers['${PIPE_PROOF_HEADER}'], target.token, nonce)) {
+ request.destroy()
+ failed(UNPROVEN)
+ return
+ }
// The service forgot the session (it restarted, or it expired). An HTTP client opens another on a 404; a stdio client
// cannot know to, so an agent running for days would lose this connection until it restarts.
if (answer.statusCode === 404 && session && !retried && sent.method !== 'initialize' && opening) {
diff --git a/cli/src/lib/localTransport.ts b/cli/src/lib/localTransport.ts
index a1226af5b..627968500 100644
--- a/cli/src/lib/localTransport.ts
+++ b/cli/src/lib/localTransport.ts
@@ -118,6 +118,16 @@ export function fetchOverSocket(socketPath: string): typeof fetch {
}
}
+/** `fetch` that sends every request over the pipe [target] names at the time, whatever host its address names: it proves the pipe's
+ * token and takes only an answer that proves it back. With no pipe it fails as `fetch` does for a daemon that is not there. */
+export function fetchOverPipe(target: () => PipeTarget | null): typeof fetch {
+ return async (input, init) => {
+ const pipe = target()
+ if (!pipe) throw notThere()
+ return overSocket(pipe.pipe, new Request(input, init), pipe)
+ }
+}
+
/**
* `fetch` for the daemon on [port] of [dataDir]: a request to its loopback address goes over its socket where it can
* have one, and on Windows over its pipe ([pipe], `daemonPipe` by default) or nowhere. Any other address, such as a
diff --git a/cli/src/lib/peerAccount.spec.ts b/cli/src/lib/peerAccount.spec.ts
index 525f3abc0..3dd3b8939 100644
--- a/cli/src/lib/peerAccount.spec.ts
+++ b/cli/src/lib/peerAccount.spec.ts
@@ -1,6 +1,6 @@
import { createServer, connect, type AddressInfo, type Socket } from 'node:net'
import { afterEach, describe, expect, it } from 'vitest'
-import { lsofShowsPeer, peerIsThisAccount, portHolderIsThisAccount, procNetListener, procNetOwner, WINDOWS_PEER_LOOKUPS, WINDOWS_PEER_MS, WINDOWS_PEER_QUEUE, windowsPeerQuery, type WindowsPeerRun } from './peerAccount.js'
+import { lsofShowsPeer, peerIsThisAccount, portHolderIsThisAccount, procNetListener, procNetOwner, WINDOWS_PEER_LOOKUPS, WINDOWS_PEER_MS, WINDOWS_PEER_QUEUE, windowsListenerQuery, windowsPeerQuery, type WindowsPeerRun } from './peerAccount.js'
describe('who is at the other end of a loopback connection', () => {
const opened: Array<() => unknown> = []
@@ -203,6 +203,68 @@ describe('who is at the other end of a loopback connection', () => {
})
})
+ // Reed's review of #2605: Windows answered null here, so the connectors bridge never moved off a port the Team account held
+ // from boot, and the owner's agents kept sending their tool calls to that account (task #2162).
+ describe('on Windows, who holds a listening port, by asking Windows', () => {
+ const answering = (stdout: string, status: number | null = 0) => {
+ const asked: Array<{ script: string; inputs: Record<string, string> }> = []
+ const run: WindowsPeerRun = async (script, inputs) => { asked.push({ script, inputs }); return { status, stdout } }
+ return { run, asked }
+ }
+
+ it('says no for another account\'s listener, yes for this account\'s, and nothing for a free port', async () => {
+ expect(await portHolderIsThisAccount(51793, 'win32', answering('no\r\n').run)).toBe(false)
+ expect(await portHolderIsThisAccount(51793, 'win32', answering('yes\r\n').run)).toBe(true)
+ expect(await portHolderIsThisAccount(51793, 'win32', answering('none\r\n').run)).toBeNull()
+ })
+
+ it('says nothing when the lookup fails, times out, throws or answers anything else', async () => {
+ for (const [stdout, status] of [['no', 1], ['yes', null], ['', 0], ['maybe', 0], ['yes\nno', 0]] as const) {
+ expect(await portHolderIsThisAccount(51793, 'win32', answering(stdout, status).run), `${stdout}/${status}`).toBeNull()
+ }
+ expect(await portHolderIsThisAccount(51793, 'win32', () => Promise.reject(new Error('no PowerShell')))).toBeNull()
+ })
+
+ it('passes the port as an input, never in the script\'s text', async () => {
+ const { run, asked } = answering('no')
+ await portHolderIsThisAccount(51794, 'win32', run)
+ expect(asked[0]!.inputs).toEqual({ HARNESS_LISTEN_PORT: '51794' })
+ expect(asked[0]!.script).not.toContain('51794')
+ expect(asked[0]!.script).toBe(windowsListenerQuery(51794).script)
+ })
+
+ it('counts a listener as this account\'s only by its process\'s SID, and only a process that started before it', () => {
+ const { script } = windowsListenerQuery(51793)
+ expect(script).toMatch(/Get-NetTCPConnection -State Listen -LocalPort \(\[int\]\$env:HARNESS_LISTEN_PORT\)/)
+ expect(script).toMatch(/GetOwnerSid/)
+ expect(script).toMatch(/WindowsIdentity\]::GetCurrent\(\)\.User\.Value/)
+ expect(script).toMatch(/\$started -gt \$row\.CreationTime/)
+ })
+
+ // The Windows run on #2605: Windows gives a socket's time to the second and a process's finer, so a process that opened its
+ // listener within the second it started read as started after it. Here that would move the bridge off its own port.
+ it('compares the listener\'s whole-second time with the process\'s cut to the second, with no slack, as the peer check does', () => {
+ const { script } = windowsListenerQuery(51793)
+ expect(script).toMatch(/\$started = \$process\.CreationDate\.AddTicks\(-\(\$process\.CreationDate\.Ticks % \[TimeSpan\]::TicksPerSecond\)\)/)
+ expect(script).toMatch(/\$started -gt \$row\.CreationTime/)
+ expect(script).not.toMatch(/AddSeconds/)
+ })
+
+ // Remy's review of #2605: the lookup's own PowerShell can take a freed id, and is never the holder.
+ it('never counts the lookup\'s own process as the holder', () => {
+ expect(windowsListenerQuery(51793).script).toMatch(/\$row\.OwningProcess -eq \$PID\) \{ continue \}/)
+ })
+
+ // Quinn 2's review of #2608: a listener of this account's on another address (::1, 127.0.0.2) answered yes, so the bridge
+ // waited instead of moving off another account's 127.0.0.1. Only a listener that keeps 127.0.0.1's port from being bound counts.
+ it('counts only the listeners that hold 127.0.0.1\'s port: on it, on any IPv4 address, or on any address dual-stack', () => {
+ const { script } = windowsListenerQuery(51793)
+ expect(script).toMatch(/Where-Object \{ \$_\.LocalAddress -in @\('127\.0\.0\.1', '0\.0\.0\.0', '::'\) \}/)
+ // Filtered before anything is decided: none of them is `none`, never another address's owner.
+ expect(script.indexOf("-in @('127.0.0.1'")).toBeLessThan(script.indexOf("'none'"))
+ })
+ })
+
it('reads the owner of the client end from /proc/net/tcp, not the server end', () => {
const table = [
' sl local_address rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode',
@@ -220,7 +282,6 @@ describe('who is at the other end of a loopback connection', () => {
opened.push(() => server.close())
await new Promise<void>(resolve => { server.listen(0, '127.0.0.1', resolve) })
expect(await portHolderIsThisAccount((server.address() as AddressInfo).port)).toBe(true)
- expect(await portHolderIsThisAccount(1, 'win32')).toBeNull()
const table = [
' sl local_address rem_address st tx_queue rx_queue tr tm->when retrnsmt uid timeout inode',
' 0: 0100007F:C94F 00000000:0000 0A 00000000:00000000 00:00000000 00000000 1002 0 1',
diff --git a/cli/src/lib/peerAccount.ts b/cli/src/lib/peerAccount.ts
index f71de44e5..0773cddd7 100644
--- a/cli/src/lib/peerAccount.ts
+++ b/cli/src/lib/peerAccount.ts
@@ -86,12 +86,14 @@ export function procNetListener(table: string, port: number): number | null {
/**
* Whether the process listening on loopback [port] runs as this account: null when that cannot be said (a listener gone
- * by now, a lookup that failed, Windows). macOS shows an account only its own sockets, so a port that is taken but not
- * among them is another account's.
+ * by now, a lookup that failed). macOS shows an account only its own sockets, so a port that is taken but not among them
+ * is another account's. Windows is asked ([windowsListenerQuery], [run]): it answered null until task #2162, so the
+ * connectors bridge never moved off a port the Team account held from boot (Reed's review of #2605).
*/
-export async function portHolderIsThisAccount(port: number, platform: NodeJS.Platform = process.platform): Promise<boolean | null> {
+export async function portHolderIsThisAccount(port: number, platform: NodeJS.Platform = process.platform, run: WindowsPeerRun = runWindowsPeer): Promise<boolean | null> {
+ if (platform === 'win32') return askWindowsListener(port, run)
const uid = process.getuid?.()
- if (platform === 'win32' || uid === undefined) return null
+ if (uid === undefined) return null
if (platform === 'linux') {
// A kernel with no IPv6 has no tcp6, and /proc/net/tcp alone says who holds the port then.
const tables = await Promise.all(['/proc/net/tcp', '/proc/net/tcp6'].map(file => readFile(file, 'utf8').catch(() => '')))
@@ -158,6 +160,52 @@ export function windowsPeerQuery(peerPort: number, ownPort: number, daemonPid: n
}
}
+/**
+ * Windows: whose the listeners on loopback [port] are, of those that hold 127.0.0.1's port (on it, on any IPv4 address, or
+ * dual-stack on any address). Prints `none` when nothing listens there, `yes` when one of them belongs
+ * to a process of this account (a second daemon or a handover of its own, which the bridge waits out), and `no` otherwise.
+ * As in [windowsPeerQuery], the owner is compared by SID, and a process that started after its listener was made (an id
+ * reused since its creator exited) or one gone is not this account's: the answer that moves the bridge is the safe one.
+ * The port is an input, never in the script's text.
+ */
+export function windowsListenerQuery(port: number): { script: string; inputs: Record<string, string> } {
+ return {
+ script: [
+ // Only these keep 127.0.0.1's port from being bound; this account's listener on ::1 or 127.0.0.2 must not keep the bridge
+ // waiting on another account's 127.0.0.1 (Quinn 2's review of #2608).
+ "$rows = @(Get-NetTCPConnection -State Listen -LocalPort ([int]$env:HARNESS_LISTEN_PORT) -ErrorAction SilentlyContinue | Where-Object { $_.LocalAddress -in @('127.0.0.1', '0.0.0.0', '::') })",
+ "if ($rows.Count -eq 0) { 'none'; exit 0 }",
+ '$me = [Security.Principal.WindowsIdentity]::GetCurrent().User.Value',
+ 'foreach ($row in $rows) {',
+ // The lookup's own process, or one it started, never holds the port: it could have taken a freed id (as windowsPeerQuery).
+ ' if ($row.OwningProcess -eq $PID) { continue }',
+ ' $process = Get-CimInstance Win32_Process -Filter ("ProcessId = " + [int]$row.OwningProcess)',
+ ' if (-not $process -or -not $process.CreationDate -or -not $row.CreationTime) { continue }',
+ // Windows gives a socket's time to the second and a process's finer: the process's is cut to the second and compared with
+ // no slack, as in windowsPeerQuery.
+ ' $started = $process.CreationDate.AddTicks(-($process.CreationDate.Ticks % [TimeSpan]::TicksPerSecond))',
+ ' if ($started -gt $row.CreationTime) { continue }',
+ ' $owner = Invoke-CimMethod -InputObject $process -MethodName GetOwnerSid',
+ " if ($owner.ReturnValue -eq 0 -and $owner.Sid -and $owner.Sid -eq $me) { 'yes'; exit 0 }",
+ '}',
+ "'no'",
+ ].join('\n'),
+ inputs: { HARNESS_LISTEN_PORT: String(port) },
+ }
+}
+
+async function askWindowsListener(port: number, run: WindowsPeerRun): Promise<boolean | null> {
+ const query = windowsListenerQuery(port)
+ try {
+ const result = await run(query.script, query.inputs)
+ if (result.status !== 0) return null
+ const answer = result.stdout.trim()
+ return answer === 'yes' ? true : answer === 'no' ? false : null
+ } catch {
+ return null
+ }
+}
+
/**
* How many lookups run at once. Each is a PowerShell in this account for up to WINDOWS_PEER_MS, and whoever heard the
* hook token could open connections without end (Luna's review of #2605). Past these a lookup waits its turn, so the
diff --git a/cli/src/lib/windows/bridgePipe.windows.real.spec.ts b/cli/src/lib/windows/bridgePipe.windows.real.spec.ts
new file mode 100644
index 000000000..0da22abee
--- /dev/null
+++ b/cli/src/lib/windows/bridgePipe.windows.real.spec.ts
@@ -0,0 +1,75 @@
+// The connectors bridge's pipe (lib/connectors/bridge.ts serveBridgePipe, task #2162) on a real Windows named pipe: the stdio shim an
+// agent's entry runs reaches a connection through it, and Harness's own route lists the connections through it, with nothing sent
+// to the bridge's port. Windows only; the Windows workflow runs it with src/lib/windows. The squatter and dead-process cases are
+// pinned by the unit specs over a socket named as a pipe.
+import { spawn } from 'node:child_process'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer, type Server } from 'node:http'
+import type { AddressInfo } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { connectionsBridge, bridgeRoute } from '../../cloud/bridge.js'
+import { bridgePipeRecord, readBridgePipe } from '../connectors/agents.js'
+import { serveBridgePipe } from '../connectors/bridge.js'
+import { MCP_SHIM_SOURCE } from '../connectors/mcpShimSource.js'
+import { Store } from '../connectors/store.js'
+
+const WINDOWS = process.platform === 'win32'
+const cleanup: Array<() => unknown> = []
+afterEach(async () => { for (const close of cleanup.splice(0)) await close() })
+
+async function listen(server: Server): Promise<number> {
+ await new Promise<void>((resolve) => { server.listen(0, '127.0.0.1', resolve) })
+ cleanup.push(() => new Promise((done) => { server.closeAllConnections(); server.close(done) }))
+ return (server.address() as AddressInfo).port
+}
+
+describe.runIf(WINDOWS)('the bridge\'s pipe, on real Windows', () => {
+ it('the shim and Harness\'s own route reach the bridge over it, and nothing goes to the port', async () => {
+ const home = mkdtempSync(join(tmpdir(), 'bridge-pipe-'))
+ cleanup.push(() => rmSync(home, { recursive: true, force: true }))
+ const vault = new Store(join(home, 'c'), { USERPROFILE: home })
+ const heard: string[] = [], portHeard: string[] = []
+ const upstream = createServer((request, response) => {
+ let raw = ''
+ request.on('data', (part) => { raw += part })
+ request.on('end', () => {
+ const message = JSON.parse(raw) as { id?: number; method: string }
+ heard.push(message.method)
+ if (message.id === undefined) { response.writeHead(202).end(); return }
+ response.writeHead(200, { 'Content-Type': 'application/json', 'Mcp-Session-Id': 's1' })
+ .end(JSON.stringify({ jsonrpc: '2.0', id: message.id, result: message.method === 'initialize' ? { protocolVersion: '2025-06-18' } : { tools: [] } }))
+ })
+ })
+ const port = await listen(upstream)
+ const holder = createServer((request, response) => { portHeard.push(request.url ?? ''); response.writeHead(404).end() })
+ process.env.HARNESS_CONNECTIONS_PORT = String(await listen(holder))
+ cleanup.push(() => { delete process.env.HARNESS_CONNECTIONS_PORT })
+ vault.save('linear', { access_token: 't', source: 'dcr', mcp_entry: { url: `http://127.0.0.1:${port}/mcp`, headers: {} } })
+
+ const listening = await serveBridgePipe(vault)
+ cleanup.push(() => listening.close())
+ expect(listening.path).toMatch(/^\\\\\.\\pipe\\harness-[0-9a-f]{32}$/)
+ expect(readBridgePipe(vault)?.pipe).toBe(listening.path)
+
+ const shim = join(vault.root, 'mcp-shim.mjs')
+ mkdirSync(vault.root, { recursive: true })
+ writeFileSync(shim, MCP_SHIM_SOURCE)
+ const child = spawn(process.execPath, [shim, '--pipe', bridgePipeRecord(vault), 'linear'])
+ let out = ''
+ child.stdout.on('data', (chunk) => { out += String(chunk) })
+ child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }) + '\n')
+ child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'tools/list' }) + '\n')
+ child.stdin.end()
+ await new Promise((resolve) => child.on('exit', resolve))
+ expect(out.trim().split('\n').map((line) => JSON.parse(line) as { id: number })).toEqual([
+ { jsonrpc: '2.0', id: 1, result: { protocolVersion: '2025-06-18' } },
+ { jsonrpc: '2.0', id: 2, result: { tools: [] } },
+ ])
+ expect(heard).toEqual(['initialize', 'tools/list'])
+
+ expect((await connectionsBridge(() => bridgeRoute(vault)).connections()).map((c) => c.code)).toEqual(['linear'])
+ expect(portHeard).toEqual([])
+ }, 120_000)
+})
diff --git a/cli/src/lib/windows/bridgePort.windows.real.spec.ts b/cli/src/lib/windows/bridgePort.windows.real.spec.ts
new file mode 100644
index 000000000..32242195c
--- /dev/null
+++ b/cli/src/lib/windows/bridgePort.windows.real.spec.ts
@@ -0,0 +1,22 @@
+// Who holds the connectors bridge's port (lib/peerAccount.ts portHolderIsThisAccount, task #2162), asked of real Windows: a
+// listener this process opened is this account's, and a free port has no holder. Windows only; the Windows workflow runs it
+// with src/lib/windows. Another account's listener cannot be made from one account's test run; that answer is pinned by the
+// unit spec. The yes below also shows Windows gives both times the check compares: the process started before its listener.
+import { createServer, type AddressInfo } from 'node:net'
+import { afterEach, describe, expect, it } from 'vitest'
+import { portHolderIsThisAccount } from '../peerAccount.js'
+
+const WINDOWS = process.platform === 'win32'
+const cleanup: Array<() => void> = []
+afterEach(() => { for (const close of cleanup.splice(0)) close() })
+
+describe.runIf(WINDOWS)('who holds a listening port, asked of Windows', () => {
+ it('says yes for a listener of this account, and nothing once the port is free', async () => {
+ const server = createServer()
+ await new Promise<void>((resolve) => { server.listen(0, '127.0.0.1', resolve) })
+ const port = (server.address() as AddressInfo).port
+ expect(await portHolderIsThisAccount(port, 'win32')).toBe(true)
+ await new Promise<void>((resolve) => { server.close(() => resolve()) })
+ expect(await portHolderIsThisAccount(port, 'win32')).toBeNull()
+ }, 120_000)
+})
diff --git a/cli/src/services/connectors.spec.ts b/cli/src/services/connectors.spec.ts
index 40d030752..75b19d692 100644
--- a/cli/src/services/connectors.spec.ts
+++ b/cli/src/services/connectors.spec.ts
@@ -1,5 +1,6 @@
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
-import { bridgeKey, bridgePort, bridgeSocketPath, saveBridgePort } from '../lib/connectors/agents.js'
+import { bridgeKey, bridgePort, bridgeSocketPath, harnessKey, readBridgePipe, saveBridgePort } from '../lib/connectors/agents.js'
+import { randomBytes } from 'node:crypto'
import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
import { request as httpRequest } from 'node:http'
import { connect, createServer } from 'node:net'
@@ -391,4 +392,51 @@ describe('the connectors service', () => {
}
expect(status).toBe(404)
})
+
+ // Task #2162 (Reed's review of #2605): on Windows the bridge had only its port, which the Team account can hold from boot.
+ describe('on Windows', () => {
+ const freePort = async (): Promise<number> => {
+ const free = createServer()
+ await new Promise<void>(resolve => free.listen(0, '127.0.0.1', resolve))
+ const port = (free.address() as { port: number }).port
+ await new Promise(done => free.close(done))
+ return port
+ }
+ // A Unix socket named as a pipe stands for it; short, as a socket has to fit.
+ const shortPipe = (): { folder: string; pipe: string } => {
+ const folder = mkdtempSync(join('/tmp', 'cw-'))
+ return { folder, pipe: join(folder, 'p', `harness-${randomBytes(16).toString('hex')}`) }
+ }
+
+ it('serves the bridge on a proven pipe, records it, and takes Harness\'s key off the port', async () => {
+ const { folder, pipe } = shortPipe()
+ mkdirSync(join(folder, 'p'))
+ const vault = new Store(join(home, 'store'), env)
+ const stale = harnessKey(vault)
+ bridgeKey(vault)
+ const port = await freePort()
+ try {
+ startConnectors(fakeCore(), { vault, env, port, offered: async () => ({}), retryMs: 5, platform: 'win32', pipePath: () => pipe })
+ await vi.waitFor(() => expect(readBridgePipe(vault)?.pipe).toBe(pipe))
+ expect(vault.file('harness-key.json')).toMatchObject({ socketOnly: true })
+ expect(harnessKey(vault)).not.toBe(stale)
+ expect(typeof vault.file('bridge.json').keyRetiresAt).toBe('number')
+ await vi.waitFor(async () => expect((await fetch(`http://127.0.0.1:${port}/${harnessKey(vault)}/connections`)).status).toBe(404))
+ } finally { rmSync(folder, { recursive: true, force: true }) }
+ })
+
+ it('tries the pipe again, saying so once, when it cannot listen yet', async () => {
+ const { folder, pipe } = shortPipe()
+ const vault = new Store(join(home, 'store'), env)
+ const said = vi.spyOn(console, 'warn').mockImplementation(() => {})
+ try {
+ // Its folder is not there yet: the first listens fail.
+ startConnectors(fakeCore(), { vault, env, port: await freePort(), offered: async () => ({}), retryMs: 5, platform: 'win32', pipePath: () => pipe })
+ await vi.waitFor(() => expect(said.mock.calls.flat().join(' ')).toContain('the bridge\'s pipe is not listening'))
+ mkdirSync(join(folder, 'p'))
+ await vi.waitFor(() => expect(readBridgePipe(vault)?.pipe).toBe(pipe))
+ expect(said.mock.calls.flat().filter(line => String(line).includes('pipe is not listening'))).toHaveLength(1)
+ } finally { said.mockRestore(); rmSync(folder, { recursive: true, force: true }) }
+ })
+ })
})
diff --git a/cli/src/services/connectors.ts b/cli/src/services/connectors.ts
index 2fd2117bd..8e1744697 100644
--- a/cli/src/services/connectors.ts
+++ b/cli/src/services/connectors.ts
@@ -1,6 +1,6 @@
/**
* Connected services (lib/connectors): the MCP bridge every local agent's connector entries reach, through a stdio shim to
- * its 0600 socket (and on 127.0.0.1:51793 for clients still running on that address), and `connectors`, the desktop app's Connectors screen. Agents' entries are written
+ * its 0600 socket, or on Windows its pipe (and on 127.0.0.1:51793 for clients still running on that address), and `connectors`, the desktop app's Connectors screen. Agents' entries are written
* again as it starts, so an agent installed since a service was connected gets it too.
*
* `connectors` takes `{action}`: `list`, `connect` {connector}, `flow` {flow}, `disconnect` {connector},
@@ -18,7 +18,7 @@ import type { AddressInfo } from 'node:net'
import type { CoreApi, ServiceRequests } from '../core/api.js'
import { bridgePort, bridgeSocketPath, retireBridgeKey, rotateHarnessKey, saveBridgePort, sync } from '../lib/connectors/agents.js'
import { portHolderIsThisAccount } from '../lib/peerAccount.js'
-import { createBridge, serveBridgeSocket } from '../lib/connectors/bridge.js'
+import { createBridge, serveBridgePipe, serveBridgeSocket } from '../lib/connectors/bridge.js'
import { services, type GatewayRow } from '../lib/connectors/catalog.js'
import { addApiKey, addCustom, cards, disconnect, Flows, signInFor } from '../lib/connectors/connect.js'
import * as gateway from '../lib/connectors/gateway.js'
@@ -92,7 +92,22 @@ function listenSocket(vault: Store, path: string, retryMs: number, said = false)
})
}
-export function startConnectors(core: CoreApi, overrides: Partial<ConnectorsDeps> & { holderIsMine?: (port: number) => Promise<boolean | null> } = {}): ServiceRequests {
+/** The bridge's pipe on Windows (bridge.ts `serveBridgePipe`), a new name at each try. Said once, as the socket is. */
+function listenPipe(vault: Store, path: (() => string) | undefined, retryMs: number, said = false): void {
+ serveBridgePipe(vault, path?.()).catch((error: unknown) => {
+ if (!said) console.warn(`[connectors] the bridge's pipe is not listening, trying again: ${String(error)}`)
+ setTimeout(() => listenPipe(vault, path, retryMs, true), retryMs).unref()
+ })
+}
+
+export interface ConnectorsOverrides extends Partial<ConnectorsDeps> {
+ holderIsMine?: (port: number) => Promise<boolean | null>
+ /** The platform it runs on, and on Windows where its pipe is (a test's socket named as a pipe). */
+ platform?: NodeJS.Platform
+ pipePath?: () => string
+}
+
+export function startConnectors(core: CoreApi, overrides: ConnectorsOverrides = {}): ServiceRequests {
const env = overrides.env ?? process.env
const store = overrides.vault ?? new Store(undefined, env)
const deps: ConnectorsDeps = {
@@ -103,10 +118,13 @@ export function startConnectors(core: CoreApi, overrides: Partial<ConnectorsDeps
}
const { vault } = deps
const flows = new Flows(vault, env)
- const socket = bridgeSocketPath(vault)
- // Where a socket can be, the port takes neither key for long: Harness's own goes over the socket, and the agents' retires (agents.ts).
- if (socket) { try { rotateHarnessKey(vault) } catch (error) { console.warn(`[connections] could not replace Harness's key: ${(error as Error).message}`) } }
- const bridgeKeys = socket
+ const platform = overrides.platform ?? process.platform
+ const socket = bridgeSocketPath(vault, platform)
+ // Windows has no socket, but a pipe (task #2162): until then the Team account, holding the port from boot, heard every tool call.
+ const local = socket !== null || platform === 'win32'
+ // Where a socket or pipe can be, the port takes neither key for long: Harness's own goes over it, and the agents' retires (agents.ts).
+ if (local) { try { rotateHarnessKey(vault) } catch (error) { console.warn(`[connections] could not replace Harness's key: ${(error as Error).message}`) } }
+ const bridgeKeys = local
? { key: () => { try { return retireBridgeKey(vault) } catch { return '' } } }
: { key: () => String(vault.file('bridge.json').key ?? ''), harnessKey: () => String(vault.file('harness-key.json').key ?? '') }
const bridge = createBridge(vault, bridgeKeys)
@@ -125,8 +143,9 @@ export function startConnectors(core: CoreApi, overrides: Partial<ConnectorsDeps
},
} : undefined)
if (socket) listenSocket(vault, socket, deps.retryMs)
+ else if (local) listenPipe(vault, overrides.pipePath, deps.retryMs)
// Stamped now, not at a client's first call: the day counts from this start.
- if (socket) { try { retireBridgeKey(vault) } catch { /* The next request tries again. */ } }
+ if (local) { try { retireBridgeKey(vault) } catch { /* The next request tries again. */ } }
try { sync(vault, env) } catch { /* A config that cannot be written now is written at the next connect. */ }
// Connections the same on every computer of the account: read now, at each `connectors_changed`, and
diff --git a/cli/src/services/devicesProcess.spec.ts b/cli/src/services/devicesProcess.spec.ts
index 47f929c27..d5348aa37 100644
--- a/cli/src/services/devicesProcess.spec.ts
+++ b/cli/src/services/devicesProcess.spec.ts
@@ -294,6 +294,19 @@ describe('the core\'s doors, across the link', () => {
})
describe('what the core tells the devices, reaching their port', () => {
+ // Final review of spec 2026-11-02 poll cost: the fleet reads the machine list on `machines_changed` and only every
+ // 5 minutes otherwise, so the account's notices the core forwards must reach it here too.
+ it('hands the account notices the core forwards to its listeners', () => {
+ const h = setup()
+ const heard: unknown[] = []
+ const stop = h.api().account.onNotice((notice) => heard.push(notice))
+ h.event({ kind: 'notice', notice: { type: 'machines_changed', reason: 'renamed' } })
+ expect(heard).toEqual([{ type: 'machines_changed', reason: 'renamed' }])
+ stop()
+ h.event({ kind: 'notice', notice: { type: 'machines_changed', reason: 'renamed' } })
+ expect(heard).toHaveLength(1)
+ })
+
it('is each kind of notice, read as the port takes it', () => {
const f = setup()
const focus = { voice: { machineId: 'm1', agentId: 'a1', connId: 'w1' }, form: { machineId: 'm1', connId: 'w1' } }
diff --git a/cli/src/services/devicesProcess.ts b/cli/src/services/devicesProcess.ts
index b2924b6e1..566f7eaf2 100644
--- a/cli/src/services/devicesProcess.ts
+++ b/cli/src/services/devicesProcess.ts
@@ -15,6 +15,7 @@
* everything else is asked of the core when it is needed, or told to it. The core keeps what the windows
* said and tells it again each time this process connects.
*/
+import type { BackendNotice } from '../core/api.js'
import { env } from '../config/env.js'
import type { AppSwarms } from '../cable/cableSession.js'
import type { LeadRecap, SwarmCard } from '../superTabs/cards.js'
@@ -112,6 +113,8 @@ export function runDevicesService(options: DevicesServiceOptions): ServiceProces
const tell = (kind: string, payload: Record<string, unknown> = {}): void => { core?.notice?.(kind, payload) }
// What the devices never ask of the core, answered as every service in its own process answers it.
+ /** Who hears the account's notices in this process (the fleet), told them as the core forwards each. */
+ const noticeListeners = new Set<(notice: BackendNotice) => void>()
const unasked = processCoreApi(options.dataDir, 'devices')
const account = accountLink((query, payload) => ask(query, payload))
const api: CoreApi = {
@@ -171,6 +174,9 @@ export function runDevicesService(options: DevicesServiceOptions): ServiceProces
// The core's sign-in and the gateway's seal, asked at every use: this process holds no credential and
// no E2EE identity (services/accountLink.ts).
...account,
+ // The account's notices the core forwards (core/main.ts `onAccountNotice`): the fleet reads the machine list on
+ // `machines_changed`, and only every 5 minutes otherwise (spec 2026-11-02 poll cost, Part 4.4).
+ onNotice: (listener) => { noticeListeners.add(listener); return () => { noticeListeners.delete(listener) } },
signedIn: () => view.signedIn,
environment: () => view.environment,
machines: async () => {
@@ -217,6 +223,7 @@ export function runDevicesService(options: DevicesServiceOptions): ServiceProces
/** What the core tells the devices (`service_event`), by kind: the port's own calls, across the link. */
const heard: Record<string, (payload: Record<string, unknown>) => void> = {
+ notice: ({ notice }) => { if (notice && typeof notice === 'object') for (const listener of noticeListeners) listener(notice as BackendNotice) },
card: ({ frame }) => port.card(object(frame)),
desk: ({ agentIds, foreground }) => port.desk(strings(agentIds), foreground !== false),
swarms: ({ swarms }) => port.swarms(swarms && typeof swarms === 'object' ? swarms as AppSwarms : null),
diff --git a/cli/src/services/fleet.spec.ts b/cli/src/services/fleet.spec.ts
index 337d18acf..557de3ec7 100644
--- a/cli/src/services/fleet.spec.ts
+++ b/cli/src/services/fleet.spec.ts
@@ -8,7 +8,7 @@ import type { MachineListCache } from '../device/machineList.js'
import type { RegisteredSession } from '../lib/registry.js'
import { routeVoiceTask, type RouteDecision, type RouterAgent } from '../lib/voiceRouter.js'
import { fakeCore } from '../testing/fakeCore.js'
-import { FAIL, type CoreApi } from '../core/api.js'
+import { FAIL, type BackendNotice, type CoreApi } from '../core/api.js'
import { FLEET_FALLBACKS, startFleet, type Fleet, type FleetDeps } from './fleet.js'
// The lane is a cloud socket and the pinned keys a file under the data folder: neither in a test.
@@ -105,16 +105,29 @@ afterEach(() => {
})
describe('the machine list', () => {
- it('is read through the core at once, and again every minute until the fleet stops', () => {
+ // Spec 2026-11-02-poll-cost Part 4.4: read every 60 s by every daemon with a dial, almost always unchanged.
+ it('the fleet\'s machine list is served for 45 s and refreshed on machines_changed, every 5 minutes until the fleet stops', () => {
vi.useFakeTimers()
- const { fleet, machines } = setup()
+ const base = fakeCore()
+ let told: ((notice: BackendNotice) => void) | undefined
+ const unsubscribe = vi.fn()
+ vi.mocked(base.account.onNotice).mockImplementation((listener) => { told = listener; return unsubscribe })
+ const { fleet, machines } = setup({}, base)
+ expect(machines.refresh.mock.calls).toEqual([[{ maxAgeMs: 45_000 }]])
+ vi.advanceTimersByTime(299_999)
expect(machines.refresh).toHaveBeenCalledTimes(1)
- vi.advanceTimersByTime(60_000)
- expect(machines.refresh).toHaveBeenCalledTimes(2)
+ vi.advanceTimersByTime(1)
+ expect(machines.refresh.mock.calls).toEqual([[{ maxAgeMs: 45_000 }], [{ maxAgeMs: 45_000 }]])
+ // A machine added, renamed or removed: read now, whatever the list's age. Who uses a harness here is not the list.
+ told!({ type: 'machines_changed', reason: 'renamed' })
+ told!({ type: 'machines_changed', reason: 'harness_shares' })
+ told!({ type: 'desk_changed', revision: 0 })
+ expect(machines.refresh.mock.calls.slice(2)).toEqual([[{ maxAgeMs: 0 }]])
fleet.stop()
expect(lane.stop).toHaveBeenCalled()
- vi.advanceTimersByTime(120_000)
- expect(machines.refresh).toHaveBeenCalledTimes(2)
+ expect(unsubscribe).toHaveBeenCalledOnce()
+ vi.advanceTimersByTime(600_000)
+ expect(machines.refresh).toHaveBeenCalledTimes(3)
})
})
diff --git a/cli/src/services/fleet.ts b/cli/src/services/fleet.ts
index 22e569a87..d5ee94caf 100644
--- a/cli/src/services/fleet.ts
+++ b/cli/src/services/fleet.ts
@@ -108,8 +108,12 @@ export const FLEET_FALLBACKS: PortFallbacks<Fleet> = {
const ROUTE_MAX_CANDIDATES = 15
/** What ⌘K gives the classifier before the name matcher answers instead. */
const ROUTE_CLASSIFY_APP_MS = 20_000
-/** How often the machine list is read again: the wheel's dots and the agent lists follow it. */
-const MACHINE_LIST_REFRESH_MS = 60_000
+/** How often the machine list is read again: the wheel's dots and the agent lists follow it. Every minute until spec
+ * 2026-11-02-poll-cost Part 4.4: a change to the account's machines is told (`machines_changed`) and read at once, live
+ * presence comes on the socket (`MachineListCache.applyLive`), and this is the net for a lost push. */
+const MACHINE_LIST_REFRESH_MS = 5 * 60_000
+/** A list read this recently (by this refresh, or one a notice asked for) is not read again by the timer. */
+const MACHINE_LIST_MAX_AGE_MS = 45_000
/** What the fleet needs that is not the core's to give. */
export interface FleetDeps {
@@ -131,10 +135,14 @@ export function startFleet(core: CoreApi, deps: FleetDeps): { fleet: Fleet; rout
//
// Signed out there is nothing to fetch and a fetch would only earn a 401 that empties the wheel, so the
// core answers with the one row this daemon can speak for (`account.machines`).
- const refreshMachineList = (): void => { void deps.machines.refresh() }
+ const refreshMachineList = (): void => { void deps.machines.refresh({ maxAgeMs: MACHINE_LIST_MAX_AGE_MS }) }
refreshMachineList()
const machineListTimer = setInterval(refreshMachineList, MACHINE_LIST_REFRESH_MS)
machineListTimer.unref?.()
+ // A machine added, renamed or removed: read now. Who uses a harness here (`harness_shares`) is not the list.
+ const stopNotices = core.account.onNotice((notice) => {
+ if (notice.type === 'machines_changed' && notice.reason !== 'harness_shares') void deps.machines.refresh({ maxAgeMs: 0 })
+ })
const peers = new MachinePeerStore()
const link = new DeviceLink({
@@ -221,6 +229,7 @@ export function startFleet(core: CoreApi, deps: FleetDeps): { fleet: Fleet; rout
onEvent: (listener) => devices.onEvent(listener),
stop: () => {
clearInterval(machineListTimer)
+ stopNotices()
link.stop()
},
}
diff --git a/cli/src/superTabs/cards.spec.ts b/cli/src/superTabs/cards.spec.ts
index 4cb55e65a..7861be907 100644
--- a/cli/src/superTabs/cards.spec.ts
+++ b/cli/src/superTabs/cards.spec.ts
@@ -1,5 +1,5 @@
import { afterEach, describe, expect, it, vi } from 'vitest'
-import type { CoreApi } from '../core/api.js'
+import type { BackendNotice, CoreApi } from '../core/api.js'
import { fakeCore } from '../testing/fakeCore.js'
import { lastAgentMessage, leadsOf, SwarmCards, type SwarmCard } from './cards.js'
import { swarmReply } from './fixtures/read/index.js'
@@ -528,6 +528,92 @@ describe('SwarmCards.want', () => {
})
})
+// Spec 2026-11-02-poll-cost Part 4.3: a Pro's cards read the Swarm list every 5 s, ignoring the server's pushes (prod
+// 2026-11-02: about 200 of the 279 list reads a minute). While the server says it pushes Swarm changes, as it does to
+// Desktop, the list is read when a Swarm's main parts change and every 2 minutes as the safety net.
+describe('SwarmCards and the server\'s Swarm pushes', () => {
+ it('cards read on push and every 2 minutes, every 5 s without the lease', async () => {
+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() } })
+ let told: ((notice: BackendNotice) => void) | undefined
+ const unsubscribe = vi.fn()
+ vi.mocked(t.core.account.onNotice).mockImplementation(listener => { told = listener; return unsubscribe })
+ const listed = () => t.calls.filter(c => c === 'GET /api/super-tabs/list').length
+ // The cards' timer, every 5 s here, and their clock with it.
+ const every5s = async (seconds: number) => { for (let s = 0; s < seconds; s += 5) { t.advance(5_000); await vi.advanceTimersByTimeAsync(5_000) } }
+ vi.useFakeTimers()
+ t.cards.want(true)
+ await vi.advanceTimersByTimeAsync(0)
+ expect(listed()).toBe(1)
+ // No lease: every tick.
+ await every5s(10)
+ expect(listed()).toBe(3)
+ // The server says it pushes: read once now, then only when told or every 2 minutes.
+ told!({ type: 'swarm_changed' })
+ await every5s(5)
+ expect(listed()).toBe(4)
+ await every5s(60)
+ expect(listed()).toBe(4)
+ // A machine's reading changes nothing a card shows; a commit to a Swarm's main parts does.
+ told!({ type: 'swarm_changed', tabId: 't1', lastChangedAt: 2, parts: ['machine'] })
+ await every5s(5)
+ expect(listed()).toBe(4)
+ told!({ type: 'swarm_changed', tabId: 't1', lastChangedAt: 3, parts: ['main'] })
+ await every5s(5)
+ expect(listed()).toBe(5)
+ await every5s(115)
+ expect(listed()).toBe(5)
+ await every5s(5)
+ expect(listed()).toBe(6)
+ // Five minutes without the server's word: every tick again.
+ await every5s(240)
+ const lapsed = listed()
+ await every5s(10)
+ expect(listed()).toBe(lapsed + 2)
+ t.cards.want(false)
+ expect(unsubscribe).toHaveBeenCalledOnce()
+ })
+
+ it('under the lease, a Swarm the list could not read yet is read on the next tick, not 2 minutes later', async () => {
+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() }, t2: { lastChangedAt: 1, state: swarm({ name: 'two' }) } })
+ let told: ((notice: BackendNotice) => void) | undefined
+ vi.mocked(t.core.account.onNotice).mockImplementation(listener => { told = listener; return () => {} })
+ const tick = async () => { t.advance(5_000); await vi.advanceTimersByTimeAsync(5_000) }
+ t.failing.set('t1', 500)
+ vi.useFakeTimers()
+ t.cards.want(true)
+ await vi.advanceTimersByTimeAsync(0)
+ told!({ type: 'swarm_changed' })
+ await tick()
+ expect(t.seen).toEqual([])
+ t.failing.delete('t1')
+ await tick()
+ expect(t.seen.at(-1)?.map(c => c.id)).toEqual(['t1', 't2'])
+ t.cards.want(false)
+ })
+
+ it('reads the list again on the next tick after a list read that failed under the lease', async () => {
+ const t = setup({ t1: { lastChangedAt: 1, state: swarm() } })
+ let told: ((notice: BackendNotice) => void) | undefined
+ vi.mocked(t.core.account.onNotice).mockImplementation(listener => { told = listener; return () => {} })
+ const listed = () => t.calls.filter(c => c === 'GET /api/super-tabs/list').length
+ const tick = async () => { t.advance(5_000); await vi.advanceTimersByTimeAsync(5_000) }
+ vi.useFakeTimers()
+ t.cards.want(true)
+ await vi.advanceTimersByTimeAsync(0)
+ expect(listed()).toBe(1)
+ told!({ type: 'swarm_changed' })
+ t.breakList()
+ await tick()
+ expect(listed()).toBe(2)
+ t.breakList(false)
+ await tick()
+ expect(listed()).toBe(3)
+ await tick()
+ expect(listed()).toBe(3)
+ t.cards.want(false)
+ })
+})
+
describe('SwarmCards polling cost and choice', () => {
const many = (n: number) => Object.fromEntries(Array.from({ length: n }, (_, i) => [`t${String(i).padStart(2, '0')}`, { lastChangedAt: 1, state: swarm({ name: `S${i}` }) }]))
diff --git a/cli/src/superTabs/cards.ts b/cli/src/superTabs/cards.ts
index 3b23d121e..ef3cef77c 100644
--- a/cli/src/superTabs/cards.ts
+++ b/cli/src/superTabs/cards.ts
@@ -1,7 +1,8 @@
/**
* The Swarms a Harness Pro shows as cards on Home: for each Swarm (Super Tab) this account is in, one Lead per project with
* what it is doing now, plus the last thing a Lead said, for the Pro's recap. Read as the person (never as an agent) from
- * the same backend routes the desktop uses, every 5 s while a capable Pro is attached (`want`), and a tab's detail is read
+ * the same backend routes the desktop uses, every 5 s while a capable Pro is attached (`want`); while the server pushes Swarm
+ * changes, the list only when told and every 2 minutes (CARDS_SAFETY_MS). A tab's detail is read
* only when its `lastChangedAt` moved, by what changed since the last read (superTabs/swarmReads.ts). The service hands the
* result to the core whole (`onCards`); the core owns the wire.
*
@@ -17,7 +18,7 @@
* its meaning for the Pro and older dials, which never read either.
*/
import { randomUUID } from 'node:crypto'
-import type { CoreApi } from '../core/api.js'
+import type { BackendNotice, CoreApi } from '../core/api.js'
import { backend, SuperTabHostError } from './host.js'
import { identifier, object } from './wire.js'
import { SwarmReads, type SwarmRead } from './swarmReads.js'
@@ -222,6 +223,12 @@ const recapKey = (tabId: string, leadId: string, chatId?: string) => chatId ===
/** A recap's cache key: an older dial's and a swarmBuddy dial's recap of one Buddy chat hear different voices. */
const cachedKey = (tabId: string, leadId: string, chatId: string | undefined, chat: CardChat) => `${recapKey(tabId, leadId, chatId)}${chat === 'buddy' ? ':buddy' : ''}`
const isSide = (v: unknown): v is CardSide => v === 'pm' || v === 'buddy'
+/** Spec 2026-11-02-poll-cost Part 4.3: the list was read every 5 s whatever changed (prod 2026-11-02: about 200 list reads a
+ * minute). While the server says it pushes this account's Swarm changes (`swarm_changed` naming none, repeated every 4
+ * minutes: backend lib/swarmClientPushes.ts), the list is read when a Swarm's main parts change, and after this long as the
+ * net for a lost push. The lease is Desktop's (super_tabs/controller.dart kSwarmPushLease). */
+export const CARDS_SAFETY_MS = 120_000
+const SWARM_PUSH_LEASE_MS = 5 * 60_000
const tabOf = (read: SwarmRead): TabCache => ({ lastChangedAt: read.lastChangedAt, state: read.state })
/** How long the first list waits for a Swarm whose read failed, before going without it. */
@@ -269,6 +276,12 @@ export class SwarmCards {
/** Watched conversations whose last read failed, so a run of failures is logged once. */
private failed = new Set<string>()
private readonly reads: SwarmReads
+ /** Until when the server is known to push Swarm changes, when the list was last read, and whether a change since asks
+ * for it again. */
+ private pushUntil = 0
+ private listedAt = -Infinity
+ private listTold = false
+ private stopNotices: (() => void) | null = null
constructor(private readonly core: CoreApi, private readonly machineId: string, options: { now?: () => number; intervalMs?: number; reads?: SwarmReads; log?: (line: string) => void } = {}) {
this.now = options.now ?? Date.now
@@ -284,6 +297,9 @@ export class SwarmCards {
if (!on) {
if (this.timer) clearInterval(this.timer)
this.timer = undefined
+ this.stopNotices?.()
+ this.stopNotices = null
+ this.pushUntil = 0
this.opened.clear(); this.openBy.clear(); this.include = []; this.focus = null; this.sides.clear()
// A device that attaches again starts a fresh baseline: what was said while none was here never alerts.
this.seen.clear(); this.forgetNotices()
@@ -298,11 +314,14 @@ export class SwarmCards {
this.focus = next
// The desktop's own move clears the dial's side; the move a dial's pick caused is the dial's, and keeps it.
if (refocused && !next?.fromDevice) this.sides.clear()
+ // Other Swarms to show first: the list is read for them now, whatever the server pushes.
+ if (moved) this.listTold = true
if (this.timer) {
if (refocused && this.live) { this.emit(); void this.pushOpen() }
if (moved) void this.tick()
return
}
+ this.stopNotices = this.core.account.onNotice(notice => this.heard(notice))
this.timer = setInterval(() => { void this.tick() }, this.intervalMs)
this.timer.unref?.()
void this.tick()
@@ -368,6 +387,16 @@ export class SwarmCards {
})
}
+ /** The server's word on this account's Swarms: naming none, it pushes them (and what changed meanwhile is read once); naming
+ * one, a change to its main parts is read at the next tick. A machine's reading alone changes nothing a card shows. */
+ private heard(notice: BackendNotice): void {
+ if (notice.type !== 'swarm_changed') return
+ if (notice.tabId === undefined && notice.parts === undefined) {
+ this.pushUntil = this.now() + SWARM_PUSH_LEASE_MS
+ this.listTold = true
+ } else if (notice.parts?.includes('main')) this.listTold = true
+ }
+
async tick(): Promise<void> {
if (this.busy) return
this.busy = true
@@ -390,30 +419,40 @@ export class SwarmCards {
}
private async poll(): Promise<void> {
- const rows = await this.listTabs()
- const known = new Map<string, TabCache>()
- let unread = false
- await Promise.all(rows.map(async row => {
- const id = row.id as string, held = this.tabs.get(id)
- // A row without a numeric change time cannot say it is unchanged: that tab is always read again.
- if (held && typeof row.lastChangedAt === 'number' && held.lastChangedAt === row.lastChangedAt) { known.set(id, held); return }
- try { known.set(id, tabOf(await this.reads.read(id))) } catch (error) {
- // Lost access drops only this card; any other failure keeps what was read before.
- const status = error instanceof SuperTabHostError ? error.status : 0
- if (status === 401 || status === 403) return
- if (held) known.set(id, held)
- else unread = true
- }
- }))
- this.tabs = known
- // After a restart nothing is held, so one passing failure (a 5xx, a timeout) would leave that Swarm out of the first list,
- // and the dial takes a list without a Swarm to mean it went. Bounded: a Swarm that keeps failing must not hide the others.
- const first = unread && this.last === null
- this.unreadSince = first ? this.unreadSince ?? this.now() : null
- this.holding = this.unreadSince !== null && this.now() - this.unreadSince < UNREAD_HOLD_MS
- // A Swarm that left the cards (access lost) takes the dial's side with it.
- for (const tabId of [...this.sides.keys()]) if (!known.has(tabId)) this.sides.delete(tabId)
- this.rows = rows.map(row => ({ id: row.id as string, name: row.name }))
+ // The list and the Swarms it says changed, unless the server pushes and nothing it said asks for them: the rest of the
+ // poll (the turns here, the Leads' new messages, the cards) still runs each tick from the last reads.
+ if (this.now() >= this.pushUntil || this.listTold || this.now() - this.listedAt >= CARDS_SAFETY_MS) {
+ // Cleared before the read: a change told during it asks for another.
+ this.listTold = false
+ let rows: Json[]
+ try { rows = await this.listTabs() } catch (error) { this.listTold = true; throw error }
+ this.listedAt = this.now()
+ const known = new Map<string, TabCache>()
+ let unread = false
+ await Promise.all(rows.map(async row => {
+ const id = row.id as string, held = this.tabs.get(id)
+ // A row without a numeric change time cannot say it is unchanged: that tab is always read again.
+ if (held && typeof row.lastChangedAt === 'number' && held.lastChangedAt === row.lastChangedAt) { known.set(id, held); return }
+ try { known.set(id, tabOf(await this.reads.read(id))) } catch (error) {
+ // Lost access drops only this card; any other failure keeps what was read before.
+ const status = error instanceof SuperTabHostError ? error.status : 0
+ if (status === 401 || status === 403) return
+ if (held) known.set(id, held)
+ else unread = true
+ }
+ }))
+ this.tabs = known
+ // A Swarm that could not be read and is not held is read again next tick, push or not.
+ if (unread) this.listTold = true
+ // After a restart nothing is held, so one passing failure (a 5xx, a timeout) would leave that Swarm out of the first list,
+ // and the dial takes a list without a Swarm to mean it went. Bounded: a Swarm that keeps failing must not hide the others.
+ const first = unread && this.last === null
+ this.unreadSince = first ? this.unreadSince ?? this.now() : null
+ this.holding = this.unreadSince !== null && this.now() - this.unreadSince < UNREAD_HOLD_MS
+ // A Swarm that left the cards (access lost) takes the dial's side with it.
+ for (const tabId of [...this.sides.keys()]) if (!known.has(tabId)) this.sides.delete(tabId)
+ this.rows = rows.map(row => ({ id: row.id as string, name: row.name }))
+ }
const me = (await this.core.account.identity().catch(() => null))?.accountId
// Another person signed in: nothing of the last account's is kept, and the list is said again whatever it is.
if (this.me !== undefined && me !== this.me) { this.last = null; this.recaps.clear(); this.seen.clear(); this.forgetNotices(); this.sides.clear() }
diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.ts
index e88246ebe..3224ba35f 100644
--- a/cli/src/superTabs/host.spec.ts
+++ b/cli/src/superTabs/host.spec.ts
@@ -465,12 +465,28 @@ describe('Super Tab native delivery handoff', () => {
const host = t.open()
await host.tick()
expect(delivered(t)).toContain('Replying to Lead')
- // Each try claims again; the server refuses a claim for an agent no longer in the conversation (deliveryAllowed).
+ // The server lists no delivery an agent may no longer read (store.ts allowedDeliveries), and refuses its claim
+ // (deliveryAllowed): a held write is tried again only while its list still names it, and claimed again every 2 minutes.
+ const original = vi.mocked(t.call).getMockImplementation()!
+ vi.mocked(t.call).mockImplementation(async (method, path, body) => (body as Record<string, unknown> | undefined)?.type === 'claim'
+ ? { status: 403, body: { success: false, error: { code: 'DELIVERY_REVOKED', message: 'This instruction is no longer authorized.' } } }
+ : method === 'GET' && path.endsWith('/deliveries') ? { status: 200, body: { success: true, data: [] } }
+ : original(method, path, body))
+ t.event('rejected', 'team_waiting_busy')
+ await host.tick().catch(() => {})
+ expect(t.core.turns.deliver).toHaveBeenCalledTimes(1)
+ })
+ it('never types a held quote claimed again once the server refuses the claim, though its list still names it', async () => {
+ const t = setup({ replyTo: 'question-2', text: 'GO' })
+ serve(t, () => ({ messages: [earlier()], next: null }))
+ const host = t.open()
+ await host.tick()
const original = vi.mocked(t.call).getMockImplementation()!
vi.mocked(t.call).mockImplementation(async (method, path, body) => (body as Record<string, unknown> | undefined)?.type === 'claim'
? { status: 403, body: { success: false, error: { code: 'DELIVERY_REVOKED', message: 'This instruction is no longer authorized.' } } }
: original(method, path, body))
t.event('rejected', 'team_waiting_busy')
+ t.wait(120_000)
await host.tick().catch(() => {})
expect(t.core.turns.deliver).toHaveBeenCalledTimes(1)
})
@@ -535,9 +551,11 @@ describe('Super Tab native delivery handoff', () => {
if (method === 'GET' && path.endsWith('/deliveries/delivery')) {
return { status: 200, body: { success: true, data: { id: 'delivery', status: 'confirmed' } } }
}
+ // Resolved, it is no longer open: its list, read before the receipt is asked, no longer shows it.
+ if (method === 'GET' && path.endsWith('/deliveries')) return { status: 200, body: { success: true, data: [] } }
return original(method, path, body)
})
- await host.reconcileReceipts()
+ await host.tick(); await host.reconcileReceipts()
expect(t.saved().entries).toEqual({})
expect(t.core.turns.deliver).toHaveBeenCalledTimes(1)
})
@@ -588,6 +606,8 @@ describe('Super Tab native delivery handoff', () => {
})
return s
}
+ /** The backend ended it: the agent's next list read no longer shows it, so its receipt is asked (Part 3.4). */
+ const end = async (s: ReturnType<typeof outage>, host: SuperTabHost) => { s.ended = true; await host.tick().catch(() => {}) }
const typed = async (t: ReturnType<typeof setup>) => {
const host = t.open()
await host.tick(); t.event('delivered')
@@ -625,7 +645,8 @@ describe('Super Tab native delivery handoff', () => {
it('is not sent again once the backend refuses it, as for a delivery an archive ended, and the entry goes', async () => {
for (const refusal of [{ status: 403, code: 'DELIVERY_REVOKED' }, { status: 403, code: 'FORBIDDEN' }, { status: 409, code: 'CLAIM_CONFLICT' }]) {
const t = setup(), host = await typed(t), s = outage(t)
- s.down = false; s.ended = true; s.refusal = refusal
+ s.down = false; s.refusal = refusal
+ await end(s, host)
await host.reconcileReceipts()
expect(s.acks).toBe(1)
expect(t.saved().entries).toEqual({})
@@ -639,7 +660,7 @@ describe('Super Tab native delivery handoff', () => {
it('keeps the entry while the backend still cannot take it, trying again only after a growing wait, until it gets through', async () => {
const t = setup(), host = await typed(t), s = outage(t)
// The list says nothing waits, the receipt says ended, and the acknowledgement still answers busy.
- s.ended = true
+ await end(s, host)
await host.reconcileReceipts()
expect(s.acks).toBe(1)
// 10 s, then 20 s: the receipts pass itself runs every 5 s.
@@ -662,7 +683,7 @@ describe('Super Tab native delivery handoff', () => {
it.each([['answers busy', null], ['drops the connection', 'socket closed']])('gives up after a day while the backend %s, said once, so the journal never fills', async (_case, dropped) => {
const t = setup(), host = await typed(t), s = outage(t)
- s.ended = true
+ await end(s, host)
if (dropped) {
const original = vi.mocked(t.core.account.backend).getMockImplementation()!
vi.mocked(t.core.account.backend).mockImplementation(async (method, path, body) => {
@@ -683,7 +704,8 @@ describe('Super Tab native delivery handoff', () => {
it('writes nothing once the host stops during a late acknowledgement, and keeps the entry for the next host', async () => {
const t = setup(), host = await typed(t), s = outage(t)
- s.down = false; s.ended = true
+ s.down = false
+ await end(s, host)
const original = vi.mocked(t.core.account.backend).getMockImplementation()!
vi.mocked(t.core.account.backend).mockImplementation(async (method, path, body) => {
if ((body as Record<string, unknown> | undefined)?.type === 'ack') host.stop()
@@ -696,7 +718,8 @@ describe('Super Tab native delivery handoff', () => {
it('never retires an entry that replaced the one it acknowledged late while the answer was on its way', async () => {
const t = setup(), host = await typed(t), s = outage(t)
- s.down = false; s.ended = true
+ s.down = false
+ await end(s, host)
const journal = (host as unknown as { journal: { entries: Record<string, Record<string, unknown>> } }).journal
const original = vi.mocked(t.core.account.backend).getMockImplementation()!
vi.mocked(t.core.account.backend).mockImplementation(async (method, path, body) => {
@@ -714,7 +737,8 @@ describe('Super Tab native delivery handoff', () => {
await host.tick()
if (stage === 'held') t.event('rejected', 'team_waiting_busy'); else t.event('unknown', 'lost acknowledgement')
const s = outage(t)
- s.down = false; s.ended = true
+ s.down = false
+ await end(s, host)
await host.reconcileReceipts()
expect(s.acks).toBe(0)
expect(t.saved().entries).toEqual({})
@@ -729,7 +753,12 @@ describe('Super Tab native delivery handoff', () => {
if (method === 'GET' && path.endsWith('/deliveries/delivery')) return { status: 200, body: { success: true, data: { id: 'delivery', status: 'answered' } } }
return original(method, path, body)
})
- vi.mocked(t.core.turns.leaseDeliveries).mockImplementationOnce(async () => { await host.reconcileReceipts(); return true })
+ // As if its list were not shown (no other path asks a listed entry's receipt now): the guard still holds.
+ vi.mocked(t.core.turns.leaseDeliveries).mockImplementationOnce(async () => {
+ (host as unknown as { lists: Map<string, unknown> }).lists.clear()
+ await host.reconcileReceipts()
+ return true
+ })
await host.tick()
expect(t.core.turns.deliver).toHaveBeenCalledTimes(1)
expect(t.saved().entries).toEqual({})
@@ -2790,6 +2819,25 @@ describe('a Lead\'s terminal requests', () => {
await vi.waitFor(() => expect(t.call).toHaveBeenCalledWith('POST', '/api/super-tabs/tab/commands',
{ operationId: 'terminal-r1', asAgentId: 'agent', command: { type: 'agent.screenResult', requestId: 'r1', ok: true, text: 'Allow? 1. Yes' } }))
})
+
+ // Spec 2026-11-02-poll-cost Part 4.2: picked up on the server's word, polled every 8 s while it pushes, every 3 s without.
+ it('picks one up at once when the server says one waits, and polls every 8 s only while the server pushes', async () => {
+ const t = setup()
+ Object.assign(t.core, { superTabs: { attention: vi.fn(), cards: vi.fn(), cardRecap: vi.fn(), shareObservers: vi.fn(), input: vi.fn(),
+ screen: vi.fn(async () => ({ ok: true as const, text: '> ', hold: null })) } })
+ const pickups = () => vi.mocked(t.call).mock.calls.filter(([, path]) => path === '/api/super-tabs/hosts/machine-1/terminal').length
+ const host = t.open()
+ t.idle()
+ t.push({ type: 'super_tab_deliveries' })
+ await host.tick()
+ await vi.waitFor(() => expect(pickups()).toBe(1))
+ t.wait(3_000); await host.tick()
+ expect(pickups()).toBe(1)
+ t.push({ type: '__terminal_waiting', tabId: 'tab', agentId: 'agent' })
+ await vi.waitFor(() => expect(pickups()).toBe(2))
+ t.wait(8_000); await host.tick()
+ await vi.waitFor(() => expect(pickups()).toBe(3))
+ })
})
describe('a task lost to a usage limit', () => {
@@ -3955,6 +4003,25 @@ describe('ending a Buddy\'s thread sessions', () => {
expect(ends(t)).toEqual([])
})
+ // Spec 2026-11-02-poll-cost Part 3: a delivery its pane holds no longer keeps its list read each second, and still waits.
+ it('never ends one whose delivery its pane holds', async () => {
+ const t = lifeFixture([sessionRow()])
+ t.live(true)
+ const backendOf = t.core.account.backend
+ t.core.account.backend = async (method, path, body) => {
+ if (method === 'GET' && path.endsWith('/agents/agent/deliveries')) return { status: 200, body: { data: [{ id: 'delivery', conversationId: chat, status: 'claimed' }] } }
+ if ((body as Record<string, unknown> | undefined)?.type === 'claim') {
+ return { status: 200, body: { data: { delivery: { id: 'delivery' }, message: { id: 'm', conversationId: chat, text: 'Still there?', author: { name: 'Peer' } } } } }
+ }
+ return backendOf(method, path, body)
+ }
+ vi.mocked(t.core.turns.deliver).mockImplementation(() => t.event('rejected', 'team_waiting_busy'))
+ t.push({ type: 'super_tab_deliveries' })
+ await awake(t, 2 * BUDDY_SESSION_IDLE_MS)
+ expect(t.core.turns.deliver).toHaveBeenCalled()
+ expect(ends(t)).toEqual([])
+ })
+
it('ends one whose terminal is gone for a minute as stopped, and never one gone for less', async () => {
const t = lifeFixture([sessionRow()])
await t.poll()
@@ -4951,6 +5018,215 @@ describe('deliveries the server pushes', () => {
})
})
+// Spec 2026-11-02-poll-cost Part 3: a held delivery was claimed again every second, for up to a day, and its agent's list
+// read each second with it (prod 2026-11-02: 414 claim POSTs and 294 list GETs a minute). The host now keeps the claimed
+// message, writes it again on each tick, claims it again only every 2 minutes, and reads a held agent's list every 30 s or
+// when the server says something changed.
+describe('a delivery held by a busy pane', () => {
+ const reads = (t: ReturnType<typeof setup>) => vi.mocked(t.call).mock.calls
+ .filter(([method, path]) => method === 'GET' && path.endsWith('/deliveries')).length
+ const claims = (t: ReturnType<typeof setup>) => vi.mocked(t.call).mock.calls
+ .filter(([method, , body]) => method === 'POST' && (body as Record<string, unknown> | undefined)?.type === 'claim').length
+ const writes = (t: ReturnType<typeof setup>) => vi.mocked(t.core.turns.deliver).mock.calls.length
+ const announced: BackendNotice = { type: 'super_tab_deliveries' }
+ async function seconds(t: ReturnType<typeof setup>, host: SuperTabHost, count: number) {
+ for (let i = 0; i < count; i++) { t.wait(1_000); await host.tick() }
+ }
+ /** The core refuses every write while the pane is busy, as its input does for a running turn (lib/sessionInput.ts). */
+ function heldBy(t: ReturnType<typeof setup>) {
+ const pane = { busy: true }
+ vi.mocked(t.core.turns.deliver).mockImplementation(() => { if (pane.busy) t.event('rejected', 'team_waiting_busy'); else t.event('delivered') })
+ return pane
+ }
+
+ it('a held delivery makes no claim for 2 minutes and is written once the pane frees', async () => {
+ const t = setup(), host = t.open()
+ const pane = heldBy(t)
+ t.push(announced)
+ await host.tick()
+ expect([claims(t), writes(t)]).toEqual([1, 1])
+ await seconds(t, host, 119)
+ // Written again on each tick, its claim kept, and its list read only every 30 s.
+ expect(claims(t)).toBe(1)
+ expect(writes(t)).toBe(120)
+ expect(reads(t)).toBe(4)
+ await seconds(t, host, 1)
+ expect(claims(t)).toBe(2)
+ // Told once, as before.
+ await vi.waitFor(() => expect(t.holds).toHaveLength(1))
+ pane.busy = false
+ await seconds(t, host, 1)
+ await vi.waitFor(() => expect(t.receipts).toEqual([expect.objectContaining({ uncertain: false })]))
+ expect(t.saved().entries).toEqual({})
+ await seconds(t, host, 5)
+ expect(writes(t)).toBe(122)
+ })
+
+ it('a cancel pushed while held stops the retry', async () => {
+ const t = setup(), host = t.open()
+ heldBy(t)
+ t.push(announced)
+ await host.tick()
+ await seconds(t, host, 5)
+ expect(writes(t)).toBe(6)
+ // Cancelled by its sender: the backend lists it no more and says so to this machine (Part 3.2).
+ t.idle()
+ t.push({ type: 'super_tab_deliveries', tabId: 'tab', agentId: 'agent' })
+ await seconds(t, host, 60)
+ expect(writes(t)).toBe(6)
+ expect(claims(t)).toBe(1)
+ })
+
+ // Review focus 1: a push lost while a delivery is held.
+ it('a cancel missed by push stops the retry at the next 30 s read', async () => {
+ const t = setup(), host = t.open()
+ heldBy(t)
+ t.push(announced)
+ await host.tick()
+ await seconds(t, host, 5)
+ t.idle()
+ await seconds(t, host, 24)
+ expect(writes(t)).toBe(30)
+ await seconds(t, host, 1)
+ await seconds(t, host, 60)
+ expect(writes(t)).toBe(30)
+ expect(reads(t)).toBe(4)
+ })
+
+ it('an acked message costs no extra list read', async () => {
+ const t = setup(), host = t.open()
+ t.push(announced)
+ await host.tick()
+ t.event('delivered')
+ await seconds(t, host, 1)
+ expect(t.receipts).toHaveLength(1)
+ expect(reads(t)).toBe(2)
+ await seconds(t, host, 10)
+ expect(reads(t)).toBe(2)
+ })
+
+ it('a slow pass does not refuse writes for an expired lease', async () => {
+ const t = setup()
+ let clock = 0
+ const host = t.open({ now: () => clock })
+ // The core holds a lease until its expiry: what it was last sent, and when.
+ const sent: Array<{ at: number; leases: Record<string, number> }> = []
+ vi.mocked(t.core.turns.leaseDeliveries).mockImplementation(async (_service, leases) => { sent.push({ at: clock, leases }); return true })
+ const first = 'team:service:superTabs:delivery'
+ t.push(announced)
+ await host.tick()
+ expect(t.core.turns.deliver).toHaveBeenCalledTimes(1)
+ // A second delivery arrives while the first is still being written; claiming it takes 3 s.
+ const original = vi.mocked(t.call).getMockImplementation()!
+ vi.mocked(t.call).mockImplementation(async (method, path, body) => {
+ if (method === 'GET' && path.endsWith('/deliveries')) {
+ return { status: 200, body: { success: true, data: [{ id: 'delivery', conversationId: 'lead', claimId: 'x', status: 'claimed' },
+ { id: 'second', conversationId: 'lead', claimId: null, status: 'queued' }] } }
+ }
+ if (method === 'POST' && path.endsWith('/deliveries/second')) {
+ clock += 3_000
+ return { status: 200, body: { success: true, data: { delivery: { id: 'second' }, message: { id: 'm2', conversationId: 'lead', text: 'Next.', author: { name: 'Collaborator' } } } } }
+ }
+ return original(method, path, body)
+ })
+ clock += 1_000
+ sent.length = 0
+ await host.tick()
+ // The first write's lease was renewed in this pass and reached the core while it still held.
+ expect(sent.some(({ at, leases }) => (leases[first] ?? 0) > at)).toBe(true)
+ })
+})
+
+// Spec 2026-11-02-poll-cost Part 3.4: each journal entry's receipt was asked every 5 s with no limit, and kept being asked
+// after a 403 or 404 (prod 2026-11-02: 318 receipt GETs a minute, a quarter of all requests).
+describe('receipt checks', () => {
+ const asked = (t: ReturnType<typeof setup>) => vi.mocked(t.call).mock.calls
+ .filter(([method, path]) => method === 'GET' && path.endsWith('/deliveries/delivery')).length
+ /** Held by the pane, then gone from its agent's list as the backend read it last; its receipt answers [answer]. */
+ async function unlisted(t: ReturnType<typeof setup>, host: SuperTabHost, answer: () => { status: number; body: Record<string, unknown> }) {
+ await host.tick(); t.event('rejected', 'team_waiting_busy')
+ const original = vi.mocked(t.call).getMockImplementation()!
+ vi.mocked(t.call).mockImplementation(async (method, path, body) => {
+ if (method === 'GET' && path.endsWith('/deliveries/delivery')) return answer()
+ if (method === 'GET' && path.endsWith('/deliveries')) return { status: 200, body: { success: true, data: [] } }
+ return original(method, path, body)
+ })
+ await host.tick()
+ }
+ const refused = (status: number, code: string) => () => ({ status, body: { success: false, error: { code, message: 'Refused.' } } })
+ const open = () => ({ status: 200, body: { success: true, data: { id: 'delivery', status: 'claimed' } } })
+ /** Each second for [seconds], the seconds at which the receipt was asked. */
+ async function askedAt(t: ReturnType<typeof setup>, host: SuperTabHost, seconds: number, from = 0) {
+ const at: number[] = []
+ for (let second = from; second <= seconds; second++) {
+ const before = asked(t)
+ await host.reconcileReceipts()
+ if (asked(t) > before) at.push(second)
+ t.wait(1_000)
+ }
+ return at
+ }
+
+ it('a failing entry backs off to 5 minutes', async () => {
+ const t = setup(), host = t.open()
+ await unlisted(t, host, refused(503, 'BACKEND_UNAVAILABLE'))
+ const at = await askedAt(t, host, 1_000)
+ expect(at.slice(1).map((second, i) => second - at[i]!)).toEqual([5, 10, 20, 40, 80, 160, 300, 300])
+ expect(t.saved().entries.delivery).toMatchObject({ checkFails: 9, nextCheckAt: expect.any(Number) })
+ })
+
+ it('404 and final codes retire, HOST_UNAVAILABLE does not', async () => {
+ for (const [status, code, retired] of [[404, 'NOT_FOUND', true], [403, 'FORBIDDEN', true], [409, 'DELIVERY_RESOLVED', true],
+ [400, 'BAD_REQUEST', true], [403, 'HOST_UNAVAILABLE', false], [401, 'UNAUTHORIZED', false]] as const) {
+ const t = setup(), host = t.open()
+ await unlisted(t, host, refused(status, code))
+ await host.reconcileReceipts()
+ expect(Object.keys(t.saved().entries), code).toEqual(retired ? [] : ['delivery'])
+ if (retired) expect(t.log).toHaveBeenCalledWith(expect.stringContaining(`Stopped checking delivery delivery of agent agent in Swarm tab: ${status}`))
+ }
+ })
+
+ it('an entry older than 25 h retires', async () => {
+ const t = setup(), host = t.open()
+ await unlisted(t, host, open)
+ t.wait(25 * 3_600_000 - 1_000)
+ await host.reconcileReceipts()
+ expect(Object.keys(t.saved().entries)).toEqual(['delivery'])
+ t.wait(1_000)
+ // Its next check, once due, retires it without asking: past the backend's longest hold, nothing can move it any more.
+ t.wait(5 * 60_000)
+ const before = asked(t)
+ await host.reconcileReceipts()
+ expect(asked(t)).toBe(before)
+ expect(t.saved().entries).toEqual({})
+ expect(t.log).toHaveBeenCalledWith(expect.stringContaining('Stopped checking delivery delivery of agent agent in Swarm tab: 25 h old'))
+ })
+
+ // Review focus 4: a daemon restarted with failing receipt entries on disk.
+ it('back-off resumes from the journal after a restart', async () => {
+ const t = setup(), first = t.open()
+ await unlisted(t, first, refused(503, 'BACKEND_UNAVAILABLE'))
+ expect(await askedAt(t, first, 15)).toEqual([0, 5, 15])
+ first.stop()
+ const restarted = t.open()
+ // Asked at 0, 5 and 15 s: the next is due at 35 s, and the new host waits for it rather than asking at once (its
+ // passes run every 5 s from its start at 16 s, so the first one due is at 36 s).
+ expect(await askedAt(t, restarted, 40, 16)).toEqual([36])
+ })
+
+ it('an entry the list shows is not asked about', async () => {
+ const t = setup(), host = t.open()
+ await host.tick(); t.event('rejected', 'team_waiting_busy')
+ for (let second = 0; second < 60; second++) { t.wait(1_000); await host.reconcileReceipts() }
+ expect(asked(t)).toBe(0)
+ t.idle()
+ await host.tick()
+ t.wait(5_000)
+ await host.reconcileReceipts()
+ expect(asked(t)).toBe(1)
+ })
+})
+
// WS roadmap Phase 2a: every host read its Swarm changes each second. A server that pushes (backend lib/swarmHostPushes.ts)
// tells it when a commit changed what it reads; the full read each minute stays as the safety net, and the read each
// second comes back whenever the server has not said it pushes for 5 minutes, or on a new host after a reconnect.
diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.ts
index d93ead9cf..14665e6c0 100644
--- a/cli/src/superTabs/host.ts
+++ b/cli/src/superTabs/host.ts
@@ -144,6 +144,12 @@ interface Entry {
claimId: string
stage: 'prepared' | 'submitting' | 'delivered' | 'uncertain'
receipt?: string
+ /** When this host made the entry: past RECEIPT_GIVE_UP_MS its receipt is no longer asked. One from a host before it counts
+ * from its load. */
+ createdAt?: number
+ /** Its receipt checks' back-off (RECEIPT_RETRY_MS), kept in the journal so a restart neither forgets nor bursts them. */
+ nextCheckAt?: number
+ checkFails?: number
}
/** `scrubs`: the Claude Code traces of ended Buddy sessions still to remove, by agent id, written before their close, so a host
* restarted between the close and the scrub still removes them (security re-check 2 of #2345). Older hosts drop it. */
@@ -320,6 +326,14 @@ const DELIVERY_FALLBACK_MS = 30_000
/** The server repeats that it pushes every 4 minutes on each socket: without it for this long (an older server, a rollback,
* this process started after the last one), every list is read each second again. */
const PUSH_LEASE_MS = 10 * 60_000
+/** Spec 2026-11-02-poll-cost Part 3: a delivery the core refused to write (a running turn, a draft, a dialog) was claimed again
+ * every second for as long as it was held, up to a day (prod 2026-11-02: 414 claim POSTs a minute). The claimed message is
+ * kept and written again on each tick; the claim is renewed only this often, well inside the backend's 10-minute claim quiet
+ * time (backend superTabs/deliverySettle.ts CLAIM_QUIET_MS), so the backend never ends a claim this host still holds. */
+const HELD_RECLAIM_MS = 120_000
+/** A held agent's list is read this often and on push, not each second: a cancel or an answer while it is held is pushed by
+ * the server (Part 3.2), and this read is the safety net for a lost push. */
+const HELD_LIST_MS = 30_000
const LEAD_RETRY_MS = 5_000
/** How long after a Product Manager's switch its host still closes a new session of it that starts late (leadSwitch.ts). */
const LATE_REPLACEMENT_MS = 30 * 60_000
@@ -335,6 +349,14 @@ const LATE_ACK_GIVE_UP_MS = 24 * 60 * 60_000
/** A refusal no later acknowledgement can change: the delivery is no longer this agent's, or another claim or receipt holds it.
* A sign-in (401), an update (426), throttling (429) and a server failure (5xx) say nothing of the delivery. */
const ackRefused = (error: unknown) => error instanceof SuperTabHostError && [400, 403, 404, 409].includes(error.status)
+/** Spec 2026-11-02-poll-cost Part 3.4: each entry's receipt was asked every 5 s for as long as it stayed, a refusal included.
+ * An entry not yet settled is asked again after 5 s, doubling to 5 minutes; it stops being asked on a refusal no later read
+ * can change (ackRefused's), or past the backend's longest hold (24 h) and an hour more. A host whose billing lapsed is
+ * refused as HOST_UNAVAILABLE (403) until billing returns: not final. */
+const RECEIPT_RETRY_MS = 5_000
+const RECEIPT_RETRY_MAX_MS = 5 * 60_000
+const RECEIPT_GIVE_UP_MS = 25 * 60 * 60_000
+const receiptRefused = (error: unknown) => ackRefused(error) && (error as SuperTabHostError).code !== 'HOST_UNAVAILABLE'
/** The first wait after a session the backend ended could not be closed or acknowledged, doubling up to ten minutes. */
const END_RETRY_MS = 5_000
const END_RETRY_MAX_MS = 10 * 60_000
@@ -451,8 +473,13 @@ export class SuperTabHost {
private readonly pushes = new Set<string>()
private pushAll = false
/** Per agent's list, when it was last read, what it held, and whether any of it is still in this host's hands: input in
- * flight needs a fresh read each second for its 2.5 s lease (accept), so only a list with nothing to do may wait. */
- private readonly lists = new Map<string, { readAt: number; ids: string[]; busy: boolean }>()
+ * flight needs a fresh read each second for its 2.5 s lease (accept), so only a list with nothing to do may wait. A list
+ * whose only open deliveries are held by the pane (`held`) waits too: those are written again from `claims` each tick. */
+ private readonly lists = new Map<string, { readAt: number; ids: string[]; busy: boolean; held: boolean }>()
+ /** Each delivery's last claim: the list row it came from, the backend's answer and when, and whether the core refused its
+ * write (`refused`). A refused one is written again from this, and claimed again only after HELD_RECLAIM_MS. Freed once the
+ * delivery leaves its list or the journal, and once a write is no longer refused. */
+ private readonly claims = new Map<string, { delivery: Json; result: Json; claimedAt: number; refused: boolean }>()
/** Each of this machine's thread sessions, by `tabId:agentId`: when it last did anything, since when its terminal is gone,
* and its end once asked of the backend. */
private readonly threadSessions = new Map<string, { activeAt: number; seenAt: number; missingSince?: number; ending?: 'idle' | 'stopped'
@@ -547,7 +574,8 @@ export class SuperTabHost {
this.now = options.now ?? Date.now
this.write = options.write ?? writeJournal
this.log = options.log ?? (message => console.warn(`[super-tabs] ${message}`))
- this.terminal = new TerminalHost(core, machineId, { now: this.now, log: this.log })
+ // Its pickups follow this host's delivery push lease: the server that pushes deliveries also says when a request waits.
+ this.terminal = new TerminalHost(core, machineId, { now: this.now, log: this.log, pushes: () => this.now() < this.pushUntil })
this.limitResume = new LimitResume(core, machineId, { now: this.now, log: this.log,
owns: async (tabId, assignmentId, harnessId) => (await this.sources.feed.fresh()).assignments
.some(a => a.tabId === tabId && a.assignmentId === assignmentId && a.harnessId === harnessId) })
@@ -567,6 +595,9 @@ export class SuperTabHost {
if (id !== e.deliveryId || ![e.tabId, e.agentId, e.harnessId, e.deliveryId, e.claimId].every(identifier)
|| !['prepared', 'submitting', 'delivered', 'uncertain'].includes(String(e.stage))) throw new Error('Invalid Super Tab delivery receipt.')
const entry = e as unknown as Entry
+ // Back-off a hand-edit or another release spoiled starts over; an entry from before it was dated counts from now.
+ for (const field of ['createdAt', 'nextCheckAt', 'checkFails'] as const) if (!Number.isFinite(entry[field])) delete entry[field]
+ entry.createdAt ??= this.now()
// The old process may have typed it, even when it never heard the core's receipt.
if (entry.stage === 'submitting') {
entry.stage = 'uncertain'
@@ -674,7 +705,8 @@ export class SuperTabHost {
})
}
/** The server said work waits for one agent here, or (naming none) that it pushes: read at once. Or that a commit changed
- * what this host reads (WS roadmap Phase 2a): a pass now if its feed reads now, else on the tick after its one-second gap. */
+ * what this host reads (WS roadmap Phase 2a): a pass now if its feed reads now, else on the tick after its one-second gap.
+ * Or that a Lead's terminal request waits for this machine: picked up now. */
private pushed(notice: BackendNotice): void {
if (this.stopped) return
if (notice.type === 'swarm_host_changed') {
@@ -683,6 +715,7 @@ export class SuperTabHost {
if (this.sources.feed.readsNow) void this.tick()
return
}
+ if (notice.type === '__terminal_waiting') { void this.terminal.waiting(); return }
if (notice.type !== 'super_tab_deliveries') return
this.pushUntil = this.now() + PUSH_LEASE_MS
if (identifier(notice.tabId) && identifier(notice.agentId)) this.pushes.add(`list:${notice.tabId}:${notice.agentId}`)
@@ -867,28 +900,53 @@ export class SuperTabHost {
}).finally(() => { this.receiptsRunning = null; this.nextReceiptsAt = this.now() + 5_000 })
}
private async checkReceipts(): Promise<void> {
+ const now = this.now()
+ // An entry its agent's last list still shows is open there: that read says more than a receipt would (Part 3.4).
+ const shown = new Set([...this.lists.values()].flatMap(list => list.ids))
// A held entry (the terminal was busy) is also checked: if the agent answered the message meanwhile, it is not typed.
- const pending = Object.values(this.journal.entries).filter(e => e.stage === 'uncertain' || e.stage === 'delivered'
- || (e.stage === 'prepared' && !this.active.has(typedId(e))))
- for (let i = 0; i < Math.min(pending.length, 20); i++) {
- if (this.stopped) return
- const entry = pending[(this.receiptCursor++) % pending.length]
- try {
- const result = object(await backend(this.core, 'GET', `/api/super-tabs/${entry.tabId}/agents/${entry.agentId}/deliveries/${entry.deliveryId}`))
+ const pending = Object.values(this.journal.entries).filter(e => (e.stage === 'uncertain' || e.stage === 'delivered'
+ || (e.stage === 'prepared' && !this.active.has(typedId(e)))) && !shown.has(e.deliveryId) && (e.nextCheckAt ?? 0) <= now)
+ let changed = false
+ const later = (entry: Entry, at?: number) => {
+ entry.checkFails = (entry.checkFails ?? 0) + 1
+ entry.nextCheckAt = at ?? this.now() + Math.min(RECEIPT_RETRY_MAX_MS, RECEIPT_RETRY_MS * 2 ** (entry.checkFails - 1))
+ changed = true
+ }
+ /** Retired, and said: each such retirement is a receipt this host will never acknowledge. */
+ const giveUp = (entry: Entry, why: string) => {
+ if (this.journal.entries[entry.deliveryId] !== entry || this.active.has(typedId(entry))) return
+ this.log(`Stopped checking delivery ${entry.deliveryId} of agent ${entry.agentId} in Swarm ${entry.tabId}: ${why}.`)
+ this.retireEntry(entry)
+ }
+ try {
+ for (let i = 0; i < Math.min(pending.length, 20); i++) {
if (this.stopped) return
- // Held input is retired by an answer, or once the backend ended it: it leaves the list, so the claim path never sees it
- // again. Kept, every hold the backend's delivery pass ends (backend superTabs/deliverySettle.ts) would stay here, and
- // at 1,000 entries this host accepts no more deliveries.
- const terminal = entry.stage === 'prepared' ? ['answered', 'cancelled'] : ['delivered', 'confirmed', 'superseded', 'cancelled', 'answered']
- if (result.id !== entry.deliveryId || !terminal.includes(String(result.status))) continue
- if (this.journal.entries[entry.deliveryId] !== entry || this.active.has(typedId(entry))) continue
- if (entry.stage === 'delivered' && result.status === 'cancelled') {
- const done = await this.ackLate(entry)
+ const entry = pending[(this.receiptCursor++) % pending.length]
+ if (now - (entry.createdAt ?? now) >= RECEIPT_GIVE_UP_MS) { giveUp(entry, '25 h old'); continue }
+ try {
+ const result = object(await backend(this.core, 'GET', `/api/super-tabs/${entry.tabId}/agents/${entry.agentId}/deliveries/${entry.deliveryId}`))
if (this.stopped) return
- if (!done) continue
+ // Held input is retired by an answer, or once the backend ended it: it leaves the list, so the claim path never sees it
+ // again. Kept, every hold the backend's delivery pass ends (backend superTabs/deliverySettle.ts) would stay here, and
+ // at 1,000 entries this host accepts no more deliveries.
+ const terminal = entry.stage === 'prepared' ? ['answered', 'cancelled'] : ['delivered', 'confirmed', 'superseded', 'cancelled', 'answered']
+ if (result.id !== entry.deliveryId || !terminal.includes(String(result.status))) { later(entry); continue }
+ if (this.journal.entries[entry.deliveryId] !== entry || this.active.has(typedId(entry))) continue
+ if (entry.stage === 'delivered' && result.status === 'cancelled') {
+ const done = await this.ackLate(entry)
+ if (this.stopped) return
+ // Asked again when its late acknowledgement is next due, which backs off on its own.
+ if (!done) { later(entry, this.lateAcks.get(entry.deliveryId)?.retryAt); continue }
+ }
+ this.retireEntry(entry)
+ } catch (error) {
+ // Missing authority or a network failure is not a receipt; a refusal no later read can change ends the checks.
+ if (receiptRefused(error)) giveUp(entry, `${(error as SuperTabHostError).status} ${(error as SuperTabHostError).code}`)
+ else later(entry)
}
- this.retireEntry(entry)
- } catch { /* Missing authority or a network failure is not a receipt. */ }
+ }
+ } finally {
+ if (changed && !this.stopped) this.persist()
}
}
/** Only while it is still this entry: a late acknowledgement's answer must not retire one that replaced it meanwhile. */
@@ -1033,22 +1091,31 @@ export class SuperTabHost {
const listKey = `list:${target.tabId}:${target.agent.id}`
if (this.backedOff(listKey)) continue
const last = this.lists.get(listKey)
- if (last && !pushAll && !last.busy && !pushes.has(listKey) && this.now() - last.readAt < DELIVERY_FALLBACK_MS) {
+ const due = !last || pushAll || last.busy || pushes.has(listKey) || this.now() - last.readAt >= (last.held ? HELD_LIST_MS : DELIVERY_FALLBACK_MS)
+ if (!due) {
// Unread this time, its deliveries are as the last read left them: none is taken as gone.
for (const id of last.ids) seen.add(id)
- continue
+ if (!last.ids.some(id => this.claims.get(id)?.refused)) continue
}
let listRead = false, claimError: unknown
try {
- const deliveries = await backend(this.core, 'GET', path)
- if (this.stopped) return
- if (!Array.isArray(deliveries)) throw new Error('Invalid Super Tab delivery list.')
- listRead = true
- listsRead.add(listKey)
- for (const item of deliveries) { const id = object(item).id; if (identifier(id)) listed.add(id) }
- const read = { readAt: this.now(), ids: deliveries.map(item => object(item).id).filter(identifier), busy: true }
- this.lists.set(listKey, read)
- this.deliveryRetries.delete(listKey)
+ let deliveries: unknown[]
+ if (due) {
+ const answer = await backend(this.core, 'GET', path)
+ if (this.stopped) return
+ if (!Array.isArray(answer)) throw new Error('Invalid Super Tab delivery list.')
+ deliveries = answer
+ listRead = true
+ listsRead.add(listKey)
+ for (const item of deliveries) { const id = object(item).id; if (identifier(id)) listed.add(id) }
+ this.lists.set(listKey, { readAt: this.now(), ids: deliveries.map(item => object(item).id).filter(identifier), busy: true, held: false })
+ this.deliveryRetries.delete(listKey)
+ } else {
+ // Only the held ones, in the list's order, from their kept claims: the pane may have freed since the last tick.
+ deliveries = last!.ids.flatMap(id => { const claim = this.claims.get(id); return claim?.refused ? [claim.delivery] : [] })
+ }
+ /** Acknowledged in this pass: gone from the backend's list, so they need no read next second (Part 3.3). */
+ const acked = new Set<string>()
// One waiting for its files holds the agent's later deliveries: they reach it after it, in order.
let held = false
for (const item of deliveries) {
@@ -1067,7 +1134,7 @@ export class SuperTabHost {
const entry = this.journal.entries[delivery.id]
if ((entry ? entry.stage === 'prepared' : !delivery.claimId) && !this.mayRead(target, delivery)) continue
try {
- await this.accept(target, delivery, path)
+ if (await this.accept(target, delivery, path)) acked.add(delivery.id)
const failed = this.deliveryRetries.get(claimKey)
this.deliveryRetries.delete(claimKey)
if (failed && failed.failures > 0) this.log(`Delivery ${delivery.id} went through after ${failed.failures + 1} tries, ${Math.round((this.now() - failed.since) / 60_000)} min.`)
@@ -1100,11 +1167,18 @@ export class SuperTabHost {
this.retire(delivery.id as string)
}
}
- read.busy = deliveries.some(item => !this.settled(object(item)))
+ // Taken after the pass's acknowledgements and writes: an acknowledged delivery and one the pane holds need no read next
+ // second, and the 30 s read below still catches a cancel whose push was lost.
+ const read = this.lists.get(listKey)
+ if (listRead && read) {
+ const refused = (item: Json) => identifier(item.id) && !!this.claims.get(item.id)?.refused
+ read.busy = deliveries.map(object).some(item => !this.settled(item) && !(identifier(item.id) && acked.has(item.id)) && !refused(item))
+ read.held = deliveries.map(object).some(refused)
+ }
} catch (error) {
// Authority checks and network failures both withhold input. A later fresh read may grant it again.
const message = error instanceof Error ? error.message : String(error)
- if (listRead) { if (error !== claimError) this.log(message) }
+ if (listRead || !due) { if (error !== claimError) this.log(message) }
else {
// 2026-10-28: a Lead's list failed for 45 minutes while this log said only the backend's words, with no agent.
const retry = this.retryLater(listKey), code = error instanceof SuperTabHostError ? ` (${error.code})` : ''
@@ -1132,6 +1206,8 @@ export class SuperTabHost {
if (!running.some(r => `list:${r.tabId}:${r.agent.id}` === agentKey)) this.deliveryRetries.delete(key)
else if (key.startsWith('claim:') && listsRead.has(agentKey) && !listed.has(key.slice('claim:'.length))) this.deliveryRetries.delete(key)
}
+ // A kept claim goes with its delivery: out of the journal, or no longer in a list (cancelled, answered, its agent gone).
+ for (const deliveryId of this.claims.keys()) if (!this.journal.entries[deliveryId] || !seen.has(deliveryId)) this.claims.delete(deliveryId)
for (const deliveryId of this.files.keys()) if (!this.journal.entries[deliveryId]) this.files.delete(deliveryId)
for (const deliveryId of [...this.downloads.keys()]) if (!this.journal.entries[deliveryId]) this.dropDownload(deliveryId)
for (const deliveryId of this.quotes.keys()) if (!this.journal.entries[deliveryId]) this.quotes.delete(deliveryId)
@@ -1242,9 +1318,11 @@ export class SuperTabHost {
if (now - state.seenAt >= BUDDY_SESSION_SLEEP_GAP_MS) state.activeAt = now
state.seenAt = now
// A delivery still in this host's hands is work, and so is a screen that changed. One settled (withheld, or waiting on a
- // person as uncertain) is not: it would keep the session from ever going idle (security review 1 of #2345).
+ // person as uncertain) is not: it would keep the session from ever going idle (security review 1 of #2345). One its pane
+ // holds still waits for it.
const list = this.lists.get(`list:${row.tabId}:${agent.id}`)
- if (list?.busy) state.activeAt = now
+ const waits = !!list && (list.busy || list.held)
+ if (waits) state.activeAt = now
const shown = this.terminal.progressOf([agent.harnessId])[agent.harnessId]
if (typeof shown === 'number' && shown > state.activeAt) state.activeAt = shown
const live = !!this.core.agents.byAgent(agent.harnessId) && this.core.agents.terminalAvailable(agent.harnessId)
@@ -1252,7 +1330,7 @@ export class SuperTabHost {
else state.missingSince ??= now
// Idle only on a list read this pass or lately with nothing unsettled: one never read says nothing of what waits.
const reason = !live ? (now - state.missingSince! >= BUDDY_SESSION_GONE_MS ? 'stopped' : null)
- : list && !list.busy && now - state.activeAt >= BUDDY_SESSION_IDLE_MS ? 'idle' : null
+ : list && !waits && now - state.activeAt >= BUDDY_SESSION_IDLE_MS ? 'idle' : null
// Judged again each pass: an end not yet taken is dropped once the session works again, so a retry never ends a session
// that has new work (security review 1 of #2345).
if (state.ended) continue
@@ -1687,7 +1765,9 @@ export class SuperTabHost {
return false
}
- private async accept(target: HostAgent, delivery: Json, path: string): Promise<void> {
+ /** Hands one delivery on: acknowledges a written one, renews the lease of one being written, or claims and writes it.
+ * Whether it acknowledged one, so its list need not be read again next second for it (Part 3.3). */
+ private async accept(target: HostAgent, delivery: Json, path: string): Promise<boolean> {
const deliveryId = delivery.id as string
let entry = this.journal.entries[deliveryId]
if (!entry) {
@@ -1697,7 +1777,7 @@ export class SuperTabHost {
// Retain its identity and expose the uncertainty for a human to resolve;
// this neither takes over its execution nor says whether it was written.
entry = { tabId: target.tabId, agentId: target.agent.id, harnessId: target.agent.harnessId,
- deliveryId, claimId: delivery.claimId as string || randomUUID(),
+ deliveryId, claimId: delivery.claimId as string || randomUUID(), createdAt: this.now(),
stage: delivery.claimId ? 'uncertain' : 'prepared',
...(delivery.claimId ? { receipt: delivery.status === 'uncertain' && typeof delivery.receipt === 'string' && delivery.receipt
? delivery.receipt
@@ -1726,20 +1806,27 @@ export class SuperTabHost {
this.persist()
}
if (entry.stage === 'delivered' || entry.stage === 'uncertain') {
- if (delivery.status === 'uncertain' && delivery.receipt === entry.receipt) return
+ if (delivery.status === 'uncertain' && delivery.receipt === entry.receipt) return false
await backend(this.core, 'POST', `${path}/${deliveryId}`, { type: 'ack', claimId: entry.claimId,
receipt: entry.receipt, uncertain: entry.stage === 'uncertain' })
if (entry.stage === 'delivered') { delete this.journal.entries[deliveryId]; this.persist() }
this.authorized.delete(id)
- return
+ return true
}
if (this.active.has(id)) {
+ // Sent to the core now, for this agent, not at the end of the pass: a pass slowed by another agent's reads or downloads
+ // let the core's lease lapse first, and the write was refused and claimed again.
this.authorized.set(id, this.now() + 2_500)
- return
+ await this.leases()
+ return false
}
- const result = object(await backend(this.core, 'POST', `${path}/${deliveryId}`, { type: 'claim', claimId: entry.claimId }))
+ // A write the pane refused is tried again with the claim it holds, and claimed again only every HELD_RECLAIM_MS.
+ const kept = this.claims.get(deliveryId)
+ const reuse = kept?.refused && this.now() - kept.claimedAt < HELD_RECLAIM_MS
+ const result = reuse ? kept.result : object(await backend(this.core, 'POST', `${path}/${deliveryId}`, { type: 'claim', claimId: entry.claimId }))
// The receipt check may have retired this held entry while the claim was in flight.
- if (this.stopped || this.journal.entries[deliveryId] !== entry) return
+ if (this.stopped || this.journal.entries[deliveryId] !== entry) return false
+ if (!reuse) this.claims.set(deliveryId, { delivery, result, claimedAt: this.now(), refused: kept?.refused ?? false })
const message = object(result.message)
if (typeof message.text !== 'string' || !identifier(message.conversationId)) throw new Error('The delivery has no message.')
// Downloaded before the lease: a large file must not use up the 2.5 s the core gives a write.
@@ -1796,11 +1883,11 @@ export class SuperTabHost {
context = await this.contextLines(entry, message, command, quotedOther)
this.contexts.set(deliveryId, context)
}
- if (this.stopped || this.journal.entries[deliveryId] !== entry) return
+ if (this.stopped || this.journal.entries[deliveryId] !== entry) return false
this.authorized.set(id, this.now() + 2_500)
- if (!(await this.leases()) || this.stopped) { this.authorized.delete(id); return }
- if (this.active.has(id)) return
- if (this.journal.entries[deliveryId] !== entry) { this.authorized.delete(id); return }
+ if (!(await this.leases()) || this.stopped) { this.authorized.delete(id); return false }
+ if (this.active.has(id)) return false
+ if (this.journal.entries[deliveryId] !== entry) { this.authorized.delete(id); return false }
// Listed before the Buddy can read the message, and only for a delivery still going ahead. A list it cannot write must
// not deliver files the Buddy cannot open: the delivery is tried again.
if (sent) {
@@ -1823,6 +1910,7 @@ export class SuperTabHost {
.filter(Boolean).join('\n\n')
this.core.turns.deliver(entry.harnessId, this.prompt(entry, message, attached, command, quote ?? '', result.buddyNews === true, context,
result.otherAccount === true), id)
+ return false
}
/** Takes out of a person's one Buddy's folder each project worktree whose project its person no longer reads, as the Swarm
@@ -2123,13 +2211,18 @@ export class SuperTabHost {
if (event.state === 'queued') return
this.active.delete(event.deliveryId)
this.authorized.delete(event.deliveryId)
+ const claim = this.claims.get(entry.deliveryId)
if (event.state === 'rejected' && event.reason?.startsWith('team_waiting_')) {
// The core explicitly withheld the terminal write (busy, human draft, or
// expired authority). A later fresh check may retry the same claim safely.
entry.stage = 'prepared'
delete entry.receipt
+ if (claim) claim.refused = true
this.reportWithheld(entry, event.reason)
} else {
+ this.claims.delete(entry.deliveryId)
+ // Written from a held claim, its list is read on the next tick for the acknowledgement, not 30 s on.
+ if (claim?.refused) this.pushes.add(`list:${entry.tabId}:${entry.agentId}`)
this.withheld.clear(entry.deliveryId)
entry.stage = event.state === 'delivered' || event.state === 'started' ? 'delivered' : 'uncertain'
entry.receipt = `${event.state}: ${event.reason ?? 'Native session input receipt'}`.slice(0, 2000)
diff --git a/cli/src/superTabs/terminal.spec.ts b/cli/src/superTabs/terminal.spec.ts
index f5ec7d601..eb4d75f8f 100644
--- a/cli/src/superTabs/terminal.spec.ts
+++ b/cli/src/superTabs/terminal.spec.ts
@@ -26,6 +26,7 @@ function setup(options: { live?: string[]; screen?: (harnessId: string) => Super
})
const host = new TerminalHost(core, 'm1', { now: () => clock, log: vi.fn() })
return { core, backend, sent, host,
+ now: () => clock,
wait: (ms: number) => { clock += ms },
request: (...rows: unknown[]) => { pending = rows },
showing: (next: (harnessId: string) => SuperTabScreen) => { screen = next },
@@ -134,6 +135,59 @@ describe('a host serving its Lead\'s terminal requests', () => {
})
})
+// Spec 2026-11-02-poll-cost Part 4.2: every host of a Swarm agent asked every 3 s, almost always for nothing (prod 2026-11-02:
+// 305 a minute, each a transaction). A server that pushes deliveries also says when a terminal request waits for this
+// machine (`__terminal_waiting`); the backend still gives up on a pickup after 10 s, so the fallback stays under it.
+describe('terminal requests the server pushes', () => {
+ it('with the push lease, polls every 8 s and picks up at once on __terminal_waiting', async () => {
+ let pushing = true
+ const t = setup(), host = new TerminalHost(t.core, 'm1', { now: t.now, log: vi.fn(), pushes: () => pushing })
+ await host.tick([row()])
+ expect(t.polls()).toBe(1)
+ for (let second = 1; second < 8; second++) { t.wait(1_000); await host.tick([row()]) }
+ expect(t.polls()).toBe(1)
+ t.wait(1_000); await host.tick([row()])
+ expect(t.polls()).toBe(2)
+ // Told a request waits: answered now, before the backend's 10 s are out.
+ t.request(screenRequest())
+ t.wait(1_000)
+ await host.waiting()
+ expect(t.polls()).toBe(3)
+ expect(t.sent.map(s => s.body.command.type)).toEqual(['agent.screenResult'])
+ // The next fallback poll counts from that pickup.
+ for (let second = 1; second < 8; second++) { t.wait(1_000); await host.tick([row()]) }
+ expect(t.polls()).toBe(3)
+ t.wait(1_000); await host.tick([row()])
+ expect(t.polls()).toBe(4)
+ // The lease lapses: every 3 s again.
+ pushing = false
+ t.wait(3_000); await host.tick([row()])
+ expect(t.polls()).toBe(5)
+ })
+
+ it('without it, polls every 3 s', async () => {
+ const t = setup(), host = new TerminalHost(t.core, 'm1', { now: t.now, log: vi.fn(), pushes: () => false })
+ for (let second = 0; second < 9; second++) { await host.tick([row()]); t.wait(1_000) }
+ expect(t.polls()).toBe(3)
+ })
+
+ it('picks up nothing on a push before the host has read its roster, or with no Swarm agent here', async () => {
+ const t = setup(), host = new TerminalHost(t.core, 'm1', { now: t.now, log: vi.fn(), pushes: () => true })
+ await host.waiting()
+ await host.tick([])
+ await host.waiting()
+ expect(t.polls()).toBe(0)
+ })
+
+ it('picks up once more after a push that came during a pickup', async () => {
+ const t = setup(), host = new TerminalHost(t.core, 'm1', { now: t.now, log: vi.fn(), pushes: () => true })
+ const first = host.tick([row()])
+ const pushed = host.waiting()
+ await first; await pushed
+ await vi.waitFor(() => expect(t.polls()).toBe(2))
+ })
+})
+
describe('the stuck and usage-limit alerts', () => {
const prompt = (): SuperTabScreen => ({ ok: true, text: 'Do you want to proceed?\n❯ 1. Yes\n 2. No', hold: 'permission_open' })
const idle = (): SuperTabScreen => ({ ok: true, text: '> ', hold: null })
diff --git a/cli/src/superTabs/terminal.ts b/cli/src/superTabs/terminal.ts
index 31e3b34e7..d1a9ca56f 100644
--- a/cli/src/superTabs/terminal.ts
+++ b/cli/src/superTabs/terminal.ts
@@ -19,7 +19,11 @@ type Json = Record<string, unknown>
interface Own { tabId: string; agentId: string; harnessId: string }
/** Every host of every Swarm asks, so not every second (Lead, 2026-10-23); the backend gives up on a pickup after 10 s. */
-const SERVE_EVERY_MS = 3_000
+export const SERVE_EVERY_MS = 3_000
+/** While the server pushes deliveries (the host's push lease), it also says when a request waits for this machine
+ * (`__terminal_waiting`, spec 2026-11-02-poll-cost Part 4.2): this poll is then only the net for a lost push, still inside the
+ * backend's 10 s. Prod 2026-11-02: 305 empty pickups a minute, each a transaction. */
+export const SERVE_PUSHED_EVERY_MS = 8_000
/** A screen read per agent; the 3-minute prompt wait does not need it finer. */
const WATCH_EVERY_MS = 15_000
const PROMPT_WAIT_MS = 3 * 60_000
@@ -138,32 +142,39 @@ type Episode = { since: number; alerted: boolean } | null
interface Watched { prompt: Episode; limit: Episode; model: Episode; retried?: number; skips?: number }
export class TerminalHost {
- private nextServeAt = 0
+ /** When the last pickup started: the next is due after the interval the push lease allows now, so a lapsed lease is
+ * back to every 3 s at once. */
+ private servedAt = -Infinity
private nextWatchAt = 0
private serving: Promise<void> | null = null
+ /** A push heard during a pickup: one more runs after it, since that one may have read before the request was written. */
+ private servingAgain = false
+ /** This machine's agents as the last roster named them: what a pickup a push starts answers for. */
+ private here: Array<Own & { running: boolean }> = []
private watching: Promise<void> | null = null
private readonly watched = new Map<string, Watched>()
/** Per running harness here, its last screen's digest and when that last changed. */
private readonly progress = new Map<string, { digest: string; at: number }>()
private readonly now: () => number
private readonly log: (message: string) => void
+ /** Whether the server is known to push now (the host's delivery push lease). */
+ private readonly pushes: () => boolean
- constructor(private readonly core: CoreApi, private readonly machineId: string, options: { now?: () => number; log?: (message: string) => void } = {}) {
+ constructor(private readonly core: CoreApi, private readonly machineId: string,
+ options: { now?: () => number; log?: (message: string) => void; pushes?: () => boolean } = {}) {
this.now = options.now ?? Date.now
this.log = options.log ?? (message => console.warn(`[super-tabs] ${message}`))
+ this.pushes = options.pushes ?? (() => false)
}
/** Each host roster read. Serving and watching run on their own cadence, and the returned promise is only for specs:
* the host never waits on it, so a slow screen read never delays deliveries. */
tick(rows: unknown[]): Promise<void> {
- const here = this.here(rows)
+ const here = this.here = this.agentsHere(rows)
if (!here.length) { this.watched.clear(); this.progress.clear(); return Promise.resolve() }
const own = here.filter(agent => agent.running)
const now = this.now()
- if (!this.serving && now >= this.nextServeAt) {
- this.nextServeAt = now + SERVE_EVERY_MS
- this.serving = this.serve(here).catch(error => this.log(error instanceof Error ? error.message : String(error))).finally(() => { this.serving = null })
- }
+ if (!this.serving && now - this.servedAt >= (this.pushes() ? SERVE_PUSHED_EVERY_MS : SERVE_EVERY_MS)) this.startServing()
if (!this.watching && now >= this.nextWatchAt) {
this.nextWatchAt = now + WATCH_EVERY_MS
this.watching = this.watch(own).catch(error => this.log(error instanceof Error ? error.message : String(error))).finally(() => { this.watching = null })
@@ -171,6 +182,23 @@ export class TerminalHost {
return Promise.all([this.serving, this.watching]).then(() => {})
}
+ /** The server says a terminal request waits for this machine: picked up now, not at the next poll. The promise is only
+ * for specs. Nothing before the first roster names an agent here, as the poll does. */
+ waiting(): Promise<void> {
+ if (!this.here.length) return Promise.resolve()
+ if (this.serving) { this.servingAgain = true; return this.serving }
+ return this.startServing()
+ }
+
+ private startServing(): Promise<void> {
+ this.servedAt = this.now()
+ const serving = this.serve(this.here).catch(error => this.log(error instanceof Error ? error.message : String(error))).finally(() => {
+ this.serving = null
+ if (this.servingAgain) { this.servingAgain = false; void this.waiting() }
+ })
+ return this.serving = serving
+ }
+
/** When each of these harnesses' screens last changed, epoch ms, for those running here that the watch has read. An
* agent's first read counts as a change: the host cannot know what its screen showed before. */
progressOf(harnessIds: readonly string[]): Record<string, number> {
@@ -182,7 +210,7 @@ export class TerminalHost {
/** This machine's Swarm agents, as the roster names them, and whether each runs here: a stopping one, or one whose
* session is gone, is no longer anyone's to drive, but its requests are still this host's to answer. */
- private here(rows: unknown[]): Array<Own & { running: boolean }> {
+ private agentsHere(rows: unknown[]): Array<Own & { running: boolean }> {
return rows.map(object).flatMap(row => {
const agent = object(row.agent)
return identifier(row.tabId) && identifier(agent.id) && identifier(agent.harnessId) && agent.machineId === this.machineId
diff --git a/cli/src/team/windowsBoundary.spec.ts b/cli/src/team/windowsBoundary.spec.ts
index e05060809..b62bae854 100644
--- a/cli/src/team/windowsBoundary.spec.ts
+++ b/cli/src/team/windowsBoundary.spec.ts
@@ -7,6 +7,8 @@
* account reads the code or the relay's token.
* - The owner's local credential over TCP on Windows (finding W1, fixed): no client puts it on a TCP request, and the daemon
* counts it from no other account.
+ * - The connectors bridge's port on Windows (task #2162, from Reed's review of W1): another account holding it is told apart
+ * from this account's own listener, so the bridge moves off it.
*/
import { mkdtempSync } from 'node:fs'
import type { Socket } from 'node:net'
@@ -15,7 +17,7 @@ import { join } from 'node:path'
import { describe, expect, it } from 'vitest'
import { loadOrCreateHookCredential } from '../lib/hookAuth.js'
import { localCredentialHeaders } from '../lib/localCredential.js'
-import { peerIsThisAccount } from '../lib/peerAccount.js'
+import { peerIsThisAccount, portHolderIsThisAccount } from '../lib/peerAccount.js'
import { buildWindowsSetupScript, type WindowsSetupScriptInput } from './windowsScript.js'
const OWNER_HOME = 'C:\\Users\\owner-placeholder'
@@ -136,3 +138,12 @@ describe('W1: the owner\'s local credential never goes over TCP on Windows', ()
await expect(peerIsThisAccount(stranger, 'win32', async () => ({ status: 0, stdout: 'no\r\n' }))).resolves.toBe(false)
})
})
+
+describe('the connectors bridge\'s port on Windows (task #2162)', () => {
+ // Windows answered null, so the bridge never moved: the Team account, holding 51793 from boot, kept hearing the owner's
+ // agents' tool calls and could answer them falsely. Now Windows is asked whose the listener is.
+ it('another account holding the bridge\'s port is told apart from this account\'s own, so the bridge moves off it', async () => {
+ await expect(portHolderIsThisAccount(51793, 'win32', async () => ({ status: 0, stdout: 'no\r\n' }))).resolves.toBe(false)
+ await expect(portHolderIsThisAccount(51793, 'win32', async () => ({ status: 0, stdout: 'yes\r\n' }))).resolves.toBe(true)
+ })
+})
diff --git a/desktop/lib/super_tabs/controller.dart b/desktop/lib/super_tabs/controller.dart
index 7413f76e0..664d6e65e 100644
--- a/desktop/lib/super_tabs/controller.dart
+++ b/desktop/lib/super_tabs/controller.dart
@@ -563,31 +563,129 @@ class SuperTabController extends ChangeNotifier {
}
/// Whether this poll reads. Always, unless the server pushes: then only when
- /// told and the old poll would have read by now, when the safety net is
- /// due, or while the person's own message in the open conversation waits
- /// for its receipt, which no push names.
+ /// told and the old poll would have read by now, or when the safety net is
+ /// due. A receipt, which no push names, is read on its own
+ /// ([_checkReceipt]).
bool get _pollDue {
- if (!_pushing || _receiptOpen(selectedId)) return true;
+ if (!_pushing) return true;
if ((_toldMain || _toldMachine) && _gapPassed) return true;
final last = _lastFullRead;
return last == null || clock.now().difference(last) >= kSwarmPushSafetyNet;
}
- /// The person's latest message in [id] still has a delivery in hand.
- bool _receiptOpen(String id) {
+ /// How often the person's newest message in the open conversation is read
+ /// again while its delivery is open, and for how long (the phone's, mobile
+ /// swarm_conversation.dart): a receipt moves on the delivery's own record,
+ /// which neither a push nor the conversation's counters name. One row
+ /// every 30 s, not the page every poll (spec 2026-11-02-poll-cost, Part 2).
+ static const _receiptReadEvery = Duration(seconds: 30);
+ static const _receiptReadFor = Duration(minutes: 10);
+
+ /// How long a claimed or unconfirmed delivery is read again: as long as the
+ /// backend lets it stand, an hour (`deliverySettle.ts` `HOLD_LIMIT_MS`,
+ /// `UNCERTAIN_LIMIT_MS`).
+ static const _heldReadFor = Duration(minutes: 60);
+
+ /// The deliveries read again: queued, taken by its computer (it may come
+ /// back unconfirmed), or unconfirmed until a person settles it. Past them
+ /// the receipt changes with an answer, which is a new message.
+ static const _openDeliveries = {'queued', 'claimed', 'uncertain'};
+
+ /// The own message whose receipt is followed, since when, and when it was
+ /// last read.
+ String? _receiptOf;
+ DateTime? _receiptSince, _receiptAsked;
+
+ /// The person's newest message in [id], written by them and not by an
+ /// agent or a terminal: the only one that can carry a delivery line.
+ SuperTabMessage? _latestOwn(String id) {
SuperTabMessage? own;
for (final m in _messages[id] ?? const <SuperTabMessage>[]) {
if (m.fromAgent || m.fromTerminal || m.authorId != accountId) continue;
if (own == null || m.sequence > own.sequence) own = m;
}
- return own != null &&
- own.deliveries.any(
- (d) => !const {
- 'answered',
- 'cancelled',
- 'superseded',
- }.contains(d['status']),
+ return own;
+ }
+
+ /// [messageId]'s row was just read: its receipt is as new as can be.
+ void _receiptRead(String messageId) {
+ final now = clock.now();
+ if (_receiptOf != messageId) {
+ _receiptOf = messageId;
+ _receiptSince = now;
+ }
+ _receiptAsked = now;
+ }
+
+ /// The person's latest message in [id] waits for its delivery
+ /// ([_openDeliveries]), and has not waited past its bound since this
+ /// device saw it waiting.
+ bool _receiptOpen(String id) {
+ final own = _latestOwn(id);
+ final status = own?.receiptDelivery?.status;
+ if (own == null || !_openDeliveries.contains(status)) return false;
+ final now = clock.now();
+ if (_receiptOf != own.id) {
+ _receiptOf = own.id;
+ _receiptSince = now;
+ _receiptAsked = null;
+ }
+ final bound = status == 'queued' ? _receiptReadFor : _heldReadFor;
+ return now.difference(_receiptSince!) < bound;
+ }
+
+ /// At each poll: reads the open conversation's [_receiptOpen] message again,
+ /// one row, at most every [_receiptReadEvery]. Not while away, where nobody
+ /// sees it, nor beside a read of the conversation, which brings it.
+ void _checkReceipt() {
+ final id = selectedId;
+ if (_disposed || accessRevoked || updateRequired || _away) return;
+ if (_reading.containsKey((id, false)) || !_receiptOpen(id)) return;
+ final asked = _receiptAsked;
+ if (asked != null && clock.now().difference(asked) < _receiptReadEvery) {
+ return;
+ }
+ unawaited(_readReceipt(id, _latestOwn(id)!));
+ }
+
+ /// Replaces [shown]'s row in [id] with the one read now. Dropped when
+ /// another read replaced the row meanwhile: its answer is as new.
+ Future<void> _readReceipt(String id, SuperTabMessage shown) async {
+ final messageId = shown.id;
+ _receiptRead(messageId);
+ bool stale() =>
+ _disposed ||
+ accessRevoked ||
+ snapshot?.conversation(id) == null ||
+ !(_messages[id]?.any((m) => identical(m, shown)) ?? false);
+ try {
+ final answer = await request(
+ 'GET',
+ '${_messagesPath(id)}?messageId=${Uri.encodeComponent(messageId)}',
+ );
+ if (stale()) return;
+ final rows = (answer['messages'] as List)
+ .map((m) => SuperTabMessage.fromJson(superTabMap(m)))
+ .toList();
+ if (rows.length > 1 ||
+ rows.any((m) => m.id != messageId || m.conversationId != id)) {
+ throw const FormatException(
+ 'A different message receipt was returned.',
);
+ }
+ if (rows.isEmpty || _sameMessages([shown], rows)) return;
+ _messages[id] = [
+ for (final m in _messages[id]!) identical(m, shown) ? rows.single : m,
+ ];
+ _keepRows(id, answer['messages'] as List);
+ if (id == selectedId) _viewVersion++;
+ _changed();
+ } catch (failure) {
+ if (stale()) return;
+ // Said as a messages read says it; the next check tries again.
+ if (!_inConnectGrace(failure)) _readFailure(failure, revokeTab: false);
+ _changed();
+ }
}
/// When the parts held were last read: how old a [savedView] of them is.
@@ -2043,6 +2141,8 @@ class SuperTabController extends ChangeNotifier {
throw const FormatException('A different conversation was returned.');
}
_heldGeneration[id] = (_heldGeneration[id] ?? 0) + 1;
+ // Read up to the page's end, not past it: the polls join the next pages.
+ _readMessageSeq.remove(id);
_rows.remove(id);
_keepRows(id, rows);
_messages[id] = page;
@@ -2158,6 +2258,7 @@ class SuperTabController extends ChangeNotifier {
if (!_policy.adapts) {
_poll = Timer.periodic(_every, (_) {
if (_pollDue) unawaited(refresh());
+ _checkReceipt();
});
return;
}
@@ -2180,6 +2281,7 @@ class SuperTabController extends ChangeNotifier {
? refresh()
: _readMessages(selectedId, light: true));
}
+ _checkReceipt();
_schedule(_every - clock.now().difference(began));
}
@@ -2215,6 +2317,7 @@ class SuperTabController extends ChangeNotifier {
_quoted.remove(id);
_quoting.remove(id);
_reactionSeq.remove(id);
+ _readMessageSeq.remove(id);
_forgetNewer(id);
return true;
});
@@ -3372,20 +3475,16 @@ class SuperTabController extends ChangeNotifier {
_lastFullRead = clock.now();
// Taken as the read starts: a push heard while it is out reads once more,
// on the next allowed read, unless it repeats a time already told.
- // A machine's report says nothing of any conversation: no messages for it.
- final told = _toldMain;
_toldMain = _toldMachine = false;
final took = Stopwatch()..start();
- // The open conversation's messages, asked for beside the state
+ // A first open's conversation, asked for beside the state
// ([SuperTabReading.messagesWithState]); dropped if the state moves the
- // selection elsewhere.
+ // selection elsewhere. After it, the messages wait for the state to say
+ // the conversation's own counters moved (spec 2026-11-02-poll-cost, Part
+ // 2): asked for beside every push, they were read on any change in the
+ // Swarm, a machine's reading included.
final earlyId = selectedId;
- // Only when something may have happened: a first read, a saved view, a
- // push, a message waiting for its receipt. Otherwise the messages wait
- // for the state to say there is news (roadmap 2.5).
- final earlyQuery = told || !_messagesCurrent(earlyId)
- ? _earlyQuery(earlyId)
- : null;
+ final earlyQuery = stateReads == 0 ? _earlyQuery(earlyId) : null;
final early = earlyQuery == null
? null
: (request('GET', '${_messagesPath(earlyId)}$earlyQuery')..ignore());
@@ -3519,14 +3618,11 @@ class SuperTabController extends ChangeNotifier {
if (stateReads == 1) _changed();
_watchMachineSilence();
final sidebarMs = took.elapsedMilliseconds;
- final changedAtBefore = lastChangedAt;
lastChangedAt = parts.lastChangedAt;
// A machine's report moves the newest change, and no conversation or
- // anything else that is shown.
+ // anything else that is shown (the open conversation's messages follow
+ // its own counters, [_messagesCurrent]).
if (machinesOnly) {
- _messagesAt.updateAll(
- (_, at) => at == changedAtBefore ? lastChangedAt : at,
- );
before = (
lastChangedAt: lastChangedAt,
error: before.error,
@@ -3541,12 +3637,10 @@ class SuperTabController extends ChangeNotifier {
_readUnreadBuddyChats();
_partsReadAt = clock.now();
error = null;
- // A state that moved nothing, over messages read at that very state,
- // has no news for the conversation: no read of it (roadmap 2.5).
- if (early != null ||
- !_messagesCurrent(selectedId) ||
- read.full ||
- (read.changed && !machinesOnly)) {
+ // Counters that did not move have no news for the conversation,
+ // whatever else changed: no read of it (spec 2026-11-02-poll-cost,
+ // Part 2). Its task's steps keep their own counters.
+ if (early != null || !_messagesCurrent(selectedId)) {
await (selectedId == earlyId && messagesRead != null
? messagesRead
: _readMessages(
@@ -3555,6 +3649,8 @@ class SuperTabController extends ChangeNotifier {
? (query: earlyQuery!, page: early)
: null,
));
+ } else {
+ _readSteps(selectedId, light: false);
}
if (stateReads == 1) {
// Where a first open's time went, from the tab asking to the chat it shows.
@@ -3920,21 +4016,37 @@ class SuperTabController extends ChangeNotifier {
return tail != null ? '?after=$tail' : '';
}
- /// The state's last change when [id]'s newest messages were read: while the
- /// state has not moved past it, nothing new can be in the conversation.
- final _messagesAt = <String, int>{};
-
- /// [id]'s messages are as new as the state held, and nothing outside the
- /// state is waited for: no receipt, no saved page, no newer page asked for.
- bool _messagesCurrent(String id) =>
- _policy.messagesWhenChanged &&
- !_showingSaved &&
- snapshot != null &&
- _messages[id] != null &&
- _messagesAt[id] == lastChangedAt &&
- !_holding(id) &&
- !_latestWanted.contains(id) &&
- !_receiptOpen(id);
+ /// How far [id]'s messages were read: the conversation's
+ /// `lastMessageSequence` as the state said it when the read was asked, or
+ /// the newest row it brought if that is later. A message the reader may
+ /// not see moves the counter too; remembered, it costs one empty read, not
+ /// one a poll.
+ final _readMessageSeq = <String, int>{};
+
+ /// What [id]'s messages were read up to: [_readMessageSeq], else the newest
+ /// held.
+ int _readUpTo(String id) =>
+ _readMessageSeq[id] ?? _messages[id]?.lastOrNull?.sequence ?? 0;
+
+ /// [id]'s messages are as new as its own counters say (spec
+ /// 2026-11-02-poll-cost, Part 2): no message after those read, no reaction
+ /// changed since its page, no saved page, no newer page asked for. A reader
+ /// scrolled up holding the pages below waits for [showLatest]: only a
+ /// reaction reads their rows again. `lastMessageSequence` rather than the
+ /// main stream's, because a read of what came after brings thread replies
+ /// too.
+ bool _messagesCurrent(String id) {
+ final group = snapshot?.conversation(id);
+ if (!_policy.messagesWhenChanged ||
+ _showingSaved ||
+ group == null ||
+ _messages[id] == null ||
+ _latestWanted.contains(id) ||
+ group.reactionSeq != (_reactionSeq[id] ?? 0)) {
+ return false;
+ }
+ return _holding(id) || group.lastMessageSequence <= _readUpTo(id);
+ }
/// The query of [id]'s messages read to start beside a state read, or null.
/// On first open only for the conversation the saved state named; after
@@ -3996,8 +4108,9 @@ class SuperTabController extends ChangeNotifier {
return _readMessages(id, older: older);
}
- /// [light] asks only for new messages (and the person's own unsettled
- /// receipt), not the page again; [early] is a read already asked for.
+ /// [light] asks only for new messages, and nothing under a reader holding
+ /// the pages below, whose rows a full read asks for again; [early] is a
+ /// read already asked for.
Future<void> _readMessages(
String id, {
bool older = false,
@@ -4024,10 +4137,13 @@ class SuperTabController extends ChangeNotifier {
final task = state?.conversation(id);
if (state == null || task == null) return;
for (final step in superTabStepsOf(state, task)) {
- // Read again only when the Swarm says the step moved past the rows held
- // (final review, minor 8: every poll read every step).
- final held = _messages[step.id]?.lastOrNull?.sequence;
- if (held != null && step.lastMessageSequence <= held) continue;
+ // Read again only when the Swarm says the step moved past what was read
+ // (final review, minor 8: every poll read every step); a step with no
+ // message yet is read once.
+ if (_messages[step.id] != null &&
+ step.lastMessageSequence <= _readUpTo(step.id)) {
+ continue;
+ }
unawaited(_readMessages(step.id, light: light));
}
}
@@ -4045,8 +4161,9 @@ class SuperTabController extends ChangeNotifier {
// A light check asks only for new messages, which wait while holding.
if (light && _holding(id)) return;
final generation = _heldGeneration[id];
- // What the Swarm's state had said when this read was asked for.
- final stateAt = lastChangedAt;
+ // How far the Swarm's state said the conversation went when this read
+ // was asked for.
+ final askedUpTo = snapshot!.conversation(id)!.lastMessageSequence;
// What [id] held was replaced while newer messages were on their way.
bool replaced() => !older && _heldGeneration[id] != generation;
try {
@@ -4097,12 +4214,12 @@ class SuperTabController extends ChangeNotifier {
'messages': [...shown, ...answer['messages'] as List],
};
} else if (!_disposed &&
- !older &&
- (!light || reacted) &&
+ reacted &&
tail != null &&
(answer['messages'] as List).isEmpty) {
- // No new text: refresh delivery receipts in the page already shown,
- // and on a light read the counts of a reaction that changed there.
+ // No new text, but a reaction changed in the page shown: its counts
+ // are read again. Never for receipts alone (spec 2026-11-02-poll-cost,
+ // Part 2): the person's own one is read by itself ([_checkReceipt]).
answer = await request(
'GET',
'$_path/conversations/${Uri.encodeComponent(id)}/messages?before=${tail + 1}',
@@ -4160,6 +4277,7 @@ class SuperTabController extends ChangeNotifier {
(latest, m) =>
latest == null || m.sequence > latest.sequence ? m : latest,
);
+ final ownRead = own != null && incoming.any((m) => m.id == own.id);
if (!older &&
own != null &&
own.deliveries.isNotEmpty &&
@@ -4170,9 +4288,12 @@ class SuperTabController extends ChangeNotifier {
'superseded',
}.contains(d['status']),
) &&
- !incoming.any((m) => m.id == own.id)) {
+ incoming.isNotEmpty &&
+ !ownRead) {
// New replies (or a long stream of agent updates) otherwise leave the
// original row outside this page and its inline receipt stuck at Sent.
+ // Only when something came: one may answer it; with nothing new its
+ // receipt is read by itself, if at all ([_checkReceipt]).
final receipt = await request(
'GET',
'$_path/conversations/${Uri.encodeComponent(id)}/messages?messageId=${Uri.encodeComponent(own.id)}',
@@ -4196,6 +4317,9 @@ class SuperTabController extends ChangeNotifier {
combined[row.id] = row;
}
_keepRows(id, receipt['messages'] as List);
+ if (id == selectedId) _receiptRead(own.id);
+ } else if (ownRead && id == selectedId) {
+ _receiptRead(own.id);
}
// An older page read meanwhile (during the receipt read above) stays:
// what is held now, under what this read brought.
@@ -4235,7 +4359,16 @@ class SuperTabController extends ChangeNotifier {
}
_dropShownSends(id);
if (reactionSeq is int) _reactionSeq[id] = reactionSeq;
- if (!older && !holding) _messagesAt[id] = stateAt;
+ // A page joined below a reader scrolled up leaves the rest to read.
+ if (!older && !holding) {
+ final newest = next.lastOrNull?.sequence ?? 0;
+ // An early page went out before the state this read joins: a
+ // message committed in between moved the state's counter but is not
+ // on the page, so the page vouches only for what it holds.
+ _readMessageSeq[id] = keepPlace || first != null
+ ? newest
+ : max(askedUpTo, newest);
+ }
if (older || replacing || !_before.containsKey(id)) {
_before[id] = SuperTabPage.read(answer['next']);
}
diff --git a/desktop/lib/super_tabs/model.dart b/desktop/lib/super_tabs/model.dart
index 55559d87b..ad74384f3 100644
--- a/desktop/lib/super_tabs/model.dart
+++ b/desktop/lib/super_tabs/model.dart
@@ -348,6 +348,7 @@ class SuperTabConversation {
: null,
lastMessageSequence = (row['lastMessageSequence'] as num?)?.toInt() ?? 0,
lastMainSequence = (row['lastMainSequence'] as num?)?.toInt(),
+ reactionSeq = (row['reactionSeq'] as num?)?.toInt() ?? 0,
assignment = row['assignment'] == null
? null
: Map.unmodifiable(superTabMap(row['assignment'])),
@@ -422,6 +423,11 @@ class SuperTabConversation {
/// conversation's first message since.
final int? lastMainSequence;
+ /// Counts reaction changes here (backend reactions.ts), as its messages
+ /// pages also say: a move asks for the page shown again. Absent, as before
+ /// the first reaction, it is 0, the pages' own value then.
+ final int reactionSeq;
+
/// The person who asked for this task; null on a conversation that is no
/// task, and from a server that does not say.
final String? requesterId;
diff --git a/desktop/lib/super_tabs/reading.dart b/desktop/lib/super_tabs/reading.dart
index f6c54a753..256b9c016 100644
--- a/desktop/lib/super_tabs/reading.dart
+++ b/desktop/lib/super_tabs/reading.dart
@@ -54,10 +54,11 @@ class SuperTabReading {
/// from the Swarms it is not showing.
final Duration? awayPoll;
- /// True reads the open conversation's messages only when something may
- /// have happened: a first read, a push, a state that moved since they were
- /// read, a message waiting for its receipt. A poll whose state read finds
- /// nothing new then asks for the state alone.
+ /// True reads the open conversation's messages only when its own counters
+ /// say something happened there: a first read, a saved view, a message
+ /// after those read, a changed reaction (spec 2026-11-02-poll-cost, Part
+ /// 2). A poll whose state read moves neither then asks for the state alone,
+ /// whatever else in the Swarm changed.
final bool messagesWhenChanged;
/// True reads at once when a machine able to serve Swarm reads connects,
@@ -86,7 +87,8 @@ class SuperTabReading {
];
/// True starts the saved conversation's messages read beside the first
- /// state read, instead of after it.
+ /// state read, instead of after it. Only the first: later reads wait for
+ /// the state to say the conversation moved ([messagesWhenChanged]).
final bool messagesWithState;
/// True keeps the last view of each Swarm as read on this device and draws
diff --git a/desktop/test/super_tab_chat_scroll_test.dart b/desktop/test/super_tab_chat_scroll_test.dart
index 838c3903f..b197efe81 100644
--- a/desktop/test/super_tab_chat_scroll_test.dart
+++ b/desktop/test/super_tab_chat_scroll_test.dart
@@ -58,6 +58,14 @@ void main() {
void fromAgent(ConversationServer server) => server.messages.last['author'] =
{'kind': 'agent', 'id': 'lead-agent', 'name': 'Lead'};
+ /// A reaction changes somewhere in the conversation: the next read takes
+ /// the page shown again, with every receipt in it as it is now. A receipt
+ /// alone is no reason to (spec 2026-11-02-poll-cost, Part 2).
+ void reacted(ConversationServer server) {
+ final group = (server.state['conversations'] as List).first as Map;
+ group['reactionSeq'] = ((group['reactionSeq'] as int?) ?? 0) + 1;
+ }
+
void agentUpdates(ConversationServer server, int count) {
for (var i = 0; i < count; i++) {
server.append(
@@ -131,6 +139,7 @@ void main() {
server.messages.first['deliveries'] = [
{'id': 'delivery-1', 'agentId': 'lead-agent', 'status': 'uncertain'},
];
+ reacted(server);
await c.refresh();
await tester.pumpAndSettle();
@@ -161,6 +170,7 @@ void main() {
server.messages.last['deliveries'] = [
{'id': 'delivery-1', 'agentId': 'lead-agent', 'status': 'uncertain'},
];
+ reacted(server);
await c.refresh();
await tester.pumpAndSettle();
expect(find.text("Couldn't confirm delivery"), findsOneWidget);
@@ -427,9 +437,10 @@ void main() {
'moves and regroups no row', (tester) async {
final server = ConversationServer();
agentUpdates(server, 30);
- // Desktop's: the messages read lands beside the state read, before the
- // view hears of either.
- final c = await show(tester, server, reading: SuperTabReading.desktop);
+ // A reading that asks for the messages after every state read: one with
+ // nothing new still cuts. Desktop's asks only when the conversation's
+ // counters move (spec 2026-11-02-poll-cost, Part 2).
+ final c = await show(tester, server);
position(tester).jumpTo(position(tester).maxScrollExtent / 2);
await tester.pumpAndSettle();
await poll(tester, server, c, 600, () {});
diff --git a/desktop/test/super_tab_heartbeat_test.dart b/desktop/test/super_tab_heartbeat_test.dart
index 83a6ccf05..d0daf6a79 100644
--- a/desktop/test/super_tab_heartbeat_test.dart
+++ b/desktop/test/super_tab_heartbeat_test.dart
@@ -123,23 +123,32 @@ void main() {
});
group('a read a heartbeat came with something else in', () {
- void redraws(String what, void Function(_Rig r) change, {bool? messages}) {
- test('$what: everything redraws, and the chat is read', () {
- fakeAsync((async) {
- final r = _Rig(async);
- final before = r.c.snapshot;
- change(r);
- r.beat('m1');
- async.elapse(const Duration(seconds: 3));
- expect(r.told, greaterThan(0));
- expect(identical(r.c.snapshot, before), isFalse);
- expect(r.messages, greaterThan(0));
- r.close();
- });
- });
+ // The chat is read only when its own counters move (spec
+ // 2026-11-02-poll-cost, Part 2): a machine's change redraws without it.
+ void redraws(
+ String what,
+ void Function(_Rig r) change, {
+ bool messages = false,
+ }) {
+ test(
+ '$what: everything redraws, and the chat is ${messages ? '' : 'not '}read',
+ () {
+ fakeAsync((async) {
+ final r = _Rig(async);
+ final before = r.c.snapshot;
+ change(r);
+ r.beat('m1');
+ async.elapse(const Duration(seconds: 3));
+ expect(r.told, greaterThan(0));
+ expect(identical(r.c.snapshot, before), isFalse);
+ expect(r.messages, messages ? greaterThan(0) : 0);
+ r.close();
+ });
+ },
+ );
}
- redraws('a new message', (r) => r.server.append('A reply'));
+ redraws('a new message', (r) => r.server.append('A reply'), messages: true);
redraws('a renamed machine', (r) => r.machine('m2')['name'] = 'Studio');
redraws('a paused machine', (r) => r.machine('m2')['paused'] = true);
redraws(
diff --git a/desktop/test/super_tab_pushes_test.dart b/desktop/test/super_tab_pushes_test.dart
index 9346df3ea..455b61266 100644
--- a/desktop/test/super_tab_pushes_test.dart
+++ b/desktop/test/super_tab_pushes_test.dart
@@ -163,33 +163,39 @@ void main() {
});
});
- // A receipt moves on the delivery's own record, which no Swarm push names.
- test(
- 'keeps the poll while the person\'s own message waits for its receipt',
- () {
- fakeAsync((async) {
- final server = ConversationServer()..append('Build it');
- server.messages.last['deliveries'] = [
- {'id': 'd', 'agentId': 'lead-agent', 'status': 'queued'},
- ];
- final reads = _Reads(server);
- final c = _controller(reads)..start();
- async.flushMicrotasks();
- _pushes(c);
- reads.clear();
- async.elapse(const Duration(seconds: 9));
- expect(reads.states, 3);
- server.messages.last['deliveries'] = [
- {'id': 'd', 'agentId': 'lead-agent', 'status': 'answered'},
- ];
- async.elapse(const Duration(seconds: 3));
- reads.clear();
- async.elapse(const Duration(seconds: 30));
- expect(reads.states, 0);
- c.dispose();
- });
- },
- );
+ // A receipt moves on the delivery's own record, which no Swarm push names:
+ // its row alone is read every 30 s, not the Swarm every 3 s (spec
+ // 2026-11-02-poll-cost, Part 2).
+ test('reads the person\'s own message while it waits for its receipt', () {
+ fakeAsync((async) {
+ final server = ConversationServer()..append('Build it');
+ server.messages.last['deliveries'] = [
+ {'id': 'd', 'agentId': 'lead-agent', 'status': 'queued'},
+ ];
+ final reads = _Reads(server);
+ final c = _controller(reads)..start();
+ async.flushMicrotasks();
+ _pushes(c);
+ reads.clear();
+ async.elapse(const Duration(seconds: 30));
+ expect(reads.states, 0);
+ expect(reads.paths, [
+ '/api/super-tabs/tab/conversations/lead/messages?messageId=message-1',
+ ]);
+ server.messages.last['deliveries'] = [
+ {'id': 'd', 'agentId': 'lead-agent', 'status': 'answered'},
+ ];
+ async.elapse(const Duration(seconds: 30));
+ expect(
+ c.messages('lead').single.deliveries.single['status'],
+ 'answered',
+ );
+ reads.clear();
+ async.elapse(const Duration(seconds: 25));
+ expect(reads.paths, isEmpty);
+ c.dispose();
+ });
+ });
test(
'goes back to the 3 s poll once the server\'s word is over 5 minutes old',
diff --git a/desktop/test/super_tab_quiet_mode_test.dart b/desktop/test/super_tab_quiet_mode_test.dart
index 0d783c115..ab2cb6108 100644
--- a/desktop/test/super_tab_quiet_mode_test.dart
+++ b/desktop/test/super_tab_quiet_mode_test.dart
@@ -105,8 +105,10 @@ void main() {
});
});
+ // Spec 2026-11-02-poll-cost, Part 2: its row alone, every 30 s, not the
+ // page every poll.
test(
- 'keeps reading the messages while the own message awaits a receipt',
+ 'reads only the own message, every 30 s, while it awaits a receipt',
() {
fakeAsync((async) {
final server = ConversationServer()..append('Hi');
@@ -121,13 +123,15 @@ void main() {
final c = _controller(reads)..start();
async.flushMicrotasks();
server.messages.last['deliveries'] = [delivery('answered')];
- async.elapse(_poll);
+ reads.clear();
+ async.elapse(const Duration(seconds: 30));
expect(
c.messages('lead').single.deliveries.single['status'],
'answered',
);
+ expect(reads.messageReads, 1);
reads.clear();
- async.elapse(_poll);
+ async.elapse(const Duration(seconds: 30));
expect(reads.messageReads, 0);
c.dispose();
});
diff --git a/desktop/test/super_tab_reading_test.dart b/desktop/test/super_tab_reading_test.dart
index dee69f96e..c81c558d6 100644
--- a/desktop/test/super_tab_reading_test.dart
+++ b/desktop/test/super_tab_reading_test.dart
@@ -3,6 +3,7 @@ import 'dart:async';
import 'package:fake_async/fake_async.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:harness/super_tabs/controller.dart';
+import 'package:harness/super_tabs/profile_model.dart';
import 'package:harness/super_tabs/reading.dart';
import 'support/super_tab_fixture.dart';
@@ -87,6 +88,24 @@ SuperTabController _controller(
reading: reading,
);
+/// A machine of the Swarm as its last reading left it.
+Map<String, dynamic> _machine({required int free}) => {
+ 'machineId': 'm1',
+ 'name': 'Mac Studio',
+ 'contributorId': 'owner',
+ 'scope': 'swarm',
+ 'cwd': '/swarm',
+ 'engines': ['claude'],
+ 'maxAgents': 4,
+ 'paused': false,
+ 'availableSlots': free,
+};
+
+Map<String, dynamic> _conversation(ConversationServer server, String id) =>
+ (server.state['conversations'] as List)
+ .cast<Map<String, dynamic>>()
+ .firstWhere((g) => g['id'] == id);
+
void _reply(ConversationServer server, String text) {
server.append(text);
server.messages.last['author'] = {
@@ -109,28 +128,44 @@ void main() {
reads.clear();
async.elapse(const Duration(seconds: 30));
expect(reads.states, 10);
- // Nothing new: each poll reads the page again for its receipts.
- expect(reads.pages, 10);
+ // Nothing new: each poll asks what came after the newest, and never
+ // reads the page again for its receipts (spec 2026-11-02-poll-cost).
+ expect(reads.tails, 10);
+ expect(reads.pages, 0);
c.dispose();
});
});
- test('each poll reads the state, then the messages', () {
- fakeAsync((async) {
- final server = ConversationServer()..append('Hello');
- final reads = _Reads(server);
- final c = _controller(reads)..start();
- async.flushMicrotasks();
- server.holdReads = Completer<void>();
- reads.clear();
- async.elapse(const Duration(seconds: 3));
- expect(reads.paths, [_changesRead]);
- server.holdReads!.complete();
- server.holdReads = null;
- async.flushMicrotasks();
- c.dispose();
- });
- });
+ // Spec 2026-11-02-poll-cost, Part 2: the messages follow the state read
+ // that showed the conversation's counter move, never beside it, however
+ // the read was asked for.
+ test(
+ 'each poll reads the state, then the messages its counters ask for',
+ () {
+ fakeAsync((async) {
+ final server = ConversationServer()..append('Hello');
+ final reads = _Reads(server);
+ final c = _controller(reads, reading: SuperTabReading.desktop)
+ ..start();
+ async.flushMicrotasks();
+ _reply(server, 'Done.');
+ server.holdReads = Completer<void>();
+ reads.clear();
+ c.told(main: true);
+ async.elapse(const Duration(seconds: 3));
+ expect(reads.paths, [_changesRead]);
+ server.holdReads!.complete();
+ server.holdReads = null;
+ async.flushMicrotasks();
+ expect(reads.paths, [
+ _changesRead,
+ '/api/super-tabs/tab/conversations/lead/messages?after=1',
+ ]);
+ expect(c.messages('lead').last.text, 'Done.');
+ c.dispose();
+ });
+ },
+ );
test('every poll is drawn, changed or not', () {
fakeAsync((async) {
@@ -184,6 +219,213 @@ void main() {
});
});
+ // Spec 2026-11-02-poll-cost, Part 2: the open conversation's messages are
+ // read when its own counters move, not on a change elsewhere in the Swarm.
+ group('Desktop reads by the open conversation\'s counters', () {
+ Iterable<String> leadReads(_Reads reads) =>
+ reads.paths.where((p) => p.contains('/conversations/lead/messages'));
+
+ test('no messages read while the open conversation\'s counters are '
+ 'unchanged, whatever else in the Swarm or its machines changed', () {
+ fakeAsync((async) {
+ final server = ConversationServer()..append('Hello');
+ final reads = _Reads(server);
+ final c = _controller(reads, reading: SuperTabReading.desktop)..start();
+ async.elapse(const Duration(seconds: 3));
+ reads.clear();
+ server.state['name'] = 'Pilot, renamed';
+ server.state['machines'] = [_machine(free: 3)];
+ server.append('Elsewhere', conversationId: 'offline');
+ c.told(main: true);
+ async.elapse(const Duration(seconds: 6));
+ server.state['machines'] = [_machine(free: 2)];
+ c.told(main: false);
+ async.elapse(const Duration(seconds: 30));
+ expect(reads.states, greaterThan(10));
+ expect(c.snapshot!.name, 'Pilot, renamed');
+ expect(leadReads(reads), isEmpty);
+ c.dispose();
+ });
+ });
+
+ // Review focus 2: two Swarm tabs share a machine; its reading changes
+ // both, and only the one on screen has a new message.
+ test('a change in another Swarm reads nothing here', () {
+ fakeAsync((async) {
+ final here = ConversationServer()..append('Hello');
+ final there = ConversationServer()..append('Hello');
+ for (final server in [here, there]) {
+ server.state['machines'] = [_machine(free: 4)];
+ }
+ final hereReads = _Reads(here), thereReads = _Reads(there);
+ final offScreen = _controller(
+ hereReads,
+ reading: SuperTabReading.desktop,
+ )..start();
+ final onScreen = _controller(
+ thereReads,
+ reading: SuperTabReading.desktop,
+ )..start();
+ async.elapse(const Duration(seconds: 3));
+ offScreen.away = true;
+ async.elapse(const Duration(seconds: 15));
+ hereReads.clear();
+ thereReads.clear();
+ for (final server in [here, there]) {
+ server.state['machines'] = [_machine(free: 3)];
+ }
+ _reply(there, 'Done there.');
+ offScreen.told(main: false);
+ onScreen.told(main: true);
+ async.elapse(const Duration(seconds: 30));
+ expect(hereReads.states, greaterThan(0));
+ expect(hereReads.messageReads, isEmpty);
+ expect(thereReads.messageReads, [
+ '/api/super-tabs/tab/conversations/lead/messages?after=1',
+ ]);
+ expect(onScreen.messages('lead').last.text, 'Done there.');
+ offScreen.dispose();
+ onScreen.dispose();
+ });
+ });
+
+ test('one after read when lastMessageSequence moves', () {
+ fakeAsync((async) {
+ final server = ConversationServer()..append('Hello');
+ final reads = _Reads(server);
+ final c = _controller(reads, reading: SuperTabReading.desktop)..start();
+ async.elapse(const Duration(seconds: 3));
+ reads.clear();
+ _reply(server, 'Done.');
+ async.elapse(const Duration(seconds: 30));
+ expect(leadReads(reads), [
+ '/api/super-tabs/tab/conversations/lead/messages?after=1',
+ ]);
+ expect(c.messages('lead').last.text, 'Done.');
+ // A message this reader may not see still moves the counter: one
+ // empty after, no page read again, and nothing more while it stays.
+ reads.clear();
+ _conversation(server, 'lead')['lastMessageSequence'] = 7;
+ async.elapse(const Duration(seconds: 30));
+ expect(leadReads(reads), [
+ '/api/super-tabs/tab/conversations/lead/messages?after=2',
+ ]);
+ c.dispose();
+ });
+ });
+
+ // Final review, Important 3: the early page of a reopened Swarm can end before the state it is joined with.
+ test('a reply that lands between a reopened Swarm\'s early page and its state still shows', () {
+ fakeAsync((async) {
+ final server = ConversationServer()..append('Hello');
+ final reads = _Reads(server)..holdState = [];
+ final c = _controller(
+ reads,
+ reading: SuperTabReading.desktop,
+ initial: {'tabId': 'tab', 'accountId': 'owner', 'selectedId': 'lead'},
+ )..start();
+ async.flushMicrotasks();
+ // The early page has gone out and come back; the agent answers before the state is read.
+ _reply(server, 'Done.');
+ for (final wait in reads.holdState!) {
+ wait.complete();
+ }
+ reads.holdState = null;
+ async.flushMicrotasks();
+ async.elapse(const Duration(seconds: 10));
+ expect(c.messages('lead').last.text, 'Done.');
+ c.dispose();
+ });
+ });
+
+ test('a page re-read only when reactionSeq moves', () {
+ fakeAsync((async) {
+ final server = ConversationServer()..append('Hello');
+ final reads = _Reads(server);
+ final c = _controller(reads, reading: SuperTabReading.desktop)..start();
+ async.elapse(const Duration(seconds: 3));
+ reads.clear();
+ // Someone reacts on another device.
+ server.messages.single['reactions'] = [
+ {
+ 'emoji': 'thumbs_up',
+ 'count': 1,
+ 'by': [
+ {'kind': 'person', 'id': 'peer'},
+ ],
+ },
+ ];
+ _conversation(server, 'lead')['reactionSeq'] = 1;
+ async.elapse(const Duration(seconds: 30));
+ expect(leadReads(reads), [
+ '/api/super-tabs/tab/conversations/lead/messages?after=1',
+ '/api/super-tabs/tab/conversations/lead/messages?before=2',
+ ]);
+ expect(
+ c.messages('lead').single.reactions.single.emoji,
+ SuperTabReactionEmoji.thumbsUp,
+ );
+ c.dispose();
+ });
+ });
+
+ test('the own receipt refreshes by messageId every 30 s and stops after '
+ 'its bound', () {
+ fakeAsync((async) {
+ final server = ConversationServer()..append('Build it');
+ server.messages.single['deliveries'] = [
+ {'id': 'd', 'agentId': 'lead-agent', 'status': 'queued'},
+ ];
+ final reads = _Reads(server);
+ final c = _controller(reads, reading: SuperTabReading.desktop)..start();
+ async.flushMicrotasks();
+ reads.clear();
+ async.elapse(const Duration(seconds: 60));
+ // One row every 30 s, not the page every 3 s.
+ expect(leadReads(reads), [
+ '/api/super-tabs/tab/conversations/lead/messages?messageId=message-1',
+ '/api/super-tabs/tab/conversations/lead/messages?messageId=message-1',
+ ]);
+ // Queued: read for 10 minutes, then left for the next real read.
+ async.elapse(const Duration(minutes: 9));
+ reads.clear();
+ async.elapse(const Duration(minutes: 5));
+ expect(leadReads(reads), isEmpty);
+ c.dispose();
+ });
+ });
+
+ test('a held delivery\'s receipt is read for an hour, and stops once '
+ 'delivered', () {
+ fakeAsync((async) {
+ final server = ConversationServer()..append('Build it');
+ server.messages.single['deliveries'] = [
+ {'id': 'd', 'agentId': 'lead-agent', 'status': 'claimed'},
+ ];
+ final reads = _Reads(server);
+ final c = _controller(reads, reading: SuperTabReading.desktop)..start();
+ async.elapse(const Duration(minutes: 50));
+ reads.clear();
+ async.elapse(const Duration(seconds: 60));
+ expect(reads.receipts, 2);
+ expect(reads.pages, 0);
+ server.messages.single['deliveries'] = [
+ {'id': 'd', 'agentId': 'lead-agent', 'status': 'delivered'},
+ ];
+ async.elapse(const Duration(seconds: 30));
+ expect(
+ c.messages('lead').single.deliveries.single['status'],
+ 'delivered',
+ );
+ reads.clear();
+ async.elapse(const Duration(minutes: 5));
+ expect(reads.receipts, 0);
+ expect(reads.pages, 0);
+ c.dispose();
+ });
+ });
+ });
+
group('web reading', () {
test(
'a quiet tab reads its state every 15 s, its new messages every 3 s',
@@ -202,8 +444,8 @@ void main() {
async.elapse(const Duration(seconds: 60));
expect(reads.states, 4);
expect(reads.tails, 20);
- // The page is read again only with a full read.
- expect(reads.pages, 4);
+ // The page is read again only for a changed reaction.
+ expect(reads.pages, 0);
c.dispose();
});
},
@@ -229,7 +471,8 @@ void main() {
},
);
- test('the person\'s unsettled message settles within one 3 s check', () {
+ // Spec 2026-11-02-poll-cost, Part 2: one row every 30 s, not every check.
+ test('the person\'s unsettled message settles within one 30 s check', () {
fakeAsync((async) {
final server = ConversationServer()..append('Please start.');
server.messages.first['deliveries'] = [
@@ -238,11 +481,6 @@ void main() {
final reads = _Reads(server);
final c = _controller(reads, reading: _web)..start();
async.elapse(const Duration(seconds: 61));
- // Just after a full read: the next poll is a light check.
- do {
- reads.clear();
- async.elapse(const Duration(seconds: 3));
- } while (reads.states == 0);
expect(
c.messages('lead').single.deliveries.single['status'],
'claimed',
@@ -251,12 +489,11 @@ void main() {
{'id': 'delivery', 'agentId': 'lead-agent', 'status': 'delivered'},
];
reads.clear();
- async.elapse(const Duration(seconds: 3));
+ async.elapse(const Duration(seconds: 30));
expect(
c.messages('lead').single.deliveries.single['status'],
'delivered',
);
- expect(reads.states, 0);
expect(reads.pages, 0);
expect(reads.receipts, 1);
c.dispose();
@@ -315,28 +552,33 @@ void main() {
});
});
- test('a full read asks for new messages beside the state', () {
- fakeAsync((async) {
- final server = ConversationServer()..append('Hello');
- final reads = _Reads(server);
- final c = _controller(reads, reading: _web)..start();
- async.flushMicrotasks();
- server.holdReads = Completer<void>();
- reads.clear();
- async.elapse(const Duration(seconds: 3));
- expect(reads.paths, [
- '/api/super-tabs/tab/conversations/lead/messages?after=1',
- _changesRead,
- ]);
- _reply(server, 'Done.');
- server.holdReads!.complete();
- server.holdReads = null;
- async.flushMicrotasks();
- // Its answer is used, not asked for again.
- expect(reads.tails, 1);
- c.dispose();
- });
- });
+ // Spec 2026-11-02-poll-cost, Part 2: beside every read, the messages were
+ // read on any change in the Swarm.
+ test(
+ 'a full read after the first asks for the messages after the state',
+ () {
+ fakeAsync((async) {
+ final server = ConversationServer()..append('Hello');
+ final reads = _Reads(server);
+ final c = _controller(reads, reading: _web)..start();
+ async.flushMicrotasks();
+ server.holdReads = Completer<void>();
+ reads.clear();
+ async.elapse(const Duration(seconds: 3));
+ expect(reads.paths, [_changesRead]);
+ _reply(server, 'Done.');
+ server.holdReads!.complete();
+ server.holdReads = null;
+ async.flushMicrotasks();
+ expect(reads.paths, [
+ _changesRead,
+ '/api/super-tabs/tab/conversations/lead/messages?after=1',
+ ]);
+ expect(c.messages('lead').last.text, 'Done.');
+ c.dispose();
+ });
+ },
+ );
test('a quiet full read with nothing new redraws nothing', () {
fakeAsync((async) {
@@ -369,24 +611,23 @@ void main() {
});
});
- test('a reply shows as its messages answer, not after the state', () {
+ // The spec's call: a reply shows one state read later, not beside it.
+ test('a reply shows once the state that says so answers', () {
fakeAsync((async) {
final server = ConversationServer()..append('Hello');
final reads = _Reads(server);
final c = _controller(reads, reading: _web)..start();
async.flushMicrotasks();
_reply(server, 'Done.');
- // The state answers slowly; the messages at once.
- server.holdReads = Completer<void>();
final heldStates = <Completer<void>>[];
reads.holdState = heldStates;
- server.holdReads!.complete();
- server.holdReads = null;
async.elapse(const Duration(seconds: 3));
expect(heldStates, hasLength(1));
- expect(c.messages('lead').last.text, 'Done.');
+ expect(c.messages('lead').last.text, 'Hello');
+ expect(reads.tails, 0);
heldStates.single.complete();
async.flushMicrotasks();
+ expect(c.messages('lead').last.text, 'Done.');
expect(reads.tails, 1);
c.dispose();
});
diff --git a/desktop/test/super_tab_receipt_test.dart b/desktop/test/super_tab_receipt_test.dart
index 9adc9b993..3d3d36909 100644
--- a/desktop/test/super_tab_receipt_test.dart
+++ b/desktop/test/super_tab_receipt_test.dart
@@ -134,11 +134,9 @@ void main() {
f.message['createdAt'] = DateTime.now().toIso8601String(),
);
expect(find.text('Sending…'), findsOneWidget);
- f.message['createdAt'] = f.now
- .subtract(const Duration(seconds: 8))
- .toIso8601String();
- await f.controller.refresh();
- await tester.pump();
+ // The message ages on screen: no read of it again, which a state
+ // with the same counters no longer makes (spec 2026-11-02-poll-cost).
+ await tester.pump(const Duration(seconds: 8));
f.expectQuiet();
await f.close();
},
diff --git a/docs/plans/2026-11-02-windows-bridge-pipe-plan.md b/docs/plans/2026-11-02-windows-bridge-pipe-plan.md
new file mode 100644
index 000000000..2968ea891
--- /dev/null
+++ b/docs/plans/2026-11-02-windows-bridge-pipe-plan.md
@@ -0,0 +1,136 @@
+# Windows: the connectors bridge off a held port, and over a proven pipe — Implementation Plan
+
+> **For agentic workers:** This plan is implemented by the Engineer task by task, test first (project instructions,
+> Engineer role), not by subagent-driven-development. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** On Windows, the bridge moves off a port another account holds, and MCP clients (the stdio shim) and Harness's
+own route (`cloud/bridge.ts` `bridgeRoute`) reach the bridge over a named pipe that proves itself, never the port.
+
+**Architecture:** `portHolderIsThisAccount` asks Windows who owns the listener (`Get-NetTCPConnection -State Listen`,
+owner SID against this account's, as W1's peer check does), so `listen` in `services/connectors.ts` can move. The
+bridge also listens on a pipe of its own, `\\.\pipe\harness-<random id>`, new at each start, through
+`listenLocalSocket(..., { token })`: every request proves a random token and every answer proves it back
+(`lib/windows/pipeAuth.ts`). The pipe, the edge process's pid and the token are written to `bridge-pipe.json` in the
+vault's private folder. The shim (`mcpShimSource.ts`, `--pipe <record> <code>`) and `bridgeRoute` read that record for
+each request, dial only while the recorded process runs (EPERM is another account's, so no), and take only a proven
+answer. Where a pipe exists the keys leave the port as on macOS (`rotateHarnessKey`, `retireBridgeKey`).
+
+**Tech Stack:** TypeScript (cli/), Node `http` over named pipes, Windows PowerShell 5.1 (`Get-NetTCPConnection`,
+`Win32_Process.GetOwnerSid`), vitest.
+
+**Spec:** Task #2162 (Scholes), from Reed's security review of PR #2605 (W1); macOS's version: #2558 (stdio shim),
+#2550 (credential to the real daemon only). Report: `docs/security/2026-11-02-team-account-windows.md`.
+
+## Global Constraints
+
+- Build on W1's branch (`fix/windows-w1-local-credential-pipe`, PR #2605) until it merges.
+- Nothing goes to the bridge's port from a new agent's entry or from Harness's route on Windows; with no live pipe they
+ say Harness / Connections is not running.
+- Anything but a clear yes from Windows is not "mine" for a listener; a lookup that fails says nothing (null), as today.
+- PowerShell inputs go in environment variables, never in the script's text.
+- The shim stays Node built-ins only and holds no key; the pipe token is read from the private record per request.
+- Swarm code stays out of `cli/src/core`. `src/services/connectors.ts` stays at 100% coverage (`npm run test:core`).
+- PR body starts with "Requested by [email protected] through Harness."; two security reviews (Reed, Quinn 2); a real
+ Windows workflow run on the final head.
+
+## Review Focus
+
+- A pipe of the recorded name made by another account after the edge process exits: the recorded pid gone or EPERM sends
+ nothing; a pid reused by this account's own process sends the request, and the proof refuses the answer.
+- An answer without the bridge's proof (a squatter): no byte of it reaches the MCP client or `bridgeRoute`'s caller.
+- A record that is a link, not a local pipe name (`\\host\pipe\…`), or holds a short token: not dialled.
+- A listener of this account's own (a second daemon, a handover) is still waited out, never moved from.
+- An agent still running on the old address keeps working until its key retires (24 h), as on macOS.
+
+---
+
+### Task 1: Windows says who holds the bridge's port
+
+**Files:**
+- Modify: `cli/src/lib/peerAccount.ts` (`portHolderIsThisAccount`, new `windowsListenerQuery`)
+- Test: `cli/src/lib/peerAccount.spec.ts`, `cli/src/team/windowsBoundary.spec.ts`,
+ new `cli/src/lib/windows/bridgePort.windows.real.spec.ts`
+
+**Interfaces:**
+- Produces: `windowsListenerQuery(port: number): { script: string; inputs: Record<string, string> }` printing `yes`,
+ `no` or `none`; `portHolderIsThisAccount(port, platform = process.platform, run: WindowsPeerRun = runWindowsPeer)`:
+ on win32 `yes` → true, `no` → false, `none`, a failure or a timeout → null.
+
+- [ ] **Step 1: Failing tests.** peerAccount.spec: on win32 a run answering `no` is false, `yes` true, `none` null,
+ status 1 / null / thrown null; the port is in `inputs.HARNESS_LISTEN_PORT`, not in the script. windowsBoundary.spec
+ ("the bridge on Windows"): another account's listener reads false, so the bridge moves. Real spec (Windows only): a
+ listener this process opened is `true`; a free port is `null`.
+- [ ] **Step 2: Run** `npx vitest run src/lib/peerAccount.spec.ts src/team/windowsBoundary.spec.ts` — FAIL (null on win32).
+- [ ] **Step 3: Implement.** Script: listeners on the port (`-State Listen -LocalPort`); none → `none`. Each row's
+ process must exist and have started before the row (as `windowsPeerQuery`), else it is not this account's. Any row of
+ this account's SID → `yes` (wait, never move from our own), else `no`.
+- [ ] **Step 4: Run** — PASS. Commit test first, then code.
+
+### Task 2: The bridge listens on a proven pipe on Windows, and the keys leave the port
+
+**Files:**
+- Modify: `cli/src/lib/connectors/bridge.ts` (new `serveBridgePipe`), `cli/src/lib/connectors/agents.ts`
+ (`bridgePipeRecord`, `readBridgePipe`, `bridgeLocal`), `cli/src/services/connectors.ts`
+- Test: new `cli/src/lib/connectors/bridgePipe.spec.ts`, `cli/src/services/connectors.spec.ts`
+
+**Interfaces:**
+- Produces: `serveBridgePipe(vault: Store, path = newPipePath()): Promise<LocalSocketServer>` — serves the bridge's
+ socket handler behind `listenLocalSocket(handler, path, { token })` with a fresh 32-byte token, then writes
+ `bridge-pipe.json` `{ pipe, pid: process.pid, token: <64 hex> }` under the vault lock.
+- `bridgePipeRecord(vault: Store): string` (the record's path).
+- `readBridgePipe(vault: Store, runs = ownProcessRuns): PipeTarget | null` — null unless the pipe passes `isPipePath`,
+ the pid is a positive integer this account's process runs, and the token is 64 hex.
+- `bridgeLocal(vault: Store, platform = process.platform): boolean` — a socket path, or win32.
+- `startConnectors(core, overrides & { platform?: NodeJS.Platform })`: on win32 serves the pipe (retrying as the socket
+ does) and rotates / retires the keys as where a socket is.
+
+- [ ] **Step 1: Failing tests.** bridgePipe.spec (a Unix socket named `harness-<id>` stands for the pipe): a request
+ without the token's auth is 401 and reaches no connection; one with it reaches the MCP server and its answer carries
+ the proof; the record names the pipe, this pid and the token; `readBridgePipe` is null for a dead pid, a pid answering
+ EPERM, a non-pipe name and a short token. connectors.spec: with `platform: 'win32'` the pipe is served, the record is
+ written, and Harness's key is rotated socket-only.
+- [ ] **Step 2: Run** — FAIL (no `serveBridgePipe`).
+- [ ] **Step 3: Implement** as the Interfaces say.
+- [ ] **Step 4: Run**, plus `npm run test:core` for connectors.ts at 100%. Commit test first, then code.
+
+### Task 3: The shim reaches the bridge over the pipe, and agents' entries name it on Windows
+
+**Files:**
+- Modify: `cli/src/lib/connectors/mcpShimSource.ts` (`--pipe RECORD CODE`), `cli/src/lib/connectors/agents.ts`
+ (`project`, `sync(vault, env, list?, platform?)`)
+- Test: `cli/src/lib/connectors/mcpShim.spec.ts` (group "over the pipe")
+
+**Interfaces:**
+- Consumes: Task 2's record and `serveBridgePipe`.
+- Produces: entries `{ command: managedNodePath(), args: [shim, '--pipe', bridgePipeRecord(vault), code] }` on win32.
+
+- [ ] **Step 1: Failing tests.** Over a served pipe, a holder of the old port hears nothing and tools work; with the
+ record's pid dead, or the record a link, the client is told Harness is not running and the pipe hears nothing; a
+ squatter answering without the proof gets the request but none of its answer reaches the client (an error does); the
+ entry on win32 names the shim and the record, no port and no key.
+- [ ] **Step 2: Run** — FAIL.
+- [ ] **Step 3: Implement.** Per request: lstat the record (a plain file, opened and the same file), parse, check the
+ pipe name (`\\.\pipe\harness-<32 hex>` on Windows; a socket named so elsewhere), the pid (`kill 0`; any error is no),
+ the token; send `x-harness-auth`, check `x-harness-proof` before relaying.
+- [ ] **Step 4: Run** the shim spec whole. Commit test first, then code.
+
+### Task 4: Harness's own route over the pipe
+
+**Files:**
+- Modify: `cli/src/cloud/bridge.ts` (`bridgeRoute(vault, platform = process.platform)`), `cli/src/lib/localTransport.ts`
+ (new `fetchOverPipe(target: () => PipeTarget | null): typeof fetch`)
+- Test: `cli/src/cloud/bridge.socket.spec.ts` (group "on Windows")
+
+- [ ] **Step 1: Failing tests.** On win32 with the pipe served: list, API and MCP calls go over it and a holder of the
+ port hears nothing; with no live record it says Connections is not running and sends nothing to the port; an
+ unproven answer is refused.
+- [ ] **Step 2: Run** — FAIL (win32 goes to the port).
+- [ ] **Step 3: Implement**: base `http://connections.invalid/<harnessKey>`, fetch over `readBridgePipe`.
+- [ ] **Step 4: Run**. Commit test first, then code.
+
+### Task 5: Report, real Windows check, evidence
+
+- [ ] The report's W1 "Still open" bridge line becomes fixed by this task, stating the false-answers risk before it.
+- [ ] Real Windows spec: the bridge on a real pipe answers the shim, and `portHolderIsThisAccount` on a real listener.
+ The Windows workflow runs `src/lib/windows`; ask the PM for one run on the final head.
+- [ ] Red/green in a PR comment; `npx tsc --noEmit`; affected specs; `npm run test:core`.
diff --git a/docs/plans/2026-11-03-activity-unfollow-replies-plan.md b/docs/plans/2026-11-03-activity-unfollow-replies-plan.md
new file mode 100644
index 000000000..21f18491d
--- /dev/null
+++ b/docs/plans/2026-11-03-activity-unfollow-replies-plan.md
@@ -0,0 +1,55 @@
+# Activity Unfollow Replies Implementation Plan
+
+**Goal:** Stop writing reply Activity rows for people who unfollowed that thread, and resume writing them when they follow again.
+
+**Architecture:** `writeReplyActivity` will read each candidate recipient's thread mark by its stable id in one indexed `$in` read. It will omit candidates whose mark has `follow: false` and preserve existing behavior for absent marks and `follow: true`.
+
+**Tech Stack:** TypeScript, Prisma, MongoDB, Vitest integration tests.
+
+**Spec:** Task #2247, conversation `b43385a1daf243b3b4af8999`.
+
+## Global Constraints
+
+- No environment switch.
+- Keep one indexed read for the candidate thread marks.
+- Following again must restore new reply Activity rows.
+- The Activity row remains scoped to the root's author and message's own chat.
+
+## Review Focus
+
+- An absent mark must preserve existing default-follow behavior.
+- An explicit `follow: false` must suppress rows for that person only.
+- An explicit `follow: true` must allow rows again.
+- Replies addressed to multiple candidate authors must filter each person independently.
+- The mark lookup must use one `_id: { $in: ... }` read rather than per-person queries.
+
+## Design
+
+- Growth: No new data; Activity expiry continues deleting rows after 30 days.
+- Concurrency: Read the current thread mark in the reply transaction; the existing transaction boundary is unchanged.
+- Read cost: One indexed read for the deduplicated thread and recipient mark ids.
+- Scale: One read regardless of recipient count; monitor Activity write volume and transaction latency; expected limit remains the existing recipient/message batch size.
+- Compatibility: Older clients need no change; clients that follow or unfollow continue using existing marks.
+- Migration and rollback: None; rollback restores the old writer and existing mark rows remain valid.
+- Audience: The server filters the row for the exact person whose mark is read.
+- Identity: Use person ids from message authors and mark ids, never machine-owner login.
+- Failure: The write remains in its existing transaction, so a failed mark read aborts rather than silently writing an incorrect row.
+- Platforms: Backend only; no platform-specific behavior.
+
+## Tasks
+
+### Task 1: Honor the thread's follow mark when writing Activity
+
+**Files:**
+- Modify: `backend/integration/superTabActivity.test.ts`
+- Modify: `backend/src/superTabs/activity.ts`
+
+**Interfaces:**
+- Consumes: Existing `SuperTabThreadMark` stable ids and `readBy` helper.
+- Produces: `writeReplyActivity` omits recipients with `follow: false` and otherwise retains its current behavior.
+
+- [ ] Write an integration test that creates a reply, confirms one unread Activity row, unfollows the thread, creates another reply and confirms no additional row, then follows again, creates a reply and confirms a new row.
+- [ ] Run the focused test and verify it fails because the unfollowed reply currently creates a row.
+- [ ] Update `writeReplyActivity` to read the candidate recipients' marks once by `_id: { $in: [...] }` and exclude only `follow: false`.
+- [ ] Run the focused test and verify the unfollow/follow assertions pass.
+- [ ] Run the full Super Tab integration suite and record its result.
diff --git a/docs/plans/2026-11-03-mobile-task-line-design.md b/docs/plans/2026-11-03-mobile-task-line-design.md
new file mode 100644
index 000000000..186383280
--- /dev/null
+++ b/docs/plans/2026-11-03-mobile-task-line-design.md
@@ -0,0 +1,25 @@
+# Phone task lines
+
+The phone renders the server's existing `task-line` message as a quiet opening row in the project chat. This ports Desktop's presentation to the existing phone tokens; no protocol changes.
+
+```
+[mark] Task name working ›
+[mark] Task name Answer ›
+```
+
+The title comes from the source title, falling back to message text. Words match Desktop: planned, working, in review, ready, shipped, done, stopped. Waiting says Answer only when answerFor identifies the reader; otherwise working. Unknown states say no word. Marks use the existing Lucide circleDashed, circleDot, check and circleSlash icons, matching Desktop. The name truncates when space is tight; the word stays visible. The row has a 44-point minimum tap target and one accessible label containing name and word. Answer uses stronger text weight.
+
+A tap opens the referenced task chat through the existing phone route, only while the current snapshot holds that task. A missing or invalid target remains readable without an action. A legacy ship message is hidden when a task line for that same task is present in the loaded chat; legacy messages for other tasks remain. Normal messages after a task line retain their author header.
+
+## Design
+
+- Growth: no new stored data; rows use the chat's existing loaded message window and lifetime.
+- Concurrency: N/A because this only renders immutable message snapshots on Flutter's UI isolate.
+- Read cost: no additional reads until an explicit tap opens the existing chat route; filter one loaded window in linear time.
+- Scale: at 10x loaded messages filtering remains linear; frame build time is the first warning metric.
+- Compatibility: unknown states retain title and mark without an invented word; old ship messages remain when no replacement is loaded.
+- Migration + rollback: no migration; reverting restores the existing plain-text presentation.
+- Audience: existing server-filtered snapshot and chat endpoints enforce access; no client-created target grants access.
+- Identity: reader account id controls Answer; never the computer owner's login.
+- Failure: unavailable target is readable and noninteractive; existing route reports chat read failures.
+- Platforms: shared Flutter presentation for iOS and Android; simulator validation on iOS, no physical-device installation.
diff --git a/docs/plans/2026-11-03-mobile-task-line-plan.md b/docs/plans/2026-11-03-mobile-task-line-plan.md
new file mode 100644
index 000000000..3de14fe43
--- /dev/null
+++ b/docs/plans/2026-11-03-mobile-task-line-plan.md
@@ -0,0 +1,52 @@
+# Phone Task Lines Implementation Plan
+
+> **For agentic workers:** Implement task-by-task in this Engineer session using test-driven development, followed by independent Swarm Review and Test steps. No execution handoff.
+
+**Goal:** Render server task lines on the phone with Desktop's words and marks and direct task-chat navigation.
+
+**Architecture:** Add a focused task-line widget and loaded-message filter. The chat page supplies navigation only for a task held by its reader; the ordinary message renderer dispatches task-line messages before normal prose.
+
+**Tech Stack:** Flutter 3.47.9, Dart 3.13.7, existing Lucide icons and phone design tokens.
+
+**Spec:** [Phone task lines](2026-11-03-mobile-task-line-design.md), task #2239, Desktop `desktop/lib/super_tabs/task_line.dart`.
+
+## Global Constraints
+
+- Mobile implementation and tests only; these required design/plan files are the first commit.
+- No new colors, icons, dependencies, switches or protocol changes.
+- Exact Desktop lowercase words; only Answer is capitalized and reader-specific.
+- Fakes only; never a real sign-out or physical-phone install.
+- PR body begins: Requested by [email protected] through Harness.
+
+## Review Focus
+
+- Waiting for another person must never ask this reader to Answer.
+- Missing/malformed target must not open an unrelated chat; access changes must invalidate cached row actions.
+- Legacy ship suppression must match task id, regardless of message order.
+- Long titles, narrow screens and large text must keep the word and tap target usable.
+- Unknown state and missing title retain a readable row; ordinary messages after special rows retain their author.
+
+## Task 1: Render and open task lines in chat
+
+**Files:**
+- Create `mobile/lib/swarm/swarm_task_line.dart` (presentation and loaded-window filtering).
+- Modify `mobile/lib/swarm/swarm_message_row.dart` (special-row dispatch).
+- Modify `mobile/lib/swarm/swarm_conversation_page.dart` (target resolution, navigation, filtering and grouping).
+- Create `mobile/test/swarm/swarm_task_line_test.dart` (real row and chat widgets using fake transport).
+
+**Interfaces:**
+- Produces `SwarmTaskLine({required SuperTabMessage message, required String readerId, VoidCallback? onOpen})`.
+- Produces `List<SuperTabMessage> swarmTaskLineMessages(List<SuperTabMessage> messages)`.
+- Extends `SwarmMessageRow` with optional `VoidCallback? onOpenTask`.
+- Consumes `openSwarmConversation(BuildContext, String swarmId, String conversationId)` and reader snapshot conversations.
+
+- [ ] Write and commit failing widget tests using existing public row/chat APIs: for each state assert literal title, word and Lucide mark; waiting for reader asserts Answer, another reader asserts working. Assert fallback title/unknown state, accessible label, narrow/large-text layout, target chat navigation, inaccessible target, per-task legacy ship suppression and author grouping after special rows.
+- [ ] Run `flutter test test/swarm/swarm_task_line_test.dart --reporter expanded`; record expected failures (plain prose, missing state marks, no task navigation, duplicate ship row) on unchanged main production code.
+- [ ] Implement the focused widget with phone typography, muted marks and minimum 44-point target. Dispatch before prose, resolve targets through the snapshot, filter redundant ship rows and exclude special rows from author grouping.
+- [ ] Repeat the affected tests and commit passing code separately from the red tests. Push after this completed task.
+- [ ] Run the full mobile `flutter test` once (20-minute bound), and analyze changed Dart files (5-minute bound). Independent checks may run alongside one another within capacity; no backend or Desktop suites are needed for mobile-only rendering. Record failures honestly and bound baseline diagnosis to 10 minutes.
+- [ ] Mark the PR ready once green evidence is recorded. Ask Cleo for independent review and the named local Tester for iOS simulator screenshots of every state plus navigation. Read all acceptance checks before reporting completion.
+
+## Validation and timing
+
+Record implementation, validation, review/test waiting, merge and publication separately in the PR. Task received 2026-11-02 17:15 UTC. Engineer does not merge or release; PM owns those later phases. No deterministic receipt reuse is planned for newly added behavior. Required evidence: red/green task-line tests, full mobile suite, changed-file analysis, simulator screenshots and independent review/test verdicts.
diff --git a/docs/security/2026-11-02-team-account-windows.md b/docs/security/2026-11-02-team-account-windows.md
index 728e75fdc..ddbb89f8f 100644
--- a/docs/security/2026-11-02-team-account-windows.md
+++ b/docs/security/2026-11-02-team-account-windows.md
@@ -11,13 +11,13 @@ text and values the code produces. Nothing on a real account, permission or file
**The folders hold; the daemon's port does not.** Ports were covered only in part: the Team daemon's own port was not read. The ACLs setup writes keep the Team account out of the owner's profile.
Other accounts can't read the sign-in code or the relay's token, and the daemon's pipe proves both ends. On Windows the owner's
local credential went over TCP to whoever holds the daemon's port, and the daemon accepted it from any account (W1, fixed in
-task #2095; the connectors bridge's port is still open, its own task, so Team accounts on Windows are not closed yet).
+task #2095; the connectors bridge's port is fixed in task #2162).
The Team account's daemon starts at boot, before the owner signs in. Purge was written for POSIX paths. It never deleted a
Codex Product Manager's own home on Windows (W2, fixed in this pull request), and it can't finish a Claude Code one there (W3).
| ID | Rating | Finding | Status |
|---|---|---|---|
-| W1 | **High** | The owner's local credential goes to whoever holds the daemon's port, and opens the daemon from any account | **Fixed** in task #2095 for every client, test first. The Store add-ons over the pipe (task #2161): fixed, and run on real Windows x64 and Arm against the installed daemon (Windows workflow run 41464966703). The connectors bridge is still open (own task) |
+| W1 | **High** | The owner's local credential goes to whoever holds the daemon's port, and opens the daemon from any account | **Fixed** in task #2095 for every client, test first. The Store add-ons over the pipe (task #2161): fixed, and run on real Windows x64 and Arm against the installed daemon (Windows workflow run 41464966703). The connectors bridge: fixed in task #2162, and run on real Windows x64 and Arm (Windows workflow run 41488691783) |
| W2 | **High** | Purge left a Codex Product Manager's whole home on Windows, and could take every PM's home on any platform | **Fixed here**, test first |
| W3 | Medium | Purge can't scrub a Claude Code Product Manager on Windows: the account stays held, its memory stays | Read in code, fix requested |
| W4 | Medium | The Team account can stall the owner's read of its status file | Read in code, fix requested |
@@ -83,12 +83,25 @@ make the daemon refuse the credential over TCP from another account. Windows can
is not running. Their `localCredentialHeaders` give nothing on Windows and their 401 probe never runs there
(`store/tools/windows-pipe.test.mjs`, run on Windows by the Windows workflow, with `store/tools/windows-ci/store-pipe.mjs`
against the installed daemon).
-- Still open, rated Medium, its own task: the connectors bridge. Its default port (51793) is the same for every account, the Team
- daemon also starts connectors, and on Windows `portHolderIsThisAccount` answers null, so the owner's bridge never moves off a
- held port (`services/connectors.ts`). Whoever holds it from boot reads every tool call of the owner's agents and can answer them
- falsely, and Harness's own `bridgeRoute` trusts those answers too. The key opens nothing from another account now. macOS has the
- stdio shim and the move-off (#2558, #2550); Windows has neither. The fix is the shim and Harness's route over the proven pipe;
- a Windows listener-owner lookup, so the bridge moves off a held port, is a cheap first step.
+- The connectors bridge (task #2162, from Reed's review of #2605, Medium at least; fixed, and run on real Windows x64 and Arm: Windows workflow run 41488691783). Until then, `portHolderIsThisAccount`
+ answered null on Windows, so the bridge never moved off a port another account held, and agents' entries and Harness's own
+ `bridgeRoute` named that port. The bridge's default port, 51793, is the same for every account, and the Team account's daemon
+ starts connectors at boot, so in practice the Team account read every tool call of the owner's agents and could return false
+ tool answers to agents running with the owner's rights. The key opened nothing from another account after W1, but the answers
+ were taken. Now:
+ - Windows is asked whose the listener is (`lib/peerAccount.ts` `windowsListenerQuery`: `Get-NetTCPConnection -State Listen`,
+ the process's owner SID against this account's; a process that started after its listener, its time cut to the second as
+ Windows gives the listener's, or the lookup's own process, counted as not this account's),
+ so the bridge moves off another account's port, as on macOS and Linux.
+ - The bridge also listens on a pipe of a new name at each start, `\\.\pipe\harness-<id>`, whose every request proves a token
+ new at each start, and whose every answer proves it back (`lib/connectors/bridge.ts` `serveBridgePipe`). The pipe, the
+ serving process and the token are recorded in `bridge-pipe.json` in the vault's private folder.
+ - Agents' entries run the stdio shim with `--pipe <record>` (`mcpShimSource.ts`), and Harness's own `bridgeRoute` goes over the
+ same pipe. Both dial it only while the recorded process runs as this account (EPERM is no), and take no answer without the
+ proof. With no live pipe they say Harness or Connections is not running; nothing goes to the port. As on macOS, Harness's key
+ is replaced once and never crosses the port, and the agents' old key opens the port for a day, for agents still running on it.
+ - Left as for the daemon's pipe: a recorded pid this account's own process took since (by chance) is still dialled, and the
+ request reaches whatever made a pipe of the name; its answer is refused by the proof.
- Still open: the OpenCode, Kilo, Pi and Amp plugins (`engines/kit/pluginFetch.ts`) have no socket on Windows and post to the
port with the hook-only token and the session's details. The token opens nothing from another account now, but whoever holds
the port hears both, and each new connection costs the daemon's one-second lookup. They need the pipe too, a separate task.
diff --git a/docs/superpowers/plans/2026-11-02-poll-cost.md b/docs/superpowers/plans/2026-11-02-poll-cost.md
new file mode 100644
index 000000000..8cc110ce8
--- /dev/null
+++ b/docs/superpowers/plans/2026-11-02-poll-cost.md
@@ -0,0 +1,459 @@
+# Poll cost: Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Cut backend CPU spent on polls: count what polls return, patch the last four whole-reloaded cache entries, and make
+the daemon and Desktop stop reads that tell nothing new.
+
+**Architecture:**
+- **Backend:** adds counters, extends the delta cache (#2519) to `feed`, `light`, `host:state:{m}`, `host:inputs` and
+ `startsOf`, makes the receipt read cheap, and pushes delivery cancels/answers and terminal requests.
+- **CLI daemon:** retries held deliveries locally, backs off receipt checks, and slows its other polls behind push leases.
+- **Desktop:** reads the open conversation's messages only when its own counters move.
+
+**Tech Stack:** TypeScript (backend Node/Fastify/Prisma-on-Mongo/ioredis; CLI Node), Dart/Flutter (Desktop), vitest,
+flutter test.
+
+**Spec:** `docs/superpowers/specs/2026-11-02-poll-cost-design.md` (read it first; it carries the why and the measured
+numbers).
+
+## Global Constraints
+
+- **No commits or pushes until Ken asks.** Branch `perf/poll-cost` from `main`. Leave work in the tree.
+- **Repository conventions:** docs and comments in English, saying why; no dead code; each file keeps its style.
+- **Release order:**
+ 1. backend: Tasks 1–9;
+ 2. CLI: Tasks 10–14;
+ 3. Desktop: Task 15.
+
+ Each client task falls back to today's cadence without the backend's push lease.
+- **Spec values:**
+
+ | Value | Where |
+ |---|---|
+ | Held delivery re-claim at most every 2 min; held agent list every 30 s plus on push | Part 3 |
+ | Receipt check back-off 5 s doubling to 5 min; retire on final refusal or after 25 h; `HOST_UNAVAILABLE` from billing is not final | Part 3 |
+ | Telemetry settings at start, on local change and hourly; reports every 5 min | Part 4 |
+ | Terminal: `__terminal_waiting` push; 8 s fallback poll with the push lease, 3 s without; backend deadline stays 10 s | Part 4 |
+ | Fleet machine list 45 s TTL, refresh every 5 min plus on `machines_changed`; window path joins in-flight reads only | Part 4 |
+ | Experiment settings re-read only on `desk_changed` with revision 0 | Part 4 |
+ | Pro cards follow the `swarm_changed` push lease with a 2 min safety net | Part 4 |
+ | Desktop own-receipt refresh by `?messageId=` every 30 s, bounded 10 min (60 min held), for queued, claimed, uncertain | Part 2 |
+- **Tests:**
+ - backend: `NODE_ENV=test HARNESS_CREDENTIAL_ENCRYPTION_KEY=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=`, integration
+ with `--config vitest.super-tabs.config.ts`, real Redis with `REDIS_TEST_URL=redis://127.0.0.1:6379/15`;
+ - CLI: `npx vitest run <files>`; `npm run test:core` when touching `src/core` or `src/services`;
+ - Desktop: `flutter test <files>` from `desktop/`.
+
+## Review Focus
+
+1. **A push lost while a delivery is held.** The held message must still be written within 30 s of the pane freeing, and a
+ cancel must still stop it. Test: Task 10, "a cancel missed by push stops the retry at the next 30 s read".
+2. **Desktop with two Swarm tabs, one off screen.** The off-screen tab's open conversation must not read messages on the
+ other tab's changes. Test: Task 15, "a change in another Swarm reads nothing here".
+3. **A machine that leaves a Swarm while its `host:state` is held.** Its rows must not keep showing that Swarm's agents. Test:
+ Task 5, "a machine whose agents all left derives an empty state".
+4. **A daemon restarted with held deliveries and failing receipt entries on disk.** Back-off state must survive or restart
+ safely, with no burst of retries. Test: Task 11, "back-off resumes from the journal after a restart".
+5. **An older daemon against the new backend.** `__terminal_waiting` and the extra delivery pushes must not break it. Test:
+ Task 9, "a frame an older daemon sees is a `__` control frame or a delivery push it already reads".
+
+---
+
+### Task 1: counters (backend, Part 0)
+
+**Files:**
+- Modify: `backend/src/lib/routeLatency.ts`.
+- Modify the route handlers: `GET changes`, `GET messages` (`after`), `GET deliveries`, `hosts/:m/terminal` in
+ `backend/src/routes/superTabs*.ts`.
+- Create: `backend/src/lib/deliveryCalls.ts`.
+- Modify: `backend/src/superTabs/store.ts` (`delivery`, `deliveryReceipt`).
+- Modify: `backend/src/server.ts`.
+- Test: `routeLatency.test.ts`, `deliveryCalls.test.ts`.
+
+**Interfaces:**
+- Produces:
+ ```ts
+ export function markNothingNew(request: FastifyRequest): void // routeLatency.ts
+ // route window gains: empty: number; bytes: number (from Content-Length or payload length in onSend)
+ export function recordDeliveryCall(event: 'reclaim' | 'receipt403' | 'receipt404' | 'hold', reason?: string): void
+ export function startDeliveryCalls(opts?: { everyMs?: number; log?: Log }): () => void // logs 'delivery calls'
+ ```
+
+- [ ] **Step 1:** Write the tests:
+ - `'a reply marked nothing-new counts as empty, and bytes are summed per route'`;
+ - `'delivery calls counts re-claims within 10 s, receipt 403/404 and holds by reason, and logs nothing when empty'`.
+- [ ] **Step 2:** Run them: `npx vitest run src/lib/routeLatency.test.ts src/lib/deliveryCalls.test.ts`. Expected: FAIL.
+- [ ] **Step 3: Implement.**
+ - Each handler calls `markNothingNew` when its reply carries nothing new:
+ - changes with no changed parts;
+ - messages `after` with no rows;
+ - deliveries with none open;
+ - terminal with no request.
+ - `store.delivery` records `reclaim` when the same host claims the same delivery within 10 s, and `hold` with its reason.
+ - `deliveryReceipt` records its 403/404.
+ - `server.ts` starts and stops the `delivery calls` log beside `startRetryStats`.
+- [ ] **Step 4:** Run the tests and `npx tsc --noEmit`. Expected: PASS.
+
+### Task 2: delta carries host columns (backend)
+
+**Files:**
+- Modify: `backend/src/superTabs/parts/load.ts` (`CHANGED_FIELDS`, `changedPart`) and `parts/types.ts` (`Part`).
+- Test: `integration/superTabCache.test.ts` (`describe('loadDelta')`).
+
+**Interfaces:**
+- Produces: `Part.host?: { digest?: string; changedAt?: number }`, set by `changedPart` from `hostDigest` (groups) and
+ `hostChangedAt` (machines). Load paths never set it.
+
+- [ ] **Step 1:** Write the test `'loadDelta carries a group's hostDigest and a machine's hostChangedAt'`.
+- [ ] **Step 2:** Run: `npx vitest run --config vitest.super-tabs.config.ts integration/superTabCache.test.ts -t loadDelta`.
+ Expected: FAIL.
+- [ ] **Step 3: Implement.**
+ - Add `hostDigest: 1, hostChangedAt: 1` to `CHANGED_FIELDS`, and map them in `changedPart`.
+ - Every patch rule's `asLoaded` drops `host`, as it drops `readAt`.
+- [ ] **Step 4:** Run the cache unit and integration tests. Expected: PASS.
+
+### Task 3: `feed` patched (backend, Part 1.1)
+
+**Files:**
+- Modify: `backend/src/superTabs/cachePatch.ts`, `cachedReads.ts` (`readChanged`).
+- Test: `cachePatch.test.ts`, `cachedReads.test.ts`.
+
+**Interfaces:**
+- Produces: `export const feedRule: PatchRule<{ from: number; parts: Part[] }>`.
+ - Kinds: all seven.
+ - Merge by kind and key, newer version wins.
+ - Keeps tombstones, dormant groups and `readAt`; drops `host`.
+ - `from` unchanged.
+
+- [ ] **Step 1:** Write the tests:
+ - `'feedRule keeps tombstones, dormant groups and readAt, and the newer version'`;
+ - `'readChanged passes feedRule'`.
+- [ ] **Step 2:** Run them. Expected: FAIL.
+- [ ] **Step 3:** Implement. `readChanged` passes `feedRule` as the fifth argument of `view.get`.
+- [ ] **Step 4:** Run `npx vitest run src/superTabs`. Expected: PASS.
+
+### Task 4: one light selection and projection (backend, Part 1.2, shared core)
+
+**Files:**
+- Create: `backend/src/superTabs/parts/lightSelect.ts`.
+- Modify: `backend/src/superTabs/parts/light.ts` (`loadLight` and `lightGroup` use it).
+- Test: `parts/lightSelect.test.ts`, `parts/light.test.ts`.
+
+**Interfaces:**
+- Produces:
+ ```ts
+ export function projectLightGroup(group: Part<GroupData>): Part<GroupData> // GROUP_FIELDS always/whenRunning, as lightGroup
+ export interface LightCandidates { head: Part<HeadData>; members: Part[]; agents: Part<Agent>[]; starts: Part<AgentStart>[];
+ groups: Part<GroupData>[] } // groups: any superset of what is selected
+ export function lightSelect(c: LightCandidates, opts: { groups?: 'active' | 'working'; groupIds?: string[]; agentIds?: string[];
+ projectIds?: string[]; includeRecentStarts?: boolean }): Omit<SwarmParts, 'machines'>
+ ```
+- **Rule:**
+ - `loadLight` keeps its index reads as the candidate fetch, then returns `lightSelect(candidates, opts)`.
+ - The selection is written once: Lead conversations, running work, start- and invitation-named, undecided work, legacy
+ agents' awake groups, plus `groupIds`/`agentIds`/`projectIds` as `loadLight` reads them.
+
+- [ ] **Step 1:** Write the tests:
+ - `'projectLightGroup equals lightGroup of the projected row'`, for running and finished work and every `GROUP_FIELDS`
+ entry;
+ - `'lightSelect over all parts equals loadLight'`, on generated Swarms for `working`, `active`, and with agent, project
+ and group names.
+- [ ] **Step 2:** Run: `npx vitest run src/superTabs/parts`. Expected: FAIL.
+- [ ] **Step 3:** Implement, and move `loadLight`'s in-code selection into `lightSelect`.
+- [ ] **Step 4:** Run `npx vitest run src/superTabs` and `integration/superTabCache.test.ts`. Expected: PASS, with
+ `light.test.ts` unchanged.
+
+### Task 5: `light` and `host:state:{m}` derived from patched entries (backend, Part 1.2)
+
+**Files:**
+- Modify: `backend/src/superTabs/cachedReads.ts` (`readLight`) and `read/host.ts` (`tabState`, `hostParts`).
+- Test: `cachedReads.test.ts`, `read/host.test.ts`.
+
+**Interfaces:**
+- Consumes: `lightSelect`, `projectLightGroup` (Task 4); `readParts` entries (`parts`, `machines`,
+ `dormant:agent:{id}`, `light-group:{id}`).
+- Produces: `readLight` and `tabState` keep their signatures. On a cache miss their loader derives from the held entries,
+ not from Mongo. Without a view (`DIRECT`) they call `loadLight` as today.
+
+- [ ] **Step 1:** Write the tests:
+ - `'readLight derives from the held base and reads no Swarm collection'` (spied `db`, no calls);
+ - `'host:state derives the machine's agents' dormant conversations from dormant:agent entries'`;
+ - `'a machine whose agents all left derives an empty state'`.
+- [ ] **Step 2:** Run them. Expected: FAIL.
+- [ ] **Step 3: Implement.** The candidates are:
+ - the base;
+ - each named agent's `dormant:agent:{id}` (for `host:state`);
+ - `light-group:{id}` for named ids the base lacks.
+
+ Project the selected groups with `projectLightGroup`. The machines come from `readMachines`.
+- [ ] **Step 4:** Run `npx vitest run src/superTabs` and the integration `superTabs.test.ts` (host rows). Expected: PASS.
+
+### Task 6: `host:inputs` held as a patched map (backend, Part 1.3)
+
+**Files:**
+- Modify: `backend/src/superTabs/read/host.ts` (`inputs`), `cachePatch.ts`.
+- Test: `cachePatch.test.ts`, `read/host.test.ts`.
+
+**Interfaces:**
+- Produces:
+ ```ts
+ export interface HostInputs { head: number; members: Record<string, number>; agents: Record<string, number>;
+ starts: Record<string, number>; machines: Record<string, number>; groups: Record<string, string> } // digest + '0'|'1'; '' if missing
+ export const hostInputsRule: PatchRule<HostInputs | null> // kinds: head, member, agent, start, machine, group
+ export function hostInputsHash(inputs: HostInputs | null): string | null // today's sha256, same key order and slice
+ ```
+
+- [ ] **Step 1:** Write the tests:
+ - `'hostInputsHash equals today's hash for the same rows'` (golden from the current `inputs`);
+ - `'hostInputsRule moves only the changed keys, and a missing digest gives null'`.
+- [ ] **Step 2:** Run them. Expected: FAIL.
+- [ ] **Step 3: Implement.**
+ - The loader reads the map with today's five queries.
+ - `host.ts` compares `hostInputsHash(map)`.
+ - The entry is held at scope `main` with `hostInputsRule`.
+- [ ] **Step 4:** Run them. Expected: PASS.
+
+### Task 7: `startsOf` patched (backend, Part 1.4)
+
+**Files:**
+- Modify: `backend/src/superTabs/cachePatch.ts`, `read/service.ts` (`pollStarts`).
+- Test: `cachePatch.test.ts`.
+
+**Interfaces:**
+- Produces: `export function startsOfRule(agents: readonly string[]): PatchRule<Part<AgentStart>[]>`. A live start whose
+ `stableId(request.machineId, harnessId)` is in `agents` is added or replaced; otherwise it is dropped.
+
+- [ ] **Step 1:** Write the test `'startsOfRule follows starts in and out of the agent list'`.
+- [ ] **Step 2:** Run it. Expected: FAIL.
+- [ ] **Step 3:** Implement. `pollStarts` passes the rule.
+- [ ] **Step 4:** Run it. Expected: PASS.
+
+### Task 8: equivalence extended (backend)
+
+**Files:**
+- Modify: `backend/integration/superTabCacheDelta.test.ts`.
+
+- [ ] **Step 1:** Extend the existing test. After each of the 60 seeded writes, compare each entry with its direct load:
+
+ | Entry | Equals |
+ |---|---|
+ | `readChanged(view, since)` | `loadChanged(since)` |
+ | `readLight(view, LIGHT)` | `loadLight({groups:'working'})` |
+ | `tabState` for each machine | `hostParts` + `loadMachines` |
+ | the `host:inputs` hash | today's hash |
+ | `startsOf` | `loadStartsOfAgents` |
+
+ Compare by `cacheDigest`, and include machine readings and a machine leaving.
+- [ ] **Step 2:** Run: `npx vitest run --config vitest.super-tabs.config.ts integration/superTabCacheDelta.test.ts`.
+ Expected: PASS. A failure is a bug in Tasks 2–7: fix it there.
+- [ ] **Step 3:** Mutation-check.
+ - Drop the version guard in `feedRule`: expect FAIL.
+ - Drop running work from `lightSelect`: expect FAIL.
+ - Restore both.
+
+### Task 9: cheap receipt read and new pushes (backend, Parts 3.2, 3.4, 4.2)
+
+**Files:**
+- Modify: `backend/src/superTabs/store.ts`:
+ - `deliveryReceipt`;
+ - the cancel and answer writes at ~1518, 1525, 1693, 1701, 1714, 2281 and 3436 call `this.announce` for held
+ deliveries;
+ - the terminal request write calls a new `terminalWaiting` hook.
+- Modify: `backend/src/lib/swarmDeliveryPushes.ts` (a `__terminal_waiting` frame on the same machine channel) and the
+ route/worker wiring of the hooks.
+- Test: `store` unit or integration `superTabs.test.ts`, `swarmDeliveryPushes.test.ts`.
+
+**Interfaces:**
+- Produces:
+ ```ts
+ // store hooks
+ terminalWaiting?: (waiting: { machineId: string; tabId: string; agentId: string }) => void
+ // frame on the machine's down channel
+ { type: '__terminal_waiting', payload: { tabId, agentId } }
+ ```
+- `deliveryReceipt`:
+ - reads the delivery row and the machine row;
+ - checks owner, host and billing as today, and that the Swarm row is readable;
+ - loads the Swarm through the read cache only when the row lacks `machineOwnerId`.
+
+- [ ] **Step 1:** Write the tests:
+ - `'a receipt with machineOwnerId loads no Swarm parts'` (profiled reads);
+ - `'cancelling or answering a held delivery tells its machine'`;
+ - `'a terminal request tells its machine with __terminal_waiting'`;
+ - `'a frame an older daemon sees is a __ control frame or a delivery push it already reads'`.
+- [ ] **Step 2:** Run them. Expected: FAIL.
+- [ ] **Step 3:** Implement. `TERMINAL_PICKUP_MS` stays 10 s.
+- [ ] **Step 4:** Run `npx vitest run src/lib src/superTabs`, the integration `superTabs.test.ts`, and `npx tsc --noEmit`.
+ Expected: PASS.
+
+### Task 10: held deliveries retried locally (CLI, Part 3.1–3.3, 3.5)
+
+**Files:**
+- Modify: `cli/src/superTabs/host.ts`:
+ - `accept` ~1719;
+ - `heard` ~2099;
+ - the list read ~1011–1082;
+ - `pushed` ~658;
+ - the write lease ~1716 and ~1777.
+- Test: `cli/src/superTabs/host.spec.ts` (or the host's existing spec).
+
+**Interfaces:**
+- Produces:
+ - `const HELD_RECLAIM_MS = 120_000`, `const HELD_LIST_MS = 30_000`.
+ - A refused write (`team_waiting_*`, dialog, draft, unavailable screen) keeps the claimed message in a per-delivery map.
+ It is retried on each tick and re-claimed at most every `HELD_RECLAIM_MS`; `hold` is sent once, as today.
+ - A held agent's list is read every `HELD_LIST_MS` and on push.
+ - `busy` is computed from the list after the pass's acks.
+ - The write lease is taken per agent right before its write.
+
+- [ ] **Step 1:** Write the tests, with a fake core that refuses then accepts, and a fake backend:
+ - `'a held delivery makes no claim for 2 minutes and is written once the pane frees'`;
+ - `'a cancel pushed while held stops the retry'`;
+ - `'a cancel missed by push stops the retry at the next 30 s read'`;
+ - `'an acked message costs no extra list read'`;
+ - `'a slow pass does not refuse writes for an expired lease'`.
+- [ ] **Step 2:** Run: `npx vitest run src/superTabs/host`. Expected: FAIL.
+- [ ] **Step 3:** Implement. Re-link signed files on retry (`relink`).
+- [ ] **Step 4:** Run the host specs and `npm run typecheck`. Expected: PASS.
+
+### Task 11: receipt checks back off and retire (CLI, Part 3.4)
+
+**Files:**
+- Modify: `cli/src/superTabs/host.ts` (`checkReceipts` ~849 and the journal entry type).
+- Test: the host spec.
+
+**Interfaces:**
+- Produces:
+ - Journal entry fields `nextCheckAt: number` and `checkFails: number`, persisted.
+ - Back-off: 5 s doubling to 5 min.
+ - Retire on 404, on codes `ackRefused` treats as final, or when older than 25 h. Never retire on `HOST_UNAVAILABLE`.
+ - An entry the last list showed is skipped.
+
+- [ ] **Step 1:** Write the tests:
+ - `'a failing entry backs off to 5 minutes'`;
+ - `'404 and final codes retire, HOST_UNAVAILABLE does not'`;
+ - `'an entry older than 25 h retires'`;
+ - `'back-off resumes from the journal after a restart'`;
+ - `'an entry the list shows is not asked about'`.
+- [ ] **Step 2:** Run them. Expected: FAIL.
+- [ ] **Step 3:** Implement.
+- [ ] **Step 4:** Run them. Expected: PASS.
+
+### Task 12: terminal pickup by push (CLI, Part 4.2)
+
+**Files:**
+- Modify: `cli/src/superTabs/terminal.ts` (`SERVE_EVERY_MS` ~22) and the gateway's `backendControl` (`gateway.ts`), which
+ hands `__terminal_waiting` to the core's notices.
+- Test: `terminal.spec.ts`, `gateway.spec.ts`.
+
+**Interfaces:**
+- Produces:
+ - `export const SERVE_EVERY_MS = 3_000` and `export const SERVE_PUSHED_EVERY_MS = 8_000`.
+ - The 8 s interval applies while the delivery push lease is held.
+ - A `__terminal_waiting` notice triggers an immediate pickup.
+
+- [ ] **Step 1:** Write the tests:
+ - `'with the push lease, polls every 8 s and picks up at once on __terminal_waiting'`;
+ - `'without it, polls every 3 s'`.
+- [ ] **Step 2:** Run them. Expected: FAIL.
+- [ ] **Step 3:** Implement.
+- [ ] **Step 4:** Run `npx vitest run src/superTabs src/gateway`. Expected: PASS.
+
+### Task 13: telemetry cadence (CLI, Part 4.1)
+
+**Files:**
+- Modify: `cli/src/gateway/productUsage.ts` (`TICK_MS` ~27, `syncOnce` ~296).
+- Test: `productUsage.spec.ts`.
+
+**Interfaces:**
+- Produces:
+ - Settings GET at start, after a local `choice()`, and when `SETTINGS_EVERY_MS = 3_600_000` has passed.
+ - Report POST every `REPORT_EVERY_MS = 300_000`, from the on-disk queue.
+ - `CHOICE_CHANGED` still re-reads settings at once.
+
+- [ ] **Step 1:** Write the tests:
+ - `'settings are read at start, on a local choice, hourly, and on CHOICE_CHANGED only'`;
+ - `'reports go every 5 minutes'`.
+- [ ] **Step 2:** Run them. Expected: FAIL.
+- [ ] **Step 3:** Implement.
+- [ ] **Step 4:** Run them. Expected: PASS.
+
+### Task 14: cards, fleet machine list, experiments (CLI, Part 4.3–4.5)
+
+**Files:**
+- Modify:
+ - `cli/src/superTabs/cards.ts` (`intervalMs` ~269, the tick ~300);
+ - `cli/src/device/machineList.ts` (`MachineListCache.refresh`);
+ - `cli/src/services/fleet.ts`;
+ - `cli/src/core/experiments.ts` (~135).
+- Test: `cards.spec.ts`, `machineList.spec.ts`, `fleet.spec.ts`, `experiments.spec.ts` (core: run `npm run test:core`).
+
+**Interfaces:**
+- Produces:
+ - **Cards:** read `list` only when told by `swarm_changed` (main parts) or after a `CARDS_SAFETY_MS = 120_000` gap, while
+ the push lease holds; 5 s without it.
+ - **`MachineListCache.refresh({ maxAgeMs })`:** joins a read in flight, and returns the held list when it is younger than
+ `maxAgeMs`. The fleet passes `45_000`, refreshes every 5 min, and on `machines_changed` with `maxAgeMs: 0`. The window
+ path passes `0`.
+ - **Experiments:** `desk_changed` triggers a read only when its `revision === 0`.
+
+- [ ] **Step 1:** Write the tests:
+ - `'cards read on push and every 2 minutes, every 5 s without the lease'`;
+ - `'the fleet's machine list is served for 45 s and refreshed on machines_changed, a window always reads'`;
+ - `'a desk operation's desk_changed reads no experiments, a revision-0 one does'`.
+- [ ] **Step 2:** Run them. Expected: FAIL.
+- [ ] **Step 3:** Implement.
+- [ ] **Step 4:** Run the specs and `npm run test:core`. Expected: PASS at 100% for the core and services files touched.
+
+### Task 15: Desktop reads messages by the open conversation's counters (Desktop, Part 2)
+
+**Files:**
+- Modify:
+ - `desktop/lib/super_tabs/controller.dart`: `_pollDue` ~523, `_receiptOpen` ~531, `_read`/`refresh` early read ~3148,
+ the messages gate ~3158–3292, `_loadMessages` ~3785;
+ - `desktop/lib/super_tabs/model.dart`: parse `reactionSeq` and `messageSeq`.
+- Test:
+ - `desktop/test/super_tab_reading_test.dart`;
+ - update `super_tab_reactions_test.dart`, `super_tab_message_paging_test.dart` and `super_tab_saved_view_test.dart`.
+
+**Interfaces:**
+- Produces:
+ - Per open conversation, the controller remembers `readMessageSeq` and `readReactionSeq`.
+ - A messages read happens only when the conversation's `lastMessageSequence > readMessageSeq` (`after`) or
+ `reactionSeq != readReactionSeq` (page re-read), plus first reads, saved views and `_latestWanted`.
+ - No early read in parallel with the state read.
+ - `_receiptOpen` counts queued, claimed and uncertain only, within 10 min (60 min held). The own message refreshes with
+ `?messageId=` every 30 s.
+
+- [ ] **Step 1:** Write the tests:
+ - `'no messages read while the open conversation's counters are unchanged, whatever else in the Swarm or its machines
+ changed'`;
+ - `'a change in another Swarm reads nothing here'`;
+ - `'one after read when lastMessageSequence moves'`;
+ - `'a page re-read only when reactionSeq moves'`;
+ - `'the own receipt refreshes by messageId every 30 s and stops after its bound'`.
+ - Update "each poll reads the state, then the messages" to the new rule.
+- [ ] **Step 2:** Run: `cd desktop && flutter test test/super_tab_reading_test.dart`. Expected: FAIL.
+- [ ] **Step 3:** Implement.
+- [ ] **Step 4:** Run `flutter test test/super_tab_*` and `flutter analyze`. Expected: PASS.
+
+### Task 16: validation, review and measurement
+
+- [ ] **Step 1:** Typecheck backend and CLI; run `flutter analyze` for Desktop.
+- [ ] **Step 2:** Run the full suites:
+ - backend unit with `REDIS_TEST_URL`;
+ - backend integration;
+ - CLI `npm test`, compared with `main`'s known failures;
+ - CLI `npm run test:core`;
+ - Desktop `flutter test`.
+- [ ] **Step 3:** Run the CLI e2e for delivery and terminal: `npm run test:e2e -- delivery terminal` (the closest e2e specs).
+- [ ] **Step 4:** One independent reviewer (Opus) on the whole diff, with the spec, this plan and its Review Focus. Fix
+ Critical and Important findings test-first.
+- [ ] **Step 5:** After each release, compare against the spec's numbers:
+ - `route latency` empty counts and per-route requests;
+ - `delivery calls`;
+ - `swarm cache` full loads per entry;
+ - `cpu by kind` and the profile.
+
+ Report to Ken. Do not commit until he asks.
diff --git a/docs/superpowers/specs/2026-11-02-poll-cost-design.md b/docs/superpowers/specs/2026-11-02-poll-cost-design.md
new file mode 100644
index 000000000..81dc772ff
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-02-poll-cost-design.md
@@ -0,0 +1,288 @@
+# Backend CPU from polling: fewer and cheaper reads, server, Desktop and CLI
+
+**Status:** draft for review · **Owner:** Ken · **Area:** backend (`superTabs/cache*.ts`, `cachedReads.ts`, `read/*`,
+`store.ts`), Desktop (`desktop/lib/super_tabs/controller.dart`), CLI daemon (`cli/src/superTabs/host.ts`, `terminal.ts`,
+`cards.ts`, `gateway/productUsage.ts`, `core/experiments.ts`, `machineList.ts`)
+**Follows:** [2026-11-02-swarm-cache-delta-design.md](2026-11-02-swarm-cache-delta-design.md) (#2519, released in v1.3.85).
+#2394 (measure 1 minute in 10) stays held, as Ken decided.
+
+## Why
+
+Prod on v1.3.85, 2026-11-02 08:30–08:50Z, 4 pods, ~4,180 requests/min.
+
+The delta cache works: verify sample 0 mismatches, `parts` served 84% hit, 13% patched, 3% full. DB bytes per request
+fell from 145 to 102 KB. But CPU per request is flat (~32.6 ms), because most of what is left is **polling**: reads repeated
+whether or not anything changed for the reader.
+
+| Source | Measured | Cause (traced in code, file:line in the traces below) |
+|---|---|---|
+| Cache entries still reloaded whole on every bump: `feed`, `host` (almost all of it `host:state:{machineId}`, the light Swarm each machine's host rows are built from; `host:inputs` is a 22-character hash), `light`, `startsOf` | 610 + 273 + 170 + 80 MB per 20 min, against 11 MB for `parts`; `freeze` 6.4% of the JS thread | They have no patch rule (non-goal of the last spec) |
+| Desktop's messages reads | person `after` 237/min, ~0 rows each; person bare `before` 234/min, ~131 rows decoded each | Every `after` that comes back empty is followed by a re-read of the 100-row page shown (`controller.dart:3785-3795`). The read is triggered by any change anywhere in the Swarm, including each machine's reading every 15 s, and by `_receiptOpen`, which stays true for `delivered`/`confirmed` until an agent replies with `replyTo` (`controller.dart:524,531-545`): in practice forever |
+| Daemon delivery loop | list GET 294/min, claim/ack/hold POST 414/min, receipt GET 318/min (25% of all requests) | A held delivery is re-claimed every second, for up to 24 h (`host.ts:1719` with `:2099-2104`). Receipt checks ask every 5 s with no limit and keep asking after 403/404 (`host.ts:843-873`). Each receipt GET loads a whole Swarm (`store.ts deliveryReceipt`). `busy` is taken before the ack, costing one more list read per message (`host.ts:1082`) |
+| Daemon telemetry | settings GET 330/min, report POST 284/min | Every 45–75 s per gateway, though the report already carries the settings revision (`productUsage.ts:299,350,380`) |
+| Terminal pickup | `hosts/:m/terminal` 305/min, almost always empty; each a transaction | Every 3 s on daemons hosting Swarm agents (`terminal.ts:22,163-166`) |
+| Lists | `super-tabs/list` 279/min, `machines` 227/min, `experimental-settings` 127/min | Pro cards poll `list` every 5 s, ignoring pushes (`cards.ts:269,300,376`); `MachineListCache` has no TTL (`machineList.ts:140`); every desk operation makes every daemon and window re-read experiment settings (`core/experiments.ts:135`, `desk.ts:56`) |
+
+The traces' findings are from code reading. Prod rates fit them (see each part). Part 0 adds the counters that turn the
+estimates into measurements.
+
+## Goal
+
+Cut what polls cost the backend, without making anything a person sees wrong or noticeably late:
+
+- **Fewer requests:** about −1,500 requests/min (−35%) at today's load, mostly empty or repeated ones.
+- **Cheaper reads:** the four remaining whole reloads become patches, which removes most of `freeze`'s 6.4% and a share of
+ Prisma's 21%.
+- **Measured success:** CPU per request and per minute in `cpu by kind`, requests per route in `route latency`, and the
+ new counters, before and after each release.
+
+### Non-goals
+
+- **#2394, the measurement windows:** held.
+- **Pushing deltas over WebSocket instead of "told, then read":** an architecture change for its own spec. This spec only
+ removes reads that tell nothing new.
+- **The phone:** it already reads messages by its counters. Making it honour `swarm_changed` instead of polling `/changes`
+ every 5 s is a later, separate change.
+- **Message history retention and compaction:** spec 5.
+
+### Anti-goals
+
+- **No missed messages or answers:** a message, an answer or an agent's work must never show late beyond the bounds stated
+ here.
+- **No lost deliveries:** a held delivery must still reach its agent when the pane frees, and a receipt must still be acked.
+- **No silent staleness:** every new wait has a stated bound, and a fallback read when a push is lost.
+
+## Part 0 — counters first (backend, ships with Part 1)
+
+The counters go into the existing minute logs; they record counts only, never ids or content:
+
+- **`route latency`:** per route, how many replies carried nothing new. That means `GET changes` with no changed parts,
+ `GET messages` `after` with no rows, `GET deliveries` with nothing open, and `hosts/:m/terminal` with no request. Also
+ bytes out per route.
+- **`messages by reader`** (already there): unchanged.
+- **New `delivery calls` log:**
+ - claims of a delivery already claimed by the same host within 10 s, counted as re-claims;
+ - receipt GETs answering 403/404;
+ - holds by reason.
+
+## Part 1 — the last four whole reloads become patches (backend)
+
+Builds on `SwarmCache`'s delta (one per Swarm and stamp, `cache.ts deltaFor`). Each entry gets a patch rule, or is derived
+from an entry that has one. The equivalence test of #2519 extends to each.
+
+1. **`feed`** (the change feed `GET changes` reads: parts changed after `from`, `cachedReads.ts readChanged`):
+ - **Rule:** merge the delta's parts by kind and key, keeping the newer version. The feed keeps tombstones, dormant
+ groups and machines' `readAt`, as `loadChanged` returns them, so this rule keeps `readAt`, unlike the base's.
+ - `from` stays as loaded. The feed grows until its 10-minute full reload. A busy Swarm changes about 80 parts in 5 min,
+ so that is bounded.
+ - Kinds: all seven, machines by `readAt` too. The feed is scoped `all`, so a machine reading patches it with machine
+ parts only.
+2. **`light` and `host:state:{machineId}`** (`readLight`, the light base `GET changes` reads; `read/host.ts tabState`, the
+ light Swarm a machine's host rows are built from):
+ - **Derived, not loaded:** both are `loadLight` selections, built in memory from entries that are already patched. The
+ inputs are:
+ - the `parts` entry and `machines`;
+ - `dormant:agent:{id}` (Phase 2 of the last spec) for the dormant conversations of a machine's agents;
+ - `light-group:{id}` for a named conversation the base lacks.
+ - `light` is `groups: 'working'`:
+ - Lead conversations;
+ - running work;
+ - conversations named by an unfinished start or an invitation;
+ - undecided work;
+ - legacy agents' awake groups.
+ - `host:state:{m}` adds that machine's agents' conversations (dormant ones too), its starts' conversations and their
+ projects' awake ones (`read/host.ts hostParts`).
+ - Conversations are projected through `GROUP_FIELDS` as `lightGroup` does.
+ - Each is held per Swarm and stamp, under today's name and scope.
+ - The selection and the projection move to one function that `loadLight` also uses, so the loaded and derived forms
+ cannot drift.
+3. **`host:inputs`** (`read/host.ts inputs`, the signature behind `unchanged` answers to machines). It is a small value, but
+ recomputing it reads every live row's stamps from five collections:
+ - **Held as a map, not a hash:** the head's `changedAt`, and `key → changedAt` for members, agents and starts. Also
+ `key → hostChangedAt` for machines, and `key → hostDigest + dormant` for every live group.
+ - **Rule:** patch the map from the delta. The delta's projection adds `hostDigest` and `hostChangedAt`.
+ - The hash is computed from the map in key order, exactly as today.
+ - **Superseded:** main landed `read/hostInputs.ts` first (`host:groups` patched by `hostGroupsRule`, the same etag
+ format). It patches the conversations, the long part, and still reads the other four collections' stamps. This branch
+ uses it and drops its own map.
+ - Scope `main`: a machine's own reading leaves `hostChangedAt`, so it moves no machine stamp here.
+4. **`startsOf:{agents}`** (`read/service.ts pollStarts`):
+ - **Rule:** a live start whose agent (`stableId(machineId, harnessId)`) is in the entry's list is added or replaced; a
+ tombstone, or a start whose agent left the list, goes.
+
+**Expected:** these four were ~1.1 GB of whole reloads per 20 min. After this change they should be about the size of the
+`parts` entry's patches (~10–20 MB per 20 min).
+
+## Part 2 — Desktop reads messages by the open conversation's own counters (Desktop)
+
+1. **Trigger:**
+ - The open conversation's messages are read only when its counters moved since what is shown:
+ `lastMessageSequence` (or `lastMainSequence`) above the held tail, or `reactionSeq` changed.
+ - These come with every `/changes` and `/parts` read (`read/contract.ts:35-38`). Desktop parses `reactionSeq` and
+ `messageSeq` into the conversation model.
+ - Swarm-wide signals stop triggering a messages read: `read.changed`, `lastChangedAt`, `_toldMachine` and `_toldMain`.
+ - **My call: the early read is dropped.** Today a push starts the messages read in parallel with the state read. After
+ this change the messages read follows the state read that showed the counter move, so a reply shows one `/changes`
+ round trip later (tens of ms). Kept, the early read would fire on every Swarm-wide push and keep most of today's reads.
+ - **My call: the trigger is `lastMessageSequence`,** not `lastMainSequence`, because `after` pages also bring thread
+ replies and their summaries.
+ - **My call: Desktop remembers the counter value it last read,** not only the held tail, so a message hidden from the
+ reader costs one empty `after`, not one per poll.
+ - First reads, saved views (`_showingSaved`) and `_latestWanted` still read the latest page.
+2. **No page re-read after an empty `after`** (`controller.dart:3785-3795`), unless `reactionSeq` moved. A message the reader
+ cannot see still moves the sequence; that costs one empty `after`, which is cheap.
+3. **Receipts:**
+ - `_receiptOpen` uses the phone's set: queued, claimed, uncertain. It is bounded by time: 10 minutes, or 60 for held
+ deliveries (`swarm_conversation.dart:1074-1081,1123`).
+ - The person's own message is refreshed with `?messageId=`: one row every 30 s, not the 100-row page every 3 s.
+ - **Cost, my call:** a "Delivered → Answered" receipt on other rows of the page updates on the next real read rather
+ than within 3 s.
+4. **Unchanged:** the 3 s poll of `/changes`, the 15 s cadence off screen, and the push gating.
+
+**Expected:** about 234 page re-reads/min and most of the 237 empty `after` reads are removed. That is roughly a third of the
+`messages` route, ~11% of the JS thread, and the route's heaviest reads.
+
+## Part 3 — the daemon's delivery loop (CLI, plus one backend change)
+
+1. **A held delivery is retried locally.**
+ - When the core refuses a write (dialog, draft, screen unavailable, `team_waiting_*`), the host keeps the claimed message
+ in memory and retries the write on its own tick.
+ - It re-claims at most every 2 min, well inside the backend's claim quiet time of 10 min (`deliverySettle.ts:13`), and
+ sends `hold` once, as today.
+ - The core's write lease is renewed locally.
+ - Signed file links that expire are re-linked (`relink` exists).
+2. **A held agent's list is read every 30 s and on push, not every second.**
+ - The backend also pushes `super_tab_deliveries` when a delivery is cancelled or answered while held. Today it pushes
+ only on new deliveries, so it must, or a cancel would wait 30 s.
+3. **`busy` is computed after the pass**, so an acked message costs no extra list read.
+4. **Receipt checks:**
+ - An entry the list already shows is not asked about.
+ - Each entry backs off: 5 s doubling to 5 min.
+ - An entry is retired on a final refusal, or after 25 h:
+ - final means the codes `ackRefused` already treats as final, and 404;
+ - **my call:** a `HOST_UNAVAILABLE` from a billing lapse is not final, since it ends when billing returns.
+ - On the backend, `deliveryReceipt` answers from the delivery row and the machine row. It loads the Swarm (through the
+ read cache, not a command transaction) only when the row lacks `machineOwnerId`. It keeps the Swarm-row check (the Swarm
+ still exists and is readable).
+5. **The pass's write lease** (2.5 s, `host.ts:1716,1777`) is taken per agent right before its write, not once before a pass
+ over every agent, so a slow pass no longer turns into refusals and re-claims.
+
+**Expected:**
+- claim POSTs: 414 → ~60/min;
+- list GETs: 294 → ~120/min;
+- receipt GETs: 318 → ~40/min, each also much cheaper.
+
+## Part 4 — the other daemon polls (CLI)
+
+1. **Telemetry:**
+ - Settings are read at start, on a local settings change, and hourly.
+ - Reports go every 5 minutes from the queue already on disk. The report's `revision` already makes the backend refuse
+ counts after an opt-out elsewhere (`CHOICE_CHANGED`).
+ - Expected: 330 → ~10/min settings, 284 → ~50/min reports.
+2. **Terminal pickup** (my calls, from the builder check):
+ - **Backend:** when a terminal request waits for a machine, it pushes a new control frame `__terminal_waiting` on that
+ machine's channel. It ships in release step 1. The `__` prefix makes older daemons drop it silently, as they drop
+ `__tui_open`.
+ - **Daemon:** a daemon that has heard the backend push in the last 5 minutes (the delivery push lease it already keeps)
+ picks up on the push and polls every 8 s as a fallback. Without that lease it polls every 3 s, as today.
+ - **The backend's pickup deadline stays 10 s for every host,** so a Lead still learns quickly when a machine is gone, and
+ old daemons keep working unchanged.
+ - Expected: 305 → ~115/min.
+3. **Pro cards' `list`:** follow the `swarm_changed` push lease as Desktop does, with a 2 min safety net. Expected: −200/min.
+4. **`MachineListCache`** (my call, from the builder check):
+ - The 45 s TTL applies only to the fleet's own refresh (`services/fleet.ts`), which moves from every 60 s to every
+ 5 min plus on `machines_changed`.
+ - A window's `/api/machines` (`gateway/accountHttp.ts`) gets no TTL; it only joins a read already in flight. A window
+ re-reading after `machines_changed`, or after its own rename, create or delete, still sees the change at once.
+ - Expected: about −60/min.
+5. **Experiment settings:**
+ - Re-read only on `desk_changed` with revision 0, which is what experiment changes publish (`experimentalSettings.ts:31`).
+ - Desk operations publish their own revision.
+ - Expected: most of 127/min.
+
+## Release order and switches
+
+1. **Backend first: Part 0, Part 1, the backend side of Part 3.4, Part 3.2's push and Part 4.2's `__terminal_waiting`.** Part 1 rides `SWARM_CACHE_DELTA`
+ (off: today's reloads). The receipt read and the extra push need no switch; older daemons ignore an extra push.
+2. **CLI:** Parts 3 and 4. Each falls back to today's cadence when the backend has not said it pushes (the leases that
+ already exist).
+3. **Desktop:** Part 2.
+
+Each release is judged against its own counters before the next.
+
+## Design (AGENTS.md checklist)
+
+- **Growth:**
+ - `feed` grows until its 10-minute full reload (bounded by a Swarm's changes in 10 min); `light` and `host:inputs` hold
+ one value per Swarm and stamp. All of these stay within the LRU's byte budget.
+ - The daemon keeps held messages in memory, at most one per delivery, freed on ack, cancel or settle.
+ - The receipt journal still retires entries; it now also retires failing ones.
+- **Concurrency:**
+ - Cache entries follow the delta cache's rules: no locks, one delta per Swarm and stamp.
+ - A delivery's claim still guards it on the backend. A local retry never writes twice: the core's write lease and the
+ claim id are kept.
+- **Read cost:**
+ - Part 1: reads only what changed.
+ - Part 2: reads messages only when the conversation's counters say so.
+ - Part 3: the receipt is read from its row.
+ - Part 4: settings and lists are read on change, or on a long timer.
+- **Scale:** at 10x daemons or viewers, requests grow with real changes, not with time × clients. First warnings: `route
+ latency` nothing-new counts, `delivery calls` re-claims, and `swarm cache` full loads.
+- **Compatibility:**
+ - Old Desktops and daemons keep working against the new backend.
+ - The new clients against an old backend fall back to today's cadence, through the push leases they already read.
+ - No API or response shape changes. The only additions are the extra delivery pushes, the `__terminal_waiting` frame
+ (dropped by older daemons) and the delta projection's fields.
+- **Migration and rollback:**
+ - Nothing is stored except daemon journal fields for back-off.
+ - Backend: `SWARM_CACHE_DELTA=off`, or the previous release.
+ - Clients: the previous release.
+- **Audience:**
+ - Permissions are applied after the cache, as today (`readerView`).
+ - The receipt read keeps its owner, host and billing checks; only the way it finds them changes.
+ - The `?messageId=` read is the same route, with the same checks.
+- **Identity:** nothing new is keyed by, or sent as, the machine owner's login.
+- **Failure:**
+ - A lost push costs at most the stated fallback: 30 s for deliveries and terminal pickup, 2 min for cards and lists.
+ - A failing receipt check backs off and is retired, and is counted in `delivery calls`.
+ - A cache entry that cannot be patched loads in full, as today.
+- **Platforms:**
+ - Backend on Linux pods.
+ - The CLI daemon on macOS, Linux and Windows: the timers are the same code on all three.
+ - Desktop on macOS, Windows and Linux, and the web build. The web build shares `SuperTabController`, so Part 2 applies
+ to it too.
+
+## Tests
+
+- **Part 0:** each counter, counts only, including the empty-window rule.
+- **Part 1:**
+ - extend #2519's equivalence test: after each of 60 seeded writes, `feed` equals `loadChanged(from)`, `light` equals
+ `loadLight({groups:'working'})`, `host:state:{m}` equals `hostParts` for each machine, `host:inputs` equals today's hash, and `startsOf` equals `loadStartsOfAgents`;
+ - a test that `loadLight` and the derived light share one selection and projection.
+- **Part 2** (Desktop widget and controller tests):
+ - no messages read while the open conversation's counters are unchanged, whatever else in the Swarm or its machines
+ changed;
+ - one `after` read when `lastMessageSequence` moves;
+ - a page re-read only when `reactionSeq` moves;
+ - the own-receipt refresh by `?messageId=` stops after its bound.
+ - Update `super_tab_reading_test.dart` "each poll reads the state, then the messages" and the paging, reaction and
+ saved-view tests that assert `?before=`.
+- **Part 3** (CLI, `npm run test:core` scope where the files are core or service, or the host's own specs):
+ - a held delivery makes no claim for 2 min and is written once the pane frees;
+ - a cancel pushed while held stops the retry;
+ - `busy` after the ack causes no extra list read;
+ - receipt back-off, retirement on 403/404 and after 25 h;
+ - `deliveryReceipt` makes no Swarm load when the row names its owner (backend).
+- **Part 4:** each cadence, each push path, each fallback when the push lease lapses, and experiment re-reads only on
+ revision 0.
+- **End to end:** the CLI's e2e suite for delivery (a held pane, then freed) and for terminal pickup by push.
+
+## Risks
+
+| Risk | Mitigation |
+|---|---|
+| Desktop misses a message because a counter did not move | A posted message always moves `lastMessageSequence` (store writes it with the message); the 60 s safety net stays |
+| A delivery held in memory is lost on a daemon restart | It is still claimed on the backend; after restart the list shows it again and the normal path resumes (as today after a crash) |
+| A receipt entry is retired wrongly, so a late ack is lost | Retire only on 403/404 or after 25 h, past the backend's longest hold; count every retirement |
+| The derived light base drifts from `loadLight` | One shared selection and projection; equivalence test after every seeded write |
+| Telemetry lags or over-collects after an opt-out elsewhere | Bounded to 5 min; the backend's revision check refuses stale counts |
diff --git a/mobile/lib/swarm/swarm_conversation_page.dart b/mobile/lib/swarm/swarm_conversation_page.dart
index d94ac84fa..7b56ce2c1 100644
--- a/mobile/lib/swarm/swarm_conversation_page.dart
+++ b/mobile/lib/swarm/swarm_conversation_page.dart
@@ -50,6 +50,7 @@ import 'swarm_reactions.dart';
import 'swarm_read_marks.dart';
import 'swarm_session.dart';
import 'swarm_style.dart';
+import 'swarm_task_line.dart';
import 'swarm_thread.dart';
import 'swarm_thread_line.dart';
import 'swarm_thread_page.dart';
@@ -914,6 +915,20 @@ class _SwarmConversationPageState extends State<SwarmConversationPage>
);
}
+ VoidCallback? _taskOpener(SwarmConversation c, SuperTabMessage message) {
+ final taskId = message.source['taskId'];
+ if (!swarmIsTaskLine(message) ||
+ taskId is! String ||
+ c.reader.snapshot?.conversation(taskId) == null) {
+ return null;
+ }
+ return () {
+ if (c.reader.snapshot?.conversation(taskId) != null) {
+ openSwarmConversation(context, widget.swarmId, taskId);
+ }
+ };
+ }
+
/// One of thread [t]'s messages as the chat draws its own, less what only
/// the chat has: no quote, no thread line, no Reply (the box is the reply).
Widget _threadRow(
@@ -940,6 +955,7 @@ class _SwarmConversationPageState extends State<SwarmConversationPage>
tagged: _taggedOf(c, m).keys.toList(),
taggedAddresses: _taggedOf(c, m),
readerId: c.reader.accountId,
+ onOpenTask: _taskOpener(c, m),
grouped: grouped,
lit: lit,
followed: followed,
@@ -1687,12 +1703,14 @@ class _SwarmConversationPageState extends State<SwarmConversationPage>
stream,
(agentId) => snapshot?.agent(agentId),
);
- final messages = answered.isEmpty
- ? stream
- : [
- for (final m in stream)
- if (!answered.contains(m.id)) m,
- ];
+ final messages = swarmTaskLineMessages(
+ answered.isEmpty
+ ? stream
+ : [
+ for (final m in stream)
+ if (!answered.contains(m.id)) m,
+ ],
+ );
// The notes hidden are part of what the rows were made from: a warning
// goes once its agent's prompt is answered, with no new message.
final from = (
@@ -1790,6 +1808,12 @@ class _SwarmConversationPageState extends State<SwarmConversationPage>
key,
(
m,
+ // Drop a cached opener when access to its target changes.
+ snapshot?.conversation(
+ m.source['taskId'] is String
+ ? m.source['taskId'] as String
+ : '',
+ ),
card,
name,
swarmLookKey(look),
@@ -1828,6 +1852,7 @@ class _SwarmConversationPageState extends State<SwarmConversationPage>
tagged: tagged.keys.toList(),
taggedAddresses: tagged,
readerId: c.reader.accountId,
+ onOpenTask: _taskOpener(c, m),
grouped: grouped,
lit: lit,
followed: followed,
@@ -2674,6 +2699,8 @@ String swarmDayLabel(DateTime day, DateTime now) {
Set<String> swarmGroupedMessages(List<SuperTabMessage> messages) {
bool joins(SuperTabMessage current, SuperTabMessage previous) {
bool plain(SuperTabMessage m) =>
+ !swarmIsTaskLine(m) &&
+ m.source['kind'] != 'ship' &&
m.replyTo == null &&
m.text.length <= 280 &&
!m.text.contains('\n') &&
diff --git a/mobile/lib/swarm/swarm_message_row.dart b/mobile/lib/swarm/swarm_message_row.dart
index f11680050..0645cc784 100644
--- a/mobile/lib/swarm/swarm_message_row.dart
+++ b/mobile/lib/swarm/swarm_message_row.dart
@@ -19,6 +19,7 @@ import 'swarm_code_block.dart';
import 'swarm_file_links.dart';
import 'swarm_face.dart';
import 'swarm_ship_row.dart';
+import 'swarm_task_line.dart';
/// The chat's prose in the app's own face, as prototype v2 draws it: the
/// messages, quotes, names and the field. Times, roles and day dividers stay
@@ -291,6 +292,7 @@ class SwarmMessageRow extends StatelessWidget {
this.receipt,
this.card,
this.onLongPress,
+ this.onOpenTask,
});
final SuperTabMessage message;
@@ -324,6 +326,9 @@ class SwarmMessageRow extends StatelessWidget {
final Widget? quote;
final VoidCallback onTap;
+ /// Opens a task held by the current reader; null for an unavailable target.
+ final VoidCallback? onOpenTask;
+
/// Null where the person cannot post, or in the thread itself.
final VoidCallback? onReply;
@@ -375,6 +380,14 @@ class SwarmMessageRow extends StatelessWidget {
@override
Widget build(BuildContext context) {
+ if (swarmIsTaskLine(message)) {
+ return SwarmTaskLine(
+ key: ValueKey('swarm-message-${message.id}'),
+ message: message,
+ readerId: readerId,
+ onOpen: onOpenTask,
+ );
+ }
// A ship line is a card, not a message from its author.
if (swarmShips(message)) {
return SwarmShipRow(
diff --git a/mobile/lib/swarm/swarm_task_line.dart b/mobile/lib/swarm/swarm_task_line.dart
new file mode 100644
index 000000000..b92c4afc6
--- /dev/null
+++ b/mobile/lib/swarm/swarm_task_line.dart
@@ -0,0 +1,141 @@
+import 'package:flutter/material.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
+
+import 'package:harness_mobile/shared/theme/app_space.dart';
+import 'package:harness_mobile/shared/theme/app_theme.dart';
+
+import 'model.dart';
+import 'swarm_message_row.dart' show swarmChatText;
+
+/// The server edits this message in place as its task moves.
+bool swarmIsTaskLine(SuperTabMessage message) =>
+ message.source['kind'] == 'task-line';
+
+/// A task's line replaces its older Shipped card in the loaded chat window.
+/// A ship for another task, or without a replacement here, remains visible.
+List<SuperTabMessage> swarmTaskLineMessages(List<SuperTabMessage> messages) {
+ final lined = <String>{
+ for (final message in messages)
+ if (swarmIsTaskLine(message) && message.source['taskId'] is String)
+ message.source['taskId'] as String,
+ };
+ if (lined.isEmpty) return messages;
+ return [
+ for (final message in messages)
+ if (!(message.source['kind'] == 'ship' &&
+ lined.contains(message.source['conversationId'])))
+ message,
+ ];
+}
+
+/// Desktop's task words; a future state makes no claim this build cannot keep.
+String _word(SuperTabMessage message, String readerId) =>
+ switch (message.source['state']) {
+ 'planned' => 'planned',
+ 'working' => 'working',
+ 'waiting' =>
+ message.source['answerFor'] == readerId ? 'Answer' : 'working',
+ 'review' => 'in review',
+ 'ready' => 'ready',
+ 'shipped' => 'shipped',
+ 'done' => 'done',
+ 'stopped' => 'stopped',
+ _ => '',
+ };
+
+IconData _mark(SuperTabMessage message) => switch (message.source['state']) {
+ 'planned' => LucideIcons.circleDashed,
+ 'shipped' || 'done' => LucideIcons.check,
+ 'stopped' => LucideIcons.circleSlash,
+ _ => LucideIcons.circleDot,
+};
+
+/// One quiet, thumb-sized row: mark, task name and word. Opening the task is
+/// available only while the caller's current read holds that conversation.
+class SwarmTaskLine extends StatelessWidget {
+ const SwarmTaskLine({
+ super.key,
+ required this.message,
+ required this.readerId,
+ this.onOpen,
+ });
+
+ final SuperTabMessage message;
+ final String readerId;
+ final VoidCallback? onOpen;
+
+ @override
+ Widget build(BuildContext context) {
+ AppTheme.watch(context);
+ final title = switch (message.source['title']) {
+ final String title when title.isNotEmpty => title,
+ _ => message.text,
+ };
+ final word = _word(message, readerId);
+ final answer = word == 'Answer';
+ return Semantics(
+ label: word.isEmpty ? title : '$title, $word',
+ button: onOpen != null,
+ onTap: onOpen,
+ excludeSemantics: true,
+ child: Material(
+ color: Colors.transparent,
+ child: InkWell(
+ onTap: onOpen,
+ child: ConstrainedBox(
+ constraints: const BoxConstraints(minHeight: 44),
+ child: Padding(
+ padding: const EdgeInsets.symmetric(
+ horizontal: AppSpace.l,
+ vertical: AppSpace.s,
+ ),
+ child: Row(
+ children: [
+ Icon(
+ _mark(message),
+ size: 16,
+ color: AppPalette.textSecondary,
+ ),
+ const SizedBox(width: AppSpace.s),
+ Expanded(
+ child: Text(
+ title,
+ maxLines: 1,
+ overflow: TextOverflow.ellipsis,
+ style: swarmChatText(
+ 16,
+ weight: answer ? FontWeight.w600 : FontWeight.w400,
+ ),
+ ),
+ ),
+ if (word.isNotEmpty) ...[
+ const SizedBox(width: AppSpace.s),
+ Text(
+ word,
+ maxLines: 1,
+ style: swarmChatText(
+ 14,
+ color: answer
+ ? AppPalette.textPrimary
+ : AppPalette.textSecondary,
+ weight: answer ? FontWeight.w600 : FontWeight.w400,
+ ),
+ ),
+ ],
+ if (onOpen != null) ...[
+ const SizedBox(width: AppSpace.s),
+ Icon(
+ LucideIcons.chevronRight300,
+ size: 18,
+ color: AppPalette.textFaint,
+ ),
+ ],
+ ],
+ ),
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+}
diff --git a/mobile/test/swarm/swarm_task_line_test.dart b/mobile/test/swarm/swarm_task_line_test.dart
new file mode 100644
index 000000000..4b10c216f
--- /dev/null
+++ b/mobile/test/swarm/swarm_task_line_test.dart
@@ -0,0 +1,321 @@
+import 'dart:ui' show SemanticsAction;
+
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness_mobile/notify/system_notices.dart';
+import 'package:harness_mobile/settings/experimental_features.dart';
+import 'package:harness_mobile/swarm/model.dart';
+import 'package:harness_mobile/swarm/swarm_conversation_page.dart';
+import 'package:harness_mobile/swarm/swarm_message_row.dart';
+import 'package:harness_mobile/swarm/swarm_session.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
+
+import '../voice_fakes.dart';
+import 'swarm_fixture.dart';
+
+// Literal server payloads: expectations below come from Desktop's contract.
+Map<String, dynamic> taskLine({
+ String state = 'working',
+ Object? title = 'Fix login',
+ Object? target = 'task-1',
+ String? answerFor,
+ String id = 'line-1',
+ int sequence = 2,
+}) => {
+ 'id': id,
+ 'conversationId': leadChat,
+ 'sequence': sequence,
+ 'text': 'Fix login · $state',
+ 'author': {'kind': 'agent', 'id': 'agent-lead', 'name': 'River'},
+ 'createdAt': DateTime.utc(2026, 11, 2, 17, sequence).toIso8601String(),
+ 'source': {
+ 'kind': 'task-line',
+ 'state': state,
+ 'title': title,
+ 'taskId': target,
+ 'answerFor': ?answerFor,
+ },
+};
+
+Map<String, dynamic> legacyShip(String target, int sequence) => {
+ ...taskLine(id: 'ship-$target', sequence: sequence),
+ 'text': 'Shipped: $target',
+ 'source': {'kind': 'ship', 'conversationId': target, 'title': target},
+};
+
+FakeSwarm taskLineBackend(
+ List<Map<String, dynamic>> page, {
+ bool target = true,
+}) {
+ final fake = FakeSwarm();
+ fake.routes['/api/super-tabs/list'] = (_) => {
+ 'tabs': [
+ {'id': tab, 'name': 'Phone Swarm', 'ownerId': me},
+ ],
+ 'next': null,
+ };
+ fake.routes['/api/super-tabs/$tab/parts'] = (_) => firstLoad(
+ groups: [
+ groupData(leadChat, title: 'Project chat', lastMessageSequence: 10),
+ if (target) groupData('task-1', title: 'Fix login'),
+ ],
+ );
+ fake.routes['/api/super-tabs/$tab/changes'] = (_) => changes(cursor: 'c2');
+ fake.routes['/api/super-tabs/$tab/decisions'] = (_) => {
+ 'decisions': <Object>[],
+ };
+ fake.routes['/api/super-tabs/$tab/mentions'] = (_) => {
+ 'mentions': <Object>[],
+ };
+ fake.routes['/api/super-tabs/$tab/conversations/$leadChat/messages'] = (_) =>
+ {'messages': page.reversed.toList(), 'threads': <Object>[], 'next': null};
+ fake.routes['/api/super-tabs/$tab/conversations/task-1/messages'] = (_) => {
+ 'messages': [
+ {
+ ...taskLine(),
+ 'id': 'task-message',
+ 'conversationId': 'task-1',
+ 'text': 'Inside the task chat',
+ 'source': {'kind': 'message'},
+ },
+ ],
+ 'threads': <Object>[],
+ 'next': null,
+ };
+ fake.routes['/api/super-tabs/$tab/commands'] = (_) => {
+ 'result': <String, dynamic>{},
+ };
+ return fake;
+}
+
+Future<SwarmHost> pumpTaskChat(WidgetTester tester, FakeSwarm fake) async {
+ await tester.binding.setSurfaceSize(const Size(390, 844));
+ addTearDown(() => tester.binding.setSurfaceSize(null));
+ final features = ExperimentalFeaturesStore(storage: MemoryKeyValueStore())
+ ..value = {PhoneExperiment.swarm};
+ final account = ValueNotifier<String?>(me);
+ final host = SwarmHost(
+ accountId: () => account.value,
+ account: account,
+ request: fake.request,
+ notices: SilentSystemNotices(),
+ features: features,
+ readMarks: MemoryKeyValueStore(),
+ )..foreground = false;
+ addTearDown(host.dispose);
+ await tester.pumpWidget(
+ MaterialApp(
+ builder: (context, child) => SwarmScope(notifier: host, child: child!),
+ home: const SwarmConversationPage(swarmId: tab, conversationId: leadChat),
+ ),
+ );
+ await tester.pumpAndSettle();
+ return host;
+}
+
+Future<void> pumpRow(
+ WidgetTester tester,
+ Map<String, dynamic> data, {
+ String readerId = me,
+ double width = 390,
+ double scale = 1,
+}) async {
+ await tester.binding.setSurfaceSize(Size(width, 844));
+ addTearDown(() => tester.binding.setSurfaceSize(null));
+ await tester.pumpWidget(
+ MaterialApp(
+ builder: (context, child) => MediaQuery(
+ data: MediaQuery.of(context)
+ .copyWith(textScaler: TextScaler.linear(scale)),
+ child: child!,
+ ),
+ home: Scaffold(
+ body: ListView(
+ children: [
+ SwarmMessageRow(
+ message: SuperTabMessage.fromJson(data),
+ name: 'River',
+ look: (picture: null, status: null),
+ role: 'PM',
+ readerId: readerId,
+ mentions: SwarmMentions(const []),
+ grouped: false,
+ lit: false,
+ quote: null,
+ actions: false,
+ onTap: () {},
+ onReply: null,
+ ),
+ ],
+ ),
+ ),
+ ),
+ );
+}
+
+void main() {
+ // Removing dispatch, using fallback text, or mapping any state incorrectly
+ // breaks these consumer-visible widget assertions.
+ for (final (state, word, mark) in [
+ ('planned', 'planned', LucideIcons.circleDashed),
+ ('working', 'working', LucideIcons.circleDot),
+ ('waiting', 'working', LucideIcons.circleDot),
+ ('review', 'in review', LucideIcons.circleDot),
+ ('ready', 'ready', LucideIcons.circleDot),
+ ('shipped', 'shipped', LucideIcons.check),
+ ('done', 'done', LucideIcons.check),
+ ('stopped', 'stopped', LucideIcons.circleSlash),
+ ]) {
+ testWidgets('$state shows the task name, Desktop word and mark', (
+ tester,
+ ) async {
+ await pumpRow(tester, taskLine(state: state));
+ expect(find.text('Fix login'), findsOneWidget);
+ expect(find.text(word), findsOneWidget);
+ expect(find.byIcon(mark), findsOneWidget);
+ expect(find.text('River'), findsNothing);
+ expect(find.text('Fix login · $state'), findsNothing);
+ });
+ }
+
+ testWidgets('waiting asks only the named reader to Answer', (tester) async {
+ final semantics = tester.ensureSemantics();
+ final data = taskLine(state: 'waiting', answerFor: me);
+ await pumpRow(tester, data);
+ expect(find.text('Answer'), findsOneWidget);
+ expect(find.bySemanticsLabel('Fix login, Answer'), findsOneWidget);
+ expect(
+ tester.widget<Text>(find.text('Answer')).style?.fontWeight,
+ FontWeight.w600,
+ );
+ await pumpRow(tester, data, readerId: 'someone-else');
+ expect(find.text('Answer'), findsNothing);
+ expect(find.text('working'), findsOneWidget);
+ semantics.dispose();
+ });
+
+ testWidgets('unknown state keeps fallback text without inventing a word', (
+ tester,
+ ) async {
+ await pumpRow(tester, taskLine(state: 'future', title: null));
+ expect(find.text('Fix login · future'), findsOneWidget);
+ expect(find.byIcon(LucideIcons.circleDot), findsOneWidget);
+ expect(find.text('working'), findsNothing);
+ expect(find.text('River'), findsNothing);
+ });
+
+ testWidgets(
+ 'long name keeps the word and thumb target on a narrow large-text phone',
+ (tester) async {
+ final name = List.filled(12, 'A long task name').join(' ');
+ await pumpRow(
+ tester,
+ taskLine(title: name, state: 'review'),
+ width: 320,
+ scale: 2,
+ );
+ expect(find.text(name), findsOneWidget);
+ expect(find.text('in review'), findsOneWidget);
+ expect(tester.takeException(), isNull);
+ final row = find.byKey(const ValueKey('swarm-message-line-1'));
+ expect(tester.getSize(row).height, greaterThanOrEqualTo(44));
+ },
+ );
+
+ testWidgets('tapping a line opens its task chat without a reply action', (
+ tester,
+ ) async {
+ final semantics = tester.ensureSemantics();
+ await pumpTaskChat(tester, taskLineBackend([taskLine()]));
+ expect(
+ tester
+ .getSemantics(find.bySemanticsLabel('Fix login, working'))
+ .getSemanticsData()
+ .hasAction(SemanticsAction.tap),
+ isTrue,
+ );
+ semantics.dispose();
+ await tester.tap(find.byKey(const ValueKey('swarm-message-line-1')));
+ await tester.pumpAndSettle();
+ expect(find.text('Inside the task chat'), findsOneWidget);
+ expect(
+ tester
+ .widget<SwarmConversationPage>(
+ find.byType(SwarmConversationPage).last,
+ )
+ .conversationId,
+ 'task-1',
+ );
+ expect(find.text('Reply in thread'), findsNothing);
+ });
+
+ for (final target in <Object?>['task-1', 7, null]) {
+ testWidgets(
+ 'a target absent from the read stays readable without navigation: $target',
+ (tester) async {
+ final semantics = tester.ensureSemantics();
+ final fake = taskLineBackend([taskLine(target: target)], target: false);
+ await pumpTaskChat(tester, fake);
+ expect(find.text('Fix login'), findsOneWidget);
+ expect(
+ tester
+ .getSemantics(find.bySemanticsLabel('Fix login, working'))
+ .getSemanticsData()
+ .hasAction(SemanticsAction.tap),
+ isFalse,
+ );
+ await tester.tap(find.byKey(const ValueKey('swarm-message-line-1')));
+ await tester.pumpAndSettle();
+ expect(find.byType(SwarmConversationPage), findsOneWidget);
+ expect(
+ fake.paths.any((p) => p.contains('/conversations/task-1/messages')),
+ isFalse,
+ );
+ expect(find.text('Copy'), findsNothing);
+ semantics.dispose();
+ },
+ );
+ }
+
+ for (final lineFirst in [true, false]) {
+ testWidgets('a line hides only its task’s legacy ship, order $lineFirst', (
+ tester,
+ ) async {
+ final line = taskLine(sequence: lineFirst ? 1 : 3);
+ final ship = legacyShip('task-1', 2);
+ await pumpTaskChat(
+ tester,
+ taskLineBackend([
+ if (lineFirst) line,
+ ship,
+ if (!lineFirst) line,
+ legacyShip('other-task', 4),
+ ]),
+ );
+ expect(find.text('Fix login'), findsOneWidget);
+ expect(find.text('Shipped: task-1'), findsNothing);
+ expect(find.text('Shipped: other-task'), findsOneWidget);
+ });
+ }
+
+ testWidgets('a legacy ship stays when no line replaces it', (tester) async {
+ await pumpTaskChat(tester, taskLineBackend([legacyShip('task-1', 2)]));
+ expect(find.text('Shipped: task-1'), findsOneWidget);
+ });
+
+ test('a normal message after a task line keeps its author header', () {
+ final line = taskLine(sequence: 1);
+ final normal = {
+ ...taskLine(id: 'normal', sequence: 2),
+ 'source': {'kind': 'message'},
+ 'text': 'A normal follow-up',
+ };
+ expect(
+ swarmGroupedMessages([
+ SuperTabMessage.fromJson(line),
+ SuperTabMessage.fromJson(normal),
+ ]),
+ isEmpty,
+ );
+ });
+}