@vibe-agent-toolkit/cli 0.2.0-rc.11 → 0.2.0-rc.12

package/README.md

@@ -85,7 +85,7 @@ vat doctor --verbose
 ```
 
 **What it checks:**
-- Node.js version (>=22.13.0 required — the range comes from the CLI's own `engines.node`)
+- Node.js version (>=22.16.0 required — the range comes from the CLI's own `engines.node`)
 - Git installation and repository
 - Configuration file exists and is valid
 - VAT version (checks for updates)
@@ -103,7 +103,7 @@ report and states how many it hid):
 Running diagnostic checks...
 
 ✅ Node.js version
-   v22.13.0 (meets requirement: >=22.13.0)
+   v22.16.0 (meets requirement: >=22.16.0)
 
 ✅ Git installed
    git version 2.43.0
@@ -131,7 +131,7 @@ If checks fail, doctor provides specific suggestions:
 
 ```
 ❌ Node.js version
-   v22.4.0 does not satisfy the required range. Node.js >=22.13.0 required.
+   v22.4.0 does not satisfy the required range. Node.js >=22.16.0 required.
    💡 Install a Node.js version in that range: https://nodejs.org/ or use nvm
 ```
 

package/dist/bin/supervise-cli.d.ts

@@ -0,0 +1,45 @@
+/**
+ * How the `vat` wrapper (`vat.ts`) waits on the CLI it spawned, and ends the way the CLI ended.
+ *
+ * Its own module so the decisions are reachable by a unit test with a stand-in child: `vat.ts`
+ * runs `main()` on import.
+ */
+import type { ChildProcess } from 'node:child_process';
+/**
+ * Wait on the CLI child, and end this process the way it ended.
+ *
+ * ## 🚨 This wrapper is the `vat` an operator, a CI runner and `timeout(1)` start
+ *
+ * So `kill <pid>` lands HERE, not on the CLI. While the CLI runs, every terminating signal is
+ * guarded (`handleTerminatingSignals`) so this process never dies before it: it waits for the
+ * CLI's `exit`, then ends the same way — dying of the same signal when the CLI died of a
+ * terminating one (re-raised; exit 2 where the raise cannot kill this process, and always on
+ * Windows), otherwise with its exit code. A repeat within `REPEAT_SIGNAL_WINDOW_MS` is
+ * swallowed (a terminal's group Ctrl-C reaches this process and the CLI both).
+ *
+ * - **A repeat after that window FORCES the ending**: the CLI is SIGKILLed — on Windows with its
+ *   whole tree (`taskkill /T /F`) — and this process dies of the repeat at once. An operator whose
+ *   first Ctrl-C or kill met a cleanup that hung can always end the run with a second.
+ *
+ * - **POSIX: the first signal is FORWARDED** to the CLI, because a signal sent to this pid alone
+ *   reaches nothing else. A terminal Ctrl-C signals the whole foreground group, so the CLI then
+ *   receives SIGINT twice — once from the terminal, once forwarded. That is safe only because
+ *   every handler the CLI has goes through `handleTerminatingSignals`, which swallows a repeat
+ *   that arrives with the first.
+ * - **Windows: NOTHING is forwarded.** The only signals delivered there are console events
+ *   (Ctrl-C, Ctrl-Break, the console closing), which the console already sends to every attached
+ *   process, the CLI included; and `child.kill` there is `TerminateProcess`, which would PRE-EMPT
+ *   the CLI's own cleanup (a progress directory, a clone, the MCP shutdown line). The guard still
+ *   keeps this process waiting for the CLI, so it ends as the CLI ended.
+ * - **A SIGKILL of this wrapper** (POSIX) runs none of this: the CLI (and anything it supervises)
+ *   runs on to its own end, bounded by its own watchdog. The CLI's stdin is this process's,
+ *   inherited — a pipe here would break every interactive command — so it never reads end-of-file.
+ * - **An outside kill of this wrapper on Windows** (`TerminateProcess`, `taskkill /F`) runs none
+ *   of this either, but ends the CLI with it: libuv spawns the CLI (not `detached`) into a
+ *   kill-on-close job object whose only handle this process holds, and the CLI's own children
+ *   go the same way with it.
+ *
+ * @param child - The spawned CLI
+ */
+export declare function superviseCli(child: ChildProcess): void;
+//# sourceMappingURL=supervise-cli.d.ts.map

package/dist/bin/supervise-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervise-cli.d.ts","sourceRoot":"","sources":["../../src/bin/supervise-cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAUvD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAmCtD"}

package/dist/bin/supervise-cli.js

@@ -0,0 +1,83 @@
+/**
+ * How the `vat` wrapper (`vat.ts`) waits on the CLI it spawned, and ends the way the CLI ended.
+ *
+ * Its own module so the decisions are reachable by a unit test with a stand-in child: `vat.ts`
+ * runs `main()` on import.
+ */
+import { ExitCode, exitCodeOfChild } from '@vibe-agent-toolkit/schema';
+import { handleTerminatingSignals, isTerminatingSignal, killProcessTree, reRaiseSignal, } from '@vibe-agent-toolkit/utils/process';
+/**
+ * Wait on the CLI child, and end this process the way it ended.
+ *
+ * ## 🚨 This wrapper is the `vat` an operator, a CI runner and `timeout(1)` start
+ *
+ * So `kill <pid>` lands HERE, not on the CLI. While the CLI runs, every terminating signal is
+ * guarded (`handleTerminatingSignals`) so this process never dies before it: it waits for the
+ * CLI's `exit`, then ends the same way — dying of the same signal when the CLI died of a
+ * terminating one (re-raised; exit 2 where the raise cannot kill this process, and always on
+ * Windows), otherwise with its exit code. A repeat within `REPEAT_SIGNAL_WINDOW_MS` is
+ * swallowed (a terminal's group Ctrl-C reaches this process and the CLI both).
+ *
+ * - **A repeat after that window FORCES the ending**: the CLI is SIGKILLed — on Windows with its
+ *   whole tree (`taskkill /T /F`) — and this process dies of the repeat at once. An operator whose
+ *   first Ctrl-C or kill met a cleanup that hung can always end the run with a second.
+ *
+ * - **POSIX: the first signal is FORWARDED** to the CLI, because a signal sent to this pid alone
+ *   reaches nothing else. A terminal Ctrl-C signals the whole foreground group, so the CLI then
+ *   receives SIGINT twice — once from the terminal, once forwarded. That is safe only because
+ *   every handler the CLI has goes through `handleTerminatingSignals`, which swallows a repeat
+ *   that arrives with the first.
+ * - **Windows: NOTHING is forwarded.** The only signals delivered there are console events
+ *   (Ctrl-C, Ctrl-Break, the console closing), which the console already sends to every attached
+ *   process, the CLI included; and `child.kill` there is `TerminateProcess`, which would PRE-EMPT
+ *   the CLI's own cleanup (a progress directory, a clone, the MCP shutdown line). The guard still
+ *   keeps this process waiting for the CLI, so it ends as the CLI ended.
+ * - **A SIGKILL of this wrapper** (POSIX) runs none of this: the CLI (and anything it supervises)
+ *   runs on to its own end, bounded by its own watchdog. The CLI's stdin is this process's,
+ *   inherited — a pipe here would break every interactive command — so it never reads end-of-file.
+ * - **An outside kill of this wrapper on Windows** (`TerminateProcess`, `taskkill /F`) runs none
+ *   of this either, but ends the CLI with it: libuv spawns the CLI (not `detached`) into a
+ *   kill-on-close job object whose only handle this process holds, and the CLI's own children
+ *   go the same way with it.
+ *
+ * @param child - The spawned CLI
+ */
+export function superviseCli(child) {
+    let cliEnded = () => undefined;
+    const ended = new Promise((resolve) => {
+        cliEnded = resolve;
+    });
+    const guard = handleTerminatingSignals({
+        fallbackExitCode: ExitCode.ERROR,
+        cleanup: (signal, forced) => {
+            // Not a group leader (a terminal's signals must reach it, and it reads the terminal): its pid.
+            forced.addEventListener('abort', () => {
+                killProcessTree(child, { groupLeader: false, throughChild: false });
+            }, { once: true });
+            if (process.platform !== 'win32')
+                child.kill(signal);
+            // Wait for the CLI: its `exit` below is what ends this process.
+            return ended;
+        },
+    });
+    // A child that never started has no status, which is not a verdict: exit 2. A failed FORWARD
+    // (a signal the platform cannot send) also lands here, with the child running — it is ignored,
+    // and the child's own `exit` still ends this process.
+    child.on('error', () => {
+        if (child.pid !== undefined)
+            return;
+        guard.release();
+        process.exit(ExitCode.ERROR);
+    });
+    child.on('exit', (code, signal) => {
+        cliEnded();
+        guard.release();
+        if (signal !== null && isTerminatingSignal(signal))
+            reRaiseSignal(signal, ExitCode.ERROR);
+        // The child derived its code from its own document. Any other signal death has no status, and
+        // a code off the contract (an older build's, Node's abort) is not a verdict the child
+        // published, so neither is forwarded verbatim.
+        process.exit(exitCodeOfChild(code));
+    });
+}
+//# sourceMappingURL=supervise-cli.js.map

package/dist/bin/supervise-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"supervise-cli.js","sourceRoot":"","sources":["../../src/bin/supervise-cli.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC;AACvE,OAAO,EACL,wBAAwB,EACxB,mBAAmB,EACnB,eAAe,EACf,aAAa,GACd,MAAM,mCAAmC,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,MAAM,UAAU,YAAY,CAAC,KAAmB;IAC9C,IAAI,QAAQ,GAAe,GAAG,EAAE,CAAC,SAAS,CAAC;IAC3C,MAAM,KAAK,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC1C,QAAQ,GAAG,OAAO,CAAC;IACrB,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAG,wBAAwB,CAAC;QACrC,gBAAgB,EAAE,QAAQ,CAAC,KAAK;QAChC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE;YAC1B,+FAA+F;YAC/F,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBACpC,eAAe,CAAC,KAAK,EAAE,EAAE,WAAW,EAAE,KAAK,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;YACtE,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACnB,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;gBAAE,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACrD,gEAAgE;YAChE,OAAO,KAAK,CAAC;QACf,CAAC;KACF,CAAC,CAAC;IAEH,6FAA6F;IAC7F,+FAA+F;IAC/F,sDAAsD;IACtD,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;QACrB,IAAI,KAAK,CAAC,GAAG,KAAK,SAAS;YAAE,OAAO;QACpC,KAAK,CAAC,OAAO,EAAE,CAAC;QAChB,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/B,CAAC,CAAC,CAAC;IACH,KAAK,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE;QAChC,QAAQ,EAAE,CAAC;QACX,KAAK,CAAC,OAAO,EAAE,CAAC;QAChB,IAAI,MAAM,KAAK,IAAI,IAAI,mBAAmB,CAAC,MAAM,CAAC;YAAE,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC1F,8FAA8F;QAC9F,sFAAsF;QACtF,+CAA+C;QAC/C,OAAO,CAAC,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/bin/vat

@@ -2,10 +2,21 @@
 /**
  * Smart vat wrapper with context-aware execution
  *
- * Automatically detects execution context and delegates to appropriate binary:
- * - Developer mode: Inside vibe-agent-toolkit repo → packages/cli/dist/bin.js (unpackaged dev build)
- * - Local install: Project has vibe-agent-toolkit → node_modules version (packaged)
- * - Global install: Fallback → globally installed version (packaged)
+ * Resolution precedence:
+ * 1. `VAT_BIN` — an explicit `dist/bin.js` path, highest precedence. A path
+ *    that does not exist, or that names this wrapper itself (`dist/bin/vat.js`,
+ *    which would re-resolve and spawn itself forever), is a hard error
+ *    (exit 2) — never a silent fall-through to a lower priority.
+ * 2. `VAT_ROOT_DIR` — a monorepo checkout root; `<root>/packages/cli/dist/bin.js`
+ *    must already be built, or this is a hard error (exit 2).
+ * 3. Dev mode: Inside vibe-agent-toolkit repo → packages/cli/dist/bin.js (unpackaged dev build)
+ * 4. Local install: Project has vibe-agent-toolkit → node_modules version (packaged)
+ * 5. Global install: Fallback → globally installed version (packaged)
+ *
+ * `VAT_TEST_ROOT` is separate from the above: it only changes the directory
+ * project-root detection (priorities 3–5) starts from — it never names a
+ * binary. For every `VAT_*` variable above, an empty string is treated as
+ * unset (`if (process.env[...])`), matching the historical behaviour.
  *
  * Features:
  * - Version detection and comparison
@@ -14,14 +25,15 @@
  *
  * Works in both git and non-git directories.
  */
-import { spawnSync } from 'node:child_process';
-import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
 import { createRequire } from 'node:module';
-import { dirname } from 'node:path';
+import { basename, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { exitCodeOfChild, installLastResortExit } from '@vibe-agent-toolkit/schema';
-import { findNodeWorkspaceRoot, isPathAbsentError, safePath, } from '@vibe-agent-toolkit/utils';
-import { describeStdioBlocking, makeStdioBlocking, } from '@vibe-agent-toolkit/utils/process';
+import { ExitCode, installLastResortExit } from '@vibe-agent-toolkit/schema';
+import { findNodeWorkspaceRoot, followedKindSync, isPathAbsentError, safePath, } from '@vibe-agent-toolkit/utils';
+import { describeStdioBlocking, makeStdioBlocking } from '@vibe-agent-toolkit/utils/process';
+import { superviseCli } from './supervise-cli.js';
 // Before ANY output. This file — not bin.ts — is what package.json maps `vat` to,
 // so it is the CLI entry point in every installed copy, and `makeStdioBlocking`
 // is documented as belonging first thing in one. The delegated child applies it
@@ -45,6 +57,18 @@ function reportStdioBlocking(debug) {
 // A throw nothing below caught ends on ExitCode.ERROR, never Node's default 1.
 installLastResortExit();
 const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Run the CLI as a child of this process, and end the way it ended.
+ *
+ * Asynchronous, never `spawnSync`: this wrapper is the `vat` an operator and a CI runner start, so
+ * `kill <pid>` lands here, and a synchronous spawn died of it at once while the CLI — with any
+ * `resources check` child it supervises — ran on, reparented. How a signal is handled meanwhile
+ * (forwarded on POSIX, never on Windows) and how this process then ends: {@link superviseCli}.
+ *
+ * @param binPath - The CLI entry (`dist/bin.js`) to run
+ * @param context - How it was found, for `VAT_CONTEXT`
+ * @param contextPath - Where it was found, for `VAT_CONTEXT_PATH`
+ */
 function spawnCli(binPath, context, contextPath) {
     const env = {
         ...process.env,
@@ -53,14 +77,42 @@ function spawnCli(binPath, context, contextPath) {
     };
     // The node running this wrapper, never a PATH lookup: the child must be the
     // same binary, and `node` by name is whatever PATH says first.
-    const result = spawnSync(process.execPath, [binPath, ...process.argv.slice(2)], {
+    superviseCli(spawn(process.execPath, [binPath, ...process.argv.slice(2)], {
         stdio: 'inherit',
         env,
-    });
-    // The child derived its code from its own document. A signal death has no
-    // status, and a code off the contract (an older build's, Node's abort) is not
-    // a verdict the child published, so neither is forwarded verbatim.
-    process.exit(exitCodeOfChild(result.status));
+    }));
+}
+/**
+ * The explicit overrides, in precedence order. A named target that cannot be
+ * run is an error, never a fall-through — see the header docstring.
+ */
+function explicitOverride(env) {
+    const vatBin = env['VAT_BIN'];
+    if (vatBin) {
+        const binPath = safePath.resolve(vatBin);
+        if (basename(binPath) === 'vat.js' && basename(dirname(binPath)) === 'bin') {
+            refuseOverride('VAT_BIN', binPath, 'names the context-detecting wrapper, which would re-resolve and run itself; point it at dist/bin.js');
+        }
+        // The operator's own variable: its own `within`.
+        if (followedKindSync(binPath, binPath) === 'absent')
+            refuseOverride('VAT_BIN', binPath, 'does not exist');
+        // <root>/packages/cli/dist/bin.js: dist → cli → packages → <root> is FOUR hops.
+        return { binPath, contextPath: dirname(dirname(dirname(dirname(binPath)))), variable: 'VAT_BIN' };
+    }
+    const rootDir = env['VAT_ROOT_DIR'];
+    if (rootDir) {
+        const binPath = safePath.join(rootDir, 'packages/cli/dist/bin.js');
+        // Beneath the directory the operator named: its links are read before followed.
+        if (followedKindSync(binPath, rootDir) === 'absent')
+            refuseOverride('VAT_ROOT_DIR', binPath, 'has no built CLI (run `bun run build` there)');
+        return { binPath, contextPath: rootDir, variable: 'VAT_ROOT_DIR' };
+    }
+    return null;
+}
+/** Print why the named override was refused and exit with {@link ExitCode.ERROR}. */
+function refuseOverride(variable, path, why) {
+    process.stderr.write(`vat: ${variable} ${why}: ${path}\nUnset ${variable} to use normal resolution.\n`);
+    process.exit(ExitCode.ERROR);
 }
 /**
  * Check if we're in vibe-agent-toolkit repo (developer mode)
@@ -72,12 +124,14 @@ function spawnCli(binPath, context, contextPath) {
 function getDevModeBinary(projectRoot) {
     const wrapperPath = safePath.join(projectRoot, 'packages/cli/dist/bin/vat.js');
     const binPath = safePath.join(projectRoot, 'packages/cli/dist/bin.js');
+    // Beneath the project root found from the operator's cwd: its links are read before followed.
+    const present = (path) => followedKindSync(path, projectRoot) !== 'absent';
     if (process.env['VAT_DEBUG'] === '1') {
-        console.error(`[vat debug] Dev check - wrapper: ${wrapperPath} (${existsSync(wrapperPath)})`);
-        console.error(`[vat debug] Dev check - bin: ${binPath} (${existsSync(binPath)})`);
+        console.error(`[vat debug] Dev check - wrapper: ${wrapperPath} (${present(wrapperPath)})`);
+        console.error(`[vat debug] Dev check - bin: ${binPath} (${present(binPath)})`);
     }
     // Both files must exist to confirm we're in vibe-agent-toolkit repo
-    if (existsSync(wrapperPath) && existsSync(binPath)) {
+    if (present(wrapperPath) && present(binPath)) {
         return binPath;
     }
     return null;
@@ -91,8 +145,8 @@ function getDevModeBinary(projectRoot) {
  * layout and **does not exist under pnpm**. An adopter depending on
  * the umbrella `vibe-agent-toolkit` package gets no top-level
  * `node_modules/@vibe-agent-toolkit/` directory at all; the real CLI lives under
- * `node_modules/.pnpm/@vibe-agent-toolkit+cli@<ver>_<hash>/…`. So priority 3 never
- * fired for them, resolution fell through to priority 4, and whichever copy of
+ * `node_modules/.pnpm/@vibe-agent-toolkit+cli@<ver>_<hash>/…`. So priority 4 never
+ * fired for them, resolution fell through to priority 5, and whichever copy of
  * `vat.js` happened to be invoked won — silently ignoring the version they pinned.
  * That is the exact failure `findLocalInstall` exists to prevent, and it was
  * invisible on npm/bun, where the flat layout makes the probe succeed.
@@ -135,7 +189,8 @@ function findLocalInstall(projectRoot) {
         // Still existence-checked: a dependency can be installed without having been
         // built (a fresh workspace checkout, a partial install), and spawning a
         // missing file would fail far from its cause.
-        if (existsSync(localBin))
+        // Beneath the package directory Node's resolver found: its links are read before followed.
+        if (followedKindSync(localBin, dirname(manifestPath)) !== 'absent')
             return localBin;
     }
     return null;
@@ -143,7 +198,7 @@ function findLocalInstall(projectRoot) {
 /**
  * `require.resolve` reduced to "found it, or didn't".
  *
- * A NOT-FOUND is priority 3's ordinary "not applicable" answer — no local
+ * A NOT-FOUND is priority 4's ordinary "not applicable" answer — no local
  * install on this base — so it falls through to the next base and ultimately to
  * the global install rather than failing the run. Two codes spell it: the
  * package is not installed (`MODULE_NOT_FOUND`), or it is installed but too old
@@ -173,18 +228,14 @@ function isResolutionNotFound(error) {
  */
 function readVersion(packageJsonPath) {
     try {
-        if (!existsSync(packageJsonPath)) {
-            return null;
-        }
         const content = readFileSync(packageJsonPath, 'utf-8');
         const pkg = JSON.parse(content);
         return pkg.version ?? null;
     }
     catch (error) {
-        // The existence check above is not atomic with the read: a manifest removed
-        // between the two is "not found". A manifest the OS refuses, or one that is
-        // not JSON, is not — this wrapper is about to dispatch to that very install,
-        // and a broken manifest is the first fact worth seeing.
+        // No existence probe: the read's own absence is "not found". A manifest the
+        // OS refuses, or one that is not JSON, is not — this wrapper is about to
+        // dispatch to that very install, and a broken manifest is the first fact worth seeing.
         if (isPathAbsentError(error))
             return null;
         throw error;
@@ -202,18 +253,19 @@ function main() {
     const args = process.argv.slice(2);
     const debug = process.env['VAT_DEBUG'] === '1';
     // Reported here rather than in the block further down because every dispatch
-    // path below ends in `spawnCli`, which never returns.
+    // path below ends in `spawnCli`.
     reportStdioBlocking(debug);
-    // Priority 1: Explicit override via VAT_ROOT_DIR
-    if (process.env['VAT_ROOT_DIR']) {
-        const binPath = safePath.join(process.env['VAT_ROOT_DIR'], 'packages/cli/dist/bin.js');
-        if (existsSync(binPath)) {
-            if (debug) {
-                console.error('[vat debug] Using VAT_ROOT_DIR override');
-                console.error(`[vat debug] Binary: ${binPath}`);
-            }
-            spawnCli(binPath, 'dev', process.env['VAT_ROOT_DIR']);
+    // Priority 1 & 2: Explicit override via VAT_BIN or VAT_ROOT_DIR. A named
+    // target that cannot be run exits here (ExitCode.ERROR) — it never falls
+    // through to dev/local/global resolution below.
+    const override = explicitOverride(process.env);
+    if (override) {
+        if (debug) {
+            console.error(`[vat debug] Using ${override.variable} override`);
+            console.error(`[vat debug] Binary: ${override.binPath}`);
         }
+        spawnCli(override.binPath, 'dev', override.contextPath);
+        return;
     }
     // Find the Node monorepo workspace root from the current working directory.
     // bin/vat.ts uses this to locate packages/cli/dist/bin.js in dev mode —
@@ -222,14 +274,14 @@ function main() {
     let binPath;
     let context;
     let binDir;
-    // Priority 2: Check for developer mode (inside vibe-agent-toolkit repo)
+    // Priority 3: Check for developer mode (inside vibe-agent-toolkit repo)
     const devBin = getDevModeBinary(projectRoot);
     if (devBin) {
         binPath = devBin;
         context = 'dev';
         binDir = dirname(dirname(devBin)); // packages/cli/dist -> packages/cli
     }
-    // Priority 3: Check for local install (node_modules)
+    // Priority 4: Check for local install (node_modules)
     else {
         const localBin = findLocalInstall(projectRoot);
         if (localBin) {
@@ -237,7 +289,7 @@ function main() {
             context = 'local';
             binDir = dirname(dirname(localBin)); // node_modules/@vibe-agent-toolkit/cli/dist -> node_modules/@vibe-agent-toolkit/cli
         }
-        // Priority 4: Use global install (this script's location)
+        // Priority 5: Use global install (this script's location)
         else {
             binPath = safePath.resolve(__dirname, '../bin.js');
             context = 'global';

package/dist/bin/vat.d.ts

@@ -2,10 +2,21 @@
 /**
  * Smart vat wrapper with context-aware execution
  *
- * Automatically detects execution context and delegates to appropriate binary:
- * - Developer mode: Inside vibe-agent-toolkit repo → packages/cli/dist/bin.js (unpackaged dev build)
- * - Local install: Project has vibe-agent-toolkit → node_modules version (packaged)
- * - Global install: Fallback → globally installed version (packaged)
+ * Resolution precedence:
+ * 1. `VAT_BIN` — an explicit `dist/bin.js` path, highest precedence. A path
+ *    that does not exist, or that names this wrapper itself (`dist/bin/vat.js`,
+ *    which would re-resolve and spawn itself forever), is a hard error
+ *    (exit 2) — never a silent fall-through to a lower priority.
+ * 2. `VAT_ROOT_DIR` — a monorepo checkout root; `<root>/packages/cli/dist/bin.js`
+ *    must already be built, or this is a hard error (exit 2).
+ * 3. Dev mode: Inside vibe-agent-toolkit repo → packages/cli/dist/bin.js (unpackaged dev build)
+ * 4. Local install: Project has vibe-agent-toolkit → node_modules version (packaged)
+ * 5. Global install: Fallback → globally installed version (packaged)
+ *
+ * `VAT_TEST_ROOT` is separate from the above: it only changes the directory
+ * project-root detection (priorities 3–5) starts from — it never names a
+ * binary. For every `VAT_*` variable above, an empty string is treated as
+ * unset (`if (process.env[...])`), matching the historical behaviour.
  *
  * Features:
  * - Version detection and comparison

package/dist/bin/vat.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"vat.d.ts","sourceRoot":"","sources":["../../src/bin/vat.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;GAcG"}
+{"version":3,"file":"vat.d.ts","sourceRoot":"","sources":["../../src/bin/vat.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG"}