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(worker): a worker that signaled done leaves a settled inbox

Gastón Péchieu8e17163e5ac7
diff --git a/src/main/hive.ts b/src/main/hive.ts
index 4537c2bf..f7deeb2b 100644
--- a/src/main/hive.ts
+++ b/src/main/hive.ts
@@ -1013,6 +1013,43 @@ export class HiveManager {
} catch { /* best-effort — never crash a lifecycle handler */ }
}
+ /**
+ * Move every unread message in an agent's inbox to inbox/.done — the agent has
+ * finished with the whole mailbox (an ephemeral worker that signaled done), so
+ * nothing left in it is pending any more. Workers rarely file their own work
+ * order before signaling done, and a worker id is reused on every re-hire of
+ * the same name (`worker-<request name>`), so without this each new incarnation
+ * boots into its predecessors' stale orders: it is told to "work everything
+ * still pending", spends its first turns re-triaging tasks its memory says are
+ * finished, and the inbox-wake watchdog reads the oldest of those as mail that
+ * has been unanswered for days. Returns how many messages were filed (0 when
+ * the inbox was already clean or the agent has no mailbox). Best-effort —
+ * never throws, so the release path that calls it can't be crashed by a
+ * half-written file.
+ */
+ settleInbox(id: string): number {
+ const root = this.root();
+ if (!root) return 0;
+ const inbox = join(root, 'agents', id, 'inbox');
+ if (!existsSync(inbox)) return 0;
+ let files: string[];
+ try { files = readdirSync(inbox).filter((f) => f.endsWith('.json')); } catch { return 0; }
+ if (files.length === 0) return 0;
+ const done = join(inbox, '.done');
+ let moved = 0;
+ try { mkdirSync(done, { recursive: true }); } catch { return 0; }
+ for (const f of files) {
+ try { renameSync(join(inbox, f), join(done, f)); moved++; } catch { /* skip; a later settle retries */ }
+ }
+ if (moved > 0) {
+ try {
+ this.appendLog({ kind: 'inbox-settled', agentId: id, count: moved });
+ this.commit(`hive: settle inbox of ${id} (${moved} unread)`);
+ } catch { /* best-effort */ }
+ }
+ return moved;
+ }
+
/**
* Change an agent's display name without changing its durable identity.
* The registry key, agent directory, session id, and every mailbox path remain
diff --git a/src/main/index.ts b/src/main/index.ts
index 40634ac6..c238b478 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -4883,6 +4883,16 @@ async function ephemeralWorkerTick(): Promise<void> {
// Success: the worker already replied in-thread; just release it.
rec.releasing = true;
console.log(`[worker] ${workerId} signaled done — releasing`);
+ // Its mailbox is finished with too. Workers seldom file their own work
+ // order before signaling done, and the id is reused on every re-hire of
+ // the same name, so anything left unread here would greet the next
+ // incarnation as "pending" work (seen live 2026-09-07: 13 of 30 worker
+ // inboxes carried finished orders; a re-hired worker spent its first
+ // turns re-triaging yesterday's, and the watchdog read it as mail
+ // unanswered for 21h). Only the DONE path settles — an idle/token-cap
+ // reap never signaled completion, so its unread mail stays pending.
+ const settled = hive.settleInbox(workerId);
+ if (settled > 0) console.log(`[worker] ${workerId}: filed ${settled} unread inbox message(s) under inbox/.done`);
ptyManager.kill(workerId);
teardownPty(workerId);
continue;
diff --git a/test/worker-inbox-settle.test.cjs b/test/worker-inbox-settle.test.cjs
new file mode 100644
index 00000000..9afa3faa
--- /dev/null
+++ b/test/worker-inbox-settle.test.cjs
@@ -0,0 +1,87 @@
+'use strict';
+// A worker that signaled done is finished with its whole mailbox.
+//
+// Before this: an ephemeral worker's inbox was left exactly as the worker left
+// it when it was released, and workers seldom file their own work order under
+// inbox/.done before signaling done. The worker id is `worker-<request name>`,
+// reused on every re-hire of the same name, so each new incarnation booted into
+// its predecessors' finished orders: the boot nudge told it to "work everything
+// still pending", it spent its first turns re-triaging tasks its memory said
+// were done, and the inbox-wake watchdog read the oldest order as mail that had
+// gone unanswered for 21 hours. Seen live 2026-09-07: 13 of 30 worker inboxes
+// on one floor carried finished orders, one of them three deep.
+//
+// The release path now files whatever is still unread. Only the DONE path does —
+// an idle or token-cap reap never signaled completion, so its mail stays pending.
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const loadTs = require('./load-ts.cjs');
+
+const { HiveManager } = loadTs('src/main/hive.ts');
+
+async function floor(t) {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'md-inbox-settle-'));
+ t.after(() => fs.rmSync(home, { recursive: true, force: true }));
+ const hive = new HiveManager(() => home, () => true);
+ await hive.ensureAgent({ id: 'god-1', name: 'Michael', provider: 'claude', cwd: home, isGod: true });
+ await hive.ensureAgent({ id: 'worker-phyllis', name: 'Phyllis', provider: 'claude', cwd: home });
+ return { home, hive };
+}
+
+const inboxDir = (hive, id) => path.join(hive.root(), 'agents', id, 'inbox');
+const jsonFiles = (dir) => fs.readdirSync(dir).filter((f) => f.endsWith('.json')).sort();
+const entries = (hive, kind) => hive.logTail(500).filter((e) => e.kind === kind);
+
+test('settling files every unread message under inbox/.done and says how many', async (t) => {
+ const { hive } = await floor(t);
+ hive.send({ to: 'worker-phyllis', act: 'request', subject: 'Phyllis', body: 'yesterday\'s work order' }, 'god-1');
+ hive.send({ to: 'worker-phyllis', act: 'inform', subject: 'IOCs', body: 'anchors from Ryan' }, 'god-1');
+ const before = jsonFiles(inboxDir(hive, 'worker-phyllis'));
+ assert.equal(before.length, 2, 'both messages are pending before the worker is released');
+
+ assert.equal(hive.settleInbox('worker-phyllis'), 2);
+
+ assert.deepEqual(hive.inbox('worker-phyllis'), [], 'nothing reads as pending any more');
+ assert.deepEqual(jsonFiles(path.join(inboxDir(hive, 'worker-phyllis'), '.done')), before,
+ 'the messages are filed, not deleted — the same files, now under .done');
+ const [logged] = entries(hive, 'inbox-settled');
+ assert.deepEqual({ agentId: logged.agentId, count: logged.count }, { agentId: 'worker-phyllis', count: 2 },
+ 'the ledger records the settle so a later reader knows why the inbox is empty');
+});
+
+test('a clean inbox settles to zero without touching the ledger; an unknown agent is a no-op', async (t) => {
+ const { hive } = await floor(t);
+ assert.equal(hive.settleInbox('worker-phyllis'), 0);
+ assert.equal(hive.settleInbox('worker-nobody'), 0);
+ assert.equal(entries(hive, 'inbox-settled').length, 0);
+ // Idempotent: a second settle after a real one finds nothing left.
+ hive.send({ to: 'worker-phyllis', act: 'request', subject: 'Phyllis', body: 'order' }, 'god-1');
+ assert.equal(hive.settleInbox('worker-phyllis'), 1);
+ assert.equal(hive.settleInbox('worker-phyllis'), 0);
+});
+
+test('a message already filed under .done is left alone (never re-filed or duplicated)', async (t) => {
+ const { hive } = await floor(t);
+ hive.send({ to: 'worker-phyllis', act: 'request', subject: 'Phyllis', body: 'order' }, 'god-1');
+ const dir = inboxDir(hive, 'worker-phyllis');
+ const [f] = jsonFiles(dir);
+ fs.renameSync(path.join(dir, f), path.join(dir, '.done', f));
+ assert.equal(hive.settleInbox('worker-phyllis'), 0);
+ assert.deepEqual(jsonFiles(path.join(dir, '.done')), [f]);
+});
+
+// The release path is the only caller, and it must be the DONE branch — pinned
+// by reading index.ts as text, since the tick is not importable on its own.
+test('the ephemeral-worker tick settles the inbox on the done path, before the kill, and only there', () => {
+ const source = fs.readFileSync(path.join(__dirname, '..', 'src/main/index.ts'), 'utf8');
+ const done = source.indexOf('signaled done — releasing');
+ assert.ok(done > 0, 'the done branch exists');
+ const settle = source.indexOf('hive.settleInbox(workerId)', done);
+ assert.ok(settle > 0, 'the done branch settles the inbox');
+ const kill = source.indexOf('ptyManager.kill(workerId)', done);
+ assert.ok(settle < kill, 'the settle happens before the PTY is killed (the worker dir still exists either way, but the order keeps the log readable)');
+ assert.equal(source.indexOf('hive.settleInbox', kill), -1, 'neither the token-cap nor the idle reap settles — they never signaled completion');
+});