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

package/src/local/device-identity.mjs

@@ -1,8 +1,15 @@
 import { createHash, createPrivateKey, generateKeyPairSync, randomBytes, sign, webcrypto } 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,192 @@ 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;
+}
+
+export const deviceWebCrypto = webcrypto;

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

@@ -0,0 +1,87 @@
+import {
+  createDeviceIdentity,
+  createDeviceSessionDraft,
+  createDeviceSessionIdentity,
+  finalizeDeviceSessionIdentity,
+  publicDeviceJwkJson,
+  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 function publicDeviceRootJwkJson(identity) {
+  validateDeviceRootIdentity(identity);
+  return publicDeviceJwkJson(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/errors.mjs

@@ -6,6 +6,9 @@ const ERROR_CODES = new Set([
 ]);
 
 const RETRYABLE_CODES = new Set(["timeout", "network_error", "unavailable"]);
+const MAX_PUBLIC_ERROR_MESSAGE_CHARS = 2000;
+const MAX_PUBLIC_ERROR_DETAILS_BYTES = 512 * 1024;
+const UNSAFE_ERROR_CONTROLS = /[\u0000-\u001f\u007f\u200B-\u200F\u202A-\u202E\u2066-\u2069\uFEFF]/g;
 
 export class BridgeError extends Error {
   constructor(code, message, options = {}) {
@@ -29,7 +32,7 @@ export function normalizeBridgeError(error, options = {}) {
       : safeFallbackMessage(error, code);
   return new BridgeError(code, message, {
     cause: error instanceof Error ? error : undefined,
-    expose: options.expose !== false,
+    expose: options.expose === true,
     retryable: options.retryable,
   });
 }
@@ -50,11 +53,12 @@ export function errorCode(error, fallback = "execution_failed") {
 
 export function publicError(error, options = {}) {
   const normalized = normalizeBridgeError(error, options);
+  const details = normalized.expose ? publicErrorDetails(normalized.details) : undefined;
   return {
     code: normalized.code,
-    message: normalized.expose ? normalized.message : defaultMessage(normalized.code),
+    message: publicErrorMessage(normalized.expose ? normalized.message : defaultMessage(normalized.code)),
     retryable: normalized.retryable,
-    ...(normalized.expose && normalized.details ? { details: normalized.details } : {}),
+    ...(details ? { details } : {}),
   };
 }
 
@@ -106,3 +110,21 @@ function defaultMessage(code) {
 function isRecord(value) {
   return Boolean(value) && typeof value === "object" && !Array.isArray(value);
 }
+
+function publicErrorMessage(value) {
+  const normalized = String(value || "").replace(UNSAFE_ERROR_CONTROLS, " ").replace(/\s+/g, " ").trim();
+  return (normalized || "operation failed").slice(0, MAX_PUBLIC_ERROR_MESSAGE_CHARS);
+}
+
+function publicErrorDetails(value) {
+  if (!isRecord(value)) return undefined;
+  try {
+    const serialized = JSON.stringify(value, (_key, current) => {
+      if (["bigint", "function", "symbol", "undefined"].includes(typeof current)) throw new TypeError("unsupported error detail");
+      if (typeof current === "number" && !Number.isFinite(current)) throw new TypeError("unsupported error detail");
+      return current;
+    });
+    if (!serialized || Buffer.byteLength(serialized) > MAX_PUBLIC_ERROR_DETAILS_BYTES) return undefined;
+    return JSON.parse(serialized);
+  } catch { return undefined; }
+}

package/src/local/git-service.mjs

@@ -4,10 +4,11 @@ import { BridgeError } from "./errors.mjs";
 import { clampInteger } from "./numbers.mjs";
 
 export class GitService {
-  constructor({ resolveExistingPath, displayPath, runProcess, maximumBytes }) {
+  constructor({ resolveExistingPath, displayPath, runInternalProcess, gitExecutable, maximumBytes }) {
     this.resolveExistingPath = resolveExistingPath;
     this.displayPath = displayPath;
-    this.runProcess = runProcess;
+    this.runInternalProcess = runInternalProcess;
+    this.gitExecutable = typeof gitExecutable === "function" ? gitExecutable : () => String(gitExecutable || "");
     this.maximumBytes = maximumBytes;
   }
 
@@ -16,54 +17,54 @@ export class GitService {
     if (!git.ok) return git.result;
     const commandArgs = ["-c", "core.fsmonitor=false", "-C", git.root, "status", "--short", "--branch"];
     if (git.pathspec) commandArgs.push("--", git.pathspec);
-    const result = await this.runProcess("git", commandArgs, 30_000, true, 512 * 1024, context);
-    return { ...result, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root) };
+    const result = await this.runInternalProcess(this.gitExecutable(), commandArgs, 30_000, true, 512 * 1024, context);
+    return { ...result, path: this.displayPath(git.target, context), gitRoot: this.displayPath(git.root, context) };
   }
 
   async diff(args = {}, context = {}) {
     const maxBytes = clampInteger(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
     const git = await this.context(args.path || ".", context);
-    if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
+    if (!git.ok) return { ...git.result, path: this.displayPath(git.target, context) };
     const commandArgs = ["-c", "core.fsmonitor=false", "-c", "diff.external=", "-C", git.root, "diff", "--no-ext-diff", "--no-textconv"];
     if (args.staged) commandArgs.push("--cached");
     if (git.pathspec) commandArgs.push("--", git.pathspec);
-    const result = await this.runProcess("git", commandArgs, 60_000, true, maxBytes, context);
-    return { ...result, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root), staged: args.staged === true };
+    const result = await this.runInternalProcess(this.gitExecutable(), commandArgs, 60_000, true, maxBytes, context);
+    return { ...result, path: this.displayPath(git.target, context), gitRoot: this.displayPath(git.root, context), staged: args.staged === true };
   }
 
   async log(args = {}, context = {}) {
     const git = await this.context(args.path || ".", context);
-    if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
+    if (!git.ok) return { ...git.result, path: this.displayPath(git.target, context) };
     const maxCount = clampInteger(args.max_count, 20, 1, 100);
     const format = "%H%x1f%h%x1f%aI%x1f%an%x1f%ae%x1f%s%x1e";
     const commandArgs = ["-c", "core.fsmonitor=false", "-C", git.root, "log", `--max-count=${maxCount}`, `--format=${format}`];
     if (git.pathspec) commandArgs.push("--", git.pathspec);
-    const result = await this.runProcess("git", commandArgs, 30_000, true, 1024 * 1024, context);
+    const result = await this.runInternalProcess(this.gitExecutable(), commandArgs, 30_000, true, 1024 * 1024, context);
     const commits = result.stdout.split("\x1e").map((record) => record.trim()).filter(Boolean).map((record) => {
       const [hash, short, authored_at, author_name, author_email, subject] = record.split("\x1f");
       const commit = { hash, short, authored_at, author_name, subject };
       if (args.include_author_email === true) commit.author_email = author_email;
       return commit;
     });
-    return { code: result.code, stderr: result.stderr, commits, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root) };
+    return { code: result.code, stderr: result.stderr, commits, path: this.displayPath(git.target, context), gitRoot: this.displayPath(git.root, context) };
   }
 
   async show(args = {}, context = {}) {
     const git = await this.context(args.path || ".", context);
-    if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
+    if (!git.ok) return { ...git.result, path: this.displayPath(git.target, context) };
     const revision = validateRevision(args.revision || "HEAD");
     const maxBytes = clampInteger(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
     const commandArgs = ["-c", "core.fsmonitor=false", "-c", "diff.external=", "-C", git.root, "show", "--no-ext-diff", "--no-textconv", "--decorate=no", revision];
     if (git.pathspec) commandArgs.push("--", git.pathspec);
-    const result = await this.runProcess("git", commandArgs, 60_000, true, maxBytes, context);
-    return { ...result, revision, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root) };
+    const result = await this.runInternalProcess(this.gitExecutable(), commandArgs, 60_000, true, maxBytes, context);
+    return { ...result, revision, path: this.displayPath(git.target, context), gitRoot: this.displayPath(git.root, context) };
   }
 
   async context(inputPath, context = {}) {
-    const target = await this.resolveExistingPath(inputPath);
+    const target = await this.resolveExistingPath(inputPath, context);
     const info = await stat(target);
     const cwd = info.isDirectory() ? target : dirname(target);
-    const result = await this.runProcess("git", ["-c", "core.fsmonitor=false", "-C", cwd, "rev-parse", "--show-toplevel"], 10_000, true, 512 * 1024, context);
+    const result = await this.runInternalProcess(this.gitExecutable(), ["-c", "core.fsmonitor=false", "-C", cwd, "rev-parse", "--show-toplevel"], 10_000, true, 512 * 1024, context);
     if (result.code !== 0) return { ok: false, result, target };
     const root = result.stdout.trim();
     const repoRelative = relative(root, target);

package/src/local/job-runner.mjs

@@ -9,6 +9,7 @@ import { createExclusiveFileSync, removeOwnedJsonFileSync, replaceFileAtomically
 import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
 import { currentProcessStartTimeMs } from "./process-identity.mjs";
 import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { persistManagedJobTerminal } from "./managed-job-terminal.mjs";
 
 const RESOURCE_TOKEN = /\{\{resource:([a-z][a-z0-9._-]{0,63})\}\}/g;
 const TEMP_TOKEN = /\{\{temp:([a-z][a-z0-9._-]{0,63})\}\}/g;
@@ -55,14 +56,15 @@ for (const signal of ["SIGTERM", "SIGINT"]) {
 
 const initial = readJson(statusFile, MAX_STATUS_BYTES);
 assertLaunchState(initial);
-createExclusiveFileSync(runnerPidFile, `${JSON.stringify({ pid: process.pid, processStartedAt: RUNNER_PROCESS_STARTED_AT })}\n`, { mode: 0o600 });
 try {
+  createExclusiveFileSync(runnerPidFile, `${JSON.stringify({ pid: process.pid, processStartedAt: RUNNER_PROCESS_STARTED_AT })}\n`, { mode: 0o600 });
   if (recover) await releaseRecoveryClaim();
   const plan = readJson(planFile, 1024 * 1024);
   assertPlanIntegrity(plan, initial);
   await main(plan, initial);
 } catch (error) {
   recordFatalRunnerError(error);
+  process.exitCode = 1;
 }
 
 async function releaseRecoveryClaim() {
@@ -125,7 +127,6 @@ async function main(plan, initial) {
     } catch (error) {
       cleanupError ||= error;
     }
-    rmSync(runtimeDir, { recursive: true, force: true });
   }
 
   const cancelled = mainError instanceof JobCancelledError || existsSync(cancelFile);
@@ -148,17 +149,16 @@ async function main(plan, initial) {
     capture_remaining_bytes: captureBudget.remaining,
     finished_at: new Date().toISOString(),
   };
-  writeJson(resultFile, result, MAX_RESULT_BYTES);
-  updateStatus(status, {
-    status: finalStatus,
-    current_phase: null,
-    current_step: null,
-    finished_at: result.finished_at,
-    error_class: result.error_class || result.cleanup_error_class,
+  const terminal = persistManagedJobTerminal({
+    statusFile, resultFile,
+    artifacts: [runtimeDir, planFile, runnerPidFile, cancelFile],
+    status: { ...status, runner_pid: process.pid, runner_process_started_at: RUNNER_PROCESS_STARTED_AT },
+    result, writeJson,
+    removeFile: (file) => rmSync(file, { recursive: true, force: true }),
+    maxStatusBytes: MAX_STATUS_BYTES, maxResultBytes: MAX_RESULT_BYTES,
   });
-  try { rmSync(planFile, { force: true }); } catch {}
-  try { rmSync(runnerPidFile, { force: true }); } catch {}
-  try { rmSync(cancelFile, { force: true }); } catch {}
+  Object.assign(status, terminal.status);
+  reportTerminalPersistenceFailure(terminal);
 }
 
 function assertLaunchState(status) {
@@ -176,7 +176,6 @@ function assertPlanIntegrity(plan, status) {
 }
 
 function recordFatalRunnerError(error) {
-  rmSync(runtimeDir, { recursive: true, force: true });
   const now = new Date().toISOString();
   let status = {};
   try { status = readJson(statusFile, MAX_STATUS_BYTES); } catch {}
@@ -192,24 +191,33 @@ function recordFatalRunnerError(error) {
     cleanup_error_class: recover ? classifyError(error) : null,
     finished_at: now,
   };
-  try { writeJson(resultFile, result, MAX_RESULT_BYTES); } catch {}
-  try {
-    writeJson(statusFile, {
+  const terminal = persistManagedJobTerminal({
+    statusFile, resultFile,
+    artifacts: [runtimeDir, planFile, runnerPidFile, cancelFile],
+    status: {
       ...status,
-      status: finalStatus,
-      current_phase: null,
-      current_step: null,
       runner_pid: process.pid,
       runner_process_started_at: RUNNER_PROCESS_STARTED_AT,
-      updated_at: now,
-      finished_at: now,
-      error_class: result.error_class,
       cleanup_guarantee: "best-effort-finally-and-recovery",
-    }, MAX_STATUS_BYTES);
-  } catch {}
-  try { rmSync(planFile, { force: true }); } catch {}
-  try { rmSync(runnerPidFile, { force: true }); } catch {}
-  try { rmSync(cancelFile, { force: true }); } catch {}
+    },
+    result, writeJson,
+    removeFile: (file) => rmSync(file, { recursive: true, force: true }),
+    maxStatusBytes: MAX_STATUS_BYTES, maxResultBytes: MAX_RESULT_BYTES,
+  });
+  reportTerminalPersistenceFailure(terminal);
+}
+
+function reportTerminalPersistenceFailure(terminal) {
+  if (terminal.statusPersisted && terminal.artifactsScrubbed && !terminal.statusErrorClass) return;
+  const fields = [
+    `status_persisted=${terminal.statusPersisted}`,
+    `result_persisted=${terminal.resultPersisted}`,
+    `artifacts_scrubbed=${terminal.artifactsScrubbed}`,
+    `status_error=${terminal.statusErrorClass || "none"}`,
+    `result_error=${terminal.resultErrorClass || "none"}`,
+    `cleanup_error=${terminal.cleanupErrorClass || "none"}`,
+  ];
+  process.stderr.write(`managed job terminal persistence incomplete: ${fields.join(" ")}\n`);
 }
 
 async function runStep(step, index, phase, plan, resourceContext, cancellationAware, captureBudget) {

package/src/local/log.mjs

@@ -46,9 +46,21 @@ export function createLogger(options = {}) {
 
   const write = (stream, level, label, color, message, fields) => {
     if (LEVEL_RANK[level] < LEVEL_RANK[minimumLevel]) return;
+    const sanitizedMessage = sanitizeLogText(message, MAX_LOG_MESSAGE_CHARS);
+    if (options.format === "json") {
+      const entry = sanitizeLogValue({
+        timestamp: new Date().toISOString(),
+        level: level === "success" ? "info" : level,
+        component,
+        message: sanitizedMessage,
+        ...(fields && typeof fields === "object" ? fields : {}),
+      });
+      stream.write(`${JSON.stringify(entry)}\n`);
+      return;
+    }
     const prefix = useColor ? `${color}${label}${COLORS.reset}` : label;
     const suffix = formatFields(fields);
-    stream.write(`${prefix} ${component}: ${sanitizeLogText(message, MAX_LOG_MESSAGE_CHARS)}${suffix}\n`);
+    stream.write(`${prefix} ${component}: ${sanitizedMessage}${suffix}\n`);
   };
 
   const event = (level, name, fields = {}, message = "") => {
@@ -83,6 +95,7 @@ export function createLogger(options = {}) {
   return {
     verbose: minimumLevel === "debug",
     level: minimumLevel,
+    format: options.format === "json" ? "json" : "text",
     child(childComponent) {
       return createLogger({ ...options, component: childComponent });
     },