heedvane 0.0.0-stage → 0.2.0

package/dist/listener/endpoint.js

@@ -0,0 +1,125 @@
+import { randomBytes } from "node:crypto";
+import { chmod, mkdir, open, readFile, rename } from "node:fs/promises";
+import { createServer } from "node:net";
+import { basename, dirname, join } from "node:path";
+import { unlinkOptional } from "../best-effort.js";
+/** The variable names the dispatcher scripts and the Hermes plugin read, sourced straight from endpoint.env. */
+const PORT_KEY = "HEED_AGENT_HOOK_PORT";
+const TOKEN_KEY = "HEED_AGENT_HOOK_TOKEN";
+/** Path of the endpoint file: `root/endpoint.env`. */
+export function endpointPath(root) {
+    return join(root, "endpoint.env");
+}
+/** Parse KEY=VALUE lines (ignores blanks, `#` comments, and matching quotes). */
+function parseEnvFile(content) {
+    const values = {};
+    for (const rawLine of content.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        let value = line.slice(eq + 1).trim();
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        values[key] = value;
+    }
+    return values;
+}
+/**
+ * Read `{port, token}` from `root/endpoint.env`.
+ * Returns null when the file does not exist. If the file exists but is
+ * missing/incoherent, the corresponding field degrades (`port` -> 0,
+ * `token` -> "") so callers can produce a precise remediation error.
+ */
+export async function readEndpoint(root) {
+    let content;
+    try {
+        content = await readFile(endpointPath(root), "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+    const values = parseEnvFile(content);
+    const port = Number.parseInt(values[PORT_KEY] ?? "", 10);
+    return {
+        port: Number.isInteger(port) && port >= 0 && port <= 65535 ? port : 0,
+        token: values[TOKEN_KEY] ?? "",
+    };
+}
+/**
+ * Atomic write: temp file in the same directory (created 0600, fsync'd,
+ * chmod'd to defeat umask), then rename over the target. Same contract as
+ * write-file-atomic, kept stdlib-only so the listener has zero deps.
+ */
+async function atomicWriteFile(filePath, data, mode) {
+    const dir = dirname(filePath);
+    await mkdir(dir, { recursive: true });
+    const tmp = join(dir, `.${basename(filePath)}.${process.pid}.${Date.now().toString(36)}.tmp`);
+    const handle = await open(tmp, "w", mode);
+    try {
+        await handle.writeFile(data, "utf8");
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    try {
+        await chmod(tmp, mode);
+        await rename(tmp, filePath);
+    }
+    catch (err) {
+        await unlinkOptional(tmp);
+        throw err;
+    }
+}
+/** Atomically write `root/endpoint.env` (mode 0600) with the port and token lines. */
+export async function writeEndpoint(root, endpoint) {
+    const content = `${PORT_KEY}=${endpoint.port}\n${TOKEN_KEY}=${endpoint.token}\n`;
+    await atomicWriteFile(endpointPath(root), content, 0o600);
+}
+/** A loopback port free right now (the OS picks it). */
+async function freeLoopbackPort() {
+    const server = createServer();
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", resolve);
+    });
+    const address = server.address();
+    await new Promise((resolve) => server.close(() => resolve()));
+    if (address === null || typeof address !== "object")
+        throw new Error("could not reserve a loopback port");
+    return address.port;
+}
+/**
+ * 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 async function ensureEndpoint(root) {
+    const existing = await readEndpoint(root);
+    if (existing !== null && existing.port > 0 && existing.token)
+        return existing;
+    const endpoint = { port: await freeLoopbackPort(), token: randomBytes(32).toString("hex") };
+    await writeEndpoint(root, endpoint);
+    return endpoint;
+}
+/**
+ * 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.
+ */
+export async function pingListener(endpoint) {
+    try {
+        await fetch(`http://127.0.0.1:${endpoint.port}/hook/claude`, { signal: AbortSignal.timeout(750) });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/listener/forward.d.ts

@@ -0,0 +1,36 @@
+import { type Backend } from "../backend/client.js";
+/** Held while Heedvane is unreachable; past this, the oldest {@link SHED_FRACTION} moves to the dead-letter file in one rewrite. */
+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;
+/** 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. */
+export declare const MAX_REFUSALS = 3;
+export interface Outbox<T> {
+    /** Queue an item; it is on disk when this resolves. It is stamped with the current sign-in, or with `identity` when the caller read it earlier (a replayed event belongs to the sign-in the replay began under). */
+    add: (item: T, identity?: string | null) => Promise<void>;
+    /** Send everything queued; what could not be sent stays queued for the next flush. One at a time. */
+    flush: () => Promise<void>;
+}
+export interface OutboxRoute {
+    /** The outbox's file name stem under `<root>/spool`. */
+    name: string;
+    path: string;
+    /** The body's array key, `{ [key]: items }`, also the first element of a 400's issue paths. */
+    key: string;
+    maxItems: number;
+    maxBytes: number;
+}
+/** Steering's delivery reports: at most 100 per post and 256 KiB per body (a little headroom for the wrapper). */
+export declare const DELIVERIES_ROUTE: OutboxRoute;
+export interface OutboxContext {
+    /** The heed root; the outbox lives in its spool directory. */
+    root: string;
+    backend: Backend | null;
+    log: (message: string) => void;
+    /** The clock the backoff reads (tests move it). */
+    now?: () => number;
+}
+/** 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>>;

package/dist/listener/forward.js

@@ -0,0 +1,257 @@
+/**
+ * Steering's delivery reports (`POST /api/agent/steering/deliveries`) are queued to an on-disk outbox
+ * and sent in batches.
+ *
+ * Each item remembers the sign-in that queued it (`Backend.identity`) and is sent only under that same
+ * sign-in, read in the same snapshot as its bearer; after a login to another organization, or with items
+ * queued under no sign-in, those items move to the dead-letter file and nothing of theirs is sent. A failed disk write fails only its own caller; the next write runs.
+ *
+ * Nothing waits only in memory: an item is appended to an on-disk outbox (`<root>/spool/<name>.outbox.jsonl`)
+ * before `add` resolves and leaves it only once its send settled, so a crash or restart resends it
+ * (Heedvane drops the duplicate by `id`). One flush runs at a time, and settled items leave by id.
+ *
+ * No answer, 5xx, 401, 403, 404, 408 and 429 keep the batch: none is the items' fault. A kept batch is
+ * retried with exponential backoff (5 s doubling to 5 min), logged once per streak; past the cap
+ * (5,000 items, or 500 while the route answers 403 or 404) the oldest tenth moves to the dead-letter
+ * file in one write, so one item the server never accepts cannot hold the head forever and stop every
+ * later item, and a full outbox costs a hook one append. Any other 4xx splits the batch until the refused item is alone (a 400 that names its items
+ * drops just those); an item refused alone {@link MAX_REFUSALS} times moves to
+ * `<root>/spool/<name>.dead-letter.jsonl` with the answer, and everything behind it is delivered. The dead-letter file turns over at {@link DEAD_LETTER_MAX_BYTES}, keeping one older generation.
+ */
+import { randomUUID } from "node:crypto";
+import { appendFile, mkdir, readFile, rename, stat } from "node:fs/promises";
+import { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { callHeedvaneAs } from "../backend/client.js";
+import { errorMessage, isRecord } from "../guards.js";
+import { spoolDir } from "./spool.js";
+/** Held while Heedvane is unreachable; past this, the oldest {@link SHED_FRACTION} moves to the dead-letter file in one rewrite. */
+export const QUEUE_MAX = 5_000;
+/** Held while the route refuses this machine outright (403) or does not exist (404): nothing will change soon. */
+export const REFUSED_QUEUE_MAX = 500;
+/** How much of a full outbox is shed at once, so the rewrite happens once per many items, not per item. */
+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;
+/** 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. */
+export const MAX_REFUSALS = 3;
+/** Answers that say nothing about the items: the credential, the route or the server, so keep them. */
+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 }) {
+    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 refusals = new Map();
+    // File writes in order, so a rewrite never races an append.
+    let writes = Promise.resolve();
+    // 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);
+        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();
+    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 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 });
+        });
+    };
+    // 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 };
+    const cap = () => (kept.status === 403 || kept.status === 404 ? REFUSED_QUEUE_MAX : QUEUE_MAX);
+    // Oldest first: the head is the item most likely to be the one never accepted. Dead-lettered, not discarded.
+    const shedOldest = async () => {
+        const shed = queue.slice(0, Math.ceil(cap() * SHED_FRACTION));
+        if (kept.shed === 0)
+            log(`[heedvane] ${route.path}: the outbox is full${kept.status === null ? "" : ` (Heedvane answers ${kept.status})`}; the oldest items move to the dead-letter file`);
+        kept.shed += shed.length;
+        await deadLetter(shed, kept.status, { reason: "outbox full" });
+        removeFromQueue(new Set(shed.map((entry) => entry.id)));
+        await rewrite();
+    };
+    let shedding = null;
+    const add = async (item, stampedAs) => {
+        const identity = stampedAs !== undefined ? stampedAs : ((await backend?.identity()) ?? null);
+        // One shed at a time, shared by every add that finds the outbox full; the check and the push below share one tick.
+        if (queue.length >= cap())
+            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 }));
+    };
+    const keptFlush = (status) => {
+        kept.streak += 1;
+        kept.status = status ?? null;
+        kept.until = now() + Math.min(BACKOFF_BASE_MS * 2 ** (kept.streak - 1), BACKOFF_MAX_MS);
+        if (kept.streak === 1)
+            log(`[heedvane] ${route.path}: ${status === null || status === undefined ? "Heedvane did not answer" : `Heedvane answered ${status}`}; ${queue.length} item(s) wait, retried with backoff`);
+    };
+    const delivered = () => {
+        if (kept.streak > 0)
+            log(`[heedvane] ${route.path}: delivering again after ${kept.streak} kept flush(es)${kept.shed > 0 ? `; ${kept.shed} old item(s) were dead-lettered meanwhile` : ""}`);
+        Object.assign(kept, { streak: 0, until: 0, status: null, shed: 0 });
+    };
+    const flushOnce = async () => {
+        for (;;) {
+            // The identity is read around the bearer so a login to another organization in between sends nothing.
+            const { identity, bearer } = await backend.credential();
+            await deadLetterOtherSignIns(identity);
+            const eligible = queue.filter((entry) => entry.identity !== null && entry.identity === identity);
+            if (eligible.length === 0)
+                return;
+            const sender = { url: backend.url, bearer, route, refusals, deadLetter };
+            const sent = await sendBatch(sender, nextBatch(eligible, route));
+            const settled = new Set(sent.settled);
+            for (let index = queue.length - 1; index >= 0; index -= 1)
+                if (settled.has(queue[index].id))
+                    queue.splice(index, 1);
+            if (settled.size > 0)
+                await rewrite();
+            if (sent.kept)
+                return keptFlush(sent.status); // keep them, and everything after, for a later flush
+            delivered();
+        }
+    };
+    // Items another sign-in queued are never sent under this one: they move, whole, to the dead-letter file.
+    // With no sign-in at all (null) nothing moves, so a momentary read failure costs nothing.
+    const deadLetterOtherSignIns = async (identity) => {
+        if (identity === null)
+            return;
+        const foreign = queue.filter((entry) => entry.identity !== identity);
+        if (foreign.length === 0)
+            return;
+        await deadLetter(foreign, null, { reason: "queued under another Heedvane sign-in, or under none" });
+        removeFromQueue(new Set(foreign.map((entry) => entry.id)));
+        await rewrite();
+    };
+    // Removed only after the dead-letter append succeeded, so a full disk never loses an item.
+    const removeFromQueue = (gone) => {
+        for (let index = queue.length - 1; index >= 0; index -= 1)
+            if (gone.has(queue[index].id))
+                queue.splice(index, 1);
+    };
+    let flushing = null;
+    const flush = () => {
+        if (backend === null || now() < kept.until)
+            return Promise.resolve();
+        flushing ??= flushOnce().catch((err) => log(`[heedvane] ${route.path}: could not update the outbox after a send: ${errorMessage(err)}`)).finally(() => (flushing = null));
+        return flushing;
+    };
+    return { add, flush };
+}
+/** The outbox file's entries (a torn last line and duplicates are skipped), and whether the file ends on a line break. */
+async function readOutbox(file) {
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return { entries: [], endsCleanly: true };
+        throw err;
+    }
+    const seen = new Set();
+    const entries = text.split("\n").flatMap((line) => {
+        const entry = parseEntry(line);
+        if (entry === null || seen.has(entry.id))
+            return [];
+        seen.add(entry.id);
+        return [entry];
+    });
+    return { entries, endsCleanly: text === "" || text.endsWith("\n") };
+}
+function parseEntry(line) {
+    if (line.trim() === "")
+        return null;
+    try {
+        const value = JSON.parse(line);
+        return isRecord(value) && typeof value["id"] === "string" && "item" in value
+            ? { id: value["id"], item: value["item"], identity: typeof value["identity"] === "string" ? value["identity"] : null }
+            : null;
+    }
+    catch {
+        return null; // a torn append: the item was never acknowledged as queued
+    }
+}
+/** The queue's next batch: at most the route's items and bytes, but always at least one. */
+function nextBatch(queue, route) {
+    const batch = [];
+    let bytes = 0;
+    for (const entry of queue.slice(0, route.maxItems)) {
+        const size = Buffer.byteLength(JSON.stringify(entry.item));
+        if (batch.length > 0 && bytes + size > route.maxBytes)
+            break;
+        batch.push(entry);
+        bytes += size;
+    }
+    return batch;
+}
+const kept = (status) => ({ settled: [], kept: true, status });
+async function sendBatch(sender, entries) {
+    const { route } = sender;
+    const answer = await callHeedvaneAs(sender.url, sender.bearer, { method: "POST", path: route.path, body: { [route.key]: entries.map((entry) => entry.item) }, timeoutMs: SEND_TIMEOUT_MS });
+    if (answer === null)
+        return kept(null);
+    if (answer.status >= 200 && answer.status < 300)
+        return { settled: entries.map((entry) => entry.id), kept: false };
+    if (answer.status < 400 || answer.status >= 500 || KEEP_STATUSES.has(answer.status))
+        return kept(answer.status);
+    return settleRefused(sender, { entries, status: answer.status, json: answer.json });
+}
+/** A refusing 4xx: dead-letter what the answer names, else split until the refused item is alone. */
+async function settleRefused(sender, refusal) {
+    const { entries, status, json } = refusal;
+    if (entries.length === 1)
+        return refusedAlone(sender, refusal);
+    const named = status === 400 ? rejectedIndexes(json, sender.route.key, entries.length) : new Set();
+    if (named.size > 0) {
+        const bad = entries.filter((_, index) => named.has(index));
+        await sender.deadLetter(bad, status, json);
+        const rest = entries.filter((_, index) => !named.has(index));
+        const sent = rest.length === 0 ? { settled: [], kept: false } : await sendBatch(sender, rest);
+        return { ...sent, settled: [...bad.map((entry) => entry.id), ...sent.settled] };
+    }
+    const half = Math.ceil(entries.length / 2);
+    const first = await sendBatch(sender, entries.slice(0, half));
+    if (first.kept)
+        return first;
+    const second = await sendBatch(sender, entries.slice(half));
+    return { ...second, settled: [...first.settled, ...second.settled] };
+}
+async function refusedAlone(sender, refusal) {
+    const entry = refusal.entries[0];
+    const refused = (sender.refusals.get(entry.id) ?? 0) + 1;
+    if (refused < MAX_REFUSALS) {
+        sender.refusals.set(entry.id, refused);
+        return kept(refusal.status);
+    }
+    sender.refusals.delete(entry.id);
+    await sender.deadLetter([entry], refusal.status, refusal.json);
+    return { settled: [entry.id], kept: false };
+}
+/** The item indexes a 400's zod `issues` point at (`[key, i, …]`). */
+function rejectedIndexes(json, key, count) {
+    const issues = isRecord(json) && Array.isArray(json["issues"]) ? json["issues"] : [];
+    const indexes = issues.flatMap((issue) => {
+        const path = isRecord(issue) && Array.isArray(issue["path"]) ? issue["path"] : [];
+        return path[0] === key && Number.isInteger(path[1]) && path[1] < count ? [path[1]] : [];
+    });
+    return new Set(indexes);
+}

package/dist/listener/serve.d.ts

@@ -0,0 +1,2 @@
+import { type StartedListener } from "./server.js";
+export declare function serveHooks(home: string, out: (line: string) => void): Promise<StartedListener>;

package/dist/listener/serve.js

@@ -0,0 +1,155 @@
+/**
+ * `npx heedvane listener start`: the loopback listener wired to Heedvane. Each event is logged
+ * and answered with the skill check, steering, organization instructions and memory recall
+ * (src/reply/reply.ts), from this machine alone: no hook waits on Heedvane. The organization's
+ * steering policy is fetched at start and once per session, at its session start
+ * (src/steering/rules.ts); a session holds the policy it started with. It is cached, so a restarted
+ * 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 { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { backendAt } 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 { 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 { DELIVERIES_ROUTE, outbox } from "./forward.js";
+import { startListener } 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" };
+/** Where the dispatcher finds the pre-rendered instruction answer for one Claude Code event (dispatchers/posix.ts). */
+function instructionAnswerPath(root, hookEventName) {
+    return join(root, "steering", `instructions-${hookEventName}.json`);
+}
+export async function serveHooks(home, out) {
+    const root = join(home, ".heed");
+    await ensureEndpoint(root);
+    const log = (message) => out(`  · ${message}`);
+    const config = heedvaneConfigAt(root);
+    // 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) => {
+        out(`  · [heedvane] could not check whose sign-in the spool and caches belong to (${errorMessage(err)}); the listener did not start. Fix or remove ${signedInAsPath(root)} and start it again`);
+        throw err;
+    });
+    // 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);
+    // 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 });
+    const ctx = {
+        config,
+        backend: org,
+        root,
+        home,
+        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)}`)),
+        stopBlocks: new Map(),
+        violations: new Map(),
+        sessionEnds: new Map(),
+    };
+    const syncPolicy = async () => {
+        if (org === null)
+            return;
+        const identity = await org.identity();
+        const synced = await fetchSteeringPolicy(org, BACKEND_BUDGET_MS);
+        if (!("policy" in synced))
+            return refusedSync(synced.status, log);
+        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.
+        if ((await org.identity()) !== identity)
+            await discardSteeringCaches(root);
+    };
+    // 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();
+    const started = await startListener({
+        root,
+        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)
+                return {};
+            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(), teamMemoryAtStart(org, envelope)]);
+                if (policy !== null)
+                    sessionPolicies.set(envelope.session, policy);
+            }
+            else if (envelope.event === "session_end")
+                sessionPolicies.delete(envelope.session);
+            return replyFor(envelope, ctx, { toolInput: isRecord(body) ? uncappedToolInput(body) : undefined, teamMemory });
+        },
+        log,
+    });
+    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");
+    return started;
+}
+/** 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);
+    return org === null || gitOrigin === "" ? undefined : fetchTeamMemoryMap(org, gitOrigin);
+}
+/** A refused sync keeps the cached policy; a refused credential is said loudly, every sync. */
+function refusedSync(status, log) {
+    if (status === 401)
+        log("[heedvane] HEEDVANE REFUSED THIS MACHINE'S CREDENTIAL (401): steering rules and skills are not reaching Heedvane. Run npx heedvane login again, or on CI save an organization key with npx heedvane auth org");
+    else if (status === 403)
+        log("[heedvane] Heedvane does not serve steering to this organization (403): the plan or the credential's access does not include it");
+}
+/**
+ * Pre-render the organization instructions as the Claude Code answers the dispatcher prints when the
+ * listener cannot answer, so they are injected even then; removed when there are none.
+ */
+async function writeInstructionAnswers(root, policy) {
+    await mkdir(join(root, "steering"), { recursive: true, mode: 0o700 });
+    for (const [event, hookEventName] of Object.entries(INSTRUCTION_EVENTS)) {
+        const path = instructionAnswerPath(root, hookEventName);
+        const envelope = { v: 1, event, agent: "claude", session: "", pane: "", receivedAt: "", payload: {} };
+        const answer = harnessOutput(envelope, { ...ALLOW, context: instructionContext(policy, event) });
+        if (Object.keys(answer).length > 0)
+            await writeFileAtomic(path, JSON.stringify(answer), { mode: 0o600 });
+        else
+            await unlink(path).catch(() => undefined); // absent already: nothing to inject
+    }
+}

package/dist/listener/server.d.ts

@@ -0,0 +1,48 @@
+import type { IncomingMessage, Server } from "node:http";
+import type { Envelope } from "../events/contract.js";
+/** Agent ids accepted on `/hook/<agentId>`. */
+export declare const KNOWN_AGENTS: ReadonlySet<string>;
+/** Request body cap: 5 MB. */
+export declare const MAX_BODY_BYTES = 5242880;
+/** The hook's stdout JSON for the agent, or nothing for `{}`. */
+export type HookReply = Record<string, unknown> | void;
+/** What the listener hands the consumer for each accepted POST. */
+export interface HookEventContext {
+    agent: string;
+    body: unknown;
+    /** The canonical envelope every ingest path emits (normalized at the door). */
+    envelope: Envelope;
+    headers: IncomingMessage["headers"];
+    /** A spooled event replayed at start: record it, but its agent stopped waiting for an answer long ago. */
+    replayed?: boolean;
+}
+export interface StartListenerOptions {
+    /** Heed root directory containing `endpoint.env`. */
+    root: string;
+    /** Called (and awaited) for every accepted event. */
+    onEvent: (event: HookEventContext) => HookReply | Promise<HookReply>;
+    /** Warning sink; defaults to console.log. */
+    log?: (message: string) => void;
+    /** Override the known-agent table (defaults to KNOWN_AGENTS). */
+    knownAgents?: ReadonlySet<string>;
+}
+export interface StartedListener {
+    server: Server;
+    /** The actual bound port (useful when endpoint.env said 0). */
+    port: number;
+    /** Spooled events replayed through `onEvent` at start. */
+    replayed: number;
+}
+/**
+ * Constant-time token comparison. Both sides are hashed first so the buffers
+ * always match in length (timingSafeEqual throws on length mismatch, and a
+ * length-leaking early return would defeat the point).
+ */
+export declare function safeTokenEqual(a: string, b: string): boolean;
+/**
+ * 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
+ * endpoint.env. Refuses to start (with remediation) when endpoint.env is
+ * missing or has no TOKEN.
+ */
+export declare function startListener(options: StartListenerOptions): Promise<StartedListener>;