@memberjunction/server 6.2.0-edge.6 → 6.2.0-edge.8

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;
     }
@@ -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,13 +1,15 @@
-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';
@@ -40,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
@@ -191,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.
      */
@@ -215,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;
         }
@@ -228,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.
@@ -236,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.
@@ -584,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);
+  }
+}

package/src/agentSessions/sessionDeadline.ts

@@ -0,0 +1,81 @@
+import type { SessionCloseReason } from './SessionManager.js';
+
+/** The close reasons an expiry check can yield: the two ways a live session runs out of time. */
+export type ExpiryReason = Extract<SessionCloseReason, 'Idle' | 'TimeLimit'>;
+
+/**
+ * Parses the absolute deadline (ms) from a session's `Config_` JSON, or null when absent/malformed.
+ * A malformed deadline counts as absent by design: a sweep must never throw on one bad row, so null
+ * is the documented failure result here, not a swallowed error.
+ */
+export function ParseSessionDeadlineMs(configJson: string | null | undefined): number | null {
+    if (!configJson) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(configJson) as { maxSessionDeadlineIso?: unknown };
+        if (typeof parsed.maxSessionDeadlineIso !== 'string') {
+            return null;
+        }
+        const ms = Date.parse(parsed.maxSessionDeadlineIso);
+        return Number.isNaN(ms) ? null : ms;
+    } catch {
+        // Malformed JSON: treated as "no deadline" (see doc comment).
+        return null;
+    }
+}
+
+/**
+ * Decides why a session has expired, or null when it has not.
+ *
+ * Two moments can expire a session: its idle moment (`LastActiveAt + closeThresholdMs`) and its authored
+ * hard deadline (`Config_.maxSessionDeadlineIso`). Only a moment that has already passed (`<= nowMs`)
+ * counts, and the EARLIER of the passed moments wins. A tie at the same instant yields `TimeLimit`:
+ * the authored rule beats the safety net. A row without a usable `LastActiveAt` (null, or a value that
+ * does not parse to a date) is never `Idle`, and neither is any row when `closeThresholdMs` is non-finite.
+ * `LastActiveAt` is typed `Date` but may arrive as an ISO string from a provider, so both are accepted.
+ */
+export function ExpiryCloseReason(
+    session: { LastActiveAt: Date | string | null | undefined; Config_: string | null | undefined },
+    nowMs: number,
+    closeThresholdMs: number,
+): ExpiryReason | null {
+    const lastActiveMs = session.LastActiveAt ? new Date(session.LastActiveAt).getTime() : Number.NaN;
+    const idleMs = lastActiveMs + closeThresholdMs;
+    const idleAt = Number.isFinite(idleMs) ? idleMs : null;
+    const deadlineAt = ParseSessionDeadlineMs(session.Config_);
+    const idlePassed = idleAt !== null && idleAt <= nowMs;
+    const deadlinePassed = deadlineAt !== null && deadlineAt <= nowMs;
+    if (deadlinePassed && idlePassed) {
+        return deadlineAt <= idleAt ? 'TimeLimit' : 'Idle';
+    }
+    if (deadlinePassed) {
+        return 'TimeLimit';
+    }
+    return idlePassed ? 'Idle' : null;
+}
+
+/**
+ * How far ahead of a stored deadline a browser's `TimeLimit` claim is still believed. The browser's
+ * alarm runs on its own clock: when it extends to a server ISO deadline it anchors that time against its
+ * own `Date.now()`, so a client clock running ahead of the server fires early by the difference (a throttled
+ * tab only fires late). A minute absorbs that skew without letting a client end a session meant to run for
+ * minutes more.
+ */
+export const DEADLINE_CLAIM_SKEW_MS = 60_000;
+
+/**
+ * Verifies a `TimeLimit` close claim against the session's stored deadline. The browser claims, the server
+ * verifies: the claim holds when the stored deadline has passed or falls within {@link DEADLINE_CLAIM_SKEW_MS},
+ * otherwise (no deadline, or one far in the future) the close is recorded as `Explicit`. The janitor's own
+ * `TimeLimit` trivially passes, so every caller shares one path, and this module remains the single place that
+ * answers "did the deadline pass?" for both the sweep and the client claim. Idleness never counts here.
+ */
+export function VerifyTimeLimitClaim(
+    session: { LastActiveAt: Date | string | null | undefined; Config_: string | null | undefined },
+    nowMs: number,
+): 'TimeLimit' | 'Explicit' {
+    return ExpiryCloseReason(session, nowMs + DEADLINE_CLAIM_SKEW_MS, Number.POSITIVE_INFINITY) === 'TimeLimit'
+        ? 'TimeLimit'
+        : 'Explicit';
+}

package/src/auth/APIKeyScopeAuth.ts

@@ -7,6 +7,7 @@
 import { AuthorizationError } from 'type-graphql';
 import { GetAPIKeyEngine, AuthorizationResult, AuthorizationRequest } from '@memberjunction/api-keys';
 import { UserInfo, RunView } from '@memberjunction/core';
+import { EscapeSQLString } from '@memberjunction/global';
 import { MJAPIKeyEntity, MJAPIApplicationEntity } from '@memberjunction/core-entities';
 
 /**
@@ -96,7 +97,7 @@ export async function CheckAPIKeyScope(
     const rv = new RunView();
     const keyResult = await rv.RunView<MJAPIKeyEntity>({
         EntityName: 'MJ: API Keys',
-        ExtraFilter: `ID='${apiKeyId}'`,
+        ExtraFilter: `ID='${EscapeSQLString(apiKeyId)}'`,
         ResultType: 'entity_object'
     }, contextUser);
 
@@ -117,7 +118,7 @@ export async function CheckAPIKeyScope(
     // Get the application by name
     const appResult = await rv.RunView<MJAPIApplicationEntity>({
         EntityName: 'MJ: API Applications',
-        ExtraFilter: `Name='${applicationName}'`,
+        ExtraFilter: `Name='${EscapeSQLString(applicationName)}'`,
         ResultType: 'entity_object'
     }, contextUser);
 
@@ -224,7 +225,7 @@ export async function CheckAPIKeyScopeAndLog(
     // Get the API key
     const keyResult = await rv.RunView<MJAPIKeyEntity>({
         EntityName: 'MJ: API Keys',
-        ExtraFilter: `ID='${apiKeyId}'`,
+        ExtraFilter: `ID='${EscapeSQLString(apiKeyId)}'`,
         ResultType: 'entity_object'
     }, contextUser);
 
@@ -245,7 +246,7 @@ export async function CheckAPIKeyScopeAndLog(
     // Get the application
     const appResult = await rv.RunView<MJAPIApplicationEntity>({
         EntityName: 'MJ: API Applications',
-        ExtraFilter: `Name='${applicationName}'`,
+        ExtraFilter: `Name='${EscapeSQLString(applicationName)}'`,
         ResultType: 'entity_object'
     }, contextUser);