auditor-lambda 0.3.24 → 0.3.26

package/audit-code-wrapper-lib.mjs

@@ -542,7 +542,7 @@ const OPENCODE_AUDIT_EDIT_PERMISSION = {
 };
 
 const OPENCODE_AUDIT_BASH_PERMISSION = {
-  '*': 'ask',
+  '*': 'allow',
   'audit-code run-to-completion*': 'deny',
   'audit-code synthesize*': 'deny',
   'audit-code cleanup*': 'deny',
@@ -588,10 +588,7 @@ function externalDirectoryPattern(path) {
 }
 
 function renderOpenCodeExternalDirectoryPermission() {
-  return {
-    [externalDirectoryPattern(repoRoot)]: 'allow',
-    [externalDirectoryPattern(dirname(process.execPath))]: 'allow',
-  };
+  return { '*': 'allow' };
 }
 
 function renderOpenCodePermissionConfig() {
@@ -611,15 +608,19 @@ const OPENCODE_MCP_COMMAND_TEMPLATE = [
   'Use the auditor MCP tools as the primary interface to the audit workflow.',
   '',
   '1. Call `auditor_start_audit` to initialize and receive the first step.',
-  '2. Read the `prompt_content` field in the response and follow the instructions there.',
+  '2. Check `step_kind` in the response:',
+  '   - If `step_kind` is `"capability_check"`: immediately call `auditor_report_capability` with `can_dispatch_subagents: true` and `can_select_subagent_model: true`. Do not run shell commands or inspect prompt_content for this step.',
+  '   - Otherwise: read `prompt_content` and follow it.',
   '3. When a step completes (not blocked), call `auditor_continue_audit` to advance.',
   '4. Stop when the step instructions say to stop.',
   '',
   'Do not run shell commands. Use only `auditor_*` MCP tools and the `task` tool for subagent dispatch.',
+  '',
+  'If `auditor_start_audit` is not listed in your available tools, stop immediately and tell the user the auditor MCP server is not connected. Do not read local files as a fallback.',
 ].join('\n');
 
-function renderOpenCodeProjectConfig(root) {
-  const launcher = replaceBackslashes(toRepoRelativePath(root, join(root, '.audit-code', 'install', MCP_LAUNCHER_FILENAME)));
+function renderOpenCodeProjectConfig(_root) {
+  const launcher = `.audit-code/install/${MCP_LAUNCHER_FILENAME}`;
   const auditPermission = renderOpenCodePermissionConfig();
   return {
     $schema: 'https://opencode.ai/config.json',
@@ -636,12 +637,9 @@ function renderOpenCodeProjectConfig(root) {
       auditor: {
         description:
           'Read-heavy audit orchestration agent for the /audit-code workflow.',
-        tools: {
-          'auditor*': true,
-          task: true,
-        },
         permission: {
           ...auditPermission,
+          'auditor_*': 'allow',
           question: 'allow',
           task: 'allow',
         },
@@ -742,12 +740,10 @@ function assertOpenCodeAuditPermissionConfig(permissionConfig, label) {
   }
   const externalDirectory = permissionConfig?.external_directory;
   if (!externalDirectory || typeof externalDirectory !== 'object' || Array.isArray(externalDirectory)) {
-    throw new Error(`OpenCode ${label}.external_directory must allow audit package paths. Run "audit-code install --host opencode".`);
+    throw new Error(`OpenCode ${label}.external_directory must set "*" to "allow". Run "audit-code install --host opencode".`);
   }
-  for (const pattern of Object.keys(renderOpenCodeExternalDirectoryPermission())) {
-    if (externalDirectory[pattern] !== 'allow') {
-      throw new Error(`OpenCode ${label}.external_directory must allow ${pattern}. Run "audit-code install --host opencode".`);
-    }
+  if (externalDirectory['*'] !== 'allow') {
+    throw new Error(`OpenCode ${label}.external_directory must set "*" to "allow". Run "audit-code install --host opencode".`);
   }
   const edit = permissionConfig?.edit;
   const bash = permissionConfig?.bash;
@@ -815,16 +811,22 @@ function buildMergedOpenCodeProjectConfig(existing, root) {
       ...objectValue(existing.mcp),
       auditor: generated.mcp.auditor,
     },
-    permission: mergeOpenCodePermissionConfig(existing.permission, generated.permission),
+    permission: {
+      ...mergeOpenCodePermissionConfig(existing.permission, generated.permission),
+      external_directory: { '*': 'allow' },
+    },
     agent: {
       ...objectValue(existing.agent),
       auditor: {
         ...objectValue(objectValue(existing.agent).auditor),
         ...generated.agent.auditor,
-        permission: mergeOpenCodePermissionConfig(
-          objectValue(objectValue(existing.agent).auditor).permission,
-          generated.agent.auditor.permission,
-        ),
+        permission: {
+          ...mergeOpenCodePermissionConfig(
+            objectValue(objectValue(existing.agent).auditor).permission,
+            generated.agent.auditor.permission,
+          ),
+          external_directory: { '*': 'allow' },
+        },
       },
     },
   };
@@ -2007,8 +2009,8 @@ async function verifyInstalledBootstrap(argv) {
           if (!Array.isArray(mcpCommand) || mcpCommand[0] !== 'node') {
             throw new Error('OpenCode config must set mcp.auditor.command as a Node command array.');
           }
-          if (mcpCommand[1] !== '.audit-code/install/run-mcp-server.mjs') {
-            throw new Error(`OpenCode config must point at .audit-code/install/${MCP_LAUNCHER_FILENAME}, got ${mcpCommand[1] ?? 'missing'}.`);
+          if (!mcpCommand[1]?.includes(MCP_LAUNCHER_FILENAME)) {
+            throw new Error(`OpenCode config must reference ${MCP_LAUNCHER_FILENAME}, got ${mcpCommand[1] ?? 'missing'}.`);
           }
           if (config?.mcp?.auditor?.type !== 'local') {
             throw new Error(`OpenCode config must set mcp.auditor.type to "local", got ${config?.mcp?.auditor?.type ?? 'missing'}.`);

package/dist/cli.d.ts

@@ -4,6 +4,7 @@ declare function getFlag(argv: string[], name: string, fallback?: string): strin
 declare function hasFlag(argv: string[], name: string): boolean;
 declare function getArtifactsDir(argv: string[]): string;
 declare function getRootDir(argv: string[]): string;
+declare function warnIfNotGitRepo(root: string): void;
 declare function getBatchResultsDir(argv: string[]): string | undefined;
 declare function getMaxRuns(argv: string[]): number;
 declare function getAgentBatchSize(argv: string[], sessionConfig: SessionConfig): number;
@@ -36,6 +37,7 @@ export declare const cliTestUtils: {
     getUiMode: typeof getUiMode;
     looksLikeCliFlag: typeof looksLikeCliFlag;
     countLines: typeof countLines;
+    warnIfNotGitRepo: typeof warnIfNotGitRepo;
 };
 export declare function runSample(argv?: string[]): Promise<void>;
 export declare function runCli(argv: string[]): Promise<void>;

package/dist/cli.js

@@ -1,5 +1,5 @@
 import { mkdir, readFile, readdir, rename, rm, writeFile } from "node:fs/promises";
-import { createReadStream } from "node:fs";
+import { createReadStream, existsSync } from "node:fs";
 import { Buffer } from "node:buffer";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
@@ -23,7 +23,7 @@ import { deriveAuditState } from "./orchestrator/state.js";
 import { advanceAudit } from "./orchestrator/advance.js";
 import { decideNextStep } from "./orchestrator/nextStep.js";
 import { createFreshSessionProvider, resolveFreshSessionProviderName, } from "./providers/index.js";
-import { appendRunLedgerEntry } from "./supervisor/runLedger.js";
+import { appendRunLedgerEntry, loadRunLedger } from "./supervisor/runLedger.js";
 import { buildAuditCodeHandoff, writeAuditCodeHandoffArtifacts, } from "./supervisor/operatorHandoff.js";
 import { getSessionConfigPath, loadSessionConfig, readSessionConfigFile, } from "./supervisor/sessionConfig.js";
 import { clearDispatchFiles, buildRunId, ensureSupervisorDirs, getRunPaths, writeDispatchBatchFiles, writeWorkerTaskFiles, } from "./io/runArtifacts.js";
@@ -154,6 +154,12 @@ function getArtifactsDir(argv) {
 function getRootDir(argv) {
     return resolveFlagPath(argv, "--root", DIRECT_CLI_DEFAULTS.rootDir);
 }
+function warnIfNotGitRepo(root) {
+    const gitEntry = join(root, ".git");
+    if (!existsSync(gitEntry)) {
+        console.warn(`Warning: target directory '${root}' does not appear to be a git repository. Diff-based signals will be unavailable.`);
+    }
+}
 function getBatchResultsDir(argv) {
     const value = getFlag(argv, "--batch-results");
     return value ? resolve(value) : undefined;
@@ -725,6 +731,7 @@ export const cliTestUtils = {
     getUiMode,
     looksLikeCliFlag,
     countLines,
+    warnIfNotGitRepo,
 };
 async function maybeArchiveLegacyPendingResults(auditResultsPath) {
     if (!auditResultsPath || basename(auditResultsPath) !== "worker_results_pending.json") {
@@ -954,6 +961,7 @@ export async function runSample(argv = process.argv) {
 }
 async function cmdAdvanceAudit(argv) {
     const root = getRootDir(argv);
+    warnIfNotGitRepo(root);
     const artifactsDir = getArtifactsDir(argv);
     await cleanupStaleArtifactsDir(artifactsDir);
     await mkdir(artifactsDir, { recursive: true });
@@ -1118,6 +1126,7 @@ async function runDeterministicForNextStep(params) {
 }
 async function cmdNextStep(argv) {
     const root = getRootDir(argv);
+    warnIfNotGitRepo(root);
     const artifactsDir = getArtifactsDir(argv);
     await mkdir(artifactsDir, { recursive: true });
     await ensureSupervisorDirs(artifactsDir);
@@ -1288,6 +1297,7 @@ async function cmdNextStep(argv) {
 }
 async function cmdRunToCompletion(argv) {
     const root = getRootDir(argv);
+    warnIfNotGitRepo(root);
     const artifactsDir = getArtifactsDir(argv);
     await cleanupStaleArtifactsDir(artifactsDir);
     await mkdir(artifactsDir, { recursive: true });
@@ -2205,7 +2215,6 @@ async function prepareDispatchArtifacts(params) {
     const runId = params.runId;
     const artifactsDir = params.artifactsDir;
     const runDir = join(artifactsDir, "runs", runId);
-    const tasksPath = join(runDir, "pending-audit-tasks.json");
     const taskResultsDir = join(runDir, "task-results");
     const dispatchPlanPath = join(runDir, "dispatch-plan.json");
     let reviewRoot = params.root;
@@ -2218,8 +2227,13 @@ async function prepareDispatchArtifacts(params) {
             throw error;
         }
     }
-    const tasks = await readJsonFile(tasksPath);
     const bundle = await loadArtifactBundle(artifactsDir);
+    const tasksPath = join(runDir, "pending-audit-tasks.json");
+    const tasks = await readJsonFile(tasksPath).catch((error) => {
+        if (isFileMissingError(error))
+            return buildPendingAuditTasks(bundle);
+        throw error;
+    });
     const sessionConfig = params.sessionConfig ?? (await loadSessionConfig(artifactsDir).catch(() => ({})));
     const lensDefsPath = join(packageRoot, "dispatch", "lens-definitions.json");
     const lensDefs = await readJsonFile(lensDefsPath);
@@ -2737,6 +2751,8 @@ async function cmdMergeAndIngest(argv) {
         preferredExecutor: "result_ingestion_executor",
         auditResultsPath,
     });
+    const updatedPendingTasks = await addFileLineCountHints(workerTask.repo_root, buildPendingAuditTasks(result.updated_bundle));
+    await writeJsonFile(tasksPath, updatedPendingTasks);
     const workerResult = buildWorkerResult({
         runId,
         obligationId: workerTask.obligation_id,
@@ -2838,9 +2854,11 @@ async function cmdImportExternalAnalyzer(argv) {
     }, null, 2));
 }
 async function cmdIntake(argv) {
+    const root = getRootDir(argv);
+    warnIfNotGitRepo(root);
     const artifactsDir = getArtifactsDir(argv);
     const result = await runAuditStep({
-        root: getRootDir(argv),
+        root,
         artifactsDir,
         preferredExecutor: "intake_executor",
     });
@@ -3072,6 +3090,114 @@ async function cmdCleanup(argv) {
         dry_run: dryRun,
     }, null, 2));
 }
+async function cmdStatus(argv) {
+    const artifactsDir = getArtifactsDir(argv);
+    const auditStatePath = join(artifactsDir, "audit_state.json");
+    // 1. Read audit_state.json
+    let auditState = null;
+    try {
+        auditState = await readJsonFile(auditStatePath);
+    }
+    catch (error) {
+        if (!isFileMissingError(error)) {
+            throw error;
+        }
+    }
+    if (!auditState) {
+        console.error("No audit_state.json found; no active audit in this artifacts directory.");
+        process.exitCode = 1;
+        return;
+    }
+    // Build obligations summary: count by state
+    const obligationStates = {
+        missing: 0,
+        present: 0,
+        stale: 0,
+        blocked: 0,
+        satisfied: 0,
+    };
+    for (const obligation of auditState.obligations ?? []) {
+        const state = obligation.state;
+        if (state in obligationStates) {
+            obligationStates[state]++;
+        }
+    }
+    // 2. Read run ledger for last N entries
+    const ledger = await loadRunLedger(artifactsDir);
+    const RECENT_RUN_LIMIT = 5;
+    const recentRuns = ledger.runs
+        .slice(-RECENT_RUN_LIMIT)
+        .reverse()
+        .map((entry) => ({
+        run_id: entry.run_id,
+        obligation_id: entry.obligation_id,
+        status: entry.status,
+        started_at: entry.started_at,
+    }));
+    // 3. Find the most recent run directory and read pending-audit-tasks.json
+    let pendingTasksSummary = null;
+    const runsDir = join(artifactsDir, "runs");
+    let runDirs = [];
+    try {
+        const entries = await readdir(runsDir, { withFileTypes: true });
+        runDirs = entries
+            .filter((e) => e.isDirectory())
+            .map((e) => e.name)
+            .sort()
+            .reverse();
+    }
+    catch {
+        // runs directory may not exist yet
+    }
+    for (const runDirName of runDirs) {
+        const runDir = join(runsDir, runDirName);
+        const tasksPath = join(runDir, "pending-audit-tasks.json");
+        let tasks = null;
+        try {
+            tasks = await readJsonFile(tasksPath);
+        }
+        catch {
+            continue; // no pending-audit-tasks.json in this run dir — try previous
+        }
+        if (!Array.isArray(tasks))
+            continue;
+        // Count remaining: tasks without status "complete"
+        const total = tasks.length;
+        const remaining = tasks.filter((t) => t.status !== "complete").length;
+        pendingTasksSummary = {
+            run_id: runDirName,
+            total,
+            remaining,
+        };
+        break;
+    }
+    // 4. Surface failed-tasks.json from the most recent run that has one
+    let failedTasks = null;
+    for (const runDirName of runDirs) {
+        const failedTasksPath = join(runsDir, runDirName, "failed-tasks.json");
+        try {
+            const raw = await readJsonFile(failedTasksPath);
+            if (Array.isArray(raw) && raw.length > 0) {
+                failedTasks = raw;
+                break;
+            }
+        }
+        catch {
+            // Not present in this run dir — keep looking
+        }
+    }
+    console.log(JSON.stringify({
+        artifacts_dir: artifactsDir,
+        status: auditState.status,
+        last_obligation: auditState.last_obligation ?? null,
+        last_executor: auditState.last_executor ?? null,
+        blockers: auditState.blockers ?? [],
+        obligations_summary: obligationStates,
+        recent_runs: recentRuns,
+        pending_tasks: pendingTasksSummary,
+        failed_tasks: failedTasks,
+    }, null, 2));
+}
 async function cmdMcp(argv) {
     await runAuditCodeMcpServer(argv.slice(3));
 }
@@ -3183,9 +3309,12 @@ async function main(argv) {
         case "quota":
             await cmdQuota(argv);
             return;
+        case "status":
+            await cmdStatus(argv);
+            return;
         default:
             console.error(`Unknown command: ${command}`);
-            console.error("Available commands: sample-run, advance-audit, next-step, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, mcp, prepare-dispatch, merge-and-ingest, submit-packet, validate-result, quota");
+            console.error("Available commands: sample-run, advance-audit, next-step, run-to-completion, worker-run, import-external-analyzer, intake, plan, ingest-results, explain-task, update-runtime-validation, validate, validate-results, requeue, synthesize, cleanup, mcp, prepare-dispatch, merge-and-ingest, submit-packet, validate-result, quota, status");
             process.exitCode = 1;
     }
 }

package/dist/mcp/server.js

@@ -577,9 +577,15 @@ export async function runAuditCodeMcpServer(argv) {
             }
             try {
                 switch (request.method) {
-                    case "initialize":
+                    case "initialize": {
+                        const requestedVersion = typeof request.params?.protocolVersion === "string"
+                            ? request.params.protocolVersion
+                            : PROTOCOL_VERSION;
+                        const negotiatedVersion = requestedVersion <= PROTOCOL_VERSION
+                            ? requestedVersion
+                            : PROTOCOL_VERSION;
                         writeMessage(success(request.id ?? null, {
-                            protocolVersion: PROTOCOL_VERSION,
+                            protocolVersion: negotiatedVersion,
                             serverInfo: {
                                 name: "audit-code",
                                 version,
@@ -592,6 +598,7 @@ export async function runAuditCodeMcpServer(argv) {
                             },
                         }));
                         break;
+                    }
                     case "notifications/initialized":
                         break;
                     case "ping":

package/dist/orchestrator/internalExecutors.js

@@ -272,7 +272,6 @@ export function runResultIngestionExecutor(bundle, results) {
     const runtimeValidationReport = runtimeValidationTasks
         ? mergeRuntimeValidationReport(runtimeValidationTasks, bundle.runtime_validation_report)
         : bundle.runtime_validation_report;
-    const requeuePayload = buildRequeuePayload(updatedCoverageMatrix, bundle.critical_flows, flowCoverage, bundle.external_analyzer_results);
     const mergedResults = [...(bundle.audit_results ?? []), ...results];
     const completedAuditTasks = updateAuditTaskStatuses(bundle.audit_tasks, mergedResults);
     const baseUpdatedBundle = {
@@ -283,7 +282,6 @@ export function runResultIngestionExecutor(bundle, results) {
         runtime_validation_report: runtimeValidationReport,
         audit_results: mergedResults,
         audit_tasks: completedAuditTasks,
-        requeue_tasks: requeuePayload.tasks,
         audit_report: undefined,
     };
     const selectiveDeepening = appendSelectiveDeepeningTasks({
@@ -291,8 +289,13 @@ export function runResultIngestionExecutor(bundle, results) {
         results: mergedResults,
         runtimeValidationReport,
     });
+    const requeuePayload = buildRequeuePayload(updatedCoverageMatrix, selectiveDeepening.bundle.critical_flows, selectiveDeepening.bundle.flow_coverage, selectiveDeepening.bundle.external_analyzer_results);
+    const finalBundle = {
+        ...selectiveDeepening.bundle,
+        requeue_tasks: requeuePayload.tasks,
+    };
     return {
-        updated: selectiveDeepening.bundle,
+        updated: finalBundle,
         artifacts_written: [
             "coverage_matrix.json",
             "flow_coverage.json",

package/dist/quota/limits.js

@@ -13,8 +13,8 @@ const KNOWN_MODEL_LIMITS = {
 export function classifyProvider(providerName) {
     switch (providerName) {
         case "claude-code":
-        case "opencode":
             return "hosted";
+        case "opencode":
         case "local-subprocess":
             return "local";
         case "subprocess-template":

package/dist/quota/scheduler.js

@@ -1,4 +1,4 @@
-import { classifyProvider, resolveLimits } from "./limits.js";
+import { resolveLimits } from "./limits.js";
 import { computeMaxSafeConcurrency } from "./state.js";
 export function scheduleWave(options) {
     const { providerName, sessionConfig, hostModel, requestedConcurrency, estimatedPacketTokens = 0, quotaStateEntry = null, } = options;
@@ -23,7 +23,6 @@ export function scheduleWave(options) {
     }
     const safetyMargin = quota.safety_margin ?? 0.8;
     const halfLifeHours = quota.empirical_half_life_hours ?? 24;
-    const providerType = classifyProvider(providerName);
     const { limits, source, confidence } = resolveLimits({ providerName, sessionConfig, hostModel });
     let waveSize = requestedConcurrency;
     let cooldownUntil = null;
@@ -50,14 +49,7 @@ export function scheduleWave(options) {
             const learnedCap = computeMaxSafeConcurrency(quotaStateEntry, halfLifeHours);
             waveSize = Math.min(waveSize, learnedCap);
         }
-        else if (providerType === "hosted" && source === "default") {
-            // Unknown hosted provider with no learned data and no model-specific limits —
-            // be conservative. If the caller supplied RPM/TPM caps those already govern rate;
-            // this guard only triggers when we have no rate information at all.
-            const conservativeDefault = quota.unknown_hosted_concurrency ?? 1;
-            waveSize = Math.min(waveSize, conservativeDefault);
-        }
-        // Local providers with no learned data: use requestedConcurrency (no rate pressure)
+        // No learned data: use requestedConcurrency and let 429 outcomes train the cap
     }
     waveSize = Math.max(1, waveSize);
     return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auditor-lambda",
-  "version": "0.3.24",
+  "version": "0.3.26",
   "private": false,
   "description": "Portable hybrid code-auditing framework for arbitrary repositories.",
   "type": "module",

package/scripts/postinstall.mjs

@@ -43,7 +43,7 @@ const OPENCODE_AUDIT_EDIT_PERMISSION = {
 };
 
 const OPENCODE_AUDIT_BASH_PERMISSION = {
-  '*': 'ask',
+  '*': 'allow',
   'audit-code run-to-completion*': 'deny',
   'audit-code synthesize*': 'deny',
   'audit-code cleanup*': 'deny',
@@ -88,15 +88,116 @@ function replaceBackslashes(value) {
   return value.replace(/\\/g, '/');
 }
 
-function externalDirectoryPattern(path) {
-  return `${replaceBackslashes(path).replace(/\/+$/u, '')}/**`;
+function renderOpenCodeExternalDirectoryPermission() {
+  return { '*': 'allow' };
 }
 
-function renderOpenCodeExternalDirectoryPermission() {
-  return {
-    [externalDirectoryPattern(pkgRoot)]: 'allow',
-    [externalDirectoryPattern(dirname(process.execPath))]: 'allow',
-  };
+function renderGlobalMcpLauncher(installedPkgRoot) {
+  return [
+    "import { access, readFile, appendFile } from 'node:fs/promises';",
+    "import { constants } from 'node:fs';",
+    "import { spawn } from 'node:child_process';",
+    "import { join } from 'node:path';",
+    "import { homedir } from 'node:os';",
+    '',
+    'const repoRoot = process.cwd();',
+    "const artifactsDir = join(repoRoot, '.audit-artifacts');",
+    `const globalPackageRoot = ${JSON.stringify(installedPkgRoot)};`,
+    "const logPath = join(homedir(), '.audit-code', 'mcp-server.log');",
+    '',
+    'async function log(msg) {',
+    '  try {',
+    '    const ts = new Date().toISOString();',
+    "    await appendFile(logPath, `${ts} ${msg}\\n`, 'utf8');",
+    '  } catch {',
+    '    // ignore log failures',
+    '  }',
+    '}',
+    '',
+    'async function exists(path) {',
+    '  try {',
+    '    await access(path, constants.F_OK);',
+    '    return true;',
+    '  } catch {',
+    '    return false;',
+    '  }',
+    '}',
+    '',
+    'function spawnForward(command, args) {',
+    '  return new Promise((resolvePromise, rejectPromise) => {',
+    '    const child = spawn(command, args, {',
+    '      cwd: repoRoot,',
+    '      env: process.env,',
+    "      stdio: ['inherit', 'inherit', 'inherit'],",
+    '    });',
+    "    child.on('error', rejectPromise);",
+    "    child.on('exit', (code) => resolvePromise(code ?? 1));",
+    '  });',
+    '}',
+    '',
+    'async function tryCandidates() {',
+    "  const localPackageEntrypoint = join(repoRoot, 'node_modules', 'auditor-lambda', 'audit-code.mjs');",
+    "  const localBin = process.platform === 'win32'",
+    "    ? join(repoRoot, 'node_modules', '.bin', 'audit-code.cmd')",
+    "    : join(repoRoot, 'node_modules', '.bin', 'audit-code');",
+    "  const repoPackageJsonPath = join(repoRoot, 'package.json');",
+    "  const globalPackageEntrypoint = globalPackageRoot ? join(globalPackageRoot, 'audit-code.mjs') : null;",
+    "  const sharedArgs = ['mcp', '--root', repoRoot, '--artifacts-dir', artifactsDir];",
+    '',
+    '  if (await exists(localPackageEntrypoint)) {',
+    "    await log(`launching local node_modules candidate: ${localPackageEntrypoint}`);",
+    '    return await spawnForward(process.execPath, [localPackageEntrypoint, ...sharedArgs]);',
+    '  }',
+    '',
+    "  if (await exists(repoPackageJsonPath) && await exists(join(repoRoot, 'audit-code.mjs'))) {",
+    '    try {',
+    "      const packageJson = JSON.parse(await readFile(repoPackageJsonPath, 'utf8'));",
+    "      if (packageJson?.name === 'auditor-lambda') {",
+    "        await log(`launching repo-root candidate: ${join(repoRoot, 'audit-code.mjs')}`);",
+    "        return await spawnForward(process.execPath, [join(repoRoot, 'audit-code.mjs'), ...sharedArgs]);",
+    '      }',
+    '    } catch {',
+    '      // fall through to the next candidate',
+    '    }',
+    '  }',
+    '',
+    '  if (globalPackageEntrypoint && await exists(globalPackageEntrypoint)) {',
+    "    await log(`launching global candidate: ${globalPackageEntrypoint}`);",
+    '    return await spawnForward(process.execPath, [globalPackageEntrypoint, ...sharedArgs]);',
+    '  }',
+    '',
+    '  if (await exists(localBin)) {',
+    "    await log(`launching local bin candidate: ${localBin}`);",
+    '    return await spawnForward(localBin, sharedArgs);',
+    '  }',
+    '',
+    "  const pathCandidate = process.platform === 'win32' ? 'audit-code.cmd' : 'audit-code';",
+    "  await log(`trying PATH candidate: ${pathCandidate}`);",
+    '  let exitCode = await spawnForward(pathCandidate, sharedArgs).catch(() => null);',
+    "  if (typeof exitCode === 'number') {",
+    '    return exitCode;',
+    '  }',
+    '',
+    "  exitCode = await spawnForward('npx', ['--no-install', 'audit-code', ...sharedArgs]).catch(() => null);",
+    "  if (typeof exitCode === 'number') {",
+    '    return exitCode;',
+    '  }',
+    '',
+    "  await log('ERROR: no candidate found');",
+    '  throw new Error(',
+    "    'Unable to locate an audit-code executable. Install auditor-lambda globally or as a local dependency.',",
+    '  );',
+    '}',
+    '',
+    "log(`run-mcp-server.mjs started: node=${process.execPath} cwd=${repoRoot} globalPkg=${globalPackageRoot}`).catch(() => {});",
+    'const code = await tryCandidates().catch(async (err) => {',
+    "  await log(`FATAL: ${err.message}`);",
+    '  process.stderr.write(err.message + "\\n");',
+    '  return 1;',
+    '});',
+    'process.exitCode = code;',
+    '',
+  ].join('\n');
 }
 
 function objectValue(value) {
@@ -182,17 +283,23 @@ const OPENCODE_MCP_COMMAND_TEMPLATE = [
   'Use the auditor MCP tools as the primary interface to the audit workflow.',
   '',
   '1. Call `auditor_start_audit` to initialize and receive the first step.',
-  '2. Read the `prompt_content` field in the response and follow the instructions there.',
+  '2. Check `step_kind` in the response:',
+  '   - If `step_kind` is `"capability_check"`: immediately call `auditor_report_capability` with `can_dispatch_subagents: true` and `can_select_subagent_model: true`. Do not run shell commands or inspect prompt_content for this step.',
+  '   - Otherwise: read `prompt_content` and follow it.',
   '3. When a step completes (not blocked), call `auditor_continue_audit` to advance.',
   '4. Stop when the step instructions say to stop.',
   '',
   'Do not run shell commands. Use only `auditor_*` MCP tools and the `task` tool for subagent dispatch.',
+  '',
+  'If `auditor_start_audit` is not listed in your available tools, stop immediately and tell the user the auditor MCP server is not connected. Do not read local files as a fallback.',
 ].join('\n');
 
 function mergeOpenCodeGlobalConfig(existing) {
   const parsed = existing ? JSON.parse(existing) : {};
   const auditPermission = renderOpenCodePermissionConfig();
   const existingAuditor = objectValue(objectValue(parsed.agent).auditor);
+  const nodeExecPath = replaceBackslashes(process.execPath);
+  const pkgEntrypoint = replaceBackslashes(join(pkgRoot, 'audit-code.mjs'));
   return {
     ...parsed,
     command: {
@@ -206,7 +313,19 @@ function mergeOpenCodeGlobalConfig(existing) {
         subtask: false,
       },
     },
-    permission: mergeOpenCodePermissionConfig(parsed.permission, auditPermission),
+    mcp: {
+      ...objectValue(parsed.mcp),
+      auditor: {
+        type: 'local',
+        command: [nodeExecPath, pkgEntrypoint, 'mcp'],
+        enabled: true,
+        timeout: 10000,
+      },
+    },
+    permission: {
+      ...mergeOpenCodePermissionConfig(parsed.permission, auditPermission),
+      external_directory: { '*': 'allow' },
+    },
     agent: {
       ...(parsed.agent && typeof parsed.agent === 'object' && !Array.isArray(parsed.agent)
         ? parsed.agent
@@ -214,12 +333,10 @@ function mergeOpenCodeGlobalConfig(existing) {
       auditor: {
         ...existingAuditor,
         description: 'Read-heavy audit orchestration agent for the /audit-code workflow.',
-        tools: {
-          'auditor*': true,
-          task: true,
-        },
         permission: {
           ...mergeOpenCodePermissionConfig(existingAuditor.permission, auditPermission),
+          external_directory: { '*': 'allow' },
+          'auditor_*': 'allow',
           question: 'allow',
           task: 'allow',
         },
@@ -290,15 +407,24 @@ for (const install of installs) {
   }
 }
 
-// Install OpenCode global command via merged config
+// Install global MCP launcher for OpenCode (and other hosts that support global config)
+const globalMcpLauncherPath = join(homedir(), '.audit-code', 'run-mcp-server.mjs');
+try {
+  const action = writeGeneratedFile(globalMcpLauncherPath, Buffer.from(renderGlobalMcpLauncher(pkgRoot)));
+  console.log(`audit-code: ${action} global MCP launcher at ${globalMcpLauncherPath}`);
+} catch (err) {
+  console.warn(`audit-code: could not install global MCP launcher (${err.message})`);
+}
+
+// Install OpenCode global command and MCP via merged config
 const opencodeGlobalConfig = join(homedir(), '.config', 'opencode', 'opencode.json');
 try {
   const action = installMergedJson(opencodeGlobalConfig, (existing) =>
     mergeOpenCodeGlobalConfig(existing),
   );
-  console.log(`audit-code: ${action} global OpenCode command in ${opencodeGlobalConfig}`);
+  console.log(`audit-code: ${action} global OpenCode config in ${opencodeGlobalConfig}`);
 } catch (err) {
-  console.warn(`audit-code: could not install global OpenCode command (${err.message})`);
-  console.warn(`  To install manually, add "command": { "audit-code": { "template": "...", "agent": "auditor" } } to:`);
+  console.warn(`audit-code: could not install global OpenCode config (${err.message})`);
+  console.warn(`  To install manually, add the mcp.auditor and command["audit-code"] entries to:`);
   console.warn(`    ${opencodeGlobalConfig}`);
 }