@osfactory/har 0.49.1 → 0.50.0

package/dist/index.js

@@ -28694,6 +28694,10 @@ var init_control_config = __esm({
 });
 
 // src/utils/shell.ts
+function quoteShellArg(arg) {
+  if (/^[A-Za-z0-9_./:=+-]+$/.test(arg)) return arg;
+  return `'${arg.replace(/'/g, `'\\''`)}'`;
+}
 function run(command2, options = {}) {
   try {
     const stdout = (0, import_child_process.execSync)(command2, {
@@ -29055,10 +29059,6 @@ var init_slot_registry = __esm({
 });
 
 // src/core/local-executor.ts
-function quoteShellArg(arg) {
-  if (/^[A-Za-z0-9_./:=+-]+$/.test(arg)) return arg;
-  return `'${arg.replace(/'/g, `'\\''`)}'`;
-}
 function buildLaunchFlagArgs(flags) {
   const args = [];
   if (flags.worktree === false) args.push("--no-worktree");
@@ -29790,10 +29790,32 @@ var init_slot_launch_guard_occupied = __esm({
   }
 });
 
+// src/utils/package-runner.ts
+function commandExists(command2) {
+  const result = (0, import_child_process6.spawnSync)("sh", ["-c", `command -v ${JSON.stringify(command2)}`], {
+    encoding: "utf8"
+  });
+  return result.status === 0 && Boolean(result.stdout?.trim());
+}
+function packageRunner() {
+  if (cached !== void 0) return cached;
+  const available = RUNNERS.find((runner) => commandExists(runner.split(" ")[0]));
+  cached = available ?? RUNNERS[0];
+  return cached;
+}
+var import_child_process6, RUNNERS, cached;
+var init_package_runner = __esm({
+  "src/utils/package-runner.ts"() {
+    "use strict";
+    import_child_process6 = require("child_process");
+    RUNNERS = ["npx --yes", "bunx", "pnpm dlx", "yarn dlx"];
+  }
+});
+
 // src/core/slot-preflight.ts
 function listPm2Processes() {
   try {
-    const raw = (0, import_child_process6.execSync)("npx --yes pm2 jlist", {
+    const raw = (0, import_child_process7.execSync)(`${packageRunner()} pm2 jlist`, {
       encoding: "utf8",
       stdio: ["pipe", "pipe", "ignore"],
       timeout: 3e3
@@ -29874,7 +29896,7 @@ function inspectSlotReadiness(repoPath, agentId, options = {}) {
       remediation: "Stop the other harness session (./.har/teardown.sh in that repo) or use a different agent slot.",
       details: { processes: foreign.processes }
     });
-    remediations.push("Inspect with: npx pm2 jlist | grep agent-" + agentId);
+    remediations.push(`Inspect with: ${packageRunner()} pm2 jlist | grep agent-${agentId}`);
   }
   if (usesPm2 && pm2Procs) {
     const slotPrefix = `har-${projectName}-agent-${agentId}-`;
@@ -30008,7 +30030,7 @@ function formatPreflightReport(agentId, readiness) {
   }
   return lines2.join("\n");
 }
-var path16, import_child_process6;
+var path16, import_child_process7;
 var init_slot_preflight = __esm({
   "src/core/slot-preflight.ts"() {
     "use strict";
@@ -30019,14 +30041,15 @@ var init_slot_preflight = __esm({
     init_slot_launch_guard_occupied();
     init_slot_ports();
     init_slot_registry();
-    import_child_process6 = require("child_process");
+    import_child_process7 = require("child_process");
+    init_package_runner();
   }
 });
 
 // src/core/slot-status.ts
 function readGitRemote(repoPath) {
   try {
-    const remote = (0, import_child_process7.execSync)("git remote get-url origin", {
+    const remote = (0, import_child_process8.execSync)("git remote get-url origin", {
       cwd: repoPath,
       encoding: "utf8",
       stdio: ["pipe", "pipe", "ignore"]
@@ -30038,7 +30061,7 @@ function readGitRemote(repoPath) {
 }
 function runGit2(cwd, args) {
   try {
-    return (0, import_child_process7.execSync)(`git ${args}`, {
+    return (0, import_child_process8.execSync)(`git ${args}`, {
       cwd,
       encoding: "utf8",
       stdio: ["pipe", "pipe", "ignore"]
@@ -30114,7 +30137,7 @@ function lastBuildPass(run2) {
 }
 function listPm2Processes2() {
   try {
-    const raw = (0, import_child_process7.execSync)("npx --yes pm2 jlist", {
+    const raw = (0, import_child_process8.execSync)(`${packageRunner()} pm2 jlist`, {
       encoding: "utf8",
       stdio: ["pipe", "pipe", "ignore"],
       timeout: 3e3
@@ -30217,14 +30240,14 @@ function collectEnvironmentStatus(repoPath) {
     generatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
 }
-var fs16, os6, path17, import_child_process7, BYPASS_WARNING_MS;
+var fs16, os6, path17, import_child_process8, BYPASS_WARNING_MS;
 var init_slot_status = __esm({
   "src/core/slot-status.ts"() {
     "use strict";
     fs16 = __toESM(require("fs"));
     os6 = __toESM(require("os"));
     path17 = __toESM(require("path"));
-    import_child_process7 = require("child_process");
+    import_child_process8 = require("child_process");
     init_env();
     init_manifest();
     init_stages();
@@ -30232,6 +30255,7 @@ var init_slot_status = __esm({
     init_runs();
     init_slot_registry();
     init_slot_preflight();
+    init_package_runner();
     BYPASS_WARNING_MS = 15 * 60 * 1e3;
   }
 });
@@ -31227,11 +31251,11 @@ function buildTelemetryEnvBlock(attrs) {
   const lines2 = [
     "",
     "# HAR session attribution (generated)",
-    `HAR_SESSION_KEY=${attrs.sessionKey}`,
-    ...attrs.workUnitId ? [`HAR_WORK_UNIT_ID=${attrs.workUnitId}`] : [],
-    ...attrs.attemptId ? [`HAR_ATTEMPT_ID=${attrs.attemptId}`] : [],
-    `HAR_CONTROL_API_URL=${apiUrl}`,
-    `OTEL_RESOURCE_ATTRIBUTES=${buildOtelResourceAttributes(attrs)}`,
+    `HAR_SESSION_KEY=${quoteShellArg(attrs.sessionKey)}`,
+    ...attrs.workUnitId ? [`HAR_WORK_UNIT_ID=${quoteShellArg(attrs.workUnitId)}`] : [],
+    ...attrs.attemptId ? [`HAR_ATTEMPT_ID=${quoteShellArg(attrs.attemptId)}`] : [],
+    `HAR_CONTROL_API_URL=${quoteShellArg(apiUrl)}`,
+    `OTEL_RESOURCE_ATTRIBUTES=${quoteShellArg(buildOtelResourceAttributes(attrs))}`,
     "# Agent telemetry: @osfactory/otel-hook \u2192 Mission Control (har telemetry on|off)"
   ];
   return lines2.join("\n") + "\n";
@@ -31264,6 +31288,7 @@ var init_telemetry_env = __esm({
     fs20 = __toESM(require("fs"));
     path21 = __toESM(require("path"));
     init_control_config();
+    init_shell();
     TELEMETRY_MARKER_START = "# HAR session attribution (generated)";
     TELEMETRY_MARKER_END = "# end HAR telemetry";
   }
@@ -53489,8 +53514,8 @@ exec "${otelHookCommand}" run \\
   }
   return wrapperPath;
 }
-function commandExists2(command2) {
-  const result = (0, import_child_process10.spawnSync)("sh", ["-c", `command -v ${JSON.stringify(command2)}`], {
+function commandExists3(command2) {
+  const result = (0, import_child_process11.spawnSync)("sh", ["-c", `command -v ${JSON.stringify(command2)}`], {
     encoding: "utf8"
   });
   return result.status === 0 && Boolean(result.stdout?.trim());
@@ -53500,25 +53525,37 @@ function resolveOtelHookCommand(hooksHome) {
   if (fs41.existsSync(local)) return local;
   return null;
 }
+function resolveHooksInstaller(hooksHome) {
+  const candidates = [
+    {
+      command: "npm",
+      args: ["install", "--prefix", hooksHome, "--no-fund", "--no-audit", OTEL_HOOKS_PACKAGE]
+    },
+    { command: "bun", args: ["add", "--cwd", hooksHome, OTEL_HOOKS_PACKAGE] },
+    { command: "pnpm", args: ["add", "--dir", hooksHome, OTEL_HOOKS_PACKAGE] }
+  ];
+  return candidates.find((candidate) => commandExists3(candidate.command)) ?? null;
+}
 function tryInstallPackage(hooksHome) {
   fs41.mkdirSync(hooksHome, { recursive: true });
-  if (!commandExists2("npm")) {
+  const installer = resolveHooksInstaller(hooksHome);
+  if (!installer) {
     return {
       ok: false,
-      detail: "npm not found; install Node.js to use @osfactory/otel-hook"
+      detail: "no package manager found; install Node.js or bun to use @osfactory/otel-hook"
     };
   }
-  const result = (0, import_child_process10.spawnSync)(
-    "npm",
-    ["install", "--prefix", hooksHome, "--no-fund", "--no-audit", OTEL_HOOKS_PACKAGE],
-    { encoding: "utf8", timeout: 18e4 }
-  );
+  const described = `${installer.command} ${installer.args.join(" ")}`;
+  const result = (0, import_child_process11.spawnSync)(installer.command, installer.args, {
+    encoding: "utf8",
+    timeout: 18e4
+  });
   if (result.status === 0 && fs41.existsSync(localOtelHookBin(hooksHome))) {
-    return { ok: true, detail: `npm install --prefix ${hooksHome} ${OTEL_HOOKS_PACKAGE}` };
+    return { ok: true, detail: described };
   }
   return {
     ok: false,
-    detail: `npm install ${OTEL_HOOKS_PACKAGE} failed: ${(result.stderr || result.stdout || "").trim().slice(0, 400)}`
+    detail: `${described} failed: ${(result.stderr || result.stdout || "").trim().slice(0, 400)}`
   };
 }
 function uninstallLegacyPythonHooks(hooksHome) {
@@ -53529,9 +53566,9 @@ function uninstallLegacyPythonHooks(hooksHome) {
     ["pip3", ["uninstall", "-y", "opentelemetry-hooks"]]
   ];
   for (const [cmd, args] of attempts) {
-    if (!commandExists2(cmd)) continue;
+    if (!commandExists3(cmd)) continue;
     try {
-      (0, import_child_process10.spawnSync)(cmd, args, { encoding: "utf8", timeout: 6e4 });
+      (0, import_child_process11.spawnSync)(cmd, args, { encoding: "utf8", timeout: 6e4 });
     } catch {
     }
   }
@@ -53563,7 +53600,7 @@ function normalizeLegacyProviderFlagsInCommand(command2) {
 }
 function runSetupProvider(providerId, otelHookCommand, wrapperPath) {
   const hookCommand = `${wrapperPath} --provider ${providerId}`;
-  const result = (0, import_child_process10.spawnSync)(
+  const result = (0, import_child_process11.spawnSync)(
     otelHookCommand,
     [
       "setup",
@@ -53804,11 +53841,11 @@ function ensureOtelHooks(options) {
 function disableOtelHooksExport() {
   return writeOtelHooksConfig(buildOtelHooksConfig({ enabled: false }));
 }
-var import_child_process10, fs41, os15, path47, OTEL_HOOKS_PACKAGE, OTEL_HOOKS_PROVIDERS, OTEL_HOOKS_AGENTS, LEGACY_CURSOR_ONLY_HOOK_EVENTS;
+var import_child_process11, fs41, os15, path47, OTEL_HOOKS_PACKAGE, OTEL_HOOKS_PROVIDERS, OTEL_HOOKS_AGENTS, LEGACY_CURSOR_ONLY_HOOK_EVENTS;
 var init_otel_hooks = __esm({
   "src/core/otel-hooks.ts"() {
     "use strict";
-    import_child_process10 = require("child_process");
+    import_child_process11 = require("child_process");
     fs41 = __toESM(require("fs"));
     os15 = __toESM(require("os"));
     path47 = __toESM(require("path"));
@@ -70177,13 +70214,13 @@ var path44 = __toESM(require("path"));
 var readline5 = __toESM(require("readline"));
 
 // src/utils/clipboard.ts
-var import_child_process8 = require("child_process");
-function commandExists(command2) {
-  const probe = process.platform === "win32" ? (0, import_child_process8.spawnSync)("where", [command2], { encoding: "utf8", stdio: ["ignore", "ignore", "ignore"] }) : (0, import_child_process8.spawnSync)("which", [command2], { encoding: "utf8", stdio: ["ignore", "ignore", "ignore"] });
+var import_child_process9 = require("child_process");
+function commandExists2(command2) {
+  const probe = process.platform === "win32" ? (0, import_child_process9.spawnSync)("where", [command2], { encoding: "utf8", stdio: ["ignore", "ignore", "ignore"] }) : (0, import_child_process9.spawnSync)("which", [command2], { encoding: "utf8", stdio: ["ignore", "ignore", "ignore"] });
   return probe.status === 0;
 }
 function tryPipeCommand(command2, args, text) {
-  const result = (0, import_child_process8.spawnSync)(command2, args, {
+  const result = (0, import_child_process9.spawnSync)(command2, args, {
     input: text,
     encoding: "utf8",
     stdio: ["pipe", "ignore", "ignore"]
@@ -70198,12 +70235,12 @@ function writeOsc52Clipboard(text, stream = process.stderr) {
   return true;
 }
 function copyViaPlatformTools(text) {
-  if (process.platform === "darwin" && commandExists("pbcopy")) {
+  if (process.platform === "darwin" && commandExists2("pbcopy")) {
     if (tryPipeCommand("pbcopy", [], text)) return { ok: true, method: "pbcopy" };
   }
   if (process.platform === "win32") {
-    if (commandExists("powershell")) {
-      const result = (0, import_child_process8.spawnSync)(
+    if (commandExists2("powershell")) {
+      const result = (0, import_child_process9.spawnSync)(
         "powershell",
         [
           "-NoProfile",
@@ -70219,18 +70256,18 @@ function copyViaPlatformTools(text) {
       );
       if (result.status === 0 && !result.error) return { ok: true, method: "powershell" };
     }
-    if (commandExists("clip") && tryPipeCommand("clip", [], text)) {
+    if (commandExists2("clip") && tryPipeCommand("clip", [], text)) {
       return { ok: true, method: "clip" };
     }
   }
   if (process.platform === "linux" || process.platform === "freebsd" || process.platform === "openbsd") {
-    if (commandExists("wl-copy") && tryPipeCommand("wl-copy", [], text)) {
+    if (commandExists2("wl-copy") && tryPipeCommand("wl-copy", [], text)) {
       return { ok: true, method: "wl-copy" };
     }
-    if (commandExists("xclip") && tryPipeCommand("xclip", ["-selection", "clipboard"], text)) {
+    if (commandExists2("xclip") && tryPipeCommand("xclip", ["-selection", "clipboard"], text)) {
       return { ok: true, method: "xclip" };
     }
-    if (commandExists("xsel") && tryPipeCommand("xsel", ["--clipboard", "--input"], text)) {
+    if (commandExists2("xsel") && tryPipeCommand("xsel", ["--clipboard", "--input"], text)) {
       return { ok: true, method: "xsel" };
     }
   }
@@ -70449,7 +70486,7 @@ init_validation();
 init_control_config();
 
 // src/core/control-lifecycle.ts
-var import_child_process9 = require("child_process");
+var import_child_process10 = require("child_process");
 var path46 = __toESM(require("path"));
 
 // src/core/control-image.ts
@@ -70502,7 +70539,7 @@ function buildDockerRunArgs(options) {
   return args;
 }
 function runDocker(args) {
-  const result = (0, import_child_process9.spawnSync)("docker", args, {
+  const result = (0, import_child_process10.spawnSync)("docker", args, {
     stdio: "inherit",
     env: process.env
   });
@@ -70512,7 +70549,7 @@ function runDocker(args) {
   return result.status ?? 1;
 }
 function controlContainerExists(name = CONTROL_CONTAINER_NAME) {
-  const result = (0, import_child_process9.spawnSync)("docker", ["ps", "-aq", "-f", `name=^${name}$`], {
+  const result = (0, import_child_process10.spawnSync)("docker", ["ps", "-aq", "-f", `name=^${name}$`], {
     encoding: "utf8",
     stdio: ["pipe", "pipe", "ignore"]
   });
@@ -72352,13 +72389,13 @@ init_portal_credentials();
 // src/core/portal-login.ts
 var http = __toESM(require("http"));
 var import_crypto = require("crypto");
-var import_child_process11 = require("child_process");
+var import_child_process12 = require("child_process");
 var CALLBACK_PATH = "/callback";
 var LOGIN_TIMEOUT_MS = 3 * 6e4;
 function openBrowser(url) {
   const [cmd, args] = process.platform === "darwin" ? ["open", [url]] : process.platform === "win32" ? ["cmd", ["/c", "start", "", url]] : ["xdg-open", [url]];
   try {
-    const child = (0, import_child_process11.spawn)(cmd, args, { stdio: "ignore", detached: true });
+    const child = (0, import_child_process12.spawn)(cmd, args, { stdio: "ignore", detached: true });
     child.on("error", () => {
     });
     child.unref();
@@ -73518,7 +73555,7 @@ __export(util_exports, {
   assertNever: () => assertNever,
   assertNotEqual: () => assertNotEqual,
   assignProp: () => assignProp,
-  cached: () => cached,
+  cached: () => cached2,
   captureStackTrace: () => captureStackTrace,
   cleanEnum: () => cleanEnum,
   cleanRegex: () => cleanRegex,
@@ -73583,7 +73620,7 @@ function jsonStringifyReplacer(_2, value) {
     return value.toString();
   return value;
 }
-function cached(getter) {
+function cached2(getter) {
   const set = false;
   return {
     get value() {
@@ -73672,7 +73709,7 @@ var captureStackTrace = Error.captureStackTrace ? Error.captureStackTrace : (...
 function isObject(data) {
   return typeof data === "object" && data !== null && !Array.isArray(data);
 }
-var allowsEval = cached(() => {
+var allowsEval = cached2(() => {
   if (typeof navigator !== "undefined" && navigator?.userAgent?.includes("Cloudflare")) {
     return false;
   }
@@ -75167,7 +75204,7 @@ function handleOptionalObjectResult(result, final, key, input) {
 }
 var $ZodObject = /* @__PURE__ */ $constructor("$ZodObject", (inst, def) => {
   $ZodType.init(inst, def);
-  const _normalized = cached(() => {
+  const _normalized = cached2(() => {
     const keys = Object.keys(def.shape);
     for (const k of keys) {
       if (!(def.shape[k] instanceof $ZodType)) {
@@ -75402,7 +75439,7 @@ var $ZodDiscriminatedUnion = /* @__PURE__ */ $constructor("$ZodDiscriminatedUnio
     }
     return propValues;
   });
-  const disc = cached(() => {
+  const disc = cached2(() => {
     const opts = def.options;
     const map = /* @__PURE__ */ new Map();
     for (const o of opts) {

package/dist/templates/adaptation-prompt-init.md

@@ -69,6 +69,11 @@ how this project is built and tested. Use toolchain variables from `.env.agent.<
 The stock verify section is keyed by `HARNESS_ECOSYSTEM`; it is a starting point,
 not the repo's final contract. Replace conventions that do not match this project.
 
+`${NPM_BIN}` may resolve to bun, pnpm, or yarn as well as npm, so keep Node steps
+package-manager agnostic: always `${NPM_BIN:-npm} run <script>` (never bare
+`${NPM_BIN} test`, which runs bun's own test runner), and never npm-only flags
+such as `--prefix` — use a subshell like `(cd docs && ${NPM_BIN:-npm} run build)`.
+
 **Tier contract:**
 
 | Mode | Command | Intent |

package/dist/templates/adaptation-prompt-maintain.md

@@ -25,7 +25,7 @@ Prefer targeted edits over full rewrites. Key files to review:
 Keep this accurate — it is the harness index. Update whenever scripts, stages, or workflow change.
 
 ### `.har/harness.env`, `verify.sh`, `provision-toolchain.sh`, `ecosystem.agent.template.cjs`, `CLAUDE.agent.md`
-Align commands and instructions with the current stack. Verify steps must use toolchain paths from `.env.agent.<id>` (`PYTHON_BIN`, `NPM_BIN`, `XCODEBUILD_BIN`, …) — never hardcoded venv or interpreter paths. Replace stock ecosystem conventions that do not match the repository; do not leave npm/pytest/go/cargo/maven/gradle examples in place by accident.
+Align commands and instructions with the current stack. Verify steps must use toolchain paths from `.env.agent.<id>` (`PYTHON_BIN`, `NPM_BIN`, `XCODEBUILD_BIN`, …) — never hardcoded venv or interpreter paths. `NPM_BIN` may be bun, pnpm, or yarn, so Node steps must use `${NPM_BIN:-npm} run <script>` and avoid npm-only flags such as `--prefix`. Replace stock ecosystem conventions that do not match the repository; do not leave npm/pytest/go/cargo/maven/gradle examples in place by accident.
 
 ### `.har/env.template`, `setup-infra.sh`, `docker-compose.agent.yml`
 Update only if infra changed.

package/dist/templates/har-boilerplate/agent-cli.sh

@@ -28,7 +28,7 @@ case "$COMMAND" in
     ENV_FILE="$(resolve_agent_env_file "$AGENT_ID" "$REPO_ROOT" || true)"
     WORKTREE_DIR="$(existing_slot_worktree "$AGENT_ID")"
     REG_FILE="$(slot_registry_file "$AGENT_ID")"
-    PM2_RAW=$(npx --yes pm2 jlist 2>/dev/null || true)
+    PM2_RAW=$($(har_pkg_exec) pm2 jlist 2>/dev/null || true)
     PM2_FOUND=false
     PM2_FOREIGN=false
     PM2_LEGACY=false
@@ -123,22 +123,23 @@ process.stdin.on('end', () => {
   logs)
     SERVICE="${3:-}"
     if [ -n "$SERVICE" ]; then
-      npx pm2 logs "${PM2_SLOT_PREFIX}-${SERVICE}" --lines 100
+      $(har_pkg_exec) pm2 logs "${PM2_SLOT_PREFIX}-${SERVICE}" --lines 100
     else
-      npx pm2 logs --name "${PM2_SLOT_PREFIX}" --lines 100
+      $(har_pkg_exec) pm2 logs --name "${PM2_SLOT_PREFIX}" --lines 100
     fi
     ;;
 
   restart)
     SERVICE="${3:-}"
+    PKG_EXEC="$(har_pkg_exec)"
     if [ -n "$SERVICE" ]; then
-      npx pm2 restart "${PM2_SLOT_PREFIX}-${SERVICE}"
+      $(har_pkg_exec) pm2 restart "${PM2_SLOT_PREFIX}-${SERVICE}"
     else
-      npx pm2 jlist 2>/dev/null | node -e "
+      $(har_pkg_exec) pm2 jlist 2>/dev/null | node -e "
 const prefix = '${PM2_SLOT_PREFIX}-';
 const d = JSON.parse(require('fs').readFileSync('/dev/stdin','utf8'));
 const names = d.filter(x => x.name && x.name.startsWith(prefix)).map(x => x.name);
-names.forEach(n => require('child_process').execSync('npx pm2 restart ' + n, {stdio:'inherit'}));
+names.forEach(n => require('child_process').execSync('${PKG_EXEC} pm2 restart ' + n, {stdio:'inherit'}));
 if (names.length === 0) console.log('No processes found for ${PM2_SLOT_PREFIX}');
 " 2>/dev/null || true
     fi

package/dist/templates/har-boilerplate/agent-slot.sh

@@ -184,7 +184,7 @@ har_check_foreign_pm2() {
   local agent_id="$1"
   local pm2_raw
   har_harness_uses_pm2 || return 0
-  pm2_raw="$(npx --yes pm2 jlist 2>/dev/null || true)"
+  pm2_raw="$($(har_pkg_exec) pm2 jlist 2>/dev/null || true)"
   [ -n "$pm2_raw" ] || return 0
   set +e
   echo "$pm2_raw" | node -e "

package/dist/templates/har-boilerplate/harness.env

@@ -51,6 +51,10 @@ export HARNESS_AGENT_SLOT_MAX=5
 # Ecosystem: auto (detect from manifests) | node | python | go | rust | java | ruby | none
 export HARNESS_ECOSYSTEM="auto"
 # export HARNESS_INSTALL_CMD="make deps"
+# Node package manager: auto-detected from package.json "packageManager" and the
+# lockfile (bun.lock → bun, pnpm-lock.yaml → pnpm, yarn.lock → yarn, else npm),
+# falling back to whichever is installed. Set to pin one: npm | bun | pnpm | yarn
+# export HARNESS_NODE_PACKAGE_MANAGER="bun"
 
 # Shared infrastructure — space-separated docker compose service names from
 # docker-compose.agent.yml. Started ONCE by setup-infra.sh and shared by all
@@ -66,6 +70,119 @@ har_infra_enabled() {
   esac
 }
 
+# ── Node package manager helpers ──────────────────────────────────────────────
+# Mirrored verbatim in harness.env and provision-toolchain.sh so a sourcing
+# script and the provisioning subprocess resolve the same tool.
+
+# Package managers HAR can drive, in fallback preference order.
+HAR_NODE_PACKAGE_MANAGERS="npm bun pnpm yarn"
+
+# Package manager the repo declares: an explicit HARNESS_NODE_PACKAGE_MANAGER
+# wins, then package.json "packageManager", then the lockfile. Empty when the
+# repo says nothing.
+har_node_declared_package_manager() {
+  local dir="${1:-.}"
+
+  if [ -n "${HARNESS_NODE_PACKAGE_MANAGER:-}" ]; then
+    echo "$HARNESS_NODE_PACKAGE_MANAGER"
+    return
+  fi
+  if [ -f "$dir/package.json" ]; then
+    local field
+    field="$(sed -n 's/.*"packageManager"[[:space:]]*:[[:space:]]*"\([a-z]*\)@.*/\1/p' "$dir/package.json" | head -1)"
+    if [ -n "$field" ]; then
+      echo "$field"
+      return
+    fi
+  fi
+  if [ -f "$dir/bun.lock" ] || [ -f "$dir/bun.lockb" ]; then echo bun; return; fi
+  if [ -f "$dir/pnpm-lock.yaml" ]; then echo pnpm; return; fi
+  if [ -f "$dir/yarn.lock" ]; then echo yarn; return; fi
+  if [ -f "$dir/package-lock.json" ]; then echo npm; return; fi
+  echo ""
+}
+
+# Package manager to actually run. A manager the repo declares but this machine
+# lacks falls back to one that is installed, so a repo pinned to npm still
+# provisions on a bun-only machine (and the reverse).
+har_node_package_manager() {
+  local dir="${1:-.}"
+  local declared
+  declared="$(har_node_declared_package_manager "$dir")"
+
+  if [ -n "$declared" ] && command -v "$declared" >/dev/null 2>&1; then
+    echo "$declared"
+    return
+  fi
+
+  local candidate
+  for candidate in $HAR_NODE_PACKAGE_MANAGERS; do
+    if command -v "$candidate" >/dev/null 2>&1; then
+      echo "$candidate"
+      return
+    fi
+  done
+
+  echo "${declared:-npm}"
+}
+
+# Lockfile a manager writes, so a substitute install can clean up after itself.
+har_node_lockfile() {
+  case "$1" in
+    bun) echo "bun.lock" ;;
+    npm) echo "package-lock.json" ;;
+    pnpm) echo "pnpm-lock.yaml" ;;
+    yarn) echo "yarn.lock" ;;
+    *) echo "" ;;
+  esac
+}
+
+# Install dependencies in a directory. When a substitute manager stands in for
+# the one the repo declares, any lockfile it creates is removed afterwards:
+# provisioning must not migrate the repo to a different package manager.
+# (bun writes bun.lock even under --no-save, so the flags alone are not enough.)
+har_node_install() {
+  local dir="$1"
+  local manager="$2"
+  local declared="${3:-}"
+  local substituting=false
+  local lockfile=""
+  local had_lockfile=false
+
+  if [ -n "$declared" ] && [ "$declared" != "$manager" ]; then
+    substituting=true
+    lockfile="$(har_node_lockfile "$manager")"
+    if [ -n "$lockfile" ] && [ -e "$dir/$lockfile" ]; then
+      had_lockfile=true
+    fi
+  fi
+
+  local code=0
+  (cd "$dir" && "$manager" install --silent) || code=$?
+
+  if [ "$substituting" = true ] && [ "$had_lockfile" = false ] && [ -n "$lockfile" ]; then
+    rm -f "$dir/$lockfile"
+    [ "$manager" = "bun" ] && rm -f "$dir/bun.lockb"
+  fi
+  return $code
+}
+
+# Package runner (npx equivalent) for one-off CLIs such as pm2, including the
+# flag that keeps it non-interactive. Takes a manager name, or none to resolve
+# from the environment and PATH.
+har_pkg_exec() {
+  case "${1:-${HARNESS_NODE_PACKAGE_MANAGER:-}}" in
+    bun) echo "bunx"; return ;;
+    pnpm) echo "pnpm dlx"; return ;;
+    yarn) echo "yarn dlx"; return ;;
+    npm) echo "npx --yes"; return ;;
+  esac
+  if command -v npx >/dev/null 2>&1; then echo "npx --yes"; return; fi
+  if command -v bunx >/dev/null 2>&1; then echo "bunx"; return; fi
+  if command -v pnpm >/dev/null 2>&1; then echo "pnpm dlx"; return; fi
+  echo "npx --yes"
+}
+
 # Postgres client — uses host tools when installed, otherwise docker exec into
 # the shared db container. Usage: har_pg psql -d postgres -c "SELECT 1"
 #                                 har_pg createdb -T template_x agent_1

package/dist/templates/har-boilerplate/launch.sh

@@ -249,13 +249,13 @@ DEBUG_PORT="$DEBUG_PORT" \
 
 PM2_REGEX="$(har_pm2_delete_regex "$AGENT_ID")"
 # Stop existing processes for this agent (project-scoped — never touch other harnesses).
-npx --yes pm2 delete "$PM2_REGEX" 2>/dev/null || true
+$(har_pkg_exec) pm2 delete "$PM2_REGEX" 2>/dev/null || true
 
 # Start PM2 processes
 log "Starting PM2 processes..."
 cd "$WORK_DIR"
-npx pm2 start "$ECOSYSTEM_FILE"
-npx pm2 save --force >/dev/null 2>&1 || true
+$(har_pkg_exec) pm2 start "$ECOSYSTEM_FILE"
+$(har_pkg_exec) pm2 save --force >/dev/null 2>&1 || true
 
 # Health check
 if [ -n "${HARNESS_HEALTH_CHECK_PATH:-}" ]; then