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

package/src/local/state.mjs

@@ -1,22 +1,25 @@
 import { createHash, randomBytes } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, realpathSync, rmSync, unlinkSync, readdirSync, statSync } from "node:fs";
+import { existsSync, lstatSync, mkdirSync, realpathSync, unlinkSync, readdirSync, statSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
-import serverMetadata from "../shared/server-metadata.json" with { type: "json" };
-import { replaceFileSync } from "./atomic-fs.mjs";
 import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import { preserveFileSnapshotSync } from "./file-snapshot-preservation.mjs";
 import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
-import { createDeviceIdentity, validateDeviceIdentity } from "./device-identity.mjs";
+import { createDeviceIdentity } from "./device-identity.mjs";
+import { validateDeviceRootIdentity } from "./device-root-provider.mjs";
 import { currentProcessStartTimeMs, inspectProcessInstance } from "./process-identity.mjs";
-import { chmodRegularFileSync, ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "./secure-file.mjs";
+import { ensureOwnerOnlyDir, inspectPathIfPresentSync, ownerOnlyFile, readBoundedRegularFileSync, readBoundedRegularFileWithInfoSync, retryTransientMultipleLinksSync, unlinkRegularFileIfIdentitySync } from "./secure-file.mjs";
+import { isPlainRecord } from "./records.mjs";
+import { exactFilesystemInteger, filesystemIdentity, filesystemTimeMs, sameFilesystemIdentity } from "./filesystem-identity.mjs";
+import { appName, packageRoot } from "./package-identity.mjs";
+import { inspectStateRootGeneration, pruneRetiredStateRootDirectories, removeStateRootGenerationIfCurrent } from "./state-root-retirement.mjs";
+import { validateOwnedStateNamespaces } from "./state-root-owned-namespaces.mjs";
 
-export const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
-export const appName = String(serverMetadata.name);
 const STATE_MARKER = ".machine-bridge-mcp-state";
 const STATE_MARKER_SCHEMA = 2;
 export const STATE_SCHEMA_VERSION = 6;
 const GLOBAL_CONFIG_SCHEMA = 1;
+const RECOVERY_MARKER_SCHEMA = 1;
 const CORRUPT_RECOVERY = Symbol("corrupt-recovery");
 const MAX_STATE_JSON_BYTES = 2 * 1024 * 1024;
 const MAX_LOCK_BYTES = 64 * 1024;
@@ -24,6 +27,7 @@ const MAX_MARKER_BYTES = 4096;
 const STARTUP_LOCK_MAX_AGE_MS = 2 * 60 * 60 * 1000;
 const MALFORMED_LOCK_GRACE_MS = 60_000;
 const MAINTENANCE_LOCK_MAX_AGE_MS = 2 * 60 * 60 * 1000;
+const MACHINE_SERVICE_LOCK_MAX_AGE_MS = 2 * 60 * 60 * 1000;
 
 export function expandHome(input = "") {
   if (!input || input === "~") return os.homedir();
@@ -31,6 +35,12 @@ export function expandHome(input = "") {
   return input;
 }
 
+function expandHomeFrom(input, home) {
+  if (!input || input === "~") return home;
+  if (input.startsWith("~/")) return path.join(home, input.slice(2));
+  return input;
+}
+
 export function resolveWorkspace(input = process.cwd()) {
   const resolved = path.resolve(expandHome(input));
   return realpathSync.native ? realpathSync.native(resolved) : realpathSync(resolved);
@@ -46,13 +56,16 @@ export function ensureWorkspaceDirectory(input) {
   return resolveWorkspace(requested);
 }
 
-export function defaultStateRoot() {
-  if (process.platform === "win32") {
-    const base = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+export function defaultStateRoot(options = {}) {
+  const platform = String(options.platform || process.platform);
+  const home = path.resolve(String(options.home || os.homedir()));
+  const environment = options.environment && typeof options.environment === "object" ? options.environment : process.env;
+  if (platform === "win32") {
+    const base = environment.APPDATA ? expandHomeFrom(String(environment.APPDATA), home) : path.join(home, "AppData", "Roaming");
     return path.join(base, appName);
   }
-  if (process.env.XDG_STATE_HOME) return path.join(expandHome(process.env.XDG_STATE_HOME), appName);
-  return path.join(os.homedir(), ".local", "state", appName);
+  if (environment.XDG_STATE_HOME) return path.join(expandHomeFrom(String(environment.XDG_STATE_HOME), home), appName);
+  return path.join(home, ".local", "state", appName);
 }
 
 
@@ -60,13 +73,16 @@ function configPath(stateRoot = defaultStateRoot()) {
   return path.join(expandHome(stateRoot), "config.json");
 }
 
-export function loadGlobalConfig(stateRoot = defaultStateRoot()) {
+export function loadGlobalConfig(stateRoot = defaultStateRoot(), options = {}) {
   const root = path.resolve(expandHome(stateRoot));
   assertNoForeignMaintenance(root);
   const file = configPath(root);
-  if (!existsSync(file)) return { schemaVersion: GLOBAL_CONFIG_SCHEMA };
+  const inspect = options.inspectPathIfPresentSync || inspectPathIfPresentSync;
+  const info = inspect(file, "global configuration file");
+  if (!info) return { schemaVersion: GLOBAL_CONFIG_SCHEMA };
+  if (info.isSymbolicLink() || !info.isFile()) throw new Error("global configuration file must be a regular file and not a symbolic link");
   ownerOnlyFile(file);
-  const config = readJsonObjectOrBackup(file);
+  const config = readJsonObjectOrBackup(file, { allowEmptyRecovery: true });
   if (config[CORRUPT_RECOVERY]) return { schemaVersion: GLOBAL_CONFIG_SCHEMA };
   if (config.schemaVersion !== GLOBAL_CONFIG_SCHEMA) {
     throw new Error("global configuration schema is obsolete; remove the state root and initialize the current version");
@@ -100,16 +116,21 @@ export function selectedWorkspace(stateRoot = defaultStateRoot()) {
 
 export function validateStateRootForRemoval(stateRoot = defaultStateRoot()) {
   const root = path.resolve(expandHome(stateRoot));
-  if (!existsSync(root)) return { exists: false, root };
+  if (!inspectPathIfPresentSync(root, "state root")) return { exists: false, root };
   const canonical = assertSafeStateRootForRemoval(root);
   return { exists: true, root: canonical };
 }
 
 export function removeStateRoot(stateRoot = defaultStateRoot()) {
-  const validation = validateStateRootForRemoval(stateRoot);
+  const requested = path.resolve(expandHome(stateRoot));
+  pruneRetiredStateRootDirectories(requested, assertSafeStateRootForRemoval);
+  const validation = validateStateRootForRemoval(requested);
   if (!validation.exists) return false;
-  rmSync(validation.root, { recursive: true, force: true });
-  return true;
+  const generation = inspectStateRootGeneration(validation.root);
+  if (removeStateRootGenerationIfCurrent(validation.root, generation, assertSafeStateRootForRemoval)) return true;
+  pruneRetiredStateRootDirectories(requested, assertSafeStateRootForRemoval);
+  if (!inspectPathIfPresentSync(validation.root, "state root")) return false;
+  throw new Error("state root changed during generation-bound removal; state requires inspection");
 }
 
 function workspaceHash(workspace) {
@@ -127,7 +148,7 @@ function profileDirForWorkspace(workspace, stateRoot = defaultStateRoot()) {
 function canonicalizePotentialPath(input) {
   let existing = path.resolve(input);
   const suffix = [];
-  while (!existsSync(existing)) {
+  while (!inspectPathIfPresentSync(existing, "path identity")) {
     const parent = path.dirname(existing);
     if (parent === existing) break;
     suffix.unshift(path.basename(existing));
@@ -149,6 +170,16 @@ function assertStateRootSeparatedFromWorkspace(stateRoot, workspace) {
   }
 }
 
+function samePotentialPathIdentity(left, right) {
+  try {
+    const a = canonicalizePotentialPath(String(left));
+    const b = canonicalizePotentialPath(String(right));
+    return process.platform === "win32" ? a.toLowerCase() === b.toLowerCase() : a === b;
+  } catch {
+    return false;
+  }
+}
+
 function sameWorkspaceIdentity(left, right) {
   try {
     const a = resolveWorkspace(left);
@@ -169,13 +200,24 @@ export function loadState(workspace, options = {}) {
   const profileDir = profileDirForWorkspace(canonicalWorkspace, stateRoot);
   const statePath = path.join(profileDir, "state.json");
   ensureOwnerOnlyDir(profileDir);
+  removeObsoleteOperationLeaseState(profileDir);
+  const recoveryPath = recoveryMarkerPath(statePath);
+  const recoveryPending = Boolean(inspectPathIfPresentSync(recoveryPath, "state recovery marker"));
+  const recoverySnapshot = recoveryPending ? readRecoveryMarker(recoveryPath, statePath) : null;
+  const recoveryMarker = recoverySnapshot?.marker || null;
   let state = {};
-  if (existsSync(statePath)) {
+  if (inspectPathIfPresentSync(statePath, "workspace state")) {
     ownerOnlyFile(statePath);
-    state = readJsonObjectOrBackup(statePath);
-    if (!state[CORRUPT_RECOVERY] && state.schemaVersion !== STATE_SCHEMA_VERSION) {
+    state = readJsonObjectOrBackup(statePath, { recoveryPath });
+    if (state.schemaVersion !== STATE_SCHEMA_VERSION) {
       throw new Error("workspace state schema is obsolete; remove the state root and initialize the current version");
     }
+    assertWorkspaceStateEnvelope(state, { canonicalWorkspace, stateRoot, profileDir, statePath });
+    if (recoverySnapshot && !unlinkRegularFileIfIdentitySync(recoveryPath, recoverySnapshot.identity, "state recovery marker")) {
+      throw new Error("workspace state recovery marker changed before removal");
+    }
+  } else if (recoveryPending) {
+    throw recoveryRequiredError(recoveryMarker);
   }
   state.schemaVersion = STATE_SCHEMA_VERSION;
   state.workspace = {
@@ -185,17 +227,78 @@ export function loadState(workspace, options = {}) {
   };
   state.paths = { stateRoot, profileDir, statePath };
   state.worker ||= {};
+  delete state.worker.accountAdminSecret;
   state.policy ||= {};
   state.resources ||= {};
   return state;
 }
 
+function removeObsoleteOperationLeaseState(profileDir) {
+  const file = path.join(profileDir, "operation-leases.json");
+  const info = inspectPathIfPresentSync(file, "obsolete operation lease state", {
+    lstatSync: (target) => lstatSync(target, { bigint: true }),
+  });
+  if (!info) return false;
+  if (info.isSymbolicLink() || !info.isFile() || info.nlink !== 1n) {
+    throw new Error("obsolete operation lease state must be a single-link regular file before migration cleanup");
+  }
+  const identity = filesystemIdentity(info, "obsolete operation lease state");
+  if (!unlinkRegularFileIfIdentitySync(file, identity, "obsolete operation lease state")) {
+    throw new Error("obsolete operation lease state changed before migration cleanup");
+  }
+  return true;
+}
+
 export function saveState(state) {
-  assertNoForeignMaintenance(state?.paths?.stateRoot);
-  const statePath = state?.paths?.statePath;
-  if (!statePath) throw new Error("state path is missing");
-  ensureOwnerOnlyDir(path.dirname(statePath));
-  atomicWriteJson(statePath, { ...state });
+  const envelope = assertWorkspaceStateEnvelope(state);
+  assertNoForeignMaintenance(envelope.stateRoot);
+  assertValidStateMarker(path.join(envelope.stateRoot, STATE_MARKER));
+  ensureOwnerOnlyDir(envelope.profileDir);
+  atomicWriteJson(envelope.statePath, { ...state });
+  const recoveryPath = recoveryMarkerPath(envelope.statePath);
+  if (inspectPathIfPresentSync(recoveryPath, "state recovery marker")) {
+    const recoverySnapshot = readRecoveryMarker(recoveryPath, envelope.statePath);
+    if (!unlinkRegularFileIfIdentitySync(recoveryPath, recoverySnapshot.identity, "state recovery marker")) {
+      throw new Error("workspace state recovery marker changed before removal");
+    }
+  }
+}
+
+function assertWorkspaceStateEnvelope(state, expected = {}) {
+  if (!isPlainRecord(state) || state.schemaVersion !== STATE_SCHEMA_VERSION) {
+    throw new Error("workspace state envelope is incomplete or uses the wrong schema");
+  }
+  if (!isPlainRecord(state.workspace) || typeof state.workspace.path !== "string" || typeof state.workspace.hash !== "string") {
+    throw new Error("workspace state envelope is missing workspace identity");
+  }
+  if (!isPlainRecord(state.paths) || !isPlainRecord(state.worker) || !isPlainRecord(state.policy) || !isPlainRecord(state.resources)) {
+    throw new Error("workspace state envelope is missing required object fields");
+  }
+  const canonicalWorkspace = resolveWorkspace(expected.canonicalWorkspace || state.workspace.path);
+  const expectedHash = workspaceHash(canonicalWorkspace);
+  if (!sameWorkspaceIdentity(state.workspace.path, canonicalWorkspace) || state.workspace.hash !== expectedHash) {
+    throw new Error("workspace state envelope does not match the selected workspace");
+  }
+  if (typeof state.paths.stateRoot !== "string" || !state.paths.stateRoot
+      || typeof state.paths.profileDir !== "string" || !state.paths.profileDir
+      || typeof state.paths.statePath !== "string" || !state.paths.statePath) {
+    throw new Error("workspace state envelope is missing canonical state paths");
+  }
+  const stateRoot = canonicalizePotentialPath(expected.stateRoot || state.paths.stateRoot);
+  const profileDir = canonicalizePotentialPath(expected.profileDir || state.paths.profileDir);
+  const statePath = canonicalizePotentialPath(expected.statePath || state.paths.statePath);
+  const expectedProfileDir = canonicalizePotentialPath(profileDirForWorkspace(canonicalWorkspace, stateRoot));
+  const expectedStatePath = canonicalizePotentialPath(path.join(expectedProfileDir, "state.json"));
+  if (!samePotentialPathIdentity(profileDir, expectedProfileDir) || !samePotentialPathIdentity(statePath, expectedStatePath)) {
+    throw new Error("workspace state envelope contains inconsistent state paths");
+  }
+  if (!samePotentialPathIdentity(state.paths.stateRoot, stateRoot)
+      || !samePotentialPathIdentity(state.paths.profileDir, profileDir)
+      || !samePotentialPathIdentity(state.paths.statePath, statePath)) {
+    throw new Error("workspace state envelope does not match the active state location");
+  }
+  assertStateRootSeparatedFromWorkspace(stateRoot, canonicalWorkspace);
+  return { canonicalWorkspace, stateRoot, profileDir, statePath };
 }
 
 export function daemonLockPathForState(state) {
@@ -212,9 +315,59 @@ function lockPathForState(state, name) {
   return path.join(profileDir, name);
 }
 
+export function machineServiceControlRoot(options = {}) {
+  const home = path.resolve(String(options.home || os.homedir()));
+  if (options.controlRoot) return path.resolve(expandHomeFrom(String(options.controlRoot), home));
+  if (String(options.platform || process.platform) === "win32") {
+    const environment = options.environment && typeof options.environment === "object" ? options.environment : process.env;
+    const base = environment.APPDATA ? expandHomeFrom(String(environment.APPDATA), home) : path.join(home, "AppData", "Roaming");
+    return path.join(base, `${appName}-control`);
+  }
+  return path.join(home, ".local", "state", `${appName}-control`);
+}
+
+export function machineServiceLockPath(options = {}) {
+  return path.join(machineServiceControlRoot(options), "service-operation.lock");
+}
+
+export function acquireMachineServiceLock(metadata = {}, options = {}) {
+  const root = machineServiceControlRoot(options);
+  ensureOwnerOnlyDir(root);
+  assertNoForeignMaintenance(root);
+  const operation = typeof metadata.operation === "string" && /^[a-z][a-z0-9._-]{0,63}$/.test(metadata.operation)
+    ? metadata.operation
+    : "service-operation";
+  return acquireProcessLock(machineServiceLockPath({ controlRoot: root }), {
+    workspace: { path: "" },
+    paths: { profileDir: root, stateRoot: root },
+  }, "machine-service", { operation }, { maxAgeMs: MACHINE_SERVICE_LOCK_MAX_AGE_MS });
+}
+
+export async function acquireMachineServiceLockWithWait(options = {}) {
+  const timeoutMs = boundedPositiveInteger(options.timeoutMs, 30_000);
+  const pollMs = boundedPositiveInteger(options.pollMs, 100);
+  const logger = options.logger || { info() {} };
+  const metadata = { operation: options.operation };
+  let lock = acquireMachineServiceLock(metadata, options);
+  if (lock.acquired) return lock;
+  logger.info?.("waiting for another process to finish the current machine-service operation");
+  const deadline = createMonotonicDeadline(timeoutMs);
+  while (!deadline.expired()) {
+    await new Promise((resolvePromise) => { setTimeout(resolvePromise, Math.min(pollMs, Math.max(1, deadline.remainingMs()))); });
+    lock = acquireMachineServiceLock(metadata, options);
+    if (lock.acquired) {
+      logger.info?.("the previous machine-service operation finished; continuing");
+      return lock;
+    }
+  }
+  const pid = lock.owner?.pid ? `pid ${lock.owner.pid}` : "unknown pid";
+  const operation = typeof lock.owner?.operation === "string" ? ` (${lock.owner.operation})` : "";
+  throw new Error(`another machine-service operation did not finish within ${Math.ceil(timeoutMs / 1000)} seconds (${pid}${operation}); inspect the process before retrying`);
+}
+
 export function acquireMaintenanceLock(stateRoot, metadata = {}) {
   const root = path.resolve(expandHome(stateRoot));
-  if (!existsSync(root)) throw new Error("cannot acquire maintenance lock for a missing state root");
+  if (!inspectPathIfPresentSync(root, "state root")) throw new Error("cannot acquire maintenance lock for a missing state root");
   const operation = typeof metadata.operation === "string" && /^[a-z][a-z0-9._-]{0,63}$/.test(metadata.operation)
     ? metadata.operation
     : "maintenance";
@@ -231,7 +384,6 @@ export function assertStateMaintenanceAvailable(stateRoot) {
 function assertNoForeignMaintenance(stateRoot) {
   if (!stateRoot) return;
   const file = path.join(path.resolve(expandHome(stateRoot)), "maintenance.lock");
-  if (!existsSync(file)) return;
   const snapshot = readProcessLockSnapshot(file);
   if (!snapshot) return;
   if (!snapshot.owner) {
@@ -256,7 +408,7 @@ function assertNoForeignMaintenance(stateRoot) {
 
 export function acquireDaemonLock(state, metadata = {}) {
   assertNoForeignMaintenance(state?.paths?.stateRoot);
-  const details = {};
+  const details = { startupReady: false, startupReadyAt: null, nodeVersion: process.versions.node };
   if (metadata?.mode === "foreground" || metadata?.mode === "service") details.mode = metadata.mode;
   if (typeof metadata?.version === "string" && /^[0-9A-Za-z.+_-]{1,64}$/.test(metadata.version)) details.version = metadata.version;
   return acquireProcessLock(daemonLockPathForState(state), state, "daemon", details, { maxAgeMs: Number.POSITIVE_INFINITY });
@@ -276,8 +428,7 @@ export async function acquireStartupLockWithWait(state, options = {}) {
   const metadata = { operation: options.operation };
   let lock = acquireStartupLock(state, metadata);
   if (lock.acquired) return lock;
-  const ownerPid = lock.owner?.pid ? `pid ${lock.owner.pid}` : "another process";
-  logger.info?.(`waiting for ${ownerPid} to finish the current startup/state operation`);
+  logger.info?.("waiting for another process to finish the current startup/state operation");
   const deadline = createMonotonicDeadline(timeoutMs);
   while (!deadline.expired()) {
     await new Promise((resolvePromise) => { setTimeout(resolvePromise, Math.min(pollMs, Math.max(1, deadline.remainingMs()))); });
@@ -311,12 +462,17 @@ function acquireProcessLock(lockPath, state, purpose, details = {}, options = {}
       createExclusiveFileSync(lockPath, `${JSON.stringify(payload, null, 2)}
 `, { mode: 0o600 });
       ownerOnlyFile(lockPath);
-      return {
+      const lock = {
         acquired: true,
         path: lockPath,
         owner: payload,
+        update(patch) {
+          lock.owner = updateProcessLock(lockPath, token, patch);
+          return lock.owner;
+        },
         release() { releaseProcessLock(lockPath, token); },
       };
+      return lock;
     } catch (error) {
       if (error?.code !== "EEXIST") throw error;
       const snapshot = readProcessLockSnapshot(lockPath);
@@ -345,26 +501,31 @@ function acquireProcessLock(lockPath, state, purpose, details = {}, options = {}
 }
 
 function readProcessLockSnapshot(lockPath) {
-  let info;
-  try { info = lstatSync(lockPath); } catch (error) {
-    if (error?.code === "ENOENT") return null;
+  let opened;
+  try {
+    opened = retryTransientMultipleLinksSync(() => readBoundedRegularFileWithInfoSync(lockPath, MAX_LOCK_BYTES, "process lock", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    }));
+  } catch (error) {
+    if (error?.code === "ENOENT" || error?.cause?.code === "ENOENT") return null;
     throw error;
   }
-  if (info.isSymbolicLink()) throw new Error(`process lock must not be a symbolic link: ${lockPath}`);
-  if (!info.isFile()) throw new Error(`process lock is not a regular file: ${lockPath}`);
+  const info = lockIdentity(opened.identityInfo, opened.identity);
+  let text;
+  try { text = new TextDecoder("utf-8", { fatal: true }).decode(opened.buffer); }
+  catch { return { owner: null, info }; }
   let owner = null;
   try {
-    const parsed = JSON.parse(readBoundedUtf8(lockPath, MAX_LOCK_BYTES, "lock file"));
+    const parsed = JSON.parse(text);
     if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) owner = parsed;
-  } catch (error) {
-    if (error?.code === "ENOENT") return null;
-  }
-  return { owner, info: lockIdentity(info) };
+  } catch { /* Successfully read malformed JSON remains eligible for bounded stale recovery. */ }
+  return { owner, info };
 }
 
 function removeLockSnapshot(lockPath, snapshot) {
   let current;
-  try { current = lstatSync(lockPath); } catch (error) { return error?.code === "ENOENT"; }
+  try { current = lstatSync(lockPath, { bigint: true }); } catch (error) { return error?.code === "ENOENT"; }
   if (current.isSymbolicLink() || !current.isFile()) return false;
   if (!sameLockIdentity(snapshot.info, lockIdentity(current))) return false;
   if (snapshot.owner?.token) {
@@ -379,17 +540,48 @@ function removeLockSnapshot(lockPath, snapshot) {
   }
 }
 
-function lockIdentity(info) {
+function lockIdentity(info, identity = filesystemIdentity(info, "process lock")) {
   return {
-    dev: Number(info.dev),
-    ino: Number(info.ino),
-    size: Number(info.size),
-    mtimeMs: Number(info.mtimeMs),
+    ...identity,
+    size: exactFilesystemInteger(info.size, "process lock size"),
+    nlink: exactFilesystemInteger(info.nlink, "process lock link count"),
+    mtimeMs: filesystemTimeMs(info.mtimeMs, "process lock modification time"),
   };
 }
 
 function sameLockIdentity(left, right) {
-  return left.dev === right.dev && left.ino === right.ino && left.size === right.size && left.mtimeMs === right.mtimeMs;
+  return sameFilesystemIdentity(left, right) && left.size === right.size && left.mtimeMs === right.mtimeMs;
+}
+
+function updateProcessLock(lockPath, token, patch) {
+  if (!isPlainRecord(patch)) throw new TypeError("process lock update must be a plain record");
+  const allowed = new Set(["startupReady", "startupReadyAt"]);
+  for (const key of Object.keys(patch)) {
+    if (!allowed.has(key)) throw new Error(`process lock field is immutable: ${key}`);
+  }
+  if (patch.startupReady !== true) {
+    throw new TypeError("process lock startup readiness can only be published as true");
+  }
+  if (typeof patch.startupReadyAt !== "string" || !Number.isFinite(Date.parse(patch.startupReadyAt))) {
+    throw new TypeError("process lock startupReadyAt update must be an ISO timestamp");
+  }
+  const snapshot = readProcessLockSnapshot(lockPath);
+  if (!snapshot?.owner || snapshot.owner.token !== token || snapshot.owner.pid !== process.pid) {
+    throw new Error("process lock ownership changed before update");
+  }
+  if (snapshot.owner.purpose !== "daemon") {
+    throw new Error("only daemon locks can publish startup readiness");
+  }
+  if (snapshot.owner.startupReady === true || snapshot.owner.startupReadyAt !== null) {
+    throw new Error("process lock startup readiness was already published");
+  }
+  const updated = { ...snapshot.owner, startupReady: true, startupReadyAt: patch.startupReadyAt };
+  const content = `${JSON.stringify(updated, null, 2)}
+`;
+  if (Buffer.byteLength(content) > MAX_LOCK_BYTES) throw new Error("process lock update exceeds the size limit");
+  replaceFileAtomicallySync(lockPath, content, { mode: 0o600 });
+  ownerOnlyFile(lockPath);
+  return updated;
 }
 
 function releaseProcessLock(lockPath, token) {
@@ -400,12 +592,7 @@ function releaseProcessLock(lockPath, token) {
 }
 
 export function readDaemonLockOwner(lockPath) {
-  try {
-    const parsed = JSON.parse(readBoundedUtf8(lockPath, MAX_LOCK_BYTES, "lock file"));
-    return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : null;
-  } catch {
-    return null;
-  }
+  return readProcessLockSnapshot(lockPath)?.owner || null;
 }
 
 function boundedPositiveInteger(value, fallback) {
@@ -413,17 +600,23 @@ function boundedPositiveInteger(value, fallback) {
   return Number.isFinite(parsed) ? Math.max(1, Math.floor(parsed)) : fallback;
 }
 
-function readBoundedUtf8(filePath, maxBytes, label) {
-  const buffer = readBoundedRegularFileSync(filePath, maxBytes, label);
+function readBoundedUtf8(filePath, maxBytes, label, options = {}) {
+  return decodeUtf8(readBoundedRegularFileSync(filePath, maxBytes, label, options), label);
+}
+
+function decodeUtf8(buffer, label) {
   try {
     return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
-  } catch {
-    throw new Error(`${label} is not valid UTF-8`);
+  } catch (cause) {
+    throw Object.assign(new Error(`${label} is not valid UTF-8`, { cause }), { code: "ERR_INVALID_UTF8" });
   }
 }
 
-function readJsonObjectOrBackup(filePath) {
-  const text = readBoundedUtf8(filePath, MAX_STATE_JSON_BYTES, "state JSON");
+function readJsonObjectOrBackup(filePath, options = {}) {
+  const opened = readBoundedRegularFileWithInfoSync(filePath, MAX_STATE_JSON_BYTES, "state JSON", {
+    verifyPathIdentity: true, rejectMultipleLinks: true,
+  });
+  const text = decodeUtf8(opened.buffer, "state JSON");
   let parsed;
   try {
     parsed = JSON.parse(text);
@@ -431,15 +624,52 @@ function readJsonObjectOrBackup(filePath) {
     return parsed;
   } catch {
     const backupPath = `${filePath}.corrupt-${Date.now()}-${randomBytes(4).toString("hex")}`;
-    replaceFileSync(filePath, backupPath);
+    preserveFileSnapshotSync(filePath, backupPath, opened.buffer, opened.identity, { label: "state JSON", mode: 0o600 });
     ownerOnlyFile(backupPath);
     pruneBackups(filePath, 3);
-    const recovered = {};
-    Object.defineProperty(recovered, CORRUPT_RECOVERY, { value: true });
-    return recovered;
+    if (options.allowEmptyRecovery === true) {
+      const recovered = {};
+      Object.defineProperty(recovered, CORRUPT_RECOVERY, { value: true });
+      return recovered;
+    }
+    const recoveryPath = options.recoveryPath || recoveryMarkerPath(filePath);
+    const marker = { schemaVersion: RECOVERY_MARKER_SCHEMA, backup: path.basename(backupPath), detectedAt: new Date().toISOString() };
+    replaceFileAtomicallySync(recoveryPath, `${JSON.stringify(marker, null, 2)}\n`, { mode: 0o600 });
+    ownerOnlyFile(recoveryPath);
+    throw recoveryRequiredError(marker);
   }
 }
 
+function recoveryMarkerPath(statePath) { return `${statePath}.recovery-required`; }
+
+function readRecoveryMarker(markerPath, statePath) {
+  ownerOnlyFile(markerPath);
+  let opened;
+  let marker;
+  try {
+    opened = readBoundedRegularFileWithInfoSync(markerPath, MAX_MARKER_BYTES, "state recovery marker", {
+      verifyPathIdentity: true, rejectMultipleLinks: true,
+    });
+    marker = JSON.parse(decodeUtf8(opened.buffer, "state recovery marker"));
+  } catch { throw new Error("workspace state recovery marker is invalid; inspect the profile manually before continuing"); }
+  if (marker?.schemaVersion !== RECOVERY_MARKER_SCHEMA || typeof marker.backup !== "string"
+      || !marker.backup.startsWith(`${path.basename(statePath)}.corrupt-`) || path.basename(marker.backup) !== marker.backup
+      || !Number.isFinite(Date.parse(String(marker.detectedAt || "")))) {
+    throw new Error("workspace state recovery marker is invalid; inspect the profile manually before continuing");
+  }
+  return {
+    marker: Object.freeze({ schemaVersion: marker.schemaVersion, backup: marker.backup, detectedAt: marker.detectedAt }),
+    identity: opened.identity,
+  };
+}
+
+function recoveryRequiredError(marker) {
+  const backup = marker?.backup || "the bounded corrupt backup";
+  const error = new Error(`workspace state recovery is required; invalid JSON was preserved as ${backup}. Restore a valid current-schema state.json or intentionally remove this profile before restarting`);
+  error.code = "state_recovery_required";
+  return error;
+}
+
 function ensureStateRoot(inputRoot) {
   const root = path.resolve(expandHome(inputRoot));
   if (existsSync(root)) {
@@ -473,6 +703,9 @@ function assertSafeStateRootForRemoval(root) {
     path.resolve(packageRoot),
   ]);
   if (forbidden.has(canonical)) throw new Error(`refusing to remove unsafe state root: ${canonical}`);
+  if (currentEntrypointInsideStateRoot(canonical)) {
+    throw new Error("refusing to remove a state root that contains the currently executing Machine Bridge CLI; run uninstall from an installation outside that state root");
+  }
   if (looksLikeSourceTree(canonical) || stateRootMatchesRecordedWorkspace(canonical)) {
     throw new Error(`refusing to remove state root that appears to be a workspace: ${canonical}`);
   }
@@ -480,6 +713,7 @@ function assertSafeStateRootForRemoval(root) {
   if (!hasOnlyStateEntries(entries)) {
     throw new Error(`refusing to remove state root containing unrelated entries: ${canonical}`);
   }
+  validateOwnedStateNamespaces(canonical);
   const marker = path.join(canonical, STATE_MARKER);
   if (existsSync(marker)) {
     assertValidStateMarker(marker);
@@ -489,7 +723,7 @@ function assertSafeStateRootForRemoval(root) {
 }
 
 function assertValidStateMarker(marker) {
-  const content = readBoundedUtf8(marker, MAX_MARKER_BYTES, "state marker");
+  const content = readBoundedUtf8(marker, MAX_MARKER_BYTES, "state marker", { verifyPathIdentity: true, rejectMultipleLinks: true });
   let value;
   try { value = JSON.parse(content); } catch { throw new Error(`invalid state root marker: ${marker}`); }
   if (value?.app !== appName || value?.schema !== STATE_MARKER_SCHEMA) {
@@ -498,10 +732,26 @@ function assertValidStateMarker(marker) {
 }
 
 function hasOnlyStateEntries(entries) {
-  const allowed = new Set([STATE_MARKER, "config.json", "browser-bridge.json", "maintenance.lock", "profiles", "logs", "service-environment.json", "service-launcher.cmd"]);
+  const allowed = new Set([STATE_MARKER, "config.json", "browser-bridge.json", "maintenance.lock", "profiles", "logs", "service-environment.json", "service-launcher.cmd", "toolchains", "release-channels", "release-tasks"]);
   return entries.every((entry) => allowed.has(entry) || /^config\.json\.corrupt-\d+(?:-[a-f0-9]{8})?$/.test(entry));
 }
 
+function currentEntrypointInsideStateRoot(root) {
+  const entry = String(process.argv[1] || "").trim();
+  if (!entry) return false;
+  let canonicalRoot;
+  let resolved;
+  try {
+    canonicalRoot = canonicalizePotentialPath(root);
+    resolved = canonicalizePotentialPath(entry);
+  } catch {
+    canonicalRoot = path.resolve(root);
+    resolved = path.resolve(entry);
+  }
+  const relative = path.relative(canonicalRoot, resolved);
+  return Boolean(relative) && relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
 function looksLikeSourceTree(root) {
   return [".git", ".hg", ".svn", "package.json", "pyproject.toml", "Cargo.toml", "go.mod"].some((name) => existsSync(path.join(root, name)));
 }
@@ -511,13 +761,12 @@ function stateRootMatchesRecordedWorkspace(root) {
   if (typeof config?.selectedWorkspace === "string" && sameWorkspaceIdentity(config.selectedWorkspace, root)) return true;
 
   const profiles = path.join(root, "profiles");
-  let entries;
-  try {
-    entries = readdirSync(profiles, { withFileTypes: true });
-  } catch (error) {
-    if (error?.code === "ENOENT") return false;
-    throw new Error("could not inspect state-root profiles before removal", { cause: error });
+  const profilesInfo = inspectPathIfPresentSync(profiles, "state-root profiles");
+  if (!profilesInfo) return false;
+  if (profilesInfo.isSymbolicLink() || !profilesInfo.isDirectory()) {
+    throw new Error("state-root profiles must be a real directory before removal");
   }
+  const entries = readdirSync(profiles, { withFileTypes: true });
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const profileDir = path.join(profiles, entry.name);
@@ -532,7 +781,7 @@ function stateRootMatchesRecordedWorkspace(root) {
 function readOptionalRemovalJson(file, label) {
   let text;
   try {
-    text = readBoundedUtf8(file, MAX_STATE_JSON_BYTES, label);
+    text = readBoundedUtf8(file, MAX_STATE_JSON_BYTES, label, { verifyPathIdentity: true, rejectMultipleLinks: true });
   } catch (error) {
     if (error?.code === "ENOENT" || error?.cause?.code === "ENOENT") return null;
     throw new Error(`${label} could not be verified before state removal`, { cause: error });
@@ -569,7 +818,7 @@ function cleanupStaleAtomicTemps(dir, baseName = "") {
     const file = path.join(dir, name);
     try {
       if (now - statSync(file).mtimeMs > 60 * 60 * 1000) unlinkSync(file);
-    } catch {}
+    } catch { /* Stale-temp cleanup is opportunistic and must not block the authoritative state write. */ }
   }
 }
 
@@ -586,16 +835,18 @@ function pruneBackups(filePath, keep) {
     return;
   }
   for (const backup of backups.slice(keep)) {
-    try { unlinkSync(backup.path); } catch {}
+    try { unlinkSync(backup.path); }
+    catch { /* Backup pruning is bounded housekeeping; retained backups are safer than failing state recovery. */ }
   }
 }
 
 export function ensureWorkerSecrets(state, options = {}) {
   state.worker ||= {};
+  delete state.worker.accountAdminSecret;
   const enrollingDeviceIdentity = !state.worker.deviceIdentity;
-  if (!state.worker.accountAdminSecret || options.rotateSecrets) state.worker.accountAdminSecret = randomToken("account_admin");
-  if (enrollingDeviceIdentity || options.rotateSecrets) state.worker.deviceIdentity = createDeviceIdentity();
-  else validateDeviceIdentity(state.worker.deviceIdentity);
+  if (enrollingDeviceIdentity || (options.rotateSecrets && !options.deferDeviceRotation)) state.worker.deviceIdentity = createDeviceIdentity();
+  else validateDeviceRootIdentity(state.worker.deviceIdentity);
+  if (state.worker.pendingDeviceIdentity) validateDeviceRootIdentity(state.worker.pendingDeviceIdentity);
   delete state.worker.daemonSecret;
   if (!state.worker.oauthTokenVersion || enrollingDeviceIdentity || options.rotateSecrets) {
     state.worker.oauthTokenVersion = randomToken("token_version");
@@ -622,26 +873,53 @@ export function ensureWorkerSecrets(state, options = {}) {
   delete state.worker.updatedAt;
 }
 
-function defaultWorkerName(hash) {
-  return `mbm-${String(hash || "default").slice(0, 12)}`;
+export function deploymentDeviceIdentity(state) {
+  const identity = state?.worker?.pendingDeviceIdentity || state?.worker?.deviceIdentity;
+  return validateDeviceRootIdentity(identity);
 }
 
-function randomToken(prefix) {
-  return `${prefix}_${randomBytes(32).toString("base64url")}`;
+export function promotePendingDeviceIdentity(state) {
+  const pending = state?.worker?.pendingDeviceIdentity;
+  if (!pending) return false;
+  validateDeviceRootIdentity(pending);
+  const current = state.worker.deviceIdentity;
+  if (current) {
+    const previous = Array.isArray(state.worker.previousDeviceIdentities) ? state.worker.previousDeviceIdentities : [];
+    state.worker.previousDeviceIdentities = [...previous, publicDeviceRootRecord(current)].slice(-2);
+  }
+  state.worker.deviceIdentity = pending;
+  delete state.worker.pendingDeviceIdentity;
+  return true;
 }
 
-export function ensureOwnerOnlyDir(dir, options = {}) {
-  return ensureOwnerOnlyDirectorySync(dir, options);
+function publicDeviceRootRecord(identity) {
+  validateDeviceRootIdentity(identity);
+  return {
+    scheme: identity.scheme,
+    provider: identity.provider || "portable-jwk-v1",
+    brokerProtocol: identity.brokerProtocol || undefined,
+    brokerPath: identity.brokerPath || undefined,
+    brokerIdentifier: identity.brokerIdentifier || undefined,
+    brokerTeamIdentifier: identity.brokerTeamIdentifier || undefined,
+    keyTag: identity.keyTag || undefined,
+    publicJwk: identity.publicJwk,
+    keyId: identity.keyId,
+    createdAt: identity.createdAt,
+    retiredAt: new Date().toISOString(),
+  };
 }
 
-export function ownerOnlyFile(filePath) {
-  chmodRegularFileSync(filePath, 0o600, "owner-only path");
+function defaultWorkerName(hash) {
+  return `mbm-${String(hash || "default").slice(0, 12)}`;
+}
+
+function randomToken(prefix) {
+  return `${prefix}_${randomBytes(32).toString("base64url")}`;
 }
 
 export function redactState(state) {
   const clone = redactHomeInValue(JSON.parse(JSON.stringify(state)));
-  if (clone.worker?.accountAdminSecret) clone.worker.accountAdminSecret = "<redacted>";
-  if (clone.worker?.deviceIdentity?.privateJwk?.d) clone.worker.deviceIdentity.privateJwk.d = "<redacted>";
+  redactDeviceIdentityState(clone.worker);
   if (clone.worker?.oauthTokenVersion) clone.worker.oauthTokenVersion = "<redacted>";
   if (clone.resources && typeof clone.resources === "object") {
     for (const value of Object.values(clone.resources)) {
@@ -653,6 +931,22 @@ export function redactState(state) {
   return clone;
 }
 
+
+function redactDeviceIdentityState(worker) {
+  if (!worker || typeof worker !== "object") return;
+  for (const identity of [
+    worker.deviceIdentity,
+    worker.pendingDeviceIdentity,
+    ...(Array.isArray(worker.previousDeviceIdentities) ? worker.previousDeviceIdentities : []),
+  ]) {
+    if (!identity || typeof identity !== "object") continue;
+    delete identity.privateJwk;
+    delete identity.publicJwk;
+    if (identity.brokerPath) identity.brokerPath = "<local-broker-path>";
+    if (identity.keyTag) identity.keyTag = "<local-key-tag>";
+  }
+}
+
 function redactHomeInValue(value) {
   const home = os.homedir();
   if (typeof value === "string") {
@@ -665,7 +959,3 @@ function redactHomeInValue(value) {
   }
   return value;
 }
-
-export function previewSecret(_value) {
-  return "<redacted>";
-}