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.

fix(messages): never deliver what an older version queued under `started` (#1212)

Deef4e760931339
diff --git a/cli/src/agentClient/commands.ts b/cli/src/agentClient/commands.ts
index f4ec6a876..b136de9ec 100644
--- a/cli/src/agentClient/commands.ts
+++ b/cli/src/agentClient/commands.ts
@@ -494,7 +494,7 @@ const memberKey = (machineId: string, agentId: string): string => `${machineId}/
*/
export function spawnRefusal(caller: Caller, live: ReadonlySet<string>, ledger: Ledger, localMachineId: string, now: number): string | null {
if (ledger.depthOf(caller) >= SPAWN_LIMITS.depth) {
- return 'A harness started this far down may not start more. Do the work yourself, or tell the harness that started you.'
+ return 'A harness started this far down may not start more. Do the work yourself, or say so in your answer.'
}
const mine = ledger.childrenOf(caller)
const liveMine = new Set(mine.filter((row) => live.has(memberKey(row.child.machineId, row.child.agentId))).map((row) => memberKey(row.child.machineId, row.child.agentId)))
diff --git a/cli/src/messages/mailbox.spec.ts b/cli/src/messages/mailbox.spec.ts
index 99c4624f8..a12ca8484 100644
--- a/cli/src/messages/mailbox.spec.ts
+++ b/cli/src/messages/mailbox.spec.ts
@@ -312,6 +312,27 @@ describe('Agent Messages\' mailbox', () => {
expect(t.writable).not.toHaveBeenCalled()
})
+ it('on start, fails what may never be delivered before the directory is read and before anything goes back to a hook', () => {
+ const t = setup()
+ const never = t.accept(message('m0000006'))
+ const fine = t.accept(message('m0000007'))
+ expect(never.attempt).toBeDefined()
+ t.store.save()
+ const statuses: DeliveryStatus[] = []
+ // The directory is not read yet (signed out, the backend down): nothing else is refused.
+ const restarted = new Mailbox({ store: new MessageStore(join(root, 'state')), inbox: t.inbox, agent: () => null, deliver: () => {}, refused: () => 'refused', ready: () => false,
+ forbidden: (d) => (d.messageId === 'm0000006' ? 'it was sent outside any tab with Agent Messages on' : null), text: () => '', changed: (s) => { statuses.push(s) }, now: t.now })
+ restarted.start()
+ restarted.stop()
+ const state = new MessageStore(join(root, 'state')).state.local
+ expect(state.find((d) => d.key === never.key)).toMatchObject({ state: 'failed', reason: 'it was sent outside any tab with Agent Messages on' })
+ expect(statuses).toEqual([expect.objectContaining({ messageId: 'm0000006', state: 'failed' })])
+ // Its attempt in flight did not go back to the hook; the other one's did.
+ expect(t.inbox.waiting('%3', never.key)).toBe(false)
+ expect(state.find((d) => d.key === fine.key)).toMatchObject({ state: 'queued' })
+ expect(t.inbox.waiting('%3', fine.key)).toBe(true)
+ })
+
it('pumps on its own every few seconds once started, and stops', () => {
vi.useFakeTimers()
const t = setup()
diff --git a/cli/src/messages/mailbox.ts b/cli/src/messages/mailbox.ts
index 3382ad4f4..a12532995 100644
--- a/cli/src/messages/mailbox.ts
+++ b/cli/src/messages/mailbox.ts
@@ -54,6 +54,9 @@ export interface MailboxDeps {
refused(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
+ * directory is read and before anything goes back to a hook, which takes what waits in its inbox on its own. */
+ forbidden?(delivery: LocalDelivery): string | null
/** The text an agent reads for a delivery: the message, and the roster note when it is new to the agent. */
text(delivery: LocalDelivery, message: Message): string
/** A delivery changed; the store is saved after. */
@@ -94,6 +97,10 @@ export class Mailbox {
start(): void {
if (this.started) return
this.started = true
+ for (const delivery of this.local) {
+ const forbidden = delivery.state === 'queued' ? this.deps.forbidden?.(delivery) : null
+ if (forbidden) this.fail(delivery, forbidden)
+ }
this.takeBackAttempts()
// Anything left taken back from a hook goes back to it, unless its delivery is over.
for (const [pane, key] of this.deps.inbox.reclaimed()) {
diff --git a/cli/src/messages/service.spec.ts b/cli/src/messages/service.spec.ts
index b4341a87f..34cb57d96 100644
--- a/cli/src/messages/service.spec.ts
+++ b/cli/src/messages/service.spec.ts
@@ -300,34 +300,47 @@ describe('a harness and the harnesses it started', () => {
expect(t.delivered.map(([agentId]) => agentId)).toEqual(['api'])
})
- it('a message an older version queued between them under no tab is refused, not delivered', async () => {
+ it('a message an older version queued between them under no tab is never delivered, read directory or not', async () => {
vi.useFakeTimers()
- // Queued by 0.3.75 under its `started` log, waiting in web's inbox for its hook.
+ // Queued by 0.3.75 under its `started` log: one waiting in web's inbox for its hook, and one to api, which shares
+ // a tab with Agent Messages on with lead now.
const store = new MessageStore(join(root, 'state'))
- const message = { id: 'm0000old', tabId: 'started', at: 1, text: 'Also check the footer.',
- from: { machineId: 'm1', agentId: 'lead', name: 'lead', engine: 'codex', machine: 'studio' }, to: [{ machineId: 'm1', agentId: 'web', name: 'web' }] }
- store.record(message)
- store.status({ messageId: message.id, machineId: 'm1', agentId: 'web', state: 'queued', at: 1 })
- const key = deliveryKey(message.id, 'web')
- store.state.local.push({ key, messageId: message.id, agentId: 'web', pane: '%3', session: 's-web', state: 'queued', tries: 0, nextTryAt: 0, at: 1 })
+ const old = (id: string, to: string) => ({ id, tabId: 'started', at: 1, text: 'Also check the footer.',
+ from: { machineId: 'm1', agentId: 'lead', name: 'lead', engine: 'codex', machine: 'studio' }, to: [{ machineId: 'm1', agentId: to, name: to }] })
+ const queue = (id: string, to: string, pane: string) => {
+ store.record(old(id, to))
+ store.status({ messageId: id, machineId: 'm1', agentId: to, state: 'queued', at: 1 })
+ store.state.local.push({ key: deliveryKey(id, to), messageId: id, agentId: to, pane, session: `s-${to}`, state: 'queued', tries: 0, nextTryAt: 0, at: 1 })
+ new PaneInbox(join(root, 'inbox-root')).put(pane, deliveryKey(id, to), { session: `s-${to}`, text: 'Also check the footer.' })
+ }
+ queue('m0000old', 'web', '%3')
+ queue('m0000ol2', 'api', '%2')
store.save()
- new PaneInbox(join(root, 'inbox-root')).put('%3', key, { session: 's-web', text: 'Also check the footer.' })
start('lead', 'web')
- const t = setup()
- expect(t.inbox.waiting('%3', key)).toBe(true)
+ // The directory cannot be read: they are failed all the same, before a hook can take them.
+ const t = setup({ backendStatus: 500 })
+ expect(t.inbox.waiting('%3', deliveryKey('m0000old', 'web'))).toBe(true)
t.service.start()
- await vi.advanceTimersByTimeAsync(0)
- expect(t.inbox.waiting('%3', key)).toBe(false)
+ expect(t.inbox.waiting('%3', deliveryKey('m0000old', 'web'))).toBe(false)
+ expect(t.inbox.waiting('%2', deliveryKey('m0000ol2', 'api'))).toBe(false)
+ await vi.advanceTimersByTimeAsync(TICK_MS * 2)
expect(t.delivered).toEqual([])
const history = await t.ask({ action: 'history', tabId: 'started' })
- expect((history.messages as Array<{ statuses: unknown[] }>)[0].statuses).toEqual([
- expect.objectContaining({ machineId: 'm1', agentId: 'web', state: 'failed', reason: 'it is no longer in a tab with the sender' }),
+ expect((history.messages as Array<{ statuses: unknown[] }>).map((m) => m.statuses)).toEqual([
+ [expect.objectContaining({ machineId: 'm1', agentId: 'web', state: 'failed', reason: 'it was sent outside any tab with Agent Messages on' })],
+ [expect.objectContaining({ machineId: 'm1', agentId: 'api', state: 'failed', reason: 'it was sent outside any tab with Agent Messages on' })],
])
- await vi.advanceTimersByTimeAsync(TICK_MS * 2)
- expect(t.delivered).toEqual([])
t.service.stop()
})
+ it('a hand-over an older machine logged under `started` is failed even between two in a tab with Agent Messages on', async () => {
+ const t = setup()
+ const answer = await t.ask({ action: 'deliver', message: { id: 'm00000cc', tabId: 'started', text: 'hi', at: 5,
+ from: { machineId: 'm2', agentId: 'phone', name: 'phone', engine: 'claude', machine: 'laptop' }, to: [{ machineId: 'm1', agentId: 'api', name: 'api' }] } }, OWNER_REMOTE)
+ expect(answer.statuses).toEqual([expect.objectContaining({ agentId: 'api', state: 'failed', reason: 'it was sent outside any tab with Agent Messages on' })])
+ expect(t.delivered).toEqual([])
+ })
+
it('reach a tab teammate by the start of its id, for a harness whose name is a sentence', async () => {
const titled = { ...session('abcdef99-1', '%3'), title: 'so we have built it, then' } as unknown as RegisteredSession
const t = setup({ agents: [session('lead', '%1', 'codex'), titled],
diff --git a/cli/src/messages/service.ts b/cli/src/messages/service.ts
index ace172975..d88e85d1f 100644
--- a/cli/src/messages/service.ts
+++ b/cli/src/messages/service.ts
@@ -114,6 +114,7 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})
},
deliver: (agentId, text, deliveryId) => { core.turns.deliver(agentId, text, deliveryId); options.changed?.() },
refused: (delivery) => refusal(delivery),
+ forbidden: (delivery) => forbidden(delivery),
ready: () => directory.current() !== null,
text: (delivery, message) => {
const roster = rosterOf(delivery.agentId)
@@ -123,14 +124,27 @@ export function startAgentMessages(core: CoreApi, options: MessagesOptions = {})
writable: () => options.changed?.(),
})
- /** Why a local delivery can no longer be made, or null. Nothing is refused before the directory is read. */
+ /**
+ * Why a local delivery may never be made, whatever the tabs say, or null. Before 2026-10-11 a harness and one it
+ * started messaged each other with no tab on, logged under `started`; Agent Messages off means off, so what an
+ * older version left waiting there is never delivered, even to two that share a tab with it on now. Asked before
+ * the directory is read too: the hook takes what waits in a pane's inbox without asking, and a directory that
+ * cannot be read (signed out, the backend down) would otherwise leave it there to be taken.
+ */
+ function forbidden(delivery: LocalDelivery): string | null {
+ 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 {
const entry = store.entry(delivery.messageId)
if (!entry) return 'the message is no longer kept'
+ const never = forbidden(delivery)
+ if (never) return never
if (!directory.current()) return null
const recipient = { machineId: self(), agentId: delivery.agentId }
- // Only a tab with Agent Messages on carries a message: one an older version queued between a harness and one
- // it started, under no tab (`started`), is refused here like any other.
+ // Only a tab with Agent Messages on carries a message.
if (directory.shared(entry.message.from, recipient)) 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'
diff --git a/docs/design/2026-10-11-agent-client.md b/docs/design/2026-10-11-agent-client.md
index 659fcad4a..4ae3e1a41 100644
--- a/docs/design/2026-10-11-agent-client.md
+++ b/docs/design/2026-10-11-agent-client.md
@@ -263,8 +263,9 @@ may message another only where the person turned Agent Messages on (the tab's ch
depth); `send`, `harness send` alone and delivery go through the tabs alone. A send to a harness one started, with
no shared tab on, is refused with the same words as any other recipient: `MESSAGES_OFF` in a tab with it off,
`UNKNOWN_RECIPIENT` ("No teammate named …") otherwise.
-- A message an older version queued under `started` is failed like one whose tab was turned off, its inbox file
- withdrawn, as soon as the service reads the directory.
+- A message an older version queued under `started` is never delivered: it is failed and its inbox file withdrawn
+ as the service starts, before the directory is read (the hook takes what waits in an inbox without asking, and a
+ directory that cannot be read would have left it there), even between two that now share a tab with it on.
- The record (`agent-client/started.jsonl`) stays: `ps`, the limits, the depth and `close` read it.
- For a follow-up to a harness it started, an agent starts it with everything in the task, or, where Agent Messages
are on in its tab, sends.