@nexus-cortex/core 4.69.1 → 4.71.0

package/dist/orchestrator/CortexOrchestrator.js

@@ -30,11 +30,17 @@ import { CacheMetricsAccumulator } from '../session/CacheMetricsAccumulator.js';
 import { SubAgentProcessManager, createSubAgentProcessManager } from './SubAgentProcessManager.js';
 // Phase 1: Tool Architecture Refactor - Unified Tool Registry
 import { toolFactory } from '../tools/ToolFactory.js';
-import { resolveToolProfile, resolveToolAnchor, isNarrowProfile, isToolAllowedByProfile, applyToolProfile } from '../tools/ToolProfile.js';
+import { resolveToolProfile, resolveToolAnchor, resolveFrameProfile, isNarrowProfile, isToolAllowedByProfile, applyToolProfile } from '../tools/ToolProfile.js';
 import { slashCommandRegistry } from '../commands/SlashCommandRegistry.js';
 import { prefixMcpToolName, parseMcpToolName } from '../mcp/mcpToolNamespacing.js';
-import { DecisionStore, stableInputHash } from '../training/DecisionStore.js';
-import { formatPriorReminder } from '../training/DecisionPriorInjector.js';
+import { DecisionStore } from '../training/DecisionStore.js';
+import { formatPriorReminder, formatFamilyReminder } from '../training/DecisionPriorInjector.js';
+import { classifyErrorFamily } from '../training/errorFamily.js';
+import { classifyToolOutcome } from '../training/toolOutcome.js';
+import { LoopLadder, formatLadderSignal } from '../training/loopLadder.js';
+import { shouldNudgeInaction, formatInactionNudge } from './inactionGuard.js';
+import { applyImageTtlForRequest } from './imageTtl.js';
+import { verifyRequirements, resolveEndTurnRequirementsMode } from './requirementsVerification.js';
 import { ModelRouterMatrix } from '../training/ModelRouterMatrix.js';
 import { classifyTask } from '../training/TaskClassifier.js';
 import { closestToolMatches } from './toolNameMatcher.js';
@@ -143,6 +149,10 @@ export class CortexOrchestrator {
     /** The active model card's anchorProfile (captured at request assembly) —
      *  env CORTEX_TOOL_ANCHOR still overrides inside resolveToolAnchor. */
     cardAnchorProfile = null;
+    /** Card frameProfile ('lifted'|'persist') captured with the anchor — under
+     *  'persist' the anchor never lifts (backlog item 5; env
+     *  CORTEX_TOOL_ANCHOR_PERSIST overrides in resolveFrameProfile). */
+    cardFrameProfile = null;
     /** P6 deferral (CORTEX_PROMPT_MASS=defer): the static corpus is delivered
      *  exactly once, at the anchor-lift boundary. One-shot per orchestrator. */
     deferredCorpusDelivered = false;
@@ -316,8 +326,10 @@ export class CortexOrchestrator {
                     // deferred setup tools are actually findable.
                     const extras = [...this.getMcpManagementTools(), ...this.getContextManagementTools()];
                     const seen = new Set();
+                    const catalogVision = this.getModel(this.currentModelId ?? '')?.vision === true;
                     return [...toolFactory.getAllTools(), ...extras]
                         .filter((t) => endTurnGateOn || t.name !== 'EndTurn')
+                        .filter((t) => catalogVision || t.name !== 'ReadImage')
                         .filter((t) => (seen.has(t.name) ? false : (seen.add(t.name), true)))
                         .map((t) => ({
                         name: namingHandler.convertName(t.name, convention),
@@ -446,9 +458,12 @@ export class CortexOrchestrator {
         const model = this.getModel(modelId);
         // Phase 1 & Phase 2: Get tools (used for both injection context and API request)
         const endTurnGateOn = (process.env.CORTEX_ENDTURN_GATE) === 'true';
-        const factoryTools = this.applyBaseToolAllowlist(endTurnGateOn
-            ? toolFactory.getAllTools()
-            : toolFactory.getAllTools().filter(t => t.name !== 'EndTurn'));
+        // Vision gate (item 7): ReadImage is offered ONLY to probe-verified vision
+        // cards — a text-only model must never see or reach the image path.
+        const visionOn = model?.vision === true;
+        const factoryTools = this.applyBaseToolAllowlist(toolFactory.getAllTools()
+            .filter(t => endTurnGateOn || t.name !== 'EndTurn')
+            .filter(t => visionOn || t.name !== 'ReadImage'));
         // Tool-profile: MCP/management/context tools bypass ToolFactory, so the
         // bash-only arm must suppress them here or the surface leaks (lean keeps
         // them — they are part of the "guided" surface under test).
@@ -699,6 +714,7 @@ export class CortexOrchestrator {
         // Card-level home door: capture the active card's anchorProfile (env
         // CORTEX_TOOL_ANCHOR overrides inside the resolver; env 'none' disables).
         this.cardAnchorProfile = effectiveModel.anchorProfile ?? null;
+        this.cardFrameProfile = effectiveModel.frameProfile ?? null;
         // Thread the CARD's anchor to the executors (per-orchestrator config, by
         // reference) so framing-aware executor behavior (ShellTool steering
         // default) is model-card/registry-scoped, not process-global env.
@@ -978,6 +994,9 @@ export class CortexOrchestrator {
         // Round 18b: track whether we've already retried on empty response so
         // we don't loop forever. See empty-detection block below.
         let emptyResponseRetryUsed = false;
+        // Inaction guard (backlog item 2 — the ladder's inverse): single-nudge
+        // bound for the actless-verbose retry. Default OFF via env.
+        let inactionNudgeUsed = false;
         // EndTurn gate (Stage 1): the turn must not complete until the model
         // calls the EndTurn attestation tool. Steering is ignored by some
         // models (grok-4.3); a required tool call is not. Bounded so a model
@@ -1021,6 +1040,13 @@ export class CortexOrchestrator {
         const thisTurnToolOutputs = [];
         // Loop detection: Track recent tool calls to detect repetitive loops
         const recentToolCalls = [];
+        // Unified Outcome Ladder (docs/UNIFIED_OUTCOME_LADDER.md): per-approach
+        // FAILURE escalation — remind(2)→diversify(4)→break(6) over normalized
+        // near-duplicate approaches. Complements isToolProgressStalled (which is
+        // outcome-blind exact-hash cycling) by firing earlier on failing thrash.
+        const loopLadder = new LoopLadder();
+        let ladderBreak = null;
+        let ladderSignal = null;
         // Track all tool uses across iterations for response
         const allExecutedToolUses = [];
         // Track tool call counts for diversity warning
@@ -1198,6 +1224,130 @@ export class CortexOrchestrator {
                             continue;
                         }
                     }
+                    // Inaction guard (backlog item 2 — the loop ladder's inverse).
+                    // TB2 2×2: persist-frame arms produced never-acted failures (5
+                    // pro-persist) — a huge reason-to-the-wall text dump with ZERO tool
+                    // calls, invisible to every call-counting guard. One bounded
+                    // steering retry, R18b-style; default OFF (CORTEX_INACTION_NUDGE).
+                    {
+                        const responseChars = Array.isArray(currentAssistantCanonicalMessage.content)
+                            ? currentAssistantCanonicalMessage.content
+                                .map((b) => b?.type === 'text' ? (b.text || '') : b?.type === 'thinking' ? (b.thinking || '') : '')
+                                .join('').length
+                            : String(currentAssistantCanonicalMessage.content ?? '').length;
+                        if (hasVisibleText &&
+                            !structuredOutputState?.result &&
+                            shouldNudgeInaction({
+                                responseChars,
+                                toolUseBlocksThisResponse: 0,
+                                executedToolCallsThisTurn: allExecutedToolUses.length,
+                                toolsOffered: toolsToUse.length,
+                                turnNumber: this.turnNumber,
+                                alreadyNudged: inactionNudgeUsed,
+                            })) {
+                            inactionNudgeUsed = true;
+                            console.warn(`[Orchestrator] Inaction guard: actless-verbose response (${responseChars} chars, 0 tool calls). ` +
+                                `Injecting act-first nudge (single retry).`);
+                            // Observability (backlog item 3): bank the event either way it
+                            // resolves — the distiller counts nudge→acted conversions.
+                            {
+                                const store = this.getDecisionStore();
+                                if (store) {
+                                    void store
+                                        .recordEvent({
+                                        sessionId: this.currentSessionId ?? 'unknown',
+                                        kind: 'inaction_nudge',
+                                        detail: { responseChars, turnNumber: this.turnNumber },
+                                    })
+                                        .catch(() => { });
+                                }
+                            }
+                            const inactionUserMessage = {
+                                uuid: uuidv4(),
+                                timestamp: new Date().toISOString(),
+                                type: 'user',
+                                message: {
+                                    role: 'user',
+                                    content: [{
+                                            type: 'text',
+                                            text: `<system-reminder>${formatInactionNudge()}</system-reminder>`,
+                                        }],
+                                },
+                                timeline: {
+                                    sessionId: this.currentSessionId,
+                                    conversationId: this.currentConversationId,
+                                    turnNumber: this.turnNumber + 1,
+                                },
+                                model: {
+                                    id: effectiveModel.id,
+                                    provider: effectiveModel.provider,
+                                    apiPattern: effectiveModel.api.pattern,
+                                },
+                            };
+                            this.messageHistory.push(inactionUserMessage);
+                            await this.historyStore.appendMessage(this.currentSessionId, inactionUserMessage);
+                            await this.ensureHistoryFitsModel(effectiveModel);
+                            const inactionCanonicalHistory = this.convertToCanonicalMessages([...this.messageHistory]);
+                            const inactionRequest = this.gatewayTranslation.prepareRequest(inactionCanonicalHistory, toolsToUse, effectiveModel, {
+                                temperature: options.parameters?.temperature,
+                                maxTokens: options.parameters?.maxTokens,
+                                topP: options.parameters?.topP,
+                                reasoningEffort: options.parameters?.reasoningEffort,
+                                stream: options.streaming,
+                                staticSystemPrompt: this.currentStaticSystemPrompt, // R28
+                                conversationId: this.currentConversationId, // R28b
+                            });
+                            if (this.lastResponseId && effectiveModel.api.pattern === 'responses') {
+                                inactionRequest.previousResponseId = this.lastResponseId;
+                            }
+                            inactionRequest.conversationId = this.currentSessionId;
+                            let inactionApiResponse;
+                            if (this.retryMiddleware) {
+                                const r = await this.retryMiddleware.executeWithRetry(() => this.apiClient.sendRequest(inactionRequest, effectiveModel), 'inaction_nudge_retry');
+                                inactionApiResponse = r.result;
+                            }
+                            else {
+                                inactionApiResponse = await this.apiClient.sendRequest(inactionRequest, effectiveModel);
+                            }
+                            const inactionConverted = this.gatewayTranslation.convertResponse(inactionApiResponse.data, effectiveModel, {
+                                sessionId: this.currentSessionId,
+                                conversationId: this.currentConversationId,
+                                turnNumber: this.turnNumber + 1,
+                            });
+                            if (effectiveModel.api.pattern === 'responses' && inactionApiResponse.data?.id) {
+                                this.lastResponseId = inactionApiResponse.data.id;
+                                this.lastResponseIdProvider = effectiveModel.provider; // R20a
+                            }
+                            if (inactionConverted.messages && inactionConverted.messages.length > 0) {
+                                const inactionAssistantCanonical = inactionConverted.messages[0];
+                                const inactionAssistantMessage = {
+                                    uuid: inactionAssistantCanonical.uuid,
+                                    timestamp: inactionAssistantCanonical.timestamp,
+                                    type: 'assistant',
+                                    message: {
+                                        role: 'assistant',
+                                        content: inactionAssistantCanonical.content,
+                                    },
+                                    timeline: {
+                                        sessionId: this.currentSessionId,
+                                        conversationId: this.currentConversationId,
+                                        turnNumber: this.turnNumber + 1,
+                                    },
+                                    model: {
+                                        id: effectiveModel.id,
+                                        provider: effectiveModel.provider,
+                                        apiPattern: effectiveModel.api.pattern,
+                                    },
+                                    ...(inactionConverted.usage && { usage: inactionConverted.usage }),
+                                };
+                                this.messageHistory.push(inactionAssistantMessage);
+                                await this.historyStore.appendMessage(this.currentSessionId, inactionAssistantMessage);
+                                currentAssistantMessage = inactionAssistantMessage;
+                                currentAssistantCanonicalMessage = inactionAssistantCanonical;
+                                continue;
+                            }
+                        }
+                    }
                     // EndTurn gate (Stage 1): refuse to finalize until the model has
                     // called the EndTurn attestation tool. Only arms when the turn
                     // actually used a (non-EndTurn) tool — pure-language turns bypass.
@@ -1221,8 +1371,27 @@ export class CortexOrchestrator {
                         if (!cv.ok)
                             stage3Violations = cv.violations;
                     }
-                    if (endTurnGateEnabled && turnUsedTools && endTurnNudges < END_TURN_MAX_NUDGES &&
-                        (!endTurnCalled || stage3Violations.length > 0)) {
+                    // Fallback observability (backlog item 1.4): when the nudge bound
+                    // is exhausted and the gate is STILL unsatisfied, the turn ships
+                    // anyway (liveness beats purity) — but that fallback-accept was
+                    // previously silent. Bank an event so the distiller can see
+                    // un-attested passes.
+                    const endTurnGateUnsatisfied = endTurnGateEnabled && turnUsedTools && (!endTurnCalled || stage3Violations.length > 0);
+                    if (endTurnGateUnsatisfied && endTurnNudges >= END_TURN_MAX_NUDGES) {
+                        const fallbackReason = !endTurnCalled ? 'missing-EndTurn' : 'coordinate-violation';
+                        console.warn(`[Orchestrator] EndTurn gate FALLBACK-ACCEPT: ${fallbackReason} after ${endTurnNudges} nudges — turn ships un-attested.`);
+                        const store = this.getDecisionStore();
+                        if (store) {
+                            void store
+                                .recordEvent({
+                                sessionId: this.currentSessionId ?? 'unknown',
+                                kind: 'endturn_gate_fallback',
+                                detail: { reason: fallbackReason, nudges: endTurnNudges, iteration: toolCallIteration },
+                            })
+                                .catch(() => { });
+                        }
+                    }
+                    if (endTurnGateUnsatisfied && endTurnNudges < END_TURN_MAX_NUDGES) {
                         endTurnNudges++;
                         const gateReason = !endTurnCalled ? 'missing-EndTurn' : 'coordinate-violation';
                         console.warn(`[Orchestrator] EndTurn gate: ${gateReason} ` +
@@ -1498,6 +1667,49 @@ export class CortexOrchestrator {
                 try {
                     const toolResults = await this.handleToolCalls(toolUseBlocks, abortController.signal, structuredOutputState);
                     clearTimeout(timeoutId);
+                    // Unified Outcome Ladder: observe each result's TRUE outcome (exit
+                    // codes, not wire is_error) and escalate on repeated failing
+                    // approaches. The strongest signal this batch is injected at the
+                    // signals block below; a 'break' rung ends the loop R29b-style.
+                    ladderSignal = null;
+                    {
+                        const inputById = new Map(toolUseBlocks.map((b) => [b.id, b.input]));
+                        for (const tr of toolResults) {
+                            if (tr.tool_name === 'EndTurn')
+                                continue;
+                            const input = inputById.get(tr.tool_use_id);
+                            if (input === undefined)
+                                continue;
+                            const outcome = classifyToolOutcome(tr.tool_name, input, tr);
+                            const ladder = loopLadder.observe(tr.tool_name, outcome);
+                            const sig = formatLadderSignal(tr.tool_name, ladder);
+                            if (sig)
+                                ladderSignal = sig;
+                            if (ladder.action === 'break')
+                                ladderBreak = sig;
+                            // Observability (backlog item 3): escalations are invisible in
+                            // the session record (signals inject post-persist) — bank each
+                            // rung as a decision-store event for the distiller.
+                            if (ladder.action !== 'none') {
+                                const store = this.getDecisionStore();
+                                if (store) {
+                                    void store
+                                        .recordEvent({
+                                        sessionId: this.currentSessionId ?? 'unknown',
+                                        kind: 'loop_escalation',
+                                        toolName: tr.tool_name,
+                                        detail: {
+                                            rung: ladder.action,
+                                            count: ladder.count,
+                                            approachHash: outcome.approachHash,
+                                            ...(outcome.family ? { family: outcome.family } : {}),
+                                        },
+                                    })
+                                        .catch(() => { });
+                                }
+                            }
+                        }
+                    }
                     // File-history snapshots (Claude Code parity — previously built but
                     // UNWIRED: FileCheckpointManager existed with zero markModified
                     // callers and its snapshot message was discarded). Mark files
@@ -1578,7 +1790,31 @@ export class CortexOrchestrator {
                         lastEndTurnCitations = Array.isArray(cits) ? cits : undefined; // Stage 3 baseline
                         const verdict = verifyCitationsGrounded(cits, thisTurnToolOutputs.join('\n'));
                         if (verdict.grounded) {
-                            endTurnCalled = true;
+                            // Stage 4 (backlog item 1, CORTEX_ENDTURN_REQUIREMENTS): verify
+                            // the requirements attestation — the wrong-artifact weapon.
+                            // Stage 2 verifies citations; nothing before this forced
+                            // re-reading the TASK. Rides the same nudge budget: a Stage-4
+                            // reject leaves the gate unsatisfied so the bounded
+                            // fallback-accept still guarantees liveness.
+                            if (resolveEndTurnRequirementsMode()) {
+                                const s4 = verifyRequirements({
+                                    requirements: etUse?.input?.requirements,
+                                    verification: etUse?.input?.verification,
+                                    userTaskText: this.lastRealUserText(),
+                                    turnUsedMutatingTool,
+                                });
+                                if (s4.ok) {
+                                    endTurnCalled = true;
+                                }
+                                else {
+                                    tr.is_error = true;
+                                    tr.content = s4.nudge;
+                                    console.warn('[Orchestrator] Stage4: EndTurn rejected — requirements attestation unsatisfied.');
+                                }
+                            }
+                            else {
+                                endTurnCalled = true;
+                            }
                         }
                         else {
                             const bad = verdict.ungrounded
@@ -1592,6 +1828,9 @@ export class CortexOrchestrator {
                             console.warn(`[Orchestrator] Stage2: EndTurn rejected — ${verdict.ungrounded.length} ungrounded citation(s).`);
                         }
                     }
+                    // Item 7: scrub ReadImage payloads from metadata BEFORE persist;
+                    // the images inject as a user message after the results land.
+                    const pendingImages = this.collectPendingImages(toolResults, effectiveModel.vision === true);
                     // Create tool_result messages and add to history
                     for (const toolResult of toolResults) {
                         const toolResultMessageId = uuidv4();
@@ -1726,14 +1965,43 @@ export class CortexOrchestrator {
                     const progressStalled = isToolProgressStalled(recentToolCalls);
                     const budgetSignal = computeToolBudgetSignal(effectiveToolBudgetCount, TOOL_BUDGET_SOFT, progressStalled);
                     const diversityWarning = this.getDiversityWarning(toolCallCounts);
-                    if (budgetSignal || diversityWarning) {
-                        const signals = [budgetSignal, diversityWarning].filter(Boolean).join('\n');
+                    if (budgetSignal || diversityWarning || ladderSignal) {
+                        const signals = [budgetSignal, diversityWarning, ladderSignal].filter(Boolean).join('\n');
                         const lastMsg = this.messageHistory[this.messageHistory.length - 1];
                         if (lastMsg?.message?.content?.[0]?.type === 'tool_result') {
                             const block = lastMsg.message.content[0];
                             const existing = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
                             block.content = existing + '\n\n' + signals;
+                            // Observability (backlog item 3, micro-suite defect #4): this
+                            // mutation happens AFTER the tool_result was persisted — the
+                            // durable session lacks the steering the model saw. Bank a
+                            // steering_injected event so harvest/distill sees it. Session rows
+                            // stay append-only (never rewritten).
+                            const store = this.getDecisionStore();
+                            if (store) {
+                                const kinds = [
+                                    budgetSignal ? 'budget' : null,
+                                    diversityWarning ? 'diversity' : null,
+                                    ladderSignal ? 'ladder' : null,
+                                ].filter(Boolean);
+                                void store
+                                    .recordEvent({
+                                    sessionId: this.currentSessionId ?? 'unknown',
+                                    kind: 'steering_injected',
+                                    detail: { kinds, iteration: toolCallIteration, chars: signals.length },
+                                })
+                                    .catch(() => { });
+                            }
                         }
+                        ladderSignal = null; // consumed — never re-inject on later iterations
+                    }
+                    // Ladder break (teach-then-break): the break instruction is already in
+                    // the tool result above; exit the loop R29b-style so the post-loop
+                    // synthesis net produces an honest final answer — never the blunt
+                    // toolCallIteration=MAX turn-kill of the exact-match detector.
+                    if (ladderBreak) {
+                        console.warn('[Orchestrator] LoopLadder break: repeated failing approach — forcing synthesis.');
+                        break;
                     }
                     // R29b hard cap: a weaker model may ignore the firm budget reminders
                     // and keep spinning (benchmark: deepseek 46 successful local calls,
@@ -1774,6 +2042,10 @@ export class CortexOrchestrator {
                             console.error(`[Orchestrator Mentorship] Interleaved continuation thinking failed:`, error.message);
                         }
                     }
+                    // Item 7: attach any ReadImage images as a user message so the
+                    // continuation request carries them (after the signals block — it
+                    // targets the LAST message being a tool_result).
+                    await this.injectImageUserMessage(pendingImages, effectiveModel);
                     // Send tool results back to model and get continuation response
                     // Proactive context management - ensure history fits before continuation
                     await this.ensureHistoryFitsModel(effectiveModel);
@@ -1782,7 +2054,11 @@ export class CortexOrchestrator {
                     // full profile applies from here. Rebuild from allTools because the
                     // armed anchor narrowed toolsToUse at assembly. (When deferred loading
                     // is on, the re-filter block below performs the rebuild.)
-                    if (!this.anchorLifted && resolveToolAnchor(process.env, this.cardAnchorProfile)) {
+                    if (!this.anchorLifted &&
+                        resolveToolAnchor(process.env, this.cardAnchorProfile) &&
+                        // Persist frame (backlog item 5): the anchored surface IS the session
+                        // surface — never lift, never deliver the deferred corpus.
+                        resolveFrameProfile(process.env, this.cardFrameProfile) !== 'persist') {
                         this.anchorLifted = true;
                         if (!(this.config.enableDeferredToolLoading && !isPTCEnabled)) {
                             toolsToUse = allTools;
@@ -2372,9 +2648,11 @@ export class CortexOrchestrator {
         // === END MENTORSHIP HOOKS ===
         // Get tools (needed for middleware injection decision)
         const endTurnGateOn2 = (process.env.CORTEX_ENDTURN_GATE) === 'true';
-        const factoryTools = this.applyBaseToolAllowlist(endTurnGateOn2
-            ? toolFactory.getAllTools()
-            : toolFactory.getAllTools().filter(t => t.name !== 'EndTurn'));
+        // Vision gate (item 7): streaming mirror of the sendMessage filter.
+        const visionOn2 = model?.vision === true;
+        const factoryTools = this.applyBaseToolAllowlist(toolFactory.getAllTools()
+            .filter(t => endTurnGateOn2 || t.name !== 'EndTurn')
+            .filter(t => visionOn2 || t.name !== 'ReadImage'));
         // Tool-profile: streaming mirror of the non-streaming suppression above.
         const bashOnlyProfile2 = isNarrowProfile();
         const mcpTools = this.mcpAutoInject && !bashOnlyProfile2 ? this.getMcpToolsAsCanonical() : [];
@@ -2564,6 +2842,7 @@ export class CortexOrchestrator {
         // Card-level home door: capture the active card's anchorProfile (env
         // CORTEX_TOOL_ANCHOR overrides inside the resolver; env 'none' disables).
         this.cardAnchorProfile = effectiveModel.anchorProfile ?? null;
+        this.cardFrameProfile = effectiveModel.frameProfile ?? null;
         // Thread the CARD's anchor to the executors (per-orchestrator config, by
         // reference) so framing-aware executor behavior (ShellTool steering
         // default) is model-card/registry-scoped, not process-global env.
@@ -2766,7 +3045,12 @@ export class CortexOrchestrator {
         let toolCallIteration = 0;
         let totalToolErrors = 0;
         let emptyResponseRetryUsed = false; // R32: parity with sendMessage R18b guard
+        let inactionNudgeUsed = false; // Inaction guard (backlog item 2) — streaming parity
         const allToolCalls = [];
+        // Unified Outcome Ladder (streaming parity — see sendMessage).
+        const loopLadder = new LoopLadder();
+        let ladderBreak = null;
+        let ladderSignal = null;
         const allExecutedToolUses = [];
         const toolCallCounts = new Map();
         // DEBUG: Log canonical message content structure for tool extraction (streaming path)
@@ -2933,6 +3217,136 @@ export class CortexOrchestrator {
                         console.warn(`[Orchestrator Streaming] R32 retry failed:`, retryErr);
                     }
                 }
+                // Inaction guard (backlog item 2 — streaming parity with sendMessage).
+                // Actless-verbose first-turn response in a tool-capable request: one
+                // bounded act-first steering retry. Default OFF (CORTEX_INACTION_NUDGE).
+                {
+                    const responseChars = Array.isArray(currentAssistantCanonicalMessage.content)
+                        ? currentAssistantCanonicalMessage.content
+                            .map((b) => b?.type === 'text' ? (b.text || '') : b?.type === 'thinking' ? (b.thinking || '') : '')
+                            .join('').length
+                        : String(currentAssistantCanonicalMessage.content ?? '').length;
+                    if (hasVisibleText &&
+                        shouldNudgeInaction({
+                            responseChars,
+                            toolUseBlocksThisResponse: 0,
+                            executedToolCallsThisTurn: allExecutedToolUses.length,
+                            toolsOffered: toolsToUse.length,
+                            turnNumber: this.turnNumber,
+                            alreadyNudged: inactionNudgeUsed,
+                        })) {
+                        inactionNudgeUsed = true;
+                        console.warn(`[Orchestrator Streaming] Inaction guard: actless-verbose response (${responseChars} chars, 0 tool calls). ` +
+                            `Injecting act-first nudge (single retry).`);
+                        {
+                            const store = this.getDecisionStore();
+                            if (store) {
+                                void store
+                                    .recordEvent({
+                                    sessionId: this.currentSessionId ?? 'unknown',
+                                    kind: 'inaction_nudge',
+                                    detail: { responseChars, turnNumber: this.turnNumber, streaming: true },
+                                })
+                                    .catch(() => { });
+                            }
+                        }
+                        const inactionUserMessage = {
+                            uuid: uuidv4(),
+                            timestamp: new Date().toISOString(),
+                            type: 'user',
+                            message: {
+                                role: 'user',
+                                content: [{
+                                        type: 'text',
+                                        text: `<system-reminder>${formatInactionNudge()}</system-reminder>`,
+                                    }],
+                            },
+                            timeline: {
+                                sessionId: this.currentSessionId,
+                                conversationId: this.currentConversationId,
+                                turnNumber: this.turnNumber + 1,
+                            },
+                            model: {
+                                id: effectiveModel.id,
+                                provider: effectiveModel.provider,
+                                apiPattern: effectiveModel.api.pattern,
+                            },
+                        };
+                        this.messageHistory.push(inactionUserMessage);
+                        await this.historyStore.appendMessage(this.currentSessionId, inactionUserMessage);
+                        try {
+                            await this.ensureHistoryFitsModel(effectiveModel);
+                            const retryCanonicalHistory = this.convertToCanonicalMessages([...this.messageHistory]);
+                            const retryRequest = this.gatewayTranslation.prepareRequest(retryCanonicalHistory, toolsToUse, effectiveModel, {
+                                temperature: options.parameters?.temperature,
+                                maxTokens: options.parameters?.maxTokens,
+                                topP: options.parameters?.topP,
+                                reasoningEffort: options.parameters?.reasoningEffort,
+                                stream: false,
+                                staticSystemPrompt: this.currentStaticSystemPrompt,
+                                conversationId: this.currentConversationId,
+                            });
+                            if (this.lastResponseId && effectiveModel.api.pattern === 'responses') {
+                                retryRequest.previousResponseId = this.lastResponseId;
+                            }
+                            retryRequest.conversationId = this.currentSessionId;
+                            let retryApiResponse;
+                            if (this.retryMiddleware) {
+                                const retryResult = await this.retryMiddleware.executeWithRetry(() => this.apiClient.sendRequest(retryRequest, effectiveModel), 'inaction_nudge_retry');
+                                retryApiResponse = retryResult.result;
+                            }
+                            else {
+                                retryApiResponse = await this.apiClient.sendRequest(retryRequest, effectiveModel);
+                            }
+                            const retryConverted = this.gatewayTranslation.convertResponse(retryApiResponse.data, effectiveModel, {
+                                sessionId: this.currentSessionId,
+                                conversationId: this.currentConversationId,
+                                turnNumber: this.turnNumber + 1,
+                            });
+                            if (effectiveModel.api.pattern === 'responses' && retryApiResponse.data?.id) {
+                                this.lastResponseId = retryApiResponse.data.id;
+                                this.lastResponseIdProvider = effectiveModel.provider;
+                            }
+                            if (retryConverted.messages && retryConverted.messages.length > 0) {
+                                const retryAssistantCanonical = retryConverted.messages[0];
+                                const retryAssistantMessage = {
+                                    uuid: retryAssistantCanonical.uuid,
+                                    timestamp: retryAssistantCanonical.timestamp,
+                                    type: 'assistant',
+                                    message: {
+                                        role: 'assistant',
+                                        content: retryAssistantCanonical.content,
+                                    },
+                                    timeline: {
+                                        sessionId: this.currentSessionId,
+                                        conversationId: this.currentConversationId,
+                                        turnNumber: this.turnNumber + 1,
+                                    },
+                                    model: {
+                                        id: effectiveModel.id,
+                                        provider: effectiveModel.provider,
+                                        apiPattern: effectiveModel.api.pattern,
+                                    },
+                                    ...(retryConverted.usage && { usage: retryConverted.usage }),
+                                };
+                                this.messageHistory.push(retryAssistantMessage);
+                                await this.historyStore.appendMessage(this.currentSessionId, retryAssistantMessage);
+                                currentAssistantCanonicalMessage = retryAssistantCanonical;
+                                const retryText = retryAssistantCanonical.content
+                                    .filter((b) => b && b.type === 'text' && typeof b.text === 'string')
+                                    .map((b) => b.text)
+                                    .join('');
+                                if (retryText.trim().length > 0) {
+                                    yield { type: 'text_delta', delta: retryText };
+                                }
+                                continue; // re-enter loop — retry may have produced tool_use
+                            }
+                        }
+                        catch (retryErr) {
+                            console.warn(`[Orchestrator Streaming] Inaction-nudge retry failed:`, retryErr);
+                        }
+                    }
+                }
                 hasToolUse = false;
                 break;
             }
@@ -2972,6 +3386,45 @@ export class CortexOrchestrator {
                 // Execute tools (reuse existing method)
                 const toolResults = await this.handleToolCalls(toolUseBlocks, abortController.signal, structuredOutputState);
                 clearTimeout(timeoutId);
+                // Unified Outcome Ladder (streaming parity with sendMessage).
+                ladderSignal = null;
+                {
+                    const inputById = new Map(toolUseBlocks.map((b) => [b.id, b.input]));
+                    for (const tr of toolResults) {
+                        if (tr.tool_name === 'EndTurn')
+                            continue;
+                        const input = inputById.get(tr.tool_use_id);
+                        if (input === undefined)
+                            continue;
+                        const outcome = classifyToolOutcome(tr.tool_name, input, tr);
+                        const ladder = loopLadder.observe(tr.tool_name, outcome);
+                        const sig = formatLadderSignal(tr.tool_name, ladder);
+                        if (sig)
+                            ladderSignal = sig;
+                        if (ladder.action === 'break')
+                            ladderBreak = sig;
+                        // Observability (backlog item 3): streaming parity — bank each
+                        // escalation rung as a decision-store event.
+                        if (ladder.action !== 'none') {
+                            const store = this.getDecisionStore();
+                            if (store) {
+                                void store
+                                    .recordEvent({
+                                    sessionId: this.currentSessionId ?? 'unknown',
+                                    kind: 'loop_escalation',
+                                    toolName: tr.tool_name,
+                                    detail: {
+                                        rung: ladder.action,
+                                        count: ladder.count,
+                                        approachHash: outcome.approachHash,
+                                        ...(outcome.family ? { family: outcome.family } : {}),
+                                    },
+                                })
+                                    .catch(() => { });
+                            }
+                        }
+                    }
+                }
                 // R21 (2026-05-15): same fix as non-streaming path — count consecutive
                 // ITERATIONS WITH ZERO SUCCESSFUL TOOLS, not cumulative individual
                 // failures. Reset whenever at least one tool succeeded.
@@ -2992,6 +3445,8 @@ export class CortexOrchestrator {
                 else if (successCount > 0) {
                     totalToolErrors = 0; // Reset — model is making progress
                 }
+                // Item 7: scrub ReadImage payloads before persist (streaming parity).
+                const pendingImages = this.collectPendingImages(toolResults, effectiveModel.vision === true);
                 // Create tool_result messages and save to history
                 for (const toolResult of toolResults) {
                     // Emit tool result as streaming chunk for CLI display
@@ -3123,15 +3578,43 @@ export class CortexOrchestrator {
                 const progressStalled = isToolProgressStalled(allToolCalls);
                 const budgetSignal = computeToolBudgetSignal(effectiveToolBudgetCount, TOOL_BUDGET_SOFT, progressStalled);
                 const diversityWarning = this.getDiversityWarning(toolCallCounts);
-                if (budgetSignal || diversityWarning) {
-                    const signals = [budgetSignal, diversityWarning].filter(Boolean).join('\n');
+                if (budgetSignal || diversityWarning || ladderSignal) {
+                    const signals = [budgetSignal, diversityWarning, ladderSignal].filter(Boolean).join('\n');
                     const lastMsg = this.messageHistory[this.messageHistory.length - 1];
                     if (lastMsg?.message?.content?.[0]?.type === 'tool_result') {
                         const block = lastMsg.message.content[0];
                         const existing = typeof block.content === 'string' ? block.content : JSON.stringify(block.content);
                         block.content = existing + '\n\n' + signals;
+                        // Observability (backlog item 3): post-persist mutation — bank a
+                        // steering_injected event (streaming parity).
+                        const store = this.getDecisionStore();
+                        if (store) {
+                            const kinds = [
+                                budgetSignal ? 'budget' : null,
+                                diversityWarning ? 'diversity' : null,
+                                ladderSignal ? 'ladder' : null,
+                            ].filter(Boolean);
+                            void store
+                                .recordEvent({
+                                sessionId: this.currentSessionId ?? 'unknown',
+                                kind: 'steering_injected',
+                                detail: { kinds, iteration: toolCallIteration, chars: signals.length, streaming: true },
+                            })
+                                .catch(() => { });
+                        }
                     }
+                    ladderSignal = null; // consumed
                 }
+                // Ladder break (streaming parity): instruction already injected above;
+                // exit R29b-style so the streaming synthesis net closes the turn.
+                if (ladderBreak) {
+                    console.warn('[Orchestrator Streaming] LoopLadder break: repeated failing approach — forcing synthesis.');
+                    break;
+                }
+                // Item 7: attach ReadImage images as a user message (streaming parity;
+                // after the signals block — it targets the LAST message being a
+                // tool_result).
+                await this.injectImageUserMessage(pendingImages, effectiveModel);
                 // R29b hard cap (streaming parity): force-stop at 2x soft budget;
                 // the post-loop R29a streaming net then synthesizes a deliverable.
                 // Progress-gated hard cap (parity with sendMessage): force-stop only when
@@ -3170,7 +3653,11 @@ export class CortexOrchestrator {
                 // Proactive context management - ensure history fits before streaming continuation
                 await this.ensureHistoryFitsModel(effectiveModel);
                 // Anchor lift — streaming mirror of the sendMessage continuation path.
-                if (!this.anchorLifted && resolveToolAnchor(process.env, this.cardAnchorProfile)) {
+                if (!this.anchorLifted &&
+                    resolveToolAnchor(process.env, this.cardAnchorProfile) &&
+                    // Persist frame (backlog item 5): the anchored surface IS the session
+                    // surface — never lift, never deliver the deferred corpus.
+                    resolveFrameProfile(process.env, this.cardFrameProfile) !== 'persist') {
                     this.anchorLifted = true;
                     if (!(this.config.enableDeferredToolLoading && !isPTCEnabled)) {
                         toolsToUse = allTools;
@@ -5886,6 +6373,89 @@ export class CortexOrchestrator {
         }
         return this.routerMatrix;
     }
+    /** Item 7 (image-path bridge): consume ReadImage payloads from this batch.
+     *  SCRUBS the base64 payload out of tool_result metadata BEFORE the result
+     *  is persisted (no double-stored image; the image rides the injected user
+     *  message instead). When the active model is not vision-capable (a
+     *  hallucinated/PTC call that slipped the surface gate), the result is
+     *  rewritten into an actionable error — a text-only model must never have
+     *  an image dangled at it. */
+    collectPendingImages(toolResults, modelVision) {
+        const out = [];
+        for (const tr of toolResults) {
+            const payload = tr.metadata?.imagePayload;
+            if (!payload)
+                continue;
+            delete tr.metadata.imagePayload;
+            if (tr.is_error)
+                continue;
+            if (!modelVision) {
+                tr.is_error = true;
+                tr.content =
+                    'ReadImage requires a vision-capable model — the active model cannot see images. ' +
+                        'Extract what you need through bash instead (e.g. tesseract OCR, ffprobe, PIL).';
+                continue;
+            }
+            out.push({ mediaType: payload.mediaType, data: payload.base64 });
+        }
+        return out;
+    }
+    /** Item 7: attach collected images as a synthetic USER message (R18b shape).
+     *  Providers reject image parts on tool messages — DeepSeek accepts them on
+     *  user messages only — so the image hops from the tool_result to the next
+     *  user turn. Persisted BEFORE the continuation request is assembled, so the
+     *  session record shows exactly what the model saw (item-3 lesson). */
+    async injectImageUserMessage(images, effectiveModel) {
+        if (images.length === 0)
+            return;
+        const content = [{
+                type: 'text',
+                text: `<system-reminder>Visual input from ReadImage (${images.length} image${images.length > 1 ? 's' : ''}) attached below — read the image content directly.</system-reminder>`,
+            }];
+        for (const img of images) {
+            content.push({ type: 'image', image: { mediaType: img.mediaType, data: img.data } });
+        }
+        const imageUserMessage = {
+            uuid: uuidv4(),
+            timestamp: new Date().toISOString(),
+            type: 'user',
+            message: { role: 'user', content },
+            timeline: {
+                sessionId: this.currentSessionId,
+                conversationId: this.currentConversationId,
+                turnNumber: this.turnNumber + 1,
+            },
+            model: {
+                id: effectiveModel.id,
+                provider: effectiveModel.provider,
+                apiPattern: effectiveModel.api.pattern,
+            },
+        };
+        this.messageHistory.push(imageUserMessage);
+        await this.historyStore.appendMessage(this.currentSessionId, imageUserMessage);
+    }
+    /** The turn's real user prompt text — the most recent user message that is
+     *  neither a tool_result carrier nor an injected <system-reminder> steering
+     *  message. Used by EndTurn Stage 4 to judge task shape. Empty string when
+     *  none found (Stage 4 then never fires its task-shape branch). */
+    lastRealUserText() {
+        for (let i = this.messageHistory.length - 1; i >= 0; i--) {
+            const m = this.messageHistory[i];
+            const isUser = m?.type === 'user' || m?.message?.role === 'user';
+            if (!isUser)
+                continue;
+            const content = m?.message?.content;
+            if (Array.isArray(content) && content.some((b) => b?.type === 'tool_result'))
+                continue;
+            const text = Array.isArray(content)
+                ? content.filter((b) => b?.type === 'text').map((b) => b.text || '').join('\n')
+                : typeof content === 'string' ? content : '';
+            if (!text.trim() || text.trimStart().startsWith('<system-reminder>'))
+                continue;
+            return text;
+        }
+        return '';
+    }
     getDecisionStore() {
         if (this.isRecordingEnabled() === false && this.isLookupEnabled() === false) {
             return undefined;
@@ -5915,7 +6485,14 @@ export class CortexOrchestrator {
         const store = this.getDecisionStore();
         if (!store)
             return result;
-        const inputHash = stableInputHash(toolUse.input);
+        // Unified outcome layer (docs/UNIFIED_OUTCOME_LADDER.md): ONE failure
+        // semantics for recording + reminders. Critically, a bash command that
+        // ran and exited nonzero is a FAILURE here even though its tool result
+        // is not is_error on the wire (ShellTool returns success results for
+        // exit!=0) — previously those loops were recorded as successes, so the
+        // prior/family reminders never fired on the dominant thrash mode.
+        const outcome = classifyToolOutcome(toolUse.name, toolUse.input, result);
+        const inputHash = outcome.exactHash;
         let augmented = result;
         // 1. Lookup priors (read side) — only emits reminder when failures exist.
         //    Fetch the 3 most recent matching decisions so the formatter can
@@ -5930,6 +6507,21 @@ export class CortexOrchestrator {
                 if (reminder && result.content) {
                     augmented = { ...result, content: reminder + result.content };
                 }
+                else if (outcome.status !== 'ok' && result.content) {
+                    // Family lens (AHE borrow): no exact-input prior fired, but the
+                    // CURRENT failure may be the latest of a repeated-approach family
+                    // across different inputs — hint once the family has >=2 prior
+                    // failures spanning >=2 distinct inputs. Gated on the UNIFIED
+                    // outcome (not is_error) so failing-command loops are covered.
+                    const family = outcome.family ?? classifyErrorFamily(String(result.content).slice(0, 200));
+                    if (family) {
+                        const ff = await store.familyFailures(toolUse.name, family);
+                        const famReminder = formatFamilyReminder(toolUse.name, family, ff.count, ff.distinctInputs, ff.recent);
+                        if (famReminder) {
+                            augmented = { ...result, content: famReminder + result.content };
+                        }
+                    }
+                }
             }
             catch (err) {
                 if (this.config.debug) {
@@ -5945,8 +6537,10 @@ export class CortexOrchestrator {
                     sessionId: this.currentSessionId ?? 'unknown',
                     toolName: toolUse.name,
                     input: toolUse.input,
-                    success: !result.is_error,
-                    ...(result.is_error
+                    // Unified outcome: exit!=0 commands are FAILURES for the store even
+                    // though their wire result is not is_error (see outcome above).
+                    success: outcome.status === 'ok',
+                    ...(outcome.status !== 'ok'
                         ? { errorSnippet: String(result.content).slice(0, 200) }
                         : {}),
                 });
@@ -6503,10 +7097,15 @@ export class CortexOrchestrator {
         });
         // Validate and repair any orphaned tool_use blocks (crash recovery)
         const repaired = this.validateAndRepairMessages(converted);
+        // Image TTL eviction (item 7 addendum): stale images forfeit the whole
+        // request's cache reads on vision-exp — stub them out of the REQUEST copy
+        // after CORTEX_IMAGE_TTL_TURNS. Always-on (not utilization-gated); pure;
+        // swaps content arrays only (cache contract).
+        const imageAged = applyImageTtlForRequest(repaired);
         // Age-tiered tool-result pruning on the outgoing request copy (all
         // request-build call sites flow through here). No-op below the
         // utilization gate; never touches the cache (pruner clones).
-        return this.pruneAgedForRequest(repaired);
+        return this.pruneAgedForRequest(imageAged);
     }
     /**
      * Apply age-tiered tool-result pruning to an outgoing canonical request
@@ -6664,6 +7263,13 @@ export class CortexOrchestrator {
                         }
                         return thinkingBlock;
                     }
+                    else if (block.type === 'image') {
+                        // Item 7 (image-path bridge): pass image blocks through
+                        // untouched — the unknown-type fallback below stringifies,
+                        // which delivered the base64 as TEXT to the model (live-probe
+                        // finding 2026-08-25: "attached base64 blob").
+                        return { type: 'image', image: block.image };
+                    }
                     else if (block.type === 'redacted_thinking') {
                         // XAI grok-4/4.1 encrypted reasoning — preserve opaquely
                         return {