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

package/src/local/delegated-process-sandbox.mjs

@@ -0,0 +1,148 @@
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { BridgeError } from "./errors.mjs";
+
+const MACOS_SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+let macosProbeResult;
+
+export function delegatedProcessCommand({ command, args = [], workspace, runtimeDir, context = {}, platform = process.platform, forceDelegated = false } = {}) {
+  const principal = context?.authority?.principal;
+  if (!forceDelegated && (!principal || principal.kind !== "account" || principal.role === "owner")) {
+    return { command, args, isolation: "owner-or-local-user" };
+  }
+  if (platform === "darwin" && macosSandboxAvailable({ platform })) {
+    const profile = macosProfile({ workspace, runtimeDir });
+    return {
+      command: MACOS_SANDBOX_EXEC,
+      args: ["-p", profile, String(command), ...args.map(String)],
+      isolation: "macos-sandbox-exec-workspace",
+    };
+  }
+  throw new BridgeError(
+    "policy_denied",
+    "delegated process execution requires a behavior-verified OS workspace sandbox; use the owner account or an isolated worker account/VM",
+    { details: { reason: "delegated_process_isolation_unavailable", platform } },
+  );
+}
+
+export function delegatedProcessIsolationStatus(platform = process.platform) {
+  if (platform === "darwin" && macosSandboxAvailable({ platform })) {
+    return {
+      available: true,
+      provider: "macos-sandbox-exec-deny-default",
+      network: "allowed",
+      filesystem: "workspace-and-runtime-write; system-runtime-read",
+      keychain: "common Keychain CLI access denied by the behavior probe; not a complete same-user tenancy boundary",
+      apple_events: "not reachable through the deny-default profile",
+      residual: "sandbox-exec is a compatibility boundary, not separate OS-user tenancy; choose a narrow workspace",
+    };
+  }
+  return {
+    available: false,
+    provider: null,
+    network: "unavailable",
+    filesystem: "unavailable",
+    keychain: "unavailable",
+    apple_events: "unavailable",
+    residual: platform === "darwin"
+      ? "sandbox-exec exists but the workspace read/write, outside-path denial, or Keychain-denial behavior probe failed; delegated execution fails closed"
+      : "no verified delegated process sandbox provider is installed; delegated execution fails closed",
+  };
+}
+
+export function macosDelegatedSandboxProfile({ workspace, runtimeDir } = {}) {
+  return macosProfile({ workspace, runtimeDir });
+}
+
+export function macosSandboxAvailable(options = {}) {
+  if (options.refresh === true) macosProbeResult = undefined;
+  if (macosProbeResult !== undefined) return macosProbeResult;
+  const platform = String(options.platform || process.platform);
+  const exists = typeof options.exists === "function" ? options.exists : existsSync;
+  if (platform !== "darwin" || !exists(MACOS_SANDBOX_EXEC)) {
+    macosProbeResult = false;
+    return false;
+  }
+  const probe = typeof options.behaviorProbe === "function" ? options.behaviorProbe : probeMacosDelegatedSandbox;
+  macosProbeResult = probe({ spawnSyncProcess: options.spawnSync || spawnSync }) === true;
+  return macosProbeResult;
+}
+
+export function probeMacosDelegatedSandbox(options = {}) {
+  const run = typeof options.spawnSyncProcess === "function" ? options.spawnSyncProcess : spawnSync;
+  const root = mkdtempSync(path.join(tmpdir(), "mbm-delegated-sandbox-probe-"));
+  const workspace = path.join(root, "workspace");
+  const runtimeDir = path.join(root, "runtime");
+  const outside = path.join(root, "outside.txt");
+  const outsideWrite = path.join(root, "outside-write.txt");
+  const workspaceWrite = path.join(workspace, "allowed-write.txt");
+  try {
+    mkdirSync(workspace, { mode: 0o700 });
+    mkdirSync(runtimeDir, { mode: 0o700 });
+    writeFileSync(path.join(workspace, "allowed.txt"), "allowed\n", { mode: 0o600 });
+    writeFileSync(outside, "blocked\n", { mode: 0o600 });
+    const profile = macosProfile({ workspace, runtimeDir });
+    const execute = (argv) => run(MACOS_SANDBOX_EXEC, ["-p", profile, ...argv], {
+      encoding: "utf8",
+      timeout: 5_000,
+      killSignal: "SIGKILL",
+      maxBuffer: 64 * 1024,
+      windowsHide: true,
+      env: { PATH: "/usr/bin:/bin:/usr/sbin:/sbin", HOME: workspace, TMPDIR: runtimeDir, LANG: "C", LC_ALL: "C" },
+    });
+    const allowedRead = execute(["/bin/cat", path.join(workspace, "allowed.txt")]);
+    const allowedWrite = execute(["/bin/sh", "-c", `printf allowed > ${shellQuote(workspaceWrite)}`]);
+    const blockedRead = execute(["/bin/cat", outside]);
+    const blockedWrite = execute(["/bin/sh", "-c", `printf blocked > ${shellQuote(outsideWrite)}`]);
+    const keychain = execute(["/usr/bin/security", "list-keychains"]);
+    return allowedRead.status === 0 && allowedWrite.status === 0 && existsSync(workspaceWrite)
+      && blockedRead.status !== 0 && blockedWrite.status !== 0 && !existsSync(outsideWrite)
+      && keychain.status !== 0;
+  } catch {
+    return false;
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
+function macosProfile({ workspace, runtimeDir }) {
+  const readable = [
+    "/System",
+    "/usr",
+    "/bin",
+    "/sbin",
+    "/Library",
+    "/Applications",
+    "/opt/homebrew",
+    "/nix/store",
+    "/private/etc",
+    "/private/var/db",
+    "/dev",
+    workspace,
+    runtimeDir,
+  ].filter(Boolean);
+  const writable = [workspace, runtimeDir, "/private/tmp"].filter(Boolean);
+  return [
+    "(version 1)",
+    "(deny default)",
+    "(allow process*)",
+    "(allow signal (target self))",
+    "(allow sysctl-read)",
+    "(allow mach-lookup)",
+    "(allow ipc-posix-shm)",
+    "(allow network*)",
+    "(allow file-read-metadata)",
+    ...readable.map((value) => `(allow file-read* (subpath ${sandboxString(path.resolve(value))}))`),
+    ...writable.map((value) => `(allow file-write* (subpath ${sandboxString(path.resolve(value))}))`),
+  ].join(" ");
+}
+
+function sandboxString(value) {
+  return `"${String(value).replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"`;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replaceAll("'", `'\\''`)}'`;
+}

package/src/local/device-identity.mjs

@@ -1,8 +1,15 @@
-import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, sign, webcrypto } from "node:crypto";
+import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, sign } from "node:crypto";
 import { DAEMON_AUTH_SCHEME, DAEMON_PREFLIGHT_SCHEME, daemonAuthTranscript, daemonPreflightTranscript } from "../shared/daemon-auth.mjs";
+import {
+  DEVICE_SESSION_CERTIFICATE_SCHEME,
+  DEVICE_SESSION_MAX_LIFETIME_SECONDS,
+  canonicalPublicJwk,
+  deviceSessionCertificateTranscript,
+} from "../shared/device-session-auth.mjs";
 
 const DEVICE_KEY_TYPE = "EC";
 const DEVICE_CURVE = "P-256";
+const SESSION_CERTIFICATE_HEADER = "X-Bridge-Device-Certificate";
 
 export function createDeviceIdentity() {
   const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
@@ -19,90 +26,190 @@ export function createDeviceIdentity() {
   };
 }
 
+export function createDeviceSessionIdentity(rootIdentity, workerOrigin, server, version, now = Date.now()) {
+  validateDeviceIdentity(rootIdentity);
+  const draft = createDeviceSessionDraft(rootIdentity, workerOrigin, server, version, now);
+  return finalizeDeviceSessionIdentity(draft, signDeviceTranscript(rootIdentity, draft.transcript));
+}
+
+export function createDeviceSessionDraft(rootIdentity, workerOrigin, server, version, now = Date.now()) {
+  validatePublicDeviceRoot(rootIdentity);
+  const issuedAt = Math.floor(Number(now) / 1000);
+  if (!Number.isSafeInteger(issuedAt) || issuedAt <= 0) throw new Error("device session timestamp is invalid");
+  const expiresAt = issuedAt + DEVICE_SESSION_MAX_LIFETIME_SECONDS;
+  const { privateKey, publicKey } = generateKeyPairSync("ec", { namedCurve: "prime256v1" });
+  const privateJwk = privateKey.export({ format: "jwk" });
+  const publicJwk = publicKey.export({ format: "jwk" });
+  validatePrivateDeviceJwk(privateJwk);
+  validatePublicDeviceJwk(publicJwk);
+  const nonce = randomBytes(24).toString("base64url");
+  const certificateBody = {
+    scheme: DEVICE_SESSION_CERTIFICATE_SCHEME,
+    root_key_id: rootIdentity.keyId,
+    public_jwk: canonicalPublicJwk(publicJwk),
+    issued_at: issuedAt,
+    expires_at: expiresAt,
+    nonce,
+  };
+  const transcript = deviceSessionCertificateTranscript({
+    workerOrigin,
+    server,
+    version,
+    rootKeyId: rootIdentity.keyId,
+    publicJwk,
+    issuedAt,
+    expiresAt,
+    nonce,
+  });
+  return {
+    transcript,
+    certificateBody,
+    session: {
+      scheme: DAEMON_AUTH_SCHEME,
+      privateJwk,
+      publicJwk,
+      keyId: deviceKeyId(publicJwk),
+      createdAt: new Date(Number(now)).toISOString(),
+      expiresAt: new Date(expiresAt * 1000).toISOString(),
+    },
+  };
+}
+
+export function finalizeDeviceSessionIdentity(draft, signature) {
+  if (!draft || typeof draft !== "object" || !draft.session || !draft.certificateBody) throw new Error("device session draft is invalid");
+  if (!/^[A-Za-z0-9_-]{86}$/.test(String(signature || ""))) throw new Error("device session root signature is invalid");
+  const identity = {
+    ...draft.session,
+    certificate: { ...draft.certificateBody, signature },
+  };
+  return validateDeviceSessionIdentity(identity);
+}
+
+export function validatePublicDeviceRoot(identity) {
+  if (!identity || typeof identity !== "object" || Array.isArray(identity)) throw new Error("device root identity is missing");
+  if (identity.scheme !== DAEMON_AUTH_SCHEME) throw new Error("device root identity scheme is invalid");
+  validatePublicDeviceJwk(identity.publicJwk);
+  if (identity.keyId !== deviceKeyId(identity.publicJwk)) throw new Error("device root identity key id is invalid");
+  if (!Number.isFinite(Date.parse(String(identity.createdAt || "")))) throw new Error("device root identity creation time is invalid");
+  return identity;
+}
+
 export function publicDeviceJwkJson(identity) {
   const publicJwk = identity?.publicJwk;
   validatePublicDeviceJwk(publicJwk);
   return JSON.stringify(publicJwk);
 }
 
-
 export function createDaemonPreflightHeaders(identity, workerOrigin, server, version, now = Date.now()) {
-  validatePrivateDeviceJwk(identity?.privateJwk);
+  validateDeviceSessionIdentity(identity, now);
   const issuedAt = Math.floor(Number(now) / 1000);
   if (!Number.isSafeInteger(issuedAt) || issuedAt <= 0) throw new Error("device preflight timestamp is invalid");
   const nonce = randomBytes(24).toString("base64url");
   const transcript = daemonPreflightTranscript({ workerOrigin, server, version, nonce, issuedAt });
-  const key = createPrivateKey({ key: identity.privateJwk, format: "jwk" });
-  const signature = sign("sha256", Buffer.from(transcript, "utf8"), { key, dsaEncoding: "ieee-p1363" }).toString("base64url");
+  const signature = signDeviceTranscript(identity, transcript);
   return {
     "X-Bridge-Device-Scheme": DAEMON_PREFLIGHT_SCHEME,
-    "X-Bridge-Device-Key": String(identity.keyId || deviceKeyId(identity.publicJwk)),
+    "X-Bridge-Device-Key": identity.keyId,
     "X-Bridge-Device-Nonce": nonce,
     "X-Bridge-Device-Time": String(issuedAt),
     "X-Bridge-Device-Signature": signature,
+    [SESSION_CERTIFICATE_HEADER]: encodeDeviceSessionCertificate(identity),
   };
 }
 
+export function encodeDeviceSessionCertificate(identity) {
+  validateDeviceSessionIdentity(identity);
+  return Buffer.from(JSON.stringify(identity.certificate), "utf8").toString("base64url");
+}
+
+export function signWithDeviceSessionIdentity(identity, transcript) {
+  validateDeviceSessionIdentity(identity);
+  const text = String(transcript || "");
+  if (!text || Buffer.byteLength(text) > 64 * 1024) throw new Error("device session signing transcript is empty or too large");
+  return signDeviceTranscript(identity, text);
+}
+
 export async function createDaemonAuthentication(identity, welcome, instanceId) {
-  validatePrivateDeviceJwk(identity?.privateJwk);
+  validateDeviceSessionIdentity(identity);
   const auth = welcome?.authentication;
-  if (!auth || auth.scheme !== DAEMON_AUTH_SCHEME) throw new Error("Worker did not request supported device authentication");
-  const workerOrigin = new URL(String(welcome.worker_origin || "")).origin;
+  if (!auth || auth.scheme !== DAEMON_AUTH_SCHEME) throw new Error("Worker did not provide a supported device challenge");
+  const challenge = String(auth.challenge || "");
+  const issuedAt = Number(auth.issued_at);
+  const expiresAt = Number(auth.expires_at);
+  if (!/^daemon_challenge_[A-Za-z0-9_-]{40,96}$/.test(challenge)) throw new Error("Worker device challenge is invalid");
+  if (!Number.isSafeInteger(issuedAt) || !Number.isSafeInteger(expiresAt) || expiresAt <= issuedAt) throw new Error("Worker device challenge lifetime is invalid");
+  if (Math.floor(Date.now() / 1000) > expiresAt) throw new Error("Worker device challenge expired");
   const transcript = daemonAuthTranscript({
-    challenge: auth.challenge,
-    workerOrigin,
-    server: welcome.server,
-    version: welcome.version,
+    challenge,
+    workerOrigin: String(welcome.worker_origin || ""),
+    server: String(welcome.server || ""),
+    version: String(welcome.version || ""),
     instanceId,
-    issuedAt: auth.issued_at,
+    issuedAt,
   });
-  const privateKey = await webcrypto.subtle.importKey(
-    "jwk",
-    identity.privateJwk,
-    { name: "ECDSA", namedCurve: DEVICE_CURVE },
-    false,
-    ["sign"],
-  );
-  const signature = await webcrypto.subtle.sign(
-    { name: "ECDSA", hash: "SHA-256" },
-    privateKey,
-    new TextEncoder().encode(transcript),
-  );
   return {
     scheme: DAEMON_AUTH_SCHEME,
-    challenge: String(auth.challenge),
-    issued_at: Number(auth.issued_at),
-    key_id: String(identity.keyId || deviceKeyId(identity.publicJwk)),
-    signature: Buffer.from(signature).toString("base64url"),
+    key_id: identity.keyId,
+    challenge,
+    issued_at: issuedAt,
+    signature: signDeviceTranscript(identity, transcript),
   };
 }
 
-export function deviceKeyId(publicJwk) {
-  validatePublicDeviceJwk(publicJwk);
-  const canonical = JSON.stringify({ crv: publicJwk.crv, kty: publicJwk.kty, x: publicJwk.x, y: publicJwk.y });
-  return `device_${createHash("sha256").update(canonical).digest("base64url").slice(0, 32)}`;
-}
-
 export function validateDeviceIdentity(identity) {
   if (!identity || typeof identity !== "object" || Array.isArray(identity)) throw new Error("device identity is missing");
-  if (identity.scheme !== DAEMON_AUTH_SCHEME) throw new Error("device identity scheme is unsupported");
+  if (identity.scheme !== DAEMON_AUTH_SCHEME) throw new Error("device identity scheme is invalid");
   validatePrivateDeviceJwk(identity.privateJwk);
   validatePublicDeviceJwk(identity.publicJwk);
-  const expectedKeyId = deviceKeyId(identity.publicJwk);
-  if (identity.keyId !== expectedKeyId) throw new Error("device identity key id does not match its public key");
+  const expectedPublic = publicFromPrivate(identity.privateJwk);
+  if (!samePublicJwk(expectedPublic, identity.publicJwk)) throw new Error("device identity public and private keys do not match");
+  if (identity.keyId !== deviceKeyId(identity.publicJwk)) throw new Error("device identity key id is invalid");
+  if (!Number.isFinite(Date.parse(String(identity.createdAt || "")))) throw new Error("device identity creation time is invalid");
   return identity;
 }
 
-function validatePrivateDeviceJwk(jwk) {
-  validatePublicDeviceJwk(jwk);
-  if (typeof jwk.d !== "string" || !/^[A-Za-z0-9_-]{40,48}$/.test(jwk.d)) throw new Error("device private key is invalid");
+export function validateDeviceSessionIdentity(identity, now = Date.now()) {
+  validateDeviceIdentity(identity);
+  const certificate = identity.certificate;
+  if (!certificate || typeof certificate !== "object" || Array.isArray(certificate)) throw new Error("device session certificate is missing");
+  if (certificate.scheme !== DEVICE_SESSION_CERTIFICATE_SCHEME) throw new Error("device session certificate scheme is invalid");
+  if (identity.keyId !== deviceKeyId(certificate.public_jwk) || !samePublicJwk(identity.publicJwk, certificate.public_jwk)) {
+    throw new Error("device session certificate key mismatch");
+  }
+  const expiresAt = Number(certificate.expires_at);
+  if (!Number.isSafeInteger(expiresAt) || Math.floor(Number(now) / 1000) > expiresAt) throw new Error("device session certificate expired");
+  if (!/^[A-Za-z0-9_-]{86}$/.test(String(certificate.signature || ""))) throw new Error("device session certificate signature is invalid");
+  return identity;
 }
 
-function validatePublicDeviceJwk(jwk) {
-  if (!jwk || typeof jwk !== "object" || Array.isArray(jwk)) throw new Error("device public key is invalid");
-  if (jwk.kty !== DEVICE_KEY_TYPE || jwk.crv !== DEVICE_CURVE) throw new Error("device public key must use P-256");
-  if (typeof jwk.x !== "string" || typeof jwk.y !== "string") throw new Error("device public key coordinates are invalid");
-  if (!/^[A-Za-z0-9_-]{42,44}$/.test(jwk.x) || !/^[A-Za-z0-9_-]{42,44}$/.test(jwk.y)) {
-    throw new Error("device public key coordinates are invalid");
-  }
+export function deviceKeyId(publicJwk) {
+  validatePublicDeviceJwk(publicJwk);
+  const canonical = JSON.stringify(canonicalPublicJwk(publicJwk));
+  return `device_${createHash("sha256").update(canonical).digest("base64url").slice(0, 32)}`;
+}
+
+function signDeviceTranscript(identity, transcript) {
+  validatePrivateDeviceJwk(identity?.privateJwk);
+  const key = createPrivateKey({ key: identity.privateJwk, format: "jwk" });
+  return sign("sha256", Buffer.from(transcript, "utf8"), { key, dsaEncoding: "ieee-p1363" }).toString("base64url");
+}
+
+function publicFromPrivate(privateJwk) {
+  const privateKey = createPrivateKey({ key: privateJwk, format: "jwk" });
+  return privateKey.export({ format: "jwk" });
+}
+
+function validatePrivateDeviceJwk(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("device private key is invalid");
+  if (value.kty !== DEVICE_KEY_TYPE || value.crv !== DEVICE_CURVE || typeof value.d !== "string") throw new Error("device private key is invalid");
+  validatePublicDeviceJwk(value);
+}
+
+function validatePublicDeviceJwk(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("device public key is invalid");
+  if (value.kty !== DEVICE_KEY_TYPE || value.crv !== DEVICE_CURVE || typeof value.x !== "string" || typeof value.y !== "string") throw new Error("device public key is invalid");
+}
+
+function samePublicJwk(left, right) {
+  return left?.kty === right?.kty && left?.crv === right?.crv && left?.x === right?.x && left?.y === right?.y;
 }

package/src/local/device-root-provider.mjs

@@ -0,0 +1,81 @@
+import {
+  createDeviceIdentity,
+  createDeviceSessionDraft,
+  createDeviceSessionIdentity,
+  finalizeDeviceSessionIdentity,
+  validateDeviceIdentity,
+  validatePublicDeviceRoot,
+} from "./device-identity.mjs";
+import {
+  configuredMacosTrustBrokerPath,
+  ensureMacosSecureDeviceRoot,
+  isMacosSecureDeviceRoot,
+  signWithMacosSecureDeviceRoot,
+} from "./macos-trust-broker.mjs";
+
+export function validateDeviceRootIdentity(identity) {
+  if (isMacosSecureDeviceRoot(identity)) return identity;
+  return validateDeviceIdentity(identity);
+}
+
+export async function ensurePreferredDeviceRoot({
+  profileDir,
+  workspaceHash,
+  existing = null,
+  rotate = false,
+  platform = process.platform,
+  brokerPath = undefined,
+  env = process.env,
+  secureRootFactory = ensureMacosSecureDeviceRoot,
+} = {}) {
+  const configuredBroker = brokerPath === undefined ? configuredMacosTrustBrokerPath(env) : brokerPath;
+  const selectedBroker = configuredBroker || (isMacosSecureDeviceRoot(existing) ? existing.brokerPath : null);
+  if (platform === "darwin" && selectedBroker) {
+    return secureRootFactory({
+      profileDir,
+      workspaceHash,
+      existing,
+      rotate,
+      brokerPath: selectedBroker,
+    });
+  }
+  if (!rotate && existing) return validateDeviceRootIdentity(existing);
+  return createDeviceIdentity();
+}
+
+export async function createDeviceSessionForRoot(identity, workerOrigin, server, version, {
+  profileDir,
+  now = Date.now(),
+  reason = "Authorize Machine Bridge startup",
+} = {}) {
+  if (!isMacosSecureDeviceRoot(identity)) return createDeviceSessionIdentity(validateDeviceIdentity(identity), workerOrigin, server, version, now);
+  validatePublicDeviceRoot(identity);
+  const draft = createDeviceSessionDraft(identity, workerOrigin, server, version, now);
+  const signature = signWithMacosSecureDeviceRoot(identity, draft.transcript, { profileDir, reason });
+  return finalizeDeviceSessionIdentity(draft, signature);
+}
+
+export function deviceRootProviderStatus(identity, { env = process.env } = {}) {
+  if (isMacosSecureDeviceRoot(identity)) {
+    return {
+      provider: identity.provider,
+      private_key_exportable: false,
+      root_storage: "Secure Enclave",
+      broker_provisioned: true,
+      session_signing: "one user-presence operation per daemon start",
+      reconnect_signing: "ephemeral in-memory key",
+      key_id: identity.keyId,
+    };
+  }
+  validateDeviceIdentity(identity);
+  return {
+    provider: "portable-jwk-v1",
+    private_key_exportable: true,
+    root_storage: "owner-only local state",
+    broker_provisioned: Boolean(String(env?.MBM_MACOS_TRUST_BROKER || "").trim()),
+    secure_enclave_enrollment: "requires a provisioning-profile-validated app-like broker configured through MBM_MACOS_TRUST_BROKER",
+    session_signing: "local file-backed root",
+    reconnect_signing: "ephemeral in-memory key",
+    key_id: identity.keyId,
+  };
+}

package/src/local/directory-metadata.mjs

@@ -0,0 +1,47 @@
+// @ts-check
+
+import { opendir } from "node:fs/promises";
+import { resolve } from "node:path";
+import { pathEntryIfExists } from "./path-inspection.mjs";
+
+export const DIRECTORY_METADATA_BATCH_SIZE = 16;
+
+export async function* directoryEntriesWithMetadata(directory, options = {}) {
+  const openDirectory = options.openDirectory || opendir;
+  const inspect = options.inspect || pathEntryIfExists;
+  const throwIfCancelled = typeof options.throwIfCancelled === "function" ? options.throwIfCancelled : () => {};
+  const context = options.context || {};
+  const batchSize = positiveBatchSize(options.batchSize);
+  const handle = await openDirectory(directory);
+  let batch = [];
+  for await (const entry of handle) {
+    throwIfCancelled(context);
+    batch.push({ entry, path: resolve(directory, entry.name) });
+    if (batch.length < batchSize) continue;
+    const settled = await inspectBatch(batch, inspect, throwIfCancelled, context);
+    batch = [];
+    for (const result of settled) {
+      throwIfCancelled(context);
+      if (result.status === "rejected") throw result.reason;
+      yield result.value;
+    }
+  }
+  if (!batch.length) return;
+  const settled = await inspectBatch(batch, inspect, throwIfCancelled, context);
+  for (const result of settled) {
+    throwIfCancelled(context);
+    if (result.status === "rejected") throw result.reason;
+    yield result.value;
+  }
+}
+
+async function inspectBatch(batch, inspect, throwIfCancelled, context) {
+  return Promise.allSettled(batch.map(async (item) => {
+    throwIfCancelled(context);
+    return { ...item, info: await inspect(item.path) };
+  }));
+}
+
+function positiveBatchSize(value) {
+  return Number.isInteger(value) && value > 0 && value <= 64 ? value : DIRECTORY_METADATA_BATCH_SIZE;
+}

package/src/local/doctor-reporting.mjs

@@ -0,0 +1,23 @@
+export const DOCTOR_RUNTIME_SCOPE = Object.freeze({
+  running_service_process_inspected: false,
+  remote_relay_inspected: false,
+  reason: "doctor uses an isolated local runtime; inspect authenticated server_info.daemon.relay_transport for the running service relay",
+});
+
+export function doctorRuntimeCheckProjection(check = {}) {
+  const layer = String(check.layer || "unknown");
+  const skipped = check.skipped === true;
+  const detail = skipped && layer === "remote-relay"
+    ? "not inspected (doctor uses an isolated local runtime; inspect authenticated server_info.daemon.relay_transport)"
+    : skipped
+      ? `skipped (${check.error_class || "not applicable"})`
+      : check.ok === true
+        ? "ok"
+        : check.error_class || "failed";
+  return {
+    name: `runtime:${layer}`,
+    ok: skipped || check.ok === true,
+    applicable: !skipped,
+    detail,
+  };
+}

package/src/local/durable-process-spec.mjs

@@ -0,0 +1,80 @@
+import { stat } from "node:fs/promises";
+import { basename } from "node:path";
+import { BridgeError } from "./errors.mjs";
+import { delegatedProcessCommand } from "./delegated-process-sandbox.mjs";
+import { MAX_COMMAND_BYTES, validateArgv } from "./process-contract.mjs";
+import { durableProcessExecutionTimeoutSeconds, durableRegisteredCommandTimeoutSeconds } from "./process-foreground-timeout.mjs";
+import { workspaceShellCommand } from "./shell.mjs";
+
+export async function prepareDurableDirectProcess(service, args, context = {}) {
+  service.policyGate.assert("run_process");
+  const idempotencyKey = durableProcessIdempotencyKey(args, context);
+  const argv = validateArgv(args.argv);
+  const cwd = await service.resolveExistingPath(args.cwd || ".", context);
+  if (!(await stat(cwd)).isDirectory()) throw new BridgeError("invalid_request", "cwd is not a directory");
+  return durableSpec(service, {
+    sourceTool: "run_process",
+    name: `durable run_process: ${basename(argv[0])}`,
+    argv,
+    cwd,
+    timeoutSeconds: durableProcessExecutionTimeoutSeconds(args.timeout_seconds),
+    idempotencyKey,
+  }, context);
+}
+
+export async function prepareDurableRegisteredProcess(service, args, context = {}) {
+  service.policyGate.assert("run_local_command");
+  const idempotencyKey = durableProcessIdempotencyKey(args, context);
+  const command = await service.resolveLocalCommand(args, context);
+  const argv = validateArgv(command.argv);
+  const cwd = await service.resolveExistingPath(command.cwd, context);
+  if (!(await stat(cwd)).isDirectory()) throw new BridgeError("invalid_request", "registered command cwd is not a directory");
+  return durableSpec(service, {
+    sourceTool: "run_local_command",
+    name: `durable command: ${String(command.name || basename(argv[0])).slice(0, 96)}`,
+    argv,
+    cwd,
+    timeoutSeconds: durableRegisteredCommandTimeoutSeconds(args, command),
+    idempotencyKey,
+  }, context);
+}
+
+export function prepareDurableShellProcess(service, args, context = {}) {
+  service.policyGate.assert("exec_command");
+  const idempotencyKey = durableProcessIdempotencyKey(args, context);
+  const command = args?.command;
+  if (!command || typeof command !== "string") throw new BridgeError("invalid_request", "command is required");
+  if (command.includes("\0")) throw new BridgeError("invalid_request", "command contains a NUL byte");
+  if (Buffer.byteLength(command) > MAX_COMMAND_BYTES) throw new BridgeError("limit_exceeded", `command exceeds maximum size (${MAX_COMMAND_BYTES} bytes)`);
+  const shell = workspaceShellCommand(command);
+  return durableSpec(service, {
+    sourceTool: "exec_command",
+    name: "durable shell command",
+    argv: [shell.cmd, ...shell.args],
+    cwd: service.workspace,
+    timeoutSeconds: durableProcessExecutionTimeoutSeconds(args.timeout_seconds),
+    idempotencyKey,
+  }, context);
+}
+
+function durableSpec(service, spec, context) {
+  const launch = delegatedProcessCommand({
+    command: process.execPath,
+    args: [],
+    workspace: service.workspace,
+    runtimeDir: service.runtimeDir,
+    context,
+  });
+  return { ...spec, delegatedProcess: launch.isolation !== "owner-or-local-user" };
+}
+
+function durableProcessIdempotencyKey(args, context) {
+  const key = args?.idempotency_key;
+  if (context?.origin === "relay" && key === undefined) {
+    throw new BridgeError("invalid_request", "remote durable process execution requires idempotency_key before dispatch so an ambiguous acceptance response can be recovered without duplicate execution", {
+      retryable: false,
+      details: { side_effects_started: false, recovery_credential_required: "idempotency_key" },
+    });
+  }
+  return key;
+}