@nexus-cortex/core 4.120.0 → 4.122.0

package/dist/orchestrator/CortexOrchestrator.js

@@ -19,8 +19,9 @@ import { join as pathJoin } from 'path';
 import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'fs';
 import { execSync } from 'node:child_process';
 import { ENV_RECON_COMMAND, resolveLiftPlanConfig, parsePlannerResponse } from '../training/liftPlanner.js';
-import { resolveEndTurnResolverConfig, parseResolverVerdict, effectiveMaxRejects, budgetedVetoEscalation, decideVetoAction, shouldFinishConfirm, buildFinishConfirmMessage, buildMeetsConfirmMessage, gapHoldable, parseSpecChecks } from '../training/endTurnResolver.js';
+import { resolveEndTurnResolverConfig, parseResolverVerdict, effectiveMaxRejects, budgetedVetoEscalation, decideVetoAction, shouldFinishConfirm, buildFinishConfirmMessage, buildMeetsConfirmMessage, gapHoldable, parseSpecChecks, applyVetoFloor, holdProgressed, specCheckEvidence } from '../training/endTurnResolver.js';
 import { jevAvailable, jevNoul, buildGapHoldState, GAP_HOLD_QUESTIONS } from '../training/jevGate.js'; // R173b
+import { isValueShapedTask, parseDerivationReply, methodsDiffer, parseValueLines, extractNumbers, reconcile, buildDerivationHoldMessage, isDerivationCommandAllowed } from '../training/independentDerivation.js'; // R176
 import { resolveDeadlineExitConfig, deadlineExitCallBudget, parseDeadlineExitVerdict } from '../training/deadlineExitMentor.js';
 import { isTaskShaped } from './requirementsVerification.js';
 import { extractServerSideMetadata, XAIServerSideTools, OpenAIServerSideTools, toCanonicalTool } from '../tools/ServerSideTools.js';
@@ -244,6 +245,10 @@ export class CortexOrchestrator {
     judgeAdjudicatedThisFinish = false;
     specChecks = null; // R174: blind spec-derived checks authored for this turn (null = not yet)
     specChecksMeta = { genLatencyMs: 0, refused: 0, raw: 0 }; // R174
+    specChecksPromise = null; // R174b: authored at lift in the background (CORTEX_JUDGE_SPEC_TESTS_AT=lift)
+    specFailHistory = new Map(); // R174b: consecutive identical spec failures
+    lastHoldMs = 0; // R173c: wall clock of the last hold/veto this turn
+    derivationHolds = 0; // R176: independent-derivation holds this turn (max 1)
     liftPlanText = ''; // 4.107.0: the PLAN OF ATTACK delivered at lift — handed to the resolver / deadline-exit / loop-exit judges as an advisory anchor
     effectiveDeferredLoading = true; // per-turn resolved deferred-loading (card > env > settings); set at assembly
     /**
@@ -713,6 +718,59 @@ export class CortexOrchestrator {
             }
         }
     }
+    /** R176: read the artifact the task names (the agent's deliverable) for reconciliation — direct, bounded, text only;
+     *  an absolute path outside the workspace is still the task's own file, so it is read rather than refused. */
+    readDeliverable(cwd, artifact, maxChars = 1500) {
+        try {
+            const abs = artifact.startsWith('/') ? artifact : `${cwd}/${artifact}`;
+            if (!existsSync(abs))
+                return `${artifact}: NOT FOUND`;
+            const text = readFileSync(abs, 'utf8');
+            return `${artifact}:\n${text.length > maxChars ? text.slice(0, maxChars) + '\n…' : text}`;
+        }
+        catch (e) {
+            return `${artifact}: unreadable (${String(e?.message ?? e).slice(0, 80)})`;
+        }
+    }
+    /** R174/R174b: author the blind spec checks (task text + env report ONLY). Sets specChecks/specChecksMeta; never throws. */
+    async authorSpecChecks(task) {
+        const cfg = resolveEndTurnResolverConfig();
+        const store = this.getDecisionStore();
+        const sessionId = this.currentSessionId ?? 'unknown';
+        const g0 = Date.now();
+        if (!this.helperMiddleware?.deriveSpecChecks) {
+            this.specChecks = [];
+            return [];
+        }
+        const specTimeoutMs = mentorSurfaceTimeoutMs('endturn-resolver', parseInt(process.env.CORTEX_ENDTURN_RESOLVER_TIMEOUT_MS ?? '90000', 10));
+        try {
+            const raw = await withTimeout(this.helperMiddleware.deriveSpecChecks({ task, envReport: this.gatherEnvReport({ fresh: false }), max: cfg.specTestsMax, helperModelId: this.config.reactiveMentorship?.helperModelId }), specTimeoutMs);
+            const parsed = parseSpecChecks(raw ?? '', cfg.specTestsMax);
+            const allowed = parsed.filter((c) => isInvestigateCommandAllowed(c));
+            this.specChecks = allowed;
+            this.specChecksMeta = { genLatencyMs: Date.now() - g0, refused: parsed.length - allowed.length, raw: (raw ?? '').length };
+        }
+        catch {
+            this.specChecks = [];
+            this.specChecksMeta = { genLatencyMs: Date.now() - g0, refused: 0, raw: 0 };
+        }
+        if (store)
+            void store.recordEvent({ sessionId, kind: 'spec_tests', toolName: 'EndTurn', detail: { checks: this.specChecks, ...this.specChecksMeta, at: cfg.specTestsAt, mentor: this.mentorWire('endturn-resolver', cfg.effort, 1200) } }).catch(() => { });
+        console.warn(`[EndTurnResolver] R174 SPEC-TESTS — ${this.specChecks.length} blind check(s) authored at ${cfg.specTestsAt} in ${this.specChecksMeta.genLatencyMs} ms (${this.specChecksMeta.refused} refused)`);
+        return this.specChecks;
+    }
+    /** R174b: at lift, start authoring the spec checks in the background so a late first finish still has them. */
+    maybeAuthorSpecChecksAtLift() {
+        const cfg = resolveEndTurnResolverConfig();
+        if (!cfg.specTests || cfg.specTestsAt !== 'lift' || this.specChecks !== null || this.specChecksPromise)
+            return;
+        if (!resolveEndTurnResolver(process.env))
+            return;
+        const task = this.lastRealUserText();
+        if (!task.trim())
+            return;
+        this.specChecksPromise = this.authorSpecChecks(task).catch(() => []);
+    }
     async adjudicateEndTurn(ev, toolResults, toolUses, model) {
         if (!resolveEndTurnResolver(process.env, model.endTurnResolver))
             return;
@@ -788,39 +846,27 @@ export class CortexOrchestrator {
             let specPassed = 0;
             let specFailed = 0;
             let specInconclusive = 0;
+            let specSuspect = 0;
             let specResults = '';
-            if (cfg.specTests && this.helperMiddleware.deriveSpecChecks) {
-                if (this.specChecks === null) {
-                    const g0 = Date.now();
-                    const specTimeoutMs = mentorSurfaceTimeoutMs('endturn-resolver', parseInt(process.env.CORTEX_ENDTURN_RESOLVER_TIMEOUT_MS ?? '90000', 10));
-                    try {
-                        const raw = await withTimeout(this.helperMiddleware.deriveSpecChecks({ task, envReport: this.gatherEnvReport({ fresh: false }), max: cfg.specTestsMax, helperModelId: this.config.reactiveMentorship?.helperModelId }), specTimeoutMs);
-                        const parsed = parseSpecChecks(raw ?? '', cfg.specTestsMax);
-                        const allowed = parsed.filter((c) => isInvestigateCommandAllowed(c));
-                        this.specChecks = allowed;
-                        this.specChecksMeta = { genLatencyMs: Date.now() - g0, refused: parsed.length - allowed.length, raw: (raw ?? '').length };
-                    }
-                    catch {
-                        this.specChecks = [];
-                        this.specChecksMeta = { genLatencyMs: Date.now() - g0, refused: 0, raw: 0 };
-                    }
-                    if (store)
-                        void store.recordEvent({ sessionId, kind: 'spec_tests', toolName: 'EndTurn', detail: { checks: this.specChecks, ...this.specChecksMeta, mentor: this.mentorWire('endturn-resolver', cfg.effort, 1200) } }).catch(() => { });
-                    console.warn(`[EndTurnResolver] R174 SPEC-TESTS — ${this.specChecks.length} blind check(s) authored in ${this.specChecksMeta.genLatencyMs} ms (${this.specChecksMeta.refused} refused)`);
-                }
-                for (const c of this.specChecks) {
-                    const r = runCheck(judgeCwd, c, jcfg);
+            if (cfg.specTests) {
+                if (this.specChecks === null)
+                    this.specChecks = await (this.specChecksPromise ?? this.authorSpecChecks(task)); // R174b: lift-authored or now
+                // R174b: two passes — classify every check, then apply repeat suppression (a check failing identically at
+                // specRepeatMax consecutive adjudications, while no OTHER check failed, is `suspect`: shown, not evidence).
+                const runs = this.specChecks.map((c) => { const r = runCheck(judgeCwd, c, jcfg); return { c, r, k: classifyCheckRun(r) }; });
+                const failedCmds = runs.filter((x) => x.k === 'failed').map((x) => x.c);
+                for (const x of runs) {
+                    const ev = specCheckEvidence(this.specFailHistory, x.c, x.r, x.k, cfg.specRepeatMax, failedCmds.some((f) => f !== x.c));
                     specRan += 1;
-                    {
-                        const k = classifyCheckRun(r);
-                        if (k === 'passed')
-                            specPassed += 1;
-                        else if (k === 'failed')
-                            specFailed += 1;
-                        else
-                            specInconclusive += 1;
-                    }
-                    specResults += (specResults ? '\n\n' : '') + r;
+                    if (ev === 'passed')
+                        specPassed += 1;
+                    else if (ev === 'failed')
+                        specFailed += 1;
+                    else if (ev === 'suspect')
+                        specSuspect += 1;
+                    else
+                        specInconclusive += 1;
+                    specResults += (specResults ? '\n\n' : '') + x.r + (ev === 'suspect' ? '\n(this check has failed identically at consecutive finishes while everything else passed — treat it as SUSPECT, not as proof of a gap)' : '');
                 }
             }
             const combinedCheck = [checkResult, namedResults ? `JUDGE-NAMED CHECKS (from your previous fix plan; executed by the harness just now):\n${namedResults}` : '',
@@ -951,8 +997,12 @@ export class CortexOrchestrator {
             }
             const holdable = gapHoldable({ gapHold: cfg.gapHold, remainingFrac: resolverRemainingFrac, minRemaining: resolveBudgetContinueMinRemaining(), planChars: verdict.plan.length, jevMode: cfg.gapHoldJev, jevFixable, jevMin: cfg.gapHoldJevMin });
             const checksFailed = namedFailed > 0 || specFailed > 0; // R166 + R174
+            // R173c: a re-hold needs real work since the last hold (elapsed time or a changed open-items list), not just tool calls.
+            const msSinceLastHold = this.lastHoldMs > 0 ? Date.now() - this.lastHoldMs : null;
+            const holdProg = holdProgressed({ rejects: this.endTurnResolverRejects, msSinceLastHold, priorPlan: this.judgePriorPlan, plan: verdict.plan, minIntervalMs: cfg.gapHoldMinIntervalMs, maxSimilarity: cfg.gapHoldPlanMaxSimilarity });
+            const progressedForHold = holdable ? (progressed && holdProg) : progressed;
             let action = cfg.semantic
-                ? decideVetoAction({ meets: verdict.meets, blank: verdict.blank, retire: verdict.retire && cfg.abstain, confidence: verdict.confidence, rejects: this.endTurnResolverRejects, cap: resolverCap, progressed, escalated: this.judgeEscalated, checksFailed, vetoMode: cfg.vetoMode, evidenceCap: cfg.evidenceCap, gapHoldable: holdable })
+                ? decideVetoAction({ meets: verdict.meets, blank: verdict.blank, retire: verdict.retire && cfg.abstain, confidence: verdict.confidence, rejects: this.endTurnResolverRejects, cap: resolverCap, progressed: progressedForHold, escalated: this.judgeEscalated, checksFailed, vetoMode: cfg.vetoMode, evidenceCap: cfg.evidenceCap, gapHoldable: holdable })
                 : (verdict.blank || (verdict.retire && cfg.abstain) || verdict.meets || !verdict.plan ? 'accept' : 'veto');
             if (action === 'escalate') {
                 // R165: the junior re-attested without working the plan — one thinking-on adjudication before we accept with the gap recorded.
@@ -966,10 +1016,60 @@ export class CortexOrchestrator {
                         verdict = v2;
                     }
                 }
-                action = decideVetoAction({ meets: verdict.meets, blank: verdict.blank, retire: verdict.retire && cfg.abstain, confidence: verdict.confidence, rejects: this.endTurnResolverRejects, cap: resolverCap, progressed, escalated: true, checksFailed, vetoMode: cfg.vetoMode, evidenceCap: cfg.evidenceCap, gapHoldable: holdable });
+                action = decideVetoAction({ meets: verdict.meets, blank: verdict.blank, retire: verdict.retire && cfg.abstain, confidence: verdict.confidence, rejects: this.endTurnResolverRejects, cap: resolverCap, progressed: progressedForHold, escalated: true, checksFailed, vetoMode: cfg.vetoMode, evidenceCap: cfg.evidenceCap, gapHoldable: holdable });
                 if (action === 'escalate')
                     action = 'accept-with-gap';
             }
+            // R173c: the budget floor — below CORTEX_JUDGE_VETO_MIN_REMAINING nothing holds the finish (the gap is recorded).
+            const belowFloor = cfg.vetoMinRemaining > 0 && resolverRemainingFrac !== null && resolverRemainingFrac < cfg.vetoMinRemaining && action === 'veto';
+            action = applyVetoFloor(action, resolverRemainingFrac, cfg.vetoMinRemaining);
+            // R176 HB-INDEPENDENT-DERIVATION: on a value-shaped task, before a finish that would otherwise STAND, recompute the result by a
+            // different method and hold ONCE on disagreement. Never below the budget floor; never more than once per turn.
+            let derivationHold = null;
+            let derivationInfo = null;
+            if (cfg.derivation === 'on' && action !== 'veto' && action !== 'escalate' && this.derivationHolds < 1 && !belowFloor &&
+                !(cfg.vetoMinRemaining > 0 && resolverRemainingFrac !== null && resolverRemainingFrac < cfg.vetoMinRemaining) && this.helperMiddleware.deriveIndependentCheck) {
+                const shape = isValueShapedTask(task);
+                derivationInfo = { valueShaped: shape.valueShaped, reason: shape.reason, artifacts: shape.artifacts };
+                if (shape.valueShaped) {
+                    const d0 = Date.now();
+                    try {
+                        const deliverable = shape.artifacts.map((a) => this.readDeliverable(judgeCwd, a)).join('\n\n');
+                        const raw = await withTimeout(this.helperMiddleware.deriveIndependentCheck({ task, deliverable: `${deliverable}\n\nAGENT FINAL MESSAGE:\n${this.lastAssistantText().slice(0, 2000)}`, agentSummary: attestation, envReport: this.gatherEnvReport({ fresh: false }), values: [], helperModelId: this.config.reactiveMentorship?.helperModelId }), timeoutMs);
+                        const plan = parseDerivationReply(raw ?? '', 3);
+                        const allowed = plan.checks.filter((c) => isDerivationCommandAllowed(c, isInvestigateCommandAllowed));
+                        const refusedCmds = plan.checks.filter((c) => !allowed.includes(c)).map((c) => c.slice(0, 200));
+                        const derived = {};
+                        const outputs = [];
+                        for (const c of allowed) {
+                            const r = runCheck(judgeCwd, c, jcfg);
+                            outputs.push(r);
+                            Object.assign(derived, parseValueLines(r));
+                        }
+                        // Fallback when the author printed values without the `VALUE name=` contract: take the LAST few numbers each check printed
+                        // and require that at least one matches the deliverable — conservative (a disagreement needs every printed number to miss).
+                        let fallback = false;
+                        if (!Object.keys(derived).length && outputs.length) {
+                            const tail = outputs.flatMap((o) => extractNumbers(o.split('\n').slice(1).join('\n')).slice(-3));
+                            tail.slice(-6).forEach((v, i) => { derived[`printed${i + 1}`] = String(v); });
+                            fallback = tail.length > 0;
+                        }
+                        let rec = reconcile(`${deliverable}\n${this.lastAssistantText()}`, derived, cfg.derivationTol);
+                        if (fallback && rec.compared.some((c) => c.matched !== null))
+                            rec = { ...rec, agreement: 'agree' };
+                        const differ = methodsDiffer(plan.methodAgent, plan.methodIndependent);
+                        derivationInfo = { ...derivationInfo, methodAgent: plan.methodAgent, methodIndependent: plan.methodIndependent, methodsDiffer: differ, checks: allowed.length, refused: refusedCmds.length, refusedCmds, fallback, checkOutputs: outputs.map((o) => o.slice(0, 600)), derived, agreement: rec.agreement, compared: rec.compared, latencyMs: Date.now() - d0 };
+                        if (rec.agreement === 'disagree' && differ)
+                            derivationHold = { message: buildDerivationHoldMessage({ methodIndependent: plan.methodIndependent, compared: rec.compared, remainingFrac: resolverRemainingFrac }) };
+                        console.warn(`[EndTurnResolver] R176 DERIVATION — ${rec.agreement} (${allowed.length} check(s), methodsDiffer=${differ}) in ${Date.now() - d0} ms`);
+                    }
+                    catch (e) {
+                        derivationInfo = { ...derivationInfo, error: String(e?.message ?? e).slice(0, 120) };
+                    }
+                }
+                if (store)
+                    void store.recordEvent({ sessionId, kind: 'independent_derivation', toolName: 'EndTurn', detail: { ...derivationInfo, held: !!derivationHold, remainingFrac: resolverRemainingFrac } }).catch(() => { });
+            }
             this.judgeAdjudicatedThisFinish = verdict.parsed;
             const latencyMs = Date.now() - t0;
             // OBSERVABILITY (resolver-AB follow-up, 2026-09-05): bank the TEXT the resolver produced +
@@ -990,7 +1090,9 @@ export class CortexOrchestrator {
                         vetoMode: cfg.vetoMode, evidenceCap: cfg.evidenceCap, namedRanNow, namedInconclusive, // R166 / R166b
                         toolRounds: cfg.toolRounds, roundsUsed, investigateChecks, investigateReads, investigateRefused, autoLooped, toolAutoLoop: cfg.toolAutoLoop, roundLatencyMs, evidenceChars: evidenceRounds.join('').length, // R170 / R170b
                         gapHold: cfg.gapHold, gapHoldable: holdable, jevMode: cfg.gapHoldJev, jevFixable, jevLatencyMs, // R173 / R173b
-                        specTests: cfg.specTests, specChecks: this.specChecks?.length ?? 0, specRan, specPassed, specFailed, specInconclusive, specGenLatencyMs: this.specChecksMeta.genLatencyMs, // R174
+                        specTests: cfg.specTests, specChecks: this.specChecks?.length ?? 0, specRan, specPassed, specFailed, specInconclusive, specSuspect, specGenLatencyMs: this.specChecksMeta.genLatencyMs, specTestsAt: cfg.specTestsAt, // R174 / R174b
+                        vetoMinRemaining: cfg.vetoMinRemaining, belowFloor, holdProgressed: holdProg, msSinceLastHold, // R173c
+                        derivation: cfg.derivation, derivationAgreement: derivationInfo?.agreement ?? null, derivationHeld: !!derivationHold, // R176
                         latencyMs, rawLen: (text ?? '').length,
                         deltaChars: workspaceDelta.length, checkRan: !!checkResult, checkPassed: checkResult ? /→ PASSED/.test(checkResult) : null,
                         liftPlanChars: this.liftPlanText.length,
@@ -1016,6 +1118,7 @@ export class CortexOrchestrator {
             }
             else if (action === 'veto') {
                 this.endTurnResolverRejects += 1;
+                this.lastHoldMs = Date.now(); // R173c
                 ev.endTurnCalled = false; // VETO the finish
                 if (cfg.semantic) {
                     this.judgeNamedChecks = verdict.checks;
@@ -1033,6 +1136,15 @@ export class CortexOrchestrator {
                         budgetedVetoEscalation(this.endTurnResolverRejects, resolverCap, resolverRemainingMs ?? 0, this.turnDeadlineMsActive); // R160
                 console.warn(`[EndTurnResolver] GAP — vetoed finish (${verdict.plan.length}-char plan, reject ${this.endTurnResolverRejects}/${resolverCap}${resolverRemainingFrac === null ? '' : `, budget remaining ${Math.round(resolverRemainingFrac * 100)}%`})`);
             }
+            else if (derivationHold) {
+                // R176: the finish would stand, but an independent recomputation disagrees — hold once with both values shown.
+                this.derivationHolds += 1;
+                this.lastHoldMs = Date.now();
+                ev.endTurnCalled = false;
+                et.is_error = true;
+                et.content = derivationHold.message;
+                console.warn(`[EndTurnResolver] R176 DERIVATION-HOLD — finish held once on a disagreeing independent recomputation`);
+            }
             else if ((action === 'accept-with-gap' || action === 'accept-low-confidence') &&
                 shouldFinishConfirm({ action, remainingFrac: resolverRemainingFrac, confirmsUsed: this.finishConfirms, cfg })) {
                 // R167 HB-FINISH-CONFIRM: the judge would accept with a gap and budget remains — hold ONCE with an informed
@@ -2010,7 +2122,11 @@ export class CortexOrchestrator {
         this.judgeEscalated = false;
         this.judgeAdjudicatedThisFinish = false;
         this.specChecks = null;
-        this.specChecksMeta = { genLatencyMs: 0, refused: 0, raw: 0 }; // R165 per-turn / R174
+        this.specChecksMeta = { genLatencyMs: 0, refused: 0, raw: 0 };
+        this.specChecksPromise = null;
+        this.specFailHistory.clear();
+        this.lastHoldMs = 0;
+        this.derivationHolds = 0; // R165 per-turn / R174 / R173c / R176
         this.recordDsmlRecovery(currentAssistantCanonicalMessage);
         let toolCallIteration = 0;
         // R137 HB-POLL-REPEAT-BREAKER: the exact-repeat breaker used to force-exit by overwriting
@@ -3226,6 +3342,7 @@ export class CortexOrchestrator {
                         await this.deliverDeferredCorpusAtLift(effectiveModel);
                         this.deliverLiftNudge(allTools, effectiveModel); // A′ proposal-1: SearchTools/AskForAdvice signpost at lift
                         await this.deliverLiftPlanAtLift(effectiveModel); // LIFT_MENTOR_PLANNER: bounded mentor-planner at lift (dark unless CORTEX_LIFT_PLAN)
+                        this.maybeAuthorSpecChecksAtLift(); // R174b: blind spec checks authored in the background at lift (CORTEX_JUDGE_SPEC_TESTS_AT=lift)
                         if (this.config.debug)
                             console.log('[Anchor] lifted at first tool_result boundary — session profile applies');
                     }
@@ -4215,7 +4332,11 @@ export class CortexOrchestrator {
         this.judgeEscalated = false;
         this.judgeAdjudicatedThisFinish = false;
         this.specChecks = null;
-        this.specChecksMeta = { genLatencyMs: 0, refused: 0, raw: 0 }; // R165 per-turn / R174
+        this.specChecksMeta = { genLatencyMs: 0, refused: 0, raw: 0 };
+        this.specChecksPromise = null;
+        this.specFailHistory.clear();
+        this.lastHoldMs = 0;
+        this.derivationHolds = 0; // R165 per-turn / R174 / R173c / R176
         this.recordDsmlRecovery(currentAssistantCanonicalMessage);
         const assistantMessageId = currentAssistantCanonicalMessage.uuid;
         const assistantMessage = {
@@ -5014,6 +5135,7 @@ export class CortexOrchestrator {
                     await this.deliverDeferredCorpusAtLift(effectiveModel);
                     this.deliverLiftNudge(allTools, effectiveModel); // A′ proposal-1: SearchTools/AskForAdvice signpost at lift
                     await this.deliverLiftPlanAtLift(effectiveModel); // LIFT_MENTOR_PLANNER: bounded mentor-planner at lift (dark unless CORTEX_LIFT_PLAN)
+                    this.maybeAuthorSpecChecksAtLift(); // R174b: blind spec checks authored in the background at lift (CORTEX_JUDGE_SPEC_TESTS_AT=lift)
                     if (this.config.debug)
                         console.log('[Anchor] lifted at first tool_result boundary — session profile applies');
                 }