auditor-lambda 0.2.1 → 0.2.2

package/dist/io/artifacts.js

@@ -22,8 +22,10 @@ export const ARTIFACT_FILE_TO_BUNDLE_KEY = {
     "audit_state.json": "audit_state",
     "artifact_metadata.json": "artifact_metadata",
 };
+const _bundleKeyCoverage = true;
 export function getArtifactValue(bundle, artifactName) {
-    const key = ARTIFACT_FILE_TO_BUNDLE_KEY[artifactName];
+    const map = ARTIFACT_FILE_TO_BUNDLE_KEY;
+    const key = map[artifactName];
     return key ? bundle[key] : undefined;
 }
 export async function loadArtifactBundle(root) {
@@ -51,8 +53,7 @@ export async function loadArtifactBundle(root) {
     bundle.root_cause_clusters = await readOptionalJsonFile(`${root}/root_cause_clusters.json`);
     bundle.synthesis_report = await readOptionalJsonFile(`${root}/synthesis_report.json`);
     bundle.audit_state = await readOptionalJsonFile(`${root}/audit_state.json`);
-    bundle.artifact_metadata =
-        await readOptionalJsonFile(`${root}/artifact_metadata.json`);
+    bundle.artifact_metadata = await readOptionalJsonFile(`${root}/artifact_metadata.json`);
     return bundle;
 }
 export async function writeCoreArtifacts(root, bundle) {

package/dist/io/runArtifacts.js

@@ -3,7 +3,7 @@ import { join } from "node:path";
 import { writeJsonFile } from "./json.js";
 export function buildRunId(obligationId, index) {
     const timestamp = new Date().toISOString().replace(/[:.]/g, "-");
-    const obligation = obligationId ?? "terminal";
+    const obligation = (obligationId ?? "terminal").replace(/[^a-zA-Z0-9_-]/g, "-");
     return `${timestamp}_${obligation}_${String(index).padStart(3, "0")}`;
 }
 export function getRunPaths(artifactsDir, runId) {

package/dist/orchestrator/advance.js

@@ -13,7 +13,7 @@ export async function advanceAudit(bundle, options = {}) {
         : decision.selected_obligation;
     if (!selectedExecutor) {
         const state = deriveAuditState(bundle);
-        state.last_executor = selectedExecutor ?? undefined;
+        // Do not overwrite last_executor when no executor was selected — preserve prior value
         state.last_obligation = selectedObligation ?? undefined;
         return {
             audit_state: state,
@@ -27,76 +27,58 @@ export async function advanceAudit(bundle, options = {}) {
         };
     }
     let run;
-    try {
-        switch (selectedExecutor) {
-            case "intake_executor":
-                if (!options.root)
-                    throw new Error("advanceAudit intake_executor requires root");
-                run = await runIntakeExecutor(bundle, options.root);
-                break;
-            case "structure_executor":
-                run = runStructureExecutor(bundle);
-                break;
-            case "planning_executor":
-                run = runPlanningExecutor(bundle, options.lineIndex ?? {});
-                break;
-            case "result_ingestion_executor":
-                run = runResultIngestionExecutor(bundle, options.auditResults ?? bundle.audit_results ?? []);
-                break;
-            case "synthesis_executor":
-                run = runSynthesisExecutor(bundle, options.auditResults);
-                break;
-            case "runtime_validation_update_executor":
-                if (!options.runtimeValidationUpdates)
-                    throw new Error("advanceAudit runtime_validation_update_executor requires runtimeValidationUpdates");
-                run = runRuntimeValidationUpdateExecutor(bundle, options.runtimeValidationUpdates);
-                break;
-            case "external_analyzer_import_executor":
-                if (!options.externalAnalyzerResults)
-                    throw new Error("advanceAudit external_analyzer_import_executor requires externalAnalyzerResults");
-                run = runExternalAnalyzerImportExecutor(bundle, options.externalAnalyzerResults);
-                break;
-            case "auto_fix_executor":
-                if (!options.root)
-                    throw new Error("advanceAudit auto_fix_executor requires root");
-                run = runAutoFixExecutor(bundle, options.root);
-                break;
-            case "syntax_resolution_executor":
-                if (!options.root)
-                    throw new Error("advanceAudit syntax_resolution_executor requires root");
-                run = runSyntaxResolutionExecutor(bundle, options.root);
-                break;
-            default: {
-                const state = deriveAuditState(bundle);
-                state.last_executor = selectedExecutor;
-                state.last_obligation = selectedObligation ?? undefined;
-                return {
-                    audit_state: state,
-                    selected_obligation: selectedObligation,
-                    selected_executor: selectedExecutor,
-                    progress_made: false,
-                    artifacts_written: ["audit_state.json"],
-                    progress_summary: `Executor ${selectedExecutor} is selected but not yet dispatched through advance-audit.`,
-                    next_likely_step: selectedObligation,
-                    updated_bundle: { ...bundle, audit_state: state },
-                };
-            }
-        }
-    }
-    catch (err) {
-        const state = deriveAuditState(bundle);
-        state.last_executor = selectedExecutor;
-        state.last_obligation = selectedObligation ?? undefined;
-        return {
-            audit_state: state,
-            selected_obligation: selectedObligation,
-            selected_executor: selectedExecutor,
-            progress_made: false,
-            artifacts_written: [],
-            progress_summary: `Executor ${selectedExecutor} failed: ${err instanceof Error ? err.message : String(err)}`,
-            next_likely_step: selectedObligation,
-            updated_bundle: { ...bundle, audit_state: state },
-        };
+    switch (selectedExecutor) {
+        case "intake_executor":
+            if (!options.root)
+                throw new Error("advanceAudit intake_executor requires root");
+            run = await runIntakeExecutor(bundle, options.root);
+            break;
+        case "structure_executor":
+            run = runStructureExecutor(bundle);
+            break;
+        case "planning_executor":
+            run = runPlanningExecutor(bundle, options.lineIndex ?? {});
+            break;
+        case "result_ingestion_executor":
+            run = runResultIngestionExecutor(bundle, options.auditResults ?? bundle.audit_results ?? []);
+            break;
+        case "synthesis_executor":
+            run = runSynthesisExecutor(bundle, options.auditResults);
+            break;
+        case "runtime_validation_update_executor":
+            if (!options.runtimeValidationUpdates)
+                throw new Error("advanceAudit runtime_validation_update_executor requires runtimeValidationUpdates");
+            run = runRuntimeValidationUpdateExecutor(bundle, options.runtimeValidationUpdates);
+            break;
+        case "external_analyzer_import_executor":
+            if (!options.externalAnalyzerResults)
+                throw new Error("advanceAudit external_analyzer_import_executor requires externalAnalyzerResults");
+            run = runExternalAnalyzerImportExecutor(bundle, options.externalAnalyzerResults);
+            break;
+        case "auto_fix_executor":
+            if (!options.root)
+                throw new Error("advanceAudit auto_fix_executor requires root");
+            run = runAutoFixExecutor(bundle, options.root);
+            break;
+        case "syntax_resolution_executor":
+            if (!options.root)
+                throw new Error("advanceAudit syntax_resolution_executor requires root");
+            run = runSyntaxResolutionExecutor(bundle, options.root);
+            break;
+        default:
+            const state = deriveAuditState(bundle);
+            state.last_executor = selectedExecutor;
+            state.last_obligation = selectedObligation ?? undefined;
+            return {
+                audit_state: state,
+                selected_obligation: selectedObligation,
+                selected_executor: selectedExecutor,
+                progress_made: false,
+                artifacts_written: ["audit_state.json"],
+                progress_summary: `Executor ${selectedExecutor} is selected but not yet dispatched through advance-audit.`,
+                next_likely_step: selectedObligation,
+                updated_bundle: { ...bundle, audit_state: state },
+            };
     }
     const metadata = computeArtifactMetadata(run.updated, bundle.artifact_metadata);
     const metadataBundle = { ...run.updated, artifact_metadata: metadata };

package/dist/orchestrator/flowCoverage.js

@@ -10,12 +10,11 @@ function lensSetForFlow(concerns) {
     return concerns.filter((concern) => allowed.includes(concern));
 }
 export function buildFlowCoverage(criticalFlows, coverageMatrix) {
-    const fileIndex = new Map(coverageMatrix.files.map((file) => [file.path, file]));
     const flows = criticalFlows.flows.map((flow) => {
         const required = lensSetForFlow(flow.concerns);
         const completed = new Set();
         for (const path of flow.paths) {
-            const record = fileIndex.get(path);
+            const record = coverageMatrix.files.find((file) => file.path === path);
             if (!record || record.audit_status === "excluded") {
                 continue;
             }

package/dist/orchestrator/internalExecutors.js

@@ -118,9 +118,9 @@ export function runResultIngestionExecutor(bundle, results) {
     if (!bundle.coverage_matrix) {
         throw new Error("Cannot ingest results without coverage_matrix");
     }
-    ingestAuditResults(bundle.coverage_matrix, results);
+    const updatedCoverageMatrix = ingestAuditResults(bundle.coverage_matrix, results);
     const flowCoverage = bundle.critical_flows
-        ? buildFlowCoverage(bundle.critical_flows, bundle.coverage_matrix)
+        ? buildFlowCoverage(bundle.critical_flows, updatedCoverageMatrix)
         : bundle.flow_coverage;
     const runtimeValidationTasks = bundle.unit_manifest
         ? buildRuntimeValidationTasks(bundle.unit_manifest, bundle.critical_flows, flowCoverage)
@@ -128,15 +128,13 @@ export function runResultIngestionExecutor(bundle, results) {
     const runtimeValidationReport = runtimeValidationTasks
         ? preserveOrPlaceholder(runtimeValidationTasks, bundle.runtime_validation_report)
         : bundle.runtime_validation_report;
-    const requeuePayload = bundle.coverage_matrix
-        ? buildRequeuePayload(bundle.coverage_matrix, bundle.critical_flows, flowCoverage, bundle.external_analyzer_results)
-        : { tasks: [], task_count: 0 };
+    const requeuePayload = buildRequeuePayload(updatedCoverageMatrix, bundle.critical_flows, flowCoverage, bundle.external_analyzer_results);
     const mergedResults = [...(bundle.audit_results ?? []), ...results];
     const synthesisReport = buildSynthesisReport(mergedResults, runtimeValidationReport, bundle.external_analyzer_results);
     return {
         updated: {
             ...bundle,
-            coverage_matrix: bundle.coverage_matrix,
+            coverage_matrix: updatedCoverageMatrix,
             flow_coverage: flowCoverage,
             runtime_validation_tasks: runtimeValidationTasks,
             runtime_validation_report: runtimeValidationReport,

package/dist/orchestrator/planning.js

@@ -1,27 +1,19 @@
 import { applyUnitCoverage, createCoverageMatrix, markExcludedPath, } from "../coverage.js";
 import { isAuditExcludedStatus } from "../extractors/disposition.js";
+const CATEGORY_LENS_TABLE = [
+    [["security", "secret"], ["security", "correctness"]],
+    [["dependency", "vuln"], ["security", "config_deployment"]],
+    [["tests", "coverage"], ["tests"]],
+    [["data"], ["data_integrity", "correctness"]],
+    [["reliability", "concurrency"], ["reliability", "correctness"]],
+    [["maintainability", "lint", "style"], ["maintainability"]],
+];
 function analyzerCategoryToLenses(category) {
     const normalized = category.toLowerCase();
-    if (normalized.includes("security") || normalized.includes("secret")) {
-        return ["security", "correctness"];
-    }
-    if (normalized.includes("dependency") || normalized.includes("vuln")) {
-        return ["security", "config_deployment"];
-    }
-    if (normalized.includes("tests") || normalized.includes("coverage")) {
-        return ["tests"];
-    }
-    if (normalized.includes("data")) {
-        return ["data_integrity", "correctness"];
-    }
-    if (normalized.includes("reliability") ||
-        normalized.includes("concurrency")) {
-        return ["reliability", "correctness"];
-    }
-    if (normalized.includes("maintainability") ||
-        normalized.includes("lint") ||
-        normalized.includes("style")) {
-        return ["maintainability"];
+    for (const [keywords, lenses] of CATEGORY_LENS_TABLE) {
+        if (keywords.some((kw) => normalized.includes(kw))) {
+            return lenses;
+        }
     }
     return ["correctness"];
 }

package/dist/orchestrator/resultIngestion.js

@@ -1,5 +1,6 @@
 import { applyReviewedRanges } from "../coverage.js";
 export function ingestAuditResults(coverageMatrix, results) {
+    const matrix = JSON.parse(JSON.stringify(coverageMatrix));
     const reviewedRanges = results.flatMap((result) => result.reviewed_ranges.map((range) => ({
         path: range.path,
         start: range.start,
@@ -8,6 +9,6 @@ export function ingestAuditResults(coverageMatrix, results) {
         lens: result.lens,
         agent_role: result.agent_role,
     })));
-    applyReviewedRanges(coverageMatrix, reviewedRanges);
-    return coverageMatrix;
+    applyReviewedRanges(matrix, reviewedRanges);
+    return matrix;
 }

package/dist/orchestrator/runtimeValidation.js

@@ -63,6 +63,11 @@ export function buildRuntimeValidationTasks(unitManifest, criticalFlows, flowCov
             });
         }
     }
+    const RUNTIME_TASK_CAP = 100;
+    if (tasks.length > RUNTIME_TASK_CAP) {
+        process.stderr.write(`[runtime-validation] generated ${tasks.length} tasks which exceeds the cap of ${RUNTIME_TASK_CAP}; truncating to avoid runaway expansion\n`);
+        tasks.splice(RUNTIME_TASK_CAP);
+    }
     return { tasks };
 }
 export function buildPlaceholderRuntimeValidationReport(tasks) {

package/dist/orchestrator/syntaxResolutionExecutor.js

@@ -20,12 +20,16 @@ function runTsc(root) {
                         category: "correctness",
                         severity: "error",
                         path: match[1].replace(/\\/g, "/"),
+                        line_start: parseInt(match[2], 10),
                         summary: match[3],
                         rule: "tsc",
                     });
                 }
             }
         }
+        else {
+            process.stderr.write(`[syntax-resolution] tsc exited with no stdout; stderr: ${(error.stderr?.toString() ?? "").slice(0, 200)}\n`);
+        }
     }
     return results;
 }
@@ -51,6 +55,7 @@ function runEslint(root) {
                             path: fileResult.filePath
                                 .replace(/\\/g, "/")
                                 .replace(root.replace(/\\/g, "/") + "/", ""),
+                            line_start: msg.line,
                             summary: msg.message,
                             rule: msg.ruleId || "eslint-error",
                         });
@@ -58,9 +63,12 @@ function runEslint(root) {
                 }
             }
             catch (e) {
-                // failed to parse
+                process.stderr.write(`[syntax-resolution] eslint output could not be parsed: ${(error.stdout?.toString() ?? "").slice(0, 200)}\n`);
             }
         }
+        else {
+            process.stderr.write(`[syntax-resolution] eslint exited with no stdout; stderr: ${(error.stderr?.toString() ?? "").slice(0, 200)}\n`);
+        }
     }
     return results;
 }
@@ -78,7 +86,7 @@ export function runSyntaxResolutionExecutor(bundle, root) {
     const seen = new Set();
     const deduped = [];
     for (const r of merged) {
-        const key = `${r.path}:${r.rule}:${r.summary}`;
+        const key = `${r.path}:${r.line_start ?? ""}:${r.rule}:${r.summary}`;
         if (!seen.has(key)) {
             seen.add(key);
             deduped.push(r);

package/dist/orchestrator/taskBuilder.js

@@ -1,18 +1,3 @@
-function modelHintForLens(lens) {
-    switch (lens) {
-        case "security":
-        case "correctness":
-        case "reliability":
-        case "data_integrity":
-            return "capable";
-        case "architecture":
-        case "maintainability":
-        case "tests":
-            return "balanced";
-        default:
-            return "fast";
-    }
-}
 function taskPriority(hasExternalSignal, lens) {
     if (hasExternalSignal &&
         (lens === "security" || lens === "data_integrity" || lens === "reliability")) {
@@ -52,8 +37,9 @@ function pickAnalyzerLens(category) {
         return "maintainability";
     return "correctness";
 }
+const DEFAULT_FILE_SPLIT_THRESHOLD = 3000;
 export function buildChunkedAuditTasks(unitManifest, unitLineIndex, options = {}) {
-    const fileSplitThreshold = options.file_split_threshold ?? 3000;
+    const fileSplitThreshold = options.file_split_threshold ?? DEFAULT_FILE_SPLIT_THRESHOLD;
     const allowed = new Set(options.limit_lenses ?? []);
     const enforceLensFilter = allowed.size > 0;
     const tasks = [];
@@ -91,7 +77,6 @@ export function buildChunkedAuditTasks(unitManifest, unitLineIndex, options = {}
                         rationale: `Audit ${unit.unit_id} (${normalFiles.length} file${normalFiles.length === 1 ? "" : "s"}) under the ${lens} lens.${hasExternalSignal ? " External analyzer signals raise priority." : ""}`,
                         priority,
                         tags,
-                        model_hint: modelHintForLens(lens),
                     });
                 }
             }
@@ -110,10 +95,7 @@ export function buildChunkedAuditTasks(unitManifest, unitLineIndex, options = {}
                     file_paths: [filePath],
                     rationale: `Audit ${filePath} (large file, split from unit) under the ${lens} lens.${fileHasSignal ? " External analyzer signals raise priority." : ""}`,
                     priority: taskPriority(fileHasSignal, lens),
-                    tags: fileHasSignal
-                        ? ["external_analyzer_signal", "large_file"]
-                        : ["large_file"],
-                    model_hint: modelHintForLens(lens),
+                    tags: fileHasSignal ? ["external_analyzer_signal", "large_file"] : ["large_file"],
                 });
             }
         }
@@ -125,37 +107,42 @@ export function buildChunkedAuditTasks(unitManifest, unitLineIndex, options = {}
         return a.task_id.localeCompare(b.task_id);
     });
 }
+/** Strip control characters and newlines, then truncate to maxLen. */
+function sanitizeField(value, maxLen) {
+    return value.replace(/[\x00-\x1f\x7f]/g, " ").slice(0, maxLen).trimEnd();
+}
 export function buildExternalSignalTasks(coverageMatrix, _unitLineIndex, externalAnalyzerResults) {
     if (!externalAnalyzerResults) {
         return [];
     }
     const tasks = [];
     const seen = new Set();
-    const coverageIndex = new Map(coverageMatrix.files.map((file) => [file.path, file]));
     for (const result of externalAnalyzerResults.results) {
-        const lens = pickAnalyzerLens(result.category);
-        const coverage = coverageIndex.get(result.path);
+        const safeCategory = sanitizeField(result.category, 80);
+        const safePath = sanitizeField(result.path ?? "", 260);
+        const safeSummary = sanitizeField(result.summary ?? "", 200);
+        const lens = pickAnalyzerLens(safeCategory);
+        const coverage = coverageMatrix.files.find((file) => file.path === result.path);
         if (!coverage || coverage.audit_status === "excluded") {
             continue;
         }
-        const id = `analyzer:${externalAnalyzerResults.tool}:${lens}:${result.path}:${result.id}`;
+        const id = `analyzer:${externalAnalyzerResults.tool}:${lens}:${safePath}:${result.id}`;
         if (seen.has(id)) {
             continue;
         }
         seen.add(id);
         tasks.push({
             task_id: id,
-            unit_id: coverage.unit_ids[0] ?? `analyzer:${result.path}`,
+            unit_id: coverage.unit_ids[0] ?? `analyzer:${safePath}`,
             pass_id: `analyzer:${externalAnalyzerResults.tool}:${lens}`,
             lens,
             file_paths: [result.path],
-            rationale: `Analyzer follow-up for ${result.path} under the ${lens} lens because ${externalAnalyzerResults.tool} reported: ${result.summary}`,
+            rationale: `Analyzer follow-up for ${safePath} under the ${lens} lens because ${externalAnalyzerResults.tool} reported: ${safeSummary}`,
             priority: "high",
             tags: [
                 "external_analyzer_signal",
                 `external_tool:${externalAnalyzerResults.tool}`,
             ],
-            model_hint: modelHintForLens(lens),
         });
     }
     return tasks.sort((a, b) => a.task_id.localeCompare(b.task_id));

package/dist/prompts/renderWorkerPrompt.js

@@ -4,7 +4,8 @@ function shellQuote(arg) {
 export function renderWorkerPrompt(task) {
     const command = task.worker_command.map(shellQuote).join(" ");
     if (task.preferred_executor === "agent" && task.audit_results_path) {
-        const tasksPath = task.pending_audit_tasks_path ?? `${task.artifacts_dir}/audit_tasks.json`;
+        const tasksPath = task.pending_audit_tasks_path ??
+            `${task.artifacts_dir}/audit_tasks.json`;
         const lines = [
             "You are executing one bounded audit task for audit-code.",
             `Run ID: ${task.run_id}`,

package/dist/providers/claudeCodeProvider.js

@@ -9,7 +9,7 @@ export class ClaudeCodeProvider {
     async launch(input) {
         if (process.env.CLAUDECODE) {
             throw new Error("claude-code provider cannot be used inside an active Claude Code session. " +
-                'Set provider to "local-subprocess" in .audit-artifacts/session-config.json, ' +
+                "Set provider to \"local-subprocess\" in .audit-artifacts/session-config.json, " +
                 "then run /audit-code conversationally and follow the dispatch prompts manually.");
         }
         const prompt = await readFile(input.promptPath, "utf8");
@@ -17,7 +17,6 @@ export class ClaudeCodeProvider {
         const args = [
             "-p",
             prompt,
-            ...(input.model ? ["--model", input.model] : []),
             ...(this.config.extra_args ?? []),
             "--dangerously-skip-permissions",
         ];

package/dist/providers/constants.d.ts

@@ -0,0 +1 @@
+export declare const LOCAL_SUBPROCESS_PROVIDER_NAME: "local-subprocess";

package/dist/providers/constants.js

@@ -0,0 +1 @@
+export const LOCAL_SUBPROCESS_PROVIDER_NAME = "local-subprocess";

package/dist/providers/index.js

@@ -39,9 +39,7 @@ export function resolveFreshSessionProviderName(name, sessionConfig = {}, option
     const opencodeCommand = sessionConfig.opencode?.command ?? "opencode";
     const claudeAvailable = !insideClaudeCode && lookupCommand(claudeCommand);
     const opencodeAvailable = lookupCommand(opencodeCommand);
-    if (!insideClaudeCode &&
-        hasConfiguredClaudeCode(sessionConfig) &&
-        claudeAvailable) {
+    if (!insideClaudeCode && hasConfiguredClaudeCode(sessionConfig) && claudeAvailable) {
         return "claude-code";
     }
     if (hasConfiguredOpenCode(sessionConfig) && opencodeAvailable) {
@@ -57,6 +55,12 @@ export function resolveFreshSessionProviderName(name, sessionConfig = {}, option
 }
 export function createFreshSessionProvider(name, sessionConfig = {}) {
     const providerName = resolveFreshSessionProviderName(name, sessionConfig);
+    if (providerName === "local-subprocess" &&
+        (name ?? sessionConfig.provider) === "auto") {
+        process.stderr.write("audit-code: auto provider resolved to local-subprocess — no capable agent provider detected. " +
+            "Agent tasks will require manual dispatch. Configure claude-code, opencode, or subprocess-template " +
+            "in session-config.json to automate them.\n");
+    }
     switch (providerName) {
         case "local-subprocess":
             return new LocalSubprocessProvider();

package/dist/providers/opencodeProvider.js

@@ -9,12 +9,7 @@ export class OpenCodeProvider {
     async launch(input) {
         const prompt = await readFile(input.promptPath, "utf8");
         const command = this.config.command ?? "opencode";
-        const args = [
-            "run",
-            prompt,
-            ...(input.model ? ["--model", input.model] : []),
-            ...(this.config.extra_args ?? []),
-        ];
+        const args = ["run", prompt, ...(this.config.extra_args ?? [])];
         return await spawnLoggedCommand(command, args, input);
     }
 }

package/dist/providers/spawnLoggedCommand.js

@@ -3,6 +3,10 @@ import { spawn } from "node:child_process";
 function tee(write, chunk) {
     write.write(chunk);
 }
+// On Windows `command` must be the resolved .cmd / .exe path because `spawn`
+// does not consult PATH for executables without a shell. Callers should use
+// `platformCommand()` (scripts/smoke-packaged-audit-code.mjs) or similar to
+// supply the correct command form for the host OS.
 export async function spawnLoggedCommand(command, args, input, env) {
     return await new Promise((resolve, reject) => {
         const stdoutLog = createWriteStream(input.stdoutPath, { flags: "a" });

package/dist/providers/types.d.ts

@@ -9,7 +9,6 @@ export interface LaunchFreshSessionInput {
     stderrPath: string;
     uiMode: "visible" | "headless";
     timeoutMs: number;
-    model?: string;
 }
 export interface LaunchFreshSessionResult {
     accepted: boolean;

package/dist/supervisor/operatorHandoff.d.ts

@@ -14,6 +14,7 @@ export interface AuditCodeHandoffArtifactPaths {
     audit_tasks: string | null;
     runtime_validation_tasks: string | null;
 }
+export declare const CONFIG_ERROR_BLOCKER_PREFIX = "config-error:";
 export interface AuditCodeHandoff {
     status: AuditTopLevelStatus;
     repo_root: string;
@@ -33,5 +34,6 @@ export declare function buildAuditCodeHandoff(params: {
     bundle: ArtifactBundle;
     providerName?: string | null;
     progressSummary: string;
+    isConfigError?: boolean;
 }): AuditCodeHandoff;
 export declare function writeAuditCodeHandoffArtifacts(handoff: AuditCodeHandoff): Promise<void>;

package/dist/supervisor/operatorHandoff.js

@@ -1,6 +1,8 @@
 import { mkdir, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { writeJsonFile } from "../io/json.js";
+import { LOCAL_SUBPROCESS_PROVIDER_NAME } from "../providers/constants.js";
+export const CONFIG_ERROR_BLOCKER_PREFIX = "config-error:";
 function quoteShellPath(path) {
     return `"${path.replace(/"/g, '\\"')}"`;
 }
@@ -23,8 +25,8 @@ function buildSummary(status, providerName, fallbackSummary) {
         ? `Automatic work can continue under ${providerName}. Re-run the same wrapper or inspect the listed artifacts if you need operator context.`
         : "Automatic work can continue. Re-run the same wrapper or inspect the listed artifacts if you need operator context.";
 }
-function buildSuggestedInputs(artifactsDir, status) {
-    if (status !== "blocked") {
+function buildSuggestedInputs(artifactsDir, status, isConfigError) {
+    if (status !== "blocked" || isConfigError) {
         return [];
     }
     const incomingDir = join(artifactsDir, "incoming");
@@ -52,11 +54,14 @@ function buildSuggestedCommands(suggestedInputs, status) {
     }
     return suggestedInputs.map((item) => `audit-code ${item.flag} ${quoteShellPath(item.suggested_path)}`);
 }
-function buildInteractiveProviderHint(status, providerName, sessionConfigPath) {
+function buildInteractiveProviderHint(status, providerName, sessionConfigPath, isConfigError) {
     if (status !== "blocked") {
         return null;
     }
-    const providerLabel = providerName ?? "local-subprocess";
+    if (isConfigError) {
+        return `A project configuration issue is blocking the audit. Verify that --root points to the repository root containing a project file (package.json, go.mod, etc.), then run audit-code again.`;
+    }
+    const providerLabel = providerName ?? LOCAL_SUBPROCESS_PROVIDER_NAME;
     return `Current provider is ${providerLabel}. If you want the backend to continue through an interactive provider instead of importing results manually, set "provider" in ${sessionConfigPath} to "auto", "claude-code", "opencode", "subprocess-template", or "vscode-task", then run audit-code again from the repository root.`;
 }
 function renderMarkdown(handoff) {
@@ -109,6 +114,7 @@ function renderMarkdown(handoff) {
     return lines.join("\n");
 }
 export function buildAuditCodeHandoff(params) {
+    const isConfigError = params.isConfigError ?? false;
     const incomingDir = join(params.artifactsDir, "incoming");
     const artifactPaths = {
         incoming_dir: incomingDir,
@@ -123,7 +129,7 @@ export function buildAuditCodeHandoff(params) {
             ? join(params.artifactsDir, "runtime_validation_tasks.json")
             : null,
     };
-    const suggestedInputs = buildSuggestedInputs(params.artifactsDir, params.state.status);
+    const suggestedInputs = buildSuggestedInputs(params.artifactsDir, params.state.status, isConfigError);
     return {
         status: params.state.status,
         repo_root: params.root,
@@ -133,12 +139,18 @@ export function buildAuditCodeHandoff(params) {
         pending_obligations: buildPendingObligations(params.state),
         suggested_inputs: suggestedInputs,
         suggested_commands: buildSuggestedCommands(suggestedInputs, params.state.status),
-        interactive_provider_hint: buildInteractiveProviderHint(params.state.status, params.providerName ?? null, artifactPaths.session_config),
+        interactive_provider_hint: buildInteractiveProviderHint(params.state.status, params.providerName ?? null, artifactPaths.session_config, isConfigError),
         artifact_paths: artifactPaths,
     };
 }
 export async function writeAuditCodeHandoffArtifacts(handoff) {
-    await mkdir(handoff.artifact_paths.incoming_dir, { recursive: true });
-    await writeJsonFile(handoff.artifact_paths.operator_handoff_json, handoff);
-    await writeFile(handoff.artifact_paths.operator_handoff_markdown, renderMarkdown(handoff), "utf8");
+    try {
+        await mkdir(handoff.artifact_paths.incoming_dir, { recursive: true });
+        await writeJsonFile(handoff.artifact_paths.operator_handoff_json, handoff);
+        await writeFile(handoff.artifact_paths.operator_handoff_markdown, renderMarkdown(handoff), "utf8");
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to write operator handoff artifacts: ${message}`);
+    }
 }