@on-par/factory-core 0.9.3 → 0.9.5-next.1

package/dist/run/run-issue.js

@@ -6,8 +6,10 @@
 //   3. the acquired Environment is released exactly once on every exit path.
 //   4. a failed environment lease degrades (appPort undefined) rather than parking the run.
 //   5. exactly one terminal event sequence is emitted per run, matching the returned RunOutcome
-//      (including the non-park `released` exit for an environment-caused CHECK failure, #1928).
+//      (including the non-park `released` exit for an environment-caused CHECK failure, #1928; a config cause parks, #2583).
 // PLAN may be skipped by the planReuse port after an environment release (#2340).
+// CHECK may be resumed on a kept worktree via request.resumeFrom after an environment release (#2564).
+// A config preflight (#2586) rejects unfilled template tokens before base health and PLAN; any preflight failure parks with the `config` cause (#2587).
 //
 // Path-bound CLI concerns (Octokit, worktree/environment provisioning, the events sink,
 // approval/steering, and reporting hooks) are injected as ports so this file stays free of
@@ -18,6 +20,7 @@ import { laneEnv } from '../environment/index.js';
 import { buildPhase as buildPhaseDefault } from '../phases/build.js';
 import { checkPhase as checkPhaseDefault, remainingShowstoppers, renderEnvironmentReleaseComment, } from '../phases/check.js';
 import { describeConstitutionSource } from '../constitutions/index.js';
+import { lintFactoryConfig } from '../config/config-lint.js';
 import { planPhase as planPhaseDefault } from '../phases/plan.js';
 import { shipPhase as shipPhaseDefault } from '../phases/ship.js';
 import { upsertSlicePlanComment } from '../readiness/slice-plan-github.js';
@@ -35,7 +38,7 @@ import { gateBuildOnBreaker, parseResetCooldownMs } from '../router/breaker.js';
 import { describeSteering } from '../steering/index.js';
 import { touchedFilesFrom } from './lane-file-guard.js';
 import { parkReasonFor } from './outcome.js';
-import { issueBodyHash } from './resume-context.js';
+import { configParkMessage, formatPreservedBuildMessage, issueBodyHash, preservedFixTarget, } from './resume-context.js';
 function errorMessage(err) {
     return err instanceof Error ? err.message : String(err);
 }
@@ -278,6 +281,18 @@ export async function runIssue(request, policy, ports) {
         // later would let the build worker author the standards it is graded by.
         const constitution = ports.resolveConstitution();
         log('constitution', describeConstitutionSource(constitution, request.product));
+        // Pre-PLAN config preflight (#2585/#2586), shared with `factory doctor` via lintFactoryConfig (#2612).
+        // An unknown `checkers:` entry would only fail closed in CHECK, after PLAN and BUILD spent model calls;
+        // unfilled scaffold tokens would ship a placeholder. Read-only, no subprocess, runs for localOnly too.
+        // Any failing verdict parks with the `config` cause (#2587); checker findings come first in the message.
+        const lint = lintFactoryConfig({ constitution, configFile: request.repoConfigFile });
+        if (lint.verdict !== 'ok') {
+            return terminalParked('config', [
+                'config preflight failed before PLAN:',
+                ...lint.findings.map((f) => f.message),
+                `then run factory unpark ${request.issue}`,
+            ].join('\n'));
+        }
         // Pre-PLAN base health (#2339): a red origin/main releases the issue before any model spend;
         // the CLI turns `released` into LaneEnvironmentPauseError, whose runLane branch writes the base hold.
         if (ports.checkBaseHealth && !request.localOnly) {
@@ -312,193 +327,228 @@ export async function runIssue(request, policy, ports) {
         // inside CHECK must diff against this same base rather than a moving target.
         runStartDiffBase = request.localOnly ? await captureDiffBase(ports.workspace.path) : undefined;
         // PLAN
-        await setPhase('plan');
-        const planModel = await preferFallbackWhenProviderIsOpen(request.modelPins.plan, request.modelPins.planFallback, 'PLAN');
-        // A pinned build model determines the route (#1367): an explicit repo `route` still wins, but
-        // without one the pin's harness decides, so PLAN cannot send an Anthropic-pinned build to Codex.
-        // Two guards keep the pin from resurrecting a route the operator turned off: local-only mode
-        // forces codex in PLAN and a pin must not undo that; and a codex pin while codex is disabled
-        // cannot force codex — PLAN's codex→claude fallback applies and the compatibility check below
-        // drops the pin, exactly as on main.
-        let derivedRoute = request.preferredRoute || request.localOnly
-            ? undefined
-            : routeForBuildModel(ports.router.registryRef, request.modelPins.build);
-        if (derivedRoute === 'codex' && request.codexDisabled) {
-            log('model-override', `pinned build model ${request.modelPins.build} needs the codex route but codex is disabled — the pin cannot force it`);
-            derivedRoute = undefined;
-        }
-        const pinnedRoute = request.preferredRoute ?? derivedRoute;
-        if (derivedRoute) {
-            log('model-override', `build route derived from pinned build model ${request.modelPins.build} → ${derivedRoute}`);
+        const planStartedMs = Date.now();
+        let planRoute;
+        let planSlice;
+        let buildDiffBase;
+        let builtRoute;
+        let builtModel;
+        let pinNote;
+        let buildMinutes;
+        if (request.resumeFrom) {
+            const resumed = request.resumeFrom;
+            ports.events('check')('check', `resuming #${request.issue} from CHECK on kept branch ${request.branch} — PLAN and BUILD skipped`);
+            route = resumed.route;
+            planRoute = resumed.route;
+            planSlice = undefined;
+            buildDiffBase = resumed.diffBase;
+            builtRoute = resumed.route;
+            builtModel = resumed.model;
+            pinNote = undefined;
+            buildMinutes = resumed.buildMinutes;
         }
-        const reusablePlan = async () => {
-            if (!ports.planReuse)
-                return null;
-            let hit = null;
-            try {
-                hit = await ports.planReuse.load(issueBodyHash(request.work.brief));
+        else {
+            await setPhase('plan');
+            const planModel = await preferFallbackWhenProviderIsOpen(request.modelPins.plan, request.modelPins.planFallback, 'PLAN');
+            // A pinned build model determines the route (#1367): an explicit repo `route` still wins, but
+            // without one the pin's harness decides, so PLAN cannot send an Anthropic-pinned build to Codex.
+            // Two guards keep the pin from resurrecting a route the operator turned off: local-only mode
+            // forces codex in PLAN and a pin must not undo that; and a codex pin while codex is disabled
+            // cannot force codex — PLAN's codex→claude fallback applies and the compatibility check below
+            // drops the pin, exactly as on main.
+            let derivedRoute = request.preferredRoute || request.localOnly
+                ? undefined
+                : routeForBuildModel(ports.router.registryRef, request.modelPins.build);
+            if (derivedRoute === 'codex' && request.codexDisabled) {
+                log('model-override', `pinned build model ${request.modelPins.build} needs the codex route but codex is disabled — the pin cannot force it`);
+                derivedRoute = undefined;
             }
-            catch (err) {
-                log('environment_warning', `could not read the plan-reuse record: ${errorMessage(err)} — planning`);
+            const pinnedRoute = request.preferredRoute ?? derivedRoute;
+            if (derivedRoute) {
+                log('model-override', `build route derived from pinned build model ${request.modelPins.build} → ${derivedRoute}`);
             }
-            try {
-                await ports.planReuse.clear();
+            const reusablePlan = async () => {
+                if (!ports.planReuse)
+                    return null;
+                let hit = null;
+                try {
+                    hit = await ports.planReuse.load(issueBodyHash(request.work.brief));
+                }
+                catch (err) {
+                    log('environment_warning', `could not read the plan-reuse record: ${errorMessage(err)} — planning`);
+                }
+                try {
+                    await ports.planReuse.clear();
+                }
+                catch (err) {
+                    log('environment_warning', `could not clear the plan-reuse record: ${errorMessage(err)}`);
+                }
+                if (hit) {
+                    ports.events('plan')('plan_reused', `reusing frozen plan ${request.specPath} for #${request.issue} — body unchanged since the environment release, no PLAN model call`);
+                }
+                return hit;
+            };
+            const plan = (await reusablePlan()) ??
+                (await planPhase({
+                    issue: request.issue,
+                    repo: request.repo,
+                    worktree: ports.workspace.path,
+                    specPath: request.specPath,
+                    constitution,
+                    router: ports.router,
+                    octokit: ports.octokit,
+                    log: ports.events('plan'),
+                    timeoutSeconds: request.timeouts.plan,
+                    modelOverride: planModel,
+                    modelFallbacks: planModel === request.modelPins.plan && request.modelPins.planFallback
+                        ? [request.modelPins.planFallback]
+                        : undefined,
+                    onProviderFailure: rememberProviderFailure,
+                    branch: request.branch,
+                    approvalGate: request.options.approvePlan ? ports.createApprovalGate?.() : undefined,
+                    drainSteering: request.options.approvePlan ? ports.drainSteering : undefined,
+                    codexDisabled: request.codexDisabled,
+                    localOnly: request.localOnly,
+                    laneId: request.lane,
+                    workSource: request.workSource,
+                    enforceReadiness: true,
+                    fastPath: request.efficiency.fastPath,
+                    enforceSizeGate: (request.sizeGateMode ?? 'file') !== 'off',
+                    sizeGateMode: request.sizeGateMode,
+                    maxSlices: request.maxSlices,
+                    blockUnresolvedRegressions: request.blockUnresolvedRegressions,
+                    updateIssueBodyOnEnrich: request.readinessUpdateIssueBody,
+                    preferredRoute: pinnedRoute,
+                }));
+            route = plan.route;
+            if (!plan.ok) {
+                const decomposedChildren = plan.decomposed?.childIssues ?? [];
+                if (decomposedChildren.length > 0) {
+                    await ports.onDecomposed?.(decomposedChildren);
+                    const childList = decomposedChildren.map((n) => `#${n}`).join(', ');
+                    return { state: 'escalated', reason: `issue #${request.issue} decomposed into ${childList}`, route };
+                }
+                if (plan.sliced) {
+                    return terminalEscalated(`issue #${request.issue} sliced into ${plan.sliced.sliceCount} slice(s): ${plan.escalate ?? 'slice plan recorded'}`);
+                }
+                return terminalEscalated(`plan escalated: ${plan.escalate ?? 'unknown'}`);
             }
-            catch (err) {
-                log('environment_warning', `could not clear the plan-reuse record: ${errorMessage(err)}`);
+            const planBudget = await assertBudget('PLAN');
+            if (planBudget)
+                return planBudget;
+            // Same-file lane guard (#1515): before this run claims BUILD, make sure no other
+            // in-flight run in this repo already owns a file PLAN just said this run will touch.
+            if (ports.laneFileGuard && plan.designArtifact) {
+                const touchedFiles = touchedFilesFrom(plan.designArtifact);
+                const collision = await ports.laneFileGuard.findCollision(request.repo, request.issue, touchedFiles);
+                if (collision) {
+                    return terminalParked('held', `issue held: #${request.issue} touches ${collision.file}, already claimed by in-flight issue #${collision.issue} — held until that lane finishes`);
+                }
+                if (touchedFiles.length > 0) {
+                    await ports.laneFileGuard.register(request.repo, request.issue, touchedFiles);
+                    laneFileClaimed = true;
+                }
             }
-            if (hit) {
-                ports.events('plan')('plan_reused', `reusing frozen plan ${request.specPath} for #${request.issue} — body unchanged since the environment release, no PLAN model call`);
+            // BUILD
+            await setPhase('build');
+            let buildSteering;
+            if (request.options.interactive) {
+                buildSteering = ports.drainSteering?.();
+                if (buildSteering && buildSteering.messages.length > 0) {
+                    ports.events('build')('steering_applied', describeSteering(buildSteering));
+                }
             }
-            return hit;
-        };
-        const plan = (await reusablePlan()) ??
-            (await planPhase({
+            let breakerBlocked = false;
+            if (request.failover.enabled) {
+                const providers = [
+                    ...new Set(ports.router
+                        .resolveAll('build_codex')
+                        .map((m) => ports.router.registryRef.get(m)?.provider)
+                        .filter((p) => Boolean(p))),
+                ];
+                const gate = await gateBuildOnBreaker({ breaker: ports.breaker, providers, log: ports.events('build') });
+                breakerBlocked = gate.codexBlocked;
+            }
+            // PLAN already honors pinnedRoute and rewrites the spec; re-apply here so a plan port that
+            // ignores it (a daemon or a test double) still cannot route a pinned worker elsewhere.
+            let buildRoute = pinnedRoute ?? plan.route;
+            let buildModel = request.modelPins.build;
+            if (request.failover.enabled && buildRoute === 'claude') {
+                const primaryClaude = buildModel ?? ports.router.resolveAll('build_claude')[0];
+                const fallbackCodex = request.modelPins.buildFallback ?? ports.router.resolveAll('build_codex')[0];
+                const selected = await preferFallbackWhenProviderIsOpen(primaryClaude, fallbackCodex, 'BUILD');
+                if (selected && selected !== primaryClaude) {
+                    buildRoute = 'codex';
+                    buildModel = selected;
+                }
+            }
+            if (buildModel) {
+                const harnessId = ports.router.registryRef.getHarnessId(buildModel);
+                const compatible = buildRoute === 'codex'
+                    ? ports.router.registryRef.isCodexModel(buildModel)
+                    : buildRoute === 'opencode'
+                        ? harnessId === 'opencode'
+                        : harnessId === 'claude-cli';
+                if (!compatible) {
+                    log('model_override_ignored', `build model ${buildModel} is incompatible with the ${buildRoute} route${buildRoute === request.preferredRoute ? ' pinned by .factory/config.json' : ''} — using that route's default worker`);
+                    buildModel = undefined;
+                }
+            }
+            const build = await buildPhase({
+                runId,
                 issue: request.issue,
                 repo: request.repo,
                 worktree: ports.workspace.path,
                 specPath: request.specPath,
+                branch: request.branch,
                 constitution,
+                route: buildRoute,
                 router: ports.router,
-                octokit: ports.octokit,
-                log: ports.events('plan'),
-                timeoutSeconds: request.timeouts.plan,
-                modelOverride: planModel,
-                modelFallbacks: planModel === request.modelPins.plan && request.modelPins.planFallback
-                    ? [request.modelPins.planFallback]
-                    : undefined,
+                log: ports.events('build'),
+                timeoutSeconds: request.timeouts.build,
+                skipCI: request.skipCI,
+                disablePublish: Boolean(request.localOnly),
+                publishFromBuild: request.publishFromBuild,
+                modelOverride: buildModel,
+                pinnedModel: buildModel !== undefined && buildModel === request.modelPins.build,
+                codexFallbackModel: request.modelPins.buildFallback ?? ports.router.resolveAll('build_codex')[0],
                 onProviderFailure: rememberProviderFailure,
-                branch: request.branch,
-                approvalGate: request.options.approvePlan ? ports.createApprovalGate?.() : undefined,
-                drainSteering: request.options.approvePlan ? ports.drainSteering : undefined,
-                codexDisabled: request.codexDisabled,
+                sandbox: request.sandboxPolicy,
+                steering: buildSteering,
+                appPort,
+                appBaseUrl,
+                codexDisabled: request.codexDisabled || breakerBlocked,
                 localOnly: request.localOnly,
+                autoFailover: { enabled: request.failover.enabled, fallbackModel: request.failover.fallbackModel },
+                onPgid,
                 laneId: request.lane,
-                workSource: request.workSource,
-                enforceReadiness: true,
-                fastPath: request.efficiency.fastPath,
-                enforceSizeGate: (request.sizeGateMode ?? 'file') !== 'off',
-                sizeGateMode: request.sizeGateMode,
-                maxSlices: request.maxSlices,
-                blockUnresolvedRegressions: request.blockUnresolvedRegressions,
-                updateIssueBodyOnEnrich: request.readinessUpdateIssueBody,
-                preferredRoute: pinnedRoute,
-            }));
-        route = plan.route;
-        if (!plan.ok) {
-            const decomposedChildren = plan.decomposed?.childIssues ?? [];
-            if (decomposedChildren.length > 0) {
-                await ports.onDecomposed?.(decomposedChildren);
-                const childList = decomposedChildren.map((n) => `#${n}`).join(', ');
-                return { state: 'escalated', reason: `issue #${request.issue} decomposed into ${childList}`, route };
-            }
-            if (plan.sliced) {
-                return terminalEscalated(`issue #${request.issue} sliced into ${plan.sliced.sliceCount} slice(s): ${plan.escalate ?? 'slice plan recorded'}`);
-            }
-            return terminalEscalated(`plan escalated: ${plan.escalate ?? 'unknown'}`);
-        }
-        const planBudget = await assertBudget('PLAN');
-        if (planBudget)
-            return planBudget;
-        // Same-file lane guard (#1515): before this run claims BUILD, make sure no other
-        // in-flight run in this repo already owns a file PLAN just said this run will touch.
-        if (ports.laneFileGuard && plan.designArtifact) {
-            const touchedFiles = touchedFilesFrom(plan.designArtifact);
-            const collision = await ports.laneFileGuard.findCollision(request.repo, request.issue, touchedFiles);
-            if (collision) {
-                return terminalParked('held', `issue held: #${request.issue} touches ${collision.file}, already claimed by in-flight issue #${collision.issue} — held until that lane finishes`);
-            }
-            if (touchedFiles.length > 0) {
-                await ports.laneFileGuard.register(request.repo, request.issue, touchedFiles);
-                laneFileClaimed = true;
-            }
-        }
-        // BUILD
-        await setPhase('build');
-        let buildSteering;
-        if (request.options.interactive) {
-            buildSteering = ports.drainSteering?.();
-            if (buildSteering && buildSteering.messages.length > 0) {
-                ports.events('build')('steering_applied', describeSteering(buildSteering));
-            }
-        }
-        let breakerBlocked = false;
-        if (request.failover.enabled) {
-            const providers = [
-                ...new Set(ports.router
-                    .resolveAll('build_codex')
-                    .map((m) => ports.router.registryRef.get(m)?.provider)
-                    .filter((p) => Boolean(p))),
-            ];
-            const gate = await gateBuildOnBreaker({ breaker: ports.breaker, providers, log: ports.events('build') });
-            breakerBlocked = gate.codexBlocked;
-        }
-        // PLAN already honors pinnedRoute and rewrites the spec; re-apply here so a plan port that
-        // ignores it (a daemon or a test double) still cannot route a pinned worker elsewhere.
-        let buildRoute = pinnedRoute ?? plan.route;
-        let buildModel = request.modelPins.build;
-        if (request.failover.enabled && buildRoute === 'claude') {
-            const primaryClaude = buildModel ?? ports.router.resolveAll('build_claude')[0];
-            const fallbackCodex = request.modelPins.buildFallback ?? ports.router.resolveAll('build_codex')[0];
-            const selected = await preferFallbackWhenProviderIsOpen(primaryClaude, fallbackCodex, 'BUILD');
-            if (selected && selected !== primaryClaude) {
-                buildRoute = 'codex';
-                buildModel = selected;
-            }
-        }
-        if (buildModel) {
-            const harnessId = ports.router.registryRef.getHarnessId(buildModel);
-            const compatible = buildRoute === 'codex'
-                ? ports.router.registryRef.isCodexModel(buildModel)
-                : buildRoute === 'opencode'
-                    ? harnessId === 'opencode'
-                    : harnessId === 'claude-cli';
-            if (!compatible) {
-                log('model_override_ignored', `build model ${buildModel} is incompatible with the ${buildRoute} route${buildRoute === request.preferredRoute ? ' pinned by .factory/config.json' : ''} — using that route's default worker`);
-                buildModel = undefined;
-            }
-        }
-        const build = await buildPhase({
-            runId,
-            issue: request.issue,
-            repo: request.repo,
-            worktree: ports.workspace.path,
-            specPath: request.specPath,
-            branch: request.branch,
-            constitution,
-            route: buildRoute,
-            router: ports.router,
-            log: ports.events('build'),
-            timeoutSeconds: request.timeouts.build,
-            skipCI: request.skipCI,
-            disablePublish: Boolean(request.localOnly),
-            publishFromBuild: request.publishFromBuild,
-            modelOverride: buildModel,
-            codexFallbackModel: request.modelPins.buildFallback ?? ports.router.resolveAll('build_codex')[0],
-            onProviderFailure: rememberProviderFailure,
-            sandbox: request.sandboxPolicy,
-            steering: buildSteering,
-            appPort,
-            appBaseUrl,
-            codexDisabled: request.codexDisabled || breakerBlocked,
-            localOnly: request.localOnly,
-            autoFailover: { enabled: request.failover.enabled, fallbackModel: request.failover.fallbackModel },
-            onPgid,
-            laneId: request.lane,
-        });
-        route = build.route;
-        if (!build.ok) {
-            if (build.reason === 'no_diff') {
-                return terminalParked('fail', 'build produced no diff against the base ref — no implementation was produced');
-            }
-            if (build.reason === 'junk_only_diff') {
-                return terminalParked('fail', 'build changed only generated/cache files (e.g. __pycache__) — no implementation was produced');
+            });
+            route = build.route;
+            if (!build.ok) {
+                if (build.reason === 'no_diff') {
+                    return terminalParked('fail', 'build produced no diff against the base ref — no implementation was produced');
+                }
+                if (build.reason === 'junk_only_diff') {
+                    return terminalParked('fail', 'build changed only generated/cache files (e.g. __pycache__) — no implementation was produced');
+                }
+                return terminalEscalated(`build escalated: ${build.escalate ?? 'unknown'}`);
             }
-            return terminalEscalated(`build escalated: ${build.escalate ?? 'unknown'}`);
+            const buildBudget = await assertBudget('BUILD');
+            if (buildBudget)
+                return buildBudget;
+            // #2511: say so when a permitted failover built with something other than the user's pin.
+            const pinnedBuild = request.modelPins.build;
+            pinNote =
+                pinnedBuild !== undefined && build.model !== pinnedBuild
+                    ? `build pin ${pinnedBuild} not used (${build.failoverReason ?? 'overridden'}); built with ${build.model}`
+                    : undefined;
+            planRoute = plan.route;
+            planSlice = plan.slice;
+            buildDiffBase = build.diffBase;
+            builtRoute = build.route;
+            builtModel = build.model;
+            buildMinutes = Math.max(1, Math.round((Date.now() - planStartedMs) / 60_000));
         }
-        const buildBudget = await assertBudget('BUILD');
-        if (buildBudget)
-            return buildBudget;
         // CHECK
         await setPhase('check');
         const priorFailureSignature = await ports.reworkHistory?.priorSignature(request.issue);
@@ -521,9 +571,9 @@ export async function runIssue(request, policy, ports) {
             appBaseUrl,
             onPgid,
             priorFailureSignature,
-            diffBase: request.localOnly ? runStartDiffBase : build.diffBase,
-            reworkRoute: build.route,
-            reworkModel: build.model,
+            diffBase: request.localOnly ? runStartDiffBase : buildDiffBase,
+            reworkRoute: builtRoute,
+            reworkModel: builtModel,
             laneId: request.lane,
             onActivity: ports.onActivity,
             logsDir: request.logsDir,
@@ -555,12 +605,36 @@ export async function runIssue(request, policy, ports) {
                 });
             }
         }
+        const clearCheckResume = async () => {
+            if (!request.resumeFrom)
+                return;
+            try {
+                await ports.checkResume?.clear();
+            }
+            catch (err) {
+                log('environment_warning', `could not clear the check-resume point: ${errorMessage(err)}`);
+            }
+        };
         const checkBudget = await assertBudget('CHECK');
         if (checkBudget)
             return checkBudget;
         if (!check.passed) {
             if (check.environment) {
                 const env = check.environment;
+                if (env.cause === 'config') {
+                    // A config failure fails the same way on every requeue (#2583): park with file, line and fix.
+                    await clearCheckResume();
+                    const failure = check.failureSignature !== undefined
+                        ? { failureSignature: check.failureSignature, failingChecks: env.failingChecks }
+                        : undefined;
+                    return terminalParked('config', configParkMessage({
+                        issue: request.issue,
+                        failure: env,
+                        summary: check.summary,
+                        constitution,
+                        configFile: request.repoConfigFile,
+                    }), failure);
+                }
                 if (!request.localOnly) {
                     const [owner, repoName] = request.repo.split('/');
                     try {
@@ -575,13 +649,38 @@ export async function runIssue(request, policy, ports) {
                         log('environment_warning', `could not post the environment-failure comment: ${errorMessage(err)}`);
                     }
                 }
-                log('environment-released', `every failing checker (${env.failingChecks.join(', ')}) also fails on base ${env.baseSha.slice(0, 8)} — no rework, releasing #${request.issue} to queued`);
-                if (ports.planReuse && !plan.slice) {
+                let preserve = ports.checkResume !== undefined && !request.localOnly && !planSlice;
+                let fixTarget = '';
+                if (preserve && ports.checkResume) {
+                    fixTarget = preservedFixTarget(env, constitution, request.repoConfigFile);
+                    try {
+                        await ports.checkResume.record({
+                            issue: request.issue,
+                            branch: request.branch,
+                            worktree: ports.workspace.path,
+                            diffBase: buildDiffBase,
+                            route: builtRoute,
+                            model: builtModel,
+                            buildMinutes,
+                            fixTarget,
+                            preservedAt: new Date().toISOString(),
+                        });
+                    }
+                    catch (err) {
+                        log('environment_warning', `could not record the check-resume point: ${errorMessage(err)}`);
+                        preserve = false;
+                    }
+                }
+                log('environment-released', `every failing checker (${env.failingChecks.join(', ')}) also fails on base ${env.baseSha.slice(0, 8)} — no rework, releasing #${request.issue} to queued` +
+                    (preserve
+                        ? ` — ${formatPreservedBuildMessage({ issue: request.issue, branch: request.branch, buildMinutes, fixTarget })}`
+                        : ''));
+                if (ports.planReuse && !planSlice && !request.resumeFrom) {
                     try {
                         await ports.planReuse.record({
                             bodyHash: issueBodyHash(request.work.brief),
                             baseSha: env.baseSha,
-                            route: plan.route,
+                            route: planRoute,
                             releasedAt: new Date().toISOString(),
                         });
                     }
@@ -598,6 +697,7 @@ export async function runIssue(request, policy, ports) {
                     baseSha: env.baseSha,
                     failingChecks: env.failingChecks,
                     ...(check.failureSignature !== undefined ? { failureSignature: check.failureSignature } : {}),
+                    ...(preserve ? { buildPreserved: true } : {}),
                 };
             }
             const checkFailure = check.failureSignature !== undefined
@@ -619,8 +719,10 @@ export async function runIssue(request, policy, ports) {
             const parkedMessage = showstoppers.length > 0
                 ? `${message}\nremaining showstoppers:\n${showstoppers.map((s) => `- ${s}`).join('\n')}`
                 : message;
+            await clearCheckResume();
             return terminalParked(reason, parkedMessage, checkFailure);
         }
+        await clearCheckResume();
         // Clean check — clear stale cross-run history so a future, genuinely different
         // failure is not mistaken for a repeat of one already resolved.
         await ports.reworkHistory?.clear(request.issue);
@@ -648,7 +750,7 @@ export async function runIssue(request, policy, ports) {
         if (request.prClassifier) {
             reviewRouting = await resolveReviewRouting({
                 worktree: ports.workspace.path,
-                fallbackBaseRef: build.diffBase,
+                fallbackBaseRef: buildDiffBase,
                 rules: request.prClassifier.rules,
                 readChanges: ports.readReviewFloorChanges,
             });
@@ -672,7 +774,7 @@ export async function runIssue(request, policy, ports) {
             // decided, so it cannot change the label or merge routing.
             const shadowInput = {
                 worktree: ports.workspace.path,
-                fallbackBaseRef: build.diffBase,
+                fallbackBaseRef: buildDiffBase,
                 issueTitle: request.work.title,
                 issueBody: request.work.brief,
                 specPath: request.specPath,
@@ -728,7 +830,8 @@ export async function runIssue(request, policy, ports) {
             work: request.work,
             laneId: request.lane,
             reviewRouting,
-            slice: plan.slice ? { index: plan.slice.index, count: plan.slice.plan.slices.length } : undefined,
+            ...(pinNote ? { pinNotes: [pinNote] } : {}),
+            slice: planSlice ? { index: planSlice.index, count: planSlice.plan.slices.length } : undefined,
         });
         if (!ship.ok) {
             const reason = ship.denied ? 'escalate' : ship.ciOutcome === 'infra-failure' ? 'ci-infra' : 'fail';
@@ -739,8 +842,8 @@ export async function runIssue(request, policy, ports) {
                     : 'ship phase failed';
             return terminalParked(reason, message);
         }
-        if (plan.slice) {
-            const { index, plan: slicePlan } = plan.slice;
+        if (planSlice) {
+            const { index, plan: slicePlan } = planSlice;
             const count = slicePlan.slices.length;
             if (ship.prNumber === undefined) {
                 log('ship', `slice ${index}/${count} shipped with no PR number — slice plan not updated`);
@@ -752,9 +855,9 @@ export async function runIssue(request, policy, ports) {
                         octokit: ports.octokit,
                         repo: request.repo,
                         issue: request.issue,
-                        plan: withSliceState(slicePlan, index, state, ship.prNumber),
+                        plan: withSliceState(slicePlan, index, state, ship.prNumber, request.branch),
                     });
-                    log('ship', `recorded slice ${index}/${count} as ${state} (PR #${ship.prNumber}) in the slice plan comment`);
+                    log('ship', `recorded slice ${index}/${count} as ${state} (PR #${ship.prNumber}, branch ${request.branch}) in the slice plan comment`);
                 }
                 catch (err) {
                     return terminalParked('fail', `slice ${index}/${count} PR #${ship.prNumber} opened but recording it in the slice plan comment failed: ${errorMessage(err)}`);
@@ -767,7 +870,7 @@ export async function runIssue(request, policy, ports) {
         const readyMsg = ship.alreadyDelivered
             ? `already delivered${ship.prNumber !== undefined ? ` by merged PR #${ship.prNumber}` : ' — branch already landed on main'}`
             : `PR #${ship.prNumber} ready for review`;
-        log('ready', readyMsg);
+        log('ready', pinNote ? `${readyMsg} (${pinNote})` : readyMsg);
         await ports.writeLocalRunReport?.({ outcome: 'ready', route, branch: request.branch, reworkRounds });
         return {
             state: 'ready',
@@ -775,7 +878,7 @@ export async function runIssue(request, policy, ports) {
             branch: request.branch,
             reworkRounds,
             prNumber: ship.prNumber,
-            ...(plan.slice ? { slice: { index: plan.slice.index, count: plan.slice.plan.slices.length } } : {}),
+            ...(planSlice ? { slice: { index: planSlice.index, count: planSlice.plan.slices.length } } : {}),
         };
     }
     catch (err) {