pi-fluency 0.1.3 → 0.2.0

package/extensions/pi-fluency/index.ts

@@ -8,18 +8,47 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import { Key } from "@earendil-works/pi-tui";
 import { AnalyzerConfigurationError, ModelAnalyzer, type Analyzer } from "./analyzer.js";
-import { computeFluencyAnalytics } from "./analytics.js";
+import { computeFluencyAnalytics, resolvePracticeTargets, selectPracticeAnalysisContext } from "./analytics.js";
 import { collectPrompt } from "./collector.js";
+import {
+  showCoachingOverlay,
+  type CoachingCheckResult,
+  type CoachingOverlayDecision,
+  type CoachingSnoozeDecision,
+  type CoachingSnoozeHandler,
+} from "./coaching-overlay.js";
+import {
+  analysisReuseAction,
+  analyzerResultFingerprint,
+  isCoachingEligible,
+  revalidateCoachingPolicy,
+  selectedCoachingMistakes,
+} from "./coaching.js";
 import { showFluencyOverlay, type FluencyView } from "./overlay.js";
+import { PracticeSessionSnooze } from "./practice-settings.js";
 import { sanitizeTerminalLabel } from "./sanitize.js";
 import { runSetup } from "./setup.js";
 import { formatStatus, type StatusErrorReason, type StatusState } from "./status.js";
-import { FluencyStore } from "./store.js";
-import type { FluencySettings } from "./types.js";
-import { FluencyWorker } from "./worker.js";
+import { FluencyStore, type AnalysisCommitFence } from "./store.js";
+import type { FluencySettings, PracticeSettings } from "./types.js";
+import { FluencyWorker, type ForegroundAnalysisOutcome } from "./worker.js";
 
 const STATUS_KEY = "pi-fluency";
-const USAGE = "Usage: /fluency [pause|resume|status|model|clear|stats]";
+const USAGE = "Usage: /fluency [pause|resume|status|model|clear|stats|practice [on|off|resume|reset]]";
+const PRACTICE_DISCLOSURE = "Before main submission, full sanitized draft goes to configured Fluency model and may be analyzed even if you later choose not to send it.";
+const PRACTICE_CHECK_TIMEOUT_MS = 30_000;
+const PRACTICE_CHECK_ABORT_GRACE_MS = 100;
+
+function practiceFailureMessage(kind: Exclude<ForegroundAnalysisOutcome["kind"], "success">): string {
+  switch (kind) {
+    case "busy": return "Sent without practice check — analyzer was busy for 30 seconds.";
+    case "timeout": return "Sent without practice check — analyzer timed out after 30 seconds.";
+    case "error": return "Sent without practice check — analyzer failed.";
+    case "shutdown": return "Sent without practice check — analyzer stopped during reload or shutdown.";
+    case "quarantined": return "Sent without practice check — analyzer unavailable; restart Pi to restore practice.";
+    case "cancelled": return "Sent without practice check — practice settings changed.";
+  }
+}
 
 export interface OpenInboxOptions {
   signal: AbortSignal;
@@ -35,11 +64,20 @@ export type OpenInbox = (
   options: OpenInboxOptions,
 ) => Promise<void> | void;
 
+export type ShowCoaching = (
+  ctx: ExtensionContext,
+  check: Promise<CoachingCheckResult>,
+  signal?: AbortSignal,
+  saveSnooze?: CoachingSnoozeHandler,
+) => Promise<CoachingOverlayDecision>;
+
 export interface ExtensionDependencies {
   rootDir?: string;
-  analyzerFactory?: (ctx: ExtensionContext, store: FluencyStore) => Analyzer;
+  analyzerFactory?: (ctx: ExtensionContext, store: FluencyStore, settings?: FluencySettings) => Analyzer;
   now?: () => number;
+  openStore?: (rootDir: string) => Promise<FluencyStore>;
   openInbox?: OpenInbox;
+  showCoaching?: ShowCoaching;
 }
 
 interface ResolvedDependencies extends ExtensionDependencies {
@@ -63,6 +101,27 @@ function hasValidConfiguration(settings: FluencySettings, ctx: ExtensionContext)
   return ctx.modelRegistry.find(settings.provider!, settings.modelId!) !== undefined;
 }
 
+function fenceFromPolicy(policy: { settings: FluencySettings; historyGeneration: string }): AnalysisCommitFence {
+  const settings = policy.settings;
+  return {
+    historyGeneration: policy.historyGeneration,
+    enabled: settings.enabled,
+    minimumConfidence: settings.minimumConfidence,
+    ...(settings.consentedAt === undefined ? {} : { consentedAt: settings.consentedAt }),
+    ...(settings.provider === undefined ? {} : { provider: settings.provider }),
+    ...(settings.modelId === undefined ? {} : { modelId: settings.modelId }),
+  };
+}
+
+function sameAnalysisFence(left: AnalysisCommitFence, right: AnalysisCommitFence): boolean {
+  return left.historyGeneration === right.historyGeneration
+    && left.enabled === right.enabled
+    && left.consentedAt === right.consentedAt
+    && left.provider === right.provider
+    && left.modelId === right.modelId
+    && left.minimumConfidence === right.minimumConfidence;
+}
+
 function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies): void {
   let storeRef: FluencyStore | undefined;
   let storePromise: Promise<FluencyStore> | undefined;
@@ -75,6 +134,26 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
   const notifiedErrors = new Set<string>();
   const inputSessionId = randomUUID();
   let inputSequence = 0;
+  const practiceSessionSnooze = new PracticeSessionSnooze();
+  const coachingControllers = new Set<AbortController>();
+  const scheduledCommits = new Set<Promise<void>>();
+
+  const sessionFile = (ctx: ExtensionContext): string | undefined =>
+    ctx.sessionManager?.getSessionFile?.();
+  const sessionEntries = (ctx: ExtensionContext) => ctx.sessionManager?.getEntries?.() ?? [];
+  const isSessionPracticeSnoozed = (
+    ctx: ExtensionContext,
+    store: FluencyStore,
+    practice: PracticeSettings = store.getPracticeSettings(),
+  ): boolean => practiceSessionSnooze.restore(sessionEntries(ctx), sessionFile(ctx), practice.epoch);
+  const resumeSessionPractice = (ctx: ExtensionContext, store: FluencyStore): void => {
+    const practice = store.getPracticeSettings();
+    practiceSessionSnooze.resume(
+      sessionFile(ctx),
+      practice.epoch,
+      (customType, data) => pi.appendEntry(customType, data),
+    );
+  };
 
   const publishStatus = (ctx: ExtensionContext, state: StatusState): void => {
     const text = formatStatus(state);
@@ -139,13 +218,36 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
   };
 
   const getStore = async (): Promise<FluencyStore> => {
-    storePromise ??= FluencyStore.open(dependencies.rootDir).then((store) => {
-      storeRef = store;
-      return store;
-    });
+    storePromise ??= (dependencies.openStore?.(dependencies.rootDir) ?? FluencyStore.open(dependencies.rootDir))
+      .then((store) => {
+        if (!shuttingDown) storeRef = store;
+        return store;
+      });
     return storePromise;
   };
 
+  const getStoreBefore = async (deadline: number): Promise<FluencyStore> => {
+    const acquisition = getStore().then(
+      (store) => ({ kind: "store" as const, store }),
+      () => ({ kind: "error" as const }),
+    );
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw new Error("Store acquisition deadline exceeded");
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const result = await Promise.race([
+        acquisition,
+        new Promise<{ kind: "deadline" }>((resolve) => {
+          timer = setTimeout(() => resolve({ kind: "deadline" }), remaining);
+        }),
+      ]);
+      if (result.kind === "store") return result.store;
+      throw new Error(result.kind === "error" ? "Store acquisition failed" : "Store acquisition deadline exceeded");
+    } finally {
+      if (timer !== undefined) clearTimeout(timer);
+    }
+  };
+
   const analyzerErrorReason = (error: unknown): StatusErrorReason => {
     if (!(error instanceof AnalyzerConfigurationError)) return "analyze";
     return /auth|api[- ]?key|credential|token/i.test(error.message) ? "auth" : "model";
@@ -161,9 +263,12 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
     }
   };
 
-  const createAnalyzer = (ctx: ExtensionContext, store: FluencyStore): Analyzer => {
-    if (dependencies.analyzerFactory) return dependencies.analyzerFactory(ctx, store);
-    const settings = store.getSettings();
+  const createAnalyzer = (
+    ctx: ExtensionContext,
+    store: FluencyStore,
+    settings: FluencySettings = store.getSettings(),
+  ): Analyzer => {
+    if (dependencies.analyzerFactory) return dependencies.analyzerFactory(ctx, store, settings);
     const model = settings.provider && settings.modelId
       ? ctx.modelRegistry.find(settings.provider, settings.modelId)
       : undefined;
@@ -179,11 +284,24 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
     ctxRef = ctx;
     workerRef ??= new FluencyWorker({
       analyzer: createAnalyzer(ctx, store),
+      getAnalyzerConfiguration: async (job) => {
+        if (job.fence === undefined) return undefined;
+        const currentCtx = ctxRef ?? ctx;
+        const fresh = await store.getFreshPolicySnapshot(Date.now() + 1_000);
+        const freshFence = fenceFromPolicy(fresh);
+        if (!sameAnalysisFence(job.fence, freshFence) || !hasConfiguredIdentity(fresh.settings)) return undefined;
+        return {
+          fingerprint: analyzerResultFingerprint(fresh.settings),
+          analyzer: createAnalyzer(currentCtx, store, fresh.settings),
+        };
+      },
       isIdle: () => ctxRef?.isIdle() ?? false,
       getPatterns: () => store.listKnownPatterns(),
-      onResult: async (prompt, result) => {
+      onResult: async (prompt, result, fence) => {
+        if (fence === undefined) return;
         try {
-          await store.appendAnalysis(prompt, result);
+          const committed = await store.conditionalAppendAnalysis(fence, prompt, result);
+          if (committed !== "committed") return;
         } catch (error) {
           if (ctxRef) setError(ctxRef, "store", error);
           return;
@@ -242,6 +360,10 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
           onMutationError,
           initialView,
           dependencies.now,
+          {
+            sessionSnoozed: () => isSessionPracticeSnoozed(ctx, store),
+            resumeSession: () => resumeSessionPractice(ctx, store),
+          },
         ),
     );
     overlayOpen = current;
@@ -288,6 +410,44 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
       await openInbox(ctx, store, "stats");
       return;
     }
+    if (action === "practice") {
+      await openInbox(ctx, store, "stats");
+      return;
+    }
+    if (action === "practice on") {
+      const practice = store.getPracticeSettings();
+      if (practice.consentedAt === undefined) {
+        const confirmed = await ctx.ui.confirm("Enable Pi Fluency practice?", PRACTICE_DISCLOSURE);
+        if (!confirmed) {
+          ctx.ui.notify("Pi Fluency practice unchanged", "info");
+          return;
+        }
+        await store.activatePractice(dependencies.now());
+      } else {
+        await store.setPracticeEnabled(true);
+      }
+      ctx.ui.notify("Pi Fluency practice enabled", "info");
+      return;
+    }
+    if (action === "practice off") {
+      await store.setPracticeEnabled(false);
+      ctx.ui.notify("Pi Fluency practice disabled", "info");
+      return;
+    }
+    if (action === "practice resume") {
+      // Mutation rereads sidecar under global lock, so stale process cache cannot miss durable snooze.
+      await store.resumePractice();
+      if (isSessionPracticeSnoozed(ctx, store)) resumeSessionPractice(ctx, store);
+      ctx.ui.notify("Pi Fluency practice resumed now", "info");
+      return;
+    }
+    if (action === "practice reset") {
+      if (await ctx.ui.confirm("Reset Pi Fluency practice?", "This clears practice targets, consent, mode, and snoozes. Fluency history stays unchanged.")) {
+        await store.resetPractice();
+        ctx.ui.notify("Pi Fluency practice reset", "info");
+      }
+      return;
+    }
     if (action === "pause") {
       await store.updateSettings({ enabled: false });
       await workerRef?.shutdown();
@@ -320,9 +480,15 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
       const state = active
         ? "enabled"
         : settings.enabled ? "inactive (configuration invalid)" : "paused";
+      const practice = store.getPracticeSettings();
+      const globalSnoozed = (practice.snoozedUntil ?? 0) > dependencies.now();
+      const sessionSnoozed = isSessionPracticeSnoozed(ctx, store);
+      const practiceSnooze = globalSnoozed && sessionSnoozed
+        ? "session+5-hour"
+        : sessionSnoozed ? "session" : globalSnoozed ? "5-hour" : "none";
       if (!active) clearStatus(ctx);
       ctx.ui.notify(
-        `Pi Fluency: ${state}; model=${model}; queued=${snapshot.queued}; dropped=${snapshot.dropped}; warnings=${store.getWarnings().length}`,
+        `Pi Fluency: ${state}; model=${model}; queued=${snapshot.queued}; dropped=${snapshot.dropped}; warnings=${store.getWarnings().length}; practice=${practice.enabled ? "on" : "off"}; practice-selected=${practice.targets.length}; practice-snooze=${practiceSnooze}`,
         "info",
       );
       return;
@@ -369,14 +535,11 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
   });
 
   pi.on("input", async (event, ctx) => {
+    const handlerStartedAt = Date.now();
+    const foregroundDeadline = handlerStartedAt + PRACTICE_CHECK_TIMEOUT_MS;
+    const foregroundCoordinatorDeadline = foregroundDeadline - PRACTICE_CHECK_ABORT_GRACE_MS;
     if (shuttingDown || event.source !== "interactive") return;
     ctxRef = ctx;
-    const store = await getStore();
-    if (shuttingDown) return;
-    if (!hasValidConfiguration(store.getSettings(), ctx)) {
-      publishConfigurationFailureOrClear(ctx, store);
-      return;
-    }
     const collected = collectPrompt(event.text, dependencies.now());
     if (!collected) return;
     const prompt = {
@@ -385,12 +548,353 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
         .update(`${collected.promptHash}\0${inputSessionId}\0${inputSequence++}`)
         .digest("hex"),
     };
-    if (store.hasProcessedPromptHash(prompt.promptHash)) return;
+    const idleTextOnly = ctx.isIdle()
+      && event.streamingBehavior === undefined
+      && (event.images?.length ?? 0) === 0;
+
+    // Enter may already have emptied Pi's editor. Preserve received bytes before any preflight I/O.
+    if (idleTextOnly) {
+      try {
+        ctx.ui.setEditorText(event.text);
+      } catch {
+        // Original event still owns submission. Only ordinary background collection may follow.
+        try {
+          const fallbackStore = await getStoreBefore(foregroundDeadline);
+          const fresh = await fallbackStore.getFreshPolicySnapshot(foregroundDeadline);
+          if (!shuttingDown && hasValidConfiguration(fresh.settings, ctx)) {
+            getWorker(ctx, fallbackStore).enqueue(prompt, fenceFromPolicy(fresh));
+          }
+        } catch { /* Original input remains fail-open. */ }
+        return;
+      }
+    }
+
+    let store: FluencyStore;
     try {
-      getWorker(ctx, store).enqueue(prompt);
-    } catch (error) {
-      setError(ctx, analyzerErrorReason(error), error);
+      store = await getStoreBefore(foregroundDeadline);
+    } catch {
+      if (!idleTextOnly) return;
+      try {
+        ctx.ui.setEditorText("");
+        ctx.ui.notify("Sent without practice check — policy unavailable.", "warning");
+        return { action: "continue" };
+      } catch {
+        ctx.ui.notify("Not sent — editor could not be cleared.", "error");
+        return { action: "handled" };
+      }
+    }
+    if (shuttingDown) {
+      if (idleTextOnly) {
+        try { ctx.ui.setEditorText(""); } catch { return { action: "handled" }; }
+        return { action: "continue" };
+      }
+      return;
+    }
+    const queueBackground = (policy: { settings: FluencySettings; historyGeneration: string }): void => {
+      try {
+        getWorker(ctx, store).enqueue(prompt, fenceFromPolicy(policy));
+      } catch (error) {
+        setError(ctx, analyzerErrorReason(error), error);
+      }
+    };
+    let initialPolicy;
+    try {
+      initialPolicy = await store.getFreshPolicySnapshot(foregroundDeadline);
+    } catch {
+      if (!idleTextOnly) return;
+      try {
+        ctx.ui.setEditorText("");
+        ctx.ui.notify("Sent without practice check — policy unavailable.", "warning");
+        return { action: "continue" };
+      } catch {
+        ctx.ui.notify("Not sent — editor could not be cleared.", "error");
+        return { action: "handled" };
+      }
+    }
+    if (!hasValidConfiguration(initialPolicy.settings, ctx)) {
+      publishConfigurationFailureOrClear(ctx, store);
+      if (!idleTextOnly) return;
+      try { ctx.ui.setEditorText(""); } catch {
+        ctx.ui.notify("Not sent — editor could not be cleared.", "error");
+        return { action: "handled" };
+      }
+      return { action: "continue" };
+    }
+    if (store.hasProcessedPromptHash(prompt.promptHash)) {
+      if (!idleTextOnly) return;
+      try { ctx.ui.setEditorText(""); } catch { return { action: "handled" }; }
+      return { action: "continue" };
+    }
+    if (!idleTextOnly) {
+      queueBackground(initialPolicy);
+      return;
+    }
+    let backgroundAllowed = true;
+    let backgroundPolicy = initialPolicy;
+    const restoreInputStatus = (): void => {
+      if (shuttingDown || !backgroundAllowed) clearStatus(ctx);
+      else publishProgress(ctx, store);
+    };
+    const clearForContinue = (): boolean => {
+      try {
+        ctx.ui.setEditorText("");
+        return true;
+      } catch {
+        ctx.ui.notify("Not sent — editor could not be cleared.", "error");
+        restoreInputStatus();
+        return false;
+      }
+    };
+    const failOpen = (message: string): { action: "continue" } | { action: "handled" } => {
+      if (backgroundAllowed) queueBackground(backgroundPolicy);
+      if (!clearForContinue()) return { action: "handled" };
+      ctx.ui.notify(message, "warning");
+      restoreInputStatus();
+      return { action: "continue" };
+    };
+
+    const initialSessionSnoozed = isSessionPracticeSnoozed(ctx, store, initialPolicy.practice);
+    const hasActiveTarget = resolvePracticeTargets({
+      targets: initialPolicy.practice.targets,
+      patterns: store.listKnownPatterns(),
+      ignoredPatternKeys: new Set(initialPolicy.settings.ignoredPatternKeys),
+      ignoredCategories: new Set(initialPolicy.settings.ignoredCategories),
+    }).some((target) => target.coachingEnabled);
+    if (!hasValidConfiguration(initialPolicy.settings, ctx)
+      || !hasActiveTarget
+      || !isCoachingEligible({
+        source: event.source,
+        idle: true,
+        textOnly: true,
+        collectionEligible: true,
+        sessionSnoozed: initialSessionSnoozed,
+        now: dependencies.now(),
+        policy: initialPolicy,
+      })) {
+      if (!clearForContinue()) return { action: "handled" };
+      if (hasValidConfiguration(initialPolicy.settings, ctx)) queueBackground(initialPolicy);
+      return { action: "continue" };
+    }
+
+    const commitFence = fenceFromPolicy(initialPolicy);
+    publishStatus(ctx, { kind: "practice-check" });
+    const attemptController = new AbortController();
+    coachingControllers.add(attemptController);
+    let successfulResult: Awaited<ReturnType<Analyzer["analyze"]>> | undefined;
+    let checkPolicy = initialPolicy;
+    let checkSessionSnoozed = initialSessionSnoozed;
+    let analyzerChangeObserved = false;
+    let policyReadFailed = false;
+    let coachingUiFailed = false;
+    let technicalFailureMessage = practiceFailureMessage("error");
+    const checkPromise: Promise<CoachingCheckResult> = (async () => {
+      try {
+        const context = selectPracticeAnalysisContext(initialPolicy.practice.targets, store.listKnownPatterns());
+        const outcome = await getWorker(ctx, store).analyzeForeground({
+          analyzer: createAnalyzer(ctx, store, initialPolicy.settings),
+          prompt,
+          patterns: context.patterns,
+          selectedTargets: context.targetDescriptors,
+          deadline: foregroundCoordinatorDeadline,
+          signal: attemptController.signal,
+          abortGraceMs: PRACTICE_CHECK_ABORT_GRACE_MS,
+          authorize: async () => {
+            let fresh;
+            try {
+              fresh = await store.getFreshPolicySnapshot(foregroundCoordinatorDeadline, attemptController.signal);
+            } catch (error) {
+              policyReadFailed = true;
+              technicalFailureMessage = "Sent without practice check — policy unavailable.";
+              throw error;
+            }
+            const sessionSnoozed = isSessionPracticeSnoozed(ctx, store, fresh.practice);
+            checkPolicy = fresh;
+            checkSessionSnoozed = sessionSnoozed;
+            backgroundPolicy = fresh;
+            const revalidation = revalidateCoachingPolicy(
+              initialPolicy,
+              fresh,
+              initialSessionSnoozed,
+              sessionSnoozed,
+            );
+            if (revalidation === "analytics-disabled") backgroundAllowed = false;
+            return revalidation === "unchanged"
+              && isCoachingEligible({
+                source: event.source,
+                idle: true,
+                textOnly: true,
+                collectionEligible: true,
+                sessionSnoozed,
+                now: dependencies.now(),
+                policy: fresh,
+              });
+          },
+        });
+        if (outcome.kind !== "success") {
+          if (!policyReadFailed && !coachingUiFailed) technicalFailureMessage = practiceFailureMessage(outcome.kind);
+          return { kind: "failure" };
+        }
+        successfulResult = outcome.result;
+        try {
+          checkPolicy = await store.getFreshPolicySnapshot(foregroundDeadline, attemptController.signal);
+        } catch {
+          technicalFailureMessage = "Sent without practice check — policy unavailable.";
+          return { kind: "failure" };
+        }
+        checkSessionSnoozed = isSessionPracticeSnoozed(ctx, store, checkPolicy.practice);
+        backgroundPolicy = checkPolicy;
+        const revalidation = revalidateCoachingPolicy(
+          initialPolicy,
+          checkPolicy,
+          initialSessionSnoozed,
+          checkSessionSnoozed,
+        );
+        analyzerChangeObserved = revalidation === "analyzer-changed";
+        if (revalidation === "analytics-disabled"
+          || revalidation === "analyzer-changed"
+          || revalidation === "gate-changed") {
+          technicalFailureMessage = "Sent without practice check — practice settings changed.";
+          if (revalidation === "analytics-disabled") backgroundAllowed = false;
+          return { kind: "failure" };
+        }
+        const gateStillEligible = isCoachingEligible({
+          source: event.source,
+          idle: true,
+          textOnly: true,
+          collectionEligible: true,
+          sessionSnoozed: checkSessionSnoozed,
+          now: dependencies.now(),
+          policy: checkPolicy,
+        });
+        const matches = gateStillEligible
+          ? selectedCoachingMistakes(outcome.result, checkPolicy.settings, checkPolicy.practice)
+          : [];
+        return matches.length === 0
+          ? { kind: "clean" }
+          : { kind: "matches", mistakes: matches, targets: checkPolicy.practice.targets };
+      } catch {
+        return { kind: "failure" };
+      }
+    })();
+
+    let snoozePersisted = false;
+    const persistSnooze = async (action: CoachingSnoozeDecision): Promise<void> => {
+      snoozePersisted = true;
+      if (action === "snooze-session") {
+        try {
+          practiceSessionSnooze.snooze(
+            sessionFile(ctx),
+            checkPolicy.practice.epoch,
+            (customType, data) => pi.appendEntry(customType, data),
+          );
+        } catch {
+          ctx.ui.notify("Sent once; conversation snooze was not activated.", "warning");
+        }
+        return;
+      }
+      const operationDeadline = Date.now() + 1_000;
+      const mutation = store.snoozePracticeForFiveHours(
+        checkPolicy.practice.revision,
+        operationDeadline,
+        dependencies.now(),
+      ).then((activated) => ({ kind: "result" as const, activated }), () => ({ kind: "error" as const }));
+      const first = await Promise.race([
+        mutation,
+        new Promise<{ kind: "deadline" }>((resolve) => setTimeout(
+          () => resolve({ kind: "deadline" }),
+          Math.max(0, operationDeadline - Date.now()),
+        )),
+      ]);
+      if (first.kind === "result" && first.activated) return;
+
+      // Mutation and confirmation share one absolute second. Never manufacture a second deadline.
+      if (Date.now() < operationDeadline) {
+        try {
+          const authoritative = await store.getFreshPolicySnapshot(operationDeadline);
+          if ((authoritative.practice.snoozedUntil ?? 0) > dependencies.now()) return;
+          ctx.ui.notify("Sent once; 5-hour snooze was not activated.", "warning");
+          return;
+        } catch { /* Remaining deadline could not establish authoritative state. */ }
+      }
+      ctx.ui.notify("Sent once; snooze state unknown — use /fluency practice resume.", "warning");
+    };
+
+    let decision: CoachingOverlayDecision;
+    try {
+      decision = await (dependencies.showCoaching ?? showCoachingOverlay)(
+        ctx,
+        checkPromise,
+        attemptController.signal,
+        persistSnooze,
+      );
+    } catch {
+      coachingUiFailed = true;
+      decision = "technical-failure";
+    }
+    if (decision === "edit") {
+      attemptController.abort();
+      await checkPromise;
+      coachingControllers.delete(attemptController);
+      ctx.ui.notify("Not sent — draft remains in editor.", "info");
+      restoreInputStatus();
+      return { action: "handled" };
+    }
+    if (decision === "send-unchecked" || decision === "technical-failure") {
+      const shutdownInterrupted = shuttingDown;
+      attemptController.abort();
+      await checkPromise;
+      coachingControllers.delete(attemptController);
+      if (shutdownInterrupted || shuttingDown) {
+        backgroundAllowed = false;
+        return failOpen(practiceFailureMessage("shutdown"));
+      }
+      return failOpen(decision === "send-unchecked"
+        ? "Sent without practice check — analyzer cancelled."
+        : technicalFailureMessage);
+    }
+    coachingControllers.delete(attemptController);
+
+    if ((decision === "snooze-session" || decision === "snooze-five-hours") && !snoozePersisted) {
+      await persistSnooze(decision);
+    }
+
+    if (!clearForContinue()) return { action: "handled" };
+
+    if (successfulResult !== undefined) {
+      let finalPolicy = checkPolicy;
+      let finalSessionSnoozed = checkSessionSnoozed;
+      try {
+        finalPolicy = await store.getFreshPolicySnapshot(Date.now() + 1_000);
+        finalSessionSnoozed = isSessionPracticeSnoozed(ctx, store, finalPolicy.practice);
+        backgroundPolicy = finalPolicy;
+      } catch { /* Conditional store fence remains authoritative. */ }
+      const revalidation = revalidateCoachingPolicy(
+        initialPolicy,
+        finalPolicy,
+        initialSessionSnoozed,
+        finalSessionSnoozed,
+      );
+      const reuse = analysisReuseAction("continue", revalidation);
+      if (reuse === "commit-foreground") {
+        let tracked!: Promise<void>;
+        tracked = store.conditionalAppendAnalysis(commitFence, prompt, successfulResult)
+          .then((result) => {
+            if (result === "analyzer-stale" && !shuttingDown) queueBackground(backgroundPolicy);
+            else if (result === "committed" && !shuttingDown) publishProgress(ctx, store);
+          })
+          .catch((error) => {
+            if (!shuttingDown) setError(ctx, "store", error);
+          })
+          .finally(() => scheduledCommits.delete(tracked));
+        scheduledCommits.add(tracked);
+      } else if (reuse === "queue-background" || analyzerChangeObserved) {
+        queueBackground(backgroundPolicy);
+      }
+    } else {
+      queueBackground(backgroundPolicy);
     }
+    restoreInputStatus();
+    return { action: "continue" };
   });
 
   pi.on("agent_settled", (_event, ctx) => {
@@ -417,7 +921,14 @@ function registerHandlers(pi: ExtensionAPI, dependencies: ResolvedDependencies):
       const shutdownCtx = ctxRef;
       if (shutdownCtx) clearStatus(shutdownCtx);
       overlayController?.abort();
-      await Promise.all([workerRef?.shutdown(), overlayOpen]);
+      for (const controller of coachingControllers) controller.abort();
+      const commits = Promise.allSettled([...scheduledCommits]);
+      await Promise.all([
+        workerRef?.shutdown(),
+        overlayOpen,
+        Promise.race([commits, new Promise<void>((resolve) => setTimeout(resolve, 100))]),
+      ]);
+      coachingControllers.clear();
       if (shutdownCtx) clearStatus(shutdownCtx);
       workerRef = undefined;
       overlayOpen = undefined;