Skip to content

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

fix(hive): stop stale inbox nudges waking agents against an empty inbox

hyperstream-pro52ed112af8e4
diff --git a/package.json b/package.json
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.cjs
new file mode 100644
index 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:/);
+});