auditor-lambda 0.3.20 → 0.3.21

package/dist/cli.js

@@ -35,6 +35,7 @@ import { runAuditCodeMcpServer } from "./mcp/server.js";
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const ADVANCE_AUDIT_CONTRACT_VERSION = "audit-code/v1alpha1";
 const WORKER_RESULT_CONTRACT_VERSION = "audit-code-worker-result/v1alpha1";
+const STEP_CONTRACT_VERSION = "audit-code-step/v1alpha1";
 const LARGE_FILE_PACKET_TARGET_LINES = 2500;
 const SMALL_MODEL_HINT_MAX_LINES = 500;
 const SMALL_MODEL_HINT_MAX_ESTIMATED_TOKENS = 3000;
@@ -72,6 +73,19 @@ function getFlag(argv, name, fallback) {
 function hasFlag(argv, name) {
     return argv.includes(name);
 }
+function getOptionalBooleanFlag(argv, name) {
+    const raw = getFlag(argv, name);
+    if (raw === undefined) {
+        return undefined;
+    }
+    if (raw === "true") {
+        return true;
+    }
+    if (raw === "false") {
+        return false;
+    }
+    throw new Error(`${name} must be either true or false.`);
+}
 function toBase64Url(value) {
     return Buffer.from(value, "utf8").toString("base64url");
 }
@@ -91,6 +105,12 @@ function safeArtifactStem(value) {
 function artifactNameForId(value, extension) {
     return `${safeArtifactStem(value)}_${digestId(value)}.${extension}`;
 }
+function quoteCommandArg(value) {
+    return /[\s"]/u.test(value) ? `"${value.replace(/"/g, '\\"')}"` : value;
+}
+function renderCommand(argv) {
+    return argv.map((item) => quoteCommandArg(item)).join(" ");
+}
 function taskResultPath(taskResultsDir, taskId) {
     return join(taskResultsDir, artifactNameForId(taskId, "json"));
 }
@@ -324,6 +344,293 @@ async function addFileLineCountHints(root, tasks) {
         file_line_counts: Object.fromEntries(task.file_paths.map((path) => [path, lineIndex[path] ?? 0])),
     }));
 }
+function activeReviewRunFromTask(artifactsDir, task) {
+    if (task.preferred_executor !== "agent" || !task.audit_results_path) {
+        return null;
+    }
+    const paths = getRunPaths(artifactsDir, task.run_id);
+    return {
+        run_id: task.run_id,
+        task_path: paths.taskPath,
+        prompt_path: paths.promptPath,
+        pending_audit_tasks_path: task.pending_audit_tasks_path,
+        audit_results_path: task.audit_results_path,
+        worker_command: task.worker_command,
+    };
+}
+async function loadCurrentActiveReviewRun(artifactsDir) {
+    try {
+        const task = await readJsonFile(join(artifactsDir, "dispatch", "current-task.json"));
+        return activeReviewRunFromTask(artifactsDir, task);
+    }
+    catch (error) {
+        if (isFileMissingError(error)) {
+            return null;
+        }
+        throw error;
+    }
+}
+async function writeHandoffOnly(params) {
+    const handoff = buildAuditCodeHandoff({
+        root: params.root,
+        artifactsDir: params.artifactsDir,
+        state: params.audit_state,
+        bundle: params.bundle,
+        providerName: params.providerName,
+        progressSummary: params.progress_summary,
+        isConfigError: params.isConfigError,
+        activeReviewRun: params.activeReviewRun,
+    });
+    await writeAuditCodeHandoffArtifacts(handoff);
+}
+async function ensureSemanticReviewRun(params) {
+    const existingRun = await loadCurrentActiveReviewRun(params.artifactsDir);
+    if (existingRun) {
+        const blockedState = params.bundle.audit_state?.status === "blocked"
+            ? params.bundle.audit_state
+            : buildBlockedAuditState({
+                state: params.state,
+                obligationId: params.obligationId,
+                executor: "agent",
+                blocker: buildManualReviewBlocker(LOCAL_SUBPROCESS_PROVIDER_NAME),
+            });
+        const blockedBundle = { ...params.bundle, audit_state: blockedState };
+        await writeCoreArtifacts(params.artifactsDir, blockedBundle);
+        await writeHandoffOnly({
+            root: params.root,
+            artifactsDir: params.artifactsDir,
+            bundle: blockedBundle,
+            audit_state: blockedState,
+            progress_summary: buildManualReviewBlocker(LOCAL_SUBPROCESS_PROVIDER_NAME),
+            providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+            activeReviewRun: existingRun,
+        });
+        return {
+            state: blockedState,
+            bundle: blockedBundle,
+            activeReviewRun: existingRun,
+        };
+    }
+    const blockedState = buildBlockedAuditState({
+        state: params.state,
+        obligationId: params.obligationId,
+        executor: "agent",
+        blocker: buildManualReviewBlocker(LOCAL_SUBPROCESS_PROVIDER_NAME),
+    });
+    await writeCoreArtifacts(params.artifactsDir, {
+        ...params.bundle,
+        audit_state: blockedState,
+    });
+    const runId = buildRunId(params.obligationId, 1);
+    const paths = getRunPaths(params.artifactsDir, runId);
+    const pendingTasks = await addFileLineCountHints(params.root, buildPendingAuditTasks(params.bundle));
+    const pendingTasksPath = join(paths.runDir, "pending-audit-tasks.json");
+    const auditResultsPath = join(paths.runDir, "audit-results.json");
+    const task = {
+        contract_version: "audit-code-worker/v1alpha1",
+        run_id: runId,
+        repo_root: params.root,
+        artifacts_dir: params.artifactsDir,
+        obligation_id: params.obligationId,
+        preferred_executor: "agent",
+        result_path: paths.resultPath,
+        worker_command: [
+            process.execPath,
+            params.selfCliPath,
+            "worker-run",
+            "--task",
+            paths.taskPath,
+        ],
+        audit_results_path: auditResultsPath,
+        pending_audit_tasks_path: pendingTasksPath,
+        timeout_ms: params.timeoutMs,
+        max_retries: 0,
+    };
+    const prompt = renderWorkerPrompt(task);
+    await writeWorkerTaskFiles(task, prompt, paths, params.artifactsDir, pendingTasks);
+    await writeJsonFile(pendingTasksPath, pendingTasks);
+    const activeReviewRun = activeReviewRunFromTask(params.artifactsDir, task);
+    if (!activeReviewRun) {
+        throw new Error("Internal error: failed to materialize active review run.");
+    }
+    const blockedBundle = {
+        ...params.bundle,
+        audit_state: blockedState,
+    };
+    await writeHandoffOnly({
+        root: params.root,
+        artifactsDir: params.artifactsDir,
+        bundle: blockedBundle,
+        audit_state: blockedState,
+        progress_summary: buildManualReviewBlocker(LOCAL_SUBPROCESS_PROVIDER_NAME),
+        providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+        activeReviewRun,
+    });
+    return { state: blockedState, bundle: blockedBundle, activeReviewRun };
+}
+function nextStepCommand(root, artifactsDir, extraArgs = []) {
+    return renderCommand([
+        "audit-code",
+        "next-step",
+        "--root",
+        root,
+        "--artifacts-dir",
+        artifactsDir,
+        ...extraArgs,
+    ]);
+}
+function mergeAndIngestCommand(artifactsDir, runId) {
+    return renderCommand([
+        "audit-code",
+        "merge-and-ingest",
+        "--run-id",
+        runId,
+        "--artifacts-dir",
+        artifactsDir,
+    ]);
+}
+function renderCapabilityCheckPrompt(params) {
+    const yesCommand = nextStepCommand(params.root, params.artifactsDir, [
+        "--host-can-dispatch-subagents",
+        "true",
+    ]);
+    const noCommand = nextStepCommand(params.root, params.artifactsDir, [
+        "--host-can-dispatch-subagents",
+        "false",
+    ]);
+    return [
+        "# audit-code capability check",
+        "",
+        "Decide one thing from the active toolset: does this host expose a callable subagent/delegation tool for source-code review, such as Agent, Task, or an equivalent built-in subagent call?",
+        "",
+        "Do not run shell commands to answer this. Do not inspect packet prompts, schemas, or backend command catalogs.",
+        "",
+        "If callable subagents are available, run:",
+        "",
+        `  ${yesCommand}`,
+        "",
+        "If callable subagents are not available, run:",
+        "",
+        `  ${noCommand}`,
+        "",
+        "If the host can also restrict tools per subagent or select models per subagent, add the matching `--host-can-restrict-subagent-tools true` or `--host-can-select-subagent-model true` flags to the same command. Omit those flags when unsure.",
+        "",
+        "After the command writes the next step, read and follow only its `prompt_path`.",
+        "",
+    ].join("\n");
+}
+function renderDispatchReviewPrompt(params) {
+    const mergeCommand = mergeAndIngestCommand(params.artifactsDir, params.activeReviewRun.run_id);
+    const continueCommand = nextStepCommand(params.root, params.artifactsDir);
+    const modelLine = params.hostCanSelectSubagentModel
+        ? "When launching each subagent, map `entry.model_hint.tier` (`small`, `standard`, `deep`) to an available host model without asking the user for model names."
+        : "Ignore `entry.model_hint`; this host did not report per-subagent model selection.";
+    const toolsLine = params.hostCanRestrictSubagentTools
+        ? "Restrict review subagents to read/search plus the packet submit command named in their prompt. Do not give them source edit/write tools."
+        : "Do not ask the user about per-subagent tool restrictions; this host did not report a callable restriction facility.";
+    return [
+        "# audit-code dispatch review",
+        "",
+        "Dispatch is prepared. Read only this dispatch plan JSON:",
+        "",
+        `  ${params.dispatchPlanPath}`,
+        "",
+        "Launch one host subagent for each entry in the plan. Pass the packet prompt path literally; do not load packet prompt files into this orchestrator context.",
+        "",
+        "Subagent prompt shape:",
+        "",
+        '  Read and follow the audit instructions in: <entry.prompt_path>',
+        "",
+        modelLine,
+        toolsLine,
+        "",
+        "Wait for all review subagents to finish. Each subagent must submit its packet through the submit command printed in its packet prompt and stop after successful submission.",
+        "",
+        "Then run exactly:",
+        "",
+        `  ${mergeCommand}`,
+        "",
+        "If merge-and-ingest fails, stop and report the exact command and error output. Do not manually merge results or edit audit state.",
+        "",
+        "If merge-and-ingest succeeds, run:",
+        "",
+        `  ${continueCommand}`,
+        "",
+        "Read and follow only the new step prompt path returned by that command.",
+        "",
+    ].join("\n");
+}
+function renderSingleTaskFallbackStepPrompt(params) {
+    return [
+        "# audit-code single-task fallback step",
+        "",
+        "Use this step only because the host reported no callable subagent facility.",
+        "",
+        "Read and follow exactly this generated single-task prompt:",
+        "",
+        `  ${params.singleTaskPromptPath}`,
+        "",
+        "Complete exactly one AuditResult for the task named there, write the JSON array to the prompt's audit_results_path, run the exact worker_command from that prompt, then stop.",
+        "",
+        "Do not run dispatch commands, do not prepare packets, do not run next-step again in this turn, and do not read a report after the worker command.",
+        "",
+        "The only backend command allowed after writing the result is:",
+        "",
+        `  ${renderCommand(params.activeReviewRun.worker_command)}`,
+        "",
+    ].join("\n");
+}
+function renderPresentReportPrompt(finalReportPath) {
+    return [
+        "# audit-code present report",
+        "",
+        "The deterministic audit is complete.",
+        "",
+        "Read this report and present the completed audit with work blocks first:",
+        "",
+        `  ${finalReportPath}`,
+        "",
+        "Do not run the orchestrator again for this completed audit.",
+        "",
+    ].join("\n");
+}
+function renderBlockedStepPrompt(reason) {
+    return [
+        "# audit-code blocked",
+        "",
+        "The audit cannot continue automatically from this step.",
+        "",
+        "Report this blocker verbatim and stop:",
+        "",
+        reason,
+        "",
+    ].join("\n");
+}
+async function writeCurrentStep(params) {
+    const stepsDir = join(params.artifactsDir, "steps");
+    await mkdir(stepsDir, { recursive: true });
+    const promptPath = join(stepsDir, "current-prompt.md");
+    const stepPath = join(stepsDir, "current-step.json");
+    await writeFile(promptPath, params.prompt, "utf8");
+    const step = {
+        contract_version: STEP_CONTRACT_VERSION,
+        step_kind: params.stepKind,
+        prompt_path: promptPath,
+        status: params.status,
+        run_id: params.runId,
+        allowed_commands: params.allowedCommands,
+        stop_condition: params.stopCondition,
+        repo_root: params.repoRoot,
+        artifacts_dir: params.artifactsDir,
+        artifact_paths: {
+            current_step: stepPath,
+            current_prompt: promptPath,
+            ...params.artifactPaths,
+        },
+    };
+    await writeJsonFile(stepPath, step);
+    return step;
+}
 function formatAuditResultValidationError(issues) {
     return (`audit-results validation failed with ${issues.length} error(s):\n` +
         formatAuditResultIssues(issues));
@@ -659,6 +966,253 @@ async function cmdAdvanceAudit(argv) {
         await promoteFinalAuditReport({ artifactsDir, repoRoot: root });
     }
 }
+async function runDeterministicForNextStep(params) {
+    let lastSummary = "";
+    for (let index = 0; index < params.maxRuns; index++) {
+        const bundle = await loadArtifactBundle(params.artifactsDir);
+        const decision = decideNextStep(bundle);
+        const state = decision.state;
+        if (state.status === "complete") {
+            await writeHandoffOnly({
+                root: params.root,
+                artifactsDir: params.artifactsDir,
+                bundle,
+                audit_state: state,
+                progress_summary: decision.reason,
+                providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+            });
+            const promoted = await promoteFinalAuditReport({
+                artifactsDir: params.artifactsDir,
+                repoRoot: params.root,
+            });
+            return {
+                kind: "complete",
+                state,
+                bundle,
+                finalReportPath: promoted.promoted
+                    ? join(params.root, "audit-report.md")
+                    : join(params.artifactsDir, "audit-report.md"),
+            };
+        }
+        if (decision.selected_executor === "agent") {
+            return {
+                kind: "semantic_review",
+                ...(await ensureSemanticReviewRun({
+                    root: params.root,
+                    artifactsDir: params.artifactsDir,
+                    bundle,
+                    state,
+                    obligationId: decision.selected_obligation,
+                    selfCliPath: params.selfCliPath,
+                    timeoutMs: params.timeoutMs,
+                })),
+            };
+        }
+        if (!decision.selected_executor) {
+            await writeHandoffOnly({
+                root: params.root,
+                artifactsDir: params.artifactsDir,
+                bundle,
+                audit_state: state,
+                progress_summary: lastSummary || decision.reason,
+                providerName: LOCAL_SUBPROCESS_PROVIDER_NAME,
+            });
+            return {
+                kind: "blocked",
+                state,
+                bundle,
+                reason: lastSummary || decision.reason,
+            };
+        }
+        const result = await runAuditStep({
+            root: params.root,
+            artifactsDir: params.artifactsDir,
+        });
+        lastSummary = result.progress_summary;
+        if (result.selected_executor !== "agent") {
+            await clearDispatchFiles(params.artifactsDir);
+        }
+        if (!result.progress_made) {
+            return {
+                kind: "blocked",
+                state: result.audit_state,
+                bundle: result.updated_bundle,
+                reason: result.progress_summary,
+            };
+        }
+    }
+    const bundle = await loadArtifactBundle(params.artifactsDir);
+    const state = deriveAuditState(bundle);
+    return {
+        kind: "blocked",
+        state,
+        bundle,
+        reason: `Reached max run limit (${params.maxRuns}) before a review, report, or blocker step was ready.`,
+    };
+}
+async function cmdNextStep(argv) {
+    const root = getRootDir(argv);
+    const artifactsDir = getArtifactsDir(argv);
+    await mkdir(artifactsDir, { recursive: true });
+    await ensureSupervisorDirs(artifactsDir);
+    const hostCanDispatchSubagents = getOptionalBooleanFlag(argv, "--host-can-dispatch-subagents");
+    const hostCanRestrictSubagentTools = getOptionalBooleanFlag(argv, "--host-can-restrict-subagent-tools") ??
+        false;
+    const hostCanSelectSubagentModel = getOptionalBooleanFlag(argv, "--host-can-select-subagent-model") ?? false;
+    let sessionConfig;
+    try {
+        sessionConfig = await loadSessionConfig(artifactsDir);
+    }
+    catch (error) {
+        const reason = error instanceof Error ? error.message : String(error);
+        await persistConfigErrorHandoff({
+            root,
+            artifactsDir,
+            progressSummary: reason,
+        });
+        const step = await writeCurrentStep({
+            artifactsDir,
+            stepKind: "blocked",
+            status: "blocked",
+            runId: null,
+            allowedCommands: [],
+            stopCondition: "Report the configuration blocker and stop.",
+            repoRoot: root,
+            artifactPaths: {
+                operator_handoff: join(artifactsDir, "operator-handoff.json"),
+            },
+            prompt: renderBlockedStepPrompt(reason),
+        });
+        console.log(JSON.stringify(step, null, 2));
+        return;
+    }
+    const result = await runDeterministicForNextStep({
+        root,
+        artifactsDir,
+        selfCliPath: resolve(argv[1] ?? process.argv[1] ?? ""),
+        timeoutMs: getTimeoutMs(argv, sessionConfig),
+        maxRuns: getMaxRuns(argv),
+    });
+    if (result.kind === "complete") {
+        const step = await writeCurrentStep({
+            artifactsDir,
+            stepKind: "present_report",
+            status: "complete",
+            runId: null,
+            allowedCommands: [],
+            stopCondition: "Present the final report and stop.",
+            repoRoot: root,
+            artifactPaths: {
+                final_report: result.finalReportPath,
+            },
+            prompt: renderPresentReportPrompt(result.finalReportPath),
+        });
+        console.log(JSON.stringify(step, null, 2));
+        return;
+    }
+    if (result.kind === "blocked") {
+        const step = await writeCurrentStep({
+            artifactsDir,
+            stepKind: "blocked",
+            status: "blocked",
+            runId: null,
+            allowedCommands: [],
+            stopCondition: "Report the blocker and stop.",
+            repoRoot: root,
+            artifactPaths: {
+                operator_handoff: join(artifactsDir, "operator-handoff.json"),
+            },
+            prompt: renderBlockedStepPrompt(result.reason),
+        });
+        console.log(JSON.stringify(step, null, 2));
+        return;
+    }
+    if (hostCanDispatchSubagents === undefined) {
+        const yesCommand = nextStepCommand(root, artifactsDir, [
+            "--host-can-dispatch-subagents",
+            "true",
+        ]);
+        const noCommand = nextStepCommand(root, artifactsDir, [
+            "--host-can-dispatch-subagents",
+            "false",
+        ]);
+        const step = await writeCurrentStep({
+            artifactsDir,
+            stepKind: "capability_check",
+            status: "ready",
+            runId: result.activeReviewRun.run_id,
+            allowedCommands: [yesCommand, noCommand],
+            stopCondition: "Run exactly one next-step command with an explicit host dispatch capability.",
+            repoRoot: root,
+            artifactPaths: {
+                active_review_task: result.activeReviewRun.task_path,
+                active_review_prompt: result.activeReviewRun.prompt_path,
+                pending_audit_tasks: result.activeReviewRun.pending_audit_tasks_path ?? null,
+                single_task_prompt: join(artifactsDir, "dispatch", "current-single-task-prompt.md"),
+            },
+            prompt: renderCapabilityCheckPrompt({ root, artifactsDir }),
+        });
+        console.log(JSON.stringify(step, null, 2));
+        return;
+    }
+    if (!hostCanDispatchSubagents) {
+        const singleTaskPromptPath = join(artifactsDir, "dispatch", "current-single-task-prompt.md");
+        const workerCommand = renderCommand(result.activeReviewRun.worker_command);
+        const step = await writeCurrentStep({
+            artifactsDir,
+            stepKind: "single_task_fallback",
+            status: "ready",
+            runId: result.activeReviewRun.run_id,
+            allowedCommands: [workerCommand],
+            stopCondition: "Run the exact worker_command after one result, then stop without looping.",
+            repoRoot: root,
+            artifactPaths: {
+                active_review_task: result.activeReviewRun.task_path,
+                active_review_prompt: result.activeReviewRun.prompt_path,
+                pending_audit_tasks: result.activeReviewRun.pending_audit_tasks_path ?? null,
+                audit_results: result.activeReviewRun.audit_results_path,
+                single_task_prompt: singleTaskPromptPath,
+            },
+            prompt: renderSingleTaskFallbackStepPrompt({
+                singleTaskPromptPath,
+                activeReviewRun: result.activeReviewRun,
+            }),
+        });
+        console.log(JSON.stringify(step, null, 2));
+        return;
+    }
+    const dispatch = await prepareDispatchArtifacts({
+        runId: result.activeReviewRun.run_id,
+        artifactsDir,
+        root,
+    });
+    const mergeCommand = mergeAndIngestCommand(artifactsDir, result.activeReviewRun.run_id);
+    const continueCommand = nextStepCommand(root, artifactsDir);
+    const step = await writeCurrentStep({
+        artifactsDir,
+        stepKind: "dispatch_review",
+        status: "ready",
+        runId: result.activeReviewRun.run_id,
+        allowedCommands: [mergeCommand, continueCommand],
+        stopCondition: "Dispatch every packet, merge-and-ingest once, then run next-step again.",
+        repoRoot: root,
+        artifactPaths: {
+            dispatch_plan: dispatch.dispatch_plan_path,
+            dispatch_warnings: dispatch.dispatch_warnings_path,
+            active_review_task: result.activeReviewRun.task_path,
+            pending_audit_tasks: result.activeReviewRun.pending_audit_tasks_path ?? null,
+        },
+        prompt: renderDispatchReviewPrompt({
+            root,
+            artifactsDir,
+            activeReviewRun: result.activeReviewRun,
+            dispatchPlanPath: dispatch.dispatch_plan_path,
+            hostCanRestrictSubagentTools,
+            hostCanSelectSubagentModel,
+        }),
+    });
+    console.log(JSON.stringify(step, null, 2));
+}
 async function cmdRunToCompletion(argv) {
     const root = getRootDir(argv);
     const artifactsDir = getArtifactsDir(argv);
@@ -1544,17 +2098,14 @@ function renderPacketGraphContext(packet) {
     lines.push("");
     return lines;
 }
-async function cmdPrepareDispatch(argv) {
-    const runId = getFlag(argv, "--run-id");
-    if (!runId)
-        throw new Error("prepare-dispatch requires --run-id <run_id>");
-    const artifactsDir = getArtifactsDir(argv);
+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");
-    const explicitRoot = getFlag(argv, "--root") ? getRootDir(argv) : undefined;
-    let reviewRoot = explicitRoot;
+    let reviewRoot = params.root;
     try {
         const workerTask = await readJsonFile(join(runDir, "task.json"));
         reviewRoot ??= workerTask.repo_root;
@@ -1721,6 +2272,7 @@ async function cmdPrepareDispatch(argv) {
             largeFileMode
                 ? "Use targeted Read/Grep calls. Paths are repo-relative from the current working directory."
                 : "Use your Read tool. Paths are repo-relative from the current working directory.",
+            "Prefer host Read/Grep tools. On native Windows, do not use Unix pipelines like `grep ... | head`; if shell search is unavoidable, use `Select-String` as a fallback.",
             fileList,
             "",
             ...renderPacketGraphContext(packet),
@@ -1796,7 +2348,7 @@ async function cmdPrepareDispatch(argv) {
     if (warningsPath) {
         await writeJsonFile(warningsPath, warnings);
     }
-    console.log(JSON.stringify({
+    return {
         run_id: runId,
         dispatch_plan_path: dispatchPlanPath,
         packet_count: plan.length,
@@ -1810,7 +2362,18 @@ async function cmdPrepareDispatch(argv) {
             : null,
         warning_count: warnings.length,
         dispatch_warnings_path: warningsPath,
-    }, null, 2));
+    };
+}
+async function cmdPrepareDispatch(argv) {
+    const runId = getFlag(argv, "--run-id");
+    if (!runId)
+        throw new Error("prepare-dispatch requires --run-id <run_id>");
+    const result = await prepareDispatchArtifacts({
+        runId,
+        artifactsDir: getArtifactsDir(argv),
+        root: getFlag(argv, "--root") ? getRootDir(argv) : undefined,
+    });
+    console.log(JSON.stringify(result, null, 2));
 }
 async function cmdSubmitPacket(argv) {
     const runId = resolveRunScopedArg(argv, "--run-id", "--run-id-b64");
@@ -2369,6 +2932,9 @@ async function main(argv) {
         case "advance-audit":
             await cmdAdvanceAudit(argv);
             return;
+        case "next-step":
+            await cmdNextStep(argv);
+            return;
         case "run-to-completion":
             await cmdRunToCompletion(argv);
             return;
@@ -2425,7 +2991,7 @@ async function main(argv) {
             return;
         default:
             console.error(`Unknown command: ${command}`);
-            console.error("Available commands: sample-run, advance-audit, 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");
+            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");
             process.exitCode = 1;
     }
 }

package/dist/prompts/renderWorkerPrompt.js

@@ -12,6 +12,7 @@ export function renderWorkerPrompt(task) {
             `Read: ${tasksPath}`,
             "Scope: review only the tasks listed in the Read file. Do not add tasks,",
             "edit source files, remediate findings, run unrelated audits, or write result_path.",
+            "Prefer host Read and Grep tools for source inspection. On native Windows, do not use Unix pipelines like `grep ... | head`; if shell search is unavoidable, use `Select-String` as a fallback.",
             "For each listed task: read the assigned file_paths under the specified lens,",
             "using targeted reads/searches where they give complete enough evidence without loading unrelated context,",
             "and emit exactly one AuditResult object with:",