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
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.tsindex 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.tsindex 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.tsindex 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) returnthis.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.tsindex 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 RegisteredSessionconst t = setup({ agents: [session('lead', '%1', 'codex'), titled],diff --git a/cli/src/messages/service.ts b/cli/src/messages/service.tsindex 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 neverif (!directory.current()) return nullconst 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 nullconst 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.mdindex 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 chdepth); `send`, `harness send` alone and delivery go through the tabs alone. A send to a harness one started, withno 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 Messagesare on in its tab, sends.