auditor-lambda 0.1.0 → 0.2.1

package/audit-code-wrapper-lib.mjs

@@ -1,36 +1,53 @@
-import { access, mkdir, open, readFile, readdir, stat, unlink, writeFile } from 'node:fs/promises';
-import { constants } from 'node:fs';
-import { spawn } from 'node:child_process';
-import { dirname, join, relative, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
+import {
+  access,
+  mkdir,
+  open,
+  readFile,
+  readdir,
+  stat,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { constants } from "node:fs";
+import { spawn } from "node:child_process";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
 const repoRoot = dirname(fileURLToPath(import.meta.url));
-const distEntry = join(repoRoot, 'dist', 'index.js');
-const packageJsonPath = join(repoRoot, 'package.json');
-const promptAssetPath = join(repoRoot, 'skills', 'audit-code', 'audit-code.prompt.md');
-const skillAssetPath = join(repoRoot, 'skills', 'audit-code', 'SKILL.md');
-const tsconfigPath = join(repoRoot, 'tsconfig.json');
-const sourceRoot = join(repoRoot, 'src');
-const buildLockPath = join(repoRoot, '.audit-code-build.lock');
+const distEntry = join(repoRoot, "dist", "index.js");
+const packageJsonPath = join(repoRoot, "package.json");
+const promptAssetPath = join(
+  repoRoot,
+  "skills",
+  "audit-code",
+  "audit-code.prompt.md",
+);
+const skillAssetPath = join(repoRoot, "skills", "audit-code", "SKILL.md");
+const tsconfigPath = join(repoRoot, "tsconfig.json");
+const sourceRoot = join(repoRoot, "src");
+const buildLockPath = join(repoRoot, ".audit-code-build.lock");
 const BUILD_LOCK_MAX_AGE_MS = 5 * 60 * 1000;
 const BUILD_LOCK_WAIT_TIMEOUT_MS = 2 * 60 * 1000;
 const BUILD_LOCK_WAIT_INTERVAL_MS = 200;
-const INSTALL_MARKER_START = '<!-- audit-code:begin -->';
-const INSTALL_MARKER_END = '<!-- audit-code:end -->';
-const INSTALL_GUIDE_FILENAME = 'GETTING-STARTED.md';
-const DEFAULT_INSTALL_HOST = 'all';
-const packageVersion = JSON.parse(await readFile(packageJsonPath, 'utf8')).version;
-
-function hasFlag(argv, name) {
-  return argv.includes(name);
-}
-
-function getFlag(argv, name) {
-  const index = argv.indexOf(name);
-  if (index < 0) return undefined;
-  return argv[index + 1];
-}
-
+const INSTALL_MARKER_START = "<!-- audit-code:begin -->";
+const INSTALL_MARKER_END = "<!-- audit-code:end -->";
+const INSTALL_GUIDE_FILENAME = "GETTING-STARTED.md";
+const DEFAULT_INSTALL_HOST = "all";
+const INSTALLED_PROMPT_FILENAME = "audit-code.import.md";
+const packageVersion = JSON.parse(
+  await readFile(packageJsonPath, "utf8"),
+).version;
+
+function hasFlag(argv, name) {
+  return argv.includes(name);
+}
+
+function getFlag(argv, name) {
+  const index = argv.indexOf(name);
+  if (index < 0) return undefined;
+  return argv[index + 1];
+}
+
 function setDefaultFlag(argv, name, value) {
   if (!hasFlag(argv, name)) {
     argv.push(name, value);
@@ -44,11 +61,11 @@ function requireFlagValue(argv, name) {
   }
   return value;
 }
-
-function npmExecutable() {
-  return process.platform === 'win32' ? 'npm.cmd' : 'npm';
-}
-
+
+function npmExecutable() {
+  return process.platform === "win32" ? "npm.cmd" : "npm";
+}
+
 function nodeExecutable() {
   return process.execPath;
 }
@@ -60,13 +77,13 @@ function quoteForCmd(arg) {
 }
 
 function resolveSpawn(command, args) {
-  if (!(process.platform === 'win32' && /\.(cmd|bat)$/i.test(command))) {
+  if (!(process.platform === "win32" && /\.(cmd|bat)$/i.test(command))) {
     return { command, args };
   }
 
   return {
-    command: process.env.ComSpec ?? 'cmd.exe',
-    args: ['/d', '/s', '/c', [command, ...args].map(quoteForCmd).join(' ')],
+    command: process.env.ComSpec ?? "cmd.exe",
+    args: ["/d", "/s", "/c", [command, ...args].map(quoteForCmd).join(" ")],
   };
 }
 
@@ -75,72 +92,78 @@ function run(command, args, options = {}) {
     const resolved = resolveSpawn(command, args);
     const child = spawn(resolved.command, resolved.args, {
       cwd: repoRoot,
-      stdio: options.capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
-      env: process.env
+      stdio: options.capture ? ["ignore", "pipe", "pipe"] : "inherit",
+      env: process.env,
     });
-
-    let stdout = '';
-    let stderr = '';
-
-    if (options.capture) {
-      child.stdout?.on('data', (chunk) => {
-        stdout += String(chunk);
-      });
-      child.stderr?.on('data', (chunk) => {
-        stderr += String(chunk);
-      });
-    }
-
-    child.on('error', rejectPromise);
-    child.on('exit', (code) => {
-      if (code === 0) {
-        resolvePromise({ stdout, stderr });
-        return;
-      }
-      rejectPromise(new Error(options.capture ? stderr || `Command failed with exit code ${code}.` : `Command failed with exit code ${code}.`));
-    });
-  });
-}
-
-async function sleep(ms) {
-  await new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
-}
-
+
+    let stdout = "";
+    let stderr = "";
+
+    if (options.capture) {
+      child.stdout?.on("data", (chunk) => {
+        stdout += String(chunk);
+      });
+      child.stderr?.on("data", (chunk) => {
+        stderr += String(chunk);
+      });
+    }
+
+    child.on("error", rejectPromise);
+    child.on("exit", (code) => {
+      if (code === 0) {
+        resolvePromise({ stdout, stderr });
+        return;
+      }
+      rejectPromise(
+        new Error(
+          options.capture
+            ? stderr || `Command failed with exit code ${code}.`
+            : `Command failed with exit code ${code}.`,
+        ),
+      );
+    });
+  });
+}
+
+async function sleep(ms) {
+  await new Promise((resolvePromise) => setTimeout(resolvePromise, ms));
+}
+
 async function fileExists(path) {
   try {
     await access(path, constants.F_OK);
     return true;
   } catch {
-    return false;
-  }
-}
-
-async function newestMtimeMs(path) {
-  const stats = await stat(path);
-  if (!stats.isDirectory()) {
-    return stats.mtimeMs;
-  }
-
-  let newest = stats.mtimeMs;
-  const entries = await readdir(path, { withFileTypes: true });
-  for (const entry of entries) {
-    const childPath = join(path, entry.name);
-    if (entry.isDirectory()) {
-      newest = Math.max(newest, await newestMtimeMs(childPath));
-      continue;
-    }
-    if (entry.isFile()) {
-      newest = Math.max(newest, (await stat(childPath)).mtimeMs);
-    }
-  }
-  return newest;
-}
-
+    return false;
+  }
+}
+
+async function newestMtimeMs(path) {
+  const stats = await stat(path);
+  if (!stats.isDirectory()) {
+    return stats.mtimeMs;
+  }
+
+  let newest = stats.mtimeMs;
+  const entries = await readdir(path, { withFileTypes: true });
+  for (const entry of entries) {
+    const childPath = join(path, entry.name);
+    if (entry.isDirectory()) {
+      newest = Math.max(newest, await newestMtimeMs(childPath));
+      continue;
+    }
+    if (entry.isFile()) {
+      newest = Math.max(newest, (await stat(childPath)).mtimeMs);
+    }
+  }
+  return newest;
+}
+
 async function shouldBuildDist() {
   if (!(await fileExists(distEntry))) {
     if (!(await fileExists(sourceRoot)) || !(await fileExists(tsconfigPath))) {
       throw new Error(
-        'Bundled dist is missing and source files are unavailable for rebuild.',
+        "Bundled dist is missing and source files are unavailable for rebuild.",
       );
     }
     return true;
@@ -152,115 +175,120 @@ async function shouldBuildDist() {
 
   const distMtime = (await stat(distEntry)).mtimeMs;
   const sourceMtime = await newestMtimeMs(sourceRoot);
-  const tsconfigMtime = (await stat(tsconfigPath)).mtimeMs;
-  const packageJsonMtime = (await stat(packageJsonPath)).mtimeMs;
-  const newestInput = Math.max(sourceMtime, tsconfigMtime, packageJsonMtime);
-  return distMtime < newestInput;
-}
-
-async function releaseBuildLock(handle) {
-  try {
-    await handle?.close();
-  } finally {
-    await unlink(buildLockPath).catch(() => {});
-  }
-}
-
-async function waitForPeerBuild() {
-  const start = Date.now();
-
-  while (true) {
-    if (!(await fileExists(buildLockPath))) {
-      return;
-    }
-
-    if (Date.now() - start > BUILD_LOCK_WAIT_TIMEOUT_MS) {
-      throw new Error(`Timed out waiting for build lock ${buildLockPath}.`);
-    }
-
-    await sleep(BUILD_LOCK_WAIT_INTERVAL_MS);
-  }
-}
-
-async function acquireBuildLock() {
-  while (true) {
-    try {
-      const handle = await open(buildLockPath, 'wx');
-      await handle.writeFile(JSON.stringify({ pid: process.pid, acquired_at: new Date().toISOString() }));
-      return handle;
-    } catch (error) {
-      if (error && error.code === 'EEXIST') {
-        try {
-          const lockStats = await stat(buildLockPath);
-          if (Date.now() - lockStats.mtimeMs > BUILD_LOCK_MAX_AGE_MS) {
-            await unlink(buildLockPath).catch(() => {});
-            continue;
-          }
-        } catch {
-          continue;
-        }
-
-        await waitForPeerBuild();
-        if (!(await shouldBuildDist())) {
-          return null;
-        }
-        continue;
-      }
-      throw error;
-    }
-  }
-}
-
-async function ensureBuilt() {
-  if (!(await shouldBuildDist())) {
-    return;
-  }
-
-  const lockHandle = await acquireBuildLock();
-  if (!lockHandle) {
-    return;
-  }
-
-  try {
-    if (!(await shouldBuildDist())) {
-      return;
-    }
-    await run(npmExecutable(), ['run', 'build']);
-  } finally {
-    await releaseBuildLock(lockHandle);
-  }
-}
-
+  const tsconfigMtime = (await stat(tsconfigPath)).mtimeMs;
+  const packageJsonMtime = (await stat(packageJsonPath)).mtimeMs;
+  const newestInput = Math.max(sourceMtime, tsconfigMtime, packageJsonMtime);
+  return distMtime < newestInput;
+}
+
+async function releaseBuildLock(handle) {
+  try {
+    await handle?.close();
+  } finally {
+    await unlink(buildLockPath).catch(() => {});
+  }
+}
+
+async function waitForPeerBuild() {
+  const start = Date.now();
+
+  while (true) {
+    if (!(await fileExists(buildLockPath))) {
+      return;
+    }
+
+    if (Date.now() - start > BUILD_LOCK_WAIT_TIMEOUT_MS) {
+      throw new Error(`Timed out waiting for build lock ${buildLockPath}.`);
+    }
+
+    await sleep(BUILD_LOCK_WAIT_INTERVAL_MS);
+  }
+}
+
+async function acquireBuildLock() {
+  while (true) {
+    try {
+      const handle = await open(buildLockPath, "wx");
+      await handle.writeFile(
+        JSON.stringify({
+          pid: process.pid,
+          acquired_at: new Date().toISOString(),
+        }),
+      );
+      return handle;
+    } catch (error) {
+      if (error && error.code === "EEXIST") {
+        try {
+          const lockStats = await stat(buildLockPath);
+          if (Date.now() - lockStats.mtimeMs > BUILD_LOCK_MAX_AGE_MS) {
+            await unlink(buildLockPath).catch(() => {});
+            continue;
+          }
+        } catch {
+          continue;
+        }
+
+        await waitForPeerBuild();
+        if (!(await shouldBuildDist())) {
+          return null;
+        }
+        continue;
+      }
+      throw error;
+    }
+  }
+}
+
+async function ensureBuilt() {
+  if (!(await shouldBuildDist())) {
+    return;
+  }
+
+  const lockHandle = await acquireBuildLock();
+  if (!lockHandle) {
+    return;
+  }
+
+  try {
+    if (!(await shouldBuildDist())) {
+      return;
+    }
+    await run(npmExecutable(), ["run", "build"]);
+  } finally {
+    await releaseBuildLock(lockHandle);
+  }
+}
+
 function printHelp({ usageName, preferredEntrypoint }) {
   const lines = [
     `Usage: node ${usageName} [--single-step] [--root PATH] [--artifacts-dir PATH] [--results FILE] [--updates FILE] [--external-analyzer-results FILE]`,
-    '',
-    'Helper commands:',
-    '- prompt-path prints the absolute path to the canonical /audit-code prompt asset',
-    '- install bootstraps /audit-code into supported repo-local host surfaces',
-    '- install-host --host copilot keeps the narrower Copilot-focused install path available',
-    '- validate checks the current artifact bundle plus session-config/provider readiness and exits non-zero when issues exist',
-    '',
-    'Primary usage:',
-    '- from the repository root, run the wrapper with no arguments',
-    '- default behavior advances the audit automatically until it completes or no further automatic progress is possible',
-    '- each wrapper response refreshes operator-handoff.json and operator-handoff.md under the artifacts directory',
-    '- use --single-step only for debugging or bounded-step testing',
-    '',
-    'Defaults:',
-    '- --root .',
-    '- --artifacts-dir <root>/.audit-artifacts',
-    '',
-    'Completion signals:',
-    '- done: audit_state.status is complete',
-    '- blocked/no further automatic progress: progress_made is false and next_likely_step is null'
-  ];
-
-  if (preferredEntrypoint && preferredEntrypoint !== usageName) {
-    lines.push('', `Preferred entrypoint: node ${preferredEntrypoint}`);
-  }
-
-  console.log(lines.join('\n'));
+    "",
+    "Helper commands:",
+    "- prompt-path prints the absolute path to the canonical /audit-code prompt asset",
+    "- install bootstraps /audit-code into supported repo-local host surfaces",
+    "- install-host --host copilot keeps the narrower Copilot-focused install path available",
+    "- validate checks the current artifact bundle plus session-config/provider readiness and exits non-zero when issues exist",
+    "",
+    "Primary usage:",
+    "- from the repository root, run the wrapper with no arguments",
+    "- default behavior advances the audit automatically until it completes or no further automatic progress is possible",
+    "- each wrapper response refreshes operator-handoff.json and operator-handoff.md under the artifacts directory",
+    "- use --single-step only for debugging or bounded-step testing",
+    "",
+    "Defaults:",
+    "- --root .",
+    "- --artifacts-dir <root>/.audit-artifacts",
+    "",
+    "Completion signals:",
+    "- done: audit_state.status is complete",
+    "- blocked/no further automatic progress: progress_made is false and next_likely_step is null",
+  ];
+
+  if (preferredEntrypoint && preferredEntrypoint !== usageName) {
+    lines.push("", `Preferred entrypoint: node ${preferredEntrypoint}`);
+  }
+
+  console.log(lines.join("\n"));
 }
 
 async function printPromptPath() {
@@ -272,7 +300,7 @@ async function printPromptPath() {
 }
 
 function normalizeNewlines(value) {
-  return value.replace(/\r\n/g, '\n');
+  return value.replace(/\r\n/g, "\n");
 }
 
 function splitFrontmatter(markdown) {
@@ -294,22 +322,22 @@ function renderFrontmatter(fields) {
       return false;
     }
 
-    if (typeof value === 'string') {
+    if (typeof value === "string") {
       return value.length > 0;
     }
 
     return true;
   });
   if (entries.length === 0) {
-    return '';
+    return "";
   }
 
   return [
-    '---',
+    "---",
     ...entries.map(([key, value]) => `${key}: ${value}`),
-    '---',
-    '',
-  ].join('\n');
+    "---",
+    "",
+  ].join("\n");
 }
 
 function renderPromptFile(fields, body) {
@@ -317,19 +345,19 @@ function renderPromptFile(fields, body) {
 }
 
 function toRepoRelativePath(root, targetPath) {
-  const value = relative(root, targetPath).replace(/\\/g, '/');
-  return value.length > 0 ? value : '.';
+  const value = relative(root, targetPath).replace(/\\/g, "/");
+  return value.length > 0 ? value : ".";
 }
 
 function buildInstallDirective(relativePromptPath) {
   return [
     INSTALL_MARKER_START,
-    '## /audit-code',
-    'When the user enters `/audit-code`, treat it as this repository\'s autonomous audit workflow.',
-    `If your host does not automatically register the installed slash command file, load and follow [the repo-local audit directive](${relativePromptPath.replace(/\\/g, '/')}).`,
-    'Normal usage should stay conversation-first and avoid manual `--root`, provider flags, or model-selection arguments.',
+    "## /audit-code",
+    "When the user enters `/audit-code`, treat it as this repository's autonomous audit workflow.",
+    `If your host does not automatically register the installed slash command file, load and follow [the repo-local audit directive](${relativePromptPath.replace(/\\/g, "/")}).`,
+    "Normal usage should stay conversation-first and avoid manual `--root`, provider flags, or model-selection arguments.",
     INSTALL_MARKER_END,
-  ].join('\n');
+  ].join("\n");
 }
 
 function buildInstallHostGuidance({
@@ -341,90 +369,90 @@ function buildInstallHostGuidance({
 
   if (slashCommandSurfaces.vscode_prompt) {
     guidance.push({
-      host: 'vscode',
-      label: 'VS Code',
-      support_level: 'supported',
-      setup_kind: 'repo-local-slash-command',
+      host: "vscode",
+      label: "VS Code",
+      support_level: "supported",
+      setup_kind: "repo-local-slash-command",
       summary:
-        'Use the generated VS Code / Copilot prompt surface, then invoke `/audit-code` in chat.',
+        "Use the generated VS Code / Copilot prompt surface, then invoke `/audit-code` in chat.",
       primary_path: slashCommandSurfaces.vscode_prompt,
       supporting_paths: [
         instructionSurfaces.copilot_instructions,
         instructionSurfaces.agents,
       ].filter(Boolean),
       steps: [
-        'Open this repository in VS Code or GitHub Copilot Chat.',
-        'Invoke `/audit-code` in chat.',
-        'Use the integrated terminal and run `audit-code` only when you intentionally need the repo-local backend fallback.',
+        "Open this repository in VS Code or GitHub Copilot Chat.",
+        "Invoke `/audit-code` in chat.",
+        "Use the integrated terminal and run `audit-code` only when you intentionally need the repo-local backend fallback.",
       ],
     });
   }
 
   if (slashCommandSurfaces.opencode_command) {
     guidance.push({
-      host: 'opencode',
-      label: 'OpenCode',
-      support_level: 'supported',
-      setup_kind: 'repo-local-slash-command',
+      host: "opencode",
+      label: "OpenCode",
+      support_level: "supported",
+      setup_kind: "repo-local-slash-command",
       summary:
-        'Use the generated OpenCode command surface so `/audit-code` is available without extra provider flags.',
+        "Use the generated OpenCode command surface so `/audit-code` is available without extra provider flags.",
       primary_path: slashCommandSurfaces.opencode_command,
       supporting_paths: [instructionSurfaces.agents].filter(Boolean),
       steps: [
-        'Open this repository in OpenCode.',
-        'Invoke `/audit-code` from the OpenCode command surface.',
-        'Use the repo-local backend wrapper only when you intentionally need the fallback automation path.',
+        "Open this repository in OpenCode.",
+        "Invoke `/audit-code` from the OpenCode command surface.",
+        "Use the repo-local backend wrapper only when you intentionally need the fallback automation path.",
       ],
     });
   }
 
   if (slashCommandSurfaces.claude_code_command) {
     guidance.push({
-      host: 'claude-code',
-      label: 'Claude Code',
-      support_level: 'supported',
-      setup_kind: 'repo-local-slash-command',
+      host: "claude-code",
+      label: "Claude Code",
+      support_level: "supported",
+      setup_kind: "repo-local-slash-command",
       summary:
-        'Use the generated Claude Code command surface so `/audit-code` is available inside the repository without extra provider wiring.',
+        "Use the generated Claude Code command surface so `/audit-code` is available inside the repository without extra provider wiring.",
       primary_path: slashCommandSurfaces.claude_code_command,
       supporting_paths: [instructionSurfaces.claude].filter(Boolean),
       steps: [
-        'Open this repository in Claude Code.',
-        'Invoke `/audit-code` from the Claude Code project command surface.',
-        'Use the terminal fallback and run `audit-code` only when you intentionally need the repo-local backend wrapper.',
+        "Open this repository in Claude Code.",
+        "Invoke `/audit-code` from the Claude Code project command surface.",
+        "Use the terminal fallback and run `audit-code` only when you intentionally need the repo-local backend wrapper.",
       ],
     });
   }
 
   guidance.push({
-    host: 'claude-desktop',
-    label: 'Claude Desktop',
-    support_level: 'manual-import',
-    setup_kind: 'prompt-import',
+    host: "claude-desktop",
+    label: "Claude Desktop",
+    support_level: "manual-import",
+    setup_kind: "prompt-import",
     summary:
-      'No verified project-local slash-command surface is shipped for Claude Desktop, so use the installed prompt asset as the primary path.',
+      "No verified project-local slash-command surface is shipped for Claude Desktop, so use the installed prompt asset as the primary path.",
     primary_path: installedPromptPath,
     supporting_paths: [instructionSurfaces.claude].filter(Boolean),
     steps: [
-      'Import the installed prompt asset into Claude Desktop\'s prompt or instruction surface.',
-      'Invoke `/audit-code` conversationally inside Claude Desktop after the prompt is available.',
-      'If you intentionally need the repo-local backend fallback instead, run `audit-code` from the repository root.',
+      "Import the installed prompt asset into Claude Desktop's prompt or instruction surface.",
+      "Invoke `/audit-code` conversationally inside Claude Desktop after the prompt is available.",
+      "If you intentionally need the repo-local backend fallback instead, run `audit-code` from the repository root.",
     ],
   });
 
   guidance.push({
-    host: 'antigravity',
-    label: 'Antigravity',
-    support_level: 'manual-import',
-    setup_kind: 'prompt-import-or-terminal',
+    host: "antigravity",
+    label: "Antigravity",
+    support_level: "manual-import",
+    setup_kind: "prompt-import-or-terminal",
     summary:
-      'No verified repo-local slash-command surface is shipped for Antigravity, so start from the installed prompt asset or an Antigravity-managed terminal.',
+      "No verified repo-local slash-command surface is shipped for Antigravity, so start from the installed prompt asset or an Antigravity-managed terminal.",
     primary_path: installedPromptPath,
     supporting_paths: [instructionSurfaces.agents].filter(Boolean),
     steps: [
-      'Import the installed prompt asset into Antigravity\'s prompt or instruction surface when that surface is available.',
-      'Invoke `/audit-code` conversationally inside Antigravity.',
-      'If you prefer the backend fallback, run `audit-code` from an Antigravity-managed terminal with `local-subprocess` first.',
+      "Import the installed prompt asset into Antigravity's prompt or instruction surface when that surface is available.",
+      "Invoke `/audit-code` conversationally inside Antigravity.",
+      "If you prefer the backend fallback, run `audit-code` from an Antigravity-managed terminal with `local-subprocess` first.",
     ],
   });
 
@@ -434,30 +462,30 @@ function buildInstallHostGuidance({
 function renderInstallHostSection(root, guide) {
   const lines = [
     `## ${guide.label}`,
-    '',
+    "",
     `Support level: ${guide.support_level}`,
     `Setup kind: ${guide.setup_kind}`,
-    '',
+    "",
     guide.summary,
-    '',
-    'Primary repo-local path:',
+    "",
+    "Primary repo-local path:",
     `- \`${toRepoRelativePath(root, guide.primary_path)}\``,
   ];
 
   if (guide.supporting_paths.length > 0) {
-    lines.push('', 'Supporting repo-local paths:');
+    lines.push("", "Supporting repo-local paths:");
     for (const targetPath of guide.supporting_paths) {
       lines.push(`- \`${toRepoRelativePath(root, targetPath)}\``);
     }
   }
 
-  lines.push('', 'Recommended steps:');
+  lines.push("", "Recommended steps:");
   for (const step of guide.steps) {
     lines.push(`- ${step}`);
   }
-  lines.push('');
+  lines.push("");
 
-  return lines.join('\n');
+  return lines.join("\n");
 }
 
 function renderInstallGuide({
@@ -473,67 +501,67 @@ function renderInstallGuide({
   const slashCommandPaths = Object.values(slashCommandSurfaces).filter(Boolean);
   const instructionPaths = Object.values(instructionSurfaces).filter(Boolean);
   const lines = [
-    '# audit-code bootstrap guide',
-    '',
-    'The canonical product route is `/audit-code` in conversation.',
-    '',
-    'Canonical installed assets:',
+    "# audit-code bootstrap guide",
+    "",
+    "The canonical product route is `/audit-code` in conversation.",
+    "",
+    "Canonical installed assets:",
     `- prompt asset: \`${toRepoRelativePath(root, installedPromptPath)}\``,
     `- skill asset: \`${toRepoRelativePath(root, installedSkillPath)}\``,
   ];
 
   if (slashCommandPaths.length > 0) {
-    lines.push('', 'Repo-local slash-command surfaces:');
+    lines.push("", "Repo-local slash-command surfaces:");
     for (const targetPath of slashCommandPaths) {
       lines.push(`- \`${toRepoRelativePath(root, targetPath)}\``);
     }
   }
 
   if (instructionPaths.length > 0) {
-    lines.push('', 'Compatibility instruction surfaces:');
+    lines.push("", "Compatibility instruction surfaces:");
     for (const targetPath of instructionPaths) {
       lines.push(`- \`${toRepoRelativePath(root, targetPath)}\``);
     }
   }
 
-  lines.push('', 'Host-specific quick starts:');
+  lines.push("", "Host-specific quick starts:");
   for (const guide of hostGuidance) {
     lines.push(`- ${guide.label}: ${guide.summary}`);
   }
 
   for (const guide of hostGuidance) {
-    lines.push('', renderInstallHostSection(root, guide).trimEnd());
+    lines.push("", renderInstallHostSection(root, guide).trimEnd());
   }
 
   lines.push(
-    '',
-    'Backend fallback:',
-    '- from the repository root, run `audit-code` only when you intentionally need the repo-local backend wrapper',
+    "",
+    "Backend fallback:",
+    "- from the repository root, run `audit-code` only when you intentionally need the repo-local backend wrapper",
   );
 
   if (unsupportedHosts.length > 0) {
-    lines.push('', 'Hosts still requiring extra handling today:');
+    lines.push("", "Hosts still requiring extra handling today:");
     for (const item of unsupportedHosts) {
       lines.push(`- ${item.host}: ${item.reason}`);
     }
   }
 
-  if (host !== 'all') {
+  if (host !== "all") {
     lines.push(
-      '',
+      "",
       `This install was scoped to \`${host}\`, so some repo-local surfaces may be intentionally omitted.`,
     );
   }
 
-  lines.push('');
-  return lines.join('\n');
+  lines.push("");
+  return lines.join("\n");
 }
 
 function upsertManagedBlock(existingContent, blockContent) {
   const normalized = normalizeNewlines(existingContent);
   const blockPattern = new RegExp(
     `${INSTALL_MARKER_START}[\\s\\S]*?${INSTALL_MARKER_END}`,
-    'u',
+    "u",
   );
 
   if (blockPattern.test(normalized)) {
@@ -544,34 +572,34 @@ function upsertManagedBlock(existingContent, blockContent) {
     return `${blockContent}\n`;
   }
 
-  return `${normalized.replace(/\s+$/u, '')}\n\n${blockContent}\n`;
+  return `${normalized.replace(/\s+$/u, "")}\n\n${blockContent}\n`;
 }
 
 async function writeManagedMarkdown(targetPath, blockContent) {
   const existed = await fileExists(targetPath);
-  const existingContent = existed ? await readFile(targetPath, 'utf8') : '';
+  const existingContent = existed ? await readFile(targetPath, "utf8") : "";
   const nextContent = upsertManagedBlock(existingContent, blockContent);
   await mkdir(dirname(targetPath), { recursive: true });
-  await writeFile(targetPath, nextContent, 'utf8');
+  await writeFile(targetPath, nextContent, "utf8");
   return {
     path: targetPath,
-    mode: existed ? 'updated' : 'created',
+    mode: existed ? "updated" : "created",
   };
 }
 
 async function writeGeneratedMarkdown(targetPath, content) {
   const existed = await fileExists(targetPath);
   await mkdir(dirname(targetPath), { recursive: true });
-  await writeFile(targetPath, content, 'utf8');
+  await writeFile(targetPath, content, "utf8");
   return {
     path: targetPath,
-    mode: existed ? 'updated' : 'created',
+    mode: existed ? "updated" : "created",
   };
 }
 
 function getInstallProfile(host) {
   switch (host) {
-    case 'all':
+    case "all":
       return {
         writeVSCodePrompt: true,
         writeCopilotInstructions: true,
@@ -581,7 +609,7 @@ function getInstallProfile(host) {
         writeClaudeCommand: true,
         writeCompatibilitySkills: true,
       };
-    case 'copilot':
+    case "copilot":
       return {
         writeVSCodePrompt: true,
         writeCopilotInstructions: true,
@@ -591,7 +619,7 @@ function getInstallProfile(host) {
         writeClaudeCommand: false,
         writeCompatibilitySkills: false,
       };
-    case 'vscode':
+    case "vscode":
       return {
         writeVSCodePrompt: true,
         writeCopilotInstructions: true,
@@ -601,7 +629,7 @@ function getInstallProfile(host) {
         writeClaudeCommand: false,
         writeCompatibilitySkills: false,
       };
-    case 'opencode':
+    case "opencode":
       return {
         writeVSCodePrompt: false,
         writeCopilotInstructions: false,
@@ -611,7 +639,7 @@ function getInstallProfile(host) {
         writeClaudeCommand: false,
         writeCompatibilitySkills: true,
       };
-    case 'claude-code':
+    case "claude-code":
       return {
         writeVSCodePrompt: false,
         writeCopilotInstructions: false,
@@ -642,48 +670,65 @@ async function assertDirectoryExists(path, description) {
 }
 
 async function installBootstrap(argv) {
-  const host = (getFlag(argv, '--host') ?? DEFAULT_INSTALL_HOST).toLowerCase();
-  const root = resolve(getFlag(argv, '--root') ?? '.');
-  await assertDirectoryExists(root, 'Target repository root');
+  const host = (getFlag(argv, "--host") ?? DEFAULT_INSTALL_HOST).toLowerCase();
+  const root = resolve(getFlag(argv, "--root") ?? ".");
+  await assertDirectoryExists(root, "Target repository root");
   const profile = getInstallProfile(host);
-  const promptSource = await readFile(promptAssetPath, 'utf8');
-  const skillSource = await readFile(skillAssetPath, 'utf8');
+  const promptSource = await readFile(promptAssetPath, "utf8");
+  const skillSource = await readFile(skillAssetPath, "utf8");
   const { body: promptBody } = splitFrontmatter(promptSource);
-  const installedPromptPath = join(root, '.audit-code', 'install', 'audit-code.prompt.md');
-  const installedSkillPath = join(root, '.audit-code', 'install', 'SKILL.md');
-  const installGuidePath = join(root, '.audit-code', 'install', INSTALL_GUIDE_FILENAME);
+  const installedPromptPath = join(
+    root,
+    ".audit-code",
+    "install",
+    INSTALLED_PROMPT_FILENAME,
+  );
+  const legacyInstalledPromptPath = join(
+    root,
+    ".audit-code",
+    "install",
+    "audit-code.prompt.md",
+  );
+  const installedSkillPath = join(root, ".audit-code", "install", "SKILL.md");
+  const installGuidePath = join(
+    root,
+    ".audit-code",
+    "install",
+    INSTALL_GUIDE_FILENAME,
+  );
   const slashCommandSurfaces = {
     vscode_prompt: profile.writeVSCodePrompt
-      ? join(root, '.github', 'prompts', 'audit-code.prompt.md')
+      ? join(root, ".github", "prompts", "audit-code.prompt.md")
       : null,
     opencode_command: profile.writeOpenCodeCommand
-      ? join(root, '.opencode', 'commands', 'audit-code.md')
+      ? join(root, ".opencode", "commands", "audit-code.md")
       : null,
     claude_code_command: profile.writeClaudeCommand
-      ? join(root, '.claude', 'commands', 'audit-code.md')
+      ? join(root, ".claude", "commands", "audit-code.md")
       : null,
   };
   const instructionSurfaces = {
     copilot_instructions: profile.writeCopilotInstructions
-      ? join(root, '.github', 'copilot-instructions.md')
+      ? join(root, ".github", "copilot-instructions.md")
       : null,
-    agents: profile.writeAgents ? join(root, 'AGENTS.md') : null,
-    claude: profile.writeClaudeMemory ? join(root, 'CLAUDE.md') : null,
+    agents: profile.writeAgents ? join(root, "AGENTS.md") : null,
+    claude: profile.writeClaudeMemory ? join(root, "CLAUDE.md") : null,
   };
-  const unsupportedHosts = host === 'all'
-    ? [
-        {
-          host: 'claude-desktop',
-          reason:
-            'No verified project-local slash-command installation surface is currently shipped for Claude Desktop.',
-        },
-        {
-          host: 'antigravity',
-          reason:
-            'No verified repo-local slash-command installation surface is currently shipped for Antigravity.',
-        },
-      ]
-    : [];
+  const unsupportedHosts =
+    host === "all"
+      ? [
+          {
+            host: "claude-desktop",
+            reason:
+              "No verified project-local slash-command installation surface is currently shipped for Claude Desktop.",
+          },
+          {
+            host: "antigravity",
+            reason:
+              "No verified repo-local slash-command installation surface is currently shipped for Antigravity.",
+          },
+        ]
+      : [];
   const hostGuidance = buildInstallHostGuidance({
     installedPromptPath,
     slashCommandSurfaces,
@@ -691,23 +736,21 @@ async function installBootstrap(argv) {
   });
 
   const results = [];
-  results.push(
-    await writeGeneratedMarkdown(
-      installedPromptPath,
-      promptSource,
-    ),
-  );
+  if (await fileExists(legacyInstalledPromptPath)) {
+    await unlink(legacyInstalledPromptPath).catch(() => {});
+  }
+  results.push(await writeGeneratedMarkdown(installedPromptPath, promptSource));
   results.push(await writeGeneratedMarkdown(installedSkillPath, skillSource));
 
   if (profile.writeVSCodePrompt) {
     results.push(
       await writeGeneratedMarkdown(
-        join(root, '.github', 'prompts', 'audit-code.prompt.md'),
+        join(root, ".github", "prompts", "audit-code.prompt.md"),
         renderPromptFile(
           {
-            name: 'audit-code',
-            description: 'Autonomous local loop code auditing',
-            agent: 'agent',
+            name: "audit-code",
+            description: "Autonomous local loop code auditing",
+            agent: "agent",
           },
           promptBody,
         ),
@@ -718,11 +761,11 @@ async function installBootstrap(argv) {
   if (profile.writeOpenCodeCommand) {
     results.push(
       await writeGeneratedMarkdown(
-        join(root, '.opencode', 'commands', 'audit-code.md'),
+        join(root, ".opencode", "commands", "audit-code.md"),
         renderPromptFile(
           {
-            description: 'Autonomous local loop code auditing',
-            agent: 'build',
+            description: "Autonomous local loop code auditing",
+            agent: "build",
             subtask: false,
           },
           promptBody,
@@ -734,10 +777,10 @@ async function installBootstrap(argv) {
   if (profile.writeClaudeCommand) {
     results.push(
       await writeGeneratedMarkdown(
-        join(root, '.claude', 'commands', 'audit-code.md'),
+        join(root, ".claude", "commands", "audit-code.md"),
         renderPromptFile(
           {
-            description: 'Autonomous local loop code auditing',
+            description: "Autonomous local loop code auditing",
           },
           promptBody,
         ),
@@ -745,14 +788,16 @@ async function installBootstrap(argv) {
     );
   }
 
-  const compatibilityBlockTargets = Object.values(instructionSurfaces).filter(Boolean);
+  const compatibilityBlockTargets =
+    Object.values(instructionSurfaces).filter(Boolean);
 
   for (const targetPath of compatibilityBlockTargets) {
     results.push(
       await writeManagedMarkdown(
         targetPath,
         buildInstallDirective(
-          relative(dirname(targetPath), installedPromptPath) || './.audit-code/install/audit-code.prompt.md',
+          relative(dirname(targetPath), installedPromptPath) ||
+            `./.audit-code/install/${INSTALLED_PROMPT_FILENAME}`,
         ),
       ),
     );
@@ -760,18 +805,18 @@ async function installBootstrap(argv) {
 
   if (profile.writeCompatibilitySkills) {
     const skillTargets = [
-      join(root, '.opencode', 'skills', 'audit-code'),
-      join(root, '.claude', 'skills', 'audit-code'),
-      join(root, '.agents', 'skills', 'audit-code'),
+      join(root, ".opencode", "skills", "audit-code"),
+      join(root, ".claude", "skills", "audit-code"),
+      join(root, ".agents", "skills", "audit-code"),
     ];
 
     for (const targetDir of skillTargets) {
       results.push(
-        await writeGeneratedMarkdown(join(targetDir, 'SKILL.md'), skillSource),
+        await writeGeneratedMarkdown(join(targetDir, "SKILL.md"), skillSource),
       );
       results.push(
         await writeGeneratedMarkdown(
-          join(targetDir, 'audit-code.prompt.md'),
+          join(targetDir, "audit-code.prompt.md"),
           promptSource,
         ),
       );
@@ -794,6 +839,27 @@ async function installBootstrap(argv) {
     ),
   );
 
+  const sessionConfigPath = join(
+    root,
+    ".audit-artifacts",
+    "session-config.json",
+  );
+  let sessionConfigWritten = false;
+  if (!(await fileExists(sessionConfigPath))) {
+    const insideClaudeCode = Boolean(process.env.CLAUDECODE);
+    const defaultConfig = insideClaudeCode
+      ? { provider: "local-subprocess" }
+      : { provider: "auto" };
+    await mkdir(dirname(sessionConfigPath), { recursive: true });
+    await writeFile(
+      sessionConfigPath,
+      JSON.stringify(defaultConfig, null, 2) + "\n",
+      "utf8",
+    );
+    results.push({ path: sessionConfigPath, mode: "created" });
+    sessionConfigWritten = true;
+  }
+
   console.log(
     JSON.stringify(
       {
@@ -809,9 +875,9 @@ async function installBootstrap(argv) {
         host_guidance: hostGuidance,
         unsupported_hosts: unsupportedHosts,
         next_steps: [
-          'Open the repository in your preferred host and follow the matching host_guidance entry.',
+          "Open the repository in your preferred host and follow the matching host_guidance entry.",
           `Open ${installGuidePath} for repo-local quick-start steps for VS Code, OpenCode, Claude Code, Claude Desktop, and Antigravity.`,
-          'If a host does not auto-discover slash commands, use the installed prompt asset or the listed compatibility instruction surfaces.',
+          "If a host does not auto-discover slash commands, use the installed prompt asset or the listed compatibility instruction surfaces.",
         ],
       },
       null,
@@ -821,9 +887,9 @@ async function installBootstrap(argv) {
 }
 
 async function installHostPrompt(argv) {
-  const host = requireFlagValue(argv, '--host').toLowerCase();
+  const host = requireFlagValue(argv, "--host").toLowerCase();
 
-  if (host !== 'copilot') {
+  if (host !== "copilot") {
     throw new Error(
       `install-host currently supports only "copilot". Use "install --host ${host}" for the broader bootstrap flow.`,
     );
@@ -832,13 +898,20 @@ async function installHostPrompt(argv) {
   await installBootstrap(argv);
 }
 
-async function runDistCommand(commandName, argv, { ensureArtifactsDir = false } = {}) {
+async function runDistCommand(
+  commandName,
+  argv,
+  { ensureArtifactsDir = false } = {},
+) {
   const commandArgs = [...argv];
-  const rootValue = resolve(getFlag(commandArgs, '--root') ?? '.');
-  const artifactsDir = resolve(getFlag(commandArgs, '--artifacts-dir') ?? join(rootValue, '.audit-artifacts'));
+  const rootValue = resolve(getFlag(commandArgs, "--root") ?? ".");
+  const artifactsDir = resolve(
+    getFlag(commandArgs, "--artifacts-dir") ??
+      join(rootValue, ".audit-artifacts"),
+  );
 
-  setDefaultFlag(commandArgs, '--root', rootValue);
-  setDefaultFlag(commandArgs, '--artifacts-dir', artifactsDir);
+  setDefaultFlag(commandArgs, "--root", rootValue);
+  setDefaultFlag(commandArgs, "--artifacts-dir", artifactsDir);
 
   if (ensureArtifactsDir) {
     await mkdir(artifactsDir, { recursive: true });
@@ -852,54 +925,59 @@ export async function runAuditCodeWrapper({
   usageName,
   argv = process.argv.slice(2),
   ensureArtifactsDir = true,
-  preferredEntrypoint,
-  defaultSingleStep = false
-}) {
-  if (hasFlag(argv, '--help') || hasFlag(argv, '-h')) {
-    printHelp({ usageName, preferredEntrypoint });
-    return;
-  }
-
-  if (hasFlag(argv, '--version') || hasFlag(argv, '-v')) {
+  preferredEntrypoint,
+  defaultSingleStep = false,
+}) {
+  if (hasFlag(argv, "--help") || hasFlag(argv, "-h")) {
+    printHelp({ usageName, preferredEntrypoint });
+    return;
+  }
+
+  if (hasFlag(argv, "--version") || hasFlag(argv, "-v")) {
     console.log(packageVersion);
     return;
   }
 
-  if (argv[0] === 'prompt-path') {
+  if (argv[0] === "prompt-path") {
     await printPromptPath();
     return;
   }
 
-  if (argv[0] === 'install') {
+  if (argv[0] === "install") {
     await installBootstrap(argv.slice(1));
     return;
   }
 
-  if (argv[0] === 'install-host') {
+  if (argv[0] === "install-host") {
     await installHostPrompt(argv.slice(1));
     return;
   }
 
-  if (argv[0] === 'validate') {
-    await runDistCommand('validate', argv.slice(1));
+  if (argv[0] === "validate") {
+    await runDistCommand("validate", argv.slice(1));
     return;
   }
 
   const wrapperArgs = [...argv];
-  if (defaultSingleStep && !hasFlag(wrapperArgs, '--single-step')) {
-    wrapperArgs.push('--single-step');
-  }
-  const rootValue = resolve(getFlag(wrapperArgs, '--root') ?? '.');
-  const artifactsDir = resolve(getFlag(wrapperArgs, '--artifacts-dir') ?? join(rootValue, '.audit-artifacts'));
-
-  setDefaultFlag(wrapperArgs, '--root', rootValue);
-  setDefaultFlag(wrapperArgs, '--artifacts-dir', artifactsDir);
-
-  if (ensureArtifactsDir) {
-    await mkdir(artifactsDir, { recursive: true });
-  }
-
-  await ensureBuilt();
-  const command = hasFlag(wrapperArgs, '--single-step') ? 'advance-audit' : 'run-to-completion';
-  await run(nodeExecutable(), [distEntry, command, ...wrapperArgs]);
-}
+  if (defaultSingleStep && !hasFlag(wrapperArgs, "--single-step")) {
+    wrapperArgs.push("--single-step");
+  }
+  const rootValue = resolve(getFlag(wrapperArgs, "--root") ?? ".");
+  const artifactsDir = resolve(
+    getFlag(wrapperArgs, "--artifacts-dir") ??
+      join(rootValue, ".audit-artifacts"),
+  );
+
+  setDefaultFlag(wrapperArgs, "--root", rootValue);
+  setDefaultFlag(wrapperArgs, "--artifacts-dir", artifactsDir);
+
+  if (ensureArtifactsDir) {
+    await mkdir(artifactsDir, { recursive: true });
+  }
+
+  await ensureBuilt();
+  const command = hasFlag(wrapperArgs, "--single-step")
+    ? "advance-audit"
+    : "run-to-completion";
+  await run(nodeExecutable(), [distEntry, command, ...wrapperArgs]);
+}