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

package/src/local/resource-admission-diagnostics.mjs

@@ -0,0 +1,52 @@
+const LOGGABLE_ADMISSION_REASONS = new Set([
+  "resource_capacity", "project_resource_busy", "host_pressure_red", "disk_reserve_floor",
+  "cpu_reservation", "io_reservation", "memory_reservation", "cpu_pressure_window",
+  "cpu_request_exceeds_launch_window", "fairness_wait", "coordinator_busy", "resource_busy",
+]);
+const LOGGABLE_PRESSURE_STATES = new Set(["green", "yellow", "red", "unknown"]);
+
+export function resourceAdmissionGuardrailSnapshot() {
+  return {
+    scope: "machine-user-cross-process",
+    model: "work-conserving-multi-resource",
+    durable_process_group_leases: true,
+    priority_aging: true,
+    light_operations_bypass: true,
+    default_compiler_jobs: 3,
+    hard_resource_quota: false,
+  };
+}
+
+export function resourceAdmissionLogFields(error) {
+  if (error?.details?.reason !== "resource_admission") return {};
+  const reason = String(error.details.admission_reason || "resource_busy");
+  const pressure = String(error.details.pressure_state || "unknown");
+  return {
+    resource_admission_reason: LOGGABLE_ADMISSION_REASONS.has(reason) ? reason : "resource_busy",
+    resource_pressure_state: LOGGABLE_PRESSURE_STATES.has(pressure) ? pressure : "unknown",
+  };
+}
+
+export async function resourceAdmissionDiagnostic(snapshotFunction, classifyError) {
+  if (typeof snapshotFunction !== "function") return { snapshot: null, check: null };
+  try {
+    const snapshot = await snapshotFunction();
+    return {
+      snapshot,
+      check: {
+        layer: "local-resource-admission",
+        ok: snapshot?.healthy === true,
+        pressure_state: snapshot?.pressure?.state || "unknown",
+        active_leases: Number(snapshot?.active_leases) || 0,
+        active_waiters: Number(snapshot?.waiters?.active) || 0,
+        fairness_drain_active: snapshot?.waiters?.drain_active === true,
+      },
+    };
+  } catch (error) {
+    const errorClass = classifyError(error);
+    return {
+      snapshot: { healthy: false, error_class: errorClass },
+      check: { layer: "local-resource-admission", ok: false, error_class: errorClass },
+    };
+  }
+}

package/src/local/resource-admission-policy.mjs

@@ -0,0 +1,115 @@
+import { aggregateResourceLeases, resourceRequestIncrement } from "./resource-lease-accounting.mjs";
+import { unobservedResourceCpu } from "./resource-cpu-window.mjs";
+import { resourceDiskHardFloorBytes } from "./resource-disk-headroom.mjs";
+import { optionalResourceNumber, resourcePressureState } from "./resource-pressure.mjs";
+const NON_RETRYABLE_ADMISSION_REASONS = new Set(["cpu_request_exceeds_launch_window"]);
+
+export function resourceAdmissionDecisionRetryable(decision) {
+  return !NON_RETRYABLE_ADMISSION_REASONS.has(decision?.reason);
+}
+
+export function evaluateResourceAdmission(host, leases, request, _now = Date.now(), context = {}) {
+  if (!request?.heavy) return { admitted: true, state: "light", reason: "light_bypass" };
+  const accounting = context?.accounting || {};
+  const cpuCores = Math.max(1, Number(host?.cpu_cores) || 1);
+  const totalMemoryMb = Math.max(1024, Number(host?.total_memory_mb) || 1024);
+  const used = aggregateResourceLeases(leases, accounting);
+  const unobservedCpu = unobservedResourceCpu(leases, accounting, host?.sampled_at_ms);
+  const pressure = resourcePressureState(host, used);
+  const diskReclaim = isDiskReclaimRequest(request);
+  const diskOnlyCritical = diskReclaim && pressure.state === "red"
+    && pressure.critical_reasons?.length === 1 && pressure.critical_reasons[0] === "disk_free_headroom_critical";
+  const limits = resourceLimits(cpuCores, totalMemoryMb, request.priority, diskOnlyCritical ? "yellow" : pressure.state, pressure.reasons);
+  const declared = {
+    cpu: request.unbounded ? limits.cpu : Math.max(0, Number(request.cpu) || 0),
+    io: Math.max(0, Number(request.io) || 0),
+    memory_mb: Math.max(0, Number(request.memory_mb) || 0),
+    disk_reserve_bytes: Math.max(0, Number(request.disk_reserve_bytes) || 0),
+  };
+  const requested = resourceRequestIncrement(leases, { ...request, ...declared, unbounded: false }, accounting);
+  const decision = {
+    admitted: false, state: pressure.state, reason: "resource_capacity",
+    pressure_reasons: pressure.reasons, limits, used, requested, reservation: declared,
+    cpu_window: { observed_busy_cores: optionalResourceNumber(host?.cpu_busy_cores), unobserved_reserved_cpu: unobservedCpu },
+  };
+  const bestCaseCpuLimit = resourceLimits(cpuCores, totalMemoryMb, request.priority, "green").cpu;
+  if (!request.unbounded && requested.cpu > bestCaseCpuLimit + 0.25) {
+    return { ...decision, reason: "cpu_request_exceeds_launch_window" };
+  }
+  const ignoredContention = new Set(accounting.ancestorLeaseIds || []);
+  if (request.contention_key && leases.some((lease) => lease?.request?.contention_key === request.contention_key
+      && !ignoredContention.has(lease?.lease_id))) return { ...decision, reason: "project_resource_busy" };
+  if (pressure.state === "red" && !diskOnlyCritical) return { ...decision, reason: "host_pressure_red" };
+  if (!diskReclaim && !diskReservationFits(host, used.disk_reserve_bytes, requested.disk_reserve_bytes)) return { ...decision, reason: "disk_reserve_floor" };
+  if (used.cpu + requested.cpu > limits.cpu * limits.cpu_overcommit + 0.01) return { ...decision, reason: "cpu_reservation" };
+  if (used.io + requested.io > limits.io * limits.io_overcommit + 0.01) return { ...decision, reason: "io_reservation" };
+  if (used.memory_mb + requested.memory_mb > limits.memory_mb * limits.memory_overcommit + 1) return { ...decision, reason: "memory_reservation" };
+  const currentCpu = Number.isFinite(Number(host?.cpu_busy_cores)) ? Number(host.cpu_busy_cores) : 0;
+  if (currentCpu + unobservedCpu + requested.cpu > limits.cpu + 0.25) return { ...decision, reason: "cpu_pressure_window" };
+  return { ...decision, admitted: true, reason: diskOnlyCritical ? "admitted_disk_reclaim" : pressure.state === "yellow" ? "admitted_yellow" : "admitted_green" };
+}
+
+export function resourcePressureSnapshot(host, leases, priority = "ordinary", _now = Date.now(), accounting = {}, request = null) {
+  const cpuCores = Math.max(1, Number(host?.cpu_cores) || 1);
+  const totalMemoryMb = Math.max(1024, Number(host?.total_memory_mb) || 1024);
+  const used = aggregateResourceLeases(leases, accounting);
+  const pressure = resourcePressureState(host, used);
+  const observedCpu = optionalResourceNumber(host?.cpu_busy_cores);
+  const unobservedCpu = unobservedResourceCpu(leases, accounting, host?.sampled_at_ms);
+  const snapshot = { state: pressure.state, reasons: pressure.reasons, used,
+    observed: {
+      cpu_busy_cores: observedCpu,
+      reserved_cpu: used.cpu,
+      unobserved_reserved_cpu: unobservedCpu,
+      reserved_to_observed_cpu_ratio: observedCpu !== null && observedCpu > 0 ? Math.min(1, used.cpu / observedCpu) : null,
+    },
+    limits: resourceLimits(cpuCores, totalMemoryMb, priority, pressure.state, pressure.reasons) };
+  if (request?.heavy) snapshot.requested = resourceRequestIncrement(leases, request, accounting);
+  return snapshot;
+}
+
+export function deriveHostRates(current, previous) {
+  const result = { ...current };
+  const elapsed = (Number(current?.sampled_at_ms) - Number(previous?.sampled_at_ms)) / 1000;
+  if (!(elapsed > 0 && elapsed <= 30)) return result;
+  for (const [totalKey, rateKey] of [["pageouts_total", "pageouts_per_s"], ["swapouts_total", "swapouts_per_s"]]) {
+    const currentValue = Number(current?.[totalKey]); const priorValue = Number(previous?.[totalKey]);
+    if (Number.isFinite(currentValue) && Number.isFinite(priorValue) && currentValue >= priorValue) result[rateKey] = (currentValue - priorValue) / elapsed;
+  }
+  const totalDelta = Number(current?.cpu_time_ms_total) - Number(previous?.cpu_time_ms_total);
+  const idleDelta = Number(current?.cpu_idle_ms_total) - Number(previous?.cpu_idle_ms_total);
+  const cores = Math.max(1, Number(current?.cpu_cores) || 1);
+  if (Number.isFinite(totalDelta) && Number.isFinite(idleDelta) && totalDelta > 0 && idleDelta >= 0 && idleDelta <= totalDelta) {
+    result.cpu_busy_cores = Math.max(0, Math.min(cores, cores * (1 - idleDelta / totalDelta)));
+  }
+  return result;
+}
+
+function resourceLimits(cores, totalMemoryMb, priority, state, reasons = []) {
+  const headroom = priority === "background" ? 2 : priority === "interactive" ? 1 : 1.5;
+  const constrained = state !== "green"; const reasonSet = new Set(reasons);
+  const cpuPressure = constrained && (reasonSet.has("cpu_busy") || reasonSet.has("psi_cpu_some"));
+  const ioPressure = constrained && [...reasonSet].some((reason) => reason.startsWith("disk_") || reason.startsWith("psi_io_"));
+  const memoryPressure = constrained && [...reasonSet].some((reason) =>
+    reason.startsWith("memory_pressure") || reason.startsWith("pageout_rate") || reason.startsWith("swapout_rate") || reason.startsWith("psi_memory_"));
+  return {
+    cpu: Math.max(1, cores - headroom - (cpuPressure ? 1 : 0)),
+    io: ioPressure ? 1 : 1.25,
+    memory_mb: Math.max(1024, totalMemoryMb * (memoryPressure ? 0.55 : 0.70)),
+    cpu_overcommit: cpuPressure ? 1.15 : 1.35,
+    io_overcommit: ioPressure ? 1.05 : 1.25,
+    memory_overcommit: memoryPressure ? 1.10 : 1.25,
+  };
+}
+function diskReservationFits(host, usedBytes, requestedBytes) {
+  const free = Number(host?.disk_free_bytes); const total = Number(host?.disk_total_bytes);
+  if (!Number.isFinite(free) || !Number.isFinite(total) || free <= 0 || total <= 0) return true;
+  const hardFloor = resourceDiskHardFloorBytes(total);
+  return free - usedBytes - requestedBytes >= hardFloor;
+}
+function isDiskReclaimRequest(request) {
+  return request.family === "disk-reclaim" && request.resource_class === "io"
+    && request.unbounded === false && request.serialize_project === false
+    && Number(request.cpu) <= 0.25 && Number(request.io) <= 0.75
+    && Number(request.memory_mb) <= 256 && Number(request.disk_reserve_bytes) === 0;
+}

package/src/local/resource-admission.mjs

@@ -0,0 +1,339 @@
+import { randomBytes } from "node:crypto";
+import { homedir } from "node:os";
+import { readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { performance } from "node:perf_hooks";
+import { createExclusiveFileSync, removeOwnedJsonFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import { resourceChangeSignal, resourceRetryDelayMs, resourceSleep, signalResourceChange, waitForResourceChange } from "./resource-wait.mjs";
+import { withResourceTransactionLock } from "./resource-transaction-lock.mjs";
+import { ensureOwnerOnlyDirectorySync, readBoundedRegularFileSync } from "./secure-file.mjs";
+import { currentProcessStartTimeMs, inspectProcessInstance, processStartTimeMsAsync } from "./process-identity.mjs";
+import { freshResourceHostSnapshot, resourceHostNeedsFreshIo } from "./resource-host-cache.mjs";
+import { readResourceHostSample } from "./resource-host-sample-file.mjs";
+import { sampleResourceHostAsync } from "./resource-host-snapshot.mjs";
+import { validateResourceRequest } from "./resource-request-contract.mjs";
+import { recoverResourceDirectoryStaging, RESOURCE_STAGING_BUSY_CODE } from "./resource-staging-recovery.mjs";
+import { deriveHostRates, evaluateResourceAdmission, resourceAdmissionDecisionRetryable, resourcePressureSnapshot } from "./resource-admission-policy.mjs";
+import { fitElasticRequestToPressure } from "./resource-elastic-request.mjs";
+import { resourceCoordinatorAccounting, resourceCoordinatorEvaluator } from "./resource-coordinator-accounting.mjs";
+import { cachedResourceProcessParentSamplerAsync } from "./resource-process-ancestry-cache.mjs";
+import { sampleResourceProcessParentsAsync } from "./resource-process-ancestry.mjs";
+import { resourceProjectHash, resourceRequestForProject } from "./resource-project-key.mjs";
+import { createResourceWaiter, pruneAndReadResourceWaiters, removeResourceWaiter, resourceWaiterDrainActive, resourceWaiterQueueSnapshot, selectedResourceWaiter } from "./resource-waiters.mjs";
+const SCHEMA = 1; const PROVISIONAL_TTL_MS = 30_000; const PROCESS_OWNERSHIP_LOCK_WAIT_MS = 30_000; const LEASE_FILE = /^lease_[a-f0-9]{32}\.json$/;
+export class ResourceAdmissionError extends Error {
+  constructor(decision) {
+    super(`local heavy-resource admission deferred (${decision?.reason || "resource_busy"})`);
+    this.name = "ResourceAdmissionError";
+    this.code = "MBM_RESOURCE_BUSY";
+    this.retryable = resourceAdmissionDecisionRetryable(decision);
+    this.decision = decision;
+  }
+}
+export function defaultResourceCoordinatorRoot(env = process.env) {
+  if (env.AGENT_RESOURCE_COORDINATOR_ROOT) return resolve(String(env.AGENT_RESOURCE_COORDINATOR_ROOT));
+  if (process.platform === "win32") {
+    const base = env.LOCALAPPDATA || env.APPDATA || homedir();
+    return resolve(base, "AgentResourceCoordinator");
+  }
+  const base = env.XDG_STATE_HOME ? resolve(String(env.XDG_STATE_HOME)) : join(homedir(), ".local", "state");
+  return join(base, "agent-resource-coordinator");
+}
+export class ResourceCoordinator {
+  constructor(options = {}) {
+    this.root = resolve(options.root || defaultResourceCoordinatorRoot(options.env));
+    this.sampleHost = options.sampleHost || sampleResourceHostAsync;
+    this.evaluate = options.evaluate || evaluateResourceAdmission;
+    this.now = options.now || Date.now;
+    this.sampleProcessParents = cachedResourceProcessParentSamplerAsync(options.sampleProcessParents || sampleResourceProcessParentsAsync, this.now, options.processParentCacheMs);
+    this.sleep = options.sleep || resourceSleep;
+    this.random = options.random || Math.random;
+    this.leasesDir = join(this.root, "leases");
+    this.waitersDir = join(this.root, "waiters");
+    this.hostSampleFile = join(this.root, "host-sample.json");
+    this.markerFile = join(this.root, "protocol.json");
+    this.hostSamplesInFlight = new Map();
+    this.ready = false;
+  }
+
+  async acquire(request, options = {}) {
+    if (!request?.heavy) return ResourceLease.light(request);
+    this.ensureRoot();
+    const coordinatedRequest = resourceRequestForProject(request, options.cwd);
+    const waitMs = Math.max(0, Math.min(30 * 60_000, Number(options.waitMs) || 0));
+    const started = performance.now();
+    const waiter = createResourceWaiter(this.waitersDir, coordinatedRequest, waitMs, this.now());
+    let lastDecision = null;
+    let retryAttempt = 0;
+    try {
+      while (true) {
+        const changeSignal = resourceChangeSignal(this);
+        abortIfNeeded(options.signal);
+        options.cancelCheck?.();
+        const host = await this.freshHostSnapshot(options.cwd || process.cwd(), coordinatedRequest);
+        const processParents = readdirSync(this.leasesDir).some((name) => LEASE_FILE.test(name)) ? await this.sampleProcessParents() : {};
+        const result = await this.withLock(() => {
+          const leases = this.pruneAndReadLeases();
+          const previous = readResourceHostSample(this.hostSampleFile, { optional: true });
+          const enrichedHost = deriveHostRates(host, previous);
+          this.writeJson(this.hostSampleFile, enrichedHost);
+          const accounting = resourceCoordinatorAccounting(leases, processParents, waiter.owner.pid);
+          const pressure = resourcePressureSnapshot(enrichedHost, leases, coordinatedRequest.priority, this.now(), accounting.accounting, coordinatedRequest);
+          const effectiveRequest = fitElasticRequestToPressure(coordinatedRequest, pressure);
+          if (waiter.request.cpu !== effectiveRequest.cpu || waiter.request.memory_mb !== effectiveRequest.memory_mb || waiter.request.compiler_jobs !== effectiveRequest.compiler_jobs) {
+            waiter.request = normalizedRequest(effectiveRequest); this.writeJson(join(this.waitersDir, `wait_${waiter.waiter_id}.json`), waiter);
+          }
+          const waiters = this.pruneAndReadWaiters();
+          const evaluate = resourceCoordinatorEvaluator(this.evaluate, processParents, waiter.owner.pid);
+          const decision = evaluate(enrichedHost, leases, effectiveRequest, this.now(), waiter);
+          const selected = selectedResourceWaiter(waiters, leases, enrichedHost, evaluate, this.now());
+          if (!decision.admitted || selected?.waiter_id !== waiter.waiter_id) {
+            return { decision: decision.admitted ? { ...decision, admitted: false, reason: "fairness_wait" } : decision, lease: null };
+          }
+          const lease = this.createLease(decision.reservation ? { ...effectiveRequest, ...decision.reservation } : effectiveRequest, options.cwd);
+          removeResourceWaiter(this.waitersDir, waiter);
+          return { decision, lease };
+        }, Math.max(1, Math.min(PROCESS_OWNERSHIP_LOCK_WAIT_MS, waitMs - (performance.now() - started))));
+        lastDecision = result.decision;
+        if (result.lease) return new ResourceLease(this, result.lease, result.lease.request);
+        if (!resourceAdmissionDecisionRetryable(lastDecision)) throw new ResourceAdmissionError(lastDecision);
+        const elapsed = performance.now() - started;
+        if (elapsed >= waitMs) throw new ResourceAdmissionError(lastDecision);
+        const remaining = Math.max(1, waitMs - elapsed);
+        const delay = resourceRetryDelayMs({
+          attempt: retryAttempt, priority: coordinatedRequest.priority,
+          reason: lastDecision?.reason, remainingMs: remaining, random: this.random,
+        });
+        retryAttempt += 1;
+        await waitForResourceChange(changeSignal, delay, this.sleep, options.signal);
+      }
+    } finally {
+      if (removeResourceWaiter(this.waitersDir, waiter)) signalResourceChange(this);
+    }
+  }
+  async snapshot(options = {}) {
+    this.ensureRoot();
+    const sampleRequest = options.full === true ? { resource_class: "mixed" } : { resource_class: "adaptive" };
+    const host = await this.freshHostSnapshot(options.cwd || process.cwd(), sampleRequest);
+    const processParents = readdirSync(this.leasesDir).some((name) => LEASE_FILE.test(name)) ? await this.sampleProcessParents() : {};
+    return this.withLock(() => {
+      const leases = this.pruneAndReadLeases();
+      const waiters = this.pruneAndReadWaiters();
+      const previous = readResourceHostSample(this.hostSampleFile, { optional: true });
+      const enrichedHost = deriveHostRates(host, previous);
+      this.writeJson(this.hostSampleFile, enrichedHost);
+      const accounting = resourceCoordinatorAccounting(leases, processParents); const evaluate = resourceCoordinatorEvaluator(this.evaluate, processParents); const now = this.now();
+      return {
+        schema_version: SCHEMA,
+        healthy: true,
+        root_scope: "machine_user",
+        admission_model: "work_conserving_multi_resource",
+        hard_resource_quota: false,
+        host: publicHost(enrichedHost),
+        pressure: resourcePressureSnapshot(enrichedHost, leases, options.priority || "ordinary", now, accounting.accounting),
+        active_leases: leases.length,
+        resources: accounting.resources,
+        waiters: { ...resourceWaiterQueueSnapshot(waiters, now), drain_active: resourceWaiterDrainActive(waiters, leases, enrichedHost, evaluate, now) },
+      };
+    });
+  }
+
+  async bindLease(leaseId, token, child, options = {}) {
+    if (!Number.isInteger(child?.pid) || child.pid <= 0) throw new Error("resource lease requires a spawned child pid");
+    const observedStart = await processStartTimeMsAsync(child.pid);
+    return this.withLock(() => {
+      const file = this.leasePath(leaseId);
+      const lease = this.readJson(file, 32 * 1024, "resource lease");
+      assertLeaseToken(lease, token);
+      const processGroupIsolated = options.processGroupIsolated === true && process.platform !== "win32";
+      const processGroupId = processGroupIsolated ? child.pid : null;
+      if (lease.owner.kind === "process") {
+        if (lease.owner.pid !== child.pid
+            || lease.owner.process_group_isolated !== processGroupIsolated
+            || lease.owner.process_group_id !== processGroupId) {
+          throw new Error("resource lease is already bound with different process ownership semantics");
+        }
+        return lease;
+      }
+      const nowIso = new Date(this.now()).toISOString();
+      lease.owner = {
+        kind: "process",
+        pid: child.pid,
+        process_started_at: Number.isFinite(observedStart) ? new Date(observedStart).toISOString() : nowIso,
+        process_group_id: processGroupId,
+        process_group_isolated: processGroupIsolated,
+      };
+      lease.bound_at = nowIso;
+      this.writeJson(file, lease);
+      return lease;
+    }, PROCESS_OWNERSHIP_LOCK_WAIT_MS);
+  }
+
+  async releaseLease(leaseId, token) {
+    if (!leaseId || !token) return false;
+    this.ensureRoot();
+    return this.withLock(() => {
+      const file = this.leasePath(leaseId);
+      const lease = this.readJson(file, 32 * 1024, "resource lease", true);
+      if (!lease) return false;
+      assertLeaseToken(lease, token);
+      const owner = lease.owner; const ownerStatus = owner?.kind === "process" ? inspectLeaseOwnerProcess(lease) : null;
+      if (owner?.kind === "process" && owner.process_group_isolated === true && ownerStatus?.reason !== "pid_reused" && isProcessGroupAlive(owner.process_group_id)) return true;
+      const removed = removeOwnedJsonFileSync(file, { lease_id: leaseId, token }, { maxBytes: 32 * 1024 });
+      if (!removed) throw new Error("resource lease changed before release; state may require inspection");
+      signalResourceChange(this);
+      return true;
+    }, PROCESS_OWNERSHIP_LOCK_WAIT_MS);
+  }
+  ensureRoot() {
+    if (this.ready) return;
+    ensureOwnerOnlyDirectorySync(this.root);
+    ensureOwnerOnlyDirectorySync(this.leasesDir);
+    ensureOwnerOnlyDirectorySync(this.waitersDir);
+    const marker = this.readJson(this.markerFile, 4096, "resource coordinator protocol", true);
+    if (!marker) {
+      try { createExclusiveFileSync(this.markerFile, `${JSON.stringify({ schema_version: SCHEMA, protocol: "agent-resource-coordinator" })}\n`, { mode: 0o600 }); }
+      catch (error) { if (error?.code !== "EEXIST") throw error; }
+    }
+    const current = this.readJson(this.markerFile, 4096, "resource coordinator protocol");
+    if (current?.schema_version !== SCHEMA || current?.protocol !== "agent-resource-coordinator") throw new Error("unsupported resource coordinator protocol");
+    this.ready = true;
+  }
+  async freshHostSnapshot(cwd, request = null) {
+    const scope = resourceProjectHash(cwd);
+    const needsIo = resourceHostNeedsFreshIo(request);
+    const pending = this.hostSamplesInFlight.get(scope);
+    if (pending) {
+      const shared = await pending.promise;
+      if (!needsIo || shared?.io_sampled === true) return shared;
+    }
+    const flight = { promise: freshResourceHostSnapshot({
+      cached: readResourceHostSample(this.hostSampleFile, { optional: true }),
+      current: this.now(), sampleHost: this.sampleHost, cwd, request, scope,
+    }) };
+    this.hostSamplesInFlight.set(scope, flight);
+    try { return await flight.promise; }
+    finally { if (this.hostSamplesInFlight.get(scope) === flight) this.hostSamplesInFlight.delete(scope); }
+  }
+  async withLock(callback, timeoutMs = undefined) {
+    this.ensureRoot();
+    for (let attempt = 1; attempt <= 4; attempt += 1) {
+      try { return await withResourceTransactionLock(this.root, callback, { now: this.now, sleep: this.sleep, random: this.random, timeoutMs }); }
+      catch (error) { if (error?.code !== RESOURCE_STAGING_BUSY_CODE || attempt === 4) throw error; await this.sleep(5); }
+    }
+  }
+  pruneAndReadWaiters() {
+    let entries = readdirSync(this.waitersDir, { withFileTypes: true });
+    if (recoverResourceDirectoryStaging(this.waitersDir, entries, "wait")) entries = readdirSync(this.waitersDir, { withFileTypes: true });
+    const waiters = pruneAndReadResourceWaiters(this.waitersDir, entries, this.now()); if (waiters.length < entries.length) signalResourceChange(this); return waiters;
+  }
+  pruneAndReadLeases() {
+    const leases = []; let pruned = false;
+    let entries = readdirSync(this.leasesDir, { withFileTypes: true });
+    if (recoverResourceDirectoryStaging(this.leasesDir, entries, "lease")) entries = readdirSync(this.leasesDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isFile() || !LEASE_FILE.test(entry.name)) throw new Error("resource coordinator lease directory contains an unexpected entry");
+      const file = join(this.leasesDir, entry.name);
+      const lease = this.readJson(file, 32 * 1024, "resource lease");
+      validateLease(lease);
+      if (this.leaseIsStale(lease)) {
+        if (!removeOwnedJsonFileSync(file, { lease_id: lease.lease_id, token: lease.token }, { maxBytes: 32 * 1024 })) {
+          throw new Error("resource lease changed during stale pruning");
+        }
+        pruned = true; continue;
+      }
+      leases.push(lease);
+    }
+    if (pruned) signalResourceChange(this); return leases;
+  }
+
+  leaseIsStale(lease) {
+    const owner = lease.owner; const status = inspectLeaseOwnerProcess(lease);
+    if (owner.kind === "process" && status.reason === "pid_reused") return true;
+    if (owner.kind === "process" && owner.process_group_isolated === true && isProcessGroupAlive(owner.process_group_id)) return false;
+    if (owner.kind === "provisional" && this.now() - Date.parse(lease.acquired_at) > PROVISIONAL_TTL_MS) return true;
+    return status.reclaimable === true;
+  }
+
+  createLease(request, cwd) {
+    const id = randomBytes(16).toString("hex"); const token = randomBytes(32).toString("hex");
+    const nowIso = new Date(this.now()).toISOString();
+    const lease = {
+      schema_version: SCHEMA,
+      lease_id: id,
+      token,
+      acquired_at: nowIso,
+      bound_at: null,
+      project_hash: resourceProjectHash(cwd || process.cwd()),
+      owner: {
+        kind: "provisional",
+        pid: process.pid,
+        process_started_at: new Date(currentProcessStartTimeMs()).toISOString(),
+      },
+      request: normalizedRequest(request),
+    };
+    createExclusiveFileSync(this.leasePath(id), `${JSON.stringify(lease)}\n`, { mode: 0o600 });
+    return lease;
+  }
+
+  leasePath(id) {
+    if (!/^[a-f0-9]{32}$/.test(String(id || ""))) throw new Error("invalid resource lease id");
+    return join(this.leasesDir, `lease_${id}.json`);
+  }
+  readJson(file, maxBytes, label, optional = false) {
+    try {
+      const text = readBoundedRegularFileSync(file, maxBytes, label, { verifyPathIdentity: true, rejectMultipleLinks: true }).toString("utf8");
+      const value = JSON.parse(text);
+      return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+    } catch (error) {
+      if (optional && (error?.code === "ENOENT" || error?.cause?.code === "ENOENT")) return null;
+      throw error;
+    }
+  }
+  writeJson(file, value) { replaceFileAtomicallySync(file, `${JSON.stringify(value)}\n`, { mode: 0o600 }); }
+}
+
+export class ResourceLease {
+  constructor(coordinator, lease, request) { this.coordinator = coordinator; this.id = lease.lease_id; this.token = lease.token; this.request = request; this.released = false; }
+  static light(request) { return new ResourceLease(null, { lease_id: null, token: null }, request); }
+  get active() { return Boolean(this.coordinator && this.id && !this.released); }
+  async bindProcess(child, options = {}) { if (this.active) await this.coordinator.bindLease(this.id, this.token, child, options); return this; }
+  async release() {
+    if (!this.active) return false;
+    const released = await this.coordinator.releaseLease(this.id, this.token);
+    this.released = true;
+    return released;
+  }
+}
+
+function normalizedRequest(request) {
+  const allowed = ["family", "resource_class", "priority", "cpu", "io", "memory_mb", "disk_reserve_bytes", "heavy", "compiler_jobs", "unbounded", "serialize_project", "contention_key"];
+  return Object.fromEntries(allowed.map((key) => [key, request[key] ?? null]));
+}
+function validateLease(lease) {
+  if (lease?.schema_version !== SCHEMA || !/^[a-f0-9]{32}$/.test(String(lease.lease_id || "")) || !/^[a-f0-9]{64}$/.test(String(lease.token || ""))) throw new Error("resource coordinator lease is invalid");
+  if (!Number.isFinite(Date.parse(String(lease.acquired_at || ""))) || !validOwner(lease.owner)) throw new Error("resource coordinator lease ownership is invalid");
+  validateResourceRequest(lease.request);
+  if (lease.owner.kind === "process") {
+    if (!Number.isFinite(Date.parse(String(lease.bound_at || ""))) || typeof lease.owner.process_group_isolated !== "boolean") throw new Error("resource coordinator process lease is invalid");
+    if (lease.owner.process_group_isolated && lease.owner.process_group_id !== lease.owner.pid) throw new Error("resource coordinator process group is invalid");
+    if (!lease.owner.process_group_isolated && lease.owner.process_group_id !== null) throw new Error("resource coordinator process group is invalid");
+  } else if (lease.bound_at !== null) throw new Error("resource coordinator provisional lease is invalid");
+}
+function validOwner(owner) { return ["provisional", "process"].includes(owner?.kind) && Number.isInteger(owner?.pid) && owner.pid > 0 && Number.isFinite(Date.parse(String(owner.process_started_at || ""))); }
+function assertLeaseToken(lease, token) { validateLease(lease); if (lease.token !== token) throw new Error("resource lease ownership changed"); }
+function inspectLeaseOwnerProcess(lease) { return inspectProcessInstance({ pid: lease.owner.pid, startedAt: lease.acquired_at, processStartedAt: lease.owner.process_started_at }); }
+function isProcessGroupAlive(value) {
+  const pgid = Number(value); if (process.platform === "win32" || !Number.isInteger(pgid) || pgid <= 0) return false;
+  try { process.kill(-pgid, 0); return true; } catch (error) { return error?.code === "EPERM"; }
+}
+function publicHost(host) {
+  const {
+    pageouts_total: _pageouts, swapouts_total: _swapouts,
+    cpu_time_ms_total: _cpuTime, cpu_idle_ms_total: _cpuIdle,
+    sample_scope: _sampleScope,
+    ...value
+  } = host || {};
+  return value;
+}
+function abortIfNeeded(signal) { if (signal?.aborted) throw signal.reason instanceof Error ? signal.reason : new Error("resource admission cancelled"); }

package/src/local/resource-build-root.mjs

@@ -0,0 +1,83 @@
+import { homedir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import { createExclusiveFileSync } from "./exclusive-file.mjs";
+import { preservesCompilerJobs } from "./resource-elastic-request.mjs";
+import { makeCommandJobPlan } from "./resource-make-concurrency.mjs";
+import { ensureOwnerOnlyDirectorySync, ownerOnlyFile } from "./secure-file.mjs";
+import { resourceProjectHash } from "./resource-project-key.mjs";
+
+export function defaultAgentBuildRoot(env = process.env) {
+  if (env.AGENT_BUILD_ROOT) return resolve(String(env.AGENT_BUILD_ROOT));
+  if (process.platform === "darwin") return join(homedir(), "Library", "Caches", "AgentBuilds.noindex");
+  if (process.platform === "win32") return resolve(env.LOCALAPPDATA || env.APPDATA || homedir(), "AgentBuilds");
+  return join(env.XDG_CACHE_HOME ? resolve(String(env.XDG_CACHE_HOME)) : join(homedir(), ".cache"), "agent-builds");
+}
+
+export function prepareResourceBuildCommand(command, args, environment, request, cwd, options = {}) {
+  const env = { ...environment };
+  const argv = args.map(String);
+  if (!request?.heavy) return { command, args: argv, environment: env };
+  const base = basename(String(command || "")).toLowerCase();
+  applyCompilerConcurrency(argv, base, request);
+  if (!buildRootRelevant(request.family)) return { command, args: argv, environment: env };
+  const root = ensureBuildRoot(options.root || defaultAgentBuildRoot(options.env));
+  const project = projectBuildHash(cwd);
+  env.AGENT_BUILD_ROOT ||= root;
+
+  if (request.family === "cargo") {
+    const target = ensureProjectBuildDir(root, "cargo", project);
+    if (!env.CARGO_TARGET_DIR && !hasOption(argv, "--target-dir")) env.CARGO_TARGET_DIR = target;
+  } else if (request.family === "swift" && base === "swift") {
+    const scratch = ensureProjectBuildDir(root, "swift", project);
+    if (!hasOption(argv, "--scratch-path")) insertSwiftOption(argv, "--scratch-path", scratch);
+    if (request.compiler_jobs && !hasAnyOption(argv, ["-j", "--jobs"])) insertSwiftOption(argv, "-j", String(request.compiler_jobs));
+  } else if (request.family === "xcodebuild" && base === "xcodebuild") {
+    const derived = ensureProjectBuildDir(root, "xcode", project);
+    if (!hasOption(argv, "-derivedDataPath")) argv.unshift("-derivedDataPath", derived);
+    if (request.compiler_jobs && !hasOption(argv, "-jobs")) argv.unshift("-jobs", String(request.compiler_jobs));
+  }
+  return { command, args: argv, environment: env };
+}
+
+export function projectBuildHash(cwd) {
+  return resourceProjectHash(cwd || process.cwd());
+}
+
+function ensureBuildRoot(rootInput) {
+  const root = resolve(rootInput);
+  ensureOwnerOnlyDirectorySync(root);
+  if (process.platform === "darwin") ensureNoIndexMarker(root);
+  return root;
+}
+function ensureProjectBuildDir(root, family, project) {
+  const dir = join(root, family, project);
+  ensureOwnerOnlyDirectorySync(dir);
+  return dir;
+}
+function ensureNoIndexMarker(root) {
+  const marker = join(root, ".metadata_never_index");
+  try { createExclusiveFileSync(marker, "", { mode: 0o600 }); }
+  catch (error) { if (error?.code !== "EEXIST") throw error; }
+  ownerOnlyFile(marker);
+}
+function buildRootRelevant(family) { return ["cargo", "swift", "xcodebuild"].includes(String(family || "")); }
+function hasOption(argv, option) { return argv.some((value) => value === option || value.startsWith(`${option}=`)); }
+function hasAnyOption(argv, options) { return options.some((option) => hasOption(argv, option) || (option === "-j" && argv.some((value) => /^-j\d+$/.test(value)))); }
+function insertSwiftOption(argv, flag, value) {
+  const index = argv.length && ["build", "test", "package"].includes(argv[0]) ? 1 : 0;
+  argv.splice(index, 0, flag, value);
+}
+function applyCompilerConcurrency(argv, base, request) {
+  const jobs = request?.compiler_jobs;
+  if (!jobs || request.family !== "generic-build" || preservesCompilerJobs(request)) return;
+  if (base === "make" && !makeCommandJobPlan([base, ...argv])) argv.unshift("-j", String(jobs));
+  else if (base === "ninja" && !hasAnyOption(argv, ["-j", "--jobs"])) argv.unshift("-j", String(jobs));
+  else if (base === "cmake" && !hasCmakeParallelOption(argv)) insertBeforeSeparator(argv, "--parallel", String(jobs));
+  else if (["gradle", "gradlew"].includes(base) && !hasOption(argv, "--max-workers")) argv.unshift("--max-workers", String(jobs));
+  else if (["mvn", "mvnw"].includes(base) && !hasCompactOrLongOption(argv, "-T", "--threads")) argv.unshift("-T", String(jobs));
+  else if (base === "go" && !hasGoParallelOption(argv) && ["build", "test"].includes(argv[0])) argv.splice(1, 0, "-p", String(jobs));
+}
+function hasCompactOrLongOption(argv, short, long) { return hasOption(argv, long) || argv.some((value) => value === short || value.startsWith(`${short}=`) || value.startsWith(short) && value.length > short.length); }
+function hasCmakeParallelOption(argv) { const end = argv.indexOf("--"); return argv.slice(0, end < 0 ? argv.length : end).some((value) => value.startsWith("-j") || value.startsWith("--parallel")); }
+function hasGoParallelOption(argv) { return argv.some((value) => ["-p", "--p"].includes(value) || /^--?p=/.test(value)); }
+function insertBeforeSeparator(argv, flag, value) { const index = argv.indexOf("--"); argv.splice(index < 0 ? argv.length : index, 0, flag, value); }

package/src/local/resource-cargo-concurrency.mjs

@@ -0,0 +1,38 @@
+import { availableParallelism } from "node:os";
+
+export function cargoExplicitJobPlan(argv, environment = {}, maximum = 1024) {
+  const declared = cargoDeclaredJobPlan(argv, maximum);
+  if (declared) return declared;
+  if (!Object.prototype.hasOwnProperty.call(environment || {}, "CARGO_BUILD_JOBS")) return null;
+  return cargoJobValuePlan(environment.CARGO_BUILD_JOBS, maximum, true);
+}
+
+function cargoDeclaredJobPlan(argv, maximum) {
+  let plan = null;
+  for (let index = 1; index < (argv || []).length; index += 1) {
+    const current = String(argv[index]);
+    if (current === "--") break;
+    if (["-j", "--jobs"].includes(current)) {
+      plan = cargoJobValuePlan(argv[index + 1], maximum, false); index += 1; continue;
+    }
+    if (current.startsWith("--jobs=")) { plan = cargoJobValuePlan(current.slice("--jobs=".length), maximum, false); continue; }
+    if (current.startsWith("-j") && current.length > 2) plan = cargoJobValuePlan(current.slice(2), maximum, false);
+  }
+  return plan;
+}
+
+function cargoJobValuePlan(value, maximum, preserve) {
+  const text = String(value ?? "").trim();
+  const cores = availableParallelism();
+  if (text === "default") return numericPlan(cores, maximum, preserve);
+  if (!/^-?\d+$/.test(text)) return unboundedPlan(preserve);
+  const parsed = Number(text);
+  if (!Number.isSafeInteger(parsed) || parsed === 0) return unboundedPlan(preserve);
+  const jobs = parsed < 0 ? cores + parsed : parsed;
+  return numericPlan(jobs, maximum, preserve);
+}
+function numericPlan(jobs, maximum, preserve) {
+  return Number.isSafeInteger(jobs) && jobs >= 1 && jobs <= maximum
+    ? { jobs, elastic: false, unbounded: false, preserve } : unboundedPlan(preserve);
+}
+function unboundedPlan(preserve) { return { jobs: null, elastic: false, unbounded: true, preserve }; }