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 b1748: #2744 #2766 (#2792)

0xken15b8b07a2fae71
diff --git a/backend/src/superTabs/liveness.ts b/backend/src/superTabs/liveness.ts
index 9cf713020..f46030135 100644
--- a/backend/src/superTabs/liveness.ts
+++ b/backend/src/superTabs/liveness.ts
@@ -12,6 +12,7 @@ import { staleSwitches } from './tidy.js'
import { ledProject, projectsOf } from './projects.js'
import { coordinatorNameOf } from './instructions.js'
import { waitedOn } from './leaderboard/record.js'
+import { isStep } from './steps.js'
// Work never sits with a dead owner (design: "A Swarm that never stops", 2026-10-26). A worker's active assignment is held
// by a lease that its progress renews. A dead, stalled or limited worker loses it within minutes: the assignment becomes
@@ -86,6 +87,39 @@ export function waitingForReview(assignment: Assignment): boolean {
&& READY_FOR_REVIEW.test(assignment.result) && REVISION.test(assignment.result)
}
+/** A task's Engineer waits on one of its own steps while that step's agent is at work on it (Diego, 2026-11-03, #2323: the
+ * instructions never ask the Engineer to set review while its Review and Test run, so it lost its task 35 minutes in). A
+ * step in Ready has handed its verdict over, and one whose verdict asked for changes waits for the Engineer's new revision
+ * (review of #2744): then it is the Engineer's turn, else the two would wait on each other. */
+export function waitingOnSteps(state: SuperTabState, group: Conversation, steps: StepIndex = stepIndex(state)): boolean {
+ return !isStep(group) && (steps.get(group.id) ?? []).some(step => !step.archived && activeWork(step) && step.assignment!.status !== 'review'
+ && !(reviews(step, group) && waitsOnRevisionOf(step, group)))
+}
+
+/** The loaded steps of each task, by task id, read once per pass: liveness runs inside every machine report and command
+ * write, so a scan of every conversation per task would grow with tasks times conversations (review of #2744). */
+type StepIndex = ReadonlyMap<string, Conversation[]>
+function stepIndex(state: SuperTabState): StepIndex {
+ const steps = new Map<string, Conversation[]>()
+ for (const c of state.conversations) {
+ if (!c.reviewOf) continue
+ const of = steps.get(c.reviewOf)
+ if (of) of.push(c)
+ else steps.set(c.reviewOf, [c])
+ }
+ return steps
+}
+
+/** [task]'s Engineer waited on its steps, as its record says, and none is at work now: its quiet time runs from now, as
+ * revisionReady's does, so it has 30 minutes to act on what they found and a hung Engineer is still found. The record it
+ * writes ends that wait, so this runs once per wait. */
+function stepsEnded(state: SuperTabState, task: Conversation, now: number, steps?: StepIndex): void {
+ if (!activeWork(task) || task.assignment!.status !== 'working' || task.liveness?.state !== 'waiting' || task.liveness.why !== 'review') return
+ if (waitingOnSteps(state, task, steps)) return
+ restartQuietTime(task.assignment!, now)
+ recordTaskState(state, task, now)
+}
+
/** Work that stopped waiting for its review counts its quiet time from now: its agent keeps it QUIET_RUNNING_MS without
* progress, as after its last screen change, though its screen stayed still while it waited. */
export function restartQuietTime(assignment: Assignment, now: number): void {
@@ -99,9 +133,13 @@ export function restartQuietTime(assignment: Assignment, now: number): void {
function reviewedBuild(state: SuperTabState, group: Conversation): Conversation | undefined {
if (!group.reviewOf) return undefined
const build = state.conversations.find(c => c.id === group.reviewOf)
- return build && !build.archived && activeWork(build) && (build.projectId ?? 'lead') === (group.projectId ?? 'lead') ? build : undefined
+ return build && reviews(group, build) ? build : undefined
}
+/** Whether [build] is one [step] reviews now: active work of the same project, not archived (reviewedBuild). */
+const reviews = (step: Conversation, build: Conversation): boolean =>
+ !build.archived && activeWork(build) && (build.projectId ?? 'lead') === (step.projectId ?? 'lead')
+
/** The active linked tasks (reviewOf [build]) its own [agentId] holds: the Reviewer's or Tester's task for that build. */
function ownLinkedTasks(state: SuperTabState, build: Conversation, agentId: string): Conversation[] {
return state.conversations.filter(c => c.reviewOf === build.id && activeWork(c) && c.assignment!.agentId === agentId
@@ -116,8 +154,12 @@ function ownLinkedTasks(state: SuperTabState, build: Conversation, agentId: stri
* silence still moves (#2241: 35 attempts lost in a day). */
export function waitingForRevision(state: SuperTabState, group: Conversation): boolean {
const build = reviewedBuild(state, group)
- if (!build) return false
- const assignment = group.assignment
+ return !!build && waitsOnRevisionOf(group, build)
+}
+
+/** waitingForRevision of [step] for the [build] it reviews, already found (reviewedBuild). */
+function waitsOnRevisionOf(step: Conversation, build: Conversation): boolean {
+ const assignment = step.assignment
return assignment?.changesRequestedAt !== undefined || (assignment?.toldEngineerAt !== undefined && !waitingForReview(build.assignment!))
}
@@ -229,15 +271,17 @@ function limitReason(worker: Agent, now: number): string | null {
/** The earliest time a task held by a worker on [machineId] may be lost to its lease running out, as lostReason reads it now,
* or undefined when none can. Reports that keep its session running with progress no older can only move it later. */
export function nextLossAt(state: SuperTabState, machineId: string): number | undefined {
+ const steps = stepIndex(state)
const ends = workerTasks(state)
- .filter(({ group, worker, assignment }) => worker.machineId === machineId && !waitingForReview(assignment) && !waitingForRevision(state, group))
+ .filter(({ group, worker, assignment }) => worker.machineId === machineId && !waitingForReview(assignment) && !waitingForRevision(state, group)
+ && !waitingOnSteps(state, group, steps))
.map(({ group, assignment, worker }) => leaseEnd(group, assignment, reportRenewedAt(state, worker)))
.filter((end): end is number => end !== undefined)
return ends.length ? Math.min(...ends) : undefined
}
/** Why a worker has lost its task now, or null while it still holds it. Only a machine that has reported can be offline. */
-function lostReason(state: SuperTabState, group: Conversation, worker: Agent, assignment: Assignment, now: number): string | null {
+function lostReason(state: SuperTabState, group: Conversation, worker: Agent, assignment: Assignment, now: number, steps: StepIndex): string | null {
const pool = state.machines?.find(m => m.machineId === worker.machineId)
if (pool?.observation?.stoppedHarnessIds.includes(worker.harnessId)) return sessionStopped(pool.name)
if (pool?.observation && now - pool.observation.receivedAt > OFFLINE_LOST_MS) return machineOffline(pool.name)
@@ -246,7 +290,7 @@ function lostReason(state: SuperTabState, group: Conversation, worker: Agent, as
// Its host alerts only after ten minutes of retries without an answer (cli superTabs/terminal.ts MODEL_WAIT_MS), so a
// short burst of failures that recovers never gets here.
if (worker.alerting?.includes('model')) return 'its model keeps failing'
- if (waitingForReview(assignment) || waitingForRevision(state, group)) return null
+ if (waitingForReview(assignment) || waitingForRevision(state, group) || waitingOnSteps(state, group, steps)) return null
const end = leaseEnd(group, assignment, reportRenewedAt(state, worker))
if (end !== undefined && now > end) {
const progress = lastProgress(state, worker, assignment)
@@ -286,8 +330,11 @@ function loseTask(state: SuperTabState, group: Conversation, worker: Agent, reas
* the agents of a machine that just reported. A task lost to that limit resumes at `resumeAt` when its screen said when the
* limit resets (the host types into the same session then, cli superTabs/limitResume.ts). */
export function loseTasks(state: SuperTabState, now: number, which: (worker: Agent) => boolean = () => true, resumeAt?: string): MessageDraft[] {
+ const steps = stepIndex(state)
return workerTasks(state).filter(t => which(t.worker)).flatMap(({ group, assignment, worker }) => {
- const reason = lostReason(state, group, worker, assignment, now)
+ // A step that ended with no write to its task, or was lost earlier in this same pass, ends its Engineer's wait first.
+ stepsEnded(state, group, now, steps)
+ const reason = lostReason(state, group, worker, assignment, now, steps)
return reason ? loseTask(state, group, worker, reason, now, resumeAt && reason === limitReason(worker, now) ? resumeAt : undefined) : []
})
}
@@ -377,8 +424,8 @@ const FINISHED_WORK = ['done', 'cancelled', 'stopped']
/** A task in review waits while one of its linked tasks (reviewOf it) is open. With none open, nothing opens a review by itself
* (project instructions, phase 4), so after TASK_QUIET_MS from its last progress, or from when its last linked task ended, it
* is quiet and its coordinator hears once (final review of the branch). Only loaded linked tasks count: an archived one ended. */
-function reviewWait(state: SuperTabState, group: Conversation, progress: number, now: number): TaskLiveness {
- const linked = state.conversations.filter(c => c.reviewOf === group.id)
+function reviewWait(group: Conversation, progress: number, now: number, steps: StepIndex): TaskLiveness {
+ const linked = steps.get(group.id) ?? []
const ended = (c: Conversation) => c.archived || (!!c.assignment && FINISHED_WORK.includes(c.assignment.status))
if (linked.some(c => !ended(c))) return { state: 'waiting', why: 'review', since: progress }
const since = Math.max(progress, ...linked.map(c => (c.lastActivityAt && Date.parse(c.lastActivityAt)) || 0))
@@ -388,7 +435,7 @@ function reviewWait(state: SuperTabState, group: Conversation, progress: number,
/** The state of a project task now, from what is loaded (never a further read), or null while it is working (its agent
* reported in the last 30 minutes) and for anything that is not a task: a Lead or Leads conversation, a private chat (it
* never holds work), an archived group, finished work, or none yet. */
-export function taskLiveness(state: SuperTabState, group: Conversation, now: number): TaskLiveness | null {
+export function taskLiveness(state: SuperTabState, group: Conversation, now: number, steps: StepIndex = stepIndex(state)): TaskLiveness | null {
if (group.kind || group.audience || group.archived || projectsOf(state).some(p => p.leadConversationId === group.id)) return null
if (!projectsOf(state).some(p => p.id === (group.projectId ?? 'lead'))) return null
const assignment = group.assignment
@@ -402,11 +449,14 @@ export function taskLiveness(state: SuperTabState, group: Conversation, now: num
const asked = assignment.askedOf && state.people.some(p => p.id === assignment.askedOf) ? assignment.askedOf : undefined
return { state: 'waiting', why: 'person', personId: asked ?? waitedOn(state, group), since: group.ledger?.waiting?.since ?? progress }
}
- if (assignment.status === 'review') return reviewWait(state, group, progress, now)
+ // A step in Ready is the review itself: it waits on its task's owner to act on its verdict, never on a review of its own.
+ if (assignment.status === 'review' && isStep(group)) return { state: 'waiting', why: 'review', since: progress }
+ if (assignment.status === 'review') return reviewWait(group, progress, now, steps)
if (assignment.status === 'blocked') return { state: 'waiting', why: 'blocked', since: progress }
// A review whose verdict asked for changes waits for the new revision; once it is ready, its quiet time runs from then
// (revisionReady restarts its progress).
if (waitingForRevision(state, group)) return { state: 'waiting', why: 'revision', since: progress }
+ if (waitingOnSteps(state, group, steps)) return { state: 'waiting', why: 'review', since: progress }
return now - progress >= TASK_QUIET_MS ? { state: 'quiet', why: 'silent', since: progress } : null
}
// Only unfinished starts are loaded, with those that ended in this same write.
@@ -429,13 +479,19 @@ const FINISHED_OR_ARCHIVED = (group: Conversation) => group.archived || (!!group
/** What a task's record becomes: its state now. A task whose start failed stays orphaned until it has work again, since
* that start is no longer loaded once it ended; nothing else outlives what made it. */
-const nextState = (state: SuperTabState, group: Conversation, now: number) => taskLiveness(state, group, now)
+const nextState = (state: SuperTabState, group: Conversation, now: number, steps?: StepIndex) => taskLiveness(state, group, now, steps)
?? (group.liveness?.why === 'start-failed' && !activeWork(group) && !FINISHED_OR_ARCHIVED(group) ? group.liveness : undefined)
/** Records the state of the task a command changed, in that command's own write, so the time checks find nothing to rewrite
* (a machine's reading must write no group, read/host.ts). A stall is left to the time checks, which wake the Lead for it;
* a failed start is not, since its own notice told the Lead and the next sweep no longer loads it. */
export function recordTaskState(state: SuperTabState, group: Conversation, now: number): void {
+ // A step's change is its task's too: the Engineer waits on it from its start and gets its time back when it ends.
+ const task = isStep(group) ? state.conversations.find(c => c.id === group.reviewOf) : undefined
+ if (task) {
+ stepsEnded(state, task, now)
+ recordTaskState(state, task, now)
+ }
const next = nextState(state, group, now)
if (sameState(group.liveness, next) || (next && next.state !== 'waiting' && next.why !== 'start-failed')) return
if (next) group.liveness = next
@@ -464,9 +520,10 @@ function stalledLine(state: SuperTabState, group: Conversation, liveness: TaskLi
* task has no record, so a steady Swarm's sweeps write nothing. */
function recordTaskStates(state: SuperTabState, now: number): MessageDraft[] {
const stalled = new Map<string, Array<{ group: Conversation; next: TaskLiveness }>>()
+ const steps = stepIndex(state)
for (const group of state.conversations) {
const before = group.liveness
- const next = nextState(state, group, now)
+ const next = nextState(state, group, now, steps)
if (sameState(before, next)) continue
if (next && (next.state === 'quiet' || next.state === 'orphaned') && before?.state !== next.state && next.why !== 'lost' && next.why !== 'start-failed') {
const projectId = group.projectId ?? 'lead'
diff --git a/backend/src/superTabs/steps.test.ts b/backend/src/superTabs/steps.test.ts
index 34583581c..de8002f2f 100644
--- a/backend/src/superTabs/steps.test.ts
+++ b/backend/src/superTabs/steps.test.ts
@@ -10,7 +10,7 @@ import { extracted } from './parts/write.js'
import { stepEndedRows, stepSleeps } from './steps.js'
import { reportedAs } from './projectUpdates.js'
import { idleNotices } from './tidy.js'
-import { QUIET_RUNNING_MS, sweepLiveness } from './liveness.js'
+import { QUIET_RUNNING_MS, sweepForLead, sweepLiveness } from './liveness.js'
const owner: Extract<Actor, { kind: 'person' }> = { kind: 'person', userId: 'owner', email: '[email protected]' }
const config: AgentConfiguration = { engine: 'codex', model: 'test-model', effort: 'high', contextWindow: 200000, engineVersion: 'fixture' }
@@ -628,3 +628,77 @@ describe('checks with several checkers', () => {
expect(read()).not.toHaveProperty('verdicts')
})
})
+
+// Diego, 2026-11-03 (#2323): liveness read waiting only from a task's own status. An Engineer that stayed working while its
+// Review and Test steps ran lost its task 35 minutes in, and a step in Ready, itself the review, woke the PM as a review
+// nobody had opened.
+describe('an Engineer waiting on its own steps', () => {
+ const MIN = 60_000
+ const reviewing = () => {
+ const f = stepsFixture()
+ const id = f.step('Review')
+ const rev = f.add('rev', id)
+ f.run({ type: 'work.assign', conversationId: id, agentId: rev }, f.as(f.dev))
+ const stepStatus = (status: string) =>
+ f.run({ type: 'work.status', conversationId: id, assignmentId: f.group(id).assignment!.id, status, result: `Review ${status}` } as Command, f.as(rev))
+ // The Reviewer keeps reporting while it reviews; the Engineer's screen stays still.
+ const reviewFor = (minutes: number) => { for (let m = 0; m < minutes; m += 4) { f.tick(4 * MIN); stepStatus('working') } }
+ return { f, id, rev, stepStatus, reviewFor, task: () => f.group(f.task).assignment! }
+ }
+
+ it('keeps its task while a step is working, and is lost 30 minutes after the last step ends', () => {
+ const { f, stepStatus, reviewFor, task } = reviewing()
+ reviewFor(36)
+ sweepLiveness(f.state, f.now)
+ expect(task()).toMatchObject({ status: 'working' })
+ stepStatus('done')
+ f.tick(QUIET_RUNNING_MS - MIN)
+ sweepLiveness(f.state, f.now)
+ expect(task()).toMatchObject({ status: 'working' })
+ f.tick(2 * MIN)
+ sweepLiveness(f.state, f.now)
+ expect(task()).toMatchObject({ status: 'lost' })
+ })
+
+ it('gets its 30 minutes from a step\'s Ready, its turn to act on the verdict', () => {
+ const { f, stepStatus, reviewFor, task } = reviewing()
+ reviewFor(36)
+ stepStatus('review')
+ f.tick(QUIET_RUNNING_MS - MIN)
+ sweepLiveness(f.state, f.now)
+ expect(task()).toMatchObject({ status: 'working' })
+ f.tick(2 * MIN)
+ sweepLiveness(f.state, f.now)
+ expect(task()).toMatchObject({ status: 'lost' })
+ })
+
+ // Review of #2744 (Wren2): a Reviewer stays working through the fix round its verdict asked for, waiting on the Engineer's
+ // new revision; counting that step held the two on each other, so a hung Engineer was never found.
+ for (const via of ['a post', 'a failed check'] as const) {
+ it(`gets its 30 minutes from a verdict asking for changes by ${via}, while its Reviewer waits on it`, () => {
+ const { f, id, rev, reviewFor, task } = reviewing()
+ reviewFor(8)
+ if (via === 'a post') {
+ f.run({ type: 'message.send', conversationId: id, text: 'Ready to merge: With fixes. One Important.', replyTo: null, recipientIds: [f.dev] } as Command, f.as(rev))
+ } else {
+ f.run({ type: 'work.check', conversationId: f.task, assignmentId: task().id, checkId: f.group(f.task).checks[0]!.id, passed: false,
+ evidence: 'One Important at x.ts:1' } as Command, f.as(rev))
+ }
+ f.tick(QUIET_RUNNING_MS - MIN)
+ sweepLiveness(f.state, f.now)
+ expect(task()).toMatchObject({ status: 'working' })
+ f.tick(2 * MIN)
+ sweepLiveness(f.state, f.now)
+ expect(task()).toMatchObject({ status: 'lost' })
+ })
+ }
+
+ it('a step in Ready waits on its task owner and never wakes the PM as a stalled review', () => {
+ const { f, id, stepStatus } = reviewing()
+ stepStatus('review')
+ f.tick(31 * MIN)
+ const rows = sweepForLead(f.state, f.now)
+ expect(rows.filter(r => r.source?.kind === 'work-stalled')).toEqual([])
+ expect(f.group(id).liveness).toMatchObject({ state: 'waiting', why: 'review' })
+ })
+})
diff --git a/cli/src/cable/cableSession.spec.ts b/cli/src/cable/cableSession.spec.ts
index a551848d4..a51149d1a 100644
--- a/cli/src/cable/cableSession.spec.ts
+++ b/cli/src/cable/cableSession.spec.ts
@@ -2153,6 +2153,65 @@ describe('cable session', () => {
await session.stop()
})
+ // Diego's dial, 2026-11-03: a Kilo agent's 325 models made a 32 KB frame against the 8 KB cap, and the daemon closed the
+ // whole USB link over it. Every tap on the picker did it again.
+ it('answers a catalog too big for one frame within the cap and keeps the link', async () => {
+ const catalog = Array.from({ length: 325 }, (_, i) => `runtime-v1:kilo:openrouter:provider-${String(i).padStart(3, '0')}/a-model-name-long-enough-to-be-about-one-hundred-bytes@high`)
+ const { session, port } = await connect(makeHost({ listModels: async () => catalog }))
+ try {
+ port.say({ t: 'hello', product: 'harness', mac: 'aa:bb' })
+ await vi.waitFor(() => expect(port.types()).toContain('agents.end'))
+ port.sent.length = 0
+ port.frames.length = 0
+ port.say({ t: 'models.list', agentId: 'a1', mode: 'model', selected: catalog[299], request: 7 })
+ await vi.waitFor(() => expect(port.types()).toContain('models'))
+ const replies = port.sent.filter((m) => m.t === 'models')
+ expect(replies).toHaveLength(1)
+ const [reply] = replies
+ expect(reply.request).toBe(7)
+ const items = reply.items as Array<{ id: string }>
+ expect(items.length).toBeGreaterThan(1)
+ expect(items.length).toBeLessThanOrEqual(48)
+ expect(items[0]).toEqual({ id: catalog[299] })
+ // The rest in the catalog's order, the selected one not again.
+ expect(items.slice(1).map((m) => m.id)).toEqual(catalog.filter((id) => id !== catalog[299]).slice(0, items.length - 1))
+ for (const frame of port.frames) expect(frame.length).toBeLessThanOrEqual(8192)
+ expect(port.isOpen).toBe(true)
+ } finally { await session.stop() }
+ })
+
+ it('leaves out a selected id the catalog does not list, and an id too long to fit, and sends the rest', async () => {
+ const huge = `runtime-v1:x:${'y'.repeat(9000)}`
+ const { session, port } = await connect(makeHost({ listModels: async () => ['m-1', huge, 'm-2'] }))
+ try {
+ port.say({ t: 'hello', product: 'harness', mac: 'aa:bb' })
+ await vi.waitFor(() => expect(port.types()).toContain('agents.end'))
+ port.sent.length = 0
+ port.say({ t: 'models.list', agentId: 'a1', selected: 'gone', request: 8 })
+ await vi.waitFor(() => expect(port.types()).toContain('models'))
+ expect(port.sent.find((m) => m.t === 'models')).toMatchObject({ request: 8, items: [{ id: 'm-1' }, { id: 'm-2' }] })
+ expect(port.isOpen).toBe(true)
+ } finally { await session.stop() }
+ })
+
+ it('drops and logs a frame over the cap, and the link stays up', async () => {
+ const lines: string[] = []
+ const { session, port } = await connect(makeHost({ log: (l) => lines.push(l) }))
+ try {
+ port.say({ t: 'hello', product: 'harness', mac: 'aa:bb' })
+ await vi.waitFor(() => expect(port.types()).toContain('agents.end'))
+ // A message this side made too big is its own bug, never the port's: nothing a dial asks may close the link over it.
+ const send = (session as unknown as { send(m: Record<string, unknown>): Promise<boolean> }).send.bind(session)
+ expect(await send({ t: 'oversized', pad: 'x'.repeat(9000) })).toBe(false)
+ expect(port.isOpen).toBe(true)
+ expect(lines.filter((l) => l.includes('oversized'))).toHaveLength(1)
+ expect(lines.some((l) => l.includes('write failed'))).toBe(false)
+ port.sent.length = 0
+ expect(await send({ t: 'small' })).toBe(true)
+ expect(port.types()).toEqual(['small'])
+ } finally { await session.stop() }
+ })
+
it('answers models.list when the provider throws', async () => {
const { session, port } = await connect(makeHost({ listModels: async () => { throw new Error('no engine') } }))
port.say({ t: 'hello', product: 'harness', mac: 'aa:bb' })
diff --git a/cli/src/cable/cableSession.ts b/cli/src/cable/cableSession.ts
index 595624520..2a85ef9bc 100644
--- a/cli/src/cable/cableSession.ts
+++ b/cli/src/cable/cableSession.ts
@@ -237,6 +237,8 @@ function fitText(full: string, make: (text: string) => Message): Message {
let nextCardSession = 0
const SWARM_IDS_MAX = 24
const SWARM_TOKENS_MAX = 480
+/** The models a dial's picker holds (ui_habitat.c): more are never sent. */
+const MODELS_MAX = 48
/** Tokens as `cable_json_guard.c` counts them: every object, array, string (keys too) and bare value. */
function jsonTokens(value: unknown): number {
@@ -245,6 +247,13 @@ function jsonTokens(value: unknown): number {
return 1
}
+/** Whether a message fits one frame as the device reads it: the cable's payload cap, with a margin for anything the
+ * frame carries beyond this JSON (its seq), and the firmware's JSON guard, which refuses a frame of more than 512
+ * tokens whole. */
+function fitsFrame(m: unknown): boolean {
+ return Buffer.byteLength(JSON.stringify(m), 'utf8') <= CABLE_MAX_PAYLOAD - 256 && jsonTokens(m) <= SWARM_TOKENS_MAX
+}
+
function clipUtf8(text: string, max: number): string {
const flat = text.replace(/[\r\n\t]+/g, ' ')
if (Buffer.byteLength(flat, 'utf8') <= max) return flat
@@ -1487,10 +1496,21 @@ export class CableSession {
const serial = msg.request
const request = typeof serial === 'number' && Number.isInteger(serial)
&& serial > 0 && serial <= 0x7fffffff ? serial : undefined
- await this.send({
- t: 'models', agentId, ...(request === undefined ? {} : { request }),
- items: items.map((id) => ({ id })),
- })
+ // One frame, as the dial keeps it: the model it has selected first, then the catalog in order, up to the 48 its
+ // picker holds and only while the frame stays within the cap (bytes, and tokens as cable_json_guard.c counts
+ // them). A Kilo agent lists about 325 ids, about 32 KB against the 8 KB cap (Diego, 2026-11-03).
+ const selected = str('selected')
+ const ordered = selected && items.includes(selected) ? [selected, ...items.filter((id) => id !== selected)] : items
+ const reply: Message = { t: 'models', agentId, ...(request === undefined ? {} : { request }), items: [] as Array<{ id: string }> }
+ const kept = reply.items as Array<{ id: string }>
+ for (const id of ordered) {
+ if (kept.length >= MODELS_MAX) break
+ kept.push({ id })
+ // An id that does not fit is left out; a shorter one after it may still.
+ if (!fitsFrame(reply)) kept.pop()
+ }
+ if (kept.length < ordered.length) this.log(`cable: models for ${agentId}: ${kept.length} of ${ordered.length} fit one frame`)
+ await this.send(reply)
return
}
case 'focus':
@@ -2517,9 +2537,19 @@ export class CableSession {
private async send(msg: Message): Promise<boolean> {
if (!this.link?.isOpen) return false
+ // A message over the frame cap is this side's bug, never a dead port: it is dropped and said, and the link stays up.
+ // Closing over it took the whole dial down on every tap of a long model list (Diego, 2026-11-03).
+ let frame: Uint8Array
+ try {
+ const framed = this.seqOn ? { ...msg, seq: this.seq } : msg
+ frame = encodeCableFrame(CableType.Json, Buffer.from(JSON.stringify(framed), 'utf8'))
+ } catch (err) {
+ this.log(`cable: dropped a ${String(msg.t)} frame (${(err as Error).message})`)
+ return false
+ }
+ if (this.seqOn) this.seq++
try {
- const framed = this.seqOn ? { ...msg, seq: this.seq++ } : msg
- await this.put(this.link, encodeCableFrame(CableType.Json, Buffer.from(JSON.stringify(framed), 'utf8')))
+ await this.put(this.link, frame)
return true
} catch (err) {
this.log(`cable: write failed (${(err as Error).message})`)
@@ -3232,10 +3262,7 @@ export class CableSession {
tiles: withTiles ? flatTiles : [],
})
if (!this.swarmMembers) return build(swarms, () => false)
- // Two limits, both the device's: the cable's payload cap (with a margin for anything the frame carries
- // beyond this JSON) and the firmware's JSON guard, which refuses a frame of more than 512 tokens WHOLE,
- // leaving the Tabs screen empty. Count with room to spare.
- const fits = (m: Message) => Buffer.byteLength(JSON.stringify(m), 'utf8') <= CABLE_MAX_PAYLOAD - 256 && jsonTokens(m) <= SWARM_TOKENS_MAX
+ // Both of the device's limits (fitsFrame): a frame over the JSON guard is refused WHOLE, leaving the Tabs screen empty.
const selectedRow = swarms.find((s) => s.id === selected)
const capped = swarms.length <= SWARMS_MAX ? swarms
: swarms.slice(0, SWARMS_MAX).some((s) => s === selectedRow) || !selectedRow ? swarms.slice(0, SWARMS_MAX)
@@ -3246,7 +3273,7 @@ export class CableSession {
const others = capped.filter((s) => s !== selectedRow).slice(0, selectedRow ? n - 1 : n)
const list = capped.filter((s) => s === selectedRow || others.includes(s))
const attempts = [build(list, () => true, true), build(list, () => true), build(list, (s) => s.id === selected), build(list, () => false)]
- const at = attempts.findIndex(fits)
+ const at = attempts.findIndex(fitsFrame)
if (at < 0) continue
if (at > 0 || n < capped.length) this.noteTrimmed(key, `${at === 1 ? 'member names' : at === 2 ? 'ids of the other tabs' : at === 3 ? 'member ids' : ''} dropped${n < capped.length ? `, ${capped.length - n} tab(s) left out` : ''}`)
return attempts[at]
diff --git a/docs/plans/2026-11-03-dial-models-list-cap-plan.md b/docs/plans/2026-11-03-dial-models-list-cap-plan.md
new file mode 100644
index 000000000..4004e61b7
--- /dev/null
+++ b/docs/plans/2026-11-03-dial-models-list-cap-plan.md
@@ -0,0 +1,54 @@
+# Round Dial: A Model List Too Big for One Frame No Longer Drops the USB Link Implementation Plan
+
+> **How this is worked:** by the project's instructions, task by task, each failing test committed before its code.
+
+**Goal:** The dial's model picker shows the selected model plus the rest, up to 48, within one frame, and an oversized frame never closes the port.
+
+**Architecture:** `models.list` (cli/src/cable/cableSession.ts) answers the selected id first, then the catalog in order, up to the dial's 48, and stops before the frame would pass `CABLE_MAX_PAYLOAD - 256` bytes or `SWARM_TOKENS_MAX` tokens, the bounds other Swarm frames already use. `send()` tells an encode failure (a message over the cap: a bug on this side) from a write failure (a dead port): the first is logged and dropped, and only the second closes the link.
+
+**Tech Stack:** TypeScript, Vitest.
+
+**Spec:** Task #2340 (Diego), brief in conversation 99cbcd773e7621eb9cd2180b.
+
+## Global Constraints
+
+- The PR body starts with: `Requested by [email protected] through Harness.`
+- No firmware change. Never publish firmware, run upload scripts or touch the device update manifest.
+- Only `cli/src/cable/cableSession.ts` and its spec change.
+- Before Ready: both new tests fail on main, red/green evidence in a PR comment, and `npm run test:super-tabs`.
+
+## Review Focus
+
+1. A selected id that is not in the catalog (an engine's list moved on): nothing invented, the list goes as it is. Test in Task 1.
+2. A single model id longer than the frame allows on its own: it is skipped, and the next ones that fit still go. Test in Task 1.
+3. A write that fails on a live port (the dial unplugged mid-frame) still closes the link, as today. The existing write-failure tests stay green.
+
+---
+
+### Task 1: models.list fits one frame
+
+**Files:**
+- Modify: `cli/src/cable/cableSession.ts:1473-1495`
+- Test: `cli/src/cable/cableSession.spec.ts` (beside 'answers models.list even when the catalog is empty')
+
+**Interfaces:**
+- Produces: the `models` reply's `items` hold at most 48 `{ id }`: the `selected` id first when the catalog lists it, then the catalog in order without it. The reply's JSON is at most `CABLE_MAX_PAYLOAD - 256` bytes, and `jsonTokens` is at most `SWARM_TOKENS_MAX`.
+
+- [ ] **Step 1: Write the failing tests** `answers a catalog too big for one frame within the cap and keeps the link` (325 runtime-v1 ids of about 100 bytes; hello, wait for `agents.end`, `models.list` request 7 selecting the 300th id: one `models` frame for request 7, at most 48 items, the selected id first, every frame within 8192 bytes, port open). Also `leaves out a selected id the catalog does not list, and an id too long to fit`.
+- [ ] **Step 2: Run** `cd cli && npx vitest run src/cable/cableSession.spec.ts -t "models"`. Expected: FAIL (the port closed with "write failed").
+- [ ] **Step 3: Commit the failing tests.**
+- [ ] **Step 4: Implement** the selection and the fitting loop in the `models.list` case.
+- [ ] **Step 5: Run** the file. Expected: PASS. **Step 6: Commit.**
+
+### Task 2: An oversized frame is dropped, not the link
+
+**Files:**
+- Modify: `cli/src/cable/cableSession.ts:2516-2527` (`send`)
+- Test: `cli/src/cable/cableSession.spec.ts`
+
+**Interfaces:**
+- Produces: `send(msg)` returns false and logs `cable: dropped a <t> frame over the cap (<n> bytes)` when the message cannot be framed; the port stays open. A write failure logs `write failed` and closes the link as today.
+
+- [ ] **Step 1: Write the failing test** `drops and logs a frame over the cap, and the link stays up`: a message of about 9000 bytes sent through the session returns false, a log line names it, `port.isOpen` stays true, and the next small message still goes.
+- [ ] **Step 2: Run.** Expected: FAIL (the port closed). **Step 3: Commit.**
+- [ ] **Step 4: Implement.** **Step 5: Run** the file and `npm run test:super-tabs`. Expected: PASS. **Step 6: Commit and push.**