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.
TypeScript 3d-modelingagent-frameworkagent-harnessai-agentscadclaude-codecodexcoding-agentsdeveloper-toolsesp32game-developmentmcp-servermulti-agentopen-hardwareopencodeopenharnesspcbroboticsterminaltmux
Merge batch 11-03 b1748: #2744 #2766 (#2792)
0xken15b8b07a2fae71
diff --git a/backend/src/superTabs/liveness.ts b/backend/src/superTabs/liveness.tsindex 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 undefinedconst 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.assignmentreturn 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 nullconst 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 nullif (!projectsOf(state).some(p => p.id === (group.projectId ?? 'lead'))) return nullconst assignment = group.assignment@@ -402,11 +449,14 @@ export function taskLiveness(state: SuperTabState, group: Conversation, now: numconst asked = assignment.askedOf && state.people.some(p => p.id === assignment.askedOf) ? assignment.askedOf : undefinedreturn { 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')) returnif (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)) continueif (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.tsindex 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.tsindex 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.tsindex 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 = 0const SWARM_IDS_MAX = 24const 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.requestconst 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) continueif (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.mdnew file mode 100644index 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.**