heedvane 0.1.0 → 0.2.0

package/README.md

@@ -1,28 +1,63 @@
 # heedvane
 
-Connect the coding agents on your machine to your Heedvane organization: steering rules, approved-skill
+Connect the coding agents on your machine to your Heedvane organization: guardrails, approved-skill
 checks and team memory for Claude Code, Codex, Cursor, Gemini CLI, Hermes, OpenCode and more.
 
 ```sh
-npx heedvane connect --server https://app.heedvane.com --org <organization id>
+npx heedvane
 ```
 
-Copy the exact command from the Agents page of your Heedvane dashboard. It needs Node.js 22 or newer.
+The installer shows the agents it found on your machine. Tick the ones you want, choose what Heedvane
+adds and does, confirm. It installs, starts Heedvane in the background and signs you in through the
+browser. It needs Node.js 22 or newer.
+
+Your dashboard's Agents page has the same command with your server and organization filled in:
+
+```sh
+npx heedvane connect --server https://app.heedvane.com --org <organization id>
+```
 
 ## What it changes
 
-- Writes `~/.heed/heed.yaml`, your control file. Edit it any time, then run `npx heedvane setup`.
-- Adds Heedvane's hooks, MCP server entry and skill to each agent it detects. A config file it edits is
+- Writes `~/.heed/heed.yaml`, your control file, with your answers. Run `npx heedvane` again to change
+  them.
+- Adds Heedvane's hooks, MCP server entry and skill to each agent you ticked. A config file it edits is
   backed up first.
-- Signs you in through the browser. Headless machines use `npx heedvane auth org < key-file`.
+- Starts Heedvane's local listener, which answers the hooks. After a restart the hooks start it again by
+  themselves, at most once a minute. Set `HEED_LISTENER_AUTOSTART=0` to turn that off.
 
 Run `npx heedvane connect --dry-run` to see every file it would touch without writing anything.
 
+## Software factories, CI and containers
+
+Agents that run unattended (a factory looping on a server, a CI job, a container on AWS) use the same
+package without the installer:
+
+```sh
+# Once, when you build the image: install the hooks for the agent the factory runs
+npx -y heedvane connect --server https://app.heedvane.com --org <organization id> --agent claude --yes
+
+# When the container starts: sign in with an organization key from your secret store
+printf '%s' "$HEEDVANE_ORG_KEY" | npx heedvane auth org
+
+# Every agent run: Heedvane answers the hooks for exactly this run
+npx heedvane run -- claude -p "fix the failing tests"
+```
+
+`run` keeps the agent's terminal output and exit code, so your pipeline reads them as before. Heedvane's
+own lines go to stderr and `~/.heed/listener.log`.
+
+- Claude Code runs the hooks in print mode (`claude -p`), but not with `--bare`.
+- Codex runs hooks only after they are trusted.
+- Pi and Flue agents cannot be connected yet.
+
 ## Everyday commands
 
 | Command | What it does |
 | --- | --- |
-| `npx heedvane listener start` | Runs the local listener that answers the hooks. Keep it running. |
+| `npx heedvane` | Opens the installer: change agents and features any time. |
 | `npx heedvane doctor` | Checks the install and prints a fix for each problem. |
+| `npx heedvane listener start` | Runs the listener in the foreground. |
+| `npx heedvane run -- <command>` | Runs one agent with Heedvane, for CI and containers. |
 | `npx heedvane uninstall` | Removes only the entries Heedvane added. `heed.yaml` stays. |
 | `npx heedvane --help` | Lists every command and flag. |

package/dist/cli.d.ts

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { type PromptStreams } from "./installer.js";
 export interface MainOptions {
     /** Env override (tests inject HEED_HOME fixtures). Defaults to process.env. */
     env?: Record<string, string | undefined>;
@@ -12,6 +13,10 @@ export interface MainOptions {
     cwd?: string;
     /** May init/setup start a browser sign-in? Defaults to whether a person is at the terminal. */
     interactive?: boolean;
+    /** Where the interactive installer reads keys and draws; defaults to the terminal (tests inject streams). */
+    prompts?: PromptStreams;
+    /** Starts the listener in the background for the installer; defaults to a detached `listener start` (tests pass a stand-in). */
+    startListener?: (home: string) => Promise<boolean>;
 }
 declare function main(argv: string[], opts?: MainOptions): Promise<number>;
 /** All of stdin as text (where `auth` reads its key). */

package/dist/cli.js

@@ -4,16 +4,16 @@
  * listener | status | mcp. Plain argv parsing (no commander); all state
  * mutations flow through plan → apply; --dry-run writes nothing.
  */
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { createWriteStream, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
 import { spawn } from "node:child_process";
-import { homedir, platform } from "node:os";
-import { join } from "node:path";
+import { constants as osConstants, homedir, platform } from "node:os";
+import { dirname, join } from "node:path";
 import { supportedClients } from "./clients/definitions.js";
 import { installHermesPlugin } from "./clients/hermes-plugin.js";
 import { applyEntry } from "./apply.js";
-import { DEFAULT_HEED_YAML_TEMPLATE, loadHeedFile, loadHeedFileAt, withServerUrl } from "./heed-file.js";
+import { DEFAULT_HEED_YAML_TEMPLATE, heedvaneConfigAt, loadHeedFile, loadHeedFileAt, withInstallChoices, withServerUrl } from "./heed-file.js";
 import { planActions, desiredEntriesFor, isClientDetected } from "./plan.js";
-import { appliedFailed, renderApplied, renderDetection, renderPlan, wouldInstallSummary } from "./render.js";
+import { appliedFailed, capabilitySummary, renderApplied, renderDetection, renderPlan, wouldInstallSummary } from "./render.js";
 import { runDoctor } from "./doctor.js";
 import { installSkill } from "./skill/bundle.js";
 import { canonicalSkillFiles, skillDigest } from "./skill/content.js";
@@ -23,17 +23,21 @@ import { removeDeferredHookGroups, removeStaleHookGroups, uninstall } from "./un
 import { statusText, runMcpStdio } from "./mcp-server.js";
 import { errorMessage } from "./guards.js";
 import { ensureEndpoint } from "./listener/endpoint.js";
+import { listenerLogPath, startListenerInBackground } from "./listener/background.js";
 import { serveHooks } from "./listener/serve.js";
 import { cmdAuth, cmdLogin, cmdSkills } from "./commands/heedvane.js";
 import { cmdMemory } from "./commands/memory.js";
 import { backendAt } from "./backend/credentials.js";
 import { readLogin } from "./backend/login.js";
+import { agentLines, askChoices, brandIntro, confirmInstall, installCancelled, installFinished, installWithSpinner, listenerStep, promptLine, showInstalled } from "./installer.js";
 const USAGE = `  heedvane-hook — cross-agent steering, guardrails & analysis
 
-  Usage: npx heedvane <command> [flags]   (installed: heedvane <command>)
+  Usage: npx heedvane [command] [flags]   (installed: heedvane <command>)
+         npx heedvane on its own, at a terminal, opens the installer: tick agents and features, confirm.
 
   Commands:
-    connect         one-step setup: write ~/.heed/heed.yaml, configure detected CLI & GUI agents, and sign in
+    connect         set up this machine: the installer at a terminal; with --yes (or in a script) every detected agent at once
+    run -- <cmd>    CI, containers and software factories: Heedvane answers the hooks for the length of one agent run
     init            write ~/.heed/heed.yaml (if missing), plan, apply
     setup           plan + apply from an existing heed.yaml
     doctor          scoped, remediation-carrying health check
@@ -100,6 +104,8 @@ function parseInvocation(args) {
 async function main(argv, opts = {}) {
     const ctx = commandContext(argv, opts);
     const command = ctx.positional[0];
+    if (command === undefined && takesInstaller(ctx))
+        return cmdInstall(ctx);
     if (!command || command === "help" || command === "--help") {
         ctx.out(USAGE);
         return command ? 0 : 2;
@@ -119,12 +125,14 @@ function commandContext(argv, opts) {
         openBrowser: opts.openBrowser ?? openSystemBrowser,
         interactive: opts.interactive ?? (process.stdin.isTTY === true && process.stdout.isTTY === true),
         cwd: opts.cwd ?? process.cwd(),
+        prompts: opts.prompts ?? {},
+        startListener: opts.startListener ?? ((home) => startListenerInBackground(home, fileURLToPath(import.meta.url), env)),
     };
 }
 async function routeCommand(command, ctx) {
     switch (command) {
         case "connect":
-            return cmdInit({ ...ctx, flags: { ...ctx.flags, yes: true } });
+            return takesInstaller(ctx) ? cmdInstall(ctx) : cmdInit({ ...ctx, flags: { ...ctx.flags, yes: true } });
         case "init":
             return cmdInit(ctx);
         case "setup":
@@ -150,6 +158,8 @@ async function routeServiceCommand(command, ctx) {
         case "listener": {
             return cmdListener({ home: ctx.home, out: ctx.out, rest: ctx.args.slice(ctx.args.indexOf("listener") + 1) });
         }
+        case "run":
+            return cmdRun({ home: ctx.home, env: ctx.env, command: ctx.args.slice(ctx.args.indexOf("--") + 1), separated: ctx.args.includes("--") });
         case "login":
             return cmdLogin(backendCommandContext(ctx));
         case "auth":
@@ -235,15 +245,39 @@ async function cmdInit(ctx) {
 }
 /** heed.yaml (or the template) with `--server` as `heedvane.url`; null when it already names that server. Throws on an unusable URL. */
 function withServer(home, loaded, server) {
-    const current = loaded.existed ? readFileSync(join(home, ".heed", "heed.yaml"), "utf8") : DEFAULT_HEED_YAML_TEMPLATE;
-    const text = withServerUrl(current, server);
+    const text = withServerUrl(heedText(home, loaded.existed), server);
     const heedFile = loadHeedFile(text);
     if (loaded.existed && heedFile.heedvane.url === loaded.heedFile.heedvane.url)
         return null;
     return { heedFile, existed: loaded.existed, text };
 }
 async function applyAndReport(ctx, spec) {
-    const { home, env, out, flags } = ctx;
+    const { out, flags } = ctx;
+    const { actions, applied } = await installPlan(ctx, spec);
+    for (const line of renderApplied(applied))
+        out(line);
+    if (!flags.dryRun)
+        await signInIfNeeded(ctx, spec.heedFile.heedvane.url);
+    out("");
+    out("  Next: open a new agent session and run /heedvane-status.");
+    out("  Re-run `npx heedvane doctor` after any heed.yaml edit.");
+    const failed = applied.some(appliedFailed);
+    if (flags.json)
+        outJson(out, { status: failed ? "failed" : "applied", plannedActions: actions, appliedActions: applied });
+    return failed ? 1 : 0;
+}
+/** Writes heed.yaml when it is missing, or when `--server` changed its URL. */
+function writeControlFile({ home, out }, { heedFile, existed, text }) {
+    if (existed && text === undefined)
+        return;
+    mkdirSync(join(home, ".heed"), { recursive: true, mode: 0o700 });
+    writeFileSync(join(home, ".heed", "heed.yaml"), text ?? DEFAULT_HEED_YAML_TEMPLATE, { mode: 0o600 });
+    out(existed ? `  ✓ Set heedvane.url in ~/.heed/heed.yaml to ${heedFile.heedvane.url}` : `  ✓ Wrote ~/.heed/heed.yaml (your control file — edit any time)`);
+}
+/** Without a sign-in to `url` (and to `--org`, when named), sign in now when a person is at the terminal, else say how. Never fails setup. */
+/** Writes heed.yaml, applies the plan, issues the listener endpoint and records the machine state. Prints only what applying prints. */
+async function installPlan(ctx, spec) {
+    const { home, env, out } = ctx;
     const { heedFile, agents } = spec;
     // The control file comes first (mock order): "✓ Wrote ~/.heed/heed.yaml".
     writeControlFile(ctx, spec);
@@ -251,12 +285,11 @@ async function applyAndReport(ctx, spec) {
     const dispatcher = {
         denySkillsWhenUnchecked: heedFile.heedvane.skills.enforce && heedFile.heedvane.skills.whenUnknown === "deny",
         gating: heedFile.gating.mode,
+        nodeDir: dirname(process.execPath),
     };
     const applied = await applyPlan(actions, { home, env, out, dispatcher });
     // The listener port and token every dispatcher reads; kept once issued.
     await ensureEndpoint(join(home, ".heed"));
-    for (const line of renderApplied(applied))
-        out(line);
     // Machine state: CLI-owned; preserve an existing endpoint.
     const root = join(home, ".heed");
     const existing = await readState(root);
@@ -266,25 +299,8 @@ async function applyAndReport(ctx, spec) {
     if (skillInstalled)
         state.skill = { version: "1", digest: skillDigest(canonicalSkillFiles()) };
     await writeStateAtomic(root, state);
-    if (!flags.dryRun)
-        await signInIfNeeded(ctx, heedFile.heedvane.url);
-    out("");
-    out("  Next: open a new agent session and run /heedvane-status.");
-    out("  Re-run `npx heedvane doctor` after any heed.yaml edit.");
-    const failed = applied.some(appliedFailed);
-    if (flags.json)
-        outJson(out, { status: failed ? "failed" : "applied", plannedActions: actions, appliedActions: applied });
-    return failed ? 1 : 0;
+    return { actions, applied };
 }
-/** Writes heed.yaml when it is missing, or when `--server` changed its URL. */
-function writeControlFile({ home, out }, { heedFile, existed, text }) {
-    if (existed && text === undefined)
-        return;
-    mkdirSync(join(home, ".heed"), { recursive: true, mode: 0o700 });
-    writeFileSync(join(home, ".heed", "heed.yaml"), text ?? DEFAULT_HEED_YAML_TEMPLATE, { mode: 0o600 });
-    out(existed ? `  ✓ Set heedvane.url in ~/.heed/heed.yaml to ${heedFile.heedvane.url}` : `  ✓ Wrote ~/.heed/heed.yaml (your control file — edit any time)`);
-}
-/** Without a sign-in to `url` (and to `--org`, when named), sign in now when a person is at the terminal, else say how. Never fails setup. */
 async function signInIfNeeded(ctx, url) {
     const root = join(ctx.home, ".heed");
     if ((await backendAt(root, url)) !== null && (await onRequestedOrg(root, ctx.org)))
@@ -335,6 +351,67 @@ async function cmdSetup(ctx) {
     }
     return applyAndReport(ctx, { heedFile, agents: ctx.agents, existed: true });
 }
+/** A person at a terminal who did not ask for the one-shot path (`--yes`, `--dry-run`, `--json`) or for help. */
+function takesInstaller(ctx) {
+    return ctx.interactive && !ctx.flags.yes && !ctx.flags.dryRun && !ctx.flags.json && !ctx.args.includes("--help");
+}
+/** heed.yaml's text, or the template when there is none yet. */
+function heedText(home, existed) {
+    return existed ? readFileSync(join(home, ".heed", "heed.yaml"), "utf8") : DEFAULT_HEED_YAML_TEMPLATE;
+}
+/** The installer: pick agents, integrations and features, confirm, install, start the listener, sign in. */
+async function cmdInstall(ctx) {
+    const base = installerBase(ctx);
+    if (typeof base === "string") {
+        ctx.out(`  ✗ ${base}`);
+        return 1;
+    }
+    const { prompts } = ctx;
+    brandIntro(base.heedFile.heedvane.url, ctx.org, prompts);
+    const choices = await askChoices(agentOptions(ctx), base.heedFile, prompts);
+    if (choices === null)
+        return installCancelled(prompts);
+    const text = withInstallChoices(base.text, choices);
+    const spec = { heedFile: loadHeedFile(text), agents: choices.agents === "auto" ? [] : choices.agents, existed: base.existed, text };
+    const names = new Map(detectionRows(ctx.home, ctx.env).map((row) => [row.client.id, row.client.displayName]));
+    const planned = agentLines(planFor({ home: ctx.home, env: ctx.env, ...spec }), names);
+    if (!(await confirmInstall(planned, prompts)))
+        return installCancelled(prompts);
+    const notes = [];
+    const { actions, applied } = await installWithSpinner(planned.length, () => installPlan({ ...ctx, out: (line) => notes.push(line) }, spec), prompts);
+    notes.forEach(promptLine(prompts));
+    showInstalled(agentLines(actions, names, applied), prompts);
+    const listening = await listenerStep(() => ctx.startListener(ctx.home), listenerLogPath(join(ctx.home, ".heed")), prompts);
+    await signInIfNeeded({ ...ctx, out: promptLine(prompts) }, spec.heedFile.heedvane.url);
+    installFinished(nextSteps(listening, spec.heedFile.heedvane.url), prompts);
+    return applied.some(appliedFailed) ? 1 : 0;
+}
+/** heed.yaml's current text (or the template) with `--server` applied, parsed; a message when either cannot be used. */
+function installerBase({ home, server }) {
+    const loaded = loadOrTemplate(home);
+    if (loaded.error)
+        return `~/.heed/heed.yaml does not parse: ${loaded.error}`;
+    try {
+        const current = heedText(home, loaded.existed);
+        const text = server === undefined ? current : withServerUrl(current, server);
+        return { heedFile: loadHeedFile(text), existed: loaded.existed, text };
+    }
+    catch (err) {
+        return `--server ${server} cannot be used: ${errorMessage(err)}`;
+    }
+}
+function agentOptions({ home, env }) {
+    return detectionRows(home, env).map(({ client, detected }) => ({ id: client.id, name: client.displayName, detected, capability: capabilitySummary(client) }));
+}
+function nextSteps(listening, server) {
+    return [
+        "Open a new agent session: Heedvane joins it at session start.",
+        `Watch your sessions: ${server}`,
+        ...(listening ? [] : ["Heedvane starts by itself with your next agent session. To see why it did not start now: npx heedvane listener start"]),
+        "Check the install: npx heedvane doctor",
+        "Change your choices: npx heedvane",
+    ];
+}
 /** Hermes' hooks capability rides its native plugin; installHermesPlugin owns creation and ownership checks. */
 async function applyHermesPlugin(client, ctx) {
     const path = join(ctx.home, ".hermes", "plugins", "heedvane-hooks", "plugin.yaml");
@@ -499,6 +576,51 @@ async function cmdListener(ctx) {
     });
     return 0;
 }
+/**
+ * `run -- <agent command>`: a listener for exactly one agent run, for CI, containers and software
+ * factories where nothing stays running. The agent keeps stdin, stdout and stderr; the listener writes to
+ * ~/.heed/listener.log and Heedvane's own lines go to stderr, so an agent's JSON output stays parseable.
+ * Returns the agent's exit code (128 + signal number when a signal ended it).
+ */
+async function cmdRun(ctx) {
+    const say = (line) => void process.stderr.write(`heedvane: ${line}\n`);
+    if (!ctx.separated || ctx.command.length === 0) {
+        say('usage: npx heedvane run -- <agent command>, e.g. npx heedvane run -- claude -p "fix the failing tests"');
+        return 2;
+    }
+    const root = join(ctx.home, ".heed");
+    mkdirSync(root, { recursive: true, mode: 0o700 }); // a fresh container has no ~/.heed yet
+    const log = createWriteStream(listenerLogPath(root), { flags: "a", mode: 0o600 });
+    const started = await serveHooks(ctx.home, (line) => void log.write(`${line}\n`));
+    if ((await backendAt(root, heedvaneConfigAt(root).url)) === null)
+        say("not signed in, so guardrails are off: printf '%s' \"$HEEDVANE_ORG_KEY\" | npx heedvane auth org");
+    say(`listening on 127.0.0.1:${started.port}; log: ${listenerLogPath(root)}`);
+    try {
+        // The agent's hooks find this listener's endpoint through HEED_AGENT_HOOK_ROOT, also when HEED_HOME is not $HOME.
+        return await runAgent(ctx.command, { ...ctx.env, HEED_HOME: ctx.home, HEED_AGENT_HOOK_ROOT: root }, say);
+    }
+    finally {
+        await new Promise((resolve) => started.server.close(() => resolve()));
+        await new Promise((resolve) => log.end(resolve));
+    }
+}
+/** Runs the agent with this process's terminal, passes Ctrl-C and `docker stop` on to it, and resolves with its exit code. */
+function runAgent([program, ...args], env, say) {
+    return new Promise((resolve) => {
+        const child = spawn(program, args, { stdio: "inherit", env });
+        const forward = (signal) => void child.kill(signal);
+        process.on("SIGINT", forward).on("SIGTERM", forward);
+        const settle = (code) => {
+            process.off("SIGINT", forward).off("SIGTERM", forward);
+            resolve(code);
+        };
+        child.on("error", (err) => {
+            say(`could not start ${program}: ${errorMessage(err)}`);
+            settle(127);
+        });
+        child.on("exit", (code, signal) => settle(code ?? 128 + (signal === null ? 0 : osConstants.signals[signal])));
+    });
+}
 function backendCommandContext(ctx) {
     return { home: ctx.home, out: ctx.out, words: ctx.positional.slice(1), project: ctx.args.includes("--project"), readStdin: ctx.readStdin, openBrowser: ctx.openBrowser };
 }

package/dist/dispatchers/posix.d.ts

@@ -17,6 +17,12 @@ import type { HeedGatingConfig } from "../heed-file.js";
  * X-Heed-Agent-Hook-Token and X-Heed-Hook-Version: 1, 0.5s connect / 0.8s max, falling back to spool
  * on any failure. The listener answers from this machine alone; only a session start waits (2s max)
  * for the session's one fetch of the steering policy.
+ *
+ * Start on the fly: when nothing listens on the port (curl exit 7, connection refused), the event is
+ * spooled and `npx -y heedvane listener start` is started in the background, at most once a minute
+ * (a `listener.starting` lock directory older than a minute is cleared). The listener replays the
+ * spool when it starts, so steering comes back by itself after a restart; no login service is needed.
+ * `HEED_LISTENER_AUTOSTART=0` in the agent's environment turns this off.
  */
 export interface DispatcherOptions {
     /** heed.yaml `heedvane.skills.whenUnknown: deny`: with no listener to check it, deny a skill use. */
@@ -24,6 +30,9 @@ export interface DispatcherOptions {
     /** heed.yaml `gating.mode`: `pane` (the default) runs the hooks only in sessions launched with
      *  HEED_SESSION set; `always` runs them in every session. */
     gating?: HeedGatingConfig["mode"];
+    /** The folder holding node and npx at install time, appended to PATH for the start on the fly:
+     *  an agent launched from a desktop app may run its hooks without them on PATH. */
+    nodeDir?: string;
 }
 export declare function dispatcherScript(agentId: string, options?: DispatcherOptions): string;
 /** The on-disk dispatcher directory under the heed root. */

package/dist/dispatchers/posix.js

@@ -15,6 +15,7 @@ export function dispatcherScript(agentId, options = {}) {
     // Only Claude Code's deny shape is verified; other agents keep the fail-open fallback.
     const denySkills = options.denySkillsWhenUnchecked === true && agentId === "claude";
     const gating = options.gating ?? "always";
+    const nodeDir = (options.nodeDir ?? "").replaceAll("'", "'\\''");
     return `#!/bin/sh
 # heedvane-agent-hook dispatcher for ${agentId} — generated by heedvane-hook. Do not hand-edit.
 # Rewritten wholesale by \`npx heedvane setup\`; policy updates never touch agent configs.
@@ -29,6 +30,7 @@ HEED_HOOK_AGENT="${agentId}"
 HEED_HOOK_VERSION=1
 HEED_HOOK_SPOOL_CAP=5242880
 HEED_HOOK_SPOOL_TTL_DAYS=7
+HEED_HOOK_NODE_DIR='${nodeDir}'
 
 [ -n "\${HOME:-}" ] || exit 0
 
@@ -93,6 +95,19 @@ spool_hook_event() {
   return 0
 }
 
+# Nothing listens (connection refused): start the listener in the background, at most one try a
+# minute, so steering comes back by itself after a restart. It replays the spooled event at its start.
+heed_start_listener() {
+  [ "\${HEED_LISTENER_AUTOSTART:-1}" != "0" ] || return 0
+  _root="\${HEED_HOOK_ENDPOINT_FILE%/*}"
+  case "$_root" in */.heed) ;; *) return 0 ;; esac
+  _lock="$_root/listener.starting"
+  find "$_lock" -maxdepth 0 -mmin +1 -exec rmdir {} \\; 2>/dev/null || :
+  mkdir "$_lock" 2>/dev/null || return 0
+  (PATH="$PATH:$HEED_HOOK_NODE_DIR" HEED_HOME="\${_root%/.heed}" nohup npx -y heedvane listener start < /dev/null >> "$_root/listener.log" 2>&1 &) 2>/dev/null || :
+  return 0
+}
+
 # The hook payload arrives on stdin. command -p keeps cat working under a stripped PATH.
 payload="$(command -p cat 2>/dev/null || cat)"
 
@@ -152,7 +167,9 @@ reply="$(printf '%s' "$payload" | curl -sS --fail -X POST "http://127.0.0.1:\${H
   -H "X-Heed-Hook-Version: \${HEED_HOOK_VERSION}" \\
   -H "X-Heed-Event-Id: \${heed_event_id:-}" \\
   --data-binary @- 2>/dev/null)" || {
+  heed_curl_exit=$?
   spool_hook_event "$payload"
+  [ "$heed_curl_exit" -ne 7 ] || heed_start_listener
   heed_answer "$heed_fallback"
 }
 

package/dist/doctor.js

@@ -12,7 +12,7 @@ import { desiredEntriesFor, hooksDeferredTo, isClientDetected } from "./plan.js"
 import { readInstalledSkillDigest } from "./skill/bundle.js";
 import { HeedStateCorruptError, readState } from "./state.js";
 import { readApprovedSkills } from "./skills/approved.js";
-import { readEndpoint } from "./listener/endpoint.js";
+import { pingListener, readEndpoint } from "./listener/endpoint.js";
 import { errorMessage } from "./guards.js";
 const INIT_REMEDIATION = "run npx heedvane init";
 const SETUP_REMEDIATION = "run npx heedvane setup";
@@ -294,23 +294,10 @@ async function checkListener(root) {
     if (!endpoint.port) {
         return { ...base, detail: "endpoint.env incomplete (no port) — re-run npx heedvane setup" };
     }
-    try {
-        const res = await fetch(`http://127.0.0.1:${endpoint.port}/hook/claude`, {
-            method: "POST",
-            headers: { "content-type": "application/json", ...(endpoint.token ? { "x-heed-agent-hook-token": endpoint.token } : {}) },
-            body: JSON.stringify({ v: 1, event: "doctor_probe", agent: "claude", receivedAt: new Date().toISOString() }),
-            signal: AbortSignal.timeout(750),
-        });
-        if (res.ok || res.status === 400 || res.status === 401) {
-            // Reachable is the point; auth/payload validation is the server's business.
-            return { ...base, detail: `reachable on 127.0.0.1:${endpoint.port}` };
-        }
-        return { ...base, detail: `responded ${res.status} on 127.0.0.1:${endpoint.port} (reachable)` };
-    }
-    catch {
-        return {
-            ...base,
-            detail: `not reachable on 127.0.0.1:${endpoint.port} — ${ENFORCEMENT_OFF}; events will spool (warn-only; never fails the report)`,
-        };
-    }
+    if (await pingListener(endpoint))
+        return { ...base, detail: `reachable on 127.0.0.1:${endpoint.port}` };
+    return {
+        ...base,
+        detail: `not reachable on 127.0.0.1:${endpoint.port} — ${ENFORCEMENT_OFF}; events will spool (warn-only; never fails the report)`,
+    };
 }

package/dist/heed-file.d.ts

@@ -57,6 +57,17 @@ export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 He
 export declare function loadHeedFile(text: string): HeedFile;
 /** `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. */
+    agents: "auto" | string[];
+    install: HeedInstallConfig;
+    steering: boolean;
+    memory: boolean;
+    skillChecks: boolean;
+}
+/** `text` with the installer's choices written into the fields that already hold them; the file's comments stay. */
+export declare function withInstallChoices(text: string, choices: InstallChoices): string;
 /**
  * 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

package/dist/heed-file.js

@@ -235,6 +235,27 @@ export function withServerUrl(text, url) {
         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`);

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

@@ -19,3 +19,8 @@ export declare function writeEndpoint(root: string, endpoint: Endpoint): Promise
  * (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>;

package/dist/listener/endpoint.js

@@ -110,3 +110,16 @@ export async function ensureEndpoint(root) {
     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/render.d.ts

@@ -6,6 +6,8 @@ export interface DetectionRow {
     /** Marker path relative to home, e.g. ~/.claude */
     markerRel: string;
 }
+/** What Heedvane installs into an agent, e.g. "hooks + MCP + skill". */
+export declare function capabilitySummary(client: ResolvedClient): string;
 export declare function renderDetection(rows: DetectionRow[]): string[];
 /**
  * The summary line from the spec:

package/dist/render.js

@@ -4,7 +4,8 @@
  */
 import { basename } from "node:path";
 import { wouldInstallCount } from "./plan.js";
-function capabilitySummary(client) {
+/** What Heedvane installs into an agent, e.g. "hooks + MCP + skill". */
+export function capabilitySummary(client) {
     const parts = [];
     if (client.capabilities.includes("hooks"))
         parts.push("hooks");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heedvane",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Heedvane for coding agents: one command installs steering, guardrails, team memory and skill checks into Claude Code, Codex, Cursor, Gemini CLI and more.",
   "private": false,
   "type": "module",
@@ -23,6 +23,7 @@
     "prepack": "tsc -p tsconfig.json"
   },
   "dependencies": {
+    "@clack/prompts": "^1.8.1",
     "jsonc-parser": "^3.3.1",
     "smol-toml": "^1.9.1",
     "write-file-atomic": "^5.0.1",