@agentvault/grok-bridge 0.3.1 → 0.4.0

package/dist/index.js

@@ -54,6 +54,24 @@ var init_pending_invite = __esm({
   }
 });
 
+// src/log.ts
+import { format } from "node:util";
+function stamp(message) {
+  const ts = (/* @__PURE__ */ new Date()).toISOString();
+  return message.split("\n").map((line) => `${ts} ${line}`).join("\n");
+}
+function logLine(...args) {
+  console.error(stamp(format(...args)));
+}
+function printLine(text) {
+  console.log(text);
+}
+var init_log = __esm({
+  "src/log.ts"() {
+    "use strict";
+  }
+});
+
 // src/config.ts
 import { existsSync as existsSync2, readFileSync as readFileSync3, mkdirSync as mkdirSync2, chmodSync as chmodSync2 } from "node:fs";
 import { join as join6, resolve as resolve2, sep, dirname } from "node:path";
@@ -71,7 +89,7 @@ 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
+  npm i -g @agentvault/grok-bridge && agentvault-grok-bridge install`
     );
   }
 }
@@ -83,6 +101,17 @@ function hasRecoverableBackup(dataDir) {
     return false;
   }
 }
+function readPersistedDeviceId(dataDir) {
+  for (const f2 of [...CRED_FILES, BACKUP_FILE]) {
+    try {
+      const parsed = JSON.parse(readFileSync3(join6(dataDir, f2), "utf-8"));
+      const id = parsed?.deviceId;
+      if (typeof id === "string" && id) return id;
+    } catch {
+    }
+  }
+  return null;
+}
 function hasPersistedCreds(dataDir) {
   if (CRED_FILES.some((f2) => existsSync2(join6(dataDir, f2)))) return true;
   return hasRecoverableBackup(dataDir);
@@ -91,20 +120,41 @@ function slugify2(name) {
   return name.toLowerCase().replace(/[^a-z0-9-]/g, "-");
 }
 function resolveDataDir(env) {
-  if (env.AV_DATA_DIR) return { dataDir: env.AV_DATA_DIR, source: "explicit" };
+  const supplied = env.AV_AGENT_NAME?.trim();
+  const agentName = supplied || LEGACY_DEFAULT_AGENT_NAME;
+  const agentNameSource = supplied ? "supplied" : "defaulted";
+  if (env.AV_DATA_DIR)
+    return { dataDir: env.AV_DATA_DIR, source: "explicit", agentName, agentNameSource };
   const base = join6(env.HOME ?? "", ".agentvault", "grok-room-bridge");
-  return { dataDir: join6(base, slugify2(env.AV_AGENT_NAME ?? "grok")), source: "per-agent" };
+  const perAgent = join6(base, slugify2(agentName));
+  if (!supplied && !hasPersistedCreds(perAgent)) {
+    throw new Error(
+      `AV_AGENT_NAME is required \u2014 it names WHICH agent this bridge runs as, and therefore where its credentials live. No credentials were found at ${perAgent}, so there is no existing install to infer a name from. Re-run with AV_AGENT_NAME=<agent-name> set.`
+    );
+  }
+  return { dataDir: perAgent, source: "per-agent", agentName, agentNameSource };
 }
 function loadConfig(env, argv = []) {
-  const { dataDir, source: dataDirSource } = resolveDataDir(env);
+  const { dataDir, source: dataDirSource, agentName, agentNameSource } = resolveDataDir(env);
+  if (agentNameSource === "defaulted") {
+    logLine(
+      `[config] AV_AGENT_NAME was not set \u2014 running as "${agentName}" from the existing credentials at ${dataDir}. Set AV_AGENT_NAME to name this agent explicitly; a future install will require it.`
+    );
+  }
   const inviteToken = (argv[0] && !argv[0].startsWith("-") ? argv[0] : "") || env.AV_INVITE_TOKEN || readPendingInvite(dataDir) || "";
+  if (argv.includes(REMOVED_INSTALL_FLAG)) {
+    throw new Error(
+      `${REMOVED_INSTALL_FLAG} was removed \u2014 it handed the agent over from a foreground process that could be reaped before the encrypted group finished forming, leaving an agent that was connected and mute (#909). Use the subcommand instead, which lets the service enrol itself:
+  npm i -g @agentvault/grok-bridge && AV_AGENT_NAME=<agent-name> AV_INVITE_TOKEN=<token> agentvault-grok-bridge install`
+    );
+  }
   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 || join6(dirname(dataDir), "workspaces", slugify2(env.AV_AGENT_NAME ?? "grok"));
+  const workspaceDir = env.AV_WORKSPACE_DIR || join6(dirname(dataDir), "workspaces", slugify2(agentName));
   const wsReal = resolve2(workspaceDir);
   const ddReal = resolve2(dataDir);
   if (wsReal === ddReal || wsReal.startsWith(ddReal + sep) || ddReal.startsWith(wsReal + sep)) {
@@ -129,17 +179,14 @@ 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).
-    // Defaults to "Grok" — this package IS the Grok bridge, so an unset
-    // AV_AGENT_NAME still names the actual model running the session, not a
-    // placeholder impersonating some other agent.
-    agentName: env.AV_AGENT_NAME ?? "Grok",
+    // Resolved in resolveDataDir so the name, the data dir and the workspace dir
+    // can never disagree about who this agent is (#921/#927).
+    agentName,
+    agentNameSource,
     roomFilter: env.AV_ROOM_ID || void 0,
     workspaceDir,
     grokPath: env.AV_GROK_PATH || void 0,
@@ -149,35 +196,19 @@ function loadConfig(env, argv = []) {
     systemPrompt: env.AV_SYSTEM_PROMPT || void 0
   };
 }
-var INSTALL_FLAG, VERSION_FLAGS, HELP_FLAGS, KNOWN_FLAGS, CRED_FILES, BACKUP_FILE;
+var REMOVED_INSTALL_FLAG, VERSION_FLAGS, HELP_FLAGS, KNOWN_FLAGS, CRED_FILES, BACKUP_FILE, LEGACY_DEFAULT_AGENT_NAME;
 var init_config = __esm({
   "src/config.ts"() {
     "use strict";
     init_pending_invite();
-    INSTALL_FLAG = "--install";
+    init_log();
+    REMOVED_INSTALL_FLAG = "--install";
     VERSION_FLAGS = ["--version", "-v"];
     HELP_FLAGS = ["--help", "-h"];
-    KNOWN_FLAGS = /* @__PURE__ */ new Set([INSTALL_FLAG, ...VERSION_FLAGS, ...HELP_FLAGS]);
+    KNOWN_FLAGS = /* @__PURE__ */ new Set([...VERSION_FLAGS, ...HELP_FLAGS]);
     CRED_FILES = ["agentvault.json", "secure-channel.json"];
     BACKUP_FILE = "agentvault.json.bak";
-  }
-});
-
-// src/log.ts
-import { format } from "node:util";
-function stamp(message) {
-  const ts = (/* @__PURE__ */ new Date()).toISOString();
-  return message.split("\n").map((line) => `${ts} ${line}`).join("\n");
-}
-function logLine(...args) {
-  console.error(stamp(format(...args)));
-}
-function printLine(text) {
-  console.log(text);
-}
-var init_log = __esm({
-  "src/log.ts"() {
-    "use strict";
+    LEGACY_DEFAULT_AGENT_NAME = "Grok";
   }
 });
 
@@ -211,16 +242,6 @@ 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"() {
@@ -314,6 +335,37 @@ ${envEntries}
 </plist>
 `;
 }
+function parsePlistEnv(xml) {
+  const out = {};
+  const keyIdx = xml.indexOf("<key>EnvironmentVariables</key>");
+  if (keyIdx < 0) return out;
+  const open = xml.indexOf("<dict>", keyIdx);
+  if (open < 0) return out;
+  let depth = 0;
+  let i2 = open;
+  let close = -1;
+  const tag = /<(\/?)dict>/g;
+  tag.lastIndex = open;
+  let m2;
+  while (m2 = tag.exec(xml)) {
+    depth += m2[1] ? -1 : 1;
+    if (depth === 0) {
+      close = m2.index;
+      break;
+    }
+    i2 = m2.index;
+  }
+  void i2;
+  if (close < 0) return out;
+  const body = xml.slice(open, close);
+  const pair = /<key>([\s\S]*?)<\/key>\s*<string>([\s\S]*?)<\/string>/g;
+  let p2;
+  while (p2 = pair.exec(body)) out[unesc(p2[1])] = unesc(p2[2]);
+  return out;
+}
+function unesc(s2) {
+  return s2.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&amp;/g, "&");
+}
 var LaunchdBackend;
 var init_launchd = __esm({
   "src/service/launchd.ts"() {
@@ -368,6 +420,26 @@ var init_launchd = __esm({
         const r2 = this.deps.exec("launchctl", ["print", `${this.domain()}/${label}`]);
         return { loaded: r2.code === 0, detail: r2.stdout };
       }
+      /** #913 item 3 — every installed service whose label starts with `prefix`.
+       *
+       *  Reads the plist directory rather than `launchctl list`, because an ORPHAN
+       *  is typically installed-but-not-loaded: the revoked device exits 0 and
+       *  KeepAlive leaves it down. `launchctl list` would not show the very thing
+       *  doctor exists to find. */
+      list(prefix) {
+        const dir = join11(this.deps.home, "Library", "LaunchAgents");
+        const out = [];
+        for (const name of this.deps.readdir(dir)) {
+          if (!name.startsWith(prefix) || !name.endsWith(".plist")) continue;
+          const path2 = join11(dir, name);
+          out.push({
+            label: name.slice(0, -".plist".length),
+            path: path2,
+            env: parsePlistEnv(this.deps.readFile(path2))
+          });
+        }
+        return out.sort((a2, b2) => a2.label.localeCompare(b2.label));
+      }
     };
   }
 });
@@ -399,6 +471,24 @@ StandardError=append:${spec.logErr}
 WantedBy=default.target
 `;
 }
+function parseUnitEnv(text) {
+  const out = {};
+  for (const line of text.split("\n")) {
+    const m2 = /^Environment="([\s\S]*)"\s*$/.exec(line.trim());
+    if (!m2) continue;
+    const eq = unq(m2[1]);
+    const at = eq.indexOf("=");
+    if (at <= 0) continue;
+    out[eq.slice(0, at)] = eq.slice(at + 1);
+  }
+  return out;
+}
+function unq(s2) {
+  return s2.replace(/%%/g, "%").replace(
+    /\\([\s\S])/g,
+    (_2, c2) => c2 === "n" ? "\n" : c2 === "r" ? "\r" : c2 === "t" ? "	" : c2
+  );
+}
 var SystemdBackend;
 var init_systemd = __esm({
   "src/service/systemd.ts"() {
@@ -439,18 +529,33 @@ var init_systemd = __esm({
         const active = this.deps.exec("systemctl", ["--user", "is-active", `${label}.service`]);
         return { loaded: enabled.code === 0, detail: `${enabled.stdout.trim() || "?"} / ${active.stdout.trim() || "?"}` };
       }
+      /** #913 item 3 — every installed unit whose label starts with `prefix`.
+       *
+       *  Reads the unit directory rather than `systemctl list-units`, because an
+       *  ORPHAN is installed-but-inactive: the revoked device exits 0, which
+       *  SuccessExitStatus=0 treats as success, so it is never restarted. A
+       *  running-units listing would not show the thing doctor exists to find. */
+      list(prefix) {
+        const dir = join12(this.deps.home, ".config", "systemd", "user");
+        const out = [];
+        for (const name of this.deps.readdir(dir)) {
+          if (!name.startsWith(prefix) || !name.endsWith(".service")) continue;
+          const path2 = join12(dir, name);
+          out.push({
+            label: name.slice(0, -".service".length),
+            path: path2,
+            env: parseUnitEnv(this.deps.readFile(path2))
+          });
+        }
+        return out.sort((a2, b2) => a2.label.localeCompare(b2.label));
+      }
     };
   }
 });
 
 // src/service/backend.ts
-var backend_exports = {};
-__export(backend_exports, {
-  defaultDeps: () => defaultDeps,
-  selectBackend: () => selectBackend
-});
 import { spawnSync } from "node:child_process";
-import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync3, rmSync as rmSync2, existsSync as existsSync4, chmodSync as chmodSync5 } from "node:fs";
+import { mkdirSync as mkdirSync5, writeFileSync as writeFileSync3, rmSync as rmSync2, existsSync as existsSync4, chmodSync as chmodSync5, readdirSync, readFileSync as readFileSync4 } from "node:fs";
 import { userInfo } from "node:os";
 function defaultDeps() {
   return {
@@ -465,7 +570,21 @@ function defaultDeps() {
     mkdir: (p2) => mkdirSync5(p2, { recursive: true }),
     chmod: (p2, m2) => chmodSync5(p2, m2),
     rm: (p2) => rmSync2(p2, { force: true }),
-    exists: (p2) => existsSync4(p2)
+    exists: (p2) => existsSync4(p2),
+    readdir: (p2) => {
+      try {
+        return readdirSync(p2);
+      } catch {
+        return [];
+      }
+    },
+    readFile: (p2) => {
+      try {
+        return readFileSync4(p2, "utf8");
+      } catch {
+        return "";
+      }
+    }
   };
 }
 function selectBackend(platform, deps) {
@@ -488,16 +607,20 @@ var init_backend = __esm({
 // src/service/subcommand.ts
 var subcommand_exports = {};
 __export(subcommand_exports, {
+  labelFor: () => labelFor,
   maybeRunServiceSubcommand: () => maybeRunServiceSubcommand
 });
-function labelFor(env) {
+function requireAgentName(env) {
   const name = env.AV_AGENT_NAME?.trim();
   if (!name) {
     throw new Error(
       "AV_AGENT_NAME is required \u2014 it names WHICH agent's service to act on. Re-run as: AV_AGENT_NAME=<agent-name> agentvault-grok-bridge <subcommand>"
     );
   }
-  return `dev.agentvault.grok-${slugify2(name)}`;
+  return name;
+}
+function labelFor(env) {
+  return `dev.agentvault.grok-${slugify2(requireAgentName(env))}`;
 }
 function maybeRunServiceSubcommand(argv, env, deps) {
   const cmd = argv[2];
@@ -507,7 +630,9 @@ function maybeRunServiceSubcommand(argv, env, deps) {
     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`
+        // "doctor" is dispatched earlier, in index.ts, so it never reaches here.
+        // Named anyway: a customer who typed `doctr` should see it offered.
+        `unknown subcommand: ${cmd} \u2014 expected one of ${[...SERVICE_CMDS, "doctor"].join(", ")}, an invite token, or no argument at all`
       );
     }
     return false;
@@ -517,6 +642,8 @@ function maybeRunServiceSubcommand(argv, env, deps) {
   const log = deps?.log ?? ((m2) => logLine("[grok-bridge] " + m2));
   try {
     if (cmd === "install") {
+      requireAgentName(env);
+      assertInstallableEntrypoint(entrypoint);
       const cfg = loadConfig(env, []);
       const firstBoot = !hasPersistedCreds(cfg.dataDir) && !!cfg.inviteToken;
       if (firstBoot) {
@@ -574,96 +701,313 @@ var init_subcommand = __esm({
   }
 });
 
-// src/service/install-on-ready.ts
-var install_on_ready_exports = {};
-__export(install_on_ready_exports, {
-  installOnReady: () => installOnReady
+// src/service/doctor.ts
+import { basename } from "node:path";
+async function buildDoctorReport(d2) {
+  const installed = d2.labelPrefixes.flatMap((p2) => d2.backend.list(p2));
+  const services = [];
+  for (const s2 of installed) services.push(await inspect(s2, d2));
+  const claimed = new Set(installed.map((s2) => s2.env.AV_DATA_DIR).filter(Boolean));
+  const unsupervised = [];
+  for (const dataDir of d2.credDirs()) {
+    if (claimed.has(dataDir)) continue;
+    unsupervised.push(await inspectUnsupervised(dataDir, d2));
+  }
+  return {
+    labelPrefixes: d2.labelPrefixes,
+    services,
+    unsupervised,
+    notChecked: d2.otherLabels()
+  };
+}
+async function inspect(s2, d2) {
+  const agentName = s2.env.AV_AGENT_NAME ?? "";
+  const dataDir = s2.env.AV_DATA_DIR ?? "";
+  let loaded = false;
+  try {
+    loaded = d2.backend.status(s2.label).loaded;
+  } catch {
+  }
+  const base = { label: s2.label, agentName, dataDir, loaded, deviceId: "" };
+  if (!dataDir) {
+    return {
+      ...base,
+      verdict: "WARN",
+      detail: "the service definition bakes no AV_DATA_DIR, so doctor cannot find its credentials and cannot check its device"
+    };
+  }
+  const creds = d2.readCreds(dataDir);
+  if (!creds?.deviceId) {
+    return {
+      ...base,
+      verdict: "WARN",
+      detail: `no credentials at ${dataDir} \u2014 installed, but this agent never enrolled`
+    };
+  }
+  const deviceId = creds.deviceId;
+  let probe;
+  try {
+    probe = await d2.fetchStatus(d2.apiUrl, deviceId);
+  } catch (e) {
+    return { ...base, deviceId, verdict: "SKIP", detail: `could not check the device: ${e.message}` };
+  }
+  if (probe.inconclusive) {
+    return { ...base, deviceId, verdict: "SKIP", detail: `could not check the device: ${probe.inconclusive}` };
+  }
+  if (probe.gone) {
+    return {
+      ...base,
+      deviceId,
+      verdict: "FAIL",
+      detail: "the device no longer exists \u2014 this service is an orphan",
+      fix: d2.uninstallCommand(agentName)
+    };
+  }
+  switch (probe.status) {
+    case "ACTIVE":
+      return { ...base, deviceId, verdict: "PASS", detail: "device ACTIVE" };
+    case "PENDING":
+      return {
+        ...base,
+        deviceId,
+        verdict: "WARN",
+        detail: "device PENDING \u2014 enrolled, but never approved in AgentVault"
+      };
+    case "REVOKED":
+      return {
+        ...base,
+        deviceId,
+        verdict: "FAIL",
+        detail: "the device was REVOKED \u2014 this service is an orphan",
+        fix: d2.uninstallCommand(agentName)
+      };
+    default:
+      return {
+        ...base,
+        deviceId,
+        verdict: "SKIP",
+        detail: `the server reported a status this build does not recognise (${probe.status || "none"})`
+      };
+  }
+}
+async function inspectUnsupervised(dataDir, d2) {
+  const agentName = basename(dataDir);
+  const base = { dataDir, agentName, deviceId: "" };
+  const deviceId = d2.readCreds(dataDir)?.deviceId;
+  if (!deviceId) {
+    return { ...base, verdict: "WARN", detail: "credentials present but they hold no device id" };
+  }
+  let probe;
+  try {
+    probe = await d2.fetchStatus(d2.apiUrl, deviceId);
+  } catch (e) {
+    return { ...base, deviceId, verdict: "SKIP", detail: `could not check the device: ${e.message}` };
+  }
+  if (probe.inconclusive) {
+    return { ...base, deviceId, verdict: "SKIP", detail: `could not check the device: ${probe.inconclusive}` };
+  }
+  if (probe.gone) {
+    return {
+      ...base,
+      deviceId,
+      verdict: "WARN",
+      detail: "the device no longer exists \u2014 these are leftover credentials for a deleted agent"
+    };
+  }
+  if (probe.status === "ACTIVE") {
+    return {
+      ...base,
+      deviceId,
+      verdict: "WARN",
+      detail: "the device is ACTIVE but nothing supervises it \u2014 this agent is not running",
+      fix: d2.installCommand(agentName)
+    };
+  }
+  if (probe.status === "PENDING") {
+    return {
+      ...base,
+      deviceId,
+      verdict: "WARN",
+      detail: "device PENDING \u2014 enrolled, but never approved in AgentVault"
+    };
+  }
+  if (probe.status === "REVOKED") {
+    return {
+      ...base,
+      deviceId,
+      verdict: "WARN",
+      detail: "the device was REVOKED \u2014 these are leftover credentials"
+    };
+  }
+  return {
+    ...base,
+    deviceId,
+    verdict: "SKIP",
+    detail: `the server reported a status this build does not recognise (${probe.status || "none"})`
+  };
+}
+function formatDoctorReport(r2) {
+  const out = [];
+  out.push(`Services installed for this bridge (${r2.labelPrefixes.map((p2) => p2 + "*").join(", ")})`);
+  if (r2.services.length === 0) {
+    out.push(`  No services installed for this bridge on this machine.`);
+  }
+  for (const s2 of r2.services) {
+    out.push(
+      `  ${s2.verdict.padEnd(PAD)}${s2.label}  [${s2.agentName || "unnamed"}]  ${s2.loaded ? "loaded" : "not loaded"}  \u2014  ${s2.detail}`
+    );
+    if (s2.fix) out.push(`  ${"".padEnd(PAD)}fix: ${s2.fix}`);
+  }
+  if (r2.unsupervised.length) {
+    out.push("");
+    out.push("Credentials on disk that no installed service points at");
+    for (const u2 of r2.unsupervised) {
+      out.push(`  ${u2.verdict.padEnd(PAD)}${u2.agentName}  \u2014  ${u2.detail}`);
+      out.push(`  ${"".padEnd(PAD)}${u2.dataDir}`);
+      if (u2.fix) out.push(`  ${"".padEnd(PAD)}fix: ${u2.fix}`);
+    }
+  }
+  if (r2.notChecked.length) {
+    out.push("");
+    out.push("Found on this machine, NOT checked by this command");
+    for (const l2 of r2.notChecked) out.push(`  ${l2}`);
+    out.push(
+      "  These belong to other AgentVault agent families. This command can only read the credentials of its own, so it says nothing about their health."
+    );
+  }
+  const counts = { PASS: 0, WARN: 0, FAIL: 0, SKIP: 0 };
+  for (const s2 of r2.services) counts[s2.verdict]++;
+  for (const u2 of r2.unsupervised) counts[u2.verdict]++;
+  out.push("");
+  out.push(
+    `Summary: ${counts.PASS} PASS, ${counts.WARN} WARN, ${counts.FAIL} FAIL, ${counts.SKIP} SKIP` + (counts.SKIP ? " (SKIP = could not check, NOT a problem found)" : "")
+  );
+  if (counts.FAIL) {
+    out.push(
+      "`uninstall` removes the SERVICE only \u2014 your credentials stay on disk, so a mistake here costs a re-install, not an identity."
+    );
+  }
+  return out;
+}
+var PAD;
+var init_doctor = __esm({
+  "src/service/doctor.ts"() {
+    "use strict";
+    PAD = 6;
+  }
+});
+
+// src/service/doctor-cli.ts
+var doctor_cli_exports = {};
+__export(doctor_cli_exports, {
+  fetchDeviceStatus: () => fetchDeviceStatus,
+  maybeRunDoctorSubcommand: () => maybeRunDoctorSubcommand,
+  realDoctorDeps: () => realDoctorDeps
 });
-import { existsSync as existsSync5, readFileSync as readFileSync4 } from "node:fs";
 import { join as join13 } from "node:path";
-function installOnReady(channel, cfg, deps) {
-  const hasCreds = deps.hasCreds ?? hasPersistedCreds;
-  const readLauncher = deps.readLauncher ?? ((p2) => existsSync5(p2) ? readFileSync4(p2, "utf8") : void 0);
-  const fenceAuthExists = deps.fenceAuthExists ?? ((home) => existsSync5(join13(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);
-      }
-    })();
+import { readdirSync as readdirSync2 } from "node:fs";
+async function fetchDeviceStatus(apiUrl, deviceId, doFetch = fetch) {
+  const res = await doFetch(`${apiUrl}/api/v1/devices/${deviceId}/status`, {
+    signal: AbortSignal.timeout(PROBE_TIMEOUT_MS)
   });
+  if (res.status === 404) {
+    try {
+      await res.json();
+    } catch {
+      return {
+        inconclusive: `${apiUrl} answered 404 with a non-JSON body \u2014 check AV_API_URL points at the API`
+      };
+    }
+    return { gone: true };
+  }
+  if (res.status === 429) return { inconclusive: "rate limited by the API (429)" };
+  if (!res.ok) return { inconclusive: `the API answered ${res.status}` };
+  let body;
+  try {
+    body = await res.json();
+  } catch {
+    return { inconclusive: `${apiUrl} answered 200 with a non-JSON body \u2014 check AV_API_URL` };
+  }
+  return { status: body?.status };
+}
+function listCredDirs(base) {
+  const out = [];
+  if (hasPersistedCreds(base)) out.push(base);
+  let names;
+  try {
+    names = readdirSync2(base);
+  } catch {
+    return out;
+  }
+  for (const name of names) {
+    const dir = join13(base, name);
+    if (hasPersistedCreds(dir)) out.push(dir);
+  }
+  return out;
+}
+function otherFamilyLabels(backend) {
+  const out = [];
+  for (const p2 of OTHER_FAMILY_PREFIXES) {
+    try {
+      for (const s2 of backend.list(p2)) out.push(s2.label);
+    } catch {
+    }
+  }
+  return out.sort();
+}
+function realDoctorDeps(env) {
+  const backend = selectBackend(process.platform);
+  const base = join13(env.HOME ?? "", ".agentvault", "grok-room-bridge");
+  return {
+    backend,
+    labelPrefixes: [LABEL_PREFIX],
+    base,
+    // Same default as config.ts. Read from the env directly rather than through
+    // loadConfig, which now REFUSES without AV_AGENT_NAME (#921) — and doctor's
+    // whole job is to run when you do not know which agents exist.
+    apiUrl: env.AV_API_URL ?? "https://api.agentvault.chat",
+    uninstallCommand: (n2) => `AV_AGENT_NAME=${n2 || "<agent-name>"} agentvault-grok-bridge uninstall`,
+    installCommand: (n2) => `AV_AGENT_NAME=${n2 || "<agent-name>"} agentvault-grok-bridge install`,
+    readCreds: (dir) => {
+      const deviceId = readPersistedDeviceId(dir);
+      return deviceId ? { deviceId } : null;
+    },
+    credDirs: () => listCredDirs(base),
+    fetchStatus: (apiUrl, deviceId) => fetchDeviceStatus(apiUrl, deviceId),
+    otherLabels: () => otherFamilyLabels(backend)
+  };
 }
-var DEFAULT_IDLE_TIMEOUT_MS;
-var init_install_on_ready = __esm({
-  "src/service/install-on-ready.ts"() {
+async function maybeRunDoctorSubcommand(argv, opts = {}) {
+  if (argv[2] !== "doctor") return false;
+  const log = opts.log ?? printLine;
+  try {
+    const report = await buildDoctorReport(opts.deps ?? realDoctorDeps(opts.env ?? process.env));
+    for (const line of formatDoctorReport(report)) log(line);
+    if (report.services.some((s2) => s2.verdict === "FAIL")) process.exitCode = 1;
+  } catch (e) {
+    log(`doctor could not run: ${e.message}`);
+    process.exitCode = 1;
+  }
+  return true;
+}
+var LABEL_PREFIX, OTHER_FAMILY_PREFIXES, PROBE_TIMEOUT_MS;
+var init_doctor_cli = __esm({
+  "src/service/doctor-cli.ts"() {
     "use strict";
-    init_config();
-    init_spec();
-    init_launcher();
     init_backend();
-    DEFAULT_IDLE_TIMEOUT_MS = 3e4;
+    init_config();
+    init_log();
+    init_doctor();
+    LABEL_PREFIX = "dev.agentvault.grok-";
+    OTHER_FAMILY_PREFIXES = [
+      "dev.agentvault.bridge-",
+      // claude bridge, current label
+      "com.agentvault.claude-bridge.",
+      // claude bridge, pre-rename label (#837)
+      "ai.hermes.gateway"
+      // hermes, one service per profile
+    ];
+    PROBE_TIMEOUT_MS = 8e3;
   }
 });
 
@@ -730,6 +1074,25 @@ var __toESM = (mod4, isNodeMode, target) => (target = mod4 != null ? __create(__
   isNodeMode || !mod4 || !mod4.__esModule ? __defProp2(target, "default", { value: mod4, enumerable: true }) : target,
   mod4
 ));
+function toEpoch(v2) {
+  if (typeof v2 === "bigint") return v2;
+  if (typeof v2 === "number") {
+    return Number.isFinite(v2) ? BigInt(Math.trunc(v2)) : null;
+  }
+  if (typeof v2 === "string" && /^\d+$/.test(v2)) return BigInt(v2);
+  return null;
+}
+function classifyCommitFailure(messageEpoch, groupEpoch) {
+  const msg = toEpoch(messageEpoch);
+  const grp = toEpoch(groupEpoch);
+  if (msg === null || grp === null) return "count";
+  return msg < grp ? "already-applied" : "count";
+}
+var init_mls_commit_classify = __esm2({
+  "src/mls-commit-classify.ts"() {
+    "use strict";
+  }
+});
 var __filename;
 var __dirname;
 var url2;
@@ -64077,7 +64440,7 @@ var init_mls_kp_pool = __esm2({
   }
 });
 function ownIdentity() {
-  const v2 = true ? "0.23.22" : FALLBACK;
+  const v2 = true ? "0.23.23" : FALLBACK;
   return `${PACKAGE}@${v2}`;
 }
 function buildClientVersion(override) {
@@ -64989,6 +65352,7 @@ var SecureChannel;
 var init_channel = __esm2({
   async "src/channel.ts"() {
     "use strict";
+    init_mls_commit_classify();
     await init_libsodium_wrappers();
     await init_dist();
     await init_dist();
@@ -66055,7 +66419,7 @@ var init_channel = __esm2({
        */
       sendActivitySpan(spanData) {
         if (!this._ws || this._ws.readyState !== WebSocket.OPEN) return;
-        const pluginVersion = true ? "0.23.22" : "0.0.0-dev";
+        const pluginVersion = true ? "0.23.23" : "0.0.0-dev";
         const agentName = this.config.agentName ?? "Agent";
         const resource = {
           "service.name": "agentvault-agent",
@@ -67965,7 +68329,7 @@ var init_channel = __esm2({
                 agentVersion: this.config.agentVersion ?? "0.0.0",
                 // __AV_VERSION__ is injected by esbuild from package.json at build time.
                 // Falls back to "0.0.0-dev" in non-bundled contexts (tests).
-                pluginVersion: true ? "0.23.22" : "0.0.0-dev"
+                pluginVersion: true ? "0.23.23" : "0.0.0-dev"
               });
               this._telemetryReporter.startAutoFlush(3e4);
             }
@@ -68289,7 +68653,7 @@ var init_channel = __esm2({
                     agentVersion: this.config.agentVersion ?? "0.0.0",
                     // __AV_VERSION__ is injected by esbuild from package.json at build time.
                     // Falls back to "0.0.0-dev" in non-bundled contexts (tests).
-                    pluginVersion: true ? "0.23.22" : "0.0.0-dev"
+                    pluginVersion: true ? "0.23.23" : "0.0.0-dev"
                   });
                   this._telemetryReporter.startAutoFlush(3e4);
                 }
@@ -69695,7 +70059,14 @@ ${messageText}`;
                 console.log(`[SecureChannel] MLS commit processed for room ${roomId.slice(0, 8)} (epoch=${mlsGroup.epoch})`);
                 this._mlsCommitFailCounts.delete(roomId);
               } catch (err) {
-                await this._onCommitFailure(roomId, groupId, err, `room ${roomId.slice(0, 8)}`);
+                await this._onCommitFailure(
+                  roomId,
+                  groupId,
+                  err,
+                  `room ${roomId.slice(0, 8)}`,
+                  data.epoch,
+                  mlsGroup.epoch
+                );
               }
             } else {
               this._bufferMlsCommit(groupId, epoch, data);
@@ -69715,7 +70086,14 @@ ${messageText}`;
                 console.log(`[SecureChannel] MLS commit processed for A2A ${chId.slice(0, 8)} (epoch=${mlsGroup.epoch})`);
                 this._mlsCommitFailCounts.delete(`a2a:${chId}`);
               } catch (err) {
-                await this._onCommitFailure(`a2a:${chId}`, groupId, err, `A2A ${chId.slice(0, 8)}`);
+                await this._onCommitFailure(
+                  `a2a:${chId}`,
+                  groupId,
+                  err,
+                  `A2A ${chId.slice(0, 8)}`,
+                  data.epoch,
+                  mlsGroup.epoch
+                );
               }
             } else {
               this._bufferMlsCommit(groupId, epoch, data);
@@ -69801,7 +70179,13 @@ ${messageText}`;
        * Never re-throws. The caller's only handler logs and drops, so throwing here
        * is indistinguishable from swallowing — it just moves the swallow one frame up.
        */
-      async _onCommitFailure(groupKey, mlsGroupId, err, label) {
+      async _onCommitFailure(groupKey, mlsGroupId, err, label, messageEpoch, groupEpoch) {
+        if (classifyCommitFailure(messageEpoch, groupEpoch) === "already-applied") {
+          console.debug(
+            `[SecureChannel] Skipping already-applied MLS commit for ${label} (commit epoch ${String(messageEpoch)} is behind group epoch ${String(groupEpoch)})`
+          );
+          return;
+        }
         const count = (this._mlsCommitFailCounts.get(groupKey) ?? 0) + 1;
         this._mlsCommitFailCounts.set(groupKey, count);
         console.error(
@@ -71699,7 +72083,7 @@ ${messageText}`;
           return;
         }
         this._authFailedThisSession = true;
-        const authReason = data?.reason ?? "device_revoked";
+        const authReason = data?.reason ?? "unknown";
         console.warn(
           `[SecureChannel] connection_rejected (reason=${data?.reason ?? "unknown"}, retryable=false) \u2014 terminal; surfacing auth_failed`
         );
@@ -98280,7 +98664,7 @@ var init_index = __esm2({
     init_skill_invoker();
     await init_skill_telemetry();
     await init_policy_enforcer();
-    VERSION = true ? "0.23.22" : "0.0.0-dev";
+    VERSION = true ? "0.23.23" : "0.0.0-dev";
   }
 });
 await init_index();
@@ -98921,6 +99305,40 @@ async function startRoomMcpServer(opts) {
   };
 }
 
+// src/service/self-uninstall.ts
+init_subcommand();
+init_backend();
+init_log();
+var DEVICE_IS_GONE = "device_revoked";
+function selfUninstallOnTerminal(reason, env, deps = {}) {
+  if (reason !== DEVICE_IS_GONE) return false;
+  const log = deps.log ?? ((m2) => logLine("[grok-bridge] " + m2));
+  let label;
+  try {
+    label = labelFor(env);
+  } catch (e) {
+    log(
+      `device was revoked, but ${e.message} \u2014 cannot tell which service to remove. Remove it by hand with: AV_AGENT_NAME=<agent-name> agentvault-grok-bridge uninstall`
+    );
+    return false;
+  }
+  try {
+    if (!deps.backend && process.platform !== "darwin" && process.platform !== "linux") return false;
+    const backend = deps.backend ?? selectBackend(process.platform);
+    if (!backend.status(label).loaded) return false;
+    backend.uninstall(label);
+    log(
+      `device was revoked \u2014 removed the supervised service ${label} so it does not sit installed on this machine pointing at an agent that no longer exists. Your credentials are still on disk and were NOT touched; re-install with a fresh invite token from AgentVault to reconnect.`
+    );
+    return true;
+  } catch (e) {
+    log(
+      `device was revoked, but removing the service ${label} failed: ${e.message}. Remove it by hand with: AV_AGENT_NAME=<agent-name> agentvault-grok-bridge uninstall`
+    );
+    return false;
+  }
+}
+
 // src/bridge.ts
 var RoomHushState = class {
   until = /* @__PURE__ */ new Map();
@@ -98976,11 +99394,13 @@ var ActiveTarget = class {
 function attachLifecycle2(channel, opts = {}) {
   const log = opts.log ?? (() => {
   });
+  const selfUninstall = opts.selfUninstall ?? selfUninstallOnTerminal;
   const onTerminal = opts.onTerminal ?? ((_reason, o2) => process.exit(o2.restart ? 1 : 0));
   const terminal = (reason, restart) => {
     log(
       `terminal condition (${reason}) \u2014 ${restart ? "gave up reconnecting; supervisor may respawn" : "this device must re-enroll or another session has taken over"}. Re-run/re-install with a fresh invite token from AgentVault if this persists.`
     );
+    selfUninstall(reason, process.env);
     onTerminal(reason, { restart });
   };
   channel.on("auth_failed", (e) => terminal(e.reason, false));
@@ -99134,6 +99554,10 @@ var shutdown = async (code = 0) => {
   }
 };
 async function main() {
+  const { maybeRunDoctorSubcommand: maybeRunDoctorSubcommand2 } = await Promise.resolve().then(() => (init_doctor_cli(), doctor_cli_exports));
+  if (await maybeRunDoctorSubcommand2(process.argv)) {
+    process.exit(process.exitCode ?? 0);
+  }
   const { maybeRunServiceSubcommand: maybeRunServiceSubcommand2 } = await Promise.resolve().then(() => (init_subcommand(), subcommand_exports));
   if (maybeRunServiceSubcommand2(process.argv, process.env, {
     log: (m2) => logLine("[grok-bridge] " + m2)
@@ -99143,7 +99567,7 @@ async function main() {
   const info = parseInfoFlags(process.argv.slice(2));
   if (info.showVersion || info.showHelp) {
     const version2 = buildClientVersion2(
-      true ? "0.3.1" : void 0
+      true ? "0.4.0" : void 0
     );
     if (info.showVersion) printLine(version2);
     if (info.showHelp) {
@@ -99182,11 +99606,6 @@ async function main() {
     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);
-  }
   mkdirSync6(cfg.workspaceDir, { recursive: true });
   mkdirSync6(cfg.fenceHome, { recursive: true });
   seedFenceCredential({
@@ -99201,7 +99620,7 @@ async function main() {
     agentName: cfg.agentName,
     platform: "node",
     clientVersion: buildClientVersion2(
-      true ? "0.3.1" : void 0
+      true ? "0.4.0" : void 0
     )
   });
   channelRef = channel;
@@ -99292,23 +99711,6 @@ async function main() {
       logLine("[grok-bridge] enrolled \u2014 pending invite consumed and removed");
     }
   });
-  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) => {