fraim 2.0.339 → 2.0.341

package/dist/src/local-mcp-server/stdio-server.js

@@ -66,8 +66,10 @@ const redact_secrets_1 = require("../core/utils/redact-secrets");
 const pack_home_1 = require("../cli/utils/pack-home");
 const local_registry_resolver_1 = require("../core/utils/local-registry-resolver");
 const ai_mentor_1 = require("../core/ai-mentor");
+const run_recovery_state_1 = require("../core/run-recovery-state");
 const quality_evidence_1 = require("../core/quality-evidence");
 const handoff_contracts_1 = require("../core/handoff-contracts");
+const proposal_set_contract_1 = require("../core/proposal-set-contract");
 const test_evidence_contract_1 = require("../core/test-evidence-contract");
 const project_fraim_paths_1 = require("../core/utils/project-fraim-paths");
 const usage_collector_js_1 = require("./usage-collector.js");
@@ -530,6 +532,8 @@ class FraimLocalMCPServer {
         this.machineInfo = null;
         this.repoInfo = null;
         this.engine = null;
+        this.usageUploadInFlight = null;
+        this.usageUploadRequested = false;
         this.otlpServer = null;
         this.isShutdown = false;
         this.mentoringResponseCache = null;
@@ -567,6 +571,8 @@ class FraimLocalMCPServer {
         if (this.isShutdown)
             return;
         this.isShutdown = true;
+        this.usageUploadRequested = false;
+        // Telemetry is best effort: process exit does not wait for or replay uploads.
         this.usageCollector.shutdown();
         if (this.otlpServer?.server) {
             (0, otlp_metrics_receiver_js_1.stopOtlpReceiver)(this.otlpServer.server);
@@ -1195,58 +1201,179 @@ class FraimLocalMCPServer {
             return null;
         return (0, path_1.join)(homeDir, '.fraim', 'cache', 'registry', 'providers', filename);
     }
-    /**
-     * Issue #1590, Gate 4 — path to the per-run phase-start marker.
-     * ~/.fraim/run-state/{jobId}.json, keyed by the jobId seekMentoring already
-     * carries on every call, so no new identifier or collision risk across the
-     * user's concurrent multi-issue fleet.
-     */
-    getRunStateMarkerPath(jobId) {
-        const homeDir = this.getHomeDir();
-        if (!homeDir)
-            return null;
-        return (0, path_1.join)(homeDir, '.fraim', 'run-state', `${jobId}.json`);
+    /** Session/job-name key also admits starts that do not yet carry a jobId. */
+    getRunStateDir() {
+        return (0, path_1.join)((0, project_fraim_paths_1.getUserFraimDirPath)(), 'run-state');
+    }
+    getRunStateMarkerPath(sessionId, jobName) {
+        const key = (0, crypto_1.createHash)('sha256').update(JSON.stringify([sessionId, jobName])).digest('hex');
+        return (0, path_1.join)(this.getRunStateDir(), `phase-${key}.json`);
     }
-    /** Reads and parses the run-state marker, tolerating a missing/corrupt file (warn-only signal, never throws). */
-    readRunStateMarker(jobId) {
+    readRunStateMarker(sessionId, jobName) {
         try {
-            const markerPath = this.getRunStateMarkerPath(jobId);
+            const markerPath = this.getRunStateMarkerPath(sessionId, jobName);
             if (!markerPath || !(0, fs_1.existsSync)(markerPath))
                 return undefined;
             return JSON.parse((0, fs_1.readFileSync)(markerPath, 'utf8'));
         }
         catch (error) {
-            this.log(`⚠️ [phase-start] failed to read run-state marker for jobId=${jobId}: ${error.message}`);
+            this.log(`[phase-start] Could not read marker: ${error.message}`);
             return undefined;
         }
     }
-    /** Upserts one phase's started timestamp into the run-state marker. Best-effort: a write failure only degrades Gate 4 to always-warn for this run. */
-    writeRunStateMarker(jobId, phaseId, timestamp) {
+    writeRunStateMarker(sessionId, jobName, marker) {
         try {
-            const markerPath = this.getRunStateMarkerPath(jobId);
+            const markerPath = this.getRunStateMarkerPath(sessionId, jobName);
             if (!markerPath)
                 return;
-            const existing = this.readRunStateMarker(jobId);
-            const updated = (0, handoff_contracts_1.upsertPhaseStarted)(existing, phaseId, timestamp);
+            if (!marker.phaseInstances?.length) {
+                if ((0, fs_1.existsSync)(markerPath))
+                    (0, fs_1.unlinkSync)(markerPath);
+                return;
+            }
             (0, fs_1.mkdirSync)((0, path_1.dirname)(markerPath), { recursive: true });
-            (0, fs_1.writeFileSync)(markerPath, JSON.stringify(updated), 'utf8');
+            (0, fs_1.writeFileSync)(markerPath, JSON.stringify(marker), 'utf8');
         }
         catch (error) {
-            this.log(`⚠️ [phase-start] failed to write run-state marker for jobId=${jobId}: ${error.message}`);
+            this.log(`[phase-start] Could not persist marker: ${error.message}`);
+        }
+    }
+    /** Publish complete JSON before updating its discoverability pointers. */
+    writeRecoveryJson(path, value) {
+        (0, fs_1.mkdirSync)((0, path_1.dirname)(path), { recursive: true });
+        const temporary = `${path}.${(0, crypto_1.randomUUID)()}.tmp`;
+        try {
+            (0, fs_1.writeFileSync)(temporary, JSON.stringify(value), { encoding: 'utf8', mode: 0o600 });
+            (0, fs_1.renameSync)(temporary, path);
+        }
+        finally {
+            if ((0, fs_1.existsSync)(temporary))
+                (0, fs_1.unlinkSync)(temporary);
         }
     }
-    /** Deletes the run-state marker at job completion so the directory does not grow unbounded across a user's history of completed jobs. */
-    deleteRunStateMarker(jobId) {
+    /**
+     * Record every mentoring attempt, then advance only after accepted response
+     * finalization. No request-supplied nextPhase can advance durable recovery.
+     * The Hub run pointer bridges CLI and MCP session IDs, which are unrelated.
+     */
+    recordRecoveryState(args, sessionId, acceptedNext) {
+        if (!sessionId || sessionId === 'unknown'
+            || typeof args.jobName !== 'string' || !args.jobName
+            || typeof args.currentPhase !== 'string' || !args.currentPhase
+            || !['starting', 'complete', 'failure', 'incomplete'].includes(args.status))
+            return;
         try {
-            const markerPath = this.getRunStateMarkerPath(jobId);
-            if (markerPath && (0, fs_1.existsSync)(markerPath)) {
-                (0, fs_1.unlinkSync)(markerPath);
+            const root = this.getRunStateDir();
+            const jobId = typeof args.jobId === 'string' && args.jobId ? args.jobId : undefined;
+            const stateFile = jobId ? `${(0, run_recovery_state_1.safeRunStateKey)(jobId)}.json`
+                : `anonymous-${(0, run_recovery_state_1.safeRunStateKey)(JSON.stringify([sessionId, args.jobName]))}.json`;
+            const statePath = (0, path_1.join)(root, stateFile);
+            let previous;
+            let priorPath = statePath;
+            if (jobId && !(0, fs_1.existsSync)(statePath)) {
+                // Bind the currently anonymous run without adopting an older run's history.
+                const anonymousFile = `anonymous-${(0, run_recovery_state_1.safeRunStateKey)(JSON.stringify([sessionId, args.jobName]))}.json`;
+                const sessionPath = (0, path_1.join)(root, 'sessions', `${(0, run_recovery_state_1.safeRunStateKey)(sessionId)}.json`);
+                try {
+                    const pointer = JSON.parse((0, fs_1.readFileSync)(sessionPath, 'utf8'));
+                    if (!pointer.jobId && pointer.sessionId === sessionId && pointer.stateFile === anonymousFile) {
+                        priorPath = (0, path_1.join)(root, anonymousFile);
+                    }
+                }
+                catch { /* No valid anonymous pointer to promote. */ }
             }
+            if ((0, fs_1.existsSync)(priorPath)) {
+                try {
+                    const parsed = JSON.parse((0, fs_1.readFileSync)(priorPath, 'utf8'));
+                    const identityMatches = parsed?.jobId === jobId
+                        || (priorPath !== statePath && !parsed?.jobId && parsed?.sessionId === sessionId);
+                    if (identityMatches && parsed?.currentJobName === args.jobName
+                        && typeof parsed.sessionId === 'string'
+                        && ['active', 'waiting_review', 'terminal'].includes(parsed.status)
+                        && (typeof parsed.currentPhase === 'string' || parsed.currentPhase === null)
+                        && parsed.startedPhases && typeof parsed.startedPhases === 'object' && !Array.isArray(parsed.startedPhases)
+                        && Array.isArray(parsed.completedPhases))
+                        previous = parsed;
+                }
+                catch (error) {
+                    this.log(`[phase-recovery] Rebuilding unreadable state: ${error.message}`);
+                }
+            }
+            const timestamp = new Date().toISOString();
+            const accepted = acceptedNext !== undefined;
+            const currentPhase = accepted
+                ? (args.status === 'complete' ? acceptedNext.nextPhase : acceptedNext.nextPhase || args.currentPhase)
+                : previous ? previous.currentPhase : args.currentPhase;
+            const completedPhases = previous?.completedPhases || [];
+            if (accepted && (args.status === 'complete' || args.status === 'failure')) {
+                completedPhases.push({ phase: args.currentPhase, status: args.status, timestamp });
+            }
+            const parsedHandoff = [args.reviewHandoff, args.evidence?.reviewHandoff, args.findings?.reviewHandoff]
+                .map((value) => {
+                if (typeof value !== 'string')
+                    return value;
+                try {
+                    return JSON.parse(value);
+                }
+                catch {
+                    return undefined;
+                }
+            })
+                .find((value) => value && typeof value === 'object' && !Array.isArray(value) && typeof value.reviewRequired === 'boolean');
+            const status = !accepted && previous?.status !== 'active' && previous?.status
+                ? previous.status
+                : currentPhase === 'address-feedback'
+                    || (previous?.status === 'waiting_review' && currentPhase === previous.currentPhase && args.status !== 'failure')
+                    || (accepted && args.status === 'complete' && parsedHandoff?.reviewRequired === true)
+                    ? 'waiting_review' : currentPhase === null ? 'terminal' : 'active';
+            const state = {
+                jobId, sessionId, currentJobName: args.jobName, currentPhase,
+                issueNumber: typeof args.issueNumber === 'string' ? args.issueNumber : previous?.issueNumber,
+                status, lastStatus: args.status, lastAttemptPhase: args.currentPhase, updatedAt: timestamp,
+                startedPhases: accepted && args.status === 'starting'
+                    ? { ...previous?.startedPhases, [currentPhase || args.currentPhase]: timestamp }
+                    : previous?.startedPhases || {},
+                completedPhases,
+            };
+            this.writeRecoveryJson(statePath, state);
+            const pointer = { jobId, sessionId, stateFile };
+            this.writeRecoveryJson((0, path_1.join)(root, 'sessions', `${(0, run_recovery_state_1.safeRunStateKey)(sessionId)}.json`), pointer);
+            const hubRunId = process.env.FRAIM_HUB_RUN_ID;
+            if (hubRunId)
+                this.writeRecoveryJson((0, path_1.join)(root, 'runs', `${(0, run_recovery_state_1.safeRunStateKey)(hubRunId)}.json`), pointer);
         }
         catch (error) {
-            this.log(`⚠️ [phase-start] failed to delete run-state marker for jobId=${jobId}: ${error.message}`);
+            this.log(`[phase-recovery] Could not persist recovery state: ${error.message}`);
         }
     }
+    /** Called only after the response has passed every rejecting contract. */
+    acceptPhaseTracking(args, sessionId, nextPhase) {
+        this.recordRecoveryState(args, sessionId, { nextPhase });
+        if (!sessionId || sessionId === 'unknown' || !args.jobName || !args.currentPhase) {
+            return args.status === 'complete' || args.status === 'failure'
+                ? `Phase-start notice: phase ${args.currentPhase || '(unknown)'} cannot be matched to a run because its session or job identity is missing. Completion remains accepted.\n\n` : '';
+        }
+        const context = {
+            sessionId, jobName: args.jobName, phaseId: args.currentPhase, jobId: args.jobId,
+            resumeId: process.env.FRAIM_PHASE_RESUME_ID || undefined,
+        };
+        const timestamp = new Date().toISOString();
+        const marker = this.readRunStateMarker(sessionId, args.jobName);
+        if (args.status === 'starting') {
+            this.writeRunStateMarker(sessionId, args.jobName, (0, handoff_contracts_1.recordPhaseStart)(marker, { ...context, timestamp }));
+            return '';
+        }
+        if (args.status !== 'complete' && args.status !== 'failure')
+            return '';
+        const inspection = (0, handoff_contracts_1.inspectPhaseCompletion)(marker, context);
+        const updated = (0, handoff_contracts_1.commitPhaseCompletion)(marker, inspection, { ...context, timestamp });
+        if (args.status === 'complete' && nextPhase === null) {
+            updated.phaseInstances = updated.phaseInstances?.filter((instance) => instance.jobId && instance.jobId !== args.jobId);
+        }
+        this.writeRunStateMarker(sessionId, args.jobName, updated);
+        return (inspection.missingStart ? (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase) : '')
+            + (!args.jobId ? `Run-tracking notice: phase ${args.currentPhase} has no jobId; matching used the session, job name and phase.\n\n` : '');
+    }
     readCachedTemplateFile(filename) {
         try {
             const cachePath = this.getProviderCachePath(filename);
@@ -2428,41 +2555,40 @@ class FraimLocalMCPServer {
         if (request.method === 'tools/call' && typeof toolName === 'string') {
             // 🔍 SMART DISPATCHER: Intercept mentoring and job/workflow tools for local overrides
             if (toolName === 'seekMentoring') {
+                this.recordRecoveryState(args, requestSessionId);
+                // #1766: report an unrenderable supplied handoff before any mentoring
+                // success response, including when phase-policy enforcement is disabled.
+                // Match the host's direct/evidence/findings precedence and JSON support.
+                const suppliedHandoffs = [args.reviewHandoff, args.evidence?.reviewHandoff, args.findings?.reviewHandoff]
+                    .filter((value) => value !== undefined && value !== null)
+                    .map((value) => {
+                    if (typeof value !== 'string')
+                        return value;
+                    try {
+                        return JSON.parse(value);
+                    }
+                    catch {
+                        return value;
+                    }
+                });
+                const suppliedHandoff = suppliedHandoffs.find((value) => value && typeof value === 'object' && !Array.isArray(value) && typeof value.reviewRequired === 'boolean') ?? suppliedHandoffs[0];
+                if (suppliedHandoffs.length > 0) {
+                    const normalizationError = (0, handoff_contracts_1.reviewHandoffNormalizationError)(suppliedHandoff);
+                    if (normalizationError) {
+                        return {
+                            jsonrpc: '2.0',
+                            id: request.id,
+                            result: {
+                                isError: true,
+                                content: [{ type: 'text', text: `Review handoff was not applied: ${normalizationError}. This response does not confirm delivery.` }],
+                            },
+                        };
+                    }
+                }
                 try {
                     const mentor = this.getMentor(requestSessionId);
                     const tutoringResponse = await mentor.handleMentoringRequest(args);
                     this.log(`✅ Local seekMentoring succeeded for ${args.jobName}:${args.currentPhase}`);
-                    // Store response data for usage tracking (Bug fix: capture nextPhase and jobId)
-                    if (!this.mentoringResponseCache) {
-                        this.mentoringResponseCache = new Map();
-                    }
-                    this.mentoringResponseCache.set(request.id, {
-                        nextPhase: tutoringResponse.nextPhase,
-                        jobId: args.jobId || requestSessionId // Use jobId from args, fallback to sessionId
-                    });
-                    // Phase-start marker (Issue #1590 — warn-only).
-                    //
-                    // Detects a resumed address-feedback turn that never called
-                    // seekMentoring(status: "starting") for this run: the mentoring
-                    // response cache above is in-memory, keyed by request.id, and does
-                    // not survive the process restart a Hub resume performs, so a
-                    // durable per-jobId marker on disk is the only signal that
-                    // survives it. Scoped to address-feedback only (PHASE_START_WARN_PHASES);
-                    // never rejects — a lost marker (disk cleanup, first-ever run
-                    // before this shipped) must not strand a legitimate resume.
-                    let phaseStartWarning = '';
-                    if (args.jobId && handoff_contracts_1.PHASE_START_WARN_PHASES.includes(args.currentPhase)) {
-                        if (args.status === 'starting') {
-                            this.writeRunStateMarker(args.jobId, args.currentPhase, new Date().toISOString());
-                        }
-                        else if (args.status === 'complete' || args.status === 'failure') {
-                            const marker = this.readRunStateMarker(args.jobId);
-                            if (!(0, handoff_contracts_1.hasPhaseStarted)(marker, args.currentPhase)) {
-                                this.log(`⚠️ [phase-start] ${args.currentPhase} entered without a starting call this run: jobId=${args.jobId}`);
-                                phaseStartWarning = (0, handoff_contracts_1.buildPhaseStartWarning)(args.currentPhase);
-                            }
-                        }
-                    }
                     // Quality enforcement (Issue #251).
                     //
                     // The local proxy owns seekMentoring for personalized-job support.
@@ -2551,6 +2677,16 @@ class FraimLocalMCPServer {
                         repo: handoffRepoState,
                     });
                     handoffErrors.push(...await this.validateNextJobRecommendationJobIds(args.evidence?.nextJobRecommendations, mentor));
+                    // Issue #1857: enforced on its own terms rather than folded into
+                    // handoffErrors. `missingField` below reads handoffErrors[0], and the
+                    // reviewHandoff escape hatch keys off that, so a reviewHandoff error in
+                    // slot 0 would silently carry a bad proposalSet through with it. These
+                    // are independent contracts and stay independent.
+                    const proposalSetErrors = (0, proposal_set_contract_1.validateProposalSet)(args.evidence?.proposalSet);
+                    if (proposalSetErrors) {
+                        this.log(`⚠️ Proposal set contract rejected seekMentoring for ${args.jobName}:${args.currentPhase}: ${proposalSetErrors.join('; ')}`);
+                        return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, (0, handoff_contracts_1.buildHandoffRejectionMessage)(args.currentPhase, 'proposalSet', proposalSetErrors));
+                    }
                     if (handoffErrors.length > 0) {
                         const missingField = handoffErrors[0].includes('reviewHandoff') ? 'reviewHandoff'
                             : handoffErrors[0].includes('nextJobRecommendations') ? 'nextJobRecommendations'
@@ -2616,7 +2752,20 @@ class FraimLocalMCPServer {
                         const rejection = (0, test_evidence_contract_1.buildTestEvidenceRejectionMessage)(args.currentPhase, testEvidenceErrors);
                         return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, rejection);
                     }
-                    return await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, phaseStartWarning + tutoringResponse.message);
+                    const acceptedResponse = await this.finalizeLocalToolTextResponse(request, requestSessionId, requestId, tutoringResponse.message);
+                    if (acceptedResponse.error || acceptedResponse.result?.isError)
+                        return acceptedResponse;
+                    const phaseStartWarning = this.acceptPhaseTracking(args, requestSessionId, tutoringResponse.nextPhase);
+                    if (phaseStartWarning && acceptedResponse.result?.content?.[0]) {
+                        acceptedResponse.result.content[0].text = phaseStartWarning + acceptedResponse.result.content[0].text;
+                    }
+                    if (!this.mentoringResponseCache)
+                        this.mentoringResponseCache = new Map();
+                    this.mentoringResponseCache.set(request.id, {
+                        nextPhase: tutoringResponse.nextPhase,
+                        jobId: args.jobId,
+                    });
+                    return acceptedResponse;
                 }
                 catch (error) {
                     this.log(`⚠️ Local seekMentoring failed: ${error.message}. Falling back to remote.`);
@@ -2735,6 +2884,19 @@ class FraimLocalMCPServer {
         }
         const response = await this._doProxyToRemote(injectedRequest, requestId);
         const processedResponse = await this.finalizeToolResponse(injectedRequest, response, requestSessionId, requestId);
+        // Reconcile remote fallback against the same persisted local instance.
+        // Only the remote's explicit accepted result can consume a start.
+        if (toolName === 'seekMentoring' && !processedResponse.error && !processedResponse.result?.isError
+            && response.result?.structuredContent?.phaseAccepted === true) {
+            const metadata = response.result.structuredContent;
+            const textBlock = processedResponse.result?.content?.find((item) => item.type === 'text');
+            if (textBlock) {
+                const remoteWarning = metadata.phaseStartWarning;
+                if (remoteWarning)
+                    textBlock.text = textBlock.text.replace(remoteWarning, '');
+                textBlock.text = this.acceptPhaseTracking(args, requestSessionId, metadata.nextPhase) + textBlock.text;
+            }
+        }
         this.log(`📤 ${injectedRequest.method} → ${processedResponse.error ? 'ERROR' : 'OK'}`);
         return processedResponse;
     }
@@ -2829,9 +2991,7 @@ class FraimLocalMCPServer {
         process.stdin.setEncoding('utf8');
         // Set up periodic usage data upload
         const uploadInterval = setInterval(() => {
-            this.uploadUsageData().catch(error => {
-                this.log(`⚠️ Failed to upload usage data: ${error.message}`);
-            });
+            void this.uploadUsageData();
         }, 60000); // Upload every minute
         uploadInterval.unref?.();
         // Clean up interval on shutdown
@@ -2923,7 +3083,8 @@ class FraimLocalMCPServer {
         let args = request.params?.arguments || {};
         const requestSessionId = this.extractSessionIdFromRequest(request);
         if (toolName && requestSessionId) {
-            const success = !response.error;
+            const success = !response.error && !response.result?.isError;
+            let acceptedPhaseResponse = success && response.result?.structuredContent?.phaseAccepted === true;
             this.log(`📊 Collecting usage: ${toolName} (session: ${requestSessionId}, success: ${success})`);
             if (!this.repoInfo) {
                 this.detectRepoInfo();
@@ -2933,6 +3094,7 @@ class FraimLocalMCPServer {
                 const requestId = request.id;
                 const cachedResponse = this.mentoringResponseCache.get(requestId);
                 if (cachedResponse) {
+                    acceptedPhaseResponse = success;
                     args = {
                         ...args,
                         nextPhase: cachedResponse.nextPhase,
@@ -2952,38 +3114,19 @@ class FraimLocalMCPServer {
                     this.log(`📊 Enriched get_fraim_job args with jobId=${cached.jobId}, action=start`);
                 }
             }
-            // Capture the current queue size before collection
+            // Keep enrichment request-local until it settles. Neither another call
+            // nor the uploader may observe an event that is still being constructed.
+            const enrichment = toolName === 'seekMentoring' ? await this.captureTokenUsage() : {};
+            if (this.isShutdown)
+                return;
+            // Capture the current queue size before synchronous publication.
             const beforeCount = this.usageCollector.getEventCount();
             try {
-                this.usageCollector.collectMCPCall(toolName, args, requestSessionId, success);
+                this.usageCollector.collectMCPCall(toolName, args, requestSessionId, success, enrichment);
                 // Check if the event was actually added to the queue
                 const afterCount = this.usageCollector.getEventCount();
                 if (afterCount > beforeCount) {
                     this.log(`📊 ✅ Event queued successfully (queue: ${afterCount})`);
-                    // Issue #330: pluggable token capture by agent.
-                    if (toolName === 'seekMentoring') {
-                        try {
-                            const agentName = this.agentInfo?.name;
-                            const agentModel = this.agentInfo?.model;
-                            const adapter = (0, token_adapter_registry_js_1.resolveTokenAdapter)(agentName);
-                            const result = await adapter.capture({
-                                agent: agentName,
-                                model: agentModel,
-                                log: (msg) => this.log(`📊 ${msg}`),
-                            });
-                            if (result.snapshot) {
-                                this.usageCollector.attachTokenSnapshot(result.snapshot);
-                                this.log(`📊 🔢 Token snapshot attached via ${adapter.id} adapter (input=${result.snapshot.inputTokens}, output=${result.snapshot.outputTokens})`);
-                            }
-                            else if (result.reason) {
-                                this.usageCollector.attachCaptureUnavailable(result.reason);
-                                this.log(`📊 ℹ️ Token capture unavailable (${result.reason}) for adapter ${adapter.id}`);
-                            }
-                        }
-                        catch (err) {
-                            this.log(`📊 ⚠️ Token snapshot capture failed (non-blocking): ${err.message}`);
-                        }
-                    }
                 }
                 else {
                     this.log(`📊 ⚠️ Event not queued - tool may not be tracked: ${toolName}`);
@@ -2993,7 +3136,7 @@ class FraimLocalMCPServer {
                     }
                 }
                 // Emit job-complete event when seekMentoring reaches the final phase
-                if (toolName === 'seekMentoring' && args.nextPhase === null && args.jobName && args.jobId) {
+                if (toolName === 'seekMentoring' && acceptedPhaseResponse && args.status === 'complete' && args.nextPhase === null && args.jobName && args.jobId) {
                     try {
                         this.usageCollector.collectJobComplete(args.jobName, args.jobId, requestSessionId);
                         this.log(`📊 ✅ Job complete event emitted: ${args.jobName} (jobId: ${args.jobId})`);
@@ -3001,10 +3144,11 @@ class FraimLocalMCPServer {
                     catch (err) {
                         this.log(`📊 ⚠️ Job complete event failed (non-blocking): ${err.message}`);
                     }
-                    // Issue #1590, Gate 4: clean up the per-run phase-start marker so
-                    // ~/.fraim/run-state/ does not grow unbounded across a user's
-                    // history of completed jobs.
-                    this.deleteRunStateMarker(args.jobId);
+                }
+                if (toolName === 'seekMentoring' && afterCount > beforeCount) {
+                    // Start HTTP now, after the terminal pair is collected, without making
+                    // the local mentoring response depend on transport latency or success.
+                    void this.uploadUsageData();
                 }
             }
             catch (error) {
@@ -3015,6 +3159,30 @@ class FraimLocalMCPServer {
             this.log(`⚠️ Skipping usage collection: toolName=${toolName}, sessionId=${requestSessionId}`);
         }
     }
+    /** Capture only this request's enrichment before publishing its usage event. */
+    async captureTokenUsage() {
+        try {
+            const agentName = this.agentInfo?.name;
+            const agentModel = this.agentInfo?.model;
+            const adapter = (0, token_adapter_registry_js_1.resolveTokenAdapter)(agentName);
+            const result = await adapter.capture({
+                agent: agentName,
+                model: agentModel,
+                log: (msg) => this.log(`📊 ${msg}`),
+            });
+            if (result.snapshot) {
+                this.log(`Token snapshot captured via ${adapter.id} adapter (input=${result.snapshot.inputTokens}, output=${result.snapshot.outputTokens})`);
+                return { tokenSnapshot: result.snapshot };
+            }
+            const reason = result.reason || 'token_capture_unavailable';
+            this.log(`Token capture unavailable (${reason}) for adapter ${adapter.id}`);
+            return { tokenCaptureUnavailableReason: reason };
+        }
+        catch {
+            this.log('Token capture failed; recording unavailable');
+            return { tokenCaptureUnavailableReason: 'token_capture_error' };
+        }
+    }
     /**
      * Emit a quality score to the remote FRAIM server (Issue #251).
      *
@@ -3045,24 +3213,39 @@ class FraimLocalMCPServer {
     /**
      * Flush collected usage data to the remote server
      */
-    async uploadUsageData() {
-        const eventCount = this.usageCollector.getEventCount();
-        this.log(`📊 Upload check: ${eventCount} events queued`);
-        if (eventCount === 0) {
-            return; // Nothing to flush
-        }
-        try {
-            this.log(`📊 Attempting to flush ${eventCount} events to ${this.remoteUrl}/api/analytics/events`);
-            await this.usageCollector.flush(this.remoteUrl, this.apiKey);
-            this.log(`📊 ✅ Successfully flushed ${eventCount} usage events to remote server`);
-        }
-        catch (error) {
-            this.log(`📊 ❌ Usage flushing error: ${error.message}`);
-            // Log additional details for debugging
-            if (error.response) {
-                this.log(`📊 🔍 HTTP Status: ${error.response.status}, Data: ${JSON.stringify(error.response.data)}`);
+    uploadUsageData() {
+        if (this.isShutdown)
+            return Promise.resolve();
+        this.usageUploadRequested = true;
+        if (this.usageUploadInFlight)
+            return this.usageUploadInFlight;
+        const upload = async () => {
+            while (this.usageUploadRequested && !this.isShutdown) {
+                this.usageUploadRequested = false;
+                const eventCount = this.usageCollector.getEventCount();
+                if (eventCount === 0)
+                    return;
+                const startedAt = Date.now();
+                try {
+                    await this.usageCollector.flush(this.remoteUrl, this.apiKey);
+                    this.log(`Usage upload succeeded: ${eventCount} events, ${Date.now() - startedAt}ms`);
+                }
+                catch {
+                    // The collector alone restores the failed snapshot. Even if another
+                    // trigger arrived in flight, wait for a later trigger after failure.
+                    this.usageUploadRequested = false;
+                    this.log(`Usage upload failed; buffered for a later trigger (${Date.now() - startedAt}ms)`);
+                    return;
+                }
             }
-        }
+        };
+        this.usageUploadInFlight = upload().finally(() => {
+            this.usageUploadInFlight = null;
+            // A trigger can run between the loop settling and this promise cleanup.
+            if (this.usageUploadRequested && !this.isShutdown)
+                return this.uploadUsageData();
+        });
+        return this.usageUploadInFlight;
     }
 }
 exports.FraimLocalMCPServer = FraimLocalMCPServer;

package/dist/src/local-mcp-server/usage-collector.js

@@ -57,7 +57,7 @@ class UsageCollector {
     /**
      * Collect MCP tool call event
      */
-    collectMCPCall(toolName, args, sessionId, success = true) {
+    collectMCPCall(toolName, args, sessionId, success = true, enrichment = {}) {
         const parsed = this.parseMCPCall(toolName, args);
         if (!parsed) {
             const errorMsg = `[UsageCollector] 🚫 Tool not tracked: ${toolName}`;
@@ -83,6 +83,8 @@ class UsageCollector {
             repoIdentifier: this.repoIdentifier || undefined,
             agentName: this.agentName || undefined,
             agentModel: this.agentModel || undefined,
+            tokenSnapshot: enrichment.tokenSnapshot,
+            tokenCaptureUnavailableReason: enrichment.tokenCaptureUnavailableReason,
             jobId: args.jobId || undefined, // Bug fix: capture jobId from enriched args
             args: Object.keys(analyticsArgs).length > 0 ? analyticsArgs : undefined
         };
@@ -212,25 +214,6 @@ class UsageCollector {
         this.events = [];
         return eventsToUpload;
     }
-    /**
-     * Attach a token snapshot to the most recently queued event.
-     * Used to associate Prometheus-scraped token data with seekMentoring events.
-     */
-    attachTokenSnapshot(snapshot) {
-        if (this.events.length > 0) {
-            this.events[this.events.length - 1].tokenSnapshot = snapshot;
-        }
-    }
-    /**
-     * Issue #330: when a token capture adapter returns null, record the
-     * typed reason on the most recently queued event so the dashboard
-     * can explain coverage gaps to the user.
-     */
-    attachCaptureUnavailable(reason) {
-        if (this.events.length > 0) {
-            this.events[this.events.length - 1].tokenCaptureUnavailableReason = reason;
-        }
-    }
     /**
      * Get current event count
      */
@@ -269,17 +252,10 @@ class UsageCollector {
             // Success - events are already cleared from the queue
         }
         catch (error) {
-            const status = error.response?.status;
-            const message = error.response?.data?.error || error.message;
-            const errorMsg = `[UsageCollector] ❌ Failed to flush usage events (HTTP ${status}): ${message}`;
+            const status = typeof error.response?.status === 'number' ? error.response.status : 'unavailable';
+            const errorMsg = `[UsageCollector] Failed to flush usage events (HTTP ${status}); batch retained for retry`;
             console.error(errorMsg);
             process.stderr.write(errorMsg + '\n');
-            // Log additional debug info
-            if (error.response?.data) {
-                const debugMsg = `[UsageCollector] 🔍 Response data: ${JSON.stringify(error.response.data)}`;
-                console.error(debugMsg);
-                process.stderr.write(debugMsg + '\n');
-            }
             // Put events back at the beginning of the queue for next try
             this.events = [...events, ...this.events];
             // Re-throw the error so the main server can log it too

package/dist/src/mcp/tool-schemas.js

@@ -335,7 +335,7 @@ Do not use this tool for other repositories or external project issue trackers.`
                     },
                     jobId: {
                         type: 'string',
-                        description: 'Job ID returned by get_fraim_job. Required for tracking job execution and completion.'
+                        description: 'Job ID returned by get_fraim_job. Supply when available; phase starts without it match by session, job name and phase.'
                     },
                     issueNumber: {
                         type: 'string',
@@ -372,7 +372,7 @@ Do not use this tool for other repositories or external project issue trackers.`
                         description: 'Absolute path to the directory you are actually working in right now, when it differs from this session\'s default project directory — most commonly an issue worktree created by prep-issue.sh. Pass this on submit-phase calls carrying evidence.reviewHandoff so the review-action-completeness check reads the branch of your real worktree instead of a directory this long-lived session cached earlier. Optional; omit when working in the default project directory.'
                     }
                 },
-                required: requiredWithSession(['jobName', 'jobId', 'issueNumber', 'currentPhase', 'status'])
+                required: requiredWithSession(['jobName', 'issueNumber', 'currentPhase', 'status'])
             }
         }
     ];