@memberjunction/server 5.40.2 → 5.42.0

package/src/__tests__/RemoteBrowserAudioStream.test.ts

@@ -0,0 +1,181 @@
+// type-graphql decorators on the resolver call `Reflect.getMetadata`, which only exists when this
+// polyfill is loaded first. MUST precede any import that pulls in the resolver file.
+import 'reflect-metadata';
+
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { RemoteBrowserCapabilityNotSupportedError } from '@memberjunction/remote-browser-base';
+
+// type-graphql's `@Field()`/`@ObjectType()`/`@Mutation()` decorators need `emitDecoratorMetadata`
+// reflection (a build-time tsc feature) that vitest's esbuild transform does NOT apply, so importing the
+// decorated resolver throws "Unable to infer GraphQL type". This unit test exercises the resolver's plain
+// TS logic (idempotency / capability fallback / publish envelope), not its GraphQL schema — so we replace
+// the decorators with no-ops. (The real schema is validated by the build + integration tests.)
+vi.mock('type-graphql', () => {
+  const noopDecorator = () => () => undefined;
+  return {
+    Resolver: noopDecorator,
+    Mutation: noopDecorator,
+    Query: noopDecorator,
+    Subscription: noopDecorator,
+    ObjectType: noopDecorator,
+    InputType: noopDecorator,
+    Field: noopDecorator,
+    Arg: noopDecorator,
+    Args: noopDecorator,
+    Ctx: noopDecorator,
+    PubSub: noopDecorator,
+    Root: noopDecorator,
+    Float: class {},
+    Int: class {},
+    ID: class {},
+  };
+});
+
+// --- Mock the live-session engine the resolver drives. A single mutable session object lets each
+//     test script what StartAudioStream/StopAudioStream do (succeed / throw a capability error). ---
+interface FakeLiveSession {
+  StartAudioStream: ReturnType<typeof vi.fn>;
+  StopAudioStream: ReturnType<typeof vi.fn>;
+}
+const liveSession: FakeLiveSession = {
+  StartAudioStream: vi.fn(async () => undefined),
+  StopAudioStream: vi.fn(async () => undefined),
+};
+const startSessionMock = vi.fn(async () => liveSession);
+const getSessionMock = vi.fn(() => liveSession as FakeLiveSession | undefined);
+vi.mock('@memberjunction/remote-browser-server', () => ({
+  RemoteBrowserEngine: {
+    Instance: {
+      StartSessionForAgentSession: (...args: unknown[]) => startSessionMock(...(args as [])),
+      GetSessionForAgentSession: (...args: unknown[]) => getSessionMock(...(args as [])),
+    },
+  },
+}));
+
+// Keep the AI imports (visual interpreter) inert — they aren't exercised by the audio path.
+vi.mock('@memberjunction/aiengine', () => ({ AIEngine: { Instance: { Config: vi.fn(), Prompts: [] } } }));
+vi.mock('@memberjunction/ai-prompts', () => ({ AIPromptRunner: class {} }));
+// Spread the real module so transitively-loaded code (e.g. ArtifactToolManager → DataSnapshotToolLibrary,
+// which extends BaseArtifactToolLibrary) still resolves with its REAL base classes; only AIPromptParams is
+// overridden for the test. (Subsumes the narrower stub-two-exports approach — any other transitive export
+// is supplied by the real module rather than coming back undefined.)
+vi.mock('@memberjunction/ai-core-plus', async (importOriginal) => ({
+  ...(await importOriginal<typeof import('@memberjunction/ai-core-plus')>()),
+  AIPromptParams: class {},
+}));
+
+import { RemoteBrowserActionResolver } from '../resolvers/RemoteBrowserActionResolver.js';
+
+/**
+ * A test subclass that bypasses the ownership/provider plumbing (covered elsewhere) so the audio-stream
+ * logic — idempotency, capability fallback, the publish envelope — is exercised in isolation.
+ */
+class TestableResolver extends RemoteBrowserActionResolver {
+  // Stub the user/provider gate to a fixed authenticated user.
+  protected requireUserAndProvider() {
+    return { contextUser: { ID: 'user-1' }, provider: {} } as never;
+  }
+  // Stub session ownership + provider-name resolution.
+  protected async loadOwnedSession() {
+    return { ID: 'sess-1', AgentID: 'agent-1', UserID: 'user-1' } as never;
+  }
+  protected async resolveProviderName() {
+    return 'Self-Hosted Chrome';
+  }
+}
+
+/** A minimal pub/sub spy capturing every published envelope. */
+function makePubSub(): { publish: ReturnType<typeof vi.fn>; published: Array<{ topic: string; payload: unknown }> } {
+  const published: Array<{ topic: string; payload: unknown }> = [];
+  return {
+    publish: vi.fn((topic: string, payload: unknown) => {
+      published.push({ topic, payload });
+      return Promise.resolve();
+    }),
+    published,
+  };
+}
+
+const ctx = { userPayload: { sessionId: 'push-sess-1' }, providers: {} } as never;
+
+describe('RemoteBrowserActionResolver — audio stream', () => {
+  let resolver: TestableResolver;
+
+  beforeEach(() => {
+    resolver = new TestableResolver();
+    liveSession.StartAudioStream.mockReset().mockResolvedValue(undefined);
+    liveSession.StopAudioStream.mockReset().mockResolvedValue(undefined);
+    startSessionMock.mockReset().mockResolvedValue(liveSession);
+    getSessionMock.mockReset().mockReturnValue(liveSession);
+  });
+
+  it('starts the stream and reports Streaming: true', async () => {
+    const pubSub = makePubSub();
+    const result = await resolver.StartRemoteBrowserAudioStream('sess-1', ctx, pubSub as never);
+    expect(result).toEqual({ Streaming: true });
+    expect(liveSession.StartAudioStream).toHaveBeenCalledTimes(1);
+  });
+
+  it('is idempotent — a second start does not re-invoke StartAudioStream', async () => {
+    const pubSub = makePubSub();
+    await resolver.StartRemoteBrowserAudioStream('sess-1', ctx, pubSub as never);
+    const second = await resolver.StartRemoteBrowserAudioStream('sess-1', ctx, pubSub as never);
+    expect(second).toEqual({ Streaming: true });
+    expect(liveSession.StartAudioStream).toHaveBeenCalledTimes(1);
+  });
+
+  it('reports Streaming: false when the backend has no audio capability (graceful fallback)', async () => {
+    liveSession.StartAudioStream.mockRejectedValueOnce(
+      new RemoteBrowserCapabilityNotSupportedError('AudioStreaming', 'Browserless'),
+    );
+    const pubSub = makePubSub();
+    const result = await resolver.StartRemoteBrowserAudioStream('sess-1', ctx, pubSub as never);
+    expect(result).toEqual({ Streaming: false });
+  });
+
+  it('publishes each chunk as a RemoteBrowserAudioChunk envelope scoped to the push session', async () => {
+    const pubSub = makePubSub();
+    // Capture the onChunk callback the resolver hands to StartAudioStream, then drive a chunk through it.
+    let onChunk: ((c: unknown) => void) | null = null;
+    liveSession.StartAudioStream.mockImplementationOnce(async (cb: (c: unknown) => void) => {
+      onChunk = cb;
+    });
+    await resolver.StartRemoteBrowserAudioStream('sess-1', ctx, pubSub as never);
+
+    onChunk?.({ DataBase64: 'QUJD', Codec: 'webm-opus', SampleRate: 48000, Channels: 2, SequenceNumber: 7 });
+
+    expect(pubSub.published).toHaveLength(1);
+    const envelope = pubSub.published[0] as { topic: string; payload: { message: string; sessionId: string } };
+    expect(envelope.topic).toBe('PUSH_STATUS_UPDATES');
+    expect(envelope.payload.sessionId).toBe('push-sess-1');
+    expect(JSON.parse(envelope.payload.message)).toEqual({
+      resolver: 'RemoteBrowserActionResolver',
+      type: 'RemoteBrowserAudioChunk',
+      agentSessionID: 'sess-1',
+      dataBase64: 'QUJD',
+      codec: 'webm-opus',
+      sampleRate: 48000,
+      channels: 2,
+      seq: 7,
+    });
+  });
+
+  it('stop clears the started set (so a later start re-invokes) and best-effort stops the session', async () => {
+    const pubSub = makePubSub();
+    await resolver.StartRemoteBrowserAudioStream('sess-1', ctx, pubSub as never);
+    const stopped = await resolver.StopRemoteBrowserAudioStream('sess-1', ctx);
+    expect(stopped).toBe(true);
+    expect(liveSession.StopAudioStream).toHaveBeenCalledTimes(1);
+
+    // After stop, a new start re-invokes StartAudioStream (idempotency set was cleared).
+    await resolver.StartRemoteBrowserAudioStream('sess-1', ctx, pubSub as never);
+    expect(liveSession.StartAudioStream).toHaveBeenCalledTimes(2);
+  });
+
+  it('stop is best-effort — a StopAudioStream rejection still resolves true', async () => {
+    const pubSub = makePubSub();
+    await resolver.StartRemoteBrowserAudioStream('sess-1', ctx, pubSub as never);
+    liveSession.StopAudioStream.mockRejectedValueOnce(new Error('no audio backend'));
+    await expect(resolver.StopRemoteBrowserAudioStream('sess-1', ctx)).resolves.toBe(true);
+  });
+});

package/src/__tests__/RemoteBrowserGoalEngine.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import type { UserInfo } from '@memberjunction/core';
+import { RunComputerUseParams, type StepRecord } from '@memberjunction/computer-use';
+import { MJComputerUseEngine, MJRunComputerUseParams } from '@memberjunction/computer-use-engine';
+import { CdpRemoteBrowserSession, type ComputerUseGoalRun } from '@memberjunction/remote-browser-cdp';
+import type { MJAIAgentRunStepEntity } from '@memberjunction/core-entities';
+import {
+  buildMJGoalParams,
+  BindRemoteBrowserGoalEngine,
+  MJProgressComputerUseEngine,
+  extractCoAgentRunID,
+  finalizeBrowserGoalStep,
+} from '../agentSessions/remoteBrowserGoalEngine.js';
+
+const USER = { ID: 'u-1', Email: 'amith@bluecypress.io' } as unknown as UserInfo;
+
+/** Builds a base RunComputerUseParams the CDP session would hand to the goal engine. */
+function baseParams(): RunComputerUseParams {
+  return Object.assign(new RunComputerUseParams(), { Goal: 'log in', MaxSteps: 7, StartUrl: 'https://app.test/' });
+}
+
+describe('buildMJGoalParams', () => {
+  it('produces MJ-aware params that carry over the base goal/step/url fields', () => {
+    const mj = buildMJGoalParams(baseParams(), USER);
+    expect(mj).toBeInstanceOf(MJRunComputerUseParams);
+    expect(mj.Goal).toBe('log in');
+    expect(mj.MaxSteps).toBe(7);
+    expect(mj.StartUrl).toBe('https://app.test/');
+  });
+
+  it('injects the acting ContextUser so MJ prompts run as that user', () => {
+    expect(buildMJGoalParams(baseParams(), USER).ContextUser).toBe(USER);
+  });
+
+  it('leaves ContextUser undefined when none is supplied', () => {
+    expect(buildMJGoalParams(baseParams()).ContextUser).toBeUndefined();
+  });
+
+  it('threads the parent run + step ids for observability nesting', () => {
+    const mj = buildMJGoalParams(baseParams(), USER, 'coagent-run-1', 'goal-step-1');
+    expect(mj.AgentRunId).toBe('coagent-run-1');
+    expect(mj.AgentRunStepID).toBe('goal-step-1');
+  });
+
+  it('leaves the run/step ids undefined when not supplied', () => {
+    const mj = buildMJGoalParams(baseParams(), USER);
+    expect(mj.AgentRunId).toBeUndefined();
+    expect(mj.AgentRunStepID).toBeUndefined();
+  });
+});
+
+describe('extractCoAgentRunID', () => {
+  it('pulls coAgentRunID out of a session Config_ blob', () => {
+    expect(extractCoAgentRunID(JSON.stringify({ coAgentRunID: 'run-9', promptRunID: 'p' }))).toBe('run-9');
+  });
+  it('returns undefined for a missing key, null/empty config, or non-string value', () => {
+    expect(extractCoAgentRunID(JSON.stringify({ promptRunID: 'p' }))).toBeUndefined();
+    expect(extractCoAgentRunID(null)).toBeUndefined();
+    expect(extractCoAgentRunID(undefined)).toBeUndefined();
+    expect(extractCoAgentRunID('')).toBeUndefined();
+    expect(extractCoAgentRunID(JSON.stringify({ coAgentRunID: 123 }))).toBeUndefined();
+  });
+  it('returns undefined for malformed JSON (best-effort)', () => {
+    expect(extractCoAgentRunID('{not json')).toBeUndefined();
+  });
+});
+
+describe('finalizeBrowserGoalStep', () => {
+  function fakeStep() {
+    return {
+      StartedAt: new Date(),
+      Save: vi.fn(async () => true),
+      LatestResult: { CompleteMessage: '' },
+    } as unknown as MJAIAgentRunStepEntity & { Save: ReturnType<typeof vi.fn> };
+  }
+
+  it('finalizes the parent step Completed from a successful goal result + saves', async () => {
+    const step = fakeStep();
+    await finalizeBrowserGoalStep(step, { Success: true, Strategy: 'ComputerUse', Status: 'Completed', StepCount: 4, CurrentUrl: 'https://done/' });
+    expect(step.Status).toBe('Completed');
+    expect(step.Success).toBe(true);
+    expect((step as unknown as { Save: ReturnType<typeof vi.fn> }).Save).toHaveBeenCalledOnce();
+    const out = JSON.parse(step.OutputData as string);
+    expect(out.strategy).toBe('ComputerUse');
+    expect(out.stepCount).toBe(4);
+  });
+
+  it('finalizes Failed and carries the detail as the error message', async () => {
+    const step = fakeStep();
+    await finalizeBrowserGoalStep(step, { Success: false, Status: 'Error', Detail: 'login blocked' });
+    expect(step.Status).toBe('Failed');
+    expect(step.ErrorMessage).toBe('login blocked');
+  });
+
+  it('is a no-op when the step is null (no co-agent run to nest under)', async () => {
+    await expect(finalizeBrowserGoalStep(null, { Success: true })).resolves.toBeUndefined();
+  });
+});
+
+describe('MJProgressComputerUseEngine', () => {
+  it('is an MJ computer-use engine that satisfies the goal-run seam', () => {
+    const engine = new MJProgressComputerUseEngine();
+    expect(engine).toBeInstanceOf(MJComputerUseEngine);
+    // Seam surface the CDP session drives:
+    expect(typeof engine.SetBrowserAdapter).toBe('function');
+    expect(typeof engine.Stop).toBe('function');
+    expect(typeof engine.Run).toBe('function');
+  });
+
+  it('forwards a model-safe progress note on each completed step', () => {
+    const engine = new MJProgressComputerUseEngine();
+    const notes: { Step: number; Message: string; Url?: string }[] = [];
+    engine.OnProgress = (p) => notes.push(p);
+
+    // onStepComplete is protected; the base MJ media-persistence path is a no-op here (no prompt-run id /
+    // context user set), so this exercises only the progress forwarding.
+    const step = { StepNumber: 2, ControllerReasoning: 'typing username', Url: 'https://app.test/login', Screenshot: '' } as StepRecord;
+    (engine as unknown as { onStepComplete(s: StepRecord, p: MJRunComputerUseParams): void }).onStepComplete(step, new MJRunComputerUseParams());
+
+    expect(notes).toEqual([{ Step: 2, Message: 'typing username', Url: 'https://app.test/login' }]);
+  });
+});
+
+describe('BindRemoteBrowserGoalEngine', () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it('binds a factory that yields an MJ progress engine', () => {
+    const spy = vi.spyOn(CdpRemoteBrowserSession, 'SetGoalEngineFactory');
+    BindRemoteBrowserGoalEngine();
+
+    expect(spy).toHaveBeenCalledOnce();
+    const factory = spy.mock.calls[0][0] as () => ComputerUseGoalRun;
+    expect(factory()).toBeInstanceOf(MJProgressComputerUseEngine);
+  });
+
+  it('never throws (a binding hiccup must not abort server boot)', () => {
+    vi.spyOn(CdpRemoteBrowserSession, 'SetGoalEngineFactory').mockImplementation(() => {
+      throw new Error('boom');
+    });
+    expect(() => BindRemoteBrowserGoalEngine()).not.toThrow();
+  });
+});

package/src/__tests__/SessionJanitor.test.ts

@@ -0,0 +1,234 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock CanRun (unused by the janitor path, but SessionManager imports it).
+vi.mock('@memberjunction/ai-engine-base', () => ({
+    AIAgentPermissionHelper: { HasPermission: vi.fn(async () => true) },
+}));
+
+// Capture the ExtraFilter passed to each sweep page and return controllable rows.
+const runViewMock = vi.fn();
+vi.mock('@memberjunction/core', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@memberjunction/core')>();
+    return {
+        ...actual,
+        RunView: {
+            ...actual.RunView,
+            FromMetadataProvider: () => ({ RunView: runViewMock }),
+        },
+    };
+});
+
+import { SessionJanitor } from '../agentSessions/SessionJanitor.js';
+import { GetHostInstanceID, GetHostNamePrefix } from '../agentSessions/HostInstance.js';
+import type { UserInfo, IMetadataProvider } from '@memberjunction/core';
+
+interface FakeSession {
+    ID: string;
+    Status: 'Active' | 'Idle' | 'Closed';
+    Load: (id: string) => Promise<boolean>;
+    Save: () => Promise<boolean>;
+    LatestResult?: { CompleteMessage?: string };
+    ClosedAt?: Date | null;
+    CloseReason?: string | null;
+}
+
+function makeUser(): UserInfo {
+    return { ID: 'system-user', Email: 'system@example.com' } as unknown as UserInfo;
+}
+
+/**
+ * Build a provider whose GetEntityObject (used by SessionManager.CloseSession to load a session by
+ * ID) returns a fresh entity backed by `store`, recording which IDs get closed. The channel sweep
+ * inside CloseSession uses runViewMock, which we default to an empty channel list.
+ */
+function makeProvider(store: Map<string, 'Active' | 'Idle' | 'Closed'>): {
+    provider: IMetadataProvider;
+    closedIds: string[];
+    closedReasons: Map<string, string | null>;
+} {
+    const closedIds: string[] = [];
+    const closedReasons = new Map<string, string | null>();
+    const provider = {
+        GetEntityObject: vi.fn(async (entityName: string) => {
+            // Both the session-load and (within close) channel rows come through here in real code,
+            // but channels are returned via runViewMock; this factory only serves session loads.
+            const entity: FakeSession = {
+                ID: '',
+                Status: 'Active',
+                Load: vi.fn(async (id: string) => {
+                    const status = store.get(id);
+                    if (status == null) return false;
+                    entity.ID = id;
+                    entity.Status = status;
+                    return true;
+                }),
+                Save: vi.fn(async () => {
+                    if (entity.Status === 'Closed') {
+                        store.set(entity.ID, 'Closed');
+                        closedIds.push(entity.ID);
+                        closedReasons.set(entity.ID, entity.CloseReason ?? null);
+                    }
+                    return true;
+                }),
+                LatestResult: { CompleteMessage: '' },
+            };
+            return entity as unknown as Awaited<ReturnType<IMetadataProvider['GetEntityObject']>>;
+        }),
+    } as unknown as IMetadataProvider;
+    return { provider, closedIds, closedReasons };
+}
+
+/**
+ * Queue of result-sets for the *session* sweep pages (entity 'MJ: AI Agent Sessions'). Channel
+ * sweeps (entity 'MJ: AI Agent Session Channels', issued by CloseSession) always resolve empty so
+ * they never consume a queued session page. This keeps page assertions deterministic.
+ */
+let sessionPages: Array<{ Success: boolean; Results: unknown[]; ErrorMessage?: string }> = [];
+
+/** Only the RunView calls that paged the session sweep (ignores the channel-sweep calls). */
+function sessionSweepCalls(): Array<[{ EntityName: string; ExtraFilter: string; AfterKey?: unknown }]> {
+    return runViewMock.mock.calls.filter(
+        (c) => (c[0] as { EntityName: string }).EntityName === 'MJ: AI Agent Sessions',
+    ) as Array<[{ EntityName: string; ExtraFilter: string; AfterKey?: unknown }]>;
+}
+
+beforeEach(() => {
+    runViewMock.mockReset();
+    sessionPages = [];
+    runViewMock.mockImplementation(async (params: { EntityName: string }) => {
+        if (params.EntityName === 'MJ: AI Agent Session Channels') {
+            return { Success: true, Results: [] };
+        }
+        return sessionPages.shift() ?? { Success: true, Results: [] };
+    });
+    // Reset the singleton's timers/state between tests.
+    SessionJanitor.Instance.Stop();
+});
+
+describe('SessionJanitor.RunStartupRecovery', () => {
+    it('closes prior-boot orphans of this host but not current-host or other-host sessions', async () => {
+        // The sweep SQL filters by host prefix + "<> current"; here we emulate the DB by having
+        // runViewMock return only the rows that filter WOULD match (prior-boot orphans). We assert
+        // (a) the filter is correct and (b) the returned orphans get closed.
+        const orphan = { ID: 'orphan-1', Status: 'Active' };
+        sessionPages = [{ Success: true, Results: [orphan] }];
+
+        const store = new Map<string, 'Active' | 'Idle' | 'Closed'>([['orphan-1', 'Active']]);
+        const { provider, closedIds, closedReasons } = makeProvider(store);
+
+        const count = await SessionJanitor.Instance.RunStartupRecovery(provider, makeUser());
+
+        expect(count).toBe(1);
+        expect(closedIds).toContain('orphan-1');
+        // Orphan recovery stamps the janitor close cause.
+        expect(closedReasons.get('orphan-1')).toBe('Janitor');
+
+        // Assert the recovery filter targets this host's *other* boots, never the current instance.
+        const filter = sessionSweepCalls()[0][0].ExtraFilter as string;
+        expect(filter).toContain("Status IN ('Active','Idle')");
+        expect(filter).toContain(`HostInstanceID LIKE '${GetHostNamePrefix()}%'`);
+        expect(filter).toContain(`HostInstanceID <> '${GetHostInstanceID()}'`);
+    });
+});
+
+describe('SessionJanitor.RunStalenessSweep', () => {
+    it('closes only past-threshold sessions (filter is staleness-scoped)', async () => {
+        const stale = { ID: 'stale-1', Status: 'Idle' };
+        sessionPages = [{ Success: true, Results: [stale] }];
+
+        const store = new Map<string, 'Active' | 'Idle' | 'Closed'>([['stale-1', 'Idle']]);
+        const { provider, closedIds, closedReasons } = makeProvider(store);
+
+        const count = await SessionJanitor.Instance.RunStalenessSweep(provider, makeUser());
+
+        expect(count).toBe(1);
+        expect(closedIds).toContain('stale-1');
+        // Staleness sweep stamps the janitor close cause.
+        expect(closedReasons.get('stale-1')).toBe('Janitor');
+
+        const filter = sessionSweepCalls()[0][0].ExtraFilter as string;
+        expect(filter).toContain("Status IN ('Active','Idle')");
+        expect(filter).toMatch(/LastActiveAt < '.*'/);
+    });
+
+    it('is idempotent — re-closing already-Closed rows is a harmless no-op', async () => {
+        const alreadyClosed = { ID: 'done-1', Status: 'Closed' };
+        sessionPages = [{ Success: true, Results: [alreadyClosed] }];
+
+        const store = new Map<string, 'Active' | 'Idle' | 'Closed'>([['done-1', 'Closed']]);
+        const { provider, closedIds } = makeProvider(store);
+
+        const count = await SessionJanitor.Instance.RunStalenessSweep(provider, makeUser());
+
+        // CloseSession returns true (idempotent) but no new close-write happens.
+        expect(count).toBe(1);
+        expect(closedIds).not.toContain('done-1');
+    });
+
+    it('uses keyset pagination — advances AfterKey across full pages and stops on a partial page', async () => {
+        // First page is full (200) → expect a second call with AfterKey set; second page partial → stop.
+        const fullPage = Array.from({ length: 200 }, (_, i) => ({ ID: `s-${i}`, Status: 'Active' }));
+        const tailPage = [{ ID: 's-tail', Status: 'Active' }];
+        sessionPages = [
+            { Success: true, Results: fullPage },
+            { Success: true, Results: tailPage },
+        ];
+
+        const store = new Map<string, 'Active' | 'Idle' | 'Closed'>();
+        for (const r of [...fullPage, ...tailPage]) store.set(r.ID, 'Active');
+        const { provider } = makeProvider(store);
+
+        await SessionJanitor.Instance.RunStalenessSweep(provider, makeUser());
+
+        const calls = sessionSweepCalls();
+        expect(calls).toHaveLength(2);
+        expect(calls[0][0].AfterKey).toBeUndefined();
+        expect(calls[1][0].AfterKey).toBeDefined();
+    });
+
+    it('stops cleanly on a load failure without throwing', async () => {
+        sessionPages = [{ Success: false, ErrorMessage: 'boom', Results: [] }];
+        const { provider, closedIds } = makeProvider(new Map());
+
+        const count = await SessionJanitor.Instance.RunStalenessSweep(provider, makeUser());
+        expect(count).toBe(0);
+        expect(closedIds.length).toBe(0);
+    });
+});
+
+describe('SessionJanitor shutdown drain', () => {
+    it('RunShutdownDrain closes only this exact host instance, stamping CloseReason = Shutdown', async () => {
+        const live = { ID: 'mine-1', Status: 'Active' };
+        sessionPages = [{ Success: true, Results: [live] }];
+
+        const store = new Map<string, 'Active' | 'Idle' | 'Closed'>([['mine-1', 'Active']]);
+        const { provider, closedIds, closedReasons } = makeProvider(store);
+
+        const count = await SessionJanitor.Instance.RunShutdownDrain(provider, makeUser());
+
+        expect(count).toBe(1);
+        expect(closedIds).toContain('mine-1');
+        expect(closedReasons.get('mine-1')).toBe('Shutdown');
+
+        // The drain targets the CURRENT boot's exact instance id — not the host-prefix orphan filter.
+        const filter = sessionSweepCalls()[0][0].ExtraFilter as string;
+        expect(filter).toContain("Status IN ('Active','Idle')");
+        expect(filter).toContain(`HostInstanceID = '${GetHostInstanceID()}'`);
+    });
+
+    it('Shutdown() drains this host\'s live sessions with the Shutdown reason after Start()', async () => {
+        // Start consumes one (empty) page for startup recovery; queue the drain page after it.
+        sessionPages = [
+            { Success: true, Results: [] },                                   // startup recovery
+            { Success: true, Results: [{ ID: 'mine-2', Status: 'Idle' }] },   // shutdown drain
+        ];
+        const store = new Map<string, 'Active' | 'Idle' | 'Closed'>([['mine-2', 'Idle']]);
+        const { provider, closedIds, closedReasons } = makeProvider(store);
+
+        await SessionJanitor.Instance.Start(provider, makeUser(), 60_000);
+        await SessionJanitor.Instance.Shutdown();
+
+        expect(closedIds).toContain('mine-2');
+        expect(closedReasons.get('mine-2')).toBe('Shutdown');
+    });
+});