machine-bridge-mcp 0.18.1 → 1.0.1

package/scripts/sarif-security-gate.mjs

@@ -0,0 +1,146 @@
+import { readFileSync, readdirSync, statSync } from "node:fs";
+import { readBoundedRegularFileSync } from "../src/local/secure-file.mjs";
+import { basename, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+const args = process.argv.slice(2);
+const targets = args.filter((value) => !value.startsWith("--"));
+const allowlistOption = args.find((value) => value.startsWith("--allowlist="));
+const allowlistPath = resolve(root, allowlistOption ? allowlistOption.slice("--allowlist=".length) : ".github/codeql-accepted-findings.json");
+if (!targets.length) throw new Error("usage: node scripts/sarif-security-gate.mjs SARIF_PATH [...SARIF_PATH]");
+
+const accepted = loadAcceptedFindings(allowlistPath);
+const sarifFiles = targets.flatMap((target) => collectSarifFiles(resolve(target)));
+if (!sarifFiles.length) throw new Error("CodeQL security gate received no SARIF files");
+
+const blocked = [];
+const acknowledged = [];
+for (const file of sarifFiles) {
+  const document = readSarif(file);
+  for (const run of document.runs || []) inspectRun(run, file, accepted, blocked, acknowledged);
+}
+
+for (const finding of acknowledged) {
+  process.stderr.write(`accepted CodeQL finding: ${finding.ruleId} at ${finding.path} (${finding.reason}; expires ${finding.expires})\n`);
+}
+if (blocked.length) {
+  for (const finding of blocked.slice(0, 100)) {
+    process.stderr.write(`${finding.path}:${finding.line}: ${finding.ruleId}: ${finding.message}\n`);
+  }
+  if (blocked.length > 100) process.stderr.write(`... ${blocked.length - 100} additional security findings omitted\n`);
+  throw new Error(`CodeQL security gate rejected ${blocked.length} unaccepted security finding(s)`);
+}
+process.stderr.write(`CodeQL security gate ok (${sarifFiles.length} SARIF file(s); ${acknowledged.length} explicitly accepted finding(s))\n`);
+
+function inspectRun(run, file, allowlist, blockedFindings, acceptedFindings) {
+  const rules = new Map();
+  for (const rule of run.tool?.driver?.rules || []) rules.set(rule.id, rule);
+  for (const result of run.results || []) {
+    const ruleId = String(result.ruleId || "");
+    const rule = rules.get(ruleId) || {};
+    if (!isSecurityRule(rule)) continue;
+    const location = primaryLocation(result);
+    const path = normalizeSarifPath(location.path, run, file);
+    const line = Number(location.line) || 1;
+    const message = boundedMessage(result.message?.text || result.message?.markdown || rule.shortDescription?.text || "security finding");
+    const exception = allowlist.get(`${ruleId}\0${path}`);
+    if (exception) acceptedFindings.push({ ruleId, path, ...exception });
+    else blockedFindings.push({ ruleId, path, line, message });
+  }
+}
+
+function isSecurityRule(rule) {
+  const properties = rule?.properties || {};
+  const tags = Array.isArray(properties.tags) ? properties.tags.map((value) => String(value).toLowerCase()) : [];
+  const severity = Number(properties["security-severity"]);
+  return tags.includes("security") || (Number.isFinite(severity) && severity > 0);
+}
+
+function primaryLocation(result) {
+  const physical = result.locations?.[0]?.physicalLocation || {};
+  return {
+    path: physical.artifactLocation?.uri || "<unknown>",
+    line: physical.region?.startLine || 1,
+  };
+}
+
+function normalizeSarifPath(value, run, sarifFile) {
+  let path = String(value || "<unknown>").replaceAll("\\", "/");
+  try { path = decodeURIComponent(path); } catch {}
+  if (path.startsWith("file://")) path = fileURLToPath(path).replaceAll("\\", "/");
+  const baseId = run.originalUriBaseIds?.["%SRCROOT%"]?.uri;
+  if (baseId && path.startsWith(String(baseId))) path = path.slice(String(baseId).length);
+  if (isAbsolute(path)) {
+    const repositoryRelative = relative(root, path).split(sep).join("/");
+    path = repositoryRelative === ".." || repositoryRelative.startsWith("../") ? path : repositoryRelative;
+  }
+  path = path.replace(/^\.\//, "").replace(/^\/+/, "");
+  if (!path || path === ".") return `<unknown:${basename(sarifFile)}>`;
+  return path;
+}
+
+function loadAcceptedFindings(file) {
+  let document;
+  try { document = JSON.parse(readFileSync(file, "utf8")); } catch (error) {
+    if (error?.code === "ENOENT") return new Map();
+    throw new Error(`CodeQL accepted-findings file is invalid: ${file}`, { cause: error });
+  }
+  if (document?.schemaVersion !== 1 || !Array.isArray(document.accepted)) {
+    throw new Error("CodeQL accepted-findings file must use schemaVersion 1 and an accepted array");
+  }
+  const today = new Date().toISOString().slice(0, 10);
+  const entries = new Map();
+  for (const item of document.accepted) {
+    const ruleId = String(item?.ruleId || "");
+    const path = String(item?.path || "").replaceAll("\\", "/").replace(/^\.\//, "");
+    const reason = String(item?.reason || "").trim();
+    const expires = String(item?.expires || "");
+    if (!ruleId || !path || reason.length < 40 || !/^\d{4}-\d{2}-\d{2}$/.test(expires)) {
+      throw new Error("each accepted CodeQL finding requires ruleId, path, a substantive reason, and YYYY-MM-DD expires");
+    }
+    if (expires < today) throw new Error(`accepted CodeQL finding expired: ${ruleId} at ${path}`);
+    const key = `${ruleId}\0${path}`;
+    if (entries.has(key)) throw new Error(`duplicate accepted CodeQL finding: ${ruleId} at ${path}`);
+    entries.set(key, { reason, expires });
+  }
+  return entries;
+}
+
+function collectSarifFiles(input) {
+  const info = statSync(input);
+  if (info.isFile()) return isSarifName(input) ? [input] : [];
+  if (!info.isDirectory()) return [];
+  const files = [];
+  const stack = [input];
+  while (stack.length) {
+    const directory = stack.pop();
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) stack.push(path);
+      else if (entry.isFile() && isSarifName(path)) files.push(path);
+      if (files.length > 100) throw new Error("CodeQL security gate received more than 100 SARIF files");
+    }
+  }
+  return files.sort();
+}
+
+function isSarifName(file) {
+  const name = file.toLowerCase();
+  return extname(name) === ".sarif" || name.endsWith(".sarif.json");
+}
+
+function readSarif(file) {
+  const repositoryPath = relative(root, file).split(sep).join("/");
+  const bytes = readBoundedRegularFileSync(file, 100 * 1024 * 1024, "SARIF file");
+  let text;
+  try { text = new TextDecoder("utf-8", { fatal: true }).decode(bytes); }
+  catch { throw new Error(`SARIF file is not valid UTF-8: ${repositoryPath}`); }
+  const document = JSON.parse(text);
+  if (!Array.isArray(document?.runs)) throw new Error(`invalid SARIF document: ${repositoryPath}`);
+  return document;
+}
+
+function boundedMessage(value) {
+  return String(value || "").replace(/\s+/g, " ").slice(0, 500);
+}

package/src/local/account-access.mjs

@@ -6,7 +6,6 @@ export const ACCOUNT_ACCESS_REVISION = Number(accessContract.revision);
 export const ACCOUNT_ROLES = Object.freeze(Object.fromEntries(
   Object.entries(accessContract.roles).map(([name, value]) => [name, Object.freeze({ ...value })]),
 ));
-export const DEFAULT_ACCOUNT_ROLE = String(accessContract.defaultRole);
 export const OWNER_ACCOUNT_ROLE = String(accessContract.ownerRole);
 
 export function normalizeAccountRole(value) {

package/src/local/atomic-fs.mjs

@@ -7,7 +7,7 @@ export function replaceFileSync(source, target, options = {}) {
   const rename = typeof options.rename === "function" ? options.rename : renameSync;
   const sleep = typeof options.sleep === "function" ? options.sleep : sleepSync;
   const random = typeof options.random === "function" ? options.random : Math.random;
-  const attempts = clampInteger(options.attempts, 16, 1, 64);
+  const attempts = clampInteger(options.attempts, 32, 1, 64);
   const baseDelayMs = clampInteger(options.baseDelayMs, 15, 0, 1000);
   const maxDelayMs = Math.max(baseDelayMs, clampInteger(options.maxDelayMs, 250, 0, 2000));
   let lastError;

package/src/local/browser-bridge.mjs

@@ -5,11 +5,11 @@ import { WebSocket, WebSocketServer } from "ws";
 import { createToolAuthorizer } from "./policy.mjs";
 import { assertStateMaintenanceAvailable, packageRoot } from "./state.mjs";
 import {
-  BROWSER_EXTENSION_PROTOCOL, EXPECTED_EXTENSION_VERSION, MAX_BROWSER_MESSAGE_BYTES, REQUIRED_EXTENSION_CAPABILITIES,
+  BROWSER_EXTENSION_PROTOCOL, EXPECTED_EXTENSION_VERSION, MAX_BROWSER_MESSAGE_BYTES,
   closeProtocolSocket, normalizeCompatibleExtensionInfo, parseBrowserSocketMessage, parseExtensionHello, safeSocketSend,
 } from "./browser-extension-protocol.mjs";
 import {
-  DEFAULT_BROWSER_PORT, isAllowedExtensionOrigin, isAllowedLoopbackHost, loadOrCreatePairing,
+  isAllowedExtensionOrigin, isAllowedLoopbackHost, loadOrCreatePairing,
   pairingHtml, savePairing, securityHeaders, sendJson,
 } from "./browser-pairing-store.mjs";
 import {

package/src/local/browser-extension-protocol.mjs

@@ -4,7 +4,7 @@ import { packageRoot } from "./state.mjs";
 
 export const BROWSER_EXTENSION_PROTOCOL = 3;
 export const EXPECTED_EXTENSION_VERSION = extensionVersion();
-export const REQUIRED_EXTENSION_CAPABILITIES = Object.freeze([
+const REQUIRED_EXTENSION_CAPABILITIES = Object.freeze([
   "semantic_snapshot_refs", "actionability_waits", "trusted_input", "tab_management", "explicit_waits",
 ]);
 export const MAX_BROWSER_MESSAGE_BYTES = 8 * 1024 * 1024;

package/src/local/browser-pairing-store.mjs

@@ -1,19 +1,18 @@
 import { randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { readBoundedRegularFileSync } from "./secure-file.mjs";
-import { assertStateMaintenanceAvailable, ownerOnlyFile } from "./state.mjs";
+import { assertStateMaintenanceAvailable, ensureOwnerOnlyDir, ownerOnlyFile } from "./state.mjs";
 import { EXPECTED_EXTENSION_VERSION } from "./browser-extension-protocol.mjs";
 
-export const DEFAULT_BROWSER_PORT = 39393;
+const DEFAULT_BROWSER_PORT = 39393;
 const PAIRING_FILE = "browser-bridge.json";
 
 export async function loadOrCreatePairing(stateRoot) {
   if (!stateRoot) return { token: randomBytes(32).toString("base64url"), port: DEFAULT_BROWSER_PORT };
   assertStateMaintenanceAvailable(stateRoot);
-  await mkdir(stateRoot, { recursive: true, mode: 0o700 });
+  ensureOwnerOnlyDir(stateRoot);
   const file = join(stateRoot, PAIRING_FILE);
   for (let attempt = 0; attempt < 2; attempt += 1) {
     if (existsSync(file)) {

package/src/local/cli.mjs

@@ -1,10 +1,11 @@
-import { createHash, randomBytes } from "node:crypto";
-import { existsSync, readdirSync, readFileSync, statSync, unlinkSync } from "node:fs";
+import { createHmac } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import path, { join, resolve } from "node:path";
 import process from "node:process";
 import readline from "node:readline/promises";
 import { LocalRuntime } from "./runtime.mjs";
 import { acquireDaemonLockWithTakeover, inspectWorkspaceDaemon, stopWorkspaceServiceDaemon } from "./daemon-process.mjs";
+import { inspectProcessInstance } from "./process-identity.mjs";
 import { runStdioServer } from "./stdio.mjs";
 import { assertCanonicalFullPolicy, POLICY_PROFILES, toolsForPolicy } from "./tools.mjs";
 import { resolvePolicy } from "./cli-policy.mjs";
@@ -14,25 +15,22 @@ import { generateAccountPassword } from "./account-admin.mjs";
 import { accountAdminClient, createAccountCommand } from "./cli-account-admin.mjs";
 export { resolvePolicy } from "./cli-policy.mjs";
 export { parseArgs, validateCommandOptions, validateLoggingOptions, validatePositionals } from "./cli-options.mjs";
-import { classifyOperationalError, createLogger, normalizeLogLevel, sanitizeLogText } from "./log.mjs";
-import { run, runWrangler } from "./shell.mjs";
+import { classifyOperationalError, createLogger, sanitizeLogText } from "./log.mjs";
+import { runExecutable, runWrangler } from "./shell.mjs";
 import { runFullAccessTest } from "./full-access-test.mjs";
-import { inspectProcessInstance } from "./process-identity.mjs";
 import { stopAndRemoveAutostart } from "./service-lifecycle.mjs";
 import { activeStateJobs, activeStateLocks, knownProfileStates, knownWorkerNames } from "./state-inventory.mjs";
-import { createExclusiveFileSync } from "./exclusive-file.mjs";
+import { withWorkerSecretsFile } from "./worker-secret-file.mjs";
 import {
   acquireMaintenanceLock,
   acquireStartupLockWithWait,
   appName,
   daemonLockPathForState,
   defaultStateRoot,
-  ensureOwnerOnlyDir,
   ensureWorkerSecrets,
   expandHome,
   loadGlobalConfig,
   loadState,
-  ownerOnlyFile,
   packageRoot,
   readDaemonLockOwner,
   redactState,
@@ -362,7 +360,7 @@ async function clientConfigCommand(args) {
 
 async function ensureWorker(state, args) {
   const logger = createLogger({ level: args.json ? "error" : effectiveLogLevel(args), format: effectiveLogFormat(args), component: "worker" });
-  const desiredHash = workerDeployHash(state);
+  const desiredHash = workerDeploymentFingerprint(state);
   const expectedVersion = currentPackageVersion();
   const complete = state.worker.url && state.worker.mcpServerUrl && state.worker.accountAdminSecret && state.worker.daemonSecret && state.worker.oauthTokenVersion && state.worker.name;
   if (!args.forceWorker && !args.rotateSecrets && complete && state.worker.deployHash === desiredHash) {
@@ -383,7 +381,7 @@ async function ensureWorker(state, args) {
   }
 
   logger.info("Deploying Cloudflare Worker", { name: state.worker.name });
-  const deploy = await withSecretsFile(state, secretFile => runWrangler([
+  const deploy = await withWorkerSecretsFile(state, secretFile => runWrangler([
     "deploy",
     "--name", state.worker.name,
     "--minify",
@@ -409,52 +407,21 @@ async function ensureWorker(state, args) {
   return state.worker;
 }
 
-async function withSecretsFile(state, callback) {
-  const dir = state.paths.profileDir;
-  ensureOwnerOnlyDir(dir);
-  cleanupStaleSecretFiles(dir);
-  const tempPath = resolve(dir, `worker-secrets-${process.pid}-${Date.now()}-${randomBytes(6).toString("hex")}.json`);
-  const payload = {
-    ACCOUNT_ADMIN_SECRET: state.worker.accountAdminSecret,
-    DAEMON_SHARED_SECRET: state.worker.daemonSecret,
-    OAUTH_TOKEN_VERSION: state.worker.oauthTokenVersion,
-  };
-  createExclusiveFileSync(tempPath, JSON.stringify(payload), { mode: 0o600 });
-  ownerOnlyFile(tempPath);
-  try {
-    return await callback(tempPath);
-  } finally {
-    try { unlinkSync(tempPath); } catch {}
-  }
-}
-
-export function cleanupStaleSecretFiles(dir) {
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (!entry.isFile()) continue;
-    const match = /^worker-secrets-(\d+)-(\d+)(?:-[a-f0-9]+)?\.json$/.exec(entry.name);
-    if (!match) continue;
-    const file = resolve(dir, entry.name);
-    try {
-      const pid = Number(match[1]);
-      const createdAt = Number(match[2]);
-      const identity = inspectProcessInstance({ pid, startedAt: new Date(createdAt).toISOString() });
-      if (!identity.current) unlinkSync(file);
-    } catch {}
-  }
-}
 
-function workerDeployHash(state) {
-  const hash = createHash("sha256");
-  hash.update("mbm-worker-deploy-v2");
-  hash.update(String(state.worker.name || ""));
-  hash.update(String(state.worker.accountAdminSecret || ""));
-  hash.update(String(state.worker.daemonSecret || ""));
-  hash.update(String(state.worker.oauthTokenVersion || ""));
+function workerDeploymentFingerprint(state) {
+  const keyMaterial = [
+    String(state.worker.accountAdminSecret || ""),
+    String(state.worker.daemonSecret || ""),
+    String(state.worker.oauthTokenVersion || ""),
+  ].join("\0");
+  const fingerprint = createHmac("sha256", keyMaterial);
+  fingerprint.update("mbm-worker-deploy-v3");
+  fingerprint.update(String(state.worker.name || ""));
   for (const file of workerDeployHashFiles()) {
-    hash.update(path.relative(packageRoot, file));
-    hash.update(workerHashContent(file));
+    fingerprint.update(path.relative(packageRoot, file));
+    fingerprint.update(workerHashContent(file));
   }
-  return hash.digest("hex");
+  return fingerprint.digest("hex");
 }
 
 function workerHashContent(file) {
@@ -606,7 +573,7 @@ async function doctorCommand(args) {
   const checks = [];
   checks.push({ name: "node", ok: isSupportedNodeVersion(), detail: process.version });
   const npmCommand = npmVersionCommand();
-  const npm = await run(npmCommand.file, npmCommand.args, { capture: true, allowFailure: true, timeoutMs: 10_000 });
+  const npm = await runExecutable(npmCommand.file, npmCommand.args, { capture: true, allowFailure: true, timeoutMs: 10_000 });
   const npmDetail = sanitizeLines(npm.stdout || npm.stderr);
   checks.push({ name: "npm", ok: npm.code === 0 && isSupportedNpmVersion(npmDetail), detail: npmDetail || "unavailable" });
   const wrangler = await runWrangler(["--version"], { capture: true, allowFailure: true });
@@ -805,7 +772,7 @@ async function stopAutostartBestEffort(logger) {
 async function uninstallCommand(args) {
   const stateRoot = stateRootFromArgs(args);
   const deleteRemote = !args.keepWorker;
-  const validation = validateStateRootForRemoval(stateRoot);
+  validateStateRootForRemoval(stateRoot);
   const action = deleteRemote
     ? `delete deployed Worker(s), remove autostart entries, and remove local state at ${stateRoot}`
     : `remove autostart entries and local state at ${stateRoot} while keeping deployed Worker(s)`;

package/src/local/default-instructions.mjs

@@ -8,8 +8,8 @@ const MAX_PROJECT_CONTEXT_BYTES = 16 * 1024;
 const MAX_SCRIPT_NAMES = 24;
 const MAX_WORKFLOW_FILES = 20;
 
-export const BUILTIN_INSTRUCTIONS_SOURCE = "machine-bridge://defaults/working-agreements";
-export const AUTOMATIC_PROJECT_CONTEXT_SOURCE = "machine-bridge://project-context/current";
+const BUILTIN_INSTRUCTIONS_SOURCE = "machine-bridge://defaults/working-agreements";
+const AUTOMATIC_PROJECT_CONTEXT_SOURCE = "machine-bridge://project-context/current";
 
 const BUILTIN_INSTRUCTIONS = `# Machine Bridge default working agreements
 
@@ -43,8 +43,9 @@ These are conservative defaults. Explicit current-user requests and more specifi
 
 ## Git and delivery
 
+- Before any GitHub read or mutation, read the effective project instructions. If they require local git, gh, and gh api through Machine Bridge, never call a hosted GitHub connector or ChatGPT GitHub plugin; if that local control plane is unavailable, stop and report the boundary instead of substituting another control plane.
 - Do not amend, rebase, force-push, delete branches or tags, or discard working-tree changes unless explicitly requested.
-- Commit or push only when the current task or repository instructions authorize it. Do not create tags, releases, or package publications merely because a version changed.
+- Commit or push only when the current task or repository instructions authorize it. Follow repository-specific source-release ownership when it explicitly authorizes tags and GitHub Releases; otherwise do not create them merely because a version changed.
 - Summarize what changed, which checks ran, and any remaining limitations or operator steps.
 `;
 

package/src/local/errors.mjs

@@ -19,10 +19,6 @@ export class BridgeError extends Error {
   }
 }
 
-export function bridgeError(code, message, options) {
-  return new BridgeError(code, message, options);
-}
-
 export function normalizeBridgeError(error, options = {}) {
   if (error instanceof BridgeError) return error;
   const code = errorCode(error, options.defaultCode);
@@ -70,7 +66,7 @@ export function remoteBridgeError(value, fallbackMessage = "remote operation fai
   return new BridgeError("execution_failed", fallbackMessage);
 }
 
-export function normalizeErrorCode(value, fallback = "execution_failed") {
+function normalizeErrorCode(value, fallback = "execution_failed") {
   const code = String(value || "").trim().toLowerCase().replace(/[^a-z0-9_-]/g, "_").slice(0, 64);
   return ERROR_CODES.has(code) ? code : fallback;
 }

package/src/local/exclusive-file.mjs

@@ -1,6 +1,6 @@
 import { randomBytes } from "node:crypto";
 import {
-  chmodSync,
+  fchmodSync,
   closeSync,
   fsyncSync,
   linkSync,
@@ -21,12 +21,12 @@ export function createExclusiveFileSync(target, content, options = {}) {
   try {
     fd = openSync(temporary, "wx", mode);
     writeFileSync(fd, content);
+    setDescriptorMode(fd, mode);
     fsyncSync(fd);
     closeSync(fd);
     fd = undefined;
     linkSync(temporary, target);
     linked = true;
-    try { chmodSync(target, mode); } catch {}
     return { created: true, path: target };
   } finally {
     if (fd !== undefined) try { closeSync(fd); } catch {}
@@ -44,11 +44,11 @@ export function replaceFileAtomicallySync(target, content, options = {}) {
   try {
     fd = openSync(temporary, "wx", mode);
     writeFileSync(fd, content);
+    setDescriptorMode(fd, mode);
     fsyncSync(fd);
     closeSync(fd);
     fd = undefined;
     replaceFileSync(temporary, target);
-    try { chmodSync(target, mode); } catch {}
     return { replaced: true, path: target };
   } catch (error) {
     if (fd !== undefined) try { closeSync(fd); } catch {}
@@ -92,3 +92,9 @@ function sameIdentity(left, right) {
     && Number(left.size) === Number(right.size)
     && Number(left.mtimeMs) === Number(right.mtimeMs);
 }
+
+function setDescriptorMode(fd, mode) {
+  try { fchmodSync(fd, mode); } catch (error) {
+    if (process.platform !== "win32") throw error;
+  }
+}

package/src/local/full-access-test.mjs

@@ -4,7 +4,7 @@ import { join, resolve } from "node:path";
 import process from "node:process";
 import { LocalRuntime } from "./runtime.mjs";
 import { generateSshKeyPair } from "./ssh-key.mjs";
-import { run } from "./shell.mjs";
+import { runExecutable } from "./shell.mjs";
 import { allToolNames, assertCanonicalFullPolicy, policyProfile } from "./tools.mjs";
 
 const TERMINAL_JOB_STATES = new Set([
@@ -90,7 +90,7 @@ export async function runFullAccessTest({ workspace, policy = policyProfile("ful
     }));
 
     const nullConfig = process.platform === "win32" ? "NUL" : "/dev/null";
-    const sshConfig = await run("ssh", ["-F", nullConfig, "-G", "localhost"], {
+    const sshConfig = await runExecutable("ssh", ["-F", nullConfig, "-G", "localhost"], {
       capture: true,
       allowFailure: true,
       timeoutMs: 15_000,
@@ -98,14 +98,14 @@ export async function runFullAccessTest({ workspace, policy = policyProfile("ful
     });
     checks.push(check("ssh-client", sshConfig.code === 0));
 
-    const gcloud = await run("gcloud", ["--version"], {
+    const gcloud = await runExecutable("gcloud", ["--version"], {
       capture: true,
       allowFailure: true,
       timeoutMs: 30_000,
       maxOutputBytes: 64 * 1024,
     });
     const osLoginHelp = gcloud.code === 0
-      ? await run("gcloud", ["help", "compute", "os-login", "ssh-keys", "add"], {
+      ? await runExecutable("gcloud", ["help", "compute", "os-login", "ssh-keys", "add"], {
           capture: true,
           allowFailure: true,
           timeoutMs: 30_000,
@@ -119,7 +119,7 @@ export async function runFullAccessTest({ workspace, policy = policyProfile("ful
 
     const sudo = process.platform === "win32"
       ? { code: 0, skipped: true }
-      : await run("sudo", ["-n", "true"], {
+      : await runExecutable("sudo", ["-n", "true"], {
           capture: true,
           allowFailure: true,
           timeoutMs: 10_000,

package/src/local/job-runner.mjs

@@ -54,8 +54,8 @@ for (const signal of ["SIGTERM", "SIGINT"]) {
 const initial = readJson(statusFile, MAX_STATUS_BYTES);
 assertLaunchState(initial);
 createExclusiveFileSync(runnerPidFile, `${JSON.stringify({ pid: process.pid, processStartedAt: RUNNER_PROCESS_STARTED_AT })}\n`, { mode: 0o600 });
-if (recover) rmSync(join(jobDir, "recovery.lock"), { force: true });
 try {
+  if (recover) await releaseRecoveryClaim();
   const plan = readJson(planFile, 1024 * 1024);
   assertPlanIntegrity(plan, initial);
   await main(plan, initial);

package/src/local/managed-jobs.mjs

@@ -1,15 +1,15 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
-import { chmodSync, closeSync, constants as fsConstants, existsSync, fstatSync, ftruncateSync, lstatSync, openSync, readSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { closeSync, constants as fsConstants, existsSync, ftruncateSync, lstatSync, readSync, readdirSync, realpathSync, rmSync, statSync, writeFileSync, writeSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { assertStateMaintenanceAvailable, ensureOwnerOnlyDir, ownerOnlyFile } from "./state.mjs";
 import { createExclusiveFileSync, replaceFileAtomicallySync } from "./exclusive-file.mjs";
 import { currentProcessStartTimeMs, inspectProcessInstance, processStartTimeMs } from "./process-identity.mjs";
-import { readBoundedRegularFileSync, readBoundedRegularFileWithInfoSync } from "./secure-file.mjs";
+import { openRegularFileSync, readBoundedRegularFileSync } from "./secure-file.mjs";
 import { createToolAuthorizer } from "./policy.mjs";
 import { BridgeError } from "./errors.mjs";
-import { inspectResourceFile, normalizeResourceRegistry, publicResourceRegistry, validatePlan, validateResourceName } from "./managed-job-plan.mjs";
+import { inspectResourceFile, normalizeResourceRegistry, validatePlan } from "./managed-job-plan.mjs";
 export { inspectResourceFile, publicResourceRegistry, validateResourceName } from "./managed-job-plan.mjs";
 import { clampInteger } from "./numbers.mjs";
 
@@ -120,7 +120,7 @@ export class ManagedJobManager {
       status.status = "queued";
       status.updated_at = new Date().toISOString();
       status.approved_at = status.updated_at;
-      status.approval = localOperator ? "local-operator" : "mcp";
+      status.approval = "local-operator";
       status.cleanup_guarantee = "best-effort-finally-and-recovery";
       atomicWriteJson(statusFile, status, 256 * 1024);
       try {
@@ -589,22 +589,14 @@ function pidLockOwner(pid, startedAtMs) {
   };
 }
 
-function readPidLockOwner(file) {
-  return readPidLockSnapshot(file)?.owner || null;
-}
-
 function readPidLockSnapshot(file) {
   let info;
   try { info = lstatSync(file); } catch (error) { if (error?.code === "ENOENT") return null; throw error; }
   if (info.isSymbolicLink() || !info.isFile()) throw new Error("job lock must be a regular non-symbolic-link file");
   let owner = null;
   try {
-    const text = readBoundedFile(file, 1024).toString("utf8").trim();
-    if (/^\d+$/.test(text)) owner = { pid: Number(text), startedAt: new Date(info.mtimeMs).toISOString() };
-    else {
-      const parsed = JSON.parse(text);
-      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) owner = parsed;
-    }
+    const parsed = JSON.parse(readBoundedFile(file, 1024).toString("utf8").trim());
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) owner = parsed;
   } catch (error) {
     if (error?.code === "ENOENT") return null;
   }
@@ -780,34 +772,27 @@ function readBoundedFile(file, maxBytes) {
 }
 
 function openPrivateAppendFile(file) {
-  if (existsSync(file)) {
-    const info = lstatSync(file);
-    if (info.isSymbolicLink() || !info.isFile()) throw new Error("runner diagnostic path must be a regular file and not a symbolic link");
-  }
-  const flags = Number(fsConstants.O_WRONLY) | Number(fsConstants.O_CREAT) | Number(fsConstants.O_APPEND) | Number(fsConstants.O_NOFOLLOW || 0);
-  const fd = openSync(file, flags, 0o600);
-  try {
-    if (!fstatSync(fd).isFile()) throw new Error("runner diagnostic path is not a regular file");
-    chmodSync(file, 0o600);
-    return fd;
-  } catch (error) {
-    closeSync(fd);
-    throw error;
-  }
+  return openRegularFileSync(
+    file,
+    Number(fsConstants.O_WRONLY) | Number(fsConstants.O_CREAT) | Number(fsConstants.O_APPEND),
+    { label: "runner diagnostic path", mode: 0o600, chmod: 0o600 },
+  ).fd;
 }
 
 function trimDiagnosticFile(file, maxBytes = 64 * 1024, keepBytes = 32 * 1024) {
   let fd;
   try {
-    const flags = Number(fsConstants.O_RDWR) | Number(fsConstants.O_NOFOLLOW || 0);
-    fd = openSync(file, flags);
-    const info = fstatSync(fd);
-    if (!info.isFile() || info.size <= maxBytes) return;
-    const length = Math.min(keepBytes, info.size);
+    const opened = openRegularFileSync(file, fsConstants.O_RDWR, {
+      label: "runner diagnostic path",
+      chmod: 0o600,
+    });
+    fd = opened.fd;
+    if (opened.info.size <= maxBytes) return;
+    const length = Math.min(keepBytes, opened.info.size);
     const buffer = Buffer.alloc(length);
     let offset = 0;
     while (offset < length) {
-      const count = readSync(fd, buffer, offset, length - offset, info.size - length + offset);
+      const count = readSync(fd, buffer, offset, length - offset, opened.info.size - length + offset);
       if (!count) break;
       offset += count;
     }
@@ -816,20 +801,17 @@ function trimDiagnosticFile(file, maxBytes = 64 * 1024, keepBytes = 32 * 1024) {
     if (newline >= 0 && newline < tail.length - 1) tail = tail.subarray(newline + 1);
     ftruncateSync(fd, 0);
     if (tail.length) writeSync(fd, tail, 0, tail.length, 0);
-    try { chmodSync(file, 0o600); } catch {}
-  } catch {
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
   } finally {
-    if (fd !== undefined) try { closeSync(fd); } catch {}
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch {
+        // Descriptor close is best effort after the trim result is already determined.
+      }
+    }
   }
 }
 
-function realpathFile(path) {
-  const input = resolve(path);
-  const linkInfo = lstatSync(input);
-  if (!linkInfo.isFile() && !linkInfo.isSymbolicLink()) throw new Error("resource path is not a regular file");
-  return realpathSync.native ? realpathSync.native(input) : realpathSync(input);
-}
-
 function resourceErrorClass(error) {
   const message = String(error?.message || error || "");
   if (/permission|EACCES|EPERM/i.test(message)) return "permission_denied";
@@ -843,9 +825,3 @@ function resourceErrorClass(error) {
 function safeReadDir(dir) {
   return readdirSync(dir, { withFileTypes: true });
 }
-
-function boundedString(value, maxBytes, label) {
-  if (typeof value !== "string" || value.includes("\0")) throw new Error(`${label} must be a string without NUL bytes`);
-  if (Buffer.byteLength(value) > maxBytes) throw new Error(`${label} exceeds ${maxBytes} bytes`);
-  return value;
-}

package/src/local/relay-connection.mjs

@@ -118,6 +118,13 @@ export class RelayConnection {
     return this.sendOnSocket(this.socket, value);
   }
 
+  interrupt(category = "relay_transport_error") {
+    if (this.closed || !this.socket) return false;
+    this.pendingCloseCategory = String(category || "relay_transport_error");
+    terminateSocket(this.socket);
+    return true;
+  }
+
   observeWelcome(message = {}) {
     const socket = this.socket;
     if (this.closed || this.ready || !this.isSocketOpen(socket)) return false;