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

package/dist/core/agent-session.js

@@ -51,6 +51,7 @@ import { CompactionLifecycleCoordinator } from "./compaction/lifecycle.js";
 import { isTurnStuckOnContextOverflow } from "./compaction/stuck-overflow.js";
 import { isWarmSummaryAnchorValid } from "./compaction/warm-anchor.js";
 import { CONTINUE_FROM_LEAF_CUSTOM_TYPE, CONTINUE_FROM_LEAF_DIRECTIVE, ContinueFromLeafError, trackTurnAdmission, } from "./continue-from-leaf.js";
+import { credentialRecoveryRevision } from "./credential-recovery-revision.js";
 import { admitCursorHistory, cursorAdmissionBudgetBytes } from "./cursor-history-admission.js";
 import { DEFAULT_THINKING_LEVEL } from "./defaults.js";
 import { resolveDiscoveredResourcePaths } from "./discovered-resource-scope.js";
@@ -128,6 +129,7 @@ import { createModelConfigErrorReporter, isModelConfigFailure, } from "./retry-f
 import { ProbeBackScheduler } from "./retry-fallback/probe-scheduler.js";
 import { REQUEST_SHAPE_FAILURE_TEXT, REQUEST_SHAPE_RECOVERY_ENTRY_TYPE, REQUEST_SHAPE_RECOVERY_NOTE, RequestShapeRecovery, } from "./retry-fallback/request-shape.js";
 import { AccountUsageLimitError, describeUsageLimitEntry, describeUsageLimitMessage, usageLimitScope, } from "./retry-fallback/usage-limit.js";
+import { recordRungFailure } from "./retry-fallback/exhaustion.js";
 import { validateFallbackChains } from "./retry-fallback/validate.js";
 import { RunHolds } from "./run-holds.js";
 import { startRunResumeTurn } from "./run-resume-turn.js";
@@ -610,6 +612,8 @@ export class AgentSession {
         this._userActivity = createUserActivitySource();
         this._extensionMode = "print";
         this._providerRequiredNoticed = false;
+        // Every rung that failed this turn, in order: the exhaustion event leads with the first (senpi#4084).
+        this._fallbackTurnFailures = [];
         this._probeBackLaneSeq = 0;
         // Tool registry for extension getTools/setTools
         this._toolRegistry = new Map();
@@ -901,6 +905,7 @@ export class AgentSession {
             emit: (event) => this._emit(event),
             getCurrentSelector: () => (this.model ? { model: this.model, thinkingLevel: this.thinkingLevel } : undefined),
             isAuthAvailable: (provider) => this._modelRuntime.hasConfiguredAuth(provider),
+            recoveryRevision: (provider) => credentialRecoveryRevision(this._modelRuntime.authStorage, provider),
         });
         this._unfollowProviderAccountChanges = followProviderAccountChanges(this._retryFallback);
         this._probeBackScheduler = new ProbeBackScheduler({
@@ -1749,6 +1754,16 @@ export class AgentSession {
         this.agent.state.messages = this.sessionManager.buildSessionContext().messages;
         this._emitEntryAppended(entry.id);
     }
+    _emitFallbackExhausted(chainKey, lastError) {
+        const failures = [...this._fallbackTurnFailures];
+        const primaryError = failures[0];
+        this._emit({
+            type: "retry_fallback_exhausted",
+            chainKey,
+            lastError,
+            ...(primaryError === undefined ? {} : { primaryError, failures }),
+        });
+    }
     _emit(event, captureSource = event) {
         this._recoveryIdentity?.observe(event);
         const produced = event;
@@ -1761,11 +1776,8 @@ export class AgentSession {
         if (event.type === "entry_appended") {
             event = { ...event, entry: describeUsageLimitEntry(event.entry) };
         }
-        if (event.type === "retry_fallback_exhausted" && usageLimitScope(event.lastError) === "account") {
-            event = {
-                ...event,
-                lastError: new AccountUsageLimitError(this.model?.provider ?? "", event.lastError).message,
-            };
+        if (event.type === "retry_fallback_exhausted") {
+            event = describeExhaustedFailures(event, this.model?.provider ?? "");
         }
         if (event.type === "agent_end") {
             event = {
@@ -2556,6 +2568,7 @@ export class AgentSession {
         if (event.type === "message_start" && event.message.role === "user") {
             this._overflowRecoveryRungs = 0;
             this._retryFallback.resetTurn();
+            this._fallbackTurnFailures = [];
             const messageText = userMessageText(event.message.content);
             // Image-only input has no text to match: find it by the message the queue handed to the agent (#3592).
             const imageOnlyQueued = messageText
@@ -4107,7 +4120,10 @@ export class AgentSession {
         const promptGuidelines = [];
         for (const name of contributingToolNames) {
             const snippet = this._toolPromptSnippets.get(name);
-            if (snippet) {
+            // A model-facing tool whose schema description the model already reads gets no snippet line;
+            // withheld eval-only tools keep theirs (senpi#5335).
+            const describedToModel = validToolNames.includes(name) && (this._toolRegistry.get(name)?.description.trim() ?? "") !== "";
+            if (snippet && !describedToModel) {
                 toolSnippets[name] = snippet;
             }
             const toolGuidelines = this._toolPromptGuidelines.get(name);
@@ -4130,38 +4146,40 @@ export class AgentSession {
             customPrompt: loaderSystemPrompt,
             appendSystemPrompt: loaderAppendSystemPrompt.length > 0 ? loaderAppendSystemPrompt.join("\n\n") : undefined,
         };
+        const evalOnlyArmed = this._isEvalOnlyPolicyArmed();
+        const armed = evalOnlyArmed ? (this._evalOnlyToolNames ?? new Set()) : new Set();
+        const registered = new Set([...armed].filter((name) => this._toolRegistry.has(name)));
+        // The eval-only paragraph below states the grep rule for this render, so the grep snippet that
+        // renders the eval-only grep guideline stays out of it (senpi#5335).
+        const { grep: _grepSnippet, ...snippetsWithoutGrep } = toolSnippets;
         const prompt = buildDynamicSystemPrompt({
             ...this._baseSystemPromptOptions,
+            ...(registered.has("grep") ? { toolSnippets: snippetsWithoutGrep } : {}),
             onParts: (parts) => {
                 this._baseSystemPromptParts = parts;
             },
         });
-        if (!this._isEvalOnlyPolicyArmed())
+        if (!evalOnlyArmed)
             return prompt;
-        const armed = this._evalOnlyToolNames ?? new Set();
-        const registered = new Set([...armed].filter((name) => this._toolRegistry.has(name)));
-        const sentences = [];
+        const helpers = [];
         const shellHelpers = ["bash", "powershell"].filter((name) => registered.has(name)).map(evalHelperCall);
-        if (shellHelpers.length > 0) {
-            sentences.push(`Shell commands run ONLY inside eval cells via ${shellHelpers.join(" or ")}; hooks and permissions still apply.`);
-        }
-        if (registered.has("workflow")) {
-            sentences.push(`The workflow tool runs ONLY inside eval cells via ${evalHelperCall("workflow")}; hooks and permissions still apply.`);
-        }
+        if (shellHelpers.length > 0)
+            helpers.push(`${shellHelpers.join(" / ")} shell`);
+        if (registered.has("workflow"))
+            helpers.push(evalHelperCall("workflow"));
         // Declared tools and SDK overrides outside the built-in groups still need eval guidance.
-        const otherHelpers = [...registered]
+        helpers.push(...[...registered]
             .filter((name) => name !== "bash" && name !== "powershell" && name !== "workflow" && name !== "grep" && name !== "glob")
-            .map(evalHelperCall);
-        if (otherHelpers.length > 0) {
-            sentences.push(`These tools run ONLY inside eval cells via ${otherHelpers.join(" or ")}; hooks and permissions still apply.`);
-        }
+            .map(evalHelperCall));
         if (registered.has("glob")) {
-            sentences.push(`File-name search runs ONLY inside eval cells via ${evalHelperCall("glob")}; it matches a glob such as **/*.ts, respects .gitignore, and applies hooks and permissions - prefer it over find/ls in tool.bash.`);
+            helpers.push(`${evalHelperCall("glob")} file-name search (glob like **/*.ts, respects .gitignore; over find/ls)`);
         }
         if (registered.has("grep")) {
-            sentences.push(`Text search runs ONLY inside eval cells via ${evalHelperCall("grep")}; it returns structured matches, respects .gitignore, and applies hooks and permissions - prefer it over rg/grep in tool.bash.`);
+            helpers.push(`${evalHelperCall("grep")} text search (structured, respects .gitignore; over rg/grep; page full -> skip, narrow with glob/path)`);
         }
-        return sentences.length > 0 ? `${prompt}\n\n${sentences.join("\n\n")}` : prompt;
+        return helpers.length > 0
+            ? `${prompt}\n\nEval-only tools (hooks + permissions still apply): ${helpers.join("; ")}.`
+            : prompt;
     }
     /**
      * Run `input` extension handlers for queued (steer / follow-up) input.
@@ -4481,6 +4499,7 @@ export class AgentSession {
                 const model = this.model;
                 if (model && !this._pendingModelSwitch && this._retryFallback.isProviderSpent(model.provider)) {
                     this._retryFallback.resetTurn();
+                    this._fallbackTurnFailures = [];
                     const errorMessage = this._retryFallback.accountError(model.provider);
                     // Routing around a remembered failure did not observe another provider failure.
                     if (!(await this._retryFallback.tryFallback("transient", { errorMessage }, false))) {
@@ -10427,11 +10446,7 @@ export class AgentSession {
         const finishRetryAttempt = (attempt, finalError) => {
             const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
             if (exhaustedChainKey) {
-                this._emit({
-                    type: "retry_fallback_exhausted",
-                    chainKey: exhaustedChainKey,
-                    lastError: errorMessage,
-                });
+                this._emitFallbackExhausted(exhaustedChainKey, errorMessage);
             }
             this._emit({
                 type: "auto_retry_end",
@@ -10494,6 +10509,11 @@ export class AgentSession {
         let is429TierRouted = false;
         let hintTierDelayMs;
         const tryFallback = async (reason, failure) => {
+            recordRungFailure(this._fallbackTurnFailures, {
+                model: `${message.provider}/${message.model}`,
+                reason,
+                error: errorMessage,
+            });
             try {
                 return await this._retryFallback.tryFallback(reason, failure);
             }
@@ -10513,7 +10533,7 @@ export class AgentSession {
             if (!switchedFallback) {
                 const chainKey = this._retryFallback.exhaustedChainKey;
                 if (chainKey)
-                    this._emit({ type: "retry_fallback_exhausted", chainKey, lastError: errorMessage });
+                    this._emitFallbackExhausted(chainKey, errorMessage);
                 if (this._retryAttempt > 0) {
                     this._emit({
                         type: "auto_retry_end",
@@ -10570,11 +10590,7 @@ export class AgentSession {
                 if (!switchedFallback) {
                     const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
                     if (exhaustedChainKey) {
-                        this._emit({
-                            type: "retry_fallback_exhausted",
-                            chainKey: exhaustedChainKey,
-                            lastError: errorMessage,
-                        });
+                        this._emitFallbackExhausted(exhaustedChainKey, errorMessage);
                     }
                     this._resolveRetry();
                     return "not-handled";
@@ -10604,11 +10620,7 @@ export class AgentSession {
             if (!switchedFallback) {
                 const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
                 if (exhaustedChainKey) {
-                    this._emit({
-                        type: "retry_fallback_exhausted",
-                        chainKey: exhaustedChainKey,
-                        lastError: errorMessage,
-                    });
+                    this._emitFallbackExhausted(exhaustedChainKey, errorMessage);
                 }
                 if (this._retryAttempt > 0) {
                     this._emit({
@@ -10669,11 +10681,7 @@ export class AgentSession {
                     else {
                         const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
                         if (exhaustedChainKey) {
-                            this._emit({
-                                type: "retry_fallback_exhausted",
-                                chainKey: exhaustedChainKey,
-                                lastError: errorMessage,
-                            });
+                            this._emitFallbackExhausted(exhaustedChainKey, errorMessage);
                         }
                         this._emit({
                             type: "auto_retry_end",
@@ -10721,11 +10729,7 @@ export class AgentSession {
                         else {
                             const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
                             if (exhaustedChainKey) {
-                                this._emit({
-                                    type: "retry_fallback_exhausted",
-                                    chainKey: exhaustedChainKey,
-                                    lastError: errorMessage,
-                                });
+                                this._emitFallbackExhausted(exhaustedChainKey, errorMessage);
                             }
                             this._emit({
                                 type: "auto_retry_end",
@@ -10762,11 +10766,7 @@ export class AgentSession {
                             else {
                                 const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
                                 if (exhaustedChainKey) {
-                                    this._emit({
-                                        type: "retry_fallback_exhausted",
-                                        chainKey: exhaustedChainKey,
-                                        lastError: errorMessage,
-                                    });
+                                    this._emitFallbackExhausted(exhaustedChainKey, errorMessage);
                                 }
                                 this._emit({
                                     type: "auto_retry_end",
@@ -10822,11 +10822,7 @@ export class AgentSession {
                 else {
                     const exhaustedChainKey = this._retryFallback.exhaustedChainKey;
                     if (exhaustedChainKey) {
-                        this._emit({
-                            type: "retry_fallback_exhausted",
-                            chainKey: exhaustedChainKey,
-                            lastError: errorMessage,
-                        });
+                        this._emitFallbackExhausted(exhaustedChainKey, errorMessage);
                     }
                     this._emit({
                         type: "auto_retry_end",
@@ -11109,8 +11105,8 @@ export class AgentSession {
         else {
             // Add to agent state immediately
             this.agent.state.messages.push(bashMessage);
-            // Save to session
-            this.sessionManager.appendMessage(bashMessage);
+            // Save to session; every RPC observer learns of it the way it learns of any persisted entry (senpi#5576).
+            this._emitEntryAppended(this.sessionManager.appendMessage(bashMessage));
             this._incrementMessageRevision();
         }
     }
@@ -11145,7 +11141,7 @@ export class AgentSession {
             // Add to agent state
             this.agent.state.messages.push(bashMessage);
             // Save to session
-            this.sessionManager.appendMessage(bashMessage);
+            this._emitEntryAppended(this.sessionManager.appendMessage(bashMessage));
             this._incrementMessageRevision();
         }
         this._pendingBashMessages = [];
@@ -11802,4 +11798,18 @@ function messageFingerprint(message) {
     const requestContext = usage?.contextUsage;
     return `${size}:${usage?.input ?? ""}:${usage?.output ?? ""}:${usage?.totalTokens ?? ""}:${requestContext?.input}:${requestContext?.output}:${requestContext === null}`;
 }
+// Clients see each rung's provider text through the same account-limit description as `lastError`.
+function describeExhaustedFailures(event, currentProvider) {
+    const describe = (error, provider) => usageLimitScope(error) === "account" ? new AccountUsageLimitError(provider, error).message : error;
+    const failures = event.failures?.map((failure) => ({
+        ...failure,
+        error: describe(failure.error, failure.model.slice(0, Math.max(0, failure.model.indexOf("/")))),
+    }));
+    const primaryError = failures?.[0];
+    return {
+        ...event,
+        lastError: describe(event.lastError, currentProvider),
+        ...(failures === undefined || primaryError === undefined ? {} : { failures, primaryError }),
+    };
+}
 //# sourceMappingURL=agent-session.js.map

package/dist/core/auth-storage.d.ts

@@ -5,6 +5,7 @@
 import type { ApiKeyCredential, AuthOperationOptions, Credential, CredentialInfo, CredentialStore, OAuthAuth, OAuthCredential, OAuthLoginCallbacks } from "@earendil-works/pi-ai";
 import { type CredentialKind } from "@earendil-works/pi-ai/auth/pool/kinds";
 import { type CredentialSlot } from "@earendil-works/pi-ai/auth/pool/slots";
+import { type AuthStoreLoadError } from "./auth-store-load-error.ts";
 type AuthStorageData = Record<string, Credential>;
 /** A credential problem the user should see once per change: `id` changes when the problem does. */
 export type AuthNotice = {
@@ -101,6 +102,7 @@ export declare class AuthStorage implements CredentialStore {
     private busyReads;
     private dataLoaded;
     private dataFromBusyRead;
+    private loadError;
     private constructor();
     static create(authPath?: string): AuthStorage;
     getStoragePath(): string | undefined;
@@ -125,6 +127,10 @@ export declare class AuthStorage implements CredentialStore {
      */
     private backupAuthFile;
     private updateReadState;
+    /** The shared read state holds the store's current contents: this instance answers from it again. */
+    private adoptReadState;
+    /** A sync write that parsed and saved the locked store proves it loads again. */
+    private writeLocked;
     /**
      * Reload credentials from storage.
      */
@@ -135,6 +141,17 @@ export declare class AuthStorage implements CredentialStore {
      * store, or a busy read after a successful load, is not busy.
      */
     isCredentialStoreBusy(): boolean;
+    /**
+     * Why the store could not be loaded on its last read, or undefined once any read or write of this
+     * instance finds it good again (senpi#4413). While set, the in-memory credentials are not the store's
+     * contents; a store that cannot be read or parsed also refuses every write.
+     */
+    getLoadError(): AuthStoreLoadError | undefined;
+    /**
+     * Records a failed read; returns false when it repeats the load error already reported, so a store
+     * that stays broken is not re-recorded on every status read that retries it.
+     */
+    private noteLoadFailure;
     /**
      * Monotonic count of reads (sync or async) that found the store locked before it ever
      * loaded and answered with the empty placeholder. A change across an operation means
@@ -176,6 +193,7 @@ export declare class AuthStorage implements CredentialStore {
     private noteReplacement;
     remove(provider: string): void;
     listSlots(provider: string): CredentialSlot[];
+    /** Adding a new slot is a sign-in and stamps a fresh `loginId`; updating an existing slot keeps it (senpi#4099). */
     setSlot(provider: string, slot: CredentialSlot): void;
     removeSlot(provider: string, name: string): void;
     has(provider: string): boolean;
@@ -184,6 +202,7 @@ export declare class AuthStorage implements CredentialStore {
     getAll(): AuthStorageData;
     drainErrors(): Error[];
     private reloadFromStorageAsync;
+    private reloadLockedAsync;
     private readLatestData;
     read(provider: string, options?: AuthOperationOptions): Promise<Credential | undefined>;
     readSlot(provider: string, slotName: string, options?: AuthOperationOptions): Promise<Credential | undefined>;

package/dist/core/auth-storage.js

@@ -4,6 +4,7 @@
  */
 import { findEnvKeys, getEnvApiKey, readByProviderId } from "@earendil-works/pi-ai";
 import { slotKind, unusedSlotKinds } from "@earendil-works/pi-ai/auth/pool/kinds";
+import { stampLogin } from "@earendil-works/pi-ai/auth/pool/login-id";
 import { appendLoginSlot, listSlots, projectSlot, removeSlot, repairManagedSentinelSlots, upsertSlot, } from "@earendil-works/pi-ai/auth/pool/slots";
 import { builtinProviders } from "@earendil-works/pi-ai/providers/all";
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "fs";
@@ -16,6 +17,7 @@ import { stripBom } from "../utils/text.js";
 import { signOutLegacyClaudeLogins } from "./anthropic-legacy-sign-out.js";
 import { resolveReadOnlyCredential, resolveStoredCredential, resolveStoredSlot, validateReadOnlyAuthData, } from "./auth-credential-values.js";
 import { migrateLegacyProviderKeys } from "./auth-provider-key-migration.js";
+import { describeAuthStoreLoadFailure, failureAfterRead, parseAuthDocument, } from "./auth-store-load-error.js";
 import { ANTHROPIC_SUBSCRIPTION_PROVIDER_ID } from "./extensions/builtin/anthropic-subscription/provider-id.js";
 import { signInAgainMessage, signInRequiredNames } from "./extensions/builtin/anthropic-subscription/sign-in-again.js";
 import { lockWithLossHandling } from "./file-lock.js";
@@ -392,7 +394,7 @@ export class AuthStorage {
         // Mutation paths keep the stored keys as-is: the key migration (and its
         // pre-write backup) belongs to the load seam, so a write can never drop a
         // legacy entry without the backup that preserves it.
-        return repairPoisonedPoolSlots(JSON.parse(stripBom(content))).data;
+        return repairPoisonedPoolSlots(parseAuthDocument(content)).data;
     }
     /**
      * Reports whether the parse healed poisoned pool slots or moved legacy
@@ -406,7 +408,7 @@ export class AuthStorage {
         if (!content) {
             return { data: {}, repaired: false, migrated: false };
         }
-        const repaired = repairPoisonedPoolSlots(JSON.parse(stripBom(content)));
+        const repaired = repairPoisonedPoolSlots(parseAuthDocument(content));
         const migrated = migrateLegacyProviderKeys(repaired.data);
         const moved = signOutLegacyClaudeLogins(migrated.data);
         if (moved.skipped && !this.reportedMigrationSkips.has(moved.skipped)) {
@@ -444,19 +446,37 @@ export class AuthStorage {
         this.data = data;
         this.dataLoaded = true;
         this.dataFromBusyRead = false;
+        this.loadError = undefined;
         this.readState.data = data;
         this.readState.loaded = true;
         this.readState.revision = revision;
     }
+    /** The shared read state holds the store's current contents: this instance answers from it again. */
+    adoptReadState(data) {
+        this.data = data;
+        this.dataLoaded = true;
+        this.dataFromBusyRead = false;
+        this.loadError = undefined;
+        return data;
+    }
+    /** A sync write that parsed and saved the locked store proves it loads again. */
+    writeLocked(fn) {
+        const result = this.storage.withLock(fn);
+        this.loadError = undefined;
+        return result;
+    }
     /**
      * Reload credentials from storage.
      */
     reload() {
         let data = {};
         let revision;
+        const load = { parsed: false, writeBack: false };
         try {
             this.storage.withLock((current) => {
                 const parsed = this.parseStorageContent(current);
+                load.parsed = true;
+                load.writeBack = parsed.repaired || parsed.migrated;
                 data = parsed.data;
                 // A written repair or migration invalidates the revision read before
                 // it; leaving it unset makes the next reader re-read instead of
@@ -472,9 +492,17 @@ export class AuthStorage {
             this.updateReadState(data, revision);
             return "loaded";
         }
-        catch (error) {
-            // Preserve the last valid in-memory snapshot.
-            this.recordError(error instanceof Error ? error : new Error(String(error)));
+        catch (rawError) {
+            const error = failureAfterRead(rawError, load);
+            const recorded = this.noteLoadFailure(error);
+            // auth.json parsed and only a later step failed (a write-back or a lost lock): its parsed
+            // credentials stand, as on the async path. A failure before the parse keeps the last snapshot.
+            if (load.parsed) {
+                this.updateReadState(data, revision);
+                this.loadError = describeAuthStoreLoadFailure(error);
+            }
+            if (!recorded)
+                return "failed";
             if (!(error instanceof CredentialStoreBusyError))
                 return "failed";
             if (!this.dataLoaded) {
@@ -492,6 +520,30 @@ export class AuthStorage {
     isCredentialStoreBusy() {
         return this.dataFromBusyRead;
     }
+    /**
+     * Why the store could not be loaded on its last read, or undefined once any read or write of this
+     * instance finds it good again (senpi#4413). While set, the in-memory credentials are not the store's
+     * contents; a store that cannot be read or parsed also refuses every write.
+     */
+    getLoadError() {
+        return this.loadError;
+    }
+    /**
+     * Records a failed read; returns false when it repeats the load error already reported, so a store
+     * that stays broken is not re-recorded on every status read that retries it.
+     */
+    noteLoadFailure(error) {
+        const loadError = describeAuthStoreLoadFailure(error);
+        const repeated = loadError !== undefined &&
+            this.loadError?.kind === loadError.kind &&
+            this.loadError.reason === loadError.reason;
+        if (loadError)
+            this.loadError = loadError;
+        if (repeated)
+            return false;
+        this.recordError(error);
+        return true;
+    }
     /**
      * Monotonic count of reads (sync or async) that found the store locked before it ever
      * loaded and answered with the empty placeholder. A change across an operation means
@@ -524,12 +576,12 @@ export class AuthStorage {
      * `takeReplacement`, so no credential disappears without the user being told where it went.
      */
     set(provider, credential) {
-        return this.storage.withLock((content) => {
+        return this.writeLocked((content) => {
             const currentData = this.parseStorageData(content);
             const replacement = this.noteReplacement(provider, currentData[provider], credential, content);
-            const next = appendLoginSlot(currentData[provider], credential, undefined, {
+            const next = stampLogin(appendLoginSlot(currentData[provider], credential, undefined, {
                 accountIdentity: this.oauthAuth(provider)?.accountIdentity,
-            });
+            }));
             const nextData = { ...currentData, [provider]: next };
             this.data = nextData;
             return { result: replacement, next: JSON.stringify(nextData, null, 2) };
@@ -609,7 +661,7 @@ export class AuthStorage {
         return replacement;
     }
     remove(provider) {
-        this.storage.withLock((content) => {
+        this.writeLocked((content) => {
             const nextData = { ...this.parseStorageData(content) };
             delete nextData[provider];
             this.data = nextData;
@@ -619,17 +671,21 @@ export class AuthStorage {
     listSlots(provider) {
         return listSlots(readByProviderId(this.data, provider));
     }
+    /** Adding a new slot is a sign-in and stamps a fresh `loginId`; updating an existing slot keeps it (senpi#4099). */
     setSlot(provider, slot) {
-        this.storage.withLock((content) => {
+        this.writeLocked((content) => {
             const currentData = this.parseStorageData(content);
-            const next = upsertSlot(currentData[provider], slot);
+            const current = currentData[provider];
+            const upserted = upsertSlot(current, slot);
+            const adds = !listSlots(current).some((existing) => existing.name === slot.name);
+            const next = adds ? stampLogin(upserted) : upserted;
             const nextData = { ...currentData, [provider]: next };
             this.data = nextData;
             return { result: undefined, next: JSON.stringify(nextData, null, 2) };
         });
     }
     removeSlot(provider, name) {
-        this.storage.withLock((content) => {
+        this.writeLocked((content) => {
             const currentData = this.parseStorageData(content);
             const next = removeSlot(currentData[provider], name);
             const nextData = { ...currentData };
@@ -666,16 +722,34 @@ export class AuthStorage {
         return errors;
     }
     async reloadFromStorageAsync(options) {
-        return this.storage.withLockAsync(async (content) => {
-            const parsed = this.parseStorageContent(content);
-            const revision = parsed.repaired || parsed.migrated || !this.authPath ? undefined : getFileContentRevision(this.authPath);
-            this.updateReadState(parsed.data, revision);
-            if (parsed.migrated)
-                this.backupAuthFile(content);
-            return parsed.repaired || parsed.migrated
-                ? { result: parsed.data, next: JSON.stringify(parsed.data, null, 2) }
-                : { result: parsed.data };
-        }, options);
+        try {
+            return await this.reloadLockedAsync(options);
+        }
+        catch (error) {
+            if (!options?.signal?.aborted)
+                this.loadError = describeAuthStoreLoadFailure(error) ?? this.loadError;
+            throw error;
+        }
+    }
+    async reloadLockedAsync(options) {
+        const load = { parsed: false, writeBack: false };
+        try {
+            return await this.storage.withLockAsync(async (content) => {
+                const parsed = this.parseStorageContent(content);
+                load.parsed = true;
+                load.writeBack = parsed.repaired || parsed.migrated;
+                const revision = parsed.repaired || parsed.migrated || !this.authPath ? undefined : getFileContentRevision(this.authPath);
+                this.updateReadState(parsed.data, revision);
+                if (parsed.migrated)
+                    this.backupAuthFile(content);
+                return parsed.repaired || parsed.migrated
+                    ? { result: parsed.data, next: JSON.stringify(parsed.data, null, 2) }
+                    : { result: parsed.data };
+            }, options);
+        }
+        catch (error) {
+            throw failureAfterRead(error, load);
+        }
     }
     async readLatestData(options) {
         options?.signal?.throwIfAborted();
@@ -692,7 +766,7 @@ export class AuthStorage {
         }
         const revision = getFileContentRevision(this.authPath);
         if (revision !== undefined && revision === this.readState.revision)
-            return this.readState.data;
+            return this.adoptReadState(this.readState.data);
         if (!this.readState.reload) {
             const controller = new AbortController();
             const reload = {
@@ -715,10 +789,11 @@ export class AuthStorage {
         reload.readers++;
         try {
             try {
-                return await raceWithAbortSignal(reload.promise, options?.signal);
+                return this.adoptReadState(await raceWithAbortSignal(reload.promise, options?.signal));
             }
             catch (error) {
                 options?.signal?.throwIfAborted();
+                this.loadError = describeAuthStoreLoadFailure(error) ?? this.loadError;
                 this.noteBusyFallback(error);
                 return this.readState.data;
             }

package/dist/core/auth-store-load-error.d.ts

@@ -0,0 +1,29 @@
+export type AuthStoreLoadErrorKind = "malformed_json" | "invalid_format" | "unreadable" | "write_back_failed";
+/**
+ * Why an existing auth.json could not be loaded (senpi#4413). `reason` is safe to show and send to
+ * clients: it never carries the file's path or contents.
+ */
+export interface AuthStoreLoadError {
+    readonly kind: AuthStoreLoadErrorKind;
+    readonly reason: string;
+}
+export declare class AuthStoreUnreadableError extends Error {
+    readonly loadError: AuthStoreLoadError;
+    constructor(loadError: AuthStoreLoadError);
+}
+/** The top-level object of an auth.json document; anything else is refused rather than read as empty. */
+export declare function parseAuthDocument(content: string): Record<string, unknown>;
+/**
+ * The load error a failed store read stands for, or undefined when the failure says nothing about
+ * the file: a lock held by another writer, a read the caller aborted, or a lock lost after a clean read.
+ */
+export declare function describeAuthStoreLoadFailure(error: unknown): AuthStoreLoadError | undefined;
+/**
+ * The error a store load surfaces: once auth.json parsed, a later failure (a write-back or a lost lock)
+ * becomes an AuthStoreAfterReadError so it is never reported as an unreadable file. Aborts pass through.
+ */
+export declare function failureAfterRead(error: unknown, load: {
+    parsed: boolean;
+    writeBack: boolean;
+}): unknown;
+//# sourceMappingURL=auth-store-load-error.d.ts.map