heedvane 0.3.3 → 0.3.4

package/dist/listener/serve.js

@@ -7,22 +7,26 @@
  * listener enforces before its first sync. Without a credential it still runs: the skill check is
  * local and the rest is skipped.
  */
-import { mkdir, unlink } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { mkdir, rm, unlink } from "node:fs/promises";
 import { join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
-import { backendAt } from "../backend/credentials.js";
+import { backendAt, signInIdentity } from "../backend/credentials.js";
 import { discardSteeringCaches, reconcileSignIn, signedInAsPath } from "../backend/sign-in-change.js";
 import { uncappedToolInput } from "../events/normalize.js";
 import { errorMessage, isRecord } from "../guards.js";
-import { heedvaneConfigAt } from "../heed-file.js";
+import { START_LOCK } from "../hook-fallback.js";
+import { DEFAULT_HEED_YAML_TEMPLATE, loadHeedFile, readHeedFileAt } from "../heed-file.js";
 import { harnessOutput } from "../reply/harness-output.js";
 import { fetchTeamMemoryMap } from "../memory/team-memory.js";
 import { BACKEND_BUDGET_MS, eventRemote, replyFor } from "../reply/reply.js";
 import { ALLOW } from "../reply/verdict.js";
 import { fetchSteeringPolicy, instructionContext, readSteeringPolicy, saveSteeringPolicy } from "../steering/rules.js";
-import { ensureEndpoint } from "./endpoint.js";
+import { setTimeout as delay } from "node:timers/promises";
+import { ensureEndpoint, freeLoopbackPort, HEEDVANE_VERSION, listenerVerdict, probeListener, readEndpoint, writeEndpoint } from "./endpoint.js";
 import { DELIVERIES_ROUTE, outbox } from "./forward.js";
-import { startListener } from "./server.js";
+import { SHUTDOWN_ROUTE, startListener, STOP_REASON_HEADER } from "./server.js";
 const FLUSH_INTERVAL_MS = 5_000;
 /** The Claude Code events whose organization instructions the dispatcher answers with when the listener is down. */
 const INSTRUCTION_EVENTS = { session_start: "SessionStart", user_prompt_submit: "UserPromptSubmit" };
@@ -30,11 +34,31 @@ const INSTRUCTION_EVENTS = { session_start: "SessionStart", user_prompt_submit:
 function instructionAnswerPath(root, hookEventName) {
     return join(root, "steering", `instructions-${hookEventName}.json`);
 }
+/** A listener of this version already runs at the port with the settings this one would run (or a newer one runs): nothing to start. */
+export class ListenerAlreadyRuns extends Error {
+    version;
+    constructor(version, newer) {
+        super(newer ? `a newer Heedvane listener (${version}) already runs` : `a Heedvane listener (${version}) already runs with these settings`);
+        this.name = "ListenerAlreadyRuns";
+        this.version = version;
+    }
+}
+/**
+ * The listener for `home`, and the one place a listener starts (`listener start`, which `ensureListener` and the hooks
+ * run). It reads heed.yaml once, prepares everything a hook's answer needs, and only then takes the port: a listener
+ * there that {@link listenerVerdict} says to keep makes it throw {@link ListenerAlreadyRuns}; any other is asked to stop,
+ * and this one binds as soon as the port is free. Rejects when the port stays taken.
+ */
 export async function serveHooks(home, out) {
     const root = join(home, ".heed");
-    await ensureEndpoint(root);
+    const served = await ensureEndpoint(root);
     const log = (message) => out(`  · ${message}`);
-    const config = heedvaneConfigAt(root);
+    const settings = await settingsToRun(root);
+    if (settings.unparseable === undefined)
+        writeFileAtomic.sync(lastGoodPath(root), settings.text, { mode: 0o600 });
+    else
+        log(`[heedvane] ${settings.unparseable}; the listener runs with the settings it last started with. Fix it, then: npx heedvane listener restart`);
+    const config = settings.config;
     // Whatever an earlier sign-in left (spooled events, instructions, caches) is set aside before anything reads it or replays it.
     // Failing closed: when it cannot tell whose sign-in the leftovers belong to, the listener does not start and does not replay or enforce under a guess; it says why.
     await reconcileSignIn(root, config.url).catch((err) => {
@@ -44,12 +68,18 @@ export async function serveHooks(home, out) {
     // A hook never waits on a login refresh; it runs in the background and is logged when it fails.
     const org = await backendAt(root, config.url, { wait: false, log });
     // The policy is the sign-in's own: a cache from, or a login to, another organization never applies.
-    let policyFor = (await org?.identity()) ?? null;
-    let policy = await readSteeringPolicy(root, policyFor);
+    let policy = await readSteeringPolicy(root, (await org?.identity()) ?? null);
     // Each session holds the policy fetched at its session start; one without (the listener started mid-session) uses the last synced.
     // shortcut: a session that never ends keeps its entry until the listener restarts; upgrade if sessions pile up.
     const sessionPolicies = new Map();
-    const deliveries = await outbox(DELIVERIES_ROUTE, { root, backend: org, log });
+    // The outbox file is rewritten whole, so it is read and written only once the listener this one replaces has exited.
+    let outboxFree = () => undefined;
+    const fileFree = new Promise((resolve) => (outboxFree = resolve));
+    const deliveries = outbox(DELIVERIES_ROUTE, { root, backend: org, log, fileFree })
+        .catch((err) => {
+        log(`[heedvane] could not open the steering delivery outbox, so this listener sends no reports: ${errorMessage(err)}`);
+        return null;
+    });
     const ctx = {
         config,
         backend: org,
@@ -58,7 +88,10 @@ export async function serveHooks(home, out) {
         log,
         policy: (session) => sessionPolicies.get(session) ?? policy,
         // Sent at once: Heedvane settles an enforcement's outcome from the session's next event, so a late report misreads it.
-        report: (delivery) => void deliveries.add(delivery).then(deliveries.flush).catch((err) => log(`[heedvane] could not queue a steering delivery report: ${errorMessage(err)}`)),
+        report: (delivery) => void deliveries.then((box) => box?.add(delivery).then(box.flush)).catch((err) => {
+            log(`[heedvane] could not queue a steering delivery report: ${errorMessage(err)}`);
+            return undefined; // a hook's answer never waits on its report
+        }),
         stopBlocks: new Map(),
         violations: new Map(),
         sessionEnds: new Map(),
@@ -73,7 +106,6 @@ export async function serveHooks(home, out) {
         if ((await org.identity()) !== identity)
             return; // signed in elsewhere meanwhile: that sign-in syncs its own
         policy = synced.policy;
-        policyFor = identity;
         await saveSteeringPolicy(root, synced.answer, identity);
         await writeInstructionAnswers(root, policy);
         // A sign-in that changed while these were written has already cleaned up; do not leave its predecessor's rules behind.
@@ -82,20 +114,17 @@ export async function serveHooks(home, out) {
     };
     // A sync that cannot write its cache is logged, never an unhandled rejection that ends the listener.
     const syncPolicySafely = () => syncPolicy().catch((err) => log(`[heedvane] could not sync the steering policy: ${errorMessage(err)}`));
-    await syncPolicySafely();
+    // Without a cached policy the first answers would miss the organization's rules: fetch it before taking the port.
+    const cached = policy !== null;
+    if (!cached)
+        await syncPolicySafely();
+    const handover = takeOver({ root, served, settings: settings.hash, log });
     const started = await startListener({
         root,
+        endpoint: served,
+        settings: settings.hash,
+        onAddressInUse: handover.onAddressInUse,
         onEvent: async ({ envelope, body, replayed }) => {
-            const signedInAs = (await org?.identity()) ?? null;
-            if (signedInAs !== policyFor) {
-                policy = null;
-                sessionPolicies.clear();
-                // What was pending or counted belongs to the organization signed out of: it must not reach, or be reported under, the next.
-                ctx.violations.clear();
-                ctx.stopBlocks.clear();
-                policyFor = signedInAs;
-                void syncPolicySafely();
-            }
             out(JSON.stringify(envelope));
             // A replayed event's agent got its answer (the fallback) long ago: record it, never re-steer it.
             if (replayed === true)
@@ -103,7 +132,7 @@ export async function serveHooks(home, out) {
             let teamMemory;
             if (envelope.event === "session_start") {
                 // The one wait on Heedvane in a hook: the policy and the team memory's map, fetched together.
-                [, teamMemory] = await Promise.all([syncPolicySafely(), config.dataMode === "metrics-only" ? undefined : teamMemoryAtStart(org, envelope)]);
+                [, teamMemory] = await Promise.all([syncPolicySafely(), ctx.config.dataMode === "metrics-only" ? undefined : teamMemoryAtStart(org, envelope)]);
                 if (policy !== null)
                     sessionPolicies.set(envelope.session, policy);
             }
@@ -112,19 +141,154 @@ export async function serveHooks(home, out) {
             return replyFor(envelope, ctx, { toolInput: isRecord(body) ? uncappedToolInput(body) : undefined, teamMemory });
         },
         log,
+    }).catch(async (err) => {
+        // A listener it keeps already runs: the hooks may start one at once should that one end.
+        if (err instanceof ListenerAlreadyRuns)
+            await rm(join(root, START_LOCK), { recursive: true, force: true });
+        throw err;
+    });
+    void handover.exited().then(outboxFree);
+    if (cached)
+        void syncPolicySafely();
+    const flush = () => void deliveries.then((box) => box?.flush());
+    // A listener steps down once endpoint.env no longer names it (another start moved, or Heedvane was removed): no hook
+    // reaches it there, and its last reports go out as it closes. A read that fails keeps it running.
+    const stepDownWhenReplaced = async () => {
+        const named = await readEndpoint(root).catch(() => undefined);
+        if (named === undefined || (named !== null && named.port === started.port && named.token === served.token))
+            return;
+        log(`[heedvane] endpoint.env names ${named === null ? "no listener" : `127.0.0.1:${named.port}`}, not this listener (${started.port}); it stops`);
+        started.server.close();
+        started.server.closeIdleConnections();
+    };
+    const timer = setInterval(() => {
+        flush();
+        void stepDownWhenReplaced();
+    }, FLUSH_INTERVAL_MS).unref();
+    started.server.on("close", () => {
+        clearInterval(timer);
+        flush();
     });
-    if (org !== null) {
-        const flush = () => void deliveries.flush();
-        const timer = setInterval(flush, FLUSH_INTERVAL_MS);
-        started.server.on("close", () => {
-            clearInterval(timer);
-            flush();
-        });
-    }
     if (org === null)
         log("not signed in (npx heedvane login) and no organization key: steering is off");
+    // Listening: the hooks may start a fresh listener at once when this one exits.
+    await rm(join(root, START_LOCK), { recursive: true, force: true });
     return started;
 }
+/** How long a listener that was asked to stop gets to free the port, and then to exit (it may be sending reports). */
+const HANDOVER_PORT_MS = 5_000;
+const HANDOVER_EXIT_MS = 15_000;
+const HANDOVER_POLL_MS = 20;
+/**
+ * Taking the port from the listener that holds it: each time the bind finds the port taken, the listener there is
+ * judged by {@link listenerVerdict}; one to keep ends this start ({@link ListenerAlreadyRuns}), any other is asked once to
+ * stop. A port no Heedvane listener ever answered on is another program's: this one moves to a free port in
+ * endpoint.env, which the hooks read on every event. `exited` resolves once the stopped listener's process is gone, so
+ * its last writes are on disk.
+ */
+function takeOver({ root, served, settings, log }) {
+    const endpoint = { ...served };
+    const deadline = Date.now() + HANDOVER_PORT_MS;
+    let asked = false;
+    let seen = false;
+    let pid = null;
+    const onAddressInUse = async () => {
+        const running = await probeListener(endpoint);
+        seen ||= running !== null;
+        const verdict = listenerVerdict(running, settings);
+        if (running !== null && (verdict === "keep" || verdict === "newer"))
+            throw new ListenerAlreadyRuns(running.version, verdict === "newer");
+        if (running !== null && !asked) {
+            asked = true;
+            pid = (await askToStop(endpoint, verdict === "replace" ? `replaced by version ${HEEDVANE_VERSION}` : "heed.yaml or the sign-in changed")).pid;
+        }
+        // A listener of this machine too busy to answer in 750 ms counts as another program too: it steps down once it sees endpoint.env name this one.
+        if (!seen)
+            return movedToFreePort();
+        if (Date.now() > deadline)
+            return null;
+        await delay(HANDOVER_POLL_MS);
+        return endpoint.port;
+    };
+    const movedToFreePort = async () => {
+        const taken = endpoint.port;
+        // Another start may have moved since this one read endpoint.env: a listener to keep on the port it names ends this one.
+        const named = await readEndpoint(root).catch(() => null);
+        const there = named !== null && named.port !== taken ? await probeListener(named) : null;
+        const verdict = listenerVerdict(there, settings);
+        if (there !== null && (verdict === "keep" || verdict === "newer"))
+            throw new ListenerAlreadyRuns(there.version, verdict === "newer");
+        endpoint.port = await freeLoopbackPort();
+        await writeEndpoint(root, endpoint);
+        log(`[heedvane] nothing on 127.0.0.1:${taken} answered as this machine's listener (another program, or a listener too busy to answer), so this one moves to ${endpoint.port} (endpoint.env)`);
+        return endpoint.port;
+    };
+    const exited = async () => {
+        // shortcut: a listener older than 0.3.4 does not name its pid, so it is not waited for; its last reports may be sent twice (Heedvane drops copies by id).
+        if (pid === null)
+            return;
+        for (const until = Date.now() + HANDOVER_EXIT_MS; isAlive(pid); await delay(HANDOVER_POLL_MS)) {
+            if (Date.now() > until)
+                return log(`[heedvane] the listener this one replaced (pid ${pid}) has not exited after ${HANDOVER_EXIT_MS / 1000} s; its outbox is read anyway`);
+        }
+    };
+    return { onAddressInUse, exited };
+}
+/** Asks the listener at `endpoint` to stop: its answer's status (null without one) and the pid it names (0.3.4 on). */
+export async function askToStop(endpoint, reason) {
+    try {
+        const answer = await fetch(`http://127.0.0.1:${endpoint.port}${SHUTDOWN_ROUTE}`, { method: "POST", headers: { "x-heed-agent-hook-token": endpoint.token, [STOP_REASON_HEADER]: reason }, signal: AbortSignal.timeout(HANDOVER_PORT_MS) });
+        const body = (await answer.json().catch(() => null));
+        return { status: answer.status, pid: typeof body?.pid === "number" ? body.pid : null };
+    }
+    catch {
+        return { status: null, pid: null }; // no answer: whoever asked waits for the port, and gives up
+    }
+}
+/** Whether process `pid` still runs. */
+export function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === "EPERM"; // it runs, as another user
+    }
+}
+/** Where a listener keeps the heed.yaml it last started with, which it runs while heed.yaml does not parse. */
+export function lastGoodPath(root) {
+    return join(root, "heed.yaml.last-good");
+}
+/**
+ * The settings a listener started now would run: heed.yaml (the template's when there is none), else, when it does not
+ * parse, the copy a listener last started with. Throws when neither parses. The hash covers the same text that was
+ * parsed and the sign-in, so a running listener's report compares with it exactly.
+ */
+export async function settingsToRun(root) {
+    const { config, text, unparseable } = heedYamlToRun(root);
+    const identity = await signInIdentity(root, config.url);
+    return { config, text, unparseable, hash: createHash("sha256").update(text).update(`\0${identity}`).digest("hex").slice(0, 16) };
+}
+function heedYamlToRun(root) {
+    const heedYaml = join(root, "heed.yaml");
+    try {
+        const { heedFile, text } = readHeedFileAt(heedYaml);
+        return { config: heedFile.heedvane, text };
+    }
+    catch (err) {
+        const { code, syscall } = err;
+        // The template's text, so the copy kept as the last good one parses when a heed.yaml written later does not.
+        if (code === "ENOENT")
+            return { config: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE).heedvane, text: DEFAULT_HEED_YAML_TEMPLATE };
+        // A read error (EACCES, EISDIR) has a system call; a parse error does not.
+        const unparseable = `${heedYaml} ${syscall === undefined ? `does not parse (${errorMessage(err)})` : `cannot be read (${code})`}`;
+        // shortcut: with no last-good copy (a first heed.yaml that never parsed) no listener starts and the hooks retry once a minute; start on the template if that case shows up.
+        if (!existsSync(lastGoodPath(root)))
+            throw new Error(`${unparseable}, and there is no last good copy of it to run`, { cause: err });
+        const text = readFileSync(lastGoodPath(root), "utf8");
+        return { config: loadHeedFile(text).heedvane, text, unparseable };
+    }
+}
 /** The map of the session's repository, or nothing to ask without a credential or a checkout origin. */
 async function teamMemoryAtStart(org, envelope) {
     const gitOrigin = org === null ? "" : await eventRemote(envelope);

package/dist/listener/server.d.ts

@@ -1,4 +1,5 @@
 import type { IncomingMessage, Server } from "node:http";
+import { type Endpoint } from "./endpoint.js";
 import type { Envelope } from "../events/contract.js";
 /** Agent ids accepted on `/hook/<agentId>`. */
 export declare const KNOWN_AGENTS: ReadonlySet<string>;
@@ -25,6 +26,12 @@ export interface StartListenerOptions {
     log?: (message: string) => void;
     /** Override the known-agent table (defaults to KNOWN_AGENTS). */
     knownAgents?: ReadonlySet<string>;
+    /** The port and token to serve instead of reading endpoint.env (serveHooks passes the one it ensured; port 0 takes any free one). */
+    endpoint?: Endpoint;
+    /** The hash of the settings the listener runs (serve.ts `settingsToRun`), named in its probe answer. */
+    settings?: string;
+    /** The port is taken: resolves true to bind again (the listener there was asked to stop), false to give up. */
+    onAddressInUse?: () => Promise<number | null>;
 }
 export interface StartedListener {
     server: Server;
@@ -41,6 +48,8 @@ export interface StartedListener {
 export declare function safeTokenEqual(a: string, b: string): boolean;
 /** `POST /shutdown` with the token: uninstall stops the listener it no longer has hooks for. */
 export declare const SHUTDOWN_ROUTE = "/shutdown";
+/** Why a command asks the listener to stop, for the one line it logs. */
+export declare const STOP_REASON_HEADER = "x-heed-stop-reason";
 /**
  * Start the loopback hook listener: binds 127.0.0.1 only (never 0.0.0.0),
  * serves POST /hook/<agentId>, auths via x-heed-agent-hook-token against

package/dist/listener/server.js

@@ -1,6 +1,7 @@
 import { createServer } from "node:http";
 import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
-import { endpointPath, readEndpoint } from "./endpoint.js";
+import { listenerProof, PROBE_REFUSAL, PROOF_HEADER } from "../hook-fallback.js";
+import { endpointPath, HEEDVANE_VERSION, readEndpoint } from "./endpoint.js";
 import { drainSpool } from "./spool.js";
 import { normalize } from "../events/normalize.js";
 import { errorMessage } from "../guards.js";
@@ -13,6 +14,7 @@ export const KNOWN_AGENTS = new Set([
     "gemini",
     "cursor",
     "opencode",
+    "pi",
     "qwen-code",
     "kimi",
     "droid",
@@ -73,6 +75,8 @@ function sendJson(res, status, body) {
 const ROUTE_PATTERN = /^\/hook\/([A-Za-z0-9_-]+)$/;
 /** `POST /shutdown` with the token: uninstall stops the listener it no longer has hooks for. */
 export const SHUTDOWN_ROUTE = "/shutdown";
+/** Why a command asks the listener to stop, for the one line it logs. */
+export const STOP_REASON_HEADER = "x-heed-stop-reason";
 /** True after answering a token-carrying `POST /shutdown`; the listener closes once the answer is sent. */
 function handledShutdown(req, res, deps) {
     if (req.method !== "POST" || new URL(req.url ?? "/", "http://127.0.0.1").pathname !== SHUTDOWN_ROUTE)
@@ -81,12 +85,14 @@ function handledShutdown(req, res, deps) {
         sendJson(res, 401, { error: "invalid or missing x-heed-agent-hook-token" });
         return true;
     }
+    deps.log(`[heedvane] listener stopping: ${String(req.headers[STOP_REASON_HEADER] ?? "asked to stop")}`);
     res.on("finish", deps.stop);
-    sendJson(res, 200, { stopping: true });
+    // The pid: whoever takes over waits for this process to exit before it reads the files this one still writes.
+    sendJson(res, 200, { stopping: true, pid: process.pid });
     return true;
 }
 /** The route's agent id, or null after answering 404/405. */
-function routeAgent(req, res, agents) {
+function routeAgent(req, res, deps) {
     const route = ROUTE_PATTERN.exec(new URL(req.url ?? "/", "http://127.0.0.1").pathname);
     if (route === null) {
         sendJson(res, 404, { error: "not found" });
@@ -94,10 +100,10 @@ function routeAgent(req, res, agents) {
     }
     const agent = route[1];
     if (req.method !== "POST") {
-        sendJson(res, 405, { error: "method not allowed; POST only" });
+        sendJson(res, 405, { error: PROBE_REFUSAL, version: HEEDVANE_VERSION, settings: deps.settings });
         return null;
     }
-    if (!agents.has(agent)) {
+    if (!deps.agents.has(agent)) {
         sendJson(res, 404, { error: `unknown agent route: /hook/${agent}` });
         return null;
     }
@@ -158,15 +164,16 @@ function parseJsonObject(bodyText, res) {
     return body;
 }
 /** Last-resort responder: an async failure must not hang or crash the process. */
-function internalErrorResponder(res) {
-    return () => {
+function internalErrorResponder(res, log) {
+    return (err) => {
+        log(`[heedvane] could not answer a hook (500): ${errorMessage(err)}`); // the hooks' notice points at this log
         sendJson(res, 500, { error: "internal error" });
     };
 }
 async function handleRequest(req, res, deps) {
     if (handledShutdown(req, res, deps))
         return;
-    const agent = routeAgent(req, res, deps.agents);
+    const agent = routeAgent(req, res, deps);
     if (agent === null)
         return;
     if (!hasValidToken(req, deps.token)) {
@@ -186,9 +193,19 @@ async function handleRequest(req, res, deps) {
         return;
     // Normalize at the door: every accepted event leaves as the canonical
     // envelope — one taxonomy for all ingest paths (listener, spool replay).
-    const envelope = normalize(agent, body, { id: eventId(req.headers["x-heed-event-id"]) });
+    const id = eventId(req.headers["x-heed-event-id"]);
+    // The fallback asks again with the hook's event id when the first answer did not reach it (a timeout, a takeover):
+    // both asks get the answer of one steering of the event.
+    const answer = deps.answers.get(id) ?? answerKept(deps.answers, id, Promise.resolve(deps.onEvent({ agent, body, envelope: normalize(agent, body, { id }), headers: req.headers })));
     // The dispatcher prints this body as the agent's hook output; `{}` lets the agent continue.
-    sendJson(res, 200, (await deps.onEvent({ agent, body, envelope, headers: req.headers })) ?? {});
+    sendJson(res, 200, (await answer) ?? {});
+}
+/** How long an event's answer is kept for its hook's second ask, which comes within seconds. */
+const ANSWER_KEPT_MS = 30_000;
+function answerKept(answers, id, answer) {
+    answers.set(id, answer);
+    setTimeout(() => answers.delete(id), ANSWER_KEPT_MS).unref();
+    return answer;
 }
 /**
  * Start the loopback hook listener: binds 127.0.0.1 only (never 0.0.0.0),
@@ -197,7 +214,7 @@ async function handleRequest(req, res, deps) {
  * missing or has no TOKEN.
  */
 export async function startListener(options) {
-    const endpoint = await readEndpoint(options.root);
+    const endpoint = options.endpoint ?? (await readEndpoint(options.root));
     if (endpoint === null) {
         throw new Error(`No endpoint.env at ${endpointPath(options.root)} — the listener has no port/token to serve. ` +
             `Remediation: run "npx heedvane setup" to write ${endpointPath(options.root)} ` +
@@ -210,8 +227,10 @@ export async function startListener(options) {
     }
     const log = options.log ?? ((message) => console.log(message));
     const agents = options.knownAgents ?? KNOWN_AGENTS;
+    const proof = await listenerProof(endpoint.token);
     const server = createServer((req, res) => {
-        handleRequest(req, res, deps).catch(internalErrorResponder(res));
+        res.setHeader(PROOF_HEADER, proof); // on every answer: this machine's listener, for the hooks and the start's probe
+        handleRequest(req, res, deps).catch(internalErrorResponder(res, log));
     });
     const deps = {
         agents,
@@ -219,24 +238,20 @@ export async function startListener(options) {
         onEvent: options.onEvent,
         log,
         warned: new Set(),
+        answers: new Map(),
+        settings: options.settings,
+        // Hooks already in flight get their answers; only idle keep-alive connections close now.
         stop: () => {
             server.close();
-            server.closeAllConnections();
+            server.closeIdleConnections();
         },
     };
     // Node-level slowloris hardening (covers stalls before the request handler
     // fires); requestTimeout must be larger than headersTimeout.
     server.requestTimeout = REQUEST_TIMEOUT_MS;
     server.headersTimeout = REQUEST_TIMEOUT_MS - 500;
-    await new Promise((resolve, reject) => {
-        const onListenError = (err) => reject(err);
-        server.once("error", onListenError);
-        server.listen(endpoint.port, "127.0.0.1", () => {
-            server.off("error", onListenError);
-            server.on("error", (err) => log(`[heedvane] listener error: ${err.message}`));
-            resolve();
-        });
-    });
+    await listenOn(server, endpoint.port, options.onAddressInUse);
+    server.on("error", (err) => log(`[heedvane] listener error: ${err.message}`));
     const address = server.address();
     const port = address !== null && typeof address === "object" ? address.port : endpoint.port;
     // Events the dispatchers spooled while no listener was up enter through the same door.
@@ -261,6 +276,28 @@ export async function startListener(options) {
     });
     return { server, port, replayed };
 }
+/** Binds `port`; while another process holds it, `onAddressInUse` names the port to try next, or null to give up. */
+async function listenOn(server, port, onAddressInUse) {
+    for (let next = port;;) {
+        try {
+            return await bind(server, next);
+        }
+        catch (err) {
+            next = err.code === "EADDRINUSE" ? await onAddressInUse?.() : null;
+            if (next === null || next === undefined)
+                throw err;
+        }
+    }
+}
+function bind(server, port) {
+    return new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(port, "127.0.0.1", () => {
+            server.off("error", reject);
+            resolve();
+        });
+    });
+}
 /** The dispatcher's event id when it is a plausible one, else a fresh one (scripts older than ids). */
 function eventId(value) {
     return typeof value === "string" && /^[A-Za-z0-9-]{8,64}$/.test(value) ? value : randomUUID();

package/dist/listener/spool.d.ts

@@ -1,19 +1,4 @@
-/**
- * One spooled hook event, exactly as the dispatcher script (`spool_hook_event` in
- * dispatchers/posix.ts, the only writer) appends it: `payload` is the raw hook JSON text
- * the agent piped in, `source` the agent id. Cap and TTL are enforced by that writer.
- */
-export interface SpooledEvent {
-    paneKey: string;
-    tabId: string;
-    worktreeId: string;
-    launchToken: string;
-    source: string;
-    receivedAt: string;
-    payload: string;
-    /** The event's unique id (absent in lines from scripts older than ids). */
-    id?: string;
-}
+import { type SpoolRecord } from "../hook-fallback.js";
 /** Directory under the heed root that holds per-pane spool files. */
 export declare function spoolDir(root: string): string;
 /** A pane spool file, or one a drain claimed (renamed away from the dispatcher) and has not finished. */
@@ -25,4 +10,4 @@ export declare function isPaneSpoolFile(name: string): boolean;
  * next call. Lines that fail to parse are skipped (a torn append from a killed dispatcher). Returns the
  * number of events delivered.
  */
-export declare function drainSpool(root: string, onEvent: (event: SpooledEvent) => void | Promise<void>): Promise<number>;
+export declare function drainSpool(root: string, onEvent: (event: SpoolRecord) => void | Promise<void>): Promise<number>;

package/dist/listener/spool.js

@@ -1,8 +1,11 @@
 import { readdir, readFile, rename, unlink } from "node:fs/promises";
 import { join } from "node:path";
+import { SPOOL_DIR, SPOOL_FILE_PREFIX, SPOOL_FILE_SUFFIX } from "../hook-fallback.js";
+// The spool's records (SpoolRecord) have two writers, with the values of src/hook-fallback.ts, cap and TTL included:
+// the dispatcher script (`spool_hook_event` in dispatchers/posix.ts) and Pi's guard (src/guard.ts).
 /** Directory under the heed root that holds per-pane spool files. */
 export function spoolDir(root) {
-    return join(root, "spool");
+    return join(root, SPOOL_DIR);
 }
 /** One spool line, or null for a torn append from a killed dispatcher (dropped by design). */
 function parseSpoolLine(line) {
@@ -15,7 +18,7 @@ function parseSpoolLine(line) {
 }
 /** A pane spool file, or one a drain claimed (renamed away from the dispatcher) and has not finished. */
 export function isPaneSpoolFile(name) {
-    return name.startsWith("pane-") && (name.endsWith(".jsonl") || name.includes(".jsonl.claimed-"));
+    return name.startsWith(SPOOL_FILE_PREFIX) && (name.endsWith(SPOOL_FILE_SUFFIX) || name.includes(`${SPOOL_FILE_SUFFIX}.claimed-`));
 }
 /**
  * Drain every pane spool file: claim it by renaming it, so the dispatcher's next append starts a fresh
@@ -39,7 +42,7 @@ export async function drainSpool(root, onEvent) {
     for (const entry of entries.sort()) {
         if (!isPaneSpoolFile(entry))
             continue;
-        const claimed = entry.endsWith(".jsonl") ? `${entry}.claimed-${Date.now()}-${process.pid}` : entry;
+        const claimed = entry.endsWith(SPOOL_FILE_SUFFIX) ? `${entry}.claimed-${Date.now()}-${process.pid}` : entry;
         const filePath = join(dir, claimed);
         if (claimed !== entry)
             await rename(join(dir, entry), filePath);

package/dist/mcp.d.ts

@@ -1,8 +1,8 @@
 /**
  * Heedvane's MCP connection: the one MCP entry the installer registers, named `heedvane`, pointing at
- * the organization's remote server (`<server>/api/mcp/<org>`), in the shapes the dashboard's setup writes
- * (apps/web/src/lib/agent/mcp-setup.ts `HEEDVANE_MCP_SERVER_NAME`). The agent signs in to it in the
- * browser on first use.
+ * the organization's remote server (`<server>/api/mcp/<org>`). Remote entries take the shapes the dashboard's
+ * setup writes (apps/web/src/lib/agent/mcp-setup.ts `HEEDVANE_MCP_SERVER_NAME`); Claude Desktop's mcp-remote bridge
+ * (`bridgeEntry`, with the installing Node's folder) is this CLI's own. The agent signs in in the browser on first use.
  *
  * Identity: uninstall and detection recognize an entry by its name and shape together, never by a name
  * alone: today's connection, the local helper earlier versions registered (`npx -y heedvane mcp`, under any
@@ -10,18 +10,37 @@
  */
 /** The entry's name in every agent's MCP config. */
 export declare const HEEDVANE_SERVER_NAME = "heedvane";
+/** Why metrics only registers no MCP connection: its tools send questions and repository names to Heedvane. */
+export declare const MCP_OFF_METRICS_ONLY = "Heedvane's MCP connection: off under Metrics only, since its tools send your questions and repository names to Heedvane";
 /** What to do when no organization is known, so no MCP connection can be registered. */
-export declare const MCP_NEEDS_ORG = "Heedvane's MCP connection needs your organization: run the connect command from your dashboard's Settings (it has --org), or npx heedvane connect --org <id>";
+export declare const MCP_NEEDS_ORG = "Heedvane's MCP connection needs your organization: run the connect command from your dashboard's Settings (it has --org), or npx -y heedvane connect --org <id>";
+/** How to add the organization: `setup` cannot, since it compiles heed.yaml as it is. */
+export declare const ORG_REMEDIATION = "run the connect command from your dashboard's Settings, or npx -y heedvane connect --org <organization id>";
 /** Uninstall/detection marker for inline dispatcher snippets (hooks configs). */
 export declare const SNIPPET_MARKER = "heedvane-agent-hook-form";
 /** The connection's URL for an organization, as the dashboard builds it (`buildHeedvaneMcpUrl`). */
 export declare function connectorUrl(server: string, org: string): string;
+/**
+ * The entry as drift checks compare it: a bridge's installing-Node folder is left out, since the launcher finds a Node
+ * without it, and connect run from another Node is no change to the connection.
+ */
+export declare function comparableEntry(entry: unknown): unknown;
+/** The variable a software factory holds its organization API key in; the dashboard's factory commands use it. */
+export declare const ORG_KEY_ENV = "HEEDVANE_ORG_KEY";
+/** The software-factory connection entry for this agent; undefined where it keeps the browser sign-in. */
+export declare function keyConnectorEntry(clientId: string, url: string): Record<string, unknown> | undefined;
 /** The connection entry for this agent, or undefined when the installer does not register it there. `nodeDir` (POSIX only) is the installing Node's folder, for an entry that runs a local bridge. */
 export declare function connectorEntry(clientId: string, url: string, nodeDir?: string): Record<string, unknown> | undefined;
+/** The organization an entry's Heedvane MCP URL names at `server`, if it points there. */
+export declare function connectorOrganization(entry: unknown, server: string): string | undefined;
+/** The strings an entry names a server URL with: any agent's URL field, or a bridge's arguments. */
+export declare function entryUrls(entry: unknown): string[];
 /** Is this today's connection entry? Its name and a Heedvane MCP URL both have to match. */
 export declare function isConnectorEntry(name: string, entry: unknown): boolean;
 /** Is this an entry an earlier version wrote: the local helper under any name, or the connection under its earlier name? */
 export declare function isLegacyEntry(name: string, entry: unknown): boolean;
+/** Does this entry run the local helper an earlier version registered, under any name? */
+export declare function isHelperEntry(_name: string, entry: unknown): boolean;
 /** Is this server entry Heedvane's, today's or an earlier version's? Used by uninstall, detection and doctor. */
 export declare function isHeedvaneEntry(name: string, entry: unknown): boolean;
 /** Names of the entries `match` accepts in a parsed config's MCP containers, as `container::name`. */