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

package/src/local/resource-process-ancestry-cache.mjs

@@ -0,0 +1,43 @@
+const DEFAULT_CACHE_MS = 1_000;
+
+export function cachedResourceProcessParentSampler(sample, now = Date.now, cacheMs = DEFAULT_CACHE_MS) {
+  const ttl = Math.max(0, Number(cacheMs) || 0);
+  let sampledAt = null;
+  let cached = null;
+  return () => {
+    const current = Number(now());
+    if (cacheFresh(sampledAt, current, ttl)) return cached;
+    cached = normalizeSnapshot(sample());
+    sampledAt = finishedAt(now, current);
+    return cached;
+  };
+}
+
+export function cachedResourceProcessParentSamplerAsync(sample, now = Date.now, cacheMs = DEFAULT_CACHE_MS) {
+  const ttl = Math.max(0, Number(cacheMs) || 0);
+  let sampledAt = null;
+  let cached = null;
+  let inFlight = null;
+  return async () => {
+    const current = Number(now());
+    if (cacheFresh(sampledAt, current, ttl)) return cached;
+    if (inFlight) return inFlight;
+    inFlight = Promise.resolve().then(() => sample()).then((value) => {
+      cached = normalizeSnapshot(value);
+      sampledAt = finishedAt(now, current);
+      return cached;
+    }).finally(() => { inFlight = null; });
+    return inFlight;
+  };
+}
+
+function normalizeSnapshot(value) {
+  return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function cacheFresh(sampledAt, current, ttl) {
+  return sampledAt !== null && Number.isFinite(current) && current >= sampledAt && current - sampledAt <= ttl;
+}
+function finishedAt(now, fallback) {
+  const finished = Number(now());
+  return Number.isFinite(finished) ? finished : Number.isFinite(fallback) ? fallback : null;
+}

package/src/local/resource-process-ancestry.mjs

@@ -0,0 +1,32 @@
+import { runResourceProbeAsync, runResourceProbeSync } from "./resource-probe-command.mjs";
+
+const COMMAND_OPTIONS = { timeoutMs: 3_000, maxOutputBytes: 1024 * 1024 };
+
+export function sampleResourceProcessParents(options = {}) {
+  const run = options.run || ((command, args) => runResourceProbeSync(command, args, COMMAND_OPTIONS));
+  const result = processParentCommand(run);
+  return result?.ok ? parseResourceProcessParents(result.stdout) : null;
+}
+
+export async function sampleResourceProcessParentsAsync(options = {}) {
+  const run = options.run || ((command, args) => runResourceProbeAsync(command, args, COMMAND_OPTIONS));
+  const result = await processParentCommand(run);
+  return result?.ok ? parseResourceProcessParents(result.stdout) : null;
+}
+
+export function parseResourceProcessParents(value) {
+  const parents = {};
+  for (const line of String(value || "").split(/\r?\n/)) {
+    const match = /^\s*([1-9][0-9]*)\s+([0-9]+)\s*$/.exec(line);
+    if (!match) continue;
+    const pid = Number(match[1]); const parent = Number(match[2]);
+    if (Number.isInteger(pid) && pid > 0 && Number.isInteger(parent) && parent >= 0) parents[String(pid)] = parent;
+  }
+  return Object.keys(parents).length ? parents : null;
+}
+
+function processParentCommand(run) {
+  return process.platform === "win32"
+    ? run("powershell.exe", ["-NoProfile", "-NonInteractive", "-Command", "Get-CimInstance Win32_Process | ForEach-Object { \"$($_.ProcessId) $($_.ParentProcessId)\" }"])
+    : run("ps", ["-axo", "pid=,ppid="]);
+}

package/src/local/resource-process-priority.mjs

@@ -0,0 +1,15 @@
+import { existsSync } from "node:fs";
+
+const POSIX_NICE = "/usr/bin/nice";
+const BACKGROUND_NICE_INCREMENT = 5;
+const UNBOUNDED_NICE_INCREMENT = 2;
+
+export function applyResourceProcessPriority(command, args, request, options = {}) {
+  const values = args.map(String);
+  if (process.platform === "win32" || request?.heavy !== true) return { command, args: values };
+  const increment = request?.priority === "background" ? BACKGROUND_NICE_INCREMENT : request?.unbounded === true ? UNBOUNDED_NICE_INCREMENT : 0;
+  if (!increment) return { command, args: values };
+  const nice = String(options.niceExecutable || POSIX_NICE);
+  if (!existsSync(nice)) return { command, args: values };
+  return { command: nice, args: ["-n", String(increment), String(command), ...values] };
+}

package/src/local/resource-project-key.mjs

@@ -0,0 +1,53 @@
+import { createHash } from "node:crypto";
+import { realpathSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+export function resourceRequestForProject(request, cwd) {
+  const result = { ...request };
+  if (result.serialize_project !== true) return result;
+  const project = normalizeResourceProjectIdentity(canonicalResourceProjectPath(cwd));
+  return { ...result, contention_key: resourceProjectContentionKey(result.family, project) };
+}
+
+export function resourceProjectContentionKey(family, projectIdentity) {
+  const material = `agent-resource-contention-v1\0${family || "unknown"}\0${String(projectIdentity || "")}`;
+  return createHash("sha256").update(material).digest("hex").slice(0, 32);
+}
+
+export function resourceProjectIdentityHash(projectIdentity) {
+  return createHash("sha256").update(String(projectIdentity || "")).digest("hex").slice(0, 24);
+}
+
+export function resourceProjectHash(cwd) {
+  const identity = normalizeResourceProjectIdentity(canonicalResourceProjectPath(cwd));
+  return resourceProjectIdentityHash(identity);
+}
+
+export function canonicalResourceProjectPath(cwd) {
+  const target = resolve(cwd || process.cwd());
+  const missing = [];
+  let current = target;
+  while (true) {
+    try {
+      const canonical = realpathSync.native ? realpathSync.native(current) : realpathSync(current);
+      return missing.reduceRight((value, name) => resolve(value, name), canonical);
+    } catch (error) {
+      if (error?.code !== "ENOENT" && error?.code !== "ENOTDIR") throw error;
+      const parent = dirname(current);
+      if (parent === current) return target;
+      missing.push(basename(current));
+      current = parent;
+    }
+  }
+}
+
+export function normalizeResourceProjectIdentity(value, platform = process.platform) {
+  let text = String(value || "");
+  if (platform !== "win32") return text;
+  text = text.replaceAll("/", "\\");
+  const folded = text.toLowerCase();
+  const extendedUnc = "\\\\?\\unc\\";
+  const extended = "\\\\?\\";
+  if (folded.startsWith(extendedUnc)) text = `\\\\${text.slice(extendedUnc.length)}`;
+  else if (folded.startsWith(extended)) text = text.slice(extended.length);
+  return text.toLowerCase();
+}

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

@@ -0,0 +1,33 @@
+export function pytestWorkerPlan(argv, text, maximum = 1024) {
+  const requested = optionValue(argv, text, ["-n", "--numprocesses"]);
+  if (requested === null) return { jobs: 1, elastic: false, unbounded: false };
+  if (requested === "0") return { jobs: 1, elastic: false, unbounded: false };
+  if (/^\d+$/.test(requested)) return numericPlan(requested, maximum);
+  if (!["auto", "logical"].includes(requested.toLowerCase())) return unboundedPlan();
+  const cap = optionValue(argv, text, ["--maxprocesses"]);
+  return cap !== null && /^\d+$/.test(cap) ? numericPlan(cap, maximum) : unboundedPlan();
+}
+
+function optionValue(argv, text, flags) {
+  for (let index = 1; index < argv.length; index += 1) {
+    const value = String(argv[index] || "");
+    for (const flag of flags) {
+      if (value === flag) return String(argv[index + 1] || "").trim();
+      if (value.startsWith(`${flag}=`)) return value.slice(flag.length + 1).trim();
+      if (flag === "-n" && value.startsWith("-n") && value.length > 2) return value.slice(2).trim();
+    }
+  }
+  if (flags.includes("-n")) {
+    const compact = /(?:^|\s)-n([^\s]+)/i.exec(text);
+    if (compact) return compact[1];
+  }
+  const names = flags.map((flag) => flag.replace(/^-+/, "")).join("|");
+  const match = new RegExp(`(?:^|\\s)--?(?:${names})[=\\s]+([^\\s]+)`, "i").exec(text);
+  return match ? match[1] : null;
+}
+function numericPlan(value, maximum) {
+  const parsed = Number(value);
+  return Number.isSafeInteger(parsed) && parsed >= 1 && parsed <= maximum
+    ? { jobs: parsed, elastic: false, unbounded: false } : unboundedPlan();
+}
+function unboundedPlan() { return { jobs: null, elastic: false, unbounded: true }; }

package/src/local/resource-release-control-classification.mjs

@@ -0,0 +1,14 @@
+import path from "node:path";
+
+const NODE_TARGET_NAMES = new Set(["node", "node.exe"]);
+const CANARY_ENTRY_NAME = "release-oauth-canary.mjs";
+const CANARY_FLAG = "--allow-live-oauth-canary";
+
+export function releaseControlCommandIsLight(base, args = []) {
+  const head = String(base || "").toLowerCase();
+  if (!NODE_TARGET_NAMES.has(head)) return false;
+  const values = args.map((value) => String(value));
+  if (values.length !== 2 || values[1] !== CANARY_FLAG) return false;
+  const entry = values[0];
+  return path.isAbsolute(entry) && path.basename(entry).toLowerCase() === CANARY_ENTRY_NAME;
+}

package/src/local/resource-release-control-executable.mjs

@@ -0,0 +1,70 @@
+import { constants as fsConstants } from "node:fs";
+import { access, realpath, stat } from "node:fs/promises";
+import path from "node:path";
+
+const RELEASE_CONTROL_UNSAFE_ENVIRONMENT_KEYS = new Set([
+  "NODE_OPTIONS", "NODE_PATH", "NODE_V8_COVERAGE", "NODE_COMPILE_CACHE", "NODE_ICU_DATA",
+  "NODE_DEBUG", "NODE_DEBUG_NATIVE", "NODE_REDIRECT_WARNINGS", "NODE_EXTRA_CA_CERTS", "NODE_PRESERVE_SYMLINKS",
+  "NODE_TLS_REJECT_UNAUTHORIZED", "SSL_CERT_FILE", "SSL_CERT_DIR", "SSLKEYLOGFILE", "OPENSSL_CONF",
+  "UV_THREADPOOL_SIZE", "LD_PRELOAD", "LD_AUDIT", "LD_LIBRARY_PATH",
+  "DYLD_INSERT_LIBRARIES", "DYLD_LIBRARY_PATH", "DYLD_FRAMEWORK_PATH",
+  "DYLD_FALLBACK_LIBRARY_PATH", "DYLD_FALLBACK_FRAMEWORK_PATH",
+]);
+
+export function releaseControlEnvironmentIsTrusted(environment = {}) {
+  if (!environment || typeof environment !== "object" || Array.isArray(environment)) return false;
+  return !Object.keys(environment).some((key) => RELEASE_CONTROL_UNSAFE_ENVIRONMENT_KEYS.has(String(key).toUpperCase()));
+}
+
+export async function releaseControlExecutableIsTrusted(command, environment = {}, options = {}) {
+  if (!releaseControlEnvironmentIsTrusted(environment)) return false;
+  const platform = String(options.platform || process.platform);
+  const pathApi = platform === "win32" ? path.win32 : path.posix;
+  const cwd = pathApi.resolve(String(options.cwd || "."));
+  const lookupOptions = { ...options, cwd, platform, pathApi };
+  const invoked = await resolveInvokedExecutable(command, environment, lookupOptions);
+  if (!invoked) return false;
+  const runtime = await inspectExecutable(options.runtimeExecutable || process.execPath, lookupOptions);
+  if (!runtime) return false;
+  return samePath(invoked.path, runtime.path, platform);
+}
+
+async function resolveInvokedExecutable(command, environment, options) {
+  const raw = String(command || "");
+  if (!raw) return null;
+  const { cwd, platform, pathApi } = options;
+  if (pathApi.isAbsolute(raw) || raw.includes("/") || raw.includes("\\")) {
+    return inspectExecutable(pathApi.resolve(cwd, raw), options);
+  }
+  const search = String(environment?.PATH || environment?.Path || "");
+  if (!search) return null;
+  const roots = search.split(pathApi.delimiter);
+  if (platform === "win32") roots.unshift(cwd);
+  const names = platform === "win32" ? windowsNames(raw, environment?.PATHEXT, pathApi) : [raw];
+  for (const root of roots) {
+    const directory = root ? (pathApi.isAbsolute(root) ? pathApi.resolve(root) : pathApi.resolve(cwd, root)) : cwd;
+    for (const name of names) {
+      const result = await inspectExecutable(pathApi.join(directory, name), options);
+      if (result) return result;
+    }
+  }
+  return null;
+}
+
+async function inspectExecutable(candidate, options) {
+  try {
+    if (options.platform !== "win32") await (options.access || access)(candidate, fsConstants.X_OK);
+    const canonical = await (options.realpath || realpath)(candidate);
+    const info = await (options.stat || stat)(canonical);
+    return info.isFile() ? { path: canonical } : null;
+  } catch { return null; }
+}
+
+function windowsNames(command, value, pathApi) {
+  const extensions = String(value || ".COM;.EXE;.BAT;.CMD").split(";").filter(Boolean);
+  return pathApi.extname(command) ? [command] : [command, ...extensions.map((extension) => `${command}${extension.toLowerCase()}`)];
+}
+
+function samePath(left, right, platform) {
+  return platform === "win32" ? left.toLowerCase() === right.toLowerCase() : left === right;
+}

package/src/local/resource-release-control-workspace.mjs

@@ -0,0 +1,41 @@
+import { realpath } from "node:fs/promises";
+import { basename, join, resolve } from "node:path";
+import { packageName, packageRoot, packageVersion } from "./package-identity.mjs";
+import { readOptionalRegularUtf8 } from "./project-metadata.mjs";
+import { releaseControlCommandIsLight } from "./resource-release-control-classification.mjs";
+import { releaseControlExecutableIsTrusted } from "./resource-release-control-executable.mjs";
+
+const PACKAGE_BYTES = 1024 * 1024, ENTRY_BYTES = 256 * 1024;
+const CANARY_ENTRY = join("scripts", "release-oauth-canary.mjs");
+
+export async function releaseControlWorkspaceForCommand(command, args = [], cwd = "", environment = {}) {
+  const base = basename(String(command || "")).toLowerCase();
+  const values = args.map((value) => String(value));
+  if (!releaseControlCommandIsLight(base, values)) return false;
+  if (!await releaseControlExecutableIsTrusted(command, environment, { cwd })) return false;
+  if (!await releaseControlRuntimeEntrypointMatches(values[0])) return false;
+  return releaseControlWorkspaceMatches(cwd);
+}
+
+export async function releaseControlWorkspaceMatches(cwd) {
+  if (typeof cwd !== "string" || !cwd.trim()) return false;
+  try {
+    const root = resolve(cwd);
+    const packageText = await readOptionalRegularUtf8(join(root, "package.json"), PACKAGE_BYTES);
+    if (!packageText) return false;
+    const manifest = JSON.parse(packageText);
+    if (manifest?.name !== packageName || manifest?.version !== packageVersion) return false;
+    const [target, runtime] = await Promise.all([
+      readOptionalRegularUtf8(join(root, CANARY_ENTRY), ENTRY_BYTES),
+      readOptionalRegularUtf8(join(packageRoot, CANARY_ENTRY), ENTRY_BYTES),
+    ]);
+    return target !== null && target === runtime;
+  } catch { return false; }
+}
+
+async function releaseControlRuntimeEntrypointMatches(entry) {
+  try {
+    const [target, runtime] = await Promise.all([realpath(String(entry || "")), realpath(join(packageRoot, CANARY_ENTRY))]);
+    return process.platform === "win32" ? target.toLowerCase() === runtime.toLowerCase() : target === runtime;
+  } catch { return false; }
+}

package/src/local/resource-request-contract.mjs

@@ -0,0 +1,30 @@
+const FAMILY = /^[a-z][a-z0-9-]{0,47}$/;
+const CONTENTION_KEY = /^[a-f0-9]{32}$/;
+const RESOURCE_CLASSES = new Set(["adaptive", "cpu", "io", "mixed", "unbounded"]);
+const PRIORITIES = new Set(["interactive", "ordinary", "background"]);
+
+export function validateResourceRequest(request) {
+  if (!request || typeof request !== "object" || Array.isArray(request)) throw new Error("resource request is invalid");
+  if (!FAMILY.test(String(request.family || "")) || !RESOURCE_CLASSES.has(request.resource_class)
+      || !PRIORITIES.has(request.priority) || request.heavy !== true
+      || typeof request.unbounded !== "boolean" || typeof request.serialize_project !== "boolean") {
+    throw new Error("resource request contract is invalid");
+  }
+  finiteRange(request.cpu, 0, 1024, "cpu");
+  finiteRange(request.io, 0, 1024, "io");
+  finiteRange(request.memory_mb, 0, 16 * 1024 * 1024, "memory");
+  finiteRange(request.disk_reserve_bytes, 0, 1024 ** 5, "disk reservation");
+  if (request.compiler_jobs !== null && (!Number.isInteger(request.compiler_jobs) || request.compiler_jobs < 1 || request.compiler_jobs > 1024)) {
+    throw new Error("resource request compiler jobs are invalid");
+  }
+  if (request.contention_key !== null && !CONTENTION_KEY.test(String(request.contention_key || ""))) {
+    throw new Error("resource request contention key is invalid");
+  }
+  return request;
+}
+
+function finiteRange(value, minimum, maximum, label) {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < minimum || value > maximum) {
+    throw new Error(`resource request ${label} is invalid`);
+  }
+}

package/src/local/resource-script-classification.mjs

@@ -0,0 +1,44 @@
+import { basename } from "node:path";
+const HEAVY_SCRIPT_MARKER = /(?:^|[._-])(?:check|checks|build|test|tests|testing|verify|verification|gate|release|archive|fuzz|coverage|benchmark|bench|smoke)(?:$|[._-])/i;
+const HEAVY_PACKAGE_SEGMENT = /(?:^|[:._-])(?:check|build|test|tests|verify|gate|release|archive|fuzz|coverage|benchmark|bench|smoke)(?:$|[:._-])/i;
+const SCRIPT_EXTENSION = /\.(?:sh|bash|zsh|js|mjs|cjs|py|rb|pl)$/i;
+const PACKAGE_MANAGERS = new Set(["npm", "pnpm", "yarn", "bun"]);
+export function heavyScriptName(value) {
+  const raw = String(value || "");
+  const name = basename(raw).toLowerCase();
+  const scriptLike = raw.includes("/") || raw.includes("\\") || SCRIPT_EXTENSION.test(name);
+  return scriptLike && HEAVY_SCRIPT_MARKER.test(name);
+}
+
+export function directInterpreterHeavyScript(base, args = []) {
+  const node = base === "node" || base === "node.exe";
+  const python = /^python(?:3(?:\.\d+)?)?(?:\.exe)?$/.test(base);
+  if (!node && !python) return false;
+  const values = args.map(String);
+  if (python && values.some((value) => ["-c", "-m"].includes(value))) return false;
+  if (node && values.some((value) => ["-e", "--eval", "-p", "--print"].includes(value))) return false;
+  const operand = values.find((value) => !value.startsWith("-")) || "";
+  return Boolean(operand && heavyScriptName(operand));
+}
+export function verificationPlanCommand(base, args = []) {
+  const values = args.map(String);
+  if ((base === "node" || base === "node.exe") && basename(values.find((value) => !value.startsWith("-")) || "").toLowerCase() === "run-checks.mjs") return true;
+  if (!PACKAGE_MANAGERS.has(base)) return false;
+  const first = String(values[0] || "").toLowerCase();
+  const script = ["run", "run-script"].includes(first) ? String(values[1] || "").toLowerCase() : first;
+  return ["check", "check:fast", "check:full", "check:platform"].includes(script);
+}
+
+export function packageManagerTokensHeavy(tokens = []) {
+  const head = String(tokens[0] || "").toLowerCase();
+  if (!PACKAGE_MANAGERS.has(head)) return false;
+  const args = tokens.slice(1).map((value) => String(value));
+  const first = String(args[0] || "").toLowerCase();
+  if (["install", "ci", "build", "test"].includes(first)) return true;
+  if (["run", "run-script"].includes(first)) return heavyPackageScriptName(args[1]);
+  return ["pnpm", "yarn", "bun"].includes(head) && heavyPackageScriptName(first);
+}
+
+export function heavyPackageScriptName(value) {
+  return HEAVY_PACKAGE_SEGMENT.test(String(value || "").toLowerCase());
+}

package/src/local/resource-shell-analysis.mjs

@@ -0,0 +1,58 @@
+import { basename } from "node:path";
+import { heavyScriptName } from "./resource-script-classification.mjs";
+
+export function shellPayload(base, args) {
+  if (!["zsh", "bash", "sh", "powershell.exe", "pwsh", "cmd.exe"].includes(base)) return "";
+  const index = args.findIndex((entry) => ["-c", "-command", "/c"].includes(entry.toLowerCase()));
+  return index >= 0 ? String(args[index + 1] || "") : args.join(" ");
+}
+
+export function shellSegments(text) {
+  return String(text || "").split(/&&|\|\||[;|()\n]/).map((value) => value.trim()).filter(Boolean);
+}
+
+export function commandTokens(segment) {
+  const tokens = String(segment).trim().split(/\s+/).filter(Boolean); let index = 0;
+  while (index < tokens.length) {
+    const token = tokens[index];
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(token) || ["env", "command", "exec", "time"].includes(token)) { index += 1; continue; }
+    if (token === "nice") { index += 1; if (tokens[index] === "-n") index += 2; else if (/^-?\d+$/.test(tokens[index] || "")) index += 1; continue; }
+    break;
+  }
+  return tokens.slice(index).map((value, tokenIndex) => tokenIndex ? value : basename(value).toLowerCase());
+}
+
+export function shellCommandHeads(text) {
+  return shellSegments(text).map((segment) => commandTokens(segment)[0]).filter(Boolean);
+}
+
+export function commandHeadIs(text, base, command) {
+  return base === command || shellCommandHeads(text).includes(command);
+}
+
+export function commandHeadIn(text, base, commands) {
+  return commands.includes(base) || shellCommandHeads(text).some((value) => commands.includes(value));
+}
+
+export function pythonModuleHeadIs(text, base, module) {
+  if (/^python(?:3(?:\.\d+)?)?$/.test(base)) return String(text).includes(`-m ${module}`);
+  return shellSegments(text).some((segment) => pythonModuleTokens(commandTokens(segment), module));
+}
+
+export function pythonModuleTokens(tokens, module) {
+  return /^python(?:3(?:\.\d+)?)?$/.test(tokens[0] || "") && tokens[1] === "-m" && tokens[2] === module;
+}
+
+export function heavyShellScript(args, text) {
+  const commandString = args.some((value) => String(value).toLowerCase() === "-c");
+  const direct = commandString ? null : args.find((value) => !String(value).startsWith("-"));
+  if (direct && heavyScriptName(direct)) return true;
+  return shellSegments(text).some((segment) => {
+    const tokens = commandTokens(segment);
+    if (!tokens.length) return false;
+    if (heavyScriptName(tokens[0])) return true;
+    if (!["sh", "bash", "zsh"].includes(tokens[0])) return false;
+    const script = tokens.slice(1).find((token) => !String(token).startsWith("-"));
+    return Boolean(script && heavyScriptName(script));
+  });
+}

package/src/local/resource-staging-recovery.mjs

@@ -0,0 +1,97 @@
+import { lstatSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { filesystemIdentity, sameFilesystemIdentity } from "./filesystem-identity.mjs";
+import { inspectProcessInstance } from "./process-identity.mjs";
+
+const STAGING = /^\.(?<target>(?<kind>lease|wait)_[a-f0-9]{32}\.json)\.(?<pid>[1-9][0-9]*)\.(?<nonce>[a-f0-9]{16})\.tmp$/;
+const OWNER_STAGING = /^\.owner\.json\.(?<pid>[1-9][0-9]*)\.(?<nonce>[a-f0-9]{16})\.tmp$/;
+const FINAL = Object.freeze({ lease: /^lease_[a-f0-9]{32}\.json$/, wait: /^wait_[a-f0-9]{32}\.json$/ });
+export const RESOURCE_STAGING_BUSY_CODE = "MBM_RESOURCE_STAGING_BUSY";
+
+export function recoverResourceTransactionOwnerStaging(dir) {
+  const entries = readdirSync(dir, { withFileTypes: true });
+  if (!entries.length) return true;
+  if (entries.some((entry) => entry.name === "owner.json")) return false;
+  if (entries.length !== 1) throw new Error("resource transaction lock contains unexpected owner-publication state");
+  const entry = entries[0];
+  const match = entry.isFile() ? OWNER_STAGING.exec(entry.name) : null;
+  if (!match) throw new Error("resource transaction lock contains unexpected owner-publication state");
+  const stagingPath = join(dir, entry.name);
+  const staging = inspect(stagingPath, "resource transaction owner staging file");
+  if (stagingPublisherMayBeCurrent(Number(match.groups.pid), staging)) return false;
+  if (staging.nlink !== 1n) throw new Error("resource transaction owner staging file has unexpected links");
+  const current = inspect(stagingPath, "resource transaction owner staging file");
+  if (current.nlink !== 1n || !sameFilesystemIdentity(staging.identity, current.identity)) {
+    throw new Error("resource transaction owner staging file changed during recovery");
+  }
+  unlinkSync(stagingPath);
+  return true;
+}
+
+export function recoverResourceDirectoryStaging(dir, entries, kind) {
+  const expected = FINAL[kind];
+  if (!expected) throw new Error("resource staging kind is invalid");
+  let recovered = false;
+  for (const entry of entries) {
+    if (entry.isFile() && expected.test(entry.name)) continue;
+    const match = entry.isFile() ? STAGING.exec(entry.name) : null;
+    if (!match || match.groups?.kind !== kind) throw new Error(`resource coordinator ${kind} directory contains an unexpected entry`);
+    recoverStagingAlias(dir, entry.name, match.groups.target, Number(match.groups.pid));
+    recovered = true;
+  }
+  return recovered;
+}
+
+function recoverStagingAlias(dir, stagingName, targetName, publisherPid) {
+  const stagingPath = join(dir, stagingName);
+  const targetPath = join(dir, targetName);
+  const staging = inspect(stagingPath, "resource coordinator staging file");
+  const target = inspectOptional(targetPath, "resource coordinator published file");
+  if (target) {
+    const sameObject = sameFilesystemIdentity(staging.identity, target.identity);
+    if (sameObject) {
+      if (staging.nlink !== 2n || target.nlink !== 2n) throw new Error("resource coordinator committed staging alias has unexpected links");
+      verifyPair(stagingPath, targetPath, staging, target, true);
+      unlinkSync(stagingPath);
+      return;
+    }
+    if (stagingPublisherMayBeCurrent(publisherPid, staging)) throw Object.assign(new Error("resource coordinator staging file is still owned by a live publisher"), { code: RESOURCE_STAGING_BUSY_CODE });
+    if (staging.nlink !== 1n || target.nlink !== 1n) throw new Error("resource coordinator uncommitted replacement staging has unexpected links");
+    verifyPair(stagingPath, targetPath, staging, target, false);
+    unlinkSync(stagingPath);
+    return;
+  }
+  if (stagingPublisherMayBeCurrent(publisherPid, staging)) throw Object.assign(new Error("resource coordinator staging file is still owned by a live publisher"), { code: RESOURCE_STAGING_BUSY_CODE });
+  if (staging.nlink !== 1n) throw new Error("resource coordinator uncommitted staging file has unexpected links");
+  const current = inspect(stagingPath, "resource coordinator staging file");
+  if (current.nlink !== 1n || !sameFilesystemIdentity(staging.identity, current.identity)) {
+    throw new Error("resource coordinator staging file changed during recovery");
+  }
+  unlinkSync(stagingPath);
+}
+
+function verifyPair(stagingPath, targetPath, staging, target, requireSameObject) {
+  const currentStaging = inspect(stagingPath, "resource coordinator staging file");
+  const currentTarget = inspect(targetPath, "resource coordinator published file");
+  if (currentStaging.nlink !== staging.nlink || currentTarget.nlink !== target.nlink
+      || !sameFilesystemIdentity(staging.identity, currentStaging.identity)
+      || !sameFilesystemIdentity(target.identity, currentTarget.identity)
+      || (requireSameObject && !sameFilesystemIdentity(currentStaging.identity, currentTarget.identity))) {
+    throw new Error("resource coordinator staging file changed during recovery");
+  }
+}
+
+function inspect(file, label) {
+  const info = lstatSync(file, { bigint: true });
+  if (info.isSymbolicLink() || !info.isFile()) throw new Error(`${label} must be a regular file`);
+  return { nlink: info.nlink, identity: filesystemIdentity(info, label), modified_at: Number(info.mtimeMs) };
+}
+function inspectOptional(file, label) {
+  try { return inspect(file, label); }
+  catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+}
+
+function stagingPublisherMayBeCurrent(pid, staging) {
+  const status = inspectProcessInstance({ pid, startedAt: staging.modified_at });
+  return status.alive === true && status.reclaimable !== true;
+}

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

@@ -0,0 +1,31 @@
+const SWIFT_UINT32_MAX = 4_294_967_295;
+
+export function swiftJobPlan(argv, maximum = 1024) {
+  let plan = null;
+  for (let index = 1; index < (argv || []).length; index += 1) {
+    const value = String(argv[index] || ""); if (value === "--") break;
+    let current = null;
+    if (["-j", "--jobs"].includes(value)) {
+      if (index + 1 >= argv.length) return invalidPlan();
+      current = numericPlan(argv[index + 1], maximum); index += 1;
+    } else if (value.startsWith("--jobs=")) {
+      const attached = value.slice("--jobs=".length); if (!attached && index + 1 >= argv.length) return invalidPlan(); current = numericPlan(attached || argv[++index], maximum);
+    } else if (value.startsWith("-j=")) {
+      const attached = value.slice("-j=".length); if (!attached) return invalidPlan(); current = numericPlan(attached, maximum);
+    } else if (value.startsWith("-j") && value !== "-j") return invalidPlan();
+    if (current?.invalid) return current;
+    if (current) plan = current;
+  }
+  return plan;
+}
+
+function numericPlan(value, maximum) {
+  const text = String(value ?? "");
+  if (!/^\+?\d+$/.test(text)) return invalidPlan();
+  const parsed = Number(text);
+  if (!Number.isSafeInteger(parsed) || parsed > SWIFT_UINT32_MAX) return invalidPlan();
+  if (parsed === 0) return unboundedPlan();
+  return parsed <= maximum ? { jobs: parsed, elastic: false, unbounded: false } : unboundedPlan();
+}
+function invalidPlan() { return { jobs: null, elastic: false, unbounded: false, invalid: true }; }
+function unboundedPlan() { return { jobs: null, elastic: false, unbounded: true }; }