@agentvault/grok-bridge 0.1.0 → 0.2.0

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,29 @@
+/**
+ * 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";
+/**
+ * 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 +64,10 @@ 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;
 }
 export declare function loadConfig(env: NodeJS.ProcessEnv, argv?: string[]): BridgeConfig;
 //# sourceMappingURL=config.d.ts.map

package/dist/index.js

@@ -12,6 +12,18 @@ 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 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 +47,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 the only supported flag is ${INSTALL_FLAG}`
+    );
+  }
   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 +78,9 @@ 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),
     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 +97,12 @@ function loadConfig(env, argv = []) {
     systemPrompt: env.AV_SYSTEM_PROMPT || void 0
   };
 }
-var CRED_FILES, BACKUP_FILE;
+var INSTALL_FLAG, KNOWN_FLAGS, CRED_FILES, BACKUP_FILE;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
+    INSTALL_FLAG = "--install";
+    KNOWN_FLAGS = /* @__PURE__ */ new Set([INSTALL_FLAG]);
     CRED_FILES = ["agentvault.json", "secure-channel.json"];
     BACKUP_FILE = "agentvault.json.bak";
   }
@@ -130,6 +153,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"() {
@@ -232,7 +265,6 @@ var init_launchd = __esm({
       constructor(deps) {
         this.deps = deps;
       }
-      deps;
       plistPath(label) {
         return join10(this.deps.home, "Library", "LaunchAgents", `${label}.plist`);
       }
@@ -317,7 +349,6 @@ var init_systemd = __esm({
       constructor(deps) {
         this.deps = deps;
       }
-      deps;
       unitPath(label) {
         return join11(this.deps.home, ".config", "systemd", "user", `${label}.service`);
       }
@@ -353,6 +384,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";
@@ -456,12 +492,105 @@ 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
+// ../../../../packages/plugin/dist/index.js
 import * as nc from "node:crypto";
 import { chmod, mkdir, writeFile } from "node:fs/promises";
 import { readdir, readFile, rename, rm } from "node:fs/promises";
@@ -732,7 +861,7 @@ var init_libsodium_sumo = __esm2({
           }, Module: function(binary) {
           }, Instance: function(module2, info) {
             this.exports = // EMSCRIPTEN_START_ASM
-            (function instantiate(ea2) {
+            function instantiate(ea2) {
               var a2;
               var b2 = new Uint8Array(123);
               for (var c2 = 25; c2 >= 0; --c2) {
@@ -40527,7 +40656,7 @@ var init_libsodium_sumo = __esm2({
                 } } }), f: yi, g: ma2, h: Ba2, i: ma2, j: ka2, k: Le2, l: Je2, m: zg, n: yg, o: xg, p: wg, q: ka2, r: Ba2, s: ka2, t: ka2, u: Le2, v: ra2, w: vg, x: ug, y: tg, z: sg, A: Ba2, B: rg, C: qg, D: pg, E: ng, F: mg, G: lg, H: kg, I: jg, J: ka2, K: Ce2, L: Ba2, M: ma2, N: Ta2, O: ra2, P: ka2, Q: Oa2, R: Ba2, S: ma2, T: Ta2, U: ra2, V: ig, W: hg, X: gg, Y: fg, Z: ka2, _: Ma2, $: Ba2, aa: ma2, ba: Ta2, ca: ra2, da: ka2, ea: ka2, fa: Kg, ga: wd, ha: vd, ia: ra2, ja: ka2, ka: ka2, la: Cb, ma: ra2, na: Xa2, oa: eg, pa: qb, qa: dg, ra: cg, sa: ua2, ta: ka2, ua: Dc, va: ra2, wa: Va2, xa: ud, ya: Ya2, za: bg, Aa: ag, Ba: ka2, Ca: ka2, Da: Dc, Ea: ra2, Fa: ze2, Ga: ud, Ha: Ng, Ia: wd, Ja: vd, Ka: ka2, La: ka2, Ma: ka2, Na: ka2, Oa: Ma2, Pa: ka2, Qa: ma2, Ra: ma2, Sa: Ta2, Ta: dh2, Ua: ch, Va: bh, Wa: ah, Xa: Lb, Ya: Kb, Za: td, _a: sd, $a: rd, ab: $f, bb: _f, cb: Zf, db: qd, eb: Yf, fb: pd, gb: Xf, hb: Wf, ib: Uf, jb: Md, kb: tc, lb: nb, mb, nb: Lb, ob: Kb, pb: td, qb: sd, rb: ka2, sb: ka2, tb: ka2, ub: ka2, vb: Ma2, wb: ka2, xb: ma2, yb: ma2, zb: Ta2, Ab: Aa2, Bb: ka2, Cb: ma2, Db: ka2, Eb: ma2, Fb: Sa2, Gb: ka2, Hb: ma2, Ib: ka2, Jb: ma2, Kb: vb, Lb: ua2, Mb: ma2, Nb: ka2, Ob: ma2, Pb: ub, Qb: ua2, Rb: ma2, Sb: ka2, Tb: ma2, Ub: tb, Vb: ua2, Wb: ma2, Xb: ka2, Yb: ma2, Zb: ma2, _b: ua2, $b: ka2, ac: ma2, bc: ua2, cc: ka2, dc: Nd, ec: pe2, fc: od, gc: fh, hc: nd, ic: eh, jc: ra2, kc: ma2, lc: ua2, mc: ka2, nc: ma2, oc: ua2, pc: ka2, qc: ma2, rc: ma2, sc: pe2, tc: ra2, uc: od, vc: Tf, wc: Ja2, xc: xh, yc: nd, zc: Ia2, Ac: ua2, Bc: md, Cc: Lg, Dc: ka2, Ec: Ag, Fc: Ub, Gc: Sf, Hc: Ua2, Ic: Rf, Jc: ua2, Kc: Cb, Lc: Za2, Mc: ic, Nc: Ca2, Oc: md, Pc: ma2, Qc: ua2, Rc: Oa2, Sc: ka2, Tc: ld, Uc: Nd, Vc: ma2, Wc: ua2, Xc: Oa2, Yc: ka2, Zc: ld, _c: ra2, $c: Gh, ad: Fh, bd: Eh, cd: Dh, dd: ra2, ed: Ch, fd: ka2, gd: Ba2, hd: Bh, id: Cb, jd: ze2, kd: hi, ld: gi, md: fi, nd: ei, od: di, pd: ua2, qd: Ba2, rd: ci, sd: Dc, td: Gg, ud: nb, vd: Fg, wd: Eg, xd: ka2, yd: ka2, zd: ka2, Ad: ka2, Bd: Dg, Cd: Rc, Dd: ma2, Ed: ka2, Fd: kd, Gd: jd, Hd: Sg, Id: id, Jd: Rg, Kd: Qg, Ld: ra2, Md: kd, Nd: jd, Od: Ga2, Pd: id, Qd: Fa2, Rd: ma2, Sd: ka2, Td: Rc, Ud: ra2, Vd: Db, Wd: ma2, Xd: wa2, Yd: Ba2, Zd: wa2, _d: ma2, $d: yc, ae: wh, be: Vb, ce: wa2, de: xc, ee: wc, fe: vc, ge: me2, he: vh, ie: uh, je: Oa2, ke: th, le: Pf, me: Of, ne: Nf, oe: Mf, pe: Lf, qe: fb, re: ma2, se: wa2, te: Ba2, ue: wa2, ve: ma2, we: yc, xe: fe2, ye: Db, ze: wa2, Ae: xc, Be: wc, Ce: fb, De: ee2, Ee: Vb, Fe: de2, Ge: vc, He: uc, Ie: Kf, Je: hd, Ke: Jf, Le: Db, Me: fb, Ne: fb, Oe: ma2, Pe: wa2, Qe: Ba2, Re: wa2, Se: ma2, Te: yc, Ue: fe2, Ve: Db, We: wa2, Xe: xc, Ye: wc, Ze: fb, _e: ee2, $e: Vb, af: de2, bf: vc, cf: uc, df: Hf, ef: hd, ff: Gf, gf: Ff, hf: Ef, jf: sh, kf: Jg, lf: Ig, mf: Hg, nf: ka2, of: ka2, pf: Ea2, qf: wb, rf: ka2, sf: ka2, tf: ka2, uf: Ma2, vf: ka2, wf: ma2, xf: ma2, yf: Ta2, zf: Mg, Af: Lb, Bf: Kb, Cf: ra2, Df: rd, Ef: Df, Ff: qd, Gf: pd, Hf: Lb, If: Kb, Jf: ka2, Kf: Ma2, Lf: ka2, Mf: ma2, Nf: ma2, Of: Ta2, Pf: ra2, Qf: ra2, Rf: Mh, Sf: Lh, Tf: Kh, Uf: Cf, Vf: Bf, Wf: Jh, Xf: Ih, Yf: Ma2, Zf: ka2, _f: Hh, $f: Ba2, ag: Db, bg: fb, cg: Vb, dg: Oa2, eg: ma2, fg: Tg, gg: gd, hg: Je2, ig: Oa2, jg: ma2, kg: gd, lg: Cb, mg: ua2, ng: ka2, og: ka2, pg: ua2, qg: Wd, rg: lh, sg: kh, tg: jh, ug: fd, vg: ed, wg: dd, xg: cd, yg: ih, zg: ic, Ag: hh, Bg: gh, Cg: Cb, Dg: ua2, Eg: ka2, Fg: ka2, Gg: ua2, Hg: Wd, Ig: nh, Jg: mh, Kg: Vd, Lg: ic, Mg: Ud, Ng: Td, Og: Yd, Pg: Xd, Qg: ph, Rg: oh, Sg: cd, Tg: ed, Ug: dd, Vg: fd, Wg: ka2, Xg: Oa2, Yg: wa2, Zg: ka2, _g: Ce2, $g: wa2, ah: zf, bh: yf, ch: xf, dh: wf, eh: vf, fh: uf, gh: ra2, hh: ra2, ih: ka2, jh: Ma2, kh: wa2, lh: qh, mh: bd, nh: ad, oh: ra2, ph: ka2, qh: Oa2, rh: wa2, sh: tf, th: sf, uh: rf, vh: ra2, wh: bd, xh: qf, yh: ad, zh: ka2, Ah: Ma2, Bh: wa2, Ch: ra2, Dh: ma2, Eh: ka2, Fh: ua2, Gh: db, Hh: kb, Ih: xd, Jh: oi, Kh: ni, Lh: Ae2, Mh: mi, Nh: za2, Oh: li, Ph: ka2, Qh: ki, Rh: pf, Sh: Ah, Th: zh, Uh: yh, Vh: Bc, Wh: Ac, Xh: ti, Yh: ji, Zh: ii, _h: Cg, $h: Bg, ai: fb, bi: Ba2, ci: tc, di: nb, ei: rh, fi: $c, gi: of, hi: nf, ii: mf, ji: _c, ki: lf, li: Yc, mi: kf, ni: ka2, oi: ka2, pi: ka2, qi: ka2, ri: Ma2, si: ma2, ti: Ta2, ui: jf, vi: hf, wi: Md, xi: bi, yi: ai, zi: $h, Ai: _h, Bi: Zh, Ci: ye2, Di: xe2, Ei: we2, Fi: ve2, Gi: ue2, Hi: te2, Ii: se2, Ji: re2, Ki: ka2, Li: ua2, Mi: ka2, Ni: ua2, Oi: ka2, Pi: Yh, Qi: Xh, Ri: Wh, Si: Vh, Ti: Uh, Ui: Th, Vi: Sh, Wi: Rh, Xi: Qh, Yi: Ph, Zi: Oh, _i: re2, $i: Nh, aj: ka2, bj: ua2, cj: ua2, dj: ka2, ej: gf, fj: ma2, gj: wa2, hj: Ba2, ij: wa2, jj: ka2, kj: $g, lj: _g, mj: Zg, nj: wa2, oj: Ed, pj: wa2, qj: Yg, rj: Ed, sj: me2, tj: uc, uj: ff, vj: ef, wj: df, xj: cf, yj: Xg, zj: Wg, Aj: Vg, Bj: Ug, Cj: ka2, Dj: ka2, Ej: Pg, Fj: Og, Gj: ka2, Hj: ka2, Ij: $c, Jj: bf, Kj: _c, Lj: Yc, Mj: ka2, Nj: Ma2, Oj: ma2, Pj: Ta2, Qj: ma2, Rj: ma2, Sj: af, Tj: $e2, Uj: _e2, Vj: ka2, Wj: Oa2, Xj: wa2, Yj: ra2, Zj: Ze2, _j: Ye2, $j: ka2, ak: Oa2, bk: wa2, ck: ra2, dk: ka2, ek: Ma2, fk: wa2, gk: Xe2, hk: We2, ik: Ve2, jk: ra2, kk: Da2, lk: ta2 };
               }
               return da2(ea2);
-            })(info);
+            }(info);
           }, instantiate: function(binary, info) {
             return { then: function(ok) {
               var module2 = new WebAssembly2.Module(binary);
@@ -81102,7 +81231,7 @@ function _stringbool(Classes, _params) {
     type: "pipe",
     in: stringSchema,
     out: booleanSchema,
-    transform: ((input, payload) => {
+    transform: (input, payload) => {
       let data = input;
       if (params.case !== "sensitive")
         data = data.toLowerCase();
@@ -81121,14 +81250,14 @@ function _stringbool(Classes, _params) {
         });
         return {};
       }
-    }),
-    reverseTransform: ((input, _payload) => {
+    },
+    reverseTransform: (input, _payload) => {
       if (input === true) {
         return truthyArray[0] || "true";
       } else {
         return falsyArray[0] || "false";
       }
-    }),
+    },
     error: params.error
   });
   return codec2;
@@ -82184,10 +82313,10 @@ var init_schemas2 = __esm2({
       inst.with = inst.check;
       inst.clone = (_def, params) => clone(inst, _def, params);
       inst.brand = () => inst;
-      inst.register = ((reg, meta3) => {
+      inst.register = (reg, meta3) => {
         reg.add(inst, meta3);
         return inst;
-      });
+      };
       inst.apply = (fn) => fn(inst);
     });
     ZodMiniObject = /* @__PURE__ */ $constructor("ZodMiniObject", (inst, def) => {
@@ -83273,10 +83402,10 @@ var init_schemas3 = __esm2({
       inst.with = inst.check;
       inst.clone = (def2, params) => clone(inst, def2, params);
       inst.brand = () => inst;
-      inst.register = ((reg, meta3) => {
+      inst.register = (reg, meta3) => {
         reg.add(inst, meta3);
         return inst;
-      });
+      };
       inst.parse = (data, params) => parse2(inst, data, params, { callee: inst.parse });
       inst.safeParse = (data, params) => safeParse3(inst, data, params);
       inst.parseAsync = async (data, params) => parseAsync2(inst, data, params, { callee: inst.parseAsync });
@@ -83938,13 +84067,11 @@ function assertCompleteRequestPrompt(request) {
   if (request.params.ref.type !== "ref/prompt") {
     throw new TypeError(`Expected CompleteRequestPrompt, but got ${request.params.ref.type}`);
   }
-  void request;
 }
 function assertCompleteRequestResourceTemplate(request) {
   if (request.params.ref.type !== "ref/resource") {
     throw new TypeError(`Expected CompleteRequestResourceTemplate, but got ${request.params.ref.type}`);
   }
-  void request;
 }
 var LATEST_PROTOCOL_VERSION;
 var DEFAULT_NEGOTIATED_PROTOCOL_VERSION;
@@ -98107,8 +98234,6 @@ var GrokSession = class {
     this.driver = driver2;
     this.opts = opts;
   }
-  driver;
-  opts;
   queue = [];
   running = false;
   /** The message whose turn is in flight, or null between turns. Null is a
@@ -98221,9 +98346,6 @@ var AcpChildDied = class extends Error {
     this.signal = signal;
     this.name = "AcpChildDied";
   }
-  method;
-  code;
-  signal;
 };
 var AcpTimeout = class extends Error {
   constructor(method, ms) {
@@ -98232,8 +98354,6 @@ var AcpTimeout = class extends Error {
     this.ms = ms;
     this.name = "AcpTimeout";
   }
-  method;
-  ms;
 };
 var AcpConnection = class {
   constructor(child, opts) {
@@ -98251,7 +98371,6 @@ var AcpConnection = class {
       this.stdinErrors++;
     });
   }
-  child;
   nextId = 1;
   pending = /* @__PURE__ */ new Map();
   /** Undecoded leftover. Decode UTF-8 only on complete lines so a 4-byte
@@ -98434,8 +98553,6 @@ var GrokDriver = class {
     this.acp.onNotification((method, params) => this.onNotification(method, params));
     this.acp.onRequest((method, params) => this.onAgentRequest(method, params));
   }
-  child;
-  opts;
   acp;
   session = null;
   /** State for the turn currently in flight. Null between turns, so a late
@@ -98846,16 +98963,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);
   }
@@ -98868,6 +99045,11 @@ async function main() {
     process.exit(process.exitCode ?? 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 +99064,10 @@ async function main() {
     agentName: cfg.agentName,
     platform: "node",
     clientVersion: buildClientVersion2(
-      true ? "0.1.0" : void 0
+      true ? "0.2.0" : void 0
     )
   });
+  channelRef = channel;
   let session;
   mcp = await startRoomMcpServer({
     // `session` is assigned further down. The current ordering is safe — grok
@@ -98902,7 +99085,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 +99100,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 +99150,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/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/package.json

@@ -1,13 +1,21 @@
 {
   "name": "@agentvault/grok-bridge",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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"
 }