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

package/src/local/managed-job-lock.mjs

@@ -3,17 +3,39 @@ import { lstatSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { currentProcessStartTimeMs, inspectProcessInstance, processStartTimeMs } from "./process-identity.mjs";
-import { readBoundedRegularFileSync } from "./secure-file.mjs";
-import { ownerOnlyFile } from "./state.mjs";
+import { ownerOnlyFile, readBoundedRegularFileWithInfoSync, retryTransientMultipleLinksSync } from "./secure-file.mjs";
+import { exactFilesystemInteger, filesystemIdentity, filesystemTimeMs, sameFilesystemIdentity } from "./filesystem-identity.mjs";
 
 export function acquireRecoveryLock(dir) {
   return acquirePidLock(join(dir, "recovery.lock"), { allowHandoff: true });
 }
 
+export function acquireJobCapacityLock(jobRoot) {
+  return acquirePidLock(join(jobRoot, "capacity.lock"));
+}
+
 export function acquireJobTransitionLock(dir) {
   return acquirePidLock(join(dir, "transition.lock"));
 }
 
+export function activeManagedJobLock(file) {
+  let snapshot;
+  try { snapshot = readPidLockSnapshot(file); } catch {
+    return { active: true, pid: null, reason: "invalid_or_unreadable_lock" };
+  }
+  if (!snapshot) return null;
+  const age = Date.now() - snapshot.info.mtimeMs;
+  if (!snapshot.owner || !Number.isInteger(snapshot.owner.pid) || snapshot.owner.pid <= 0
+      || !Number.isFinite(Date.parse(String(snapshot.owner.startedAt || "")))) {
+    return age < 60_000 ? { active: true, pid: null, reason: "recent_malformed_lock" } : null;
+  }
+  const identity = inspectProcessInstance(snapshot.owner, { maxAgeMs: 5 * 60_000 });
+  if (identity.current || (identity.alive && !identity.reclaimable)) {
+    return { active: true, pid: snapshot.owner.pid, reason: identity.reason };
+  }
+  return null;
+}
+
 function acquirePidLock(file, { allowHandoff = false } = {}) {
   for (let attempt = 0; attempt < 3; attempt += 1) {
     const owner = pidLockOwner(process.pid, currentProcessStartTimeMs());
@@ -54,17 +76,22 @@ function pidLockOwner(pid, startedAtMs) {
 }
 
 function readPidLockSnapshot(file) {
-  let info;
-  try { info = lstatSync(file); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
-  if (info.isSymbolicLink() || !info.isFile()) throw new Error("job lock must be a regular non-symbolic-link file");
-  let owner = null;
+  let opened;
   try {
-    const parsed = JSON.parse(readBoundedRegularFileSync(file, 1024).toString("utf8").trim());
-    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) owner = parsed;
+    opened = retryTransientMultipleLinksSync(() => readBoundedRegularFileWithInfoSync(file, 1024, "job lock", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    }));
   } catch (error) {
-    if (error?.code === "ENOENT") return null;
+    if (error?.code === "ENOENT" || error?.cause?.code === "ENOENT") return null;
+    throw error;
   }
-  return { owner, info: pidLockIdentity(info) };
+  let owner = null;
+  try {
+    const parsed = JSON.parse(opened.buffer.toString("utf8").trim());
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) owner = parsed;
+  } catch { /* Successfully read malformed JSON may be reclaimed only after the stale grace. */ }
+  return { owner, info: pidLockIdentity(opened.identityInfo, opened.identity) };
 }
 
 function removePidLockOwnedBy(file, token) {
@@ -75,7 +102,7 @@ function removePidLockOwnedBy(file, token) {
 
 function removePidLockSnapshot(file, snapshot) {
   let current;
-  try { current = lstatSync(file); } catch (error) { return error?.code === "ENOENT"; }
+  try { current = lstatSync(file, { bigint: true }); } catch (error) { return error?.code === "ENOENT"; }
   if (current.isSymbolicLink() || !current.isFile()) return false;
   if (!samePidLockIdentity(snapshot.info, pidLockIdentity(current))) return false;
   if (snapshot.owner?.token) {
@@ -85,12 +112,17 @@ function removePidLockSnapshot(file, snapshot) {
   try { rmSync(file); return true; } catch (error) { return error?.code === "ENOENT"; }
 }
 
-function pidLockIdentity(info) {
-  return { dev: Number(info.dev), ino: Number(info.ino), size: Number(info.size), mtimeMs: Number(info.mtimeMs) };
+function pidLockIdentity(info, identity = filesystemIdentity(info, "managed-job lock")) {
+  return {
+    ...identity,
+    size: exactFilesystemInteger(info.size, "managed-job lock size"),
+    nlink: exactFilesystemInteger(info.nlink, "managed-job lock link count"),
+    mtimeMs: filesystemTimeMs(info.mtimeMs, "managed-job lock modification time"),
+  };
 }
 
 function samePidLockIdentity(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.nlink === right.nlink && left.mtimeMs === right.mtimeMs;
 }
 
 function replacePrivateTextFile(file, content) {

package/src/local/managed-job-plan.mjs

@@ -2,7 +2,6 @@ import { createHash } from "node:crypto";
 import { lstatSync, realpathSync, statSync } from "node:fs";
 import { basename, isAbsolute, relative, resolve, sep } from "node:path";
 import { readBoundedRegularFileWithInfoSync } from "./secure-file.mjs";
-import { clampInteger } from "./numbers.mjs";
 
 const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
 const RESOURCE_TOKEN = /\{\{resource:([a-z][a-z0-9._-]{0,63})\}\}/g;
@@ -17,10 +16,10 @@ export function validateResourceName(value) {
   return name;
 }
 
-export function inspectResourceFile(inputPath, { allowInsecurePermissions = false, includeHash = false } = {}) {
+export function inspectResourceFile(inputPath, { allowInsecurePermissions = false, includeHash = false, includeContent = false } = {}) {
   const path = resolve(String(inputPath || ""));
   const canonical = realpathFile(path);
-  const { buffer: content, info } = readBoundedRegularFileWithInfoSync(canonical, MAX_RESOURCE_BYTES);
+  const { buffer: content, info } = readBoundedRegularFileWithInfoSync(canonical, MAX_RESOURCE_BYTES, "resource file", { verifyPathIdentity: true });
   if (process.platform !== "win32" && !allowInsecurePermissions && (info.mode & 0o077) !== 0) {
     throw new Error("resource file is readable by group or others; restrict permissions or use --allow-insecure-permissions");
   }
@@ -33,6 +32,7 @@ export function inspectResourceFile(inputPath, { allowInsecurePermissions = fals
     updatedAt: new Date().toISOString(),
     allowInsecurePermissions: allowInsecurePermissions === true,
     ...(includeHash ? { sha256: createHash("sha256").update(content).digest("hex") } : {}),
+    ...(includeContent ? { content } : {}),
   };
 }
 
@@ -53,10 +53,10 @@ export function validatePlan(args, context) {
   if (!args || typeof args !== "object" || Array.isArray(args)) throw new Error("job arguments must be an object");
   const allowed = new Set(["name", "steps", "finally_steps", "temporary_files"]);
   for (const key of Object.keys(args)) if (!allowed.has(key)) throw new Error(`job contains unknown field: ${key}`);
-  const name = String(args.name || "managed job").trim().slice(0, 128) || "managed job";
+  const name = args.name === undefined ? "managed job" : boundedString(args.name, 128, "name").trim() || "managed job";
   const steps = validateSteps(args.steps, "steps", context);
-  const finallySteps = validateSteps(args.finally_steps || [], "finally_steps", context, true);
-  const temporaryFiles = validateTemporaryFiles(args.temporary_files || []);
+  const finallySteps = validateSteps(args.finally_steps === undefined ? [] : args.finally_steps, "finally_steps", context, true);
+  const temporaryFiles = validateTemporaryFiles(args.temporary_files === undefined ? [] : args.temporary_files);
   if (!steps.length) throw new Error("steps must contain at least one step");
   return {
     version: 1,
@@ -83,7 +83,7 @@ function validateTemporaryFiles(value) {
     const content = boundedString(item.content, 256 * 1024, `temporary_files[${index}].content`);
     totalBytes += Buffer.byteLength(content);
     if (totalBytes > MAX_TEMPORARY_FILE_BYTES) throw new Error(`temporary file contents exceed ${MAX_TEMPORARY_FILE_BYTES} bytes`);
-    return { name, content, executable: item.executable === true };
+    return { name, content, executable: optionalBoolean(item.executable, `temporary_files[${index}].executable`) };
   });
 }
 
@@ -113,19 +113,37 @@ function validateSteps(value, label, context, allowEmpty = false) {
       env_resources: envResources,
       stdin,
       stdin_resource: stdinResource,
-      timeout_seconds: clampInteger(input.timeout_seconds, 600, 1, 3600),
-      allow_failure: input.allow_failure === true,
-      capture_output: input.capture_output === "discard" ? "discard" : "redacted",
+      timeout_seconds: optionalInteger(input.timeout_seconds, 600, 1, 3600, `${label}[${index}].timeout_seconds`),
+      allow_failure: optionalBoolean(input.allow_failure, `${label}[${index}].allow_failure`),
+      capture_output: validateCaptureOutput(input.capture_output, `${label}[${index}].capture_output`),
     };
   });
 }
 
+function optionalBoolean(value, label) {
+  if (value === undefined) return false;
+  if (typeof value !== "boolean") throw new Error(`${label} must be a boolean`);
+  return value;
+}
+
+function optionalInteger(value, defaultValue, min, max, label) {
+  if (value === undefined) return defaultValue;
+  if (!Number.isInteger(value) || value < min || value > max) throw new Error(`${label} must be an integer between ${min} and ${max}`);
+  return value;
+}
+
+function validateCaptureOutput(value, label) {
+  if (value === undefined || value === "redacted") return "redacted";
+  if (value === "discard") return "discard";
+  throw new Error(`${label} must be redacted or discard`);
+}
+
 function validateEnv(value, label) {
   if (value === undefined) return {};
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
   const entries = Object.entries(value);
   if (entries.length > 64) throw new Error(`${label} has too many entries`);
-  const out = {};
+  const out = Object.create(null);
   for (const [key, raw] of entries) {
     if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)) throw new Error(`${label} contains invalid variable name: ${key}`);
     out[key] = boundedString(raw, 16 * 1024, `${label}.${key}`);
@@ -138,7 +156,7 @@ function validateEnvResources(value, label) {
   if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
   const entries = Object.entries(value);
   if (entries.length > 32) throw new Error(`${label} has too many entries`);
-  const out = {};
+  const out = Object.create(null);
   for (const [key, raw] of entries) {
     if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)) throw new Error(`${label} contains invalid variable name: ${key}`);
     out[key] = validateResourceName(raw);
@@ -175,8 +193,14 @@ function referencedResources(steps, registry) {
 
 export function normalizeResourceRegistry(resources) {
   const out = Object.create(null);
-  if (!resources || typeof resources !== "object" || Array.isArray(resources)) return out;
-  for (const [rawName, rawValue] of Object.entries(resources).slice(0, MAX_RESOURCES)) {
+  if (resources === undefined || resources === null) return out;
+  if (typeof resources !== "object" || Array.isArray(resources)) throw new Error("local resource registry must be an object");
+  let count = 0;
+  for (const rawName in resources) {
+    if (!Object.hasOwn(resources, rawName)) continue;
+    count += 1;
+    if (count > MAX_RESOURCES) throw new Error(`local resource registry limit exceeded (${MAX_RESOURCES})`);
+    const rawValue = resources[rawName];
     const name = validateResourceName(rawName);
     if (!rawValue || rawValue.kind !== "file" || typeof rawValue.path !== "string") continue;
     out[name] = {

package/src/local/managed-job-projection.mjs

@@ -31,23 +31,27 @@ export function reviewablePlan(plan) {
   };
 }
 
+/**
+ * Project owner-only managed-job timing out of delegated result reads.
+ * @param {Record<string, unknown> | null | undefined} result
+ * @param {{includeResourceAdmissionTiming?: boolean}} [options]
+ */
+export function projectManagedJobResult(result, { includeResourceAdmissionTiming = false } = {}) {
+  if (!result || includeResourceAdmissionTiming) return result;
+  const projectSteps = (/** @type {unknown} */ steps) => Array.isArray(steps) ? steps.map((/** @type {unknown} */ step) => {
+    if (!step || typeof step !== "object" || Array.isArray(step)) return step;
+    const { resource_admission_ms: _resourceAdmissionMs, ...projected } = /** @type {Record<string, unknown>} */ (step);
+    return projected;
+  }) : steps;
+  return { ...result, steps: projectSteps(result.steps), finally_steps: projectSteps(result.finally_steps) };
+}
+
 /**
  * Return the stable public status shape without runner identity or internal paths.
- * @param {{
- *   job_id?: unknown,
- *   name?: unknown,
- *   status?: unknown,
- *   created_at?: unknown,
- *   started_at?: unknown,
- *   finished_at?: unknown,
- *   current_phase?: unknown,
- *   current_step?: unknown,
- *   approval?: unknown,
- *   plan_sha256?: unknown,
- *   cleanup_guarantee?: unknown,
- *   error_class?: unknown,
- *   recovery_attempts?: unknown
- * }} status
+ * @param {{job_id?: unknown, name?: unknown, status?: unknown, created_at?: unknown, started_at?: unknown,
+ * finished_at?: unknown, current_phase?: unknown, current_step?: unknown, approval?: unknown, plan_sha256?: unknown,
+ * cleanup_guarantee?: unknown, error_class?: unknown, recovery_attempts?: unknown, result_persisted?: unknown,
+ * terminal_record_error_class?: unknown, artifact_cleanup_pending?: unknown, artifact_cleanup_error_class?: unknown}} status
  */
 export function publicStatus(status) {
   return {
@@ -64,5 +68,9 @@ export function publicStatus(status) {
     cleanup_guarantee: status.cleanup_guarantee ?? "best-effort-finally-and-recovery",
     error_class: status.error_class ?? null,
     recovery_attempts: Number(status.recovery_attempts || 0),
+    result_persisted: typeof status.result_persisted === "boolean" ? status.result_persisted : null,
+    terminal_record_error_class: status.terminal_record_error_class ?? null,
+    artifact_cleanup_pending: status.artifact_cleanup_pending === true,
+    artifact_cleanup_error_class: status.artifact_cleanup_error_class ?? null,
   };
 }

package/src/local/managed-job-retention.mjs

@@ -0,0 +1,128 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { MANAGED_JOB_ID } from "./managed-job-directory.mjs";
+import { inspectManagedJobDirectoryGeneration, pruneRetiredManagedJobDirectories, removeManagedJobDirectoryIfCurrent } from "./managed-job-directory-generation.mjs";
+import { managedJobCapacitySnapshot, MAX_JOBS } from "./managed-job-capacity.mjs";
+import { runnerProcessIsCurrent } from "./managed-job-runner.mjs";
+import { acquireJobTransitionLock } from "./managed-job-lock.mjs";
+import { atomicWriteJson, readJson, resourceErrorClass, safeReadDir } from "./managed-job-storage.mjs";
+import { ACTIVE_JOB_STATES, isTerminalManagedJobStatus, persistManagedJobTerminal } from "./managed-job-terminal.mjs";
+import { scrubTerminalJobArtifacts } from "./managed-job-terminal-maintenance.mjs";
+const JOB_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+const STAGED_PLAN_RETENTION_MS = 24 * 60 * 60 * 1000;
+export const PLAN_RETAINING_STATES = new Set(["staged", ...ACTIVE_JOB_STATES]);
+export function pruneManagedJobs({ jobRoot, logger = console, reserveSlots = 0 }) {
+  const reserved = Math.max(0, Math.min(MAX_JOBS, Math.floor(Number(reserveSlots) || 0)));
+  const targetMaximum = MAX_JOBS - reserved;
+  pruneRetiredManagedJobDirectories(jobRoot, logger);
+  const entries = [];
+  for (const entry of safeReadDir(jobRoot)) {
+    if (!MANAGED_JOB_ID.test(entry.name)) continue;
+    if (!entry.isDirectory()) { logger.warn?.("managed job pruning retained wrong-type job state", { error_class: "integrity_error" }); continue; }
+    const dir = join(jobRoot, entry.name);
+    let status; let mtime;
+    let generation;
+    try {
+      status = readJson(join(dir, "status.json"), 256 * 1024, "job status");
+      const observed = inspectManagedJobDirectoryGeneration(dir);
+      mtime = observed.mtimeMs;
+      generation = observed.identity;
+    } catch (error) {
+      logger.warn?.("managed job pruning skipped unreadable state; retaining it for inspection", { error_class: resourceErrorClass(error) });
+      continue;
+    }
+    if (!status) {
+      const fallbackOwner = { startedAt: new Date(mtime).toISOString() };
+      let runnerAlive;
+      try { runnerAlive = runnerProcessIsCurrent(fallbackOwner, dir, { ownerOnly: true }); }
+      catch (error) {
+        logger.warn?.("managed job pruning skipped unreadable runner ownership; retaining it for inspection", { error_class: resourceErrorClass(error) });
+        entries.push({ dir, status, mtime });
+        continue;
+      }
+      if (!runnerAlive && Date.now() - mtime > 60_000) {
+        removeManagedJobDirectoryIfCurrent(dir, generation);
+        continue;
+      }
+    }
+    if (status && status.job_id !== entry.name) {
+      logger.warn?.("managed job pruning skipped mismatched directory identity; retaining it for inspection", { error_class: "integrity_error" });
+      entries.push({ dir, status: null, mtime });
+      continue;
+    }
+    if (status?.status === "staged" && stagedPlanExpired(status, mtime)) {
+      const transition = acquireJobTransitionLock(dir);
+      if (!transition) {
+        entries.push({ dir, status, mtime });
+        continue;
+      }
+      try {
+        try { status = readJson(join(dir, "status.json"), 256 * 1024, "job status"); }
+        catch (error) {
+          logger.warn?.("managed job pruning skipped unreadable staged state; retaining it for inspection", { error_class: resourceErrorClass(error) });
+          entries.push({ dir, status, mtime });
+          continue;
+        }
+        if (status?.status === "staged" && stagedPlanExpired(status, mtime)) status = expireStagedJob(dir, status);
+      } finally {
+        transition.release();
+      }
+    }
+    if (status && !PLAN_RETAINING_STATES.has(status.status) && !isTerminalManagedJobStatus(status.status)) {
+      logger.warn?.("managed job pruning skipped invalid status; retaining it for inspection", { error_class: "integrity_error" }); entries.push({ dir, status, mtime }); continue;
+    }
+    if (status && isTerminalManagedJobStatus(status.status)) {
+      try {
+        scrubTerminalJobArtifacts(dir, status);
+        generation = inspectManagedJobDirectoryGeneration(dir).identity;
+      } catch (error) {
+        logger.warn?.("managed job pruning retained inconsistent terminal state", { error_class: error?.code === "integrity_error" ? "integrity_error" : resourceErrorClass(error) });
+        entries.push({ dir, status: null, mtime }); continue;
+      }
+    }
+    entries.push({ dir, status, mtime, generation });
+  }
+  const finished = entries
+    .filter(({ status }) => status && isTerminalManagedJobStatus(status.status))
+    .sort((a, b) => terminalRetentionTime(b.status, b.mtime) - terminalRetentionTime(a.status, a.mtime));
+  const now = Date.now();
+  for (const item of finished) {
+    if (now - terminalRetentionTime(item.status, item.mtime) > JOB_RETENTION_MS) {
+      removeManagedJobDirectoryIfCurrent(item.dir, item.generation);
+    }
+  }
+  const retainedCount = () => managedJobCapacitySnapshot(jobRoot).retained_state;
+  if (retainedCount() <= targetMaximum) return;
+  const removable = entries
+    .filter(({ status }) => status && isTerminalManagedJobStatus(status.status))
+    .sort((a, b) => terminalRetentionTime(a.status, a.mtime) - terminalRetentionTime(b.status, b.mtime));
+  for (const item of removable) {
+    if (retainedCount() <= targetMaximum) break;
+    removeManagedJobDirectoryIfCurrent(item.dir, item.generation);
+  }
+}
+function stagedPlanExpired(status, fallbackMtime) {
+  const createdAt = Date.parse(String(status?.created_at || ""));
+  const baseline = Number.isFinite(createdAt) ? createdAt : fallbackMtime;
+  return Number.isFinite(baseline) && Date.now() - baseline > STAGED_PLAN_RETENTION_MS;
+}
+function terminalRetentionTime(status, fallbackMtime) {
+  const finishedAt = Date.parse(String(status?.finished_at || ""));
+  return Number.isFinite(finishedAt) ? finishedAt : fallbackMtime;
+}
+function expireStagedJob(dir, status) {
+  const finishedAt = new Date().toISOString();
+  const result = {
+    job_id: status.job_id, name: status.name, status: "expired_before_start",
+    steps: [], finally_steps: [], error_class: "expired", cleanup_error_class: null, finished_at: finishedAt,
+  };
+  const terminal = persistManagedJobTerminal({
+    statusFile: join(dir, "status.json"), resultFile: join(dir, "result.json"),
+    artifacts: [join(dir, "runtime"), join(dir, "plan.json"), join(dir, "runner.pid"), join(dir, "cancel")],
+    status: { ...status, cleanup_guarantee: "not-started" }, result,
+    writeJson: atomicWriteJson, removeFile: (file) => rmSync(file, { recursive: true, force: true }),
+    maxStatusBytes: 256 * 1024, maxResultBytes: 4 * 1024 * 1024, classifyPersistenceError: resourceErrorClass,
+  });
+  if (!terminal.statusPersisted) throw new Error(`managed job staged expiry status persistence failed: ${terminal.statusErrorClass}`);
+  return terminal.status;
+}

package/src/local/managed-job-runner-claim.mjs

@@ -0,0 +1,70 @@
+import { join } from "node:path";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import { inspectPathIfPresentSync, ownerOnlyFile, readBoundedRegularFileSync, retryTransientMultipleLinksSync } from "./secure-file.mjs";
+
+const RUNNER_CLAIM_BYTES = 1024;
+const RUNNER_CLAIM_WAIT_MS = 30_000;
+
+export function publishProvisionalRunnerClaim(dir, pid, launchToken) {
+  if (!/^[a-f0-9]{32}$/.test(String(launchToken || ""))) throw new Error("runner launch token is invalid");
+  const file = join(dir, "runner.pid");
+  const claim = { pid, startedAt: new Date().toISOString(), launchToken, committed: false };
+  try {
+    createExclusiveFileSync(file, `${JSON.stringify(claim)}\n`, { mode: 0o600 });
+  } catch (error) {
+    if (error?.code !== "EEXIST") throw error;
+    const existing = readRunnerClaim(file, "managed job runner claim already exists but is unreadable");
+    if (Number(existing?.pid) !== pid || existing?.launchToken !== launchToken) {
+      throw new Error("managed job runner claim is owned by another process or launch");
+    }
+    if (existing.committed === true) return;
+    if (existing.committed !== false) throw new Error("managed job runner claim has an invalid provisional state");
+    claim.startedAt = typeof existing.startedAt === "string" && existing.startedAt ? existing.startedAt : claim.startedAt;
+  }
+  ownerOnlyFile(file);
+  replaceFileAtomicallySync(file, `${JSON.stringify({ ...claim, committed: true })}\n`, { mode: 0o600 });
+}
+
+export async function confirmRunnerClaim({
+  file, pid, processStartedAt, launchToken, inspectPath = inspectPathIfPresentSync,
+  waitMs = RUNNER_CLAIM_WAIT_MS,
+}) {
+  const exact = { pid, startedAt: new Date().toISOString(), processStartedAt };
+  if (!launchToken) {
+    createExclusiveFileSync(file, `${JSON.stringify(exact)}\n`, { mode: 0o600 });
+    return;
+  }
+  if (!/^[a-f0-9]{32}$/.test(launchToken)) throw new Error("runner launch token is invalid");
+  const deadline = createMonotonicDeadline(waitMs);
+  while (!deadline.expired()) {
+    if (!inspectPath(file, "managed job runner claim")) {
+      await new Promise((resolvePromise) => { setTimeout(resolvePromise, 10); });
+      continue;
+    }
+    const provisional = readRunnerClaim(file, "runner ownership claim is unreadable");
+    if (Number(provisional?.pid) !== pid || provisional?.launchToken !== launchToken) {
+      throw new Error("runner ownership claim does not match the spawned process");
+    }
+    if (provisional.committed !== true) {
+      await new Promise((resolvePromise) => { setTimeout(resolvePromise, Math.min(10, Math.max(1, deadline.remainingMs()))); });
+      continue;
+    }
+    exact.startedAt = typeof provisional.startedAt === "string" && provisional.startedAt
+      ? provisional.startedAt
+      : exact.startedAt;
+    replaceFileAtomicallySync(file, `${JSON.stringify(exact)}\n`, { mode: 0o600 });
+    return;
+  }
+  throw new Error("runner ownership claim was not published before startup deadline");
+}
+
+function readRunnerClaim(file, message) {
+  try {
+    const bytes = retryTransientMultipleLinksSync(() => readBoundedRegularFileSync(file, RUNNER_CLAIM_BYTES, "managed job runner claim", {
+      verifyPathIdentity: true,
+      rejectMultipleLinks: true,
+    }));
+    return JSON.parse(bytes.toString("utf8"));
+  } catch (error) { throw new Error(message, { cause: error }); }
+}

package/src/local/managed-job-runner.mjs

@@ -1,15 +1,19 @@
 import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
 import { closeSync } from "node:fs";
-import { basename, join } from "node:path";
+import { join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { inspectProcessInstance } from "./process-identity.mjs";
 import { classifyOperationalError } from "./log.mjs";
-import { ownerOnlyFile } from "./state.mjs";
+import { ownerOnlyFile } from "./secure-file.mjs";
 import { openPrivateAppendFile, readBoundedFile, trimDiagnosticFile } from "./managed-job-storage.mjs";
+import { publishProvisionalRunnerClaim } from "./managed-job-runner-claim.mjs";
+import { EXECUTION_SURFACE, withExecutionSurface } from "./execution-surface.mjs";
 
 const RUNNER_PATH = fileURLToPath(new URL("./job-runner.mjs", import.meta.url));
 
 export function launchRunner(dir, recover = false, recoveryToken = "", options = {}) {
+  const launchToken = randomBytes(16).toString("hex");
   const args = [RUNNER_PATH, "--job-dir", dir];
   if (recover) args.push("--recover");
   const stdoutFile = join(dir, "runner.out.log");
@@ -28,7 +32,7 @@ export function launchRunner(dir, recover = false, recoveryToken = "", options =
       stdio: ["ignore", stdoutFd, stderrFd],
       windowsHide: true,
       shell: false,
-      env: recoveryToken ? { ...process.env, MBM_RECOVERY_LOCK_TOKEN: recoveryToken } : process.env,
+      env: managedRunnerEnvironment({ fullEnv: options.fullEnv === true, recoveryToken, launchToken, source: options.env || process.env }),
     });
   } finally {
     if (stdoutFd !== undefined) closeSync(stdoutFd);
@@ -39,13 +43,19 @@ export function launchRunner(dir, recover = false, recoveryToken = "", options =
   const logger = options.logger || console;
   child.once?.("error", (error) => {
     logger.error?.("managed job runner process reported an asynchronous failure", {
-      job_id: basename(dir),
       recovery: recover,
       error_class: classifyOperationalError(error),
     });
   });
   const pid = Number(child.pid);
   if (!Number.isInteger(pid) || pid <= 0) throw new Error("managed job runner did not receive a process id");
+  try {
+    publishProvisionalRunnerClaim(dir, pid, launchToken);
+  } catch (error) {
+    try { child.kill?.("SIGKILL"); }
+    catch { /* An uncommitted two-phase runner claim prevents this child from executing even if local kill delivery fails. */ }
+    throw error;
+  }
   child.unref();
   return pid;
 }
@@ -63,11 +73,26 @@ export function runnerProcessIsCurrent(status, dir, { ownerOnly = false } = {})
 }
 
 function readRunnerOwner(dir, fallback = {}) {
-  try {
-    const parsed = JSON.parse(readBoundedFile(join(dir, "runner.pid"), 1024).toString("utf8"));
-    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return { ...fallback };
-    return { ...fallback, ...parsed };
-  } catch {
-    return { ...fallback };
+  let text;
+  try { text = readBoundedFile(join(dir, "runner.pid"), 1024).toString("utf8"); }
+  catch (error) { if (error?.code === "ENOENT") return { ...fallback }; throw error; }
+  let parsed;
+  try { parsed = JSON.parse(text); }
+  catch (error) { throw new Error("managed job runner claim is invalid", { cause: error }); }
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) throw new Error("managed job runner claim is invalid");
+  return { ...fallback, ...parsed };
+}
+
+export function managedRunnerEnvironment({ fullEnv = false, recoveryToken = "", launchToken = "", source = process.env } = {}) {
+  const env = fullEnv ? { ...source } : {};
+  if (!fullEnv) {
+    for (const key of ["PATH", "HOME", "USERPROFILE", "SystemRoot", "WINDIR", "COMSPEC", "PATHEXT", "LANG", "LC_ALL", "LC_CTYPE", "TMPDIR", "TEMP", "TMP", "AGENT_RESOURCE_COORDINATOR_ROOT", "AGENT_BUILD_ROOT"]) {
+      if (typeof source[key] === "string" && source[key]) env[key] = source[key];
+    }
   }
+  if (recoveryToken) env.MBM_RECOVERY_LOCK_TOKEN = recoveryToken;
+  else delete env.MBM_RECOVERY_LOCK_TOKEN;
+  if (launchToken) env.MBM_RUNNER_LAUNCH_TOKEN = launchToken;
+  else delete env.MBM_RUNNER_LAUNCH_TOKEN;
+  return withExecutionSurface(env, EXECUTION_SURFACE.managedJob);
 }

package/src/local/managed-job-storage.mjs

@@ -1,8 +1,10 @@
 import { closeSync, constants as fsConstants, ftruncateSync, readSync, readdirSync, writeSync } from "node:fs";
 import { dirname } from "node:path";
+
+const MANAGED_STATE_READ_ATTEMPTS = 4;
 import { replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { openRegularFileSync, readBoundedRegularFileSync } from "./secure-file.mjs";
-import { ensureOwnerOnlyDir, ownerOnlyFile } from "./state.mjs";
+import { ensureOwnerOnlyDir, ownerOnlyFile } from "./secure-file.mjs";
 
 export function atomicWriteJson(file, value, maxBytes) {
   ensureOwnerOnlyDir(dirname(file));
@@ -12,11 +14,21 @@ export function atomicWriteJson(file, value, maxBytes) {
   ownerOnlyFile(file);
 }
 
-export function readJson(file, maxBytes, label = "JSON") {
+export function readJson(file, maxBytes, label = "JSON", options = {}) {
+  const readFile = typeof options.readFile === "function" ? options.readFile : readBoundedRegularFileSync;
   let buffer;
-  try { buffer = readBoundedFile(file, maxBytes); } catch (error) {
-    if (error?.code === "ENOENT") return null;
-    throw new Error(`${label} is unavailable (${resourceErrorClass(error)})`);
+  for (let attempt = 1; attempt <= MANAGED_STATE_READ_ATTEMPTS; attempt += 1) {
+    try {
+      buffer = readFile(file, maxBytes, "managed job state", {
+        verifyPathIdentity: true,
+        rejectMultipleLinks: true,
+      });
+      break;
+    } catch (error) {
+      if (error?.code === "ENOENT") return null;
+      if (error?.code === "MBM_IDENTITY_CHANGED" && attempt < MANAGED_STATE_READ_ATTEMPTS) continue;
+      throw new Error(`${label} is unavailable (${resourceErrorClass(error)})`, { cause: error });
+    }
   }
   let text;
   try { text = new TextDecoder("utf-8", { fatal: true }).decode(buffer); } catch {
@@ -41,7 +53,7 @@ export function openPrivateAppendFile(file) {
   return openRegularFileSync(
     file,
     Number(fsConstants.O_WRONLY) | Number(fsConstants.O_CREAT) | Number(fsConstants.O_APPEND),
-    { label: "runner diagnostic path", mode: 0o600, chmod: 0o600 },
+    { label: "runner diagnostic path", mode: 0o600, chmod: 0o600, rejectMultipleLinks: true },
   ).fd;
 }
 
@@ -51,6 +63,7 @@ export function trimDiagnosticFile(file, maxBytes = 64 * 1024, keepBytes = 32 *
     const opened = openRegularFileSync(file, fsConstants.O_RDWR, {
       label: "runner diagnostic path",
       chmod: 0o600,
+      rejectMultipleLinks: true,
     });
     fd = opened.fd;
     if (opened.info.size <= maxBytes) return;
@@ -79,10 +92,13 @@ export function trimDiagnosticFile(file, maxBytes = 64 * 1024, keepBytes = 32 *
 }
 
 export function resourceErrorClass(error) {
+  if (error?.code === "integrity_error") return "integrity_error";
+  if (error?.code === "MBM_IDENTITY_CHANGED" || error?.cause?.code === "MBM_IDENTITY_CHANGED") return "identity_changed";
   const message = String(error?.message || error || "");
   if (/permission|EACCES|EPERM/i.test(message)) return "permission_denied";
   if (/not found|ENOENT/i.test(message)) return "not_found";
   if (/symbolic link/i.test(message)) return "symbolic_link_denied";
+  if (/multiple hard links/i.test(message)) return "insecure_links";
   if (/readable by group|permissions/i.test(message)) return "insecure_permissions";
   if (/exceeds/i.test(message)) return "size_limit";
   return "resource_unavailable";