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

package/src/local/resource-transaction-lock.mjs

@@ -0,0 +1,189 @@
+import { randomBytes } from "node:crypto";
+import { lstatSync, mkdirSync, renameSync, rmSync, rmdirSync } from "node:fs";
+import { join } from "node:path";
+import { removeOwnedJsonFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
+import { filesystemIdentity, filesystemTimeMs } from "./filesystem-identity.mjs";
+import { createMonotonicDeadline } from "./monotonic-deadline.mjs";
+import { currentProcessStartTimeMs, inspectProcessInstance } from "./process-identity.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { recoverResourceTransactionOwnerStaging } from "./resource-staging-recovery.mjs";
+const LOCK_NAME = "transaction.lock";
+const OWNER_NAME = "owner.json";
+const LOCK_PURPOSE = "resource-coordinator";
+const LOCK_WAIT_MS = 5_000;
+const INCOMPLETE_OWNER_GRACE_MS = 5_000;
+const MAX_OWNER_BYTES = 8 * 1024;
+// Keep the schema-1 directory wire shape while beta.60 can still be the live daemon.
+// The directory mkdir is the cross-version transition mutex; owner.json is atomically
+// materialized immediately afterwards and incomplete claims are only reclaimable after
+// the bounded incomplete-owner grace.
+export async function withResourceTransactionLock(root, callback, options = {}) {
+  if (typeof callback !== "function") throw new TypeError("resource transaction lock requires a callback");
+  const lockPath = join(root, LOCK_NAME);
+  const now = typeof options.now === "function" ? options.now : Date.now;
+  const sleep = typeof options.sleep === "function" ? options.sleep : defaultSleep;
+  const random = typeof options.random === "function" ? options.random : Math.random;
+  const deadline = createMonotonicDeadline(positiveInteger(options.timeoutMs, LOCK_WAIT_MS));
+  const owner = directoryOwner(now());
+
+  while (true) {
+    const acquired = tryAcquireDirectoryLock(lockPath, owner);
+    if (acquired) return runWithDirectoryLock(lockPath, acquired, owner.token, callback);
+    const observed = inspectExistingLock(lockPath, now());
+    if (observed.kind === "missing") continue;
+    if (observed.reclaimable && typeof options.beforeReclaim === "function") await options.beforeReclaim(observed);
+    if (observed.reclaimable && reclaimObservedLock(lockPath, observed, options)) continue;
+    if (deadline.expired()) throw Object.assign(new Error("resource coordinator transaction state is busy; retry after the current operation finishes"), { code: "MBM_RESOURCE_TRANSACTION_BUSY" });
+    await sleep(Math.min(25 + Math.floor(random() * 50), Math.max(1, deadline.remainingMs())));
+  }
+}
+
+function tryAcquireDirectoryLock(lockPath, owner) {
+  try { mkdirSync(lockPath, { mode: 0o700 }); }
+  catch (error) { if (error?.code === "EEXIST") return null; throw error; }
+  const identity = directoryIdentity(lstatDirectory(lockPath));
+  try {
+    replaceFileAtomicallySync(join(lockPath, OWNER_NAME), `${JSON.stringify(owner)}\n`, { mode: 0o600 });
+    return identity;
+  } catch (error) {
+    let cleanupError = null;
+    try { removeDirectoryGeneration(lockPath, identity, null, "failed acquisition"); } catch (failure) { cleanupError = failure; }
+    if (cleanupError) throw new AggregateError([error, cleanupError], "resource transaction acquisition failed and cleanup was incomplete");
+    throw error;
+  }
+}
+
+async function runWithDirectoryLock(lockPath, identity, token, callback) {
+  let result;
+  let callbackError = null;
+  try { result = await callback(); } catch (error) { callbackError = error; }
+  let releaseError = null;
+  try {
+    if (!removeDirectoryGeneration(lockPath, identity, token, "release")) {
+      releaseError = new Error("resource coordinator transaction lock changed before release; state may require inspection");
+    }
+  } catch (error) {
+    releaseError = new Error("resource coordinator transaction lock release failed; state may require inspection", { cause: error });
+  }
+  if (callbackError && releaseError) throw new AggregateError([callbackError, releaseError], "resource transaction failed and lock release was incomplete");
+  if (releaseError) throw releaseError;
+  if (callbackError) throw callbackError;
+  return result;
+}
+
+function inspectExistingLock(lockPath, now) {
+  let info;
+  try { info = lstatSync(lockPath, { bigint: true }); }
+  catch (error) { if (error?.code === "ENOENT") return { kind: "missing", reclaimable: false }; throw error; }
+  if (info.isSymbolicLink()) throw new Error("resource coordinator transaction lock must not be a symbolic link");
+  if (info.isDirectory()) return inspectDirectoryLock(lockPath, info, now);
+  if (info.isFile()) return inspectPriorFileLock(lockPath);
+  throw new Error("resource coordinator transaction lock has an unsupported filesystem type");
+}
+
+function inspectDirectoryLock(lockPath, info, now) {
+  const identity = directoryIdentity(info);
+  let owner;
+  try { owner = readJson(join(lockPath, OWNER_NAME), MAX_OWNER_BYTES, "resource transaction owner"); }
+  catch (error) {
+    if (!isMissing(error)) throw error;
+    const age = now - filesystemTimeMs(info.mtimeMs, "resource transaction lock modification time");
+    return { kind: "directory", identity, owner: null, reclaimable: age >= INCOMPLETE_OWNER_GRACE_MS };
+  }
+  if (!validDirectoryOwner(owner)) throw new Error("resource coordinator transaction owner is invalid");
+  const status = inspectProcessInstance({ pid: owner.pid, startedAt: owner.started_at, processStartedAt: owner.process_started_at });
+  return { kind: "directory", identity, owner, reclaimable: status.reclaimable === true };
+}
+
+function inspectPriorFileLock(lockPath) {
+  const owner = readJson(lockPath, MAX_OWNER_BYTES, "resource transaction owner-state lock");
+  if (!validPriorFileOwner(owner)) throw new Error("resource coordinator prior owner-state lock is invalid");
+  const status = inspectProcessInstance(owner);
+  return { kind: "file", owner, reclaimable: status.reclaimable === true };
+}
+
+function reclaimObservedLock(lockPath, observed, options = {}) {
+  if (observed.kind === "file") {
+    return removeOwnedJsonFileSync(lockPath, { token: observed.owner.token, purpose: LOCK_PURPOSE }, { maxBytes: MAX_OWNER_BYTES });
+  }
+  return removeDirectoryGeneration(lockPath, observed.identity, observed.owner?.token ?? null, "stale recovery", {
+    expectedOwnerMissing: observed.owner === null,
+    beforeRestore: options.beforeRestore,
+  });
+}
+
+function removeDirectoryGeneration(lockPath, expectedIdentity, expectedToken, reason, { expectedOwnerMissing = false, beforeRestore = null } = {}) {
+  if (expectedOwnerMissing) {
+    let current; try { current = lstatDirectory(lockPath); } catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+    if (!sameDirectoryIdentity(expectedIdentity, directoryIdentity(current))) return false;
+    try { readJson(join(lockPath, OWNER_NAME), MAX_OWNER_BYTES, "resource transaction owner"); return false; }
+    catch (error) { if (!isMissing(error)) throw error; }
+    if (!recoverResourceTransactionOwnerStaging(lockPath)) return false;
+    try { rmdirSync(lockPath); return true; }
+    catch (error) { if (["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error?.code)) return false; throw error; }
+  }
+  const quarantine = `${lockPath}.stale.${process.pid}.${randomBytes(8).toString("hex")}`;
+  try { renameSync(lockPath, quarantine); }
+  catch (error) { if (error?.code === "ENOENT") return false; throw error; }
+  let verified = false;
+  try {
+    const movedInfo = lstatDirectory(quarantine);
+    if (!sameDirectoryIdentity(expectedIdentity, directoryIdentity(movedInfo))) throw new Error(`resource transaction directory changed during ${reason}`);
+    if (expectedToken !== null) {
+      const movedOwner = readJson(join(quarantine, OWNER_NAME), MAX_OWNER_BYTES, "resource transaction owner");
+      if (!validDirectoryOwner(movedOwner) || movedOwner.token !== expectedToken) throw new Error(`resource transaction owner changed during ${reason}`);
+    }
+    verified = true;
+  } finally { if (!verified) restoreQuarantine(lockPath, quarantine, beforeRestore); }
+  rmSync(quarantine, { recursive: true, force: false });
+  return true;
+}
+function restoreQuarantine(lockPath, quarantine, beforeRestore = null) {
+  if (typeof beforeRestore === "function") beforeRestore({ lockPath, quarantine });
+  try { lstatSync(lockPath); throw new Error("resource transaction lock was replaced before quarantine restore; state requires inspection"); }
+  catch (error) { if (error?.code !== "ENOENT") throw error; }
+  try { renameSync(quarantine, lockPath); }
+  catch (error) { throw new Error("resource transaction quarantine could not be restored; state requires inspection", { cause: error }); }
+}
+function directoryOwner(now) {
+  return { schema_version: 1, token: randomBytes(16).toString("hex"), pid: process.pid,
+    started_at: new Date(now).toISOString(), process_started_at: new Date(currentProcessStartTimeMs()).toISOString() };
+}
+
+function validDirectoryOwner(owner) {
+  return Number.isInteger(owner?.pid) && owner.pid > 0
+    && Number.isFinite(Date.parse(String(owner.started_at || "")))
+    && Number.isFinite(Date.parse(String(owner.process_started_at || "")))
+    && /^[a-f0-9]{32}$/.test(String(owner.token || ""));
+}
+
+function validPriorFileOwner(owner) {
+  return Number.isInteger(owner?.pid) && owner.pid > 0
+    && owner.purpose === LOCK_PURPOSE
+    && Number.isFinite(Date.parse(String(owner.startedAt || "")))
+    && Number.isFinite(Date.parse(String(owner.processStartedAt || "")))
+    && /^[a-f0-9]{32}$/.test(String(owner.token || ""));
+}
+
+function readJson(file, maxBytes, label) {
+  const text = readBoundedRegularFileSync(file, maxBytes, label, { verifyPathIdentity: true, rejectMultipleLinks: true }).toString("utf8");
+  let value;
+  try { value = JSON.parse(text); } catch { throw new Error(`${label} is not valid JSON`); }
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must contain a JSON object`);
+  return value;
+}
+
+function lstatDirectory(path) {
+  const info = lstatSync(path, { bigint: true });
+  if (info.isSymbolicLink() || !info.isDirectory()) throw new Error("resource coordinator transaction lock must be a real directory");
+  return info;
+}
+
+function directoryIdentity(info) {
+  const identity = filesystemIdentity(info, "resource transaction directory");
+  return { dev: identity.dev, ino: identity.ino };
+}
+function sameDirectoryIdentity(left, right) { return left?.dev === right?.dev && left?.ino === right?.ino; }
+function isMissing(error) { return error?.code === "ENOENT" || error?.cause?.code === "ENOENT"; }
+function positiveInteger(value, fallback) { const number = Number(value); return Number.isFinite(number) && number > 0 ? Math.floor(number) : fallback; }
+function defaultSleep(milliseconds) { return new Promise((resolvePromise) => { setTimeout(resolvePromise, milliseconds); }); }

package/src/local/resource-wait.mjs

@@ -0,0 +1,48 @@
+const changeSignals = new WeakMap();
+
+export function resourceSleep(ms, signal) {
+  return new Promise((resolvePromise, rejectPromise) => {
+    let timer;
+    const cleanup = () => signal?.removeEventListener("abort", onAbort);
+    const onAbort = () => {
+      clearTimeout(timer);
+      cleanup();
+      rejectPromise(signal?.reason instanceof Error ? signal.reason : new Error("resource admission cancelled"));
+    };
+    timer = setTimeout(() => { cleanup(); resolvePromise(); }, ms);
+    if (signal?.aborted) onAbort();
+    else signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+export function resourceChangeSignal(owner) {
+  let controller = changeSignals.get(owner);
+  if (!controller || controller.signal.aborted) { controller = new AbortController(); changeSignals.set(owner, controller); }
+  return controller.signal;
+}
+
+export function signalResourceChange(owner) {
+  const previous = changeSignals.get(owner);
+  changeSignals.set(owner, new AbortController());
+  previous?.abort(new Error("resource capacity changed"));
+}
+
+export async function waitForResourceChange(changeSignal, ms, sleep = resourceSleep, signal) {
+  const combined = signal ? AbortSignal.any([signal, changeSignal]) : changeSignal;
+  try { await sleep(ms, combined); return false; }
+  catch (error) { if (changeSignal.aborted && !signal?.aborted) return true; throw error; }
+}
+
+export function resourceRetryDelayMs({ attempt = 0, priority = "ordinary", reason = "", remainingMs = 0, random = Math.random } = {}) {
+  const base = priority === "interactive" ? 100 : priority === "background" ? 500 : 200;
+  const cap = priority === "interactive" ? 600 : priority === "background" ? 3_000 : 1_500;
+  const step = Math.max(0, Math.min(4, Math.floor(Number(attempt) || 0)));
+  let minimum = Math.min(cap, base * (2 ** step));
+  if (reason === "host_pressure_red") minimum = Math.max(minimum, Math.min(cap, priority === "interactive" ? 300 : 600));
+  else if (reason === "cpu_pressure_window") minimum = Math.max(minimum, Math.min(cap, priority === "interactive" ? 150 : 300));
+  const maximum = Math.min(cap, Math.max(minimum, Math.floor(minimum * 1.5)));
+  const unit = Math.max(0, Math.min(1, Number(random?.()) || 0));
+  const delay = minimum + Math.floor((maximum - minimum) * unit);
+  const remaining = Math.max(1, Math.floor(Number(remainingMs) || 1));
+  return Math.max(1, Math.min(delay, remaining));
+}

package/src/local/resource-waiters.mjs

@@ -0,0 +1,139 @@
+import { randomBytes } from "node:crypto";
+import { join } from "node:path";
+import { createExclusiveFileSync, removeOwnedJsonFileSync } from "./exclusive-file.mjs";
+import { currentProcessStartTimeMs, inspectProcessInstance } from "./process-identity.mjs";
+import { readBoundedRegularFileSync } from "./secure-file.mjs";
+import { validateResourceRequest } from "./resource-request-contract.mjs";
+const SCHEMA = 1;
+const WAITER_FILE = /^wait_[a-f0-9]{32}\.json$/;
+const MAX_WAITER_BYTES = 16 * 1024;
+const WAITER_GRACE_MS = 5_000;
+const AGING_MS = 120_000;
+const PROTECTION_FLOOR_MS = AGING_MS;
+const LEASE_DRAIN_REASONS = new Set(["project_resource_busy", "cpu_reservation", "io_reservation", "memory_reservation", "disk_reserve_floor"]);
+export function createResourceWaiter(waitersDir, request, waitMs, now = Date.now()) {
+  const waiterId = randomBytes(16).toString("hex");
+  const token = randomBytes(32).toString("hex");
+  const expiresAt = now + Math.max(5_000, Number(waitMs) || 0) + WAITER_GRACE_MS;
+  const waiter = {
+    schema_version: SCHEMA,
+    waiter_id: waiterId,
+    token,
+    enqueued_at: new Date(now).toISOString(),
+    expires_at: new Date(expiresAt).toISOString(),
+    owner: { pid: process.pid, process_started_at: new Date(currentProcessStartTimeMs()).toISOString() },
+    request: normalizeWaiterRequest(request),
+  };
+  createExclusiveFileSync(waiterPath(waitersDir, waiterId), `${JSON.stringify(waiter)}\n`, { mode: 0o600 });
+  return waiter;
+}
+export function removeResourceWaiter(waitersDir, waiter) {
+  if (!waiter?.waiter_id || !waiter?.token) return false;
+  return removeOwnedJsonFileSync(waiterPath(waitersDir, waiter.waiter_id), {
+    waiter_id: waiter.waiter_id, token: waiter.token,
+  }, { maxBytes: MAX_WAITER_BYTES });
+}
+
+export function pruneAndReadResourceWaiters(waitersDir, entries, now = Date.now()) {
+  const waiters = [];
+  for (const entry of entries) {
+    if (!entry.isFile() || !WAITER_FILE.test(entry.name)) throw new Error("resource coordinator waiter directory contains an unexpected entry");
+    const file = join(waitersDir, entry.name);
+    let waiter;
+    try { waiter = readWaiter(file); }
+    catch (error) { if (error?.code === "ENOENT" || error?.cause?.code === "ENOENT") continue; throw error; }
+    validateWaiter(waiter);
+    if (waiterIsStale(waiter, now)) {
+      if (!removeResourceWaiter(waitersDir, waiter)) throw new Error("resource waiter changed during stale pruning");
+      continue;
+    }
+    waiters.push(waiter);
+  }
+  return waiters;
+}
+
+export function selectedResourceWaiter(waiters, leases, host, evaluate, now = Date.now()) { return resourceWaiterSelectionState(waiters, leases, host, evaluate, now).selected; }
+export function resourceWaiterDrainActive(waiters, leases, host, evaluate, now = Date.now()) { return resourceWaiterSelectionState(waiters, leases, host, evaluate, now).drainActive; }
+function resourceWaiterSelectionState(waiters, leases, host, evaluate, now) {
+  const ranked = [...waiters].sort((left, right) => compareWaiters(left, right, now));
+  const selected = ranked.find((waiter) => evaluate(host, leases, waiter.request, now, waiter).admitted) || null;
+  const protectedWaiter = leases.length ? ranked.find((waiter) => {
+    const current = evaluate(host, leases, waiter.request, now, waiter); const empty = evaluate(host, [], waiter.request, now, waiter);
+    return resourceWaiterProtected(waiter, now) && LEASE_DRAIN_REASONS.has(current.reason) && (empty.admitted || empty.reason === "cpu_pressure_window");
+  }) : null;
+  const drainActive = Boolean(protectedWaiter && (!selected || compareWaiters(protectedWaiter, selected, now) <= 0));
+  return { selected: drainActive ? null : selected, drainActive };
+}
+export function resourceWaiterRank(waiter, now = Date.now()) {
+  const base = waiterBaseRank(waiter);
+  const enqueued = Date.parse(String(waiter?.enqueued_at || ""));
+  const ageBoost = Number.isFinite(enqueued) ? Math.floor(Math.max(0, now - enqueued) / AGING_MS) : 0;
+  return Math.max(0, base - ageBoost);
+}
+
+export function resourceWaiterProtected(waiter, now = Date.now()) {
+  const enqueued = Date.parse(String(waiter?.enqueued_at || ""));
+  if (!Number.isFinite(enqueued) || resourceWaiterRank(waiter, now) !== 0) return false;
+  const protectionAge = Math.max(PROTECTION_FLOOR_MS, waiterBaseRank(waiter) * AGING_MS);
+  return Math.max(0, now - enqueued) >= protectionAge;
+}
+
+export function resourceWaiterQueueSnapshot(waiters, now = Date.now()) {
+  const byPriority = { interactive: 0, ordinary: 0, background: 0 };
+  let oldest = null;
+  for (const waiter of waiters || []) {
+    const priority = ["interactive", "ordinary", "background"].includes(waiter?.request?.priority) ? waiter.request.priority : "ordinary";
+    byPriority[priority] += 1;
+    const enqueued = Date.parse(String(waiter?.enqueued_at || ""));
+    if (Number.isFinite(enqueued) && (oldest === null || enqueued < oldest)) oldest = enqueued;
+  }
+  return {
+    active: (waiters || []).length,
+    by_priority: byPriority,
+    protected: (waiters || []).filter((waiter) => resourceWaiterProtected(waiter, now)).length,
+    oldest_ms: oldest === null ? 0 : Math.max(0, now - oldest),
+  };
+}
+
+function waiterBaseRank(waiter) {
+  return waiter?.request?.priority === "interactive" ? 0 : waiter?.request?.priority === "ordinary" ? 1 : 2;
+}
+function compareWaiters(left, right, now) {
+  const rank = resourceWaiterRank(left, now) - resourceWaiterRank(right, now);
+  if (rank) return rank;
+  const time = Date.parse(left.enqueued_at) - Date.parse(right.enqueued_at);
+  return time || String(left.waiter_id).localeCompare(String(right.waiter_id));
+}
+function waiterIsStale(waiter, now) {
+  if (Date.parse(waiter.expires_at) < now) return true;
+  const status = inspectProcessInstance({
+    pid: waiter.owner.pid,
+    startedAt: waiter.enqueued_at,
+    processStartedAt: waiter.owner.process_started_at,
+  });
+  return status.reclaimable === true;
+}
+function validateWaiter(waiter) {
+  if (waiter?.schema_version !== SCHEMA || !/^[a-f0-9]{32}$/.test(String(waiter.waiter_id || ""))
+      || !/^[a-f0-9]{64}$/.test(String(waiter.token || ""))) throw new Error("resource coordinator waiter is invalid");
+  if (!Number.isFinite(Date.parse(String(waiter.enqueued_at || ""))) || !Number.isFinite(Date.parse(String(waiter.expires_at || "")))
+      || !Number.isInteger(waiter.owner?.pid) || waiter.owner.pid <= 0
+      || !Number.isFinite(Date.parse(String(waiter.owner?.process_started_at || "")))) throw new Error("resource coordinator waiter ownership is invalid");
+  validateResourceRequest(waiter.request);
+}
+function readWaiter(file) {
+  const text = readBoundedRegularFileSync(file, MAX_WAITER_BYTES, "resource waiter", {
+    verifyPathIdentity: true, rejectMultipleLinks: true,
+  }).toString("utf8");
+  const value = JSON.parse(text);
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("resource coordinator waiter is invalid");
+  return value;
+}
+function waiterPath(waitersDir, id) {
+  if (!/^[a-f0-9]{32}$/.test(String(id || ""))) throw new Error("invalid resource waiter id");
+  return join(waitersDir, `wait_${id}.json`);
+}
+function normalizeWaiterRequest(request = {}) {
+  const keys = ["family", "resource_class", "priority", "cpu", "io", "memory_mb", "disk_reserve_bytes", "heavy", "compiler_jobs", "unbounded", "serialize_project", "contention_key"];
+  return Object.fromEntries(keys.map((key) => [key, request[key] ?? null]));
+}

package/src/local/resource-xcode-command.mjs

@@ -0,0 +1,7 @@
+const XCODE_LIGHT_FLAGS = new Set([
+  "-usage", "-help", "-license", "-checkFirstLaunchStatus", "-showsdks", "-version", "-list",
+]);
+
+export function xcodeIsLightCommand(args) {
+  return args.some((value) => XCODE_LIGHT_FLAGS.has(String(value)));
+}

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

@@ -0,0 +1,34 @@
+export function xcodeBuildJobPlan(argv, maximum = 1024) {
+  let plan = null; let seen = 0;
+  for (let index = 1; index < (argv || []).length; index += 1) {
+    const value = String(argv[index] || "");
+    if (value === "-jobs") {
+      seen += 1; if (seen > 1 || index + 1 >= argv.length) return invalidPlan();
+      plan = xcodeJobValuePlan(argv[index + 1], maximum); index += 1;
+    } else if (value.startsWith("-jobs=")) {
+      return unboundedPlan();
+    } else if (value.startsWith("-jobs")) return unboundedPlan();
+  }
+  return plan;
+}
+export function xcodeHasIndependentTestFanout(argv) {
+  return (argv || []).slice(1).some((value) => ["test", "test-without-building"].includes(String(value)));
+}
+export function xcodeResourcePlan(base, argv, defaultJobs = 3, maximum = 1024) {
+  if (base !== "xcodebuild") return { resourceClass: "unbounded", cpu: 6, compilerJobs: null, elastic: false, unbounded: true };
+  const build = xcodeBuildJobPlan(argv, maximum); if (build?.invalid) return build;
+  const plan = build || { jobs: defaultJobs, elastic: true, unbounded: false }; const unbounded = plan.unbounded || xcodeHasIndependentTestFanout(argv);
+  return { resourceClass: unbounded ? "unbounded" : "mixed", cpu: unbounded ? 6 : plan.jobs, compilerJobs: plan.unbounded ? null : plan.jobs, elastic: !unbounded && plan.elastic, unbounded };
+}
+function xcodeJobValuePlan(value, maximum) {
+  const text = String(value ?? "");
+  if (/^\+?\d+$/.test(text)) {
+    const parsed = Number(text); if (!Number.isSafeInteger(parsed)) return unboundedPlan();
+    if (parsed < 1) return invalidPlan();
+    return parsed <= maximum ? { jobs: parsed, elastic: false, unbounded: false } : unboundedPlan();
+  }
+  if (/^-\d+$/.test(text)) return invalidPlan();
+  return unboundedPlan();
+}
+function invalidPlan() { return { jobs: null, elastic: false, unbounded: false, invalid: true }; }
+function unboundedPlan() { return { jobs: null, elastic: false, unbounded: true }; }

package/src/local/resource-xcode-non-build.mjs

@@ -0,0 +1,19 @@
+const GIB = 1024 ** 3;
+const PACKAGE = new Set(["-resolvePackageDependencies"]);
+const ARTIFACT = new Set(["-exportArchive", "-exportNotarizedApp", "-exportLocalizations", "-importLocalizations", "-create-xcframework"]);
+const MAINTENANCE = new Set(["-runFirstLaunch", "-downloadAllPlatforms", "-prepareDeviceSupport", "-downloadPlatform", "-importPlatform", "-downloadComponent", "-importComponent"]);
+const DELETE = new Set(["-deleteComponent"]);
+const QUERY = new Set(["-showComponent", "-showdestinations", "-showTestPlans", "-showBuildSettings", "-showBuildSettingsForIndex", "-find-executable", "-find-library"]);
+
+export function xcodeNonBuildResourcePlan(args) {
+  const flags = new Set(args.map(String));
+  if ([...MAINTENANCE].some((flag) => flags.has(flag))) return plan("xcode-maintenance", "unbounded", 6, 0.95, 2048, 8 * GIB, true, false);
+  if ([...ARTIFACT].some((flag) => flags.has(flag))) return plan("xcode-artifact", "io", 1, 0.9, 1536, 8 * GIB, false, true);
+  if ([...PACKAGE].some((flag) => flags.has(flag))) return plan("xcode-package-resolution", "mixed", 2, 0.65, 1536, 4 * GIB, false, true);
+  if ([...DELETE].some((flag) => flags.has(flag))) return plan("xcode-maintenance", "io", 1, 0.9, 1024, 0, false, false);
+  if ([...QUERY].some((flag) => flags.has(flag))) return plan("xcode-query", "adaptive", 0.75, 0.2, 768, 0, false, false);
+  return null;
+}
+function plan(family, resourceClass, cpu, io, memoryMb, diskBytes, unbounded, serializeProject) {
+  return { family, resourceClass, cpu, io, memoryMb, diskBytes, unbounded, serializeProject };
+}