mixdog 0.7.5 → 0.7.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.7.5",
+  "version": "0.7.6",
   "description": "Claude Code all-in-one agent plugin — autonomous agents, continuous memory, cost-aware sub-agents, and syntax-aware code editing.",
   "hooks": "./hooks/hooks.json",
   "mcpServers": {

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 Notable changes are tracked per release, starting at 0.7.1.
 
+## 0.7.7 — 2026-06-18
+
+- Add in-app OAuth sign-in for the Codex (`openai-oauth`) and Claude
+  (`anthropic-oauth`) providers, mirroring the existing Grok login: the
+  Setup UI can sign in directly when no CLI credentials are detected.
+- `npx mixdog` (no args) now runs the installer directly; `mixdog install`
+  and `mixdog install --dry-run` (a no-side-effect install preview) are the
+  install/test entry points. Any other args launch Claude Code.
+- Add a Claude Code CLI preflight to setup: if `claude` is missing, offer to
+  run the official native installer (consent-prompted; never in CI).
+- Polished terminal setup wizard: arrow-key menus, checkboxes, progress bars,
+  and spinners (zero-dependency, grapheme/CJK-aware) replace the plain prompts.
+- Bridge workers stay visible in the statusline correctly: completed workers
+  persist as idle for 1h (was swept at 5 min), and worker scoping survives a
+  daemon restart (clientHostPid instead of the volatile owner-session id).
+- Fix `bridge list includeClosed:true` so closed-session tombstones are
+  actually returned.
+
 ## 0.7.1 — 2026-06-12
 
 Initial versioned release.

package/README.md

@@ -48,6 +48,24 @@ as JSON you can diff.
 
 ## Install
 
+**From npm (terminal):**
+
+```bash
+npx mixdog                # register plugin + run the setup wizard
+mixdog install            # same install + wizard (explicit subcommand)
+mixdog install --dry-run  # preview install steps (no writes, prompts, or installs)
+npm i -g mixdog           # then launch Claude Code with mixdog pre-loaded:
+mixdog                    # no args → same setup wizard as `npx mixdog`
+mixdog --version          # other args (e.g. `setup`) → claude --dangerously-load-development-channels plugin:mixdog@trib-plugin …
+mixdog --dangerously-skip-permissions   # extra Claude flags pass through
+```
+
+With no arguments, or with `install` (optional `--dry-run`), `mixdog` runs the
+install flow. Any other arguments start Claude Code with mixdog pre-loaded; the
+`claude` CLI must be on your PATH.
+
+**Inside Claude Code (slash commands):**
+
 ```
 /plugin marketplace add trib-plugin/mixdog
 /plugin install mixdog@trib-plugin

package/hooks/hooks.json

@@ -7,17 +7,17 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\" --part=rules",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\" --part=rules",
             "timeout": 30
           },
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\" --part=core",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\" --part=core",
             "timeout": 130
           },
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\" --part=recap",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\" --part=recap",
             "timeout": 130
           }
         ]
@@ -29,7 +29,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\"",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\"",
             "timeout": 10
           }
         ]
@@ -41,7 +41,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "\"${CLAUDE_PLUGIN_ROOT}/native/mixdog-shim/target/release/mixdog-shim.exe\" --kind=post-tool",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/shim-launcher.cjs\" --kind=post-tool",
             "timeout": 5
           }
         ]
@@ -70,4 +70,4 @@
       }
     ]
   }
-}
+}

package/hooks/session-start.cjs

@@ -508,6 +508,77 @@ function resolveTranscriptPath() {
   return '';
 }
 
+// Prior-session transcript for the ingest-watermark barrier on `/clear`.
+// SessionStart carries the NEW session_id; rules-part rebind records the
+// outgoing path in active-instance.json `priorTranscriptPath` before updating
+// `transcriptPath`. Resolution is deterministic (no mtime scan).
+function resolvePriorTranscriptPath() {
+  const sessionId = String(_event.session_id || _event.sessionId || '').trim();
+  const active = readJson(ACTIVE_INSTANCE_FILE);
+  const tp = active && active.transcriptPath;
+  if (typeof tp === 'string' && tp && fs.existsSync(tp)) {
+    const base = path.basename(tp, '.jsonl');
+    if (sessionId && base !== sessionId) return tp;
+  }
+  const prior = active && active.priorTranscriptPath;
+  if (typeof prior === 'string' && prior && fs.existsSync(prior)) {
+    const base = path.basename(prior, '.jsonl');
+    if (sessionId && base !== sessionId) return prior;
+  }
+  return '';
+}
+
+// Poll memory-service until offsetBytes >= fileSize for the prior transcript,
+// bounded by a dedicated sub-budget so cycle1 keeps a floor of the grace window.
+async function awaitPriorTranscriptIngested(deadline, opts = {}) {
+  const slot = opts.slot || 'unknown';
+  const start = Date.now();
+  const windowMs = Math.max(0, deadline - start);
+  // ~4s cap on the 8s graceMs case; smaller windows get half — cycle1 retains the rest.
+  const BARRIER_BUDGET_MS = Math.min(4000, windowMs / 2);
+  const barrierDeadline = Math.min(deadline, start + BARRIER_BUDGET_MS);
+  const priorPath = resolvePriorTranscriptPath();
+  if (!priorPath) {
+    teeStderr(`[session-start] ingest-barrier slot=${slot} skip reason=no-prior-transcript source=${_event.source || ''}\n`);
+    return;
+  }
+  teeStderr(`[session-start] ingest-barrier slot=${slot} priorPath=${priorPath}\n`);
+  const pollMs = 200;
+  while (Date.now() < barrierDeadline) {
+    const remaining = barrierDeadline - Date.now();
+    if (remaining <= 0) break;
+    const port = await getLiveMemoryServicePort(Math.min(200, remaining));
+    if (!port) {
+      await sleepMs(Math.min(pollMs, remaining));
+      continue;
+    }
+    try {
+      const res = await httpPostJson({
+        hostname: '127.0.0.1',
+        port,
+        path: '/transcript/ingest-sync',
+        timeoutMs: Math.min(5000, remaining),
+        body: { path: priorPath, cwd: _event.cwd || process.cwd() },
+      });
+      if (res.statusCode === 200) {
+        let parsed;
+        try { parsed = JSON.parse(res.body); } catch { parsed = null; }
+        if (parsed && parsed.ok === true && parsed.complete === true) {
+          teeStderr(`[session-start] ingest-barrier slot=${slot} complete offsetBytes=${parsed.offsetBytes} fileSize=${parsed.fileSize} elapsed=${Date.now() - start}ms\n`);
+          return;
+        }
+        if (parsed && parsed.ok === true) {
+          teeStderr(`[session-start] ingest-barrier slot=${slot} pending offsetBytes=${parsed.offsetBytes} fileSize=${parsed.fileSize}\n`);
+        }
+      }
+    } catch (e) {
+      teeStderr(`[session-start] ingest-barrier slot=${slot} err=${(e && e.message) || e}\n`);
+    }
+    await sleepMs(Math.min(pollMs, Math.max(0, barrierDeadline - Date.now())));
+  }
+  teeStderr(`[session-start] ingest-barrier slot=${slot} deadline-reached proceed elapsed=${Date.now() - start}ms\n`);
+}
+
 function rebindActiveInstance() {
   try {
     const activePath = ACTIVE_INSTANCE_FILE;
@@ -1071,6 +1142,7 @@ async function requestCycle1(timeoutMs, opts = {}) {
   const transientDeadline = start + TRANSIENT_RETRY_BUDGET_MS;
 
   try {
+    await awaitPriorTranscriptIngested(deadline, opts);
     let r1 = await requestCycle1Once(deadline, opts);
     let transientAttempt = 0;
     while (
@@ -1085,8 +1157,7 @@ async function requestCycle1(timeoutMs, opts = {}) {
     }
     if (!r1.ok) return r1;
     if (r1.processed != null && r1.processed > 0) return r1;
-    // Genuine empty (no pending raw rows AND no in-flight dedup hit) — retry
-    // would do nothing useful, skip the second pass.
+    // After ingest-barrier, pendingRows===0 with no in-flight dedup is terminal.
     if (r1.pendingRows === 0 && r1.skippedInFlight === false) return r1;
     const RETRY_DELAY_MS = 800;
     const remaining = deadline - Date.now();

package/hooks/shim-launcher.cjs

@@ -0,0 +1,51 @@
+'use strict';
+
+const { spawnSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+const SHIM_ARCH_ALIAS = Object.freeze({
+  x64: 'x86_64',
+  arm64: 'aarch64',
+  ia32: 'i686',
+});
+
+function shimBinExt() {
+  return process.platform === 'win32' ? '.exe' : '';
+}
+
+function shimArchTag() {
+  const arch = SHIM_ARCH_ALIAS[process.arch] || process.arch;
+  const os = process.platform === 'win32' ? 'windows'
+    : process.platform === 'darwin' ? 'macos'
+    : 'linux';
+  return `${os}-${arch}`;
+}
+
+function resolveShim(pluginRoot) {
+  const ext = shimBinExt();
+  const name = 'mixdog-shim' + ext;
+  const candidates = [
+    path.join(pluginRoot, 'native', 'mixdog-shim', 'target', 'release', name),
+    path.join(pluginRoot, 'native', 'prebuilt', shimArchTag(), name),
+  ];
+  for (const candidate of candidates) {
+    try {
+      if (fs.existsSync(candidate)) return candidate;
+    } catch { /* ignore */ }
+  }
+  return null;
+}
+
+const pluginRoot = process.env.CLAUDE_PLUGIN_ROOT;
+if (!pluginRoot) process.exit(0);
+
+const shimPath = resolveShim(pluginRoot);
+if (!shimPath) process.exit(0);
+
+const child = spawnSync(shimPath, process.argv.slice(2), {
+  stdio: 'inherit',
+  windowsHide: true,
+});
+
+process.exit(child.status ?? 0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mixdog",
-  "version": "0.7.5",
+  "version": "0.7.7",
   "description": "Claude Code all-in-one bridge plugin: role-based bridge workers, continuous memory, and syntax-aware code editing.",
   "author": "mixdog contributors <dev@tribgames.com>",
   "license": "MIT",
@@ -9,7 +9,7 @@
   "bin": {
     "mcfg": "./setup/launch.mjs",
     "mixdog-install": "./setup/install.mjs",
-    "mixdog": "./setup/install.mjs"
+    "mixdog": "./setup/mixdog-cli.mjs"
   },
   "engines": {
     "bun": ">=1.1.0"

package/scripts/bootstrap.mjs

@@ -8,80 +8,26 @@
  * Deps: node built-ins only (node:child_process, node:fs, node:path, node:url, node:os).
  */
 import { spawnSync, spawn } from 'node:child_process';
-import { existsSync, readFileSync, writeFileSync, renameSync } from 'node:fs';
+import { readFileSync, writeFileSync, renameSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { prepShim } from './prep-shim.mjs';
 import { prepPatch } from './prep-patch.mjs';
+import { resolveBun, installBunViaNpm } from './resolve-bun.mjs';
 
 const scriptDir  = dirname(fileURLToPath(import.meta.url));
 const pluginRoot = dirname(scriptDir);
 const isWin      = process.platform === 'win32';
 
-// ---------------------------------------------------------------------------
-// Locate bun — returns absolute path or null.
-// ---------------------------------------------------------------------------
-function findSystemBun() {
-  const cmd = isWin ? 'where.exe' : 'which';
-  const r = spawnSync(cmd, ['bun'], { encoding: 'utf8', windowsHide: true });
-  if (r.status !== 0 || !r.stdout) return null;
-  const lines = r.stdout.split(/\r?\n/).map(l => l.trim()).filter(Boolean);
-  // On Windows `where bun` can list a .cmd/.ps1 shim before the real .exe;
-  // the downstream spawn is no-shell, so prefer an actual .exe when present.
-  const pick = isWin ? (lines.find(l => l.toLowerCase().endsWith('.exe')) ?? lines[0]) : lines[0];
-  if (!pick) return null;
-  return existsSync(pick) ? pick : null;
-}
-
-function findLocalBun() {
-  // After `npm install bun`, the .bin entry on Windows is a .cmd/.sh shim
-  // (not bun.exe), while the real binary lands in node_modules/bun/bin/. Check
-  // the package's own bin dir too — otherwise a clean-machine npm fallback can
-  // succeed yet resolveBun() still returns null and we exit "still not found".
-  const candidates = [
-    join(pluginRoot, 'node_modules', '.bin', isWin ? 'bun.exe' : 'bun'),
-    join(pluginRoot, 'node_modules', 'bun', 'bin', isWin ? 'bun.exe' : 'bun'),
-  ];
-  for (const p of candidates) if (existsSync(p)) return p;
-  return null;
-}
-
-function resolveBun() {
-  return findSystemBun() ?? findLocalBun();
-}
-
-// ---------------------------------------------------------------------------
-// npm-install bun locally if nothing found.
-// ---------------------------------------------------------------------------
-function installBunViaNpm() {
-  process.stderr.write(
-    '[bootstrap] bun not found on PATH — installing via npm (npm install --no-save --silent bun)...\n'
-  );
-  const r = spawnSync('npm', ['install', '--no-save', '--silent', 'bun'], {
-    cwd: pluginRoot,
-    stdio: 'inherit',
-    shell: false,
-    windowsHide: true,
-  });
-  if (r.status !== 0 || r.error) {
-    const hint = r.error ? ` (${r.error.message})` : '';
-    process.stderr.write(
-      `[bootstrap] npm install failed${hint}.\n` +
-      '[bootstrap] Please install bun manually: https://bun.sh\n'
-    );
-    process.exit(1);
-  }
-}
-
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
-let bunPath = resolveBun();
+let bunPath = resolveBun(pluginRoot);
 
 if (!bunPath) {
-  installBunViaNpm();
-  bunPath = resolveBun();
+  installBunViaNpm(pluginRoot);
+  bunPath = resolveBun(pluginRoot);
   if (!bunPath) {
     process.stderr.write(
       '[bootstrap] bun still not found after npm install.\n' +

package/scripts/ensure-deps.mjs

@@ -0,0 +1,259 @@
+/**
+ * ensure-deps.mjs — install or seed runtime deps into <dataDir>/.deps and stamp.
+ */
+import { createHash } from 'crypto';
+import { spawnSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import { dirname, join } from 'path';
+import { assertSafeOwnedDir } from '../src/shared/user-data-guard.mjs';
+
+const RENAME_RETRY_CODES = new Set(['EPERM', 'EACCES', 'EBUSY', 'EEXIST']);
+const RENAME_BACKOFFS_MS = Object.freeze([25, 50, 100, 200, 400, 800, 1200, 1600]);
+
+function sleepSync(ms) {
+  try {
+    const buf = new SharedArrayBuffer(4);
+    Atomics.wait(new Int32Array(buf), 0, 0, Math.max(1, Number(ms) || 1));
+  } catch {}
+}
+
+export function renameWithRetrySync(src, dst) {
+  let lastErr = null;
+  for (let attempt = 0; attempt <= RENAME_BACKOFFS_MS.length; attempt++) {
+    try {
+      fs.renameSync(src, dst);
+      return true;
+    } catch (err) {
+      lastErr = err;
+      if (!RENAME_RETRY_CODES.has(err?.code) || attempt >= RENAME_BACKOFFS_MS.length) break;
+      sleepSync(RENAME_BACKOFFS_MS[attempt] + Math.floor(Math.random() * 50));
+    }
+  }
+  throw lastErr;
+}
+
+const requiredDepNames = [
+  ['@modelcontextprotocol', 'sdk', 'package.json'],
+  ['zod', 'package.json'],
+  ['zod-to-json-schema', 'package.json'],
+  ['openai', 'package.json'],
+];
+
+export function hasRequiredDeps(nmDir) {
+  return requiredDepNames.every((parts) => fs.existsSync(join(nmDir, ...parts)));
+}
+
+/** Find hoisted node_modules (npx) that satisfies hasRequiredDeps. */
+export function resolveNmWithRequiredDeps(pluginRoot) {
+  let dir = pluginRoot;
+  for (let depth = 0; depth < 16; depth++) {
+    const nm = join(dir, 'node_modules');
+    if (hasRequiredDeps(nm)) return nm;
+    const parent = dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+const LOCK_POLL_MS = 250;
+const LOCK_MAX_MS = 15 * 60 * 1000;
+const LOCK_XHOST_MS = 10 * 60 * 1000;
+
+function acquireLock(lockFile) {
+  const start = Date.now();
+  while (Date.now() - start < LOCK_MAX_MS) {
+    try {
+      const body = JSON.stringify({
+        pid: process.pid,
+        hostname: os.hostname(),
+        startedAt: Date.now(),
+      });
+      fs.writeFileSync(lockFile, body, { flag: 'wx' });
+      return;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      try {
+        const raw = fs.readFileSync(lockFile, 'utf8');
+        const body = JSON.parse(raw);
+        const st = fs.statSync(lockFile);
+        const sameHost = body.hostname === os.hostname();
+        let dead = false;
+        if (sameHost) {
+          try { process.kill(body.pid, 0); }
+          catch (ke) { if (ke.code === 'ESRCH') dead = true; }
+        } else if (Date.now() - st.mtimeMs > LOCK_XHOST_MS) {
+          dead = true;
+        }
+        if (dead) fs.unlinkSync(lockFile);
+      } catch { /* lock may have been released — retry */ }
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, LOCK_POLL_MS);
+    }
+  }
+  throw new Error(
+    `timed out waiting for dependency install lock after ${LOCK_MAX_MS / 60000} minutes`,
+  );
+}
+
+function releaseLock(lockFile) {
+  try { fs.unlinkSync(lockFile); } catch {}
+}
+
+function sha256(buf) {
+  return createHash('sha256').update(buf).digest('hex');
+}
+
+export function computeDepHash(pkgJsonPath, pkgLockPath) {
+  if (fs.existsSync(pkgLockPath)) {
+    return sha256(fs.readFileSync(pkgLockPath));
+  }
+  const pkg = JSON.parse(fs.readFileSync(pkgJsonPath, 'utf8'));
+  const depKeys = ['dependencies', 'optionalDependencies', 'peerDependencies'];
+  const depObj = {};
+  for (const k of depKeys) {
+    if (pkg[k]) {
+      depObj[k] = Object.fromEntries(
+        Object.entries(pkg[k]).sort(([a], [b]) => a.localeCompare(b)),
+      );
+    }
+  }
+  return sha256(Buffer.from(JSON.stringify(depObj)));
+}
+
+const INSTALL_TIMEOUT_MS = 180_000;
+
+function resolveBunExec(bunPath) {
+  for (const p of [bunPath, process.env.BUN_EXEC_PATH]) {
+    if (p && typeof p === 'string' && fs.existsSync(p)) return p;
+  }
+  return null;
+}
+
+function depsAlreadySatisfied(stampPath, sharedNm, currentHash) {
+  let storedHash = '';
+  try { storedHash = fs.readFileSync(stampPath, 'utf8').trim(); } catch {}
+  return currentHash === storedHash && hasRequiredDeps(sharedNm);
+}
+
+function runFrozenLockfileInstall(bunExec, depsDir, stdio = 'inherit') {
+  return spawnSync(bunExec, ['install', '--frozen-lockfile'], {
+    cwd: depsDir,
+    stdio,
+    timeout: INSTALL_TIMEOUT_MS,
+    windowsHide: true,
+    encoding: stdio === 'pipe' ? 'utf8' : undefined,
+  });
+}
+
+/**
+ * @returns {{ satisfied: boolean, skipped?: boolean, method?: 'seed'|'install', reason?: string }}
+ */
+export function ensureRuntimeDeps({
+  dataDir,
+  pluginRoot,
+  bunPath,
+  seedNm,
+  logPrefix = '[run-mcp]',
+  /** @type {'inherit' | 'pipe' | 'ignore'} */
+  installStdio = 'inherit',
+}) {
+  const pluginPkg = join(pluginRoot, 'package.json');
+  const pluginLock = join(pluginRoot, 'bun.lock');
+
+  const depsDir = join(dataDir, '.deps');
+  const sharedPkg = join(depsDir, 'package.json');
+  const sharedLock = join(depsDir, 'bun.lock');
+  const sharedNm = join(depsDir, 'node_modules');
+  const stamp = join(depsDir, '.deps-stamp');
+  const stampTmp = join(depsDir, '.deps-stamp.tmp');
+  const lockFile = join(depsDir, '.install.lock');
+
+  const currentHash = computeDepHash(pluginPkg, pluginLock);
+  if (depsAlreadySatisfied(stamp, sharedNm, currentHash)) {
+    return { satisfied: true, skipped: true };
+  }
+
+  assertSafeOwnedDir(depsDir, dataDir, 'bun install');
+  fs.mkdirSync(depsDir, { recursive: true });
+  acquireLock(lockFile);
+  try {
+    if (depsAlreadySatisfied(stamp, sharedNm, currentHash)) {
+      return { satisfied: true, skipped: true };
+    }
+
+    fs.copyFileSync(pluginPkg, sharedPkg);
+    if (fs.existsSync(pluginLock)) fs.copyFileSync(pluginLock, sharedLock);
+
+    const bunExec = resolveBunExec(bunPath);
+
+    const canSeed = seedNm && hasRequiredDeps(seedNm);
+    if (canSeed) {
+      process.stderr.write(
+        `${logPrefix} seeding shared deps from ${seedNm} (skipping bun install)\n`,
+      );
+      fs.cpSync(seedNm, sharedNm, { recursive: true, force: true });
+      if (!bunExec) {
+        process.stderr.write(
+          `${logPrefix} bun not available — cannot validate seeded tree against lock\n`,
+        );
+        return { satisfied: false, reason: 'bun unavailable' };
+      }
+      process.stderr.write(
+        `${logPrefix} validating seeded deps: bun install --frozen-lockfile\n`,
+      );
+      const validate = runFrozenLockfileInstall(bunExec, depsDir, installStdio);
+      if (validate.status !== 0) {
+        const detail = validate.status ?? validate.signal ?? 'unknown';
+        process.stderr.write(
+          `${logPrefix} WARN: seeded tree failed frozen-lockfile (${detail}) — ` +
+          'not stamping (runtime will install normally)\n',
+        );
+        return { satisfied: false, reason: 'frozen-lockfile validation failed' };
+      }
+      fs.writeFileSync(stampTmp, currentHash);
+      renameWithRetrySync(stampTmp, stamp);
+      return { satisfied: true, method: 'seed' };
+    } else {
+      if (!bunExec) {
+        process.stderr.write(
+          `${logPrefix} bun not available — skipping install (will retry on launch)\n`,
+        );
+        return { satisfied: false, reason: 'bun unavailable' };
+      }
+      const args = fs.existsSync(sharedLock)
+        ? ['install', '--frozen-lockfile']
+        : ['install'];
+      process.stderr.write(`${logPrefix} installing shared deps: bun ${args.join(' ')}\n`);
+
+      const result = spawnSync(bunExec, args, {
+        cwd: depsDir,
+        stdio: installStdio,
+        timeout: INSTALL_TIMEOUT_MS,
+        windowsHide: true,
+        encoding: installStdio === 'pipe' ? 'utf8' : undefined,
+      });
+      if (result.error?.code === 'ETIMEDOUT' || result.signal === 'SIGTERM') {
+        process.stderr.write(
+          `${logPrefix} WARN: bun install timed out after ${INSTALL_TIMEOUT_MS}ms — ` +
+          'continuing with existing node_modules (stale lock removed)\n',
+        );
+        try { fs.unlinkSync(lockFile); } catch {}
+        return { satisfied: false, reason: 'install timed out' };
+      } else if (result.status !== 0) {
+        const detail = result.status ?? result.signal ?? 'unknown';
+        process.stderr.write(
+          `${logPrefix} WARN: bun install exited with status ${detail} — ` +
+          'continuing with existing node_modules if available\n',
+        );
+        return { satisfied: false, reason: 'install failed' };
+      } else {
+        fs.writeFileSync(stampTmp, currentHash);
+        renameWithRetrySync(stampTmp, stamp);
+        return { satisfied: true, method: 'install' };
+      }
+    }
+  } finally {
+    releaseLock(lockFile);
+  }
+}