@nexus-cortex/core 4.69.1 → 4.71.0

package/dist/orchestrator/imageTtl.d.ts

@@ -0,0 +1,37 @@
+/**
+ * imageTtl — request-build-time image eviction (backlog item 7 addendum,
+ * MEASURED 2026-08-25): on deepseek-v4-flash-vision-exp an image ANYWHERE in
+ * the request disables cache reads for the ENTIRE request (probe: identical
+ * repeat cached=0 while a text-only request hit the same 896-token prefix).
+ * The image's own ≤384 tokens are irrelevant — one stale image forfeits the
+ * ~31× cache-hit discount on every subsequent turn.
+ *
+ * Fix: after the image has been visible for CORTEX_IMAGE_TTL_TURNS assistant
+ * responses (default 3 — enough to look, act, and confirm), the outgoing
+ * REQUEST COPY replaces the image block with a deterministic text stub. The
+ * session history is never rewritten (append-only invariant; the model can
+ * always ReadImage again). The one-time prefix bust at the TTL boundary is
+ * the good kind: it restores caching for the rest of the session, and the
+ * stub is byte-stable so the prefix re-stabilizes immediately.
+ *
+ * Pure — applied in convertToCanonicalMessages' request pipeline. MUST NOT
+ * mutate the input blocks/arrays (cached wrappers share the content array;
+ * same contract as the repair pass: swap arrays, never edit blocks).
+ */
+import type { CanonicalMessage } from '../adapters/FormatAdapter.interface.js';
+/** Resolve the TTL from env. Returns null when eviction is DISABLED
+ *  ('off'/'never'/'0'); otherwise a positive integer (default 3). */
+export declare function resolveImageTtlTurns(env?: NodeJS.ProcessEnv): number | null;
+/** Deterministic stub — NO timestamps or counters, so the request prefix is
+ *  byte-stable on every build after the eviction boundary. */
+export declare function imageEvictionStub(): {
+    type: 'text';
+    text: string;
+};
+/**
+ * Replace image blocks older than `ttl` assistant responses with the stub,
+ * on a request copy. An image's age = number of assistant-role messages
+ * appearing AFTER its message in the array.
+ */
+export declare function applyImageTtlForRequest(messages: CanonicalMessage[], ttl?: number | null): CanonicalMessage[];
+//# sourceMappingURL=imageTtl.d.ts.map

package/dist/orchestrator/imageTtl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageTtl.d.ts","sourceRoot":"","sources":["../../src/orchestrator/imageTtl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wCAAwC,CAAC;AAE/E;qEACqE;AACrE,wBAAgB,oBAAoB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,GAAG,IAAI,CAKxF;AAED;8DAC8D;AAC9D,wBAAgB,iBAAiB,IAAI;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAKlE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,gBAAgB,EAAE,EAC5B,GAAG,GAAE,MAAM,GAAG,IAA6B,GAC1C,gBAAgB,EAAE,CAsBpB"}

package/dist/orchestrator/imageTtl.js

@@ -0,0 +1,72 @@
+/**
+ * imageTtl — request-build-time image eviction (backlog item 7 addendum,
+ * MEASURED 2026-08-25): on deepseek-v4-flash-vision-exp an image ANYWHERE in
+ * the request disables cache reads for the ENTIRE request (probe: identical
+ * repeat cached=0 while a text-only request hit the same 896-token prefix).
+ * The image's own ≤384 tokens are irrelevant — one stale image forfeits the
+ * ~31× cache-hit discount on every subsequent turn.
+ *
+ * Fix: after the image has been visible for CORTEX_IMAGE_TTL_TURNS assistant
+ * responses (default 3 — enough to look, act, and confirm), the outgoing
+ * REQUEST COPY replaces the image block with a deterministic text stub. The
+ * session history is never rewritten (append-only invariant; the model can
+ * always ReadImage again). The one-time prefix bust at the TTL boundary is
+ * the good kind: it restores caching for the rest of the session, and the
+ * stub is byte-stable so the prefix re-stabilizes immediately.
+ *
+ * Pure — applied in convertToCanonicalMessages' request pipeline. MUST NOT
+ * mutate the input blocks/arrays (cached wrappers share the content array;
+ * same contract as the repair pass: swap arrays, never edit blocks).
+ */
+/** Resolve the TTL from env. Returns null when eviction is DISABLED
+ *  ('off'/'never'/'0'); otherwise a positive integer (default 3). */
+export function resolveImageTtlTurns(env = process.env) {
+    const raw = (env.CORTEX_IMAGE_TTL_TURNS ?? '').trim().toLowerCase();
+    if (raw === 'off' || raw === 'never' || raw === '0')
+        return null;
+    if (/^\d+$/.test(raw) && Number(raw) > 0)
+        return Number(raw);
+    return 3;
+}
+/** Deterministic stub — NO timestamps or counters, so the request prefix is
+ *  byte-stable on every build after the eviction boundary. */
+export function imageEvictionStub() {
+    return {
+        type: 'text',
+        text: '[image evicted from context to restore prompt caching — run ReadImage on the file again if you need to see it]',
+    };
+}
+/**
+ * Replace image blocks older than `ttl` assistant responses with the stub,
+ * on a request copy. An image's age = number of assistant-role messages
+ * appearing AFTER its message in the array.
+ */
+export function applyImageTtlForRequest(messages, ttl = resolveImageTtlTurns()) {
+    if (ttl === null)
+        return messages;
+    // Suffix counts of assistant messages, computed once.
+    const assistantsAfter = new Array(messages.length);
+    let count = 0;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        assistantsAfter[i] = count;
+        if (messages[i].role === 'assistant')
+            count++;
+    }
+    let changed = false;
+    const out = messages.map((msg, i) => {
+        if (msg.role !== 'user')
+            return msg;
+        if (assistantsAfter[i] < ttl)
+            return msg;
+        if (!msg.content.some((b) => b.type === 'image'))
+            return msg;
+        changed = true;
+        // Swap the content ARRAY; never mutate shared blocks (cache contract).
+        return {
+            ...msg,
+            content: msg.content.map((b) => (b.type === 'image' ? imageEvictionStub() : b)),
+        };
+    });
+    return changed ? out : messages;
+}
+//# sourceMappingURL=imageTtl.js.map

package/dist/orchestrator/imageTtl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageTtl.js","sourceRoot":"","sources":["../../src/orchestrator/imageTtl.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH;qEACqE;AACrE,MAAM,UAAU,oBAAoB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACvE,MAAM,GAAG,GAAG,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACpE,IAAI,GAAG,KAAK,KAAK,IAAI,GAAG,KAAK,OAAO,IAAI,GAAG,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACjE,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,MAAM,CAAC,GAAG,CAAC,CAAC;IAC7D,OAAO,CAAC,CAAC;AACX,CAAC;AAED;8DAC8D;AAC9D,MAAM,UAAU,iBAAiB;IAC/B,OAAO;QACL,IAAI,EAAE,MAAM;QACZ,IAAI,EAAE,gHAAgH;KACvH,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,QAA4B,EAC5B,MAAqB,oBAAoB,EAAE;IAE3C,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,QAAQ,CAAC;IAClC,sDAAsD;IACtD,MAAM,eAAe,GAAG,IAAI,KAAK,CAAS,QAAQ,CAAC,MAAM,CAAC,CAAC;IAC3D,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QAC9C,eAAe,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC;QAC3B,IAAI,QAAQ,CAAC,CAAC,CAAE,CAAC,IAAI,KAAK,WAAW;YAAE,KAAK,EAAE,CAAC;IACjD,CAAC;IACD,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,MAAM,GAAG,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;QAClC,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM;YAAE,OAAO,GAAG,CAAC;QACpC,IAAI,eAAe,CAAC,CAAC,CAAE,GAAG,GAAG;YAAE,OAAO,GAAG,CAAC;QAC1C,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC;YAAE,OAAO,GAAG,CAAC;QAC7D,OAAO,GAAG,IAAI,CAAC;QACf,uEAAuE;QACvE,OAAO;YACL,GAAG,GAAG;YACN,OAAO,EAAE,GAAG,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,iBAAiB,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;SAChF,CAAC;IACJ,CAAC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC;AAClC,CAAC"}

package/dist/orchestrator/inactionGuard.d.ts

@@ -0,0 +1,42 @@
+/**
+ * inactionGuard — the loop ladder's INVERSE (docs/HARNESS_IMPROVEMENT_BACKLOG.md
+ * item 2). TB2 2×2 evidence: persist-frame arms produced never-acted /
+ * over-deliberated failures (5 pro-persist, 2 each flash arm, 0 pro-lifted) —
+ * the model reasons to the output wall with ZERO tool calls, so every
+ * existing guard (which all count tool calls) is blind to it.
+ *
+ * Mechanism: extends the R18b/R32 empty-response-retry precedent to
+ * ACTLESS-VERBOSE responses — one injected "act first" steering retry,
+ * bounded, fallback-accept. Default OFF (`CORTEX_INACTION_NUDGE=true` arms
+ * it; bench/server profiles arm, interactive CLI stays off until specificity
+ * is proven broadly).
+ */
+export interface InactionCheckInput {
+    /** Total visible text+thinking characters of the final assistant response. */
+    responseChars: number;
+    /** Tool_use blocks in THIS assistant response (0 at the natural exit). */
+    toolUseBlocksThisResponse: number;
+    /** Tool calls executed across the ENTIRE turn so far. */
+    executedToolCallsThisTurn: number;
+    /** Tools offered on the request (0 = pure-chat, guard never fires). */
+    toolsOffered: number;
+    /** Orchestrator turn counter (0 = first turn of the session). v1 gate:
+     *  only the first turn — later turns of a conversation are much more
+     *  likely to be legitimately analytic follow-ups. */
+    turnNumber: number;
+    /** Single-nudge bound (mirrors emptyResponseRetryUsed). */
+    alreadyNudged: boolean;
+}
+/** Resolve arming + threshold from env. Default OFF; threshold default 4000
+ *  chars (the TB2 never-acted signature was multi-thousand-char reasoning
+ *  dumps — short direct answers must never trigger). */
+export declare function resolveInactionConfig(env?: NodeJS.ProcessEnv): {
+    enabled: boolean;
+    minChars: number;
+};
+/** Should the inaction nudge fire? Pure — all state passed in. */
+export declare function shouldNudgeInaction(input: InactionCheckInput, env?: NodeJS.ProcessEnv): boolean;
+/** The injected steering text (system-reminder-wrapped by the caller's
+ *  standard synthetic-user-message shape). */
+export declare function formatInactionNudge(): string;
+//# sourceMappingURL=inactionGuard.d.ts.map

package/dist/orchestrator/inactionGuard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inactionGuard.d.ts","sourceRoot":"","sources":["../../src/orchestrator/inactionGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,kBAAkB;IACjC,8EAA8E;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,yBAAyB,EAAE,MAAM,CAAC;IAClC,yDAAyD;IACzD,yBAAyB,EAAE,MAAM,CAAC;IAClC,uEAAuE;IACvE,YAAY,EAAE,MAAM,CAAC;IACrB;;yDAEqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,2DAA2D;IAC3D,aAAa,EAAE,OAAO,CAAC;CACxB;AAED;;wDAEwD;AACxD,wBAAgB,qBAAqB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG;IAC3E,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;CAClB,CAKA;AAED,kEAAkE;AAClE,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,kBAAkB,EACzB,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAST;AAED;8CAC8C;AAC9C,wBAAgB,mBAAmB,IAAI,MAAM,CAM5C"}

package/dist/orchestrator/inactionGuard.js

@@ -0,0 +1,47 @@
+/**
+ * inactionGuard — the loop ladder's INVERSE (docs/HARNESS_IMPROVEMENT_BACKLOG.md
+ * item 2). TB2 2×2 evidence: persist-frame arms produced never-acted /
+ * over-deliberated failures (5 pro-persist, 2 each flash arm, 0 pro-lifted) —
+ * the model reasons to the output wall with ZERO tool calls, so every
+ * existing guard (which all count tool calls) is blind to it.
+ *
+ * Mechanism: extends the R18b/R32 empty-response-retry precedent to
+ * ACTLESS-VERBOSE responses — one injected "act first" steering retry,
+ * bounded, fallback-accept. Default OFF (`CORTEX_INACTION_NUDGE=true` arms
+ * it; bench/server profiles arm, interactive CLI stays off until specificity
+ * is proven broadly).
+ */
+/** Resolve arming + threshold from env. Default OFF; threshold default 4000
+ *  chars (the TB2 never-acted signature was multi-thousand-char reasoning
+ *  dumps — short direct answers must never trigger). */
+export function resolveInactionConfig(env = process.env) {
+    const enabled = (env.CORTEX_INACTION_NUDGE ?? '').trim().toLowerCase() === 'true';
+    const raw = env.CORTEX_INACTION_MIN_CHARS?.trim();
+    const minChars = raw && /^\d+$/.test(raw) && Number(raw) > 0 ? Number(raw) : 4000;
+    return { enabled, minChars };
+}
+/** Should the inaction nudge fire? Pure — all state passed in. */
+export function shouldNudgeInaction(input, env = process.env) {
+    const cfg = resolveInactionConfig(env);
+    if (!cfg.enabled)
+        return false;
+    if (input.alreadyNudged)
+        return false;
+    if (input.toolsOffered === 0)
+        return false; // pure-chat request
+    if (input.turnNumber !== 0)
+        return false; // conservative v1: first turn only
+    if (input.toolUseBlocksThisResponse > 0)
+        return false;
+    if (input.executedToolCallsThisTurn > 0)
+        return false; // it acted earlier this turn
+    return input.responseChars >= cfg.minChars;
+}
+/** The injected steering text (system-reminder-wrapped by the caller's
+ *  standard synthetic-user-message shape). */
+export function formatInactionNudge() {
+    return ('You produced a long analysis but ran no commands. Act first: run at least ' +
+        'one tool call to ground or execute your plan (inspect the actual files/state, ' +
+        'or make the first concrete change), then answer. Do not restate the plan.');
+}
+//# sourceMappingURL=inactionGuard.js.map

package/dist/orchestrator/inactionGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inactionGuard.js","sourceRoot":"","sources":["../../src/orchestrator/inactionGuard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAmBH;;wDAEwD;AACxD,MAAM,UAAU,qBAAqB,CAAC,MAAyB,OAAO,CAAC,GAAG;IAIxE,MAAM,OAAO,GAAG,CAAC,GAAG,CAAC,qBAAqB,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM,CAAC;IAClF,MAAM,GAAG,GAAG,GAAG,CAAC,yBAAyB,EAAE,IAAI,EAAE,CAAC;IAClD,MAAM,QAAQ,GAAG,GAAG,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;AAC/B,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,mBAAmB,CACjC,KAAyB,EACzB,MAAyB,OAAO,CAAC,GAAG;IAEpC,MAAM,GAAG,GAAG,qBAAqB,CAAC,GAAG,CAAC,CAAC;IACvC,IAAI,CAAC,GAAG,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC/B,IAAI,KAAK,CAAC,aAAa;QAAE,OAAO,KAAK,CAAC;IACtC,IAAI,KAAK,CAAC,YAAY,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,oBAAoB;IAChE,IAAI,KAAK,CAAC,UAAU,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,mCAAmC;IAC7E,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACtD,IAAI,KAAK,CAAC,yBAAyB,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,CAAC,6BAA6B;IACpF,OAAO,KAAK,CAAC,aAAa,IAAI,GAAG,CAAC,QAAQ,CAAC;AAC7C,CAAC;AAED;8CAC8C;AAC9C,MAAM,UAAU,mBAAmB;IACjC,OAAO,CACL,4EAA4E;QAC5E,gFAAgF;QAChF,2EAA2E,CAC5E,CAAC;AACJ,CAAC"}

package/dist/orchestrator/requirementsVerification.d.ts

@@ -0,0 +1,43 @@
+/**
+ * requirementsVerification — EndTurn Stage 4 (docs/HARNESS_IMPROVEMENT_BACKLOG.md
+ * item 1). The as-shipped gate verifies CITATIONS (Stage 2 grounding, Stage 3
+ * coordinates) but not TASK REQUIREMENTS: a wrong-artifact finish passes with
+ * honest citations and a legitimate empty `verification` ("none asked") —
+ * TB2's 2nd-largest failure class (20 wrong-artifact fails, 11 in
+ * flash-persist alone). Stage 4 makes the model re-read the task statement
+ * and attest each stated requirement.
+ *
+ * Armed by CORTEX_ENDTURN_REQUIREMENTS=true (off by default; the
+ * persist+EndTurn bench cell and server profiles arm it). Pure — the
+ * orchestrator supplies all state.
+ */
+export interface RequirementRow {
+    requirement: string;
+    satisfied_by: string;
+    verified_how: string;
+}
+export interface RequirementsVerdict {
+    ok: boolean;
+    /** Rejection text to surface on the EndTurn tool_result (Stage-2 style). */
+    nudge?: string;
+}
+export declare function resolveEndTurnRequirementsMode(env?: NodeJS.ProcessEnv): boolean;
+/** Conservative imperative/task-shape heuristic: does the user text ask for
+ *  work (vs. a question/discussion)? False negatives are acceptable (no
+ *  nudge); false positives are the cost to avoid. */
+export declare function isTaskShaped(userText: string): boolean;
+/**
+ * Stage 4: verify the `requirements` attestation. Caller gates on
+ * resolveEndTurnRequirementsMode() — this function assumes armed mode.
+ */
+export declare function verifyRequirements(input: {
+    /** Raw `requirements` value from the EndTurn tool input. */
+    requirements: unknown;
+    /** Raw `verification` value from the EndTurn tool input. */
+    verification: unknown;
+    /** The turn's real user prompt text (empty string when unknown). */
+    userTaskText: string;
+    /** Did this turn run Edit/Write/Bash/NotebookEdit? */
+    turnUsedMutatingTool: boolean;
+}): RequirementsVerdict;
+//# sourceMappingURL=requirementsVerification.d.ts.map

package/dist/orchestrator/requirementsVerification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirementsVerification.d.ts","sourceRoot":"","sources":["../../src/orchestrator/requirementsVerification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,8BAA8B,CAC5C,GAAG,GAAE,MAAM,CAAC,UAAwB,GACnC,OAAO,CAET;AAED;;qDAEqD;AACrD,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAKtD;AAID;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE;IACxC,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,4DAA4D;IAC5D,YAAY,EAAE,OAAO,CAAC;IACtB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,oBAAoB,EAAE,OAAO,CAAC;CAC/B,GAAG,mBAAmB,CAoEtB"}

package/dist/orchestrator/requirementsVerification.js

@@ -0,0 +1,87 @@
+/**
+ * requirementsVerification — EndTurn Stage 4 (docs/HARNESS_IMPROVEMENT_BACKLOG.md
+ * item 1). The as-shipped gate verifies CITATIONS (Stage 2 grounding, Stage 3
+ * coordinates) but not TASK REQUIREMENTS: a wrong-artifact finish passes with
+ * honest citations and a legitimate empty `verification` ("none asked") —
+ * TB2's 2nd-largest failure class (20 wrong-artifact fails, 11 in
+ * flash-persist alone). Stage 4 makes the model re-read the task statement
+ * and attest each stated requirement.
+ *
+ * Armed by CORTEX_ENDTURN_REQUIREMENTS=true (off by default; the
+ * persist+EndTurn bench cell and server profiles arm it). Pure — the
+ * orchestrator supplies all state.
+ */
+export function resolveEndTurnRequirementsMode(env = process.env) {
+    return (env.CORTEX_ENDTURN_REQUIREMENTS ?? '').trim().toLowerCase() === 'true';
+}
+/** Conservative imperative/task-shape heuristic: does the user text ask for
+ *  work (vs. a question/discussion)? False negatives are acceptable (no
+ *  nudge); false positives are the cost to avoid. */
+export function isTaskShaped(userText) {
+    if (!userText || userText.length < 8)
+        return false;
+    return /\b(fix|add|implement|create|write|build|make|update|refactor|convert|generate|install|configure|set up|setup|remove|delete|rename|migrate|optimi[sz]e|debug|repair|extract|compress|decompress|parse|train|deploy|run)\b/i.test(userText);
+}
+const UNVERIFIED_RE = /^\s*unverified\s*$/i;
+/**
+ * Stage 4: verify the `requirements` attestation. Caller gates on
+ * resolveEndTurnRequirementsMode() — this function assumes armed mode.
+ */
+export function verifyRequirements(input) {
+    const reqs = Array.isArray(input.requirements) ? input.requirements : null;
+    const verification = Array.isArray(input.verification) ? input.verification : [];
+    // 4a — task-shaped turn with no requirements enumerated.
+    if ((!reqs || reqs.length === 0) && isTaskShaped(input.userTaskText)) {
+        return {
+            ok: false,
+            nudge: 'EndTurn REJECTED (requirements) — this turn has a stated task but you enumerated no requirements. ' +
+                'Re-read the task statement and list EACH stated requirement in `requirements` ' +
+                '[{requirement, satisfied_by, verified_how}]: `satisfied_by` = what in your artifact satisfies it; ' +
+                '`verified_how` = the command/observation that proves it, or the literal string "UNVERIFIED". ' +
+                'Then call EndTurn again.',
+        };
+    }
+    // 4b — malformed rows.
+    if (reqs) {
+        const bad = reqs.findIndex((r) => !r ||
+            typeof r !== 'object' ||
+            typeof r.requirement !== 'string' ||
+            typeof r.satisfied_by !== 'string' ||
+            typeof r.verified_how !== 'string');
+        if (bad !== -1) {
+            return {
+                ok: false,
+                nudge: `EndTurn REJECTED (requirements) — row ${bad + 1} is malformed. Each row must be ` +
+                    '{requirement, satisfied_by, verified_how} (strings). Use "UNVERIFIED" as verified_how ' +
+                    'when you did not verify a requirement — do not omit the field. Then call EndTurn again.',
+            };
+        }
+        // 4c — unverified rows must be nudged ONCE toward verification.
+        const unverified = reqs.filter((r) => UNVERIFIED_RE.test(r.verified_how));
+        if (unverified.length > 0) {
+            const names = unverified
+                .slice(0, 3)
+                .map((r) => `"${r.requirement.slice(0, 80)}"`)
+                .join(', ');
+            return {
+                ok: false,
+                nudge: `EndTurn REJECTED (requirements) — ${unverified.length} requirement(s) are UNVERIFIED: ${names}. ` +
+                    'For each: either RUN the check that proves it (then put the command + observed result in ' +
+                    '`verified_how`), or move it to `open_items` with a one-line justification and delete the row. ' +
+                    'Then call EndTurn again.',
+            };
+        }
+    }
+    // 4d — mutating turn that ran no checks at all.
+    if (input.turnUsedMutatingTool && verification.length === 0) {
+        return {
+            ok: false,
+            nudge: 'EndTurn REJECTED (verification) — you modified files this turn but `verification` is empty: ' +
+                'no build/test/lint/behavior check was run. Run at least one check that exercises what you ' +
+                'changed and list it with the real result line, or state in `open_items` why no check is ' +
+                'possible. Then call EndTurn again.',
+        };
+    }
+    return { ok: true };
+}
+//# sourceMappingURL=requirementsVerification.js.map

package/dist/orchestrator/requirementsVerification.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"requirementsVerification.js","sourceRoot":"","sources":["../../src/orchestrator/requirementsVerification.ts"],"names":[],"mappings":"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"}

package/dist/tools/ToolProfile.d.ts

@@ -29,6 +29,15 @@ export declare function resolveToolProfile(env?: NodeJS.ProcessEnv): ToolProfile
  * — the dsh anchored-standard point). 'full' or unknown → no anchor.
  */
 export declare function resolveToolAnchor(env?: NodeJS.ProcessEnv, cardAnchor?: string | null): ToolProfileName | null;
+/**
+ * CORTEX_TOOL_ANCHOR_PERSIST — frame selection for an armed anchor (backlog
+ * item 5). 'lifted' (default): the anchor lifts at the first tool_result
+ * boundary and the session's full profile applies. 'persist': the anchored
+ * surface stays the ONLY surface for the whole session (the TB2 persist
+ * frame, previously an installed-copy patch). Precedence: env override >
+ * card frameProfile > 'lifted'. Irrelevant when no anchor is armed.
+ */
+export declare function resolveFrameProfile(env?: NodeJS.ProcessEnv, cardFrame?: string | null): 'lifted' | 'persist';
 /** Do MCP / management / context tools ride along? Narrow arms suppress them
  *  (surface leak otherwise); full and lean keep them. */
 export declare function isNarrowProfile(profile?: ToolProfileName): boolean;

package/dist/tools/ToolProfile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ToolProfile.d.ts","sourceRoot":"","sources":["../../src/tools/ToolProfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAoBxF,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,eAAe,CAIxF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,eAAe,GAAG,IAAI,CASxB;AAED;yDACyD;AACzD,wBAAgB,eAAe,CAAC,OAAO,GAAE,eAAsC,GAAG,OAAO,CAExF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EACjF,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,GAAE,eAAsC,GAC9C,CAAC,EAAE,CAML;AAED;8EAC8E;AAC9E,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAChD,OAAO,GAAE,eAAsC,GAC9C,OAAO,CAOT"}
+{"version":3,"file":"ToolProfile.d.ts","sourceRoot":"","sources":["../../src/tools/ToolProfile.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,MAAM,GAAG,WAAW,GAAG,WAAW,GAAG,WAAW,CAAC;AAwBxF,wBAAgB,kBAAkB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,eAAe,CAIxF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,GACzB,eAAe,GAAG,IAAI,CASxB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GACxB,QAAQ,GAAG,SAAS,CAOtB;AAED;yDACyD;AACzD,wBAAgB,eAAe,CAAC,OAAO,GAAE,eAAsC,GAAG,OAAO,CAExF;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAAE,EACjF,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,GAAE,eAAsC,GAC9C,CAAC,EAAE,CAML;AAED;8EAC8E;AAC9E,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,MAAM,EACZ,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,EAChD,OAAO,GAAE,eAAsC,GAC9C,OAAO,CAOT"}

package/dist/tools/ToolProfile.js

@@ -28,11 +28,15 @@ const ALWAYS_KEEP = new Set(['EndTurn', 'AskUserQuestion']);
 const BASH_ONLY = new Set(['Bash', ...ALWAYS_KEEP]);
 /** bash-plus: the minimal-harness arm (BASH_PLUS_SPEC.md, R61) — the Pi/dsh
  *  surface class: shell + structural file ops, nothing else. The shell-native
- *  small-model graduation target and P1 anchoring-A/B arm. */
-const BASH_PLUS = new Set(['Bash', 'Read', 'Edit', 'Write', ...ALWAYS_KEEP]);
+ *  small-model graduation target and P1 anchoring-A/B arm.
+ *  ReadImage rides the practical doors (item 7): the orchestrator's VISION
+ *  GATE strips it for non-vision cards BEFORE profile filtering, so set
+ *  membership changes nothing for existing text-only frames — a vision card
+ *  under a narrow door gets door+ReadImage (the vision-arm shape). */
+const BASH_PLUS = new Set(['Bash', 'Read', 'Edit', 'Write', 'ReadImage', ...ALWAYS_KEEP]);
 /** bash-edit: the dsh-Minimal shape — shell + structural editor ONLY (their
  *  bash + str_replace_editor). The deepseek home-door candidate. */
-const BASH_EDIT = new Set(['Bash', 'Edit', ...ALWAYS_KEEP]);
+const BASH_EDIT = new Set(['Bash', 'Edit', 'ReadImage', ...ALWAYS_KEEP]);
 export function resolveToolProfile(env = process.env) {
     const raw = (env.CORTEX_TOOL_PROFILE ?? 'full').trim().toLowerCase();
     if (raw === 'lean' || raw === 'bash-only' || raw === 'bash-plus' || raw === 'bash-edit')
@@ -58,6 +62,25 @@ export function resolveToolAnchor(env = process.env, cardAnchor) {
         return card;
     return null;
 }
+/**
+ * CORTEX_TOOL_ANCHOR_PERSIST — frame selection for an armed anchor (backlog
+ * item 5). 'lifted' (default): the anchor lifts at the first tool_result
+ * boundary and the session's full profile applies. 'persist': the anchored
+ * surface stays the ONLY surface for the whole session (the TB2 persist
+ * frame, previously an installed-copy patch). Precedence: env override >
+ * card frameProfile > 'lifted'. Irrelevant when no anchor is armed.
+ */
+export function resolveFrameProfile(env = process.env, cardFrame) {
+    const raw = (env.CORTEX_TOOL_ANCHOR_PERSIST ?? '').trim().toLowerCase();
+    if (raw === 'true' || raw === '1' || raw === 'persist')
+        return 'persist';
+    if (raw === 'false' || raw === '0' || raw === 'off' || raw === 'lifted')
+        return 'lifted';
+    const card = (cardFrame ?? '').trim().toLowerCase();
+    if (card === 'persist')
+        return 'persist';
+    return 'lifted';
+}
 /** Do MCP / management / context tools ride along? Narrow arms suppress them
  *  (surface leak otherwise); full and lean keep them. */
 export function isNarrowProfile(profile = resolveToolProfile()) {

package/dist/tools/ToolProfile.js.map

@@ -1 +1 @@
-{"version":3,"file":"ToolProfile.js","sourceRoot":"","sources":["../../src/tools/ToolProfile.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ToolProfile.js","sourceRoot":"","sources":["../../src/tools/ToolProfile.ts"],"names":[],"mappings":"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"}

package/dist/tools/registries/BaseToolRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BaseToolRegistry.d.ts","sourceRoot":"","sources":["../../../src/tools/registries/BaseToolRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAgnErG;;GAEG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;;IAS7D;;OAEG;IACH,WAAW,IAAI,uBAAuB,EAAE;IAIxC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS;IAI1D;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,uBAAuB,EAAE;IAIrE;;OAEG;IACH,YAAY,IAAI,MAAM;CAGvB;AAGD,eAAO,MAAM,gBAAgB,kBAAyB,CAAC"}
+{"version":3,"file":"BaseToolRegistry.d.ts","sourceRoot":"","sources":["../../../src/tools/registries/BaseToolRegistry.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,uBAAuB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAypErG;;GAEG;AACH,qBAAa,gBAAiB,YAAW,YAAY;IACnD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAuC;;IAS7D;;OAEG;IACH,WAAW,IAAI,uBAAuB,EAAE;IAIxC;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,uBAAuB,GAAG,SAAS;IAI1D;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI9B;;OAEG;IACH,kBAAkB,CAAC,QAAQ,EAAE,YAAY,GAAG,uBAAuB,EAAE;IAIrE;;OAEG;IACH,YAAY,IAAI,MAAM;CAGvB;AAGD,eAAO,MAAM,gBAAgB,kBAAyB,CAAC"}

package/dist/tools/registries/BaseToolRegistry.js

@@ -20,7 +20,7 @@ const BASE_TOOLS = [
 By default, it reads up to 2000 lines starting from the beginning of the file.
 When you already know which part of the file you need, only read that part. This can be important for larger files.
 Results are returned using cat -n format, with line numbers starting at 1.
-This tool can read images (PNG, JPG, etc), PDFs (.pdf — for large PDFs provide the pages parameter, max 20 pages per request), and Jupyter notebooks (.ipynb — returns all cells with outputs).
+This tool reads TEXT files. For images (PNG/JPG/GIF/WebP) use the ReadImage tool when available — Read on a binary file returns unusable bytes.
 Do NOT re-read a file you just edited to verify — Edit would have errored if the change failed, and the harness tracks file state for you.`,
         schema: {
             type: 'object',
@@ -113,6 +113,33 @@ GUIDANCE:
             version: '1.0.0'
         }
     },
+    {
+        name: 'ReadImage',
+        description: `Load an image file (PNG, JPEG, GIF, or WebP) so you can SEE it — the image is attached to the conversation as visual input on the next message. Use this to inspect screenshots, diagrams, charts, rendered output, or video frames (extract frames first, e.g. via ffmpeg).
+
+GUIDANCE:
+- Only available when the active model supports image input.
+- Format is detected from file content (magic bytes), not the extension.
+- Large images: the provider downscales (~800x800) — no need to resize first unless over the 32 MiB limit.
+- Unsupported formats (BMP/TIFF/PDF): convert first (e.g. Bash + Python PIL), then ReadImage.`,
+        schema: {
+            type: 'object',
+            properties: {
+                file_path: {
+                    type: 'string',
+                    description: 'Path to the image file (absolute, or relative to the working directory).'
+                }
+            },
+            required: ['file_path']
+        },
+        category: 'base',
+        discoveryTier: 'essential', // vision-gated; must be on TURN 1 (deferred loading hid it behind SearchTools — live-probe finding 2026-08-25),
+        metadata: {
+            immutable: true,
+            executionEnvironment: 'client',
+            version: '1.0.0'
+        }
+    },
     {
         name: 'Edit',
         description: `Performs exact string replacements in files.
@@ -950,6 +977,7 @@ Use plan mode for tasks with genuine ambiguity — multiple reasonable architect
 
 - citations: list EACH specific reference in your draft with the exact verbatim source you copied it from this turn. If you cannot produce the verbatim source, the reference is unverified — delete it from your answer and do not list it (quote the code instead of asserting a coordinate). Inventing one is a failed answer, exactly like a non-matching edit old_string.
 - verification: list each build/test/lint command you actually ran with the real result line you saw. Do not list a command you did not run.
+- requirements: re-read the ORIGINAL task statement and list each requirement it states, with what in your artifact satisfies it and the command/observation that proves it (or the literal "UNVERIFIED"). Finishing without checking the artifact against the stated task is the most common failed answer.
 - self_review: re-read your draft as a skeptical reviewer — what you did NOT check, what is assumed/possibly wrong, what one more tool call would verify. This pass exists to catch your own mistakes before they ship.
 - summary / open_items: what you delivered and any gaps — do not hide them.
 
@@ -981,6 +1009,19 @@ After EndTurn returns, act on your own self_review, then produce your final plai
                         required: ['command', 'observed_result']
                     }
                 },
+                requirements: {
+                    type: 'array',
+                    description: 'Each requirement STATED in the original task, checked against your artifact. Empty array = the turn had no stated task. verified_how is the command/observation proving the requirement is met, or the literal string "UNVERIFIED".',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            requirement: { type: 'string', description: 'A requirement as stated in the task.' },
+                            satisfied_by: { type: 'string', description: 'What in your artifact satisfies it.' },
+                            verified_how: { type: 'string', description: 'The command/observation that proves it — or "UNVERIFIED".' }
+                        },
+                        required: ['requirement', 'satisfied_by', 'verified_how']
+                    }
+                },
                 summary: {
                     type: 'string',
                     description: 'One sentence: what you delivered this turn.'