@memberjunction/server 6.2.0-edge.5 → 6.2.0-edge.7

package/src/agentSessions/HandoffOfferExpiry.ts

@@ -0,0 +1,18 @@
+import { HandoffOfferRegistry } from '@memberjunction/livekit-room-server';
+import type { HandoffOfferSweepSettings } from '../backgroundSweepConfigUnits.js';
+
+/**
+ * Applies `agentSessions.handoffOfferExpiry` to the process-wide handoff offer registry. The registry
+ * starts its expiry sweep (a read of `MJ: Interaction Offers` every 15 seconds) as soon as it loads, on
+ * every MJAPI whatever its role; this either stops that sweep, so an idle server sends no periodic
+ * query for it, or restarts it on the configured interval. Overdue offers still read as expired when
+ * the sweep is off. See the Serverless Database Auto-Pause guide.
+ */
+export function ApplyHandoffOfferExpirySettings(settings: HandoffOfferSweepSettings): void {
+    const registry = HandoffOfferRegistry.Instance;
+    if (settings.enabled) {
+        registry.StartPeriodicSweep(settings.sweepIntervalMs);
+    } else {
+        registry.StopPeriodicSweep();
+    }
+}

package/src/agentSessions/ReturningVisitorRecap.ts

@@ -146,6 +146,7 @@ async function recapAlreadyExists(conversationId: string, contextUser: UserInfo)
       ExtraFilter: `SourceConversationID = '${conversationId}' AND IsAutoGenerated = 1 AND Type = 'Context'`,
       Fields: ['ID'],
       MaxRows: 1,
+      SkipTotalRowCount: true,
       ResultType: 'simple',
     },
     contextUser,

package/src/agentSessions/SessionJanitor.ts

@@ -19,6 +19,8 @@ import {
 } from '@memberjunction/ai-agents';
 import { GetCurrentHostInstance, GetHostInstanceID, HostInstanceIdentity } from './HostInstance.js';
 import { SessionManager, SessionCloseReason } from './SessionManager.js';
+import type { SessionJanitorSettings } from '../backgroundSweepConfigUnits.js';
+import { ExpiryCloseReason, ExpiryReason } from './sessionDeadline.js';
 
 /** Entity name for session rows (kept in sync with {@link SessionManager}). */
 const SESSION_ENTITY = 'MJ: AI Agent Sessions';
@@ -195,6 +197,24 @@ interface RecoveryVisit {
     Recovered: boolean;
 }
 
+/**
+ * The close reason for a row the staleness sweep's SQL already judged stale (`LastActiveAt < cutoff`).
+ * {@link ExpiryCloseReason} returns null for such a row only when `LastActiveAt` will not parse (or the
+ * threshold is non-finite); skipping it would leave it `Active` forever, so it closes as `'Idle'` and the
+ * fallback is logged with the session ID.
+ */
+function staleRowCloseReason(session: MJAIAgentSessionEntity, nowMs: number, thresholdMs: number): ExpiryReason {
+    const reason = ExpiryCloseReason(session, nowMs, thresholdMs);
+    if (reason !== null) {
+        return reason;
+    }
+    LogError(
+        `[SessionJanitor] Staleness sweep: session ${session.ID} has LastActiveAt ${String(session.LastActiveAt)}; ` +
+            'LastActiveAt unparseable; closing as Idle',
+    );
+    return 'Idle';
+}
+
 /**
  * `BaseSingleton` background reconciler that keeps the durable `AIAgentSession` state from drifting
  * away from volatile process reality. A crash/redeploy vaporizes a host's in-memory sockets but
@@ -212,9 +232,12 @@ interface RecoveryVisit {
  *    `closeThresholdMinutes`, regardless of host. Catches sessions whose owner died without a clean
  *    reboot (OOM, scaled-down pod).
  * 3. **Max-duration sweep ({@link RunMaxDurationSweep})** — run on every periodic tick after the
- *    staleness sweep. Closes any session past its stored hard deadline (the public voice cost cap).
+ *    staleness sweep. Closes any session past its stored hard deadline (the public voice cost cap), and
+ *    any deadline-carrying session whose idle moment has passed; it stamps that row `'Idle'` when the idle
+ *    moment came before the deadline.
  *
- * The close sweeps stamp `CloseReason = 'Janitor'`. A shutdown-time path — {@link RunShutdownDrain},
+ * Startup recovery stamps `CloseReason = 'Janitor'`; the staleness and max-duration sweeps stamp `'Idle'` or
+ * `'TimeLimit'`, whichever expiry moment passed first ({@link ExpiryCloseReason}). A shutdown-time path — {@link RunShutdownDrain},
  * invoked from {@link Shutdown} during the graceful ShutdownRegistry drain — closes this exact host
  * instance's own live sessions with `CloseReason = 'Shutdown'`.
  *
@@ -318,6 +341,39 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
         this.scheduleSweep();
     }
 
+    /**
+     * Starts the janitor the way the host's `agentSessions.janitor` settings ask: applies the interval
+     * and close threshold, then {@link Start} when enabled, or {@link StartRecoveryOnly} when not.
+     * Throws (before doing any work) on an invalid interval or threshold; see {@link Configure}.
+     */
+    public async StartWithSettings(settings: SessionJanitorSettings, provider: DatabaseProviderBase, systemUser: UserInfo): Promise<void> {
+        this.Configure({ sweepIntervalMs: settings.sweepIntervalMs, closeThresholdMinutes: settings.closeThresholdMinutes });
+        if (settings.enabled) {
+            await this.Start(provider, systemUser);
+        } else {
+            await this.StartRecoveryOnly(provider, systemUser);
+        }
+    }
+
+    /**
+     * {@link Start} without the periodic tick, for hosts that turned the janitor off: run own-host
+     * startup recovery once and register for the graceful-shutdown drain, but schedule nothing, so an
+     * idle process issues no periodic queries. Stale-session, max-duration and recording-recovery
+     * sweeps then do not run in this process. Stops a tick an earlier {@link Start} scheduled.
+     */
+    public async StartRecoveryOnly(provider: DatabaseProviderBase, systemUser: UserInfo): Promise<void> {
+        this.Stop();
+        this._provider = provider;
+        this._systemUser = systemUser;
+        this.ensureRegistered();
+        await this.RunStartupRecovery(provider, systemUser);
+    }
+
+    /** Whether the periodic tick is currently scheduled (diagnostics and tests). */
+    public get IsSweepScheduled(): boolean {
+        return this._sweepTimer !== null;
+    }
+
     /**
      * Stops the periodic tick and keeps any new recording recovery pass from starting until the next
      * {@link Start}, including one a tick already in progress would have started. A pass that is already
@@ -335,7 +391,7 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
      * {@link IShutdownable}: stop the timer, then drain this host's own live sessions so a
      * graceful stop never strands `Active`/`Idle` rows for the next boot's janitor to mop up, then wait
      * (at most {@link RECOVERY_SHUTDOWN_WAIT_MS}) for an in-flight recording recovery pass.
-     * Drained sessions are stamped `CloseReason = 'Shutdown'` (vs. `'Janitor'` for crash orphans),
+     * Drained sessions are stamped `CloseReason = 'Shutdown'` (vs. `'Janitor'` for crash orphans from an earlier boot),
      * so the dashboards can tell a clean redeploy from a reconciled crash. Never throws; the drain
      * is skipped when {@link Start} was never called (no captured provider/user).
      */
@@ -360,7 +416,7 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
     public async RunShutdownDrain(provider: IMetadataProvider, systemUser: UserInfo): Promise<number> {
         const current = GetHostInstanceID().replace(/'/g, "''");
         const filter = `Status IN ('Active','Idle') AND HostInstanceID = '${current}'`;
-        const closed = await this.sweepAndClose(filter, provider, systemUser, 'Shutdown');
+        const closed = await this.sweepAndClose(filter, provider, systemUser, () => 'Shutdown');
         if (closed > 0) {
             LogStatus(`[SessionJanitor] Shutdown drain closed ${closed} live session(s) owned by this host instance`);
         }
@@ -389,8 +445,9 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
             `AND HostInstanceID LIKE '${prefix}%' ` +
             `AND HostInstanceID <> '${current}'`;
         // The LIKE narrows the read; the exact check decides, since LIKE reads a `_` in a host name as any character.
-        const isPriorBoot = (session: MJAIAgentSessionEntity): boolean => hostInstance.IsPriorBoot(session.HostInstanceID);
-        const closed = await this.sweepAndClose(filter, provider, systemUser, 'Janitor', isPriorBoot);
+        const reasonFor = (session: MJAIAgentSessionEntity): SessionCloseReason | null =>
+            hostInstance.IsPriorBoot(session.HostInstanceID) ? 'Janitor' : null;
+        const closed = await this.sweepAndClose(filter, provider, systemUser, reasonFor);
         if (closed > 0) {
             LogStatus(
                 `[SessionJanitor] Startup recovery closed ${closed} orphaned session(s) from an earlier boot of this instance ` +
@@ -402,12 +459,18 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
 
     /**
      * Force-close any `Active`/`Idle` session whose `LastActiveAt` is older than the configured
-     * close threshold, regardless of host. Idempotent and concurrency-safe. Returns the count closed.
+     * close threshold, regardless of host. Stamped `'Idle'`, or `'TimeLimit'` when the row's authored deadline
+     * passed before its idle moment ({@link ExpiryCloseReason}). A row the SQL judged stale is never skipped:
+     * when its `LastActiveAt` will not parse it closes as `'Idle'` with a `LogError` ({@link staleRowCloseReason}).
+     * Idempotent and concurrency-safe. Returns the count closed.
      */
     public async RunStalenessSweep(provider: IMetadataProvider, systemUser: UserInfo): Promise<number> {
-        const cutoffIso = new Date(Date.now() - this._config.closeThresholdMinutes * 60_000).toISOString();
+        // One clock read feeds both the SQL cutoff and the per-row decision, so they cannot disagree.
+        const nowMs = Date.now();
+        const thresholdMs = this._config.closeThresholdMinutes * 60_000;
+        const cutoffIso = new Date(nowMs - thresholdMs).toISOString();
         const filter = `Status IN ('Active','Idle') AND LastActiveAt < '${cutoffIso}'`;
-        const closed = await this.sweepAndClose(filter, provider, systemUser, 'Janitor');
+        const closed = await this.sweepAndClose(filter, provider, systemUser, s => staleRowCloseReason(s, nowMs, thresholdMs));
         if (closed > 0) {
             LogStatus(`[SessionJanitor] Staleness sweep closed ${closed} stale session(s) (>${this._config.closeThresholdMinutes}m idle)`);
         }
@@ -422,20 +485,18 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
      *
      * Only sessions that CARRY a deadline are loaded (a cheap `Config_ LIKE` pre-filter), then the exact
      * ISO deadline is parsed and compared in JS (`Config_` is JSON, not a queryable column). Stamped
-     * `CloseReason = 'Janitor'`, idempotent + concurrency-safe like the other sweeps. Returns the count closed.
+     * `'TimeLimit'`, or `'Idle'` when the row's idle moment passed before its deadline ({@link ExpiryCloseReason});
+     * idempotent + concurrency-safe like the other sweeps. Returns the count closed.
      */
     public async RunMaxDurationSweep(provider: IMetadataProvider, systemUser: UserInfo): Promise<number> {
         const nowMs = Date.now();
         // Only consider sessions that carry a deadline marker — keeps this sweep cheap (it never touches
         // the far-more-common uncapped sessions) while the JS check below enforces the exact deadline.
         const filter = `Status IN ('Active','Idle') AND Config LIKE '%maxSessionDeadlineIso%'`;
-        const isExpired = (session: MJAIAgentSessionEntity): boolean => {
-            const deadlineMs = this.parseSessionDeadlineMs(session.Config_);
-            return deadlineMs != null && deadlineMs <= nowMs;
-        };
-        const closed = await this.sweepAndClose(filter, provider, systemUser, 'Janitor', isExpired);
+        const thresholdMs = this._config.closeThresholdMinutes * 60_000;
+        const closed = await this.sweepAndClose(filter, provider, systemUser, s => ExpiryCloseReason(s, nowMs, thresholdMs));
         if (closed > 0) {
-            LogStatus(`[SessionJanitor] Max-duration sweep closed ${closed} session(s) past their hard duration cap`);
+            LogStatus(`[SessionJanitor] Max-duration sweep closed ${closed} capped session(s) past their deadline or idle threshold`);
         }
         return closed;
     }
@@ -647,9 +708,9 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
 
     /**
      * Gives a status-less session with ledger shards back a `Pending` status so it can be claimed (the
-     * claim only takes Pending/Partial/stale Assembling). The status is lost when a `BaseEntity.Save` of
-     * the session (e.g. its close) loaded the row before a shard or terminal proc wrote it and saved
-     * after: `spUpdate` rewrites every column, so it puts back the stale NULL status and counts.
+     * claim only takes Pending/Partial/stale Assembling). That is how statuses were lost before #6010
+     * made the ledger columns not updatable through an entity save (a stale `Save` of the session, e.g. its
+     * close, put back the NULL status and counts). The restore stays for rows hit before then.
      *
      * The terminal proc is the existing way to set a NULL status to `Pending`. It is stamped with the
      * counts the session still stores, or 0 for a NULL count (the proc accepts any count over NULL), and
@@ -705,23 +766,6 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
         }
     }
 
-    /** Parses the absolute deadline (ms) from a session's `Config_` JSON, or null when absent/malformed. */
-    private parseSessionDeadlineMs(configJson: string | null | undefined): number | null {
-        if (!configJson) {
-            return null;
-        }
-        try {
-            const parsed = JSON.parse(configJson) as { maxSessionDeadlineIso?: string };
-            if (typeof parsed.maxSessionDeadlineIso !== 'string') {
-                return null;
-            }
-            const ms = Date.parse(parsed.maxSessionDeadlineIso);
-            return Number.isNaN(ms) ? null : ms;
-        } catch {
-            return null;
-        }
-    }
-
     // ----- internals -------------------------------------------------------------------------
 
     /** Register for graceful shutdown exactly once. */
@@ -993,7 +1037,9 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
 
     /**
      * Page through every session matching `filter` with keyset (`AfterKey`) pagination and close each
-     * via {@link SessionManager.CloseSession}, stamping `closeReason` on every row it transitions.
+     * via {@link SessionManager.CloseSession}, stamping the reason `reasonFor` returns for that row.
+     * A `null` reason skips the row (the SQL filter only narrows; `reasonFor` decides), and skipped rows
+     * are dropped before the channel batch load so it covers only rows that will close.
      * Returns the number successfully closed. A `Closed`-by-now row (raced by another instance) is a
      * harmless no-op that keeps its original reason.
      */
@@ -1001,30 +1047,34 @@ export class SessionJanitor extends BaseSingleton<SessionJanitor> implements ISh
         filter: string,
         provider: IMetadataProvider,
         systemUser: UserInfo,
-        closeReason: SessionCloseReason,
-        shouldClose?: (session: MJAIAgentSessionEntity) => boolean,
+        reasonFor: (session: MJAIAgentSessionEntity) => SessionCloseReason | null,
     ): Promise<number> {
         let closedCount = 0;
         await this.forEachSessionPage(filter, provider, systemUser, async fetched => {
-            // Optional in-JS narrowing (e.g. exact deadline check the SQL pre-filter can't express).
-            const page = shouldClose ? fetched.filter(shouldClose) : fetched;
-            if (page.length === 0) {
+            const toClose: Array<{ session: MJAIAgentSessionEntity; reason: SessionCloseReason }> = [];
+            for (const session of fetched) {
+                const reason = reasonFor(session);
+                if (reason !== null) {
+                    toClose.push({ session, reason });
+                }
+            }
+            if (toClose.length === 0) {
                 return;
             }
             // Batch-load every channel for this whole page of sessions in ONE query, then hand each
             // session its own slice to CloseSession — avoids the N+1 channel read (one RunView per
             // closing session) that tripped the sequential / multiple-same-entity telemetry.
             const channelsBySession = await this.sessionManager.LoadActiveChannelsBySession(
-                page.map(s => s.ID),
+                toClose.map(c => c.session.ID),
                 systemUser,
                 provider,
             );
-            for (const session of page) {
+            for (const { session, reason } of toClose) {
                 const closed = await this.sessionManager.CloseSession(
                     session.ID,
                     systemUser,
                     provider,
-                    closeReason,
+                    reason,
                     channelsBySession.get(session.ID.toLowerCase()) ?? [],
                 );
                 if (closed) {

package/src/agentSessions/SessionManager.ts

@@ -1,18 +1,21 @@
-import { IMetadataProvider, UserInfo, LogError, RunView } from '@memberjunction/core';
+import { IMetadataProvider, UserInfo, LogError, LogStatus, RunView } from '@memberjunction/core';
 import { MJLruCache } from '@memberjunction/global';
 import {
     MJAIAgentSessionEntity,
     MJAIAgentSessionChannelEntity,
     MJConversationEntity,
 } from '@memberjunction/core-entities';
+import { RunWithTrustedSessionConfigWrites } from '@memberjunction/core-entities-server';
 import { AIAgentPermissionHelper } from '@memberjunction/ai-engine-base';
 import { RealtimeClientSessionService, RealtimeChannelServerHost } from '@memberjunction/ai-agents';
 import type { BridgeDisconnectReason } from '@memberjunction/ai-bridge-base';
+import { ParseSessionDeadlineMs, VerifyTimeLimitClaim } from './sessionDeadline.js';
 import { GetHostInstanceID } from './HostInstance.js';
 import { WriteReturningVisitorRecap } from './ReturningVisitorRecap.js';
 import { SessionRunIDVerifier, SessionRunIDs } from './SessionRunIDVerifier.js';
 import { ResolveScopedAnonymousRunUser } from '../realtimeWidget/widgetGuestElevation.js';
 import { RecordingAssemblyScheduler } from '../realtimeSessions/RecordingAssemblyScheduler.js';
+import { ResolveSessionScopeIdentity } from '../realtimeSessions/sessionAccess.js';
 
 /** Entity names — centralised so the `MJ:`-prefix convention is applied in exactly one place. */
 const SESSION_ENTITY = 'MJ: AI Agent Sessions';
@@ -39,11 +42,14 @@ export interface CreateSessionInput {
 /**
  * Why a session was closed — persisted to `AIAgentSession.CloseReason` alongside the
  * `Status = 'Closed'` transition so the admin dashboards can distinguish a user hanging up
- * (`Explicit`) from janitor reconciliation (`Janitor`), a graceful host drain (`Shutdown`),
- * or a failure-path teardown (`Error`). `NULL` in the column means "legacy/unknown" — rows
- * closed before this column existed.
+ * (`Explicit`) from janitor reconciliation (`Janitor`, an orphan from an earlier boot), a graceful
+ * host drain (`Shutdown`), a failure-path teardown (`Error`), an expired authored deadline
+ * (`TimeLimit`) or a session left quiet past the idle threshold (`Idle`). `NULL` in the column means
+ * "legacy/unknown" — rows closed before this column existed.
+ *
+ * Derived from the generated entity so the column's CHECK constraint stays the single source of truth.
  */
-export type SessionCloseReason = 'Explicit' | 'Janitor' | 'Shutdown' | 'Error';
+export type SessionCloseReason = NonNullable<MJAIAgentSessionEntity['CloseReason']>;
 
 /**
  * The {@link SessionCloseReason} for a session whose bridged agent has left (see
@@ -153,11 +159,13 @@ export class SessionManager {
     /**
      * Authorize and create a new session. Flow:
      * 1. `CanRun` check on the agent — denied → {@link SessionAuthorizationError}, no row written.
-     * 2. Resolve the conversation (use the supplied one, or create+link a fresh Conversation).
+     * 2. Resolve the conversation (use the supplied one, or create+link a fresh Conversation). An anonymous
+     *    caller may only supply a conversation stamped with its own scope identity.
      * 3. Persist the `AIAgentSession` as `Active`, stamped with this host and `LastActiveAt = now`.
      *
      * @returns the saved {@link MJAIAgentSessionEntity}.
-     * @throws {SessionAuthorizationError} when the user may not run the agent.
+     * @throws {SessionAuthorizationError} when the user may not run the agent, or an anonymous caller supplies a
+     *   conversation that is not its own.
      * @throws {Error} when conversation creation or session save fails.
      */
     public async CreateSession(
@@ -166,6 +174,9 @@ export class SessionManager {
         provider: IMetadataProvider,
     ): Promise<MJAIAgentSessionEntity> {
         await this.assertCanRun(input.agentID, contextUser);
+        if (input.conversationID && contextUser.IsMagicLinkAnonymous) {
+            await this.assertAnonymousOwnsConversation(input.conversationID, contextUser, provider);
+        }
 
         const conversationID = input.conversationID
             ?? await this.createConversation(input, contextUser, provider);
@@ -185,6 +196,8 @@ export class SessionManager {
      *   call sites (the user-initiated close mutations) stamp the common case without modification;
      *   background callers (janitor sweeps, shutdown drain, error teardowns) must pass their reason
      *   explicitly. `NULL` rows remain only for legacy data closed before the column existed.
+     *   A `'TimeLimit'` is verified against the session's stored deadline ({@link VerifyTimeLimitClaim}); a claim the
+     *   deadline does not back is recorded as `'Explicit'` and logged, never refused.
      *
      * @remarks P5 adds in-flight-run abort + `ClientToolRequestManager.ClearSession` here.
      */
@@ -209,7 +222,9 @@ export class SessionManager {
             return true;
         }
 
-        const closed = await this.markSessionClosed(session, closeReason);
+        // Verified once: the stamped reason and the plugin notification must agree, so a client's unbacked claim steers neither.
+        const verifiedReason = this.verifiedCloseReason(session, closeReason);
+        const closed = await this.markSessionClosed(session, verifiedReason);
         if (!closed) {
             return false;
         }
@@ -222,7 +237,7 @@ export class SessionManager {
         }
         await this.disconnectChannels(agentSessionID, contextUser, provider, preloadedChannels);
         await this.finalizeObservabilityRuns(session, contextUser, provider);
-        await this.notifyChannelPluginsSessionClosed(agentSessionID, closeReason);
+        await this.notifyChannelPluginsSessionClosed(agentSessionID, verifiedReason);
         // Returning-visitor recap (RV2): if this session's conversation is returning-visitor-enabled,
         // summarize it into an Active memory note so the visitor's next session opens with prior context.
         // Best-effort + no-op for non-returning-visitor conversations; never blocks teardown.
@@ -230,6 +245,25 @@ export class SessionManager {
         return true;
     }
 
+    /**
+     * Returns the reason to stamp: a `'TimeLimit'` claim the session's stored deadline does not back becomes
+     * `'Explicit'` (logged with the stored deadline); every other reason passes through.
+     */
+    private verifiedCloseReason(session: MJAIAgentSessionEntity, closeReason: SessionCloseReason): SessionCloseReason {
+        if (closeReason !== 'TimeLimit') {
+            return closeReason;
+        }
+        const verified = VerifyTimeLimitClaim(session, Date.now());
+        if (verified === 'Explicit') {
+            const deadlineMs = ParseSessionDeadlineMs(session.Config_);
+            LogStatus(
+                `SessionManager.CloseSession: TimeLimit claim for session ${session.ID} not backed by its stored deadline ` +
+                    `(${deadlineMs === null ? 'none stored' : new Date(deadlineMs).toISOString()}); closing as Explicit.`,
+            );
+        }
+        return verified;
+    }
+
     /**
      * Closes a session that was created for one bridged agent (a bot in a meeting room) once that agent's bridge has
      * ended, whatever ended it: the agent was stopped, the meeting was ended, everyone left, the model session was lost.
@@ -448,6 +482,23 @@ export class SessionManager {
 
     // ----- internals -------------------------------------------------------------------------
 
+    /**
+     * Throws {@link SessionAuthorizationError} unless the anonymous caller owns the conversation it wants to bind a
+     * new session to: the conversation, read as the caller, loads, and its `ExternalID` equals the caller's scope
+     * identity ({@link ResolveSessionScopeIdentity}). A caller with no scope identity is refused. Every anonymous
+     * visitor shares one Anonymous user, so row-level security alone may let one visitor read another's
+     * conversation; without this check the new session row and its relays would point into that conversation.
+     */
+    private async assertAnonymousOwnsConversation(conversationID: string, contextUser: UserInfo, provider: IMetadataProvider): Promise<void> {
+        const conversation = await provider.GetEntityObject<MJConversationEntity>(CONVERSATION_ENTITY, contextUser);
+        const loaded = await conversation.Load(conversationID);
+        const scopeIdentity = ResolveSessionScopeIdentity(contextUser);
+        if (!loaded || !scopeIdentity || conversation.ExternalID !== scopeIdentity) {
+            LogError(`SessionManager.CreateSession: refused anonymous user ${contextUser.ID} binding a session to conversation ${conversationID} (${loaded ? 'not its own' : 'not readable'}).`);
+            throw new SessionAuthorizationError('Not authorized to start a session on this conversation.');
+        }
+    }
+
     /** Throws {@link SessionAuthorizationError} unless the user has `CanRun` on the agent. */
     private async assertCanRun(agentID: string, contextUser: UserInfo): Promise<void> {
         const canRun = await AIAgentPermissionHelper.HasPermission(agentID, contextUser, 'run');
@@ -468,13 +519,13 @@ export class SessionManager {
         conversation.NewRecord();
         conversation.UserID = input.userID;
         conversation.Name = 'Agent Session';
-        // For a magic-link-anonymous principal (e.g. a public web-widget voice guest), stamp the
-        // session's conversation with the signed per-session scope so the Widget Guest RLS filters
-        // ({{ScopeResourceID}}) isolate this session — and everything chained to it (AI Agent
-        // Sessions via ConversationID, Session Channels via the session) — from other guests
-        // sharing the Anonymous UserID. No-op for named principals (no scope → default ExternalID).
-        if (contextUser.MagicLinkScope?.ResourceID) {
-            conversation.ExternalID = contextUser.MagicLinkScope.ResourceID;
+        // Stamp the scope identity AuthorizeSessionAccess compares against (one rule, one place:
+        // ResolveSessionScopeIdentity) — the token's resource scope when it has one, else an anonymous
+        // visitor's mj_sid. This isolates anonymous visitors that share the Anonymous UserID, and keeps
+        // the {{ScopeResourceID}} RLS filters matching the visitor's own rows. No-op for unscoped named principals.
+        const scopeIdentity = ResolveSessionScopeIdentity(contextUser);
+        if (scopeIdentity) {
+            conversation.ExternalID = scopeIdentity;
         }
 
         // Returning-visitor memory (RV1/RV2/RV4) for the VOICE path: the widget guest token carries the
@@ -539,9 +590,9 @@ export class SessionManager {
     }
 
     /**
-     * Loads a session entity by ID, returning null when it cannot be loaded. The server entity
-     * (`MJAIAgentSessionEntityServer`) keeps the lifecycle saves that follow from writing back the
-     * recording ledger's columns (#5294).
+     * Loads a session entity by ID, returning null when it cannot be loaded. The lifecycle saves that
+     * follow cannot write back the recording ledger's columns: those have `AllowUpdateAPI=0`, so they are
+     * not parameters of `spUpdateAIAgentSession` (#5294, #6010).
      */
     private async loadSession(
         agentSessionID: string,
@@ -561,7 +612,9 @@ export class SessionManager {
         session.Status = 'Closed';
         session.ClosedAt = new Date();
         session.CloseReason = closeReason;
-        return this.saveOrLog(session, 'CloseSession');
+        // The session entity refuses a server-only CloseReason from an untrusted save; this is the server's own
+        // (already verified) close, so it saves inside the trusted session-write scope.
+        return RunWithTrustedSessionConfigWrites(() => this.saveOrLog(session, 'CloseSession'));
     }
 
     /** Marks every channel row of the session `Disconnected` (with `DisconnectedAt`), if not already. */

package/src/agentSessions/conversationBrowsers.ts

@@ -0,0 +1,143 @@
+/**
+ * @fileoverview The remote browsers this process holds for TEXT conversations: who owns each and when it
+ * was last used. Backs the caps (`realtime.conversationBrowser.maxPerUser` and `maxAnonymousTotal`) and ends browsers
+ * nobody uses any more, since a reloaded or closed tab never ends its own
+ * (`realtime.conversationBrowser.idleMinutes`). Realtime calls' browsers are not tracked here: they end
+ * with their session.
+ *
+ * @module @memberjunction/server/agentSessions
+ */
+import { GraphQLError } from 'graphql';
+import { LogError, LogStatus } from '@memberjunction/core';
+import { BaseSingleton, IShutdownable, ShutdownRegistry } from '@memberjunction/global';
+import { RemoteBrowserEngine } from '@memberjunction/remote-browser-server';
+import type { ConversationBrowserConfig } from '../config.js';
+
+/** How often idle conversation browsers are looked for. */
+const REAP_INTERVAL_MS = 60_000;
+
+/** The `extensions.code` of a {@link RemoteBrowserRefusedError}, which a client reads to stop asking. */
+export const REMOTE_BROWSER_REFUSED = 'REMOTE_BROWSER_REFUSED';
+
+/**
+ * A remote-browser request this server refuses however often it is asked: browsers not enabled, a session
+ * that is not the caller's or does not exist, or a cap reached.
+ */
+export class RemoteBrowserRefusedError extends GraphQLError {
+  constructor(message: string) {
+    super(message, { extensions: { code: REMOTE_BROWSER_REFUSED } });
+    this.name = 'RemoteBrowserRefusedError';
+  }
+}
+
+/** Who a conversation browser counts against: a user, or an anonymous guest's own scope. */
+export interface ConversationBrowserOwner {
+  Key: string;
+  Anonymous: boolean;
+}
+
+interface HeldBrowser {
+  Owner: ConversationBrowserOwner;
+  LastUsedAt: number;
+  IdleMs: number;
+}
+
+export class ConversationBrowserLedger extends BaseSingleton<ConversationBrowserLedger> implements IShutdownable {
+  public readonly ShutdownName = 'ConversationBrowserLedger';
+  private readonly held = new Map<string, HeldBrowser>();
+  private reapTimer: ReturnType<typeof setInterval> | null = null;
+
+  /**
+   * How an idle browser is ended. The resolver points this at its own end path, so a reaped browser
+   * leaves no stream bookkeeping behind; until then the engine ends it directly.
+   */
+  public EndBrowser: (conversationID: string) => Promise<unknown> = (conversationID) =>
+    RemoteBrowserEngine.Instance.EndSessionForAgentSession(conversationID);
+
+  protected constructor() {
+    super();
+  }
+
+  public static get Instance(): ConversationBrowserLedger {
+    return super.getInstance<ConversationBrowserLedger>();
+  }
+
+  /**
+   * Records that a conversation's browser is about to be used. A conversation the ledger does not hold
+   * yet counts against its owner's cap and, for an anonymous guest, against the cap all guests share: a
+   * guest can start a new scope cheaply, so its own cap alone bounds nothing.
+   *
+   * @throws RemoteBrowserRefusedError when the owner already holds `maxPerUser` conversation browsers, or
+   * guests together already hold `maxAnonymousTotal`.
+   */
+  public Claim(conversationID: string, owner: ConversationBrowserOwner, limits: Pick<ConversationBrowserConfig, 'maxPerUser' | 'maxAnonymousTotal' | 'idleMinutes'>): void {
+    const key = conversationID.toLowerCase();
+    if (!this.held.has(key)) {
+      const held = Array.from(this.held.values());
+      const count = held.filter((b) => b.Owner.Key === owner.Key).length;
+      if (count >= limits.maxPerUser) {
+        throw new RemoteBrowserRefusedError(`You already have ${count} conversation browser(s) open, the most this server allows. Close one first.`);
+      }
+      if (owner.Anonymous && held.filter((b) => b.Owner.Anonymous).length >= limits.maxAnonymousTotal) {
+        throw new RemoteBrowserRefusedError('Every conversation browser this server allows for guests is in use. Try again later.');
+      }
+    }
+    this.held.set(key, { Owner: owner, LastUsedAt: Date.now(), IdleMs: limits.idleMinutes * 60_000 });
+    this.startReaper();
+  }
+
+  /** Marks a held browser as used (an action, a snapshot poll, human input), which puts off its idle end. */
+  public Touch(conversationID: string): void {
+    const browser = this.held.get(conversationID.toLowerCase());
+    if (browser) {
+      browser.LastUsedAt = Date.now();
+    }
+  }
+
+  /** Forgets a conversation's browser once it has been ended. */
+  public Release(conversationID: string): void {
+    this.held.delete(conversationID.toLowerCase());
+  }
+
+  /** Ends every held browser unused for longer than its idle limit. Returns how many were ended. */
+  public async ReapIdle(): Promise<number> {
+    const now = Date.now();
+    const idle = Array.from(this.held).filter(([, b]) => now - b.LastUsedAt > b.IdleMs).map(([id]) => id);
+    for (const conversationID of idle) {
+      this.held.delete(conversationID);
+      try {
+        await this.EndBrowser(conversationID);
+      } catch (err) {
+        LogError(`[ConversationBrowsers] Failed to end the idle browser of conversation ${conversationID}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    if (idle.length > 0) {
+      LogStatus(`[ConversationBrowsers] Ended ${idle.length} idle conversation browser(s).`);
+    }
+    return idle.length;
+  }
+
+  /** Ends every held browser on a graceful shutdown, so none outlives the server. Idempotent. */
+  public async Shutdown(): Promise<void> {
+    if (this.reapTimer) {
+      clearInterval(this.reapTimer);
+      this.reapTimer = null;
+    }
+    const held = Array.from(this.held.keys());
+    this.held.clear();
+    await Promise.allSettled(held.map((conversationID) => this.EndBrowser(conversationID)));
+  }
+
+  /**
+   * One unref'd timer per process, started with the first browser, so the reaper costs nothing until then.
+   * The ledger joins the graceful shutdown at the same time.
+   */
+  private startReaper(): void {
+    if (this.reapTimer) {
+      return;
+    }
+    this.reapTimer = setInterval(() => void this.ReapIdle(), REAP_INTERVAL_MS);
+    this.reapTimer.unref?.();
+    ShutdownRegistry.Instance.Register(this);
+  }
+}