heedvane 0.3.3 → 0.3.4

package/dist/listener/background.d.ts

@@ -1,8 +1,52 @@
+import { type Endpoint } from "./endpoint.js";
+/** `listener start`'s exit code when the port stays taken: the Heedvane listener there did not stop when asked. */
+export declare const PORT_TAKEN_EXIT = 3;
 /** Where a background listener writes what it prints. */
 export declare function listenerLogPath(root: string): string;
+/** What {@link ensureListener} found and did. */
+export type ListenerOutcome = 
+/** No endpoint.env: Heedvane's hooks were never set up on this machine, so no listener is wanted. */
+{
+    kind: "not set up";
+}
+/** One of this version already ran with the current settings. */
+ | {
+    kind: "running";
+}
+/** None ran, an older version ran, or this version on other settings: one with the current settings answers now. */
+ | {
+    kind: "started" | "replaced" | "restarted";
+}
+/** A newer version runs and was kept, as this CLI is the older; `earlierSettings` when it runs other settings than these. */
+ | {
+    kind: "newer";
+    version: string;
+    earlierSettings: boolean;
+}
+/** The one at the port did not stop when asked (0.2.0 and earlier have no way to be asked). */
+ | {
+    kind: "did not stop";
+    port: number;
+}
+/** None answers with the current settings; why, or the listener's log says why. */
+ | {
+    kind: "did not start";
+    log: string;
+    why?: string;
+};
 /**
- * Starts `listener start` as a process that outlives this one, unless a listener already answers.
- * True once the listener answers its probe; false when it did not within 5 s (its log says why).
- * It stops at logout or restart; the hooks then start it again on the fly (src/dispatchers/posix.ts).
+ * The one owner of which listener runs: it compares what the running listener reports about itself (its version and
+ * the hash of its settings) with the settings a listener would run now, and acts on {@link listenerVerdict}. A listener
+ * to start, replace or restart is started in the background with this package's own CLI (`listener start`, which takes
+ * the port over from the old one), and this waits until a listener it can keep answers, whatever version won the port.
+ * Every command that changes heed.yaml or the sign-in, `listener restart` and `run` call it last.
  */
-export declare function startListenerInBackground(home: string, cliPath: string, env: NodeJS.ProcessEnv): Promise<boolean>;
+export declare function ensureListener(home: string, cliPath: string, env: NodeJS.ProcessEnv): Promise<ListenerOutcome>;
+/** What stops a listener that does not stop when asked, ready to paste. */
+export declare function stopCommand(port: number): string;
+/**
+ * Asks the listener at `endpoint` to stop (POST /shutdown) and waits until its process has exited (until it no longer
+ * answers, for one older than 0.3.4, which does not name its pid), as long as its last reports may take to send.
+ * "no stop route" for a listener from 0.2.0 or earlier, which runs until logout or restart.
+ */
+export declare function stopRunningListener(endpoint: Endpoint, reason?: string): Promise<"stopped" | "no stop route" | "still running">;

package/dist/listener/background.js

@@ -1,36 +1,170 @@
 import { spawn } from "node:child_process";
-import { closeSync, openSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
-import { ensureEndpoint, pingListener } from "./endpoint.js";
-/** How long a freshly started listener gets to answer before the start counts as failed. */
-const START_WAIT_MS = 5_000;
-const START_POLL_MS = 250;
+import { errorMessage } from "../guards.js";
+import { START_LOCK, START_LOCK_HOLDER, START_LOCK_MINUTES } from "../hook-fallback.js";
+import { listenerVerdict, pingListener, probeListener, readEndpoint } from "./endpoint.js";
+import { SEND_TIMEOUT_MS } from "./forward.js";
+import { askToStop, isAlive, settingsToRun } from "./serve.js";
+/** How long a listener started in the background gets to answer with the current settings. */
+const START_WAIT_MS = 10_000;
+const START_POLL_MS = 100;
+/** How long a listener asked to stop gets to exit: its last flush may be sending reports. */
+const STOP_WAIT_MS = SEND_TIMEOUT_MS + 2_000;
+const STOP_POLL_MS = 100;
+/** `listener start`'s exit code when the port stays taken: the Heedvane listener there did not stop when asked. */
+export const PORT_TAKEN_EXIT = 3;
 /** Where a background listener writes what it prints. */
 export function listenerLogPath(root) {
     return join(root, "listener.log");
 }
 /**
- * Starts `listener start` as a process that outlives this one, unless a listener already answers.
- * True once the listener answers its probe; false when it did not within 5 s (its log says why).
- * It stops at logout or restart; the hooks then start it again on the fly (src/dispatchers/posix.ts).
+ * The one owner of which listener runs: it compares what the running listener reports about itself (its version and
+ * the hash of its settings) with the settings a listener would run now, and acts on {@link listenerVerdict}. A listener
+ * to start, replace or restart is started in the background with this package's own CLI (`listener start`, which takes
+ * the port over from the old one), and this waits until a listener it can keep answers, whatever version won the port.
+ * Every command that changes heed.yaml or the sign-in, `listener restart` and `run` call it last.
  */
-export async function startListenerInBackground(home, cliPath, env) {
+export async function ensureListener(home, cliPath, env) {
     const root = join(home, ".heed");
-    const endpoint = await ensureEndpoint(root);
-    if (await pingListener(endpoint))
+    const endpoint = await readEndpoint(root).catch(() => null);
+    if (endpoint === null)
+        return { kind: "not set up" };
+    let unusable;
+    const current = await settingsToRun(root).then((settings) => settings.hash, (err) => {
+        unusable = errorMessage(err);
+        return null;
+    });
+    const found = await probeListener(endpoint);
+    const verdict = listenerVerdict(found, current);
+    if (verdict === "newer")
+        return newer(found, current);
+    if (verdict === "keep")
+        return { kind: "running" };
+    // No heed.yaml parses and no copy of the last good one: a listener started now would end at once (its log says why).
+    if (current === null)
+        return { kind: "did not start", log: listenerLogPath(root), why: unusable };
+    // The start's exit code once it ended (null when it could not be spawned or was killed); unset while another start
+    // (the hooks' or another command's) holds the start lock: that one brings up the listener this waits for.
+    const start = {};
+    const began = Date.now();
+    const spawnOnceLockIsTaken = () => {
+        if (start.spawned !== undefined || !tookStartLock(root, Date.now() - began > LOCK_WAIT_MS))
+            return;
+        start.spawned = true;
+        const child = spawnBackgroundListener(home, cliPath, env).on("error", () => (start.ended = null)).on("exit", (code) => (start.ended = code));
+        writeFileSync(join(root, START_LOCK, START_LOCK_HOLDER), String(child.pid ?? ""));
+    };
+    spawnOnceLockIsTaken();
+    // Until a deadline, not a count of pauses: a probe of a port that never answers takes its whole timeout.
+    for (let until = Date.now() + START_WAIT_MS, ended = false; !ended && Date.now() < until; await delay(START_POLL_MS)) {
+        ended = start.ended !== undefined; // read before the probe: one made after the start ended has the last word
+        // endpoint.env as the start leaves it: one that finds another program on the port moves to a free one.
+        const running = await probeListener((await readEndpoint(root).catch(() => null)) ?? endpoint);
+        const now = listenerVerdict(running, current);
+        if (now === "newer")
+            return newer(running, current);
+        if (now === "keep")
+            return { kind: STARTED[verdict] };
+        spawnOnceLockIsTaken(); // after the probe: a lock freed by a start that listens is not taken for a second one
+    }
+    // A start that ended without a listener to keep leaves the lock to the next one (one that listens removes it).
+    if (start.ended !== undefined)
+        rmSync(join(root, START_LOCK), { recursive: true, force: true });
+    // Only the start knows whether the port stayed taken or it ended before taking it (its log says why).
+    if (start.ended === PORT_TAKEN_EXIT)
+        return { kind: "did not stop", port: endpoint.port };
+    return { kind: "did not start", log: listenerLogPath(root) };
+}
+/** The pid of the start that holds the lock: NaN until it is written, and once the lock is gone. */
+function startLockHolder(lock) {
+    try {
+        return Number.parseInt(readFileSync(join(lock, START_LOCK_HOLDER), "utf8"), 10);
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        return Number.NaN;
+    }
+}
+/**
+ * How long a command waits for a start that holds the lock before it starts one itself: a hook's `npx` that cannot reach
+ * the registry holds it for a minute and more. A second start is safe: it re-reads endpoint.env, and a listener
+ * endpoint.env does not name steps down.
+ */
+const LOCK_WAIT_MS = 2_500;
+/**
+ * Takes the start lock (src/hook-fallback.ts START_LOCK), so only one start runs at a time: false while another holds
+ * it. It is taken over when the start named in it has ended, when it is older than a start may take, or `waitedLong`.
+ */
+function tookStartLock(root, waitedLong) {
+    const lock = join(root, START_LOCK);
+    const holder = startLockHolder(lock);
+    const stale = Date.now() - (statSync(lock, { throwIfNoEntry: false })?.mtimeMs ?? Date.now()) > START_LOCK_MINUTES * 60_000;
+    if (stale || waitedLong || (Number.isInteger(holder) && !isAlive(holder)))
+        rmSync(lock, { recursive: true, force: true });
+    try {
+        mkdirSync(lock);
         return true;
-    const log = openSync(listenerLogPath(root), "a", 0o600);
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+        return false; // another start holds it
+    }
+}
+const STARTED = { start: "started", replace: "replaced", restart: "restarted" };
+/** The newer version that runs, kept, on the settings a listener would run now (`current`) or on earlier ones. */
+function newer(running, current) {
+    // shortcut: a newer listener's settings hash is compared as this version computes it; if a later version hashes other bytes, give the probe a hash version.
+    return { kind: "newer", version: running?.version ?? "", earlierSettings: current !== null && running?.settings !== current };
+}
+/** What stops a listener that does not stop when asked, ready to paste. */
+export function stopCommand(port) {
+    return `kill $(lsof -t -iTCP:${port} -sTCP:LISTEN)`;
+}
+/**
+ * Spawns `listener start` as a process that outlives this one, its output in the listener's log, without waiting for
+ * it to answer. A spawn that fails (no node, no permission) is an `error` event on the returned process, never an
+ * error that ends the caller.
+ */
+function spawnBackgroundListener(home, cliPath, env) {
+    const log = openLog(listenerLogPath(join(home, ".heed")));
     try {
-        spawn(process.execPath, [cliPath, "listener", "start"], { detached: true, stdio: ["ignore", log, log], env: { ...env, HEED_HOME: home } }).unref();
+        // This process's own Node flags (none under npx), so a listener started from source runs as this process does.
+        const child = spawn(process.execPath, [...process.execArgv, cliPath, "listener", "start"], { detached: true, windowsHide: true, stdio: ["ignore", log, log], env: { ...env, HEED_HOME: home } });
+        child.on("error", () => undefined); // reported by the listener not answering (ensureListener)
+        child.unref();
+        return child;
     }
     finally {
-        closeSync(log);
+        if (log !== "ignore")
+            closeSync(log);
+    }
+}
+/** The listener's log, opened to append; "ignore" when it cannot be (a folder in its place, a full disk): the listener runs without it. */
+function openLog(path) {
+    try {
+        return openSync(path, "a", 0o600);
+    }
+    catch {
+        return "ignore";
     }
-    for (let waited = 0; waited < START_WAIT_MS; waited += START_POLL_MS) {
-        await delay(START_POLL_MS);
-        if (await pingListener(endpoint))
-            return true;
+}
+/**
+ * Asks the listener at `endpoint` to stop (POST /shutdown) and waits until its process has exited (until it no longer
+ * answers, for one older than 0.3.4, which does not name its pid), as long as its last reports may take to send.
+ * "no stop route" for a listener from 0.2.0 or earlier, which runs until logout or restart.
+ */
+export async function stopRunningListener(endpoint, reason = "asked to stop") {
+    const { status, pid } = await askToStop(endpoint, reason);
+    if (status === 404)
+        return "no stop route";
+    const gone = pid !== null ? async () => !isAlive(pid) : async () => !(await pingListener(endpoint));
+    for (const until = Date.now() + STOP_WAIT_MS; Date.now() < until; await delay(STOP_POLL_MS)) {
+        if (await gone())
+            return "stopped";
     }
-    return false;
+    return "still running";
 }

package/dist/listener/endpoint.d.ts

@@ -12,15 +12,38 @@ export declare function endpointPath(root: string): string;
  * `token` -> "") so callers can produce a precise remediation error.
  */
 export declare function readEndpoint(root: string): Promise<Endpoint | null>;
-/** Atomically write `root/endpoint.env` (mode 0600) with the port and token lines. */
+/** Atomically write `root/endpoint.env` (mode 0600) with the port, token and proof lines. */
 export declare function writeEndpoint(root: string, endpoint: Endpoint): Promise<void>;
+/** A loopback port free right now (the OS picks it). */
+export declare function freeLoopbackPort(): Promise<number>;
 /**
  * The listener endpoint, issued once: an existing endpoint.env with a port and token is kept
  * (dispatchers already point at it); otherwise a free loopback port and a fresh 256-bit token are written.
  */
 export declare function ensureEndpoint(root: string): Promise<Endpoint>;
+/** This package's version, which the listener names in its probe answer so an older one is found and replaced. */
+export declare const HEEDVANE_VERSION: string;
 /**
- * Whether a listener answers at `endpoint` within 750 ms. The probe is a GET, which the listener refuses
- * with 405 before it reads a token or records anything, so probing never adds an event.
+ * The version of Heedvane's listener at `endpoint` ("" for one from before 0.3.4, which names none), or null when it
+ * does not answer within 750 ms. The probe is a GET, which the listener refuses with 405 and {@link PROBE_REFUSAL}
+ * before it reads a token or records anything, so probing never adds an event, and another program on the port,
+ * which answers otherwise, is never taken for it (nor sent its token).
  */
+export declare function listenerVersion(endpoint: Endpoint): Promise<string | null>;
+/** What a running listener says about itself in its probe answer: its version, and the hash of the settings it runs (0.3.4 on). */
+export interface RunningListener {
+    version: string;
+    settings?: string;
+}
+/** What to do about the listener at the port, given what it reports and the settings a listener would run now. */
+export type ListenerVerdict = "start" | "replace" | "restart" | "keep" | "newer";
+/**
+ * The one decision of which listener should run. Nothing answers: start one. An older version: replace it. A newer
+ * one: keep it (this CLI is the older). The same version on other settings: restart it. Else keep it. `current` is
+ * null when no settings parse at all: a running listener is then kept, so a bad heed.yaml never stops the checks.
+ */
+export declare function listenerVerdict(running: RunningListener | null, current: string | null): ListenerVerdict;
+/** The listener's probe answer: its version (see {@link listenerVersion}) and the settings it runs (0.3.4 on). */
+export declare function probeListener(endpoint: Endpoint): Promise<RunningListener | null>;
+/** Whether Heedvane's listener, of any version, answers at `endpoint` (see {@link listenerVersion}). */
 export declare function pingListener(endpoint: Endpoint): Promise<boolean>;

package/dist/listener/endpoint.js

@@ -1,4 +1,6 @@
 import { randomBytes } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { listenerProof, PROBE_REFUSAL, PROOF_HEADER, PROOF_KEY } from "../hook-fallback.js";
 import { chmod, mkdir, open, readFile, rename } from "node:fs/promises";
 import { createServer } from "node:net";
 import { basename, dirname, join } from "node:path";
@@ -80,13 +82,13 @@ async function atomicWriteFile(filePath, data, mode) {
         throw err;
     }
 }
-/** Atomically write `root/endpoint.env` (mode 0600) with the port and token lines. */
+/** Atomically write `root/endpoint.env` (mode 0600) with the port, token and proof lines. */
 export async function writeEndpoint(root, endpoint) {
-    const content = `${PORT_KEY}=${endpoint.port}\n${TOKEN_KEY}=${endpoint.token}\n`;
+    const content = `${PORT_KEY}=${endpoint.port}\n${TOKEN_KEY}=${endpoint.token}\n${PROOF_KEY}=${await listenerProof(endpoint.token)}\n`;
     await atomicWriteFile(endpointPath(root), content, 0o600);
 }
 /** A loopback port free right now (the OS picks it). */
-async function freeLoopbackPort() {
+export async function freeLoopbackPort() {
     const server = createServer();
     await new Promise((resolve, reject) => {
         server.once("error", reject);
@@ -104,22 +106,65 @@ async function freeLoopbackPort() {
  */
 export async function ensureEndpoint(root) {
     const existing = await readEndpoint(root);
-    if (existing !== null && existing.port > 0 && existing.token)
+    if (existing !== null && existing.port > 0 && existing.token) {
+        // One written before the proof (0.3.3 and earlier) gets its line, which the hooks read.
+        if (!(await readFile(endpointPath(root), "utf8")).includes(`${PROOF_KEY}=`))
+            await writeEndpoint(root, existing);
         return existing;
+    }
     const endpoint = { port: await freeLoopbackPort(), token: randomBytes(32).toString("hex") };
     await writeEndpoint(root, endpoint);
     return endpoint;
 }
+/** This package's version, which the listener names in its probe answer so an older one is found and replaced. */
+export const HEEDVANE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
 /**
- * Whether a listener answers at `endpoint` within 750 ms. The probe is a GET, which the listener refuses
- * with 405 before it reads a token or records anything, so probing never adds an event.
+ * The version of Heedvane's listener at `endpoint` ("" for one from before 0.3.4, which names none), or null when it
+ * does not answer within 750 ms. The probe is a GET, which the listener refuses with 405 and {@link PROBE_REFUSAL}
+ * before it reads a token or records anything, so probing never adds an event, and another program on the port,
+ * which answers otherwise, is never taken for it (nor sent its token).
  */
-export async function pingListener(endpoint) {
+export async function listenerVersion(endpoint) {
+    return (await probeListener(endpoint))?.version ?? null;
+}
+/**
+ * The one decision of which listener should run. Nothing answers: start one. An older version: replace it. A newer
+ * one: keep it (this CLI is the older). The same version on other settings: restart it. Else keep it. `current` is
+ * null when no settings parse at all: a running listener is then kept, so a bad heed.yaml never stops the checks.
+ */
+export function listenerVerdict(running, current) {
+    if (running === null)
+        return "start";
+    // Whatever its version: a listener started now would have nothing to run.
+    if (current === null)
+        return "keep";
+    // shortcut: digit-wise compare, so a prerelease (0.4.0-beta.1) counts as newer than its release; use semver once prereleases ship.
+    const order = running.version.localeCompare(HEEDVANE_VERSION, "en", { numeric: true });
+    if (order < 0)
+        return "replace";
+    if (order > 0)
+        return "newer";
+    return current !== null && running.settings !== current ? "restart" : "keep";
+}
+/** The listener's probe answer: its version (see {@link listenerVersion}) and the settings it runs (0.3.4 on). */
+export async function probeListener(endpoint) {
     try {
-        await fetch(`http://127.0.0.1:${endpoint.port}/hook/claude`, { signal: AbortSignal.timeout(750) });
-        return true;
+        const answer = await fetch(`http://127.0.0.1:${endpoint.port}/hook/claude`, { signal: AbortSignal.timeout(750) });
+        const body = (answer.status === 405 ? await answer.json() : null);
+        if (body?.error !== PROBE_REFUSAL)
+            return null;
+        const settings = typeof body.settings === "string" ? body.settings : undefined;
+        // One that names its settings (0.3.4 on) proves it is this machine's listener; an older one cannot, and is replaced
+        // (the hooks never take its answers: src/guard.ts).
+        if (settings !== undefined && answer.headers.get(PROOF_HEADER) !== (await listenerProof(endpoint.token)))
+            return null;
+        return { version: typeof body.version === "string" ? body.version : "", settings };
     }
     catch {
-        return false;
+        return null; // nothing answers, or not in the listener's JSON: not the listener
     }
 }
+/** Whether Heedvane's listener, of any version, answers at `endpoint` (see {@link listenerVersion}). */
+export async function pingListener(endpoint) {
+    return (await listenerVersion(endpoint)) !== null;
+}

package/dist/listener/forward.d.ts

@@ -3,6 +3,7 @@ import { type Backend } from "../backend/client.js";
 export declare const QUEUE_MAX = 5000;
 /** Held while the route refuses this machine outright (403) or does not exist (404): nothing will change soon. */
 export declare const REFUSED_QUEUE_MAX = 500;
+export declare const SEND_TIMEOUT_MS = 10000;
 /** The dead-letter file turns over at this size (the old one is kept once as `.1`), so a permanent refusal cannot fill the disk. */
 export declare const DEAD_LETTER_MAX_BYTES: number;
 /** How often an item refused on its own is retried before it is dead-lettered. */
@@ -31,6 +32,11 @@ export interface OutboxContext {
     log: (message: string) => void;
     /** The clock the backoff reads (tests move it). */
     now?: () => number;
+    /**
+     * Resolves once the outbox file is this outbox's alone: the listener it replaced has exited. Until then items are
+     * kept in memory and sent at once, and the file is read and written after (the default: free now).
+     */
+    fileFree?: Promise<void>;
 }
 /** An outbox for one route, loaded with whatever an earlier listener left unsent. Without a backend it only queues. */
-export declare function outbox<T>(route: OutboxRoute, { root, backend, log, now }: OutboxContext): Promise<Outbox<T>>;
+export declare function outbox<T>(route: OutboxRoute, { root, backend, log, now, fileFree }: OutboxContext): Promise<Outbox<T>>;

package/dist/listener/forward.js

@@ -34,7 +34,7 @@ const SHED_FRACTION = 0.1;
 /** Kept batches wait this long before the next try, doubling per kept flush up to {@link BACKOFF_MAX_MS}. */
 const BACKOFF_BASE_MS = 5_000;
 const BACKOFF_MAX_MS = 5 * 60_000;
-const SEND_TIMEOUT_MS = 10_000;
+export const SEND_TIMEOUT_MS = 10_000;
 /** The dead-letter file turns over at this size (the old one is kept once as `.1`), so a permanent refusal cannot fill the disk. */
 export const DEAD_LETTER_MAX_BYTES = 50 * 1024 * 1024;
 /** How often an item refused on its own is retried before it is dead-lettered. */
@@ -44,34 +44,61 @@ const KEEP_STATUSES = new Set([401, 403, 404, 408, 429]);
 /** Steering's delivery reports: at most 100 per post and 256 KiB per body (a little headroom for the wrapper). */
 export const DELIVERIES_ROUTE = { name: "deliveries", path: "/api/agent/steering/deliveries", key: "deliveries", maxItems: 100, maxBytes: 250 * 1024 };
 /** An outbox for one route, loaded with whatever an earlier listener left unsent. Without a backend it only queues. */
-export async function outbox(route, { root, backend, log, now = Date.now }) {
+export async function outbox(route, { root, backend, log, now = Date.now, fileFree }) {
     const dir = spoolDir(root);
     const file = join(dir, `${route.name}.outbox.jsonl`);
     await mkdir(dir, { recursive: true, mode: 0o700 });
-    const { entries: queue, endsCleanly } = await readOutbox(file);
+    const queue = [];
+    const loaded = async () => {
+        const { entries, endsCleanly } = await readOutbox(file);
+        // A crash mid-append left a line with no newline: the next append would glue onto it and be lost with it.
+        if (!endsCleanly)
+            await writeFileAtomic(file, entries.map((entry) => `${JSON.stringify(entry)}\n`).join(""), { mode: 0o600 });
+        queue.unshift(...entries); // older than anything added meanwhile
+    };
     const refusals = new Map();
-    // File writes in order, so a rewrite never races an append.
-    let writes = Promise.resolve();
+    // File writes in order, so a rewrite never races an append; the first is the load.
+    const load = fileFree === undefined ? loaded() : fileFree.then(loaded);
+    if (fileFree === undefined)
+        await load;
+    let fileIsFree = fileFree === undefined;
+    // A file the load after a handover could not read is never written: what the replaced listener left waits for the next start.
+    let unreadable = false;
+    let writes = load.then(() => void (fileIsFree = true), (err) => {
+        unreadable = true;
+        log(`[heedvane] could not open the steering delivery outbox after the handover (${errorMessage(err)}); reports are sent from memory, and the file is left for the next start`);
+    });
     // One failed write (a full disk, a permission) fails its own caller only; the next write still runs.
     const persist = (write) => {
-        const next = writes.then(write);
+        const next = writes.then(() => (unreadable ? undefined : write()));
         writes = next.catch(() => undefined);
         return next;
     };
-    const rewrite = () => persist(() => writeFileAtomic(file, queue.map((entry) => `${JSON.stringify(entry)}\n`).join(""), { mode: 0o600 }));
-    // A crash mid-append left a line with no newline: the next append would glue onto it and be lost with it.
-    if (!endsCleanly)
-        await rewrite();
+    // Until the file is free its writes wait behind the load, and nothing waits on them: a send goes out at once, and a failed write is logged.
+    const unlessWaiting = (written) => {
+        if (fileIsFree)
+            return written;
+        void written.catch((err) => {
+            log(`[heedvane] ${route.path}: could not update the outbox: ${errorMessage(err)}`);
+            return undefined; // logged: the items were sent from memory, or wait there for the next flush
+        });
+        return Promise.resolve();
+    };
+    const rewrite = () => unlessWaiting(persist(() => writeFileAtomic(file, queue.map((entry) => `${JSON.stringify(entry)}\n`).join(""), { mode: 0o600 })));
+    // The dead-letter file is not the outbox: its writes never wait behind the outbox's load, and the caller waits for them.
+    let deadLetters = Promise.resolve();
     const deadLetter = (entries, status, json) => {
         log(`[heedvane] dead-lettered ${entries.length} item(s) ${route.path} (${status ?? "no answer"}): ${JSON.stringify(json).slice(0, 500)}`);
         const lines = entries.map((entry) => `${JSON.stringify({ deadAt: new Date().toISOString(), status, answer: json, ...entry })}\n`).join("");
         const deadFile = join(dir, `${route.name}.dead-letter.jsonl`);
-        return persist(async () => {
+        const next = deadLetters.then(async () => {
             const size = await stat(deadFile).then((info) => info.size, () => 0);
             if (size >= DEAD_LETTER_MAX_BYTES)
                 await rename(deadFile, `${deadFile}.1`);
             await appendFile(deadFile, lines, { mode: 0o600 });
         });
+        deadLetters = next.catch(() => undefined);
+        return next;
     };
     // A streak of kept flushes: back off, say so once, and hold fewer items while the route refuses outright.
     const kept = { streak: 0, until: 0, status: null, shed: 0 };
@@ -94,7 +121,8 @@ export async function outbox(route, { root, backend, log, now = Date.now }) {
             await (shedding ??= shedOldest().finally(() => (shedding = null)));
         const entry = { id: isRecord(item) && typeof item["id"] === "string" ? item["id"] : randomUUID(), item, identity };
         queue.push(entry);
-        return persist(() => appendFile(file, `${JSON.stringify(entry)}\n`, { mode: 0o600 }));
+        // Before the file is free the item is sent from memory at once; its line is written once the file is.
+        return unlessWaiting(persist(() => appendFile(file, `${JSON.stringify(entry)}\n`, { mode: 0o600 })));
     };
     const keptFlush = (status) => {
         kept.streak += 1;

package/dist/listener/serve.d.ts

@@ -1,2 +1,39 @@
+import { type HeedvaneConfig } from "../heed-file.js";
+import { type Endpoint } from "./endpoint.js";
 import { type StartedListener } from "./server.js";
+/** 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 declare class ListenerAlreadyRuns extends Error {
+    readonly version: string;
+    constructor(version: string, newer: boolean);
+}
+/**
+ * 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 declare function serveHooks(home: string, out: (line: string) => void): Promise<StartedListener>;
+/** Asks the listener at `endpoint` to stop: its answer's status (null without one) and the pid it names (0.3.4 on). */
+export declare function askToStop(endpoint: Endpoint, reason: string): Promise<{
+    status: number | null;
+    pid: number | null;
+}>;
+/** Whether process `pid` still runs. */
+export declare function isAlive(pid: number): boolean;
+/** The settings a listener started now runs, read once: heed.yaml's text, its `heedvane` section and their hash. */
+export interface ListenerSettings {
+    config: HeedvaneConfig;
+    text: string;
+    /** Hash of the text and the sign-in, which the listener names in its probe answer. */
+    hash: string;
+    /** Why heed.yaml cannot be used (it cannot be read, or does not parse), when these are the last good settings instead. */
+    unparseable?: string;
+}
+/** Where a listener keeps the heed.yaml it last started with, which it runs while heed.yaml does not parse. */
+export declare function lastGoodPath(root: string): string;
+/**
+ * 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 declare function settingsToRun(root: string): Promise<ListenerSettings>;