audit-tools 0.30.49 → 0.30.53

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, HostSessionQuotaSource, buildProviderModelKey, captureStepBoundaryFriction } from "audit-tools/shared";
+import { readOptionalJsonFile, writeJsonFile, writeTextFile, buildAuditDeliverablePair, formatValidationIssues, isRecord, withFsRetry, RunLogger, DISPATCH_PROMPT_HANDOFF_NOTE, renderQuotaCoverageNudge, renderTokenBudgetView, 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;
@@ -498,11 +517,42 @@ export async function driveRollingDispatch(levels, options) {
             });
             dispatcher.enqueue(packets);
             levelResults.push(...(await dispatcher.run()));
+            // Piece D: surface the wave's partial-completion terminal (quota_paused /
+            // empty_pool). Aggregate across waves keeping the EARLIEST-reset quota_paused
+            // terminal (a paused wave is retryable and should resume soonest); union the
+            // stranded ids so a later step re-dispatches all of them. An empty_pool
+            // terminal only stands when no quota_paused terminal was seen.
+            out.terminal = mergePartialTerminals(out.terminal, dispatcher.getTerminal());
         }
         out.levels.push({ blockIds: level.map((b) => b.block_id), results: levelResults });
     }
     return out;
 }
+/**
+ * Fold a newly-observed partial-completion terminal into the run's aggregate
+ * (piece D). Prefers `quota_paused` (retryable) over `empty_pool`; among
+ * quota_paused terminals keeps the EARLIEST `earliest_reset_at`; always unions the
+ * stranded ids so no stranded node is lost across waves.
+ */
+function mergePartialTerminals(prior, next) {
+    if (!next)
+        return prior;
+    if (!prior)
+        return next;
+    const strandedIds = [...new Set([...prior.stranded_ids, ...next.stranded_ids])];
+    const priorPaused = prior.reason === "quota_paused";
+    const nextPaused = next.reason === "quota_paused";
+    if (priorPaused || nextPaused) {
+        const resets = [prior.earliest_reset_at, next.earliest_reset_at].filter((r) => typeof r === "string");
+        const earliest = resets.length > 0 ? resets.sort()[0] : undefined;
+        return {
+            reason: "quota_paused",
+            stranded_ids: strandedIds,
+            ...(earliest ? { earliest_reset_at: earliest } : {}),
+        };
+    }
+    return { reason: prior.reason, stranded_ids: strandedIds };
+}
 /**
  * Backends the orchestrator can drive IN-PROCESS as the per-node implement worker
  * via `driveRollingImplementDispatch` (it resolves + launches the provider with each
@@ -599,8 +649,7 @@ export async function driveRollingImplementDispatch(options) {
     // 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 = options.sessionConfig?.provider ??
-        "claude-code";
+    const providerName = resolveHostProviderName(options.sessionConfig);
     const hostSessionModelKey = buildProviderModelKey(providerName, options.sessionConfig
         ?.block_quota?.host_model ??
         options.waveOptions?.hostModelId ??
@@ -716,7 +765,7 @@ export async function driveRollingImplementDispatch(options) {
     // the merge-time write-scope gate reads — for file-ownership-disjoint admission
     // (INV-SOO). A block with no plan scope falls back to its touched_files.
     const writePathsByBlock = new Map(allBlockScopes.map((s) => [s.block_id, s.write_paths]));
-    await driveRollingDispatch(levels, {
+    const driven = await driveRollingDispatch(levels, {
         confirmedPools,
         sessionConfig: options.sessionConfig ?? {},
         dispatchNode: dispatchNodeWithWorktree,
@@ -726,6 +775,19 @@ export async function driveRollingImplementDispatch(options) {
         hostSession,
         scopeForBlock: (block) => writePathsByBlock.get(block.block_id) ?? block.touched_files ?? [],
     });
+    // Piece D — persist the rolling engine's partial-completion terminal onto state
+    // BEFORE the merge, so the merge can SKIP-block the quota_paused stranded nodes
+    // (their worker rate-limited → no result file, but they must stay PENDING for a
+    // later step to redispatch clean — the worktrees were PRESERVED by
+    // acceptNodeWorktree). An `empty_pool` terminal does not affect the merge (its
+    // nodes are genuine failures); the `partial_terminal` obligation blocks them.
+    if (driven.terminal) {
+        const pre = await new StateStore(artifactsDir).loadState();
+        if (pre) {
+            pre.partial_completion_terminal = driven.terminal;
+            await new StateStore(artifactsDir).saveState(pre);
+        }
+    }
     // Deterministic merge: same path the wave flow uses (tolerant remap, write-scope
     // gate against each verified branch, lost-update detection). Worktrees are
     // already removed; the merge reads each node's result file + branch diff.
@@ -821,161 +883,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));
 }
@@ -1378,8 +1292,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,
@@ -1437,6 +1350,8 @@ Then run:
 
 ${renderQuotaCoverageNudge(rolling.quotaPath, artifactsDir)}
 
+${renderTokenBudgetView(rolling.quotaPath)}
+
 ${DISPATCH_PROMPT_HANDOFF_NOTE}
 `,
                 allowedCommands: [acceptCmd, rollMerge, rollNext],
@@ -1533,6 +1448,8 @@ ${SHARED_REBUILD_BETWEEN_LEVELS_NOTE}
 
 ${renderQuotaCoverageNudge(implQuotaPath, artifactsDir)}
 
+${renderTokenBudgetView(implQuotaPath)}
+
 ${DISPATCH_PROMPT_HANDOFF_NOTE}
 
 After all results exist:
@@ -1548,6 +1465,41 @@ Then run:
             artifactPaths: { dispatch_plan: planPath, dispatch_quota: implQuotaPath },
         }) };
 }
+/**
+ * Piece D — the quota-paused resumable step. The rolling engine stranded one or
+ * more nodes because every eligible provider pool hit a host session limit and is
+ * paused until its stated reset. The stranded nodes stay PENDING (their worktrees
+ * were preserved), so re-running next-step at/after `resetAt` redispatches them
+ * clean. Emitted (not blocked) so the run is resumable, never a failure.
+ */
+async function buildQuotaPausedStep(params) {
+    const { root, artifactsDir, runId, strandedIds, resetAt } = params;
+    const nextCommand = loaderCommand("next-step");
+    const resetLine = resetAt
+        ? `The earliest provider reset is \`${resetAt}\`. Wait until then, then run:`
+        : `Wait for the provider session limit to reset, then run:`;
+    return writeCurrentStep({
+        stepKind: "quota_paused",
+        status: "ready",
+        runId,
+        repoRoot: root,
+        artifactsDir,
+        prompt: `
+# Remediation paused — provider session limit
+
+Every eligible provider pool hit a host session limit and is paused until its
+stated reset. ${strandedIds.length} node(s) are stranded and remain PENDING —
+their worktrees were preserved, so they will redispatch clean on resume. Nothing
+was blocked or failed; this is a resumable pause.
+
+${resetLine}
+
+\`${nextCommand}\`
+`,
+        allowedCommands: [nextCommand],
+        stopCondition: "Stop and wait for the provider reset. Re-running next-step resumes the stranded nodes.",
+    });
+}
 // --- Per-state handlers -----------------------------------------------------
 // Each handler owns one branch of the original decideNextStepInner dispatch.
 // Handlers that emit a step return RemediationStep directly; handlers that need
@@ -2216,7 +2168,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.
@@ -3021,10 +2973,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:
 
@@ -3061,7 +3011,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.
@@ -3421,6 +3371,28 @@ function buildMainObligations(ctx) {
                 const terminal = s.partial_completion_terminal;
                 if (!terminal)
                     return { kind: "transition", state: s };
+                // Piece D — quota_paused is a RETRYABLE pause, NOT a failure. The stranded
+                // nodes stay PENDING (their worktrees were preserved), nothing is blocked,
+                // and the close transition is NOT forced. EMIT a paused step (terminating
+                // this advance loop) that tells the host to re-run next-step at/after the
+                // stated reset, when the pool's session limit has cleared and the stranded
+                // nodes redispatch clean. Clearing the terminal here (before the emit) so
+                // the resuming step starts fresh; the pending nodes are the durable signal.
+                if (terminal.reason === "quota_paused") {
+                    const resetAt = terminal.earliest_reset_at ?? null;
+                    delete s.partial_completion_terminal;
+                    await store.saveState(s);
+                    return {
+                        kind: "emit",
+                        step: await buildQuotaPausedStep({
+                            root,
+                            artifactsDir,
+                            runId: stateRunId(s),
+                            strandedIds: terminal.stranded_ids ?? [],
+                            resetAt,
+                        }),
+                    };
+                }
                 const strandedSet = new Set(terminal.stranded_ids ?? []);
                 for (const it of Object.values(s.items ?? {})) {
                     if (isTerminalStatus(it.status))