feat(hints): rank safe recovery candidates (#1018)

src/hints/hint-engine.ts

@@ -18,6 +18,7 @@ import type { ToolCallEvent } from '../dashboard/types';
 import type { ActivityTracker } from '../dashboard/activity-tracker';
 import { PatternLearner } from './pattern-learner';
 import { ProgressTracker } from './progress-tracker.js';
+import { formatCandidateHint, rankRecoveryCandidates, type RecoveryCandidate } from '../recovery';
 import { RepeatedCallDetector } from './repeated-call-detector.js';
 import { errorRecoveryRules } from './rules/error-recovery';
 import { blockingPageRules } from './rules/blocking-page';
@@ -85,6 +86,7 @@ export interface HintResult {
     tool?: string;
     reason: string;
   };
+  candidates?: RecoveryCandidate[];
   context?: {
     element?: string;
     coordinates?: string;
@@ -238,9 +240,11 @@ export class HintEngine {
       const key = escalationKey('progress-tracker-stuck');
       const fireCount = (this.hintEscalation.get(key) || 0) + 1;
       this.hintEscalation.set(key, fireCount);
+      const candidates = rankRecoveryCandidates({ toolName, resultText, isError, recentCalls });
       const rawHintText = 'STOP — you are stuck. The last several tool calls made no meaningful progress ' +
         '(errors, stale refs, auth redirects, or timeouts). ' +
         'Step back and try a completely different approach, or ask the user for help.' +
+        formatCandidateHint(candidates) +
         (ledgerHint ? ` ${ledgerHint}` : '');
       const severity = fireCount >= 2 ? 'critical' as const : 'warning' as const;
       this.log({ timestamp: Date.now(), toolName, isError, matchedRule: 'progress-tracker-stuck', hint: rawHintText, severity, fireCount });
@@ -251,15 +255,18 @@ export class HintEngine {
         fireCount,
         hint: this.formatHintMessage(severity, rawHintText, fireCount),
         rawHint: rawHintText,
+        ...(candidates.length > 0 && { candidates }),
       };
     }
 
     if (status === 'stalling') {
       const key = escalationKey('progress-tracker-stalling');
       const fireCount = (this.hintEscalation.get(key) || 0) + 1;
       this.hintEscalation.set(key, fireCount);
+      const candidates = rankRecoveryCandidates({ toolName, resultText, isError, recentCalls });
       const rawHintText = 'Warning: recent tool calls are not making progress. ' +
         'Consider trying a different approach before getting stuck.' +
+        formatCandidateHint(candidates) +
         (ledgerHint ? ` ${ledgerHint}` : '');
       const severity = this.getSeverity(fireCount);
       this.log({ timestamp: Date.now(), toolName, isError, matchedRule: 'progress-tracker-stalling', hint: rawHintText, severity, fireCount });
@@ -270,6 +277,7 @@ export class HintEngine {
         fireCount,
         hint: this.formatHintMessage(severity, rawHintText, fireCount),
         rawHint: rawHintText,
+        ...(candidates.length > 0 && { candidates }),
       };
     }
 

src/mcp-server.ts

@@ -2050,6 +2050,7 @@ export class MCPServer {
               rule: hintResult.rule,
               fireCount: hintResult.fireCount,
               ...(hintResult.suggestion && { suggestion: hintResult.suggestion }),
+              ...(hintResult.candidates && { candidates: hintResult.candidates }),
               ...(hintResult.context && { context: hintResult.context }),
             };
             const content = (result as Record<string, unknown>).content;
@@ -2258,6 +2259,7 @@ export class MCPServer {
             rule: hintResult.rule,
             fireCount: hintResult.fireCount,
             ...(hintResult.suggestion && { suggestion: hintResult.suggestion }),
+            ...(hintResult.candidates && { candidates: hintResult.candidates }),
             ...(hintResult.context && { context: hintResult.context }),
           };
           if (Array.isArray(errResult.content)) {