@webpresso/agent-kit 3.3.3 → 3.3.5

package/dist/esm/symlinker/consumers.js

@@ -17,7 +17,7 @@
  * the canonical `.agent/{rules,skills}` SSOT always project.
  *
  * The `UNIFIED_CONSUMERS` registry below describes per-IDE projection of the
- * unified rule/skill content kinds (catalog ∪ consumer). Strategies:
+ * unified rule/skill/agent content kinds (catalog ∪ consumer). Strategies:
  *   - 'symlink':   create a relative symlink to the source (file or dir)
  *   - 'copy':      copy file or recursively copy dir tree
  *   - 'transform': run a transform function over the body and write the
@@ -59,6 +59,8 @@ export function unifiedRuleFilename(consumer, slug) {
  * `selectUnifiedConsumers(hosts)`:
  *   - `.agent/{rules,skills}/` (working dir, SSOT): symlink, always
  *   - `.claude/rules/`: symlink, always (rules are not plugin-delivered)
+ *   - `.claude/agents/`: symlink, always (canonical subagents; Claude has no
+ *     native subagent delivery channel, so this projection is not plugin-owned)
  *
  * Project-local legacy skill roots are intentionally omitted. Codex has no
  * `.codex/agents/` consumer.
@@ -69,6 +71,10 @@ export const DEFAULT_UNIFIED_CONSUMERS = [
     { id: "agent-skills", dir: ".agent/skills", acceptsKind: "skill", strategy: "symlink" },
     // Claude: rules are scaffolded to .claude/rules; skills come from native channels.
     { id: "claude-rules", dir: ".claude/rules", acceptsKind: "rule", strategy: "symlink" },
+    // Claude: canonical subagents are scaffolded to .claude/agents. Host-agnostic
+    // (unconditional) because subagents were previously scaffolded unconditionally
+    // by the now-retired standalone scaffoldSubagents scaffolder.
+    { id: "claude-agents", dir: ".claude/agents", acceptsKind: "agent", strategy: "symlink" },
 ];
 /**
  * Projection surfaces retired by a newer agent-kit release.

package/dist/esm/symlinker/unified-sync.d.ts

@@ -1,8 +1,8 @@
 /**
- * Unified rule + skill sync.
+ * Unified rule + skill + agent sync.
  *
- * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills}/`) UNION
- * consumer (`<repo>/agent-{rules,skills}/`). The loader returns a
+ * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills,agents}/`)
+ * UNION consumer (`<repo>/agent-{rules,skills,agents}/`). The loader returns a
  * source-tagged record list; this module projects that list into per-IDE
  * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
  *

package/dist/esm/symlinker/unified-sync.js

@@ -1,8 +1,8 @@
 /**
- * Unified rule + skill sync.
+ * Unified rule + skill + agent sync.
  *
- * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills}/`) UNION
- * consumer (`<repo>/agent-{rules,skills}/`). The loader returns a
+ * Source of truth: catalog (`<pkg>/dist/catalog/agent/{rules,skills,agents}/`)
+ * UNION consumer (`<repo>/agent-{rules,skills,agents}/`). The loader returns a
  * source-tagged record list; this module projects that list into per-IDE
  * surfaces according to `DEFAULT_UNIFIED_CONSUMERS`.
  *
@@ -86,7 +86,9 @@ function planTargets(records, consumers, consumerRoot) {
             const consumerDirAbs = join(consumerRoot, consumer.dir);
             let entryName;
             let targetPath;
-            if (record.kind === "rule") {
+            if (record.kind === "rule" || record.kind === "agent") {
+                // agent records are file-shaped like rules (a single <slug>.md),
+                // not dir-shaped like skills.
                 entryName = unifiedRuleFilename(consumer, record.slug);
                 targetPath = join(consumerDirAbs, entryName);
             }
@@ -248,13 +250,40 @@ function applyTarget(plan, check) {
         }
     }
 }
+/**
+ * True when `fullPath` is a symlink whose resolved target's directory is one
+ * of `managedSourceDirs`. Used to distinguish an agent-kit-managed symlink
+ * (safe to prune when stale/renamed) from a real file or a foreign symlink
+ * (never agent-kit-managed, must survive `wp sync`). The resolved target
+ * itself need not currently exist — a dangling symlink to a since-removed
+ * catalog agent still resolves into the managed source dir and is prunable.
+ */
+function isManagedAgentSymlink(fullPath, managedSourceDirs) {
+    let stat;
+    try {
+        stat = lstatSync(fullPath);
+    }
+    catch {
+        return false;
+    }
+    if (!stat.isSymbolicLink())
+        return false;
+    try {
+        const linkTarget = readlinkSync(fullPath);
+        const resolved = resolve(dirname(fullPath), linkTarget);
+        return managedSourceDirs.has(dirname(resolved));
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Remove entries under each consumer dir that no longer correspond to any
  * planned record. Only removes entries whose shape matches the consumer's
  * managed pattern (rule files: `<slug><ext>`; skill dirs: subdirectories).
  * Real files outside the managed pattern (README.md, .gitkeep) are left alone.
  */
-function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
+function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs, configuredAgentSourceDirs) {
     const expectedByConsumerDir = new Map();
     for (const plan of plans) {
         const key = plan.consumer.dir;
@@ -265,6 +294,25 @@ function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
         }
         set.add(plan.entryName);
     }
+    // Directories that agent-kind sources resolve from (the catalog `agents/`
+    // dir, and a consumer `agent-agents/` override dir if present). Unlike
+    // `.claude/rules` and `.claude/skills` — surfaces with no legitimate
+    // hand-authoring workflow — `.claude/agents` is Claude Code's own native
+    // subagent authoring location. A consumer-authored `.claude/agents/foo.md`
+    // that was never agent-kit-managed must survive `wp sync`; only symlinks
+    // that resolve into a known managed source dir are eligible for pruning.
+    //
+    // The set unions plan-derived dirs with the CONFIGURED source dirs so it is
+    // never empty: with an empty or missing catalog agents dir there are no
+    // plans, and a plans-only set would leave nothing provably managed — the
+    // sweep must then delete nothing, not everything. Dangling managed symlinks
+    // (pointing into a configured dir whose file is gone) stay prunable.
+    const agentSourceDirs = new Set([
+        ...configuredAgentSourceDirs,
+        ...plans
+            .filter((plan) => plan.record.kind === "agent")
+            .map((plan) => dirname(plan.record.filePath)),
+    ]);
     let removed = 0;
     const mismatches = [];
     // Each unique dir gets a single sweep — multiple consumers can share a dir
@@ -292,15 +340,28 @@ function pruneStale(plans, consumers, consumerRoot, check, preserveSkillSlugs) {
                 preserveSkillSlugs.has(name) &&
                 entry.isDirectory())
                 continue;
-            // Only prune entries that match a managed shape: rule extension OR a
-            // directory (skill).
-            const matchesRulePattern = consumersForDir.some((c) => c.acceptsKind === "rule" && name.endsWith(c.ruleExtension ?? ".md"));
+            // Only prune entries that match a managed shape: rule/agent extension
+            // OR a directory (skill). Agent records are file-shaped like rules.
+            const matchesRulePattern = consumersForDir.some((c) => (c.acceptsKind === "rule" || c.acceptsKind === "agent") &&
+                name.endsWith(c.ruleExtension ?? ".md"));
             const matchesSkillPattern = consumersForDir.some((c) => c.acceptsKind === "skill") && entry.isDirectory();
             // Also handle stale symlinks of either shape.
             const isLink = entry.isSymbolicLink();
             if (!matchesRulePattern && !matchesSkillPattern && !isLink)
                 continue;
             const fullPath = join(dirAbs, name);
+            // Conservative prune for agent-only dirs: skip real files and foreign
+            // symlinks (anything not resolving into a known agent-kit managed
+            // source dir). This guard is unconditional — the source-dir set is
+            // configuration-derived and never empty, so a broken install (empty or
+            // missing catalog agents dir) cannot degrade the sweep into deleting
+            // hand-authored files. Rules/skills dirs have no legitimate
+            // hand-authoring workflow, so their existing
+            // sweep-everything-unexpected behavior is unchanged.
+            const isAgentOnlyDir = consumersForDir.every((c) => c.acceptsKind === "agent");
+            if (isAgentOnlyDir && !isManagedAgentSymlink(fullPath, agentSourceDirs)) {
+                continue;
+            }
             if (check) {
                 mismatches.push({
                     consumerId: consumersForDir[0]?.id ?? dir,
@@ -348,7 +409,7 @@ function pruneEmptyRetiredConsumerDirs(consumers, consumerRoot, check) {
  * Main entrypoint. See module docstring.
  */
 export function runUnifiedSync(options) {
-    const kinds = options.kinds ?? ["rule", "skill"];
+    const kinds = options.kinds ?? ["rule", "skill", "agent"];
     const kindSet = new Set(kinds);
     const consumers = (options.consumers ?? selectUnifiedConsumers(options.hosts)).filter((consumer) => kindSet.has(consumer.acceptsKind));
     const activeDirs = new Set(consumers.map((consumer) => consumer.dir));
@@ -394,10 +455,26 @@ export function runUnifiedSync(options) {
             }
         }
     }
-    const prune = pruneStale(plans, consumers, consumerRoot, options.check === true, options.preserveSkillSlugs);
+    // Configuration-derived agent source dirs (catalog `agents/` plus the
+    // consumer `agent-agents/` override). Added in both raw-resolved and
+    // realpath forms so set membership survives the /var → /private/var realm
+    // split on macOS. Present even when the dirs are empty or absent — that is
+    // the point: prune eligibility must not collapse to "everything" when a
+    // broken install yields zero planned agent records.
+    const configuredAgentSourceDirs = new Set();
+    for (const candidate of [
+        join(options.catalogDir, "agents"),
+        join(consumerRoot, "agent-agents"),
+    ]) {
+        configuredAgentSourceDirs.add(resolve(candidate));
+        if (existsSync(candidate)) {
+            configuredAgentSourceDirs.add(realpathSync(candidate));
+        }
+    }
+    const prune = pruneStale(plans, consumers, consumerRoot, options.check === true, options.preserveSkillSlugs, configuredAgentSourceDirs);
     fixCount += prune.removed;
     mismatches.push(...prune.mismatches);
-    const retiredPrune = pruneStale([], retiredConsumers, consumerRoot, options.check === true, undefined);
+    const retiredPrune = pruneStale([], retiredConsumers, consumerRoot, options.check === true, undefined, configuredAgentSourceDirs);
     fixCount += retiredPrune.removed;
     mismatches.push(...retiredPrune.mismatches);
     const retiredDirectories = pruneEmptyRetiredConsumerDirs(retiredConsumers, consumerRoot, options.check === true);

package/dist/esm/test/shard-durations.json

@@ -296,7 +296,6 @@
             "src/hooks/dispatch/index.test.ts": 11.771874999999994,
             "src/hooks/shared/hook-bootstrap.test.ts": 58.217375000000004,
             "src/cli/commands/init/scaffolders/agent-hooks/emitters/grok.test.ts": 67.57654199999999,
-            "src/cli/commands/init/scaffolders/subagents/index.test.ts": 49.99270800000005,
             "src/blueprint/core/validation/criteria.test.ts": 9.635125000000016,
             "src/cli/commands/session.test.ts": 662.8378339999999,
             "src/cli/commands/dash/run-registry.test.ts": 793.002083,
@@ -560,7 +559,6 @@
             "src/audit/no-legacy-cli-bin.test.ts": 56.865957999999864,
             "src/mcp/tools/session-elision.test.ts": 4564.6535,
             "src/hooks/pretool-guard/validators/ux-quality.test.ts": 105.19341700000041,
-            "src/config/oxlint/monorepo-paths.test.ts": 11.33191700000043,
             "src/cli/commands/init/source-repo-hook-policy.test.ts": 65.89804200000003,
             "src/secrets/config/schema.test.ts": 190.3588749999999,
             "scripts/bench/scenarios/_schema.test.ts": 53.78470799999968,

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");
+}