heedvane 0.3.3 → 0.3.4

package/dist/guard.js

@@ -0,0 +1,302 @@
+// heedvane: Heedvane's guard for Pi. It asks the local Heedvane listener before each tool runs, and lets the tool run when it cannot ask.
+//
+// One file serves every Pi:
+// - The Pi coding agent loads it as an extension: `npx -y heedvane connect --agent pi` copies it to
+//   `<Pi's agent folder>/extensions/heedvane.ts`, and `npx -y heedvane uninstall` removes it.
+// - Code built on Pi's core (`@earendil-works/pi-agent-core`): `new Agent({ ..., beforeToolCall })`.
+// - Pi Durable (`@earendil-works/pi-durable`), which does not run on Pi's core: `hook(ToolTask, { beforeTool })`.
+// It imports only Node's own modules and src/hook-fallback.ts, which the copy carries inline, so it runs on its own.
+// It is also every agent's fallback when the listener cannot answer ({@link keepUnanswered}): the dispatchers and
+// Hermes run its copy `fallback.mjs` with UNANSWERED_FLAG. It spools the event for the listener to replay, starts a
+// listener, tells the person once per session that calls are not checked, and lets the tool run.
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { appendFileSync, closeSync, mkdirSync, openSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, join, sep } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { parseEnv } from "node:util";
+import { HOOK_TIMEOUT_MS, LISTENER_START, OTHER_SIGN_IN_DIR, PANE_KEY_ENV, listenerProof, PROBE_REFUSAL, PROOF_HEADER, SESSION_START_TIMEOUT_MS, SPOOL_CAP_BYTES, SPOOL_DIR, SPOOL_ENV, SPOOL_FILE_PREFIX, SPOOL_FILE_SUFFIX, SPOOL_TTL_DAYS, START_LOCK, START_LOCK_HOLDER, START_LOCK_MINUTES, RETRY_AFTER_MS, UNANSWERED_FLAG, UNCHECKED_ERROR_NOTICE, UNCHECKED_MARK_PREFIX, UNCHECKED_NOTICE } from "./hook-fallback.js";
+/** heed.yaml `gating.mode`, set in the copy `connect` installs: `pane` asks only in sessions started with HEED_SESSION. Code that imports the guard always asks. */
+const GATING = "always";
+/** Pi's built-in tools under Claude Code's names, the names Heedvane's rules list. */
+const RULE_TOOL_NAMES = { bash: "Bash", read: "Read", edit: "Edit", write: "Write", grep: "Grep", find: "Glob", ls: "LS" };
+const FALLBACK_REASON = "Heedvane's rules refuse this tool call.";
+/**
+ * Heedvane's reason to refuse this tool call, or undefined to let it run. It never throws: when the listener cannot
+ * answer (none runs, another program holds its port, or it answers with an error) the event is spooled for it to
+ * replay and the tool runs, as with every agent's hooks.
+ */
+export async function heedvaneRefusal(call) {
+    let asked;
+    try {
+        if (GATING !== "always" && !process.env["HEED_SESSION"])
+            return undefined;
+        asked = { place: listenerPlace(), event: { event: hookEvent(call), id: randomUUID() } };
+        const question = { agent: "pi", body: JSON.stringify(asked.event.event), id: asked.event.id };
+        const answer = await listenerAnswer(asked.place, question).catch((err) => {
+            return askAgain(asked.place, question, err); // its second answer; a refusal of the listener's own is rethrown there
+        });
+        return refusalIn(answer);
+    }
+    catch (err) {
+        if (refusedWith(err) === undefined)
+            keepForTheListener(call, asked, err);
+        else if (noteRefused(asked.place.root, err, { source: "pi", payload: JSON.stringify(asked.event.event), id: asked.event.id, session: asked.event.event.session_id }))
+            tell(call, UNCHECKED_ERROR_NOTICE);
+        return undefined;
+    }
+}
+/** The process's folder; the home folder when it cannot say (its folder was removed). */
+function cwdOrHome() {
+    try {
+        return process.cwd();
+    }
+    catch {
+        return homedir();
+    }
+}
+/** The call as Claude Code's PreToolUse, with Claude Code's tool names. */
+function hookEvent(call) {
+    return {
+        hook_event_name: "PreToolUse",
+        session_id: call.session ?? process.env["HEED_SESSION"] ?? `pi-${process.pid}`,
+        cwd: call.cwd ?? cwdOrHome(),
+        tool_name: RULE_TOOL_NAMES[call.tool] ?? call.tool,
+        tool_input: call.input,
+        tool_use_id: call.id,
+    };
+}
+/**
+ * The port and token from HEED_AGENT_HOOK_PORT and HEED_AGENT_HOOK_TOKEN when both are set, else from the endpoint file:
+ * HEED_AGENT_HOOK_ENDPOINT, else endpoint.env in HEED_AGENT_HOOK_ROOT (which `heedvane run` sets), else in ~/.heed.
+ * An empty variable counts as unset, as in the dispatchers.
+ */
+function listenerPlace() {
+    const endpointFile = process.env["HEED_AGENT_HOOK_ENDPOINT"] || join(process.env["HEED_AGENT_HOOK_ROOT"] || join(homedir(), ".heed"), "endpoint.env");
+    const root = dirname(endpointFile);
+    const fromEnv = { port: process.env["HEED_AGENT_HOOK_PORT"], token: process.env["HEED_AGENT_HOOK_TOKEN"] };
+    if (fromEnv.port && fromEnv.token)
+        return { root, ...fromEnv };
+    try {
+        const values = parseEnv(readFileSync(endpointFile, "utf8"));
+        return { root, port: values["HEED_AGENT_HOOK_PORT"], token: values["HEED_AGENT_HOOK_TOKEN"] };
+    }
+    catch {
+        return { root }; // no endpoint file: nothing to ask, the event is spooled
+    }
+}
+/**
+ * The listener's answer; throws when there is none: no endpoint, nothing listening, another program, or an error
+ * answer. An error answer from a listener that names its settings (0.3.4 on), other than 503 (it is stopping), is its
+ * own answer to this event: the error carries its status as `refused`, and starting another listener would change nothing.
+ */
+async function listenerAnswer(place, { agent, body, id }) {
+    if (!place.port || !place.token)
+        throw new Error("no listener endpoint");
+    const route = `http://127.0.0.1:${place.port}/hook/${agent}`;
+    // Every call, since the port can change hands between calls; a probe on loopback costs well under a millisecond.
+    const probe = await fetch(route, { signal: AbortSignal.timeout(HOOK_TIMEOUT_MS) });
+    const about = (probe.status === 405 ? await probe.json() : {});
+    // Only this machine's listener names the proof of its token; a listener before 0.3.4 names none, and is never asked.
+    // shortcut: proof is static and readable by GET; another OS user can replay it — challenge-response (nonce + HMAC, no token on the wire) right after this PR
+    const proof = await listenerProof(place.token);
+    const proven = (answer) => answer.headers.get(PROOF_HEADER) === proof;
+    if (about.error !== PROBE_REFUSAL || !proven(probe))
+        throw new Error(`another program answers on 127.0.0.1:${place.port}`);
+    const response = await fetch(route, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-Heed-Agent-Hook-Token": place.token, "X-Heed-Hook-Version": "1", "X-Heed-Event-Id": id },
+        body,
+        // As long as the dispatcher's own ask: a session start waits for Heedvane's team memory.
+        signal: AbortSignal.timeout(/"hook_event_name": ?"SessionStart"/.test(body) ? SESSION_START_TIMEOUT_MS : HOOK_TIMEOUT_MS),
+    });
+    if (!proven(response))
+        throw new Error(`another program answers on 127.0.0.1:${place.port}`);
+    if (!response.ok)
+        throw Object.assign(new Error(`the listener answered ${response.status}`), { refused: typeof about.settings === "string" && response.status !== 503 ? response.status : undefined });
+    return response.json();
+}
+/** The listener's answer after one pause, unless `failed` was its own error answer: a listener taking over from another binds within milliseconds. */
+async function askAgain(place, question, failed) {
+    if (refusedWith(failed) !== undefined)
+        throw failed;
+    // Nothing to ask without a port and a token (no endpoint.env: heedvane/guard without Heedvane installed), so no pause.
+    if (!place.port || !place.token)
+        throw failed ?? new Error("no listener endpoint");
+    await delay(RETRY_AFTER_MS);
+    return listenerAnswer(place, question);
+}
+/** The status of the listener's own error answer to this event (see {@link listenerAnswer}), or undefined. */
+function refusedWith(err) {
+    const status = err?.refused;
+    return typeof status === "number" ? status : undefined;
+}
+/**
+ * A current listener answered this event with an error: the call runs, the listener's log says so, and this says
+ * whether the session is yet to be told (once, by its own marker). A server error (5xx) may pass, so the event is kept
+ * for the listener to replay; a refused request (4xx) would be refused again.
+ */
+function noteRefused(root, err, unanswered) {
+    // shortcut: the kept event waits for the next listener start to replay it, upgrade if a running listener should drain its spool.
+    if ((refusedWith(err) ?? 0) >= 500)
+        attempt(() => spoolEvent(root, unanswered));
+    attempt(() => appendFileSync(join(root, "listener.log"), `[heedvane] ${String(err)} to a hook; the call ran unchecked\n`, { mode: 0o600 }));
+    return attempt(() => markTold(root, `error-${unanswered.session}`)) === true;
+}
+/** The reason in the listener's `{block: true, reason}`, or undefined when it lets the call run. */
+function refusalIn(answer) {
+    if (typeof answer !== "object" || answer === null || answer.block !== true)
+        return undefined;
+    const reason = answer.reason;
+    return typeof reason === "string" && reason !== "" ? reason : FALLBACK_REASON;
+}
+/**
+ * Pi's call the listener did not answer, kept for it ({@link keepUnanswered}), the session told once. `asked` is
+ * undefined when the guard failed before it could ask: the call is then built again here and the failure logged.
+ * It never throws into Pi.
+ */
+function keepForTheListener(call, asked, err) {
+    const { place, event } = asked ?? { place: { root: join(homedir(), ".heed") }, event: { event: hookEvent(call), id: randomUUID() } };
+    const unanswered = { source: "pi", payload: JSON.stringify(event.event), id: event.id, session: event.event.session_id };
+    if (keepUnanswered(place.root, unanswered))
+        tell(call, UNCHECKED_NOTICE);
+    if (asked === undefined)
+        attempt(() => appendFileSync(join(place.root, "listener.log"), `[heedvane] Pi's guard could not ask the listener (${String(err)}); the call ran unchecked and is spooled\n`, { mode: 0o600 }));
+}
+/** Shows the person `notice` where Pi can (its notice, or stderr); never throws into Pi. */
+function tell(call, notice) {
+    attempt(() => (call.tell ?? ((text) => tellPerson(undefined, text)))(notice));
+}
+/**
+ * Every agent's fallback when the listener gives no answer: keeps the event in the spool for the listener to replay,
+ * starts a listener (on any failure: on Windows a refused loopback connection outlasts the timeout), and says whether
+ * the session is yet to be told that its calls are not checked; its marker is written now. Never throws.
+ */
+export function keepUnanswered(root, unanswered) {
+    attempt(() => spoolEvent(root, unanswered));
+    attempt(() => startListener(root));
+    return attempt(() => markTold(root, unanswered.session)) === true;
+}
+/** `step`'s result, or undefined when it throws (a full disk, a read-only home, a start already under way): the tool still runs. */
+function attempt(step) {
+    try {
+        return step();
+    }
+    catch {
+        return undefined; // the fallback's own failure never reaches the agent
+    }
+}
+/** The spool record, in the pane's file, which the listener replays when it starts; spool files past their TTL go first. */
+function spoolEvent(root, { source, payload, id }) {
+    const pane = PANE_KEY_ENV.map((variable) => process.env[variable]).find(Boolean) ?? "";
+    const dir = join(root, SPOOL_DIR);
+    const file = join(dir, `${SPOOL_FILE_PREFIX}${pane || "default"}${SPOOL_FILE_SUFFIX}`);
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    attempt(() => pruneSpool(dir)); // a prune that fails (an older Node in Pi, a file another hook just removed) never costs the event
+    if ((statSync(file, { throwIfNoEntry: false })?.size ?? 0) >= SPOOL_CAP_BYTES)
+        return;
+    const fromEnv = Object.fromEntries(Object.entries(SPOOL_ENV).map(([field, variable]) => [field, process.env[variable] ?? ""]));
+    const record = { paneKey: pane, ...fromEnv, source, receivedAt: new Date().toISOString(), id, payload };
+    appendFileSync(file, `${JSON.stringify(record)}\n`, { mode: 0o600 });
+}
+/** Removes spool files, told markers and the events set aside after a change of sign-in that are older than SPOOL_TTL_DAYS. */
+function pruneSpool(dir) {
+    const cutoff = Date.now() - SPOOL_TTL_DAYS * 86_400_000;
+    for (const entry of readdirSync(dir, { recursive: true, withFileTypes: true })) {
+        const path = join(entry.parentPath, entry.name);
+        const pruned = entry.name.startsWith(SPOOL_FILE_PREFIX) || entry.name.startsWith(UNCHECKED_MARK_PREFIX) || path.includes(`${sep}${OTHER_SIGN_IN_DIR}${sep}`);
+        if (entry.isFile() && pruned && statSync(path).mtimeMs < cutoff)
+            rmSync(path, { force: true });
+    }
+}
+/** Writes the session's told marker in the spool folder; false when it was there: the session has been told. */
+function markTold(root, session) {
+    const marker = join(root, SPOOL_DIR, `${UNCHECKED_MARK_PREFIX}${session.replace(/[^A-Za-z0-9_.-]/g, "") || "default"}`);
+    mkdirSync(dirname(marker), { recursive: true, mode: 0o700 });
+    closeSync(openSync(marker, "wx", 0o600)); // throws when the marker is there
+    return true;
+}
+/** LISTENER_START from the heed folder, in the background, at most once a minute; `listener start` decides whether one must start. */
+function startListener(root) {
+    if (process.env["HEED_LISTENER_AUTOSTART"] === "0" || basename(root) !== ".heed")
+        return;
+    const lock = join(root, START_LOCK);
+    const lockAge = Date.now() - (statSync(lock, { throwIfNoEntry: false })?.mtimeMs ?? Date.now());
+    if (lockAge > START_LOCK_MINUTES * 60_000)
+        rmSync(lock, { recursive: true, force: true });
+    mkdirSync(lock); // throws when another start holds the lock
+    const log = openSync(join(root, "listener.log"), "a", 0o600);
+    try {
+        // From the heed folder: in the agent's project, npx could run a `heedvane` the project's package.json names.
+        // The folder of the Node that runs this is the last place to find npx: an agent started from a desktop app may have none on PATH.
+        const path = `${process.env["PATH"] ?? ""}${delimiter}${dirname(process.execPath)}`;
+        const [command, ...args] = LISTENER_START;
+        // Windows runs npx as npx.cmd, which Node starts only through a shell. Not run on Windows in this package's tests.
+        const child = spawn(command, args, { cwd: root, detached: true, windowsHide: true, shell: process.platform === "win32", stdio: ["ignore", log, log], env: { ...process.env, NODE_OPTIONS: undefined, PATH: path, HEED_HOME: dirname(root) } }); // Node drops undefined variables; the agent's NODE_OPTIONS are its project's
+        child.on("error", () => undefined); // no npx: the next start is a minute away
+        child.unref();
+        writeFileSync(join(lock, START_LOCK_HOLDER), String(child.pid ?? "")); // a command takes the lock over once this start has ended
+    }
+    finally {
+        closeSync(log);
+    }
+}
+/** Pi's core: `new Agent({ beforeToolCall })`, or `agent.beforeToolCall = beforeToolCall`. */
+export async function beforeToolCall(context) {
+    const reason = await heedvaneRefusal({ tool: context.toolCall.name, input: context.args, id: context.toolCall.id });
+    return reason === undefined ? undefined : { block: true, reason };
+}
+/** Pi Durable: `defineExtension({ name: "heedvane", hooks: [hook(ToolTask, { beforeTool })] })`. Its conversation is the session. */
+export async function beforeTool(call, api) {
+    const session = api?.conversationId === undefined ? undefined : `pi-durable-${api.conversationId}`;
+    const reason = await heedvaneRefusal({ tool: call.name, input: call.arguments, id: call.id, session });
+    return reason === undefined ? undefined : { block: reason };
+}
+/** The Pi coding agent's extension entry point. */
+export default function heedvane(pi) {
+    pi.on("tool_call", async (event, ctx) => {
+        const reason = await heedvaneRefusal({ tool: event.toolName, input: event.input, id: event.toolCallId, cwd: ctx?.cwd, session: sessionOf(ctx), tell: (notice) => tellPerson(ctx, notice) });
+        return reason === undefined ? undefined : { block: true, reason };
+    });
+}
+/** Pi's warning notice where it has a UI; on stderr in print and JSON modes, where a pipeline's log shows it. */
+function tellPerson(ctx, notice) {
+    if (ctx?.hasUI === true && ctx.ui?.notify !== undefined)
+        ctx.ui.notify(`Heedvane: ${notice}`, "warning");
+    else
+        process.stderr.write(`heedvane: ${notice}\n`);
+}
+function sessionOf(ctx) {
+    try {
+        return ctx?.sessionManager?.getSessionId?.();
+    }
+    catch {
+        return undefined; // a session manager that cannot say: the process's session stands in
+    }
+}
+/**
+ * `node fallback.mjs --heedvane-unanswered <agent> [notice field]`: the dispatchers' and Hermes' fallback, with the
+ * hook's event on stdin and the answer the hook gives without the listener in HEED_HOOK_FALLBACK_ANSWER. Keeps the
+ * event, and prints that answer with the notice in the agent's notice field the first time in a session.
+ */
+async function answerUnanswered([agent = "", noticeField]) {
+    const fallback = JSON.parse(process.env["HEED_HOOK_FALLBACK_ANSWER"] || "{}");
+    const payload = readFileSync(0, "utf8");
+    const place = listenerPlace();
+    const question = { agent, body: payload, id: process.env["HEED_HOOK_EVENT_ID"] || randomUUID() };
+    // The hook asked once already; a listener taking the port over answers the second time.
+    const answer = await askAgain(place, question, undefined).catch((err) => {
+        const unanswered = { source: agent, payload, id: question.id, session: sessionIn(payload) };
+        const [told, notice] = refusedWith(err) === undefined ? [keepUnanswered(place.root, unanswered), UNCHECKED_NOTICE] : [noteRefused(place.root, err, unanswered), UNCHECKED_ERROR_NOTICE];
+        return told && noticeField ? { [noticeField]: notice, ...fallback } : fallback;
+    });
+    process.stdout.write(`${JSON.stringify(answer)}\n`);
+}
+/** The hook event's session id, or "" when it names none. */
+function sessionIn(payload) {
+    const session = attempt(() => JSON.parse(payload).session_id);
+    return typeof session === "string" ? session : "";
+}
+if (process.argv[2] === UNANSWERED_FLAG)
+    void answerUnanswered(process.argv.slice(3));

package/dist/heed-file.d.ts

@@ -67,8 +67,6 @@ export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 He
 export declare function loadHeedFile(text: string): HeedFile;
 /** `text` with each `[path, value]` written in place; the file's comments stay. Validate with {@link loadHeedFile}. */
 export declare function withSettings(text: string, settings: ReadonlyArray<readonly [string[], unknown]>): string;
-/** `text` with `heedvane.url` set to `url` (`connect --server`); the file's comments stay. Validate with {@link loadHeedFile}. */
-export declare function withServerUrl(text: string, url: string): string;
 /** What the interactive installer asks: which agents, which integrations, and which Heedvane features. */
 export interface InstallChoices {
     /** Chosen agent ids, or "auto" for every detected agent. */
@@ -87,5 +85,10 @@ export declare function withInstallChoices(text: string, choices: InstallChoices
  * the file cannot be rewritten the key is ignored in memory and the line says that instead.
  */
 export declare function loadHeedFileAt(path: string, log?: (line: string) => void): HeedFile;
+/** {@link loadHeedFileAt}, with the file's text as it is on disk afterwards: what the settings it holds hash from. */
+export declare function readHeedFileAt(path: string, log?: (line: string) => void): {
+    heedFile: HeedFile;
+    text: string;
+};
 /** heed.yaml's `heedvane` section under `root`; the template's defaults before init has written one. */
 export declare function heedvaneConfigAt(root: string): HeedvaneConfig;

package/dist/heed-file.js

@@ -262,10 +262,6 @@ export function withSettings(text, settings) {
     }
     return String(document);
 }
-/** `text` with `heedvane.url` set to `url` (`connect --server`); the file's comments stay. Validate with {@link loadHeedFile}. */
-export function withServerUrl(text, url) {
-    return withSettings(text, [[["heedvane", "url"], url]]);
-}
 /** `text` with the installer's choices written into the fields that already hold them; the file's comments stay. */
 export function withInstallChoices(text, choices) {
     return withSettings(text, [
@@ -288,22 +284,26 @@ const toStderr = (line) => void process.stderr.write(`${line}\n`);
  * the file cannot be rewritten the key is ignored in memory and the line says that instead.
  */
 export function loadHeedFileAt(path, log = toStderr) {
+    return readHeedFileAt(path, log).heedFile;
+}
+/** {@link loadHeedFileAt}, with the file's text as it is on disk afterwards: what the settings it holds hash from. */
+export function readHeedFileAt(path, log = toStderr) {
     const text = readFileSync(path, "utf8");
     const document = parseDocument(text);
     const retired = document.errors.length > 0 ? [] : RETIRED_KEYS.filter((path) => document.hasIn(path));
     if (retired.length === 0)
-        return loadHeedFile(text);
+        return { heedFile: loadHeedFile(text), text };
     const names = retired.map((path) => path.join(".")).join(", ");
     for (const path of retired)
         document.deleteIn(path);
     const refusal = rewriteInPlace(path, document);
     if (refusal === null) {
         log(`[heedvane] removed ${names} from ${path}: no hook waits on Heedvane any more`);
-        return loadHeedFile(String(document));
+        return { heedFile: loadHeedFile(String(document)), text: String(document) };
     }
     // The file stays as it was (an alias to the removed key cannot be written back, or the disk refused): load it without the key.
     log(`[heedvane] could not remove ${names} from ${path} (${errorMessage(refusal)}); it is ignored`);
-    return loadHeedFile(JSON.stringify(withoutKeys(parse(text), retired)));
+    return { heedFile: loadHeedFile(JSON.stringify(withoutKeys(parse(text), retired))), text };
 }
 /** Writes the document over `path`; the error that stopped it, or null. */
 function rewriteInPlace(path, document) {

package/dist/hook-fallback.d.ts

@@ -0,0 +1,73 @@
+/**
+ * What an agent's hook does when Heedvane's listener cannot answer, owned here once. Pi's guard (src/guard.ts) is the
+ * one fallback that acts on these values: Pi runs it in process, and the POSIX dispatchers (src/dispatchers/posix.ts)
+ * and Hermes' plugin (src/clients/hermes-plugin.ts) run its installed copy, {@link FALLBACK_FILE}. The listener reads
+ * the spool they describe (src/listener/spool.ts). It imports nothing, so each copy of the guard carries it inline
+ * (src/clients/pi-extension.ts).
+ */
+/** The listener's refusal of a GET on a hook route: the answer that tells it apart from another program on its port. */
+export declare const PROBE_REFUSAL = "method not allowed; POST only";
+/**
+ * The header every answer of this machine's listener (0.3.4 on) carries, and the endpoint.env line the dispatchers read it
+ * from: {@link listenerProof} of the token, so it proves the answer is that listener's without showing the token.
+ */
+export declare const PROOF_HEADER = "X-Heed-Listener";
+export declare const PROOF_KEY = "HEED_AGENT_HOOK_PROOF";
+/** What the proof signs; Hermes' plugin signs the same text in Python. */
+export declare const PROOF_MESSAGE = "heedvane listener";
+/** The proof of the listener with `token`: HMAC-SHA-256 of {@link PROOF_MESSAGE} under it, 32 hex digits. WebCrypto, so this file imports nothing. */
+export declare function listenerProof(token: string): Promise<string>;
+/** Events no listener answered: `<heed root>/spool/pane-<pane key, else session, else "default">.jsonl`, one JSON record a line. */
+export declare const SPOOL_DIR = "spool";
+export declare const SPOOL_FILE_PREFIX = "pane-";
+export declare const SPOOL_FILE_SUFFIX = ".jsonl";
+/** A pane's spool file stops growing at 5 MB. */
+export declare const SPOOL_CAP_BYTES = 5242880;
+/** Spool files, and the events set aside after a change of sign-in, older than this are removed. */
+export declare const SPOOL_TTL_DAYS = 7;
+export declare const OTHER_SIGN_IN_DIR = "other-sign-in";
+/** One spooled event. `payload` is the hook's JSON text, `source` the agent id. */
+export interface SpoolRecord {
+    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;
+}
+/** The record fields copied from the agent's environment, and the pane key's variables in order. */
+export declare const SPOOL_ENV: {
+    readonly tabId: "HEED_TAB_ID";
+    readonly worktreeId: "HEED_WORKTREE_ID";
+    readonly launchToken: "HEED_LAUNCH_TOKEN";
+};
+export declare const PANE_KEY_ENV: readonly ["HEED_PANE_KEY", "HEED_SESSION"];
+/** Told once per session, where the agent can show it, when the hook cannot ask the listener; the agent still continues. */
+export declare const UNCHECKED_NOTICE = "Heedvane is not reachable; actions are not being checked.";
+/** Told once per session when the listener answers a call with an error of its own; that call ran unchecked. */
+export declare const UNCHECKED_ERROR_NOTICE = "Heedvane's listener answered with an error, so an action was not checked; ~/.heed/listener.log says why.";
+/** The marker, one per session in the spool folder, that the session has been told. */
+export declare const UNCHECKED_MARK_PREFIX = "unchecked-";
+/** How long a hook waits for the listener: to connect, to answer, and at a session start (its one policy fetch). */
+export declare const HOOK_CONNECT_TIMEOUT_MS = 500;
+export declare const HOOK_TIMEOUT_MS = 800;
+export declare const SESSION_START_TIMEOUT_MS = 2000;
+/** The guard's copy beside the dispatchers' scripts and in Hermes' plugin, which they run with this flag when the listener did not answer. */
+export declare const FALLBACK_FILE = "fallback.mjs";
+export declare const UNANSWERED_FLAG = "--heedvane-unanswered";
+/** How long the fallback waits before it asks the listener once more: one taking the port over binds within milliseconds. */
+export declare const RETRY_AFTER_MS = 250;
+/** The longest Hermes waits for the fallback: a second for Node's start and keeping the event, the pause, the probe and the ask. */
+export declare const FALLBACK_TIMEOUT_MS: number;
+/** The file beside the dispatchers' scripts that names the Node the fallback runs with: the one that last installed the hooks. */
+export declare const HOOK_NODE_FILE = "node";
+/** With nothing listening, the hook starts the listener with this command from the heed folder, at most once a minute. */
+export declare const LISTENER_START: readonly ["npx", "-y", "heedvane", "listener", "start"];
+/** The lock folder in the heed folder that keeps it to one start a minute; the listener removes it once it listens. */
+export declare const START_LOCK = "listener.starting";
+export declare const START_LOCK_MINUTES = 1;
+/** The file in the start lock naming the pid of the start that holds it. */
+export declare const START_LOCK_HOLDER = "pid";

package/dist/hook-fallback.js

@@ -0,0 +1,61 @@
+/**
+ * What an agent's hook does when Heedvane's listener cannot answer, owned here once. Pi's guard (src/guard.ts) is the
+ * one fallback that acts on these values: Pi runs it in process, and the POSIX dispatchers (src/dispatchers/posix.ts)
+ * and Hermes' plugin (src/clients/hermes-plugin.ts) run its installed copy, {@link FALLBACK_FILE}. The listener reads
+ * the spool they describe (src/listener/spool.ts). It imports nothing, so each copy of the guard carries it inline
+ * (src/clients/pi-extension.ts).
+ */
+/** The listener's refusal of a GET on a hook route: the answer that tells it apart from another program on its port. */
+export const PROBE_REFUSAL = "method not allowed; POST only";
+/**
+ * The header every answer of this machine's listener (0.3.4 on) carries, and the endpoint.env line the dispatchers read it
+ * from: {@link listenerProof} of the token, so it proves the answer is that listener's without showing the token.
+ */
+export const PROOF_HEADER = "X-Heed-Listener";
+export const PROOF_KEY = "HEED_AGENT_HOOK_PROOF";
+/** What the proof signs; Hermes' plugin signs the same text in Python. */
+export const PROOF_MESSAGE = "heedvane listener";
+/** The proof of the listener with `token`: HMAC-SHA-256 of {@link PROOF_MESSAGE} under it, 32 hex digits. WebCrypto, so this file imports nothing. */
+export async function listenerProof(token) {
+    const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(token), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const mac = new Uint8Array(await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(PROOF_MESSAGE)));
+    return Array.from(mac.subarray(0, 16), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+/** Events no listener answered: `<heed root>/spool/pane-<pane key, else session, else "default">.jsonl`, one JSON record a line. */
+export const SPOOL_DIR = "spool";
+export const SPOOL_FILE_PREFIX = "pane-";
+export const SPOOL_FILE_SUFFIX = ".jsonl";
+/** A pane's spool file stops growing at 5 MB. */
+export const SPOOL_CAP_BYTES = 5_242_880;
+/** Spool files, and the events set aside after a change of sign-in, older than this are removed. */
+export const SPOOL_TTL_DAYS = 7;
+export const OTHER_SIGN_IN_DIR = "other-sign-in";
+/** The record fields copied from the agent's environment, and the pane key's variables in order. */
+export const SPOOL_ENV = { tabId: "HEED_TAB_ID", worktreeId: "HEED_WORKTREE_ID", launchToken: "HEED_LAUNCH_TOKEN" };
+export const PANE_KEY_ENV = ["HEED_PANE_KEY", "HEED_SESSION"];
+/** Told once per session, where the agent can show it, when the hook cannot ask the listener; the agent still continues. */
+export const UNCHECKED_NOTICE = "Heedvane is not reachable; actions are not being checked.";
+/** Told once per session when the listener answers a call with an error of its own; that call ran unchecked. */
+export const UNCHECKED_ERROR_NOTICE = "Heedvane's listener answered with an error, so an action was not checked; ~/.heed/listener.log says why.";
+/** The marker, one per session in the spool folder, that the session has been told. */
+export const UNCHECKED_MARK_PREFIX = "unchecked-";
+/** How long a hook waits for the listener: to connect, to answer, and at a session start (its one policy fetch). */
+export const HOOK_CONNECT_TIMEOUT_MS = 500;
+export const HOOK_TIMEOUT_MS = 800;
+export const SESSION_START_TIMEOUT_MS = 2_000;
+/** The guard's copy beside the dispatchers' scripts and in Hermes' plugin, which they run with this flag when the listener did not answer. */
+export const FALLBACK_FILE = "fallback.mjs";
+export const UNANSWERED_FLAG = "--heedvane-unanswered";
+/** How long the fallback waits before it asks the listener once more: one taking the port over binds within milliseconds. */
+export const RETRY_AFTER_MS = 250;
+/** The longest Hermes waits for the fallback: a second for Node's start and keeping the event, the pause, the probe and the ask. */
+export const FALLBACK_TIMEOUT_MS = 1_000 + RETRY_AFTER_MS + 2 * HOOK_TIMEOUT_MS;
+/** The file beside the dispatchers' scripts that names the Node the fallback runs with: the one that last installed the hooks. */
+export const HOOK_NODE_FILE = "node";
+/** With nothing listening, the hook starts the listener with this command from the heed folder, at most once a minute. */
+export const LISTENER_START = ["npx", "-y", "heedvane", "listener", "start"];
+/** The lock folder in the heed folder that keeps it to one start a minute; the listener removes it once it listens. */
+export const START_LOCK = "listener.starting";
+export const START_LOCK_MINUTES = 1;
+/** The file in the start lock naming the pid of the start that holds it. */
+export const START_LOCK_HOLDER = "pid";

package/dist/installer.d.ts

@@ -1,7 +1,7 @@
 import type { Readable, Writable } from "node:stream";
 import type { DataMode, HeedFile, InstallChoices } from "./heed-file.js";
-import type { PlannedAction } from "./plan.js";
 import { type AppliedResult } from "./render.js";
+import { type PlannedAction } from "./plan.js";
 /** Where the questions are read and drawn: the process's terminal unless a test injects streams. */
 export interface PromptStreams {
     input?: Readable;
@@ -29,7 +29,7 @@ export declare function askChoices(agents: AgentOption[], current: HeedFile, str
 /** Shows what the install will do and asks to go ahead; false when the person declines or cancels. */
 export declare function confirmInstall(agents: AgentLine[], details: string[], streams: PromptStreams): Promise<boolean>;
 /** The summary's lines about the whole install: what leaves the machine, and where the MCP connection points. */
-export declare function installDetails(heedFile: HeedFile, connector: string | undefined): string[];
+export declare function installDetails(heedFile: HeedFile): string[];
 /** Runs the install behind a spinner; the spinner ends with the outcome either way. */
 export declare function installWithSpinner<T>(agentCount: number, work: () => Promise<T>, streams: PromptStreams): Promise<T>;
 /** One line per agent: a green tick and what it got, or what failed and why. */
@@ -37,7 +37,7 @@ export declare function showInstalled(agents: AgentLine[], streams: PromptStream
 /** A line the install prints along the way (the sign-in link, for one), shown inside the installer's frame. */
 export declare function promptLine(streams: PromptStreams): (line: string) => void;
 /** Starts the listener in the background behind a spinner; true when it answers. */
-export declare function listenerStep(start: () => Promise<boolean>, logPath: string, streams: PromptStreams): Promise<boolean>;
+export declare function listenerStep(start: () => Promise<true | string>, streams: PromptStreams): Promise<boolean>;
 /**
  * One line per agent from the plan, in plan order: what it gets ("hooks · MCP · skill"), "already set up"
  * when nothing changes, or why it gets nothing. `applied` adds what failed when the install ran.
@@ -45,8 +45,8 @@ export declare function listenerStep(start: () => Promise<boolean>, logPath: str
 export declare function agentLines(actions: PlannedAction[], names: ReadonlyMap<string, string>, applied?: AppliedResult[]): AgentLine[];
 /** The closing line after a cancel or a "no": nothing was written. Returns the exit code, 1. */
 export declare function installCancelled(streams: PromptStreams): number;
-/** The closing lines after an install. */
-export declare function installFinished(lines: string[], streams: PromptStreams): void;
+/** The closing lines after an install; without a sign-in it is installed but not yet set up. */
+export declare function installFinished(lines: string[], signedIn: boolean, streams: PromptStreams): void;
 /** What each data mode lets leave this machine, as the installer says it. */
 export declare const DATA_MODE_LABEL: Record<DataMode, {
     label: string;

package/dist/installer.js

@@ -7,7 +7,7 @@
 import { cancel, confirm, intro, isCancel, log, multiselect, note, outro, select, spinner } from "@clack/prompts";
 import { styleText } from "node:util";
 import { appliedFailed } from "./render.js";
-import { MCP_NEEDS_ORG } from "./mcp.js";
+import { connectionNote, heedvaneConnector } from "./plan.js";
 const INTEGRATION_LABEL = { hooks: "hooks", mcp: "MCP server", skill: "skill", skip: "" };
 /** The header: the name, what Heedvane does, and which server and organization this install connects to. */
 export function brandIntro(server, org, streams) {
@@ -46,11 +46,12 @@ export async function confirmInstall(agents, details, streams) {
     return !isCancel(answer) && answer;
 }
 /** The summary's lines about the whole install: what leaves the machine, and where the MCP connection points. */
-export function installDetails(heedFile, connector) {
+export function installDetails(heedFile) {
     const lines = [`What leaves this machine: ${DATA_MODE_LABEL[heedFile.heedvane.dataMode].label}`];
     if (!heedFile.install.mcp)
         return lines;
-    return [...lines, connector === undefined ? MCP_NEEDS_ORG : `Heedvane's MCP connection: ${connector}`];
+    const connector = heedvaneConnector(heedFile);
+    return [...lines, connector === undefined ? connectionNote(heedFile) : `Heedvane's MCP connection: ${connector}`];
 }
 /** Runs the install behind a spinner; the spinner ends with the outcome either way. */
 export async function installWithSpinner(agentCount, work, streams) {
@@ -85,15 +86,15 @@ export function promptLine(streams) {
     };
 }
 /** Starts the listener in the background behind a spinner; true when it answers. */
-export async function listenerStep(start, logPath, streams) {
+export async function listenerStep(start, streams) {
     const progress = spinner({ output: streams.output });
     progress.start("Starting Heedvane in the background");
-    const started = await start().catch(() => false);
-    if (started)
+    const started = await start().catch(() => "Heedvane did not start");
+    if (started === true)
         progress.stop("Heedvane is running in the background");
     else
-        progress.error(`Heedvane did not start; see ${logPath}`);
-    return started;
+        progress.error(started);
+    return started === true;
 }
 /**
  * One line per agent from the plan, in plan order: what it gets ("hooks · MCP · skill"), "already set up"
@@ -113,10 +114,10 @@ export function installCancelled(streams) {
     cancel("Nothing was installed. Run npx heedvane again any time.", streams);
     return 1;
 }
-/** The closing lines after an install. */
-export function installFinished(lines, streams) {
+/** The closing lines after an install; without a sign-in it is installed but not yet set up. */
+export function installFinished(lines, signedIn, streams) {
     note(lines.join("\n"), "Next", streams);
-    outro("Heedvane is set up.", streams);
+    outro(signedIn ? "Heedvane is set up." : "Installed, but not signed in yet: run npx -y heedvane login", streams);
 }
 async function pickAgents(agents, current, streams) {
     const ordered = [...agents.filter((agent) => agent.detected), ...agents.filter((agent) => !agent.detected)];
@@ -182,7 +183,7 @@ function brandBadge(text, output) {
 }
 /** What one agent gets: its integrations, "already set up" when nothing changes, or why it gets nothing. */
 function agentParts(id, own) {
-    const installs = own.filter((action) => action.kind !== "skip");
+    const installs = own.filter((action) => action.kind !== "skip" && action.operation !== "remove");
     if (installs.length === 0)
         return own.map((action) => styleText("dim", action.reason?.replace(`${id}: `, "") ?? "nothing to add"));
     if (installs.every((action) => action.operation === "unchanged"))