@nexus-cortex/core 4.124.10 → 4.124.12

package/dist/orchestrator/CortexOrchestrator.js

@@ -23,6 +23,7 @@ import { resolveEndTurnResolverConfig, parseResolverVerdict, effectiveMaxRejects
 import { jevAvailable, jevNoul, buildGapHoldState, GAP_HOLD_QUESTIONS } from '../training/jevGate.js'; // R173b
 import { resolveFrameConfig, FRAME_CONTRACT, FRAME_TOOL_NAME } from '../frames/frameConfig.js'; // R179
 import { FrameRunner } from '../frames/frameRunner.js'; // R179
+import { parseRequirementLedger, initLedger, updateLedger, ledgerCounts, ledgerHoldable, formatLedgerForWriter, formatLedgerForJudge, formatLedgerHoldMessage, buildLedgerJevState, buildLedgerJevQuestions, applyLedgerJevAnswers } from '../training/requirementLedger.js'; // R187
 import { isValueShapedTask, parseDerivationReply, methodsDiffer, parseValueLines, extractNumbers, reconcile, buildDerivationHoldMessage, isDerivationCommandAllowed, checkRunPassed, checkRunBody } from '../training/independentDerivation.js'; // R176
 import { resolveDeadlineExitConfig, deadlineExitCallBudget, parseDeadlineExitVerdict } from '../training/deadlineExitMentor.js';
 import { isTaskShaped } from './requirementsVerification.js';
@@ -249,6 +250,10 @@ export class CortexOrchestrator {
     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)
+    reqLedger = null; // R187: the stated-requirement ledger for this turn (null = not yet authored)
+    reqLedgerPromise = null; // R187: authored at lift in the background
+    reqLedgerHolds = 0; // R187: ledger holds used this turn
+    reqLedgerMeta = { genLatencyMs: 0, raw: 0, refused: 0 }; // R187
     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)
@@ -542,6 +547,7 @@ export class CortexOrchestrator {
                     void store.recordEvent({
                         sessionId, kind: 'lift_plan', detail: { fired: true, planChars: 0, empty: true, ...r171, mentor: this.mentorWire('lift-plan', resolveLiftPlanConfig().effort, resolveLiftPlanConfig().outputBudgetTokens) },
                     }).catch(() => { });
+                await this.deliverRequirementLedgerToWriter(lastMsg); // R187: the ledger rides even when the plan is empty
                 return; // fail-open: proceed without a plan
             }
             const retire = /\bRETIRE\b/i.test(plan);
@@ -564,6 +570,7 @@ export class CortexOrchestrator {
             if (this.config.debug) {
                 console.log(`[LiftPlan] plan delivered at lift (${plan.length} chars, retire=${retire}, criteria=${criteriaStated})`);
             }
+            await this.deliverRequirementLedgerToWriter(lastMsg); // R187
         }
         catch (e) {
             if (store)
@@ -574,6 +581,26 @@ export class CortexOrchestrator {
                 console.warn(`[LiftPlan] delivery failed (continuing without): ${e?.message ?? e}`);
         }
     }
+    /** R187: append the requirement ledger to the lift observation the writer is about to see (waits for the lift-time authoring,
+     *  bounded by the resolver timeout; fail-open to nothing). One-shot per turn. */
+    reqLedgerDelivered = false;
+    async deliverRequirementLedgerToWriter(lastMsg) {
+        const cfg = resolveEndTurnResolverConfig();
+        if (!cfg.reqLedger || this.reqLedgerDelivered)
+            return;
+        this.reqLedgerDelivered = true;
+        try {
+            const entries = this.reqLedger ?? (this.reqLedgerPromise ? await withTimeout(this.reqLedgerPromise, mentorSurfaceTimeoutMs('endturn-resolver', parseInt(process.env.CORTEX_ENDTURN_RESOLVER_TIMEOUT_MS ?? '90000', 10))) : null);
+            const text = formatLedgerForWriter(entries ?? []);
+            if (!text)
+                return;
+            lastMsg?.message?.content?.push?.({ type: 'text', text: `<system-reminder>\n${text}\n</system-reminder>` });
+            const store = this.getDecisionStore();
+            if (store)
+                void store.recordEvent({ sessionId: this.currentSessionId ?? 'unknown', kind: 'requirement_ledger_delivered', toolName: 'EndTurn', detail: { lines: (entries ?? []).length, chars: text.length } }).catch(() => { });
+        }
+        catch { /* fail-open */ }
+    }
     /** Bounded read-only environment recon (ENV_RECON_COMMAND), gathered ONCE and cached — shared by the
      *  lift planner and the EndTurn resolver. Fail-open: partial stdout on timeout/non-zero, else empty. */
     gatherEnvReport(opts = {}) {
@@ -762,6 +789,47 @@ export class CortexOrchestrator {
         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;
     }
+    /** R187: author the requirement ledger (task text + env report ONLY). Sets reqLedger/reqLedgerMeta; never throws. */
+    async authorRequirementLedger(task) {
+        const cfg = resolveEndTurnResolverConfig();
+        const store = this.getDecisionStore();
+        const sessionId = this.currentSessionId ?? 'unknown';
+        const g0 = Date.now();
+        if (!this.helperMiddleware?.deriveRequirementLedger) {
+            this.reqLedger = [];
+            return [];
+        }
+        const tmo = mentorSurfaceTimeoutMs('endturn-resolver', parseInt(process.env.CORTEX_ENDTURN_RESOLVER_TIMEOUT_MS ?? '90000', 10));
+        try {
+            const raw = await withTimeout(this.helperMiddleware.deriveRequirementLedger({ task, envReport: this.gatherEnvReport({ fresh: false }), max: cfg.reqLedgerMax, helperModelId: this.config.reactiveMentorship?.helperModelId }), tmo);
+            const lines = parseRequirementLedger(raw ?? '', cfg.reqLedgerMax);
+            // a check that is not read-only is dropped (the line stays, unverifiable) — same denylist as every other harness-run check
+            let refused = 0;
+            const safe = lines.map((l) => (l.check && !isInvestigateCommandAllowed(l.check) ? (refused += 1, { ...l, check: null }) : l));
+            this.reqLedger = initLedger(safe);
+            this.reqLedgerMeta = { genLatencyMs: Date.now() - g0, raw: (raw ?? '').length, refused };
+        }
+        catch {
+            this.reqLedger = [];
+            this.reqLedgerMeta = { genLatencyMs: Date.now() - g0, raw: 0, refused: 0 };
+        }
+        if (store)
+            void store.recordEvent({ sessionId, kind: 'requirement_ledger', toolName: 'EndTurn', detail: { lines: this.reqLedger.map((e) => ({ id: e.id, kind: e.kind, text: e.text, check: e.check })), ...this.reqLedgerMeta, mentor: this.mentorWire('endturn-resolver', cfg.effort, 2000) } }).catch(() => { });
+        console.warn(`[EndTurnResolver] R187 REQUIREMENT LEDGER — ${this.reqLedger.length} line(s) (${this.reqLedger.filter((e) => e.check).length} with checks, ${this.reqLedgerMeta.refused} refused) in ${this.reqLedgerMeta.genLatencyMs} ms`);
+        return this.reqLedger;
+    }
+    /** R187: at lift, start authoring the ledger in the background (delivered to the writer by deliverLiftPlanAtLift when ready). */
+    maybeAuthorRequirementLedgerAtLift() {
+        const cfg = resolveEndTurnResolverConfig();
+        if (!cfg.reqLedger || this.reqLedger !== null || this.reqLedgerPromise)
+            return;
+        if (!resolveEndTurnResolver(process.env))
+            return;
+        const task = this.lastRealUserText();
+        if (!task.trim())
+            return;
+        this.reqLedgerPromise = this.authorRequirementLedger(task).catch(() => []);
+    }
     /** R174b: at lift, start authoring the spec checks in the background so a late first finish still has them. */
     maybeAuthorSpecChecksAtLift() {
         const cfg = resolveEndTurnResolverConfig();
@@ -872,8 +940,34 @@ export class CortexOrchestrator {
                     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)' : '');
                 }
             }
+            // R187 HB-REQUIREMENT-LEDGER: run each stated requirement's check; a FAILED line is R166 evidence; an OPEN line (never exercised) can hold once.
+            let reqResults = '';
+            let reqCounts = { lines: 0, open: 0, exercised: 0, failed: 0, unverifiable: 0 };
+            let reqJev = null;
+            if (cfg.reqLedger) {
+                if (this.reqLedger === null)
+                    this.reqLedger = await (this.reqLedgerPromise ?? this.authorRequirementLedger(task));
+                const runs = this.reqLedger.filter((e) => e.check).map((e) => { const r = runCheck(judgeCwd, e.check, jcfg); return { id: e.id, result: r, cls: classifyCheckRun(r) }; });
+                this.reqLedger = updateLedger(this.reqLedger, runs);
+                // R187b: Jev decides the lines the shell could not — typed per-line questions on the writer's attestation + harness evidence.
+                if (cfg.reqLedgerJev && jevAvailable() && this.reqLedger.some((e) => e.status === 'open' || e.status === 'unverifiable')) {
+                    const j0 = Date.now();
+                    try {
+                        const jr = await jevNoul(buildLedgerJevState({ task, entries: this.reqLedger, attestation, workProduct }), buildLedgerJevQuestions(this.reqLedger));
+                        const applied = applyLedgerJevAnswers(this.reqLedger, jr ? jr.probabilities : null, cfg.reqLedgerJevMin);
+                        this.reqLedger = applied.entries;
+                        reqJev = { asked: applied.asked, closed: applied.closed, latencyMs: Date.now() - j0 };
+                    }
+                    catch {
+                        reqJev = { asked: 0, closed: [], latencyMs: Date.now() - j0, error: true };
+                    }
+                }
+                reqCounts = ledgerCounts(this.reqLedger);
+                reqResults = formatLedgerForJudge(this.reqLedger);
+            }
             const combinedCheck = [checkResult, namedResults ? `JUDGE-NAMED CHECKS (from your previous fix plan; executed by the harness just now):\n${namedResults}` : '',
-                specResults ? `SPEC CHECKS (derived from the TASK text before any work was seen; executed by the harness just now — a FAILED one is a requirement not yet met):\n${specResults}` : ''] // R174
+                specResults ? `SPEC CHECKS (derived from the TASK text before any work was seen; executed by the harness just now — a FAILED one is a requirement not yet met):\n${specResults}` : '', // R174
+                reqResults] // R187
                 .filter(Boolean).join('\n\n');
             const callsSince = this.turnToolCallTotal - this.toolCallsAtLastVeto;
             const progressed = this.endTurnResolverRejects === 0 || callsSince >= cfg.progressMinCalls || namedPassed > this.judgePriorNamedPassed; // R166a: newly-passing checks, not any passing check
@@ -999,7 +1093,7 @@ 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
+            const checksFailed = namedFailed > 0 || specFailed > 0 || reqCounts.failed > 0; // R166 + R174 + R187
             // 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 });
@@ -1026,11 +1120,18 @@ export class CortexOrchestrator {
             // 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);
+            // R187: a finish that would otherwise stand while a STATED requirement is still OPEN (its check never passed nor failed — never
+            // exercised) is held once with the open lines named. Never below the budget floor; a FAILED line already went the R166 evidence way.
+            let reqHold = null;
+            if (cfg.reqLedger && this.reqLedger && action !== 'veto' && action !== 'escalate' && !belowFloor &&
+                ledgerHoldable({ open: reqCounts.open, holdsUsed: this.reqLedgerHolds, maxHolds: cfg.reqLedgerHoldMax, remainingFrac: resolverRemainingFrac, minRemaining: cfg.vetoMinRemaining })) {
+                reqHold = { message: formatLedgerHoldMessage({ entries: this.reqLedger, holdIndex: this.reqLedgerHolds + 1, maxHolds: cfg.reqLedgerHoldMax, remainingFrac: resolverRemainingFrac }) };
+            }
             // 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 &&
+            if (cfg.derivation === 'on' && !reqHold && 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 };
@@ -1098,6 +1199,7 @@ export class CortexOrchestrator {
                         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, holdGapMs: msSinceLastHold, planSim: Number(planSimilarity(this.judgePriorPlan, verdict.plan).toFixed(3)), msSinceLastHold, // R173c
                         derivation: cfg.derivation, derivationAgreement: derivationInfo?.agreement ?? null, derivationHeld: !!derivationHold, // R176
+                        reqLedger: cfg.reqLedger, reqLines: reqCounts.lines, reqOpen: reqCounts.open, reqExercised: reqCounts.exercised, reqFailed: reqCounts.failed, reqUnverifiable: reqCounts.unverifiable, reqHeld: !!reqHold, reqHolds: this.reqLedgerHolds, reqGenLatencyMs: this.reqLedgerMeta.genLatencyMs, reqJev: cfg.reqLedgerJev, reqJevAsked: reqJev?.asked ?? 0, reqJevClosed: reqJev?.closed ?? [], reqJevLatencyMs: reqJev?.latencyMs ?? 0, // R187/R187b
                         latencyMs, rawLen: (text ?? '').length,
                         deltaChars: workspaceDelta.length, checkRan: !!checkResult, checkPassed: checkResult ? /→ PASSED/.test(checkResult) : null,
                         liftPlanChars: this.liftPlanText.length,
@@ -1137,10 +1239,20 @@ export class CortexOrchestrator {
                         `${verdict.plan}\n\nDo this, verify against the task's own criteria (not your own tests), then call EndTurn again.` +
                         (namedResultsNow ? `\n\nHARNESS-RUN CHECKS (named by the reviewer, executed just now — the failing ones are the gap):\n${namedResultsNow.slice(0, 3000)}` : '') + // R166
                         (specFailed > 0 ? `\n\nSPEC CHECKS (derived from the TASK text before your work was seen, executed just now — a FAILED one is a stated requirement not yet met):\n${specResults.slice(0, 3000)}` : '') + // R174
+                        (reqCounts.failed > 0 ? `\n\nREQUIREMENT LEDGER (stated requirements, checked just now — a FAILED line is a stated requirement not yet met):\n${reqResults.slice(0, 3000)}` : '') + // R187
                         (holdable && !checksFailed ? `\n\nNo harness-run check failed, but the reviewer named open items and budget remains — this hold returns them to you (hold ${this.endTurnResolverRejects}/${resolverCap}).` : '') + // R173
                         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 (reqHold) {
+                // R187: the finish would stand, but a stated requirement was never exercised — hold once with the open lines named.
+                this.reqLedgerHolds += 1;
+                this.lastHoldMs = Date.now();
+                ev.endTurnCalled = false;
+                et.is_error = true;
+                et.content = reqHold.message;
+                console.warn(`[EndTurnResolver] R187 LEDGER-HOLD — finish held (${reqCounts.open} open of ${reqCounts.lines} stated requirements; hold ${this.reqLedgerHolds}/${cfg.reqLedgerHoldMax})`);
+            }
             else if (derivationHold) {
                 // R176: the finish would stand, but an independent recomputation disagrees — hold once with both values shown.
                 this.derivationHolds += 1;
@@ -1847,6 +1959,9 @@ export class CortexOrchestrator {
         if (toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.applyAnchorIfArmed(toolsToUse);
         }
+        // R179 engagement evidence: in the terminal frame the offered surface must be FrameAction (+EndTurn) — log it so a silent narrowing is visible.
+        if (frameCfg.frame === 'terminus')
+            console.log(`[Frame] tools offered (${toolsToUse?.length ?? 0}): ${(toolsToUse ?? []).map((t) => t.name).join(', ')}`);
         // StructuredOutput (grok-build port): when the caller requested
         // schema-constrained output, inject the request-scoped synthetic tool.
         // Appended AFTER server-side detection and the deferred filter so it can
@@ -2133,6 +2248,11 @@ export class CortexOrchestrator {
         this.specChecksMeta = { genLatencyMs: 0, refused: 0, raw: 0 };
         this.specChecksPromise = null;
         this.specFailHistory.clear();
+        this.reqLedger = null;
+        this.reqLedgerPromise = null;
+        this.reqLedgerHolds = 0;
+        this.reqLedgerMeta = { genLatencyMs: 0, raw: 0, refused: 0 };
+        this.reqLedgerDelivered = false;
         this.lastHoldMs = 0;
         this.derivationHolds = 0; // R165 per-turn / R174 / R173c / R176
         this.recordDsmlRecovery(currentAssistantCanonicalMessage);
@@ -3350,6 +3470,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.maybeAuthorRequirementLedgerAtLift(); // R187: the stated-requirement ledger, authored in the background at lift
                         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');
@@ -4160,6 +4281,9 @@ export class CortexOrchestrator {
         if (toolsToUse && toolsToUse.length > 0) {
             toolsToUse = this.applyAnchorIfArmed(toolsToUse);
         }
+        // R179 engagement evidence: in the terminal frame the offered surface must be FrameAction (+EndTurn) — log it so a silent narrowing is visible.
+        if (resolveFrameConfig(process.env).frame === 'terminus')
+            console.log(`[Frame] tools offered (${toolsToUse?.length ?? 0}): ${(toolsToUse ?? []).map((t) => t.name).join(', ')}`);
         // StructuredOutput (grok-build port) — streaming mirror of the sendMessage
         // injection: appended AFTER server-side detection and the deferred filter;
         // covers every request of the turn via the shared `toolsToUse` variable
@@ -4344,6 +4468,11 @@ export class CortexOrchestrator {
         this.specChecksMeta = { genLatencyMs: 0, refused: 0, raw: 0 };
         this.specChecksPromise = null;
         this.specFailHistory.clear();
+        this.reqLedger = null;
+        this.reqLedgerPromise = null;
+        this.reqLedgerHolds = 0;
+        this.reqLedgerMeta = { genLatencyMs: 0, raw: 0, refused: 0 };
+        this.reqLedgerDelivered = false;
         this.lastHoldMs = 0;
         this.derivationHolds = 0; // R165 per-turn / R174 / R173c / R176
         this.recordDsmlRecovery(currentAssistantCanonicalMessage);
@@ -5144,6 +5273,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.maybeAuthorRequirementLedgerAtLift(); // R187: the stated-requirement ledger, authored in the background at lift
                     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');
@@ -5823,7 +5953,7 @@ export class CortexOrchestrator {
                 recordEvent: (kind, detail) => { const st = this.getDecisionStore(); if (st)
                     void st.recordEvent({ sessionId: this.currentSessionId ?? 'unknown', kind: kind, toolName: FRAME_TOOL_NAME, detail }).catch(() => { }); },
                 jev: cfg.chooser === 'jev' && jevAvailable() ? async (state, questions) => { const r = await jevNoul(state, questions); return r ? r.probabilities : null; } : undefined,
-                author: cfg.author === 'helper' && this.helperMiddleware ? async (ctx) => this.helperMiddleware.generateFrameCandidates(ctx) : undefined, // R185
+                author: cfg.author === 'helper' && this.helperMiddleware ? async (ctx) => this.helperMiddleware.generateFrameCandidates({ ...ctx, ...(cfg.authorModel ? { helperModelId: cfg.authorModel } : {}) }) : undefined, // R185 (+R186 author model)
             });
         }
         return this.frameRunner;