heedvane 0.2.1 → 0.3.4

package/dist/heed-file.d.ts

@@ -27,9 +27,19 @@ export interface HeedSkillsConfig {
     /** No synced approved list, or no listener to check it: let the skill run with a warning, or deny it. */
     whenUnknown: "allow" | "deny";
 }
+/**
+ * What leaves this machine (the installer and data modes proposal, "Proposed data modes"). `look-but-dont-keep`:
+ * Heedvane's guardrail checks read the prompt or tool call and keep only the verdict. `metrics-only`: only counts and
+ * names leave; the organization's fixed rules still run here, Heedvane's own checks and team memory do not.
+ */
+export declare const DATA_MODES: readonly ["look-but-dont-keep", "metrics-only"];
+export type DataMode = (typeof DATA_MODES)[number];
 /** The Heedvane backend the listener asks for steering, approved skills and memory. */
 export interface HeedvaneConfig {
     url: string;
+    /** The organization `connect --org` named: Heedvane's MCP connection URL carries it. */
+    org?: string;
+    dataMode: DataMode;
     steering: boolean;
     memory: boolean;
     skills: HeedSkillsConfig;
@@ -47,7 +57,7 @@ export interface HeedFile {
  * The commented control file written by `npx heedvane init`.
  * Kept loadable: loadHeedFile(DEFAULT_HEED_YAML_TEMPLATE) yields every default.
  */
-export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 Heedvane agent hooks control file (v1)\nschemaVersion: v1\n\n# Where managed scripts and spool live. Default below; one install per machine.\nroot: ~/.heed\n\n# The hook listener (Orca's pattern): loopback HTTP, token-authed, per-agent routes.\nlistener:\n  port: 0            # 0 = pick a free port at first start, persist to endpoint.env\n  spool: true        # spool to disk when listener is unreachable (5 MB cap, 7-day TTL)\n\n# Which agents to manage. `auto` = every detected agent on the machine.\nagents: auto        # or an explicit list: [claude, codex, warp]\n\n# Which integrations to install per agent where supported.\ninstall:\n  hooks: true       # native hook config injection (skipped where the agent has none)\n  skill: true       # heedvane-hooks skill bundle -> ~/.agents/skills/heedvane-hooks/\n  mcp: true         # heedvane MCP server registration (universal fallback, incl. Warp)\n\n# Session gating (Orca's env-gated dispatcher pattern).\ngating:\n  mode: always      # always = every session; pane = only sessions launched with HEED_SESSION env\n\n# The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).\nheedvane:\n  url: https://app.heedvane.com\n  steering: true      # ask the organization's steering rules before tool calls, prompts and stops\n  memory: true        # add your private memories (~/.heed/memory, local only) at session start\n  skills:\n    enforce: true     # deny skills that are not on the organization's approved list\n    strict: false     # also require the local SKILL.md to match the approved revision\n    whenUnknown: allow  # no synced list (run npx heedvane skills sync) or listener down: allow or deny\n";
+export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 Heedvane agent hooks control file (v1)\nschemaVersion: v1\n\n# Where managed scripts and spool live. Default below; one install per machine.\nroot: ~/.heed\n\n# The hook listener (Orca's pattern): loopback HTTP, token-authed, per-agent routes.\nlistener:\n  port: 0            # 0 = pick a free port at first start, persist to endpoint.env\n  spool: true        # spool to disk when listener is unreachable (5 MB cap, 7-day TTL)\n\n# Which agents to manage. `auto` = every detected agent on the machine.\nagents: auto        # or an explicit list: [claude, codex, warp]\n\n# Which integrations to install per agent where supported.\ninstall:\n  hooks: true       # native hook config injection (skipped where the agent has none)\n  skill: true       # heedvane-hooks skill bundle -> ~/.agents/skills/heedvane-hooks/\n  mcp: true         # heedvane MCP server registration (universal fallback, incl. Warp)\n\n# Session gating (Orca's env-gated dispatcher pattern).\ngating:\n  mode: always      # always = every session; pane = only sessions launched with HEED_SESSION env\n\n# The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).\nheedvane:\n  url: https://app.heedvane.com\n  dataMode: look-but-dont-keep  # what leaves this machine: look-but-dont-keep (checks read prompts and tool calls, keep only verdicts) or metrics-only (only counts and names)\n  steering: true      # ask the organization's steering rules before tool calls, prompts and stops\n  memory: true        # add your private memories (~/.heed/memory, local only) at session start\n  skills:\n    enforce: true     # deny skills that are not on the organization's approved list\n    strict: false     # also require the local SKILL.md to match the approved revision\n    whenUnknown: allow  # no synced list (run npx heedvane skills sync) or listener down: allow or deny\n";
 /**
  * Parse and validate a heed.yaml document, returning the fully normalized file.
  * Throws {@link HeedFileError} (message prefixed "invalid heed.yaml:") on any problem:
@@ -55,13 +65,14 @@ export declare const DEFAULT_HEED_YAML_TEMPLATE = "# ~/.heed/heed.yaml \u2014 He
  * (top-level or nested), or wrong-typed values.
  */
 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;
+/** `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;
 /** 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;
+    dataMode: DataMode;
     steering: boolean;
     memory: boolean;
     skillChecks: boolean;
@@ -74,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

@@ -3,6 +3,12 @@ import { join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { isScalar, parse, parseDocument } from "yaml";
 import { errorMessage, isRecord } from "./guards.js";
+/**
+ * What leaves this machine (the installer and data modes proposal, "Proposed data modes"). `look-but-dont-keep`:
+ * Heedvane's guardrail checks read the prompt or tool call and keep only the verdict. `metrics-only`: only counts and
+ * names leave; the organization's fixed rules still run here, Heedvane's own checks and team memory do not.
+ */
+export const DATA_MODES = ["look-but-dont-keep", "metrics-only"];
 /** Error raised for any invalid heed.yaml. The message is user-facing: keep it precise. */
 class HeedFileError extends Error {
     constructor(message) {
@@ -50,6 +56,7 @@ gating:
 # The Heedvane backend (credentials: npx heedvane auth, stored in ~/.heed/credentials.json).
 heedvane:
   url: https://app.heedvane.com
+  dataMode: look-but-dont-keep  # what leaves this machine: look-but-dont-keep (checks read prompts and tool calls, keep only verdicts) or metrics-only (only counts and names)
   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:
@@ -165,12 +172,29 @@ function validateSkills(raw) {
     }
     return out;
 }
+/** `heedvane.org` and `heedvane.dataMode`, when set. */
+function validateOrgAndDataMode(map) {
+    const out = {};
+    const { org, dataMode } = map;
+    if (org !== undefined) {
+        if (typeof org !== "string" || org.trim() === "")
+            throw new HeedFileError(`"heedvane.org" must be a non-empty string, got ${describeType(org)}`);
+        out.org = org.trim();
+    }
+    if (dataMode !== undefined) {
+        const known = DATA_MODES.find((mode) => mode === dataMode);
+        if (known === undefined)
+            throw new HeedFileError(`"heedvane.dataMode" must be one of ${DATA_MODES.join(", ")}, got ${JSON.stringify(dataMode)}`);
+        out.dataMode = known;
+    }
+    return out;
+}
 function validateHeedvane(raw) {
-    const out = { url: "https://app.heedvane.com", steering: true, memory: true, skills: validateSkills(undefined) };
+    const out = { url: "https://app.heedvane.com", dataMode: "look-but-dont-keep", steering: true, memory: true, skills: validateSkills(undefined) };
     if (raw === undefined)
         return out;
     const map = expectMapping(raw, "heedvane");
-    rejectUnknownKeys(map, ["url", "steering", "memory", "skills"], "heedvane");
+    rejectUnknownKeys(map, ["url", "org", "dataMode", "steering", "memory", "skills"], "heedvane");
     const url = map["url"];
     if (url !== undefined) {
         if (typeof url !== "string" || !URL.canParse(url) || !/^https?:$/.test(new URL(url).protocol)) {
@@ -178,6 +202,7 @@ function validateHeedvane(raw) {
         }
         out.url = url.replace(/\/+$/, "");
     }
+    Object.assign(out, validateOrgAndDataMode(map));
     if (map["steering"] !== undefined)
         out.steering = expectBool(map["steering"], "heedvane.steering");
     if (map["memory"] !== undefined)
@@ -225,36 +250,30 @@ export function loadHeedFile(text) {
         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) {
+/** `text` with each `[path, value]` written in place; the file's comments stay. Validate with {@link loadHeedFile}. */
+export function withSettings(text, settings) {
     const document = parseDocument(text);
-    const current = document.getIn(["heedvane", "url"], true);
-    if (isScalar(current))
-        current.value = url;
-    else
-        document.setIn(["heedvane", "url"], url);
+    for (const [path, value] of settings) {
+        const current = document.getIn(path, true);
+        if (isScalar(current) && typeof value !== "object")
+            current.value = value;
+        else
+            document.setIn(path, value);
+    }
     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 = [
+    return withSettings(text, [
         [["agents"], choices.agents],
         [["install", "hooks"], choices.install.hooks],
         [["install", "skill"], choices.install.skill],
         [["install", "mcp"], choices.install.mcp],
+        [["heedvane", "dataMode"], choices.dataMode],
         [["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"]];
@@ -265,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 { HeedFile, InstallChoices } from "./heed-file.js";
-import type { PlannedAction } from "./plan.js";
+import type { DataMode, HeedFile, InstallChoices } from "./heed-file.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;
@@ -27,7 +27,9 @@ export declare function brandIntro(server: string, org: string | undefined, stre
 /** 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>;
+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): 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. */
@@ -35,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.
@@ -43,5 +45,10 @@ 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;
+    hint: string;
+}>;

package/dist/installer.js

@@ -4,9 +4,10 @@
  * 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 { cancel, confirm, intro, isCancel, log, multiselect, note, outro, select, spinner } from "@clack/prompts";
 import { styleText } from "node:util";
 import { appliedFailed } from "./render.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) {
@@ -19,6 +20,9 @@ export async function askChoices(agents, current, streams) {
     const picked = await pickAgents(agents, current, streams);
     if (picked === null)
         return null;
+    const dataMode = await pickDataMode(current.heedvane.dataMode, streams);
+    if (dataMode === null)
+        return null;
     const install = await pickIntegrations(current.install, streams);
     if (install === null)
         return null;
@@ -28,18 +32,27 @@ export async function askChoices(agents, current, streams) {
     return {
         agents: sameAsDetected(picked, agents) ? "auto" : picked,
         install,
+        dataMode,
         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) {
+export async function confirmInstall(agents, details, 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);
+    note([...agentRows(agents), "", ...details, footer].join("\n"), "Ready to install", streams);
     const answer = await confirm({ message: "Install now?", initialValue: true, ...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) {
+    const lines = [`What leaves this machine: ${DATA_MODE_LABEL[heedFile.heedvane.dataMode].label}`];
+    if (!heedFile.install.mcp)
+        return lines;
+    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) {
     const progress = spinner({ output: streams.output });
@@ -73,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"
@@ -101,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)];
@@ -118,12 +131,26 @@ async function pickAgents(agents, current, streams) {
     });
     return isCancel(answer) ? null : answer;
 }
+/** What each data mode lets leave this machine, as the installer says it. */
+export const DATA_MODE_LABEL = {
+    "look-but-dont-keep": { label: "Look but don't keep", hint: "Heedvane's checks read prompts and tool calls, then keep only the verdict" },
+    "metrics-only": { label: "Metrics only", hint: "only counts and names leave; your organization's fixed rules still run here" },
+};
+async function pickDataMode(current, streams) {
+    const answer = await select({
+        message: "How much should leave this machine?",
+        options: Object.keys(DATA_MODE_LABEL).map((mode) => ({ value: mode, ...DATA_MODE_LABEL[mode] })),
+        initialValue: current,
+        ...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: "mcp", label: "MCP server", hint: "findings, reports and 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]),
@@ -156,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"))

package/dist/listener/background.d.ts

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