heedvane 0.2.1 → 0.3.4

package/dist/cli.js

@@ -1,35 +1,38 @@
 #!/usr/bin/env node
 /**
- * heedvane-hook — command routing: init | setup | doctor | uninstall |
- * listener | status | mcp. Plain argv parsing (no commander); all state
+ * heedvane — command routing: connect | init | setup | login | auth | doctor |
+ * uninstall | listener | run | status | skills | memory. Plain argv parsing (no commander); all state
  * mutations flow through plan → apply; --dry-run writes nothing.
  */
-import { createWriteStream, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, realpathSync } from "node:fs";
 import { spawn } from "node:child_process";
 import { constants as osConstants, homedir, platform } from "node:os";
-import { dirname, join } from "node:path";
+import { join } from "node:path";
 import { supportedClients } from "./clients/definitions.js";
-import { installHermesPlugin } from "./clients/hermes-plugin.js";
+import { installHookFiles } from "./clients/hook-files.js";
 import { applyEntry } from "./apply.js";
-import { DEFAULT_HEED_YAML_TEMPLATE, heedvaneConfigAt, loadHeedFile, loadHeedFileAt, withInstallChoices, withServerUrl } from "./heed-file.js";
-import { planActions, desiredEntriesFor, isClientDetected } from "./plan.js";
+import { DATA_MODES, DEFAULT_HEED_YAML_TEMPLATE, loadHeedFile, loadHeedFileAt, withInstallChoices, withSettings } from "./heed-file.js";
+import { bridgeNodeDir, connectionNote, planActions, desiredEntriesFor, hasOwnConnection, heedvaneConnector, isClientDetected, legacyOrganization, mcpLeftovers, sendsOrgKey } from "./plan.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";
 import { emptyState, readState, writeStateAtomic } from "./state.js";
-import { writeDispatcherScript } from "./dispatchers/posix.js";
-import { removeDeferredHookGroups, removeStaleHookGroups, uninstall } from "./uninstall.js";
-import { statusText, runMcpStdio } from "./mcp-server.js";
+import { writeDispatcherScript, writeHookNode } from "./dispatchers/posix.js";
+import { removeDeferredHookGroups, removeLegacyMcpEntries, removeStaleHookGroups, uninstall } from "./uninstall.js";
+import { statusText } from "./status.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 { ensureEndpoint, HEEDVANE_VERSION } from "./listener/endpoint.js";
+import { ensureListener, listenerLogPath, PORT_TAKEN_EXIT, stopCommand } from "./listener/background.js";
+import { ListenerAlreadyRuns, serveHooks, settingsToRun } from "./listener/serve.js";
+import { keyConnectorEntry, ORG_KEY_ENV } from "./mcp.js";
 import { cmdAuth, cmdLogin, cmdSkills } from "./commands/heedvane.js";
+import { cmdMcpStub } from "./commands/mcp-stub.js";
+import writeFileAtomic from "write-file-atomic";
 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";
+import { agentLines, askChoices, brandIntro, confirmInstall, installCancelled, installDetails, 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>)
@@ -42,17 +45,17 @@ const USAGE = `  heedvane-hook — cross-agent steering, guardrails & analysis
     setup           plan + apply from an existing heed.yaml
     doctor          scoped, remediation-carrying health check
     uninstall       marker-verified removal (never touches heed.yaml)
-    listener        listener controls (start): answers hooks with skill checks, steering and memory
+    listener        listener controls (start, restart): answers hooks with skill checks, steering and memory
     login           sign in to Heedvane in the browser (~/.heed/login.json, 0600; refreshed automatically)
     auth org        CI/headless: store an organization API key read from stdin (~/.heed/credentials.json, 0600)
     skills sync     install the organization's approved skills and cache the list hooks enforce
     memory list|show|search   browse this repository's team memory (a folder, one memory, or a question)
     status          quick state summary
-    mcp             run the MCP stdio server (what agents register)
 
   Flags: --dry-run --yes --json --agent <id> (repeatable) --client <id> --purge-config --project
          --server <url> (connect/init: the Heedvane app to use, saved as heedvane.url; --url also works)
-         --org <id> (connect/init: the organization the sign-in must belong to)`;
+         --org <id> (connect/init: the organization the sign-in must belong to; also registers Heedvane's MCP connection)
+         --mode <look-but-dont-keep|metrics-only> (connect/init: what leaves this machine, saved as heedvane.dataMode)`;
 function resolveHome(env) {
     return env.HEED_HOME ?? homedir();
 }
@@ -98,25 +101,30 @@ function parseInvocation(args) {
         clients: parseRepeatedFlag(args, "--client"),
         server: flagValue(args, "--server") ?? flagValue(args, "--url"),
         org: flagValue(args, "--org"),
+        mode: flagValue(args, "--mode"),
         positional: positionalArgs(args, VALUE_FLAGS),
     };
 }
 /** Flags without a value. */
 const SWITCH_FLAGS = ["--dry-run", "--yes", "--json", "--purge-config", "--project", "--help", "-h"];
 /** Flags followed by a value. */
-const VALUE_FLAGS = ["--agent", "--client", "--folder", "--offset", "--url", "--server", "--org", "--token"];
+const VALUE_FLAGS = ["--agent", "--client", "--folder", "--offset", "--url", "--server", "--org", "--mode", "--token"];
 /** Heedvane's own arguments: everything before `--`, after which `run` passes the rest to the agent. */
 function ownArgs(args) {
     const separator = args.indexOf("--");
     return separator < 0 ? args : args.slice(0, separator);
 }
-/** The first argument that looks like a flag but is not one of ours (values of value flags skipped). */
-function unknownFlag(args) {
+/** What is wrong with the flags: one that is not ours, or a value flag without its value (a clipped paste); undefined when nothing is. */
+function flagProblem(args) {
     for (let i = 0; i < args.length; i++) {
-        if (VALUE_FLAGS.includes(args[i]))
+        const arg = args[i];
+        if (VALUE_FLAGS.includes(arg)) {
             i += 1;
-        else if (args[i].startsWith("-") && !SWITCH_FLAGS.includes(args[i]))
-            return args[i];
+            if (args[i] === undefined || args[i].startsWith("-"))
+                return `${arg} needs a value`;
+        }
+        else if (arg.startsWith("-") && !SWITCH_FLAGS.includes(arg))
+            return `unknown flag: ${arg}`;
     }
     return undefined;
 }
@@ -144,9 +152,9 @@ async function main(argv, opts = {}) {
         ctx.out(helpFor(helpTopic(ctx.positional)));
         return 0;
     }
-    const unknown = unknownFlag(own);
-    if (unknown !== undefined) {
-        ctx.out(`  ✗ unknown flag: ${unknown} (nothing was changed)`);
+    const problem = flagProblem(own);
+    if (problem !== undefined) {
+        ctx.out(`  ✗ ${problem} (nothing was changed)`);
         ctx.out(helpFor(command));
         return 2;
     }
@@ -168,11 +176,11 @@ function commandContext(argv, opts) {
         out: opts.write ?? ((line) => console.log(line)),
         args,
         readStdin: opts.readStdin ?? readProcessStdin,
-        openBrowser: opts.openBrowser ?? openSystemBrowser,
+        openBrowser: opts.openBrowser ?? ((url) => openSystemBrowser(url, env.BROWSER)),
         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)),
+        ensureListener: opts.ensureListener ?? ((home) => ensureListener(home, fileURLToPath(import.meta.url), env)),
     };
 }
 async function routeCommand(command, ctx) {
@@ -197,20 +205,23 @@ async function routeServiceCommand(command, ctx) {
             ctx.out(await statusText());
             return 0;
         }
-        case "mcp": {
-            runMcpStdio({ write: (line) => ctx.out(line) });
-            return 0;
-        }
         case "listener": {
-            return cmdListener({ home: ctx.home, out: ctx.out, rest: ctx.args.slice(ctx.args.indexOf("listener") + 1) });
+            return cmdListener({ ...ctx, 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":
+            return cmdRun({ home: ctx.home, env: ctx.env, ensureListener: ctx.ensureListener, command: ctx.args.slice(ctx.args.indexOf("--") + 1), separated: ctx.args.includes("--") });
+        case "login": {
+            const code = await cmdLogin(backendCommandContext(ctx));
+            return code === 0 ? afterSignIn(ctx, await switchConnections(ctx, "browser")) : code;
+        }
+        case "auth": {
+            const code = await cmdAuth(backendCommandContext(ctx));
+            return code === 0 && ctx.positional[1] === "org" ? afterSignIn(ctx, await switchConnections(ctx, "key")) : code;
+        }
         case "skills":
-            return (command === "auth" ? cmdAuth : cmdSkills)(backendCommandContext(ctx));
+            return cmdSkills(backendCommandContext(ctx));
+        case "mcp":
+            return cmdMcpStub();
         case "memory":
             return cmdMemory({ home: ctx.home, out: ctx.out, words: ctx.positional.slice(1), flag: (name) => flagValue(ctx.args, name), cwd: ctx.cwd });
         default:
@@ -260,11 +271,11 @@ async function cmdInit(ctx) {
     }
     let serverEdit;
     try {
-        serverEdit = ctx.server === undefined ? null : withServer(home, loaded, ctx.server);
+        serverEdit = withFlags(loaded, ctx);
     }
     catch (err) {
         out("");
-        out(`  ✗ --server ${ctx.server} cannot be used: ${errorMessage(err)}`);
+        out(`  ✗ ${errorMessage(err)}`);
         return 1;
     }
     const { heedFile, existed } = serverEdit ?? loaded;
@@ -289,53 +300,100 @@ async function cmdInit(ctx) {
     // --yes: first non-dry run has approval; proceed to write.
     return applyAndReport(ctx, { heedFile, agents, existed, ...(serverEdit === null ? {} : { text: serverEdit.text }) });
 }
-/** 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 text = withServerUrl(heedText(home, loaded.existed), server);
-    const heedFile = loadHeedFile(text);
-    if (loaded.existed && heedFile.heedvane.url === loaded.heedFile.heedvane.url)
+/** The heed.yaml settings `--server`, `--org` and `--mode` name; a refusal when a value cannot be used. */
+function flagSettings({ server, org, mode }) {
+    if (mode !== undefined && !DATA_MODES.some((known) => known === mode))
+        throw new Error(`--mode ${mode} is not one of ${DATA_MODES.join(", ")}; nothing was changed`);
+    const settings = [[["heedvane", "url"], server], [["heedvane", "org"], org], [["heedvane", "dataMode"], mode]];
+    return settings.filter((setting) => setting[1] !== undefined);
+}
+/**
+ * heed.yaml (or the template) with the flags' settings; null when they change nothing. Throws on a value it cannot use.
+ * Without an organization or a saved login, one an earlier version's connection names counts as `--org`, so connect can replace it.
+ */
+function withFlags(loaded, flags) {
+    const { home, env } = flags;
+    const server = flags.server ?? loaded.heedFile.heedvane.url;
+    // Only when nothing else names one: a saved login says which organization this machine belongs to.
+    const earlierOrg = flags.org === undefined && loaded.heedFile.heedvane.org === undefined && !existsSync(join(home, ".heed", "login.json")) ? legacyOrganization(supportedClients({ home, platform: platform(), env }), server) : undefined;
+    const settings = flagSettings({ ...flags, org: flags.org ?? earlierOrg });
+    if (settings.length === 0)
+        return null;
+    const text = withSettings(heedText(home, loaded.existed), settings);
+    let heedFile;
+    try {
+        heedFile = loadHeedFile(text);
+    }
+    catch (err) {
+        throw new Error(`${flags.server === undefined ? "a flag" : `--server ${flags.server}`} cannot be used: ${errorMessage(err)}`, { cause: err });
+    }
+    if (loaded.existed && JSON.stringify(heedFile.heedvane) === JSON.stringify(loaded.heedFile.heedvane))
         return null;
     return { heedFile, existed: loaded.existed, text };
 }
+/** A sign-in that is not to the organization asked for: nothing is applied, but the sign-in it tried is saved, so the listener runs with it. */
+async function signInRefused({ out, flags, ensureListener, home }) {
+    out("  Nothing was changed; run this command again once signed in to that organization.");
+    const stillRunning = flags.dryRun ? undefined : sayListenerFully(await ensureListener(home), (line) => out(`  ${line}`));
+    if (flags.json)
+        outJson(out, { status: "failed", plannedActions: [], appliedActions: [], ...(stillRunning === undefined ? {} : { listener: stillRunning }) });
+    return 1;
+}
 async function applyAndReport(ctx, spec) {
     const { out, flags } = ctx;
+    if (!(await signedInToOrg(ctx, spec.heedFile.heedvane)))
+        return signInRefused(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);
+    const signedIn = flags.dryRun || (await signInIfNeeded(ctx, spec.heedFile.heedvane));
+    // Last, after the sign-in, so the listener runs with it.
+    const stillRunning = flags.dryRun ? undefined : sayListener(await ctx.ensureListener(ctx.home), (line) => out(`  ${line}`));
+    printNextSteps(out, spec.heedFile, stillRunning);
+    const failed = applied.some(appliedFailed) || !signedIn || stillRunning !== undefined;
     if (flags.json)
-        outJson(out, { status: failed ? "failed" : "applied", plannedActions: actions, appliedActions: applied });
+        outJson(out, { status: failed ? "failed" : "applied", plannedActions: actions, appliedActions: applied, ...(stillRunning === undefined ? {} : { listener: stillRunning }) });
     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)
+/** What connect says last: an old listener that did not stop, and what to do next. */
+function printNextSteps(out, heedFile, stillRunning) {
+    out("");
+    if (stillRunning !== undefined)
+        out(`  ✗ ${stillRunning}`);
+    out(`  Next: ${stillRunning === undefined ? "open" : "once it is stopped, open"} a new agent session; Heedvane joins it at session start.`);
+    const note = connectionNote(heedFile);
+    if (note !== undefined)
+        out(`  ${note}`);
+    out("  Re-run `npx heedvane doctor` after any heed.yaml edit.");
+}
+/** Writes heed.yaml when it is missing or this run changed it, in one atomic step, and names the settings that changed. */
+function writeControlFile({ home, out }, { heedFile, existed, text }, before) {
+    const path = join(home, ".heed", "heed.yaml");
+    if (existed && (text === undefined || text === readFileSync(path, "utf8")))
         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)`);
+    writeFileAtomic.sync(path, text ?? DEFAULT_HEED_YAML_TEMPLATE, { mode: 0o600 });
+    if (!existed)
+        return out(`  ✓ Wrote ~/.heed/heed.yaml (your control file — edit any time)`);
+    const { url, org, dataMode } = heedFile.heedvane;
+    for (const [name, value] of [["url", url], ["org", org], ["dataMode", dataMode]]) {
+        if (value !== undefined && value !== before?.[name])
+            out(`  ✓ Set heedvane.${name} in ~/.heed/heed.yaml to ${value}`);
+    }
 }
-/** 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);
+    const before = spec.existed ? loadOrTemplate(home).heedFile.heedvane : undefined;
+    writeControlFile(ctx, spec, before);
     const actions = planFor({ home, env, heedFile, agents });
-    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 });
+    const applied = await applyPlan(actions, applyContext({ home, env, out }, heedFile));
     // The listener port and token every dispatcher reads; kept once issued.
     await ensureEndpoint(join(home, ".heed"));
+    // The Node every hook's fallback runs with: the one running this install.
+    await writeHookNode(home, env["PATH"]);
     // Machine state: CLI-owned; preserve an existing endpoint.
     const root = join(home, ".heed");
     const existing = await readState(root);
@@ -347,25 +405,130 @@ async function installPlan(ctx, spec) {
     await writeStateAtomic(root, state);
     return { actions, applied };
 }
-async function signInIfNeeded(ctx, url) {
-    const root = join(ctx.home, ".heed");
-    if ((await backendAt(root, url)) !== null && (await onRequestedOrg(root, ctx.org)))
-        return;
+/**
+ * What a command says after {@link ensureListener}: a line, and `stillRunning` (the command exits 1) when the listener
+ * at the port did not stop when asked.
+ */
+function listenerReport(outcome) {
+    switch (outcome.kind) {
+        case "not set up":
+        case "running":
+            return {};
+        case "started":
+            return { line: "✓ started the listener" };
+        case "replaced":
+            return { line: `✓ replaced an older listener with this version (${HEEDVANE_VERSION})` };
+        case "restarted":
+            return { line: "✓ restarted the listener with the new settings" };
+        case "newer":
+            // This older CLI never replaces it (that would downgrade it); the newer one restarts itself with these settings.
+            if (outcome.earlierSettings)
+                return { stillRunning: `A newer Heedvane listener (${outcome.version}) runs with the earlier settings, and this npx heedvane (${HEEDVANE_VERSION}) is older, so it did not replace it. Apply the settings with the newer one: npx -y heedvane@latest listener restart` };
+            return { line: `· kept the newer listener that runs (${outcome.version}); this npx heedvane (${HEEDVANE_VERSION}) is older: npx -y heedvane@latest` };
+        case "did not start":
+            // With a reason (no settings to run), a hook's start would end the same way.
+            return { line: outcome.why !== undefined ? `· the listener did not start: ${outcome.why}` : `· the listener did not start (${outcome.log} says why); the hooks start one with the next agent event` };
+        case "did not stop":
+            return { stillRunning: `A Heedvane listener on 127.0.0.1:${outcome.port} still answers your agents and did not stop when asked. Stop it: ${stopCommand(outcome.port)}` };
+    }
+}
+/** Says what making sure of the listener did; the old listener that did not stop, if any. */
+function sayListener(outcome, say) {
+    const { line, stillRunning } = listenerReport(outcome);
+    if (line !== undefined)
+        say(line);
+    return stillRunning;
+}
+/** {@link sayListener}, with the old listener that did not stop said as a failure. */
+function sayListenerFully(outcome, say) {
+    const stillRunning = sayListener(outcome, say);
+    if (stillRunning !== undefined)
+        say(`✗ ${stillRunning}`);
+    return stillRunning;
+}
+/** After `login` or `auth org` (exit `code`): the listener runs with the new sign-in; 1 when the old one did not stop. */
+async function afterSignIn(ctx, code) {
+    return sayListenerFully(await ctx.ensureListener(ctx.home), (line) => ctx.out(`  ${line}`)) === undefined ? code : 1;
+}
+/** What applying needs from heed.yaml: the settings baked into each dispatcher and Heedvane's MCP connection URL. */
+function applyContext({ home, env, out }, heedFile) {
+    const dispatcher = {
+        denySkillsWhenUnchecked: heedFile.heedvane.skills.enforce && heedFile.heedvane.skills.whenUnknown === "deny",
+        gating: heedFile.gating.mode,
+    };
+    return { home, env, out, dispatcher, connector: heedvaneConnector(heedFile), mcpLeftovers: mcpLeftovers(heedFile) };
+}
+/**
+ * A change of sign-in switches the Heedvane connections connect installed to the form it needs: `auth org` (a software
+ * factory, whose image was often built without the key) to sending HEEDVANE_ORG_KEY, `login` back to the browser
+ * sign-in. Only agents with a key form switch; it adds no connection and leaves a user's own entry alone.
+ */
+async function switchConnections({ home, env, out }, to) {
+    const loaded = loadOrTemplate(home);
+    const connector = loaded.existed && loaded.error === undefined ? heedvaneConnector(loaded.heedFile) : undefined;
+    // No connection to switch: none was asked for, no organization, or metrics only.
+    if (connector === undefined)
+        return 0;
+    const clients = supportedClients({ home, platform: platform(), env });
+    const switching = planFor({ home, env, heedFile: loaded.heedFile, agents: [] }).filter((action) => {
+        const client = clients.find((candidate) => candidate.id === action.clientId);
+        if (action.kind !== "mcp" || action.operation !== "update" || client === undefined || !hasOwnConnection(client))
+            return false;
+        return keyConnectorEntry(client.id, connector) !== undefined && sendsOrgKey(client) === (to === "browser");
+    });
+    const applied = await applyPlan(switching, applyContext({ home, env, out }, loaded.heedFile));
+    const keySet = Boolean(env[ORG_KEY_ENV]?.trim());
+    for (const result of applied)
+        out(switchedLine(result, { name: clients.find((client) => client.id === result.clientId)?.displayName ?? result.clientId, to, keySet }));
+    return applied.some(appliedFailed) ? 1 : 0;
+}
+function switchedLine(result, { name, to, keySet }) {
+    if (appliedFailed(result))
+        return `  ✗ ${name}: Heedvane's connection did not switch (${result.reason ?? result.status})`;
+    if (to === "browser")
+        return `  ✓ ${name}: Heedvane's connection signs in in the browser again`;
+    // The key came from a file: the agent sends it only where the variable is set.
+    if (!keySet)
+        return `  ! ${name}: Heedvane's connection now sends ${ORG_KEY_ENV}, which is not set here; set it where the agent runs`;
+    return `  ✓ ${name}: Heedvane's connection now sends ${ORG_KEY_ENV}`;
+}
+/** Without a sign-in to the server, sign in now when a person is at the terminal, else say how. False when that sign-in is another organization's. */
+async function signInIfNeeded(ctx, target) {
+    if ((await backendAt(join(ctx.home, ".heed"), target.url)) !== null)
+        return true;
     if (!ctx.interactive) {
         ctx.out("  Next: sign in with `npx heedvane login` (CI and headless machines: npx heedvane auth org < key-file).");
-        return;
-    }
-    await cmdLogin({ home: ctx.home, out: ctx.out, words: [], project: false, readStdin: async () => "", openBrowser: ctx.openBrowser });
-    if (!(await onRequestedOrg(root, ctx.org))) {
-        ctx.out(`  ✗ This sign-in belongs to another organization than ${ctx.org}. Run \`npx heedvane login\` and pick that organization on the consent page.`);
+        return true;
     }
+    return (await signIn(ctx)) && isOrgSignIn(ctx, target);
 }
-/** True without `--org`; else whether the saved login was granted for that organization. */
-async function onRequestedOrg(root, org) {
+/**
+ * Before anything is written: a saved sign-in to another organization than the named one would send the hooks'
+ * events there while the MCP connection points here. At a terminal it signs in again first. True when the run may write.
+ */
+async function signedInToOrg(ctx, target) {
+    if (ctx.interactive && !ctx.flags.dryRun && (await otherOrganization(ctx.home, target)) !== undefined)
+        await signIn(ctx);
+    return isOrgSignIn(ctx, target);
+}
+/** False, saying how to fix it, when the saved sign-in is another organization's. */
+async function isOrgSignIn(ctx, target) {
+    const other = await otherOrganization(ctx.home, target);
+    if (other !== undefined)
+        ctx.out(`  ✗ The saved sign-in is for organization ${other}, not ${target.org}. Run \`npx heedvane login\` and pick ${target.org} on the consent page.`);
+    return other === undefined;
+}
+/** The saved login's organization when it is a different, known one at the same server; a key or an unnamed organization is not. */
+async function otherOrganization(home, { url, org }) {
     if (org === undefined)
-        return true;
-    const saved = await readLogin(root).catch(() => null);
-    return saved?.organizationId === org;
+        return undefined;
+    const saved = await readLogin(join(home, ".heed")).catch(() => null);
+    return saved?.url === url && saved.organizationId !== undefined && saved.organizationId !== org ? saved.organizationId : undefined;
+}
+/** The browser sign-in; it prints its own result. */
+/** True when the browser sign-in succeeded. */
+async function signIn(ctx) {
+    return (await cmdLogin({ home: ctx.home, out: ctx.out, words: [], project: false, readStdin: async () => "", openBrowser: ctx.openBrowser })) === 0;
 }
 async function cmdSetup(ctx) {
     const { home, out } = ctx;
@@ -405,6 +568,8 @@ function takesInstaller(ctx) {
 function heedText(home, existed) {
     return existed ? readFileSync(join(home, ".heed", "heed.yaml"), "utf8") : DEFAULT_HEED_YAML_TEMPLATE;
 }
+/** The outcomes after which a listener answers the hooks. */
+const LISTENING = new Set(["running", "started", "replaced", "restarted", "newer"]);
 /** The installer: pick agents, integrations and features, confirm, install, start the listener, sign in. */
 async function cmdInstall(ctx) {
     const base = installerBase(ctx);
@@ -414,77 +579,113 @@ async function cmdInstall(ctx) {
     }
     const { prompts } = ctx;
     brandIntro(base.heedFile.heedvane.url, ctx.org, prompts);
-    const choices = await askChoices(agentOptions(ctx), base.heedFile, prompts);
+    // `--agent` ticks exactly the agents it names.
+    const current = ctx.agents.length > 0 ? { ...base.heedFile, agents: ctx.agents } : base.heedFile;
+    const choices = await askChoices(agentOptions(ctx), current, 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)))
+    if (!(await confirmInstall(planned, installDetails(spec.heedFile), prompts)))
+        return installCancelled(prompts);
+    if (!(await signedInToOrg({ ...ctx, out: promptLine(prompts) }, spec.heedFile.heedvane))) {
+        // The sign-in it tried is saved even when it named another organization: the listener runs with it.
+        sayListenerFully(await ctx.ensureListener(ctx.home), promptLine(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;
+    const signedIn = await signInIfNeeded({ ...ctx, out: promptLine(prompts) }, spec.heedFile.heedvane);
+    // Last, after the sign-in, so the listener runs with it.
+    const ensuring = ctx.ensureListener(ctx.home);
+    const listening = await listenerStep(() => ensuring.then(listenerStepResult), prompts);
+    const outcome = await ensuring.catch(() => ({ kind: "did not start", log: listenerLogPath(join(ctx.home, ".heed")) }));
+    const { line, stillRunning } = listenerReport(outcome);
+    if (line !== undefined && outcome.kind === "newer")
+        promptLine(prompts)(line);
+    installFinished(nextSteps(listening, spec.heedFile, stillRunning), signedIn, prompts);
+    return applied.some(appliedFailed) || !signedIn || stillRunning !== undefined ? 1 : 0;
+}
+/** The installer's listener step: true once a listener runs, else what went wrong. */
+function listenerStepResult(outcome) {
+    if (LISTENING.has(outcome.kind))
+        return true;
+    if (outcome.kind === "did not stop")
+        return `A Heedvane listener on 127.0.0.1:${outcome.port} did not stop when asked`;
+    return `Heedvane did not start; ${outcome.kind === "did not start" ? (outcome.why ?? `see ${outcome.log}`) : "see ~/.heed/listener.log"}`;
 }
-/** 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);
+/** heed.yaml's current text (or the template) with `--server`, `--org` and `--mode` applied, parsed; a message when it cannot be used. */
+function installerBase(ctx) {
+    const loaded = loadOrTemplate(ctx.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 };
+        return withFlags(loaded, ctx) ?? { heedFile: loaded.heedFile, existed: loaded.existed, text: heedText(ctx.home, loaded.existed) };
     }
     catch (err) {
-        return `--server ${server} cannot be used: ${errorMessage(err)}`;
+        return 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) {
+function nextSteps(listening, heedFile, stillRunning) {
+    const server = heedFile.heedvane.url;
     return [
-        "Open a new agent session: Heedvane joins it at session start.",
+        ...(stillRunning === undefined ? ["Open a new agent session: Heedvane joins it at session start."] : [stillRunning, "Once it is stopped, open a new agent session: Heedvane joins it at session start."]),
+        ...[connectionNote(heedFile)].filter((note) => note !== undefined),
         `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"]),
+        ...(listening || stillRunning !== undefined ? [] : ["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");
-    const status = await installHermesPlugin(ctx.home, ctx.dispatcher.gating);
-    if (status === "skipped") {
-        return { clientId: client.id, kind: "hooks", status: "skipped", path, reason: "another plugin owns ~/.hermes/plugins/heedvane-hooks — left untouched" };
-    }
+/** Hooks written as whole files (Hermes' plugin, Pi's extension): never over files Heedvane did not write. */
+async function applyHookFiles(client, hookFiles, ctx) {
+    const path = hookFiles.path(client.markerPath);
+    const status = await installHookFiles(hookFiles, path, ctx.dispatcher.gating);
+    if (status === "skipped")
+        return { clientId: client.id, kind: "hooks", status: "skipped", path, reason: `${path} is not Heedvane's — left untouched` };
     return { clientId: client.id, kind: "hooks", status: status === "installed" ? "create" : "unchanged", path };
 }
+/** Folds removals into an apply result: a failed removal becomes the result, any other makes an unchanged one an update. */
+function withRemovals(items, result) {
+    let worst = result;
+    for (const item of items) {
+        if (item.status === "failed")
+            return { status: "failed", path: item.path, reason: item.detail };
+        if (worst.status === "unchanged")
+            worst = { status: "update", path: item.path };
+    }
+    return worst;
+}
 /** Drop our groups under event keys this client no longer installs; a failed removal becomes the result. */
 async function withoutStaleHookGroups(client, writes, result) {
     let worst = result;
     for (const { target, containerKey } of writes) {
         if (containerKey !== "hooks")
             continue;
-        for (const item of await removeStaleHookGroups(client, target)) {
-            if (item.status === "failed")
-                return { status: "failed", path: item.path, reason: item.detail };
-            if (worst.status === "unchanged")
-                worst = { status: "update", path: item.path };
-        }
+        worst = withRemovals(await removeStaleHookGroups(client, target), worst);
+        if (worst.status === "failed")
+            return worst;
     }
     return worst;
 }
+/** After the writes: our hook groups under events no longer installed, and the MCP entries plan.ts `mcpLeftovers` names. */
+async function withoutLeftovers(kind, client, done) {
+    if (kind === "hooks")
+        return withoutStaleHookGroups(client, done.writes, done.result);
+    if (kind !== "mcp")
+        return done.result;
+    return withRemovals(await removeLegacyMcpEntries(client, done.mcpLeftovers), done.result);
+}
 /** Patch every desired entry into the client's config files, then refresh the dispatcher script. */
 async function applyConfigEntries(action, client, ctx) {
-    const desireds = desiredEntriesFor(client, action.kind === "hooks" ? "hooks" : "mcp", { home: ctx.home, env: ctx.env });
+    const desireds = desiredEntriesFor(client, action.kind === "hooks" ? "hooks" : "mcp", { home: ctx.home, env: ctx.env, connector: ctx.connector, nodeDir: bridgeNodeDir(platform()) });
     // One write per file and container: every hook event lands (and is backed up) together.
     const writes = new Map();
     for (const d of desireds) {
@@ -503,11 +704,11 @@ async function applyConfigEntries(action, client, ctx) {
         if (res.status !== "unchanged")
             worst = res;
     }
-    if (action.kind === "hooks" && worst.status !== "failed" && worst.status !== "invalid") {
-        worst = await withoutStaleHookGroups(client, writes.values(), worst);
-    }
-    // The dispatcher script the snippet delegates to.
-    await writeDispatcherScript(ctx.home, client.id, ctx.dispatcher);
+    if (worst.status !== "failed" && worst.status !== "invalid")
+        worst = await withoutLeftovers(action.kind, client, { writes: writes.values(), result: worst, mcpLeftovers: ctx.mcpLeftovers });
+    // The dispatcher script the hook command delegates to; an MCP connection runs none.
+    if (action.kind === "hooks")
+        await writeDispatcherScript(ctx.home, client.id, ctx.dispatcher);
     return {
         clientId: action.clientId,
         kind: action.kind,
@@ -524,9 +725,11 @@ async function applyAction(action, client, ctx) {
         const status = await installSkill(join(ctx.home, ".agents", "skills"));
         return { clientId: action.clientId, kind: "skill", status, path: action.path };
     }
-    if (client.id === "hermes" && action.kind === "hooks") {
-        return applyHermesPlugin(client, ctx);
-    }
+    if (action.kind === "hooks" && client.hookFiles !== undefined)
+        return applyHookFiles(client, client.hookFiles, ctx);
+    // A connection plan.ts found current is left as it is: apply would rewrite what drift checks leave out (mcp.ts comparableEntry).
+    if (action.kind === "mcp" && action.operation === "unchanged")
+        return { clientId: action.clientId, kind: "mcp", status: "unchanged", path: action.path };
     return applyConfigEntries(action, client, ctx);
 }
 async function recordDeferredHookRemovals(client, results) {
@@ -608,25 +811,60 @@ async function cmdUninstall(ctx) {
 }
 async function cmdListener(ctx) {
     const sub = ctx.rest[0] ?? "";
+    if (sub === "restart")
+        return cmdListenerRestart(ctx);
     if (sub !== "start") {
-        ctx.out("  usage: npx heedvane listener start");
-        ctx.out("  v1 runs the listener in the foreground; service install (launchd/systemd) is opt-in later.");
+        ctx.out("  usage: npx heedvane listener start   (in the foreground; Ctrl-C stops it)");
+        ctx.out("         npx heedvane listener restart (in the background, with heed.yaml and the sign-in as they are now)");
         return sub === "" ? 2 : 1;
     }
-    const started = await serveHooks(ctx.home, ctx.out);
+    let started;
+    try {
+        started = await serveHooks(ctx.home, ctx.out);
+    }
+    catch (err) {
+        return startRefusal(ctx, err);
+    }
     ctx.out(`  ✓ listener on 127.0.0.1:${started.port}, ${started.replayed} spooled event(s) replayed (Ctrl-C to stop)`);
-    // Ends on Ctrl-C, or when uninstall asks it to stop (POST /shutdown).
+    // Ends on Ctrl-C, or when a command asks it to stop (POST /shutdown: a listener taking over, uninstall).
     await new Promise((resolve) => {
         started.server.on("close", resolve);
-        process.on("SIGINT", () => started.server.close());
+        // Once: hooks in flight finish after the first Ctrl-C; a second one ends the process at once.
+        process.once("SIGINT", () => {
+            ctx.out("  · [heedvane] listener stopping: Ctrl-C");
+            started.server.close();
+            started.server.closeIdleConnections();
+        });
     });
     return 0;
 }
+/** Why `listener start` did not start: 0 when a listener it keeps already runs, PORT_TAKEN_EXIT when the one there did not stop; else rethrows. */
+function startRefusal(ctx, err) {
+    if (err instanceof ListenerAlreadyRuns) {
+        ctx.out(`  · ${err.message}; nothing to start`);
+        return 0;
+    }
+    if (err.code !== "EADDRINUSE")
+        throw err;
+    const port = err.port ?? 0;
+    ctx.out(`  ✗ 127.0.0.1:${port} stays taken: the Heedvane listener there did not stop when asked. Stop it: ${stopCommand(port)}`);
+    return PORT_TAKEN_EXIT;
+}
+/** `listener restart`: a background listener with heed.yaml and the sign-in as they are now (after a hand edit). */
+async function cmdListenerRestart(ctx) {
+    await ensureEndpoint(join(ctx.home, ".heed"));
+    const outcome = await ctx.ensureListener(ctx.home);
+    const stillRunning = sayListenerFully(outcome, (line) => ctx.out(`  ${line}`));
+    if (outcome.kind === "running")
+        ctx.out("  ✓ the listener runs with heed.yaml and the sign-in as they are now");
+    return stillRunning !== undefined || outcome.kind === "did not start" ? 1 : 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).
+ * `run -- <agent command>`: for CI, containers and software factories. The run makes sure the machine's listener runs
+ * with the current settings ({@link ensureListener}), as every command does, and runs the agent with it; parallel runs
+ * share it. The agent keeps stdin, stdout and stderr; 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); Heedvane never keeps the agent
+ * from running.
  */
 async function cmdRun(ctx) {
     const say = (line) => void process.stderr.write(`heedvane: ${line}\n`);
@@ -635,23 +873,27 @@ async function cmdRun(ctx) {
         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));
-    }
+    // Heedvane never keeps the agent from running: a heed folder it cannot write runs the agent unchecked, and says so.
+    await prepareRun(ctx, root, say).catch((err) => {
+        say(`could not make sure the listener runs (${errorMessage(err)}), so this run's calls may not be checked`);
+        return undefined; // the agent runs all the same
+    });
+    // shortcut: the listener outlives the run, so in a container that ends with the agent a delivery report still waiting for its retry is lost; flush before returning if factories miss reports.
+    // HEED_AGENT_HOOK_ROOT: the hooks keep the spool in this heed folder, also when HEED_HOME is not $HOME.
+    return runAgent({ command: ctx.command, env: { ...ctx.env, HEED_HOME: ctx.home, HEED_AGENT_HOOK_ROOT: root }, say });
+}
+/** Before `run`'s agent starts: the heed folder, a hint when nothing is signed in, and the listener with the current settings. */
+async function prepareRun(ctx, root, say) {
+    await ensureEndpoint(root); // a fresh container has no ~/.heed yet
+    const settings = await settingsToRun(root).catch((err) => void say(`~/.heed/heed.yaml does not parse (${errorMessage(err)}), so guardrails are off`));
+    if (settings !== undefined && (await backendAt(root, settings.config.url)) === null)
+        say("not signed in, so guardrails are off: printf '%s' \"$HEEDVANE_ORG_KEY\" | npx -y heedvane auth org");
+    const stillRunning = sayListener(await ctx.ensureListener(ctx.home), (line) => say(line.replace(/^[✓·] /, "")));
+    if (stillRunning !== undefined)
+        say(stillRunning);
 }
 /** 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) {
+function runAgent({ command: [program, ...args], env, say }) {
     return new Promise((resolve) => {
         const child = spawn(program, args, { stdio: "inherit", env });
         const forward = (signal) => void child.kill(signal);
@@ -676,12 +918,15 @@ function backendCommandContext(ctx) {
  * The command that opens `url` in the default browser. Windows goes through rundll32, not `cmd /c start`:
  * cmd would cut the sign-in URL at its first `&`.
  */
-export function browserOpener(platform, url) {
+/** The command that opens `url`: `$BROWSER` when set (a no-op such as `true` keeps captures and tests off a real browser), else the platform's opener. */
+export function browserOpener(platform, url, browser) {
+    if (browser)
+        return [browser, [url]];
     const openers = { darwin: ["open", [url]], win32: ["rundll32", ["url.dll,FileProtocolHandler", url]] };
     return openers[platform] ?? ["xdg-open", [url]];
 }
-function openSystemBrowser(url) {
-    const [command, args] = browserOpener(process.platform, url);
+function openSystemBrowser(url, browser) {
+    const [command, args] = browserOpener(process.platform, url, browser);
     const child = spawn(command, args, { detached: true, stdio: "ignore" });
     child.on("error", () => undefined); // no browser opener: the printed URL is the way in
     child.unref();