machine-bridge-mcp 2.0.0 → 3.0.0-beta.102

package/src/local/call-registry.mjs

@@ -1,8 +1,10 @@
 // @ts-check
-
 import { randomBytes } from "node:crypto";
 import { performance } from "node:perf_hooks";
 import { BridgeError } from "./errors.mjs";
+import { assertCallCapacity, callCapacityConfig, callCapacitySnapshot } from "./call-capacity.mjs";
+import { bindCallPrincipal, callIdsForAuthority } from "./call-authority.mjs";
+import { assertCallRegistryOpen, cancelAllCallsAndWait, notifyCallRegistryChanged } from "./call-registry-drain.mjs";
 
 /** @typedef {ReturnType<typeof setTimeout>} TimerHandle */
 /**
@@ -15,11 +17,15 @@ import { BridgeError } from "./errors.mjs";
  *   controller: AbortController,
  *   cancelReason: string,
  *   timer: TimerHandle | null,
+ *   owner_kind?: string, owner_account_id?: string, owner_account_version?: number,
+ *   owner_client_id?: string, owner_family_id?: string,
  * }} CallRecord
  */
 /**
  * @typedef {{
  *   maximum?: unknown,
+ *   reserved?: unknown,
+ *   reservedTools?: Iterable<string>,
  *   now?: () => number,
  *   scheduler?: {setTimeout: typeof setTimeout, clearTimeout: typeof clearTimeout},
  *   onCancel?: (record: CallRecord) => void,
@@ -34,7 +40,8 @@ import { BridgeError } from "./errors.mjs";
 export class CallRegistry {
   /** @param {CallRegistryOptions} [options] */
   constructor(options = {}) {
-    this.maximum = positiveInteger(options.maximum, 16);
+    this.capacity = callCapacityConfig(options.maximum, options.reserved, options.reservedTools);
+    this.maximum = this.capacity.maximum;
     this.now = typeof options.now === "function" ? options.now : () => performance.now();
     this.scheduler = options.scheduler || { setTimeout, clearTimeout };
     this.onCancel = typeof options.onCancel === "function" ? options.onCancel : () => {};
@@ -45,18 +52,18 @@ export class CallRegistry {
 
   /** @param {OpenCallInput} [input] */
   open({ callId = "", tool = "", origin = "local", timeoutMs = 0 } = {}) {
+    assertCallRegistryOpen(this);
     const id = String(callId || `call_${randomBytes(16).toString("hex")}`);
+    const toolName = String(tool || "");
     if (this.calls.has(id)) throw new BridgeError("conflict", "duplicate in-flight call id");
-    if (this.calls.size >= this.maximum) {
-      throw new BridgeError("limit_exceeded", `too many concurrent tool calls (${this.maximum})`, { retryable: true });
-    }
+    assertCallCapacity(this.calls, this.capacity, toolName);
     const controller = new AbortController();
     const startedAt = this.now();
     const timeout = positiveInteger(timeoutMs, 0);
     /** @type {CallRecord} */
     const record = {
       id,
-      tool: String(tool || ""),
+      tool: toolName,
       origin: String(origin || "local"),
       startedAt,
       deadlineAt: timeout ? startedAt + timeout : null,
@@ -96,7 +103,7 @@ export class CallRegistry {
     if (!record) return false;
     if (record.timer) this.scheduler.clearTimeout(record.timer);
     this.calls.delete(id);
-    this.onFinish(record);
+    try { this.onFinish(record); } finally { notifyCallRegistryChanged(this); }
     return true;
   }
 
@@ -117,12 +124,20 @@ export class CallRegistry {
     return cancelled;
   }
 
-  /** @param {unknown} [reason] */
-  cancelAll(reason = "runtime stopped") {
-    for (const id of [...this.calls.keys()]) {
-      this.cancel(id, reason);
-      this.finish(id);
-    }
+  /** @param {unknown} callId @param {unknown} principal */ bindPrincipal(callId, principal) {
+    return bindCallPrincipal(this.calls.get(String(callId || "")), principal);
+  }
+
+  /** @param {unknown} revocation */ cancelAuthority(revocation) {
+    let cancelled = 0;
+    for (const id of callIdsForAuthority(this.calls.values(), revocation))
+      if (this.cancel(id, "authority revoked", "authorization_denied")) cancelled += 1;
+    return cancelled;
+  }
+
+  /** @param {unknown} [reason] @param {number} [waitMs] */
+  async cancelAllAndWait(reason = "runtime stopped", waitMs = 5_000) {
+    await cancelAllCallsAndWait(this, reason, waitMs);
   }
 
   /** @param {unknown} callId */
@@ -151,7 +166,7 @@ export class CallRegistry {
   snapshot() {
     const now = this.now();
     /** @type {Record<string, number>} */
-    const byOrigin = {};
+    const byOrigin = Object.create(null);
     let oldestMs = 0;
     for (const call of this.calls.values()) {
       byOrigin[call.origin] = (byOrigin[call.origin] || 0) + 1;
@@ -159,7 +174,7 @@ export class CallRegistry {
     }
     return {
       active: this.calls.size,
-      maximum: this.maximum,
+      ...callCapacitySnapshot(this.calls, this.capacity),
       by_origin: byOrigin,
       oldest_ms: oldestMs,
     };

package/src/local/capability-observer.mjs

@@ -34,6 +34,11 @@ export class CapabilityObserver {
       matched_commands: Array.isArray(result?.command_matches) ? result.command_matches.length : 0,
       matched_applications: Array.isArray(result?.application_matches) ? result.application_matches.length : 0,
       recommended_tools: Array.isArray(result?.recommended_tools) ? [...result.recommended_tools] : [],
+      primary_route: result?.execution_routing?.primary_route?.id || null,
+      routing_ambiguity: result?.execution_routing?.ambiguity?.level || "none",
+      routing_score_gap: Number.isFinite(Number(result?.execution_routing?.ambiguity?.score_gap))
+        ? Number(result.execution_routing.ambiguity.score_gap)
+        : 0,
       refresh_fingerprint: String(result?.refresh?.fingerprint || ""),
     };
   }

package/src/local/capability-ranking.mjs

@@ -67,9 +67,10 @@ export function recommendTools(task, { commandsAvailable, commandRelevant, skill
   const tools = ["agent_context"];
   if (skillRelevant) tools.push("load_local_skill");
   if (commandRelevant) tools.push("run_local_command");
-  if (/browser|chrome|edge|brave|网页|浏览器|表单|网站/.test(lower)) tools.push("browser_status", "browser_list_tabs", "browser_manage_tabs", "browser_inspect_page", "browser_wait", "browser_action", "browser_fill_form");
-  if (/app|application|gui|window|应用|软件|窗口|界面/.test(lower)) tools.push("list_local_applications", "inspect_local_application", "operate_local_application");
+  if (/browser|chrome|edge|brave|网页|浏览器|表单|网站/.test(lower)) tools.push("computer_observe", "computer_act", "browser_status", "browser_list_tabs", "browser_manage_tabs", "browser_inspect_page", "browser_wait", "browser_action", "browser_fill_form");
+  if (/app|application|gui|window|应用|软件|窗口|界面/.test(lower)) tools.push("computer_observe", "computer_act", "list_local_applications", "inspect_local_application", "operate_local_application");
   if (/git|commit|branch|diff|仓库|提交|分支/.test(lower)) tools.push("git_status", "git_diff");
+  if (/commit|提交/.test(lower)) tools.push("git_commit");
   if (/test|build|lint|command|terminal|测试|构建|命令|终端/.test(lower)) tools.push(commandsAvailable ? "run_local_command" : "run_process");
   if (/file|code|source|edit|write|文件|代码|源码|修改|写入/.test(lower)) tools.push("read_file", "search_text", "edit_file", "apply_patch");
   return [...new Set(tools)];

package/src/local/child-process-settlement.mjs

@@ -0,0 +1,132 @@
+// @ts-check
+
+/**
+ * @typedef {{
+ *   onSettle?: (code: number | null, signal: string | null, source: "close" | "exit_fallback") => void,
+ *   onFallback?: () => void,
+ *   schedule?: (callback: () => void, delay: number) => unknown,
+ *   clearSchedule?: (timer: unknown) => void,
+ *   fallbackMs?: unknown,
+ *   readExitState?: () => { code?: number | null, signal?: string | null },
+ * }} ChildProcessSettlementOptions
+ */
+
+/** @param {ChildProcessSettlementOptions} [options] */
+export function createChildProcessSettlement(options = {}) {
+  if (typeof options.onSettle !== "function") throw new TypeError("child settlement requires onSettle");
+  const onSettle = options.onSettle;
+  /** @type {(callback: () => void, delay: number) => unknown} */
+  const defaultSchedule = (callback, delay) => setTimeout(callback, delay);
+  /** @type {(timer: unknown) => void} */
+  const defaultClearSchedule = timer => clearTimeout(/** @type {ReturnType<typeof setTimeout>} */ (timer));
+  const schedule = typeof options.schedule === "function" ? options.schedule : defaultSchedule;
+  const clearSchedule = typeof options.clearSchedule === "function" ? options.clearSchedule : defaultClearSchedule;
+  const delay = boundedDelay(options.fallbackMs);
+  let settled = false;
+  /** @type {unknown} */
+  let timer = null;
+  let timerSet = false;
+
+  /**
+   * @param {number | null} code
+   * @param {string | null} signal
+   * @param {"close" | "exit_fallback"} source
+   */
+  function settle(code, signal, source) {
+    if (settled) return false;
+    settled = true;
+    if (timerSet) clearSchedule(timer);
+    timer = null;
+    timerSet = false;
+    onSettle(code, signal, source);
+    return true;
+  }
+
+  /** @param {number | null} code @param {string | null} signal */
+  function onClose(code, signal) { return settle(code, signal, "close"); }
+
+  /** @param {number | null} code @param {string | null} signal */
+  function onExit(code, signal) {
+    if (settled || timerSet) return false;
+    timerSet = true;
+    timer = schedule(() => {
+      timer = null;
+      timerSet = false;
+      options.onFallback?.();
+      const observed = safeExitState(options.readExitState);
+      const settledCode = typeof observed.code === "number" && Number.isInteger(observed.code) ? observed.code : code;
+      const settledSignal = observed.signal || signal;
+      settle(settledCode, settledSignal, "exit_fallback");
+    }, delay);
+    return true;
+  }
+
+  function cancel() {
+    if (settled) return false;
+    settled = true;
+    if (timerSet) clearSchedule(timer);
+    timer = null;
+    timerSet = false;
+    return true;
+  }
+
+  return Object.freeze({ onClose, onExit, cancel });
+}
+
+/**
+ * Attach the shared close-preferred settlement policy to one ChildProcess-like object.
+ * Residual stdio is destroyed only after exit has been observed and the bounded close grace expired.
+ * @param {any} child
+ * @param {ChildProcessSettlementOptions} options
+ */
+export function attachChildProcessSettlement(child, options = {}) {
+  const settlement = createChildProcessSettlement({
+    ...options,
+    readExitState: options.readExitState || (() => ({ code: child?.exitCode, signal: child?.signalCode })),
+    onFallback() {
+      for (const stream of [child?.stdin, child?.stdout, child?.stderr]) {
+        try { stream?.destroy?.(); }
+        catch { /* The process has exited; residual stream destruction is bounded best-effort cleanup. */ }
+      }
+      try { child?.unref?.(); }
+      catch { /* Detachment is advisory after process exit and cannot change the settlement result. */ }
+      options.onFallback?.();
+    },
+  });
+  /** @param {number | null} code @param {string | null} signal */
+  const onExit = (code, signal) => settlement.onExit(code, signal);
+  /** @param {number | null} code @param {string | null} signal */
+  const onClose = (code, signal) => settlement.onClose(code, signal);
+  child.once("exit", onExit);
+  child.once("close", onClose);
+  return settlement;
+}
+
+/** @param {unknown} value */
+function boundedDelay(value) {
+  if (value === undefined) return 1000;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed < 0 || parsed > 10_000) {
+    throw new TypeError("child settlement fallback must be between 0 and 10000 milliseconds");
+  }
+  return Math.floor(parsed);
+}
+export function childExitedBeforeTimeout({ exitCode = null, signalCode = null, processState = "unknown" } = {}) {
+  return Number.isInteger(exitCode) || Boolean(signalCode) || processState === "zombie";
+}
+
+/** @param {ChildProcessSettlementOptions["readExitState"]} reader @returns {{ code: number | null, signal: string | null }} */
+function safeExitState(reader) {
+  if (typeof reader !== "function") return { code: null, signal: null };
+  try {
+    const value = reader();
+    const code = value?.code;
+    const signal = value?.signal;
+    return {
+      code: typeof code === "number" && Number.isInteger(code) ? code : null,
+      signal: typeof signal === "string" && signal ? signal : null,
+    };
+  } catch {
+    return { code: null, signal: null };
+  }
+}

package/src/local/cli-account-admin.mjs

@@ -1,5 +1,7 @@
 import { AccountAdminClient, accountRoleNames, generateAccountPassword } from "./account-admin.mjs";
+import { createDeviceSessionForRoot } from "./device-root-provider.mjs";
 import { loadState } from "./state.mjs";
+import { packageVersion } from "./package-identity.mjs";
 
 export function createAccountCommand({ chooseWorkspace, confirm }) {
   if (typeof chooseWorkspace !== "function" || typeof confirm !== "function") {
@@ -8,7 +10,7 @@ export function createAccountCommand({ chooseWorkspace, confirm }) {
   return async function accountCommand(args) {
     const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
     const state = loadState(workspace, { stateDir: args.stateDir });
-    const client = accountAdminClient(state);
+    const client = await accountAdminClient(state);
     const action = String(args._[0] || "list").toLowerCase();
     const result = await performAccountAction({ action, args, client, confirm });
     if (result === null) return;
@@ -17,15 +19,36 @@ export function createAccountCommand({ chooseWorkspace, confirm }) {
   };
 }
 
-export function accountAdminClient(state) {
-  if (!state.worker?.url || !state.worker?.accountAdminSecret) {
+export async function accountAdminClient(state, sessionIdentity = null) {
+  if (!state.worker?.url || !state.worker?.deviceIdentity) {
     throw new Error("account administration requires a deployed Worker; run machine-mcp first");
   }
-  return new AccountAdminClient({ workerUrl: state.worker.url, adminSecret: state.worker.accountAdminSecret });
+  const identity = sessionIdentity || await createDeviceSessionForRoot(
+    state.worker.deviceIdentity,
+    state.worker.url,
+    "machine-bridge-mcp",
+    currentPackageVersion(),
+    { profileDir: state.paths.profileDir, reason: "Authorize Machine Bridge account administration" },
+  );
+  return new AccountAdminClient({ workerUrl: state.worker.url, sessionIdentity: identity });
+}
+
+function currentPackageVersion() {
+  return packageVersion;
 }
 
 async function performAccountAction({ action, args, client, confirm }) {
   if (action === "list") return client.list();
+  if (action === "clients") return client.listClients();
+  if (action === "revoke-client") {
+    const clientId = String(args._[1] || "");
+    if (!clientId) throw new Error("account revoke-client requires CLIENT_ID");
+    if (!args.yes && !(await confirm(`Revoke OAuth client ${clientId}?`, false))) {
+      console.log("Client revocation cancelled.");
+      return null;
+    }
+    return client.removeClient({ clientId });
+  }
   if (action === "add") {
     const name = args._[1];
     const role = args._[2];
@@ -56,10 +79,21 @@ async function performAccountAction({ action, args, client, confirm }) {
     }
     return client.remove({ accountId: account.account_id });
   }
-  throw new Error("Unknown account action. Use list, add, role, enable, disable, rotate-password, or remove.");
+  throw new Error("Unknown account action. Use list, clients, revoke-client, add, role, enable, disable, rotate-password, or remove.");
 }
 
 function printAccountResult(action, result) {
+  if (action === "clients") {
+    if (!result.clients.length) {
+      console.log("No OAuth clients configured.");
+      return;
+    }
+    for (const client of result.clients) {
+      const registration = client.registration_current === true ? "current" : "stale";
+      console.log(`${client.client_name}\t${client.trusted_role || "untrusted"}\t${client.client_id}\taccess=${client.active_access_tokens} refresh=${client.active_refresh_tokens} registration=${registration}`);
+    }
+    return;
+  }
   if (action === "list") {
     if (!result.accounts.length) {
       console.log("No accounts configured.");
@@ -75,5 +109,5 @@ function printAccountResult(action, result) {
     process.stdout.write(`Password: ${result.password}\n`);
     console.log("Save this password now; it is not stored locally or shown again. Do not share this terminal output.");
   }
-  if (result.removed) console.log("Account removed.");
+  if (result.removed) console.log(action === "revoke-client" ? "OAuth client revoked." : "Account removed.");
 }

package/src/local/cli-activate.mjs

@@ -0,0 +1,162 @@
+import { acquireDaemonLockWithTakeover, inspectWorkspaceDaemon } from "./daemon-process.mjs";
+import { effectiveLogFormat, effectiveLogLevel } from "./cli-options.mjs";
+import { createLogger } from "./log.mjs";
+import { activatePersistentRuntime } from "./runtime-activation.mjs";
+import { autostartStatus, installAutostart, startAutostart, stopAutostart } from "./service.mjs";
+import { startOwnedServiceRuntime } from "./service-runtime.mjs";
+import { acquireMachineServiceLockWithWait, acquireStartupLockWithWait, daemonLockPathForState, loadState, readDaemonLockOwner } from "./state.mjs";
+import { workerHealth } from "./worker-health.mjs";
+
+export function createActivateCommand({
+  chooseWorkspace,
+  prepareRemoteState,
+  createRemoteRuntime,
+  currentPackageVersion,
+  assertNodeVersion,
+  structuredLogger,
+} = {}) {
+  for (const [name, value] of Object.entries({
+    chooseWorkspace,
+    prepareRemoteState,
+    createRemoteRuntime,
+    currentPackageVersion,
+    assertNodeVersion,
+    structuredLogger,
+  })) {
+    if (typeof value !== "function") throw new TypeError(`activate command requires ${name}`);
+  }
+
+  return async function activateCommand(args) {
+    assertNodeVersion();
+    const logger = createLogger({
+      level: args.json ? "error" : effectiveLogLevel(args),
+      format: effectiveLogFormat(args),
+      component: "activate",
+    });
+    const workspace = await chooseWorkspace(args, { promptOnFirstRun: false, save: true, allowPositional: true });
+    let state = loadState(workspace, { stateDir: args.stateDir });
+    if (!state.worker?.url) {
+      throw new Error("activate requires an existing deployment; run machine-mcp once interactively before persistent activation");
+    }
+    const activationArgs = { ...args, noAutostart: true, daemonOnly: false };
+    const expectedVersion = currentPackageVersion();
+    const result = await activatePersistentRuntime({
+      expectedVersion,
+      acquireStartupLock: async () => {
+        const lock = await acquireStartupLockWithWait(state, { operation: "activate", logger });
+        try {
+          state = loadState(workspace, { stateDir: args.stateDir });
+          if (!state.worker?.url) throw new Error("activate requires an existing deployment; run machine-mcp once interactively before persistent activation");
+          return lock;
+        } catch (error) {
+          lock.release();
+          throw error;
+        }
+      },
+      acquireServiceLock: () => acquireMachineServiceLockWithWait({ operation: "activate", logger }),
+      inspectActivationOwnership: async () => {
+        const daemon = inspectWorkspaceDaemon(state);
+        const owner = daemon.alive && daemon.verified_service_daemon
+          ? readDaemonLockOwner(daemonLockPathForState(state))
+          : null;
+        return {
+          daemon,
+          provider: await autostartStatus(),
+          previousRuntime: owner ? { version: owner.version, entryScript: owner.entryScript } : null,
+        };
+      },
+      stopAutostart: () => stopAutostart({ logger: structuredLogger(true) }),
+      acquireDaemonLock: () => acquireDaemonLockWithTakeover(state, {
+        takeOverServiceOwner: true,
+        ownerMetadata: { mode: "foreground", version: expectedVersion },
+        logger,
+      }),
+      prepareRemoteState: ({ onRemotePrepared } = {}) => prepareRemoteState({
+        args: activationArgs,
+        workspace,
+        state,
+        logger,
+        onRemotePrepared,
+        // Candidate activation requires an existing deployment. Do not repeat
+        // first-run account provisioning after Worker convergence: that extra
+        // admin-auth round trip can fail independently before relay readiness.
+        provisionInitialOwner: false,
+      }),
+      repairRemoteState: async ({ onRemotePrepared } = {}) => {
+        logger.warn("candidate device authentication was rejected; redeploying the same Worker once with the current device identity");
+        return prepareRemoteState({
+          args: { ...activationArgs, forceWorker: true, rotateSecrets: false },
+          workspace,
+          state,
+          logger,
+          onRemotePrepared,
+          provisionInitialOwner: false,
+        });
+      },
+      createRuntime: ({ daemonLock, readiness }) => createRemoteRuntime({
+        args: activationArgs,
+        workspace,
+        state,
+        daemonLock,
+        deviceSessionIdentity: readiness.deviceSessionIdentity,
+        exitOnTerminal: false,
+      }),
+      installAutostart: ({ deferOwnerCommit } = {}) => {
+        if (deferOwnerCommit !== true) throw new Error("persistent activation requires deferred service-owner commit");
+        return installAutostart({
+          workspace,
+          stateRoot: state.paths.stateRoot,
+          entryScript: process.argv[1],
+          version: expectedVersion,
+          logger: structuredLogger(true),
+          deferOwnerCommit: true,
+        });
+      },
+      startAutostart: ({ owner } = {}) => {
+        if (!owner || owner.status !== "pending") throw new Error("persistent activation requires the pending candidate service owner");
+        return startOwnedServiceRuntime({ logger: structuredLogger(true), owner });
+      },
+      startRecoveryAutostart: () => startAutostart({ logger: structuredLogger(true) }),
+      restorePreviousAutostart: () => startAutostart({ logger: structuredLogger(true) }),
+      inspectCandidateAutostart: () => inspectWorkspaceDaemon(state, {
+        expectedVersion, expectedEntryScript: process.argv[1],
+      }),
+      inspectPreviousAutostart: (identity) => inspectWorkspaceDaemon(state, {
+        expectedVersion: identity.version, expectedEntryScript: identity.entryScript,
+      }),
+      inspectDaemon: async () => inspectWorkspaceDaemon(state, {
+        expectedVersion, expectedEntryScript: process.argv[1],
+      }),
+      checkWorker: async () => workerHealth(state.worker.url, expectedVersion, { expectedWorkerName: state.worker.name }),
+    });
+    const convergence = result.convergence;
+    const payload = {
+      ok: true,
+      version: expectedVersion,
+      workspace: state.workspace.path,
+      worker: { name: state.worker.name, url: state.worker.url, health: convergence.worker },
+      daemon: convergence.daemon,
+      service: result.serviceStart,
+      candidate_relay_verified_before_handoff: result.candidateRelayVerified,
+      candidate_auth_recovery_redeployed: result.candidateRecoveryRedeployed,
+      activation_recovered: result.activationRecovered === true,
+      activation_recovery_reason: result.activationRecovered === true ? result.recoveryReason : null,
+      activation_recovery_detail: result.activationRecovered === true ? result.recoveryDetail : null,
+    };
+    if (args.json) console.log(JSON.stringify(payload, null, 2));
+    else {
+      if (result.activationRecovered === true) {
+        logger.warn(`persistent activation completed through verified candidate-service recovery (${result.recoveryReason}): ${result.recoveryDetail}`);
+      }
+      logger.success(`Persistent runtime activated: ${expectedVersion}`);
+      logger.safePlain(`  Worker: ${state.worker.name}`);
+      logger.safePlain(`  Daemon: pid ${convergence.daemon.pid}`);
+      logger.safePlain("  Candidate relay readiness was verified before the login service handoff.");
+      if (result.activationRecovered === true) {
+        logger.safePlain("  The exact candidate login service was independently verified after the foreground candidate ended.");
+      }
+      logger.safePlain("  The login service now owns the daemon; the activation terminal may close.");
+    }
+    return payload;
+  };
+}

package/src/local/cli-local-admin.mjs

@@ -1,14 +1,15 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
 import { join, resolve } from "node:path";
 import process from "node:process";
 import { createLogger } from "./log.mjs";
 import { inspectResourceFile, loadManagedJobPlan, ManagedJobManager, publicResourceRegistry, validateResourceName } from "./managed-jobs.mjs";
 import { generateRegisteredSshKey } from "./resource-operations.mjs";
-import { readBoundedRegularFileSync } from "./secure-file.mjs";
 import {
-  acquireStartupLockWithWait, expandHome, loadState, ownerOnlyFile, packageRoot, saveState,
+  acquireStartupLockWithWait, defaultStateRoot, expandHome, loadState, saveState,
 } from "./state.mjs";
+import { readBrowserPairing, readBrowserPairingPort } from "./browser-pairing-store.mjs";
+import { startBrowserPairingLaunch } from "./browser-pairing-launch.mjs";
+import { browserExtensionPathForRuntime } from "./browser-extension-path.mjs";
 import { resolvePolicy } from "./cli-policy.mjs";
 import { readLoopbackJson } from "./loopback-health.mjs";
 
@@ -18,7 +19,7 @@ export function createLocalAdminCommands(dependencies) {
   if (typeof chooseWorkspace !== "function" || typeof confirm !== "function") {
     throw new TypeError("local admin commands require chooseWorkspace and confirm dependencies");
   }
-  const context = Object.freeze({ chooseWorkspace, confirm });
+  const context = Object.freeze({ chooseWorkspace, confirm, openExternal: dependencies.openExternal || openExternal });
   return Object.freeze({
     resourceCommand: (args) => resourceCommand(args, context),
     browserCommand: (args) => browserCommand(args, context),
@@ -197,7 +198,8 @@ async function browserCommand(args, dependencies) {
 }
 
 function browserPathAction(args) {
-  const extensionPath = resolve(packageRoot, "browser-extension");
+  const stateRoot = resolve(expandHome(args.stateDir || defaultStateRoot()));
+  const extensionPath = browserExtensionPathForRuntime({ stateRoot });
   if (args.json) console.log(JSON.stringify({ extension_path: extensionPath }, null, 2));
   else console.log(extensionPath);
 }
@@ -207,46 +209,32 @@ async function browserStatusAction(args, { chooseWorkspace }) {
   renderBrowserStatus(context.result, args.json === true);
 }
 
-async function browserPairAction(args, { chooseWorkspace }) {
+async function browserPairAction(args, { chooseWorkspace, openExternal: openTarget }) {
   const context = await browserCommandContext(args, chooseWorkspace);
   if (!context.result.running) throw new Error("browser bridge is not reachable; keep machine-mcp running and retry");
-  await openExternal(context.pairingUrl);
+  const pairing = readBrowserPairing(context.stateRoot);
+  if (!pairing || pairing.port !== context.port) throw new Error("browser pairing state changed; retry setup");
+  const launch = await startBrowserPairingLaunch({ brokerPort: pairing.port, extensionToken: pairing.extensionToken });
+  try { await openTarget(launch.url); } catch (error) { launch.close(); throw error; }
   if (args.json) {
     console.log(JSON.stringify({ ...context.result, pairing_page_opened: true }, null, 2));
     return;
   }
   console.log(`Extension path: ${context.extensionPath}`);
   console.log("Load this directory in the Chromium profile you use every day; Machine Bridge does not install it into Playwright or a separate automation profile.");
-  console.log("Enable Developer mode, choose Load unpacked, and reload the extension after each Machine Bridge upgrade.");
+  console.log("Enable Developer mode, choose Load unpacked once, and reload the same path after each Machine Bridge upgrade. Older local-candidate installs may need one Load unpacked migration to this stable path.");
   console.log(`Pairing page opened: ${context.pairingUrl}`);
 }
 
 async function browserCommandContext(args, chooseWorkspace) {
-  const extensionPath = resolve(packageRoot, "browser-extension");
   const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
   const state = loadState(workspace, { stateDir: args.stateDir });
-  const pairingFile = join(state.paths.stateRoot, "browser-bridge.json");
-  if (!existsSync(pairingFile)) {
-    throw new Error("browser bridge is not initialized; start machine-mcp once, then run this command again");
-  }
-  ownerOnlyFile(pairingFile);
-  const pairing = readBrowserPairingState(pairingFile);
-  const pairingUrl = `http://127.0.0.1:${pairing.port}/pair`;
-  const health = await readBrowserHealth(`http://127.0.0.1:${pairing.port}/healthz`);
-  return { extensionPath, pairingUrl, result: browserStatusResult(health, extensionPath, pairingUrl) };
-}
-
-function readBrowserPairingState(pairingFile) {
-  let pairing;
-  try {
-    pairing = JSON.parse(readBoundedRegularFileSync(pairingFile, 64 * 1024).toString("utf8"));
-  } catch {
-    throw new Error("browser bridge state is invalid; restart machine-mcp to repair it");
-  }
-  const port = Number(pairing.port);
-  if (!/^[A-Za-z0-9_-]{32,100}$/.test(String(pairing.token || ""))) throw new Error("browser bridge state contains an invalid token");
-  if (!Number.isInteger(port) || port < 1024 || port > 65535) throw new Error("browser bridge state contains an invalid port");
-  return { port };
+  const extensionPath = browserExtensionPathForRuntime({ stateRoot: state.paths.stateRoot });
+  const port = readBrowserPairingPort(state.paths.stateRoot);
+  if (port === null) throw new Error("browser bridge is not initialized; start machine-mcp once, then run this command again");
+  const pairingUrl = `http://127.0.0.1:${port}/pair`;
+  const health = await readBrowserHealth(`http://127.0.0.1:${port}/healthz`);
+  return { extensionPath, pairingUrl, port, stateRoot: state.paths.stateRoot, result: browserStatusResult(health, extensionPath, pairingUrl) };
 }
 
 function readBrowserHealth(healthUrl) {
@@ -302,7 +290,7 @@ function openExternal(target) {
   });
 }
 
-async function jobCommand(args, { chooseWorkspace, confirm }) {
+async function jobCommand(args, { chooseWorkspace }) {
   const action = String(args._[0] || "list").toLowerCase();
   const workspace = await chooseWorkspace({ ...args, _: [] }, { promptOnFirstRun: false, save: false, allowPositional: false });
   const state = loadState(workspace, { stateDir: args.stateDir });
@@ -320,19 +308,6 @@ async function jobCommand(args, { chooseWorkspace, confirm }) {
   else if (action === "read") result = manager.read({ job_id: args._[1] });
   else if (action === "inspect") result = manager.inspectLocal({ job_id: args._[1] });
   else if (action === "cancel") result = manager.cancel({ job_id: args._[1] });
-  else if (action === "approve") {
-    if (args.json && !args.yes) throw new Error("job approve --json requires --yes");
-    const inspection = manager.inspectLocal({ job_id: args._[1] });
-    if (!args.yes) {
-      console.log(JSON.stringify(inspection, null, 2));
-      const approved = await confirm(`Approve and execute managed job ${args._[1]}?`, false);
-      if (!approved) {
-        console.log("Managed job approval cancelled. Re-run with --yes after review to skip confirmation.");
-        return;
-      }
-    }
-    result = manager.approve({ job_id: args._[1] }, { localOperator: true });
-  }
   else if (action === "submit") {
     const planPath = args._[1];
     if (!planPath) throw new Error("job submit requires a JSON plan file");