@h-rig/runtime 0.0.6-alpha.0

package/dist/src/layout.js

@@ -0,0 +1,145 @@
+// @bun
+// packages/runtime/src/layout.ts
+import { existsSync } from "fs";
+import { basename, dirname, resolve } from "path";
+var RIG_DEFINITION_DIRNAME = "rig";
+var RIG_STATE_DIRNAME = ".rig";
+var RIG_ARTIFACTS_DIRNAME = "artifacts";
+function resolveNearestRigProjectRoot(startDir) {
+  let current = resolve(startDir);
+  let fallbackCandidate = null;
+  let projectCandidate = null;
+  for (;; ) {
+    const hasDefinition = existsSync(resolve(current, RIG_DEFINITION_DIRNAME));
+    const hasState = existsSync(resolve(current, RIG_STATE_DIRNAME));
+    const hasConfig = existsSync(resolve(current, "rig.config.ts")) || existsSync(resolve(current, "rig.config.json"));
+    const hasControlPlane = existsSync(resolve(current, "packages", "cli", "bin", "rig.ts")) || existsSync(resolve(current, "packages", "server"));
+    if (hasDefinition || hasState || hasConfig) {
+      fallbackCandidate = current;
+      if (hasControlPlane) {
+        projectCandidate = current;
+      }
+    }
+    const parent = resolve(current, "..");
+    if (parent === current) {
+      return projectCandidate ?? fallbackCandidate ?? resolve(startDir);
+    }
+    current = parent;
+  }
+}
+function resolveMonorepoRoot(projectRoot) {
+  const normalizedProjectRoot = resolve(projectRoot);
+  const explicit = process.env.MONOREPO_ROOT?.trim();
+  if (explicit) {
+    const explicitRoot = resolve(explicit);
+    const explicitParent = dirname(explicitRoot);
+    if (basename(explicitParent) === ".worktrees") {
+      const owner = dirname(explicitParent);
+      const ownerHasGit = existsSync(resolve(owner, ".git"));
+      const ownerHasTaskConfig = existsSync(resolve(owner, ".rig", "task-config.json"));
+      const ownerHasRigConfig = existsSync(resolve(owner, "rig.config.ts"));
+      if (ownerHasGit && (ownerHasTaskConfig || ownerHasRigConfig)) {
+        return owner;
+      }
+      throw new Error(`MONOREPO_ROOT points to worktree ${explicitRoot}, but the owner checkout is incomplete at ${owner}.`);
+    }
+    if (!existsSync(resolve(explicitRoot, ".git"))) {
+      throw new Error(`MONOREPO_ROOT points to ${explicitRoot}, but no git checkout was found there.`);
+    }
+    const hasTaskConfig = existsSync(resolve(explicitRoot, ".rig", "task-config.json"));
+    const hasRigConfig = existsSync(resolve(explicitRoot, "rig.config.ts"));
+    if (!hasTaskConfig && !hasRigConfig) {
+      throw new Error(`MONOREPO_ROOT points to ${explicitRoot}, but neither .rig/task-config.json nor rig.config.ts exists there.`);
+    }
+    return explicitRoot;
+  }
+  const projectParent = dirname(normalizedProjectRoot);
+  if (basename(projectParent) === ".worktrees") {
+    const worktreeOwner = dirname(projectParent);
+    const ownerHasGit = existsSync(resolve(worktreeOwner, ".git"));
+    const ownerHasTaskConfig = existsSync(resolve(worktreeOwner, ".rig", "task-config.json"));
+    const ownerHasRigConfig = existsSync(resolve(worktreeOwner, "rig.config.ts"));
+    if (ownerHasGit && (ownerHasTaskConfig || ownerHasRigConfig)) {
+      return worktreeOwner;
+    }
+  }
+  return normalizedProjectRoot;
+}
+function resolveRigDataRoot(projectRoot) {
+  return resolveMonorepoRoot(projectRoot);
+}
+function resolveRuntimeWorkspaceLayout(workspaceDir) {
+  const root = resolve(workspaceDir);
+  const rigRoot = resolve(root, ".rig");
+  const logsDir = resolve(rigRoot, "logs");
+  const stateDir = resolve(rigRoot, "state");
+  const runtimeDir = resolve(rigRoot, "runtime");
+  const binDir = resolve(rigRoot, "bin");
+  return {
+    workspaceDir: root,
+    rigRoot,
+    stateDir,
+    logsDir,
+    artifactsRoot: resolve(root, RIG_ARTIFACTS_DIRNAME),
+    runtimeDir,
+    homeDir: resolve(rigRoot, "home"),
+    tmpDir: resolve(rigRoot, "tmp"),
+    cacheDir: resolve(rigRoot, "cache"),
+    sessionDir: resolve(rigRoot, "session"),
+    binDir,
+    distDir: resolve(rigRoot, "dist"),
+    pluginBinDir: resolve(binDir, "plugins"),
+    contextPath: resolve(rigRoot, "runtime-context.json"),
+    controlPlaneEventsFile: resolve(logsDir, "control-plane.events.jsonl")
+  };
+}
+function resolveActiveRuntimeWorkspaceRoot(monorepoRoot) {
+  const explicit = process.env.RIG_TASK_WORKSPACE?.trim();
+  if (!explicit) {
+    throw new Error("No active runtime workspace. Set RIG_TASK_WORKSPACE or provision a task runtime first.");
+  }
+  return resolve(explicit);
+}
+function resolveRigLayout(projectRoot) {
+  const monorepoRoot = resolveMonorepoRoot(projectRoot);
+  const definitionRoot = resolve(projectRoot, RIG_DEFINITION_DIRNAME);
+  const runtimeWorkspaceRoot = resolveActiveRuntimeWorkspaceRoot(monorepoRoot);
+  const runtimeLayout = resolveRuntimeWorkspaceLayout(runtimeWorkspaceRoot);
+  const policyDir = resolve(definitionRoot, "policy");
+  return {
+    projectRoot,
+    monorepoRoot,
+    definitionRoot,
+    runtimeWorkspaceRoot,
+    stateRoot: runtimeLayout.rigRoot,
+    artifactsRoot: runtimeLayout.artifactsRoot,
+    configPath: resolve(definitionRoot, "config.sh"),
+    taskConfigPath: resolve(runtimeWorkspaceRoot, ".rig", "task-config.json"),
+    policyDir,
+    policyFile: resolve(policyDir, "policy.json"),
+    pluginsDir: resolve(definitionRoot, "plugins"),
+    hooksDir: resolve(definitionRoot, "hooks"),
+    toolsDir: resolve(definitionRoot, "tools"),
+    templatesDir: resolve(definitionRoot, "templates"),
+    validationDir: resolve(definitionRoot, "validation"),
+    stateDir: runtimeLayout.stateDir,
+    logsDir: runtimeLayout.logsDir,
+    notificationsDir: resolve(definitionRoot, "notifications"),
+    runtimeDir: runtimeLayout.runtimeDir,
+    distDir: runtimeLayout.distDir,
+    binDir: runtimeLayout.binDir,
+    pluginBinDir: runtimeLayout.pluginBinDir,
+    keybindingsPath: resolve(definitionRoot, "keybindings.json"),
+    controlPlaneEventsFile: runtimeLayout.controlPlaneEventsFile
+  };
+}
+export {
+  resolveRuntimeWorkspaceLayout,
+  resolveRigLayout,
+  resolveRigDataRoot,
+  resolveNearestRigProjectRoot,
+  resolveMonorepoRoot,
+  RIG_STATE_DIRNAME,
+  RIG_DEFINITION_DIRNAME,
+  RIG_ARTIFACTS_DIRNAME
+};

package/dist/src/local-server.js

@@ -0,0 +1,202 @@
+// @bun
+// packages/runtime/src/local-server.ts
+import { spawn } from "child_process";
+import { closeSync, existsSync as existsSync2, mkdirSync, openSync, readFileSync, unlinkSync } from "fs";
+import { resolve as resolve2 } from "path";
+
+// packages/runtime/src/layout.ts
+import { existsSync } from "fs";
+import { basename, dirname, resolve } from "path";
+function resolveMonorepoRoot(projectRoot) {
+  const normalizedProjectRoot = resolve(projectRoot);
+  const explicit = process.env.MONOREPO_ROOT?.trim();
+  if (explicit) {
+    const explicitRoot = resolve(explicit);
+    const explicitParent = dirname(explicitRoot);
+    if (basename(explicitParent) === ".worktrees") {
+      const owner = dirname(explicitParent);
+      const ownerHasGit = existsSync(resolve(owner, ".git"));
+      const ownerHasTaskConfig = existsSync(resolve(owner, ".rig", "task-config.json"));
+      const ownerHasRigConfig = existsSync(resolve(owner, "rig.config.ts"));
+      if (ownerHasGit && (ownerHasTaskConfig || ownerHasRigConfig)) {
+        return owner;
+      }
+      throw new Error(`MONOREPO_ROOT points to worktree ${explicitRoot}, but the owner checkout is incomplete at ${owner}.`);
+    }
+    if (!existsSync(resolve(explicitRoot, ".git"))) {
+      throw new Error(`MONOREPO_ROOT points to ${explicitRoot}, but no git checkout was found there.`);
+    }
+    const hasTaskConfig = existsSync(resolve(explicitRoot, ".rig", "task-config.json"));
+    const hasRigConfig = existsSync(resolve(explicitRoot, "rig.config.ts"));
+    if (!hasTaskConfig && !hasRigConfig) {
+      throw new Error(`MONOREPO_ROOT points to ${explicitRoot}, but neither .rig/task-config.json nor rig.config.ts exists there.`);
+    }
+    return explicitRoot;
+  }
+  const projectParent = dirname(normalizedProjectRoot);
+  if (basename(projectParent) === ".worktrees") {
+    const worktreeOwner = dirname(projectParent);
+    const ownerHasGit = existsSync(resolve(worktreeOwner, ".git"));
+    const ownerHasTaskConfig = existsSync(resolve(worktreeOwner, ".rig", "task-config.json"));
+    const ownerHasRigConfig = existsSync(resolve(worktreeOwner, "rig.config.ts"));
+    if (ownerHasGit && (ownerHasTaskConfig || ownerHasRigConfig)) {
+      return worktreeOwner;
+    }
+  }
+  return normalizedProjectRoot;
+}
+
+// packages/runtime/src/local-server.ts
+function parsePublishedRigServerState(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return null;
+  }
+  const candidate = value;
+  if (typeof candidate.pid !== "number" || !Number.isInteger(candidate.pid) || candidate.pid <= 0 || typeof candidate.host !== "string" || candidate.host.trim().length === 0 || typeof candidate.port !== "number" || !Number.isInteger(candidate.port) || candidate.port < 1 || candidate.port > 65535 || candidate.authToken !== null && candidate.authToken !== undefined && typeof candidate.authToken !== "string" || typeof candidate.startedAt !== "string" || candidate.startedAt.trim().length === 0) {
+    return null;
+  }
+  return {
+    pid: candidate.pid,
+    host: candidate.host,
+    port: candidate.port,
+    authToken: candidate.authToken ?? null,
+    startedAt: candidate.startedAt
+  };
+}
+function resolveRigServerLogPath(projectRoot) {
+  return resolve2(resolveRigServerPaths(projectRoot).logsDir, "rig-server.bootstrap.log");
+}
+function resolvePublishedRigServerStatePath(projectRoot) {
+  return resolve2(resolveRigServerPaths(projectRoot).stateDir, "rig-server.json");
+}
+function resolveRigServerPaths(projectRoot) {
+  const taskWorkspace = process.env.RIG_TASK_WORKSPACE?.trim();
+  const explicitStateDir = process.env.RIG_STATE_DIR?.trim();
+  const explicitLogsDir = process.env.RIG_LOGS_DIR?.trim();
+  const explicitSessionFile = process.env.RIG_SESSION_FILE?.trim();
+  const hostStateRoot = resolve2(projectRoot, ".rig");
+  const monorepoStateRoot = resolve2(resolveMonorepoRoot(projectRoot), ".rig");
+  const stateRoot = taskWorkspace ? resolve2(taskWorkspace, ".rig") : explicitStateDir ? resolve2(explicitStateDir, "..") : explicitLogsDir ? resolve2(explicitLogsDir, "..") : explicitSessionFile ? resolve2(explicitSessionFile, "..", "..") : existsSync2(hostStateRoot) ? hostStateRoot : monorepoStateRoot;
+  return {
+    stateDir: explicitStateDir ? resolve2(explicitStateDir) : resolve2(stateRoot, "state"),
+    logsDir: explicitLogsDir ? resolve2(explicitLogsDir) : resolve2(stateRoot, "logs")
+  };
+}
+async function readPublishedRigServerState(projectRoot) {
+  return readPublishedRigServerStateSync(projectRoot);
+}
+function readPublishedRigServerStateSync(projectRoot) {
+  const filePath = resolvePublishedRigServerStatePath(projectRoot);
+  if (!existsSync2(filePath)) {
+    return null;
+  }
+  try {
+    const rawState = readFileSync(filePath, "utf8");
+    return parsePublishedRigServerState(JSON.parse(rawState));
+  } catch {
+    return null;
+  }
+}
+function clearPublishedRigServerState(projectRoot) {
+  const filePath = resolvePublishedRigServerStatePath(projectRoot);
+  try {
+    unlinkSync(filePath);
+  } catch {}
+}
+function toLocalServerConnection(published) {
+  const baseUrl = `http://${published.host}:${published.port}`;
+  const wsUrl = new URL(`ws://${published.host}:${published.port}`);
+  if (published.authToken) {
+    wsUrl.searchParams.set("token", published.authToken);
+  }
+  return {
+    baseUrl,
+    wsUrl: wsUrl.toString(),
+    host: published.host,
+    port: published.port,
+    authToken: published.authToken
+  };
+}
+async function waitForServerHealthy(baseUrl, authToken, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  const healthUrl = new URL(`${baseUrl}/health`);
+  if (authToken !== null) {
+    healthUrl.searchParams.set("token", authToken);
+  }
+  while (Date.now() < deadline) {
+    try {
+      const response = await fetch(healthUrl.toString());
+      if (response.ok) {
+        return true;
+      }
+    } catch {}
+    await Bun.sleep(150);
+  }
+  return false;
+}
+async function waitForPublishedServer(projectRoot, authToken, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const published = await readPublishedRigServerState(projectRoot);
+    if (published && published.authToken === authToken) {
+      const connection = toLocalServerConnection(published);
+      if (await waitForServerHealthy(connection.baseUrl, connection.authToken, 500)) {
+        return published;
+      }
+    }
+    await Bun.sleep(250);
+  }
+  return null;
+}
+async function ensureLocalRigServerConnection(projectRoot, options = {}) {
+  const published = await readPublishedRigServerState(projectRoot);
+  if (published) {
+    const connection = toLocalServerConnection(published);
+    if (await waitForServerHealthy(connection.baseUrl, connection.authToken, 1500)) {
+      return connection;
+    }
+  }
+  const host = options.host ?? "127.0.0.1";
+  const startupTimeoutMs = options.startupTimeoutMs ?? 15000;
+  const authToken = Buffer.from(crypto.getRandomValues(new Uint8Array(24))).toString("hex");
+  const workspaceRoot = resolve2(import.meta.dir, "../../..");
+  const bootstrapLogPath = resolveRigServerLogPath(projectRoot);
+  mkdirSync(resolveRigServerPaths(projectRoot).logsDir, { recursive: true });
+  const bootstrapLogFd = openSync(bootstrapLogPath, "w");
+  clearPublishedRigServerState(projectRoot);
+  const child = spawn("bun", [
+    "run",
+    "packages/server/src/server.ts",
+    "start",
+    "--host",
+    host,
+    "--port",
+    "0",
+    "--auth-token",
+    authToken
+  ], {
+    cwd: workspaceRoot,
+    env: {
+      ...process.env,
+      PROJECT_RIG_ROOT: projectRoot
+    },
+    detached: true,
+    stdio: ["ignore", bootstrapLogFd, bootstrapLogFd]
+  });
+  closeSync(bootstrapLogFd);
+  child.unref();
+  const ready = await waitForPublishedServer(projectRoot, authToken, startupTimeoutMs);
+  if (!ready) {
+    child.kill();
+    const bootstrapLog = existsSync2(bootstrapLogPath) ? readFileSync(bootstrapLogPath, "utf8").trim() : "";
+    const diagnostics = bootstrapLog ? ` Startup log (${bootstrapLogPath}):
+${bootstrapLog}` : ` No bootstrap log was written.`;
+    throw new Error(`Timed out waiting for the local Rig server to start.${diagnostics}`);
+  }
+  return toLocalServerConnection(ready);
+}
+export {
+  readPublishedRigServerStateSync,
+  readPublishedRigServerState,
+  ensureLocalRigServerConnection
+};

package/dist/src/plugins.js

@@ -0,0 +1,329 @@
+// @bun
+// packages/runtime/src/plugins.ts
+import { existsSync, readdirSync } from "fs";
+import { basename, resolve } from "path";
+
+// packages/runtime/src/binary-run.ts
+import { spawn as nodeSpawn } from "child_process";
+var runtimeBinaryBuildQueue = Promise.resolve();
+async function launchRuntimeBinary(request) {
+  const options = {
+    cwd: request.cwd,
+    env: request.env ? { ...process.env, ...request.env } : process.env
+  };
+  if (request.timeoutMs !== undefined) {
+    options.timeoutMs = request.timeoutMs;
+  }
+  return spawnProcess(request.binaryPath, request.args, options);
+}
+async function spawnProcess(command, args, options) {
+  const child = nodeSpawn(command, args, {
+    cwd: options.cwd,
+    env: options.env,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  let stdout = "";
+  let stderr = "";
+  child.stdout?.setEncoding("utf8");
+  child.stderr?.setEncoding("utf8");
+  child.stdout?.on("data", (chunk) => {
+    stdout += chunk;
+  });
+  child.stderr?.on("data", (chunk) => {
+    stderr += chunk;
+  });
+  let timedOut = false;
+  let timer;
+  const exitCode = await new Promise((resolveExit, rejectExit) => {
+    if (options.timeoutMs && options.timeoutMs > 0) {
+      timer = setTimeout(() => {
+        timedOut = true;
+        child.kill();
+      }, options.timeoutMs);
+    }
+    child.once("error", rejectExit);
+    child.once("close", (code) => resolveExit(code ?? (timedOut ? 1 : 0)));
+  }).finally(() => {
+    if (timer) {
+      clearTimeout(timer);
+    }
+  });
+  return { exitCode, stdout, stderr, timedOut };
+}
+
+// packages/runtime/src/control-plane/runtime/plugin-mode.ts
+var LEGACY_PLUGIN_SCAN_ENV = "RIG_LEGACY_PLUGIN_SCAN";
+function isLegacyPluginScanEnabled(env = process.env) {
+  const value = env[LEGACY_PLUGIN_SCAN_ENV]?.trim().toLowerCase();
+  return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+
+// packages/runtime/src/plugins.ts
+var runtimeHookPhases = ["beforeCommand", "afterCommand", "onEvent"];
+var PLUGIN_SOURCE_PATTERN = /\.plugin\.(ts|js|mjs|cjs)$/;
+function inferRuntimePluginName(fileName) {
+  return fileName.replace(PLUGIN_SOURCE_PATTERN, "");
+}
+function describeRuntimePluginFiles(filePaths) {
+  return filePaths.filter((filePath) => PLUGIN_SOURCE_PATTERN.test(filePath)).map((filePath) => {
+    const fileName = filePath.split(/[\\/]/).at(-1) ?? filePath;
+    const name = inferRuntimePluginName(fileName);
+    return { name, sourcePath: filePath, binaryName: name };
+  });
+}
+
+class PluginManager {
+  eventBus;
+  context;
+  pluginDir;
+  pluginFiles;
+  pluginNames;
+  localBinDir;
+  imageBinDir;
+  pluginsRequireBinaries;
+  ensureImageBinDir;
+  plugins = null;
+  loadPromise = null;
+  constructor(options) {
+    this.eventBus = options.eventBus;
+    this.context = options.context;
+    this.pluginDir = options.pluginDir;
+    this.pluginFiles = options.pluginFiles;
+    this.pluginNames = options.pluginNames;
+    this.localBinDir = options.localBinDir;
+    this.imageBinDir = options.imageBinDir;
+    this.pluginsRequireBinaries = options.pluginsRequireBinaries;
+    this.ensureImageBinDir = options.ensureImageBinDir;
+  }
+  static async load(options) {
+    const pluginDir = options.pluginDir ?? resolve(options.projectRoot, "rig", "plugins");
+    const localBinDir = options.localBinDir ?? resolve(options.projectRoot, "rig", "plugins");
+    const imageBinDir = options.imageBinDir ?? (options.runtimeContext ? resolve(options.runtimeContext.binDir, "plugins") : "");
+    const legacyPluginScan = options.legacyPluginScan ?? isLegacyPluginScanEnabled(options.env);
+    const pluginFiles = legacyPluginScan ? safeReadDir(pluginDir).filter((entry) => PLUGIN_SOURCE_PATTERN.test(entry)) : [];
+    const pluginNames = pluginFiles.map((file) => inferRuntimePluginName(basename(file)));
+    const context = {
+      projectRoot: options.projectRoot,
+      runId: options.runId,
+      eventBus: options.eventBus
+    };
+    return new PluginManager({
+      eventBus: options.eventBus,
+      context,
+      pluginDir,
+      pluginFiles,
+      pluginNames,
+      localBinDir,
+      imageBinDir,
+      pluginsRequireBinaries: options.pluginsRequireBinaries ?? true,
+      ensureImageBinDir: options.ensureImageBinDir
+    });
+  }
+  list() {
+    if (this.plugins) {
+      return this.plugins.map((plugin) => ({
+        name: plugin.name,
+        validators: plugin.validators?.map((validator) => validator.id) ?? []
+      }));
+    }
+    return this.pluginNames.map((name) => ({ name, validators: [] }));
+  }
+  async beforeCommand(ctx) {
+    const plugins = await this.ensureLoaded();
+    for (const plugin of plugins) {
+      if (!plugin.beforeCommand)
+        continue;
+      await this.safeInvoke(plugin.name, "beforeCommand", () => plugin.beforeCommand?.(ctx, this.context));
+    }
+  }
+  async afterCommand(result) {
+    const plugins = await this.ensureLoaded();
+    for (const plugin of plugins) {
+      if (!plugin.afterCommand)
+        continue;
+      await this.safeInvoke(plugin.name, "afterCommand", () => plugin.afterCommand?.(result, this.context));
+    }
+  }
+  async onEvent(event) {
+    const plugins = this.plugins;
+    if (!plugins)
+      return;
+    for (const plugin of plugins) {
+      if (!plugin.onEvent)
+        continue;
+      await this.safeInvoke(plugin.name, "onEvent", () => plugin.onEvent?.(event, this.context));
+    }
+  }
+  async runValidators(taskId) {
+    const plugins = await this.ensureLoaded();
+    const results = [];
+    for (const plugin of plugins) {
+      for (const validator of plugin.validators ?? []) {
+        await this.eventBus.emit("validator.started", {
+          plugin: plugin.name,
+          validator: validator.id,
+          taskId
+        });
+        try {
+          const result = await validator.run({ taskId, projectRoot: this.context.projectRoot }, this.context);
+          results.push(result);
+          await this.eventBus.emit("validator.finished", {
+            plugin: plugin.name,
+            validator: validator.id,
+            taskId,
+            passed: result.passed,
+            summary: result.summary
+          });
+        } catch (error) {
+          const failed = {
+            id: validator.id,
+            passed: false,
+            summary: `${plugin.name}/${validator.id} failed unexpectedly`,
+            details: `${error}`
+          };
+          results.push(failed);
+          await this.eventBus.emit("validator.finished", {
+            plugin: plugin.name,
+            validator: validator.id,
+            taskId,
+            passed: false,
+            summary: failed.summary,
+            details: failed.details
+          });
+        }
+      }
+    }
+    return results;
+  }
+  async ensureLoaded() {
+    if (this.plugins)
+      return this.plugins;
+    if (this.loadPromise)
+      return this.loadPromise;
+    this.loadPromise = this.loadCompiledPlugins();
+    try {
+      this.plugins = await this.loadPromise;
+      return this.plugins;
+    } finally {
+      this.loadPromise = null;
+    }
+  }
+  resolveBinPath(binName) {
+    const candidates = [this.imageBinDir, this.localBinDir].filter(Boolean).map((dir) => resolve(dir, binName));
+    return candidates.find((candidate) => existsSync(candidate));
+  }
+  async loadCompiledPlugins() {
+    const plugins = [];
+    for (const file of this.pluginFiles) {
+      const binName = inferRuntimePluginName(basename(file));
+      let binPath = this.resolveBinPath(binName);
+      if (!binPath && !this.imageBinDir && this.pluginsRequireBinaries && this.ensureImageBinDir) {
+        try {
+          this.imageBinDir = await this.ensureImageBinDir(this.context.projectRoot);
+          binPath = this.resolveBinPath(binName);
+        } catch {}
+      }
+      if (!binPath) {
+        const triedPaths = [this.imageBinDir, this.localBinDir].filter(Boolean).map((dir) => resolve(dir, binName));
+        const missingError = `Compiled plugin binary not found for '${binName}'. Tried: ${triedPaths.join(", ")}`;
+        await this.eventBus.emit("plugin.error", {
+          file: resolve(this.pluginDir, file),
+          phase: "load",
+          error: missingError
+        });
+        if (this.pluginsRequireBinaries) {
+          throw new Error(missingError);
+        }
+        plugins.push({ name: binName, validators: [] });
+        await this.eventBus.emit("plugin.loaded", {
+          plugin: binName,
+          file: resolve(this.pluginDir, file),
+          source: "metadata-only"
+        });
+        continue;
+      }
+      const wrapper = createBinaryPluginWrapper(binName, binPath, this.context.projectRoot);
+      plugins.push(wrapper);
+      await this.eventBus.emit("plugin.loaded", {
+        plugin: wrapper.name,
+        file: binPath,
+        source: "compiled-binary"
+      });
+    }
+    return plugins;
+  }
+  async safeInvoke(pluginName, hook, call) {
+    try {
+      await call();
+    } catch (error) {
+      await this.eventBus.emit("plugin.error", {
+        plugin: pluginName,
+        phase: hook,
+        error: `${error}`
+      });
+    }
+  }
+}
+function createBinaryPluginWrapper(name, binPath, projectRoot) {
+  return {
+    name,
+    validators: [
+      {
+        id: `${name}:compiled`,
+        async run(ctx) {
+          const { exitCode, stdout, stderr } = await launchRuntimeBinary({
+            binaryPath: binPath,
+            args: ["--validate", ctx.taskId, ctx.projectRoot],
+            cwd: projectRoot
+          });
+          if (exitCode !== 0) {
+            return {
+              id: `${name}:compiled`,
+              passed: false,
+              summary: `Plugin binary ${name} exited with code ${exitCode}`,
+              details: stderr || stdout
+            };
+          }
+          try {
+            const results = JSON.parse(stdout.trim());
+            const failed = results.filter((result) => !result.passed);
+            if (failed.length > 0) {
+              return {
+                id: `${name}:compiled`,
+                passed: false,
+                summary: `${failed.length} of ${results.length} validator(s) failed`,
+                details: failed.map((result) => `${result.id}: ${result.summary}`).join(`
+`)
+              };
+            }
+            return {
+              id: `${name}:compiled`,
+              passed: true,
+              summary: `All ${results.length} validator(s) passed`
+            };
+          } catch {
+            return {
+              id: `${name}:compiled`,
+              passed: false,
+              summary: `Failed to parse output from compiled plugin ${name}`,
+              details: stdout.slice(0, 500)
+            };
+          }
+        }
+      }
+    ]
+  };
+}
+function safeReadDir(path) {
+  try {
+    return readdirSync(path, { withFileTypes: true }).filter((entry) => entry.isFile()).map((entry) => entry.name).sort();
+  } catch {
+    return [];
+  }
+}
+export {
+  runtimeHookPhases,
+  inferRuntimePluginName,
+  describeRuntimePluginFiles,
+  PluginManager
+};