machine-bridge-mcp 0.14.0 → 0.16.0

package/src/local/errors.mjs

@@ -0,0 +1,122 @@
+const ERROR_CODES = new Set([
+  "cancelled", "timeout", "authentication_failed", "authorization_denied", "policy_denied",
+  "invalid_request", "not_found", "conflict", "limit_exceeded", "permission_denied",
+  "path_boundary", "network_error", "protocol_error", "unavailable", "integrity_error",
+  "execution_failed", "internal_error",
+]);
+
+const RETRYABLE_CODES = new Set(["timeout", "network_error", "unavailable"]);
+
+export class BridgeError extends Error {
+  constructor(code, message, options = {}) {
+    const normalizedCode = normalizeErrorCode(code);
+    super(String(message || defaultMessage(normalizedCode)), options.cause ? { cause: options.cause } : undefined);
+    this.name = "BridgeError";
+    this.code = normalizedCode;
+    this.retryable = options.retryable === undefined ? RETRYABLE_CODES.has(normalizedCode) : options.retryable === true;
+    this.expose = options.expose !== false;
+    this.details = isRecord(options.details) ? Object.freeze({ ...options.details }) : undefined;
+  }
+}
+
+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);
+  const message = typeof options.safeMessage === "function"
+    ? options.safeMessage(error)
+    : typeof options.safeMessage === "string"
+      ? options.safeMessage
+      : safeFallbackMessage(error, code);
+  return new BridgeError(code, message, {
+    cause: error instanceof Error ? error : undefined,
+    expose: options.expose !== false,
+    retryable: options.retryable,
+  });
+}
+
+export function errorCode(error, fallback = "execution_failed") {
+  if (error instanceof BridgeError) return error.code;
+  const direct = normalizeErrorCode(error?.code, "");
+  if (direct && ERROR_CODES.has(direct)) return direct;
+  const nodeCode = String(error?.code || "").toUpperCase();
+  if (["ENOENT", "ENOTDIR"].includes(nodeCode)) return "not_found";
+  if (["EACCES", "EPERM", "EROFS"].includes(nodeCode)) return "permission_denied";
+  if (["ETIMEDOUT", "ESOCKETTIMEDOUT"].includes(nodeCode)) return "timeout";
+  if (["ECONNRESET", "ECONNREFUSED", "EHOSTUNREACH", "ENETUNREACH", "ENOTFOUND", "EAI_AGAIN"].includes(nodeCode)) return "network_error";
+  if (["EEXIST", "ENOTEMPTY", "EBUSY"].includes(nodeCode)) return "conflict";
+
+  // Legacy errors are classified once at the boundary. New code should throw BridgeError directly.
+  const message = error instanceof Error ? error.message : String(error ?? "");
+  if (/cancel/i.test(message)) return "cancelled";
+  if (/timed out/i.test(message)) return "timeout";
+  if (/unauthorized|authentication|\b401\b/i.test(message)) return "authentication_failed";
+  if (/forbidden|authorization|\b403\b/i.test(message)) return "authorization_denied";
+  if (/outside the configured workspace/i.test(message)) return "path_boundary";
+  if (/disabled|requires .* mode|requires the canonical .* profile/i.test(message)) return "policy_denied";
+  if (/not found|ENOENT/i.test(message)) return "not_found";
+  if (/permission|EACCES|EPERM/i.test(message)) return "permission_denied";
+  if (/maximum|exceeds|max_bytes|too many|limit reached/i.test(message)) return "limit_exceeded";
+  if (/integrity|hash mismatch|changed during/i.test(message)) return "integrity_error";
+  if (/protocol|unexpected .* message|invalid .* envelope/i.test(message)) return "protocol_error";
+  if (/invalid|must|requires|ambiguous|mismatch/i.test(message)) return "invalid_request";
+  return normalizeErrorCode(fallback);
+}
+
+export function publicError(error, options = {}) {
+  const normalized = normalizeBridgeError(error, options);
+  return {
+    code: normalized.code,
+    message: normalized.expose ? normalized.message : defaultMessage(normalized.code),
+    retryable: normalized.retryable,
+  };
+}
+
+export function remoteBridgeError(value, fallbackMessage = "remote operation failed") {
+  if (isRecord(value)) {
+    const code = normalizeErrorCode(value.code);
+    const message = typeof value.message === "string" && value.message ? value.message : fallbackMessage;
+    return new BridgeError(code, message, { retryable: value.retryable === true });
+  }
+  return new BridgeError("execution_failed", fallbackMessage);
+}
+
+export 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;
+}
+
+function safeFallbackMessage(error, code) {
+  if (error instanceof Error && error.message) return String(error.message).slice(0, 2000);
+  return defaultMessage(code);
+}
+
+function defaultMessage(code) {
+  const messages = {
+    cancelled: "operation cancelled",
+    timeout: "operation timed out",
+    authentication_failed: "authentication failed",
+    authorization_denied: "authorization denied",
+    policy_denied: "operation denied by policy",
+    invalid_request: "invalid request",
+    not_found: "requested resource was not found",
+    conflict: "operation conflicts with current state",
+    limit_exceeded: "operation exceeded a configured limit",
+    permission_denied: "permission denied",
+    path_boundary: "path is outside the configured boundary",
+    network_error: "network operation failed",
+    protocol_error: "protocol error",
+    unavailable: "service is unavailable",
+    integrity_error: "integrity check failed",
+    internal_error: "internal error",
+    execution_failed: "operation failed",
+  };
+  return messages[code] || messages.execution_failed;
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}

package/src/local/git-service.mjs

@@ -0,0 +1,88 @@
+import { stat } from "node:fs/promises";
+import { dirname, isAbsolute, relative, sep } from "node:path";
+import { BridgeError } from "./errors.mjs";
+
+export class GitService {
+  constructor({ resolveExistingPath, displayPath, runProcess, maximumBytes }) {
+    this.resolveExistingPath = resolveExistingPath;
+    this.displayPath = displayPath;
+    this.runProcess = runProcess;
+    this.maximumBytes = maximumBytes;
+  }
+
+  async status(args = {}, context = {}) {
+    const git = await this.context(args.path || ".", context);
+    if (!git.ok) return git.result;
+    const commandArgs = ["-c", "core.fsmonitor=false", "-C", git.root, "status", "--short", "--branch"];
+    if (git.pathspec) commandArgs.push("--", git.pathspec);
+    const result = await this.runProcess("git", commandArgs, 30_000, true, 512 * 1024, context);
+    return { ...result, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root) };
+  }
+
+  async diff(args = {}, context = {}) {
+    const maxBytes = clampInt(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
+    const git = await this.context(args.path || ".", context);
+    if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
+    const commandArgs = ["-c", "core.fsmonitor=false", "-c", "diff.external=", "-C", git.root, "diff", "--no-ext-diff", "--no-textconv"];
+    if (args.staged) commandArgs.push("--cached");
+    if (git.pathspec) commandArgs.push("--", git.pathspec);
+    const result = await this.runProcess("git", commandArgs, 60_000, true, maxBytes, context);
+    return { ...result, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root), staged: args.staged === true };
+  }
+
+  async log(args = {}, context = {}) {
+    const git = await this.context(args.path || ".", context);
+    if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
+    const maxCount = clampInt(args.max_count, 20, 1, 100);
+    const format = "%H%x1f%h%x1f%aI%x1f%an%x1f%ae%x1f%s%x1e";
+    const commandArgs = ["-c", "core.fsmonitor=false", "-C", git.root, "log", `--max-count=${maxCount}`, `--format=${format}`];
+    if (git.pathspec) commandArgs.push("--", git.pathspec);
+    const result = await this.runProcess("git", commandArgs, 30_000, true, 1024 * 1024, context);
+    const commits = result.stdout.split("\x1e").map((record) => record.trim()).filter(Boolean).map((record) => {
+      const [hash, short, authored_at, author_name, author_email, subject] = record.split("\x1f");
+      const commit = { hash, short, authored_at, author_name, subject };
+      if (args.include_author_email === true) commit.author_email = author_email;
+      return commit;
+    });
+    return { code: result.code, stderr: result.stderr, commits, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root) };
+  }
+
+  async show(args = {}, context = {}) {
+    const git = await this.context(args.path || ".", context);
+    if (!git.ok) return { ...git.result, path: this.displayPath(git.target) };
+    const revision = validateRevision(args.revision || "HEAD");
+    const maxBytes = clampInt(args.max_bytes, 1024 * 1024, 1, this.maximumBytes);
+    const commandArgs = ["-c", "core.fsmonitor=false", "-c", "diff.external=", "-C", git.root, "show", "--no-ext-diff", "--no-textconv", "--decorate=no", revision];
+    if (git.pathspec) commandArgs.push("--", git.pathspec);
+    const result = await this.runProcess("git", commandArgs, 60_000, true, maxBytes, context);
+    return { ...result, revision, path: this.displayPath(git.target), gitRoot: this.displayPath(git.root) };
+  }
+
+  async context(inputPath, context = {}) {
+    const target = await this.resolveExistingPath(inputPath);
+    const info = await stat(target);
+    const cwd = info.isDirectory() ? target : dirname(target);
+    const result = await this.runProcess("git", ["-c", "core.fsmonitor=false", "-C", cwd, "rev-parse", "--show-toplevel"], 10_000, true, 512 * 1024, context);
+    if (result.code !== 0) return { ok: false, result, target };
+    const root = result.stdout.trim();
+    const repoRelative = relative(root, target);
+    if (repoRelative.startsWith(`..${sep}`) || repoRelative === ".." || isAbsolute(repoRelative)) {
+      return { ok: false, target, result: { code: 128, stdout: "", stderr: "target is outside the detected git repository" } };
+    }
+    return { ok: true, target, root, pathspec: repoRelative || "" };
+  }
+}
+
+function validateRevision(value) {
+  const revision = String(value || "HEAD");
+  if (!revision || revision.length > 256 || revision.startsWith("-") || revision.includes("\0") || /[\r\n]/.test(revision)) {
+    throw new BridgeError("invalid_request", "invalid Git revision");
+  }
+  return revision;
+}
+
+function clampInt(value, fallback, minimum, maximum) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  const number = Number.isFinite(parsed) ? parsed : fallback;
+  return Math.min(Math.max(number, minimum), maximum);
+}

package/src/local/lifecycle.mjs

@@ -0,0 +1,64 @@
+import { BridgeError } from "./errors.mjs";
+
+const OPERATIONAL_STATES = new Set(["ready", "starting", "running"]);
+
+export class LifecycleController {
+  constructor(name = "runtime", now = Date.now) {
+    this.name = String(name || "runtime");
+    this.now = typeof now === "function" ? now : Date.now;
+    this.state = "ready";
+    this.changedAt = this.now();
+    this.failureCode = "";
+  }
+
+  beginStart() {
+    if (this.state === "running") return false;
+    if (this.state !== "ready" && this.state !== "failed") {
+      throw new BridgeError("conflict", `${this.name} cannot start from state ${this.state}`);
+    }
+    this.transition("starting");
+    return true;
+  }
+
+  markRunning() {
+    if (this.state !== "starting") throw new BridgeError("conflict", `${this.name} cannot become running from state ${this.state}`);
+    this.failureCode = "";
+    this.transition("running");
+  }
+
+  markFailed(error) {
+    this.failureCode = String(error?.code || error?.name || "execution_failed").slice(0, 64);
+    this.transition("failed");
+  }
+
+  beginStop() {
+    if (this.state === "stopped" || this.state === "stopping") return false;
+    this.transition("stopping");
+    return true;
+  }
+
+  markStopped() {
+    if (this.state !== "stopping") throw new BridgeError("conflict", `${this.name} cannot become stopped from state ${this.state}`);
+    this.transition("stopped");
+  }
+
+  assertOperational() {
+    if (!OPERATIONAL_STATES.has(this.state)) {
+      throw new BridgeError("unavailable", `${this.name} is not operational (${this.state})`, { retryable: this.state !== "stopped" });
+    }
+  }
+
+  snapshot() {
+    return {
+      state: this.state,
+      operational: OPERATIONAL_STATES.has(this.state),
+      changed_at_ms: this.changedAt,
+      failure_code: this.failureCode,
+    };
+  }
+
+  transition(next) {
+    this.state = next;
+    this.changedAt = this.now();
+  }
+}

package/src/local/log.mjs

@@ -1,5 +1,6 @@
 import process from "node:process";
 import os from "node:os";
+import { errorCode } from "./errors.mjs";
 
 const COLORS = {
   reset: "\x1b[0m",
@@ -40,7 +41,8 @@ export function createLogger(options = {}) {
   const minimumLevel = normalizeLogLevel(options.level || (quiet ? "error" : verbose ? "debug" : "info"));
   const component = sanitizeLogText(options.component ? String(options.component) : "cli", 128);
   const useColor = shouldUseColor(options);
-  const stdout = options.stderrOnly ? process.stderr : process.stdout;
+  const stderr = options.stderr || process.stderr;
+  const stdout = options.stderrOnly ? stderr : (options.stdout || process.stdout);
 
   const write = (stream, level, label, color, message, fields) => {
     if (LEVEL_RANK[level] < LEVEL_RANK[minimumLevel]) return;
@@ -49,20 +51,50 @@ export function createLogger(options = {}) {
     stream.write(`${prefix} ${component}: ${sanitizeLogText(message, MAX_LOG_MESSAGE_CHARS)}${suffix}\n`);
   };
 
+  const event = (level, name, fields = {}, message = "") => {
+    const normalizedLevel = normalizeEventLevel(level);
+    const eventName = sanitizeEventName(name);
+    const payload = { event: eventName, ...fields };
+    const humanMessage = message || eventName;
+    if (options.format === "json") {
+      if (LEVEL_RANK[normalizedLevel] < LEVEL_RANK[minimumLevel]) return;
+      const entry = sanitizeLogValue({
+        timestamp: new Date().toISOString(),
+        level: normalizedLevel === "success" ? "info" : normalizedLevel,
+        component,
+        message: sanitizeLogText(humanMessage, MAX_LOG_MESSAGE_CHARS),
+        ...payload,
+      });
+      const target = normalizedLevel === "info" || normalizedLevel === "success" ? stdout : stderr;
+      target.write(`${JSON.stringify(entry)}\n`);
+      return;
+    }
+    const methods = {
+      debug: [stderr, "[debug]", COLORS.gray],
+      info: [stdout, "[info]", COLORS.blue],
+      success: [stdout, "[ok]", COLORS.green],
+      warn: [stderr, "[warn]", COLORS.yellow],
+      error: [stderr, "[error]", COLORS.red],
+    };
+    const [stream, label, color] = methods[normalizedLevel];
+    write(stream, normalizedLevel, label, color, humanMessage, payload);
+  };
+
   return {
     verbose: minimumLevel === "debug",
     level: minimumLevel,
     child(childComponent) {
       return createLogger({ ...options, component: childComponent });
     },
+    event,
     info(message, fields) { write(stdout, "info", "[info]", COLORS.blue, message, fields); },
     success(message, fields) { write(stdout, "success", "[ok]", COLORS.green, message, fields); },
-    warn(message, fields) { write(process.stderr, "warn", "[warn]", COLORS.yellow, message, fields); },
-    error(message, fields) { write(process.stderr, "error", "[error]", COLORS.red, message, fields); },
-    debug(message, fields) { write(process.stderr, "debug", "[debug]", COLORS.gray, message, fields); },
-    plain(message = "") { if (!quiet) process.stdout.write(`${String(message)}\n`); },
-    safePlain(message = "") { if (!quiet) process.stdout.write(`${sanitizeLogText(message, MAX_LOG_MESSAGE_CHARS)}\n`); },
-    json(value) { process.stdout.write(`${JSON.stringify(value, null, 2)}\n`); },
+    warn(message, fields) { write(stderr, "warn", "[warn]", COLORS.yellow, message, fields); },
+    error(message, fields) { write(stderr, "error", "[error]", COLORS.red, message, fields); },
+    debug(message, fields) { write(stderr, "debug", "[debug]", COLORS.gray, message, fields); },
+    plain(message = "") { if (!quiet) stdout.write(`${String(message)}\n`); },
+    safePlain(message = "") { if (!quiet) stdout.write(`${sanitizeLogText(message, MAX_LOG_MESSAGE_CHARS)}\n`); },
+    json(value) { stdout.write(`${JSON.stringify(value, null, 2)}\n`); },
   };
 }
 
@@ -76,18 +108,7 @@ export function normalizeLogLevel(value = "info") {
 
 
 export function classifyOperationalError(error) {
-  const message = error instanceof Error ? error.message : String(error ?? "");
-  if (/cancel/i.test(message)) return "cancelled";
-  if (/timed out/i.test(message)) return "timeout";
-  if (/unauthorized|forbidden|authentication|\b401\b|\b403\b/i.test(message)) return "authentication_failed";
-  if (/ECONNRESET|ECONNREFUSED|ETIMEDOUT|EHOSTUNREACH|ENETUNREACH|ENOTFOUND|EAI_AGAIN|socket hang up|network|websocket|TLS|SSL/i.test(message)) return "network_error";
-  if (/outside the configured workspace/i.test(message)) return "path_boundary";
-  if (/disabled|requires .* mode/i.test(message)) return "policy_denied";
-  if (/not found|ENOENT/i.test(message)) return "not_found";
-  if (/permission|EACCES|EPERM/i.test(message)) return "permission_denied";
-  if (/maximum|exceeds|max_bytes|too many/i.test(message)) return "limit_exceeded";
-  if (/invalid|must|requires|ambiguous|mismatch/i.test(message)) return "invalid_request";
-  return "execution_failed";
+  return errorCode(error);
 }
 
 export function formatFields(fields) {
@@ -162,3 +183,13 @@ function shouldUseColor(options) {
   if (options.color === true) return true;
   return Boolean(process.stderr.isTTY || process.stdout.isTTY);
 }
+
+function normalizeEventLevel(value) {
+  const level = String(value || "info").toLowerCase();
+  return Object.prototype.hasOwnProperty.call(LEVEL_RANK, level) ? level : "info";
+}
+
+function sanitizeEventName(value) {
+  const name = String(value || "event").toLowerCase().replace(/[^a-z0-9._-]/g, "_").slice(0, 128);
+  return name || "event";
+}

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

@@ -0,0 +1,235 @@
+import { createHash } from "node:crypto";
+import { lstatSync, realpathSync, statSync } from "node:fs";
+import { basename, isAbsolute, relative, resolve, sep } from "node:path";
+import { readBoundedRegularFileWithInfoSync } from "./secure-file.mjs";
+
+const RESOURCE_NAME = /^[a-z][a-z0-9._-]{0,63}$/;
+const RESOURCE_TOKEN = /\{\{resource:([a-z][a-z0-9._-]{0,63})\}\}/g;
+const MAX_RESOURCE_BYTES = 1024 * 1024;
+const MAX_JOB_RESOURCE_BYTES = 8 * 1024 * 1024;
+const MAX_RESOURCES = 64;
+const MAX_TEMPORARY_FILE_BYTES = 512 * 1024;
+
+export function validateResourceName(value) {
+  const name = String(value || "").trim();
+  if (!RESOURCE_NAME.test(name)) throw new Error("resource name must match [a-z][a-z0-9._-]{0,63}");
+  return name;
+}
+
+export function inspectResourceFile(inputPath, { allowInsecurePermissions = false, includeHash = false } = {}) {
+  const path = resolve(String(inputPath || ""));
+  const canonical = realpathFile(path);
+  const { buffer: content, info } = readBoundedRegularFileWithInfoSync(canonical, MAX_RESOURCE_BYTES);
+  if (process.platform !== "win32" && !allowInsecurePermissions && (info.mode & 0o077) !== 0) {
+    throw new Error("resource file is readable by group or others; restrict permissions or use --allow-insecure-permissions");
+  }
+  return {
+    kind: "file",
+    path: canonical,
+    pathAliases: normalizeResourcePathAliases([path, canonical]),
+    size: info.size,
+    mode: process.platform === "win32" ? null : `0${(info.mode & 0o777).toString(8)}`,
+    updatedAt: new Date().toISOString(),
+    allowInsecurePermissions: allowInsecurePermissions === true,
+    ...(includeHash ? { sha256: createHash("sha256").update(content).digest("hex") } : {}),
+  };
+}
+
+export function publicResourceRegistry(resources = {}, { includePaths = false } = {}) {
+  const normalized = normalizeResourceRegistry(resources);
+  return Object.fromEntries(Object.entries(normalized).map(([name, value]) => [name, {
+    kind: value.kind,
+    size: value.size ?? null,
+    mode: value.mode ?? null,
+    updatedAt: value.updatedAt ?? null,
+    allowInsecurePermissions: value.allowInsecurePermissions === true,
+    paths_exposed: includePaths,
+    ...(includePaths ? { path: value.path } : {}),
+  }]));
+}
+
+export function validatePlan(args, context) {
+  if (!args || typeof args !== "object" || Array.isArray(args)) throw new Error("job arguments must be an object");
+  const allowed = new Set(["name", "steps", "finally_steps", "temporary_files"]);
+  for (const key of Object.keys(args)) if (!allowed.has(key)) throw new Error(`job contains unknown field: ${key}`);
+  const name = String(args.name || "managed job").trim().slice(0, 128) || "managed job";
+  const steps = validateSteps(args.steps, "steps", context);
+  const finallySteps = validateSteps(args.finally_steps || [], "finally_steps", context, true);
+  const temporaryFiles = validateTemporaryFiles(args.temporary_files || []);
+  if (!steps.length) throw new Error("steps must contain at least one step");
+  return {
+    version: 1,
+    name,
+    workspace: context.workspace,
+    full_env: context.fullEnv,
+    resources: referencedResources([...steps, ...finallySteps], context.resources),
+    temporary_files: temporaryFiles,
+    steps,
+    finally_steps: finallySteps,
+  };
+}
+
+function validateTemporaryFiles(value) {
+  if (!Array.isArray(value) || value.length > 16) throw new Error("temporary_files must contain 0-16 files");
+  const seen = new Set();
+  let totalBytes = 0;
+  return value.map((item, index) => {
+    if (!item || typeof item !== "object" || Array.isArray(item)) throw new Error(`temporary_files[${index}] must be an object`);
+    for (const key of Object.keys(item)) if (!["name", "content", "executable"].includes(key)) throw new Error(`temporary_files[${index}] contains unknown field: ${key}`);
+    const name = validateResourceName(item.name);
+    if (seen.has(name)) throw new Error(`duplicate temporary file name: ${name}`);
+    seen.add(name);
+    const content = boundedString(item.content, 256 * 1024, `temporary_files[${index}].content`);
+    totalBytes += Buffer.byteLength(content);
+    if (totalBytes > MAX_TEMPORARY_FILE_BYTES) throw new Error(`temporary file contents exceed ${MAX_TEMPORARY_FILE_BYTES} bytes`);
+    return { name, content, executable: item.executable === true };
+  });
+}
+
+function validateSteps(value, label, context, allowEmpty = false) {
+  if (!Array.isArray(value) || (!allowEmpty && value.length === 0) || value.length > 16) {
+    throw new Error(`${label} must contain ${allowEmpty ? "0-16" : "1-16"} steps`);
+  }
+  return value.map((input, index) => {
+    if (!input || typeof input !== "object" || Array.isArray(input)) throw new Error(`${label}[${index}] must be an object`);
+    const allowed = new Set(["name", "argv", "cwd", "env", "env_resources", "stdin", "stdin_resource", "timeout_seconds", "allow_failure", "capture_output"]);
+    for (const key of Object.keys(input)) if (!allowed.has(key)) throw new Error(`${label}[${index}] contains unknown field: ${key}`);
+    if (!Array.isArray(input.argv) || !input.argv.length || input.argv.length > 256) throw new Error(`${label}[${index}].argv must contain 1-256 strings`);
+    const argv = input.argv.map((item) => boundedString(item, 16 * 1024, `${label}[${index}].argv`));
+    if (Buffer.byteLength(JSON.stringify(argv)) > 64 * 1024) throw new Error(`${label}[${index}].argv exceeds 64 KiB`);
+    const cwd = input.cwd === undefined ? context.workspace : resolveJobCwd(input.cwd, context.workspace, context.unrestrictedPaths);
+    const env = validateEnv(input.env, `${label}[${index}].env`);
+    const envResources = validateEnvResources(input.env_resources, `${label}[${index}].env_resources`);
+    for (const key of Object.keys(envResources)) if (Object.prototype.hasOwnProperty.call(env, key)) throw new Error(`${label}[${index}] duplicates ${key} in env and env_resources`);
+    const stdin = input.stdin === undefined ? null : boundedString(input.stdin, 256 * 1024, `${label}[${index}].stdin`);
+    const stdinResource = input.stdin_resource === undefined ? null : validateResourceName(input.stdin_resource);
+    if (stdin !== null && stdinResource !== null) throw new Error(`${label}[${index}] cannot combine stdin and stdin_resource`);
+    return {
+      name: String(input.name || basename(argv[0]) || `step ${index + 1}`).slice(0, 128),
+      argv,
+      cwd,
+      env,
+      env_resources: envResources,
+      stdin,
+      stdin_resource: stdinResource,
+      timeout_seconds: clampInt(input.timeout_seconds, 600, 1, 3600),
+      allow_failure: input.allow_failure === true,
+      capture_output: input.capture_output === "discard" ? "discard" : "redacted",
+    };
+  });
+}
+
+function validateEnv(value, label) {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  const entries = Object.entries(value);
+  if (entries.length > 64) throw new Error(`${label} has too many entries`);
+  const out = {};
+  for (const [key, raw] of entries) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)) throw new Error(`${label} contains invalid variable name: ${key}`);
+    out[key] = boundedString(raw, 16 * 1024, `${label}.${key}`);
+  }
+  return out;
+}
+
+function validateEnvResources(value, label) {
+  if (value === undefined) return {};
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${label} must be an object`);
+  const entries = Object.entries(value);
+  if (entries.length > 32) throw new Error(`${label} has too many entries`);
+  const out = {};
+  for (const [key, raw] of entries) {
+    if (!/^[A-Za-z_][A-Za-z0-9_]{0,127}$/.test(key)) throw new Error(`${label} contains invalid variable name: ${key}`);
+    out[key] = validateResourceName(raw);
+  }
+  return out;
+}
+
+function referencedResources(steps, registry) {
+  const names = new Set();
+  for (const step of steps) {
+    if (step.stdin_resource) names.add(step.stdin_resource);
+    for (const name of Object.values(step.env_resources || {})) names.add(name);
+    for (const value of [...step.argv, ...Object.values(step.env)]) {
+      for (const match of String(value).matchAll(RESOURCE_TOKEN)) names.add(match[1]);
+    }
+  }
+  if (names.size > MAX_RESOURCES) throw new Error(`job references more than ${MAX_RESOURCES} local resources`);
+  const out = {};
+  let totalBytes = 0;
+  for (const name of names) {
+    const resource = registry[name];
+    if (!resource) throw new Error(`unknown local resource: ${name}`);
+    const inspected = inspectResourceFile(resource.path, { allowInsecurePermissions: resource.allowInsecurePermissions === true, includeHash: true });
+    totalBytes += inspected.size;
+    if (totalBytes > MAX_JOB_RESOURCE_BYTES) throw new Error(`job resources exceed ${MAX_JOB_RESOURCE_BYTES} bytes`);
+    out[name] = {
+      ...inspected,
+      pathAliases: normalizeResourcePathAliases([...(resource.pathAliases || []), ...(inspected.pathAliases || [])]),
+      allowInsecurePermissions: resource.allowInsecurePermissions === true,
+    };
+  }
+  return out;
+}
+
+export function normalizeResourceRegistry(resources) {
+  const out = {};
+  if (!resources || typeof resources !== "object" || Array.isArray(resources)) return out;
+  for (const [rawName, rawValue] of Object.entries(resources).slice(0, MAX_RESOURCES)) {
+    const name = validateResourceName(rawName);
+    if (!rawValue || rawValue.kind !== "file" || typeof rawValue.path !== "string") continue;
+    out[name] = {
+      kind: "file",
+      path: resolve(rawValue.path),
+      pathAliases: normalizeResourcePathAliases([rawValue.path, ...(Array.isArray(rawValue.pathAliases) ? rawValue.pathAliases : [])]),
+      size: Number.isFinite(Number(rawValue.size)) ? Number(rawValue.size) : null,
+      mode: rawValue.mode ?? null,
+      updatedAt: rawValue.updatedAt ?? null,
+      allowInsecurePermissions: rawValue.allowInsecurePermissions === true,
+    };
+  }
+  return out;
+}
+
+function normalizeResourcePathAliases(values) {
+  const aliases = [];
+  for (const value of values) {
+    if (typeof value !== "string" || !value || value.includes("\0") || value.length > 4096) continue;
+    const absolute = resolve(value);
+    if (!aliases.includes(absolute)) aliases.push(absolute);
+    if (aliases.length >= 8) break;
+  }
+  return aliases;
+}
+
+function resolveJobCwd(value, workspace, unrestrictedPaths) {
+  const raw = boundedString(value, 4096, "cwd");
+  const candidate = isAbsolute(raw) ? resolve(raw) : resolve(workspace, raw);
+  const canonical = realpathSync.native ? realpathSync.native(candidate) : realpathSync(candidate);
+  const info = statSync(canonical);
+  if (!info.isDirectory()) throw new Error("managed job cwd is not a directory");
+  if (!unrestrictedPaths) {
+    const rel = relative(workspace, canonical);
+    if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) throw new Error("managed job cwd is outside the configured workspace");
+  }
+  return canonical;
+}
+
+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 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;
+}
+
+function clampInt(value, fallback, min, max) {
+  const parsed = Number.parseInt(String(value ?? ""), 10);
+  const number = Number.isFinite(parsed) ? parsed : fallback;
+  return Math.min(Math.max(number, min), max);
+}