@webpresso/agent-kit 3.3.2 → 3.3.4

package/dist/esm/test-helpers/global-setup.js

@@ -40,13 +40,38 @@ async function withDistBuildLock(fn) {
 // idempotent, re-checked-under-lock build; every other process blocks until that release, then finds
 // the sentinels already satisfied and returns immediately. In the steady state (dist/ already built)
 // this is a single existsSync check with no lock contention at all.
+const AGENT_CORE_SENTINEL = join(REPO_ROOT, "packages/agent-core/dist/esm/repo-root/index.js");
+const AGENT_CONFIG_OXLINT_SENTINEL = join(REPO_ROOT, "packages/agent-config/dist/esm/oxlint/import-hygiene.js");
+function buildWorkspacePackage(filter) {
+    execFileSync("pnpm", ["--filter", filter, "run", "build"], {
+        cwd: REPO_ROOT,
+        encoding: "utf8",
+        env: { ...process.env, HUSKY: "0" },
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+}
+const VENDORED_OXLINT_PLUGIN = join(REPO_ROOT, "dist/esm/config/oxlint/import-hygiene.js");
+/** agent-config oxlint SSOT is imported at build/test time (rules map + vendor source). */
+function ensureAgentConfigBuiltSync() {
+    if (!existsSync(AGENT_CORE_SENTINEL)) {
+        buildWorkspacePackage("@webpresso/agent-core");
+    }
+    if (!existsSync(AGENT_CONFIG_OXLINT_SENTINEL)) {
+        buildWorkspacePackage("@webpresso/agent-config");
+    }
+}
 async function ensureDistPrepared() {
-    // Fast path: nothing to build. Only pay the lock when a build artifact is actually missing.
-    if (existsSync(DIST_SENTINEL) && existsSync(MIGRATION_SENTINEL))
+    // Fast path: agent-kit dist + migration assets + vendored inject plugins.
+    if (existsSync(DIST_SENTINEL) &&
+        existsSync(MIGRATION_SENTINEL) &&
+        existsSync(VENDORED_OXLINT_PLUGIN) &&
+        existsSync(AGENT_CONFIG_OXLINT_SENTINEL)) {
         return;
+    }
     await withDistBuildLock(async () => {
         let builtDist = false;
         // Re-check under the lock: another run may have completed the build while we waited.
+        ensureAgentConfigBuiltSync();
         if (!existsSync(DIST_SENTINEL)) {
             execFileSync("./node_modules/.bin/tshy", [], {
                 cwd: REPO_ROOT,
@@ -73,7 +98,17 @@ async function ensureDistPrepared() {
                 env: { ...process.env, HUSKY: "0" },
             });
         }
-        if (builtDist) {
+        if (builtDist || !existsSync(VENDORED_OXLINT_PLUGIN)) {
+            execFileSync("bun", ["src/build/generate-oxlintrc.ts"], {
+                cwd: REPO_ROOT,
+                encoding: "utf8",
+                env: { ...process.env, HUSKY: "0" },
+            });
+            execFileSync("bun", ["src/build/vendor-oxlint-plugins.ts"], {
+                cwd: REPO_ROOT,
+                encoding: "utf8",
+                env: { ...process.env, HUSKY: "0" },
+            });
             execFileSync("bun", ["src/build/normalize-tsconfig-json-exports.ts"], {
                 cwd: REPO_ROOT,
                 encoding: "utf8",

package/dist/esm/tool-runtime/managed-rtk.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Managed RTK binary — single ownership for install + resolve + capability probe.
+ *
+ * Consumers never brew/cargo install rtk. Setup downloads a pinned upstream
+ * release into the Webpresso cache and every call site uses that absolute path.
+ * Filters stay upstream (Apache-2.0); we only own packaging + path resolution.
+ */
+/** Pinned upstream token-killer release (https://github.com/rtk-ai/rtk). */
+export declare const RTK_MANAGED_VERSION = "0.43.0";
+export type ManagedRtkEnsureResult = {
+    readonly ok: true;
+    readonly path: string;
+    readonly installed: boolean;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export type ManagedRtkDownloader = (url: string, destFile: string) => void;
+/** Test seam. */
+export declare function resetManagedRtkCacheForTests(): void;
+export declare function managedRtkAssetName(platform?: NodeJS.Platform, arch?: string): string | null;
+export declare function managedRtkDownloadUrl(version?: string): string | null;
+/** Cache dir: `envPaths("webpresso").cache/tools/rtk/<version>/`. */
+export declare function managedRtkInstallDir(version?: string): string;
+export declare function managedRtkExecutablePath(version?: string): string;
+/**
+ * Resolve the managed executable if present on disk (no network, no probe).
+ * Prefers explicit WP_RTK_BIN, then managed cache install.
+ */
+export declare function resolveManagedRtkExecutable(): string | null;
+/** Capability probe against a concrete binary (or managed path). Fail-open. */
+export declare function probeRtkCapabilityAt(executable: string): boolean;
+/** Process-cached: managed binary exists and passes capability probe. */
+export declare function isManagedRtkAvailable(): boolean;
+/**
+ * Ensure the pinned managed rtk binary is on disk. Downloads once into the
+ * Webpresso cache. No brew/cargo. Idempotent.
+ */
+export declare function ensureManagedRtk(options?: {
+    readonly downloader?: ManagedRtkDownloader;
+    readonly version?: string;
+}): ManagedRtkEnsureResult;
+/** Write a tiny marker file for diagnostics (optional). */
+export declare function writeManagedRtkVersionMarker(path: string, version: string): void;

package/dist/esm/tool-runtime/managed-rtk.js

@@ -0,0 +1,275 @@
+/**
+ * Managed RTK binary — single ownership for install + resolve + capability probe.
+ *
+ * Consumers never brew/cargo install rtk. Setup downloads a pinned upstream
+ * release into the Webpresso cache and every call site uses that absolute path.
+ * Filters stay upstream (Apache-2.0); we only own packaging + path resolution.
+ */
+import { spawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import envPaths from "env-paths";
+/** Pinned upstream token-killer release (https://github.com/rtk-ai/rtk). */
+export const RTK_MANAGED_VERSION = "0.43.0";
+const RTK_PROBE_TIMEOUT_MS = 3000;
+const RTK_CAPABILITY_ARGS = ["gain", "--help"];
+const BINARY_NAME = process.platform === "win32" ? "rtk.exe" : "rtk";
+let cachedExecutable;
+let cachedCapability;
+/** Test seam. */
+export function resetManagedRtkCacheForTests() {
+    cachedExecutable = undefined;
+    cachedCapability = undefined;
+}
+export function managedRtkAssetName(platform = process.platform, arch = process.arch) {
+    if (platform === "darwin" && arch === "arm64")
+        return "rtk-aarch64-apple-darwin.tar.gz";
+    if (platform === "darwin" && arch === "x64")
+        return "rtk-x86_64-apple-darwin.tar.gz";
+    if (platform === "linux" && arch === "arm64")
+        return "rtk-aarch64-unknown-linux-gnu.tar.gz";
+    if (platform === "linux" && arch === "x64")
+        return "rtk-x86_64-unknown-linux-musl.tar.gz";
+    if (platform === "win32" && arch === "x64")
+        return "rtk-x86_64-pc-windows-msvc.zip";
+    return null;
+}
+export function managedRtkDownloadUrl(version = RTK_MANAGED_VERSION) {
+    const asset = managedRtkAssetName();
+    if (!asset)
+        return null;
+    return `https://github.com/rtk-ai/rtk/releases/download/v${version}/${asset}`;
+}
+/** Cache dir: `envPaths("webpresso").cache/tools/rtk/<version>/`. */
+export function managedRtkInstallDir(version = RTK_MANAGED_VERSION) {
+    const cacheRoot = process.env.WP_RTK_CACHE_ROOT ?? envPaths("webpresso", { suffix: "" }).cache;
+    return join(cacheRoot, "tools", "rtk", version);
+}
+export function managedRtkExecutablePath(version = RTK_MANAGED_VERSION) {
+    return join(managedRtkInstallDir(version), BINARY_NAME);
+}
+/**
+ * Resolve the managed executable if present on disk (no network, no probe).
+ * Prefers explicit WP_RTK_BIN, then managed cache install.
+ */
+export function resolveManagedRtkExecutable() {
+    // Skip is process-env policy for this call — do not poison the path cache.
+    if (process.env.WP_SKIP_RTK === "1")
+        return null;
+    if (cachedExecutable !== undefined)
+        return cachedExecutable;
+    const override = process.env.WP_RTK_BIN?.trim();
+    if (override && existsSync(override)) {
+        cachedExecutable = override;
+        return cachedExecutable;
+    }
+    const managed = managedRtkExecutablePath();
+    if (existsSync(managed)) {
+        cachedExecutable = managed;
+        return cachedExecutable;
+    }
+    cachedExecutable = null;
+    return null;
+}
+/** Capability probe against a concrete binary (or managed path). Fail-open. */
+export function probeRtkCapabilityAt(executable) {
+    try {
+        const result = spawnSync(executable, [...RTK_CAPABILITY_ARGS], {
+            encoding: "utf8",
+            timeout: RTK_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        return result.error == null && result.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+/** Process-cached: managed binary exists and passes capability probe. */
+export function isManagedRtkAvailable() {
+    if (cachedCapability !== undefined)
+        return cachedCapability;
+    if (process.env.WP_SKIP_RTK === "1") {
+        cachedCapability = false;
+        return false;
+    }
+    const path = resolveManagedRtkExecutable();
+    if (!path) {
+        cachedCapability = false;
+        return false;
+    }
+    cachedCapability = probeRtkCapabilityAt(path);
+    return cachedCapability;
+}
+function defaultDownloader(url, destFile) {
+    // Prefer curl when present (HTTP/2, redirects); fall back to node fetch via spawn node -e is avoided.
+    const curl = spawnSync("curl", ["-fsSL", "--retry", "2", "--retry-delay", "1", "-o", destFile, url], { encoding: "utf8", timeout: 120_000 });
+    if (curl.error || curl.status !== 0) {
+        throw new Error(`download failed (${curl.status ?? "error"}): ${String(curl.stderr ?? curl.error ?? "").trim() || url}`);
+    }
+}
+function isRegularFile(path) {
+    try {
+        return lstatSync(path).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+/** Prefer a real file named rtk / rtk.exe — ignore directories of the same name. */
+function findExtractedBinary(root) {
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            const full = join(dir, name);
+            if ((name === BINARY_NAME || name === "rtk") && isRegularFile(full)) {
+                return full;
+            }
+            try {
+                // shallow walk only one extra level for nested release layouts
+                const nested = readdirSync(full);
+                for (const child of nested) {
+                    const nestedFull = join(full, child);
+                    if ((child === BINARY_NAME || child === "rtk") && isRegularFile(nestedFull)) {
+                        return nestedFull;
+                    }
+                }
+            }
+            catch {
+                // not a dir
+            }
+        }
+    }
+    return null;
+}
+function extractArchive(archivePath, extractDir) {
+    mkdirSync(extractDir, { recursive: true });
+    if (archivePath.endsWith(".zip")) {
+        const unzip = spawnSync("unzip", ["-qo", archivePath, "-d", extractDir], {
+            encoding: "utf8",
+            timeout: 60_000,
+        });
+        if (unzip.status !== 0) {
+            throw new Error(`unzip failed: ${String(unzip.stderr ?? "").trim()}`);
+        }
+        return;
+    }
+    const tar = spawnSync("tar", ["-xzf", archivePath, "-C", extractDir], {
+        encoding: "utf8",
+        timeout: 60_000,
+    });
+    if (tar.status !== 0) {
+        throw new Error(`tar extract failed: ${String(tar.stderr ?? "").trim()}`);
+    }
+}
+/**
+ * Ensure the pinned managed rtk binary is on disk. Downloads once into the
+ * Webpresso cache. No brew/cargo. Idempotent.
+ */
+export function ensureManagedRtk(options = {}) {
+    if (process.env.WP_SKIP_RTK === "1") {
+        return { ok: false, error: "WP_SKIP_RTK=1" };
+    }
+    const version = options.version ?? RTK_MANAGED_VERSION;
+    const dest = managedRtkExecutablePath(version);
+    if (existsSync(dest) && probeRtkCapabilityAt(dest)) {
+        resetManagedRtkCacheForTests();
+        cachedExecutable = dest;
+        cachedCapability = true;
+        return { ok: true, path: dest, installed: false };
+    }
+    const url = managedRtkDownloadUrl(version);
+    if (!url) {
+        return {
+            ok: false,
+            error: `no managed rtk asset for ${process.platform}/${process.arch}`,
+        };
+    }
+    const installDir = managedRtkInstallDir(version);
+    mkdirSync(installDir, { recursive: true });
+    const work = mkdtempSync(join(tmpdir(), "wp-rtk-"));
+    try {
+        const archiveName = basename(url);
+        const archivePath = join(work, archiveName);
+        const download = options.downloader ?? defaultDownloader;
+        download(url, archivePath);
+        const extractDir = join(work, "extract");
+        extractArchive(archivePath, extractDir);
+        const found = findExtractedBinary(extractDir);
+        if (!found) {
+            return { ok: false, error: `archive did not contain ${BINARY_NAME}` };
+        }
+        mkdirSync(dirname(dest), { recursive: true });
+        // Stage under a unique name so concurrent setup never clobbers a live dest
+        // mid-probe, and we only delete our own staged file on failure.
+        const staged = join(installDir, `.rtk-staging-${process.pid}-${Date.now()}-${randomBytes(6).toString("hex")}`);
+        try {
+            try {
+                renameSync(found, staged);
+            }
+            catch {
+                const cp = spawnSync("cp", [found, staged], { encoding: "utf8" });
+                if (cp.status !== 0) {
+                    return { ok: false, error: `failed to stage managed rtk at ${staged}` };
+                }
+            }
+            if (process.platform !== "win32") {
+                chmodSync(staged, 0o755);
+            }
+            if (!probeRtkCapabilityAt(staged)) {
+                return { ok: false, error: "downloaded rtk failed capability probe (rtk gain --help)" };
+            }
+            try {
+                renameSync(staged, dest);
+            }
+            catch {
+                // Cross-device rename: replace dest via copy then drop stage.
+                const cp = spawnSync("cp", [staged, dest], { encoding: "utf8" });
+                if (cp.status !== 0) {
+                    return { ok: false, error: `failed to place managed rtk at ${dest}` };
+                }
+                if (process.platform !== "win32") {
+                    chmodSync(dest, 0o755);
+                }
+            }
+        }
+        finally {
+            try {
+                rmSync(staged, { force: true });
+            }
+            catch {
+                // ignore
+            }
+        }
+        resetManagedRtkCacheForTests();
+        cachedExecutable = dest;
+        cachedCapability = true;
+        return { ok: true, path: dest, installed: true };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: message };
+    }
+    finally {
+        try {
+            rmSync(work, { recursive: true, force: true });
+        }
+        catch {
+            // ignore
+        }
+    }
+}
+/** Write a tiny marker file for diagnostics (optional). */
+export function writeManagedRtkVersionMarker(path, version) {
+    writeFileSync(`${path}.version`, `${version}\n`, "utf8");
+}

package/dist/esm/tool-runtime/resolve-runner.js

@@ -1,12 +1,11 @@
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
 import { createRequire } from "node:module";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { Worker } from "node:worker_threads";
 import { resolveAgentKitPackageRoot } from "#cli/commands/init/package-root.js";
 import { resolveGlobalCapableVpCommand } from "#cli/global-vp.js";
 import { pathCandidates } from "#runtime/command-exists.js";
 import { readTrustedJsonFile } from "#shared-utils/read-json-file.js";
+import { isManagedRtkAvailable, resolveManagedRtkExecutable } from "./managed-rtk.js";
 const require = createRequire(import.meta.url);
 const MANAGED_TOOL_PREFIX = {
     oxfmt: {
@@ -33,196 +32,8 @@ const MANAGED_TOOL_PREFIX = {
     wrangler: { packageName: "wrangler", binName: "wrangler" },
 };
 let rtkAvailable = null;
-// The real token-killer `rtk` exposes a `gain` analytics subcommand (see
-// RTK.md); the unrelated `reachingforthejack/rtk` (Rust Type Kit) collision
-// binary does not. Probe that capability instead of `--version`, which *any*
-// `rtk` on PATH answers with exit 0 — trusting it would route wrapped commands
-// (typecheck/qa/test gates) through a foreign binary that may mangle args or
-// drop the wrapped exit code, masking a failing gate as green.
-const RTK_CAPABILITY_ARGS = ["gain", "--help"];
-// Measured cold cost of `rtk gain --help` is ~11ms; 3s is generous headroom.
-// A probe that exceeds it is a broken or wrong binary, so degrade to unfiltered
-// output rather than let a hung `rtk` stall every wrapped command (per
-// no-timeout-as-fix: the bound surfaces the fault, it does not silence it).
-const RTK_PROBE_TIMEOUT_MS = 3000;
-const RTK_PROBE_ESCALATION_DELAY_MS = 250;
-const RTK_PROBE_FORCE_KILL_OBSERVE_MS = 1000;
-const RTK_PROBE_ADAPTER_SLACK_MS = 1000;
-const RTK_PROBE_ADAPTER_TIMEOUT_MS = RTK_PROBE_TIMEOUT_MS +
-    RTK_PROBE_ESCALATION_DELAY_MS +
-    RTK_PROBE_FORCE_KILL_OBSERVE_MS +
-    RTK_PROBE_ADAPTER_SLACK_MS;
-const RTK_PROBE_STATUS_INDEX = 0;
-const RTK_PROBE_PID_INDEX = 1;
-const RTK_PROBE_PENDING = 0;
-const RTK_PROBE_AVAILABLE = 1;
-const RTK_PROBE_UNAVAILABLE = 2;
-const RTK_PROBE_CLEANUP_FAILED = 3;
-// `resolveRunner` is intentionally synchronous because it is also used by pure
-// command planners. The worker keeps that contract while allowing the inner
-// probe to use the same async, owned-process-group supervisor as long-running
-// command surfaces. The main thread only waits on shared state; it never owns a
-// timeout-killed wrapper whose descendants can escape.
-const RTK_PROBE_WORKER_SOURCE = String.raw `
-(async () => {
-  const [{ spawn }, { workerData }] = await Promise.all([
-    import("node:child_process"),
-    import("node:worker_threads"),
-  ]);
-  const state = new Int32Array(workerData.state);
-  let settled = false;
-  const finish = (status) => {
-    if (settled) return;
-    settled = true;
-    Atomics.store(state, workerData.statusIndex, status);
-    Atomics.notify(state, workerData.statusIndex);
-  };
-
-  try {
-    const {
-      createTerminationAwareChild,
-      terminateOwnedProcessTreeWithEscalation,
-    } = await import(workerData.supervisorModuleUrl);
-    if (
-      typeof createTerminationAwareChild !== "function" ||
-      typeof terminateOwnedProcessTreeWithEscalation !== "function"
-    ) {
-      finish(workerData.cleanupFailed);
-      return;
-    }
-
-    const child = spawn("rtk", workerData.args, {
-      detached: process.platform !== "win32",
-      stdio: "ignore",
-      windowsHide: true,
-    });
-    if (child.pid) Atomics.store(state, workerData.pidIndex, child.pid);
-    const tracked = createTerminationAwareChild(child, {
-      kind: "owned-process-group",
-      detached: true,
-    });
-
-    let resolving = false;
-    let timer;
-    const resolveAfterCleanup = async (status) => {
-      if (resolving) return;
-      resolving = true;
-      if (timer) clearTimeout(timer);
-      await terminateOwnedProcessTreeWithEscalation(tracked, {
-        escalationDelayMs: workerData.escalationDelayMs,
-      });
-      finish(status);
-    };
-    const settle = (status) => {
-      void resolveAfterCleanup(status).catch(() => finish(workerData.cleanupFailed));
-    };
-
-    timer = setTimeout(() => {
-      settle(workerData.unavailable);
-    }, workerData.timeoutMs);
-    child.once("error", () => {
-      settle(workerData.unavailable);
-    });
-    child.once("close", (code) => {
-      settle(code === 0 ? workerData.available : workerData.unavailable);
-    });
-  } catch {
-    finish(workerData.cleanupFailed);
-  }
-})();
-`;
-function probeRtkAvailability() {
-    if (rtkAvailable !== null)
-        return rtkAvailable;
-    const supervisorModuleUrl = resolveProbeSupervisorModuleUrl();
-    if (supervisorModuleUrl === null) {
-        rtkAvailable = false;
-        return rtkAvailable;
-    }
-    const state = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT * 2));
-    let worker;
-    try {
-        worker = new Worker(RTK_PROBE_WORKER_SOURCE, {
-            eval: true,
-            workerData: {
-                args: RTK_CAPABILITY_ARGS,
-                available: RTK_PROBE_AVAILABLE,
-                unavailable: RTK_PROBE_UNAVAILABLE,
-                cleanupFailed: RTK_PROBE_CLEANUP_FAILED,
-                statusIndex: RTK_PROBE_STATUS_INDEX,
-                pidIndex: RTK_PROBE_PID_INDEX,
-                state: state.buffer,
-                supervisorModuleUrl,
-                timeoutMs: RTK_PROBE_TIMEOUT_MS,
-                escalationDelayMs: RTK_PROBE_ESCALATION_DELAY_MS,
-            },
-        });
-        worker.unref();
-        Atomics.wait(state, RTK_PROBE_STATUS_INDEX, RTK_PROBE_PENDING, RTK_PROBE_ADAPTER_TIMEOUT_MS);
-        const status = Atomics.load(state, RTK_PROBE_STATUS_INDEX);
-        if (status === RTK_PROBE_PENDING || status === RTK_PROBE_CLEANUP_FAILED) {
-            forceReclaimProbe(Atomics.load(state, RTK_PROBE_PID_INDEX));
-        }
-        rtkAvailable = status === RTK_PROBE_AVAILABLE;
-    }
-    catch {
-        rtkAvailable = false;
-    }
-    finally {
-        void worker?.terminate();
-    }
-    return rtkAvailable;
-}
-function resolveProbeSupervisorModuleUrl() {
-    const sourceExtension = import.meta.url.endsWith(".ts") ? "ts" : "js";
-    const adjacent = new URL(`../utils/process-supervisor.${sourceExtension}`, import.meta.url);
-    try {
-        if (adjacent.protocol === "file:" && existsSync(fileURLToPath(adjacent))) {
-            return adjacent.href;
-        }
-    }
-    catch {
-        // Native runtimes can expose a virtual import.meta.url; fall back to the package root.
-    }
-    const packageRoot = resolveAgentKitPackageRoot({ moduleUrl: import.meta.url });
-    if (packageRoot === null)
-        return null;
-    for (const candidate of [
-        join(packageRoot, "dist", "esm", "utils", "process-supervisor.js"),
-        join(packageRoot, "src", "utils", "process-supervisor.ts"),
-    ]) {
-        if (existsSync(candidate))
-            return pathToFileURL(candidate).href;
-    }
-    return null;
-}
-function forceReclaimProbe(pid) {
-    if (!Number.isInteger(pid) || pid <= 0)
-        return;
-    const target = process.platform === "win32" ? pid : -pid;
-    try {
-        process.kill(target, "SIGKILL");
-    }
-    catch (error) {
-        if (error.code !== "ESRCH")
-            throw error;
-        return;
-    }
-    const deadline = Date.now() + RTK_PROBE_FORCE_KILL_OBSERVE_MS;
-    const sleeper = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
-    while (isProcessTargetAlive(target) && Date.now() < deadline) {
-        Atomics.wait(sleeper, 0, 0, 20);
-    }
-}
-function isProcessTargetAlive(target) {
-    try {
-        process.kill(target, 0);
-        return true;
-    }
-    catch (error) {
-        return error.code !== "ESRCH";
-    }
-}
+// Capability probing lives in managed-rtk (absolute binary + `gain --help`).
+// Hermetic tests use setRtkAvailabilityProbeForTest to force wrap/degrade.
 export function setRtkAvailabilityProbeForTest(value) {
     rtkAvailable = value;
 }
@@ -232,11 +43,24 @@ export function resolveOutputPolicy(outputPolicy, filterOutput) {
 function withOptionalRtk(resolution, outputPolicy) {
     if (outputPolicy !== "rtk-filtered")
         return resolution;
-    if (!probeRtkAvailability())
+    // Hermetic test seam: setRtkAvailabilityProbeForTest(true) wraps with bare "rtk".
+    if (rtkAvailable === true) {
+        return {
+            ...resolution,
+            command: "rtk",
+            args: [resolution.command, ...resolution.args],
+        };
+    }
+    if (rtkAvailable === false)
+        return resolution;
+    if (!isManagedRtkAvailable())
+        return resolution;
+    const rtkBin = resolveManagedRtkExecutable();
+    if (!rtkBin)
         return resolution;
     return {
         ...resolution,
-        command: "rtk",
+        command: rtkBin,
         args: [resolution.command, ...resolution.args],
     };
 }

package/dist/esm/utils/package-root.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Locate an installed package's root directory from its bare name.
+ *
+ * The obvious spelling — `require.resolve("<name>/package.json")` — is a trap.
+ * Node honours the target package's `exports` map, and a package that declares
+ * only `"."` (rulesync) makes that throw `ERR_PACKAGE_PATH_NOT_EXPORTED`. Every
+ * caller in this repo wrapped it in `try {} catch { return null }`, so the throw
+ * turned into a silently missing capability rather than a visible failure.
+ *
+ * Resolving the package's exported entry works instead, because any package
+ * meant to be imported has one. From there, walk up to the directory whose
+ * `package.json` actually declares that name — the entry may sit several levels
+ * deep (`<root>/dist/index.cjs`).
+ *
+ * Caveat worth knowing before reusing this: `resolve` runs under the CJS
+ * `require` condition. A package whose every export condition is `import`
+ * (ESM-only, as `@webpresso/agent-kit` itself is) has no entry resolvable this
+ * way at all. Such a package must export a condition-free `"./package.json"`
+ * target instead; this helper cannot rescue it.
+ */
+/** Minimal slice of `NodeRequire` needed here — keeps callers and tests honest. */
+export interface ModuleResolver {
+    resolve(specifier: string): string;
+}
+export declare function readPackageManifest(packageRoot: string): Record<string, unknown> | null;
+/**
+ * @param name Bare package name, scoped or unscoped (`rulesync`, `@scope/pkg`).
+ * @returns The package root directory, or `null` when it cannot be resolved.
+ */
+export declare function resolvePackageRoot(name: string, resolver: ModuleResolver, maxDepth?: number): string | null;
+/** Convenience wrapper: the installed `version` of `name`, or `null`. */
+export declare function resolvePackageVersion(name: string, resolver: ModuleResolver): string | null;