happy-stacks 0.6.12 → 0.6.13

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

@@ -64,6 +64,93 @@ test('parseCodexReviewText extracts findings JSON trailer', () => {
   assert.equal(findings[0].severity, 'major');
 });
 
+test('parseCodexReviewText extracts findings JSON trailer even when fenced', () => {
+  const review = [
+    'All good.',
+    '',
+    '===FINDINGS_JSON===',
+    '```json',
+    JSON.stringify(
+      [
+        {
+          severity: 'minor',
+          file: 'cli/src/foo.ts',
+          title: 'Prefer explicit return type',
+          recommendation: 'Add an explicit return type for clarity.',
+        },
+      ],
+      null,
+      2
+    ),
+    '```',
+  ].join('\n');
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'cli/src/foo.ts');
+  assert.equal(findings[0].severity, 'minor');
+});
+
+test('parseCodexReviewText extracts findings JSON trailer when lines are log-prefixed', () => {
+  const label = '[monorepo:augment:4/39] ';
+  const review = [
+    `${label}some preamble`,
+    `${label}===FINDINGS_JSON===`,
+    `${label}\`\`\`json`,
+    `${label}[`,
+    `${label}  {`,
+    `${label}    \"severity\": \"major\",`,
+    `${label}    \"file\": \"cli/src/x.ts\",`,
+    `${label}    \"title\": \"Fix thing\",`,
+    `${label}    \"recommendation\": \"Do it.\",`,
+    `${label}    \"needsDiscussion\": false`,
+    `${label}  }`,
+    `${label}]`,
+    `${label}\`\`\``,
+    `${label}`,
+    `${label}Request ID: abc`,
+  ].join('\n');
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'cli/src/x.ts');
+  assert.equal(findings[0].severity, 'major');
+});
+
+test('parseCodexReviewText falls back to parsing [P#] bullet lines', () => {
+  const review = [
+    '[monorepo:codex:2/21] Review comment:',
+    '[monorepo:codex:2/21] - [P1] Fix thing one — /Users/me/repo/.project/review-worktrees/codex-2-of-21-abc/cli/src/foo.ts:10-12',
+    '[monorepo:codex:2/21] - [P3] Fix thing two — /Users/me/repo/.project/review-worktrees/codex-2-of-21-abc/expo-app/sources/bar.tsx:7',
+  ].join('\n');
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 2);
+  assert.equal(findings[0].file, 'cli/src/foo.ts');
+  assert.deepEqual(findings[0].lines, { start: 10, end: 12 });
+  assert.equal(findings[0].severity, 'blocker');
+  assert.equal(findings[0].title, 'Fix thing one');
+  assert.equal(findings[1].file, 'expo-app/sources/bar.tsx');
+  assert.deepEqual(findings[1].lines, { start: 7, end: 7 });
+  assert.equal(findings[1].severity, 'minor');
+  assert.equal(findings[1].title, 'Fix thing two');
+});
+
+test('parseCodexReviewText falls back when marker exists but JSON is missing/invalid', () => {
+  const review = [
+    'instructions...',
+    '===FINDINGS_JSON===',
+    'this is not json',
+    '[monorepo:codex:2/21] - [P2] Fix thing — /Users/me/repo/.project/review-worktrees/codex-2-of-21-abc/server/src/x.ts:1-2',
+  ].join('\n');
+
+  const findings = parseCodexReviewText(review);
+  assert.equal(findings.length, 1);
+  assert.equal(findings[0].file, 'server/src/x.ts');
+  assert.deepEqual(findings[0].lines, { start: 1, end: 2 });
+  assert.equal(findings[0].severity, 'major');
+});
+
 test('formatTriageMarkdown includes required workflow fields', () => {
   const md = formatTriageMarkdown({
     runLabel: 'review-123',
@@ -78,8 +165,8 @@ test('formatTriageMarkdown includes required workflow fields', () => {
       },
     ],
   });
+  assert.match(md, /Trust checklist/i);
   assert.match(md, /Final decision: \*\*TBD\*\*/);
   assert.match(md, /Verified in validation worktree:/);
   assert.match(md, /Commit:/);
 });
-

package/scripts/utils/review/runners/augment.mjs

@@ -0,0 +1,71 @@
+import { runCaptureResult } from '../../proc/proc.mjs';
+
+export function detectAugmentAuthError({ stdout, stderr }) {
+  const combined = `${stdout ?? ''}\n${stderr ?? ''}`;
+  return combined.includes('Authentication failed') && combined.includes("Run 'auggie login'");
+}
+
+export function buildAugmentReviewArgs({
+  prompt,
+  workspaceRoot,
+  cacheDir,
+  model,
+  rulesFiles = [],
+  retryTimeoutSec,
+  maxTurns,
+} = {}) {
+  const args = ['--print', '--quiet', '--dont-save-session', '--ask', '--output-format', 'text'];
+
+  const wr = String(workspaceRoot ?? '').trim();
+  if (wr) args.push('--workspace-root', wr);
+
+  const cd = String(cacheDir ?? '').trim();
+  if (cd) args.push('--augment-cache-dir', cd);
+
+  const m = String(model ?? '').trim();
+  if (m) args.push('--model', m);
+
+  const rt = String(retryTimeoutSec ?? '').trim();
+  if (rt) args.push('--retry-timeout', rt);
+
+  const mt = String(maxTurns ?? '').trim();
+  if (mt) args.push('--max-turns', mt);
+
+  for (const rf of Array.isArray(rulesFiles) ? rulesFiles : []) {
+    const p = String(rf ?? '').trim();
+    if (!p) continue;
+    args.push('--rules', p);
+  }
+
+  const p = String(prompt ?? '').trim();
+  if (!p) throw new Error('[review] augment: missing prompt');
+  args.push(p);
+  return args;
+}
+
+export async function runAugmentReview({
+  repoDir,
+  prompt,
+  env,
+  streamLabel,
+  teeFile,
+  teeLabel,
+  cacheDir,
+  model,
+  rulesFiles = [],
+  retryTimeoutSec = 60 * 60 * 2,
+  maxTurns,
+} = {}) {
+  const args = buildAugmentReviewArgs({
+    prompt,
+    workspaceRoot: repoDir,
+    cacheDir,
+    model,
+    rulesFiles,
+    retryTimeoutSec,
+    maxTurns,
+  });
+  const res = await runCaptureResult('auggie', args, { cwd: repoDir, env: env ?? {}, streamLabel, teeFile, teeLabel });
+  return { ...res, stdout: res.out, stderr: res.err };
+}
+

package/scripts/utils/review/runners/augment.test.mjs

@@ -0,0 +1,42 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+
+import { buildAugmentReviewArgs, detectAugmentAuthError } from './augment.mjs';
+
+test('detectAugmentAuthError matches 401 login guidance', () => {
+  const stdout = "❌ Authentication failed: HTTP error: 401 Unauthorized\n   Run 'auggie login' to authenticate first.";
+  assert.equal(detectAugmentAuthError({ stdout, stderr: '' }), true);
+});
+
+test('buildAugmentReviewArgs builds auggie --print args with optional settings', () => {
+  const args = buildAugmentReviewArgs({
+    prompt: 'Review the code',
+    workspaceRoot: '/repo',
+    cacheDir: '/cache',
+    model: 'gpt-5.2',
+    rulesFiles: ['/rules/a.md', '/rules/b.md'],
+    retryTimeoutSec: 123,
+    maxTurns: 9,
+  });
+
+  assert.equal(args[0], '--print');
+  assert.ok(args.includes('--quiet'));
+  assert.ok(args.includes('--dont-save-session'));
+  assert.ok(args.includes('--ask'));
+  assert.ok(args.includes('--workspace-root'));
+  assert.ok(args.includes('/repo'));
+  assert.ok(args.includes('--augment-cache-dir'));
+  assert.ok(args.includes('/cache'));
+  assert.ok(args.includes('--model'));
+  assert.ok(args.includes('gpt-5.2'));
+  assert.ok(args.includes('--retry-timeout'));
+  assert.ok(args.includes('123'));
+  assert.ok(args.includes('--max-turns'));
+  assert.ok(args.includes('9'));
+
+  const joined = args.join(' ');
+  assert.match(joined, /--rules \/rules\/a\.md/);
+  assert.match(joined, /--rules \/rules\/b\.md/);
+  assert.equal(args.at(-1), 'Review the code');
+});
+

package/scripts/utils/review/runners/coderabbit.mjs

@@ -1,5 +1,6 @@
 import { runCaptureResult } from '../../proc/proc.mjs';
 import { join } from 'node:path';
+import { appendFile } from 'node:fs/promises';
 
 function normalizeType(raw) {
   const t = String(raw ?? '').trim().toLowerCase();
@@ -8,6 +9,19 @@ function normalizeType(raw) {
   throw new Error(`[review] invalid coderabbit type: ${raw} (expected: all|committed|uncommitted)`);
 }
 
+export function parseCodeRabbitRateLimitRetryMs(text) {
+  const s = String(text ?? '');
+  const m = s.match(/Rate limit exceeded,\s*please try after\s+(\d+)\s+minutes?\s+and\s+(\d+)\s+seconds?/i);
+  if (!m) return null;
+  const minutes = Number(m[1]);
+  const seconds = Number(m[2]);
+  if (!Number.isFinite(minutes) || minutes < 0) return null;
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  // Add +1s padding to avoid retrying too early.
+  const totalSeconds = minutes * 60 + seconds + 1;
+  return Math.max(1000, totalSeconds * 1000);
+}
+
 export function buildCodeRabbitReviewArgs({ repoDir, baseRef, baseCommit, type, configFiles }) {
   const args = ['review', '--plain', '--no-color', '--type', normalizeType(type), '--cwd', repoDir];
   const base = String(baseRef ?? '').trim();
@@ -27,8 +41,15 @@ export function buildCodeRabbitEnv({ env, homeDir }) {
   const dir = String(homeDir ?? '').trim();
   if (!dir) return merged;
 
-  merged.HOME = dir;
-  merged.USERPROFILE = dir;
+  // IMPORTANT:
+  // Do not override HOME/USERPROFILE here.
+  //
+  // CodeRabbit uses OS credential storage (e.g. macOS Keychain). If HOME is pointed at
+  // an isolated directory (like .project/coderabbit-home), the underlying keychain
+  // lookup can fail with "Keychain Not Found" and auth will not work in the wrapper.
+  //
+  // We still isolate CodeRabbit's on-disk config/cache under the provided homeDir via
+  // CODERABBIT_HOME + XDG dirs.
   merged.CODERABBIT_HOME = join(dir, '.coderabbit');
   merged.XDG_CONFIG_HOME = join(dir, '.config');
   merged.XDG_CACHE_HOME = join(dir, '.cache');
@@ -50,12 +71,35 @@ export async function runCodeRabbitReview({
 }) {
   const homeDir = (env?.HAPPY_STACKS_CODERABBIT_HOME_DIR ?? env?.HAPPY_LOCAL_CODERABBIT_HOME_DIR ?? '').toString().trim();
   const args = buildCodeRabbitReviewArgs({ repoDir, baseRef, baseCommit, type, configFiles });
-  const res = await runCaptureResult('coderabbit', args, {
-    cwd: repoDir,
-    env: buildCodeRabbitEnv({ env, homeDir }),
-    streamLabel,
-    teeFile,
-    teeLabel,
-  });
-  return { ...res, stdout: res.out, stderr: res.err };
+  const maxAttempts = 50;
+  let last = null;
+  for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+    // eslint-disable-next-line no-await-in-loop
+    const res = await runCaptureResult('coderabbit', args, {
+      cwd: repoDir,
+      env: buildCodeRabbitEnv({ env, homeDir }),
+      streamLabel,
+      teeFile,
+      teeLabel,
+    });
+    last = res;
+    if (res.ok) return { ...res, stdout: res.out, stderr: res.err };
+
+    const retryMs = parseCodeRabbitRateLimitRetryMs(`${res.out ?? ''}\n${res.err ?? ''}`);
+    if (!retryMs) return { ...res, stdout: res.out, stderr: res.err };
+
+    const seconds = Math.ceil(retryMs / 1000);
+    const msg = `[review] coderabbit rate limited; retrying in ${seconds}s (attempt ${attempt}/${maxAttempts})\n`;
+    try {
+      if (teeFile) await appendFile(teeFile, msg);
+    } catch {
+      // ignore
+    }
+    // eslint-disable-next-line no-console
+    console.warn(msg.trimEnd());
+    // eslint-disable-next-line no-await-in-loop
+    await new Promise((r) => setTimeout(r, retryMs));
+  }
+
+  return { ...last, stdout: last?.out ?? '', stderr: last?.err ?? '' };
 }

package/scripts/utils/review/runners/coderabbit.test.mjs

@@ -1,59 +1,26 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { join } from 'node:path';
 
-import { buildCodeRabbitEnv, buildCodeRabbitReviewArgs } from './coderabbit.mjs';
+import { parseCodeRabbitRateLimitRetryMs } from './coderabbit.mjs';
 
-test('buildCodeRabbitReviewArgs builds committed review args by default', () => {
-  const repoDir = '/tmp/repo';
-  const args = buildCodeRabbitReviewArgs({ repoDir, baseRef: 'upstream/main', type: undefined, configFiles: [] });
-  assert.deepEqual(args, ['review', '--plain', '--no-color', '--type', 'committed', '--cwd', repoDir, '--base', 'upstream/main']);
+test('parseCodeRabbitRateLimitRetryMs returns null when no rate limit message is present', () => {
+  assert.equal(parseCodeRabbitRateLimitRetryMs('Review completed ✔'), null);
 });
 
-test('buildCodeRabbitReviewArgs uses --base-commit when provided', () => {
-  const repoDir = '/tmp/repo';
-  const args = buildCodeRabbitReviewArgs({ repoDir, baseCommit: 'abc123', type: 'committed', configFiles: [] });
-  assert.deepEqual(args, ['review', '--plain', '--no-color', '--type', 'committed', '--cwd', repoDir, '--base-commit', 'abc123']);
-});
-
-test('buildCodeRabbitReviewArgs rejects providing both baseRef and baseCommit', () => {
-  assert.throws(
-    () => buildCodeRabbitReviewArgs({ repoDir: '/tmp/repo', baseRef: 'upstream/main', baseCommit: 'abc123', type: 'committed', configFiles: [] }),
-    /mutually exclusive/
+test('parseCodeRabbitRateLimitRetryMs parses the suggested retry delay', () => {
+  const ms = parseCodeRabbitRateLimitRetryMs(
+    '[2026-01-25T22:29:41.623Z] ❌ ERROR: Error: Rate limit exceeded, please try after 3 minutes and 2 seconds'
   );
+  assert.ok(ms);
+  // Allow +1s padding.
+  assert.equal(ms, (3 * 60 + 2 + 1) * 1000);
 });
 
-test('buildCodeRabbitReviewArgs includes --config when files are provided', () => {
-  const repoDir = '/tmp/repo';
-  const args = buildCodeRabbitReviewArgs({
-    repoDir,
-    baseRef: 'upstream/main',
-    type: 'committed',
-    configFiles: ['/tmp/a.md', '/tmp/b.md'],
-  });
-  assert.deepEqual(args, [
-    'review',
-    '--plain',
-    '--no-color',
-    '--type',
-    'committed',
-    '--cwd',
-    repoDir,
-    '--base',
-    'upstream/main',
-    '--config',
-    '/tmp/a.md',
-    '/tmp/b.md',
-  ]);
+test('parseCodeRabbitRateLimitRetryMs supports seconds-only windows', () => {
+  const ms = parseCodeRabbitRateLimitRetryMs(
+    '[2026-01-26T00:27:23.067Z] ❌ ERROR: Error: Rate limit exceeded, please try after 0 minutes and 31 seconds'
+  );
+  assert.ok(ms);
+  assert.equal(ms, (31 + 1) * 1000);
 });
 
-test('buildCodeRabbitEnv overrides HOME/XDG paths when a homeDir is provided', () => {
-  const env = buildCodeRabbitEnv({ env: { PATH: '/bin' }, homeDir: '/tmp/cr-home' });
-  assert.equal(env.PATH, '/bin');
-  assert.equal(env.HOME, '/tmp/cr-home');
-  assert.equal(env.CODERABBIT_HOME, join('/tmp/cr-home', '.coderabbit'));
-  assert.equal(env.XDG_CONFIG_HOME, join('/tmp/cr-home', '.config'));
-  assert.equal(env.XDG_CACHE_HOME, join('/tmp/cr-home', '.cache'));
-  assert.equal(env.XDG_STATE_HOME, join('/tmp/cr-home', '.local', 'state'));
-  assert.equal(env.XDG_DATA_HOME, join('/tmp/cr-home', '.local', 'share'));
-});

package/scripts/utils/review/sliced_runner.mjs

@@ -0,0 +1,39 @@
+import { runWithConcurrencyLimit } from '../proc/parallel.mjs';
+
+/**
+ * Run a list of "slice jobs" with:
+ * - a mandatory sequential first job (preflight)
+ * - parallel execution for the remainder (bounded by `limit`)
+ * - stable, input-order results
+ * - optional early-abort after the first job (e.g. auth/credits missing)
+ */
+export async function runSlicedJobs({ items, limit = 1, run, shouldAbortEarly } = {}) {
+  const list = Array.isArray(items) ? items : [];
+  if (!list.length) return [];
+  if (typeof run !== 'function') throw new Error('[review] runSlicedJobs: missing run()');
+
+  const concurrency = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 1;
+
+  const out = [];
+  // Always run the first item sequentially so we can fail fast on auth/credits problems
+  // before spinning up many long-running review jobs.
+  // eslint-disable-next-line no-await-in-loop
+  const firstRes = await run(list[0]);
+  out.push(firstRes);
+  if (typeof shouldAbortEarly === 'function' && shouldAbortEarly(firstRes)) {
+    return out;
+  }
+
+  if (list.length === 1) return out;
+
+  const rest = list.slice(1);
+  const restRes = await runWithConcurrencyLimit({
+    items: rest,
+    limit: concurrency,
+    fn: async (item) => await run(item),
+  });
+
+  // Preserve input order.
+  return [...out, ...restRes];
+}
+

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

@@ -0,0 +1,47 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { runSlicedJobs } from './sliced_runner.mjs';
+
+test('runSlicedJobs preserves order and respects concurrency', async () => {
+  const items = Array.from({ length: 7 }, (_, i) => ({ index: i + 1 }));
+
+  let active = 0;
+  let maxActive = 0;
+
+  const results = await runSlicedJobs({
+    items,
+    limit: 2,
+    run: async (item) => {
+      active += 1;
+      maxActive = Math.max(maxActive, active);
+      await new Promise((r) => setTimeout(r, 20));
+      active -= 1;
+      return { index: item.index };
+    },
+  });
+
+  assert.equal(maxActive, 2);
+  assert.deepEqual(
+    results.map((r) => r.index),
+    items.map((i) => i.index)
+  );
+});
+
+test('runSlicedJobs can abort early after the first item', async () => {
+  const items = Array.from({ length: 5 }, (_, i) => ({ index: i + 1 }));
+  const seen = [];
+
+  const results = await runSlicedJobs({
+    items,
+    limit: 3,
+    run: async (item) => {
+      seen.push(item.index);
+      return { index: item.index, abort: item.index === 1 };
+    },
+    shouldAbortEarly: (res) => Boolean(res?.abort),
+  });
+
+  assert.deepEqual(seen, [1]);
+  assert.deepEqual(results.map((r) => r.index), [1]);
+});
+

package/scripts/utils/review/tool_home_seed.mjs

@@ -0,0 +1,99 @@
+import { copyFile, cp, mkdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+async function mergeCopyDir({ srcDir, destDir }) {
+  if (!existsSync(srcDir)) return;
+  await mkdir(destDir, { recursive: true });
+  await cp(srcDir, destDir, { recursive: true, force: false, errorOnExist: false });
+}
+
+async function copyFileIfNewer({ srcFile, destFile }) {
+  if (!existsSync(srcFile)) return;
+  try {
+    const srcStat = await stat(srcFile);
+    let destStat = null;
+    try {
+      destStat = await stat(destFile);
+    } catch {
+      destStat = null;
+    }
+    if (!destStat || srcStat.mtimeMs > destStat.mtimeMs) {
+      await mkdir(join(destFile, '..'), { recursive: true });
+      await copyFile(srcFile, destFile);
+    }
+  } catch {
+    // best-effort
+  }
+}
+
+/**
+ * Best-effort: seed CodeRabbit auth/config into an isolated home directory.
+ *
+ * We do not read or print any auth contents; we only copy the on-disk state when present.
+ */
+export async function seedCodeRabbitHomeFromRealHome({ realHomeDir, isolatedHomeDir } = {}) {
+  const real = String(realHomeDir ?? '').trim();
+  const isolated = String(isolatedHomeDir ?? '').trim();
+  if (!real || !isolated || real === isolated) return;
+
+  // Common CodeRabbit state locations:
+  // - ~/.coderabbit/
+  // - ~/.config/coderabbit/ (XDG config)
+  // - ~/.cache/coderabbit/ (XDG cache)
+  // - ~/.local/share/coderabbit/ (XDG data)
+  // - ~/.local/state/coderabbit/ (XDG state)
+  //
+  // We merge-copy without overwriting existing files so a user can explicitly
+  // auth in the isolated dir and we won't clobber it.
+  await mergeCopyDir({ srcDir: join(real, '.coderabbit'), destDir: join(isolated, '.coderabbit') });
+  await mergeCopyDir({ srcDir: join(real, '.config', 'coderabbit'), destDir: join(isolated, '.config', 'coderabbit') });
+  await mergeCopyDir({ srcDir: join(real, '.cache', 'coderabbit'), destDir: join(isolated, '.cache', 'coderabbit') });
+  await mergeCopyDir({ srcDir: join(real, '.local', 'share', 'coderabbit'), destDir: join(isolated, '.local', 'share', 'coderabbit') });
+  await mergeCopyDir({ srcDir: join(real, '.local', 'state', 'coderabbit'), destDir: join(isolated, '.local', 'state', 'coderabbit') });
+
+  // If the user re-authenticated recently, refresh auth.json even when it already exists.
+  await copyFileIfNewer({
+    srcFile: join(real, '.coderabbit', 'auth.json'),
+    destFile: join(isolated, '.coderabbit', 'auth.json'),
+  });
+}
+
+/**
+ * Best-effort: seed Codex auth/config into an isolated CODEX_HOME directory.
+ *
+ * Codex stores auth/config under `CODEX_HOME` (default: ~/.codex). In stack review runs we
+ * use a per-repo isolated home (e.g. .project/codex-home) to avoid polluting ~/.codex and
+ * to keep sandboxed runs self-contained.
+ *
+ * We do not read or print any auth contents; we only copy the on-disk state when present.
+ */
+export async function seedCodexHomeFromRealHome({ realHomeDir, isolatedHomeDir } = {}) {
+  const real = String(realHomeDir ?? '').trim();
+  const isolated = String(isolatedHomeDir ?? '').trim();
+  if (!real || !isolated || real === isolated) return;
+
+  // Codex uses CODEX_HOME/{auth.json,config.toml,...}
+  await copyFileIfNewer({ srcFile: join(real, '.codex', 'auth.json'), destFile: join(isolated, 'auth.json') });
+  await copyFileIfNewer({ srcFile: join(real, '.codex', 'config.toml'), destFile: join(isolated, 'config.toml') });
+}
+
+/**
+ * Best-effort: seed Auggie (Augment CLI) auth/config into an isolated cache directory.
+ *
+ * Auggie uses `~/.augment` by default (see `--augment-cache-dir`), and supports
+ * providing session auth via `AUGMENT_SESSION_AUTH` (same format as `~/.augment/session.json`).
+ *
+ * We do not read or print any auth contents; we only copy the on-disk state when present.
+ */
+export async function seedAugmentHomeFromRealHome({ realHomeDir, isolatedHomeDir } = {}) {
+  const real = String(realHomeDir ?? '').trim();
+  const isolated = String(isolatedHomeDir ?? '').trim();
+  if (!real || !isolated || real === isolated) return;
+
+  // Copy ~/.augment/* into the isolated cache dir.
+  await mergeCopyDir({ srcDir: join(real, '.augment'), destDir: isolated });
+
+  // Refresh session.json when it is newer.
+  await copyFileIfNewer({ srcFile: join(real, '.augment', 'session.json'), destFile: join(isolated, 'session.json') });
+}