@beeos-ai/cli 1.0.13 → 1.0.14

package/dist/index.js

@@ -91,6 +91,10 @@ function configPath() {
   const p = getPlatformAdapter();
   return p.joinPath(beeoHome(), "config.toml");
 }
+function spawnEnvJsonPath() {
+  const p = getPlatformAdapter();
+  return p.joinPath(beeoHome(), "config.spawn-env.json");
+}
 function bindingPath() {
   const p = getPlatformAdapter();
   return p.joinPath(beeoHome(), "binding.json");
@@ -110,6 +114,336 @@ var init_paths = __esm({
   }
 });
 
+// ../core/dist/config/spawn-env.js
+function projectSpawnEnv(cfg) {
+  const out = {};
+  const agw = cfg.platform.agent_gateway_url?.trim();
+  if (agw)
+    out.agent_gateway_url = agw;
+  const bridge = cfg.platform.bridge_url?.trim();
+  if (bridge)
+    out.bridge_url = bridge;
+  return out;
+}
+async function saveSpawnEnvSnapshot(cfg) {
+  const p = getPlatformAdapter();
+  const path10 = spawnEnvJsonPath();
+  const snapshot = projectSpawnEnv(cfg);
+  try {
+    await p.mkdir(p.dirname(path10));
+    await p.writeFile(path10, JSON.stringify(snapshot, null, 2) + "\n");
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.error(`! warning: could not write ${path10}: ${message}
+  device-agent fleet will fall back to parsing config.toml directly.`);
+  }
+}
+var init_spawn_env = __esm({
+  "../core/dist/config/spawn-env.js"() {
+    "use strict";
+    init_platform_adapter();
+    init_paths();
+  }
+});
+
+// ../core/dist/errors.js
+function isBeeosError(err) {
+  return err instanceof BeeosError;
+}
+function toJsonFailurePayload(err) {
+  return {
+    ok: false,
+    error: {
+      code: err.code,
+      message: err.message,
+      ...err.hint !== void 0 ? { hint: err.hint } : {},
+      ...err.details !== void 0 ? { details: err.details } : {}
+    }
+  };
+}
+function formatHumanError(err) {
+  const parts = [`error [${err.code}]: ${err.message}`];
+  if (err.hint)
+    parts.push(`  $ ${err.hint}`);
+  return parts.join("\n");
+}
+var BeeosError;
+var init_errors = __esm({
+  "../core/dist/errors.js"() {
+    "use strict";
+    BeeosError = class extends Error {
+      code;
+      hint;
+      details;
+      constructor(options) {
+        super(options.message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+        this.name = "BeeosError";
+        this.code = options.code;
+        this.hint = options.hint;
+        this.details = options.details;
+      }
+    };
+  }
+});
+
+// ../core/dist/config/state.js
+function statePath() {
+  const p = getPlatformAdapter();
+  return p.joinPath(beeoHome(), "state.json");
+}
+function legacyDevicesPath() {
+  const p = getPlatformAdapter();
+  return p.joinPath(beeoHome(), "devices.json");
+}
+function defaultState() {
+  return {
+    version: 2,
+    platform: {
+      api_url: DEFAULT_API_URL,
+      agent_gateway_url: DEFAULT_AGENT_GATEWAY_URL,
+      dashboard_base_url: DEFAULT_DASHBOARD_URL
+    },
+    agents: []
+  };
+}
+async function loadState() {
+  const p = getPlatformAdapter();
+  const path10 = statePath();
+  if (await p.exists(path10)) {
+    let raw;
+    try {
+      raw = await p.readFile(path10);
+    } catch (e) {
+      throw new BeeosError({
+        code: "state_corrupted",
+        message: `failed to read ${path10}: ${describeError(e)}`,
+        hint: "Inspect the file or move it aside and re-run `beeos doctor` to regenerate from legacy state.",
+        details: { path: path10 },
+        cause: e
+      });
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(raw);
+    } catch (e) {
+      throw new BeeosError({
+        code: "state_corrupted",
+        message: `${path10} is not valid JSON: ${describeError(e)}`,
+        hint: "Move the file aside (e.g. `mv ~/.beeos/state.json ~/.beeos/state.json.broken`) and re-run `beeos doctor` to migrate from the legacy state files.",
+        details: { path: path10 }
+      });
+    }
+    return validateState(parsed, path10);
+  }
+  return migrateLegacy();
+}
+async function saveState(state) {
+  const p = getPlatformAdapter();
+  const path10 = statePath();
+  await p.mkdir(p.dirname(path10));
+  await p.writeFile(path10, JSON.stringify(state, null, 2) + "\n");
+  if (p.platform() !== "win32") {
+    try {
+      await p.chmod(path10, 384);
+    } catch {
+    }
+  }
+}
+function upsertOpenClawAgent(state, entry) {
+  const next = state.agents.filter((a) => !(a.kind === "openclaw" && a.framework === entry.framework));
+  next.push(entry);
+  return { ...state, agents: next };
+}
+function upsertDeviceAgent(state, entry) {
+  const next = state.agents.filter((a) => !(a.kind === "device" && a.serial === entry.serial));
+  next.push(entry);
+  return { ...state, agents: next };
+}
+async function mutateStateBestEffort(mutator, ctx) {
+  try {
+    const state = await loadState();
+    const next = mutator(state);
+    if (next === null)
+      return;
+    await saveState(next);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    const subject = ctx.subject ? ` for ${ctx.subject}` : "";
+    if (typeof console !== "undefined" && typeof console.warn === "function") {
+      console.warn(`Warning: could not update ~/.beeos/state.json${subject} (${msg}). ${ctx.authority} is still authoritative; run \`beeos doctor\` to repair.`);
+    }
+  }
+}
+async function migrateLegacy() {
+  const state = defaultState();
+  await tryReadSpawnEnvIntoPlatform(state);
+  const binding = await tryReadBinding();
+  if (binding) {
+    const platformAgw = state.platform.agent_gateway_url;
+    state.agents.push({
+      kind: "openclaw",
+      framework: binding.framework ?? "openclaw",
+      instance_id: binding.instance_id,
+      bound_at: binding.bound_at,
+      fingerprint: binding.fingerprint,
+      // Old binding.json never recorded per-binding AGW, so fall back
+      // to whatever the platform projection shows; saveConfig keeps
+      // this fresh on every config write.
+      agent_gateway_url: platformAgw
+    });
+  }
+  const devices = await tryReadDevices();
+  for (const d of devices) {
+    if (d.instance_id == null) {
+      continue;
+    }
+    const entry = {
+      kind: "device",
+      instance_id: d.instance_id,
+      bound_at: d.bound_at ?? 0,
+      fingerprint: d.fingerprint ?? "",
+      agent_gateway_url: d.agent_gateway_url && d.agent_gateway_url !== "" ? d.agent_gateway_url : state.platform.agent_gateway_url,
+      serial: d.serial,
+      name: d.name,
+      key_file: d.key_file,
+      http_port: d.http_port,
+      ...d.video_mode !== void 0 ? { video_mode: d.video_mode } : {},
+      ...d.backend !== void 0 ? { backend: d.backend } : {},
+      ...d.vnc_host !== void 0 ? { vnc_host: d.vnc_host } : {},
+      ...d.vnc_port !== void 0 ? { vnc_port: d.vnc_port } : {}
+    };
+    state.agents.push(entry);
+  }
+  await tryFoldVlmConfigs(state);
+  return state;
+}
+async function tryReadBinding() {
+  const p = getPlatformAdapter();
+  const path10 = bindingPath();
+  if (!await p.exists(path10))
+    return null;
+  try {
+    const raw = await p.readFile(path10);
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function tryReadDevices() {
+  const p = getPlatformAdapter();
+  const path10 = legacyDevicesPath();
+  if (!await p.exists(path10))
+    return [];
+  try {
+    const raw = await p.readFile(path10);
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed?.devices) ? parsed.devices : [];
+  } catch {
+    return [];
+  }
+}
+async function tryReadSpawnEnvIntoPlatform(state) {
+  const p = getPlatformAdapter();
+  const path10 = spawnEnvJsonPath();
+  if (!await p.exists(path10))
+    return;
+  try {
+    const raw = await p.readFile(path10);
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object")
+      return;
+    if (typeof parsed.agent_gateway_url === "string" && parsed.agent_gateway_url.length > 0) {
+      state.platform.agent_gateway_url = parsed.agent_gateway_url;
+    }
+    if (typeof parsed.bridge_url === "string" && parsed.bridge_url.length > 0) {
+      state.platform.bridge_url = parsed.bridge_url;
+    }
+  } catch {
+  }
+}
+async function tryFoldVlmConfigs(state) {
+  const p = getPlatformAdapter();
+  const root = beeoHome();
+  let entries = [];
+  try {
+    entries = await p.readdir(root);
+  } catch {
+    return;
+  }
+  const byInstanceId = /* @__PURE__ */ new Map();
+  for (const a of state.agents)
+    byInstanceId.set(a.instance_id, a);
+  for (const name of entries) {
+    if (!name.endsWith(".config.json"))
+      continue;
+    if (name === "config.spawn-env.json")
+      continue;
+    const instanceId = name.slice(0, -".config.json".length);
+    const target = byInstanceId.get(instanceId);
+    if (!target)
+      continue;
+    const filePath = p.joinPath(root, name);
+    try {
+      const raw = await p.readFile(filePath);
+      const parsed = JSON.parse(raw);
+      target.agent_config = parsed;
+    } catch {
+    }
+  }
+}
+function validateState(parsed, path10) {
+  if (!parsed || typeof parsed !== "object") {
+    throw new BeeosError({
+      code: "state_corrupted",
+      message: `${path10} did not deserialise to a JSON object.`,
+      hint: "Move the file aside and re-run `beeos doctor` to regenerate.",
+      details: { path: path10 }
+    });
+  }
+  const obj = parsed;
+  const version = obj.version;
+  if (version !== 2) {
+    throw new BeeosError({
+      code: "state_version_mismatch",
+      message: `${path10} declares version=${JSON.stringify(version)}; this CLI only understands version=2.`,
+      hint: "Either upgrade the CLI (`beeos --version` to see what you have) or move the file aside and re-bind your agents with the older CLI's flow.",
+      details: { path: path10, observed: version, expected: 2 }
+    });
+  }
+  const platform = obj.platform;
+  if (!platform || typeof platform !== "object") {
+    throw new BeeosError({
+      code: "state_corrupted",
+      message: `${path10} is missing a \`platform\` object.`,
+      hint: "Move the file aside and re-run `beeos doctor`.",
+      details: { path: path10 }
+    });
+  }
+  if (!Array.isArray(obj.agents)) {
+    throw new BeeosError({
+      code: "state_corrupted",
+      message: `${path10} \`agents\` is not an array.`,
+      hint: "Move the file aside and re-run `beeos doctor`.",
+      details: { path: path10 }
+    });
+  }
+  return obj;
+}
+function describeError(e) {
+  if (e instanceof Error)
+    return e.message;
+  return String(e);
+}
+var init_state = __esm({
+  "../core/dist/config/state.js"() {
+    "use strict";
+    init_errors();
+    init_platform_adapter();
+    init_paths();
+    init_types();
+  }
+});
+
 // ../core/dist/config/toml.js
 import * as TOML from "smol-toml";
 async function loadOrCreateConfig() {
@@ -119,6 +453,8 @@ async function loadOrCreateConfig() {
     const raw = await p.readFile(path10);
     const parsed = TOML.parse(raw);
     const cfg2 = mergeWithDefaults(parsed);
+    await saveSpawnEnvSnapshot(cfg2);
+    await refreshStatePlatformBestEffort(cfg2);
     return applyEnvOverrides(cfg2);
   }
   const cfg = defaultConfig();
@@ -144,12 +480,16 @@ async function saveConfig(cfg) {
   const p = getPlatformAdapter();
   const path10 = configPath();
   await p.mkdir(p.dirname(path10));
+  const platformBlock = {
+    api_url: cfg.platform.api_url,
+    agent_gateway_url: cfg.platform.agent_gateway_url,
+    dashboard_base_url: cfg.platform.dashboard_base_url
+  };
+  if (cfg.platform.bridge_url && cfg.platform.bridge_url.trim() !== "") {
+    platformBlock.bridge_url = cfg.platform.bridge_url;
+  }
   const serializable = {
-    platform: {
-      api_url: cfg.platform.api_url,
-      agent_gateway_url: cfg.platform.agent_gateway_url,
-      dashboard_base_url: cfg.platform.dashboard_base_url
-    },
+    platform: platformBlock,
     device: {
       http_enabled: cfg.device.http_enabled,
       http_port: cfg.device.http_port
@@ -157,6 +497,20 @@ async function saveConfig(cfg) {
   };
   const raw = TOML.stringify(serializable);
   await p.writeFile(path10, raw);
+  await saveSpawnEnvSnapshot(cfg);
+  await refreshStatePlatformBestEffort(cfg);
+}
+async function refreshStatePlatformBestEffort(cfg) {
+  const platform = {
+    api_url: cfg.platform.api_url,
+    agent_gateway_url: cfg.platform.agent_gateway_url,
+    dashboard_base_url: cfg.platform.dashboard_base_url,
+    ...cfg.platform.bridge_url && cfg.platform.bridge_url.trim() !== "" ? { bridge_url: cfg.platform.bridge_url } : {}
+  };
+  await mutateStateBestEffort((state) => platformEqual(state.platform, platform) ? null : { ...state, platform }, { authority: "config.spawn-env.json (legacy mirror)" });
+}
+function platformEqual(a, b) {
+  return a.api_url === b.api_url && a.agent_gateway_url === b.agent_gateway_url && a.dashboard_base_url === b.dashboard_base_url && a.bridge_url === b.bridge_url;
 }
 function mergeWithDefaults(parsed) {
   const platform = parsed.platform ?? {};
@@ -207,6 +561,8 @@ var init_toml = __esm({
     "use strict";
     init_platform_adapter();
     init_paths();
+    init_spawn_env();
+    init_state();
     init_types();
   }
 });
@@ -587,14 +943,18 @@ async function bindAgent(opts) {
       const instanceId = await pollUntilBound(opts.apiUrl, bindId, pollTimeoutMs);
       return { status: "bound", instanceId, source: "fresh" };
     } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      if (/timed out|expired/i.test(msg)) {
+      if (e instanceof BeeosError && e.code === "bind_pending_expired") {
         return { status: "pending_expired" };
       }
       throw e;
     }
   }
-  throw new Error(`unexpected bind status: ${resp.status}`);
+  throw new BeeosError({
+    code: "bind_protocol_unexpected",
+    message: `Unexpected bind protocol response (status: '${resp.status}').`,
+    hint: "Re-run the command. If this persists, check the platform's `/api/v1/agent/bind` health and contact support with the requested fingerprint.",
+    details: { received: resp.status, fingerprint: opts.fingerprint }
+  });
 }
 async function presentBindUrl(bindUrl, forceHeadless, log = console.log) {
   const p = getPlatformAdapter();
@@ -624,7 +984,12 @@ async function pollUntilBound(apiUrl, bindId, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
   while (true) {
     if (Date.now() > deadline) {
-      throw new Error("Bind approval timed out \u2014 please re-run the command");
+      throw new BeeosError({
+        code: "bind_pending_expired",
+        message: "Bind approval timed out \u2014 please re-run the command.",
+        hint: "Approve the request in the dashboard sooner, or re-run with the same identity to start a fresh bind.",
+        details: { source: "client_timeout", bindId }
+      });
     }
     try {
       const resp = await pollBind(apiUrl, bindId);
@@ -632,12 +997,17 @@ async function pollUntilBound(apiUrl, bindId, timeoutMs) {
         return resp.instance_id ?? "";
       }
       if (resp.status === "expired") {
-        throw new Error("Bind session expired \u2014 please re-run the command");
+        throw new BeeosError({
+          code: "bind_pending_expired",
+          message: "Bind session expired \u2014 please re-run the command.",
+          hint: "Re-run `beeos start` to start a fresh bind session.",
+          details: { source: "server_expired", bindId }
+        });
       }
     } catch (e) {
-      const msg = e instanceof Error ? e.message : String(e);
-      if (msg.includes("expired") || msg.includes("timed out"))
+      if (e instanceof BeeosError && e.code === "bind_pending_expired") {
         throw e;
+      }
       await sleep(2e3);
     }
   }
@@ -692,6 +1062,139 @@ var init_orchestrator = __esm({
     init_client();
     init_process();
     init_qr();
+    init_errors();
+  }
+});
+
+// ../core/dist/upgrade.js
+function readPinSourcesFromEnv() {
+  const env = globalThis.process?.env ?? {};
+  return {
+    env: {
+      [NPM_PKGS.CLI]: trimOrUndef(env.BEEOS_CLI_VERSION),
+      [NPM_PKGS.DEVICE_AGENT]: trimOrUndef(env.BEEOS_DEVICE_AGENT_VERSION),
+      [NPM_PKGS.DEVICE_MCP_SERVER]: trimOrUndef(env.BEEOS_MCP_SERVER_VERSION)
+    },
+    distTag: trimOrUndef(env.BEEOS_CLI_TAG)
+  };
+}
+function resolveInstallSpec(pkg, sources) {
+  const pin = sources.env?.[pkg];
+  if (pin)
+    return `${pkg}@${pin}`;
+  const tag = sources.distTag ?? "latest";
+  return `${pkg}@${tag}`;
+}
+async function npmRegistryVersion(spec) {
+  const p = getPlatformAdapter();
+  try {
+    const result = await p.exec("npm", ["view", spec, "version"], { timeout: 3e4 });
+    if (result.code !== 0)
+      return null;
+    const trimmed = result.stdout.trim();
+    return trimmed || null;
+  } catch {
+    return null;
+  }
+}
+async function npmGlobalVersion(pkg) {
+  const p = getPlatformAdapter();
+  try {
+    const result = await p.exec("npm", ["ls", "-g", "--depth=0", "--json", pkg], { timeout: 3e4 });
+    if (!result.stdout)
+      return null;
+    const parsed = JSON.parse(result.stdout);
+    const ver = parsed.dependencies?.[pkg]?.version;
+    return typeof ver === "string" ? ver : null;
+  } catch {
+    return null;
+  }
+}
+async function upgradeBeeosSuite(opts) {
+  const p = getPlatformAdapter();
+  const sources = opts.sources ?? readPinSourcesFromEnv();
+  const progress = opts.progress;
+  const specs = opts.packages.map((pkg) => ({
+    pkg,
+    spec: resolveInstallSpec(pkg, sources)
+  }));
+  const beforeVers = /* @__PURE__ */ new Map();
+  for (const { pkg } of specs) {
+    beforeVers.set(pkg, await npmGlobalVersion(pkg));
+  }
+  let needsInstall = opts.forceInstall === true;
+  if (!needsInstall) {
+    for (const { pkg, spec } of specs) {
+      const target = await npmRegistryVersion(spec);
+      const current = beforeVers.get(pkg) ?? null;
+      if (target === null || current === null || target !== current) {
+        needsInstall = true;
+        break;
+      }
+    }
+  }
+  let installFailure;
+  if (needsInstall) {
+    const args = ["install", "-g", ...specs.map((s) => s.spec)];
+    progress?.onStatus(`npm ${args.join(" ")}`);
+    try {
+      const result2 = await p.exec("npm", args, { timeout: 6e5 });
+      if (result2.code !== 0) {
+        installFailure = (result2.stderr || result2.stdout || `npm install -g exited ${result2.code}`).trim();
+      }
+    } catch (e) {
+      installFailure = e instanceof Error ? e.message : String(e);
+    }
+  } else {
+    progress?.onStatus("Already up to date \u2014 skipping npm install -g");
+  }
+  const result = { packages: [], anyChanged: false, anyFailed: false };
+  for (const { pkg, spec } of specs) {
+    const before = beforeVers.get(pkg) ?? null;
+    const after = await npmGlobalVersion(pkg);
+    const changed = before !== after;
+    const entry = {
+      pkg,
+      spec,
+      before,
+      after,
+      changed,
+      ...installFailure ? { failed: installFailure } : {}
+    };
+    result.packages.push(entry);
+    if (changed)
+      result.anyChanged = true;
+    if (entry.failed)
+      result.anyFailed = true;
+    if (changed) {
+      progress?.onStatus(`${pkg}: ${before ?? "(none)"} \u2192 ${after}`);
+    } else if (entry.failed) {
+      progress?.onStatus(`${pkg}: install failed (${entry.failed})`);
+    }
+  }
+  return result;
+}
+function trimOrUndef(v) {
+  if (v === void 0)
+    return void 0;
+  const t = v.trim();
+  return t.length > 0 ? t : void 0;
+}
+var NPM_PKGS, ALL_BEEOS_PKGS;
+var init_upgrade = __esm({
+  "../core/dist/upgrade.js"() {
+    "use strict";
+    init_platform_adapter();
+    NPM_PKGS = {
+      CLI: "@beeos-ai/cli",
+      DEVICE_AGENT: "@beeos-ai/device-agent",
+      DEVICE_MCP_SERVER: "@beeos-ai/device-mcp-server"
+    };
+    ALL_BEEOS_PKGS = [
+      NPM_PKGS.CLI,
+      NPM_PKGS.DEVICE_AGENT,
+      NPM_PKGS.DEVICE_MCP_SERVER
+    ];
   }
 });
 
@@ -718,8 +1221,21 @@ function describeFound(bin, progress) {
   }
 }
 async function upgradeDeviceAgent(progress) {
-  progress.onStatus("device-agent (TS) \u2014 upgrade out-of-band:\n  \u2022 dev:    cd agents/device-agent && git pull && pnpm install && pnpm -r build\n  \u2022 global: npm i -g @beeos-ai/device-agent@latest");
-  progress.onComplete("device-agent upgrade hint printed");
+  const outcome = await upgradeBeeosSuite({
+    packages: [NPM_PKGS.DEVICE_AGENT, NPM_PKGS.DEVICE_MCP_SERVER],
+    progress
+  });
+  if (outcome.anyFailed) {
+    const failed = outcome.packages.find((p) => p.failed)?.failed;
+    progress.onStatus(`device-agent upgrade did not finish cleanly (${failed ?? "unknown error"}).
+Manual fix: npm i -g @beeos-ai/device-agent @beeos-ai/device-mcp-server`);
+    return;
+  }
+  if (!outcome.anyChanged) {
+    progress.onComplete("device-agent already up to date");
+    return;
+  }
+  progress.onComplete("device-agent upgraded");
 }
 async function findExistingTs() {
   const p = getPlatformAdapter();
@@ -776,6 +1292,7 @@ var init_device_setup = __esm({
   "../core/dist/device-setup.js"() {
     "use strict";
     init_platform_adapter();
+    init_upgrade();
   }
 });
 
@@ -870,6 +1387,14 @@ async function ensureAdb(progress, options = {}) {
     return installAdb(progress);
   return null;
 }
+function detectAdbLicenseDecision() {
+  const env = globalThis.process?.env ?? {};
+  if (env.BEEOS_ACCEPT_ADB_LICENSE === "1")
+    return "accepted";
+  if (env.BEEOS_REJECT_ADB_LICENSE === "1")
+    return "rejected";
+  return "unknown";
+}
 function adbZipName() {
   const p = getPlatformAdapter();
   return PLATFORM_TOOLS_ARCHIVE[p.platform()] ?? null;
@@ -884,7 +1409,12 @@ function verifyPlatformToolsChecksum(zipName, data, progress) {
       progress.onStatus(`BEEOS_ADB_SKIP_CHECKSUM=1 \u2014 skipping SHA-256 verification (no pin recorded for ${zipName}).`);
       return;
     }
-    throw new Error(`platform-tools download: no SHA-256 pin recorded for "${zipName}". Refusing to execute an unverified archive. Run scripts/refresh-adb-hashes.mjs ${PLATFORM_TOOLS_REVISION} to populate, or set BEEOS_ADB_SKIP_CHECKSUM=1 to override (offline mirror / pre-pin development only; not safe for CI/release).`);
+    throw new BeeosError({
+      code: "adb_checksum_missing",
+      message: `platform-tools download: no SHA-256 pin recorded for "${zipName}".`,
+      hint: `Run scripts/refresh-adb-hashes.mjs ${PLATFORM_TOOLS_REVISION} to populate the table, or set BEEOS_ADB_SKIP_CHECKSUM=1 to override (offline mirror / pre-pin development only; not safe for CI/release).`,
+      details: { archive: zipName, revision: PLATFORM_TOOLS_REVISION }
+    });
   }
   if (actual === expected)
     return;
@@ -892,23 +1422,20 @@ function verifyPlatformToolsChecksum(zipName, data, progress) {
     progress.onStatus(`BEEOS_ADB_SKIP_CHECKSUM=1 \u2014 mismatched SHA-256 IGNORED: got ${actual.slice(0, 16)}\u2026, expected ${expected.slice(0, 16)}\u2026.`);
     return;
   }
-  throw new Error(`platform-tools SHA-256 mismatch for ${zipName}.
-  expected: ${expected}
-  got:      ${actual}
-Refusing to execute the downloaded archive. Likely causes:
-  - CDN mirror served a different revision than we pinned
-    (rotate via scripts/refresh-adb-hashes.mjs after cross-checking
-    against https://dl.google.com/android/repository/repository2-3.xml)
-  - Archive corrupted in transit (retry)
-  - Supply-chain tampering (investigate before overriding)
-Set BEEOS_ADB_SKIP_CHECKSUM=1 to bypass (not recommended).`);
-}
-var PLATFORM_TOOLS_BASE, PLATFORM_TOOLS_REVISION, PLATFORM_TOOLS_ARCHIVE, PLATFORM_TOOLS_SHA256;
+  throw new BeeosError({
+    code: "adb_checksum_mismatch",
+    message: `platform-tools SHA-256 mismatch for ${zipName}.`,
+    hint: "Likely causes:\n  - CDN mirror served a different revision than we pinned (rotate via scripts/refresh-adb-hashes.mjs after cross-checking against https://dl.google.com/android/repository/repository2-3.xml)\n  - Archive corrupted in transit (retry)\n  - Supply-chain tampering (investigate before overriding)\nSet BEEOS_ADB_SKIP_CHECKSUM=1 to bypass (not recommended).",
+    details: { archive: zipName, expected, actual }
+  });
+}
+var PLATFORM_TOOLS_BASE, PLATFORM_TOOLS_REVISION, PLATFORM_TOOLS_ARCHIVE, PLATFORM_TOOLS_SHA256, ADB_LICENSE_URL;
 var init_adb_setup = __esm({
   "../core/dist/adb-setup.js"() {
     "use strict";
     init_platform_adapter();
     init_paths();
+    init_errors();
     PLATFORM_TOOLS_BASE = "https://dl.google.com/android/repository";
     PLATFORM_TOOLS_REVISION = "r37.0.0";
     PLATFORM_TOOLS_ARCHIVE = {
@@ -917,8 +1444,41 @@ var init_adb_setup = __esm({
       win32: `platform-tools_${PLATFORM_TOOLS_REVISION}-win.zip`
     };
     PLATFORM_TOOLS_SHA256 = {
-      // Populated by scripts/refresh-adb-hashes.mjs — keys are the
-      // archive filenames for the pinned PLATFORM_TOOLS_REVISION.
+      // sha1 (google manifest): 8c4c926d0ca192376b2a04b0318484724319e67c
+      "platform-tools_r37.0.0-darwin.zip": "094a1395683c509fd4d48667da0d8b5ef4d42b2abfcd29f2e8149e2f989357c7",
+      // sha1 (google manifest): bcf323933980a59dccc3f14c339aed5fb2171163
+      "platform-tools_r37.0.0-linux.zip": "198ae156ab285fa555987219af237b31102fefe8b9d2bc274708a8d4f2865a07",
+      // sha1 (google manifest): f29bfb58d0d6f9a57d7dbcba6cc259f9ca6f58f1
+      "platform-tools_r37.0.0-win.zip": "4fe305812db074cea32903a489d061eb4454cbc90a49e8fea677f4b7af764918"
+    };
+    ADB_LICENSE_URL = "https://developer.android.com/studio/terms";
+  }
+});
+
+// ../core/dist/runtime/spawn-env.js
+function buildDeviceAgentSpawnEnv(input) {
+  const env = {};
+  if (input.agentGatewayUrl) {
+    env[DEVICE_AGENT_SPAWN_ENV_KEYS.AGENT_GATEWAY_URL] = input.agentGatewayUrl;
+  }
+  if (input.extra) {
+    for (const [k, v] of Object.entries(input.extra)) {
+      if (v)
+        env[k] = v;
+    }
+  }
+  return env;
+}
+var DEVICE_AGENT_SPAWN_ENV_KEYS;
+var init_spawn_env2 = __esm({
+  "../core/dist/runtime/spawn-env.js"() {
+    "use strict";
+    DEVICE_AGENT_SPAWN_ENV_KEYS = {
+      /**
+       * Agent Gateway base URL. Used by device-agent for `/bootstrap`,
+       * bridge config discovery, and Message Service token exchange.
+       */
+      AGENT_GATEWAY_URL: "AGENT_GATEWAY_URL"
     };
   }
 });
@@ -933,6 +1493,7 @@ var init_device = __esm({
     init_keypair();
     init_device_setup();
     init_progress();
+    init_spawn_env2();
     deviceRuntime = {
       agentFramework() {
         return "device";
@@ -1008,10 +1569,7 @@ var init_device = __esm({
         const logDir = p.joinPath(beeoHome(), "logs");
         await p.mkdir(logDir);
         const logFile = p.joinPath(logDir, `device-${serial}.log`);
-        const env = {};
-        if (agentGatewayUrl) {
-          env.AGENT_GATEWAY_URL = agentGatewayUrl;
-        }
+        const env = buildDeviceAgentSpawnEnv({ agentGatewayUrl });
         const result = await p.spawn(cmd, args, {
           detached: true,
           stdoutFile: logFile,
@@ -1199,7 +1757,9 @@ async function downloadManagedBinary(cfg, target, progress) {
   if (!data)
     return null;
   const digestUrl = `${url}.sha256`;
+  const allowUnverified = (process.env?.BEEOS_ALLOW_UNVERIFIED_SIDECAR ?? "").toLowerCase() === "1" || (process.env?.BEEOS_ALLOW_UNVERIFIED_SIDECAR ?? "").toLowerCase() === "true";
   let expected = null;
+  let digestFetchError = null;
   try {
     const digResp = await p.fetch(digestUrl);
     if (digResp.ok) {
@@ -1207,18 +1767,35 @@ async function downloadManagedBinary(cfg, target, progress) {
       const first = text.split(/\s+/)[0] ?? "";
       if (/^[a-f0-9]{64}$/i.test(first))
         expected = first.toLowerCase();
+      else
+        digestFetchError = `malformed .sha256 body: ${text.slice(0, 80)}`;
+    } else {
+      digestFetchError = `HTTP ${digResp.status}`;
     }
-  } catch {
+  } catch (e) {
+    digestFetchError = e instanceof Error ? e.message : String(e);
   }
   if (expected) {
     const actual = createHash2("sha256").update(data).digest("hex");
     if (actual !== expected) {
       progress.onStatus(`${cfg.name} checksum mismatch (expected ${expected.slice(0, 12)}\u2026, got ${actual.slice(0, 12)}\u2026) \u2014 aborting install.`);
-      return null;
+      throw new BeeosError({
+        code: "sidecar_checksum_mismatch",
+        message: `${cfg.name} archive integrity check failed at ${url}`,
+        hint: "The downloaded archive does not match the publisher's checksum. Possible causes: MITM proxy rewriting the asset, a corrupted CDN cache, or a malicious replacement. Retry once; if it persists, file a bug at the sidecar's release repo.",
+        details: { sidecar: cfg.name, url, expected, actual }
+      });
     }
     progress.onStatus(`${cfg.name} checksum ok (${expected.slice(0, 12)}\u2026).`);
+  } else if (allowUnverified) {
+    progress.onStatus(`${cfg.name}: no .sha256 sidecar at ${digestUrl} (${digestFetchError ?? "unavailable"}) \u2014 BEEOS_ALLOW_UNVERIFIED_SIDECAR=1 set, continuing without integrity check (NOT recommended).`);
   } else {
-    progress.onStatus(`${cfg.name}: no .sha256 sidecar at ${digestUrl} \u2014 continuing without integrity check`);
+    throw new BeeosError({
+      code: "sidecar_checksum_missing",
+      message: `${cfg.name}: no .sha256 sidecar at ${digestUrl}` + (digestFetchError ? ` (${digestFetchError})` : ""),
+      hint: "The publisher must ship a .sha256 alongside every release asset (cargo-dist does this by default). If you are on a locked-down network that blocks .sha256 URLs, set BEEOS_ALLOW_UNVERIFIED_SIDECAR=1 to opt out \u2014 but understand you are accepting an unverified binary.",
+      details: { sidecar: cfg.name, archiveUrl: url, digestUrl }
+    });
   }
   const binDir = p.joinPath(beeoHome(), "bin");
   await p.mkdir(binDir);
@@ -1286,6 +1863,7 @@ var init_cargo_dist = __esm({
     "use strict";
     init_platform_adapter();
     init_paths();
+    init_errors();
   }
 });
 
@@ -1549,7 +2127,7 @@ async function writeDeviceAgentConfig(input) {
   if (p.platform() !== "win32") {
     await p.chmod(file, 384);
   }
-  return file;
+  return { filePath: file, payload };
 }
 async function persistAgentConfigBestEffort(input) {
   const reporter = input.reporter ?? noopReporter;
@@ -1563,7 +2141,7 @@ async function persistAgentConfigBestEffort(input) {
     if (result.keyMissing) {
       reporter.onStatus(`  VLM API key not configured for instance ${input.instanceId} \u2014 set AROUTER_API_KEY in the dashboard, then run \`beeos device refresh-config\`.`);
     }
-    const file = await writeDeviceAgentConfig({
+    return await writeDeviceAgentConfig({
       instanceId: input.instanceId,
       vlmApiKey: result.vlmApiKey,
       vlmModel: result.vlmModel,
@@ -1573,7 +2151,6 @@ async function persistAgentConfigBestEffort(input) {
       ...input.mobileUse ? { mobileUse: input.mobileUse } : {},
       ...input.grounder ? { grounder: input.grounder } : {}
     });
-    return file;
   } catch (e) {
     reporter.onStatus(`  VLM config not fetched (${e.message}). Agent will run without ARouter \u2014 pass \`--vlm-api-key\` for standalone testing or run \`beeos device refresh-config\` later.`);
     return null;
@@ -1657,6 +2234,9 @@ function hasLocalDetection(driver) {
 function hasStartupDiagnostics(driver) {
   return typeof driver.diagnoseStartup === "function";
 }
+function hasPreflightConflictCheck(driver) {
+  return typeof driver.preflightConflictCheck === "function";
+}
 var init_driver = __esm({
   "../core/dist/agent/driver.js"() {
     "use strict";
@@ -1728,10 +2308,16 @@ async function downloadAgent(npmPackage, requestedVersion, agentFramework, progr
   }
   return dest;
 }
+function pluginVersionPin() {
+  const env = globalThis.process?.env;
+  const fromEnv = env?.BEEOS_BEEOS_CLAW_VERSION?.trim();
+  return fromEnv && fromEnv.length > 0 ? fromEnv : void 0;
+}
 async function downloadPlugin(pluginPackage, agentFramework, progress, installedVersion) {
   const p = getPlatformAdapter();
   const info = await fetchNpmPackageInfo(pluginPackage);
-  const version = info["dist-tags"]["latest"];
+  const pin = pluginVersionPin();
+  const version = pin ?? info["dist-tags"]["latest"];
   if (!version)
     throw new Error("no 'latest' tag for plugin");
   if (installedVersion && semverGte(installedVersion, version)) {
@@ -1852,13 +2438,22 @@ async function locateManagedBinary() {
 }
 async function downloadManagedOpenclaw(reporter, versionOverride) {
   reporter.onStatus(`Downloading ${OPENCLAW_NPM_PACKAGE}...`);
-  await downloadAgent(OPENCLAW_NPM_PACKAGE, versionOverride, OPENCLAW_ID, reporter);
+  await downloadAgent(OPENCLAW_NPM_PACKAGE, resolveOpenclawVersion(versionOverride), OPENCLAW_ID, reporter);
   const binary = await locateManagedBinary();
   if (!binary) {
     throw new Error("openclaw binary not found after download \u2014 expected it under ~/.beeos/agents/openclaw/versions/current/");
   }
   return binary;
 }
+function resolveOpenclawVersion(explicit) {
+  if (explicit && explicit.trim().length > 0)
+    return explicit.trim();
+  const env = globalThis.process?.env;
+  const fromEnv = env?.BEEOS_OPENCLAW_VERSION?.trim();
+  if (fromEnv && fromEnv.length > 0)
+    return fromEnv;
+  return void 0;
+}
 var init_download = __esm({
   "../core/dist/openclaw/download.js"() {
     "use strict";
@@ -1887,6 +2482,10 @@ async function readLocalPluginVersion(agentHome2) {
   }
   return null;
 }
+async function isPluginInstalled(agentHome2) {
+  const p = getPlatformAdapter();
+  return p.exists(p.joinPath(agentHome2, "extensions", "beeos-claw"));
+}
 async function findAgent(driver) {
   const managed = await locateManagedBinary();
   if (managed) {
@@ -2442,12 +3041,20 @@ function fallbackSystemHome() {
 async function isOpenclawGatewayRunning() {
   return getPlatformAdapter().tcpProbe(OPENCLAW_GATEWAY_HOST, OPENCLAW_GATEWAY_PORT, 500);
 }
+function describeError2(e) {
+  if (e instanceof Error) {
+    const msg = e.message.split(/\r?\n/, 1)[0]?.trim();
+    return msg && msg.length > 0 ? msg : e.name;
+  }
+  return String(e);
+}
 var OpenclawDriver, openClawDriver;
 var init_driver2 = __esm({
   "../core/dist/openclaw/driver.js"() {
     "use strict";
     init_platform_adapter();
     init_paths();
+    init_detector();
     init_constants();
     init_config();
     init_detect_local();
@@ -2461,10 +3068,12 @@ var init_driver2 = __esm({
       displayName = OPENCLAW_DISPLAY_NAME;
       async launch(ctx, reporter) {
         const p = getPlatformAdapter();
+        const warnings = [];
         const picked = await pickLocation(ctx, reporter);
         try {
           await ensureOpenclawPlugin(picked.home, picked.binary, reporter);
-        } catch {
+        } catch (e) {
+          warnings.push(`plugin: failed to register beeos-claw plugin into ${picked.home} (${describeError2(e)}); the gateway will start but BeeOS-specific tools may not be available. Re-run \`beeos doctor\`.`);
         }
         const gatewayToken = await resolveGatewayToken(picked.home, picked.isSystemHome);
         if (picked.isSystemHome)
@@ -2491,14 +3100,16 @@ var init_driver2 = __esm({
         } else if (picked.isSystemHome) {
           try {
             await configurePluginViaCli(configCtx);
-          } catch {
+          } catch (e) {
+            warnings.push(`live-reconfigure: failed to update beeos-claw plugin section in running ${picked.home} (${describeError2(e)}); the foreign gateway may still be serving an older plugin config. Stop it and re-run \`beeos start openclaw --force\` to force a clean register.`);
           }
           try {
             await restartGatewayViaCli(configCtx);
-          } catch {
+          } catch (e) {
+            warnings.push(`live-reconfigure: failed to restart running gateway after re-configuring (${describeError2(e)}); changes may not take effect until the gateway is restarted manually.`);
           }
         }
-        return buildOpenclawServiceSpec({
+        const spec = buildOpenclawServiceSpec({
           agentBinary: picked.binary,
           agentHome: picked.home,
           agentGatewayUrl: ctx.agentGatewayUrl,
@@ -2506,6 +3117,7 @@ var init_driver2 = __esm({
           isSystemHome: picked.isSystemHome,
           envOverrides: ctx.envOverrides
         });
+        return { spec, warnings };
       }
       async detectLocal() {
         return detectLocalOpenclaw();
@@ -2513,6 +3125,34 @@ var init_driver2 = __esm({
       async diagnoseStartup(logPath) {
         return diagnoseOpenclawStartup(logPath);
       }
+      /**
+       * P0-C of the install-link review: previously this probe lived in
+       * `commands/start.ts` with hard-coded "OpenClaw gateway port" copy
+       * and `identifyGateway()` defaults — the abstraction promise that
+       * "a new framework = a new registry entry" was broken because
+       * adding e.g. Cline / Roo would have triggered a misleading
+       * OpenClaw-flavoured error. The probe is now a driver-owned
+       * capability; the CLI just routes the structured report into a
+       * generic `gateway_port_conflict` BeeosError.
+       */
+      async preflightConflictCheck(ctx) {
+        const probe = await identifyGateway({ expectedFingerprint: ctx.fingerprint });
+        switch (probe.state) {
+          case "unreachable":
+            return { state: "unreachable" };
+          case "own":
+            return { state: "ours" };
+          case "foreign":
+            return {
+              state: "foreign",
+              detail: `a different beeos-claw gateway (fingerprint ${probe.fingerprint.slice(0, 16)}\u2026, plugin ${probe.pluginVersion || "?"})`
+            };
+          case "unknown":
+            return { state: "unknown", reason: probe.reason };
+          default:
+            return { state: "unknown", reason: `unhandled probe state` };
+        }
+      }
     };
     openClawDriver = new OpenclawDriver();
   }
@@ -2573,23 +3213,27 @@ async function detectOpenclaw() {
   const location = await findAgent(openClawDriver);
   const running = await getPlatformAdapter().tcpProbe(OPENCLAW_GATEWAY_HOST, OPENCLAW_GATEWAY_PORT, 500);
   if (location.type === "managed") {
+    const pluginInstalled = await isPluginInstalled(location.home).catch(() => false);
     return {
       found: true,
       source: "managed",
       binary: location.binary,
       home: location.home,
       version: null,
-      gatewayRunning: running
+      gatewayRunning: running,
+      pluginInstalled
     };
   }
   if (location.type === "system") {
+    const pluginInstalled = await isPluginInstalled(location.home).catch(() => false);
     return {
       found: true,
       source: "system",
       binary: location.binary,
       home: location.home,
       version: location.version || null,
-      gatewayRunning: running
+      gatewayRunning: running,
+      pluginInstalled
     };
   }
   return {
@@ -2598,7 +3242,8 @@ async function detectOpenclaw() {
     binary: null,
     home: null,
     version: null,
-    gatewayRunning: running
+    gatewayRunning: running,
+    pluginInstalled: null
   };
 }
 async function detectDevices() {
@@ -2669,7 +3314,11 @@ function summarizeExistingInstall(state) {
   lines.push(`BeeOS home : ${state.beeosHome}${state.beeosHomeExists ? "" : " (not created)"}`);
   lines.push(`Identity   : ${state.hasIdentity ? state.fingerprint ?? "(keypair present)" : "not created"}`);
   lines.push(`Binding    : ${state.binding ? `bound \u2192 instance ${state.binding.instance_id}` : "not bound"}`);
-  lines.push(`OpenClaw   : ${state.openclaw.found ? `${state.openclaw.source}${state.openclaw.version ? ` v${state.openclaw.version}` : ""} (gateway ${state.openclaw.gatewayRunning ? "running" : "stopped"})` : "not installed"}`);
+  lines.push(`OpenClaw   : ${state.openclaw.found ? `${state.openclaw.source}${state.openclaw.version ? ` v${state.openclaw.version}` : ""} (gateway ${state.openclaw.gatewayRunning ? "running" : "stopped"}` + // P2-N: surface "installed but plugin missing" so users
+  // who hit a soft-failed launch see the discrepancy on the
+  // first init/doctor pass instead of debugging a generic
+  // "tools not available" later.
+  (state.openclaw.pluginInstalled === false ? ", plugin missing" : "") + `)` : "not installed"}`);
   lines.push(`Devices    : ${state.devices.entries.length === 0 && state.devices.keyedSerials.length === 0 ? "none attached" : `${state.devices.entries.length} attached, ${state.devices.keyedSerials.length} key(s)`}`);
   lines.push(`Supervisor : ${state.supervisor.ipcReachable ? `running (${state.supervisor.targets.length} target(s))` : state.supervisor.targets.length > 0 ? `stopped, ${state.supervisor.targets.length} persisted target(s)` : "not installed"}`);
   return lines;
@@ -2770,6 +3419,7 @@ var init_target_spec = __esm({
     "use strict";
     init_scrcpy_bridge();
     init_vnc_bridge();
+    init_spawn_env2();
   }
 });
 
@@ -2969,13 +3619,23 @@ var init_launchd = __esm({
         await fs.mkdir(path2.dirname(plist), { recursive: true });
         await fs.mkdir(path2.dirname(logFile), { recursive: true });
         const resolvedSpec = await absolutizeCommand(spec);
-        await fs.writeFile(plist, renderPlist(resolvedSpec, label, logFile), {
-          mode: 420
-        });
-        const uid = process.getuid?.();
-        if (uid !== void 0) {
+        const newContent = renderPlist(resolvedSpec, label, logFile);
+        let existingContent = null;
+        try {
+          existingContent = await fs.readFile(plist, "utf-8");
+        } catch {
+        }
+        if (existingContent === newContent) {
+          const existing = await this.status(spec.id);
+          if (existing?.running)
+            return existing;
+        }
+        await fs.writeFile(plist, newContent, { mode: 420 });
+        const uid = process.getuid?.();
+        if (uid !== void 0) {
           try {
             await execFileP("launchctl", ["bootout", `gui/${uid}/${label}`]);
+            await this.waitForBootout(label, uid);
           } catch {
           }
           try {
@@ -2998,6 +3658,24 @@ var init_launchd = __esm({
         const status2 = await this.status(spec.id);
         return status2 ?? fallbackStatus(spec, label, logFile, false);
       }
+      /**
+       * Poll `launchctl print` until the service is no longer registered
+       * with launchd. `bootout` returns as soon as it sends SIGTERM, but
+       * the old process may still be alive (and holding ports) for the
+       * length of its graceful-shutdown window. `print` exits non-zero
+       * once the job is gone, which is the signal we want.
+       */
+      async waitForBootout(label, uid, timeoutMs = 3e4) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+          try {
+            await execFileP("launchctl", ["print", `gui/${uid}/${label}`]);
+            await new Promise((r) => setTimeout(r, 200));
+          } catch {
+            return;
+          }
+        }
+      }
       async uninstall(id) {
         const label = launchdLabel(id);
         const plist = this.plistPath(label);
@@ -3968,6 +4646,7 @@ async function migrateLegacySupervisor(mgr) {
   const supervisorDir = path6.join(home, "supervisor");
   const stateFile = path6.join(supervisorDir, "state.json");
   const flagFile = path6.join(home, MIGRATION_FLAG);
+  const lockFile = path6.join(home, MIGRATION_LOCK);
   if (fsSync4.existsSync(flagFile)) {
     return { ran: false, migrated: 0, errors: [], backupPath: null };
   }
@@ -3978,47 +4657,73 @@ async function migrateLegacySupervisor(mgr) {
     }
     return { ran: false, migrated: 0, errors: [], backupPath: null };
   }
-  const backupPath = `${stateFile}.migration-backup-${Date.now()}`;
-  try {
-    await fs5.copyFile(stateFile, backupPath);
-  } catch {
-  }
-  let parsed;
-  try {
-    const raw = await fs5.readFile(stateFile, "utf-8");
-    parsed = JSON.parse(raw);
-  } catch (e) {
+  if (!await acquireLock(lockFile)) {
     return {
       ran: true,
       migrated: 0,
-      errors: [{ id: "<state.json>", error: `unreadable: ${e}` }],
-      backupPath
+      errors: [{
+        id: "<lock>",
+        error: `migration-in-progress.lock held by another beeos process (${lockFile}); rerun once it exits`
+      }],
+      backupPath: null
     };
   }
-  const targets = parsed.targets ?? [];
-  const errors = [];
-  let migrated = 0;
-  for (const t of targets) {
-    const canonicalId = safeId(t.id);
+  try {
+    const backupPath = `${stateFile}.migration-backup-${Date.now()}`;
     try {
-      const spec = {
-        id: canonicalId,
-        kind: t.kind,
-        command: t.command,
-        args: t.args ?? [],
-        env: t.env,
-        cwd: t.cwd,
-        restart: t.restart ?? "on-failure",
-        label: t.label
-      };
-      await mgr.install(spec);
-      migrated++;
+      await fs5.copyFile(stateFile, backupPath);
+    } catch {
+    }
+    let parsed;
+    try {
+      const raw = await fs5.readFile(stateFile, "utf-8");
+      parsed = JSON.parse(raw);
     } catch (e) {
-      errors.push({ id: canonicalId, error: e instanceof Error ? e.message : String(e) });
+      return {
+        ran: true,
+        migrated: 0,
+        errors: [{ id: "<state.json>", error: `unreadable: ${e}` }],
+        backupPath
+      };
     }
-  }
-  await stopLegacyDaemon();
-  if (errors.length === 0) {
+    const targets = parsed.targets ?? [];
+    const errors = [];
+    const installed = [];
+    for (const t of targets) {
+      const canonicalId = safeId(t.id);
+      try {
+        const spec = {
+          id: canonicalId,
+          kind: t.kind,
+          command: t.command,
+          args: t.args ?? [],
+          env: t.env,
+          cwd: t.cwd,
+          restart: t.restart ?? "on-failure",
+          label: t.label
+        };
+        await mgr.install(spec);
+        installed.push(canonicalId);
+      } catch (e) {
+        errors.push({ id: canonicalId, error: e instanceof Error ? e.message : String(e) });
+        break;
+      }
+    }
+    if (errors.length > 0) {
+      for (const id of installed) {
+        try {
+          await mgr.uninstall(id);
+        } catch {
+        }
+      }
+      return {
+        ran: true,
+        migrated: 0,
+        errors,
+        backupPath
+      };
+    }
+    await stopLegacyDaemon();
     try {
       await fs5.writeFile(flagFile, (/* @__PURE__ */ new Date()).toISOString());
     } catch {
@@ -4027,8 +4732,56 @@ async function migrateLegacySupervisor(mgr) {
       await fs5.rm(supervisorDir, { recursive: true, force: true });
     } catch {
     }
+    return { ran: true, migrated: installed.length, errors: [], backupPath };
+  } finally {
+    try {
+      await fs5.unlink(lockFile);
+    } catch {
+    }
+  }
+}
+async function acquireLock(lockFile) {
+  try {
+    const handle = await fs5.open(lockFile, "wx");
+    try {
+      await handle.write(`${process.pid}
+${(/* @__PURE__ */ new Date()).toISOString()}
+`);
+    } finally {
+      await handle.close();
+    }
+    return true;
+  } catch (e) {
+    if (e.code !== "EEXIST") {
+      return false;
+    }
+  }
+  let stale = false;
+  try {
+    const stat = await fs5.stat(lockFile);
+    stale = Date.now() - stat.mtimeMs > STALE_LOCK_AGE_MS;
+  } catch {
+    stale = true;
+  }
+  if (!stale)
+    return false;
+  try {
+    await fs5.unlink(lockFile);
+  } catch {
+  }
+  try {
+    const handle = await fs5.open(lockFile, "wx");
+    try {
+      await handle.write(`${process.pid}
+${(/* @__PURE__ */ new Date()).toISOString()}
+`);
+    } finally {
+      await handle.close();
+    }
+    return true;
+  } catch {
+    return false;
   }
-  return { ran: true, migrated, errors, backupPath };
 }
 async function stopLegacyDaemon() {
   if (process.platform === "darwin") {
@@ -4063,7 +4816,7 @@ async function stopLegacyDaemon() {
     }
   }
 }
-var execFileP5, LEGACY_LABEL, LEGACY_SYSTEMD_UNIT, MIGRATION_FLAG;
+var execFileP5, LEGACY_LABEL, LEGACY_SYSTEMD_UNIT, MIGRATION_FLAG, MIGRATION_LOCK, STALE_LOCK_AGE_MS;
 var init_migrate = __esm({
   "../core/dist/services/migrate.js"() {
     "use strict";
@@ -4073,11 +4826,91 @@ var init_migrate = __esm({
     LEGACY_LABEL = "ai.beeos.supervisor";
     LEGACY_SYSTEMD_UNIT = "beeos-supervisor.service";
     MIGRATION_FLAG = "migrated-to-services.flag";
+    MIGRATION_LOCK = "migration-in-progress.lock";
+    STALE_LOCK_AGE_MS = 5 * 60 * 1e3;
+  }
+});
+
+// ../core/dist/services/tail-logs.js
+import fs6 from "fs/promises";
+async function readLastLines(file, n) {
+  let text = "";
+  let size = 0;
+  try {
+    text = await fs6.readFile(file, "utf8");
+    const stat = await fs6.stat(file);
+    size = stat.size;
+  } catch (e) {
+    if (e.code !== "ENOENT")
+      throw e;
+  }
+  if (text === "")
+    return { text: "", size };
+  const trimmed = text.endsWith("\n") ? text.slice(0, -1) : text;
+  const lines = trimmed.split("\n");
+  const sliced = lines.slice(Math.max(0, lines.length - n));
+  return { text: sliced.join("\n") + "\n", size };
+}
+async function tailLogFile(opts) {
+  const write = opts.write ?? ((s) => process.stdout.write(s));
+  const prefix = opts.prefix ?? "";
+  const initial = opts.initialLines ?? 50;
+  const pollMs = opts.pollIntervalMs ?? 200;
+  const writePrefixed = (chunk) => {
+    if (chunk.length === 0)
+      return;
+    if (prefix === "") {
+      write(chunk);
+      return;
+    }
+    const endsWithNewline = chunk.endsWith("\n");
+    const lines = (endsWithNewline ? chunk.slice(0, -1) : chunk).split("\n");
+    const out = lines.map((l) => `${prefix}${l}`).join("\n");
+    write(endsWithNewline ? out + "\n" : out);
+  };
+  const initialRead = await readLastLines(opts.logFile, initial);
+  writePrefixed(initialRead.text);
+  if (!opts.follow)
+    return;
+  let lastSize = initialRead.size;
+  while (!opts.signal?.aborted) {
+    await new Promise((resolve) => setTimeout(resolve, pollMs));
+    if (opts.signal?.aborted)
+      break;
+    let stat;
+    try {
+      stat = await fs6.stat(opts.logFile);
+    } catch (e) {
+      if (e.code === "ENOENT") {
+        lastSize = 0;
+        continue;
+      }
+      throw e;
+    }
+    if (stat.size === lastSize)
+      continue;
+    if (stat.size < lastSize) {
+      lastSize = 0;
+    }
+    const handle = await fs6.open(opts.logFile, "r");
+    try {
+      const buf = Buffer.alloc(stat.size - lastSize);
+      const { bytesRead } = await handle.read(buf, 0, buf.length, lastSize);
+      writePrefixed(buf.subarray(0, bytesRead).toString("utf8"));
+      lastSize = lastSize + bytesRead;
+    } finally {
+      await handle.close();
+    }
+  }
+}
+var init_tail_logs = __esm({
+  "../core/dist/services/tail-logs.js"() {
+    "use strict";
   }
 });
 
 // ../core/dist/cli-version.js
-import fs6 from "fs";
+import fs7 from "fs";
 import path7 from "path";
 import { fileURLToPath } from "url";
 function getCliVersion(moduleUrl, distTag) {
@@ -4105,8 +4938,8 @@ function readBakedDistTag() {
     let dir = here;
     for (let i = 0; i < 6; i++) {
       const candidate = path7.join(dir, "package.json");
-      if (fs6.existsSync(candidate)) {
-        const raw = fs6.readFileSync(candidate, "utf-8");
+      if (fs7.existsSync(candidate)) {
+        const raw = fs7.readFileSync(candidate, "utf-8");
         const pkg = JSON.parse(raw);
         if ((pkg.name === "@beeos-ai/cli" || pkg.name === "beeos") && pkg.beeos && typeof pkg.beeos.distTag === "string") {
           return pkg.beeos.distTag;
@@ -4131,8 +4964,8 @@ function readVersionFromModuleUrl(moduleUrl) {
   for (let i = 0; i < 6; i++) {
     const candidate = path7.join(here, "package.json");
     try {
-      if (fs6.existsSync(candidate)) {
-        const raw = fs6.readFileSync(candidate, "utf-8");
+      if (fs7.existsSync(candidate)) {
+        const raw = fs7.readFileSync(candidate, "utf-8");
         const pkg = JSON.parse(raw);
         if (typeof pkg.version === "string" && (pkg.name === "@beeos-ai/cli" || pkg.name === "beeos")) {
           return pkg.version;
@@ -4162,17 +4995,21 @@ var init_dist = __esm({
     init_types();
     init_paths();
     init_toml();
+    init_spawn_env();
     init_binding();
     init_gateway_token();
+    init_state();
     init_keypair();
     init_client();
     init_orchestrator();
     init_process();
+    init_errors();
     init_device_setup();
     init_adb_setup();
     init_device();
     init_scrcpy_bridge();
     init_vnc_bridge();
+    init_spawn_env2();
     init_agent_config();
     init_driver();
     init_detector();
@@ -4187,7 +5024,9 @@ var init_dist = __esm({
     init_factory();
     init_ids();
     init_migrate();
+    init_tail_logs();
     init_cli_version();
+    init_upgrade();
   }
 });
 
@@ -4266,6 +5105,34 @@ async function notifyFleetReloadBestEffort(baseUrl = FLEET_STATUS_BASE_URL) {
     return "unknown";
   }
 }
+async function notifyFleetRestartDeviceBestEffort(serial, baseUrl = FLEET_STATUS_BASE_URL) {
+  try {
+    const res = await fetch(
+      `${baseUrl}/fleet/devices/${encodeURIComponent(serial)}/restart`,
+      {
+        method: "POST",
+        signal: AbortSignal.timeout(FLEET_NOTIFY_TIMEOUT_MS)
+      }
+    );
+    return res.ok ? "ok" : "unknown";
+  } catch (e) {
+    if (isConnectionRefused(e)) return "not_running";
+    return "unknown";
+  }
+}
+async function notifyFleetShutdownBestEffort(baseUrl = FLEET_STATUS_BASE_URL) {
+  try {
+    const res = await fetch(`${baseUrl}/fleet/shutdown`, {
+      method: "POST",
+      signal: AbortSignal.timeout(FLEET_SHUTDOWN_TIMEOUT_MS)
+    });
+    if (res.status === 501) return "unknown";
+    return res.ok ? "ok" : "unknown";
+  } catch (e) {
+    if (isConnectionRefused(e)) return "not_running";
+    return "unknown";
+  }
+}
 function isConnectionRefused(e) {
   const code = extractErrorCode(e);
   return code === "ECONNREFUSED" || code === "ECONNRESET";
@@ -4290,12 +5157,13 @@ function printFleetNotRunningHint() {
   console.log("  device-agent fleet start     # foreground (debug-friendly)");
   console.log("");
 }
-var FLEET_STATUS_BASE_URL, FLEET_NOTIFY_TIMEOUT_MS;
+var FLEET_STATUS_BASE_URL, FLEET_NOTIFY_TIMEOUT_MS, FLEET_SHUTDOWN_TIMEOUT_MS;
 var init_fleet_notify = __esm({
   "src/commands/device/fleet-notify.ts"() {
     "use strict";
     FLEET_STATUS_BASE_URL = "http://127.0.0.1:7950";
     FLEET_NOTIFY_TIMEOUT_MS = 1e3;
+    FLEET_SHUTDOWN_TIMEOUT_MS = 5e3;
   }
 });
 
@@ -4355,7 +5223,7 @@ async function removeTargetsForSerial(mgr, serial) {
   } catch {
   }
 }
-var init_state = __esm({
+var init_state2 = __esm({
   "src/commands/device/state.ts"() {
     "use strict";
     init_dist();
@@ -4365,6 +5233,37 @@ var init_state = __esm({
 // src/commands/device/attach.ts
 import { spawn as spawn2 } from "child_process";
 import readline from "readline";
+function resolvePerDeviceAgentGatewayUrl(cfg, override) {
+  if (override === void 0) return resolveAgentGatewayUrl(cfg);
+  const trimmed = override.trim();
+  if (trimmed === "") {
+    throw new BeeosError({
+      code: "invalid_argument",
+      message: "--agent-gateway-url cannot be empty.",
+      hint: "Pass an http(s) URL, e.g. --agent-gateway-url https://agent-gw.staging.beeos.ai"
+    });
+  }
+  let parsed;
+  try {
+    parsed = new URL(trimmed);
+  } catch {
+    throw new BeeosError({
+      code: "invalid_argument",
+      message: `--agent-gateway-url is not a valid URL: ${trimmed}`,
+      hint: "Pass an http(s) URL, e.g. --agent-gateway-url https://agent-gw.staging.beeos.ai",
+      details: { value: trimmed }
+    });
+  }
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new BeeosError({
+      code: "invalid_argument",
+      message: `--agent-gateway-url must use http(s); got ${parsed.protocol}`,
+      hint: "Pass an http(s) URL, e.g. --agent-gateway-url https://agent-gw.staging.beeos.ai",
+      details: { value: trimmed, protocol: parsed.protocol }
+    });
+  }
+  return trimmed;
+}
 async function attach(options) {
   const cfg = await loadOrCreateConfig();
   const reporter = new CliReporter();
@@ -4388,17 +5287,19 @@ async function attach(options) {
     return;
   }
   const mgr = await getServiceManager();
+  let prevInstanceId = null;
   await withDeviceLock(async () => {
     const state = await loadDeviceState();
     const existingIdx = state.devices.findIndex((d) => d.serial === serial);
     if (existingIdx >= 0) {
+      prevInstanceId = state.devices[existingIdx].instance_id ?? null;
       await removeTargetsForSerial(mgr, serial);
       state.devices.splice(existingIdx, 1);
     }
     const httpPort = nextHttpPort(state, cfg.device.http_port);
     const keyFile = deviceRuntime.deviceKeyPath(serial);
-    const agentGatewayUrl = resolveAgentGatewayUrl(cfg);
-    await persistAgentConfigBestEffort({
+    const agentGatewayUrl = resolvePerDeviceAgentGatewayUrl(cfg, options.agentGatewayUrl);
+    const persistedAgentConfig = await persistAgentConfigBestEffort({
       agentGatewayUrl,
       keyFile,
       instanceId,
@@ -4413,8 +5314,12 @@ async function attach(options) {
         withVideo,
         vncHost: options.vncHost,
         vncPort: options.vncPort,
-        vncPassword: options.vncPassword
+        vncPassword: options.vncPassword,
+        agentGatewayUrl
       });
+      const fp = fingerprintFromB64(pubkeyB64);
+      const boundAt = Math.floor(Date.now() / 1e3);
+      const backend = options.vncHost ? void 0 : "adb";
       state.devices.push({
         serial,
         name,
@@ -4428,11 +5333,37 @@ async function attach(options) {
         // path through fleet → mcp). When self-attach for
         // macOS/Linux/Windows lands, this field will be set
         // accordingly (`macos`/`linux`/`windows`).
-        backend: options.vncHost ? void 0 : "adb",
+        backend,
         vnc_host: options.vncHost,
-        vnc_port: options.vncPort
+        vnc_port: options.vncPort,
+        // P0-D: pin the resolved Agent Gateway URL on the entry so
+        // the fleet supervisor reuses *this* URL on every restart
+        // instead of re-resolving from the (possibly drifting) config
+        // — and so multi-region staging users can attach devices to
+        // different gateways without splitting fleets.
+        agent_gateway_url: agentGatewayUrl
       });
       await saveDeviceState(state);
+      const stateEntry = {
+        kind: "device",
+        instance_id: instanceId,
+        bound_at: boundAt,
+        fingerprint: fp,
+        agent_gateway_url: agentGatewayUrl,
+        serial,
+        name,
+        key_file: keyFile,
+        http_port: httpPort,
+        video_mode: bridgeInfo.mode,
+        ...backend ? { backend } : {},
+        ...options.vncHost ? { vnc_host: options.vncHost } : {},
+        ...options.vncPort ? { vnc_port: options.vncPort } : {},
+        ...persistedAgentConfig ? { agent_config: persistedAgentConfig.payload } : {}
+      };
+      await mutateStateBestEffort(
+        (s) => upsertDeviceAgent(s, withCarriedForwardAgentConfig(s, stateEntry)),
+        { authority: "devices.json", subject: serial }
+      );
       console.log(`Attached device ${serial} (${name}) \u2014 instance ${instanceId}`);
       console.log(`  local http: :${httpPort} (if enabled)`);
       console.log(`  logs: device-agent fleet logs ${serial}`);
@@ -4448,6 +5379,14 @@ async function attach(options) {
       throw e;
     }
   });
+  const isRebind = prevInstanceId !== null && prevInstanceId !== instanceId;
+  if (isRebind) {
+    const outcome = await notifyFleetRestartDeviceBestEffort(serial);
+    if (outcome === "not_running") {
+      await maybeNotifyFleetWithHint(cfg);
+    }
+    return;
+  }
   await maybeNotifyFleetWithHint(cfg);
 }
 async function attachAll(cfg, reporter, withVideo, options) {
@@ -4459,9 +5398,13 @@ async function attachAll(cfg, reporter, withVideo, options) {
   console.log(`Discovered ${devices.length} device(s) via adb.`);
   await deviceRuntime.ensureAgent(reporter);
   reporter.stop();
-  const agentGatewayUrl = resolveAgentGatewayUrl(cfg);
+  const agentGatewayUrl = resolvePerDeviceAgentGatewayUrl(cfg, options.agentGatewayUrl);
   const mgr = await getServiceManager();
   const preState = await loadDeviceState();
+  const prevInstanceIdBySerial = /* @__PURE__ */ new Map();
+  for (const d of preState.devices) {
+    if (d.instance_id) prevInstanceIdBySerial.set(d.serial, d.instance_id);
+  }
   const simulatedEntries = preState.devices.map((d) => ({ ...d }));
   function reserveHttpPort(serial) {
     const port = nextHttpPort({ devices: simulatedEntries }, cfg.device.http_port);
@@ -4488,7 +5431,8 @@ async function attachAll(cfg, reporter, withVideo, options) {
         serial: device.serial,
         instanceId,
         keyFile: deviceRuntime.deviceKeyPath(device.serial),
-        httpPort
+        httpPort,
+        fingerprint: fingerprintFromB64(pubkeyB64)
       });
     } catch (e) {
       console.error(`  Failed to bind ${device.serial}: ${e}`);
@@ -4511,18 +5455,62 @@ async function attachAll(cfg, reporter, withVideo, options) {
       })
     )
   );
+  const reboundSerials = [];
   await withDeviceLock(async () => {
     const state = await loadDeviceState();
     const { committed, failures } = commitAttachResults(state, commits);
     for (const f of failures) console.error(`Failed to attach ${f.serial}: ${f.error}`);
+    for (const c of committed) {
+      const prev = prevInstanceIdBySerial.get(c.serial);
+      if (prev && prev !== c.entry.instance_id) reboundSerials.push(c.serial);
+    }
     for (const c of committed) {
       console.log(
         `Attached device ${c.serial} \u2014 instance ${c.entry.instance_id}` + (c.videoMode !== "none" ? ` (video: ${c.videoMode})` : "")
       );
     }
     await saveDeviceState(state);
+    for (const c of committed) {
+      const e = c.entry;
+      const mirror = commits.find(
+        (x) => x.ok && x.serial === c.serial
+      ).stateMirror;
+      const stateEntry = {
+        kind: "device",
+        instance_id: e.instance_id ?? "",
+        bound_at: mirror.boundAt,
+        fingerprint: mirror.fingerprint,
+        agent_gateway_url: e.agent_gateway_url && e.agent_gateway_url !== "" ? e.agent_gateway_url : mirror.agentGatewayUrl,
+        serial: e.serial,
+        name: e.name,
+        key_file: e.key_file,
+        http_port: e.http_port,
+        ...e.video_mode ? { video_mode: e.video_mode } : {},
+        ...e.backend ? { backend: e.backend } : {},
+        ...e.vnc_host ? { vnc_host: e.vnc_host } : {},
+        ...e.vnc_port ? { vnc_port: e.vnc_port } : {},
+        ...mirror.agentConfig ? { agent_config: mirror.agentConfig } : {}
+      };
+      await mutateStateBestEffort(
+        (s) => upsertDeviceAgent(s, withCarriedForwardAgentConfig(s, stateEntry)),
+        { authority: "devices.json", subject: e.serial }
+      );
+    }
     console.log(`Attached ${committed.length} device(s); supervision via device-agent fleet.`);
   });
+  if (reboundSerials.length > 0) {
+    let anyNotRunning = false;
+    for (const serial of reboundSerials) {
+      const outcome = await notifyFleetRestartDeviceBestEffort(serial);
+      if (outcome === "not_running") anyNotRunning = true;
+    }
+    if (anyNotRunning) {
+      await maybeNotifyFleetWithHint(cfg);
+    } else if (reboundSerials.length < commits.filter((c) => c.ok).length) {
+      await maybeNotifyFleetWithHint(cfg);
+    }
+    return;
+  }
   await maybeNotifyFleetWithHint(cfg);
 }
 function commitAttachResults(state, commits) {
@@ -4542,10 +5530,10 @@ function commitAttachResults(state, commits) {
 }
 async function runAttachStage2(params) {
   const { bind, cfg, mgr, reporter, agentGatewayUrl, withVideo, options } = params;
-  const { serial, instanceId, keyFile, httpPort } = bind;
+  const { serial, instanceId, keyFile, httpPort, fingerprint: fp } = bind;
   try {
     await removeTargetsForSerial(mgr, serial);
-    await persistAgentConfigBestEffort({
+    const persistedAgentConfig = await persistAgentConfigBestEffort({
       agentGatewayUrl,
       keyFile,
       instanceId,
@@ -4559,7 +5547,8 @@ async function runAttachStage2(params) {
       withVideo,
       vncHost: options.vncHost,
       vncPort: options.vncPort,
-      vncPassword: options.vncPassword
+      vncPassword: options.vncPassword,
+      agentGatewayUrl
     });
     const entry = {
       serial,
@@ -4570,9 +5559,25 @@ async function runAttachStage2(params) {
       video_mode: bridgeInfo.mode,
       backend: options.vncHost ? void 0 : "adb",
       vnc_host: options.vncHost,
-      vnc_port: options.vncPort
+      vnc_port: options.vncPort,
+      // P0-D: see attach() above — every new entry self-pins to the
+      // resolved Agent Gateway URL so the fleet supervisor (and any
+      // future per-device override flows) honour the binding's
+      // origin region.
+      agent_gateway_url: agentGatewayUrl
+    };
+    return {
+      ok: true,
+      serial,
+      entry,
+      videoMode: bridgeInfo.mode,
+      stateMirror: {
+        agentGatewayUrl,
+        fingerprint: fp,
+        boundAt: Math.floor(Date.now() / 1e3),
+        agentConfig: persistedAgentConfig?.payload ?? null
+      }
     };
-    return { ok: true, serial, entry, videoMode: bridgeInfo.mode };
   } catch (e) {
     await rollbackDeviceBind(cfg.platform.api_url, instanceId);
     return { ok: false, serial, error: e };
@@ -4684,7 +5689,7 @@ async function runDeviceAgentFleetEnable(cfg) {
 }
 async function registerVideoBridge(_mgr, reporter, params) {
   if (!params.withVideo) return { mode: "none" };
-  const agentGatewayUrl = resolveAgentGatewayUrl(params.cfg);
+  const agentGatewayUrl = params.agentGatewayUrl ?? resolveAgentGatewayUrl(params.cfg);
   if (params.vncHost) {
     const binary2 = await ensureBridgeBinaryDegraded(
       vncBridgeRuntime.ensureInstalled.bind(vncBridgeRuntime),
@@ -4737,23 +5742,80 @@ async function ensureBridgeBinaryDegraded(fn, reporter, label) {
     return null;
   }
 }
+function withCarriedForwardAgentConfig(state, entry) {
+  if (entry.agent_config) return entry;
+  const previous = state.agents.find(
+    (a) => a.kind === "device" && a.serial === entry.serial
+  );
+  if (!previous?.agent_config) return entry;
+  return { ...entry, agent_config: previous.agent_config };
+}
 async function ensureAdbAvailable(reporter) {
   const existing = await findAdb();
   if (existing) return;
   if (process.env.BEEOS_SKIP_ADB_INSTALL === "1") {
-    throw new Error(
-      "adb not found on PATH and BEEOS_SKIP_ADB_INSTALL=1 is set.\nInstall Android platform-tools manually and re-run, or unset the env var."
-    );
+    throw new BeeosError({
+      code: "adb_install_skipped",
+      message: "adb not found on PATH and BEEOS_SKIP_ADB_INSTALL=1 is set.",
+      hint: "Install Android platform-tools manually and re-run, or unset BEEOS_SKIP_ADB_INSTALL."
+    });
+  }
+  const decision = detectAdbLicenseDecision();
+  if (decision === "rejected") {
+    throw new BeeosError({
+      code: "adb_install_rejected",
+      message: "BEEOS_REJECT_ADB_LICENSE=1 is set \u2014 adb auto-install refused.",
+      hint: `Pre-install Android platform-tools and point $BEEOS_ADB_BIN at it, or unset BEEOS_REJECT_ADB_LICENSE and review the license at ${ADB_LICENSE_URL}.`,
+      details: { licenseUrl: ADB_LICENSE_URL }
+    });
+  }
+  if (decision === "unknown") {
+    const proceed = await confirmAdbLicensePrompt();
+    if (!proceed) {
+      throw new BeeosError({
+        code: "adb_install_declined",
+        message: "adb auto-install declined at the license prompt.",
+        hint: "Pre-install Android platform-tools manually and re-run, or set BEEOS_ACCEPT_ADB_LICENSE=1 in your environment."
+      });
+    }
   }
   console.log("adb not found \u2014 downloading Android platform-tools (one-time, ~10MB)...");
   try {
     await ensureAdb(reporter, { autoInstall: true });
   } catch (e) {
-    throw new Error(
-      "Failed to install adb automatically: " + String(e) + "\nWorkarounds:\n  \u2022 macOS: brew install android-platform-tools\n  \u2022 Linux: apt install android-tools-adb (or equivalent)\n  \u2022 Windows: install Android SDK Platform-Tools from https://developer.android.com/tools/releases/platform-tools\n  \u2022 Or point $BEEOS_ADB_BIN at an existing adb binary.",
-      { cause: e }
+    throw new BeeosError({
+      code: "adb_install_failed",
+      message: `Failed to install adb automatically: ${String(e)}`,
+      hint: "Workarounds:\n  \u2022 macOS: brew install android-platform-tools\n  \u2022 Linux: apt install android-tools-adb (or equivalent)\n  \u2022 Windows: install Android SDK Platform-Tools from https://developer.android.com/tools/releases/platform-tools\n  \u2022 Or point $BEEOS_ADB_BIN at an existing adb binary.",
+      cause: e
+    });
+  }
+}
+async function confirmAdbLicensePrompt() {
+  const isTty = Boolean(process.stdout.isTTY);
+  if (!isTty) {
+    console.log(
+      `  Android platform-tools license: ${ADB_LICENSE_URL}
+  Non-interactive shell \u2014 auto-accepting. Set BEEOS_ACCEPT_ADB_LICENSE=1
+  in your environment to silence this banner.`
     );
+    return true;
   }
+  console.log(
+    `
+Android SDK Platform-Tools (adb) is licensed under the Android SDK License Agreement:
+  ${ADB_LICENSE_URL}
+Set BEEOS_ACCEPT_ADB_LICENSE=1 in your environment to skip this prompt next time.
+`
+  );
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ans = await new Promise((resolve) => {
+    rl.question("Agree to the Android SDK license and download platform-tools? [Y/n]: ", (a) => {
+      rl.close();
+      resolve(a);
+    });
+  });
+  return /^(y(es)?|)$/i.test(ans.trim());
 }
 var init_attach = __esm({
   "src/commands/device/attach.ts"() {
@@ -4762,7 +5824,7 @@ var init_attach = __esm({
     init_progress2();
     init_fallback_banner();
     init_fleet_notify();
-    init_state();
+    init_state2();
   }
 });
 
@@ -4814,7 +5876,7 @@ var init_detach = __esm({
     "use strict";
     init_dist();
     init_fleet_notify();
-    init_state();
+    init_state2();
   }
 });
 
@@ -4856,7 +5918,7 @@ var init_list = __esm({
   "src/commands/device/list.ts"() {
     "use strict";
     init_dist();
-    init_state();
+    init_state2();
   }
 });
 
@@ -4892,14 +5954,49 @@ var init_exec = __esm({
   "src/commands/device/exec.ts"() {
     "use strict";
     init_dist();
-    init_state();
+    init_state2();
   }
 });
 
 // src/commands/device/upgrade.ts
 async function upgrade(options = {}) {
   const reporter = new CliReporter();
-  await deviceRuntime.upgradeAgent(reporter);
+  const outcome = await upgradeBeeosSuite({
+    packages: [NPM_PKGS.DEVICE_AGENT, NPM_PKGS.DEVICE_MCP_SERVER],
+    progress: reporter
+  });
+  reporter.stop();
+  if (outcome.anyFailed) {
+    const failed = outcome.packages.find((p) => p.failed);
+    console.error(
+      `device-agent upgrade had errors: ${failed?.failed ?? "unknown"}
+Manual fix:
+  npm i -g @beeos-ai/device-agent @beeos-ai/device-mcp-server`
+    );
+  }
+  for (const pkg of outcome.packages) {
+    if (pkg.changed) {
+      console.log(`  ${pkg.pkg}: ${pkg.before ?? "(none)"} \u2192 ${pkg.after}`);
+    } else if (!pkg.failed) {
+      console.log(`  ${pkg.pkg}: ${pkg.after ?? "(absent)"} (already current)`);
+    }
+  }
+  if (outcome.anyChanged) {
+    const reloadOutcome = await notifyFleetShutdownBestEffort();
+    switch (reloadOutcome) {
+      case "ok":
+        console.log("  Fleet asked to restart \u2014 launchd will bring it up with the new code.");
+        break;
+      case "not_running":
+        console.log("  Fleet is not running \u2014 nothing to restart.");
+        break;
+      case "unknown":
+        console.log(
+          "  Fleet restart could not be confirmed; if you see stale behaviour run\n    launchctl kickstart -k gui/$(id -u)/ai.beeos.device-fleet  # macOS\n  or stop & start the fleet manually."
+        );
+        break;
+    }
+  }
   if (options.bridges !== false) {
     try {
       await scrcpyBridgeRuntime.upgrade(reporter);
@@ -4913,11 +6010,12 @@ async function upgrade(options = {}) {
     }
   }
 }
-var init_upgrade = __esm({
+var init_upgrade2 = __esm({
   "src/commands/device/upgrade.ts"() {
     "use strict";
     init_dist();
     init_progress2();
+    init_fleet_notify();
   }
 });
 
@@ -4931,7 +6029,6 @@ async function refreshConfig(options = {}) {
     console.log("No matching devices in ~/.beeos/devices.json \u2014 nothing to refresh.");
     return;
   }
-  const mgr = await getServiceManager();
   let okCount = 0;
   let failCount = 0;
   for (const entry of targets) {
@@ -4949,27 +6046,44 @@ async function refreshConfig(options = {}) {
       failCount++;
       continue;
     }
-    const file = await persistAgentConfigBestEffort({
+    const result = await persistAgentConfigBestEffort({
       agentGatewayUrl,
       keyFile: entry.key_file,
       instanceId: entry.instance_id,
       reporter
     });
-    if (!file) {
+    if (!result) {
       console.error(
         `  Refresh failed for ${entry.serial} (see warning above) \u2014 config file left untouched.`
       );
       failCount++;
       continue;
     }
-    console.log(`  Wrote ${file}`);
-    try {
-      await mgr.restart(deviceAgentTargetId(entry.serial));
+    console.log(`  Wrote ${result.filePath}`);
+    const instanceId = entry.instance_id;
+    const payload = result.payload;
+    await mutateStateBestEffort(
+      (state) => {
+        const idx = state.agents.findIndex(
+          (a) => a.kind === "device" && a.instance_id === instanceId
+        );
+        if (idx < 0) return null;
+        const next = { ...state.agents[idx], agent_config: payload };
+        const agents = state.agents.slice();
+        agents[idx] = next;
+        return { ...state, agents };
+      },
+      { authority: "Per-instance config.json", subject: instanceId }
+    );
+    const outcome = await notifyFleetRestartDeviceBestEffort(entry.serial);
+    if (outcome === "ok") {
       console.log(`  Restarted device-agent for ${entry.serial}`);
-    } catch (e) {
-      console.error(
-        `  Service restart skipped for ${entry.serial}: ${e.message}`
+    } else if (outcome === "not_running") {
+      console.log(
+        `  fleet not running for ${entry.serial} \u2014 config will load on next start`
       );
+    } else {
+      console.error(`  fleet restart for ${entry.serial} returned an error`);
     }
     okCount++;
   }
@@ -5000,7 +6114,8 @@ var init_refresh_config = __esm({
     "use strict";
     init_dist();
     init_progress2();
-    init_state();
+    init_fleet_notify();
+    init_state2();
   }
 });
 
@@ -5022,9 +6137,9 @@ var init_device2 = __esm({
     init_detach();
     init_list();
     init_exec();
-    init_upgrade();
+    init_upgrade2();
     init_refresh_config();
-    init_state();
+    init_state2();
   }
 });
 
@@ -5037,7 +6152,7 @@ import {
   execFile as execFile6,
   spawn as nodeSpawn
 } from "child_process";
-import fs7 from "fs";
+import fs8 from "fs";
 import fsp from "fs/promises";
 import net from "net";
 import os5 from "os";
@@ -5144,11 +6259,11 @@ var NodePlatformAdapter = class {
     let stderrFd;
     if (options?.stdoutFile) {
       await fsp.mkdir(path8.dirname(options.stdoutFile), { recursive: true });
-      stdoutFd = fs7.openSync(options.stdoutFile, "a");
+      stdoutFd = fs8.openSync(options.stdoutFile, "a");
     }
     if (options?.stderrFile) {
       await fsp.mkdir(path8.dirname(options.stderrFile), { recursive: true });
-      stderrFd = options.stderrFile === options.stdoutFile ? stdoutFd : fs7.openSync(options.stderrFile, "a");
+      stderrFd = options.stderrFile === options.stdoutFile ? stdoutFd : fs8.openSync(options.stderrFile, "a");
     }
     const child = nodeSpawn(cmd, args, {
       cwd: options?.cwd,
@@ -5165,8 +6280,8 @@ var NodePlatformAdapter = class {
     if (options?.detached) {
       child.unref();
     }
-    if (stdoutFd != null) fs7.closeSync(stdoutFd);
-    if (stderrFd != null && stderrFd !== stdoutFd) fs7.closeSync(stderrFd);
+    if (stdoutFd != null) fs8.closeSync(stdoutFd);
+    if (stderrFd != null && stderrFd !== stdoutFd) fs8.closeSync(stderrFd);
     const pid = child.pid;
     if (pid == null) {
       throw new Error(`Failed to spawn process: ${cmd} ${args.join(" ")}`);
@@ -5248,6 +6363,17 @@ init_dist();
 init_progress2();
 init_fallback_banner();
 import os6 from "os";
+
+// src/json-envelope.ts
+init_dist();
+function jsonOk(data) {
+  return { ok: true, data };
+}
+function emitJsonEnvelope(env) {
+  console.log(JSON.stringify(env, null, 2));
+}
+
+// src/commands/start.ts
 async function run(agentFramework, options) {
   const p = getPlatformAdapter();
   await ensureDirs();
@@ -5256,9 +6382,12 @@ async function run(agentFramework, options) {
   const descriptor = frameworkById(agentFramework);
   if (!descriptor || descriptor.status !== "available") {
     const avail = availableFrameworks().map((f) => f.id).join(", ");
-    throw new Error(
-      `Agent framework '${agentFramework}' is not available. Available: ${avail}.`
-    );
+    throw new BeeosError({
+      code: "framework_unavailable",
+      message: `Agent framework '${agentFramework}' is not available.`,
+      hint: `Available frameworks: ${avail}.`,
+      details: { requested: agentFramework, available: avail.split(/,\s*/) }
+    });
   }
   const driver = descriptor.driver;
   const identity = await loadOrCreateIdentity();
@@ -5266,12 +6395,17 @@ async function run(agentFramework, options) {
   const pubkey = publicKeyB64(identity);
   const keyFile = p.joinPath(beeoHome(), "identity", "keypair.json");
   const agentGatewayUrl = resolveAgentGatewayUrl(cfg);
-  const probe = await identifyGateway({ expectedFingerprint: fp });
-  if (!options.force && (probe.state === "foreign" || probe.state === "unknown")) {
-    const detail = probe.state === "foreign" ? `a different beeos-claw gateway (fingerprint ${probe.fingerprint.slice(0, 16)}\u2026, plugin ${probe.pluginVersion || "?"})` : `an unrecognised process (${probe.reason})`;
-    throw new Error(
-      `OpenClaw gateway port is already in use by ${detail}. Refusing to install over it \u2014 this would make both agents fight for the same port and leak your fingerprint to the other process. Run \`beeos doctor\` to diagnose, or re-run with \`--force\` if you are certain (will terminate the existing listener).`
-    );
+  if (hasPreflightConflictCheck(driver) && !options.force) {
+    const report = await driver.preflightConflictCheck({ fingerprint: fp });
+    if (report.state === "foreign" || report.state === "unknown") {
+      const detail = report.state === "foreign" ? report.detail : `an unrecognised process (${report.reason})`;
+      throw new BeeosError({
+        code: "gateway_port_conflict",
+        message: `${driver.displayName} port is already in use by ${detail}.`,
+        hint: `Refusing to install over it \u2014 clobbering would make both agents fight for the same port and leak your fingerprint to the foreign process. Run \`beeos doctor\` to diagnose, or re-run with \`--force\` to terminate the existing listener.`,
+        details: { driver: driver.id, state: report.state }
+      });
+    }
   }
   reporter.onStatus(`Preparing ${driver.displayName}`);
   const ctx = {
@@ -5281,29 +6415,11 @@ async function run(agentFramework, options) {
     locationPreference: "auto",
     versionOverride: options.version
   };
-  const spec = await driver.launch(ctx, reporter);
+  const launchOutcome = await driver.launch(ctx, reporter);
+  const spec = launchOutcome.spec;
+  const launchWarnings = launchOutcome.warnings;
   reporter.stop();
-  const mgr = await getServiceManager();
-  maybePrintFallbackBanner(mgr.kind);
-  const status2 = await mgr.install(spec);
-  if (spec.healthcheck) {
-    try {
-      await waitForHealthcheck(spec.healthcheck, 45e3);
-    } catch (err) {
-      if (err instanceof HealthcheckTimeoutError && hasStartupDiagnostics(driver)) {
-        const diag = await driver.diagnoseStartup(serviceLogPath(driver.id));
-        if (diag) {
-          throw new Error(
-            `${diag.reason}
-${diag.hints.map((h) => `  \u2022 ${h}`).join("\n")}`
-          );
-        }
-      }
-      throw err;
-    }
-  }
   const hostname = buildHostname();
-  const gatewayPid = status2.pid ?? void 0;
   const cachedBinding = await loadBindingInfo();
   const outcome = await bindAgent({
     apiUrl: cfg.platform.api_url,
@@ -5318,52 +6434,94 @@ ${diag.hints.map((h) => `  \u2022 ${h}`).join("\n")}`
       instance_id: cachedBinding.instance_id
     } : null
   });
-  if (outcome.status === "bound_offline") {
-    emit(options.json, {
-      status: "bound_offline",
-      public_key: pubkey,
-      fingerprint: fp,
-      gateway_pid: gatewayPid,
-      agent_gateway_url: agentGatewayUrl,
-      instance_id: outcome.instanceId
-    }, `Agent running (offline, cached instance: ${outcome.instanceId})`);
-    return;
-  }
   if (outcome.status === "pending_expired") {
-    throw new Error(
-      "Bind approval timed out \u2014 please re-run `beeos start` after approving in the dashboard."
-    );
+    throw new BeeosError({
+      code: "bind_pending_expired",
+      message: "Bind approval timed out before the dashboard confirmed it.",
+      hint: "Re-run `beeos start` and approve the new request in the dashboard.",
+      details: { framework: agentFramework }
+    });
   }
+  const isOffline = outcome.status === "bound_offline";
   const boundInstanceId = outcome.instanceId;
-  try {
-    await saveBindingInfo({
-      fingerprint: fp,
-      instance_id: boundInstanceId,
-      bound_at: Math.floor(Date.now() / 1e3),
-      framework: agentFramework
-    });
-    emit(options.json, {
-      status: "bound",
-      public_key: pubkey,
-      fingerprint: fp,
-      gateway_pid: gatewayPid,
-      agent_gateway_url: agentGatewayUrl,
-      instance_id: boundInstanceId
-    }, `Agent bound to instance: ${boundInstanceId}`);
-  } catch (e) {
+  if (!isOffline) {
     try {
-      await deleteInstance(cfg.platform.api_url, boundInstanceId);
-    } catch {
+      const boundAt = Math.floor(Date.now() / 1e3);
+      await saveBindingInfo({
+        fingerprint: fp,
+        instance_id: boundInstanceId,
+        bound_at: boundAt,
+        framework: agentFramework
+      });
+      const entry = {
+        kind: "openclaw",
+        framework: agentFramework,
+        instance_id: boundInstanceId,
+        bound_at: boundAt,
+        fingerprint: fp,
+        agent_gateway_url: agentGatewayUrl
+      };
+      await mutateStateBestEffort(
+        (state) => upsertOpenClawAgent(state, entry),
+        { authority: "binding.json" }
+      );
+    } catch (e) {
+      try {
+        await deleteInstance(cfg.platform.api_url, boundInstanceId);
+      } catch {
+      }
+      try {
+        await removeBindingInfo();
+      } catch {
+      }
+      throw new BeeosError({
+        code: "bind_post_bind_failed",
+        message: `Agent bound to instance ${boundInstanceId} but post-bind step failed.`,
+        hint: `Best-effort cleanup attempted; if the instance is still visible in the dashboard, delete it manually. Underlying error: ${e instanceof Error ? e.message : String(e)}`,
+        cause: e,
+        details: { instance_id: boundInstanceId }
+      });
     }
+  }
+  const isRebind = !isOffline && cachedBinding !== null && cachedBinding.instance_id !== boundInstanceId;
+  const mgr = await getServiceManager();
+  maybePrintFallbackBanner(mgr.kind);
+  let status2 = await mgr.install(spec);
+  if (isRebind) {
+    await mgr.restart(spec.id);
+    const refreshed = await mgr.status(spec.id);
+    if (refreshed) status2 = refreshed;
+  }
+  if (spec.healthcheck) {
     try {
-      await removeBindingInfo();
-    } catch {
+      await waitForHealthcheck(spec.healthcheck, 45e3);
+    } catch (err) {
+      if (err instanceof HealthcheckTimeoutError && hasStartupDiagnostics(driver)) {
+        const diag = await driver.diagnoseStartup(serviceLogPath(driver.id));
+        if (diag) {
+          throw new BeeosError({
+            code: "service_install_failed",
+            message: diag.reason,
+            hint: diag.hints.length > 0 ? diag.hints.map((h) => `\u2022 ${h}`).join("\n  ") : void 0,
+            cause: err,
+            details: { driver: driver.id }
+          });
+        }
+      }
+      throw err;
     }
-    throw new Error(
-      `Agent bound to instance ${boundInstanceId} but post-bind step failed. Attempted best-effort cleanup; if the instance is still visible in the dashboard, delete it manually. Underlying error: ${e}`,
-      { cause: e }
-    );
   }
+  const gatewayPid = status2.pid ?? void 0;
+  emit(options.json, {
+    status: isOffline ? "bound_offline" : "bound",
+    public_key: pubkey,
+    fingerprint: fp,
+    gateway_pid: gatewayPid,
+    agent_gateway_url: agentGatewayUrl,
+    instance_id: boundInstanceId,
+    warnings: launchWarnings.length > 0 ? [...launchWarnings] : void 0
+  }, isOffline ? `Agent running (offline, cached instance: ${boundInstanceId})` : `Agent bound to instance: ${boundInstanceId}`);
+  if (!options.json) printLaunchWarnings(launchWarnings);
 }
 function buildHostname() {
   const machine = os6.hostname();
@@ -5372,11 +6530,22 @@ function buildHostname() {
 }
 function emit(json, payload, human) {
   if (json) {
-    console.log(JSON.stringify(payload, null, 2));
+    emitJsonEnvelope(jsonOk(payload));
   } else if (human) {
     console.log(human);
   }
 }
+function printLaunchWarnings(warnings) {
+  if (warnings.length === 0) return;
+  console.log("");
+  console.log("Warnings:");
+  for (const w of warnings) {
+    console.log(`  ! ${w}`);
+  }
+  console.log(
+    "  Run `beeos doctor` for a full health report."
+  );
+}
 
 // src/commands/stop.ts
 init_dist();
@@ -5395,30 +6564,56 @@ async function run2(agentFramework) {
 
 // src/commands/status.ts
 init_dist();
-async function run3() {
+async function run3(options = {}) {
   const home = beeoHome();
   const cfg = await loadOrCreateConfig();
-  console.log(`BeeOS Home: ${home}`);
-  console.log(`API URL: ${cfg.platform.api_url}`);
-  console.log(`Agent Gateway: ${cfg.platform.agent_gateway_url}`);
-  console.log("");
   const p = getPlatformAdapter();
   const fpPath = p.joinPath(home, "identity", "fingerprint");
+  let fingerprint2 = null;
   if (await p.exists(fpPath)) {
     const fp = (await p.readFile(fpPath)).trim();
-    console.log(`Identity fingerprint: ${fp}`);
-  } else {
-    console.log("Identity: not yet created");
+    if (fp) fingerprint2 = fp;
   }
-  console.log("");
   const mgr = await getServiceManager();
-  const reason = activeFallbackReason();
-  console.log(`Service manager: ${mgr.kind}${reason ? ` (${reason})` : ""}`);
+  const fallbackReason2 = activeFallbackReason();
   let services = [];
   try {
     services = await mgr.list();
   } catch {
   }
+  if (options.json) {
+    emitJsonEnvelope(
+      jsonOk({
+        beeos_home: home,
+        api_url: cfg.platform.api_url,
+        agent_gateway_url: cfg.platform.agent_gateway_url,
+        fingerprint: fingerprint2,
+        service_manager: {
+          kind: mgr.kind,
+          fallback_reason: fallbackReason2 ?? null
+        },
+        services: services.map((s) => ({
+          id: s.id,
+          installed: s.installed,
+          running: s.running,
+          pid: s.pid ?? null,
+          last_exit_code: s.lastExitCode ?? null
+        }))
+      })
+    );
+    return;
+  }
+  console.log(`BeeOS Home: ${home}`);
+  console.log(`API URL: ${cfg.platform.api_url}`);
+  console.log(`Agent Gateway: ${cfg.platform.agent_gateway_url}`);
+  console.log("");
+  if (fingerprint2) {
+    console.log(`Identity fingerprint: ${fingerprint2}`);
+  } else {
+    console.log("Identity: not yet created");
+  }
+  console.log("");
+  console.log(`Service manager: ${mgr.kind}${fallbackReason2 ? ` (${fallbackReason2})` : ""}`);
   if (services.length === 0) {
     console.log("  (no services registered)");
   } else {
@@ -5435,20 +6630,30 @@ function formatService(s) {
 // src/commands/update.ts
 init_dist();
 init_progress2();
-async function run4(agentFramework) {
+async function run4(agentFramework, options = {}) {
   if (agentFramework === "device") {
     const reporter = new CliReporter();
     await deviceRuntime.update(reporter);
     reporter.stop();
-    console.log("device updated");
+    if (options.json) {
+      emitJsonEnvelope(jsonOk({ framework: "device", action: "updated" }));
+    } else {
+      console.log("device updated");
+    }
     return;
   }
   const descriptor = frameworkById(agentFramework);
   if (!descriptor || descriptor.status !== "available") {
     const avail = availableFrameworks().map((f) => f.id).join(", ");
-    throw new Error(
-      `Unknown agent framework '${agentFramework}'. Available: ${avail}.`
-    );
+    throw new BeeosError({
+      code: "framework_unavailable",
+      message: `Unknown agent framework '${agentFramework}'.`,
+      hint: avail.length > 0 ? `Available frameworks: ${avail}.` : "No frameworks are registered \u2014 reinstall the CLI.",
+      details: {
+        requested: agentFramework,
+        available: avail.length > 0 ? avail.split(/,\s*/) : []
+      }
+    });
   }
   const mgr = await getServiceManager();
   const services = await mgr.list().catch(() => []);
@@ -5457,7 +6662,11 @@ async function run4(agentFramework) {
     await run2(agentFramework);
   }
   await run(agentFramework, { force: true });
-  console.log(`${agentFramework} updated`);
+  if (options.json) {
+    emitJsonEnvelope(jsonOk({ framework: agentFramework, action: "updated" }));
+  } else {
+    console.log(`${agentFramework} updated`);
+  }
 }
 
 // src/commands/bind-status.ts
@@ -5472,21 +6681,39 @@ async function run5(bindId, options) {
       if (await p.exists(fpPath)) {
         const fp = (await p.readFile(fpPath)).trim();
         if (fp) {
+          const boundAt = Math.floor(Date.now() / 1e3);
+          const cached2 = await safeLoadBindingInfo();
+          const framework = cached2?.framework?.trim() || "openclaw";
           await saveBindingInfo({
             fingerprint: fp,
             instance_id: resp.instance_id,
-            bound_at: Math.floor(Date.now() / 1e3)
+            bound_at: boundAt,
+            framework
           });
+          const entry = {
+            kind: "openclaw",
+            framework,
+            instance_id: resp.instance_id,
+            bound_at: boundAt,
+            fingerprint: fp,
+            agent_gateway_url: resolveAgentGatewayUrl(cfg)
+          };
+          await mutateStateBestEffort(
+            (state) => upsertOpenClawAgent(state, entry),
+            { authority: "binding.json" }
+          );
         }
       }
     } catch {
     }
   }
   if (options.json) {
-    console.log(JSON.stringify({
-      status: resp.status,
-      instance_id: resp.instance_id ?? null
-    }, null, 2));
+    emitJsonEnvelope(
+      jsonOk({
+        status: resp.status,
+        instance_id: resp.instance_id ?? null
+      })
+    );
   } else {
     console.log(`Bind status: ${resp.status}`);
     if (resp.instance_id) {
@@ -5494,6 +6721,13 @@ async function run5(bindId, options) {
     }
   }
 }
+async function safeLoadBindingInfo() {
+  try {
+    return await loadBindingInfo();
+  } catch {
+    return null;
+  }
+}
 
 // src/index.ts
 init_device2();
@@ -5504,7 +6738,7 @@ import readline2 from "readline";
 
 // src/commands/doctor.ts
 init_dist();
-import fs8 from "fs/promises";
+import fs9 from "fs/promises";
 import path9 from "path";
 var LOG_SIZE_WARN_BYTES = 50 * 1024 * 1024;
 async function run6(options) {
@@ -5521,7 +6755,8 @@ async function run6(options) {
   }
   const resolvedAgentGatewayUrl = resolveAgentGatewayUrl(cfg);
   const agentGatewayHealth = await probeAgentGateway(resolvedAgentGatewayUrl);
-  const tools = await collectToolStatus(p);
+  const tools = await collectToolStatus();
+  const shimReport = await collectShimReport();
   const warnings = [];
   const hints = [];
   if (!state.hasIdentity) {
@@ -5530,6 +6765,14 @@ async function run6(options) {
   if (state.openclaw.gatewayRunning && !state.openclaw.found) {
     warnings.push("port 18789 is in use but no OpenClaw install detected \u2014 another app may conflict");
   }
+  if (state.openclaw.found && state.openclaw.pluginInstalled === false) {
+    warnings.push(
+      `OpenClaw is installed at ${state.openclaw.home ?? "?"} but the beeos-claw plugin is not registered. BeeOS-specific tools may be unavailable to agents until this is fixed.`
+    );
+    hints.push(
+      "re-run `beeos start openclaw --force` to re-install the plugin, or check ~/.beeos/logs/services/openclaw.log for the original failure"
+    );
+  }
   if (state.devices.entries.length > 0 && services.length === 0) {
     warnings.push(
       "devices tracked via legacy devices.json \u2014 no OS services registered. Re-run `beeos device attach` to migrate them to the OS service manager."
@@ -5572,9 +6815,19 @@ async function run6(options) {
       "adb not found \u2014 `beeos device attach` will download Android platform-tools on first use"
     );
   }
-  if (!tools.python.path) {
-    warnings.push(
-      "python3 not found on PATH \u2014 device-agent uses a uv-managed interpreter; install python 3.11+ if uv is unavailable"
+  for (const e of shimReport.entries) {
+    if (e.outcome === "outdated") {
+      warnings.push(
+        `${e.pkg}: installed ${e.installed ?? "(missing)"}, npm latest ${e.latest}.`
+      );
+    } else if (e.outcome === "missing") {
+      warnings.push(`${e.pkg}: not installed globally \u2014 run 'beeos init' to install.`);
+    } else if (e.outcome === "error") {
+    }
+  }
+  if (shimReport.entries.some((e) => e.outcome === "outdated" || e.outcome === "missing")) {
+    hints.push(
+      "run `beeos init` and pick option [1] to upgrade CLI + agents to the latest npm release"
     );
   }
   const bloatedLogs = await checkLogFileSizes();
@@ -5585,29 +6838,26 @@ async function run6(options) {
     hints.push(`truncate safely: : > ${l.path}`);
   }
   if (options.json) {
-    console.log(
-      JSON.stringify(
-        {
-          platform: p.platform(),
-          arch: process.arch,
-          node: process.version,
-          beeosHome: state.beeosHome,
-          config: cfg,
-          state,
-          serviceManager: {
-            kind: mgr.kind,
-            available: serviceCheck.available,
-            fallbackReason: fallbackReason2,
-            services
-          },
-          agentGateway: agentGatewayHealth,
-          tools,
-          warnings,
-          hints
+    emitJsonEnvelope(
+      jsonOk({
+        platform: p.platform(),
+        arch: process.arch,
+        node: process.version,
+        beeosHome: state.beeosHome,
+        config: cfg,
+        state,
+        serviceManager: {
+          kind: mgr.kind,
+          available: serviceCheck.available,
+          fallbackReason: fallbackReason2,
+          services
         },
-        null,
-        2
-      )
+        agentGateway: agentGatewayHealth,
+        tools,
+        npmShims: shimReport,
+        warnings,
+        hints
+      })
     );
     return;
   }
@@ -5631,10 +6881,19 @@ async function run6(options) {
     console.log(`    - ${s.id.padEnd(28)} ${status2}${pid}`);
   }
   console.log(`  adb          : ${tools.adb.path ?? "not found"}`);
-  console.log(`  python3      : ${tools.python.path ?? "not found"}`);
   console.log(`  scrcpy-bridge: ${tools.scrcpyBridge.path ?? "not installed (auto on attach)"}`);
   console.log(`  vnc-bridge   : ${tools.vncBridge.path ?? "not installed (auto on --vnc-host)"}`);
   console.log("");
+  console.log("  npm shims:");
+  for (const e of shimReport.entries) {
+    const marker = shimMarker(e.outcome);
+    const installed = e.installed ?? "(missing)";
+    const latest = e.latest ?? "(unknown)";
+    console.log(
+      `    ${marker} ${e.pkg.padEnd(34)} installed=${installed.padEnd(8)} npm=${latest}`
+    );
+  }
+  console.log("");
   if (warnings.length > 0) {
     console.log("  Warnings:");
     for (const w of warnings) {
@@ -5652,38 +6911,57 @@ async function run6(options) {
     console.log("");
   }
 }
-async function collectToolStatus(p) {
-  const [adbPath, pythonPath, scrcpyPath, vncPath] = await Promise.all([
+async function collectToolStatus() {
+  const [adbPath, scrcpyPath, vncPath] = await Promise.all([
     findAdb().catch(() => null),
-    findPython(p).catch(() => null),
     scrcpyBridgeRuntime.findBinary().catch(() => null),
     vncBridgeRuntime.findBinary().catch(() => null)
   ]);
   return {
     adb: { path: adbPath },
-    python: { path: pythonPath },
     scrcpyBridge: { path: scrcpyPath },
     vncBridge: { path: vncPath }
   };
 }
-async function findPython(p) {
-  const whichCmd = p.platform() === "win32" ? "where" : "which";
-  for (const bin of ["python3", "python"]) {
-    try {
-      const r = await p.exec(whichCmd, [bin]);
-      if (r.code === 0 && r.stdout.trim()) {
-        return r.stdout.trim().split("\n")[0].trim();
+async function collectShimReport() {
+  const sources = readPinSourcesFromEnv();
+  const entries = await Promise.all(
+    ALL_BEEOS_PKGS.map(async (pkg) => {
+      const spec = resolveInstallSpec(pkg, sources);
+      const [installed, latest] = await Promise.all([
+        npmGlobalVersion(pkg).catch(() => null),
+        npmRegistryVersion(spec).catch(() => null)
+      ]);
+      let outcome;
+      if (latest === null) outcome = "error";
+      else if (installed === null) outcome = "missing";
+      else if (installed === latest) outcome = "ok";
+      else outcome = "outdated";
+      if (pkg === NPM_PKGS.CLI && installed === null) {
+        outcome = "missing";
       }
-    } catch {
-    }
+      return { pkg, installed, latest, spec, outcome };
+    })
+  );
+  return { entries };
+}
+function shimMarker(outcome) {
+  switch (outcome) {
+    case "ok":
+      return "\u2713";
+    case "outdated":
+      return "\u2191";
+    case "missing":
+      return "\u2717";
+    case "error":
+      return "?";
   }
-  return null;
 }
 async function checkLogFileSizes() {
   const dir = path9.join(beeoHome(), "logs", "services");
   let entries;
   try {
-    entries = await fs8.readdir(dir);
+    entries = await fs9.readdir(dir);
   } catch {
     return [];
   }
@@ -5692,7 +6970,7 @@ async function checkLogFileSizes() {
     if (!name.endsWith(".log")) continue;
     const full = path9.join(dir, name);
     try {
-      const st = await fs8.stat(full);
+      const st = await fs9.stat(full);
       if (st.isFile() && st.size >= LOG_SIZE_WARN_BYTES) {
         bloated.push({ path: full, size: st.size });
       }
@@ -5761,6 +7039,7 @@ function formatAgentGatewayStatus(h) {
 }
 
 // src/commands/init.ts
+init_progress2();
 init_fallback_banner();
 async function run7(options) {
   await ensureDirs();
@@ -5791,7 +7070,11 @@ async function run7(options) {
     return;
   }
   if (decision === "upgrade") {
-    console.log("Upgrading / ensuring OpenClaw is running...\n");
+    if (await shouldUpgradeBeeosSuite(options)) {
+      const exited = await upgradeAndMaybeExit(options);
+      if (exited) return;
+    }
+    console.log("Ensuring OpenClaw is running...\n");
   }
   if (decision === "rebind-new-key") {
     await rotateIdentity();
@@ -5801,9 +7084,12 @@ async function run7(options) {
   const descriptor = frameworkById(frameworkId);
   if (!descriptor || descriptor.status !== "available") {
     const avail = availableFrameworks().map((f) => f.id).join(", ");
-    throw new Error(
-      `Agent framework '${frameworkId}' is not available. Available: ${avail}.`
-    );
+    throw new BeeosError({
+      code: "framework_unavailable",
+      message: `Agent framework '${frameworkId}' is not available. Available: ${avail}.`,
+      hint: avail.length > 0 ? `Re-run with --framework <one-of-the-above>` : "No frameworks are registered \u2014 reinstall the CLI.",
+      details: { requested: frameworkId, available: availableFrameworks().map((f) => f.id) }
+    });
   }
   await run(descriptor.id, {
     force: true,
@@ -5951,6 +7237,60 @@ function prompt(question) {
     });
   });
 }
+async function shouldUpgradeBeeosSuite(options) {
+  if (options.headless) return false;
+  if (process.env.BEEOS_INIT_SKIP_NPM_UPGRADE === "1") return false;
+  return true;
+}
+async function upgradeAndMaybeExit(options) {
+  if (options.json) {
+    return false;
+  }
+  console.log("Checking for newer @beeos-ai/cli + agents on npm...");
+  const reporter = new CliReporter();
+  let outcome;
+  try {
+    outcome = await upgradeBeeosSuite({
+      packages: ALL_BEEOS_PKGS,
+      progress: reporter
+    });
+  } catch (e) {
+    reporter.stop();
+    console.log(
+      `  (upgrade skipped \u2014 ${e instanceof Error ? e.message : String(e)})
+  Tip: re-run \`npm install -g @beeos-ai/cli @beeos-ai/device-agent @beeos-ai/device-mcp-server\` manually.`
+    );
+    return false;
+  }
+  reporter.stop();
+  if (outcome.anyFailed) {
+    const failed = outcome.packages.find((p) => p.failed)?.failed ?? "unknown error";
+    console.log(`  \u26A0 npm install failed: ${failed}`);
+    console.log(
+      "    Manual fix:\n      npm i -g @beeos-ai/cli @beeos-ai/device-agent @beeos-ai/device-mcp-server\n"
+    );
+    return false;
+  }
+  if (!outcome.anyChanged) {
+    console.log("  All BeeOS npm packages are up to date.\n");
+    return false;
+  }
+  for (const pkg of outcome.packages) {
+    if (pkg.changed) {
+      console.log(`  ${pkg.pkg}: ${pkg.before ?? "(none)"} \u2192 ${pkg.after}`);
+    }
+  }
+  const cliEntry = outcome.packages.find((p) => p.pkg === NPM_PKGS.CLI);
+  if (cliEntry?.changed) {
+    console.log("");
+    console.log("  CLI itself was upgraded \u2014 please re-run `beeos init` to continue");
+    console.log("  with the new code. The current process is still running the old version.");
+    console.log("");
+    return true;
+  }
+  console.log("  Agents updated. Continuing init...\n");
+  return false;
+}
 
 // src/commands/service.ts
 init_dist();
@@ -5959,18 +7299,14 @@ async function install(options) {
   const check = await mgr.selfCheck();
   const reason = activeFallbackReason();
   if (options.json) {
-    console.log(
-      JSON.stringify(
-        {
-          ok: check.available,
-          manager: mgr.kind,
-          fallbackReason: reason,
-          warnings: check.warnings,
-          hints: check.hints
-        },
-        null,
-        2
-      )
+    emitJsonEnvelope(
+      jsonOk({
+        available: check.available,
+        manager: mgr.kind,
+        fallbackReason: reason,
+        warnings: check.warnings,
+        hints: check.hints
+      })
     );
     return;
   }
@@ -6004,7 +7340,7 @@ async function uninstall(options) {
     }
   }
   if (options.json) {
-    console.log(JSON.stringify({ removed, errors }, null, 2));
+    emitJsonEnvelope(jsonOk({ removed, errors }));
     return;
   }
   if (removed.length === 0 && errors.length === 0) {
@@ -6023,12 +7359,8 @@ async function status(options) {
   } catch {
   }
   if (options.json) {
-    console.log(
-      JSON.stringify(
-        { manager: mgr.kind, fallbackReason: reason, services },
-        null,
-        2
-      )
+    emitJsonEnvelope(
+      jsonOk({ manager: mgr.kind, fallbackReason: reason, services })
     );
     return;
   }
@@ -6051,13 +7383,15 @@ async function run8(options) {
   const mgr = await getServiceManager();
   const mig = await migrateLegacySupervisor(mgr);
   if (options.json) {
-    console.log(JSON.stringify({
-      ran: mig.ran,
-      migrated: mig.migrated,
-      backupPath: mig.backupPath ?? null,
-      errors: mig.errors,
-      serviceManager: mgr.kind
-    }, null, 2));
+    emitJsonEnvelope(
+      jsonOk({
+        ran: mig.ran,
+        migrated: mig.migrated,
+        backupPath: mig.backupPath ?? null,
+        errors: mig.errors,
+        serviceManager: mgr.kind
+      })
+    );
     return;
   }
   if (!mig.ran) {
@@ -6079,6 +7413,98 @@ async function run8(options) {
   }
 }
 
+// src/commands/logs.ts
+init_dist();
+function resolveLogTarget(input, services) {
+  const exact = services.find((s) => s.id === input);
+  if (exact) {
+    return { id: exact.id, logFile: exact.logFile, matchedFrom: "exact" };
+  }
+  const safe = safeId(input);
+  const safeMatch = services.find((s) => s.id === safe);
+  if (safeMatch) {
+    return { id: safeMatch.id, logFile: safeMatch.logFile, matchedFrom: "safeId" };
+  }
+  const heuristicId = `device-agent-${safe}`;
+  const heuristic = services.find((s) => s.id === heuristicId);
+  if (heuristic) {
+    return { id: heuristic.id, logFile: heuristic.logFile, matchedFrom: "adbSerialHeuristic" };
+  }
+  return {
+    id: safe,
+    logFile: serviceLogPath(safe),
+    matchedFrom: "fallback"
+  };
+}
+async function run9(idArg, options) {
+  const mgr = await getServiceManager();
+  let services = [];
+  try {
+    services = await mgr.list();
+  } catch {
+  }
+  if (!idArg) {
+    if (options.json) {
+      emitJsonEnvelope(
+        jsonOk({
+          manager: mgr.kind,
+          services: services.map((s) => ({ id: s.id, logFile: s.logFile }))
+        })
+      );
+      return;
+    }
+    if (services.length === 0) {
+      console.log("No registered BeeOS services. Start one with `beeos start <agent>` or `beeos device attach`.");
+      return;
+    }
+    console.log(`Service manager: ${mgr.kind}`);
+    console.log("Available services:");
+    for (const s of services) {
+      console.log(`  ${s.id.padEnd(28)} ${s.logFile}`);
+    }
+    console.log("\nUsage: beeos logs <id> [-f] [-n <lines>]");
+    return;
+  }
+  const target = resolveLogTarget(idArg, services);
+  if (options.json) {
+    emitJsonEnvelope(
+      jsonOk({
+        input: idArg,
+        resolved: {
+          id: target.id,
+          logFile: target.logFile,
+          matchedFrom: target.matchedFrom
+        }
+      })
+    );
+    return;
+  }
+  if (target.matchedFrom === "fallback") {
+    console.error(
+      `! No registered service matched "${idArg}". Falling back to canonical path:
+  ${target.logFile}
+  (the file may not exist yet if the service has never run.)`
+    );
+  }
+  const ac = new AbortController();
+  const onSigint = () => {
+    ac.abort();
+  };
+  if (options.follow) {
+    process.on("SIGINT", onSigint);
+  }
+  try {
+    await tailLogFile({
+      logFile: target.logFile,
+      initialLines: options.lines ?? 50,
+      follow: !!options.follow,
+      signal: ac.signal
+    });
+  } finally {
+    if (options.follow) process.off("SIGINT", onSigint);
+  }
+}
+
 // src/index.ts
 setPlatformAdapter(new NodePlatformAdapter());
 var program = new Command();
@@ -6087,15 +7513,18 @@ program.name("beeos").version(cliVersion.display).description("BeeOS \u2014 run
 program.command("init").description("One-shot install + bind flow (default entry from the curl installer)").option("--framework <name>", "Agent framework to install (default: openclaw)").option("--yes", "Non-interactive \u2014 accept the default action", false).option("--json", "Output machine-readable JSON (implies --yes)", false).option("--no-browser", "Don't auto-open a browser for bind confirmation").option("--headless", "Never open a browser (use terminal QR only)", false).option("--skip-service-prompt", "Skip the system-service install prompt", false).option("--device", "Jump straight into `beeos device attach` instead", false).action((opts) => run7(opts));
 program.command("doctor").description("Inspect local BeeOS state (install, binding, services, warnings)").option("--json", "Output machine-readable JSON", false).action((opts) => run6(opts));
 program.command("migrate").description("Migrate legacy Node supervisor state to OS-native services (one-shot)").option("--json", "Output machine-readable JSON", false).action((opts) => run8(opts));
+program.command("logs").description(
+  "Tail logs for a BeeOS service. Pass an ADB serial or service id; omit to list every registered service's log file path."
+).argument("[id]", "Service id (e.g. `device-agent-<serial>`) or raw ADB serial").option("-f, --follow", "Stream new log lines (Ctrl-C to exit)", false).option("-n, --lines <n>", "Initial trailing lines to print (default 50)", (v) => Number(v)).option("--json", "Output machine-readable JSON (resolves the path; does not stream)", false).action((id, opts) => run9(id, opts));
 var serviceCmd = program.command("service").description("Inspect and manage the OS-native service manager (launchd / systemd --user / Task Scheduler)");
 serviceCmd.command("install").description("Verify the OS service manager is available (per-target services install automatically)").option("--json", "Output machine-readable JSON", false).action((opts) => install(opts));
 serviceCmd.command("uninstall").description("Uninstall every BeeOS-managed OS service").option("--json", "Output machine-readable JSON", false).action((opts) => uninstall(opts));
 serviceCmd.command("status").description("List every BeeOS-managed OS service").option("--json", "Output machine-readable JSON", false).action((opts) => status(opts));
 program.command("start").description("Install and start an agent").argument("<agent_type>", "Agent type to start (e.g. openclaw)").option("--version <version>", "Pin to a specific version instead of latest").option("--force", "Skip confirmation prompts", false).option("--json", "Output machine-readable JSON to stdout (implies --force)", false).option("--no-browser", "Don't auto-open browser for bind confirmation").action((agentFramework, options) => run(agentFramework, options));
 program.command("stop").description("Stop a running agent").argument("<agent_type>", "Agent type to stop").action((agentFramework) => run2(agentFramework));
-program.command("status").description("Show status of managed agents").action(run3);
-program.command("update").description("Update an agent to the latest version").argument("<agent_type>", "Agent type to update").action((agentFramework) => run4(agentFramework));
-program.command("bind-status").description("Check agent binding status").argument("<bind_id>", "Bind session ID returned by `beeos start --json`").option("--json", "Output machine-readable JSON", false).action(run5);
+program.command("status").description("Show status of managed agents").option("--json", "Output machine-readable JSON envelope ({ok,data})", false).action((opts) => run3(opts));
+program.command("update").description("Update an agent to the latest version").argument("<agent_type>", "Agent type to update").option("--json", "Output machine-readable JSON envelope ({ok,data})", false).action((agentFramework, opts) => run4(agentFramework, opts));
+program.command("bind-status").description("Check agent binding status").argument("<bind_id>", "Bind session ID returned by `beeos start --json`").option("--json", "Output machine-readable JSON envelope ({ok,data})", false).action(run5);
 var deviceCmd = program.command("device").description("Manage device agents (Android/Desktop/ChromeOS)");
 deviceCmd.command("attach").description("Attach an ADB-connected device as an AI agent").option("--serial <serial>", "ADB device serial number").option("--name <name>", "Human-readable device name").option("--all", "Attach all connected ADB devices", false).option(
   "--no-video",
@@ -6103,7 +7532,10 @@ deviceCmd.command("attach").description("Attach an ADB-connected device as an AI
 ).option(
   "--vnc-host <host>",
   "Use vnc-bridge against a VNC server at this host (desktop/Linux/macOS). Implies video mode = vnc instead of scrcpy."
-).option("--vnc-port <port>", "VNC TCP port (default 5900)", (v) => Number(v)).option("--vnc-password <password>", "VNC password (forwarded via env)").action(attach);
+).option("--vnc-port <port>", "VNC TCP port (default 5900)", (v) => Number(v)).option("--vnc-password <password>", "VNC password (forwarded via env)").option(
+  "--agent-gateway-url <url>",
+  "Override the Agent Gateway URL for THIS device only (advanced; multi-region staging). Persists to the device entry so the fleet supervisor reuses it on every restart. Falls back to the global config when omitted."
+).action(attach);
 deviceCmd.command("detach").description("Detach a device agent").option("--serial <serial>", "ADB device serial number").option("--all", "Detach all devices", false).action(detach);
 deviceCmd.command("list").description("List attached devices").option("--local", "Only show locally running device agents", false).action(list);
 deviceCmd.command("exec").description("Send a natural language command to a device").option("--serial <serial>", "ADB device serial number").argument("<prompt>", "The command/prompt to execute").action(exec);
@@ -6112,6 +7544,15 @@ deviceCmd.command("refresh-config").description(
   "Re-fetch this device's VLM/ARouter config from Agent Gateway and rewrite ~/.beeos/<instance_id>.config.json (use after dashboard changes)."
 ).option("--serial <serial>", "ADB device serial number").option("--all", "Refresh every attached device", false).action(refreshConfig);
 program.parseAsync(process.argv).catch((err) => {
+  const wantsJson = process.argv.includes("--json");
+  if (isBeeosError(err)) {
+    if (wantsJson) {
+      console.log(JSON.stringify(toJsonFailurePayload(err), null, 2));
+    } else {
+      console.error(formatHumanError(err));
+    }
+    process.exit(1);
+  }
   console.error(err.message);
   process.exit(1);
 });