an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
fix(hive): stop stale inbox nudges waking agents against an empty inbox
hyperstream-pro52ed112af8e4
diff --git a/package.json b/package.jsonindex 97bb375a..3afd851d 100644--- a/package.json+++ b/package.json@@ -19,7 +19,7 @@"typecheck:node": "tsc --noEmit -p tsconfig.node.json","typecheck:web": "tsc --noEmit -p tsconfig.web.json","typecheck": "npm run typecheck:node && npm run typecheck:web",- "test:focused": "node --test test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/terminal-selection.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-task-mutation.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/release-notes.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs test/ide-image.test.cjs test/win-cmd-shim.test.cjs test/hive-windows-prompt.test.cjs test/release-drop.test.cjs test/skills.test.cjs test/skills-install.test.cjs test/hero-payload.test.cjs",+ "test:focused": "node --test test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/terminal-selection.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-task-mutation.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/release-notes.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs test/ide-image.test.cjs test/win-cmd-shim.test.cjs test/hive-windows-prompt.test.cjs test/release-drop.test.cjs test/hive-nudge.test.cjs test/skills.test.cjs test/skills-install.test.cjs test/hero-payload.test.cjs","check:links": "node tools/check-release-links.cjs","dist": "npm run build && electron-builder","dist:mac": "npm run build && electron-builder --mac",diff --git a/src/renderer/src/hooks/useHive.ts b/src/renderer/src/hooks/useHive.tsindex bb036bb4..1633588f 100644--- a/src/renderer/src/hooks/useHive.ts+++ b/src/renderer/src/hooks/useHive.ts@@ -16,6 +16,7 @@ import {} from '../../../shared/providerAutomation';import { DEFAULT_CONTEXT_TRIGGER, type ContextRule } from '../../../shared/triggers';import type { AgentProvider } from '../../../shared/agentProvider';+import { inboxNudgeText } from '../../../shared/hiveNudge';import { acquireTerminal, resetTerminal, isTerminalAutomationSafe } from '@/components/terminalPool';import { deliverWithAcknowledgement } from './queueDelivery';import { OFFICE_CAST, DEFAULT_CHARACTER } from '@/scene/office/cast';@@ -630,10 +631,14 @@ export function useHive(config: HarnessConfig | null): void {const seen = nudged.current[a.id] ?? (nudged.current[a.id] = new Set());const fresh = inbox.filter((m) => m.id && !seen.has(m.id));if (fresh.length) {- useStore.getState().enqueueMessage(- a.id,- 'You have new hive inbox message(s) — read your inbox, act on them now, and move handled ones to inbox/.done/. Act autonomously; only message god if you genuinely need a decision.'- );+ // Name the ids: the nudge is queued now and typed whenever the agent+ // next goes idle, so it can arrive long after the agent drained and+ // filed this very mail. Carrying the ids is what lets it tell+ // "already handled" from "woken for nothing". The queue keeps only+ // one nudge pending per agent (see enqueueMessage), so a suppressed+ // copy's ids stay unnamed — hence the text points at the pending+ // inbox as the authority rather than at the list.+ useStore.getState().enqueueMessage(a.id, inboxNudgeText(fresh.map((m) => m.id)));for (const m of fresh) seen.add(m.id);}} catch { /* ignore */ }diff --git a/src/renderer/src/store/store.ts b/src/renderer/src/store/store.tsindex 7ae52d5a..f051e623 100644--- a/src/renderer/src/store/store.ts+++ b/src/renderer/src/store/store.ts@@ -7,6 +7,7 @@ import type { AgentProvider } from '@shared/agentProvider';import type { HireManifest } from '@shared/hire';import { DEFAULT_ORG_TRIGGER, type OrgTriggerConfig, type WebhookTrigger } from '@shared/triggers';import { isCompactionCommand } from '@shared/providerAutomation';+import { isInboxNudge } from '@shared/hiveNudge';export type ToolKind =| 'Read' | 'Edit' | 'Write' | 'Bash' | 'WebFetch' | 'WebSearch'@@ -765,6 +766,18 @@ export const useStore = create<State>((set) => ({if (isCompactionCommand(trimmed) && queued.some((m) => isCompactionCommand(m.text))) {return s;}+ // ONE PENDING INBOX NUDGE PER AGENT — the same property, for the same+ // reason. The first nudge makes the agent drain its WHOLE inbox, so every+ // nudge queued behind it lands on a directory that agent has already+ // emptied and answers "nothing new": a delivery slot and a model+ // round-trip each, to say nothing. Mail arriving while an agent is mid-turn+ // queues one nudge per poll, so this is the common case rather than the+ // rare one, and the floor reports it as repeated empty-inbox wakes.+ // Suppressing the copy loses nothing — the surviving nudge sends the agent+ // to the same authoritative directory, where the newer mail is waiting too.+ if (isInboxNudge(trimmed) && queued.some((m) => isInboxNudge(m.text))) {+ return s;+ }const msg: QueuedMessage = {id: newQueuedId(), text: trimmed, ts: Date.now(),...(meta?.slack ? { slack: meta.slack } : {}),diff --git a/src/shared/hiveNudge.ts b/src/shared/hiveNudge.tsnew file mode 100644index 00000000..f7cfd825--- /dev/null+++ b/src/shared/hiveNudge.ts@@ -0,0 +1,39 @@+/**+ * The inbox-wake nudge — the text queued for an agent that has unread hive mail,+ * and the predicate the message queue uses to keep only one of them pending.+ *+ * The nudge is QUEUED the moment fresh mail is seen but TYPED only once the agent+ * is idle and off cooldown, and it survives a renderer reload in the persisted+ * queue. By the time it lands, the agent has often already drained that mail and+ * filed it under `inbox/.done/` — so the nudge arrives against an inbox the agent+ * itself just emptied.+ */++/** The fixed head of every nudge; the ids that follow differ per nudge. */+const NUDGE_HEAD = 'You have new hive inbox message(s)';++/**+ * Build the nudge, naming the messages that prompted it.+ *+ * The ids are diagnostic, NOT a work list: they let an agent tell "I already+ * handled this last turn" (the id sits in `inbox/.done/`) from "the harness woke+ * me for nothing", which is the distinction it otherwise cannot make and burns a+ * round-trip guessing at. The pending inbox stays authoritative — an agent that+ * has a nudge suppressed by the one-pending rule below still finds its mail by+ * reading the directory, so the text must never invite it to stop at the ids.+ */+export function inboxNudgeText(ids: string[]): string {+ const named = ids.length ? ` — at least: ${ids.join(', ')}` : '';+ return `${NUDGE_HEAD}${named}. Read your inbox, act on what is pending there, and move handled ones to inbox/.done/. Your inbox directory is authoritative: work everything still pending in it, and if a named id is already in inbox/.done/ you handled it on an earlier turn and can ignore that one. Act autonomously; only message god if you genuinely need a decision.`;+}++/**+ * Is this queued text an inbox-wake nudge?+ *+ * Matches the fixed head only, since every nudge carries different ids — the+ * point is to recognise the COMMAND, not one instance of it. Mirrors+ * `isCompactionCommand`, and the queue's one-pending rule leans on it the same way.+ */+export function isInboxNudge(text: string): boolean {+ return text.trim().startsWith(NUDGE_HEAD);+}diff --git a/test/hive-nudge.test.cjs b/test/hive-nudge.test.cjsnew file mode 100644index 00000000..47a93dfb--- /dev/null+++ b/test/hive-nudge.test.cjs@@ -0,0 +1,70 @@+'use strict';++/**+ * Regression for the repeated empty-inbox wake.+ *+ * The inbox nudge is QUEUED the moment fresh mail is seen and TYPED only once the+ * agent is idle and off cooldown, and it persists across a renderer reload. Mail+ * arriving while an agent is mid-turn therefore queues one nudge per 4s poll,+ * the agent drains its whole inbox on the first one, and every nudge behind it+ * lands on a directory the agent has already emptied — a delivery slot and a+ * model round-trip each, to be told there is nothing new. Three agents reported+ * it; one checked immediately and again at +2s and never found a file.+ *+ * The queue already holds exactly this invariant for `/compact`, for exactly this+ * reason ("idempotent in the worst way"). The nudge is the second command with+ * that property. These tests pin the predicate the invariant depends on, in the+ * spirit of the isCompactionCommand tests in provider-automation.test.cjs.+ */++const test = require('node:test');+const assert = require('node:assert/strict');+const loadTs = require('./load-ts.cjs');++const { inboxNudgeText, isInboxNudge } = loadTs('src/shared/hiveNudge.ts');++// — the queue's one-pending-nudge invariant depends entirely on this predicate —++test('every nudge the app builds is recognised as one, whatever ids it carries', () => {+ for (const ids of [[], ['a'], ['2026-08-19T18-01-00-000Z-ryan-notify-race', 'b-2']]) {+ assert.equal(isInboxNudge(inboxNudgeText(ids)), true, JSON.stringify(ids));+ }+});++test('two nudges with different ids both match, so the duplicate is dropped', () => {+ // The real queued shape: a second poll names different mail. Matching the whole+ // string instead of the fixed head would never dedupe, which is the bug.+ const first = inboxNudgeText(['msg-1']);+ const second = inboxNudgeText(['msg-2', 'msg-3']);+ assert.notEqual(first, second);+ assert.equal([first].some((t) => isInboxNudge(t)) && isInboxNudge(second), true);+});++test('prose that merely mentions the inbox is NOT a nudge', () => {+ // The queue carries operator instructions too; dropping one as a duplicate+ // nudge would silently lose real work.+ assert.equal(isInboxNudge('Please check whether you have new hive inbox message(s)'), false);+ assert.equal(isInboxNudge('summarise your inbox'), false);+ assert.equal(isInboxNudge(''), false);+});++// — the payload —++test('the nudge names the messages that prompted it', () => {+ const text = inboxNudgeText(['2026-08-19T17-10-00-000Z-broadcast-retro-rule']);+ assert.match(text, /2026-08-19T17-10-00-000Z-broadcast-retro-rule/);+});++test('the nudge keeps the pending inbox authoritative, not the id list', () => {+ // A nudge suppressed by the one-pending rule leaves its ids unnamed, so an+ // agent that stopped at the list would miss that mail entirely.+ const text = inboxNudgeText(['msg-1']);+ assert.match(text, /authoritative/);+ assert.match(text, /inbox\/\.done\//);+});++test('a nudge with no ids is still a well-formed nudge', () => {+ const text = inboxNudgeText([]);+ assert.equal(isInboxNudge(text), true);+ assert.doesNotMatch(text, /at least:/);+});