@adhdev/daemon-core 0.9.82-rc.456 → 0.9.82-rc.457

package/src/providers/cli-provider-instance.ts

@@ -22,6 +22,8 @@ import type { PtyRuntimeMetadata, PtyTransportFactory } from '../cli-adapters/pt
 import { StatusMonitor } from './status-monitor.js';
 import { ChatHistoryWriter, isNativeSourceCanonicalHistory, materializeProviderNativeHistory, readChatHistory, readProviderChatHistory } from '../config/chat-history.js';
 import { LOG } from '../logging/logger.js';
+import { recordDebugTrace } from '../logging/debug-trace.js';
+import { shouldCollectTraceCategory } from '../logging/debug-config.js';
 import { traceMeshEventStage, traceMeshEventDrop } from '../mesh/mesh-event-trace.js';
 import type { ChatMessage } from '../types.js';
 import { buildPersistedProviderEffectMessage, normalizeProviderEffects } from './control-effects.js';
@@ -1526,9 +1528,23 @@ export class CliProviderInstance implements ProviderInstance {
     }
 
     private completionFinalAssistantEvidence(parsedMessages: unknown, turnStartedAt?: number): CompletionFinalAssistantEvidence {
+        // (FALSEIDLE FixB) UPPER-BOUND turn-end evidence. completionHasFinalAssistantMessage is a
+        // pure message-content check ("does the last visible bubble read as a finalized assistant
+        // reply, post-dating the turn start?"). That LOWER bound alone treated the FIRST assistant
+        // bubble of a turn that is STILL running — a tool call in flight between two assistant
+        // bubbles — as proof the turn ended (RCA cases a & b). Require in ADDITION that the turn is
+        // genuinely OVER: hasAdapterPendingResponse() folds the three upper-bound discriminators
+        // into one — currentTurnScope closed, no in-flight tool (isProcessing false), and no partial
+        // response buffer. So a mid-turn point-sample (short-gen / fast-collapse inline paths that
+        // do NOT route through getCompletedFinalizationBlock) yields present=false and is held/settled
+        // rather than fired. A genuinely-finished turn (adapter idle, no pending) is unaffected — the
+        // gate stays open and the completion fires exactly as before. This mirrors the established
+        // `completionHasFinalAssistantMessage(...) && !hasAdapterPendingResponse()` pairing already
+        // used by the no-progress monitor reconcile path.
+        const turnClosed = !this.hasAdapterPendingResponse();
         if (this.completionHasFinalAssistantMessage(parsedMessages, turnStartedAt)) {
             return {
-                present: true,
+                present: turnClosed,
                 messages: Array.isArray(parsedMessages) ? parsedMessages : [],
                 source: 'parsed',
             };
@@ -1537,7 +1553,7 @@ export class CliProviderInstance implements ProviderInstance {
         const externalMessages = this.readExternalCompletionMessages();
         if (externalMessages) {
             return {
-                present: this.completionHasFinalAssistantMessage(externalMessages, turnStartedAt),
+                present: turnClosed && this.completionHasFinalAssistantMessage(externalMessages, turnStartedAt),
                 messages: externalMessages,
                 source: 'external-native',
             };
@@ -1690,11 +1706,21 @@ export class CliProviderInstance implements ProviderInstance {
 
         const adapterAny = this.adapter as any;
         const approvalResolvedIdle = pending.previousStatus === 'waiting_approval';
-        if (!approvalResolvedIdle) {
-            if (adapterAny?.isWaitingForResponse === true) return { reason: 'adapter_waiting_for_response', terminal: true };
-            if (adapterAny?.currentTurnScope) return { reason: 'adapter_turn_scope_active', terminal: true };
-            if (this.hasAdapterPendingResponse()) return { reason: 'adapter_pending_response', terminal: true };
-        }
+        // (FALSEIDLE-a FixA) The adapter pending-response checks run UNCONDITIONALLY.
+        // Previously they were SKIPPED when approvalResolvedIdle, on the assumption that
+        // a waiting_approval→idle transition proved the approval's turn was over. But
+        // auto-approve RESOLVES the modal and the agent RESUMES the same turn — currentTurnScope
+        // / isWaitingForResponse stay set, or a tool runs — so skipping the guard let the FIRST
+        // assistant bubble of the still-running turn be mistaken for the last and fired an early
+        // completion the coordinator could never correct (RCA case a). Keep the guard live for the
+        // approval path too: when the resumed turn genuinely ends these clear and the completion
+        // fires. Approval-resolved holds are NON-terminal (bounded by COMPLETED_FINALIZATION_MAX_WAIT_MS)
+        // so a provider that never closes its turn-scope still force-fires a weak completion rather
+        // than wedging; the non-approval path keeps its terminal hold (a genuinely-busy adapter must
+        // never force a completion out).
+        if (adapterAny?.isWaitingForResponse === true) return { reason: 'adapter_waiting_for_response', terminal: !approvalResolvedIdle };
+        if (adapterAny?.currentTurnScope) return { reason: 'adapter_turn_scope_active', terminal: !approvalResolvedIdle };
+        if (this.hasAdapterPendingResponse()) return { reason: 'adapter_pending_response', terminal: !approvalResolvedIdle };
 
         const partial = typeof this.adapter.getPartialResponse === 'function'
             ? this.adapter.getPartialResponse()
@@ -1891,6 +1917,40 @@ export class CliProviderInstance implements ProviderInstance {
         };
     }
 
+    // COMPLETION-EARLYNOTIFY instrumentation. A session-keyed FSM-transition +
+    // completion-gate snapshot recorded into the shared debug-trace ring buffer
+    // (secret-safe, length/role/pattern-name only — never screen or bubble text).
+    // Retrieved via getRecentDebugTrace (chat_debug_bundle). Both categories are a
+    // no-op unless collectDebugTrace is on AND the category is selected, so the
+    // hot-path guards below (completionTraceOn / fsmTraceOn) keep production cost
+    // at a single boolean check.
+    private completionTraceOn(): boolean {
+        return shouldCollectTraceCategory('completion-gate');
+    }
+    private fsmTraceOn(): boolean {
+        return shouldCollectTraceCategory('fsm-transition');
+    }
+    private recordCompletionGateTrace(stage: string, payload: Record<string, unknown>): void {
+        recordDebugTrace({
+            category: 'completion-gate',
+            stage,
+            level: 'debug',
+            sessionId: this.instanceId,
+            providerType: this.type,
+            payload,
+        });
+    }
+    private recordFsmTransitionTrace(payload: Record<string, unknown>): void {
+        recordDebugTrace({
+            category: 'fsm-transition',
+            stage: 'transition',
+            level: 'debug',
+            sessionId: this.instanceId,
+            providerType: this.type,
+            payload,
+        });
+    }
+
     private flushCompletedDebounceIfFinalized(): void {
         const pending = this.completedDebouncePending;
         if (!pending) {
@@ -1904,6 +1964,13 @@ export class CliProviderInstance implements ProviderInstance {
         LOG.debug('CLI', `[${this.type}] flush attempt: adapterStatus=${latestStatus.status} latestVisible=${latestVisibleStatus} generatingStartedAt=${this.generatingStartedAt} isWaitingForResponse=${!!(this.adapter as any)?.isWaitingForResponse} hasPartial=${!!this.adapter.getPartialResponse?.()}`);
         if (latestVisibleStatus !== 'idle') {
             LOG.info('CLI', `[${this.type}] cancelled pending completed (resumed ${latestVisibleStatus})`);
+            if (this.completionTraceOn()) this.recordCompletionGateTrace('cancel', {
+                blockReason: 'resumed_status',
+                latestVisibleStatus,
+                previousStatus: pending.previousStatus,
+                busyEpochAtArm: pending.busyEpochAtArm,
+                busyEpoch: this.busyEpoch,
+            });
             this.completedDebouncePending = null;
             this.completedDebounceTimer = null;
             return;
@@ -1921,6 +1988,14 @@ export class CliProviderInstance implements ProviderInstance {
         // so shared behaviour for claude/codex/antigravity is strictly stricter, never looser.
         if (typeof pending.busyEpochAtArm === 'number' && this.busyEpoch !== pending.busyEpochAtArm) {
             LOG.info('CLI', `[${this.type}] cancelled pending completed (busy re-entry during settle: epoch ${pending.busyEpochAtArm}→${this.busyEpoch})`);
+            if (this.completionTraceOn()) this.recordCompletionGateTrace('cancel', {
+                blockReason: 'busy_reentry',
+                latestVisibleStatus,
+                previousStatus: pending.previousStatus,
+                busyEpochAtArm: pending.busyEpochAtArm,
+                busyEpoch: this.busyEpoch,
+                busyEpochDelta: this.busyEpoch - pending.busyEpochAtArm,
+            });
             this.completedDebouncePending = null;
             this.completedDebounceTimer = null;
             return;
@@ -1930,6 +2005,14 @@ export class CliProviderInstance implements ProviderInstance {
             && typeof latestOutputAt === 'number'
             && latestOutputAt > pending.lastOutputAtArm) {
             LOG.info('CLI', `[${this.type}] cancelled pending completed (new PTY output during settle: ${pending.lastOutputAtArm}→${latestOutputAt})`);
+            if (this.completionTraceOn()) this.recordCompletionGateTrace('cancel', {
+                blockReason: 'new_pty_output',
+                latestVisibleStatus,
+                previousStatus: pending.previousStatus,
+                lastOutputAtArm: pending.lastOutputAtArm,
+                lastOutputAt: latestOutputAt,
+                lastOutputAtDelta: latestOutputAt - pending.lastOutputAtArm,
+            });
             this.completedDebouncePending = null;
             this.completedDebounceTimer = null;
             return;
@@ -1975,6 +2058,17 @@ export class CliProviderInstance implements ProviderInstance {
                     if (this.isMeshWorkerSession()) {
                         traceMeshEventDrop('completion_gate_hold', this.meshTraceCtx(), `${blockReason} waited=${waitedMs}ms`);
                     }
+                    // COMPLETION-EARLYNOTIFY: a hold is the CORRECT outcome when the turn is not
+                    // yet proven done (the FixA/FixB gates route here); trace it so an early-notify
+                    // investigation can see the gate holding rather than firing.
+                    if (this.completionTraceOn()) this.recordCompletionGateTrace('hold', {
+                        blockReason,
+                        latestVisibleStatus,
+                        terminal: block.terminal === true,
+                        holdForTranscript: block.holdForTranscript === true,
+                        approvalResolvedIdle: pending.previousStatus === 'waiting_approval',
+                        waitedMs,
+                    });
                     pending.loggedBlockReason = blockReason;
                 }
                 this.scheduleCompletedDebounceFlush(COMPLETED_FINALIZATION_RETRY_MS);
@@ -1997,6 +2091,19 @@ export class CliProviderInstance implements ProviderInstance {
             if (this.isMeshWorkerSession()) {
                 traceMeshEventStage('fired', this.meshTraceCtx(), `forced after ${waitedMs}ms (${blockReason})`);
             }
+            if (this.completionTraceOn()) this.recordCompletionGateTrace('fire', {
+                path: isTranscriptEvidenceGate && !emittedAfterFinalizationTimeout ? 'canon_c_decoupled' : 'forced_timeout',
+                blockReason,
+                latestVisibleStatus,
+                approvalResolvedIdle: pending.previousStatus === 'waiting_approval',
+                finalAssistantPresent: (completionDiagnostic as any).finalAssistantPresent === true,
+                evidenceSource: (completionDiagnostic as any).finalAssistantEvidenceSource ?? null,
+                lastVisibleRole: (completionDiagnostic as any).lastVisibleRole ?? null,
+                lastVisibleContentLen: (completionDiagnostic as any).lastVisibleContentLength ?? null,
+                emittedAfterFinalizationTimeout,
+                waitedMs,
+                busyEpoch: this.busyEpoch,
+            });
             this.pushEvent({
                 event: 'agent:generating_completed',
                 chatTitle: pending.chatTitle,
@@ -2028,6 +2135,14 @@ export class CliProviderInstance implements ProviderInstance {
         if (this.isMeshWorkerSession()) {
             traceMeshEventStage('fired', this.meshTraceCtx(), `duration=${pending.duration}s`);
         }
+        if (this.completionTraceOn()) this.recordCompletionGateTrace('fire', {
+            path: 'clean',
+            latestVisibleStatus,
+            approvalResolvedIdle: pending.previousStatus === 'waiting_approval',
+            finalAssistantPresent: true,
+            duration: pending.duration,
+            busyEpoch: this.busyEpoch,
+        });
         this.pushEvent({
             event: 'agent:generating_completed',
             chatTitle: pending.chatTitle,
@@ -2424,6 +2539,22 @@ export class CliProviderInstance implements ProviderInstance {
         const previousStatus = this.lastStatus;
         if (newStatus !== this.lastStatus) {
             LOG.info('CLI', `[${this.type}] status: ${this.lastStatus} → ${newStatus}`);
+            // COMPLETION-EARLYNOTIFY: snapshot every FSM status transition (the arm/fire/cancel
+            // decisions downstream all hang off these edges). Guarded so production pays only a
+            // boolean check; payload carries the visibility/auto-approve flags and the continuity
+            // clocks (busyEpoch / lastOutputAt / lastScreenChangeAt) that the completion gate reads.
+            if (this.fsmTraceOn()) this.recordFsmTransitionTrace({
+                from: this.lastStatus,
+                to: newStatus,
+                rawStatus,
+                autoApproveActive,
+                autoApproveHoldIdle,
+                autoApproveBusy: this.autoApproveBusy,
+                hasPending: this.hasAdapterPendingResponse(),
+                busyEpoch: this.busyEpoch,
+                lastOutputAt: typeof adapterStatus?.lastOutputAt === 'number' ? adapterStatus.lastOutputAt : null,
+                lastScreenChangeAt: typeof adapterStatus?.lastScreenChangeAt === 'number' ? adapterStatus.lastScreenChangeAt : null,
+            });
             // GENERATING-MISSING (win32 fresh-worktree first-turn): a freshly-launched session
             // is in 'starting' until its startup-grace settles to idle. When the FIRST inject
             // lands inside that grace window, the adapter can report status DIRECTLY
@@ -2661,6 +2792,17 @@ export class CliProviderInstance implements ProviderInstance {
                         if (this.isMeshWorkerSession()) {
                             traceMeshEventStage('arm', this.meshTraceCtx(), `short-generating settle-arm (source=${shortEvidenceSource}, missingEvidence=${missingEvidence})`);
                         }
+                        if (this.completionTraceOn()) this.recordCompletionGateTrace('arm', {
+                            branch: 'short_generating',
+                            previousStatus: this.lastStatus,
+                            turnStartedAt: shortTurnStartedAt || null,
+                            busyEpochAtArm: this.busyEpoch,
+                            lastOutputAtArm: typeof adapterStatus?.lastOutputAt === 'number' ? adapterStatus.lastOutputAt : null,
+                            flushDelay: NATIVE_HISTORY_MESH_IDLE_SETTLE_MS,
+                            evidenceSource: shortEvidenceSource,
+                            missingEvidence,
+                            hasFinalSummary: !!shortFinalSummary,
+                        });
                         this.scheduleCompletedDebounceFlush(NATIVE_HISTORY_MESH_IDLE_SETTLE_MS);
                     } else if (missingEvidence) {
                         // NON-MESH, missing evidence: suppress the completion event entirely (the
@@ -2749,6 +2891,16 @@ export class CliProviderInstance implements ProviderInstance {
                         ? (meshSettleSession ? NATIVE_HISTORY_MESH_IDLE_SETTLE_MS : 0)
                         : 3000;
                     LOG.debug('CLI', `[${this.type}] set completedDebouncePending duration=${duration}s ownsExternalHistory=${ownsExternalHistory} meshSettle=${meshSettleSession} flushDelay=${flushDelay}ms generatingStartedAt=${this.generatingStartedAt}`);
+                    if (this.completionTraceOn()) this.recordCompletionGateTrace('arm', {
+                        branch: 'normal',
+                        previousStatus: this.completedDebouncePending.previousStatus,
+                        turnStartedAt: this.completedDebouncePending.turnStartedAt ?? null,
+                        busyEpochAtArm: this.completedDebouncePending.busyEpochAtArm ?? null,
+                        lastOutputAtArm: this.completedDebouncePending.lastOutputAtArm ?? null,
+                        flushDelay,
+                        ownsExternalHistory,
+                        meshSettle: meshSettleSession,
+                    });
                     this.scheduleCompletedDebounceFlush(flushDelay);
                 }
             } else if (newStatus === 'idle' && this.lastStatus === 'starting') {

package/src/providers/provider-loader.ts

@@ -37,6 +37,11 @@ import {
   resolveActiveSource,
 } from './external-sources.js';
 import type { ProviderSourceMode } from '../config/config.js';
+import {
+  resolveRegistryBaseUrl,
+  resolveProviderTarballUrl,
+  resolveProviderTarballTarget,
+} from '../config/registry-resolver.js';
 import type { ProviderSourceConfigSnapshot, ProviderUserDirSource } from '../config/provider-source-config.js';
 import { executeNativeHistory } from './spec/native-history-executor.js';
 import { createNativeHistoryDispatcher, type ReaderId } from './native-history/dispatcher.js';
@@ -186,13 +191,19 @@ export class ProviderLoader {
   private versionArchive: VersionArchive | null = null;
   private scriptsCache = new Map<string, Partial<ProviderScripts>>();
 
+  /**
+   * Resolved registry base URL and provider tarball URL. Resolution order:
+   * explicit config field (constructor option) → env var → vendor default.
+   * See `config/registry-resolver.ts`.
+   */
+  private readonly registryBaseUrl: string;
+  private readonly providerTarballUrl: string;
+
   /** Inject VersionArchive so resolve() can auto-detect installed versions */
   setVersionArchive(archive: VersionArchive): void {
     this.versionArchive = archive;
   }
 
-  private static readonly GITHUB_TARBALL_URL = 'https://github.com/vilmire/adhdev-providers/archive/refs/heads/main.tar.gz';
-  private static readonly REGISTRY_BASE_URL = 'https://api.adhf.dev/api/v1/registry';
   private static readonly META_FILE = '.meta.json';
   private static readonly REGISTRY_META_FILE = '.registry-meta.json';
   private static readonly REPO_PROVIDER_DIRNAME = 'adhdev-providers';
@@ -278,9 +289,21 @@ export class ProviderLoader {
      * probing; production code should leave this unset.
      */
     probeStarts?: string[];
+    /**
+     * Explicit provider registry base URL override (config.registryUrl).
+     * Highest-priority resolver source, ahead of ADHDEV_REGISTRY_URL + default.
+     */
+    registryUrl?: string;
+    /**
+     * Explicit provider tarball URL override (config.providerTarballUrl).
+     * Highest-priority resolver source, ahead of ADHDEV_PROVIDER_TARBALL_URL + default.
+     */
+    providerTarballUrl?: string;
   }) {
     this.logFn = options?.logFn || LOG.forComponent('Provider').asLogFn();
     this.probeStarts = options?.probeStarts ?? [process.cwd(), __dirname];
+    this.registryBaseUrl = resolveRegistryBaseUrl(options?.registryUrl);
+    this.providerTarballUrl = resolveProviderTarballUrl(options?.providerTarballUrl);
 
     // Default directory for auto-downloads
     this.defaultProvidersDir = path.join(os.homedir(), '.adhdev', 'providers');
@@ -1554,7 +1577,7 @@ export class ProviderLoader {
       this.log('Registry sync skipped (sourceMode=no-upstream)');
       return { updated: false };
     }
-    this.log(`Registry sync starting (${ProviderLoader.REGISTRY_BASE_URL})...`);
+    this.log(`Registry sync starting (${this.registryBaseUrl})...`);
 
     const https = require('https') as typeof import('https');
     const regMetaPath = path.join(this.upstreamDir, ProviderLoader.REGISTRY_META_FILE);
@@ -1569,7 +1592,7 @@ export class ProviderLoader {
 
     try {
       // 1. Fetch provider list
-      const listUrl = `${ProviderLoader.REGISTRY_BASE_URL}/providers`;
+      const listUrl = `${this.registryBaseUrl}/providers`;
       const listBody = await new Promise<string>((resolve, reject) => {
         const req = https.get(listUrl, { headers: { 'User-Agent': 'adhdev-daemon', 'Accept': 'application/json' }, timeout: 10000 }, (res) => {
           if (res.statusCode !== 200) { reject(new Error(`registry list HTTP ${res.statusCode}`)); return; }
@@ -1592,7 +1615,7 @@ export class ProviderLoader {
         if (cachedChecksums[cacheKey] === checksum) continue; // already current
 
         // Download this provider's manifest
-        const dlUrl = `${ProviderLoader.REGISTRY_BASE_URL}/providers/${type}/${version}/download`;
+        const dlUrl = `${this.registryBaseUrl}/providers/${type}/${version}/download`;
         const manifestBody = await new Promise<string>((resolve, reject) => {
           const req = https.get(dlUrl, { headers: { 'User-Agent': 'adhdev-daemon', 'Accept': 'application/json' }, timeout: 30000 }, (res) => {
             if (res.statusCode !== 200) { reject(new Error(`registry download HTTP ${res.statusCode} for ${type}@${version}`)); return; }
@@ -1667,13 +1690,17 @@ export class ProviderLoader {
       return { updated: false };
     }
 
+    // Resolve the tarball target (config → env → vendor default) once so the
+    // HEAD probe and the download below hit the same (possibly self-hosted) URL.
+    const tarballTarget = resolveProviderTarballTarget(this.providerTarballUrl);
+
     try {
  // Step 1: HEAD request to check ETag
       const etag = await new Promise<string>((resolve, reject) => {
         const options = {
           method: 'HEAD',
-          hostname: 'github.com',
-          path: '/vilmire/adhdev-providers/archive/refs/heads/main.tar.gz',
+          hostname: tarballTarget.hostname,
+          path: tarballTarget.path,
           headers: { 'User-Agent': 'adhdev-launcher' },
           timeout: 10000,
         };
@@ -1718,7 +1745,7 @@ export class ProviderLoader {
       const tmpExtract = path.join(os.tmpdir(), `adhdev-providers-extract-${Date.now()}`);
 
  // Download tarball
-      await this.downloadFile(ProviderLoader.GITHUB_TARBALL_URL, tmpTar);
+      await this.downloadFile(tarballTarget.url, tmpTar);
 
  // Extract
       fs.mkdirSync(tmpExtract, { recursive: true });
@@ -1825,7 +1852,7 @@ export class ProviderLoader {
         etag,
         timestamp,
         lastCheck: new Date(timestamp).toISOString(),
-        source: ProviderLoader.GITHUB_TARBALL_URL,
+        source: this.providerTarballUrl,
       }, null, 2));
     } catch { }
   }

package/src/providers/spec/fsm-driver.ts

@@ -38,6 +38,8 @@ import { loadFsmSpec } from './fsm-loader.js';
 import { applyPreLaunchTrust } from './pre-launch-trust.js';
 import type { Control, DelegateTrigger } from './types.js';
 import { LOG } from '../../logging/logger.js';
+import { recordDebugTrace } from '../../logging/debug-trace.js';
+import { shouldCollectTraceCategory } from '../../logging/debug-config.js';
 import {
     WIN32_PTY_WRITE_CHUNK_CHARS,
     WIN32_PTY_WRITE_CHUNK_GAP_MS,
@@ -300,6 +302,11 @@ export class FsmDriver implements ISpecDriver {
      *  (−1 = whole screen), or a `section:<id>` / `<region>#ignore:<pat>` string
      *  when the clause scopes to a section or declares an ignore_lines filter. */
     private regionLastChangedAt = new Map<number | string, number>();
+    /** COMPLETION-EARLYNOTIFY stable-eval trace: last stable/not-stable verdict
+     *  recorded per stable region, so the trace fires only when the verdict FLIPS
+     *  (not every quiet frame). Cleared on every transition alongside
+     *  regionLastChangedAt. Diagnostic-only — never consulted by the FSM. */
+    private stableVerdictCache = new Map<number | string, boolean>();
     /** Timer that re-runs evaluate() when a time-condition would flip true
      *  with no PTY frame to trigger it. */
     private wakeTimer: ReturnType<typeof setTimeout> | null = null;
@@ -684,6 +691,7 @@ export class FsmDriver implements ISpecDriver {
         // Region change timestamps are relative to the previous state's
         // activity; reset so stable_ms in the new state measures from entry.
         this.regionLastChangedAt.clear();
+        this.stableVerdictCache.clear();
         this.pushHistory(fired.to, stateById(this.spec, fired.to)?.label ?? fired.to, {
             reason: 'transition',
             via: `${from}→${fired.to}`,
@@ -818,6 +826,13 @@ export class FsmDriver implements ISpecDriver {
     private trackRegionChanges(currentLines: string[], cursor: { row: number; col: number }, now: number): void {
         if (this.prevScreenLines.length === 0) return;
         const descs = this.stableRegionDescriptors();
+        // COMPLETION-EARLYNOTIFY hook 4: record the stable/not-stable verdict for each
+        // tracked region, but ONLY when the verdict flips (see stableVerdictCache) so a
+        // quiet screen does not spam the ring buffer. This is the case-b diagnostic — an
+        // ignore_lines-scoped stable clause declaring a tool-execution screen "stable-idle"
+        // shows up here as verdict:true with a short fingerprint. Payload carries lengths
+        // and the pattern SOURCE only — never screen text.
+        const stableTraceOn = shouldCollectTraceCategory('fsm-transition');
         // Section ranges depend on screen content, so resolve per-frame for both
         // frames — but only when some tracked region is actually section-scoped.
         const needsSections = descs.some(d => !!d.section);
@@ -839,6 +854,28 @@ export class FsmDriver implements ISpecDriver {
             const cur = filterIgnoredLines(curLines, d.ignoreRe).join('\n');
             const prev = filterIgnoredLines(prevLines, d.ignoreRe).join('\n');
             if (cur !== prev) this.regionLastChangedAt.set(d.key, now);
+            if (stableTraceOn && typeof d.holdMs === 'number') {
+                const lastChanged = this.regionLastChangedAt.get(d.key) ?? this.stateEnteredAt;
+                const ageMs = now - lastChanged;
+                const verdict = ageMs >= d.holdMs;
+                if (this.stableVerdictCache.get(d.key) !== verdict) {
+                    this.stableVerdictCache.set(d.key, verdict);
+                    recordDebugTrace({
+                        category: 'fsm-transition',
+                        stage: 'stable-eval',
+                        level: 'debug',
+                        payload: {
+                            state: this.currentStateId,
+                            regionKey: String(d.key),
+                            ignorePattern: d.ignoreRe?.source ?? null,
+                            fingerprintLen: cur.length,
+                            ageMs,
+                            holdMs: d.holdMs,
+                            verdict,
+                        },
+                    });
+                }
+            }
         }
     }
 
@@ -1440,6 +1477,11 @@ interface StableRegionDescriptor {
     section?: string;
     cursor_above?: number;
     ignoreRe?: RegExp;
+    /** The stable_ms threshold the FIRST clause on this region declares. Used
+     *  only by the COMPLETION-EARLYNOTIFY stable-eval trace to report the
+     *  stable/not-stable verdict; the FSM decision itself is owned by the
+     *  evaluator against the live clause. */
+    holdMs?: number;
 }
 
 function collectStableDescriptors(when: FsmTransition['when'], byKey: Map<number | string, StableRegionDescriptor>): void {
@@ -1447,14 +1489,19 @@ function collectStableDescriptors(when: FsmTransition['when'], byKey: Map<number
     const w = when as any;
     if ('stable_ms' in w) {
         const key = stableRegionKey(w);
-        if (!byKey.has(key)) {
+        const existing = byKey.get(key);
+        if (!existing) {
             let ignoreRe: RegExp | undefined;
             if (w.ignore_lines) {
                 // Compile once here; a bad pattern is validated at load time, so
                 // this is best-effort and simply skips the filter if it throws.
                 try { ignoreRe = new RegExp(w.ignore_lines, 'm'); } catch { /* validated at load */ }
             }
-            byKey.set(key, { key, section: w.section, cursor_above: w.cursor_above, ignoreRe });
+            byKey.set(key, { key, section: w.section, cursor_above: w.cursor_above, ignoreRe, holdMs: typeof w.stable_ms === 'number' ? w.stable_ms : undefined });
+        } else if (existing.holdMs === undefined && typeof w.stable_ms === 'number') {
+            // Enrich the -1 whole-screen seed (or an earlier clause) with a threshold
+            // so its verdict can be traced. Geometry/ignoreRe from the first set win.
+            existing.holdMs = w.stable_ms;
         }
         return;
     }