@agentvault/grok-bridge 0.1.0 → 0.2.1

package/README.md

@@ -6,6 +6,60 @@ Bridges a Grok agent into E2E-encrypted AgentVault direct messages and rooms.
 no runtime code. The only shared dependency is `@agentvault/agentvault`, the
 protocol and crypto library.
 
+## Usage
+
+**Prerequisite:** install Grok and run `grok login`. The bridge copies that
+credential into its sandbox once, at first run.
+
+### One paste (recommended) — `--install`
+
+```sh
+npm i -g @agentvault/grok-bridge
+AV_AGENT_NAME=<agent> AV_INVITE_TOKEN=<token> agentvault-grok-bridge --install
+```
+
+Enrols the agent, waits for you to click **Approve** in the dashboard, installs a
+supervised OS service (launchd on macOS, systemd on Linux), and **exits** — so
+your terminal comes back and the agent survives closing it and rebooting.
+
+Three things worth knowing:
+
+- **`npm i -g` is not optional.** The service bakes the running entrypoint into
+  its launcher. Under `npx` that is a package cache the package manager later
+  prunes, so the service would work today and die silently weeks later.
+  `--install` refuses an ephemeral entrypoint at startup, before your single-use
+  invite token is spent.
+- **`XAI_API_KEY` is NOT inherited by the service.** A supervisor does not read
+  your shell environment. Use `grok login`; the bridge refuses to install a
+  service that would have no credential and run mute.
+- **Re-running is safe.** With credentials already saved you can omit the token.
+  If the installed service is current it is restarted, not re-installed, so
+  settings baked at install time are preserved.
+
+### Foreground (no service)
+
+```sh
+AV_AGENT_NAME=<agent> AV_INVITE_TOKEN=<token> npx @agentvault/grok-bridge
+```
+
+Runs in the terminal and stops when you close it. Unchanged by `--install`.
+
+### Managing the service
+
+```sh
+agentvault-grok-bridge status      # is it loaded?
+agentvault-grok-bridge restart     # pick up new credentials / recover
+agentvault-grok-bridge uninstall   # remove it
+agentvault-grok-bridge logs        # where the logs are
+```
+
+Use `restart`, **never `install`**, to restart. `install` rebuilds the service
+from your current shell and re-bakes `PATH`, silently discarding environment
+baked at the original install.
+
+Logs go to `<data-dir>/logs/grok-bridge.error.log` — the bridge writes to stderr,
+so the `.error.log` file is the one with content in it.
+
 ## Copied-from ledger — REVIEW PERIODICALLY
 
 These files were copied once from the Claude bridge and are now owned here. A fix

package/dist/config.d.ts

@@ -1,3 +1,40 @@
+/**
+ * The one-paste install flag: enrol, install the supervised service, then EXIT so
+ * the customer's terminal comes back.
+ *
+ * WIRE LITERAL. `packages/web/lib/framework-install.ts` emits this exact string in
+ * the connect command. The two packages cannot import each other, so the only
+ * tripwire is a test on each side that names the other — see config.test.ts
+ * "freezes the wire literal".
+ *
+ * Deliberately "-" prefixed: loadConfig's token slot rejects "-" args, so adding a
+ * flag can never be mistaken for an invite token.
+ */
+export declare const INSTALL_FLAG = "--install";
+/** Informational flags. Handled BEFORE loadConfig in index.ts, because asking
+ *  "what version is this?" must not require an invite token. Listed here too so
+ *  the strict unknown-flag check does not reject them. */
+export declare const VERSION_FLAGS: readonly ["--version", "-v"];
+export declare const HELP_FLAGS: readonly ["--help", "-h"];
+/** Pure argv read for the informational flags. Deliberately independent of
+ *  loadConfig: that throws without a token, and `--version` must answer anyway. */
+export declare function parseInfoFlags(argv: string[]): {
+    showVersion: boolean;
+    showHelp: boolean;
+};
+/**
+ * Package-manager scratch caches. `service/subcommand.ts` bakes `process.argv[1]`
+ * into the launcher script, so a service installed from one of these points at a
+ * directory the package manager later prunes — it works today and dies weeks later
+ * with nothing naming the cause.
+ *
+ * A DENYLIST, not proof of durability: it covers npm's npx cache, pnpm/yarn `dlx`,
+ * `bunx`, and anything under the OS temp dir. Other ephemeral runners are knowingly
+ * unhandled.
+ */
+export declare function isEphemeralEntrypoint(entrypoint: string): boolean;
+/** Throw unless `entrypoint` is durable enough to bake into a supervised service. */
+export declare function assertInstallableEntrypoint(entrypoint: string): void;
 export declare function hasPersistedCreds(dataDir: string): boolean;
 export declare function slugify(name: string): string;
 export type DataDirSource = "explicit" | "per-agent";
@@ -38,6 +75,14 @@ export interface BridgeConfig {
      *  instructs the agent. It does not: given a bare message the model answered
      *  in prose and never called room__say, so the reply was discarded. */
     systemPrompt?: string;
+    /** Set by --install: enrol in the foreground, install the supervised service,
+     *  then EXIT so the customer's terminal returns. False leaves a bare run
+     *  byte-for-byte as it behaves today. */
+    installAfterEnroll: boolean;
+    /** --version / -v. index.ts answers these before loadConfig runs. */
+    showVersion: boolean;
+    /** --help / -h. Same. */
+    showHelp: boolean;
 }
 export declare function loadConfig(env: NodeJS.ProcessEnv, argv?: string[]): BridgeConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/index.js

@@ -12,6 +12,24 @@ var __export = (target, all) => {
 // src/config.ts
 import { existsSync, readFileSync as readFileSync2, mkdirSync, chmodSync } from "node:fs";
 import { join as join5, resolve as resolve2, sep, dirname } from "node:path";
+import { tmpdir } from "node:os";
+function parseInfoFlags(argv) {
+  return {
+    showVersion: argv.some((a2) => VERSION_FLAGS.includes(a2)),
+    showHelp: argv.some((a2) => HELP_FLAGS.includes(a2))
+  };
+}
+function isEphemeralEntrypoint(entrypoint) {
+  return entrypoint.includes("/_npx/") || entrypoint.includes("/dlx-") || entrypoint.includes("/.bun/install/cache/") || entrypoint.startsWith(tmpdir() + sep);
+}
+function assertInstallableEntrypoint(entrypoint) {
+  if (isEphemeralEntrypoint(entrypoint)) {
+    throw new Error(
+      `cannot install a background service from an ephemeral package cache (${entrypoint}) \u2014 it is deleted on cleanup and the service would silently die later. Install globally first:
+  npm i -g @agentvault/grok-bridge && agentvault-grok-bridge ` + INSTALL_FLAG
+    );
+  }
+}
 function hasRecoverableBackup(dataDir) {
   try {
     const parsed = JSON.parse(readFileSync2(join5(dataDir, BACKUP_FILE), "utf-8"));
@@ -35,6 +53,12 @@ function resolveDataDir(env) {
 function loadConfig(env, argv = []) {
   const { dataDir, source: dataDirSource } = resolveDataDir(env);
   const inviteToken = (argv[0] && !argv[0].startsWith("-") ? argv[0] : "") || env.AV_INVITE_TOKEN || "";
+  const unknownFlags = argv.filter((a2) => a2.startsWith("-") && !KNOWN_FLAGS.has(a2));
+  if (unknownFlags.length) {
+    throw new Error(
+      `unknown option(s): ${unknownFlags.join(", ")} \u2014 supported flags are ${[...KNOWN_FLAGS].join(", ")}`
+    );
+  }
   const workspaceDir = env.AV_WORKSPACE_DIR || join5(dirname(dataDir), "workspaces", slugify2(env.AV_AGENT_NAME ?? "grok"));
   const wsReal = resolve2(workspaceDir);
   const ddReal = resolve2(dataDir);
@@ -60,6 +84,10 @@ function loadConfig(env, argv = []) {
     inviteToken,
     dataDir,
     dataDirSource,
+    // One-paste install (--install): enrol, hand off to the supervisor, exit.
+    // Default false keeps a bare `npx @agentvault/grok-bridge` run identical.
+    installAfterEnroll: argv.includes(INSTALL_FLAG),
+    ...parseInfoFlags(argv),
     apiUrl: env.AV_API_URL ?? "https://api.agentvault.chat",
     // Identity shown to the agent's own session. Set this to the agent's
     // AgentVault name via AV_AGENT_NAME (the native connect command passes it).
@@ -76,10 +104,14 @@ function loadConfig(env, argv = []) {
     systemPrompt: env.AV_SYSTEM_PROMPT || void 0
   };
 }
-var CRED_FILES, BACKUP_FILE;
+var INSTALL_FLAG, VERSION_FLAGS, HELP_FLAGS, KNOWN_FLAGS, CRED_FILES, BACKUP_FILE;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
+    INSTALL_FLAG = "--install";
+    VERSION_FLAGS = ["--version", "-v"];
+    HELP_FLAGS = ["--help", "-h"];
+    KNOWN_FLAGS = /* @__PURE__ */ new Set([INSTALL_FLAG, ...VERSION_FLAGS, ...HELP_FLAGS]);
     CRED_FILES = ["agentvault.json", "secure-channel.json"];
     BACKUP_FILE = "agentvault.json.bak";
   }
@@ -94,6 +126,9 @@ function stamp(message) {
 function logLine(...args) {
   console.error(stamp(format(...args)));
 }
+function printLine(text) {
+  console.log(text);
+}
 var init_log = __esm({
   "src/log.ts"() {
     "use strict";
@@ -130,6 +165,16 @@ function writeLauncher(deps, spec) {
   deps.writeFile(spec.launcherPath, spec.launcherScript);
   deps.chmod(spec.launcherPath, 493);
 }
+function parseLauncherEntrypoint(script) {
+  if (!script) return void 0;
+  const m2 = /^if n=\$\(command -v .+\); then exec "\$n" (.+) "\$@"; fi$/m.exec(script);
+  if (!m2) return void 0;
+  return unSq(m2[1]);
+}
+function unSq(quoted) {
+  if (quoted.length < 2 || !quoted.startsWith("'") || !quoted.endsWith("'")) return void 0;
+  return quoted.slice(1, -1).replace(/'\\''/g, "'");
+}
 var FALLBACK_NODES;
 var init_launcher = __esm({
   "src/service/launcher.ts"() {
@@ -353,6 +398,11 @@ var init_systemd = __esm({
 });
 
 // src/service/backend.ts
+var backend_exports = {};
+__export(backend_exports, {
+  defaultDeps: () => defaultDeps,
+  selectBackend: () => selectBackend
+});
 import { spawnSync } from "node:child_process";
 import { mkdirSync as mkdirSync4, writeFileSync as writeFileSync2, rmSync, existsSync as existsSync3, chmodSync as chmodSync4 } from "node:fs";
 import { userInfo } from "node:os";
@@ -399,7 +449,17 @@ function labelFor(env) {
 }
 function maybeRunServiceSubcommand(argv, env, deps) {
   const cmd = argv[2];
-  if (!cmd || !SERVICE_CMDS.has(cmd)) return false;
+  if (!cmd) return false;
+  if (!SERVICE_CMDS.has(cmd)) {
+    const looksLikeToken = cmd.startsWith("av_tok_");
+    const looksLikeFlag = cmd.startsWith("-");
+    if (!looksLikeToken && !looksLikeFlag) {
+      throw new Error(
+        `unknown subcommand: ${cmd} \u2014 expected one of ${[...SERVICE_CMDS].join(", ")}, an invite token, or no argument at all`
+      );
+    }
+    return false;
+  }
   const backend = deps?.backend ?? selectBackend(process.platform);
   const entrypoint = deps?.entrypoint ?? process.argv[1];
   const log = deps?.log ?? ((m2) => logLine("[grok-bridge] " + m2));
@@ -420,7 +480,7 @@ function maybeRunServiceSubcommand(argv, env, deps) {
         path: env.PATH ?? ""
       });
       backend.install(spec);
-      log(`installed service ${spec.label} \u2014 logs: ${spec.logOut}`);
+      log(`installed service ${spec.label} \u2014 logs: ${spec.logErr}`);
       log(`check it with: agentvault-grok-bridge status`);
     } else if (cmd === "uninstall") {
       const label = labelFor(env);
@@ -456,10 +516,103 @@ var init_subcommand = __esm({
   }
 });
 
+// src/service/install-on-ready.ts
+var install_on_ready_exports = {};
+__export(install_on_ready_exports, {
+  installOnReady: () => installOnReady
+});
+import { existsSync as existsSync4, readFileSync as readFileSync3 } from "node:fs";
+import { join as join12 } from "node:path";
+function installOnReady(channel, cfg, deps) {
+  const hasCreds = deps.hasCreds ?? hasPersistedCreds;
+  const readLauncher = deps.readLauncher ?? ((p2) => existsSync4(p2) ? readFileSync3(p2, "utf8") : void 0);
+  const fenceAuthExists = deps.fenceAuthExists ?? ((home) => existsSync4(join12(home, ".grok", "auth.json")));
+  let fired = false;
+  channel.on("ready", () => {
+    if (fired) return;
+    fired = true;
+    void (async () => {
+      try {
+        if (!hasCreds(cfg.dataDir)) {
+          throw new Error(
+            `enrolment did not persist credentials to ${cfg.dataDir} \u2014 refusing to install a service that would crash-loop`
+          );
+        }
+        if (!fenceAuthExists(cfg.fenceHome)) {
+          throw new Error(
+            "no grok credential in the fence \u2014 run `grok login`, then paste the same command again (your enrolment is already saved, so the token is not needed). Note that XAI_API_KEY from your shell is NOT inherited by the background service."
+          );
+        }
+        if (deps.waitForIdle) {
+          const timeoutMs = deps.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+          let timer;
+          const timedOut = await Promise.race([
+            deps.waitForIdle().then(() => false),
+            new Promise((r2) => {
+              timer = setTimeout(() => r2(true), timeoutMs);
+            })
+          ]);
+          if (timer) clearTimeout(timer);
+          if (timedOut) {
+            deps.log(
+              `agent still busy after ${timeoutMs}ms \u2014 handing off anyway; that reply may be lost`
+            );
+          }
+        }
+        const reaped = await deps.reap();
+        if (!reaped.ok) {
+          throw new Error(
+            `teardown did not complete (${reaped.failures.join("; ")}) \u2014 refusing to install over a session that may still be open`
+          );
+        }
+        const backend = deps.backend ?? selectBackend(process.platform);
+        const spec = buildServiceSpec(cfg, {
+          entrypoint: deps.entrypoint,
+          home: deps.env.HOME ?? "",
+          path: deps.env.PATH ?? ""
+        });
+        const installedEntrypoint = parseLauncherEntrypoint(readLauncher(spec.launcherPath));
+        const entrypointIsCurrent = installedEntrypoint !== void 0 && !isEphemeralEntrypoint(installedEntrypoint) && installedEntrypoint === deps.entrypoint;
+        if (backend.status(spec.label).loaded && entrypointIsCurrent) {
+          backend.restart(spec.label);
+          deps.log(`service ${spec.label} already installed and current \u2014 restarted`);
+        } else {
+          backend.install(spec);
+          deps.log(
+            installedEntrypoint && !entrypointIsCurrent ? `service ${spec.label} pointed at a stale entrypoint (${installedEntrypoint}) \u2014 re-installed` : `installed service ${spec.label}`
+          );
+        }
+        const after = backend.status(spec.label);
+        if (!after.loaded) {
+          throw new Error(`service did not load: ${after.detail}`);
+        }
+        deps.log(`it is running now. logs: ${spec.logErr}`);
+        deps.log(`check it:   agentvault-grok-bridge status`);
+        deps.log(`restart it: agentvault-grok-bridge restart   (never 'install')`);
+        deps.exit(0);
+      } catch (e) {
+        deps.log(`--install failed: ${e instanceof Error ? e.message : String(e)}`);
+        deps.exit(1);
+      }
+    })();
+  });
+}
+var DEFAULT_IDLE_TIMEOUT_MS;
+var init_install_on_ready = __esm({
+  "src/service/install-on-ready.ts"() {
+    "use strict";
+    init_config();
+    init_spec();
+    init_launcher();
+    init_backend();
+    DEFAULT_IDLE_TIMEOUT_MS = 3e4;
+  }
+});
+
 // src/index.ts
 import { spawn } from "node:child_process";
 import { mkdirSync as mkdirSync5 } from "node:fs";
-import { join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 
 // ../plugin/dist/index.js
 import * as nc from "node:crypto";
@@ -69938,7 +70091,8 @@ ${messageText}`;
           const candidateCount = candidates.filter(Boolean).length;
           const joined = await joinWithFirstMatchingKp(welcomeBytes, candidates);
           if (!joined) {
-            console.error(`[SecureChannel] No matching KeyPackage found for Welcome \u2014 cannot join group ${groupId?.slice(0, 8)}. The Welcome is encrypted to a published KP's public key; none of our ${candidateCount} candidate bundle(s) decrypted it. The existing Welcome recovery mechanism will re-request.`);
+            console.error(`[SecureChannel] No matching KeyPackage found for Welcome \u2014 cannot join group ${groupId?.slice(0, 8)}. The Welcome is encrypted to a published KP's public key; none of our ${candidateCount} candidate bundle(s) decrypted it. Requesting a re-Welcome with a fresh KeyPackage.`);
+            if (groupId) void this._requestWelcomeSelfHeal(groupId);
             return;
           }
           const mgr = joined.mgr;
@@ -98846,16 +99000,76 @@ function buildClientVersion2(version2) {
   return `@agentvault/grok-bridge@${version2 ?? "dev"}`;
 }
 
+// src/reap.ts
+var DEFAULT_KILL_TIMEOUT_MS = 5e3;
+var SIGKILL_GRACE_MS = 250;
+function childHasExited(child) {
+  return child.exitCode !== null && child.exitCode !== void 0 || child.signalCode !== null && child.signalCode !== void 0;
+}
+function waitForChildExit(child, killTimeoutMs, log) {
+  if (childHasExited(child)) return Promise.resolve();
+  return new Promise((resolve3) => {
+    let settled = false;
+    const timers = [];
+    const done = () => {
+      if (settled) return;
+      settled = true;
+      for (const t2 of timers) clearTimeout(t2);
+      resolve3();
+    };
+    child.on("exit", done);
+    timers.push(
+      setTimeout(() => {
+        log(`grok child ignored SIGTERM after ${killTimeoutMs}ms \u2014 escalating to SIGKILL`);
+        try {
+          child.kill?.("SIGKILL");
+        } catch {
+        }
+        timers.push(setTimeout(done, SIGKILL_GRACE_MS));
+      }, killTimeoutMs)
+    );
+  });
+}
+async function reap(r2, opts = {}) {
+  const log = opts.log ?? (() => {
+  });
+  const killTimeoutMs = opts.killTimeoutMs ?? DEFAULT_KILL_TIMEOUT_MS;
+  const failures = [];
+  const attempt = async (label, fn) => {
+    try {
+      await fn();
+    } catch (e) {
+      const msg = `${label}: ${e instanceof Error ? e.message : String(e)}`;
+      failures.push(msg);
+      log(`reap: ${msg}`);
+    }
+  };
+  if (r2.channel) await attempt("channel.stop", () => r2.channel.stop());
+  if (r2.driver) await attempt("driver.stop", () => r2.driver.stop());
+  if (r2.child) await waitForChildExit(r2.child, killTimeoutMs, log);
+  if (r2.mcp) await attempt("mcp.close", () => r2.mcp.close());
+  return { ok: failures.length === 0, failures };
+}
+
 // src/index.ts
 var shuttingDown = false;
+var exiting = false;
 var driver;
 var mcp;
-var shutdown = async (code = 0) => {
-  if (shuttingDown) return;
+var channelRef;
+var childRef;
+var reapAll = async () => {
   shuttingDown = true;
+  return reap(
+    { channel: channelRef, driver, mcp, child: childRef },
+    { log: (m2) => logLine("[grok-bridge] " + m2) }
+  );
+};
+var shutdown = async (code = 0) => {
+  if (exiting) return;
+  exiting = true;
   try {
-    await driver?.stop();
-    await mcp?.close();
+    await reapAll();
   } finally {
     process.exit(code);
   }
@@ -98867,7 +99081,53 @@ async function main() {
   })) {
     process.exit(process.exitCode ?? 0);
   }
+  const info = parseInfoFlags(process.argv.slice(2));
+  if (info.showVersion || info.showHelp) {
+    const version2 = buildClientVersion2(
+      true ? "0.2.1" : void 0
+    );
+    if (info.showVersion) printLine(version2);
+    if (info.showHelp) {
+      printLine(
+        [
+          "",
+          `${version2}`,
+          "",
+          "  Bridges a Grok agent into E2E-encrypted AgentVault DMs and rooms.",
+          "",
+          "USAGE",
+          "  agentvault-grok-bridge [<invite-token>] [--install]",
+          "  agentvault-grok-bridge <install|uninstall|restart|status|logs>",
+          "",
+          "FLAGS",
+          "  --install        Enrol, install a supervised OS service, then EXIT so",
+          "                   your terminal returns. Requires a global install:",
+          "                   npm i -g @agentvault/grok-bridge",
+          "  --version, -v    Print the version.",
+          "  --help, -h       Print this.",
+          "",
+          "ENV",
+          "  AV_AGENT_NAME    The agent's AgentVault name. Required.",
+          "  AV_INVITE_TOKEN  First enrolment only; a saved data dir reconnects without it.",
+          "  AV_DATA_DIR      Credential/state dir. Defaults per agent.",
+          "",
+          "NOTES",
+          "  Run `grok login` first. XAI_API_KEY from your shell is NOT inherited by a",
+          "  supervised service, so --install refuses rather than run mute.",
+          "  To restart later use `restart`, never `install` \u2014 install re-bakes the",
+          "  service from your current shell and drops env from the original install.",
+          ""
+        ].join("\n")
+      );
+    }
+    process.exit(0);
+  }
   const cfg = loadConfig(process.env, process.argv.slice(2));
+  if (cfg.installAfterEnroll) {
+    assertInstallableEntrypoint(process.argv[1]);
+    const { selectBackend: selectBackend2 } = await Promise.resolve().then(() => (init_backend(), backend_exports));
+    selectBackend2(process.platform);
+  }
   mkdirSync5(cfg.workspaceDir, { recursive: true });
   mkdirSync5(cfg.fenceHome, { recursive: true });
   seedFenceCredential({
@@ -98882,9 +99142,10 @@ async function main() {
     agentName: cfg.agentName,
     platform: "node",
     clientVersion: buildClientVersion2(
-      true ? "0.1.0" : void 0
+      true ? "0.2.1" : void 0
     )
   });
+  channelRef = channel;
   let session;
   mcp = await startRoomMcpServer({
     // `session` is assigned further down. The current ordering is safe — grok
@@ -98902,7 +99163,7 @@ async function main() {
     },
     log: (m2) => logLine(m2)
   });
-  const pluginDir = join12(cfg.fenceHome, "av-room-plugin");
+  const pluginDir = join13(cfg.fenceHome, "av-room-plugin");
   writeRoomPluginHttp(pluginDir, mcp.url);
   const spawnSpec = grokSpawnArgs({
     grokPath: cfg.grokPath,
@@ -98917,6 +99178,7 @@ async function main() {
     env: spawnSpec.env,
     stdio: ["pipe", "pipe", "pipe"]
   });
+  childRef = child;
   child.on("error", (err) => {
     logLine(`[grok-bridge] fatal: ${describeSpawnFailure(err, spawnSpec)}`);
     process.exit(1);
@@ -98966,6 +99228,23 @@ async function main() {
     log: (m2) => logLine("[grok-bridge] " + m2),
     onTerminal: (_reason, o2) => void shutdown(o2.restart ? 1 : 0)
   });
+  if (cfg.installAfterEnroll) {
+    const { installOnReady: installOnReady2 } = await Promise.resolve().then(() => (init_install_on_ready(), install_on_ready_exports));
+    installOnReady2(channel, cfg, {
+      entrypoint: process.argv[1],
+      env: process.env,
+      // FOUND LIVE 2026-08-16: the owner's activation greeting is usually already
+      // being answered when `ready` fires, and reaping mid-turn killed the reply
+      // for good — the message was acked, so the service never saw it again.
+      // GrokSession.idle() resolves when the queue drains.
+      waitForIdle: () => session.idle(),
+      // The one shared teardown. `exiting` is deliberately NOT set here: Ctrl-C
+      // must keep working for the whole multi-second launchctl window.
+      reap: reapAll,
+      exit: (code) => process.exit(code),
+      log: (m2) => logLine("[grok-bridge] " + m2)
+    });
+  }
   await channel.start();
 }
 main().catch(async (err) => {

package/dist/log.d.ts

@@ -19,4 +19,16 @@ export declare function stamp(message: string): string;
  * just anchored to a clock.
  */
 export declare function logLine(...args: unknown[]): void;
+/**
+ * Plain stdout, no timestamp. For CLI answers a human or a script reads —
+ * `--version` and `--help` — not for daemon logging.
+ *
+ * `logLine` stamps every line and writes to stderr, which is right for a daemon
+ * and wrong here: `agentvault-grok-bridge --version` must print a version, not a
+ * version wearing a date. Anything a script would parse belongs on stdout.
+ *
+ * This lives in log.ts because the "no bare console sinks" guard test excludes
+ * only this file — the sink belongs here, and nowhere else.
+ */
+export declare function printLine(text: string): void;
 //# sourceMappingURL=log.d.ts.map

package/dist/reap.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The ONE teardown path. Both `shutdown()` and the `--install` hand-off call this;
+ * nothing copies its body.
+ *
+ * WHY IT IS SHARED. An earlier design inlined a second copy inside the install
+ * flow. That copy stopped only the driver and the MCP listener — it never closed
+ * the AgentVault WebSocket, and it did not wait for the grok child to die. Both
+ * omissions are invisible in a unit test that substitutes the teardown closure,
+ * and both matter: `LaunchdBackend.install` runs bootout -> poll-until-gone ->
+ * bootstrap -> kickstart synchronously, so the supervised service is alive the
+ * instant install returns. A half-reaped foreground process means two ACP sessions
+ * and two WebSockets for one device.
+ */
+export interface Reapable {
+    /** SecureChannel. `stop()` closes the WS, flushes pending ACKs, and sets the
+     *  stopped flag so it will not reconnect. */
+    channel?: {
+        stop(): Promise<void>;
+    };
+    driver?: {
+        stop(): Promise<void>;
+    };
+    mcp?: {
+        close(): Promise<void>;
+    };
+    /** The grok child. `exitCode`/`signalCode` are read to detect an ALREADY-dead
+     *  child; both are non-null once it has exited.
+     *
+     *  ⚠️ The signal parameter is `NodeJS.Signals`, NOT `string`. A real
+     *  `ChildProcess.kill` is `(signal?: NodeJS.Signals | number) => boolean`, and
+     *  parameter types are contravariant — declaring `string` here makes a real
+     *  ChildProcess UNASSIGNABLE to this shape and fails the strict build at the
+     *  index.ts call site. `signalCode` is `NodeJS.Signals | null` for the same
+     *  reason. Verified: widening it to `string` reintroduces TS2322. */
+    child?: {
+        kill?: (signal: NodeJS.Signals) => unknown;
+        on(event: "exit", listener: () => void): unknown;
+        exitCode?: number | null;
+        signalCode?: NodeJS.Signals | null;
+    };
+}
+export interface ReapResult {
+    /** False if any stage failed. Callers that treat a complete teardown as a
+     *  PRECONDITION (the --install hand-off does) must refuse to continue on false
+     *  rather than install over a socket that may still be open. */
+    ok: boolean;
+    failures: string[];
+}
+/**
+ * Tear everything down, in the one order that is safe.
+ *
+ * CHANNEL FIRST. Closing it stops new inbound before anything else is dismantled.
+ * With the channel last, the WebSocket keeps delivering room and DM traffic into a
+ * session whose driver is already dying, for as long as the child takes to exit —
+ * turn failures and dropped messages inside the very window this function exists
+ * to make empty. `stop()` also flushes pending ACKs, which it can only do over a
+ * socket that is still up.
+ *
+ * Every stage is guarded separately: one failure must not strand the others. A
+ * driver that throws must never leave the WebSocket open.
+ */
+export declare function reap(r: Reapable, opts?: {
+    killTimeoutMs?: number;
+    log?: (m: string) => void;
+}): Promise<ReapResult>;
+//# sourceMappingURL=reap.d.ts.map

package/dist/service/install-on-ready.d.ts

@@ -0,0 +1,57 @@
+import { type BridgeConfig } from "../config.js";
+import type { ReapResult } from "../reap.js";
+import { type ServiceBackend } from "./backend.js";
+export interface InstallOnReadyDeps {
+    entrypoint: string;
+    env: NodeJS.ProcessEnv;
+    backend?: ServiceBackend;
+    hasCreds?: (dataDir: string) => boolean;
+    /** Contents of the installed launcher, or undefined when none is installed. */
+    readLauncher?: (path: string) => string | undefined;
+    fenceAuthExists?: (fenceHome: string) => boolean;
+    /** Resolves when no turn is in flight (GrokSession.idle). See rule 2. */
+    waitForIdle?: () => Promise<void>;
+    /** Bound on that wait. The terminal coming back is the product promise, so a
+     *  wedged turn must never hold the customer's shell open. */
+    idleTimeoutMs?: number;
+    /** The ONE teardown (src/reap.ts). Must complete before launchctl runs. */
+    reap: () => Promise<ReapResult>;
+    exit: (code: number) => void;
+    log: (msg: string) => void;
+}
+interface ReadyChannel {
+    on(ev: "ready", cb: () => void): unknown;
+}
+/**
+ * One-paste install: enrol in the foreground, hand off to the supervisor, exit —
+ * so the customer's terminal comes back and the agent survives a reboot.
+ *
+ * Four rules this module exists to enforce.
+ *
+ * 1. REFUSE BEFORE REAPING. Everything that can say no does so before anything is
+ *    torn down. Refusing afterwards leaves the customer with an approved device,
+ *    a spent invite token, and no running process — strictly worse than never
+ *    having guarded at all.
+ *
+ * 2. REAP COMPLETELY, THEN BOOTSTRAP. `LaunchdBackend.install` runs bootout →
+ *    poll-until-gone → bootstrap → kickstart synchronously, so the service is
+ *    live the instant install returns. A partial teardown means two ACP sessions
+ *    and two WebSockets on one device. `reap()` reports failure rather than
+ *    swallowing it, and a failed reap is a refusal.
+ *
+ * 3. COMPARE, DON'T DETECT. `status().loaded` means only that a plist with this
+ *    label exists. The old `install` subcommand never guarded its entrypoint
+ *    (subcommand.ts), so a customer can hold a LOADED plist baked against a
+ *    pruned npx cache; restarting that repairs nothing and reports success.
+ *    Restart only when a service is loaded AND its baked entrypoint is the one we
+ *    would install. Compare the ENTRYPOINT, never the whole launcher script —
+ *    that embeds the install-time PATH and is volatile across shells.
+ *
+ * 4. VERIFY BEFORE CLAIMING. `backend.install` returns void, and launchd's
+ *    implementation runs `kickstart` regardless of every `bootstrap` exit code.
+ *    This log line is the customer's only feedback, so it comes after a
+ *    `status()` that returned loaded:true.
+ */
+export declare function installOnReady(channel: ReadyChannel, cfg: BridgeConfig, deps: InstallOnReadyDeps): void;
+export {};
+//# sourceMappingURL=install-on-ready.d.ts.map

package/dist/service/install-on-ready.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install-on-ready.d.ts","sourceRoot":"","sources":["../../src/service/install-on-ready.ts"],"names":[],"mappings":"AAEA,OAAO,EAA4C,KAAK,YAAY,EAAE,MAAM,cAAc,CAAC;AAC3F,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAG7C,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAElE,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,QAAQ,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,+EAA+E;IAC/E,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACpD,eAAe,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC;IACjD,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC;iEAC6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,CAAC;IAChC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC5B;AAMD,UAAU,YAAY;IACpB,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,EAAE,EAAE,MAAM,IAAI,GAAG,OAAO,CAAC;CAC1C;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,YAAY,EACrB,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,kBAAkB,GACvB,IAAI,CAgHN"}

package/dist/service/launcher.d.ts

@@ -13,4 +13,23 @@ export declare function renderLauncher(opts: {
 /** Write the launcher executable (0755) into the data-dir before the backend
  *  points the service at it. Shared by both platform backends. */
 export declare function writeLauncher(deps: BackendDeps, spec: ServiceSpec): void;
+/**
+ * Read back the entrypoint `renderLauncher` baked into an installed launcher.
+ *
+ * THE READER LIVES BESIDE THE WRITER ON PURPOSE. This pair decides
+ * restart-versus-reinstall, and a parser that drifts from the renderer fails
+ * SILENTLY — it just answers `undefined` forever, which the caller reads as
+ * "stale", which means every run re-installs and silently re-bakes the plist.
+ *
+ * WHY PARSE RATHER THAN BYTE-COMPARE THE SCRIPT. `renderLauncher` embeds the
+ * INSTALL-TIME PATH (`export PATH='<installPath>':"$PATH"`), taken from whichever
+ * shell ran the install. A whole-file comparison therefore reports "different"
+ * whenever the customer opens a new terminal, installs a brew formula, or
+ * switches node version manager — making the config-losing re-install the DEFAULT
+ * path. The entrypoint is the durable half, and the only half that can go stale
+ * (an npm cache gets pruned; the launcher keeps pointing at it).
+ *
+ * Returns undefined when there is no file, or when it is not one of ours.
+ */
+export declare function parseLauncherEntrypoint(script: string | undefined): string | undefined;
 //# sourceMappingURL=launcher.d.ts.map

package/dist/service/launcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../../src/service/launcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,eAAO,MAAM,cAAc,UAO1B,CAAC;AAcF;;;wEAGwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,GAAG,MAAM,CAoBT;AAED;kEACkE;AAClE,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAIxE"}
+{"version":3,"file":"launcher.d.ts","sourceRoot":"","sources":["../../src/service/launcher.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAKhD,eAAO,MAAM,cAAc,UAO1B,CAAC;AAcF;;;wEAGwE;AACxE,wBAAgB,cAAc,CAAC,IAAI,EAAE;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB,GAAG,MAAM,CAoBT;AAED;kEACkE;AAClE,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,GAAG,IAAI,CAIxE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOtF"}

package/dist/service/subcommand.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"subcommand.d.ts","sourceRoot":"","sources":["../../src/service/subcommand.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAQD;;uFAEuF;AACvF,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CA4DT"}
+{"version":3,"file":"subcommand.d.ts","sourceRoot":"","sources":["../../src/service/subcommand.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7B;AAQD;;uFAEuF;AACvF,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,MAAM,EAAE,EACd,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,IAAI,CAAC,EAAE,cAAc,GACpB,OAAO,CAoFT"}

package/package.json

@@ -1,13 +1,21 @@
 {
   "name": "@agentvault/grok-bridge",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "AgentVault Grok Bridge — daemon bridging a Grok agent into E2E-encrypted AgentVault direct messages and rooms.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "bin": { "agentvault-grok-bridge": "dist/index.js" },
-  "engines": { "node": ">=18" },
-  "files": ["dist", "README.md", "!dist/*.map"],
+  "bin": {
+    "agentvault-grok-bridge": "dist/index.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "!dist/*.map"
+  ],
   "scripts": {
     "build": "npm --prefix ../plugin run build && tsc --emitDeclarationOnly && node build.mjs",
     "start": "node dist/index.js",
@@ -16,7 +24,10 @@
     "typecheck": "tsc -p tsconfig.test.json",
     "prepublishOnly": "npm run build"
   },
-  "dependencies": { "ws": "^8.16.0", "zod": "^4.3.6" },
+  "dependencies": {
+    "ws": "^8.16.0",
+    "zod": "^4.3.6"
+  },
   "devDependencies": {
     "@agentvault/agentvault": "file:../plugin",
     "esbuild": "^0.27.3",
@@ -24,6 +35,8 @@
     "vitest": "^2.0.0",
     "@types/node": "^20.0.0"
   },
-  "publishConfig": { "access": "public" },
+  "publishConfig": {
+    "access": "public"
+  },
   "license": "MIT"
 }