audit-tools 0.30.48 → 0.30.51

package/dist/remediate/steps/nextStep.js

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, rename } from "node:fs/promises";
 import { dirname, join, resolve } from "node:path";
 import { StateStore } from "../state/store.js";
-import { readOptionalJsonFile, writeJsonFile, writeTextFile, buildAuditDeliverablePair, formatValidationIssues, isRecord, withFsRetry, RunLogger, DISPATCH_PROMPT_HANDOFF_NOTE, renderQuotaCoverageNudge, coerceJsonObjectArg, createRollingDispatcher, setQuotaStateDir, interpretFreeFormIntent, advance, decideFrictionTriage, buildFrictionTriageBlock, planHybridDispatch, readSettledPools, addSettledPool, sourceByPoolId, classifyProvider, selectDispatchDriver, renderDispatchDriverInstruction } from "audit-tools/shared";
+import { readOptionalJsonFile, writeJsonFile, writeTextFile, buildAuditDeliverablePair, formatValidationIssues, isRecord, withFsRetry, RunLogger, DISPATCH_PROMPT_HANDOFF_NOTE, renderQuotaCoverageNudge, coerceJsonObjectArg, createRollingDispatcher, setQuotaStateDir, interpretFreeFormIntent, advance, decideFrictionTriage, buildFrictionTriageBlock, planHybridDispatch, readSettledPools, addSettledPool, sourceByPoolId, classifyProvider, selectDispatchDriver, renderDispatchDriverInstruction, HostSessionQuotaSource, buildProviderModelKey, captureStepBoundaryFriction, LENSES, SEVERITIES } from "audit-tools/shared";
 import { applyPlanPipeline, buildCoverageLedger } from "../phases/plan.js";
 import { groundExtractedFindings } from "../phases/grounding.js";
 import { runTriagePhase } from "../phases/triage.js";
@@ -14,12 +14,11 @@ import { ownershipSubWaves } from "../dispatch/ownershipScheduler.js";
 import { prepareHostRollingDispatch, nodeClaimRegistry, nodeSettledPoolsPath } from "./rollingSession.js";
 import { writeCurrentStep } from "./stepWriter.js";
 import { dependencyVerifiedComplete } from "./stepUtils.js";
-import { isTerminalStatus, isVerifiedCompleteStatus, isSkipStatus, } from "../state/itemStatus.js";
+import { isTerminalStatus, isVerifiedCompleteStatus, } from "../state/itemStatus.js";
 import { deduplicateCrossLensFindings, fixupBlocksAfterDedup, } from "../dedup/crossLensDedup.js";
 import { checkAffectedFileIntegrity } from "../utils/fileIntegrity.js";
 import { resolveIntakeStep } from "./intakeResolver.js";
-import { runCommand } from "../utils/commands.js";
-import { isAuditToolsMonorepo, toolOwnedFinalGateCommands, } from "./gateCommands.js";
+import { runToolOwnedFinalGate, applyCoarseReblock, readFinalGateSidecar, writeFinalGateSidecar, } from "./finalGate.js";
 import { buildNextContractPipelineStep, shouldEnterContractPipeline, writePathASeedFromFindings, } from "./contractPipeline.js";
 import { evaluateFastPath, buildLeanExtractedPlan, distinctAffectedFiles, interpretLeanLightReviewVerdict, LEAN_LIGHT_REVIEW_SCHEMA_VERSION, } from "./leanFastPath.js";
 import { contractArtifactExists, contractPipelineDir, } from "../contractPipeline/artifactStore.js";
@@ -29,6 +28,26 @@ import { runFindingFilterPass } from "../findingFilter.js";
 import { intakePaths, isIntakeReady, readIntakeArtifacts, resolveManifestSources, } from "../intake.js";
 import { ensureIntakeRiskSignal, readIntakeRiskSignal, writeIntakeRiskSignal, escalateRiskSignal, } from "../riskSignal.js";
 import { ambiguityReviewPrompt, clarificationPrompt, collectIntakeClarificationsPrompt, collectStartingPointPrompt, loaderCommand, reviewApprovalPrompt, synthesizeIntakePrompt, triagePrompt, } from "./prompts.js";
+// Single-sourced prose renders of the canonical lens / severity vocabularies
+// (`audit-tools/shared` `LENSES` / `SEVERITIES`) for the intent-checkpoint
+// prompt copy. Previously these 11-lens / 5-severity lists were hand-copied as
+// backtick-quoted literals in three places in this file and would silently drift
+// from the canonical enum (the very drift `types/lens.ts` exists to prevent).
+const VALID_LENSES_PROSE = LENSES.map((lens) => `\`${lens}\``).join(", ");
+const VALID_SEVERITIES_PROSE = SEVERITIES.map((sev) => `\`${sev}\``).join(", ");
+/**
+ * The host's resolved provider identity for quota-key / driver-classification
+ * purposes: the configured `sessionConfig.provider`, defaulting to the
+ * conversation host (`claude-code`) when unset or `auto`. Single-sourced so the
+ * `?? "claude-code"` default and the `auto`-exclusion live in ONE place rather
+ * than being re-spelled (with an ad-hoc cast) at each dispatch call site.
+ */
+function resolveHostProviderName(sessionConfig) {
+    const provider = sessionConfig?.provider;
+    if (provider === undefined || provider === "auto")
+        return "claude-code";
+    return provider;
+}
 export function resolveHostDispatchCapability(options) {
     if (options.hostCanDispatchSubagents !== undefined) {
         return options.hostCanDispatchSubagents;
@@ -478,6 +497,7 @@ export async function driveRollingDispatch(levels, options) {
                 estimatedTokens: estimateTokens(blockByPacketId.get(node.block_id)),
                 complexity: 0.5,
             }));
+            const hostSession = options.hostSession;
             const dispatcher = createRollingDispatcher({
                 confirmedPools: options.confirmedPools,
                 sessionConfig: options.sessionConfig,
@@ -485,6 +505,15 @@ export async function driveRollingDispatch(levels, options) {
                     const block = blockByPacketId.get(packet.payload.block_id);
                     return options.dispatchNode(block, slot);
                 },
+                // Host-session escalation: feed recordLimit (write) at the rate_limited
+                // observation point and read isEscalated (strand-not-requeue). The SAME
+                // instance sized the pools, so the bounded re-limit count is account-wide.
+                ...(hostSession
+                    ? {
+                        recordRateLimit: (packet, result) => hostSession.recordLimit(result.rateLimit?.channel ?? "error", result.rateLimit?.text ?? "", packet.id),
+                        isPacketEscalated: (packetId) => hostSession.isEscalated(packetId),
+                    }
+                    : {}),
             });
             dispatcher.enqueue(packets);
             levelResults.push(...(await dispatcher.run()));
@@ -583,6 +612,30 @@ export async function driveRollingImplementDispatch(options) {
     const promptPathByBlock = new Map(plan.items
         .filter((i) => typeof i.block_id === "string")
         .map((i) => [i.block_id, i.prompt_path]));
+    // The RETAINED host-session source: threaded through pool sizing AND the
+    // dispatcher's escalation hooks so the bounded re-limit chain (recordLimit →
+    // escalate → strand → quota_escalation friction) is fed end-to-end. Its
+    // onEscalation routes to the single step-boundary friction chokepoint with this
+    // driver's artifactsDir/runId, so a bounded account-wall escalation surfaces as
+    // reviewable friction instead of only a stderr line.
+    const providerName = resolveHostProviderName(options.sessionConfig);
+    const hostSessionModelKey = buildProviderModelKey(providerName, options.sessionConfig
+        ?.block_quota?.host_model ??
+        options.waveOptions?.hostModelId ??
+        null);
+    const hostSession = new HostSessionQuotaSource({
+        providerModelKey: hostSessionModelKey,
+        onEscalation: (escalation) => {
+            void captureStepBoundaryFriction(artifactsDir, runId, {
+                eventType: "quota_escalation",
+                discriminator: escalation.packet_id,
+                note: escalation.reason,
+                severity: "high",
+                category: "trap",
+                area: "dispatch/quota",
+            }, "remediate-code");
+        },
+    });
     // Confirmed pools: quota-derived concurrency, never the raw host flag (INV-QD-11).
     const confirmedPools = await buildConfirmedPools({
         sessionConfig: options.sessionConfig,
@@ -591,6 +644,7 @@ export async function driveRollingImplementDispatch(options) {
         hostOutputTokens: options.waveOptions?.hostOutputTokens,
         hostModels: options.waveOptions?.hostModels,
         hostModelId: options.waveOptions?.hostModelId,
+        hostSession,
     });
     // The live per-node worker: the configured provider, launched with the node's
     // worktree-rooted prompt and cwd = its worktree. Tests inject `options.dispatchNode`
@@ -687,6 +741,7 @@ export async function driveRollingImplementDispatch(options) {
         rebuildSharedBetweenLevels: options.rebuildSharedBetweenLevels,
         quotaStateDir: artifactsDir,
         root,
+        hostSession,
         scopeForBlock: (block) => writePathsByBlock.get(block.block_id) ?? block.touched_files ?? [],
     });
     // Deterministic merge: same path the wave flow uses (tolerant remap, write-scope
@@ -784,161 +839,13 @@ export async function executeInProcessPartition(params) {
 // Tool-owned final completion gate (INV-RS-10) + coarse re-block (INV-RS-09)
 // ---------------------------------------------------------------------------
 //
-// INV-RS-10: the final completion gate is a TOOL-OWNED, NON-VACUOUS suite that
-// is INDEPENDENT of any `plan.test_command`. A run can only land green when this
-// suite passes; a vacuous/unset `plan.test_command` can never substitute for it.
-// The suite is executed through the env-scrubbing `runTracked` path
-// (`runCommand`), which strips CLAUDECODE / CLAUDE_CODE_* so the gate runs in a
-// clean environment regardless of the host session.
-//
-// Hard floor (always run, in order — single package, single-flight build — CE-001):
-//   1. npm run build                          (one tsc build for the whole package)
-//   2. npm run check                          (typecheck, no emit)
-//   3. BUILD-FREE unit suites at the repo root, each invoked directly so dist is
-//      never rebuilt or raced:
-//        - shared+audit:  node --import tsx/esm --test tests/shared/*.test.mjs tests/audit/*.test.mjs
-//        - remediate-code: npx vitest run
-//
-// CE-002: the hard floor is scoped to build + typecheck + unit. The
-// runtime/packaged-bin smoke surface (the `verify:release` smokes) is recorded
-// as a DECLARED RESIDUAL the floor does not gate, rather than run inline — the
-// packaged-bin smokes are the known Windows-flaky / EPERM surface and an in-loop
-// gate must converge deterministically, so they are surfaced for a separate
-// pass instead of being able to strand the run.
-// `FinalGateCommandSpec`, `isAuditToolsMonorepo`, and `toolOwnedFinalGateCommands`
-// are single-sourced in the leaf module `gateCommands.ts` (so `dispatch.ts` can
-// derive the same pinned merged-base check without an import cycle). Imported above
-// for local use here and re-exported to preserve this module's public surface +
-// test imports.
-export { isAuditToolsMonorepo, toolOwnedFinalGateCommands };
-/**
- * Run the tool-owned final gate (INV-RS-10). Each command runs through
- * `runCommand` → shared `runTracked`, which scrubs CLAUDECODE / CLAUDE_CODE_*.
- * The first failing command short-circuits the floor (a broken build makes the
- * later layers meaningless). A `runner` may be injected for tests. When the
- * audit-tools suite does not apply (non-monorepo target), the gate is
- * `scoped_out` (does not block) rather than vacuously passing.
- */
-export async function runToolOwnedFinalGate(root, opts = {}) {
-    const runtime_residual = {
-        surface: "runtime/packaged-bin smokes (verify:release)",
-        commands: [
-            "npm run smoke:packaged-audit-code",
-            "npm run smoke:packaged-remediate-code",
-        ],
-    };
-    const commands = toolOwnedFinalGateCommands(root);
-    if (commands.length === 0) {
-        // Audit-tools-specific suite does not apply here — declared scope, not a
-        // vacuous pass (it never substitutes for a real gate on the audit-tools repo).
-        return { passed: true, results: [], scoped_out: true, runtime_residual };
-    }
-    const runner = opts.runner ??
-        ((argv, cwd, packageDir) => {
-            const [command, ...args] = argv;
-            // Package-scoped unit suites run with cwd at the package (no `npm -w`); the
-            // monorepo-root build/check commands run at the repo root.
-            const effectiveCwd = packageDir ? join(root, packageDir) : cwd;
-            // runCommand → runTracked strips CLAUDECODE / CLAUDE_CODE_* (INV-RS-10).
-            const result = runCommand(command, args, {
-                cwd: effectiveCwd,
-                stdio: ["ignore", "pipe", "pipe"],
-            });
-            return { status: result.status };
-        });
-    const results = [];
-    let passed = true;
-    for (const spec of commands) {
-        const { status } = runner(spec.argv, root, spec.package_dir);
-        const cmdPassed = status === 0;
-        results.push({
-            argv: spec.argv,
-            layer: spec.layer,
-            ...(spec.package_dir ? { package_dir: spec.package_dir } : {}),
-            exit_code: status,
-            passed: cmdPassed,
-        });
-        if (!cmdPassed) {
-            passed = false;
-            break; // short-circuit: later layers are meaningless on a broken floor
-        }
-    }
-    return { passed, results, scoped_out: false, runtime_residual };
-}
-/**
- * The bound on coarse re-block iterations before the run converges to a terminal
- * `blocked` close (CE-003). Two re-block attempts give a flaky-but-recoverable
- * suite a chance to settle; the third unattributable red terminates
- * deterministically rather than livelocking.
- */
-export const COARSE_REBLOCK_BOUND = 2;
-const FINAL_GATE_STATE_FILENAME = "final-gate.json";
-async function readFinalGateSidecar(artifactsDir) {
-    const sidecar = await readOptionalJsonFile(join(artifactsDir, FINAL_GATE_STATE_FILENAME));
-    const n = sidecar?.coarse_reblock_count;
-    return {
-        count: typeof n === "number" && Number.isFinite(n) && n >= 0 ? n : 0,
-        terminated: sidecar?.terminated === true,
-    };
-}
-async function writeFinalGateSidecar(artifactsDir, count, terminated) {
-    await writeJsonFile(join(artifactsDir, FINAL_GATE_STATE_FILENAME), {
-        schema_version: "remediate-code-final-gate/v1alpha1",
-        coarse_reblock_count: count,
-        terminated,
-    });
-}
-/**
- * Coarse re-block-ALL-non-terminal on an unattributable final-gate red
- * (INV-RS-09) with a bounded, monotonic auto-terminate (CE-003).
- *
- * The tool-owned gate is whole-repo, so a red is inherently unattributable to a
- * single node. Below the bound, EVERY non-skip item (including `resolved` ones —
- * a resolved item's own change may have caused the red) is re-opened to `pending`
- * and the run re-attempts the whole repo through the rolling scheduler
- * (`reattempt_all` → `implementing`). At or above the bound, the run STOPS
- * re-attempting and converges DETERMINISTICALLY: every non-skip item becomes
- * terminal `blocked` and the run advances to `closing`.
- *
- * CE-003 no-human-host guarantee: the loop is owned entirely by the gate + the
- * rolling scheduler — it NEVER routes through the human triage prompt
- * (`waiting_for_triage`) and is bounded by `bound`, so a permanently-red sibling
- * converges to a terminal `blocked` close deterministically: never livelocking,
- * never stranding on a human prompt, and never force-closed to green (a RED gate
- * always leaves `blocked` items, so close.ts's `!anyBlocked` guard keeps the run
- * out of the fully-green path). User SKIP dispositions (ignored /
- * deemed_inappropriate) are settled decisions and are left alone. Pure (the
- * counter is supplied / returned).
- */
-export function applyCoarseReblock(state, currentCount, gateSummary, bound = COARSE_REBLOCK_BOUND) {
-    const now = new Date().toISOString();
-    if (currentCount >= bound) {
-        // Bounded auto-terminate: converge DETERMINISTICALLY to a terminal `blocked`
-        // close for a no-human host — never livelock, never a triage prompt, never green.
-        for (const it of Object.values(state.items ?? {})) {
-            if (isSkipStatus(it.status))
-                continue; // settled user decision — never overturn
-            it.status = "blocked";
-            it.started_at ??= now;
-            it.completed_at = now;
-            it.failure_reason =
-                `Tool-owned final gate failed and the coarse re-block backstop reached its ` +
-                    `bound (${bound}); converging to a terminal blocked close (no-human host). ${gateSummary}`;
-        }
-        return { state, action: "terminal_blocked", next_count: currentCount };
-    }
-    // Below the bound: re-open every non-skip item to `pending` and re-attempt the
-    // whole repo via the rolling scheduler (NOT the human triage prompt).
-    for (const it of Object.values(state.items ?? {})) {
-        if (isSkipStatus(it.status))
-            continue;
-        it.status = "pending";
-        it.failure_context =
-            `Re-attempted by the coarse final-gate backstop (unattributable whole-repo red). ${gateSummary}`;
-        delete it.completed_at;
-    }
-    return { state, action: "reattempt_all", next_count: currentCount + 1 };
-}
+// The gate runner, its bounded coarse-reblock backstop, and the sidecar counter
+// I/O were extracted behaviour-preservingly into the sibling leaf module
+// `finalGate.ts` (CP-NODE-1). They are imported below for local use in the
+// completion handler and re-exported to preserve this module's public surface +
+// existing test imports. See `finalGate.ts` for the INV-RS-10 / CE-001 / CE-002
+// documentation.
+export { isAuditToolsMonorepo, toolOwnedFinalGateCommands, runToolOwnedFinalGate, applyCoarseReblock, COARSE_REBLOCK_BOUND, } from "./finalGate.js";
 function resolvedOrTerminalItems(state) {
     return Object.values(state.items ?? {}).filter((item) => isTerminalStatus(item.status));
 }
@@ -1341,8 +1248,7 @@ async function buildImplementDispatchStep(ctx) {
         // S-BROKER-WIRING: pick the dispatch DRIVER (delegate the rolling loop to a
         // dedicated dispatcher subagent vs. drive it from the top host) off the
         // single classification + the live frontier/slot count — not host prose.
-        const hostProvider = sessionConfigImpl?.provider ??
-            "claude-code";
+        const hostProvider = resolveHostProviderName(sessionConfigImpl);
         const driverSelection = selectDispatchDriver({
             classification: classifyProvider(hostProvider),
             eligibleItemCount: rolling.session.frontier.length,
@@ -2179,7 +2085,7 @@ Choose one explicitly and report the choice to the user:
 1. **Resume the existing run** — re-run WITHOUT \`--input\`: \`${loaderCommand("next-step")}\`
 2. **Start fresh from the new input** — first move aside or delete the existing
    \`${artifactsDir}\` directory (and the stale \`remediation-report.md\` /
-   \`remediation-report.json\` in \`.audit-tools/\`, which would otherwise be overwritten on completion),
+   \`remediation-outcomes.json\` in \`.audit-tools/\`, which would otherwise be overwritten on completion),
    then re-run \`${loaderCommand("next-step --input <path>")}\`.
 
 Stop after presenting this choice. Do not advance the run until the user decides.
@@ -2984,10 +2890,8 @@ To confirm, write the final checkpoint to:
 \`\`\`
 
 Adjust \`filters\`, \`excluded_scope\`, \`must_not_touch\`, or \`free_form_intent\` to
-narrow scope. Valid severities: \`critical\`, \`high\`, \`medium\`, \`low\`, \`info\`.
-Valid lenses: \`correctness\`, \`architecture\`, \`maintainability\`, \`security\`,
-\`reliability\`, \`performance\`, \`data_integrity\`, \`tests\`, \`operability\`,
-\`config_deployment\`, \`observability\`.
+narrow scope. Valid severities: ${VALID_SEVERITIES_PROSE}.
+Valid lenses: ${VALID_LENSES_PROSE}.
 
 Once written with \`"confirmed_by": "host"\`, run:
 
@@ -3024,7 +2928,7 @@ Only \`scope_summary\` and \`intent_summary\` are required; add the optional fie
 }
 \`\`\`
 
-- \`filters\` drop findings that don't match BEFORE planning, so only the work you want is remediated. Valid severities: \`critical\`, \`high\`, \`medium\`, \`low\`, \`info\`. Valid lenses: \`correctness\`, \`architecture\`, \`maintainability\`, \`security\`, \`reliability\`, \`performance\`, \`data_integrity\`, \`tests\`, \`operability\`, \`config_deployment\`, \`observability\`. Draw \`packages\`/\`themes\` from the findings in the audit report.
+- \`filters\` drop findings that don't match BEFORE planning, so only the work you want is remediated. Valid severities: ${VALID_SEVERITIES_PROSE}. Valid lenses: ${VALID_LENSES_PROSE}. Draw \`packages\`/\`themes\` from the findings in the audit report.
 - \`excluded_scope\` drops findings whose files match a path or directory prefix; \`must_not_touch\` globs are never written.
 - Skipped findings are listed in the final remediation report under "Skipped by Intent Checkpoint".
 - Leave the optional fields out to remediate everything in the report.