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(hooks): make an unbound hook socket loud, self-healing and visible

Snehitha0ab09fa82eb3
diff --git a/docs/pr-evidence/hook-socket-after.png b/docs/pr-evidence/hook-socket-after.png
new file mode 100644
index 00000000..c5bb70b1
Binary files /dev/null and b/docs/pr-evidence/hook-socket-after.png differ
diff --git a/docs/pr-evidence/hook-socket-before.png b/docs/pr-evidence/hook-socket-before.png
new file mode 100644
index 00000000..609f9a21
Binary files /dev/null and b/docs/pr-evidence/hook-socket-before.png differ
diff --git a/src/main/hooks.ts b/src/main/hooks.ts
index a4cf0743..4b65b05f 100644
--- a/src/main/hooks.ts
+++ b/src/main/hooks.ts
@@ -10,8 +10,9 @@
*
* Runs in the Electron main process.
*/
-import { createServer, type Server } from 'node:net';
-import { existsSync, rmSync } from 'node:fs';
+import { createServer, createConnection, type Server, type Socket } from 'node:net';
+import { existsSync, rmSync, statSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
import { Notification, type WebContents } from 'electron';
import type { HiveManager } from './hive';
import type { HarnessConfig } from './config';
@@ -24,6 +25,8 @@ import { validateHookEvent } from '../shared/hookEvents';
const MAX_HOOK_FRAME_BYTES = 256 * 1024;
interface HookPayload {
+ /** Ownership probe from ensureListening(): answered with { pong, instance }, never a hook. */
+ ping?: string;
hook_event_name?: string;
agent_id?: string | null;
session_id?: string;
@@ -49,8 +52,71 @@ interface HookPayload {
cache_creation?: number;
}
+/** Live health of the hook socket — the ONE endpoint every lifecycle hook,
+ * proxy-bridge emit and cost sample travels through. When nothing accepts on
+ * it the shims' connect() fails and they exit 0 with empty stdout, which the
+ * CLI reads as "allow": the breaker is inert, fleet.json never appears, no cost
+ * is recorded — and until #277 nothing said so. The beat writes this into
+ * fleet.json so an operator (or god) can see it without a debugger. */
+export interface HookSocketHealth {
+ /** HIVE_SOCK — where the shims connect. null while the hive has no root. */
+ path: string | null;
+ /** True only while our server is listening AND (POSIX) the path still
+ * resolves to the socket we bound — a socket FILE can exist while nothing
+ * accepts on it, so existence proves nothing. */
+ listening: boolean;
+ /** Epoch ms of the current bind; null when not listening. */
+ since: number | null;
+ /** The last bind/verify failure — 'EADDRINUSE', 'ENOENT', 'REPLACED',
+ * 'NOROOT', … — or null when healthy. */
+ lastError: string | null;
+ /** Bind attempts since the last successful listen (0 when healthy). */
+ attempts: number;
+ /** Listeners this process had to abandon because a stranger took the path
+ * (see detach()) — a non-zero count is worth a look. */
+ orphans: number;
+}
+
+/** Back-off between automatic re-bind attempts after a failure. Once spent, the
+ * beat still calls ensureListening() on its own cadence, so the server never
+ * stops trying — it just stops toasting. */
+const BIND_RETRY_MS = [500, 1_000, 2_000, 4_000, 8_000];
+
+/** Identity of the socket FILE we bound — enough to tell, synchronously, whether
+ * the path still leads to it (APFS/NTFS never reuse inode numbers). */
+interface FileMark { dev: number; ino: number }
+const markOf = (p: string): FileMark | null => {
+ try { const st = statSync(p); return { dev: st.dev, ino: st.ino }; } catch { return null; }
+};
+const sameMark = (a: FileMark | null, b: FileMark | null): boolean =>
+ !!a && !!b && a.dev === b.dev && a.ino === b.ino;
+
+/** Who answers at the path: nobody (missing, or a stale file from a crashed
+ * run), a stranger (another live instance — never touched), or us. */
+type PathOwner = 'nobody' | 'other' | 'self';
+
export class HookServer {
private server: Server | null = null;
+ /** This process's identity, echoed back by the ownership ping so a probe can
+ * tell "our listener" from "some other live instance" at the same path. */
+ private readonly instanceId = randomUUID();
+ /** The socket FILE we bound (POSIX), so stop() and the beat can tell our
+ * socket from one another instance created at the same path (#277). */
+ private mark: FileMark | null = null;
+ private bound: { path: string; since: number } | null = null;
+ /** Listeners abandoned because a stranger owns the path now. Closing one would
+ * make libuv unlink(2) the PATH — by name, not by inode — and take the
+ * stranger's live socket with it. Kept unref()ed until the process exits. */
+ private orphans: Server[] = [];
+ private lastError: string | null = null;
+ private bindAttempts = 0;
+ private binding = false;
+ private retryTimer: NodeJS.Timeout | null = null;
+ /** One toast per outage, not one per retry. */
+ private alerted = false;
+ /** Set by stop(): the beat must not re-bind while the hive is being moved or
+ * the app is quitting — only start() re-arms. */
+ private stopped = false;
/** agentId → the live session's transcript file, learned from hook payloads.
* Lets the harness read per-agent telemetry (e.g. current context size)
* even when several agents share one cwd. */
@@ -86,55 +152,221 @@ export class HookServer {
private onEvent?: (agentId: string | undefined, event: string, message: string | undefined) => void
) {}
+ /** Bind the hook socket. Asynchronous and safe to call repeatedly — a
+ * listening server is left alone. Before #277 this returned SILENTLY when the
+ * hive had no root yet, and left the outcome of listen() to a console.error
+ * nobody reads: either way the whole control plane could be dead for a
+ * session with nothing logged. Now every outcome is logged (console and the
+ * hive's log.jsonl), failures are retried, and the beat keeps verifying. */
start(): void {
+ this.stopped = false;
+ void this.ensureListening();
+ }
+
+ /** The hook socket's live state — the beat writes it into fleet.json. */
+ health(): HookSocketHealth {
+ const listening = !!this.server?.listening && this.bound !== null;
+ return {
+ path: this.hive.sockPath(),
+ listening,
+ since: listening && this.bound ? this.bound.since : null,
+ lastError: this.lastError,
+ attempts: this.bindAttempts,
+ orphans: this.orphans.length
+ };
+ }
+
+ /** Make sure something is listening at HIVE_SOCK, and that it is US. Called
+ * by start() and then from the beat. Three outcomes:
+ * - not bound (never, or the last bind failed) → bind, with back-off;
+ * - bound, but the path no longer leads to our socket → we are "listening"
+ * on an orphaned inode while every shim's connect() fails: log it as lost
+ * and re-bind — unless a LIVE server owns the path now, which is never
+ * stolen;
+ * - bound and verified → nothing to do. */
+ async ensureListening(): Promise<HookSocketHealth> {
+ if (this.stopped || this.binding) return this.health();
const sock = this.hive.sockPath();
- if (!sock || this.server) return;
- // Clear a stale socket file left by a previous run.
- try { if (existsSync(sock)) rmSync(sock); } catch { /* noop */ }
-
- this.server = createServer((conn) => {
- let pending = Buffer.alloc(0);
- const rejectOversizedFrame = (bytes: number): void => {
- this.hive.appendLog({
- kind: 'hook-frame-rejected',
- reason: 'frame-too-large',
- bytes,
- limit: MAX_HOOK_FRAME_BYTES,
- });
- conn.destroy();
+ if (!sock) {
+ if (this.lastError !== 'NOROOT') {
+ this.lastError = 'NOROOT';
+ console.warn('[hive] hook socket not bound: the hive has no root yet (the beat will retry)');
+ }
+ return this.health();
+ }
+ if (this.server?.listening && this.bound) {
+ // Cheap check first (POSIX): the file at the path is still the one we bound.
+ if (this.mark && sameMark(this.mark, markOf(sock))) return this.health();
+ // Definitive check: does connecting to the path reach US?
+ const owner = await this.probe(sock);
+ if (owner === 'self') { this.mark = markOf(sock); return this.health(); }
+ const code = owner === 'other' ? 'REPLACED' : 'ENOENT';
+ this.detach(owner === 'other');
+ console.error(`[hive] hook socket LOST (${code}): ${sock} no longer reaches our listener — every hook has been allowed meanwhile`);
+ this.hive.appendLog({ kind: 'hooks', state: 'lost', path: sock, code });
+ if (owner === 'other') { this.bindAttempts += 1; this.fail(sock, 'EADDRINUSE', 'another process is listening there now'); return this.health(); }
+ }
+ await this.bind(sock);
+ return this.health();
+ }
+
+ private async bind(sock: string): Promise<void> {
+ this.binding = true;
+ try {
+ this.bindAttempts += 1;
+ if (process.platform !== 'win32' && existsSync(sock)) {
+ // A file left by a crashed run is normal and is cleared. A file a LIVE
+ // stranger accepts on is theirs: report it, never steal it.
+ if (await this.probe(sock) === 'other') { this.fail(sock, 'EADDRINUSE', 'another process is listening there'); return; }
+ try { rmSync(sock); } catch { /* listen() below reports it */ }
+ }
+ const server = createServer((conn) => this.serve(conn));
+ const outcome = new Promise<string | null>((resolve) => {
+ server.once('listening', () => resolve(null));
+ server.once('error', (e: NodeJS.ErrnoException) => resolve(e.code ?? e.message));
+ });
+ // listen() binds the path — and creates the socket file — synchronously;
+ // only the 'listening' event is deferred. Publish the handle and record
+ // which file is ours right here, before anything else can run: a caller
+ // that looks straight after start() sees the server, and a file that
+ // replaces ours later can never be mistaken for it.
+ server.listen(sock);
+ this.server = server;
+ this.mark = process.platform === 'win32' ? null : markOf(sock);
+ this.bound = { path: sock, since: Date.now() };
+ const err = await outcome;
+ if (this.server !== server) return; // stop() or a re-bind took this handle over meanwhile
+ if (err !== null) {
+ this.server = null;
+ this.mark = null;
+ this.bound = null;
+ try { server.close(); } catch { /* noop */ }
+ this.fail(sock, err, 'listen() failed');
+ return;
+ }
+ server.on('error', (e) => console.error('[hive] hook server error:', e));
+ this.lastError = null;
+ this.bindAttempts = 0;
+ this.alerted = false;
+ console.log(`[hive] hook server listening on ${sock}`);
+ this.hive.appendLog({ kind: 'hooks', state: 'listening', path: sock });
+ } finally {
+ this.binding = false;
+ }
+ }
+
+ /** A bind (or verify) failed: say so where an operator can find it, schedule
+ * a retry, and — once the back-off is spent — toast once per outage. */
+ private fail(sock: string, code: string, detail: string): void {
+ this.lastError = code;
+ console.error(`[hive] hook socket bind FAILED (${code}) at ${sock}: ${detail} — attempt ${this.bindAttempts}. Until this recovers every agent hook is ALLOWED and no cost is recorded.`);
+ this.hive.appendLog({ kind: 'hooks', state: 'bind-failed', path: sock, code, attempt: this.bindAttempts });
+ const i = Math.max(0, this.bindAttempts - 1);
+ if (i < BIND_RETRY_MS.length) {
+ if (this.retryTimer) clearTimeout(this.retryTimer);
+ this.retryTimer = setTimeout(() => { this.retryTimer = null; void this.ensureListening(); }, BIND_RETRY_MS[i]);
+ this.retryTimer.unref();
+ } else if (!this.alerted) {
+ this.alerted = true;
+ this.notify('Hive hooks are down', `Nothing is listening at ${sock} (${code}). Every agent hook is being allowed and no cost is recorded until this recovers.`);
+ }
+ }
+
+ /** One shim connection: a bounded, newline-delimited JSON frame in (#399),
+ * a JSON reply out. The ownership ping is answered here and never reaches
+ * handle(). */
+ private serve(conn: Socket): void {
+ let pending = Buffer.alloc(0);
+ const rejectOversizedFrame = (bytes: number): void => {
+ this.hive.appendLog({
+ kind: 'hook-frame-rejected',
+ reason: 'frame-too-large',
+ bytes,
+ limit: MAX_HOOK_FRAME_BYTES,
+ });
+ conn.destroy();
+ };
+ conn.on('data', (chunk) => {
+ pending = Buffer.concat([pending, chunk]);
+ const nl = pending.indexOf(0x0a);
+ if (nl === -1) {
+ if (pending.length > MAX_HOOK_FRAME_BYTES) rejectOversizedFrame(pending.length);
+ return; // wait for the full line
+ }
+ // The byte limit covers the JSON payload and excludes its newline.
+ if (nl > MAX_HOOK_FRAME_BYTES) {
+ rejectOversizedFrame(nl);
+ return;
+ }
+ // Hook shims send one newline-delimited request per connection and stop writing.
+ // conn.end() below closes the connection after that single frame is handled.
+ const frame = pending.subarray(0, nl).toString('utf8');
+ let payload: HookPayload = {};
+ try { payload = JSON.parse(frame); } catch { /* ignore */ }
+ if (typeof payload.ping === 'string') { conn.end(JSON.stringify({ pong: payload.ping, instance: this.instanceId })); return; }
+ let res: unknown = {};
+ try { res = this.handle(payload); } catch { res = {}; }
+ conn.end(JSON.stringify(res ?? {}));
+ });
+ conn.on('error', () => { /* shim hung up — ignore */ });
+ }
+
+ /** Connect to the path and ask who is there. */
+ private probe(sock: string, timeoutMs = 750): Promise<PathOwner> {
+ return new Promise((resolve) => {
+ let settled = false;
+ let connected = false;
+ let data = '';
+ const nonce = randomUUID();
+ const finish = (v: PathOwner): void => {
+ if (!settled) { settled = true; resolve(v); }
+ try { c.destroy(); } catch { /* noop */ }
};
- conn.on('data', (chunk) => {
- pending = Buffer.concat([pending, chunk]);
- const nl = pending.indexOf(0x0a);
- if (nl === -1) {
- if (pending.length > MAX_HOOK_FRAME_BYTES) rejectOversizedFrame(pending.length);
- return; // wait for the full line
- }
- // The byte limit covers the JSON payload and excludes its newline.
- if (nl > MAX_HOOK_FRAME_BYTES) {
- rejectOversizedFrame(nl);
- return;
- }
- // Hook shims send one newline-delimited request per connection and stop writing.
- // conn.end() below closes the connection after that single frame is handled.
- const frame = pending.subarray(0, nl).toString('utf8');
- let payload: HookPayload = {};
- try { payload = JSON.parse(frame); } catch { /* ignore */ }
- let res: unknown = {};
- try { res = this.handle(payload); } catch { res = {}; }
- conn.end(JSON.stringify(res ?? {}));
+ const c = createConnection(sock, () => { connected = true; c.write(JSON.stringify({ ping: nonce }) + '\n'); });
+ c.setEncoding('utf8');
+ c.on('data', (d) => { data += d; });
+ c.on('end', () => {
+ try {
+ const r = JSON.parse(data) as { pong?: string; instance?: string };
+ finish(r.pong === nonce && r.instance === this.instanceId ? 'self' : 'other');
+ } catch { finish('other'); }
});
- conn.on('error', () => { /* shim hung up — ignore */ });
+ c.on('error', () => finish(connected ? 'other' : 'nobody'));
+ setTimeout(() => finish(connected ? 'other' : 'nobody'), timeoutMs).unref();
});
- this.server.on('error', (e) => console.error('[hive] hook server error:', e));
- this.server.listen(sock);
}
- stop(): void {
- try { this.server?.close(); } catch { /* noop */ }
+ /** Let go of the current listener. Closing it is right ONLY while the path
+ * still leads to our socket (or to nothing): libuv unlink(2)s the path by NAME
+ * on close, so closing a listener whose path a live stranger has since bound
+ * deletes THEIR socket — the app is up, hooks.sock is gone, every hook
+ * allows, nothing is logged (#277). In that case the handle is abandoned
+ * instead: unreachable by path, one fd, reclaimed at exit. */
+ private detach(orphan: boolean): void {
+ const s = this.server;
this.server = null;
- const sock = this.hive.sockPath();
- try { if (sock && existsSync(sock)) rmSync(sock); } catch { /* noop */ }
+ this.mark = null;
+ this.bound = null;
+ if (!s) return;
+ if (orphan) {
+ try { s.unref(); } catch { /* noop */ }
+ this.orphans.push(s);
+ return;
+ }
+ try { s.close(); } catch { /* noop */ }
+ }
+
+ stop(): void {
+ this.stopped = true;
+ if (this.retryTimer) { clearTimeout(this.retryTimer); this.retryTimer = null; }
+ // Synchronous (quit and relaunch paths cannot wait for a probe): the file
+ // at the path is ours → close, and libuv removes it; missing → close, the
+ // unlink is a no-op; a DIFFERENT file → someone else bound the path after
+ // us, leave their socket alone and abandon ours.
+ const sock = this.bound?.path ?? null;
+ const now = sock && process.platform !== 'win32' ? markOf(sock) : null;
+ const stranger = !!this.mark && !!now && !sameMark(this.mark, now);
+ this.detach(stranger);
}
/** The transcript file of an agent's CURRENT session, if any hook has fired. */
diff --git a/src/main/index.ts b/src/main/index.ts
index 40634ac6..526764b5 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -1304,7 +1304,9 @@ function writeFleetSnapshot(): void {
onHold: !!a.onHold
};
});
- hive.writeFleetSnapshot({ ts: now, agents });
+ // `hooks` is the control plane's own health (#277): god and the operator
+ // can read from fleet.json whether hooks are being enforced at all.
+ hive.writeFleetSnapshot({ ts: now, agents, hooks: hookServer.health() });
} catch (e) {
console.error('[fleet] snapshot failed:', e);
}
@@ -5107,7 +5109,10 @@ function bootstrapHiveServices(): void {
/** Cadence of the worker inbox-wake watchdog (#151). Well under the renderer's
* own nudge cooldown so a throttled window is caught within ~15s of a stall. */
const WORKER_WAKE_POLL_MS = 15_000;
+/** How often the beat verifies the hook socket is bound AND still ours (#277). */
+const HOOK_HEALTH_MS = 15_000;
let workerWakeTimer: ReturnType<typeof setInterval> | null = null;
+let hookHealthTimer: ReturnType<typeof setInterval> | null = null;
/** Type the renderer's guarded nudge into one worker's PTY — text first, Enter a
* tick later (the exact submitToPty pattern: a single-chunk write would land the
@@ -5185,6 +5190,11 @@ function armAlwaysOnBeats(): void {
if (workerWakeTimer) clearInterval(workerWakeTimer);
workerWakeTimer = setInterval(() => { try { runWorkerWakeBeat(); } catch (e) { console.error('[worker-wake beat]', e); } }, WORKER_WAKE_POLL_MS);
runWorkerWakeBeat(); // catch-up on arm — power-resume re-arms and drains the backlog
+ // The hook socket is the whole control plane; a session where it is silently
+ // unbound looks exactly like "no workers have spawned yet" (#277). Verify it
+ // — bound, and the path still ours — and re-bind when it is not.
+ if (hookHealthTimer) clearInterval(hookHealthTimer);
+ hookHealthTimer = setInterval(() => { hookServer.ensureListening().catch((e) => console.error('[hooks beat]', e)); }, HOOK_HEALTH_MS);
}
/** Wall-clock instant we last observed the machine suspend or lock, so a resume
diff --git a/test/hooks-framing.test.cjs b/test/hooks-framing.test.cjs
index ede8cc9e..10ea79de 100644
--- a/test/hooks-framing.test.cjs
+++ b/test/hooks-framing.test.cjs
@@ -146,7 +146,9 @@ test('oversized incomplete frame is rejected without routing a payload', async (
assert.equal(result.didClose, true, 'server retained an oversized incomplete frame');
assert.deepEqual(routed, []);
assert.equal(result.response, '');
- assert.deepEqual(logs, [{
+ // The server also records its own bind in the same log (#277); only the
+ // rejection entries are this test's concern.
+ assert.deepEqual(logs.filter((l) => l.kind === 'hook-frame-rejected'), [{
kind: 'hook-frame-rejected',
reason: 'frame-too-large',
bytes: MAX_HOOK_FRAME_BYTES + 1,
@@ -175,7 +177,9 @@ test('payload one byte above the limit is rejected', async (t) => {
assert.equal(result.didClose, true);
assert.deepEqual(routed, []);
assert.equal(result.response, '');
- assert.deepEqual(logs, [{
+ // The server also records its own bind in the same log (#277); only the
+ // rejection entries are this test's concern.
+ assert.deepEqual(logs.filter((l) => l.kind === 'hook-frame-rejected'), [{
kind: 'hook-frame-rejected',
reason: 'frame-too-large',
bytes: MAX_HOOK_FRAME_BYTES + 1,
diff --git a/test/hooks-socket.test.cjs b/test/hooks-socket.test.cjs
new file mode 100644
index 00000000..32c233af
--- /dev/null
+++ b/test/hooks-socket.test.cjs
@@ -0,0 +1,193 @@
+'use strict';
+/**
+ * The hook socket (HIVE_SOCK) is the ONE endpoint every lifecycle hook, proxy
+ * emit and cost sample travels through. Upstream issue #277: it was silently
+ * unbound for a whole session — the app was up, `hooks.sock` did not exist,
+ * every hook's connect() failed and exited 0 (which the CLI reads as "allow"),
+ * fleet.json never appeared, and NOTHING was logged. These tests pin down the
+ * behaviour that makes that impossible to miss, and closes the one way we know
+ * a live socket can vanish under a running app:
+ * 1. a successful bind is reported (console + log.jsonl + fleet-visible health);
+ * 2. a failed bind is reported and retried, and toasts once the back-off is spent;
+ * 3. stop() removes only the socket file IT bound — never another instance's
+ * (an old instance hanging on quit + a relaunch is the #277 shape);
+ * 4. the beat re-binds when the socket file disappears under a listening server;
+ * 5. the beat never steals a socket another live server owns;
+ * 6. a hive with no root yet is not silent either.
+ */
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const net = require('node:net');
+const os = require('node:os');
+const path = require('node:path');
+const loadTs = require('./load-ts.cjs');
+
+const electron = require.resolve('electron');
+const toasts = [];
+require.cache[electron] = {
+ id: electron, filename: electron, loaded: true,
+ exports: {
+ Notification: class {
+ constructor(opts) { this.opts = opts; }
+ show() { toasts.push(this.opts); }
+ static isSupported() { return true; }
+ }
+ }
+};
+
+const { HiveManager } = loadTs('src/main/hive.ts');
+const { HookServer } = loadTs('src/main/hooks.ts');
+const CONFIG = { notifications: true };
+
+const posixOnly = { skip: process.platform === 'win32' ? 'named pipes have no socket file' : false };
+
+async function floor(t) {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'mdh-'));
+ const hive = new HiveManager(() => home);
+ await hive.ensureAgent({ id: 'jim-1', name: 'Jim', provider: 'claude', cwd: home });
+ const servers = [];
+ const make = () => { const s = new HookServer(hive, () => null, () => CONFIG, undefined, undefined); servers.push(s); return s; };
+ t.after(() => { for (const s of servers) { try { s.stop(); } catch { /* noop */ } } fs.rmSync(home, { recursive: true, force: true }); });
+ toasts.length = 0;
+ return { home, hive, make, sock: hive.sockPath() };
+}
+
+/** What a shim does: connect, send one JSON line, read the reply. */
+function roundTrip(sock, payload = { hook_event_name: 'Unknown', agent_id: 'jim-1' }) {
+ return new Promise((resolve, reject) => {
+ const c = net.createConnection(sock, () => c.write(JSON.stringify(payload) + '\n'));
+ let resp = '';
+ c.setEncoding('utf8');
+ c.on('data', (d) => { resp += d; });
+ c.on('end', () => resolve(resp));
+ c.on('error', reject);
+ });
+}
+
+function hookLog(hive) {
+ const p = path.join(hive.root(), 'log.jsonl');
+ if (!fs.existsSync(p)) return [];
+ return fs.readFileSync(p, 'utf8').split('\n').filter(Boolean).map((l) => JSON.parse(l)).filter((e) => e.kind === 'hooks');
+}
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Poll until `fn()` is truthy (start() binds asynchronously). */
+async function waitFor(fn, ms = 3000) {
+ const until = Date.now() + ms;
+ while (Date.now() < until) { if (fn()) return true; await sleep(20); }
+ return false;
+}
+
+test('a successful bind is reported: log.jsonl, health, and a shim round-trip', async (t) => {
+ const { hive, make, sock } = await floor(t);
+ const a = make();
+ a.start();
+ assert.ok(await waitFor(() => fs.existsSync(sock)), 'socket file appears');
+ assert.equal(await roundTrip(sock), '{}', 'a shim gets a JSON reply');
+ const log = hookLog(hive);
+ assert.deepEqual(log.map((e) => e.state), ['listening'], 'the bind is recorded where an operator can find it');
+ assert.equal(log[0].path, sock);
+ const h = a.health();
+ assert.equal(h.listening, true, JSON.stringify(h));
+ assert.equal(h.path, sock);
+ assert.equal(h.lastError, null);
+ assert.equal(h.attempts, 0);
+ assert.equal(h.orphans, 0);
+ assert.ok(typeof h.since === 'number');
+});
+
+test('a failed bind is loud and retried, and toasts once the back-off is spent', async (t) => {
+ const { home } = await floor(t);
+ const logs = [];
+ // A hive whose socket path cannot be bound (its directory does not exist).
+ const hive = { sockPath: () => path.join(home, 'nope', 'hooks.sock'), appendLog: (e) => logs.push(e) };
+ const a = new HookServer(hive, () => null, () => CONFIG, undefined, undefined);
+ t.after(() => a.stop());
+ const h = await a.ensureListening();
+ assert.equal(h.listening, false);
+ assert.ok(['ENOENT', 'EACCES'].includes(h.lastError), JSON.stringify(h)); // macOS says EACCES for a missing dir
+ assert.equal(h.attempts, 1);
+ assert.equal(logs.length, 1);
+ assert.equal(logs[0].kind, 'hooks');
+ assert.equal(logs[0].state, 'bind-failed');
+ assert.equal(logs[0].code, h.lastError);
+ assert.equal(toasts.length, 0, 'the first failure retries quietly');
+ // Exhaust the back-off (each call is one attempt; the timers would do the same).
+ for (let i = 0; i < 6; i++) await a.ensureListening();
+ assert.ok(a.health().attempts >= 6, `attempts=${a.health().attempts}`);
+ assert.equal(toasts.length, 1, 'exactly one toast per outage');
+ assert.match(toasts[0].title, /hooks are down/i);
+ assert.match(toasts[0].body, /allowed/i);
+});
+
+test('stop() removes only the socket file it bound — never another instance\'s', posixOnly, async (t) => {
+ const { make, sock } = await floor(t);
+ const a = make();
+ a.start();
+ assert.ok(await waitFor(() => fs.existsSync(sock)));
+ // The #277 shape: A lingers on quit, its socket file goes away, a relaunched
+ // instance B binds the same path, then A finally finishes quitting.
+ fs.rmSync(sock);
+ const b = make();
+ b.start();
+ assert.ok(await waitFor(() => fs.existsSync(sock)));
+ assert.equal(await roundTrip(sock), '{}', 'B serves');
+ a.stop();
+ await sleep(50);
+ assert.ok(fs.existsSync(sock), 'B\'s socket file survives A.stop()');
+ assert.equal(await roundTrip(sock), '{}', 'B still serves');
+ b.stop();
+ await sleep(50);
+ assert.ok(!fs.existsSync(sock), 'B removes its own file');
+});
+
+test('the beat re-binds when the socket file disappears under a listening server', posixOnly, async (t) => {
+ const { hive, make, sock } = await floor(t);
+ const a = make();
+ await a.ensureListening();
+ fs.rmSync(sock);
+ await assert.rejects(roundTrip(sock), /ENOENT/, 'with the file gone every shim fails to connect');
+ assert.equal(a.health().listening, true, 'and the server itself cannot tell');
+ const h = await a.ensureListening();
+ assert.equal(h.listening, true, JSON.stringify(h));
+ assert.equal(await roundTrip(sock), '{}');
+ assert.deepEqual(hookLog(hive).map((e) => `${e.state}${e.code ? ':' + e.code : ''}`), ['listening', 'lost:ENOENT', 'listening']);
+});
+
+test('the beat never steals a socket another live server owns', posixOnly, async (t) => {
+ const { make, sock } = await floor(t);
+ const a = make();
+ await a.ensureListening();
+ fs.rmSync(sock);
+ const b = make();
+ await b.ensureListening();
+ const h = await a.ensureListening();
+ assert.equal(h.listening, false, JSON.stringify(h));
+ assert.equal(h.lastError, 'EADDRINUSE');
+ assert.equal(h.orphans, 1, 'A abandoned its listener rather than closing it (libuv would unlink B\'s path)');
+ assert.equal(await roundTrip(sock), '{}', 'B keeps serving');
+ b.stop();
+ // Once the owner is gone, A takes the path back (a scheduled retry may race
+ // an explicit call, so settle rather than assert the first answer).
+ for (let i = 0; i < 20 && !(await a.ensureListening()).listening; i++) await sleep(50);
+ assert.equal(a.health().listening, true);
+ assert.equal(await roundTrip(sock), '{}');
+});
+
+test('a hive with no root yet is not silent, and binds once the root appears', async (t) => {
+ const { home } = await floor(t);
+ const logs = [];
+ let root = null;
+ const hive = { sockPath: () => (root ? path.join(root, 'hooks.sock') : null), appendLog: (e) => logs.push(e) };
+ const a = new HookServer(hive, () => null, () => CONFIG, undefined, undefined);
+ t.after(() => a.stop());
+ const h = await a.ensureListening();
+ assert.equal(h.listening, false);
+ assert.equal(h.lastError, 'NOROOT');
+ assert.equal(h.path, null);
+ root = home;
+ const h2 = await a.ensureListening();
+ assert.equal(h2.listening, true, JSON.stringify(h2));
+ assert.equal(logs.at(-1).state, 'listening');
+});