comisai 1.0.25 → 1.0.27

package/node_modules/@comis/agent/dist/executor/executor-response-filter.d.ts

@@ -44,16 +44,27 @@ export declare function scanWithOutputGuard(params: {
 /**
  * When the final assistant message is thinking-only or a
  * silent token (NO_REPLY, HEARTBEAT_OK) but text was emitted in earlier
- * turns, walk backward through session messages to find the last assistant
- * message that contained visible text blocks.
+ * turns, recover a meaningful user-visible response.
  *
- * Two-pass strategy:
- * 1. Backward walk skipping tool-call turns — finds the most recent
- *    standalone response (text-only, no toolCall/tool_use blocks).
- * 2. Forward walk from userMessageIndex including tool-call turns — finds
- *    the earliest pre-tool commentary, which is typically the framing
- *    response (e.g. "I'm going to build..."), not a late step annotation
- *    (e.g. "Step 4/4: sanity-testing...").
+ * Two-pass strategy (gated):
+ * 1. **Tool-call synthesis** (primary) — if ≥1 prior assistant turn within the
+ *    current execution window contains tool-call blocks, synthesize a
+ *    structured `[comis: tool-call summary recovered ...]` reply listing each
+ *    tool + primary identifying argument. This avoids surfacing earlier
+ *    planning prose ("let me plan this out before building...") AS the final
+ *    reply when the work was actually completed via tools.
+ * 2. **Standalone walk-backward** (fallback) — when zero prior tool calls were
+ *    collected (pure-conversational case), preserve the original behavior of
+ *    walking backward through messages to find the most recent assistant turn
+ *    with visible text-only content (no tool calls).
+ *
+ * The synthesis-gate (a single early-return — see `tool-call-synthesis-gate`
+ * comment below) ensures the standalone walk only fires when no tool calls
+ * were observed; this keeps the pass selection mutually exclusive.
+ *
+ * Suppressed when a delivery tool (`message`, `notify`) was used — the agent
+ * already delivered content via side-channel and the silent final token is
+ * intentional.
  *
  * Returns the recovered text, or the original response if no recovery needed.
  */
@@ -81,11 +92,3 @@ export declare function extractExecutionPlan(params: {
     eventBus: TypedEventBus;
     logger: ComisLogger;
 }): ExecutionPlan | undefined;
-/**
- * Generate a completeness nudge when the LLM stopped but steps remain.
- * Returns the nudge text or undefined if no nudge is needed.
- */
-export declare function generateCompletenessNudge(params: {
-    plan: ExecutionPlan;
-    verificationNudge: boolean;
-}): string | undefined;

package/node_modules/@comis/agent/dist/executor/executor-response-filter.js

@@ -13,7 +13,6 @@
  * @module
  */
 import { extractPlanFromResponse } from "../planner/plan-extractor.js";
-import { formatChecklistForInjection } from "../planner/checklist-formatter.js";
 import { stripReasoningTagsFromText } from "../response-filter/reasoning-tags.js";
 import { isVisibleTextBlock } from "./phase-filter.js";
 /**
@@ -93,16 +92,27 @@ const DELIVERY_TOOL_NAMES = ["message", "notify"];
 /**
  * When the final assistant message is thinking-only or a
  * silent token (NO_REPLY, HEARTBEAT_OK) but text was emitted in earlier
- * turns, walk backward through session messages to find the last assistant
- * message that contained visible text blocks.
+ * turns, recover a meaningful user-visible response.
  *
- * Two-pass strategy:
- * 1. Backward walk skipping tool-call turns — finds the most recent
- *    standalone response (text-only, no toolCall/tool_use blocks).
- * 2. Forward walk from userMessageIndex including tool-call turns — finds
- *    the earliest pre-tool commentary, which is typically the framing
- *    response (e.g. "I'm going to build..."), not a late step annotation
- *    (e.g. "Step 4/4: sanity-testing...").
+ * Two-pass strategy (gated):
+ * 1. **Tool-call synthesis** (primary) — if ≥1 prior assistant turn within the
+ *    current execution window contains tool-call blocks, synthesize a
+ *    structured `[comis: tool-call summary recovered ...]` reply listing each
+ *    tool + primary identifying argument. This avoids surfacing earlier
+ *    planning prose ("let me plan this out before building...") AS the final
+ *    reply when the work was actually completed via tools.
+ * 2. **Standalone walk-backward** (fallback) — when zero prior tool calls were
+ *    collected (pure-conversational case), preserve the original behavior of
+ *    walking backward through messages to find the most recent assistant turn
+ *    with visible text-only content (no tool calls).
+ *
+ * The synthesis-gate (a single early-return — see `tool-call-synthesis-gate`
+ * comment below) ensures the standalone walk only fires when no tool calls
+ * were observed; this keeps the pass selection mutually exclusive.
+ *
+ * Suppressed when a delivery tool (`message`, `notify`) was used — the agent
+ * already delivered content via side-channel and the silent final token is
+ * intentional.
  *
  * Returns the recovered text, or the original response if no recovery needed.
  */
@@ -124,8 +134,55 @@ export function recoverEmptyFinalResponse(params) {
                 return extractedResponse;
             }
             /* eslint-disable @typescript-eslint/no-explicit-any */
-            // Pass 1: backward walk — prefer the most recent standalone response
-            // (assistant turns that have text but NO tool call blocks)
+            // Collect tool-call summaries from prior assistant turns within the
+            // current execution window (lowerBound .. messages.length).
+            //
+            // Note: blocks with non-string `name` are still summarized (the helper
+            // renders them as "unknown_tool") but are NOT added to `toolNamesSet`.
+            // Consequence: a batch of purely malformed blocks emits `toolNames: []`
+            // in the INFO log while `toolCallCount` reflects the bullet count. This
+            // is intentional — `toolNames` is a deduplicated set of well-typed
+            // identifiers for log aggregation, not a per-bullet identifier list.
+            const toolCallSummaries = [];
+            const toolNamesSet = new Set();
+            for (let i = lowerBound; i < messages.length; i++) {
+                const msg = messages[i]; // eslint-disable-line security/detect-object-injection
+                if (msg?.role !== "assistant" || !Array.isArray(msg.content))
+                    continue;
+                for (const block of msg.content) {
+                    if (block?.type === "toolCall" || block?.type === "tool_use") {
+                        toolCallSummaries.push(summarizeToolCall(block));
+                        // Only well-typed names enter the set — malformed blocks are still
+                        // summarized as "unknown_tool" but excluded from toolNames.
+                        if (typeof block?.name === "string")
+                            toolNamesSet.add(block.name);
+                    }
+                }
+            }
+            // Synthesis-only-when-tool-calls contract (grep anchor: "tool-call-synthesis-gate"):
+            // Returning here is the ONE place that prevents the `standalone` walk-backward
+            // (below) from ever firing alongside synthesis. Do not add code paths
+            // that fall through to standalone after toolCallSummaries are non-empty.
+            if (toolCallSummaries.length > 0) {
+                const bullets = toolCallSummaries.map(s => `  • ${s}`).join("\n");
+                const synthesis = `[comis: tool-call summary recovered from successful operations — the assistant's final message was empty]\n` +
+                    `Completed ${toolCallSummaries.length} tool call${toolCallSummaries.length === 1 ? "" : "s"} in this batch:\n` +
+                    `${bullets}\n` +
+                    `The work was done; the assistant did not summarize. Please ask "what did you do?" if details are needed.`;
+                logger.info({
+                    module: "agent.executor.empty-turn-recovery",
+                    recoveryPass: "tool-call-synthesis",
+                    toolCallCount: toolCallSummaries.length,
+                    toolNames: [...toolNamesSet],
+                    synthesisLength: synthesis.length,
+                    hint: "Final assistant message was empty after tool batch; synthesized completion summary from tool-call history.",
+                }, "Empty-turn recovery: synthesized from tool-call history");
+                return synthesis; // tool-call-synthesis-gate — see comment above.
+            }
+            // Standalone walk-backward (pure-conversational fallback): reachable
+            // ONLY when toolCallSummaries.length === 0, guaranteed by the early-
+            // return above. Do NOT wrap in an additional conditional — the single
+            // gate above is the contract anchor.
             for (let i = messages.length - 1; i >= lowerBound; i--) {
                 const msg = messages[i]; // eslint-disable-line security/detect-object-injection
                 if (msg?.role === "assistant" && Array.isArray(msg.content)) {
@@ -145,25 +202,6 @@ export function recoverEmptyFinalResponse(params) {
                     }
                 }
             }
-            // Pass 2: forward walk — fall back to the earliest pre-tool commentary.
-            // Walking forward prefers the framing/introduction message over late
-            // step annotations (e.g. "I'm going to build..." over "Step 4/4: ...").
-            for (let i = lowerBound; i < messages.length; i++) {
-                const msg = messages[i]; // eslint-disable-line security/detect-object-injection
-                if (msg?.role === "assistant" && Array.isArray(msg.content)) {
-                    const recovered = extractVisibleText(msg.content);
-                    if (recovered) {
-                        logger.info({
-                            hint: "Final assistant message was empty or silent-token-only; recovered pre-tool commentary from earlier turn",
-                            errorKind: "transient",
-                            turnIndex: i,
-                            recoveredLength: recovered.length,
-                            recoveryPass: "pre-tool-commentary",
-                        }, "recovered visible text from earlier turn");
-                        return recovered;
-                    }
-                }
-            }
             /* eslint-enable @typescript-eslint/no-explicit-any */
         }
     }
@@ -205,6 +243,69 @@ function hasDeliveryToolCall(messages, lowerBound) {
     return false;
 }
 /* eslint-enable @typescript-eslint/no-explicit-any */
+/** Summarize a single tool-call content block as `toolName({primary_arg: "value"})`.
+ *  Reads `name` from the block, and `input` (Anthropic native) or `arguments`
+ *  (internal mapped convention) for args. Returns bare tool name on malformed
+ *  input — never throws. */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+function summarizeToolCall(call) {
+    const name = typeof call?.name === "string" ? call.name : "unknown_tool";
+    // Both Anthropic native (`input`) and internal mapped (`arguments`) shapes.
+    const args = (call?.input && typeof call.input === "object" ? call.input : undefined) ??
+        (call?.arguments && typeof call.arguments === "object" ? call.arguments : undefined);
+    if (!args)
+        return name;
+    switch (name) {
+        case "agents_manage": {
+            const action = typeof args.action === "string" ? args.action : undefined;
+            const agentId = typeof args.agent_id === "string" ? args.agent_id : undefined;
+            if (action && agentId)
+                return `agents_manage.${action}({agent_id: "${agentId}"})`;
+            if (action)
+                return `agents_manage.${action}`;
+            return "agents_manage";
+        }
+        case "write":
+        case "edit":
+        case "read": {
+            const p = typeof args.path === "string" ? args.path : undefined;
+            return p ? `${name}({path: "${p}"})` : name;
+        }
+        case "gateway": {
+            const action = typeof args.action === "string" ? args.action : undefined;
+            const section = typeof args.section === "string" ? args.section : undefined;
+            if (action && section)
+                return `gateway({action: "${action}", section: "${section}"})`;
+            if (action)
+                return `gateway({action: "${action}"})`;
+            return "gateway";
+        }
+        case "exec": {
+            const cmd = typeof args.command === "string" ? args.command : undefined;
+            if (cmd) {
+                const preview = cmd.length > 60 ? `${cmd.slice(0, 60)}…` : cmd;
+                return `exec({command: "${preview}"})`;
+            }
+            return "exec";
+        }
+        case "pipeline": {
+            const pname = typeof args.name === "string" ? args.name : undefined;
+            return pname ? `pipeline({name: "${pname}"})` : "pipeline";
+        }
+        case "sessions_spawn": {
+            const agentId = typeof args.agent_id === "string" ? args.agent_id : undefined;
+            return agentId ? `sessions_spawn({agent_id: "${agentId}"})` : "sessions_spawn";
+        }
+        case "message":
+        case "notify": {
+            const action = typeof args.action === "string" ? args.action : undefined;
+            return action ? `${name}({action: "${action}"})` : name;
+        }
+        default:
+            return name;
+    }
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
 // ---------------------------------------------------------------------------
 // SEP plan extraction (extracted from execute() success path)
 // ---------------------------------------------------------------------------
@@ -221,7 +322,6 @@ export function extractExecutionPlan(params) {
             request: messageText.slice(0, 200),
             steps,
             completedCount: 0,
-            nudged: false,
             createdAtMs: Date.now(),
         };
         logger.info({ agentId, stepCount: steps.length, durationMs: Date.now() - executionStartMs }, "SEP plan extracted");
@@ -235,23 +335,3 @@ export function extractExecutionPlan(params) {
     }
     return undefined;
 }
-// ---------------------------------------------------------------------------
-// SEP completeness nudge (extracted from execute() success path)
-// ---------------------------------------------------------------------------
-/**
- * Generate a completeness nudge when the LLM stopped but steps remain.
- * Returns the nudge text or undefined if no nudge is needed.
- */
-export function generateCompletenessNudge(params) {
-    const { plan, verificationNudge } = params;
-    if (!plan.active || plan.nudged)
-        return undefined;
-    const remaining = plan.steps.filter(s => s.status === "pending" || s.status === "in_progress");
-    if (remaining.length > 0 && plan.completedCount > 0) {
-        const checklist = formatChecklistForInjection(plan, verificationNudge);
-        return checklist
-            ? `${checklist}\n\nPlease continue with the remaining steps. If any step is no longer needed, explain why.`
-            : `You indicated completion but ${remaining.length} step(s) remain:\n${remaining.map(s => `- ${s.description}`).join("\n")}\nPlease continue. If these steps are no longer needed, explain why.`;
-    }
-    return undefined;
-}

package/node_modules/@comis/agent/dist/executor/executor-tool-assembly.js

@@ -15,7 +15,7 @@
  */
 import { SettingsManager, } from "@mariozechner/pi-coding-agent";
 import { formatSessionKey, } from "@comis/core";
-import { applyToolDeferral, buildDeferredToolsContext, createDiscoverTool, createAutoDiscoveryStubs, extractRecentlyUsedToolNames, resolveModelTier, CORE_TOOLS } from "./tool-deferral.js";
+import { applyToolDeferral, buildDeferredToolsContext, createDiscoverTool, createAutoDiscoveryStubs, extractRecentlyUsedToolNames, resolveModelTier, supportsToolSearch, CORE_TOOLS } from "./tool-deferral.js";
 import { getOrCreateDiscoveryTracker } from "./discovery-tracker.js";
 import { getOrCreateTracker, DEFAULT_LIFECYCLE_CONFIG } from "./tool-lifecycle.js";
 import { isAnthropicFamily, isGoogleFamily } from "../provider/capabilities.js";
@@ -320,10 +320,23 @@ export async function assembleTools(params) {
         const stubs = createAutoDiscoveryStubs(deferralResult.deferredEntries, discoveryTracker, deps.logger);
         mergedCustomTools.push(...stubs);
     }
-    // Build deferred context for dynamic preamble injection
+    // Build deferred context for dynamic preamble injection.
+    //
+    // 260428-oyc: under Anthropic Sonnet/Opus 4.x, request-body-injector.ts
+    // strips client-side `discover_tools` from the API payload and replaces it
+    // with the server-side `tool_search_tool_regex` + per-tool `defer_loading`
+    // flag. Pass `useToolSearch=true` so the preamble teaches the model that
+    // deferred tools auto-load on first direct invocation, rather than telling
+    // it to call a tool the model can no longer see.
+    //
+    // resolvedModel is in scope here (param of assembleToolsForAgent, see
+    // function signature ~line 143). When undefined (test paths / fallback),
+    // useToolSearch defaults to false, preserving backward-compatible
+    // discover_tools wording.
     let deferredContext = "";
     if (deferralResult.deferredEntries.length > 0) {
-        deferredContext = buildDeferredToolsContext(deferralResult.deferredEntries);
+        const useToolSearch = supportsToolSearch(resolvedModel?.id ?? "");
+        deferredContext = buildDeferredToolsContext(deferralResult.deferredEntries, { useToolSearch });
     }
     // -------------------------------------------------------------------
     // 8. JIT guide wrapping, schema pruning, snapshot, normalization, serializer

package/node_modules/@comis/agent/dist/executor/model-retry.d.ts

@@ -29,6 +29,7 @@ import type { TypedEventBus } from "@comis/core";
 import type { ComisLogger } from "@comis/infra";
 import type { AuthRotationAdapter } from "../model/auth-rotation-adapter.js";
 import type { ProviderHealthMonitor } from "../safety/provider-health-monitor.js";
+import type { LastKnownModelTracker } from "../model/last-known-model.js";
 /** Parameters for the model failover pipeline (auth rotation + model fallback). */
 export interface ModelRetryParams {
     session: AgentSession;
@@ -54,6 +55,8 @@ export interface ModelRetryParams {
         sessionKey?: string;
         /** Optional provider health monitor for failure aggregation. */
         providerHealth?: ProviderHealthMonitor;
+        /** Optional last-known-working model tracker for auth-failure fallback. */
+        lastKnownModel?: LastKnownModelTracker;
         /** Callback to receive the resetTimer function from the resettable prompt timeout. */
         onResetTimer?: (resetFn: () => void) => void;
     };
@@ -62,6 +65,11 @@ export interface ModelRetryParams {
 export interface ModelRetryResult {
     succeeded: boolean;
     error?: unknown;
+    /** The model that ultimately succeeded (primary, fallback, or LKW). */
+    effectiveModel?: {
+        provider: string;
+        model: string;
+    };
 }
 /**
  * Parse a "provider:modelId" string into provider and modelId components.
@@ -71,6 +79,12 @@ export declare function parseModelString(modelStr: string): {
     provider: string;
     modelId: string;
 } | undefined;
+/**
+ * Check whether an error is an authentication/authorization failure (401/403).
+ * Used to gate the last-known-working model fallback -- LKW only fires for
+ * auth errors, not for rate limits or transient failures.
+ */
+export declare function isAuthError(error: unknown): boolean;
 /**
  * Execute a prompt with auth rotation and model failover.
  *

package/node_modules/@comis/agent/dist/executor/model-retry.js

@@ -98,6 +98,23 @@ function parseRetryAfterMs(error) {
     return null;
 }
 // ---------------------------------------------------------------------------
+// Auth error detection
+// ---------------------------------------------------------------------------
+/**
+ * Check whether an error is an authentication/authorization failure (401/403).
+ * Used to gate the last-known-working model fallback -- LKW only fires for
+ * auth errors, not for rate limits or transient failures.
+ */
+export function isAuthError(error) {
+    const status = getErrorStatus(error);
+    if (status === 401 || status === 403)
+        return true;
+    if (error instanceof Error) {
+        return /invalid.?api.?key|authentication|unauthorized|401|403|permission.?denied/i.test(error.message);
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
 // Main function
 // ---------------------------------------------------------------------------
 /**
@@ -122,6 +139,7 @@ export async function runWithModelRetry(params) {
     const maxRetries = 1 + (authRotation?.hasProfiles(config.provider) ? 1 : 0) + fallbackModels.length;
     let promptError = undefined;
     let promptSucceeded = false;
+    let effectiveModel;
     try {
         // Primary prompt uses resettable timeout so tool completions can reset the
         // deadline. Retry/fallback paths use the original withPromptTimeout (fresh timeout).
@@ -133,6 +151,7 @@ export async function runWithModelRetry(params) {
         deps.onResetTimer?.(resettable.resetTimer);
         await resettable.promise;
         promptSucceeded = true;
+        effectiveModel = { provider: config.provider, model: config.model };
         // Record success for auth rotation cooldown tracking
         if (authRotation?.hasProfiles(config.provider)) {
             authRotation.recordSuccess(config.provider);
@@ -174,6 +193,7 @@ export async function runWithModelRetry(params) {
                         await withPromptTimeout(session.prompt(messageText, { expandPromptTemplates: false, images: promptImages }), timeoutConfig.retryPromptTimeoutMs, () => session.abort());
                         promptSucceeded = true;
                         promptError = undefined;
+                        effectiveModel = { provider: config.provider, model: config.model };
                         // Record success for auth rotation tracking
                         if (authRotation?.hasProfiles(config.provider)) {
                             authRotation.recordSuccess(config.provider);
@@ -198,6 +218,7 @@ export async function runWithModelRetry(params) {
                     await withPromptTimeout(session.prompt(messageText, { expandPromptTemplates: false, images: promptImages }), timeoutConfig.retryPromptTimeoutMs, () => session.abort());
                     promptSucceeded = true;
                     promptError = undefined;
+                    effectiveModel = { provider: config.provider, model: config.model };
                     authRotation.recordSuccess(config.provider);
                     logger.info({ provider: config.provider }, "Retry with rotated key succeeded");
                 }
@@ -257,6 +278,9 @@ export async function runWithModelRetry(params) {
                 }), timeoutConfig.retryPromptTimeoutMs, () => session.abort());
                 promptSucceeded = true;
                 promptError = undefined;
+                if (parsed) {
+                    effectiveModel = { provider: parsed.provider, model: parsed.modelId };
+                }
                 logger.info({ fallbackModel: fallbackModelStr }, "Fallback model succeeded");
                 break;
             }
@@ -296,6 +320,53 @@ export async function runWithModelRetry(params) {
                 timestamp: Date.now(),
             });
         }
+        // Last-known-working model fallback: when all configured models fail
+        // with an auth error, try a model that recently succeeded somewhere
+        // on this daemon (per-agent first, then daemon-wide from a different provider).
+        if (!promptSucceeded && isAuthError(promptError) && deps.lastKnownModel) {
+            const lkw = deps.lastKnownModel.getLastKnown(deps.agentId ?? "") ??
+                deps.lastKnownModel.getAnyKnown(config.provider);
+            if (lkw && (lkw.provider !== config.provider || lkw.model !== config.model)) {
+                eventBus.emit("model:lkw_fallback_attempt", {
+                    fromProvider: config.provider,
+                    fromModel: config.model,
+                    toProvider: lkw.provider,
+                    toModel: lkw.model,
+                    timestamp: Date.now(),
+                });
+                logger.info({ lkwProvider: lkw.provider, lkwModel: lkw.model }, "Attempting last-known-working model fallback");
+                try {
+                    const normalizedLkw = normalizeModelId(lkw.provider, lkw.model);
+                    const lkwModelObj = modelRegistry.find(lkw.provider, normalizedLkw.modelId);
+                    if (lkwModelObj) {
+                        await session.setModel(lkwModelObj);
+                    }
+                    await withPromptTimeout(session.prompt(messageText, {
+                        expandPromptTemplates: false,
+                        images: promptImages,
+                    }), timeoutConfig.retryPromptTimeoutMs, () => session.abort());
+                    promptSucceeded = true;
+                    promptError = undefined;
+                    effectiveModel = { provider: lkw.provider, model: lkw.model };
+                    eventBus.emit("model:lkw_fallback_succeeded", {
+                        provider: lkw.provider,
+                        model: lkw.model,
+                        timestamp: Date.now(),
+                    });
+                    logger.info({ lkwProvider: lkw.provider, lkwModel: lkw.model }, "Last-known-working model fallback succeeded");
+                }
+                catch (lkwError) {
+                    promptError = lkwError;
+                    logger.warn({
+                        err: lkwError,
+                        lkwProvider: lkw.provider,
+                        lkwModel: lkw.model,
+                        hint: "Last-known-working model also failed",
+                        errorKind: "dependency",
+                    }, "Last-known-working model fallback failed");
+                }
+            }
+        }
     }
-    return { succeeded: promptSucceeded, error: promptError };
+    return { succeeded: promptSucceeded, error: promptError, effectiveModel };
 }

package/node_modules/@comis/agent/dist/executor/pi-executor.d.ts

@@ -85,6 +85,8 @@ export interface PiExecutorDeps {
     circuitBreaker: CircuitBreaker;
     /** Optional provider health monitor for cross-agent pre-check. */
     providerHealth?: ProviderHealthMonitor;
+    /** Optional last-known-working model tracker for auth-failure fallback. */
+    lastKnownModel?: import("../model/last-known-model.js").LastKnownModelTracker;
     budgetGuard: BudgetGuard;
     costTracker: CostTracker;
     stepCounter: StepCounter;
@@ -92,6 +94,7 @@ export interface PiExecutorDeps {
     logger: ComisLogger;
     authStorage: AuthStorage;
     modelRegistry: ModelRegistry;
+    providerAliases?: Map<string, string>;
     sessionAdapter: ComisSessionManager;
     workspaceDir: string;
     customTools: ToolDefinition[];

package/node_modules/@comis/agent/dist/executor/pi-executor.js

@@ -30,6 +30,7 @@ import { createMessageSendLimiter } from "../safety/message-send-limiter.js";
 import { repairOrphanedMessages, scrubPoisonedThinkingBlocks } from "../session/orphaned-message-repair.js";
 import { scrubRedactedToolCalls } from "../session/scrub-redacted-tool-calls.js";
 import { createPiEventBridge } from "../bridge/pi-event-bridge.js";
+import { assertThinkingBlocksUnchanged, restoreCanonicalThinkingBlocks } from "../bridge/thinking-block-hash-invariant.js";
 import { createAdaptiveCacheRetention, createStaticRetention } from "./adaptive-cache-retention.js";
 // SessionLatch types and createSessionLatch moved to executor-session-state.ts
 import { createContextWindowGuard } from "../safety/context-window-guard.js";
@@ -47,9 +48,7 @@ import { getDeliveredGuides, setDeliveredGuides, setBreakpointIndex,
 // deleteBreakpointIndex, getBreakpointIndexMapSize moved to executor-post-execution.ts
 setCacheWarm, clearSessionCacheWarm, clearSessionLatches, getCacheBreakDetector, setEvictionCooldown, decrementEvictionCooldown as decrementEvictionCooldownForSession, recordCacheSavings, getCacheSavings, clearSessionCacheSavings, } from "./executor-session-state.js";
 import { validateInput } from "./executor-input-guard.js";
-import { scanWithOutputGuard,
-// recoverEmptyFinalResponse, extractExecutionPlan, generateCompletenessNudge moved to executor-prompt-runner.ts
- } from "./executor-response-filter.js";
+import { scanWithOutputGuard } from "./executor-response-filter.js";
 import { normalizeModelCompat } from "../provider/model-compat.js";
 import { normalizeModelId } from "../provider/model-id-normalize.js";
 import { isAnthropicFamily, isGoogleFamily } from "../provider/capabilities.js";
@@ -321,15 +320,15 @@ export function createPiExecutor(config, deps) {
             // Apply per-node model override from ExecutionOverrides and normalize shortcuts before registry lookup
             const normalizedPrimary = normalizeModelId(config.provider, config.model);
             let resolvedModel = deps.modelRegistry.find(config.provider, normalizedPrimary.modelId);
+            if (!resolvedModel && deps.providerAliases) {
+                const builtInName = deps.providerAliases.get(config.provider);
+                if (builtInName) {
+                    resolvedModel = deps.modelRegistry.find(builtInName, normalizedPrimary.modelId);
+                }
+            }
             if (normalizedPrimary.normalized) {
                 deps.logger.debug({ original: config.model, resolved: normalizedPrimary.modelId }, "Model ID normalized via shortcut");
             }
-            // Surface the silent-fallback case where pi-coding-agent picks a different
-            // provider than the user configured. When find() returns undefined for an
-            // explicit (non-default) provider/model, pi will silently shop `findInitialModel`
-            // and pick whatever built-in has env-var auth -- e.g., GEMINI_API_KEY → google.
-            // The wiring fix in setup-agents.ts should cover the YAML-provider case; this
-            // log catches stragglers (typos, disabled providers, missing API keys).
             if (!resolvedModel
                 && config.provider.toLowerCase() !== "default"
                 && config.model.toLowerCase() !== "default") {
@@ -836,6 +835,65 @@ export function createPiExecutor(config, deps) {
                             timestamp: Date.now(),
                         };
                     },
+                    // 260428-hoy: pre-LLM-call hook -- runs once per `turn_start`,
+                    // BEFORE pi-ai serializes the next request. Asserts the
+                    // cross-turn hash invariant (logs ERROR per mutated block, with
+                    // module:"agent.bridge.hash-invariant"), then heals any mutated
+                    // thinking blocks against the canonical stream-close snapshot
+                    // and writes the healed array back into session.agent.state.messages
+                    // so persistence and downstream layers see the same shape pi-ai
+                    // serializes. Order matters: assert FIRST so the diagnostic
+                    // captures every mutation before the heal overwrites it. Both
+                    // helpers swallow throws internally; the outer try/catch is a
+                    // belt-and-braces fallback -- the pre-call hook must NEVER abort
+                    // agent flow.
+                    getSessionMessages: () => {
+                        const live = session.agent.state.messages;
+                        if (!Array.isArray(live))
+                            return live;
+                        try {
+                            const stores = bridge.getThinkingBlockStores();
+                            if (stores.hashes.size > 0) {
+                                for (const sessMsg of live) {
+                                    if (!sessMsg || typeof sessMsg !== "object")
+                                        continue;
+                                    const sm = sessMsg;
+                                    if (sm.role !== "assistant")
+                                        continue;
+                                    if (typeof sm.responseId !== "string")
+                                        continue;
+                                    const prior = stores.hashes.get(sm.responseId);
+                                    if (!prior)
+                                        continue;
+                                    const currentContent = Array.isArray(sm.content)
+                                        ? sm.content
+                                        : [];
+                                    assertThinkingBlocksUnchanged(prior, currentContent, sm.responseId, {
+                                        logger: deps.logger,
+                                    });
+                                }
+                            }
+                            if (stores.canonical.size > 0) {
+                                const result = restoreCanonicalThinkingBlocks(live, stores.canonical, { logger: deps.logger });
+                                if (result.restoredCount > 0) {
+                                    // eslint-disable-next-line @typescript-eslint/no-explicit-any -- SDK interop boundary; healed array preserves AgentMessage shape
+                                    session.agent.state.messages = result.messages;
+                                    return result.messages;
+                                }
+                            }
+                        }
+                        catch {
+                            // Pre-call hook must NEVER abort agent flow.
+                        }
+                        return live;
+                    },
+                    // 260428-iag wire-edge diagnostic: resolves the per-session JSONL
+                    // path on demand. The bridge invokes this only after detecting the
+                    // signed-replay rejection signature on a 400 — never on the happy
+                    // path. Path comes from the same sessionAdapter that already
+                    // governs read/write of the file, so safePath / sessionKey routing
+                    // is reused (sessionKeyToPath -> safePath under the hood).
+                    getSessionJsonlPath: () => sessionAdapter.getSessionPath(sessionKey),
                     // Budget trajectory warning: shared ref and per-execution cap
                     perExecutionBudgetCap: config.budgets?.perExecution,
                     budgetWarningRef,
@@ -961,6 +1019,7 @@ export function createPiExecutor(config, deps) {
                             fallbackModels: deps.fallbackModels,
                             modelRegistry: deps.modelRegistry,
                             providerHealth: deps.providerHealth,
+                            lastKnownModel: deps.lastKnownModel,
                             envelopeConfig: deps.envelopeConfig,
                             outputGuard: deps.outputGuard,
                             canaryToken: deps.canaryToken,