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.

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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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: Take
const 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 > 0
return { 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.txt
new file mode 100644
index 000000000..0fe389826
--- /dev/null
+++ b/cli/src/lib/__fixtures__/claude-ide-chip-idle-pr-link.txt
@@ -0,0 +1,4 @@
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+❯ [⧉ In .env]
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ ⏵⏵ auto mode on (shift+tab to cycle) · PR ]8;id=7a3o4x;https://github.com/autonomous-ai/openharness/pull/1478\#1478]8;;\ · ← 3 agents
diff --git a/cli/src/lib/__fixtures__/claude-ide-chip-idle.txt b/cli/src/lib/__fixtures__/claude-ide-chip-idle.txt
new file mode 100644
index 000000000..eba21e55f
--- /dev/null
+++ b/cli/src/lib/__fixtures__/claude-ide-chip-idle.txt
@@ -0,0 +1,4 @@
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+❯ [⧉ In .env]
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+ ⏵⏵ auto mode on (shift+tab to cycle) · ← 3 agents
diff --git a/cli/src/lib/teamWriteHold.spec.ts b/cli/src/lib/teamWriteHold.spec.ts
index 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.ts
index 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 = null
const receipts: Record<string, unknown>[] = []
+ const holds: Record<string, unknown>[] = []
+ let clock = 0
const call: CoreApi['account']['backend'] = vi.fn(async (method, path, body) => {
let data: unknown
if (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.ts
index 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 publishObservers
private readonly active = new Set<string>()
private readonly authorized = new Map<string, number>()
+ private readonly withheld = new WithheldDeliveries()
private readonly stopHearing: () => void
private stopped = false
private running: Promise<void> | null = null
@@ -215,6 +217,7 @@ export class SuperTabHost {
if (result.id !== entry.deliveryId || !terminal.includes(String(result.status))) continue
if (this.journal.entries[entry.deliveryId] !== entry || this.active.has(typedId(entry))) continue
delete 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) return
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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) }
+}