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): settle only the mail that predates the done signal, and tell god what was filed

Gastón Péchieuc99dd3ffdeae
diff --git a/src/main/hive.ts b/src/main/hive.ts
index f7deeb2b..efbf8062 100644
--- a/src/main/hive.ts
+++ b/src/main/hive.ts
@@ -53,6 +53,17 @@ type McpDefaultsMap = { [id: string]: { enabled: boolean } } | undefined;
export type MessageAct = 'request' | 'inform' | 'propose' | 'query' | 'agree' | 'refuse' | 'done';
+/** What `settleInbox` did to a released worker's mailbox. */
+export interface SettledInbox {
+ /** Unread messages filed under inbox/.done. */
+ moved: number;
+ /** Unread messages left pending because they arrived after the cut-off. */
+ kept: number;
+ /** The filed messages that asked for something — their sender never gets
+ * an answer, and deserves to hear so instead of waiting on a dead worker. */
+ unanswered: Array<{ id: string; act: MessageAct; from: string; subject: string }>;
+}
+
export interface HiveMessage {
id: string;
conversation: string;
@@ -1022,32 +1033,53 @@ export class HiveManager {
* 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
+ * has been unanswered for days.
+ *
+ * Only mail that was already there when the worker signaled done is finished
+ * with: `before` is that signal's timestamp, and a message created after it
+ * (a follow-up question from god that crossed the worker's done) is left in
+ * place, still pending, for whoever picks the mailbox up next. Without the
+ * cut-off such a message was filed as read and nobody ever saw it. Messages
+ * whose `created_at` is unreadable fall back to the file's mtime.
+ *
+ * Returns what happened — how many were filed, how many were kept, and the
+ * filed messages that asked for something (`request` / `query`), so the
+ * caller can tell their sender that no answer is coming. Best-effort — never
+ * throws, so the release path that calls it can't be crashed by a
* half-written file.
*/
- settleInbox(id: string): number {
+ settleInbox(id: string, before = Number.POSITIVE_INFINITY): SettledInbox {
+ const out: SettledInbox = { moved: 0, kept: 0, unanswered: [] };
const root = this.root();
- if (!root) return 0;
+ if (!root) return out;
const inbox = join(root, 'agents', id, 'inbox');
- if (!existsSync(inbox)) return 0;
+ if (!existsSync(inbox)) return out;
let files: string[];
- try { files = readdirSync(inbox).filter((f) => f.endsWith('.json')); } catch { return 0; }
- if (files.length === 0) return 0;
+ try { files = readdirSync(inbox).filter((f) => f.endsWith('.json')); } catch { return out; }
+ if (files.length === 0) return out;
const done = join(inbox, '.done');
- let moved = 0;
- try { mkdirSync(done, { recursive: true }); } catch { return 0; }
+ try { mkdirSync(done, { recursive: true }); } catch { return out; }
for (const f of files) {
- try { renameSync(join(inbox, f), join(done, f)); moved++; } catch { /* skip; a later settle retries */ }
+ const fp = join(inbox, f);
+ let msg: Partial<HiveMessage> = {};
+ try { msg = JSON.parse(readFileSync(fp, 'utf8')) as Partial<HiveMessage>; } catch { /* half-written: file it by mtime */ }
+ let at = Date.parse(msg.created_at ?? '');
+ if (!Number.isFinite(at)) { try { at = statSync(fp).mtimeMs; } catch { at = 0; } }
+ if (at > before) { out.kept++; continue; }
+ try { renameSync(fp, join(done, f)); out.moved++; } catch { continue; /* skip; a later settle retries */ }
+ if (msg.act === 'request' || msg.act === 'query') {
+ out.unanswered.push({
+ id: msg.id ?? f, act: msg.act, from: msg.from ?? 'unknown', subject: msg.subject ?? ''
+ });
+ }
}
- if (moved > 0) {
+ if (out.moved > 0) {
try {
- this.appendLog({ kind: 'inbox-settled', agentId: id, count: moved });
- this.commit(`hive: settle inbox of ${id} (${moved} unread)`);
+ this.appendLog({ kind: 'inbox-settled', agentId: id, count: out.moved });
+ this.commit(`hive: settle inbox of ${id} (${out.moved} unread)`);
} catch { /* best-effort */ }
}
- return moved;
+ return out;
}
/**
diff --git a/src/main/index.ts b/src/main/index.ts
index c238b478..df333c9a 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -4615,9 +4615,11 @@ function archiveRequest(filePath: string, sub: '.done' | '.failed'): void {
}
}
-/** Did this worker post a terminal `act:"done"` yet? Scans its own outbox AND
- * outbox/.sent (the router archives delivered mail there ~every 1.5s), so the
- * signal is caught whether or not it's been routed out yet.
+/** When did this worker post its terminal `act:"done"` — or null when it has
+ * not yet. Scans its own outbox AND outbox/.sent (the router archives delivered
+ * mail there ~every 1.5s), so the signal is caught whether or not it's been
+ * routed out yet. The timestamp (the newest done, if several) is the cut-off
+ * for settling its inbox: mail that arrived after it is still pending.
*
* Stale-done guard: agent dirs persist after teardown, so REUSING a reqId would
* leave a PRIOR worker's `done` sitting in this same dir. Without a guard that
@@ -4627,10 +4629,11 @@ function archiveRequest(filePath: string, sub: '.done' | '.failed'): void {
* own timestamp), falling back to the file's mtime when `created_at` is missing
* or unparseable. When neither yields a usable timestamp we DON'T count it
* (fail toward keeping the worker alive — the idle reaper is the backstop). */
-function workerSignaledDone(workerId: string, spawnedAt: number): boolean {
+function workerDoneAt(workerId: string, spawnedAt: number): number | null {
const root = hive.root();
- if (!root) return false;
+ if (!root) return null;
const base = join(root, 'agents', workerId, 'outbox');
+ let doneAt: number | null = null;
for (const dir of [base, join(base, '.sent')]) {
if (!existsSync(dir)) continue;
let files: string[];
@@ -4645,11 +4648,11 @@ function workerSignaledDone(workerId: string, spawnedAt: number): boolean {
if (!Number.isFinite(ts)) {
try { ts = statSync(fp).mtimeMs; } catch { ts = NaN; }
}
- if (Number.isFinite(ts) && ts > spawnedAt) return true;
+ if (Number.isFinite(ts) && ts > spawnedAt && (doneAt === null || ts > doneAt)) doneAt = ts;
} catch { /* skip unreadable/partial */ }
}
}
- return false;
+ return doneAt;
}
/** Spin up one ephemeral worker from a spawn-request. Terminal failures (bad
@@ -4879,7 +4882,8 @@ async function ephemeralWorkerTick(): Promise<void> {
// worker-qa/worker-bizreview). A double teardown is a harmless no-op.
for (const [workerId, rec] of [...liveWorkers]) {
if (rec.releasing) continue;
- if (workerSignaledDone(workerId, rec.spawnedAt)) {
+ const doneAt = workerDoneAt(workerId, rec.spawnedAt);
+ if (doneAt !== null) {
// Success: the worker already replied in-thread; just release it.
rec.releasing = true;
console.log(`[worker] ${workerId} signaled done — releasing`);
@@ -4890,9 +4894,23 @@ async function ephemeralWorkerTick(): Promise<void> {
// 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`);
+ // reap never signaled completion, so its unread mail stays pending —
+ // and only mail from BEFORE the done signal: a follow-up that crossed
+ // the worker's done is still nobody's, so it stays pending. God hears
+ // which requests/queries were filed unread, so none vanishes silently.
+ const settled = hive.settleInbox(workerId, doneAt);
+ if (settled.moved > 0) console.log(`[worker] ${workerId}: filed ${settled.moved} unread inbox message(s) under inbox/.done`);
+ if (settled.kept > 0) console.log(`[worker] ${workerId}: left ${settled.kept} message(s) that arrived after its done signal pending`);
+ if (settled.unanswered.length > 0) {
+ const lines = settled.unanswered.map((m) => `- ${m.act} ${m.id} from ${m.from}: "${m.subject}"`);
+ informGod(
+ `[worker released — mail filed unread] ${workerId}`,
+ `Worker ${workerId} signaled done and was released. These messages were still unread in its inbox and were filed under inbox/.done without an answer:\n`
+ + lines.join('\n')
+ + `\nIf one of them is not the order it just completed, nobody is working on it — resend it to another agent or re-hire the worker.`,
+ rec.slack
+ );
+ }
ptyManager.kill(workerId);
teardownPty(workerId);
continue;
diff --git a/test/worker-inbox-settle.test.cjs b/test/worker-inbox-settle.test.cjs
index 9afa3faa..e980844d 100644
--- a/test/worker-inbox-settle.test.cjs
+++ b/test/worker-inbox-settle.test.cjs
@@ -1,5 +1,5 @@
'use strict';
-// A worker that signaled done is finished with its whole mailbox.
+// A worker that signaled done is finished with the mail it had when it did.
//
// 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
@@ -11,8 +11,11 @@
// 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.
+// The release path now files whatever was still unread WHEN THE WORKER SIGNALED
+// DONE. Only the DONE path does — an idle or token-cap reap never signaled
+// completion, so its mail stays pending — and only mail from before the signal:
+// a follow-up that crossed the worker's done was never seen by anyone, so it
+// stays pending too. Requests and queries filed unread are reported back to god.
const test = require('node:test');
const assert = require('node:assert/strict');
const fs = require('node:fs');
@@ -34,15 +37,26 @@ async function floor(t) {
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);
+/** A wall-clock instant strictly later than anything stamped before the call. */
+function later() {
+ const t = Date.now();
+ while (Date.now() <= t + 1) { /* spin: created_at has millisecond resolution */ }
+ return Date.now();
+}
-test('settling files every unread message under inbox/.done and says how many', async (t) => {
+test('settling files every unread message under inbox/.done and names the requests that got no answer', 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);
+ const settled = hive.settleInbox('worker-phyllis');
+ assert.equal(settled.moved, 2);
+ assert.equal(settled.kept, 0);
+ assert.deepEqual(settled.unanswered.map((m) => [m.act, m.from, m.subject]), [['request', 'god-1', 'Phyllis']],
+ 'the request is reported (its sender is owed an answer); the inform is not');
+ assert.ok(settled.unanswered[0].id, 'the report carries the message id so god can find it');
assert.deepEqual(hive.inbox('worker-phyllis'), [], 'nothing reads as pending any more');
assert.deepEqual(jsonFiles(path.join(inboxDir(hive, 'worker-phyllis'), '.done')), before,
@@ -52,15 +66,42 @@ test('settling files every unread message under inbox/.done and says how many',
'the ledger records the settle so a later reader knows why the inbox is empty');
});
+test('mail that arrived after the done signal stays pending (a follow-up that crossed the done)', async (t) => {
+ const { hive } = await floor(t);
+ hive.send({ to: 'worker-phyllis', act: 'request', subject: 'Phyllis', body: 'the order she completed' }, 'god-1');
+ const doneAt = later();
+ later();
+ hive.send({ to: 'worker-phyllis', act: 'query', subject: 'One more thing', body: 'did you also check the DNS logs?' }, 'god-1');
+
+ const settled = hive.settleInbox('worker-phyllis', doneAt);
+ assert.deepEqual({ moved: settled.moved, kept: settled.kept }, { moved: 1, kept: 1 });
+ assert.deepEqual(settled.unanswered.map((m) => m.subject), ['Phyllis'], 'only the filed request is reported');
+ assert.deepEqual(hive.inbox('worker-phyllis').map((m) => m.subject), ['One more thing'],
+ 'the follow-up is still pending for whoever picks the mailbox up next');
+ // No cut-off = everything, as the next incarnation's own done would do.
+ assert.equal(hive.settleInbox('worker-phyllis').moved, 1);
+});
+
+test('a message whose created_at is unreadable is dated by its file mtime', async (t) => {
+ const { hive } = await floor(t);
+ const dir = inboxDir(hive, 'worker-phyllis');
+ fs.writeFileSync(path.join(dir, 'half-written.json'), '{"act":"request","subject":"cut off', 'utf8');
+ assert.deepEqual(hive.settleInbox('worker-phyllis', 0), { moved: 0, kept: 1, unanswered: [] },
+ 'a cut-off before the file was written keeps it');
+ const settled = hive.settleInbox('worker-phyllis', later() + 1_000);
+ assert.deepEqual({ moved: settled.moved, kept: settled.kept, unanswered: settled.unanswered },
+ { moved: 1, kept: 0, unanswered: [] }, 'unparseable mail is filed, never reported as a request');
+});
+
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.deepEqual(hive.settleInbox('worker-phyllis'), { moved: 0, kept: 0, unanswered: [] });
+ assert.deepEqual(hive.settleInbox('worker-nobody'), { moved: 0, kept: 0, unanswered: [] });
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);
+ assert.equal(hive.settleInbox('worker-phyllis').moved, 1);
+ assert.equal(hive.settleInbox('worker-phyllis').moved, 0);
});
test('a message already filed under .done is left alone (never re-filed or duplicated)', async (t) => {
@@ -69,19 +110,22 @@ test('a message already filed under .done is left alone (never re-filed or dupli
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.equal(hive.settleInbox('worker-phyllis').moved, 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', () => {
+test('the ephemeral-worker tick settles the inbox on the done path, up to the done signal, tells god, 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 settle = source.indexOf('hive.settleInbox(workerId, doneAt)', done);
+ assert.ok(settle > 0, 'the done branch settles the inbox with the done signal as the cut-off');
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)');
+ const report = source.indexOf('settled.unanswered', settle);
+ assert.ok(report > 0 && report < kill, 'the filed requests/queries are reported to god before the kill');
+ assert.ok(source.indexOf('informGod(', report) < kill, 'the report goes through informGod');
assert.equal(source.indexOf('hive.settleInbox', kill), -1, 'neither the token-cap nor the idle reap settles — they never signaled completion');
});