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

package/src/local/tools.mjs

@@ -1,5 +1,6 @@
 import serverMetadata from "../shared/server-metadata.json" with { type: "json" };
 import { projectMcpResult } from "../shared/result-projection.mjs";
+import { completeResult } from "../shared/mcp-protocol.mjs";
 export {
   DEFAULT_POLICY_PROFILE,
   DEFAULT_POLICY_REVISION,
@@ -10,6 +11,7 @@ export {
   allToolNames,
   assertCanonicalFullPolicy,
   assertToolAllowed,
+  intersectPolicies,
   isCanonicalFullPolicy,
   normalizePolicy,
   policyAllowsAvailability,
@@ -26,13 +28,13 @@ export const MCP_PROTOCOL_VERSION = String(serverMetadata.protocolVersion);
 export const MCP_SUPPORTED_PROTOCOL_VERSIONS = Object.freeze(serverMetadata.supportedProtocolVersions.map((value) => String(value)));
 export const MCP_INSTRUCTIONS = Object.freeze(serverMetadata.instructions.map((value) => String(value))).join("\n");
 
-export function toolResult(value, isError = false) {
+export function toolResult(value, isError = false, serverInfo) {
   const special = specialMcpResult(value);
-  if (special) return { ...special, isError };
+  if (special) return completeResult({ ...special, isError }, serverInfo);
   const projection = projectMcpResult(value);
   const result = { content: [{ type: "text", text: projection.text }], isError };
-  if (projection.structuredContent) result.structuredContent = projection.structuredContent;
-  return result;
+  if (projection.hasStructuredContent) result.structuredContent = structuredClone(projection.structuredContent);
+  return completeResult(result, serverInfo);
 }
 
 export function rpcResult(id, result) {
@@ -50,7 +52,7 @@ function specialMcpResult(value) {
   const special = value && typeof value === "object" && !Array.isArray(value) ? value.$mcp : null;
   if (!special || typeof special !== "object" || !Array.isArray(special.content)) return null;
   const result = { content: structuredClone(special.content) };
-  if (special.structuredContent && typeof special.structuredContent === "object" && !Array.isArray(special.structuredContent)) {
+  if (Object.prototype.hasOwnProperty.call(special, "structuredContent")) {
     result.structuredContent = structuredClone(special.structuredContent);
   }
   return result;

package/src/local/trusted-executable.mjs

@@ -0,0 +1,53 @@
+import { accessSync, constants as fsConstants, realpathSync, statSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { BridgeError } from "./errors.mjs";
+
+export function resolveTrustedExecutable(options = {}) {
+  const platform = String(options.platform || process.platform);
+  const candidates = Array.isArray(options.candidates) ? options.candidates : [];
+  const deniedRoots = [options.workspace, options.stateRoot, options.runtimeDir, options.home || safeHome()]
+    .filter(Boolean).map((value) => canonicalOrResolved(String(value), options.realpath || realpathSync));
+  const realpath = options.realpath || realpathSync;
+  const stat = options.stat || statSync;
+  const access = options.access || accessSync;
+  for (const candidate of candidates) {
+    if (!path.isAbsolute(String(candidate || ""))) continue;
+    let canonical;
+    let info;
+    try {
+      canonical = realpath(String(candidate));
+      info = stat(canonical);
+      if (!info.isFile()) continue;
+      if (platform !== "win32") access(canonical, fsConstants.X_OK);
+    } catch { continue; }
+    if (platform !== "win32" && (Number(info.mode) & 0o022) !== 0) continue;
+    if (deniedRoots.some((root) => isWithin(canonical, root, platform))) continue;
+    return canonical;
+  }
+  const label = String(options.label || "required executable").replace(/[^A-Za-z0-9._ -]/g, "").trim() || "required executable";
+  const reason = String(options.reason || "trusted_executable_unavailable").replace(/[^A-Za-z0-9_-]/g, "_");
+  throw new BridgeError("unavailable", `trusted ${label} is unavailable`, { details: { reason, platform } });
+}
+
+export function createTrustedExecutableResolver(options = {}) {
+  const injected = typeof options.resolve === "function" ? options.resolve : null;
+  let cached = "";
+  return () => {
+    if (cached) return cached;
+    cached = String(injected ? injected() : resolveTrustedExecutable(options));
+    if (!path.isAbsolute(cached)) throw new BridgeError("unavailable", `trusted ${options.label || "executable"} is unavailable`);
+    return cached;
+  };
+}
+
+function canonicalOrResolved(value, realpath) {
+  try { return realpath(path.resolve(value)); } catch { return path.resolve(value); }
+}
+function isWithin(candidate, root, platform) {
+  const left = platform === "win32" ? candidate.toLowerCase() : candidate;
+  const right = platform === "win32" ? root.toLowerCase() : root;
+  const relative = path.relative(right, left);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function safeHome() { try { return os.homedir(); } catch { return ""; } }

package/src/local/trusted-git-executable.mjs

@@ -0,0 +1,34 @@
+import path from "node:path";
+import { createTrustedExecutableResolver, resolveTrustedExecutable } from "./trusted-executable.mjs";
+
+export function resolveTrustedGitExecutable(options = {}) {
+  const platform = String(options.platform || process.platform);
+  return resolveTrustedExecutable({
+    ...options,
+    platform,
+    label: "Git executable",
+    reason: "trusted_git_executable_unavailable",
+    candidates: Array.isArray(options.candidates) ? options.candidates : defaultGitCandidates(platform, options.env || process.env),
+  });
+}
+
+export function createTrustedGitResolver(options = {}) {
+  const platform = String(options.platform || process.platform);
+  return createTrustedExecutableResolver({
+    ...options,
+    platform,
+    label: "Git executable",
+    reason: "trusted_git_executable_unavailable",
+    candidates: Array.isArray(options.candidates) ? options.candidates : defaultGitCandidates(platform, options.env || process.env),
+  });
+}
+
+function defaultGitCandidates(platform, env) {
+  if (platform === "win32") {
+    return [env.ProgramFiles, env["ProgramFiles(x86)"]]
+      .filter(Boolean)
+      .flatMap((root) => [path.join(root, "Git", "cmd", "git.exe"), path.join(root, "Git", "bin", "git.exe")]);
+  }
+  if (platform === "darwin") return ["/usr/bin/git", "/opt/homebrew/bin/git", "/usr/local/bin/git"];
+  return ["/usr/bin/git", "/bin/git", "/usr/local/bin/git"];
+}

package/src/local/trusted-github-cli.mjs

@@ -0,0 +1,24 @@
+import path from "node:path";
+import { resolveTrustedExecutable } from "./trusted-executable.mjs";
+
+export function resolveTrustedGithubCli(options = {}) {
+  const platform = String(options.platform || process.platform);
+  return resolveTrustedExecutable({
+    ...options,
+    platform,
+    label: "GitHub CLI executable",
+    reason: "trusted_github_cli_unavailable",
+    candidates: Array.isArray(options.candidates) ? options.candidates : githubCliCandidates(platform, options.env || process.env),
+  });
+}
+
+function githubCliCandidates(platform, env) {
+  if (platform === "win32") {
+    return [
+      env.ProgramFiles && path.join(env.ProgramFiles, "GitHub CLI", "gh.exe"),
+      env.LOCALAPPDATA && path.join(env.LOCALAPPDATA, "Programs", "GitHub CLI", "gh.exe"),
+    ].filter(Boolean);
+  }
+  if (platform === "darwin") return ["/opt/homebrew/bin/gh", "/usr/local/bin/gh", "/usr/bin/gh"];
+  return ["/usr/bin/gh", "/usr/local/bin/gh", "/snap/bin/gh"];
+}

package/src/local/windows-service-convergence.mjs

@@ -0,0 +1,49 @@
+// @ts-check
+
+import { waitForStableActiveStatus } from "./service-convergence.mjs";
+
+/** @typedef {{ statusAttempts?: unknown, statusDelayMs?: unknown, stableSamples?: unknown, sleep?: (milliseconds: number) => Promise<void> }} WindowsConvergenceOptions */
+/** @typedef {Record<string, unknown> & { active?: boolean }} WindowsStatus */
+
+/** @param {() => WindowsStatus | Promise<WindowsStatus>} readStatus @param {WindowsConvergenceOptions} [options] */
+export async function stableWindowsStatus(readStatus, options = {}) {
+  if (typeof readStatus !== "function") throw new TypeError("Windows status reader is required");
+  return waitForStableActiveStatus(readStatus, {
+    attempts: boundedPositiveInteger(options.statusAttempts, 10),
+    delayMs: boundedPositiveInteger(options.statusDelayMs, 100),
+    stableSamples: boundedPositiveInteger(options.stableSamples, 5),
+    sleep: typeof options.sleep === "function" ? options.sleep : undefined,
+  });
+}
+
+/** @param {() => WindowsStatus | Promise<WindowsStatus>} readStatus @param {(status: WindowsStatus) => boolean} predicate @param {WindowsConvergenceOptions} [options] */
+export async function waitForWindowsStatus(readStatus, predicate, options = {}) {
+  if (typeof readStatus !== "function") throw new TypeError("Windows status reader is required");
+  if (typeof predicate !== "function") throw new TypeError("Windows status predicate is required");
+  const attempts = boundedPositiveInteger(options.statusAttempts, 10);
+  const delayMs = boundedPositiveInteger(options.statusDelayMs, 100);
+  const sleep = typeof options.sleep === "function"
+    ? options.sleep
+    : (/** @type {number} */ milliseconds) => new Promise(resolve => { setTimeout(resolve, milliseconds); });
+  let status = await readStatus();
+  for (let index = 1; index < attempts && !predicate(status); index += 1) {
+    await sleep(delayMs);
+    status = await readStatus();
+  }
+  return status;
+}
+
+/** @param {WindowsConvergenceOptions} [options] */
+export function windowsStatusWaitOptions(options = {}) {
+  return {
+    attempts: boundedPositiveInteger(options.statusAttempts, 10),
+    delayMs: boundedPositiveInteger(options.statusDelayMs, 100),
+    sleep: typeof options.sleep === "function" ? options.sleep : undefined,
+  };
+}
+
+/** @param {unknown} value @param {number} fallback */
+export function boundedPositiveInteger(value, fallback) {
+  const number = Number(value);
+  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
+}

package/src/local/windows-service.mjs

@@ -1,11 +1,8 @@
 import { waitForInactiveStatus } from "./service-convergence.mjs";
-import {
-  windowsLauncherPath, windowsTaskAction, writeWindowsLauncher,
-} from "./windows-launcher.mjs";
-export {
-  windowsBatchArgument, windowsCommandLineArgument, windowsLauncherContent,
-  windowsLauncherPath, windowsTaskAction, writeWindowsLauncher,
-} from "./windows-launcher.mjs";
+import { stableWindowsStatus, waitForWindowsStatus, windowsStatusWaitOptions } from "./windows-service-convergence.mjs";
+import { windowsLauncherPath, windowsTaskAction, writeWindowsLauncher } from "./windows-launcher.mjs";
+import { removeServiceDefinitionIfCurrent, snapshotServiceDefinition } from "./service-definition.mjs";
+export { windowsBatchArgument, windowsCommandLineArgument, windowsLauncherContent, windowsLauncherPath, windowsTaskAction, writeWindowsLauncher } from "./windows-launcher.mjs";
 
 export const WINDOWS_TASK = "MachineBridgeMCP";
 const WINDOWS_STATUS_SCRIPT = [
@@ -28,7 +25,9 @@ export async function installWindowsTask(spec, logger = console, options = {}) {
     "/RL", "LIMITED",
     "/F",
   ]);
-  const status = await waitForWindowsStatus(value => value.installed === true, { ...options, run });
+  const status = await waitForWindowsStatus(
+    () => statusWindowsTask({ ...options, run }), value => value.installed === true, options,
+  );
   const ok = create?.code === 0 && status.installed === true;
   if (ok) logger.info?.("Windows Scheduled Task installed for user logon");
   else logger.warn?.("Windows Scheduled Task installation failed", { reason: windowsServiceFailureReason(create, status) });
@@ -50,24 +49,46 @@ export async function startWindowsTask(logger = console, options = {}) {
   const before = await statusWindowsTask({ ...options, run });
   if (before.installed === null) return { ok: false, provider: "schtasks", task: WINDOWS_TASK, reason: "task_status_unavailable", status: before };
   if (before.installed === false) return { ok: false, provider: "schtasks", task: WINDOWS_TASK, reason: "not_installed", status: before };
+  if (before.active === true) {
+    const existing = await stableWindowsStatus(() => statusWindowsTask({ ...options, run }), options);
+    if (existing.stable) {
+      logger.info?.("Windows Scheduled Task is already running");
+      return {
+        ok: true, provider: "schtasks", task: WINDOWS_TASK, installed: true,
+        active_before: true, active: true, already_running: true, reason: "already_running", status: existing.status,
+      };
+    }
+  }
   const command = await run("schtasks", ["/Run", "/TN", WINDOWS_TASK]);
   const after = await waitForWindowsStatus(
-    status => status.active === true || completedSince(before, status),
-    { ...options, run },
+    () => statusWindowsTask({ ...options, run }),
+    status => status.active === true || completedSince(before, status), options,
   );
-  const completed = completedSince(before, after);
-  const ok = after.active === true || completed;
+  const stability = after.active === true
+    ? await stableWindowsStatus(() => statusWindowsTask({ ...options, run }), options)
+    : { stable: false, status: after };
+  const observed = stability.status;
+  const completed = completedSince(before, observed);
+  const ok = stability.stable;
   if (ok) logger.info?.("Windows Scheduled Task started");
-  else logger.warn?.("Windows Scheduled Task did not reach a running or successful completed state");
+  else logger.warn?.("Windows Scheduled Task did not remain active after the start request");
   return {
     ok,
     provider: "schtasks",
     task: WINDOWS_TASK,
     command,
-    status: after,
-    reason: after.active === true ? "started" : completed ? "completed" : "start_not_observed",
+    status: observed,
+    active_before: false,
+    active: observed?.active === true && stability.stable,
+    reason: stability.stable ? "started" : completed ? "completed_without_persistence" : "start_not_stable",
   };
 }
+export async function restartWindowsTask(logger = console, options = {}) {
+  const stopped = await stopWindowsTask(logger, options);
+  if (!stopped.ok) return { ok: false, provider: "schtasks", task: WINDOWS_TASK, reason: "stop_failed", stop: stopped };
+  const started = await startWindowsTask(logger, options);
+  return { ...started, restarted: started.ok === true, stop: stopped };
+}
 
 export async function stopWindowsTask(logger = console, options = {}) {
   const run = requiredRun(options.run);
@@ -81,6 +102,7 @@ export async function stopWindowsTask(logger = console, options = {}) {
       installed: before.installed,
       active_before: false,
       active: false,
+      restore_required: false,
       already_stopped: true,
       reason: before.installed ? "already_stopped" : "not_installed",
       status: before,
@@ -101,6 +123,7 @@ export async function stopWindowsTask(logger = console, options = {}) {
     installed: after?.installed !== false,
     active_before: true,
     active: after?.active !== false,
+    restore_required: ok,
     already_stopped: false,
     command,
     status: after,
@@ -110,17 +133,25 @@ export async function stopWindowsTask(logger = console, options = {}) {
 
 export async function uninstallWindowsTask(logger = console, options = {}) {
   const run = requiredRun(options.run);
+  const launcher = options.stateRoot ? windowsLauncherPath(options.stateRoot) : "";
+  const launcherIdentity = launcher ? snapshotServiceDefinition(launcher, "Windows service launcher") : null;
   const stopped = await stopWindowsTask(logger, { ...options, run });
   if (!stopped.ok) return { ok: false, provider: "schtasks", task: WINDOWS_TASK, stop: stopped, reason: "stop_failed" };
   const command = await run("schtasks", ["/Delete", "/TN", WINDOWS_TASK, "/F"]);
   const status = await waitForWindowsStatus(
-    value => value.installed === false,
-    { ...options, run },
+    () => statusWindowsTask({ ...options, run }), value => value.installed === false, options,
   );
-  const ok = status.installed === false;
-  if (ok) logger.info?.("Windows Scheduled Task removed");
-  else logger.warn?.("Windows Scheduled Task removal could not be verified");
-  return { ok, provider: "schtasks", task: WINDOWS_TASK, stop: stopped, command, status, reason: ok ? "removed" : "removal_not_observed" };
+  const taskRemoved = status.installed === false;
+  if (!taskRemoved) {
+    logger.warn?.("Windows Scheduled Task removal could not be verified");
+    return { ok: false, provider: "schtasks", task: WINDOWS_TASK, stop: stopped, command, status, reason: "removal_not_observed" };
+  }
+  if (launcher && !removeServiceDefinitionIfCurrent(launcher, launcherIdentity, "Windows service launcher")) {
+    logger.warn?.("Windows service launcher changed during removal; the replacement was retained.");
+    return { ok: false, provider: "schtasks", task: WINDOWS_TASK, stop: stopped, command, status, reason: "launcher_changed" };
+  }
+  logger.info?.("Windows Scheduled Task removed");
+  return { ok: true, provider: "schtasks", task: WINDOWS_TASK, stop: stopped, command, status, reason: "removed" };
 }
 
 export async function statusWindowsTask(options = {}) {
@@ -168,32 +199,8 @@ function windowsServiceFailureReason(command, status) {
   return "task_installation_unverified";
 }
 
-async function waitForWindowsStatus(predicate, options) {
-  const attempts = boundedPositiveInteger(options.statusAttempts, 10);
-  const delayMs = boundedPositiveInteger(options.statusDelayMs, 100);
-  const sleep = typeof options.sleep === "function" ? options.sleep : milliseconds => new Promise(resolve => { setTimeout(resolve, milliseconds); });
-  let status = await statusWindowsTask(options);
-  for (let index = 1; index < attempts && !predicate(status); index += 1) {
-    await sleep(delayMs);
-    status = await statusWindowsTask(options);
-  }
-  return status;
-}
-
-function windowsStatusWaitOptions(options) {
-  return {
-    attempts: boundedPositiveInteger(options.statusAttempts, 10),
-    delayMs: boundedPositiveInteger(options.statusDelayMs, 100),
-    sleep: typeof options.sleep === "function" ? options.sleep : undefined,
-  };
-}
 
 function requiredRun(run) {
   if (typeof run !== "function") throw new Error("Windows service command runner is required");
   return run;
 }
-
-function boundedPositiveInteger(value, fallback) {
-  const number = Number(value);
-  return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback;
-}

package/src/local/worker-deployment-fingerprint.mjs

@@ -0,0 +1,102 @@
+import { createHmac } from "node:crypto";
+import { lstatSync, readdirSync, realpathSync } from "node:fs";
+import path, { resolve } from "node:path";
+import { publicDeviceJwkJson } from "./device-identity.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { deploymentDeviceIdentity } from "./state.mjs";
+import { packageRoot } from "./package-identity.mjs";
+
+const MAX_WORKER_DEPLOY_SOURCE_BYTES = 16 * 1024 * 1024;
+const REQUIRED_DEPLOYMENT_PATHS = Object.freeze([
+  "src/worker",
+  "src/shared",
+  "wrangler.jsonc",
+  "tsconfig.json",
+]);
+
+export function workerDeploymentFingerprint(state, options = {}) {
+  const source = workerDeployHashFiles(options.packageRoot || packageRoot);
+  const keyMaterial = [
+    publicDeviceJwkJson(deploymentDeviceIdentity(state)),
+    String(state.worker.oauthTokenVersion || ""),
+  ].join("\0");
+  const fingerprint = createHmac("sha256", keyMaterial);
+  addFingerprintField(fingerprint, "mbm-worker-deploy-v5");
+  addFingerprintField(fingerprint, String(state.worker.name || ""));
+  addFingerprintField(fingerprint, String(source.files.length));
+  for (const file of source.files) {
+    addFingerprintField(fingerprint, path.relative(source.root, file).replaceAll(path.sep, "/"));
+    addFingerprintField(fingerprint, readBoundedRegularFileSync(
+      file,
+      MAX_WORKER_DEPLOY_SOURCE_BYTES,
+      "Worker deployment source",
+      { verifyPathIdentity: true, rejectMultipleLinks: true },
+    ));
+  }
+  return fingerprint.digest("hex");
+}
+
+function addFingerprintField(hash, value) {
+  const bytes = Buffer.isBuffer(value) ? value : Buffer.from(String(value), "utf8");
+  const length = Buffer.alloc(8);
+  length.writeBigUInt64BE(BigInt(bytes.length));
+  hash.update(length);
+  hash.update(bytes);
+}
+
+function workerDeployHashFiles(root) {
+  const canonicalRoot = requireRealDeploymentRoot(root);
+  const files = [];
+  for (const item of REQUIRED_DEPLOYMENT_PATHS) collectRequiredHashPath(canonicalRoot, item, files);
+  return Object.freeze({ root: canonicalRoot, files: files.sort() });
+}
+
+function requireRealDeploymentRoot(root) {
+  const target = resolve(root);
+  let info;
+  try { info = lstatSync(target); }
+  catch (error) {
+    if (error?.code === "ENOENT") throw new Error(`Worker deployment package root is missing: ${target}`);
+    throw error;
+  }
+  if (info.isSymbolicLink() || !info.isDirectory()) {
+    throw new Error(`Worker deployment package root must be a real directory: ${target}`);
+  }
+  return realpathSync(target);
+}
+
+function collectRequiredHashPath(root, relativePath, out) {
+  let current = root;
+  const parts = relativePath.split("/");
+  for (let index = 0; index < parts.length; index += 1) {
+    current = resolve(current, parts[index]);
+    const info = requiredPathInfo(current);
+    if (info.isSymbolicLink()) throw new Error(`Worker deployment source must not be a symbolic link: ${current}`);
+    if (index < parts.length - 1 && !info.isDirectory()) {
+      throw new Error(`Worker deployment source ancestor must be a real directory: ${current}`);
+    }
+  }
+  collectHashFiles(current, out);
+}
+
+function requiredPathInfo(target) {
+  try { return lstatSync(target); }
+  catch (error) {
+    if (error?.code === "ENOENT") throw new Error(`Worker deployment required source is missing: ${target}`);
+    throw error;
+  }
+}
+
+function collectHashFiles(target, out) {
+  const info = requiredPathInfo(target);
+  if (info.isSymbolicLink()) throw new Error(`Worker deployment source must not be a symbolic link: ${target}`);
+  if (info.isFile()) {
+    if (/\.(ts|js|mjs|json|jsonc|yaml|yml|lock)$/.test(target)) out.push(target);
+    return;
+  }
+  if (!info.isDirectory()) throw new Error(`Worker deployment source must be a regular file or directory: ${target}`);
+  for (const entry of readdirSync(target, { withFileTypes: true })) {
+    if (entry.name === "node_modules" || entry.name === ".wrangler" || entry.name.endsWith(".d.ts")) continue;
+    collectHashFiles(resolve(target, entry.name), out);
+  }
+}

package/src/local/worker-deployment.mjs

@@ -1,10 +1,11 @@
-import { createHmac } from "node:crypto";
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import path, { resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
 import { runWrangler } from "./shell.mjs";
-import { packageRoot, saveState } from "./state.mjs";
+import { saveState } from "./state.mjs";
+import { packageRoot } from "./package-identity.mjs";
 import { withWorkerSecretsFile } from "./worker-secret-file.mjs";
-import { publicDeviceJwkJson } from "./device-identity.mjs";
+import { workerDeploymentFingerprint } from "./worker-deployment-fingerprint.mjs";
+export { workerDeploymentFingerprint } from "./worker-deployment-fingerprint.mjs";
 import {
   normalizeWorkerOrigin,
   retryWorkerHealth,
@@ -12,11 +13,24 @@ import {
   workerHealthUserReason,
 } from "./worker-health.mjs";
 
+const DEFAULT_DEPLOYMENT_HEALTH_ATTEMPTS = 20;
+
+async function ensureWranglerAuthenticated({ args, runWranglerFn, stateRoot, logger }) {
+  const whoami = await runWranglerFn(["whoami"], { capture: true, allowFailure: true, stateRoot });
+  if (whoami.code === 0) return;
+  if (args.json) throw workerAuthenticationRequiredError();
+  logger.info?.("Wrangler is not logged in; opening Cloudflare login");
+  await runWranglerFn(["login"], { stateRoot });
+  const verified = await runWranglerFn(["whoami"], { capture: true, allowFailure: true, stateRoot });
+  if (verified.code !== 0) throw workerAuthenticationRequiredError();
+}
+
 export async function ensureWorkerDeployment(state, args = {}, options = {}) {
   const logger = options.logger || console;
   const expectedVersion = options.expectedVersion || currentPackageVersion(options.packageRoot || packageRoot);
   const desiredHash = workerDeploymentFingerprint(state, { packageRoot: options.packageRoot || packageRoot });
   const runWranglerFn = options.runWrangler || runWrangler;
+  const wranglerStateRoot = options.stateRoot || state.paths?.stateRoot;
   const saveStateFn = options.saveState || saveState;
   const retryHealthFn = options.retryHealth || retryWorkerHealth;
   const withSecretsFileFn = options.withSecretsFile || withWorkerSecretsFile;
@@ -24,35 +38,37 @@ export async function ensureWorkerDeployment(state, args = {}, options = {}) {
   const complete = hasCompleteWorkerState(state.worker);
 
   if (!args.forceWorker && !args.rotateSecrets && complete && state.worker.deployHash === desiredHash) {
-    const health = await retryHealthFn(state.worker.url, expectedVersion, options.existingHealthAttempts || 2, healthOptions);
+    const recordedCurrentDeployment = state.worker.deployedVersion === expectedVersion;
+    const attempts = recordedCurrentDeployment
+      ? (options.recordedDeploymentHealthAttempts ?? DEFAULT_DEPLOYMENT_HEALTH_ATTEMPTS)
+      : (options.existingHealthAttempts ?? 2);
+    const health = await retryHealthFn(state.worker.url, expectedVersion, attempts, healthOptions);
     if (health.ok) {
-      logger.success?.("Worker unchanged and healthy", { url: state.worker.url });
+      logger.success?.("Worker unchanged and healthy");
       logger.debug?.("Worker health route", { network_route: health.networkRoute || "unknown" });
       return state.worker;
     }
+    logger.debug?.("Worker health check detail", { health_error: health.error, network_route: health.networkRoute || "unknown" });
+    if (recordedCurrentDeployment) {
+      throw workerVerificationError(health.error, { deploymentSucceeded: false, recordedCurrentDeployment: true });
+    }
     if (!workerHealthRequiresRedeploy(health.error)) {
-      logger.debug?.("Worker health check detail", { health_error: health.error, network_route: health.networkRoute || "unknown" });
       throw workerVerificationError(health.error, { deploymentSucceeded: false });
     }
     logger.warn?.("Recorded Worker is stale; redeploying the same Worker", { reason: workerHealthUserReason(health.error) });
-    logger.debug?.("Worker health check detail", { health_error: health.error, network_route: health.networkRoute || "unknown" });
   }
 
   logger.info?.("Checking Cloudflare Wrangler login");
-  const whoami = await runWranglerFn(["whoami"], { capture: true, allowFailure: true });
-  if (whoami.code !== 0) {
-    logger.info?.("Wrangler is not logged in; opening Cloudflare login");
-    await runWranglerFn(["login"]);
-  }
+  await ensureWranglerAuthenticated({ args, runWranglerFn, stateRoot: wranglerStateRoot, logger });
 
-  logger.info?.("Deploying Cloudflare Worker", { name: state.worker.name });
+  logger.info?.("Deploying Cloudflare Worker");
   const deploy = await withSecretsFileFn(state, secretFile => runWranglerFn([
     "deploy",
     "--name", state.worker.name,
     "--minify",
     "--keep-vars",
     "--secrets-file", secretFile,
-  ], { capture: true }));
+  ], { capture: true, stateRoot: wranglerStateRoot }));
 
   const detectedUrl = extractWorkerUrl(deploy.stdout, state.worker.name) || extractWorkerUrl(deploy.stderr, state.worker.name);
   const recordedUrl = workerUrlMatchesName(state.worker.url, state.worker.name) ? state.worker.url : "";
@@ -68,33 +84,16 @@ export async function ensureWorkerDeployment(state, args = {}, options = {}) {
   state.worker.updatedAt = new Date().toISOString();
   saveStateFn(state);
 
-  const health = await retryHealthFn(state.worker.url, expectedVersion, options.deploymentHealthAttempts || 8, healthOptions);
+  const health = await retryHealthFn(state.worker.url, expectedVersion, options.deploymentHealthAttempts ?? DEFAULT_DEPLOYMENT_HEALTH_ATTEMPTS, healthOptions);
   if (!health.ok) {
     logger.debug?.("Worker post-deployment health detail", { health_error: health.error, network_route: health.networkRoute || "unknown" });
     throw workerVerificationError(health.error, { deploymentSucceeded: true });
   }
-  logger.success?.("Worker ready", { url: state.worker.url, version: health.version });
+  logger.success?.("Worker ready", { version: health.version });
   logger.debug?.("Worker health route", { network_route: health.networkRoute || "unknown" });
   return state.worker;
 }
 
-export function workerDeploymentFingerprint(state, options = {}) {
-  const root = resolve(options.packageRoot || packageRoot);
-  const keyMaterial = [
-    String(state.worker.accountAdminSecret || ""),
-    publicDeviceJwkJson(state.worker.deviceIdentity),
-    String(state.worker.oauthTokenVersion || ""),
-  ].join("\0");
-  const fingerprint = createHmac("sha256", keyMaterial);
-  fingerprint.update("mbm-worker-deploy-v4");
-  fingerprint.update(String(state.worker.name || ""));
-  for (const file of workerDeployHashFiles(root)) {
-    fingerprint.update(path.relative(root, file));
-    fingerprint.update(readFileSync(file, "utf8"));
-  }
-  return fingerprint.digest("hex");
-}
-
 export function extractWorkerUrl(text = "", workerName = "") {
   const candidates = [...String(text).matchAll(/https:\/\/[^\s"'<>]+/g)]
     .map((match) => match[0].replace(/[),.;:!?]+$/, ""));
@@ -119,37 +118,17 @@ export function workerUrlMatchesName(workerUrl, workerName) {
 }
 
 function hasCompleteWorkerState(worker = {}) {
-  return Boolean(worker.url && worker.mcpServerUrl && worker.accountAdminSecret && worker.deviceIdentity && worker.oauthTokenVersion && worker.name);
+  return Boolean(worker.url && worker.mcpServerUrl && worker.deviceIdentity && worker.oauthTokenVersion && worker.name);
 }
 
-function workerDeployHashFiles(root) {
-  const files = [];
-  for (const item of ["src/worker", "src/shared", "wrangler.jsonc", "tsconfig.json"]) {
-    collectHashFiles(resolve(root, item), files);
-  }
-  return files.sort();
-}
-
-function collectHashFiles(target, out) {
-  if (!existsSync(target)) return;
-  const info = statSync(target);
-  if (info.isFile()) {
-    if (/\.(ts|js|mjs|json|jsonc|yaml|yml|lock)$/.test(target)) out.push(target);
-    return;
-  }
-  if (!info.isDirectory()) return;
-  for (const entry of readdirSync(target, { withFileTypes: true })) {
-    if (entry.name === "node_modules" || entry.name === ".wrangler" || entry.name.endsWith(".d.ts")) continue;
-    collectHashFiles(resolve(target, entry.name), out);
-  }
-}
-
-function workerVerificationError(reason, { deploymentSucceeded }) {
+function workerVerificationError(reason, { deploymentSucceeded, recordedCurrentDeployment = false }) {
   const readable = workerHealthUserReason(reason);
   const guidance = workerVerificationGuidance(reason);
   const message = deploymentSucceeded
     ? `Cloudflare reported the Worker deployment succeeded, but ${readable}. The deployment fingerprint was saved, so retrying will verify the same Worker instead of deploying again. ${guidance}`
-    : `The recorded Worker could not be verified because ${readable}. No deployment was attempted. ${guidance}`;
+    : recordedCurrentDeployment
+      ? `The current Worker deployment fingerprint is already recorded, but ${readable}. No deployment was attempted because duplicating the recorded deployment is unsafe; use --force-worker only after diagnosis. ${guidance}`
+      : `The recorded Worker could not be verified because ${readable}. No deployment was attempted. ${guidance}`;
   const error = new Error(message);
   error.code = "worker_health_unverified";
   error.healthError = reason;
@@ -170,6 +149,15 @@ function workerVerificationGuidance(reason) {
   return "Run machine-mcp doctor and inspect the health endpoint before forcing another deployment.";
 }
 
+function workerAuthenticationRequiredError() {
+  const error = new Error(
+    "Cloudflare Wrangler is not authenticated; JSON mode will not start an interactive login. Complete Wrangler authentication in an ordinary owner terminal before retrying.",
+  );
+  error.code = "worker_authentication_required";
+  error.sideEffectsStarted = false;
+  return error;
+}
+
 function currentPackageVersion(root) {
   const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"));
   return String(pkg.version);