@genesislcap/ai-assistant 15.15.1 → 15.15.2

package/src/state/persistence/session-persister.ts

@@ -48,6 +48,14 @@ const DEFAULT_DIAGNOSTICS_DEBOUNCE_MS = 4_000;
  * (GENC-1351 §5.9) and set no `notResumableMessage`. Paired with the composer
  * pre-filled with the flow-activating prompt, so "send it again" is one keystroke.
  */
+/**
+ * Consecutive failed saves before persistence is declared broken (GENC-1511). Two, not one: a
+ * single failure is usually a transient blip that the next autosave clears on its own, and a
+ * modal about a problem that has already fixed itself trains people to dismiss the one that
+ * matters. At the 1 s autosave debounce this is ~2 s of exposure.
+ */
+const SAVE_FAILURES_BEFORE_BROKEN = 2;
+
 const DEFAULT_NOT_RESUMABLE_MESSAGE =
   "Sorry, I didn't manage to finish the task from your previous message. Send it again if you'd like me to try it again";
 
@@ -76,6 +84,22 @@ export interface SessionPersisterDeps {
    * events, etc. — and is diffed against the shared cursors here (GENC-1351 §5.10).
    */
   getDiagnosticEntries: () => DiagnosticEntry[];
+  /**
+   * Persistence has failed repeatedly and it is now a safe moment to tell the user (GENC-1511).
+   * Called at most once per broken episode — see {@link SessionPersister.persistSession} for the
+   * gating, which waits for the active agent to be RESUMABLE so we never advise a reload at a
+   * moment when reloading would throw away in-flight work the snapshot cannot carry.
+   */
+  onPersistenceBroken?: (detail: {
+    /** Messages in the live transcript that the store does not have. */
+    unsavedMessages: number;
+    /** `savedAt` of the last snapshot that landed, if one ever did. */
+    lastSavedAt?: string;
+    /** Why the writes are failing, as reported by the provider. */
+    reason: string;
+  }) => void;
+  /** A save landed after a broken episode — the warning can be withdrawn (GENC-1511). */
+  onPersistenceRecovered?: () => void;
 }
 
 /**
@@ -104,6 +128,30 @@ export class SessionPersister {
    * empty). Seeded on restore. See {@link reconcileAgentSnapshots}.
    */
   private _cache: Record<string, unknown> = {};
+  /**
+   * How many messages the last SUCCESSFUL write persisted. Two jobs, both GENC-1511:
+   * it is the monotonic floor for a freeze boundary (the stored transcript must never
+   * shrink), and it is what lets a running flow skip a re-write when its boundary has
+   * not moved. Content-keyed, so unlike the `interrupted` latch it replaces it can never
+   * become a one-way "never write again" state.
+   */
+  private _persistedMessages = 0;
+  /**
+   * Whether the CURRENT non-resumable episode has already stamped its `interrupted`
+   * marker. Reset by every resumable save, so each new episode stamps exactly once and
+   * the "boundary unmoved" skip below can never swallow the stamp itself (GENC-1511).
+   */
+  private _interruptedStamped = false;
+  /** Consecutive failed saves; reset by any success. GENC-1511. */
+  private _saveFailures = 0;
+  /** When the failure count crossed {@link SAVE_FAILURES_BEFORE_BROKEN}; `undefined` = healthy. */
+  private _brokenSince?: number;
+  /** Whether this broken episode has already been reported to the host. */
+  private _brokenReported = false;
+  /** `savedAt` of the last snapshot that actually landed, for the host's message. */
+  private _lastSavedAt?: string;
+  /** Provider's reason for the most recent failure, for the host's message. */
+  private _lastFailureReason = '';
   /**
    * The loaded preferences blob (GENC-1351 §5.10 Phase 2), owned here so it's
    * **shared per session** — the element's `applyPreferenceBaseline` reconciler reads
@@ -186,6 +234,92 @@ export class SessionPersister {
     }
   }
 
+  /**
+   * Record a save outcome and, when persistence has been failing, decide whether now is the
+   * moment to tell the user (GENC-1511).
+   *
+   * The gate is `resumable`, NOT "is a turn running". `busy` was the obvious choice and it is
+   * useless here: a bootstrap journey is ONE turn — measured at 2817 s containing 82 widget
+   * interactions — so waiting for a turn boundary would hold the warning for 47 minutes. What
+   * actually matters is whether a reload can be resumed from the stored snapshot, and that is
+   * exactly what `resumable` already answers for the freeze. Bootstrap keeps everything in its
+   * machine context, so it is always resumable and gets told immediately; UI Builder keeps
+   * in-flight work in an out-of-band VFS buffer, so it waits for `idle`/`done` — which is also
+   * the point at which its files have been flushed and a reload costs nothing.
+   */
+  private recordSaveOutcome(ok: boolean, reason: string, savedAt?: string): void {
+    if (ok) {
+      const wasBroken = this._brokenSince !== undefined;
+      this._saveFailures = 0;
+      this._brokenSince = undefined;
+      this._lastSavedAt = savedAt ?? this._lastSavedAt;
+      if (wasBroken) {
+        // Withdraw the warning: a save landing means the store is caught up, which we have
+        // watched happen twice in the wild — a broken window is not necessarily permanent.
+        this._brokenReported = false;
+        this.deps.onPersistenceRecovered?.();
+      }
+      return;
+    }
+    this._saveFailures += 1;
+    this._lastFailureReason = reason;
+    if (this._saveFailures >= SAVE_FAILURES_BEFORE_BROKEN && this._brokenSince === undefined) {
+      this._brokenSince = Date.now();
+    }
+  }
+
+  /**
+   * Surface a broken episode if it is now safe to advise a reload.
+   *
+   * Gated on `resumable` and NOTHING else. An earlier draft added a 90 s backstop so a flow that
+   * errored and stuck mid-state could not hold the warning forever — that was wrong, and the
+   * review caught it: the modal's only action is a reload, so firing it while the agent is
+   * non-resumable forces the user to destroy exactly the out-of-band, in-flight work the gate
+   * exists to protect. Being told late is bad; being told to do the damaging thing is worse.
+   * Surfacing a stuck flow earlier needs non-blocking warning UI, not this modal.
+   */
+  private maybeReportBroken(resumable: boolean, liveMessages: number): void {
+    if (this._brokenSince === undefined || this._brokenReported || !resumable) return;
+    this._brokenReported = true;
+    this.deps.onPersistenceBroken?.({
+      unsavedMessages: Math.max(0, liveMessages - this._persistedMessages),
+      lastSavedAt: this._lastSavedAt,
+      reason: this._lastFailureReason,
+    });
+  }
+
+  /**
+   * Non-resumable-workflow gate (GENC-1351 §5.9): consult the active agent (the flow-owner
+   * during a locked flow, like `serialize`). A thrown predicate fails safe to persisting; no
+   * live active agent (e.g. the post-restore, pre-reactivation save) leaves it resumable and
+   * persists normally.
+   *
+   * Extracted from `persistSession` so that method stays under the complexity cap, and because
+   * this answer now has two consumers: the freeze decision, and whether it is safe to advise the
+   * user to reload (GENC-1511).
+   */
+  private async resolveResumable(
+    liveActive: ReturnType<NonNullable<AiDriver['getActiveAgent']>> | undefined,
+    key: string,
+    agentSnapshots: Record<string, unknown>,
+    messages: ChatMessage[],
+    s: SessionStoreReturn['store']['aiAssistant'],
+  ): Promise<boolean> {
+    if (!liveActive?.resumable) return true;
+    try {
+      return await liveActive.resumable({
+        agentName: liveActive.name,
+        sessionKey: key,
+        state: agentSnapshots[liveActive.name],
+        messages,
+        isFlowOwner: s.flowOwnerAgentName === liveActive.name,
+      });
+    } catch (e) {
+      logger.error('Session save: resumable() threw — persisting (fail-safe):', e);
+      return true;
+    }
+  }
+
   /**
    * Capture the current session to durable storage (GENC-1351 §5.1). Reads the
    * full transcript from the driver and the restorable scalars from the store, and
@@ -231,64 +365,69 @@ export class SessionPersister {
     );
     this._cache = cache;
 
-    // Non-resumable-workflow gate (GENC-1351 §5.9): consult the active agent (the
-    // flow-owner during a locked flow, like `serialize` above). A thrown predicate
-    // fails safe to persisting; no live active agent (e.g. the post-restore,
-    // pre-reactivation save) leaves it resumable and persists normally.
-    let resumable = true;
-    if (liveActive?.resumable) {
-      try {
-        resumable = await liveActive.resumable({
-          agentName: liveActive.name,
-          sessionKey: key,
-          state: agentSnapshots[liveActive.name],
-          messages,
-          isFlowOwner: s.flowOwnerAgentName === liveActive.name,
-        });
-      } catch (e) {
-        logger.error('Session save: resumable() threw — persisting (fail-safe):', e);
-        resumable = true;
-      }
-    }
+    const resumable = await this.resolveResumable(liveActive, key, agentSnapshots, messages, s);
+
+    // Report a broken episode at the first SAFE moment, which is what `resumable` decides.
+    // Deliberately before either branch acts, so the warning does not wait on the very write
+    // that is failing.
+    this.maybeReportBroken(resumable, messages.length);
 
     if (!resumable) {
-      // FREEZE while the flow runs: stop advancing the stored snapshot so the
-      // in-flight agent's work is never persisted and the *previous* conversation is
-      // kept intact ("infinite debounce while running"). The freeze target is the
-      // **currently-persisted** snapshot — the shared source of truth — NOT any
-      // per-view memory. Stamp it once with an `interrupted` marker so restore shows
-      // an assistant "start again" message; once stamped, subsequent saves no-op.
-      const existing = await provider.load(key).catch(() => null);
-      if (existing?.interrupted) return; // already frozen + stamped by some instance
+      // FREEZE THE FLOW STATE, NOT THE TRANSCRIPT (GENC-1511).
+      //
+      // The intent of §5.9 is the one stated on `PersistedSession.interrupted`: the
+      // conversation is persisted and restored in full, and only the running agent's
+      // flow-state is dropped. The original implementation did the opposite whenever a
+      // snapshot already existed — it froze at the **stored** blob (`existing ?? …`),
+      // so everything since the last resumable save was silently rolled back, transcript
+      // included, and `if (existing?.interrupted) return` then latched that rollback in
+      // for the life of the page. A UI-builder session spent 3h17m in that state: 256
+      // loads, zero writes, and a reload that took the user back to a mid-bootstrap
+      // snapshot from three hours earlier.
+      //
+      // So the freeze target is now ALWAYS the live transcript through the last user
+      // message — the conversation plus the prompt that started the flow, with the
+      // agent's in-flight turns and flow-state dropped. Advancing on each new boundary
+      // means a long-running flow can no longer cost the user the work that preceded it.
       const { resumeMessage, resumePrompt } = resolveNonResumableNotice({
         notResumableMessage: liveActive?.notResumableMessage,
         flowActivationPrompt: s.flowActivationPrompt,
         messages,
         defaultMessage: DEFAULT_NOT_RESUMABLE_MESSAGE,
       });
-      // Freeze at the persisted snapshot (the last resumable state). Fallback when
-      // nothing is stored yet — a genuinely fresh session that goes non-resumable on
-      // its first turn, OR a load that failed (a corrupt read, a transient network
-      // error): freeze at the current transcript **through the last user message**
-      // (flow-state stripped), so we keep the conversation + the prompt that started
-      // the flow but drop the agent's in-flight turns. NEVER an empty snapshot —
-      // losing the conversation is the one outcome we must avoid.
-      const frozen =
-        existing ??
-        createPersistedSession({
-          sessionKey: key,
-          host: window.location.host,
-          messages: keepThroughLastUserMessage(messages),
-          activeAgentName: s.activeAgent?.name,
-          pinnedAgentName: s.pinnedAgentName,
-          flowOwnerAgentName: null,
-          sessionCostUsd: s.sessionUsage.costUsd,
-          contextTokens: s.contextTokens,
-          contextLimit: s.contextLimit,
-          activeModel: s.activeModel,
-          activeProviderName: s.activeProviderName,
-          agentSnapshots: {},
-        });
+      // Never regress the stored transcript. `keepThroughLastUserMessage` alone can be
+      // SHORTER than what is already persisted — an agent that goes non-resumable without
+      // a fresh user prompt (auto-advance, a resumed journey step) would otherwise drop
+      // completed exchanges that were already safely stored. Taking the max of the two
+      // makes the boundary monotonic: it advances with each new prompt and never rewinds.
+      const boundary = Math.max(
+        keepThroughLastUserMessage(messages).length,
+        this._persistedMessages,
+      );
+      const frozen = createPersistedSession({
+        sessionKey: key,
+        host: window.location.host,
+        messages: messages.slice(0, Math.min(boundary, messages.length)),
+        activeAgentName: s.activeAgent?.name,
+        pinnedAgentName: s.pinnedAgentName,
+        flowOwnerAgentName: null,
+        sessionCostUsd: s.sessionUsage.costUsd,
+        contextTokens: s.contextTokens,
+        contextLimit: s.contextLimit,
+        activeModel: s.activeModel,
+        activeProviderName: s.activeProviderName,
+        agentSnapshots: {},
+      });
+      // Skip the write when the frozen boundary has not moved — a flow autosaves on every
+      // transcript change, and while it runs the last user message (and therefore the
+      // frozen content) is unchanged, so re-writing it would put one ~MB PUT on the wire
+      // per tool call for nothing. Keyed on CONTENT, unlike the old `interrupted` latch:
+      // it re-arms the moment the boundary moves, and the resumable path below clears it,
+      // so it can never become the one-way "never write again" state it replaces. It also
+      // drops the `provider.load` this branch used to issue on every single autosave.
+      if (this._persistedMessages === frozen.messages.length && this._interruptedStamped) {
+        return;
+      }
       this.logMeta('persistence.suppressed', {
         agent: liveActive?.name ?? null,
         isFlowOwner: s.flowOwnerAgentName === liveActive?.name,
@@ -300,8 +439,34 @@ export class SessionPersister {
           ...frozen,
           interrupted: { message: resumeMessage, prompt: resumePrompt },
         });
+        this._persistedMessages = frozen.messages.length;
+        this._interruptedStamped = true;
+        this.recordSaveOutcome(true, '', frozen.savedAt);
         logger.debug('Flow non-resumable — froze snapshot + stamped interrupted marker', { key });
       } catch (e) {
+        // GENC-1511: this catch used to be the ONE swallowed failure left after the save-failed
+        // event was added to the resumable branch — so a session that broke while an agent was
+        // mid-flow still reported nothing at all, which is precisely the blind spot the
+        // user-facing warning exists to cover.
+        this.recordSaveOutcome(false, (e as Error)?.message ?? String(e));
+        // Deliberately NOT reporting from here. This is the non-resumable branch and a reload is
+        // the modal's only action, so advising one now would destroy the in-flight work the
+        // snapshot could not carry. `recordSaveOutcome` has already set `_brokenSince`, so the
+        // next `persistSession` whose `resolveResumable()` returns true reports it — late, but at
+        // a point where the advice is safe to take.
+        //
+        // (An earlier version called `maybeReportBroken(false, …)` here. Review caught that it was
+        // an unconditional no-op — that method returns immediately on `!resumable` — and that its
+        // comment pointed at a 90 s backstop which had itself been removed earlier in review.)
+        this.logMeta('persistence.save-failed', {
+          messages: frozen.messages.length,
+          agents: [],
+          active: liveActive?.name ?? null,
+          hasSerialize: !!liveActive?.serialize,
+          frozen: true,
+          error: (e as Error)?.name ?? typeof e,
+          message: (e as Error)?.message ?? String(e),
+        });
         logger.error('Session save (interrupted marker) failed:', e);
       }
       return;
@@ -326,17 +491,55 @@ export class SessionPersister {
     // Observability (GENC-1351): record what each autosave captured for stateful
     // agents — `agents: []` here means no machine snapshot was taken (the bug to
     // watch for: the active agent's `serialize()` returned nothing).
-    this.logMeta('persistence.saved', {
+    //
+    // GENC-1511: this event is emitted AFTER the write resolves, never before. It used
+    // to be logged ahead of `provider.save`, which made it a record of an ATTEMPT while
+    // reading as a record of a SAVE — and the failure below was swallowed into
+    // `logger.error`, which is not wired to Sentry. A session whose writes had been
+    // failing for three hours therefore showed 52 cheerful `persistence.saved` events
+    // and no failures anywhere: not in the debug log, not in Loki, not in Sentry. The
+    // whole incident was invisible until the box's nginx access log was read by hand.
+    const captured = {
       messages: messages.length,
       agents: Object.keys(agentSnapshots),
       active: liveActive?.name ?? null,
       hasSerialize: !!liveActive?.serialize,
       agentSnapshots,
-    });
+    };
     try {
       await provider.save(key, snapshot);
+      this._persistedMessages = messages.length;
+      this._interruptedStamped = false;
+      this.recordSaveOutcome(true, '', snapshot.savedAt);
+      this.logMeta('persistence.saved', captured);
       logger.debug('Session saved', { key, messages: messages.length });
     } catch (e) {
+      // `high` importance, and deliberately verbose: this is the one event that says
+      // "the transcript on screen is no longer backed by the store". `name` separates a
+      // provider/transport rejection from a serialisation fault — a `TypeError` here
+      // means the body never reached the wire at all, because a provider builds its
+      // request body inside the `fetch` init, so a throw while serialising creates no
+      // request and leaves no server-side trace.
+      this.recordSaveOutcome(false, (e as Error)?.message ?? String(e));
+      // Report straight away rather than waiting for the next attempt: we are on the resumable
+      // path, so a reload is safe NOW, and a one-cycle delay is a second of extra exposure for
+      // no benefit.
+      this.maybeReportBroken(true, messages.length);
+      // Deliberately NOT `...captured`: that carries the raw `agentSnapshots` object, and
+      // `recordMetaEvent` stores the detail BY REFERENCE. When the save failed *because* that
+      // object is circular — the fault this catch exists for — the high-importance failure event
+      // became circular too, so `assembleDebugLog` threw while stringifying it and
+      // `downloadDebugLog` could not produce the log this modal tells the user to save. Names
+      // and scalars only; the success event above may keep the snapshots, because a landed write
+      // has already proved them serialisable.
+      this.logMeta('persistence.save-failed', {
+        messages: captured.messages,
+        agents: captured.agents,
+        active: captured.active,
+        hasSerialize: captured.hasSerialize,
+        error: (e as Error)?.name ?? typeof e,
+        message: (e as Error)?.message ?? String(e),
+      });
       logger.error('Session save failed:', e);
     }
   }
@@ -405,6 +608,9 @@ export class SessionPersister {
       // by the history change below, before any agent re-activates) preserves the
       // machine snapshot instead of overwriting it with an empty one (GENC-1351).
       this._cache = { ...snapshot.agentSnapshots };
+      // Seed the monotonic freeze floor too (GENC-1511): a flow that goes non-resumable
+      // straight after a restore must not freeze BELOW what the restore just brought back.
+      this._persistedMessages = trimmed.length;
       // Observability (GENC-1351): record exactly what the restore primed, so a
       // post-reload debug-log export shows whether a stateful agent's snapshot
       // actually came back (meta events reset on reload, so this is the only window
@@ -537,6 +743,8 @@ export class SessionPersister {
    */
   async clearRestoreCore(): Promise<void> {
     this._cache = {};
+    this._persistedMessages = 0;
+    this._interruptedStamped = false;
     const { provider } = this.deps.getPersistence();
     const key = this.stateKey;
     if (!provider) return;