@code-yeongyu/senpi 2026.11.2-3 → 2026.11.3-2

package/dist/core/retry-fallback/controller.d.ts

@@ -41,6 +41,8 @@ export declare class RetryFallbackController {
      * original is not is never where the session rests (senpi#2376). An original that is
      * itself still held (an account usage limit with the reset it named, which can outlast
      * the circuit's 30-minute ceiling) is not restored before that hold ends (senpi#3347).
+     * At a turn boundary, a changed credential on the original's provider first releases
+     * its billing pin and parks (senpi#4099).
      */
     maybeRestorePrimary(revertPolicy: "cooldown-expiry" | "never", boundary?: "turn" | "continuation"): Promise<boolean>;
     private originalRecovered;

package/dist/core/retry-fallback/controller.js

@@ -4,6 +4,7 @@ import { firstUsableCandidate } from "./candidates.js";
 import { baseSelector, canonicalizeFallbackChains, formatSelector, parseFallbackSelector, resolveChainKey, rungSelector, } from "./chains.js";
 import { subscribeProviderAccountEvents } from "../extensions/builtin/anthropic-subscription/account-events.js";
 import { CircuitProbes } from "./circuit-probes.js";
+import { releaseOnCredentialChange } from "./credential-recovery.js";
 import { pinAfterSwitch } from "./pin.js";
 import { isPureNetworkTransient } from "./transient-network.js";
 import { UnusableEntries } from "./unusable.js";
@@ -81,6 +82,8 @@ export class RetryFallbackController {
      * original is not is never where the session rests (senpi#2376). An original that is
      * itself still held (an account usage limit with the reset it named, which can outlast
      * the circuit's 30-minute ceiling) is not restored before that hold ends (senpi#3347).
+     * At a turn boundary, a changed credential on the original's provider first releases
+     * its billing pin and parks (senpi#4099).
      */
     async maybeRestorePrimary(revertPolicy, boundary = "turn") {
         const heldForNetworkBlip = this.heldForNetworkBlip && boundary === "continuation";
@@ -88,14 +91,16 @@ export class RetryFallbackController {
             this.heldForNetworkBlip = false;
         const state = this.state;
         const current = this.deps.getCurrentSelector();
-        if (!state || state.pinned || !current)
+        if (!state || !current)
             return false;
         const selector = parseFallbackSelector(state.originalSelector, this.deps.registry);
-        if (!selector || !this.deps.isAuthAvailable(selector.provider))
-            return false;
-        const model = this.deps.registry.find(selector.provider, selector.id);
+        const model = selector && this.deps.registry.find(selector.provider, selector.id);
         if (!model)
             return false;
+        if (boundary === "turn")
+            await releaseOnCredentialChange(state, model, this.deps, this.unusable);
+        if (state.pinned || !this.deps.isAuthAvailable(model.provider))
+            return false;
         const stranded = this.unusable.isUnusable(current.model) && !this.unusable.isUnusable(model);
         if (!stranded &&
             (heldForNetworkBlip || this.unusable.isUnusable(model) || !this.originalRecovered(state, revertPolicy)))
@@ -313,7 +318,11 @@ export class RetryFallbackController {
         const from = formatSelector(current.model);
         const to = formatSelector(candidate.model);
         const prior = this.state;
+        const recoveryRevision = prior
+            ? prior.recoveryRevision
+            : await this.deps.recoveryRevision?.(current.model.provider);
         this.state = {
+            ...(recoveryRevision === undefined ? {} : { recoveryRevision }),
             chainKey: candidate.chainKey,
             originalThinkingLevel: prior?.originalThinkingLevel ?? current.thinkingLevel,
             lastAppliedThinkingLevel: thinking,

package/dist/core/retry-fallback/credential-recovery.d.ts

@@ -0,0 +1,18 @@
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { ActiveFallbackState, RetryFallbackControllerDeps } from "./controller-types.ts";
+import type { UnusableEntries } from "./unusable.ts";
+type RecoveryDeps = Pick<RetryFallbackControllerDeps, "recoveryRevision" | "cooldowns" | "circuits" | "logger">;
+/**
+ * A billing pin assumes the original's account cannot recover by retrying it. A sign-in changes
+ * that account, so when the original provider's login id moved since the episode began, the
+ * billing pin and the original's cooldown, unusable mark and circuit are released and the
+ * existing revert path tries it once. A still-dead original falls back again and pins with the
+ * fresh id. This step reads the store at a turn boundary only while a billing pin holds; the
+ * other read is `applyCandidate` (controller.ts), once when an episode begins at its first
+ * fallback switch, to record the starting id. A token refresh keeps the id or drops it to "", and
+ * an id that is gone ("") is no sign-in, so neither releases. Refusal pins hold: a new credential
+ * does not change the context that was refused (senpi#4099).
+ */
+export declare function releaseOnCredentialChange(state: ActiveFallbackState, original: Model<Api>, deps: RecoveryDeps, unusable: UnusableEntries): Promise<void>;
+export {};
+//# sourceMappingURL=credential-recovery.d.ts.map

package/dist/core/retry-fallback/credential-recovery.js

@@ -0,0 +1,32 @@
+import { formatSelector } from "./chains.js";
+/**
+ * A billing pin assumes the original's account cannot recover by retrying it. A sign-in changes
+ * that account, so when the original provider's login id moved since the episode began, the
+ * billing pin and the original's cooldown, unusable mark and circuit are released and the
+ * existing revert path tries it once. A still-dead original falls back again and pins with the
+ * fresh id. This step reads the store at a turn boundary only while a billing pin holds; the
+ * other read is `applyCandidate` (controller.ts), once when an episode begins at its first
+ * fallback switch, to record the starting id. A token refresh keeps the id or drops it to "", and
+ * an id that is gone ("") is no sign-in, so neither releases. Refusal pins hold: a new credential
+ * does not change the context that was refused (senpi#4099).
+ */
+export async function releaseOnCredentialChange(state, original, deps, unusable) {
+    if (!state.pinnedByBilling || state.recoveryRevision === undefined || !deps.recoveryRevision)
+        return;
+    const revision = await deps.recoveryRevision(original.provider);
+    if (!revision || revision === state.recoveryRevision)
+        return;
+    state.recoveryRevision = revision;
+    state.pinnedByBilling = false;
+    state.pinned = state.pinnedByRefusal;
+    const selector = formatSelector(original);
+    deps.cooldowns.clearModel(selector);
+    unusable.clear(original);
+    deps.circuits?.close(selector);
+    deps.logger.info("credential_recovery_released", {
+        chainKey: state.chainKey,
+        originalSelector: state.originalSelector,
+        trigger: "sign-in",
+    });
+}
+//# sourceMappingURL=credential-recovery.js.map

package/dist/core/retry-fallback/exhaustion.d.ts

@@ -0,0 +1,18 @@
+import type { FallbackReason } from "./controller-types.ts";
+/** One chain rung that failed during a turn's fallback walk: the model it ran on and its provider error. */
+export interface FallbackRungFailure {
+    model: string;
+    reason: FallbackReason;
+    error: string;
+}
+/** Appends a rung failure unless it repeats the last one (one failure can be offered to the walk twice). */
+export declare function recordRungFailure(failures: FallbackRungFailure[], failure: FallbackRungFailure): void;
+/**
+ * The exhaustion text every surface shows: the failure that started the walk first, then each later rung
+ * (senpi#4084). Without recorded rungs it falls back to the last error, as older events carried only that.
+ */
+export declare function describeFallbackExhaustion(event: {
+    lastError: string;
+    failures?: readonly FallbackRungFailure[];
+}): string;
+//# sourceMappingURL=exhaustion.d.ts.map

package/dist/core/retry-fallback/exhaustion.js

@@ -0,0 +1,20 @@
+/** Appends a rung failure unless it repeats the last one (one failure can be offered to the walk twice). */
+export function recordRungFailure(failures, failure) {
+    const last = failures.at(-1);
+    if (last && last.model === failure.model && last.error === failure.error)
+        return;
+    failures.push(failure);
+}
+/**
+ * The exhaustion text every surface shows: the failure that started the walk first, then each later rung
+ * (senpi#4084). Without recorded rungs it falls back to the last error, as older events carried only that.
+ */
+export function describeFallbackExhaustion(event) {
+    const failures = event.failures ?? [];
+    if (failures.length === 0)
+        return event.lastError;
+    return failures
+        .map((failure, index) => `${index === 0 ? "" : "then "}${failure.model}: ${failure.error}`)
+        .join("\n");
+}
+//# sourceMappingURL=exhaustion.js.map

package/dist/core/retry-fallback/settings.d.ts

@@ -43,7 +43,14 @@ export interface ResolvedRetryFallbackSettings {
  * `claude-opus-4-8` or `claude-opus-4-6` (senpi#3727).
  */
 export declare const DEFAULT_FALLBACK_CHAINS: FallbackChains;
-export declare function resolveRetryFallbackSettings(settings: RetrySettings | undefined): ResolvedRetryFallbackSettings;
+/**
+ * `sessionPolicy`: the chains were supplied by the session's opener (`open_session.retryFallback`,
+ * `set_retry_fallback`), so they are the session's whole policy and the shipped defaults are not merged
+ * back under them (senpi#4673). Settings-file chains still layer over the defaults.
+ */
+export declare function resolveRetryFallbackSettings(settings: RetrySettings | undefined, options?: {
+    readonly sessionPolicy?: boolean;
+}): ResolvedRetryFallbackSettings;
 export declare function resolveAbortServerSideFallback(settings: RetrySettings | undefined): boolean;
 export declare const DEFAULT_HINTED_WAIT_CAP_MS = 300000;
 export declare const DEFAULT_PROBE_BACK_MAX_MS = 3600000;

package/dist/core/retry-fallback/settings.js

@@ -46,13 +46,14 @@ function isStringArray(value) {
  * Cross-scope replacement (global vs project) stays wholesale and is handled by
  * `deepMergeSettings`; this only resolves defaults against the merged result.
  */
-function resolveFallbackChains(value) {
+function resolveFallbackChains(value, sessionPolicy) {
+    const base = () => (sessionPolicy ? {} : cloneDefaultFallbackChains());
     if (value === undefined || !isPlainObject(value))
-        return cloneDefaultFallbackChains();
-    const chains = cloneDefaultFallbackChains();
+        return base();
+    const chains = base();
     for (const [key, entries] of Object.entries(value)) {
         if (!isStringArray(entries))
-            return cloneDefaultFallbackChains();
+            return base();
         // An empty list stays in the map as a tombstone: canonicalization needs it to
         // suppress the expanded default for that family or provider variant, and
         // dropping it here would let the shipped default reappear after expansion.
@@ -60,10 +61,15 @@ function resolveFallbackChains(value) {
     }
     return chains;
 }
-export function resolveRetryFallbackSettings(settings) {
+/**
+ * `sessionPolicy`: the chains were supplied by the session's opener (`open_session.retryFallback`,
+ * `set_retry_fallback`), so they are the session's whole policy and the shipped defaults are not merged
+ * back under them (senpi#4673). Settings-file chains still layer over the defaults.
+ */
+export function resolveRetryFallbackSettings(settings, options = {}) {
     return {
         modelFallback: typeof settings?.modelFallback === "boolean" ? settings.modelFallback : true,
-        chains: resolveFallbackChains(settings?.fallbackChains),
+        chains: resolveFallbackChains(settings?.fallbackChains, options.sessionPolicy === true),
         revertPolicy: settings?.fallbackRevertPolicy === "never" ? "never" : "cooldown-expiry",
     };
 }

package/dist/core/session-log.js

@@ -7,7 +7,7 @@ const DEFAULT_MAX_BYTES = 5 * 1024 * 1024;
 const MAX_STRING_LENGTH = 200;
 const DEBUG_PREFIX = `[${APP_NAME}-session]`;
 const BLOCKED_KEY = /^(?:__proto__|constructor|prototype|headers?|env(?:ironment)?|authorization|credential(?:s)?|password|secret|token|api_?key|client_?secret)$/i;
-const ALLOWED_DATA_KEY = /^(?:action|attemptId|disposition|stage|error|mode|count|willRetry|deferAdmission|delivered|restored|cause|accepted|skipped|rejectionCause|reason|durationMs|kind|retryable|phase|op|bytes|generation|requestId|tokens|tokensBefore|tokensAfter|contextWindow|attempt|aborted|sessionId|role|provider|model|source|actor|from|to|duringTurn|persistDefault|extension|handlerEvent|queuedId|ageMs)$/;
+const ALLOWED_DATA_KEY = /^(?:action|attemptId|disposition|stage|error|mode|count|willRetry|deferAdmission|delivered|restored|cause|accepted|skipped|rejectionCause|reason|durationMs|kind|retryable|phase|op|bytes|generation|requestId|tokens|tokensBefore|tokensAfter|contextWindow|attempt|aborted|sessionId|role|provider|model|source|actor|from|to|duringTurn|persistDefault|extension|handlerEvent|queuedId|ageMs|seat|until|shared)$/;
 const SENSITIVE_TEXT = /((?:authorization\s*[:=]\s*(?:bearer|basic)\s+)|(?:bearer\s+)|(?:[?&](?:api[_-]?key|token|secret|password|auth(?:orization)?)=))[^\s&,"'}\]]+/gi;
 export function createSessionLogger(agentDir, options = {}) {
     if (typeof agentDir !== "string" || agentDir.length === 0) {

package/dist/core/settings-manager.js

@@ -1285,7 +1285,10 @@ export class SettingsManager {
         return undefined;
     }
     getRetryFallbackSettings() {
-        return resolveRetryFallbackSettings(this.settings.retry);
+        // Chains in the session-only override layer (applyRetryFallbackProfile, or an SDK applyOverrides call) are the session's whole policy.
+        return resolveRetryFallbackSettings(this.settings.retry, {
+            sessionPolicy: this.runtimeOverrides.retry?.fallbackChains !== undefined,
+        });
     }
     getFallbackCircuitSettings() {
         return resolveFallbackCircuitSettings(this.settings.fallback);

package/dist/core/system-prompt.js

@@ -6,7 +6,7 @@ import { formatSkillsForPrompt } from "./skills.js";
 /** Contributions include eval-only tools even when the selected model-facing list does not. */
 export function getEvalOnlyGrepGuideline(selectedTools, toolSnippets) {
     return toolSnippets?.grep && !selectedTools.includes("grep")
-        ? "Search file contents with tool.grep({ pattern, path }) inside eval; prefer it over rg/grep in shell"
+        ? "Content search: tool.grep({ pattern, path }) in eval, not rg/grep in shell; page full -> skip, narrow with glob/path."
         : undefined;
 }
 const SYSTEM_PROMPT_SECTION_NAME = /^[a-z][a-z0-9_-]*$/;

package/dist/core/tools/bash.d.ts

@@ -1,5 +1,6 @@
 import type { AgentTool } from "@earendil-works/pi-agent-core";
 import { type Static, Type } from "typebox";
+import { type ShellTrust } from "../../engine-trust/shell-trust.ts";
 import { type ShellConfig } from "../../utils/shell.ts";
 import type { ToolDefinition } from "../extensions/types.ts";
 import { type TruncationResult } from "./truncate.ts";
@@ -9,7 +10,7 @@ declare const bashSchema: Type.TObject<{
 }>;
 export declare const bashToolSystemPromptContribution: {
     readonly snippet: "Execute bash commands (ls, rg, find, etc.)";
-    readonly guidelines: readonly ["You can inspect PI_* environment variables for current model and session details."];
+    readonly guidelines: readonly ["PI_* env vars = current model + session details."];
 };
 export type BashToolInput = Static<typeof bashSchema>;
 /**
@@ -27,6 +28,7 @@ export type BashToolOutput = Static<typeof bashOutputSchema>;
 export interface BashToolDetails {
     truncation?: TruncationResult;
     fullOutputPath?: string;
+    trust?: ShellTrust;
 }
 /**
  * Pluggable operations for the bash tool.

package/dist/core/tools/bash.js

@@ -4,6 +4,7 @@ import { access as fsAccess } from "node:fs/promises";
 import { constants as osConstants } from "node:os";
 import { spawn } from "child_process";
 import { Type } from "typebox";
+import { annotateShellTrust } from "../../engine-trust/shell-trust.js";
 import { waitForChildProcess } from "../../utils/child-process.js";
 import { getShellConfig, getShellEnv, killProcessTree, noteDetachedChildExited, pruneTrackedDetachedChildren, trackDetachedChildPid, } from "../../utils/shell.js";
 import { modelOnlyText } from "./model-only-text.js";
@@ -34,7 +35,7 @@ const bashSchema = Type.Object({
 });
 export const bashToolSystemPromptContribution = {
     snippet: "Execute bash commands (ls, rg, find, etc.)",
-    guidelines: ["You can inspect PI_* environment variables for current model and session details."],
+    guidelines: ["PI_* env vars = current model + session details."],
 };
 /**
  * Result for programmatic callers such as codemode scripts. A non-zero exit code is an error result for the model, but scripts still resolve to this value.
@@ -432,10 +433,19 @@ export function createShellToolDefinition(cwd, config, options) {
                     wall_time_seconds: wallTimeSeconds,
                 };
                 if (exitCode !== 0) {
+                    const text = appendStatus(outputText, `Command exited with code ${exitCode}`);
+                    // The engine trust annotation (omo#10762) rides only on error results, so the success
+                    // `outputSchema` (and the prompt bytes it costs) stays unchanged.
+                    const annotation = annotateShellTrust({ exitCode, output: fullOutput.content });
+                    if (annotation === undefined) {
+                        return { content: [{ type: "text", text }], details, structuredContent, isError: true };
+                    }
                     return {
-                        content: [{ type: "text", text: appendStatus(outputText, `Command exited with code ${exitCode}`) }],
-                        details,
-                        structuredContent,
+                        content: [
+                            { type: "text", text: annotation.text === undefined ? text : `${text}\n\n${annotation.text}` },
+                        ],
+                        details: { ...details, trust: annotation.trust },
+                        structuredContent: { ...structuredContent, trust: annotation.trust },
                         isError: true,
                     };
                 }

package/dist/core/tools/edit.d.ts

@@ -11,7 +11,7 @@ declare const editSchema: Type.TObject<{
 }>;
 export declare const editToolSystemPromptContribution: {
     readonly snippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call";
-    readonly guidelines: readonly ["Use edit for precise changes (edits[].oldText must match exactly)", "When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls", "Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.", "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions."];
+    readonly guidelines: readonly ["All changes to one file -> one edit call."];
 };
 export type EditToolInput = Static<typeof editSchema>;
 export interface EditToolDetails {

package/dist/core/tools/edit.js

@@ -22,12 +22,7 @@ const editSchema = Type.Object({
 }, {});
 export const editToolSystemPromptContribution = {
     snippet: "Make precise file edits with exact text replacement, including multiple disjoint edits in one call",
-    guidelines: [
-        "Use edit for precise changes (edits[].oldText must match exactly)",
-        "When changing multiple separate locations in one file, use one edit call with multiple entries in edits[] instead of multiple edit calls",
-        "Each edits[].oldText is matched against the original file, not after earlier edits are applied. Do not emit overlapping or nested edits. Merge nearby changes into one edit.",
-        "Keep edits[].oldText as small as possible while still being unique in the file. Do not pad with large unchanged regions.",
-    ],
+    guidelines: ["All changes to one file -> one edit call."],
 };
 function isSingleEditInput(value) {
     if (!value || typeof value !== "object" || Array.isArray(value)) {

package/dist/core/tools/grep/index.js

@@ -30,9 +30,8 @@ const grepSchema = Type.Object({
 });
 export const grepToolSystemPromptContribution = {
     snippet: "Search file contents (regex/literal) across paths with structured results; respects .gitignore",
-    guidelines: [
-        "Use tool.grep for content search instead of rg/grep in a shell; paginate with skip and narrow with glob/path when a page is full",
-    ],
+    // The eval-only grep guideline (system-prompt.ts getEvalOnlyGrepGuideline) carries the pagination rule once.
+    guidelines: [],
 };
 async function pathStat(path) {
     try {

package/dist/core/tools/powershell.d.ts

@@ -1,7 +1,7 @@
 import { type BashOperations, type BashSpawnContext, type BashSpawnHook, type BashToolDetails, type BashToolInput, type BashToolOptions, type createBashTool, createShellToolDefinition } from "./bash.ts";
 export declare const powershellToolSystemPromptContribution: {
     readonly snippet: "Execute PowerShell commands";
-    readonly guidelines: readonly ["You can inspect PI_* environment variables for current model and session details."];
+    readonly guidelines: readonly ["PI_* env vars = current model + session details."];
 };
 export type PowerShellOperations = BashOperations;
 export type PowerShellSpawnContext = BashSpawnContext;

package/dist/core/tools/powershell.js

@@ -4,7 +4,7 @@ import { wrapToolDefinition } from "./tool-definition-wrapper.js";
 const UTF8_OUTPUT_PREFIX = "try { [Console]::OutputEncoding=[System.Text.Encoding]::UTF8 } catch {}\n";
 export const powershellToolSystemPromptContribution = {
     snippet: "Execute PowerShell commands",
-    guidelines: ["You can inspect PI_* environment variables for current model and session details."],
+    guidelines: ["PI_* env vars = current model + session details."],
 };
 export function createLocalPowerShellOperations() {
     const operations = createLocalShellOperations("PowerShell", getPowerShellConfig);

package/dist/core/tools/read.d.ts

@@ -11,7 +11,7 @@ declare const readSchema: Type.TObject<{
 }>;
 export declare const readToolSystemPromptContribution: {
     readonly snippet: "Read file contents";
-    readonly guidelines: readonly ["Use read to examine files instead of cat or sed."];
+    readonly guidelines: readonly ["Files: read, not cat/sed."];
 };
 export type ReadToolInput = Static<typeof readSchema>;
 export interface ReadToolDetails {

package/dist/core/tools/read.js

@@ -17,7 +17,7 @@ const readSchema = Type.Object({
 });
 export const readToolSystemPromptContribution = {
     snippet: "Read file contents",
-    guidelines: ["Use read to examine files instead of cat or sed."],
+    guidelines: ["Files: read, not cat/sed."],
 };
 const LOCAL_URI_SCHEME = /^local:\/\//i;
 const LOCAL_URI_GUIDANCE = "local:// URIs resolve only inside eval cells via the kernel read()/write() helpers; the read tool takes filesystem paths. Re-read this with the eval read() helper, or retry with the plain absolute file path.";

package/dist/core/tools/write.d.ts

@@ -8,7 +8,7 @@ declare const writeSchema: Type.TObject<{
 }>;
 export declare const writeToolSystemPromptContribution: {
     readonly snippet: "Create or overwrite files";
-    readonly guidelines: readonly ["Use write only for new files or complete rewrites."];
+    readonly guidelines: readonly ["write only for new files or full rewrites."];
 };
 export type WriteToolInput = Static<typeof writeSchema>;
 /**

package/dist/core/tools/write.js

@@ -13,7 +13,7 @@ const writeSchema = Type.Object({
 });
 export const writeToolSystemPromptContribution = {
     snippet: "Create or overwrite files",
-    guidelines: ["Use write only for new files or complete rewrites."],
+    guidelines: ["write only for new files or full rewrites."],
 };
 const defaultWriteOperations = {
     writeFile: (path, content) => fsWriteFile(path, content, "utf-8"),

package/dist/engine-trust/shell-trust.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The trust annotation on agent-shell results (omo#10762, design r13 6.7). Under a fallback generation a
+ * command that exits non-zero carries a trusted status taken from the adopted record and, only when its
+ * output looks like a certificate verification error, an untrusted hint naming the matched catalog pattern.
+ * The output never supplies a reason or an action: any command can print any text, including a forged
+ * Bun footer or trust line (design M16). Like `adopted.ts`, this module does not load the marker parser.
+ */
+import { type EngineTrustActionId } from "./actions.ts";
+import type { ENGINE_TRUST_FALLBACK_REASONS } from "./marker.ts";
+/** Catalog order decides which entry a hint names when several match. */
+declare const SHELL_TRUST_PATTERNS: readonly [readonly ["UNABLE_TO_GET_ISSUER_CERT_LOCALLY", RegExp], readonly ["UNABLE_TO_GET_ISSUER_CERT", RegExp], readonly ["UNABLE_TO_VERIFY_LEAF_SIGNATURE", RegExp], readonly ["SELF_SIGNED_CERT_IN_CHAIN", RegExp], readonly ["DEPTH_ZERO_SELF_SIGNED_CERT", RegExp], readonly ["CERT_UNTRUSTED", RegExp], readonly ["unable-to-verify-the-first-certificate", RegExp], readonly ["unable-to-get-local-issuer-certificate", RegExp], readonly ["unable-to-get-issuer-certificate", RegExp], readonly ["self-signed-certificate-in-certificate-chain", RegExp], readonly ["self-signed-certificate", RegExp], readonly ["certificate-not-trusted", RegExp]];
+export type ShellTrustPatternId = (typeof SHELL_TRUST_PATTERNS)[number][0];
+export type ShellTrust = {
+    readonly status: {
+        readonly code: "trust-import-degraded";
+        readonly reason: (typeof ENGINE_TRUST_FALLBACK_REASONS)[number];
+        readonly action: EngineTrustActionId;
+    };
+    readonly hint?: {
+        readonly code: "tls-verify-text-in-output";
+        readonly heuristic: true;
+        readonly pattern: ShellTrustPatternId;
+    };
+};
+export type ShellTrustAnnotation = {
+    readonly trust: ShellTrust;
+    /** The one fixed line appended for the model, only with a hint; it never echoes output. */
+    readonly text: string | undefined;
+};
+/** Nothing without an adopted fallback generation, on exit 0, or for a command that has no exit code. */
+export declare function annotateShellTrust({ exitCode, output, }: {
+    readonly exitCode: number | null;
+    readonly output: string;
+}): ShellTrustAnnotation | undefined;
+export {};
+//# sourceMappingURL=shell-trust.d.ts.map

package/dist/engine-trust/shell-trust.js

@@ -0,0 +1,44 @@
+/**
+ * The trust annotation on agent-shell results (omo#10762, design r13 6.7). Under a fallback generation a
+ * command that exits non-zero carries a trusted status taken from the adopted record and, only when its
+ * output looks like a certificate verification error, an untrusted hint naming the matched catalog pattern.
+ * The output never supplies a reason or an action: any command can print any text, including a forged
+ * Bun footer or trust line (design M16). Like `adopted.ts`, this module does not load the marker parser.
+ */
+import { engineTrustAction } from "./actions.js";
+import { adoptedEngineTrust } from "./adopted.js";
+/** A verification code (design 6.6) as a whole token, whatever quotes surround it. */
+const token = (code) => new RegExp(`(?<![A-Za-z0-9_])${code}(?![A-Za-z0-9_])`, "u");
+/** Catalog order decides which entry a hint names when several match. */
+const SHELL_TRUST_PATTERNS = [
+    ["UNABLE_TO_GET_ISSUER_CERT_LOCALLY", token("UNABLE_TO_GET_ISSUER_CERT_LOCALLY")],
+    ["UNABLE_TO_GET_ISSUER_CERT", token("UNABLE_TO_GET_ISSUER_CERT")],
+    ["UNABLE_TO_VERIFY_LEAF_SIGNATURE", token("UNABLE_TO_VERIFY_LEAF_SIGNATURE")],
+    ["SELF_SIGNED_CERT_IN_CHAIN", token("SELF_SIGNED_CERT_IN_CHAIN")],
+    ["DEPTH_ZERO_SELF_SIGNED_CERT", token("DEPTH_ZERO_SELF_SIGNED_CERT")],
+    ["CERT_UNTRUSTED", token("CERT_UNTRUSTED")],
+    ["unable-to-verify-the-first-certificate", /unable to verify the first certificate/iu],
+    ["unable-to-get-local-issuer-certificate", /unable to get local issuer certificate/iu],
+    ["unable-to-get-issuer-certificate", /unable to get issuer certificate/iu],
+    ["self-signed-certificate-in-certificate-chain", /self[- ]signed certificate in certificate chain/iu],
+    ["self-signed-certificate", /self[- ]signed certificate/iu],
+    ["certificate-not-trusted", /certificate not trusted/iu],
+];
+/** Nothing without an adopted fallback generation, on exit 0, or for a command that has no exit code. */
+export function annotateShellTrust({ exitCode, output, }) {
+    const marker = adoptedEngineTrust();
+    if (marker?.automatic !== "fallback" || marker.fallbackReason === null || exitCode === null || exitCode === 0) {
+        return undefined;
+    }
+    const reason = marker.fallbackReason;
+    const action = engineTrustAction(reason);
+    const status = { code: "trust-import-degraded", reason, action: action.id };
+    const pattern = SHELL_TRUST_PATTERNS.find(([, matcher]) => matcher.test(output))?.[0];
+    if (pattern === undefined)
+        return { trust: { status }, text: undefined };
+    return {
+        trust: { status, hint: { code: "tls-verify-text-in-output", heuristic: true, pattern } },
+        text: `omo: certificate import is degraded (${reason}), so some TLS connections may fail. This command's output contains text that looks like a certificate verification error; omo has not confirmed the cause. To diagnose: ${action.text}`,
+    };
+}
+//# sourceMappingURL=shell-trust.js.map

package/dist/engine-trust/transport-failure.d.ts

@@ -0,0 +1,12 @@
+import { type ProviderDiagnostic } from "@earendil-works/pi-ai";
+import { type EngineTrustActionId } from "./actions.ts";
+import type { ENGINE_TRUST_FALLBACK_REASONS } from "./marker.ts";
+type FallbackReason = (typeof ENGINE_TRUST_FALLBACK_REASONS)[number];
+export interface TransportTrustFailure {
+    readonly code: "trust-tls-failed-under-fallback";
+    readonly reason: FallbackReason;
+    readonly action: EngineTrustActionId;
+}
+export declare function transportTrustFailure(diagnostic: ProviderDiagnostic | undefined): TransportTrustFailure | undefined;
+export {};
+//# sourceMappingURL=transport-failure.d.ts.map

package/dist/engine-trust/transport-failure.js

@@ -0,0 +1,48 @@
+/**
+ * The `trust` object a provider failure carries when the request failed TLS chain verification while
+ * this engine runs on a fallback trust generation (omo#10762, design r13 6.6; senpi#5244). The code
+ * comes only from the adapter's structured transport diagnostic, which reads the native error's
+ * `code`, never message text. The object and its diagnostics record name no host, path or certificate.
+ */
+import { appendFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { isTlsChainVerificationCode } from "@earendil-works/pi-ai";
+import { engineTrustAction } from "./actions.js";
+import { adoptedEngineTrust } from "./adopted.js";
+/** Reasons this process already wrote a record for: one record per process and reason. */
+const recordedReasons = new Set();
+export function transportTrustFailure(diagnostic) {
+    if (diagnostic?.evidence !== "structured_transport" || diagnostic.code === undefined)
+        return undefined;
+    if (!isTlsChainVerificationCode(diagnostic.code))
+        return undefined;
+    const trust = adoptedEngineTrust();
+    if (trust?.automatic !== "fallback" || trust.fallbackReason === null)
+        return undefined;
+    const reason = trust.fallbackReason;
+    if (!recordedReasons.has(reason)) {
+        recordedReasons.add(reason);
+        appendDiagnosticsRecord(trust.file, {
+            v: 1,
+            at: new Date().toISOString(),
+            pid: process.pid,
+            generation: trust.sha256,
+            codes: ["trust-tls-failed-under-fallback", reason],
+        });
+    }
+    return { code: "trust-tls-failed-under-fallback", reason, action: engineTrustAction(reason).id };
+}
+/**
+ * One line, in one append, to `diagnostics.jsonl` beside the generation file (design 5.3). The append
+ * is asynchronous because this runs on the RPC session path, which takes no blocking filesystem call
+ * (no-sync-in-session-path). A record that cannot be written costs only the record: the failure still
+ * carries its `trust` object.
+ */
+function appendDiagnosticsRecord(generationFile, record) {
+    appendFile(join(dirname(generationFile), "diagnostics.jsonl"), `${JSON.stringify(record)}\n`, {
+        mode: 0o600,
+    }).catch(() => {
+        // The trust directory may be gone or read-only; the record is diagnostic only.
+    });
+}
+//# sourceMappingURL=transport-failure.js.map

package/dist/modes/interactive/interactive-mode.js

@@ -46,6 +46,7 @@ import { defaultModelPerProvider, findExactModelReferenceMatch, resolveModelScop
 import { CredentialSynchronizationError } from "../../core/model-runtime.js";
 import { formatProviderFailure } from "../../core/provider-failure.js";
 import { failureAlreadyDescribed, headNoticeShownElsewhere } from "./provider-error-description.js";
+import { describeFallbackExhaustion } from "../../core/retry-fallback/exhaustion.js";
 import { usageLimitCause } from "../../core/retry-fallback/usage-limit.js";
 import { formatMissingSessionCwdPrompt, MissingSessionCwdError } from "../../core/session-cwd.js";
 import { createSessionLogger } from "../../core/session-log.js";
@@ -4864,19 +4865,24 @@ export class InteractiveMode {
                 });
                 this.setExtensionStatus(FALLBACK_STATUS_KEY, undefined);
                 break;
-            case "retry_fallback_exhausted":
-                if (isRetryableProviderError(event.lastError)) {
+            case "retry_fallback_exhausted": {
+                // A walk that started on another failure must lead with it, not the last rung's (senpi#4084).
+                const startedElsewhere = (event.failures?.length ?? 0) > 1;
+                if (isRetryableProviderError(event.lastError) && !startedElsewhere) {
                     this.getProviderErrors().finish(event.lastError);
                     this.setExtensionStatus(FALLBACK_STATUS_KEY, undefined);
                     break;
                 }
+                if (isRetryableProviderError(event.lastError))
+                    this.getProviderErrors().clear();
                 this.showNoticeBox({
                     title: `✕ Fallback chain exhausted · ${event.chainKey}`,
                     tone: "error",
-                    why: event.lastError,
+                    why: describeFallbackExhaustion(event),
                 });
                 this.setExtensionStatus(FALLBACK_STATUS_KEY, undefined);
                 break;
+            }
             case "server_fallback_aborted":
                 this.showNoticeBox({
                     title: `⚠ Server fallback aborted · ${event.from} → ${event.to}`,

package/dist/modes/print-mode.js

@@ -7,6 +7,7 @@
  */
 import { describeProviderFailureForUser, stripTurnRetrySuppressionPrefix, } from "@earendil-works/pi-ai";
 import { flushRawStdout, waitForRawStdoutBackpressure, writeRawStdout } from "../core/output-guard.js";
+import { describeFallbackExhaustion } from "../core/retry-fallback/exhaustion.js";
 import { usageLimitCause, usageLimitScope } from "../core/retry-fallback/usage-limit.js";
 import { killTrackedDetachedChildren } from "../utils/shell.js";
 import { toJsonEvent } from "./json-event.js";
@@ -107,7 +108,7 @@ export async function runPrintMode(runtimeHost, options) {
                 console.error(`Model fallback: ${event.from} -> ${event.to} (${usageLimitCause(event.from, event.limit) ?? event.reason})`);
             }
             else if (event.type === "retry_fallback_exhausted") {
-                console.error(`Model fallback exhausted: ${event.chainKey} (${event.lastError})`);
+                console.error(`Model fallback exhausted: ${event.chainKey} (${describeFallbackExhaustion(event).replaceAll("\n", "; ")})`);
             }
             else if (event.type === "retry_fallback_reverted") {
                 const cause = event.cause === "fallback-unusable" ? ` (${event.from} cannot serve right now)` : "";