codehere 0.5.0-alpha.6 → 0.6.0

package/dist/infrastructure/orchestration/session-manager.js

@@ -25,6 +25,15 @@ import { AUDIT_FILE } from '../hooks/claude-sdk-hook.js';
 import { appendSpawned, appendCompleted, appendFinalReport, loadRecent } from './session-persistence.js';
 import { generateFinalReport, printFinalReportToTerminal } from '../../application/use-cases/generate-final-report.js';
 import { mirrorSpawnedToThread, mirrorCompletedToThread } from '../storage/project-thread-mirror.js';
+import { scanPromptBeforeSpawn } from '../hooks/pre-prompt-scan.js';
+import { generateNarration } from '../../application/use-cases/generate-narration.js';
+import { randomUUID } from 'crypto';
+import { classifyFailoverEligibility } from './failover-classifier.js';
+import { resolveFailoverTarget, toAvailability, } from './failover-policy.js';
+import { loadFailoverConfig, resolveChain } from './failover-config.js';
+import { enrichPromptWithPackSync, compileSessionPackSync, persistContextPack } from './graphify-context.js';
+import { buildFailoverHandoff, enrichPromptWithHandoff } from './context-handoff.js';
+import { mirrorFailoverToThread } from '../storage/project-thread-mirror.js';
 // ── Agent registry ─────────────────────────────────────────────────────────────
 // All backends codehere can spawn. Order here drives the default UI dropdown
 // order. Built-in adapters first; user-config-driven ones appended from
@@ -47,19 +56,25 @@ const REGISTRY = [
 // Conductor is appended to the same array so UIs that iterate REGISTRY see it.
 REGISTRY.push(buildConductorAdapter(() => REGISTRY));
 export function availableAgents() {
-    return REGISTRY.map((a) => ({ id: a.id, label: a.label, installed: a.isInstalled() }));
+    return REGISTRY.map((a) => ({
+        id: a.id,
+        label: a.label,
+        installed: a.isInstalled(),
+        ...(a.description ? { description: a.description } : {}),
+    }));
 }
 /** Per-agent readiness across the full registry. Powers the setup-aware UI. */
 export function readinessForAllAgents() {
     return REGISTRY.map((a) => {
-        if (a.checkReadiness)
-            return a.checkReadiness();
-        // Fallback for adapters that haven't implemented checkReadiness yet: treat
-        // "installed" as "ready", "not installed" as "needs_install without hint".
-        const installed = a.isInstalled();
-        return installed
-            ? { id: a.id, label: a.label, state: 'ready', installed: true }
-            : { id: a.id, label: a.label, state: 'needs_install', installed: false };
+        const base = a.checkReadiness
+            ? a.checkReadiness()
+            : a.isInstalled()
+                ? { id: a.id, label: a.label, state: 'ready', installed: true }
+                : { id: a.id, label: a.label, state: 'needs_install', installed: false };
+        // v0.6 S5 — mirror the adapter's "when to use me" description into the
+        // readiness payload so the dashboard dropdown can surface it as a
+        // plain-English hover tooltip without a separate API call.
+        return a.description ? { ...base, description: a.description } : base;
     });
 }
 export function getAdapter(id) {
@@ -115,6 +130,29 @@ export class SessionManager {
      *  reads via getFinalReport() through the /api/tasks serializer so non-technical
      *  users see the prose summary without opening a terminal. */
     finalReportBySession = new Map();
+    /** v0.6 M3 · PM Narrator. Mid-task plain-English summaries cached per
+     *  session so the API can serve the latest narration without re-running
+     *  the LLM call on every frontend poll. Latest-only — older narrations
+     *  are overwritten when a new one fires. Per claim_user_persona HIGH:
+     *  non-technical users read narration, not tool calls. */
+    narrationBySession = new Map();
+    narrationTimers = new Map();
+    narrationStepsAtLastFire = new Map();
+    /** Stores active failover offers keyed by sessionId+target. API layer
+     *  reads these via getFailoverOffers() for the /api/failover-offers endpoint. */
+    failoverOffers;
+    /** Tracks the failover error code per session so acceptFailover can emit
+      *  the correct reason in the thread event. Populated by handleFailover. */
+    failoverReasonBySession = new Map();
+    /** Session threading — tracks which session continued as which after failover.
+      *  continuedAsBySession: original → new session ID
+      *  continuedFromBySession: new → original session ID */
+    continuedAsBySession = new Map();
+    continuedFromBySession = new Map();
+    /** Final Report failure tracking — when generateFinalReport rejects, we
+      *  record it so the API can return a definitive "failed" state instead
+      *  of leaving the UI showing "Generating report…" forever. */
+    failedReportBySession = new Set();
     spawn(prompt, agentId = 'claude-code', options) {
         const adapter = getAdapter(agentId);
         if (!adapter) {
@@ -123,12 +161,35 @@ export class SessionManager {
         if (!adapter.isInstalled()) {
             throw new Error(`Agent ${adapter.label} (${adapter.id}) is not installed on this machine`);
         }
-        const session = adapter.spawn(prompt, options);
+        // Cross-vendor pre-prompt scan (task #110, slice 1). Closes the gap
+        // the FAQ now claims as "v0.5.x → v0.6 track": every adapter — not
+        // just claude-code — gets a safety scan on the user's prompt before
+        // spawn. Catches API-key paste, prompt-injection patterns, etc.
+        // Always writes one audit entry (synthetic toolName 'pre_prompt');
+        // refuses spawn ONLY when getHookMode() === 'block' AND the prompt
+        // has critical/high findings. Other modes (advisory/log-only/off)
+        // log + proceed.
+        const preScanSessionId = randomUUID();
+        const scan = scanPromptBeforeSpawn({
+            sessionId: preScanSessionId,
+            agent: agentId,
+            prompt,
+            cwd: options?.cwd,
+        });
+        if (!scan.allowed) {
+            throw new Error(scan.blockReason || 'pre-prompt scan blocked the spawn');
+        }
+        // P1 — graphify-ts structural memory: enrich prompt with compact context
+        // pack so the agent starts with a verified knowledge graph of the workspace.
+        // Respects CODEHERE_GRAPHIFY env var (auto|force|off, default=auto).
+        // Synchronous call — degrades to original prompt if graphify fails.
+        const cwd = options?.cwd ?? process.cwd();
+        const enrichedPrompt = enrichPromptWithPackSync(prompt, cwd);
+        const session = adapter.spawn(enrichedPrompt, options);
         this.sessions.set(session.sessionId, session);
         // Persistence: write the spawned record immediately so a daemon crash still
         // leaves an audit trail of what was attempted. Subscribe to exit so we can
         // capture the final status + steps + artifacts when the session settles.
-        const cwd = options?.cwd ?? process.cwd();
         this.cwdBySession.set(session.sessionId, cwd);
         appendSpawned({
             id: session.sessionId,
@@ -147,6 +208,20 @@ export class SessionManager {
             startedAt: session.startedAt,
         });
         const unsubscribe = session.subscribe((event) => {
+            // ── Failover check — intercept rate-limit / quota errors before exit ──
+            // Adapters emit 'codehere:error' (structured: { code, message, recovery })
+            // or 'error' (spawn-level: { message }). Both need classification.
+            if (event.type === 'error' || event.type === 'codehere:error') {
+                const err = event.data;
+                if (err?.code && err?.message) {
+                    const signal = classifyFailoverEligibility(session.agent, err.code, err.message);
+                    if (signal) {
+                        const newSession = this.handleFailover(session, signal);
+                        if (newSession)
+                            return; // auto-spawned — keep listening on new session
+                    }
+                }
+            }
             if (event.type !== 'exit')
                 return;
             const data = event.data;
@@ -213,12 +288,424 @@ export class SessionManager {
                 }
             })
                 .catch(() => {
-                // generateFinalReport never throws by contract; defensive only.
+                // generateFinalReport rejected — record it so the UI can show
+                // "Report unavailable" instead of "Generating report…" forever.
+                this.failedReportBySession.add(session.sessionId);
+            });
+            // P1 — persist context pack at session exit for cross-session handoff (P2).
+            // Fire-and-forget: graphify-ts may not be installed, graph may be empty,
+            // or pack compilation may fail. All degrade silently.
+            void Promise.resolve().then(() => {
+                try {
+                    const stepsStr = session.steps?.map((s) => `${s.label}: ${s.output || s.state}`).filter(Boolean).join('\n') ?? '';
+                    const pack = compileSessionPackSync(cwd, {
+                        prompt: session.prompt,
+                        artifacts: JSON.stringify(session.artifacts, null, 2),
+                        steps: stepsStr,
+                        agent: session.agent,
+                    });
+                    if (pack)
+                        persistContextPack(pack, cwd);
+                }
+                catch {
+                    // Silent degradation — context pack is enrichment, not the primary path.
+                }
             });
+            // v0.6 M3 — clean up the narration timer for this session.
+            const t = this.narrationTimers.get(session.sessionId);
+            if (t) {
+                clearInterval(t);
+                this.narrationTimers.delete(session.sessionId);
+            }
             unsubscribe();
         });
+        // v0.6 M3 — PM Narrator. Mid-task plain-English summaries fired
+        // every 30s while the session is running. Heuristic: only fire if
+        // the step count grew by ≥3 since the last narration (otherwise
+        // we'd narrate the same state with new words). Fire-and-forget;
+        // failures (no claude binary, timeout, malformed output) silently
+        // skip — narration is enrichment, not the primary surface.
+        this.startNarrationTimer(session);
         return session;
     }
+    /** Tracks which agents have already been tried for a given prompt during
+     *  a failover chain. Maps sessionId → set of agent ids already attempted. */
+    failoverTriedBySession = new Map();
+    /** v0.6.x failover — emit a failover offer when an adapter hits a
+     *  rate-limit / quota error. The offer is surfaced via the API layer
+     *  (Slice E) and optionally auto-spawned (Slice D). Returns the new
+     *  session if auto-spawn was triggered, undefined otherwise. */
+    handleFailover(session, signal) {
+        const config = loadFailoverConfig();
+        const chain = resolveChain(config?.chain);
+        const tried = this.failoverTriedBySession.get(session.sessionId) ?? new Set();
+        tried.add(signal.fromAgent);
+        this.failoverTriedBySession.set(session.sessionId, tried);
+        const adapters = allAdapters();
+        const available = toAvailability(adapters, (a) => {
+            return a.id !== signal.fromAgent && a.isInstalled();
+        });
+        const target = resolveFailoverTarget({
+            failedAgent: signal.fromAgent,
+            alreadyTried: Array.from(tried),
+            available,
+            preferredChain: config?.chain,
+        });
+        if (!target)
+            return undefined;
+        const targetAdapter = getAdapter(target);
+        if (!targetAdapter || !targetAdapter.isInstalled())
+            return undefined;
+        // Auto-failover: spawn on the next agent in the chain
+        const autoFailover = config?.autoFailover ?? true;
+        if (autoFailover) {
+            // Spawn replacement session on the next agent, preserving prompt + cwd
+            const cwd = this.cwdBySession.get(session.sessionId) ?? process.cwd();
+            // P2 — build handoff context for continuity across agent swap
+            const handoff = buildFailoverHandoff(cwd, {
+                failedAgent: session.agent,
+                failedPrompt: session.prompt,
+            });
+            // Enrich prompt with handoff if available (P2)
+            const promptWithHandoff = handoff
+                ? enrichPromptWithHandoff(session.prompt, {
+                    packId: handoff.packId,
+                    agent: session.agent,
+                    prompt: session.prompt,
+                    status: 'failed',
+                    timestamp: handoff.timestamp,
+                    nodeCount: handoff.nodeCount,
+                    edgeCount: handoff.edgeCount,
+                    task: handoff.task,
+                    payloadPreview: handoff.payloadPreview,
+                })
+                : session.prompt;
+            try {
+                const newSession = targetAdapter.spawn(promptWithHandoff, {
+                    cwd,
+                    env: process.env,
+                    preferSubscription: true,
+                });
+                // Track this new session in the same way
+                this.sessions.set(newSession.sessionId, newSession);
+                this.cwdBySession.set(newSession.sessionId, cwd);
+                appendSpawned({
+                    id: newSession.sessionId,
+                    agent: newSession.agent,
+                    prompt: promptWithHandoff,
+                    cwd,
+                    startedAt: newSession.startedAt,
+                });
+                mirrorSpawnedToThread({
+                    sessionId: newSession.sessionId,
+                    agent: newSession.agent,
+                    prompt: promptWithHandoff,
+                    cwd,
+                    startedAt: newSession.startedAt,
+                });
+                mirrorFailoverToThread({
+                    sessionId: newSession.sessionId,
+                    fromAgent: signal.fromAgent,
+                    toAgent: target,
+                    reason: signal.errorCode,
+                    cwd,
+                });
+                // Subscribe to the new session with the same failover logic
+                const unsubscribe = newSession.subscribe((event) => {
+                    if (event.type !== 'exit')
+                        return;
+                    const data = event.data;
+                    const completedAt = Date.now();
+                    this.completedAtBySession.set(newSession.sessionId, completedAt);
+                    appendCompleted({
+                        id: newSession.sessionId,
+                        status: newSession.status,
+                        durationMs: Number(data?.durationMs ?? completedAt - newSession.startedAt),
+                        completedAt,
+                        steps: newSession.steps ? [...newSession.steps] : undefined,
+                        artifacts: newSession.artifacts,
+                    });
+                    mirrorCompletedToThread({
+                        sessionId: newSession.sessionId,
+                        cwd,
+                        status: newSession.status,
+                        durationMs: Number(data?.durationMs ?? completedAt - newSession.startedAt),
+                        completedAt,
+                        steps: newSession.steps ? [...newSession.steps] : undefined,
+                        artifacts: newSession.artifacts,
+                    });
+                    const reportInput = {
+                        sessionId: newSession.sessionId,
+                        prompt: newSession.prompt,
+                        agent: newSession.agent,
+                        status: newSession.status,
+                        durationMs: completedAt - newSession.startedAt,
+                        steps: newSession.steps ? [...newSession.steps] : [],
+                        artifacts: newSession.artifacts,
+                    };
+                    generateFinalReport(reportInput)
+                        .then((report) => {
+                        if (report) {
+                            this.finalReportBySession.set(newSession.sessionId, report);
+                            appendFinalReport({
+                                id: newSession.sessionId,
+                                summary: report.summary,
+                                generatedAt: report.generatedAt,
+                                durationMs: report.durationMs,
+                            });
+                            try {
+                                printFinalReportToTerminal(reportInput, report);
+                            }
+                            catch { /* defensive */ }
+                        }
+                    })
+                        .catch(() => { });
+                    // P1 — persist context pack at failover-replacement session exit.
+                    void Promise.resolve().then(() => {
+                        try {
+                            const stepsStr = newSession.steps?.map((s) => `${s.label}: ${s.output || s.state}`).filter(Boolean).join('\n') ?? '';
+                            const pack = compileSessionPackSync(cwd, {
+                                prompt: newSession.prompt,
+                                artifacts: JSON.stringify(newSession.artifacts, null, 2),
+                                steps: stepsStr,
+                                agent: newSession.agent,
+                            });
+                            if (pack)
+                                persistContextPack(pack, cwd);
+                        }
+                        catch {
+                            // Silent degradation — context pack is enrichment, not primary path.
+                        }
+                    });
+                    const t = this.narrationTimers.get(newSession.sessionId);
+                    if (t) {
+                        clearInterval(t);
+                        this.narrationTimers.delete(newSession.sessionId);
+                    }
+                    unsubscribe();
+                });
+                this.startNarrationTimer(newSession);
+                return newSession;
+            }
+            catch {
+                // Spawn failed — fall through to offer-only mode
+                return undefined;
+            }
+        }
+        // Offer-only mode: signal the API layer to present a failover banner
+        // (Slice E handles the actual UI surfacing)
+        this.emitFailoverOffer({ session, signal, target });
+        this.failoverReasonBySession.set(session.sessionId, signal.errorCode);
+        return undefined;
+    }
+    /** Emitted when a failover offer is generated. The API layer listens
+     *  to this to surface the banner in the web UI. */
+    emitFailoverOffer(offer) {
+        // Store in a map that the API layer can poll — Slice E wires the
+        // /api/failover-offers endpoint to read from here.
+        if (!this.failoverOffers) {
+            this.failoverOffers = new Map();
+        }
+        const key = `${offer.session.sessionId}-${offer.target}`;
+        this.failoverOffers.set(key, offer);
+        // Auto-expire offers after 60 seconds to keep the map bounded
+        setTimeout(() => {
+            this.failoverOffers?.delete(key);
+        }, 60_000);
+    }
+    /** Get all active failover offers for the API layer. */
+    getFailoverOffers() {
+        if (!this.failoverOffers)
+            return [];
+        const offers = [];
+        for (const [key, offer] of this.failoverOffers) {
+            offers.push({
+                sessionId: offer.session.sessionId,
+                signal: offer.signal,
+                target: offer.target,
+                expiresAt: Date.now() + 60_000,
+            });
+        }
+        return offers;
+    }
+    /** v0.6.x P0 — user-initiated failover accept. Spawns a replacement
+       *  session on the target agent, preserving the original prompt + cwd.
+       *  P2 — injects handoff context for cross-agent continuity.
+       *  Returns the new session or undefined if the target is unavailable. */
+    acceptFailover(sessionId, targetAgent) {
+        const session = this.sessions.get(sessionId);
+        if (!session)
+            return undefined;
+        const targetAdapter = getAdapter(targetAgent);
+        if (!targetAdapter || !targetAdapter.isInstalled())
+            return undefined;
+        const cwd = this.cwdBySession.get(sessionId) ?? process.cwd();
+        // P2 — build handoff context for continuity across agent swap
+        const handoff = buildFailoverHandoff(cwd, {
+            failedAgent: session.agent,
+            failedPrompt: session.prompt,
+        });
+        const promptWithHandoff = handoff
+            ? enrichPromptWithHandoff(session.prompt, {
+                packId: handoff.packId,
+                agent: session.agent,
+                prompt: session.prompt,
+                status: 'failed',
+                timestamp: handoff.timestamp,
+                nodeCount: handoff.nodeCount,
+                edgeCount: handoff.edgeCount,
+                task: handoff.task,
+                payloadPreview: handoff.payloadPreview,
+            })
+            : session.prompt;
+        const newSession = targetAdapter.spawn(promptWithHandoff, {
+            cwd,
+            env: process.env,
+            preferSubscription: true,
+        });
+        // Track the new session
+        this.sessions.set(newSession.sessionId, newSession);
+        this.cwdBySession.set(newSession.sessionId, cwd);
+        // Session threading: record the parent-child relationship
+        this.continuedAsBySession.set(sessionId, newSession.sessionId);
+        this.continuedFromBySession.set(newSession.sessionId, sessionId);
+        appendSpawned({
+            id: newSession.sessionId,
+            agent: newSession.agent,
+            prompt: promptWithHandoff,
+            cwd,
+            startedAt: newSession.startedAt,
+        });
+        mirrorSpawnedToThread({
+            sessionId: newSession.sessionId,
+            agent: newSession.agent,
+            prompt: promptWithHandoff,
+            cwd,
+            startedAt: newSession.startedAt,
+        });
+        mirrorFailoverToThread({
+            sessionId: newSession.sessionId,
+            fromAgent: session.agent,
+            toAgent: targetAgent,
+            reason: this.failoverReasonBySession.get(session.sessionId) ?? 'error',
+            cwd,
+        });
+        // Subscribe to the new session with the same failover logic
+        const unsubscribe = newSession.subscribe((event) => {
+            if (event.type !== 'exit')
+                return;
+            const data = event.data;
+            const completedAt = Date.now();
+            this.completedAtBySession.set(newSession.sessionId, completedAt);
+            appendCompleted({
+                id: newSession.sessionId,
+                status: newSession.status,
+                durationMs: Number(data?.durationMs ?? completedAt - newSession.startedAt),
+                completedAt,
+                steps: newSession.steps ? [...newSession.steps] : undefined,
+                artifacts: newSession.artifacts,
+            });
+            mirrorCompletedToThread({
+                sessionId: newSession.sessionId,
+                cwd,
+                status: newSession.status,
+                durationMs: Number(data?.durationMs ?? completedAt - newSession.startedAt),
+                completedAt,
+                steps: newSession.steps ? [...newSession.steps] : undefined,
+                artifacts: newSession.artifacts,
+            });
+            const reportInput = {
+                sessionId: newSession.sessionId,
+                prompt: newSession.prompt,
+                agent: newSession.agent,
+                status: newSession.status,
+                durationMs: completedAt - newSession.startedAt,
+                steps: newSession.steps ? [...newSession.steps] : [],
+                artifacts: newSession.artifacts,
+            };
+            generateFinalReport(reportInput)
+                .then((report) => {
+                if (report) {
+                    this.finalReportBySession.set(newSession.sessionId, report);
+                    appendFinalReport({
+                        id: newSession.sessionId,
+                        summary: report.summary,
+                        generatedAt: report.generatedAt,
+                        durationMs: report.durationMs,
+                    });
+                    try {
+                        printFinalReportToTerminal(reportInput, report);
+                    }
+                    catch { /* defensive */ }
+                }
+            })
+                .catch(() => { });
+            // P1 — persist context pack at accept-failover replacement session exit.
+            void Promise.resolve().then(() => {
+                try {
+                    const stepsStr = newSession.steps?.map((s) => `${s.label}: ${s.output || s.state}`).filter(Boolean).join('\n') ?? '';
+                    const pack = compileSessionPackSync(cwd, {
+                        prompt: newSession.prompt,
+                        artifacts: JSON.stringify(newSession.artifacts, null, 2),
+                        steps: stepsStr,
+                        agent: newSession.agent,
+                    });
+                    if (pack)
+                        persistContextPack(pack, cwd);
+                }
+                catch {
+                    // Silent degradation — context pack is enrichment, not primary path.
+                }
+            });
+            const t = this.narrationTimers.get(newSession.sessionId);
+            if (t) {
+                clearInterval(t);
+                this.narrationTimers.delete(newSession.sessionId);
+            }
+            this.startNarrationTimer(newSession);
+            unsubscribe();
+        });
+        this.startNarrationTimer(newSession);
+        return newSession;
+    }
+    /** v0.6 M3 — periodic narration loop per session. */
+    startNarrationTimer(session) {
+        if (process.env.CODEHERE_DISABLE_NARRATOR === '1')
+            return;
+        this.narrationStepsAtLastFire.set(session.sessionId, 0);
+        const intervalMs = Number(process.env.CODEHERE_NARRATOR_INTERVAL_MS ?? 30_000);
+        const minStepDelta = Number(process.env.CODEHERE_NARRATOR_MIN_STEPS ?? 3);
+        const timer = setInterval(() => {
+            // Skip if session has settled.
+            if (session.status !== 'running')
+                return;
+            const steps = session.steps ?? [];
+            const lastFireSteps = this.narrationStepsAtLastFire.get(session.sessionId) ?? 0;
+            if (steps.length - lastFireSteps < minStepDelta)
+                return;
+            // Mark BEFORE the async call to prevent double-firing if the LLM
+            // is slow.
+            this.narrationStepsAtLastFire.set(session.sessionId, steps.length);
+            const elapsedMs = Date.now() - session.startedAt;
+            void generateNarration({
+                sessionId: session.sessionId,
+                prompt: session.prompt,
+                agent: session.agent,
+                elapsedMs,
+                steps: [...steps],
+            })
+                .then((out) => {
+                if (out)
+                    this.narrationBySession.set(session.sessionId, out);
+            })
+                .catch(() => { });
+        }, intervalMs);
+        this.narrationTimers.set(session.sessionId, timer);
+    }
+    /** v0.6 M3 — latest narration for a session, or undefined. */
+    getNarration(sessionId) {
+        return this.narrationBySession.get(sessionId);
+    }
     /** Persisted (read-only) sessions from prior daemon runs. Cached at boot. */
     listPersisted() {
         return this.persistedCache;
@@ -234,13 +721,26 @@ export class SessionManager {
     getCwd(sessionId) {
         return this.cwdBySession.get(sessionId);
     }
+    /** Session threading — which session did this one continue from (after failover)? */
+    getContinuedFrom(sessionId) {
+        return this.continuedFromBySession.get(sessionId);
+    }
+    /** Session threading — which session did this one continue as (after failover)? */
+    getContinuedAs(sessionId) {
+        return this.continuedAsBySession.get(sessionId);
+    }
     /** PM-UX Layer 3 · prose Final Report for an in-memory exited session.
-     *  Returns undefined while generation is in flight OR if the provider chain
-     *  failed (no claude-free, no claude, no credit, etc). The web UI reads this
-     *  through the /api/tasks serializer to render the prose summary inline. */
+      *  Returns undefined while generation is in flight OR if the provider chain
+      *  failed (no claude-free, no claude, no credit, etc). The web UI reads this
+      *  through the /api/tasks serializer to render the prose summary inline. */
     getFinalReport(sessionId) {
         return this.finalReportBySession.get(sessionId);
     }
+    /** Returns true if Final Report generation explicitly failed for this session.
+      *  Lets the API distinguish "not yet" from "never coming". */
+    hasFailedReport(sessionId) {
+        return this.failedReportBySession.has(sessionId);
+    }
     get(sessionId) {
         return this.sessions.get(sessionId);
     }