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(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.pngnew file mode 100644index 00000000..c5bb70b1Binary files /dev/null and b/docs/pr-evidence/hook-socket-after.png differdiff --git a/docs/pr-evidence/hook-socket-before.png b/docs/pr-evidence/hook-socket-before.pngnew file mode 100644index 00000000..609f9a21Binary files /dev/null and b/docs/pr-evidence/hook-socket-before.png differdiff --git a/src/main/hooks.ts b/src/main/hooks.tsindex 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.tsindex 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 resumediff --git a/test/hooks-framing.test.cjs b/test/hooks-framing.test.cjsindex 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.cjsnew file mode 100644index 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');+});