@ory/argus 0.14.0 → 1.0.1

package/dist/runtime.js

@@ -0,0 +1,825 @@
+"use strict";
+/**
+ * The plugin **runtime store**: resolve which code a harness runs *once*, at
+ * install time, instead of re-resolving an npm package spec on every hook
+ * invocation.
+ *
+ * Historically every harness plugin wrote its runtime hook command as a
+ * version-pinned npx spec (`npx -y -p @ory/<pkg>@<ver> ory-<h>-hook`). That
+ * froze the *resolution strategy* into each harness's config file: which code
+ * runs was decided by npm on every `PreToolUse`, forever — one `npm exec`
+ * resolution per tool call, dependent on network and npm cache state, and
+ * untestable locally without publishing to a registry first.
+ *
+ * This module replaces that with three artifacts:
+ *
+ *   1. **A runtime store** at `<dataDir>/runtime/<version>/`, an npm prefix
+ *      holding the plugin package and its dependency closure. Populated by a
+ *      single `npm install --prefix` at install time — the only package
+ *      resolution that ever happens. Several harnesses installed at the same
+ *      version share one store directory.
+ *   2. **A stable entry shim** per harness at
+ *      `<dataDir>/bin/ory-hook-<harness>.js` (and one for the MCP server).
+ *      Harness configs reference the *shim*, whose path never changes across
+ *      upgrades — so changing the runtime, or the resolution policy itself,
+ *      rewrites one small file instead of N harness config formats.
+ *   3. **A manifest** at `<dataDir>/runtime/manifest.json` recording what is
+ *      wired where, so `status` can report the runtime a harness will actually
+ *      load, upgrades can rewire, and unreferenced stores can be pruned.
+ *
+ * A **linked** runtime (`linkedRuntime`) points the shim straight at a
+ * workspace build instead of a materialized store. That is the development
+ * loop: `pnpm build` + relaunch, with no publish, no version bump, and no
+ * registry involved.
+ *
+ * ## The shim must fail open
+ *
+ * The shim is not an indirection for its own sake: it is the only place that
+ * can degrade gracefully. If the runtime store is missing — a wiped config
+ * dir, a half-finished upgrade, dotfiles synced to a new machine — a raw
+ * `node "<store>/…/hook.js"` command would exit non-zero, and a harness that
+ * treats an unanswered gate as a block (Cursor registers `preToolUse` with
+ * `failClosed: true`) would then block *every* tool call. So the generated
+ * hook shim catches an unloadable runtime, explains itself on stderr, and
+ * exits 0 with the harness's pass-through response. The MCP shim does the
+ * opposite and exits non-zero: an MCP server that cannot start gates nothing,
+ * and a silent no-op server is harder to diagnose than a loud failure.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultNpmInstaller = exports.MCP_SERVER_PACKAGE = void 0;
+exports.getRuntimeRoot = getRuntimeRoot;
+exports.getRuntimeStoreDir = getRuntimeStoreDir;
+exports.getShimDir = getShimDir;
+exports.getHookShimPath = getHookShimPath;
+exports.getMcpShimPath = getMcpShimPath;
+exports.sanitizeNpmEnv = sanitizeNpmEnv;
+exports.materializeRuntime = materializeRuntime;
+exports.linkedRuntime = linkedRuntime;
+exports.resolveRuntimeEntry = resolveRuntimeEntry;
+exports.resolveMcpRuntimeEntry = resolveMcpRuntimeEntry;
+exports.hookShimBody = hookShimBody;
+exports.writeHookShim = writeHookShim;
+exports.writeMcpShim = writeMcpShim;
+exports.hookCommand = hookCommand;
+exports.isOryRuntimeCommand = isOryRuntimeCommand;
+exports.mcpCommand = mcpCommand;
+exports.moduleSpecifier = moduleSpecifier;
+exports.readRuntimeManifest = readRuntimeManifest;
+exports.recordRuntimeWiring = recordRuntimeWiring;
+exports.getRuntimeWiring = getRuntimeWiring;
+exports.removeRuntimeWiring = removeRuntimeWiring;
+exports.pruneRuntimeStores = pruneRuntimeStores;
+exports.resolveRuntimeForInstall = resolveRuntimeForInstall;
+exports.requireHookCommand = requireHookCommand;
+exports.withRuntimeInstallLock = withRuntimeInstallLock;
+exports.wireRuntime = wireRuntime;
+exports.checkRuntimeHealth = checkRuntimeHealth;
+exports.describeRuntimeHealth = describeRuntimeHealth;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const node_child_process_1 = require("node:child_process");
+const node_crypto_1 = require("node:crypto");
+const config_js_1 = require("./config.js");
+// ─── Paths ─────────────────────────────────────────────────────────
+/** Root of the runtime store: `<dataDir>/runtime`. */
+function getRuntimeRoot() {
+    return path.join((0, config_js_1.getDataDir)(), "runtime");
+}
+/** Store directory for one version: `<dataDir>/runtime/<version>`. */
+function getRuntimeStoreDir(version) {
+    return path.join(getRuntimeRoot(), version);
+}
+function getRuntimeInstallLockPath() {
+    return path.join(getRuntimeRoot(), ".install.lock");
+}
+/** Directory holding the generated entry shims: `<dataDir>/bin`. */
+function getShimDir() {
+    return path.join((0, config_js_1.getDataDir)(), "bin");
+}
+/** Stable hook-shim path for a harness. Never changes across upgrades. */
+function getHookShimPath(harness) {
+    return path.join(getShimDir(), `ory-hook-${harness}.js`);
+}
+/** Stable MCP-server shim path. Shared by every harness. */
+function getMcpShimPath() {
+    return path.join(getShimDir(), "ory-mcp-server.js");
+}
+function getManifestPath() {
+    return path.join(getRuntimeRoot(), "manifest.json");
+}
+// ─── Runtime targets ───────────────────────────────────────────────
+/** The npm package providing the MCP server, materialized alongside plugins. */
+exports.MCP_SERVER_PACKAGE = "@ory/mcp-server";
+/** Read a package version from a package directory, if present. */
+function readPackageVersion(packageDir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(packageDir, "package.json"), "utf-8"));
+        return typeof parsed.version === "string" ? parsed.version : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Default installer: one `npm install --prefix <store> <spec>…`.
+ *
+ * `--prefix` keeps the install entirely inside the store directory (npm
+ * creates `<store>/node_modules` and, if absent, a minimal `package.json`),
+ * and `--no-save` keeps it from rewriting a manifest we do not own. The
+ * user's own npm configuration — registry, auth, proxy — applies, which is
+ * the point: this is the *one* resolution, done with the user's settings, at
+ * a moment where a failure is visible and actionable.
+ */
+const defaultNpmInstaller = ({ prefix, specs }) => {
+    const result = (0, node_child_process_1.spawnSync)("npm", [
+        "install",
+        "--prefix",
+        prefix,
+        ...specs,
+        "--no-audit",
+        "--no-fund",
+        "--no-save",
+        "--loglevel=error",
+    ], {
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+        env: sanitizeNpmEnv(process.env),
+    });
+    const output = ((result.stdout ?? "") + (result.stderr ?? "")).trim();
+    return { ok: !result.error && result.status === 0, output };
+};
+exports.defaultNpmInstaller = defaultNpmInstaller;
+/**
+ * When this install runs from inside an `npx`/`npm exec` wrapper (the
+ * documented `npx -p @ory/<harness> ory-<harness> install` entry point), the
+ * outer npm resolves the user's config and *projects it into the environment*
+ * as `npm_config_*` vars for child processes. Our inner `npm install <spec>…`
+ * inherits those — which is how the user's registry/proxy/`min-release-age`
+ * reach the store install, so we keep them.
+ *
+ * The one exception is `allow-scripts`: npm ≥ 11.6 rejects an env/CLI-level
+ * `allow-scripts` in a project-scoped install (`EALLOWSCRIPTS`), because that
+ * source is meant for one-off/global contexts. A user with
+ * `allow-scripts=…` in `~/.npmrc` (an increasingly common supply-chain
+ * hardening) would otherwise be unable to install the runtime at all. Dropping
+ * only the projected env var lets the child re-read the same setting from the
+ * `.npmrc` cascade (user/global level, which *is* permitted here), so packages
+ * that legitimately need a build step — e.g. `tree-sitter-bash` for shell
+ * decomposition — still get it.
+ */
+function sanitizeNpmEnv(env) {
+    const cleaned = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (/^npm_config_allow[-_]scripts$/i.test(key)) {
+            continue;
+        }
+        cleaned[key] = value;
+    }
+    return cleaned;
+}
+/**
+ * Materialize a runtime into the store and return it.
+ *
+ * The MCP server is installed into the same prefix by default: it is fetched
+ * by the harness at runtime in exactly the same way the hook was, so it needs
+ * the same treatment for the registry to drop out of the runtime path
+ * entirely.
+ *
+ * Throws when the install fails or the expected package directory is absent
+ * afterwards — an install that cannot materialize its runtime must say so
+ * rather than write a shim pointing at nothing.
+ */
+function materializeRuntime(opts) {
+    const { packageName, version } = opts;
+    const storeDir = getRuntimeStoreDir(version);
+    fs.mkdirSync(storeDir, { recursive: true });
+    const extras = opts.extraPackages ?? [`${exports.MCP_SERVER_PACKAGE}@${version}`];
+    // npm --no-save prunes packages omitted from a later install into the same
+    // prefix. Reinstall every runtime already wired to this shared store so
+    // adding one harness cannot remove another harness's package.
+    const retained = Object.values(readRuntimeManifest().harnesses)
+        .filter((wiring) => wiring.storeDir &&
+        path.resolve(wiring.storeDir) === path.resolve(storeDir))
+        .map((wiring) => `${wiring.packageName}@${wiring.version}`);
+    const specs = [
+        ...new Set([`${packageName}@${version}`, ...retained, ...extras]),
+    ];
+    const installer = opts.installer ?? exports.defaultNpmInstaller;
+    const result = installer({ prefix: storeDir, specs });
+    if (!result.ok) {
+        throw new Error(`Failed to materialize the Ory runtime into ${storeDir}.\n` +
+            `  npm install ${specs.join(" ")}\n` +
+            (result.output ? `  ${result.output}\n` : ""));
+    }
+    const packageDir = path.join(storeDir, "node_modules", packageName);
+    const resolvedVersion = readPackageVersion(packageDir);
+    if (!resolvedVersion) {
+        throw new Error(`The Ory runtime install reported success but ${packageDir} is missing or ` +
+            `has no readable package.json.`);
+    }
+    return {
+        kind: "materialized",
+        packageName,
+        packageDir,
+        version: resolvedVersion,
+        storeDir,
+    };
+}
+/**
+ * Use an already-built package directory as the runtime — the development
+ * path (`install --link <dir>`), where the workspace build *is* the artifact.
+ *
+ * Validates that the directory looks like a built package so a typo surfaces
+ * at install time instead of as hooks that silently never run.
+ */
+function linkedRuntime(opts) {
+    const packageDir = path.resolve(opts.packageDir);
+    const version = readPackageVersion(packageDir);
+    if (!version) {
+        throw new Error(`Cannot link the Ory runtime: ${packageDir} has no readable package.json.`);
+    }
+    if (!fs.existsSync(path.join(packageDir, "dist"))) {
+        throw new Error(`Cannot link the Ory runtime: ${packageDir}/dist is missing. Build the ` +
+            `package first (pnpm build).`);
+    }
+    return { kind: "linked", packageName: opts.packageName, packageDir, version };
+}
+/**
+ * Absolute path to an entry point inside a runtime, e.g. the hook script.
+ * Throws when the file is absent — the shim is written from this, so a bad
+ * relative path must fail at install time, not at the first tool call.
+ */
+function resolveRuntimeEntry(target, relativePath) {
+    const entry = path.join(target.packageDir, relativePath);
+    if (!fs.existsSync(entry)) {
+        throw new Error(`Ory runtime entry not found: ${entry} (package ${target.packageName}@${target.version}).`);
+    }
+    return entry;
+}
+/**
+ * The MCP server inside a runtime, or `undefined` when it isn't there.
+ *
+ * A materialized store installs it as a sibling; a linked workspace build has
+ * it two levels up (`packages/mcp-server`). Optional by design: a plugin whose
+ * MCP registration is missing should degrade to no MCP server, not fail the
+ * whole install.
+ */
+function resolveMcpRuntimeEntry(target) {
+    const candidates = target.kind === "materialized"
+        ? [path.join(target.storeDir, "node_modules", exports.MCP_SERVER_PACKAGE)]
+        : [
+            // pnpm workspace: the plugin's own node_modules links siblings.
+            path.join(target.packageDir, "node_modules", exports.MCP_SERVER_PACKAGE),
+            // …and the packages/ directory holds the source checkout.
+            path.join(target.packageDir, "..", "mcp-server"),
+        ];
+    for (const dir of candidates) {
+        const entry = path.join(dir, "dist", "index.js");
+        if (fs.existsSync(entry))
+            return entry;
+    }
+    return undefined;
+}
+// ─── Shims ─────────────────────────────────────────────────────────
+/**
+ * Body of a generated hook shim.
+ *
+ * Deliberately tiny and dependency-free: it must be loadable even when the
+ * runtime it points at is not. `require` (not `import`) so the shim works
+ * regardless of how the harness invokes it, and the pass-through response is
+ * written *before* exiting 0 so a fail-closed gate still sees a valid answer.
+ */
+function hookShimBody(opts) {
+    const { entry, packageName, version, installCommand, fallbackStdout } = opts;
+    return `#!/usr/bin/env node
+// Ory hook entry shim — generated by ${packageName}@${version}. Do not edit.
+//
+// Resolves the Ory plugin runtime once, at install time: this file is the
+// stable path harness configs reference, and it is rewritten (in place) when
+// the runtime changes. No package resolution happens on the tool-call path.
+//
+// Regenerate with: ${installCommand}
+"use strict";
+
+const ENTRY = ${JSON.stringify(entry)};
+
+try {
+  const mod = require(ENTRY);
+  // Most hook entries run their pipeline as a load-time side effect, so the
+  // require() above is the whole invocation. An entry that must stay
+  // side-effect-free on import — Amp's delegate, whose tests import it to call
+  // decideToolPermission directly — exports \`main\` instead and is run here.
+  //
+  // Without this, such an entry silently does nothing under the shim:
+  // \`require.main === module\` is false because require.main is THIS file, so its
+  // own guard never fires, the process exits 0, and a harness reading exit 0 as
+  // "allow" lets every tool through unchecked (#217).
+  if (mod && typeof mod.main === "function") {
+    Promise.resolve(mod.main()).catch(function (err) {
+      process.stderr.write(
+        "[ory-agent] hook entry failed: " + ((err && err.message) || String(err)) + "\\n"
+      );
+${fallbackStdout ? `      process.stdout.write(${JSON.stringify(fallbackStdout)});\n` : ""}      process.exit(0);
+    });
+  }
+} catch (err) {
+  // Fail OPEN. A harness that treats an unanswered permission gate as a block
+  // would otherwise block every tool call because our runtime went missing.
+  process.stderr.write(
+    "[ory-agent] plugin runtime is missing or unloadable at " +
+      ENTRY +
+      "\\n[ory-agent] tools are NOT being checked. Reinstall with: ${installCommand}\\n" +
+      "[ory-agent] cause: " +
+      ((err && err.message) || String(err)) +
+      "\\n"
+  );
+${fallbackStdout ? `  process.stdout.write(${JSON.stringify(fallbackStdout)});\n` : ""}  process.exit(0);
+}
+`;
+}
+/**
+ * Body of the MCP-server shim. Fails **loudly** (exit 1): an MCP server that
+ * cannot start blocks nothing, so a clear error beats a silent no-op server.
+ */
+function mcpShimBody(opts) {
+    const { entry, packageName, version, installCommand } = opts;
+    return `#!/usr/bin/env node
+// Ory MCP server entry shim — generated by ${packageName}@${version}. Do not edit.
+// Regenerate with: ${installCommand}
+"use strict";
+
+const ENTRY = ${JSON.stringify(entry)};
+
+try {
+  require(ENTRY);
+} catch (err) {
+  process.stderr.write(
+    "[ory-agent] MCP server runtime is missing or unloadable at " +
+      ENTRY +
+      "\\n[ory-agent] reinstall with: ${installCommand}\\n" +
+      "[ory-agent] cause: " +
+      ((err && err.message) || String(err)) +
+      "\\n"
+  );
+  process.exit(1);
+}
+`;
+}
+function writeExecutable(file, body) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, body, { mode: 0o755 });
+    // writeFileSync honors `mode` only when creating the file, so re-assert it
+    // for an overwrite of an existing shim.
+    try {
+        fs.chmodSync(file, 0o755);
+    }
+    catch {
+        /* best-effort — a non-executable shim still runs via `node <path>` */
+    }
+}
+/**
+ * Write (or rewrite) the stable hook shim for a harness and record the wiring
+ * in the manifest. Returns the shim path — what the harness config should
+ * reference, via {@link hookCommand}.
+ *
+ * `fallbackStdout` is the harness's pass-through response for the
+ * runtime-missing case. Most subprocess harnesses treat empty stdout plus
+ * exit 0 as "no opinion, proceed", which is the default; pass a JSON string
+ * for a harness that needs an explicit allow payload.
+ */
+function writeHookShim(opts) {
+    const entry = resolveRuntimeEntry(opts.target, opts.entryRelPath ?? path.join("dist", "hook.js"));
+    const shimPath = getHookShimPath(opts.harness);
+    writeExecutable(shimPath, hookShimBody({
+        entry,
+        packageName: opts.target.packageName,
+        version: opts.target.version,
+        installCommand: opts.installCommand,
+        fallbackStdout: opts.fallbackStdout ?? "",
+    }));
+    recordRuntimeWiring({
+        harness: opts.harness,
+        target: opts.target,
+        hookShim: shimPath,
+        hookEntry: entry,
+        mcpEntry: opts.mcpEntry,
+    });
+    return shimPath;
+}
+/**
+ * Write (or rewrite) the shared MCP-server shim. Returns the shim path, or
+ * `undefined` when this runtime has no MCP server to point at — callers then
+ * skip the MCP registration rather than writing a broken one.
+ */
+function writeMcpShim(opts) {
+    const entry = resolveMcpRuntimeEntry(opts.target);
+    if (!entry)
+        return undefined;
+    const shimPath = getMcpShimPath();
+    writeExecutable(shimPath, mcpShimBody({
+        entry,
+        packageName: opts.target.packageName,
+        version: opts.target.version,
+        installCommand: opts.installCommand,
+    }));
+    return shimPath;
+}
+// ─── Rendering into harness config ─────────────────────────────────
+/**
+ * The hook command a harness config should carry: `node "<shim>"`.
+ *
+ * Quoted because a data dir can contain spaces, and several harnesses run the
+ * command through a shell.
+ */
+function hookCommand(shimPath) {
+    return `node "${shimPath}"`;
+}
+/**
+ * True when a command in a harness config is one of ours.
+ *
+ * Matches the runtime shims this module writes **and** the version-pinned
+ * `npx -y -p @ory/<pkg> …` commands earlier releases wrote. The legacy pattern
+ * has to stay recognized even though nothing emits it any more: uninstall and
+ * the non-destructive install merges use this predicate, and a legacy entry
+ * left behind would keep invoking the last published release alongside the new
+ * shim.
+ */
+function isOryRuntimeCommand(command) {
+    if (!command)
+        return false;
+    return (/ory-hook-[a-z0-9-]+\.(js|cjs|mjs)/.test(command) ||
+        /ory-mcp-server\.(js|cjs|mjs)/.test(command) ||
+        // Legacy npx form: `npx … -p @ory/<pkg>[@ver] ory-<h>-hook`.
+        /@ory\/[a-z0-9-]+/.test(command) ||
+        /\bory-[a-z0-9-]+-hook\b/.test(command));
+}
+/** The MCP server registration a harness config should carry. */
+function mcpCommand(shimPath) {
+    return { command: "node", args: [shimPath] };
+}
+/**
+ * Module specifier for an *in-process* plugin: the absolute package directory.
+ *
+ * In-process harnesses (OpenCode, OpenClaw, Amp, Pi) load the plugin as a
+ * module rather than spawning a hook, so they reference the runtime directly
+ * instead of through a shim — a loader file re-exporting this path, or a
+ * `file://` plugin spec built from it.
+ */
+function moduleSpecifier(target) {
+    return target.packageDir;
+}
+const EMPTY_MANIFEST = { version: 1, harnesses: {} };
+/** Read the manifest. Returns an empty manifest when absent or unreadable. */
+function readRuntimeManifest() {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(getManifestPath(), "utf-8"));
+        const harnesses = parsed.harnesses && typeof parsed.harnesses === "object"
+            ? parsed.harnesses
+            : {};
+        return { version: 1, harnesses };
+    }
+    catch {
+        return { ...EMPTY_MANIFEST, harnesses: {} };
+    }
+}
+function writeRuntimeManifest(manifest) {
+    const file = getManifestPath();
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(manifest, null, 2) + "\n");
+}
+/** Record (or replace) one harness's wiring. Called by {@link writeHookShim}. */
+function recordRuntimeWiring(opts) {
+    const wiring = {
+        harness: opts.harness,
+        packageName: opts.target.packageName,
+        version: opts.target.version,
+        kind: opts.target.kind,
+        packageDir: opts.target.packageDir,
+        ...(opts.target.storeDir ? { storeDir: opts.target.storeDir } : {}),
+        hookShim: opts.hookShim,
+        hookEntry: opts.hookEntry,
+        ...(opts.mcpEntry ? { mcpEntry: opts.mcpEntry } : {}),
+        wiredAt: new Date().toISOString(),
+    };
+    const manifest = readRuntimeManifest();
+    manifest.harnesses[opts.harness] = wiring;
+    writeRuntimeManifest(manifest);
+    return wiring;
+}
+/** The wiring for one harness, or `undefined` when it isn't installed. */
+function getRuntimeWiring(harness) {
+    return readRuntimeManifest().harnesses[harness];
+}
+/**
+ * Forget a harness's wiring and remove its shim. Used by `uninstall`. The
+ * store itself is left to {@link pruneRuntimeStores}, which removes it only
+ * once no harness references it.
+ */
+function removeRuntimeWiring(harness) {
+    const manifest = readRuntimeManifest();
+    const wiring = manifest.harnesses[harness];
+    if (wiring) {
+        try {
+            fs.rmSync(wiring.hookShim, { force: true });
+        }
+        catch {
+            /* best-effort */
+        }
+        delete manifest.harnesses[harness];
+        writeRuntimeManifest(manifest);
+    }
+}
+/**
+ * Delete store directories no harness references any more — the GC step of an
+ * upgrade. Always called *after* the shims have been rewritten, so a store in
+ * use is never removed. Returns the directories deleted.
+ */
+function pruneRuntimeStores() {
+    const root = getRuntimeRoot();
+    let entries;
+    try {
+        entries = fs.readdirSync(root);
+    }
+    catch {
+        return [];
+    }
+    const inUse = new Set(Object.values(readRuntimeManifest().harnesses)
+        .map((w) => w.storeDir)
+        .filter((d) => !!d)
+        .map((d) => path.resolve(d)));
+    const removed = [];
+    for (const name of entries) {
+        const dir = path.join(root, name);
+        if (name === "manifest.json")
+            continue;
+        if (!fs.statSync(dir).isDirectory())
+            continue;
+        if (inUse.has(path.resolve(dir)))
+            continue;
+        fs.rmSync(dir, { recursive: true, force: true });
+        removed.push(dir);
+    }
+    return removed;
+}
+// ─── The install-side entry point ──────────────────────────────────
+/**
+ * Where an `install` should get the runtime from.
+ *
+ *   `--runtime-dir <dir>`       → link that directory
+ *   `ORY_PLUGIN_RUNTIME_DIR`    → link that directory
+ *   otherwise                   → materialize the CLI's own version
+ *
+ * The flag and the env var support explicit source installs that point at an
+ * already-built workspace package instead of materializing from a registry.
+ *
+ * The flag deliberately requires an explicit directory. A bare "link whatever
+ * package I am running from" would resolve to npx's ephemeral cache dir under
+ * the common `npx -p @ory/<pkg>` invocation — a runtime that disappears
+ * between sessions — and `--link` is already taken by at least one harness
+ * (Gemini CLI symlinks its *extension* with it), so the name has to be
+ * unambiguous too.
+ */
+function resolveRuntimeForInstall(opts) {
+    const linkDir = parseRuntimeDirFlag(opts.args ?? []);
+    if (linkDir) {
+        return linkedRuntime({ packageName: opts.packageName, packageDir: linkDir });
+    }
+    const version = readPackageVersion(opts.packageRoot);
+    if (!version) {
+        throw new Error(`Cannot determine the version to install: ${opts.packageRoot}/package.json ` +
+            `is missing or unreadable.`);
+    }
+    return materializeRuntime({
+        packageName: opts.packageName,
+        version,
+        installer: opts.installer,
+    });
+}
+/**
+ * Read `--runtime-dir <dir>` off an argv slice, falling back to the
+ * `ORY_PLUGIN_RUNTIME_DIR` env var. A flag with no value is an error rather
+ * than a silent fallback to materialization — someone passing it means to run
+ * against a local build, and quietly installing from npm instead would look
+ * like the build simply had no effect.
+ */
+function parseRuntimeDirFlag(args) {
+    const idx = args.indexOf("--runtime-dir");
+    if (idx !== -1) {
+        const next = args[idx + 1];
+        if (!next || next.startsWith("-")) {
+            throw new Error("--runtime-dir requires a directory argument.");
+        }
+        return path.resolve(next);
+    }
+    const fromEnv = process.env.ORY_PLUGIN_RUNTIME_DIR?.trim();
+    return fromEnv ? path.resolve(fromEnv) : undefined;
+}
+/**
+ * The hook command of a subprocess-hook runtime.
+ *
+ * `PreparedRuntime.hookCommand` is optional because an in-process integration
+ * imports a module instead of spawning a hook. A harness that *does* spawn one
+ * cannot be wired without it, so its absence is a programming error — better to
+ * say so than to write `undefined` into a config file.
+ */
+function requireHookCommand(runtime) {
+    if (!runtime.hookCommand) {
+        throw new Error(`The resolved runtime for ${runtime.target.packageName} has no hook ` +
+            `command (wired as in-process?).`);
+    }
+    return runtime.hookCommand;
+}
+const RUNTIME_LOCK_TIMEOUT_MS = 5 * 60_000;
+const RUNTIME_LOCK_POLL_MS = 50;
+/** Serialize installs because npm mutates and prunes the shared prefix in place. */
+function withRuntimeInstallLock(action, options = {}) {
+    const root = getRuntimeRoot();
+    const lockPath = getRuntimeInstallLockPath();
+    const deadline = Date.now() + (options.timeoutMs ?? RUNTIME_LOCK_TIMEOUT_MS);
+    fs.mkdirSync(root, { recursive: true });
+    let fd;
+    const token = `${process.pid}:${(0, node_crypto_1.randomUUID)()}`;
+    for (;;) {
+        try {
+            fd = fs.openSync(lockPath, "wx", 0o600);
+            fs.writeSync(fd, token);
+            break;
+        }
+        catch (err) {
+            if (err.code !== "EEXIST")
+                throw err;
+            if (Date.now() > deadline) {
+                throw new Error(`Timed out waiting for the Ory runtime install lock at ${lockPath}. ` +
+                    "Remove it only if no other plugin install is running.");
+            }
+            sleepRuntimeLock(options.pollMs ?? RUNTIME_LOCK_POLL_MS);
+        }
+    }
+    try {
+        return action();
+    }
+    finally {
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            /* best-effort */
+        }
+        try {
+            if (fs.readFileSync(lockPath, "utf8") === token)
+                fs.unlinkSync(lockPath);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+}
+let runtimeLockSleepBuffer;
+function sleepRuntimeLock(ms) {
+    if (runtimeLockSleepBuffer === undefined) {
+        try {
+            runtimeLockSleepBuffer = new Int32Array(new SharedArrayBuffer(4));
+        }
+        catch {
+            runtimeLockSleepBuffer = null;
+        }
+    }
+    if (!runtimeLockSleepBuffer) {
+        throw new Error("This runtime cannot wait for another Ory plugin install to finish.");
+    }
+    Atomics.wait(runtimeLockSleepBuffer, 0, 0, ms);
+}
+/**
+ * One call per plugin install: resolve the runtime, write the shims, record
+ * the wiring, and GC stores nothing references any more.
+ *
+ * Ordering matters — the shims are rewritten *before* pruning, so the store a
+ * harness is about to use is never a GC candidate.
+ */
+function wireRuntime(opts) {
+    return withRuntimeInstallLock(() => wireRuntimeUnlocked(opts));
+}
+function wireRuntimeUnlocked(opts) {
+    const target = resolveRuntimeForInstall({
+        packageName: opts.packageName,
+        packageRoot: opts.packageRoot,
+        args: opts.args,
+        installer: opts.installer,
+    });
+    const mcpEntry = opts.includeMcp === false ? undefined : resolveMcpRuntimeEntry(target);
+    let hookShim;
+    let hookCmd;
+    if (opts.inProcess) {
+        hookShim = resolveRuntimeEntry(target, opts.entryRelPath ?? path.join("dist", "index.js"));
+        recordRuntimeWiring({
+            harness: opts.harness,
+            target,
+            hookShim,
+            hookEntry: hookShim,
+            mcpEntry,
+        });
+    }
+    else {
+        hookShim = writeHookShim({
+            harness: opts.harness,
+            target,
+            entryRelPath: opts.entryRelPath,
+            installCommand: opts.installCommand,
+            fallbackStdout: opts.fallbackStdout,
+            mcpEntry,
+        });
+        hookCmd = hookCommand(hookShim);
+    }
+    const mcpShim = opts.includeMcp === false
+        ? undefined
+        : writeMcpShim({ target, installCommand: opts.installCommand });
+    // Record the harness in the shared config's install registry. Every install
+    // funnels through here, so this is the one place that knows a plugin has
+    // been added — and `uninstall` reads it to tell whether the shared config
+    // still has other consumers before wiping it.
+    (0, config_js_1.registerInstalledHarness)(opts.harness);
+    return {
+        target,
+        hookShim,
+        ...(hookCmd ? { hookCommand: hookCmd } : {}),
+        ...(mcpShim ? { mcpShim, mcpServer: mcpCommand(mcpShim) } : {}),
+        prunedStores: pruneRuntimeStores(),
+    };
+}
+/**
+ * Inspect what a harness will actually load.
+ *
+ * With the runtime resolved at install time, the wired code and the CLI a user
+ * happens to run (`npx @ory/<pkg>@latest status`) can legitimately differ —
+ * so `status` reports the runtime version found on disk, not the CLI's own.
+ * The unhappy states are each distinguishable because they have different
+ * fixes: a missing shim means the harness config points at nothing, a missing
+ * runtime means the shim will fail open (tools unchecked), and drift means the
+ * store was replaced underneath a stale shim.
+ */
+function checkRuntimeHealth(harness) {
+    const wiring = getRuntimeWiring(harness);
+    if (!wiring)
+        return { state: "not_installed" };
+    if (!fs.existsSync(wiring.hookShim))
+        return { state: "shim_missing", wiring };
+    if (!fs.existsSync(wiring.hookEntry)) {
+        return { state: "runtime_missing", wiring };
+    }
+    const onDisk = readPackageVersion(wiring.packageDir);
+    if (onDisk && onDisk !== wiring.version) {
+        return { state: "version_drift", wiring, runtimeVersion: onDisk };
+    }
+    return { state: "ok", wiring };
+}
+/** One-line human summary of {@link checkRuntimeHealth}, for `status`. */
+function describeRuntimeHealth(health) {
+    switch (health.state) {
+        case "not_installed":
+            return "not installed (no runtime wired)";
+        case "ok":
+            return (`${health.wiring.packageName}@${health.wiring.version} ` +
+                `(${health.wiring.kind}) → ${health.wiring.hookEntry}`);
+        case "shim_missing":
+            return `shim missing at ${health.wiring.hookShim} — re-run install`;
+        case "runtime_missing":
+            return (`runtime missing at ${health.wiring.hookEntry} — hooks are failing ` +
+                `open (tools are NOT being checked); re-run install`);
+        case "version_drift":
+            return (`wired to ${health.wiring.version} but ${health.runtimeVersion} is on ` +
+                `disk at ${health.wiring.packageDir} — re-run install`);
+    }
+}