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
Super Tab: say why a delivery waits, and stop reading the IDE chip as a draft (#1478)
Jacob Pham7f06cbcb3f7e
diff --git a/backend/integration/superTabs.test.ts b/backend/integration/superTabs.test.tsindex 1b71e1c3e..6799510b8 100644--- a/backend/integration/superTabs.test.ts+++ b/backend/integration/superTabs.test.ts@@ -497,6 +497,25 @@ describe('Super Tabs on a real Mongo replica set', () => {expect(await db.superTabConfiguration.count({ where: { tabId: tab } })).toBe(3)})+ it('tells the group once, in plain words, that a claimed delivery is waiting, and only for the claim holder', async () => {+ const { tab, lead } = await fixture()+ await run(tab, message('Please start.'))+ const delivery = (await store.deliveries(host, tab, lead))[0]!+ await expect(store.delivery(host, tab, lead, delivery.id, { type: 'hold', claimId: 'claim', reason: 'team_waiting_draft' }))+ .rejects.toMatchObject({ code: 'NOT_CLAIMED' })+ await store.delivery(host, tab, lead, delivery.id, { type: 'claim', claimId: 'claim' })+ await expect(store.delivery(host, tab, lead, delivery.id, { type: 'hold', claimId: 'another', reason: 'team_waiting_draft' }))+ .rejects.toMatchObject({ code: 'CLAIM_CONFLICT' })+ expect(await store.delivery(host, tab, lead, delivery.id, { type: 'hold', claimId: 'claim', reason: 'team_waiting_draft' })).toEqual({ noticed: true })+ expect(await store.delivery(host, tab, lead, delivery.id, { type: 'hold', claimId: 'claim', reason: 'team_waiting_idle' })).toEqual({ noticed: false })+ const rows = (await store.messages(owner, tab, 'lead', {})).messages+ expect(rows).toHaveLength(2)+ expect(rows[1]).toMatchObject({ author: { kind: 'agent', id: lead }, recipientIds: [], deliveries: [],+ text: expect.stringContaining('A message for Lead is waiting. There is unsent text in Lead\'s input box.') })+ await store.delivery(host, tab, lead, delivery.id, { type: 'ack', claimId: 'claim', receipt: 'done', uncertain: false })+ expect(await store.delivery(host, tab, lead, delivery.id, { type: 'hold', claimId: 'claim', reason: 'team_waiting_idle' })).toEqual({ noticed: false })+ })+it('a withdrawn host can retire its receipt without regaining conversation access', async () => {const { tab, lead } = await fixture()await run(tab, message('Keep the execution receipt after removal.'))diff --git a/backend/src/routes/superTabs.ts b/backend/src/routes/superTabs.tsindex 749b7d417..7caa01042 100644--- a/backend/src/routes/superTabs.ts+++ b/backend/src/routes/superTabs.ts@@ -10,6 +10,7 @@ import { routingPolicySchema } from '../superTabs/routingPolicy.js'import { nativeEventSchema, openNativeSchema } from '../superTabs/native.js'import { machineObservationSchema } from '../superTabs/machines.js'import { joinSwarmSchema, previewJoinSchema, saveSharingSchema } from '../superTabs/sharing.js'+import { holdReason } from '../superTabs/holdNotice.js'const id = z.string().min(1).max(160).regex(/^[A-Za-z0-9_-]+$/)const tabParams = z.object({ tabId: id })@@ -32,6 +33,7 @@ const deliveryActionParams = deliveryParams.extend({ deliveryId: id })const deliveryAction = z.discriminatedUnion('type', [z.object({ type: z.literal('claim'), claimId: id }).strict(),z.object({ type: z.literal('ack'), claimId: id, receipt: z.string().min(1).max(2000), uncertain: z.boolean() }).strict(),+ z.object({ type: z.literal('hold'), claimId: id, reason: holdReason }).strict(),])const savePolicy = z.object({ revision: z.number().int().nonnegative().safe(), policy: routingPolicySchema }).strict()const stop = z.object({ assignmentId: id, receipt: z.string().min(1).max(2000) }).strict()diff --git a/backend/src/superTabs/holdNotice.test.ts b/backend/src/superTabs/holdNotice.test.tsnew file mode 100644index 000000000..8bce61924--- /dev/null+++ b/backend/src/superTabs/holdNotice.test.ts@@ -0,0 +1,18 @@+import { describe, expect, it } from 'vitest'+import { holdNoticeText, holdReason } from './holdNotice.js'++describe('holdNoticeText', () => {+ it('says in plain words why a delivery waits, for every reason a host can report', () => {+ const lines = holdReason.options.map(reason => holdNoticeText('Lead', reason))+ expect(new Set(lines).size).toBe(holdReason.options.length)+ for (const line of lines) {+ expect(line).toMatch(/^A message for Lead is waiting\. .*It stays queued and goes in by itself as soon as that clears\.$/)+ expect(line).not.toMatch(/team_waiting|_/)+ }+ expect(holdNoticeText('Lead', 'team_waiting_draft')).toContain("There is unsent text in Lead's input box.")+ })++ it('rejects a reason it has no words for', () => {+ expect(holdReason.safeParse('team_waiting_busy').success).toBe(false)+ })+})diff --git a/backend/src/superTabs/holdNotice.ts b/backend/src/superTabs/holdNotice.tsnew file mode 100644index 000000000..6494708d5--- /dev/null+++ b/backend/src/superTabs/holdNotice.ts@@ -0,0 +1,21 @@+import { z } from 'zod'++/**+ * Why a host reports that it cannot type a delivery into an agent's terminal yet. These are the reasons the+ * harness core gives (cli/src/engines/kit/screen.ts); the host sends the code and the words live here, so+ * every client and every language of the conversation reads the same sentence.+ */+export const holdReason = z.enum(['team_waiting_unavailable', 'team_waiting_user', 'team_waiting_draft', 'team_waiting_idle', 'team_waiting_control'])+export type HoldReason = z.infer<typeof holdReason>++const WHY: Record<HoldReason, (name: string) => string> = {+ team_waiting_unavailable: name => `${name}'s terminal cannot be read right now.`,+ team_waiting_user: name => `${name} is showing a question or menu that needs a person to answer it.`,+ team_waiting_draft: name => `There is unsent text in ${name}'s input box.`,+ team_waiting_idle: name => `${name} is still busy, or its input box is not ready.`,+ team_waiting_control: name => `Someone else is using ${name}'s terminal right now.`,+}++/** The one notice a conversation gets about a delivery that has waited over 30 seconds (2026-10-21: minutes, unexplained). */+export const holdNoticeText = (agentName: string, reason: HoldReason): string =>+ `A message for ${agentName} is waiting. ${WHY[reason](agentName)} It stays queued and goes in by itself as soon as that clears.`diff --git a/backend/src/superTabs/store.ts b/backend/src/superTabs/store.tsindex bf35b7900..3d19e8a17 100644--- a/backend/src/superTabs/store.ts+++ b/backend/src/superTabs/store.ts@@ -14,6 +14,7 @@ import {activeWork, actorKey, agent, author, conversation, createSuperTab, fail, person, stableId, visibleState,SuperTabError, type Actor, type Agent, type Assignment, type Author, type MessageDraft, type SuperTabState,} from './model.js'+import { holdNoticeText, type HoldReason } from './holdNotice.js'import { closeAssignment, readDecision, recentRoutes, timedDecisionOf, writeRouteEffects } from './routeDecisions.js'import { DEFAULT_ROUTING_POLICY, effectivePolicy, routingPolicySchema, type RoutingPolicy } from './routingPolicy.js'import { authenticatedEmail, authorizeSwarmJoin, configureSharing, joinSwarmSchema, requireSharingOwner,@@ -726,7 +727,8 @@ export class SuperTabStore {/** No timeout reclaims an instruction: the same durable claim resumes, or the host reconciles it. */async delivery(user: AuthUser, tabId: string, agentId: string, deliveryId: string,- action: { type: 'claim'; claimId: string } | { type: 'ack'; claimId: string; receipt: string; uncertain: boolean }) {+ action: { type: 'claim'; claimId: string } | { type: 'ack'; claimId: string; receipt: string; uncertain: boolean }+ | { type: 'hold'; claimId: string; reason: HoldReason }) {return transaction(this.db, async tx => {const row = await this.row(tx, user, tabId)const state = stateOf(row)@@ -739,7 +741,8 @@ export class SuperTabStore {fail('DELIVERY_RESOLVED', 'A person has already resolved this delivery.')}if (delivery.claimId && delivery.claimId !== action.claimId) fail('CLAIM_CONFLICT', 'Reconcile the existing delivery before claiming it again.')- if (action.type === 'ack' && !delivery.claimId) fail('NOT_CLAIMED', 'Claim this instruction before acknowledging it.')+ if (action.type !== 'claim' && !delivery.claimId) fail('NOT_CLAIMED', 'Claim this instruction before acknowledging it.')+ if (action.type === 'hold') return this.holdNotice(tx, row, state, delivery, action.reason)const status = action.type === 'claim' ? delivery.status === 'queued' ? 'claimed' : delivery.status : action.uncertain ? 'uncertain' : 'delivered'if (delivery.status === 'delivered' && action.type === 'ack' && (action.uncertain || delivery.receipt !== action.receipt)) {fail('RECEIPT_CONFLICT', 'A delivered instruction keeps its original host receipt.')@@ -753,6 +756,19 @@ export class SuperTabStore {})}+ /** The host cannot type a claimed instruction yet. Say so once in the group, as the waiting agent; nobody is asked to act on it. */+ private async holdNotice(tx: Transaction, row: SuperTab, state: SuperTabState, delivery: SuperTabDelivery, reason: HoldReason) {+ const id = stableId('hold-notice', delivery.tabId, delivery.id)+ if (delivery.status !== 'claimed' || await tx.superTabMessage.findUnique({ where: { id } })) return { noticed: false }+ const group = conversation(state, delivery.conversationId), waiting = agent(state, delivery.agentId)+ const revision = row.revision + 1+ group.lastMessageSequence = revision+ await tx.superTab.update({ where: { id: row.id, revision: row.revision }, data: { revision, state: json(state) } })+ await this.writeMessages(tx, row.id, state, [{ id, conversationId: group.id, replyTo: null, recipients: [], text: holdNoticeText(waiting.name, reason),+ author: { kind: 'agent', id: waiting.id, name: waiting.name, membershipGeneration: waiting.membershipGeneration } }], revision)+ return { noticed: true }+ }+/** Only the recorded execution host may attest that the actual session/attempt has stopped. */async stopped(user: AuthUser, tabId: string, assignmentId: string, receipt: string) {return transaction(this.db, async tx => {diff --git a/cli/src/engines/kit/pane.ts b/cli/src/engines/kit/pane.tsindex 92aaee900..877901819 100644--- a/cli/src/engines/kit/pane.ts+++ b/cli/src/engines/kit/pane.ts@@ -229,11 +229,20 @@ export function inspectPane(engine: AgentEngine, capture: string, takeover: Takeconst rawMarker = prompt.search(marks)const rawTail = rawMarker >= 0 ? prompt.slice(rawMarker + 1) : ''const placeholder = hasPlaceholderSgr(rawTail)- if (placeholder) visible = ''+ if (placeholder || IDE_CONTEXT_CHIPS.test(visible)) visible = ''const draft = visible.length > 0return { idle: !!prompt && !dialog && !draft, plan, dialog, draft }}+/**+ * Claude Code shows what the connected IDE has open or selected as a chip in the empty composer, `❯ [⧉ In .env]` or+ * `❯ [⧉ Selected 3 lines from a.ts]`, in a colour of its own (not dim, not grey). It is context sent with the next+ * message, not text anyone typed. Read as a draft, an idle pane held every Super Tab delivery as+ * `team_waiting_draft`, and the same message was retried every second (2026-10-21, 10:44-10:49, 266 times).+ * ONLY chips and nothing else: any word typed beside one is a real draft and still holds.+ */+const IDE_CONTEXT_CHIPS = /^(?:\[⧉ [^\]]+\]\s*)+$/u+/** The latest composer prompt line; picker rows use the same glyphs, but numbered rows are not prompts. */function latestPromptLine(rawLines: string[], marks: RegExp): number {return rawLines.findLastIndex((line) => {diff --git a/cli/src/lib/__fixtures__/claude-ide-chip-idle-pr-link.txt b/cli/src/lib/__fixtures__/claude-ide-chip-idle-pr-link.txtnew file mode 100644index 000000000..0fe389826--- /dev/null+++ b/cli/src/lib/__fixtures__/claude-ide-chip-idle-pr-link.txt@@ -0,0 +1,4 @@+[38;5;244m────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────+[39m❯ [38;5;74m[⧉ In .env][39m+[38;5;244m────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────+[39m [38;5;220m⏵⏵ auto mode on[38;5;246m (shift+tab to cycle) · PR[39m [4m[38;5;220m]8;id=7a3o4x;https://github.com/autonomous-ai/openharness/pull/1478\#1478[0m[38;5;246m]8;;\ · ← 3 agentsdiff --git a/cli/src/lib/__fixtures__/claude-ide-chip-idle.txt b/cli/src/lib/__fixtures__/claude-ide-chip-idle.txtnew file mode 100644index 000000000..eba21e55f--- /dev/null+++ b/cli/src/lib/__fixtures__/claude-ide-chip-idle.txt@@ -0,0 +1,4 @@+[38;5;244m────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────+[39m❯ [38;5;74m[⧉ In .env][39m+[38;5;244m────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────+[39m [38;5;220m⏵⏵ auto mode on[38;5;246m (shift+tab to cycle) · ← 3 agents[39mdiff --git a/cli/src/lib/teamWriteHold.spec.ts b/cli/src/lib/teamWriteHold.spec.tsindex 757df57de..6725e569e 100644--- a/cli/src/lib/teamWriteHold.spec.ts+++ b/cli/src/lib/teamWriteHold.spec.ts@@ -1,3 +1,4 @@+import { readFileSync } from 'node:fs'import { expect, it } from 'vitest'import { teamWriteHold } from './teamWriteHold.js'import { CLAUDE_REWIND_CONFIRM, CLAUDE_REWIND_EMPTY, CLAUDE_REWIND_LIST, CODEX_BROWSING_SCROLLBACK } from './__fixtures__/rewindPickers.js'@@ -33,3 +34,18 @@ it('holds a delivery while Claude Code\'s Rewind menu is open, as someone at the// And Codex's scrollback browser, a pager over the whole pane, the same way as its fullscreen one.expect(teamWriteHold('codex', CODEX_BROWSING_SCROLLBACK)).toBe('team_waiting_user')})++it('does not read the IDE context chip in an empty Claude composer as a human draft', () => {+ // A real capture (tmux capture-pane -e, 2026-10-21) of an idle Lead pane with `.env` open in the IDE. It was held as+ // `team_waiting_draft`, and the delivery was retried every second for minutes.+ const idle = readFileSync(new URL('./__fixtures__/claude-ide-chip-idle.txt', import.meta.url), 'utf8')+ expect(teamWriteHold('claude', idle)).toBeNull()+ expect(teamWriteHold('claude', idle.replace('[⧉ In .env]', '[⧉ In .env] [⧉ Selected 3 lines from a.ts]'))).toBeNull()+ // Anything typed beside a chip is still somebody's draft.+ expect(teamWriteHold('claude', idle.replace('[⧉ In .env]', '[⧉ In .env] fix the'))).toBe('team_waiting_draft')+ expect(teamWriteHold('claude', idle.replace('[⧉ In .env]', 'fix the [⧉ In .env]'))).toBe('team_waiting_draft')+ // The same Lead pane at 11:05, once its footer carried an OSC 8 link to the open PR: the user's next message sat+ // as Queued behind the same chip.+ const linked = readFileSync(new URL('./__fixtures__/claude-ide-chip-idle-pr-link.txt', import.meta.url), 'utf8')+ expect(teamWriteHold('claude', linked)).toBeNull()+})diff --git a/cli/src/superTabs/host.spec.ts b/cli/src/superTabs/host.spec.tsindex 6e25737ca..ab550e847 100644--- a/cli/src/superTabs/host.spec.ts+++ b/cli/src/superTabs/host.spec.ts@@ -17,6 +17,8 @@ function setup(messageFields: Record<string, unknown> = {}) {const row = { tabId: 'tab', agent: { id: 'agent', harnessId: 'harness', machineId: 'machine-1' } }let removed = false, revoked = false, status = 'queued', claimId: string | null = nullconst receipts: Record<string, unknown>[] = []+ const holds: Record<string, unknown>[] = []+ let clock = 0const call: CoreApi['account']['backend'] = vi.fn(async (method, path, body) => {let data: unknownif (path.includes('/hosts/')) data = removed ? [] : [row]@@ -25,6 +27,7 @@ function setup(messageFields: Record<string, unknown> = {}) {else {const command = body as Record<string, unknown>if (command.type === 'claim') { claimId = command.claimId as string; status = 'claimed' }+ else if (command.type === 'hold') holds.push(command)else { receipts.push(command); status = command.uncertain ? 'uncertain' : 'delivered' }data = { delivery: { id: 'delivery', claimId, status }, message: { id: 'message', conversationId: 'lead', text: 'Build the agreed feature.', author: { name: 'Collaborator' }, ...messageFields } }}@@ -35,12 +38,13 @@ function setup(messageFields: Record<string, unknown> = {}) {account: { backend: call },turns: { onDelivery: vi.fn(fn => { listeners.add(fn); return () => { listeners.delete(fn) } }) },})- const open = () => { const host = new SuperTabHost(core, 'machine-1', { log: vi.fn() }); hosts.push(host); return host }+ const log = vi.fn()+ const open = () => { const host = new SuperTabHost(core, 'machine-1', { log, now: () => clock }); hosts.push(host); return host }const event = (state: TurnDelivery['state'], reason?: string) => {for (const fn of listeners) fn({ deliveryId: 'team:service:superTabs:delivery', sessionId: 'harness', state, reason })}const saved = () => JSON.parse(readFileSync(hostJournalFile(dir, 'machine-1'), 'utf8'))- return { core, call, open, event, receipts, saved, dir, remove: () => { removed = true }, revoke: (value = true) => { revoked = value }, foreignClaim: () => { claimId = 'another-process' } }+ return { core, call, open, event, receipts, holds, log, wait: (ms: number) => { clock += ms }, saved, dir, remove: () => { removed = true }, revoke: (value = true) => { revoked = value }, foreignClaim: () => { claimId = 'another-process' } }}describe('Super Tab native delivery handoff', () => {@@ -230,6 +234,50 @@ describe('Super Tab native delivery handoff', () => {expect(t.receipts.every(r => r.uncertain === true)).toBe(true)})+ it('logs why the core withholds a delivery once per change of reason, with how long it has waited', async () => {+ const t = setup(), host = t.open()+ await host.tick()+ for (const [reason, seconds] of [['team_waiting_draft', 0], ['team_waiting_draft', 5], ['team_waiting_idle', 10]] as const) {+ t.wait(seconds * 1000 - (seconds === 10 ? 5_000 : 0)); t.event('rejected', reason); await host.tick()+ }+ t.event('rejected', 'team_waiting_idle')+ const lines = t.log.mock.calls.map(([line]) => line as string).filter(line => line.includes('withheld'))+ expect(lines).toEqual([+ expect.stringContaining('withheld: team_waiting_draft, waiting 0s'),+ expect.stringContaining('withheld: team_waiting_idle, waiting 10s'),+ ])+ })++ it('tells the conversation once, in plain words, when a delivery waits over 30 seconds', async () => {+ const t = setup(), host = t.open()+ await host.tick()+ t.event('rejected', 'team_waiting_draft'); await host.tick()+ t.wait(29_000); t.event('rejected', 'team_waiting_draft'); await host.tick()+ expect(t.holds).toEqual([])+ t.wait(2_000); t.event('rejected', 'team_waiting_draft'); await host.tick()+ t.event('rejected', 'team_waiting_draft'); await host.tick()+ await vi.waitFor(() => expect(t.holds).toEqual([{ type: 'hold', claimId: expect.any(String), reason: 'team_waiting_draft' }]))+ t.wait(60_000); t.event('rejected', 'team_waiting_draft'); await host.tick()+ expect(t.holds).toHaveLength(1)+ })++ it('asks again for a notice that failed, but only after another 30 seconds, and says an unknown reason as unavailable', async () => {+ const t = setup(), host = t.open()+ await host.tick()+ t.event('rejected', 'team_waiting_busy'); await host.tick()+ const original = vi.mocked(t.call).getMockImplementation()!+ vi.mocked(t.call).mockImplementation(async (method, path, body) => {+ if ((body as any)?.type === 'hold') throw new Error('Backend offline')+ return original(method, path, body)+ })+ t.wait(31_000); t.event('rejected', 'team_waiting_busy'); await host.tick()+ await vi.waitFor(() => expect(t.log).toHaveBeenCalledWith('Backend offline'))+ t.wait(10_000); t.event('rejected', 'team_waiting_busy'); await host.tick()+ vi.mocked(t.call).mockImplementation(original)+ t.wait(21_000); t.event('rejected', 'team_waiting_busy'); await host.tick()+ await vi.waitFor(() => expect(t.holds).toEqual([expect.objectContaining({ reason: 'team_waiting_unavailable' })]))+ })+it('withdraws queued input on removal or revoked machine access and cannot revive it by re-sharing', async () => {const t = setup(), host = t.open()await host.tick(); t.revoke(); await host.tick()diff --git a/cli/src/superTabs/host.ts b/cli/src/superTabs/host.tsindex 1d271f815..499860faa 100644--- a/cli/src/superTabs/host.ts+++ b/cli/src/superTabs/host.ts@@ -8,6 +8,7 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'import { dirname, join } from 'node:path'import type { CoreApi, TurnDelivery } from '../core/api.js'import { shellQuote } from '../orchestrator/prompts.js'+import { noticeReason, WithheldDeliveries } from './withheld.js'type Json = Record<string, unknown>export class SuperTabHostError extends Error {@@ -75,6 +76,7 @@ export class SuperTabHost {private readonly observers: typeof publishObserversprivate readonly active = new Set<string>()private readonly authorized = new Map<string, number>()+ private readonly withheld = new WithheldDeliveries()private readonly stopHearing: () => voidprivate stopped = falseprivate running: Promise<void> | null = null@@ -215,6 +217,7 @@ export class SuperTabHost {if (result.id !== entry.deliveryId || !terminal.includes(String(result.status))) continueif (this.journal.entries[entry.deliveryId] !== entry || this.active.has(typedId(entry))) continuedelete this.journal.entries[entry.deliveryId]+ this.withheld.clear(entry.deliveryId)this.persist()} catch { /* Missing authority or a network failure is not a receipt. */ }}@@ -297,6 +300,7 @@ export class SuperTabHost {if (!entry) returnconst id = typedId(entry)delete this.journal.entries[deliveryId]+ this.withheld.clear(deliveryId)this.authorized.delete(id)if (this.active.delete(id)) this.core.turns.cancelDelivery(id)this.persist()@@ -385,6 +389,19 @@ export class SuperTabHost {+ native + reply + `Message ${String(message.id)} from ${String(object(message.author).name ?? 'a collaborator')}:\n${message.text}`}+ /** Says why the core keeps holding this delivery: once in the log per change of reason, and once to the conversation after 30 s. */+ private reportWithheld(entry: Entry, reason: string): void {+ const now = this.now()+ const reading = this.withheld.record(entry.deliveryId, reason, now)+ if (reading.changed) this.log(`delivery ${entry.deliveryId} to ${entry.harnessId} withheld: ${reason}, waiting ${Math.round(reading.waitedMs / 1000)}s`)+ if (!reading.noticeDue) return+ this.withheld.noticeStarted(entry.deliveryId, now)+ const path = `/api/super-tabs/${entry.tabId}/agents/${entry.agentId}/deliveries/${entry.deliveryId}`+ backend(this.core, 'POST', path, { type: 'hold', claimId: entry.claimId, reason: noticeReason(reason) })+ .then(() => this.withheld.noticed(entry.deliveryId))+ .catch(error => this.log(error instanceof Error ? error.message : String(error)))+ }+private heard(event: TurnDelivery): void {const entry = Object.values(this.journal.entries).find(e => typedId(e) === event.deliveryId)if (this.stopped || !entry || event.sessionId !== entry.harnessId || !this.active.has(event.deliveryId)) return@@ -396,7 +413,9 @@ export class SuperTabHost {// expired authority). A later fresh check may retry the same claim safely.entry.stage = 'prepared'delete entry.receipt+ this.reportWithheld(entry, event.reason)} else {+ 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/withheld.spec.ts b/cli/src/superTabs/withheld.spec.tsnew file mode 100644index 000000000..9d6b2a983--- /dev/null+++ b/cli/src/superTabs/withheld.spec.ts@@ -0,0 +1,36 @@+import { describe, expect, it } from 'vitest'+import { noticeReason, WAITING_NOTICE_AFTER_MS, WithheldDeliveries } from './withheld.js'++describe('WithheldDeliveries', () => {+ it('reports a reason once, then again only when it changes', () => {+ const waits = new WithheldDeliveries()+ expect(waits.record('d', 'team_waiting_draft', 1_000)).toMatchObject({ changed: true, waitedMs: 0 })+ expect(waits.record('d', 'team_waiting_draft', 2_000)).toMatchObject({ changed: false, waitedMs: 1_000 })+ expect(waits.record('d', 'team_waiting_idle', 3_000)).toMatchObject({ changed: true, waitedMs: 2_000 })+ })++ it('owes the one notice after 30 seconds, and asks again only after a failed attempt has aged', () => {+ const waits = new WithheldDeliveries()+ waits.record('d', 'team_waiting_idle', 0)+ expect(waits.record('d', 'team_waiting_idle', WAITING_NOTICE_AFTER_MS - 1).noticeDue).toBe(false)+ expect(waits.record('d', 'team_waiting_idle', WAITING_NOTICE_AFTER_MS).noticeDue).toBe(true)+ waits.noticeStarted('d', WAITING_NOTICE_AFTER_MS)+ expect(waits.record('d', 'team_waiting_idle', WAITING_NOTICE_AFTER_MS + 1).noticeDue).toBe(false)+ expect(waits.record('d', 'team_waiting_idle', 2 * WAITING_NOTICE_AFTER_MS).noticeDue).toBe(true)+ waits.noticed('d')+ expect(waits.record('d', 'team_waiting_idle', 9 * WAITING_NOTICE_AFTER_MS).noticeDue).toBe(false)+ })++ it('starts counting again for a delivery that was cleared, and ignores ones it never saw', () => {+ const waits = new WithheldDeliveries()+ waits.noticed('nobody'); waits.noticeStarted('nobody', 0)+ waits.record('d', 'team_waiting_idle', 0)+ waits.clear('d')+ expect(waits.record('d', 'team_waiting_idle', 90_000)).toMatchObject({ changed: true, waitedMs: 0, noticeDue: false })+ })++ it('passes known reasons and says any other as unavailable', () => {+ expect(noticeReason('team_waiting_user')).toBe('team_waiting_user')+ expect(noticeReason('team_waiting_busy')).toBe('team_waiting_unavailable')+ })+})diff --git a/cli/src/superTabs/withheld.ts b/cli/src/superTabs/withheld.tsnew file mode 100644index 000000000..86dfb2ab7--- /dev/null+++ b/cli/src/superTabs/withheld.ts@@ -0,0 +1,46 @@+/** How long a delivery may wait for an idle terminal before the conversation is told. */+export const WAITING_NOTICE_AFTER_MS = 30_000++/** The reasons the backend can put into words. Anything else the core invents is told as `team_waiting_unavailable`. */+const NOTICE_REASONS = ['team_waiting_unavailable', 'team_waiting_user', 'team_waiting_draft', 'team_waiting_idle', 'team_waiting_control']+export const noticeReason = (reason: string): string => NOTICE_REASONS.includes(reason) ? reason : 'team_waiting_unavailable'++interface Wait { since: number; reason: string; noticed: boolean; retryAt: number }+export interface WithheldReading {+ /** The reason differs from the one last recorded, so it is worth one log line. */+ changed: boolean+ waitedMs: number+ /** The conversation is owed its one notice. */+ noticeDue: boolean+}++/**+ * Remembers, per delivery, why the core keeps holding it back and since when. On 2026-10-21 (10:44:57-10:49:25) an+ * idle Claude pane was refused 266 times and nothing said why, neither in harness.log nor to the people waiting.+ */+export class WithheldDeliveries {+ private readonly waits = new Map<string, Wait>()++ record(deliveryId: string, reason: string, now: number): WithheldReading {+ const known = this.waits.get(deliveryId)+ const wait = known ?? { since: now, reason, noticed: false, retryAt: 0 }+ this.waits.set(deliveryId, wait)+ const changed = !known || known.reason !== reason+ wait.reason = reason+ const waitedMs = now - wait.since+ return { changed, waitedMs, noticeDue: !wait.noticed && waitedMs >= WAITING_NOTICE_AFTER_MS && now >= wait.retryAt }+ }++ noticed(deliveryId: string): void {+ const wait = this.waits.get(deliveryId)+ if (wait) wait.noticed = true+ }++ /** The notice is being posted. If it fails, it is asked for again after another interval, not on every retry. */+ noticeStarted(deliveryId: string, now: number): void {+ const wait = this.waits.get(deliveryId)+ if (wait) wait.retryAt = now + WAITING_NOTICE_AFTER_MS+ }++ clear(deliveryId: string): void { this.waits.delete(deliveryId) }+}