@happier-dev/stack 0.2.0 → 0.2.11

package/scripts/utils/proc/watch.test.mjs

@@ -0,0 +1,230 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+
+import { watchDebounced } from './watch.mjs';
+
+test('watchDebounced polls an explicit signature so missed fs.watch events still trigger onChange', async () => {
+  const calls = [];
+  let signature = 'initial';
+  let poll = null;
+  let pollTimer = null;
+
+  const watcher = watchDebounced({
+    paths: ['/tmp/hstack-watch-test'],
+    debounceMs: 0,
+    onChange(event) {
+      calls.push(`${event.eventType}:${event.filename ?? ''}`);
+    },
+    readSignature() {
+      return signature;
+    },
+    pollIntervalMs: 1234,
+    watchImpl: () => ({
+      close() {
+        calls.push('watch:closed');
+      },
+    }),
+    setIntervalImpl(fn, ms) {
+      assert.equal(ms, 1234);
+      poll = fn;
+      pollTimer = { id: 'poll' };
+      return pollTimer;
+    },
+    clearIntervalImpl(timer) {
+      assert.equal(timer, pollTimer);
+      calls.push('poll:closed');
+    },
+  });
+
+  assert.ok(watcher);
+  assert.equal(typeof poll, 'function');
+
+  await poll();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(calls, []);
+
+  signature = 'changed';
+  await poll();
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(calls, ['poll:']);
+
+  watcher.close();
+  assert.ok(calls.includes('watch:closed'));
+  assert.ok(calls.includes('poll:closed'));
+});
+
+test('watchDebounced awaits asynchronous signatures without treating pending promises as changes', async () => {
+  const calls = [];
+  const pendingReads = [];
+  let poll = null;
+
+  const watcher = watchDebounced({
+    paths: ['/tmp/hstack-watch-async-signature-test'],
+    debounceMs: 0,
+    onChange(event) {
+      calls.push(`${event.eventType}:${event.filename ?? ''}`);
+    },
+    readSignature() {
+      return new Promise((resolve) => pendingReads.push(resolve));
+    },
+    pollIntervalMs: 1234,
+    watchImpl: () => ({ close() {} }),
+    setIntervalImpl(fn) {
+      poll = fn;
+      return { unref() {} };
+    },
+    clearIntervalImpl() {},
+  });
+
+  assert.ok(watcher);
+  assert.equal(pendingReads.length, 1, 'the initial asynchronous signature read should establish the baseline');
+  pendingReads.shift()('initial');
+  await Promise.resolve();
+
+  const unchangedPoll = poll();
+  let unchangedSettled = false;
+  unchangedPoll.then(() => {
+    unchangedSettled = true;
+  });
+  for (let attempt = 0; attempt < 5 && pendingReads.length === 0; attempt += 1) {
+    await Promise.resolve();
+  }
+  assert.equal(unchangedSettled, false, 'the poll must remain pending until the signature read completes');
+  pendingReads.shift()('initial');
+  await unchangedPoll;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(calls, []);
+
+  const changedPoll = poll();
+  pendingReads.shift()('changed');
+  await changedPoll;
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  assert.deepEqual(calls, ['poll:']);
+
+  watcher.close();
+});
+
+test('watchDebounced marks filesystem events observed while its async baseline is pending', async () => {
+  const events = [];
+  let resolveBaseline;
+  let emitFilesystemEvent;
+  const watcher = watchDebounced({
+    paths: ['/tmp/hstack-watch-initializing-signature-test'],
+    debounceMs: 0,
+    onChange(event) {
+      events.push(event);
+    },
+    readSignature() {
+      return new Promise((resolve) => {
+        resolveBaseline = resolve;
+      });
+    },
+    watchImpl: (_path, _options, handler) => {
+      emitFilesystemEvent = handler;
+      return { close() {} };
+    },
+  });
+
+  emitFilesystemEvent('change', 'app.ts');
+  resolveBaseline('changed-during-baseline');
+  await new Promise((resolve) => setTimeout(resolve, 0));
+  watcher.close();
+
+  assert.equal(events.length, 1);
+  assert.equal(events[0].signatureInitializedAtObservation, false);
+  assert.equal(events[0].watchPath, '/tmp/hstack-watch-initializing-signature-test');
+});
+
+test('watchDebounced reports a filesystem observation before its debounced change callback', async () => {
+  const calls = [];
+  let emitFilesystemEvent;
+  let runDebouncedChange;
+  const watcher = watchDebounced({
+    paths: ['/tmp/hstack-watch-observation-test'],
+    debounceMs: 500,
+    onObservation(event) {
+      calls.push(`observed:${event.eventType}:${event.filename}`);
+    },
+    onChange(event) {
+      calls.push(`changed:${event.eventType}:${event.filename}`);
+    },
+    watchImpl: (_path, _options, handler) => {
+      emitFilesystemEvent = handler;
+      return { close() {} };
+    },
+    setTimeoutImpl(callback, ms) {
+      assert.equal(ms, 500);
+      runDebouncedChange = callback;
+      return { id: 'debounce' };
+    },
+    clearTimeoutImpl() {},
+  });
+
+  emitFilesystemEvent('change', 'schema.prisma');
+  assert.deepEqual(calls, ['observed:change:schema.prisma']);
+  runDebouncedChange();
+  await Promise.resolve();
+  watcher.close();
+
+  assert.deepEqual(calls, [
+    'observed:change:schema.prisma',
+    'changed:change:schema.prisma',
+  ]);
+});
+
+test('watchDebounced does not carry handled status into a later debounce window', async () => {
+  const changes = [];
+  const timers = [];
+  let handled = true;
+  let emitFilesystemEvent;
+  const watcher = watchDebounced({
+    paths: ['/tmp/hstack-watch-observation-reset-test'],
+    debounceMs: 500,
+    onObservation() {
+      return handled;
+    },
+    onChange(event) {
+      changes.push(event.observationHandled);
+    },
+    watchImpl: (_path, _options, handler) => {
+      emitFilesystemEvent = handler;
+      return { close() {} };
+    },
+    setTimeoutImpl(callback) {
+      timers.push(callback);
+      return { id: timers.length };
+    },
+    clearTimeoutImpl() {},
+  });
+
+  emitFilesystemEvent('change', 'first.ts');
+  timers.shift()();
+  await Promise.resolve();
+  handled = false;
+  emitFilesystemEvent('change', 'second.ts');
+  timers.shift()();
+  await Promise.resolve();
+  watcher.close();
+
+  assert.deepEqual(changes, [true, false]);
+});
+
+test('watchDebounced logs why no filesystem watcher or poller could start', () => {
+  const messages = [];
+  const watcher = watchDebounced({
+    paths: ['/tmp/hstack-watch-unavailable'],
+    onChange() {},
+    watchImpl() {
+      throw new Error('watch unavailable');
+    },
+    logger: {
+      log(message) { messages.push(String(message)); },
+      warn(message) { messages.push(String(message)); },
+      error(message) { messages.push(String(message)); },
+    },
+  });
+
+  assert.equal(watcher, null);
+  assert.ok(messages.some((message) => message.includes('/tmp/hstack-watch-unavailable')));
+  assert.ok(messages.some((message) => message.includes('no active filesystem watcher or signature poller')));
+});

package/scripts/utils/proc/workspace_dependencies.mjs

@@ -0,0 +1,21 @@
+export function collectInternalWorkspaceDependencyNames(
+  pkgJson,
+  currentPkgName = '',
+  { workspacePackageNames = null } = {},
+) {
+  const knownWorkspacePackageNames = workspacePackageNames
+    ? new Set(workspacePackageNames)
+    : null;
+  const names = new Set();
+  for (const source of [pkgJson?.dependencies, pkgJson?.optionalDependencies, pkgJson?.devDependencies]) {
+    if (!source || typeof source !== 'object') continue;
+    for (const name of Object.keys(source)) {
+      const isInternalWorkspace = knownWorkspacePackageNames
+        ? knownWorkspacePackageNames.has(name)
+        : name.startsWith('@happier-dev/');
+      if (!isInternalWorkspace || name === currentPkgName) continue;
+      names.add(name);
+    }
+  }
+  return Array.from(names);
+}

package/scripts/utils/proc/workspace_package_manifests.mjs

@@ -0,0 +1,108 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { pathExists } from '../fs/fs.mjs';
+
+async function readJsonIfExists(path) {
+  if (!(await pathExists(path))) {
+    return null;
+  }
+  return JSON.parse(await readFile(path, 'utf-8'));
+}
+
+function readWorkspacePatterns(pkgJson) {
+  const workspaces = pkgJson?.workspaces;
+  if (Array.isArray(workspaces)) {
+    return workspaces;
+  }
+  if (Array.isArray(workspaces?.packages)) {
+    return workspaces.packages;
+  }
+  return [];
+}
+
+function workspacePatternToSegments(pattern) {
+  const value = String(pattern ?? '').trim();
+  if (!value || value.startsWith('!')) return null;
+  return value
+    .replace(/\\/g, '/')
+    .replace(/\/+$/g, '')
+    .split('/')
+    .filter(Boolean);
+}
+
+function wildcardSegmentRegex(segment) {
+  const escaped = String(segment)
+    .replace(/[.+?^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*/g, '[^/]*');
+  return new RegExp(`^${escaped}$`);
+}
+
+async function expandWorkspacePatternSegments(baseDir, segments, index = 0) {
+  if (index >= segments.length) {
+    return [baseDir];
+  }
+
+  const segment = segments[index];
+  if (!segment || segment === '**') {
+    return [];
+  }
+
+  if (!segment.includes('*')) {
+    return await expandWorkspacePatternSegments(join(baseDir, segment), segments, index + 1);
+  }
+
+  let entries = [];
+  try {
+    entries = await readdir(baseDir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const matcher = wildcardSegmentRegex(segment);
+  const out = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!matcher.test(entry.name)) continue;
+    out.push(...await expandWorkspacePatternSegments(join(baseDir, entry.name), segments, index + 1));
+  }
+  return out;
+}
+
+export async function collectWorkspacePackageJsonPaths(monorepoRoot) {
+  const rootPkgJson = await readJsonIfExists(join(monorepoRoot, 'package.json'));
+  const patterns = readWorkspacePatterns(rootPkgJson);
+  const out = new Set();
+
+  for (const pattern of patterns) {
+    const segments = workspacePatternToSegments(pattern);
+    if (!segments?.length) continue;
+    for (const workspaceDir of await expandWorkspacePatternSegments(monorepoRoot, segments)) {
+      const pkgJsonPath = join(workspaceDir, 'package.json');
+      if (await pathExists(pkgJsonPath)) {
+        out.add(pkgJsonPath);
+      }
+    }
+  }
+
+  if (out.size === 0) {
+    for (const bucket of ['apps', 'packages']) {
+      const bucketDir = join(monorepoRoot, bucket);
+      let entries = [];
+      try {
+        entries = await readdir(bucketDir, { withFileTypes: true });
+      } catch {
+        continue;
+      }
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        const pkgJsonPath = join(bucketDir, entry.name, 'package.json');
+        if (await pathExists(pkgJsonPath)) {
+          out.add(pkgJsonPath);
+        }
+      }
+    }
+  }
+
+  return Array.from(out);
+}

package/scripts/utils/remote/install_remote_first_party_component.mjs

@@ -1,4 +1,8 @@
-import { basename } from 'node:path';
+import { execFile } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { promisify } from 'node:util';
 
 import {
   getFirstPartyComponentCatalogEntry,
@@ -9,6 +13,8 @@ import { normalizePublicReleaseRingId } from '@happier-dev/release-runtime/relea
 
 import { run, runCapture } from '../proc/proc.mjs';
 
+const execFileAsync = promisify(execFile);
+
 function safeBashSingleQuote(value) {
   const raw = String(value ?? '');
   if (raw === '') return "''";
@@ -31,6 +37,23 @@ function parseJsonLinesBestEffort(stdout) {
   return null;
 }
 
+async function runRemoteText({ target, command }) {
+  await run('ssh', [target, 'bash', '-lc', safeBashSingleQuote(command)], { env: process.env });
+}
+
+async function runRemoteJson({ target, command }) {
+  const out = await runCapture('ssh', [target, 'bash', '-lc', safeBashSingleQuote(command)], { env: process.env });
+  const parsed = parseJsonLinesBestEffort(out);
+  if (!parsed) {
+    throw new Error('Remote command did not return valid JSON');
+  }
+  return parsed;
+}
+
+function normalizeChannel(channel) {
+  return normalizePublicReleaseRingId(channel) || 'stable';
+}
+
 function sanitizeRemotePathSegment(value) {
   const sanitized = String(value ?? '')
     .trim()
@@ -53,21 +76,43 @@ function normalizeRemoteReleaseArch(value) {
   throw new Error(`Unsupported remote bootstrap architecture: ${normalized || 'unknown'}`);
 }
 
-async function runRemoteText({ target, command }) {
-  await run('ssh', [target, 'bash', '-lc', safeBashSingleQuote(command)], { env: process.env });
-}
-
-async function runRemoteJson({ target, command }) {
-  const out = await runCapture('ssh', [target, 'bash', '-lc', safeBashSingleQuote(command)], { env: process.env });
-  const parsed = parseJsonLinesBestEffort(out);
-  if (!parsed) {
-    throw new Error('Remote command did not return valid JSON');
+function normalizeScpRemotePath(remotePath) {
+  const trimmed = String(remotePath ?? '').trim();
+  if (!trimmed) return trimmed;
+  if (trimmed.startsWith('$HOME/')) {
+    return trimmed.slice('$HOME/'.length);
   }
-  return parsed;
+  if (trimmed === '$HOME') {
+    return '.';
+  }
+  return trimmed;
 }
 
-function normalizeChannel(channel) {
-  return normalizePublicReleaseRingId(channel) || 'stable';
+async function createScpReadyPayloadArchive(payloadRoot) {
+  const archiveStageRoot = await mkdtemp(join(tmpdir(), 'happier-first-party-scp-archive-'));
+  const extractedPayloadDirName = basename(payloadRoot);
+  const archiveFileName = `${extractedPayloadDirName}.tar`;
+
+  try {
+    await execFileAsync('tar', [
+      '-chf',
+      join(archiveStageRoot, archiveFileName),
+      '-C',
+      join(payloadRoot, '..'),
+      extractedPayloadDirName,
+    ]);
+    return {
+      archiveStageRoot,
+      archiveFileName,
+      extractedPayloadDirName,
+      cleanup: async () => {
+        await rm(archiveStageRoot, { recursive: true, force: true });
+      },
+    };
+  } catch (error) {
+    await rm(archiveStageRoot, { recursive: true, force: true });
+    throw error;
+  }
 }
 
 export function resolveRemoteInstalledFirstPartyBinaryPath({ componentId, channel, remoteHomeDir = '$HOME/.happier' }) {
@@ -132,38 +177,62 @@ export async function installRemoteFirstPartyComponent(
 
   try {
     const component = getFirstPartyComponentCatalogEntry(componentId);
-    const stageParent = `${remoteHomeDir}/bootstrap-staging/${sanitizeRemotePathSegment(componentId)}-${sanitizeRemotePathSegment(prepared.versionId)}-${resolvedDeps.now()}`;
-    await resolvedDeps.runRemoteText({
-      target,
-      command: `mkdir -p ${stageParent}`,
-    });
-    await resolvedDeps.runScp({
-      localPath: prepared.payloadRoot,
-      remoteTarget: `${target}:${stageParent}`,
-    });
-
-    const remotePayloadRoot = `${stageParent}/${basename(prepared.payloadRoot)}`;
-    const installerBinaryPath = `${remotePayloadRoot}/${component.binaryRelativePath}`;
-    await resolvedDeps.runRemoteText({
-      target,
-      command: [
-        'set -euo pipefail',
-        `cleanup() { rm -rf ${stageParent}; }`,
-        'trap cleanup EXIT',
-        `mkdir -p ${remoteHomeDir}`,
-        `env HAPPIER_HOME_DIR=${remoteHomeDir} ${installerBinaryPath} self __install-payload --component '${componentId}' --payload-root ${remotePayloadRoot} --version '${prepared.versionId}' --channel '${normalizedChannel}'`,
-      ].join('; '),
-    });
-
-    return {
-      binaryPath: resolveRemoteInstalledFirstPartyBinaryPath({
+    const archive = await createScpReadyPayloadArchive(prepared.payloadRoot);
+    try {
+      const variant = resolveFirstPartyComponentPublicReleaseVariant({
         componentId,
         channel: normalizedChannel,
-        remoteHomeDir,
-      }),
-      versionId: prepared.versionId,
-      source: prepared.source,
-    };
+      });
+      const stageParent = `${remoteHomeDir}/bootstrap-staging/${sanitizeRemotePathSegment(componentId)}-${sanitizeRemotePathSegment(prepared.versionId)}-${resolvedDeps.now()}`;
+      const remoteArchivePath = `${stageParent}/${sanitizeRemotePathSegment(archive.archiveFileName)}`;
+      const remoteExtractRoot = `${stageParent}/payload-extracted`;
+      const remotePayloadRoot = `${remoteExtractRoot}/${sanitizeRemotePathSegment(archive.extractedPayloadDirName)}`;
+      const installRoot = `${remoteHomeDir}/${variant.installRootName}`;
+      const versionsDir = `${installRoot}/versions`;
+      const versionDir = `${versionsDir}/${sanitizeRemotePathSegment(prepared.versionId)}`;
+      const currentPath = `${installRoot}/current`;
+      const previousPath = `${installRoot}/previous`;
+      const binaryPath = `${currentPath}/${component.binaryRelativePath}`;
+
+      await resolvedDeps.runRemoteText({
+        target,
+        command: `mkdir -p ${stageParent}`,
+      });
+      await resolvedDeps.runScp({
+        localPath: join(archive.archiveStageRoot, archive.archiveFileName),
+        remoteTarget: `${target}:${normalizeScpRemotePath(remoteArchivePath)}`,
+      });
+
+      await resolvedDeps.runRemoteText({
+        target,
+        command: [
+          'set -eu',
+          `cleanup() { rm -rf ${stageParent}; }`,
+          'trap cleanup EXIT',
+          `mkdir -p ${versionsDir}`,
+          `rm -rf ${versionDir}`,
+          `rm -rf ${remoteExtractRoot}`,
+          `mkdir -p ${remoteExtractRoot}`,
+          `tar -xf ${remoteArchivePath} -C ${remoteExtractRoot}`,
+          `cp -R ${remotePayloadRoot} ${versionDir}`,
+          `if [ -L ${currentPath} ]; then prev="$(readlink ${currentPath} || true)"; if [ -n "$prev" ]; then ln -sfn "$prev" ${previousPath}; fi; fi`,
+          `ln -sfn ${versionDir} ${currentPath}`,
+          `chmod +x ${binaryPath}`,
+        ].join('; '),
+      });
+
+      return {
+        binaryPath: resolveRemoteInstalledFirstPartyBinaryPath({
+          componentId,
+          channel: normalizedChannel,
+          remoteHomeDir,
+        }),
+        versionId: prepared.versionId,
+        source: prepared.source,
+      };
+    } finally {
+      await archive.cleanup();
+    }
   } finally {
     await prepared.cleanup();
   }

package/scripts/utils/remote/install_remote_first_party_component.test.mjs

@@ -1,5 +1,8 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
 
 import {
   installRemoteFirstPartyComponent,
@@ -9,47 +12,55 @@ import {
 test('installRemoteFirstPartyComponent uploads a verified payload and promotes it with self __install-payload', async () => {
   const remoteCommands = [];
   const scpCopies = [];
+  const payloadRootParent = await mkdtemp(join(tmpdir(), 'remote-first-party-payload-'));
+  const payloadRoot = join(payloadRootParent, 'hstack-linux-x64');
+  await mkdir(payloadRoot, { recursive: true });
+  await writeFile(join(payloadRoot, 'hstack'), '#!/bin/sh\nexit 0\n', 'utf8');
 
-  const result = await installRemoteFirstPartyComponent(
-    {
-      componentId: 'hstack',
-      channel: 'preview',
-      target: 'dev@example.test',
-    },
-    {
-      now: () => 1700000000000,
-      runRemoteJson: async () => ({ platform: 'linux', arch: 'x64' }),
-      preparePayload: async () => ({
+  try {
+    const result = await installRemoteFirstPartyComponent(
+      {
         componentId: 'hstack',
         channel: 'preview',
-        versionId: '1.2.3',
-        payloadRoot: '/tmp/local/hstack-linux-x64',
-        source: 'https://example.test/hstack.tgz',
-        cleanup: async () => undefined,
-      }),
-      runRemoteText: async ({ command }) => {
-        remoteCommands.push(command);
+        target: 'dev@example.test',
       },
-      runScp: async ({ localPath, remoteTarget }) => {
-        scpCopies.push({ localPath, remoteTarget });
+      {
+        now: () => 1700000000000,
+        runRemoteJson: async () => ({ platform: 'linux', arch: 'x64' }),
+        preparePayload: async () => ({
+          componentId: 'hstack',
+          channel: 'preview',
+          versionId: '1.2.3',
+          payloadRoot,
+          source: 'https://example.test/hstack.tgz',
+          cleanup: async () => undefined,
+        }),
+        runRemoteText: async ({ command }) => {
+          remoteCommands.push(command);
+        },
+        runScp: async ({ localPath, remoteTarget }) => {
+          scpCopies.push({ localPath, remoteTarget });
+        },
       },
-    },
-  );
+    );
 
-  assert.deepEqual(scpCopies, [
-    {
-      localPath: '/tmp/local/hstack-linux-x64',
-      remoteTarget: 'dev@example.test:$HOME/.happier/bootstrap-staging/hstack-1.2.3-1700000000000',
-    },
-  ]);
-  assert.ok(!remoteCommands.join('\n').includes('curl -fsSL https://happier.dev/install'));
-  assert.match(remoteCommands.at(-1) ?? '', /self __install-payload/);
-  assert.match(remoteCommands.at(-1) ?? '', /--component 'hstack'/);
-  assert.deepEqual(result, {
-    binaryPath: '$HOME/.happier/stack-preview/current/hstack',
-    versionId: '1.2.3',
-    source: 'https://example.test/hstack.tgz',
-  });
+    assert.equal(scpCopies.length, 1);
+    assert.match(scpCopies[0]?.localPath ?? '', /hstack-linux-x64\.tar$/);
+    assert.match(
+      scpCopies[0]?.remoteTarget ?? '',
+      /^dev@example\.test:(\$HOME\/)?\.?happier\/bootstrap-staging\/hstack-1\.2\.3-1700000000000\/hstack-linux-x64\.tar$/,
+    );
+    assert.ok(!remoteCommands.join('\n').includes('curl -fsSL https://happier.dev/install'));
+    assert.match(remoteCommands.at(-1) ?? '', /tar -xf/);
+    assert.doesNotMatch(remoteCommands.at(-1) ?? '', /self __install-payload/);
+    assert.deepEqual(result, {
+      binaryPath: '$HOME/.happier/stack-preview/current/hstack',
+      versionId: '1.2.3',
+      source: 'https://example.test/hstack.tgz',
+    });
+  } finally {
+    await rm(payloadRootParent, { recursive: true, force: true });
+  }
 });
 
 test('resolveRemoteInstalledFirstPartyBinaryPath uses the verified install root for publicdev channels', () => {

package/scripts/utils/review/augment_runner_integration.test.mjs

@@ -13,6 +13,13 @@ function resolveRepoRoot() {
   return path.resolve(here, '..', '..', '..', '..', '..');
 }
 
+function buildToolStubPath(binDir) {
+  const nodeBinDir = path.dirname(process.execPath);
+  const existing = (process.env.PATH ?? '').split(path.delimiter).filter(Boolean);
+  const rest = existing.filter((entry) => entry !== binDir && entry !== nodeBinDir);
+  return [binDir, nodeBinDir, ...rest].join(path.delimiter);
+}
+
 test('review script provides a non-empty prompt to augment in normal uncommitted mode', () => {
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'happier-review-auggie-'));
   const binDir = path.join(tmp, 'bin');
@@ -36,8 +43,8 @@ process.stdout.write('ok\\n\\n===FINDINGS_JSON===\\n[]\\n');
   const repoRoot = resolveRepoRoot();
   const env = {
     ...process.env,
-    // Ensure our stub is used.
-    PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ''}`,
+    // Keep the real Node bin available without letting its real auggie binary shadow our stub.
+    PATH: buildToolStubPath(binDir),
     // Keep Augment cache writes out of the repo.
     HAPPIER_STACK_AUGMENT_CACHE_DIR: path.join(tmp, 'augment-home'),
     HAPPIER_STACK_REPO_DIR: repoRoot,
@@ -78,7 +85,7 @@ process.stdout.write('ok\\n\\n===FINDINGS_JSON===\\n[]\\n');
   const repoRoot = resolveRepoRoot();
   const env = {
     ...process.env,
-    PATH: `${binDir}${path.delimiter}${process.env.PATH ?? ''}`,
+    PATH: buildToolStubPath(binDir),
     HAPPIER_STACK_AUGMENT_CACHE_DIR: path.join(tmp, 'augment-home'),
     // Do NOT set HAPPIER_STACK_REPO_DIR here; we want it inferred from cwd.
   };