heedvane 0.3.3 → 0.3.4

package/dist/cli.js

@@ -1,32 +1,34 @@
 #!/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 { 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 { DATA_MODES, DEFAULT_HEED_YAML_TEMPLATE, heedvaneConfigAt, loadHeedFile, loadHeedFileAt, withInstallChoices, withSettings } from "./heed-file.js";
-import { planActions, desiredEntriesFor, heedvaneConnector, installingNodeDir, 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 { writeDispatcherScript, writeHookNode } from "./dispatchers/posix.js";
 import { removeDeferredHookGroups, removeLegacyMcpEntries, removeStaleHookGroups, uninstall } from "./uninstall.js";
 import { statusText } from "./status.js";
-import { MCP_NEEDS_ORG } from "./mcp.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";
@@ -43,7 +45,7 @@ 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
@@ -112,13 +114,17 @@ 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;
 }
@@ -146,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;
     }
@@ -174,7 +180,7 @@ function commandContext(argv, opts) {
         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) {
@@ -200,15 +206,22 @@ async function routeServiceCommand(command, ctx) {
             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:
@@ -258,7 +271,7 @@ async function cmdInit(ctx) {
     }
     let serverEdit;
     try {
-        serverEdit = withFlags(home, loaded, ctx);
+        serverEdit = withFlags(loaded, ctx);
     }
     catch (err) {
         out("");
@@ -294,9 +307,16 @@ function flagSettings({ server, org, mode }) {
     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. */
-function withFlags(home, loaded, flags) {
-    const settings = flagSettings(flags);
+/**
+ * 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);
@@ -311,53 +331,69 @@ function withFlags(home, loaded, flags) {
         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; Heedvane joins it at session start.");
-    if (spec.heedFile.install.mcp && heedvaneConnector(spec.heedFile) === undefined)
-        out(`  ${MCP_NEEDS_ORG}`);
-    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 });
+    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)
+        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: installingNodeDir(),
-    };
-    const applied = await applyPlan(actions, { home, env, out, dispatcher, connector: heedvaneConnector(heedFile) });
+    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);
@@ -369,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;
@@ -427,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);
@@ -436,23 +579,44 @@ 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, installDetails(spec.heedFile, heedvaneConnector(spec.heedFile)), 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), 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`, `--org` and `--mode` applied, parsed; a message when it cannot be used. */
 function installerBase(ctx) {
@@ -460,7 +624,7 @@ function installerBase(ctx) {
     if (loaded.error)
         return `~/.heed/heed.yaml does not parse: ${loaded.error}`;
     try {
-        return withFlags(ctx.home, loaded, ctx) ?? { heedFile: loaded.heedFile, existed: loaded.existed, text: heedText(ctx.home, loaded.existed) };
+        return withFlags(loaded, ctx) ?? { heedFile: loaded.heedFile, existed: loaded.existed, text: heedText(ctx.home, loaded.existed) };
     }
     catch (err) {
         return errorMessage(err);
@@ -469,24 +633,23 @@ function installerBase(ctx) {
 function agentOptions({ home, env }) {
     return detectionRows(home, env).map(({ client, detected }) => ({ id: client.id, name: client.displayName, detected, capability: capabilitySummary(client) }));
 }
-function nextSteps(listening, heedFile) {
+function nextSteps(listening, heedFile, stillRunning) {
     const server = heedFile.heedvane.url;
     return [
-        "Open a new agent session: Heedvane joins it at session start.",
-        ...(heedFile.install.mcp && heedvaneConnector(heedFile) === undefined ? [MCP_NEEDS_ORG] : []),
+        ...(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. */
@@ -512,15 +675,17 @@ async function withoutStaleHookGroups(client, writes, result) {
     }
     return worst;
 }
-/** After the writes: our hook groups under events no longer installed, and what an earlier version registered as MCP (the local helper, the connection's earlier name), with or without a connection to write. */
+/** 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);
-    return kind === "mcp" ? withRemovals(await removeLegacyMcpEntries(client), done.result) : 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, connector: ctx.connector });
+    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) {
@@ -540,9 +705,10 @@ async function applyConfigEntries(action, client, ctx) {
             worst = res;
     }
     if (worst.status !== "failed" && worst.status !== "invalid")
-        worst = await withoutLeftovers(action.kind, client, { writes: writes.values(), result: worst });
-    // The dispatcher script the snippet delegates to.
-    await writeDispatcherScript(ctx.home, client.id, ctx.dispatcher);
+        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,
@@ -559,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) {
@@ -643,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`);
@@ -670,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);