heedvane 0.0.0-stage → 0.2.0

package/dist/heed-file.js

@@ -0,0 +1,316 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import writeFileAtomic from "write-file-atomic";
+import { isScalar, parse, parseDocument } from "yaml";
+import { errorMessage, isRecord } from "./guards.js";
+/** Error raised for any invalid heed.yaml. The message is user-facing: keep it precise. */
+class HeedFileError extends Error {
+    constructor(message) {
+        super(`invalid heed.yaml: ${message}`);
+        this.name = "HeedFileError";
+    }
+}
+const TOP_LEVEL_KEYS = [
+    "schemaVersion",
+    "root",
+    "listener",
+    "agents",
+    "install",
+    "gating",
+    "heedvane",
+];
+/**
+ * The commented control file written by `npx heedvane init`.
+ * Kept loadable: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE) yields every default.
+ */
+export const DEFAULT_HEED_YAML_TEMPLATE = `# ~/.heed/heed.yaml — Heedvane agent hooks control file (v1)
+schemaVersion: v1
+
+# Where managed scripts and spool live. Default below; one install per machine.
+root: ~/.heed
+
+# The hook listener (Orca's pattern): loopback HTTP, token-authed, per-agent routes.
+listener:
+  port: 0            # 0 = pick a free port at first start, persist to endpoint.env
+  spool: true        # spool to disk when listener is unreachable (5 MB cap, 7-day TTL)
+
+# Which agents to manage. \`auto\` = every detected agent on the machine.
+agents: auto        # or an explicit list: [claude, codex, warp]
+
+# Which integrations to install per agent where supported.
+install:
+  hooks: true       # native hook config injection (skipped where the agent has none)
+  skill: true       # heedvane-hooks skill bundle -> ~/.agents/skills/heedvane-hooks/
+  mcp: true         # heedvane MCP server registration (universal fallback, incl. Warp)
+
+# Session gating (Orca's env-gated dispatcher pattern).
+gating:
+  mode: always      # always = every session; pane = only sessions launched with HEED_SESSION env
+
+# The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).
+heedvane:
+  url: https://app.heedvane.com
+  steering: true      # ask the organization's steering rules before tool calls, prompts and stops
+  memory: true        # add your private memories (~/.heed/memory, local only) at session start
+  skills:
+    enforce: true     # deny skills that are not on the organization's approved list
+    strict: false     # also require the local SKILL.md to match the approved revision
+    whenUnknown: allow  # no synced list (run npx heedvane skills sync) or listener down: allow or deny
+`;
+function describeType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "an array";
+    return typeof value;
+}
+function expectMapping(value, key) {
+    if (!isRecord(value)) {
+        throw new HeedFileError(`"${key}" must be a mapping, got ${describeType(value)}`);
+    }
+    return value;
+}
+function rejectUnknownKeys(value, allowed, where) {
+    const unknown = Object.keys(value).filter((k) => !allowed.includes(k));
+    if (unknown.length > 0) {
+        throw new HeedFileError(`"${where}" has unknown key(s): ${unknown.map((k) => JSON.stringify(k)).join(", ")} (allowed: ${allowed.join(", ")})`);
+    }
+}
+function expectBool(value, key) {
+    if (typeof value !== "boolean") {
+        throw new HeedFileError(`"${key}" must be a boolean, got ${describeType(value)}`);
+    }
+    return value;
+}
+function validateListener(raw) {
+    const defaults = { port: 0, spool: true };
+    if (raw === undefined)
+        return defaults;
+    const map = expectMapping(raw, "listener");
+    rejectUnknownKeys(map, ["port", "spool"], "listener");
+    const out = defaults;
+    if (map["port"] !== undefined) {
+        const port = map["port"];
+        if (typeof port !== "number" || !Number.isInteger(port) || port < 0) {
+            throw new HeedFileError(`"listener.port" must be an integer >= 0, got ${describeType(port)}`);
+        }
+        out.port = port;
+    }
+    if (map["spool"] !== undefined)
+        out.spool = expectBool(map["spool"], "listener.spool");
+    return out;
+}
+function validateAgents(raw) {
+    if (raw === undefined)
+        return "auto";
+    if (raw === "auto")
+        return "auto";
+    if (!Array.isArray(raw)) {
+        throw new HeedFileError(`"agents" must be "auto" or a list of agent ids, got ${describeType(raw)}`);
+    }
+    for (const entry of raw) {
+        if (typeof entry !== "string" || entry.trim().length === 0) {
+            throw new HeedFileError(`"agents" entries must be non-empty strings, got ${JSON.stringify(entry) ?? describeType(entry)}`);
+        }
+    }
+    return raw.map((entry) => entry.trim());
+}
+function validateInstall(raw) {
+    const defaults = { hooks: true, skill: true, mcp: true };
+    if (raw === undefined)
+        return defaults;
+    const map = expectMapping(raw, "install");
+    rejectUnknownKeys(map, ["hooks", "skill", "mcp"], "install");
+    const out = defaults;
+    if (map["hooks"] !== undefined)
+        out.hooks = expectBool(map["hooks"], "install.hooks");
+    if (map["skill"] !== undefined)
+        out.skill = expectBool(map["skill"], "install.skill");
+    if (map["mcp"] !== undefined)
+        out.mcp = expectBool(map["mcp"], "install.mcp");
+    return out;
+}
+function validateGating(raw) {
+    const defaults = { mode: "always" };
+    if (raw === undefined)
+        return defaults;
+    const map = expectMapping(raw, "gating");
+    rejectUnknownKeys(map, ["mode"], "gating");
+    const out = defaults;
+    if (map["mode"] !== undefined) {
+        const mode = map["mode"];
+        if (mode !== "pane" && mode !== "always") {
+            throw new HeedFileError(`"gating.mode" must be "pane" or "always", got ${JSON.stringify(mode)}`);
+        }
+        out.mode = mode;
+    }
+    return out;
+}
+function validateSkills(raw) {
+    const out = { enforce: true, strict: false, whenUnknown: "allow" };
+    if (raw === undefined)
+        return out;
+    const map = expectMapping(raw, "heedvane.skills");
+    rejectUnknownKeys(map, ["enforce", "strict", "whenUnknown"], "heedvane.skills");
+    if (map["enforce"] !== undefined)
+        out.enforce = expectBool(map["enforce"], "heedvane.skills.enforce");
+    if (map["strict"] !== undefined)
+        out.strict = expectBool(map["strict"], "heedvane.skills.strict");
+    const whenUnknown = map["whenUnknown"];
+    if (whenUnknown !== undefined) {
+        if (whenUnknown !== "allow" && whenUnknown !== "deny") {
+            throw new HeedFileError(`"heedvane.skills.whenUnknown" must be "allow" or "deny", got ${JSON.stringify(whenUnknown)}`);
+        }
+        out.whenUnknown = whenUnknown;
+    }
+    return out;
+}
+function validateHeedvane(raw) {
+    const out = { url: "https://app.heedvane.com", steering: true, memory: true, skills: validateSkills(undefined) };
+    if (raw === undefined)
+        return out;
+    const map = expectMapping(raw, "heedvane");
+    rejectUnknownKeys(map, ["url", "steering", "memory", "skills"], "heedvane");
+    const url = map["url"];
+    if (url !== undefined) {
+        if (typeof url !== "string" || !URL.canParse(url) || !/^https?:$/.test(new URL(url).protocol)) {
+            throw new HeedFileError(`"heedvane.url" must be an http(s) URL, got ${JSON.stringify(url)}`);
+        }
+        out.url = url.replace(/\/+$/, "");
+    }
+    if (map["steering"] !== undefined)
+        out.steering = expectBool(map["steering"], "heedvane.steering");
+    if (map["memory"] !== undefined)
+        out.memory = expectBool(map["memory"], "heedvane.memory");
+    out.skills = validateSkills(map["skills"]);
+    return out;
+}
+/**
+ * Parse and validate a heed.yaml document, returning the fully normalized file.
+ * Throws {@link HeedFileError} (message prefixed "invalid heed.yaml:") on any problem:
+ * unparseable YAML, non-mapping root, missing/unknown schemaVersion, unknown keys
+ * (top-level or nested), or wrong-typed values.
+ */
+export function loadHeedFile(text) {
+    let raw;
+    try {
+        raw = parse(text);
+    }
+    catch (err) {
+        const reason = errorMessage(err);
+        throw new HeedFileError(`could not parse YAML — ${reason}`);
+    }
+    if (!isRecord(raw)) {
+        throw new HeedFileError(`expected a top-level mapping, got ${describeType(raw)}`);
+    }
+    const schemaVersion = raw["schemaVersion"];
+    if (schemaVersion === undefined) {
+        throw new HeedFileError(`missing required key "schemaVersion" (expected "v1")`);
+    }
+    if (schemaVersion !== "v1") {
+        throw new HeedFileError(`unsupported schemaVersion ${JSON.stringify(schemaVersion)} — this CLI supports "v1" only (key: schemaVersion)`);
+    }
+    rejectUnknownKeys(raw, TOP_LEVEL_KEYS, "top level");
+    const root = raw["root"];
+    if (root !== undefined && (typeof root !== "string" || root.trim().length === 0)) {
+        throw new HeedFileError(`"root" must be a non-empty string, got ${describeType(root)}`);
+    }
+    return {
+        schemaVersion: "v1",
+        root: root === undefined ? "~/.heed" : root,
+        listener: validateListener(raw["listener"]),
+        agents: validateAgents(raw["agents"]),
+        install: validateInstall(raw["install"]),
+        gating: validateGating(raw["gating"]),
+        heedvane: validateHeedvane(raw["heedvane"]),
+    };
+}
+/** `text` with `heedvane.url` set to `url` (`connect --server`); the file's comments stay. Validate with {@link loadHeedFile}. */
+export function withServerUrl(text, url) {
+    const document = parseDocument(text);
+    const current = document.getIn(["heedvane", "url"], true);
+    if (isScalar(current))
+        current.value = url;
+    else
+        document.setIn(["heedvane", "url"], url);
+    return String(document);
+}
+/** `text` with the installer's choices written into the fields that already hold them; the file's comments stay. */
+export function withInstallChoices(text, choices) {
+    const document = parseDocument(text);
+    const fields = [
+        [["agents"], choices.agents],
+        [["install", "hooks"], choices.install.hooks],
+        [["install", "skill"], choices.install.skill],
+        [["install", "mcp"], choices.install.mcp],
+        [["heedvane", "steering"], choices.steering],
+        [["heedvane", "memory"], choices.memory],
+        [["heedvane", "skills", "enforce"], choices.skillChecks],
+    ];
+    for (const [path, value] of fields) {
+        const current = document.getIn(path, true);
+        if (isScalar(current) && typeof value !== "object")
+            current.value = value;
+        else
+            document.setIn(path, value);
+    }
+    return String(document);
+}
+/** Keys earlier versions wrote into heed.yaml that nothing reads any more (policies are assigned on the server). */
+const RETIRED_KEYS = [["heedvane", "steeringTimeoutMs"], ["policy"]];
+const toStderr = (line) => void process.stderr.write(`${line}\n`);
+/**
+ * Load the heed.yaml at `path`. A retired key an earlier version wrote (`init` put `steeringTimeoutMs`
+ * in every heed.yaml) is removed from the file in place, its value never read, and one line says so; if
+ * the file cannot be rewritten the key is ignored in memory and the line says that instead.
+ */
+export function loadHeedFileAt(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);
+    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));
+    }
+    // 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)));
+}
+/** Writes the document over `path`; the error that stopped it, or null. */
+function rewriteInPlace(path, document) {
+    try {
+        writeFileAtomic.sync(path, String(document), { mode: 0o600 });
+        return null;
+    }
+    catch (err) {
+        return err ?? new Error("write refused");
+    }
+}
+/** A parsed heed.yaml less the retired keys. */
+function withoutKeys(value, retired) {
+    if (!isRecord(value))
+        return value;
+    const kept = Object.fromEntries(Object.entries(value).filter(([key]) => !retired.some((path) => path.length === 1 && path[0] === key)));
+    const heedvane = kept["heedvane"];
+    if (!isRecord(heedvane))
+        return kept;
+    const nested = retired.filter((path) => path.length === 2 && path[0] === "heedvane").map((path) => path[1]);
+    return { ...kept, heedvane: Object.fromEntries(Object.entries(heedvane).filter(([key]) => !nested.includes(key))) };
+}
+/** heed.yaml's `heedvane` section under `root`; the template's defaults before init has written one. */
+export function heedvaneConfigAt(root) {
+    try {
+        return loadHeedFileAt(join(root, "heed.yaml")).heedvane;
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+        return loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE).heedvane;
+    }
+}

package/dist/installer.d.ts

@@ -0,0 +1,47 @@
+import type { Readable, Writable } from "node:stream";
+import type { HeedFile, InstallChoices } from "./heed-file.js";
+import type { PlannedAction } from "./plan.js";
+import { type AppliedResult } from "./render.js";
+/** Where the questions are read and drawn: the process's terminal unless a test injects streams. */
+export interface PromptStreams {
+    input?: Readable;
+    output?: Writable;
+}
+/** One coding agent the installer can offer. */
+export interface AgentOption {
+    id: string;
+    name: string;
+    detected: boolean;
+    /** What Heedvane installs into it, e.g. "hooks + MCP + skill". */
+    capability: string;
+}
+/** One agent's line in the summary or the result: what is, or was, installed into it. */
+export interface AgentLine {
+    name: string;
+    parts: string[];
+    /** What failed, each with its reason; empty when everything worked. */
+    failed: string[];
+}
+/** The header: the name, what Heedvane does, and which server and organization this install connects to. */
+export declare function brandIntro(server: string, org: string | undefined, streams: PromptStreams): void;
+/** The person's choices, or null when they cancelled (Ctrl-C) at any question. */
+export declare function askChoices(agents: AgentOption[], current: HeedFile, streams: PromptStreams): Promise<InstallChoices | null>;
+/** Shows what the install will do and asks to go ahead; false when the person declines or cancels. */
+export declare function confirmInstall(agents: AgentLine[], streams: PromptStreams): Promise<boolean>;
+/** 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. */
+export declare function showInstalled(agents: AgentLine[], streams: PromptStreams): void;
+/** 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>;
+/**
+ * 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.
+ */
+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;

package/dist/installer.js

@@ -0,0 +1,174 @@
+/**
+ * The interactive installer's questions (`npx heedvane`, or `connect` at a terminal): which coding agents,
+ * what to install into them, which Heedvane features to turn on, then one confirmation. It only asks:
+ * the answers become `InstallChoices`, which cli.ts writes into heed.yaml and applies through the same
+ * plan as every other install, so a second run starts from the last answers.
+ */
+import { cancel, confirm, intro, isCancel, log, multiselect, note, outro, spinner } from "@clack/prompts";
+import { styleText } from "node:util";
+import { appliedFailed } from "./render.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) {
+    intro(brandBadge(" Heedvane ", streams.output ?? process.stdout), streams);
+    const target = org === undefined ? server : `${server} · organization ${org}`;
+    log.message([styleText("bold", "Guardrails, skill checks and team memory for your coding agents."), styleText("dim", `Connecting to ${target}`)], streams);
+}
+/** The person's choices, or null when they cancelled (Ctrl-C) at any question. */
+export async function askChoices(agents, current, streams) {
+    const picked = await pickAgents(agents, current, streams);
+    if (picked === null)
+        return null;
+    const install = await pickIntegrations(current.install, streams);
+    if (install === null)
+        return null;
+    const features = await pickFeatures(current, streams);
+    if (features === null)
+        return null;
+    return {
+        agents: sameAsDetected(picked, agents) ? "auto" : picked,
+        install,
+        steering: features.includes("steering"),
+        skillChecks: features.includes("skillChecks"),
+        memory: features.includes("memory"),
+    };
+}
+/** Shows what the install will do and asks to go ahead; false when the person declines or cancels. */
+export async function confirmInstall(agents, streams) {
+    const footer = styleText("dim", "Choices are saved in ~/.heed/heed.yaml. Each config file is backed up before it changes.");
+    note([...agentRows(agents), "", footer].join("\n"), "Ready to install", streams);
+    const answer = await confirm({ message: "Install now?", initialValue: true, ...streams });
+    return !isCancel(answer) && answer;
+}
+/** Runs the install behind a spinner; the spinner ends with the outcome either way. */
+export async function installWithSpinner(agentCount, work, streams) {
+    const progress = spinner({ output: streams.output });
+    progress.start(`Installing into ${agentCount} ${agentCount === 1 ? "agent" : "agents"}`);
+    try {
+        const result = await work();
+        progress.stop("Installed");
+        return result;
+    }
+    catch (err) {
+        progress.error("The install stopped");
+        throw err;
+    }
+}
+/** One line per agent: a green tick and what it got, or what failed and why. */
+export function showInstalled(agents, streams) {
+    const width = Math.max(...agents.map((agent) => agent.name.length));
+    for (const agent of agents) {
+        const name = styleText("bold", agent.name.padEnd(width));
+        if (agent.failed.length > 0)
+            log.error(`${name}  ${agent.failed.join("; ")}`, streams);
+        else
+            log.success(`${name}  ${agent.parts.join(styleText("dim", " · "))}`, streams);
+    }
+}
+/** A line the install prints along the way (the sign-in link, for one), shown inside the installer's frame. */
+export function promptLine(streams) {
+    return (line) => {
+        if (line.trim() !== "")
+            log.message(line.trim(), streams);
+    };
+}
+/** Starts the listener in the background behind a spinner; true when it answers. */
+export async function listenerStep(start, logPath, streams) {
+    const progress = spinner({ output: streams.output });
+    progress.start("Starting Heedvane in the background");
+    const started = await start().catch(() => false);
+    if (started)
+        progress.stop("Heedvane is running in the background");
+    else
+        progress.error(`Heedvane did not start; see ${logPath}`);
+    return started;
+}
+/**
+ * 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.
+ */
+export function agentLines(actions, names, applied = []) {
+    const ids = [...new Set(actions.map((action) => action.clientId))];
+    return ids.map((id) => {
+        const parts = agentParts(id, actions.filter((action) => action.clientId === id));
+        const failed = applied.filter((result) => result.clientId === id && appliedFailed(result))
+            .map((result) => `${result.kind}: ${result.reason ?? result.status}`);
+        return { name: names.get(id) ?? id, parts, failed };
+    });
+}
+/** The closing line after a cancel or a "no": nothing was written. Returns the exit code, 1. */
+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) {
+    note(lines.join("\n"), "Next", streams);
+    outro("Heedvane is set up.", streams);
+}
+async function pickAgents(agents, current, streams) {
+    const ordered = [...agents.filter((agent) => agent.detected), ...agents.filter((agent) => !agent.detected)];
+    const chosenBefore = current.agents === "auto" ? agents.filter((agent) => agent.detected).map((agent) => agent.id) : current.agents;
+    const answer = await multiselect({
+        message: "Which coding agents should Heedvane connect to?",
+        options: ordered.map((agent) => ({ value: agent.id, label: agent.name, hint: agent.detected ? agent.capability : "not found on this machine" })),
+        initialValues: chosenBefore.filter((id) => agents.some((agent) => agent.id === id)),
+        required: true,
+        ...streams,
+    });
+    return isCancel(answer) ? null : answer;
+}
+async function pickIntegrations(install, streams) {
+    const answer = await multiselect({
+        message: "What should Heedvane add to each agent?",
+        options: [
+            { value: "hooks", label: "Hooks", hint: "guardrails, skill checks and memory in every session" },
+            { value: "mcp", label: "MCP server", hint: "Heedvane's tools inside the agent" },
+            { value: "skill", label: "Skill", hint: "teaches the agent how to use Heedvane" },
+        ],
+        initialValues: ["hooks", "mcp", "skill"].filter((kind) => install[kind]),
+        required: true,
+        ...streams,
+    });
+    if (isCancel(answer))
+        return null;
+    return { hooks: answer.includes("hooks"), mcp: answer.includes("mcp"), skill: answer.includes("skill") };
+}
+async function pickFeatures(current, streams) {
+    const on = { steering: current.heedvane.steering, skillChecks: current.heedvane.skills.enforce, memory: current.heedvane.memory };
+    const answer = await multiselect({
+        message: "What should Heedvane do in each session?",
+        options: [
+            { value: "steering", label: "Guardrails", hint: "your organization's rules stop risky tool calls" },
+            { value: "skillChecks", label: "Skill checks", hint: "only skills your organization approved run" },
+            { value: "memory", label: "Private memory", hint: "your notes in ~/.heed/memory at session start" },
+        ],
+        initialValues: Object.keys(on).filter((feature) => on[feature]),
+        required: false,
+        ...streams,
+    });
+    return isCancel(answer) ? null : answer;
+}
+/** `text` on Heedvane's indigo (the dashboard's --brand) where the terminal shows 24-bit color, else on magenta. */
+function brandBadge(text, output) {
+    const truecolor = "hasColors" in output && typeof output.hasColors === "function" && output.hasColors(2 ** 24) === true;
+    return truecolor ? `\x1b[48;2;86;71;210m\x1b[1;97m${text}\x1b[0m` : styleText(["bgMagenta", "white", "bold"], text);
+}
+/** 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");
+    if (installs.length === 0)
+        return own.map((action) => styleText("dim", action.reason?.replace(`${id}: `, "") ?? "nothing to add"));
+    if (installs.every((action) => action.operation === "unchanged"))
+        return [styleText("dim", "already set up")];
+    return installs.map((action) => INTEGRATION_LABEL[action.kind]);
+}
+function agentRows(agents) {
+    const width = Math.max(...agents.map((agent) => agent.name.length));
+    return agents.map((agent) => `${styleText("bold", agent.name.padEnd(width))}  ${agent.parts.join(styleText("dim", " · "))}`);
+}
+/** True when exactly the detected agents were chosen: heed.yaml then keeps `auto`, so a newly installed agent joins later. */
+function sameAsDetected(picked, agents) {
+    const detected = agents.filter((agent) => agent.detected).map((agent) => agent.id);
+    return picked.length === detected.length && detected.every((id) => picked.includes(id));
+}

package/dist/listener/background.d.ts

@@ -0,0 +1,8 @@
+/** Where a background listener writes what it prints. */
+export declare function listenerLogPath(root: string): 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).
+ */
+export declare function startListenerInBackground(home: string, cliPath: string, env: NodeJS.ProcessEnv): Promise<boolean>;

package/dist/listener/background.js

@@ -0,0 +1,36 @@
+import { spawn } from "node:child_process";
+import { closeSync, openSync } 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;
+/** 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).
+ */
+export async function startListenerInBackground(home, cliPath, env) {
+    const root = join(home, ".heed");
+    const endpoint = await ensureEndpoint(root);
+    if (await pingListener(endpoint))
+        return true;
+    const log = openSync(listenerLogPath(root), "a", 0o600);
+    try {
+        spawn(process.execPath, [cliPath, "listener", "start"], { detached: true, stdio: ["ignore", log, log], env: { ...env, HEED_HOME: home } }).unref();
+    }
+    finally {
+        closeSync(log);
+    }
+    for (let waited = 0; waited < START_WAIT_MS; waited += START_POLL_MS) {
+        await delay(START_POLL_MS);
+        if (await pingListener(endpoint))
+            return true;
+    }
+    return false;
+}

package/dist/listener/endpoint.d.ts

@@ -0,0 +1,26 @@
+/** The listener's loopback endpoint, persisted under the heed root. */
+export interface Endpoint {
+    port: number;
+    token: string;
+}
+/** Path of the endpoint file: `root/endpoint.env`. */
+export declare function endpointPath(root: string): string;
+/**
+ * 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 declare function readEndpoint(root: string): Promise<Endpoint | null>;
+/** Atomically write `root/endpoint.env` (mode 0600) with the port and token lines. */
+export declare function writeEndpoint(root: string, endpoint: Endpoint): Promise<void>;
+/**
+ * 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>;
+/**
+ * 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 declare function pingListener(endpoint: Endpoint): Promise<boolean>;