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.

Agent Messages: a tab turned off holds its messages 5 minutes before they fail (#1259)

Dee2eccda165422
diff --git a/cli/src/messages/mailbox.spec.ts b/cli/src/messages/mailbox.spec.ts
index f178cddcd..6e48af151 100644
--- a/cli/src/messages/mailbox.spec.ts
+++ b/cli/src/messages/mailbox.spec.ts
@@ -25,6 +25,7 @@ function setup(over: Partial<MailboxDeps> = {}) {
const delivered: Array<[string, string, string]> = []
const statuses: DeliveryStatus[] = []
let refused: string | null = null
+ let held: string | null = null
let ready = true
const writable = vi.fn()
const deps: MailboxDeps = {
@@ -32,6 +33,7 @@ function setup(over: Partial<MailboxDeps> = {}) {
agent: () => agent,
deliver: (agentId, text, id) => { delivered.push([agentId, text, id]) },
refused: () => refused,
+ held: () => held,
ready: () => ready,
text: (_d, m) => `[${m.id}] ${m.text}`,
changed: (status) => { statuses.push(status) },
@@ -48,6 +50,7 @@ function setup(over: Partial<MailboxDeps> = {}) {
now: () => clock,
setAgent: (next: MailboxAgent | null) => { agent = next },
refuse: (why: string | null) => { refused = why },
+ hold: (why: string | null) => { held = why },
setReady: (next: boolean) => { ready = next },
claim: (pane: string, key: string) => {
// As the hook does: the rename into claimed/, which it makes.
@@ -271,6 +274,45 @@ describe('Agent Messages\' mailbox', () => {
expect(t.inbox.waiting('%3', written.key)).toBe(false)
})
+ it('holds a delivery its tab does not carry for now: out of the hook\'s reach, given to no one, put back after', () => {
+ // A tab turned off by a slip of the mouse failed the message waiting in it (2026-10-12).
+ const t = setup()
+ const waiting = t.accept({ ...message(), fyi: true })
+ expect(t.inbox.waiting('%3', waiting.key)).toBe(true)
+ t.hold('off for now')
+ t.mailbox.refuseAll()
+ expect(waiting).toMatchObject({ state: 'queued', reason: 'off for now' })
+ expect(t.inbox.waiting('%3', waiting.key)).toBe(false)
+ t.mailbox.pump()
+ expect(t.inbox.waiting('%3', waiting.key)).toBe(false)
+ t.hold(null)
+ t.mailbox.pump()
+ expect(t.inbox.waiting('%3', waiting.key)).toBe(true)
+ expect(waiting.reason).toBe(FYI_REASON)
+ // A parked attempt is back with the hook: held, it leaves the hook's reach too, and is typed again after.
+ const typed = t.accept(message('m0000002'))
+ t.event(typed.attempt!.id, 'queued')
+ t.tick(PARK_MS)
+ t.mailbox.pump()
+ expect(typed.attempt?.parked).toBe(true)
+ expect(t.inbox.waiting('%3', typed.key)).toBe(true)
+ t.hold('off for now')
+ t.mailbox.pump()
+ expect(typed).toMatchObject({ state: 'queued', reason: 'off for now', attempt: undefined })
+ expect(t.inbox.waiting('%3', typed.key)).toBe(false)
+ t.hold(null)
+ t.mailbox.pump()
+ expect(t.delivered.filter(([, , id]) => id.includes(typed.key))).toHaveLength(2)
+ // Refused for good, a parked one fails like any other.
+ t.event(typed.attempt!.id, 'queued')
+ t.tick(PARK_MS)
+ t.mailbox.pump()
+ t.refuse('gone')
+ t.mailbox.refuseAll()
+ expect(typed).toMatchObject({ state: 'failed', reason: 'gone' })
+ expect(t.inbox.waiting('%3', typed.key)).toBe(false)
+ })
+
it('fails a delivery the directory refuses, withdrawing it from the hook; nothing moves before the directory is read', () => {
const t = setup()
t.setReady(false)
diff --git a/cli/src/messages/mailbox.ts b/cli/src/messages/mailbox.ts
index f68692cd8..facdf4d24 100644
--- a/cli/src/messages/mailbox.ts
+++ b/cli/src/messages/mailbox.ts
@@ -63,6 +63,9 @@ export interface MailboxDeps {
/** Null while a delivery may still be made; otherwise why it can no longer be (it left the tab, the tab
* turned Agent Messages off). */
refused(delivery: LocalDelivery): string | null
+ /** Null while a delivery may be made; otherwise why it waits, given to no one, the hook included: its tab no longer
+ * carries it, for less long than it is held before it is refused. */
+ held?(delivery: LocalDelivery): string | null
/** Whether who may message whom is known yet: until it is, nothing is typed and nothing refused. */
ready(): boolean
/** Why a delivery may never be made, whatever the tabs say, or null: asked as the mailbox starts, before the
@@ -101,6 +104,8 @@ export const deliveryKey = (messageId: string, agentId: string): string =>
export class Mailbox {
private timer: ReturnType<typeof setInterval> | null = null
private started = false
+ /** Deliveries held out of the hook's reach while their tab does not carry them ([hold]). */
+ private readonly holding = new Set<LocalDelivery>()
constructor(private readonly deps: MailboxDeps) {}
private now(): number { return this.deps.now?.() ?? Date.now() }
private get local(): LocalDelivery[] { return this.deps.store.state.local }
@@ -204,10 +209,16 @@ export class Mailbox {
if (delivery.state !== 'queued') continue
if (delivery.reason === WAITING.team_waiting_idle) this.report(delivery, this.idleReason(delivery))
if (delivery.pane && taken.has(`${delivery.pane.slice(1)}-${delivery.key}`) && this.deps.inbox.claimed(delivery.pane, delivery.key)) { this.finish(delivery, 'hook'); continue }
- if (delivery.attempt) { this.watch(delivery); continue }
+ if (delivery.attempt) {
+ // A parked attempt is back in the hook's inbox: where its tab no longer carries it, the hook must not take it.
+ if (!delivery.attempt.parked || !this.outside(delivery)) { this.watch(delivery); continue }
+ delivery.attempt = undefined
+ }
if (!this.deps.ready()) continue
const refused = this.deps.refused(delivery)
if (refused) { this.fail(delivery, refused); continue }
+ const held = this.deps.held?.(delivery)
+ if (held) { this.hold(delivery, held); continue }
const agent = this.deps.agent(delivery.agentId)
const message = this.deps.store.entry(delivery.messageId)?.message
if (!message) { this.fail(delivery, 'the message is no longer kept'); continue }
@@ -223,7 +234,8 @@ export class Mailbox {
delivery.pane = agent.pane
delivery.session = agent.session
this.put(delivery, message, agent)
- if (delivery.reason === 'its harness is stopped') this.report(delivery, undefined)
+ const wasHeld = this.holding.delete(delivery)
+ if (wasHeld || delivery.reason === 'its harness is stopped') this.report(delivery, undefined)
this.save()
}
// News waits for the hook, or for the agent to read it: typed, it would start a turn of its own.
@@ -237,16 +249,33 @@ export class Mailbox {
}
}
- /** Withdraw what waits for an agent's messages in a tab that turned off, or that it left. */
+ /** Withdraw what waits for an agent's messages in a tab that turned off, or that it left: held for a while, then
+ * refused. */
refuseAll(): void {
if (!this.deps.ready()) return
for (const delivery of this.local) {
- if (delivery.state !== 'queued' || delivery.attempt) continue
+ if (delivery.state !== 'queued' || (delivery.attempt && !delivery.attempt.parked)) continue
const refused = this.deps.refused(delivery)
+ const held = refused ? null : this.deps.held?.(delivery)
+ if (refused || held) delivery.attempt = undefined
if (refused) this.fail(delivery, refused)
+ else if (held) this.hold(delivery, held)
}
}
+ /** Whether the tabs no longer carry a delivery, for now or for good. */
+ private outside(delivery: LocalDelivery): boolean {
+ return this.deps.ready() && Boolean(this.deps.refused(delivery) || this.deps.held?.(delivery))
+ }
+
+ /** Its tab does not carry it, for now: out of the hook's reach, given to no one, and put back once it is carried
+ * again (the pump puts what is missing from the inbox). */
+ private hold(delivery: LocalDelivery, reason: string): void {
+ this.holding.add(delivery)
+ if (delivery.pane && this.deps.inbox.waiting(delivery.pane, delivery.key)) { this.deps.inbox.withdraw(delivery.pane, delivery.key); this.save() }
+ this.report(delivery, reason)
+ }
+
/** A typed attempt in flight: parked once the core has held it behind a turn, forgotten when the core never
* took it or kept it too long. */
private watch(delivery: LocalDelivery): void {
diff --git a/cli/src/messages/service.spec.ts b/cli/src/messages/service.spec.ts
index 990460bfc..299b7f2a1 100644
--- a/cli/src/messages/service.spec.ts
+++ b/cli/src/messages/service.spec.ts
@@ -6,10 +6,10 @@ import type { BackendNotice, TurnDelivery } from '../core/api.js'
import type { RegisteredSession } from '../lib/registry.js'
import { fakeCore } from '../testing/fakeCore.js'
import { PaneInbox } from './inbox.js'
-import { deliveryKey, FYI_REASON } from './mailbox.js'
+import { deliveryKey, FYI_REASON, PUMP_MS } from './mailbox.js'
import { header, LIMITS, LONG_TEXT, longAdvice, MessageError, parseMessage, type Message } from './model.js'
import type { Rpc } from './rpc.js'
-import { REMOTE_STATUS_MS, startAgentMessages, SWEEP_AFTER_MS, TICK_MS } from './service.js'
+import { HELD_OFF_REASON, HELD_OUTSIDE_MS, REMOTE_STATUS_MS, startAgentMessages, SWEEP_AFTER_MS, TICK_MS } from './service.js'
import { MessageStore } from './store.js'
import { Ledger, ledgerPath } from '../agentClient/ledger.js'
@@ -561,16 +561,44 @@ describe('the roster note and the directory', () => {
again.stop()
})
- it('fails a waiting delivery once its tab turns Agent Messages off', async () => {
+ it('holds a waiting delivery while its tab has Agent Messages off, goes on once it is on again, and fails it later', async () => {
+ // Turned off by a slip of the mouse and on again a minute later, a tab failed the message waiting in it (2026-10-12).
+ vi.useFakeTimers()
const t = setup()
+ t.service.start()
const reply = await t.ask({ action: 'send', pane: '%1', to: 'api', text: 'x' })
t.deliveryEvent({ deliveryId: t.delivered[0][2], sessionId: 'api', state: 'rejected', reason: 'team_waiting_idle' })
- t.tabs[0].enabled = false
- t.notice({ type: 'desk_changed', revision: 6 })
- await new Promise((settle) => setTimeout(settle, 0))
- const history = await t.ask({ action: 'history', limit: 10 })
- expect((history.messages as Array<{ id: string; statuses: Array<{ state: string; reason?: string }> }>).find((m) => m.id === reply.id)!.statuses[0])
- .toMatchObject({ state: 'failed', reason: 'Agent Messages were turned off in this tab' })
+ const key = deliveryKey(reply.id as string, 'api')
+ const status = async () => ((await t.ask({ action: 'history', limit: 10 })).messages as Array<{ id: string; statuses: Array<{ state: string; reason?: string }> }>)
+ .find((m) => m.id === reply.id)!.statuses[0]
+ const turn = async (enabled: boolean) => {
+ t.tabs[0].enabled = enabled
+ t.notice({ type: 'desk_changed', revision: 6 })
+ await vi.advanceTimersByTimeAsync(0)
+ }
+ await turn(false)
+ expect(await status()).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })
+ // Given to no one meanwhile: out of the hook's reach.
+ expect(t.inbox.waiting('%2', key)).toBe(false)
+ t.tick(HELD_OUTSIDE_MS - 1)
+ await vi.advanceTimersByTimeAsync(PUMP_MS)
+ expect(await status()).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })
+ const attempts = t.delivered.length
+ await turn(true)
+ await vi.advanceTimersByTimeAsync(PUMP_MS)
+ // Carried again: put back, and typed into the idle agent.
+ expect(t.delivered.length).toBe(attempts + 1)
+ expect(t.delivered.at(-1)![2]).toContain(key)
+ expect((await status()).reason).not.toBe(HELD_OFF_REASON)
+ t.deliveryEvent({ deliveryId: t.delivered.at(-1)![2], sessionId: 'api', state: 'rejected', reason: 'team_waiting_idle' })
+ // Off for good: held a while again, then failed.
+ await turn(false)
+ expect(await status()).toMatchObject({ state: 'queued', reason: HELD_OFF_REASON })
+ t.tick(HELD_OUTSIDE_MS)
+ await vi.advanceTimersByTimeAsync(PUMP_MS)
+ expect(await status()).toMatchObject({ state: 'failed', reason: 'Agent Messages were turned off in this tab' })
+ expect(t.inbox.waiting('%2', key)).toBe(false)
+ t.service.stop()
})
it('answers a failure it did not expect without saying more', async () => {
diff --git a/cli/src/messages/service.ts b/cli/src/messages/service.ts
index 566c2fc2a..8d3fe1be8 100644
--- a/cli/src/messages/service.ts
+++ b/cli/src/messages/service.ts
@@ -58,6 +58,10 @@ export const REMOTE_STATUS_MS = 15_000
export const WHO_MS = 60_000
/** How old an inbox file nothing here waits on must be before a start sweeps it away. */
export const SWEEP_AFTER_MS = 10 * 60_000
+/** How long a delivery no tab with Agent Messages on carries is held, given to no one, before it fails. */
+export const HELD_OUTSIDE_MS = 5 * 60_000
+export const HELD_OFF_REASON = 'Agent Messages are off in this tab: it waits 5 minutes for them to be on again, then fails'
+export const HELD_LEFT_REASON = 'it is not in a tab with the sender: it waits 5 minutes for that to change, then fails'
const PANE = /^%\d{1,9}$/
/** The most messages `harness send` alone gives an agent at once, unread ones first. */
@@ -115,7 +119,8 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})
return { pane: session.tmuxPane, session: session.sessionId ?? '', available: session.active && core.agents.terminalAvailable(agentId) }
},
deliver: (agentId, text, deliveryId) => { core.turns.deliver(agentId, text, deliveryId); options.changed?.() },
- refused: (delivery) => refusal(delivery),
+ refused: (delivery) => { const v = verdict(delivery); return v && 'refused' in v ? v.refused : null },
+ held: (delivery) => { const v = verdict(delivery); return v && 'held' in v ? v.held : null },
forbidden: (delivery) => forbidden(delivery),
ready: () => directory.current() !== null,
text: (delivery, message) => {
@@ -137,19 +142,34 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})
return store.entry(delivery.messageId)?.message.tabId === 'started' ? 'it was sent outside any tab with Agent Messages on' : null
}
- /** Why a local delivery can no longer be made, or null. Only what may never be made is refused before the
- * directory is read. */
- function refusal(delivery: LocalDelivery): string | null {
+ /** When the tabs stopped carrying each local delivery (`messageId agentId`), while they do not. */
+ const outsideSince = new Map<string, number>()
+
+ /**
+ * Whether a local delivery may be made: null; held, given to no one, while no tab with Agent Messages on carries
+ * it, for HELD_OUTSIDE_MS; refused after that, or at once when it may never be made. Only what may never be made is
+ * refused before the directory is read. A tab turned off by a slip of the mouse and on again a minute later failed
+ * the message waiting in it (owner, 2026-10-12): held, it goes on once the tab is on again.
+ */
+ function verdict(delivery: LocalDelivery): { refused: string } | { held: string } | null {
const entry = store.entry(delivery.messageId)
- if (!entry) return 'the message is no longer kept'
+ if (!entry) return { refused: 'the message is no longer kept' }
const never = forbidden(delivery)
- if (never) return never
+ if (never) return { refused: never }
if (!directory.current()) return null
+ const key = `${delivery.messageId} ${delivery.agentId}`
const recipient = { machineId: self(), agentId: delivery.agentId }
// Only a tab with Agent Messages on carries a message.
- if (directory.shared(entry.message.from, recipient)) return null
+ if (directory.shared(entry.message.from, recipient)) { outsideSince.delete(key); return null }
const tab = directory.current()!.tabs.find((t) => t.id === entry.message.tabId)
- return tab && !tab.enabled ? 'Agent Messages were turned off in this tab' : 'it is no longer in a tab with the sender'
+ const off = Boolean(tab && !tab.enabled)
+ const since = outsideSince.get(key) ?? now()
+ if (now() - since < HELD_OUTSIDE_MS) {
+ outsideSince.set(key, since)
+ return { held: off ? HELD_OFF_REASON : HELD_LEFT_REASON }
+ }
+ outsideSince.delete(key)
+ return { refused: off ? 'Agent Messages were turned off in this tab' : 'it is no longer in a tab with the sender' }
}
function localChanged(status: DeliveryStatus, delivery: LocalDelivery): void {
diff --git a/docs/design/2026-10-10-agent-messages.md b/docs/design/2026-10-10-agent-messages.md
index 155206105..b8c46ffaf 100644
--- a/docs/design/2026-10-10-agent-messages.md
+++ b/docs/design/2026-10-10-agent-messages.md
@@ -245,6 +245,11 @@ returns; a start sweeps old files nothing waits on.
States: **queued**, **delivered** (claimed by the hook, or typed; "unconfirmed" when the core could not say),
**failed** (the recipient left the tab or the flag was turned off), each with the time, the route and a reason.
+A delivery no tab with Agent Messages on carries any more is held for 5 minutes before it fails: out of the hook's
+reach and never typed, so off still means off, and put back once a tab carries it again. A tab turned off by a slip
+of the mouse and on again a minute later failed the message waiting in it (owner, 2026-10-12); a harness that leaves
+its tab for a moment loses nothing either.
+
### Limits
Per sender: 30 messages in 10 minutes, then `RATE_LIMITED` and an alert to the person. Per message: 16,000