feat(desktop): proactive insights answer the question you are typing

.github/failure-classes/FC-model-optional-step-drops-owed-answer.json

@@ -0,0 +1,17 @@
+{
+  "schema_version": 1,
+  "id": "FC-model-optional-step-drops-owed-answer",
+  "status": "open",
+  "violated_contract": "When the client already holds deterministic evidence that the user asked a question \u2014 a validated user-authored-question fact \u2014 every stage between that evidence and the delivered answer must run mechanically. Leaving any stage to the model's discretion (whether to request the lookup, whether to weigh the anti-repetition list, whether to copy the citation ref) turns delivery into a coin flip: each stage individually complies most of the time, and the product still drops the answer most of the time because the stages multiply. Discretion belongs only to the stage that owns judgment \u2014 whether the retrieved content actually answers the question.",
+  "canonical_prevention": "ContextDirectorRetrievalHop.forcedLookupQuery makes retrieval mandatory when a validated user-question fact exists (the fact statement is the query, the evaluation runs once with retrieved context attached, and the recent-deliveries list is omitted mechanically); ContextFactWritePolicy.isUserAuthoredQuestion floors the fact class deterministically at write time; ContextDirectorRetrievalHop.impliedCitations attributes the citation when the message provably carries retrieved content. Content matching nothing retrieved still dies at the grounding veto.",
+  "canonical_prevention_artifact": [
+    "desktop/macos/Desktop/Tests/ContextProactivityRetrievalHopTests.swift",
+    "desktop/macos/Desktop/Tests/ContextFactWritePolicyTests.swift"
+  ],
+  "scope_hints": [
+    "desktop/macos/Desktop/Sources/ProactiveAssistants/**"
+  ],
+  "evidence_prs": [
+    11976
+  ]
+}

desktop/macos/Desktop/Sources/ProactiveAssistants/ContextBucketDirectorProbe.swift

@@ -88,18 +88,31 @@
         windowTitle: input.window,
         frameNumber: 0,
         captureTime: input.capturedAt)
-      let prompt = ContextProactivityPromptBuilder.directorStablePrompt(snapshot: snapshot)
-      let uncachedPrompt = ContextProactivityPromptBuilder.directorVolatilePrompt(
+      // A probe with retrieved items replays the *second* director call of a
+      // visit exactly as `performRetrievalHop` builds it: lookup instruction in
+      // the stable prompt, RETRIEVED CONTEXT section appended to the uncached
+      // suffix, and the lookup-enabled schema. Without them it stays the exact
+      // first-call replay it always was.
+      let retrievedSection =
+        input.retrieved.isEmpty
+        ? nil
+        : ContextDirectorRetrievalHop.promptSection(
+          query: input.lookupQuery, items: input.retrieved)
+      let allowLookup = retrievedSection != nil
+      let prompt = ContextProactivityPromptBuilder.directorStablePrompt(
+        snapshot: snapshot, allowLookup: allowLookup)
+      let volatilePrompt = ContextProactivityPromptBuilder.directorVolatilePrompt(
         tasks: input.tasks, frame: frame, recentDeliveries: input.recentDeliveries,
         visitCount: input.visitCount)
+      let uncachedPrompt = retrievedSection.map { volatilePrompt + "\n\n" + $0 } ?? volatilePrompt
       let cacheKey = ContextPromptCacheKey.director
       let started = DispatchTime.now().uptimeNanoseconds
       let result = try await completion(
         ModelQoS.Proactivity.reasoningOperation,
         prompt,
         uncachedPrompt,
         nil,
-        ContextProactivityEngine.schema,
+        ContextProactivityEngine.schema(allowLookup: allowLookup),
         cacheKey,
         800,
         nil)
@@ -115,16 +128,69 @@
         throw ContextBucketDirectorProbeError.invalidModelResponse
       }
 
-      return [
+      let citedRefs = ContextDirectorRetrievalHop.partitionCitedRefs(decision.bucketEntryRefs)
+      let validRetrieved = ContextDirectorRetrievalHop.validatedRetrievedRefs(
+        citedRefs.retrieved, allowed: Set(input.retrieved.map(\.ref)))
+      // The engine validates citations against the store; the probe has no
+      // store, so a citation validates only when it appears verbatim in the
+      // supplied snapshot text — the same "cite only supplied refs" rule.
+      let suppliedText = ([input.frozen] + input.tail + input.validatedFacts).joined(separator: "\n")
+      let validBucketRefs = citedRefs.bucket.filter { suppliedText.contains($0) }
+      let validFactIDs = decision.factIDs.filter { suppliedText.contains($0) }
+      // The real grounding guard runs on the replayed decision, so a probe run
+      // exercises model -> citation validation -> grounding veto exactly as the
+      // engine chains them.
+      let groundingPermits =
+        decision.decision == "silence"
+        ? false
+        : ContextDirectorGrounding.permitsNonSilence(
+          decision: decision.decision, entryRefs: validBucketRefs, factIDs: validFactIDs,
+          retrievedRefs: validRetrieved)
+      var output = [
         "decision": String(decision.decision.prefix(32)),
         "title": decision.title,
         "message": decision.message,
         "reasoning": decision.reasoning,
-        "bucket_entry_ref_count": "\(decision.bucketEntryRefs.count)",
+        "bucket_entry_ref_count": "\(citedRefs.bucket.count)",
         "fact_ref_count": "\(decision.factIDs.count)",
+        "retrieved_ref_count": "\(validRetrieved.count)",
+        "lookup_query": decision.lookupQuery ?? "",
+        "grounding_permits": groundingPermits ? "true" : "false",
         "model": ContextProactivityTelemetry.boundedProviderModel(result.providerModel),
         "latency_ms": "\(max(0, latencyMs))",
       ]
+      // present=1 continues a grounding-permitted decision into the real
+      // presentation gate stack, completing the model -> grounding ->
+      // presentation chain the engine runs for an organic delivery.
+      if input.present {
+        guard groundingPermits else {
+          output["presentation"] = "not_attempted_grounding_veto_or_silence"
+          return output
+        }
+        let title = decision.title
+        let message = decision.message
+        let decisionType = decision.decision
+        let refDetail = (validBucketRefs + validRetrieved).joined(separator: ", ")
+        output["presentation"] = await MainActor.run {
+          guard let ownerID = RuntimeOwnerIdentity.currentOwnerId(), !ownerID.isEmpty else {
+            return "no_owner"
+          }
+          let context = FloatingBarNotificationContext(
+            sourceTitle: title,
+            assistantId: "context-director",
+            contextSummary: "probe replay",
+            detail: refDetail,
+            provenanceRef: "probe-present")
+          let presentation = NotificationService.shared.presentContextDirectorNotification(
+            ownerID: ownerID,
+            title: title,
+            message: message,
+            decisionType: decisionType,
+            context: context)
+          return "\(presentation)"
+        }
+      }
+      return output
     }
 
     private struct Input {
@@ -145,6 +211,15 @@
       /// Optional. Lets a probe exercise the recent-delivery prompt section, which is
       /// otherwise only reachable from the live ledger.
       let recentDeliveries: [ContextBucketRecentDelivery]
+      /// Optional. Non-empty turns the replay into the visit's *second* director
+      /// call, with these items quoted in a RETRIEVED CONTEXT section.
+      let retrieved: [ContextRetrievedItem]
+      /// Optional. The lookup query echoed into the retrieved section; ignored
+      /// when `retrieved` is empty.
+      let lookupQuery: String
+      /// Optional. "1" continues a grounding-permitted decision into the real
+      /// presentation gate stack.
+      let present: Bool
 
       init(params: [String: String]) throws {
         bucketID = try Self.requiredString(params, key: "bucket_id", maxLength: 200)
@@ -183,6 +258,40 @@
         recentDeliveries = try Self.optionalRecentDeliveryList(
           params, key: "recent_deliveries",
           maxCount: ContextBucketRecentDelivery.promptCap)
+        retrieved = try Self.optionalRetrievedList(
+          params, key: "retrieved",
+          maxCount: ContextDirectorRetrievalHop.maximumPromptItems)
+        lookupQuery = params["lookup_query"].map { String($0.prefix(200)) } ?? ""
+        present = params["present"] == "1"
+      }
+
+      /// Absent means "first-call replay", so existing probe callers keep their
+      /// exact prompt, schema, and behaviour.
+      private static func optionalRetrievedList(
+        _ params: [String: String],
+        key: String,
+        maxCount: Int
+      ) throws -> [ContextRetrievedItem] {
+        guard let raw = params[key], !raw.isEmpty else { return [] }
+        guard let data = raw.data(using: .utf8),
+          let values = try? JSONSerialization.jsonObject(with: data) as? [[String: Any]],
+          values.count <= maxCount
+        else {
+          throw ContextBucketDirectorProbeError.invalidParams(key)
+        }
+        return try values.map { value in
+          guard let ref = value["ref"] as? String, !ref.isEmpty, ref.count <= 200,
+            let preview = value["preview"] as? String, !preview.isEmpty, preview.count <= 2_400
+          else {
+            throw ContextBucketDirectorProbeError.invalidParams(key)
+          }
+          let title = (value["title"] as? String) ?? ""
+          let createdAt = value["created_at"] as? String
+          guard title.count <= 400, (createdAt?.count ?? 0) <= 40 else {
+            throw ContextBucketDirectorProbeError.invalidParams(key)
+          }
+          return ContextRetrievedItem(ref: ref, title: title, preview: preview, createdAt: createdAt)
+        }
       }
 
       /// Absent means "no recent deliveries", so existing probe callers keep their behaviour.

desktop/macos/Desktop/Sources/ProactiveAssistants/ContextBucketDirectorProbeRegistration.swift

@@ -5,16 +5,18 @@
     func registerContextBucketDirectorProbe() {
       register(
         name: "probe_context_bucket_director",
-        summary: "Replay a synthetic context bucket through the director model boundary without delivery",
+        summary:
+          "Replay a synthetic context bucket through the director model boundary; present=1 continues a grounding-permitted decision into the real presentation gate stack",
         params: [
           "bucket_id", "version", "header", "frozen", "tail", "validated_facts", "tasks", "app", "window",
-          "captured_at", "notify_worthiness", "visit_count",
+          "captured_at", "notify_worthiness", "visit_count", "retrieved", "lookup_query", "present",
         ],
         safety: "network_or_model",
         sideEffects: [
           "may call model/backend services",
           "eligible replays consume the signed-in account's proactivity reasoning quota",
-          "does not write the database, change gates/settings, graduate tasks, or deliver notifications",
+          "does not write the database, change gates/settings, or graduate tasks",
+          "present=1 shows a real notification, subject to the same owner/toggle/throttle gates as an organic delivery; without it nothing is delivered",
         ]
       ) { params in
         guard AppBuild.isNonProduction else {

desktop/macos/Desktop/Sources/ProactiveAssistants/Core/AssistantCoordinator.swift

@@ -237,6 +237,52 @@ class AssistantCoordinator {
     return true
   }
 
+  /// Content-refresh transition for a long dwell whose on-screen content
+  /// changed (see `ContextDwellRefreshPolicy`): closes and reopens the ACTIVE
+  /// context through the ordinary visit machinery, so the departing frame —
+  /// which now contains what the user typed — gets extraction, departure
+  /// evaluation, and the fresh visit gets its normal entry evaluation. Every
+  /// quota, cooldown, dedup, and budget gate applies unchanged.
+  /// Returns the arriving visit's fence so the caller can capture a
+  /// post-entry frame BEFORE engaging the director: the entry evaluation only
+  /// grounds on frames captured at or after the visit began, and the
+  /// preview-skip path may not produce another full frame for a static screen.
+  func refreshActiveContextForDwell(
+    expectedApp: String, expectedWindowTitle: String?
+  ) async -> ContextVisitFence? {
+    guard ContextBucketsFeature.isEnabled else { return nil }
+    guard let app = lastTrackedApp, let frame = lastTrackedFrame else { return nil }
+    // The dwell task is detached from its tick: if the user switched contexts
+    // while it awaited, refreshing would close the just-opened visit and
+    // extract the OLD context's frame into the NEW context's bucket.
+    guard app == expectedApp,
+      ContextDetection.normalizeWindowTitle(lastTrackedWindowTitle)
+        == ContextDetection.normalizeWindowTitle(expectedWindowTitle)
+    else { return nil }
+    guard !RewindSettings.shared.isAppExcluded(app) else { return nil }
+    // A refused same-context refresh must be DROPPED, not queued: begin()
+    // stores a refused request as pending, and finishContextTransition would
+    // replay it as a phantom switch back to this context after the in-flight
+    // real transition completes.
+    guard contextTransitionQueue.inFlight == nil else { return nil }
+    let request = ContextTransitionRequest(app: app, windowTitle: lastTrackedWindowTitle)
+    guard contextTransitionQueue.begin(request) else { return nil }
+    defer { finishContextTransition(request) }
+    do {
+      let transition = try await ContextVisitCoordinator.shared.transition(
+        toApp: app,
+        windowTitle: lastTrackedWindowTitle,
+        departingFrame: frame)
+      if transition.departingQualified, let departingFence = transition.departingFence {
+        Task { await ContextBucketRollupWriter.shared.extract(frame: frame, fence: departingFence) }
+      }
+      return transition.arrivingFence
+    } catch {
+      logError("Context buckets: content-refresh transition failed", error: error)
+      return nil
+    }
+  }
+
   /// Releases a completed transition and schedules the latest context observed
   /// during its persistence await. The follow-up runs on the main actor, so it
   /// cannot race the coordinator's tracked state or start a second write in
@@ -274,6 +320,20 @@ class AssistantCoordinator {
 
   // MARK: - Frame Tracking & Distribution
 
+  /// The app of the context currently tracked for switches; the dwell task
+  /// uses it to drop stale captures after an app switch.
+  var currentTrackedApp: String? { lastTrackedApp }
+
+  /// Whether the tracker still points at this exact context. The dwell task
+  /// guards every capture with it: an app-only check let a same-app tab/title
+  /// switch during the async capture overwrite the tracked frame with the
+  /// departed window's pixels, contaminating the active bucket.
+  func isTracking(app: String, windowTitle: String?) -> Bool {
+    lastTrackedApp == app
+      && ContextDetection.normalizeWindowTitle(lastTrackedWindowTitle)
+        == ContextDetection.normalizeWindowTitle(windowTitle)
+  }
+
   /// Keep the latest frame reference fresh (call on every capture, even during delay).
   func trackFrame(_ frame: CapturedFrame) {
     lastTrackedFrame = frame

desktop/macos/Desktop/Sources/ProactiveAssistants/Core/AsyncFirstResolved.swift

@@ -0,0 +1,31 @@
+import Foundation
+import os
+
+/// First-result-wins race for awaits that may never return.
+///
+/// `withTaskGroup` cannot bound a non-cooperative child: leaving the group
+/// awaits every child, cancelled or not, so a stalled cancellation-insensitive
+/// call (SCShareableContent resolution is one) blocks the caller indefinitely.
+/// This race resumes on whichever branch finishes first and ABANDONS the
+/// other — the loser keeps running in the background and its result is
+/// dropped. Use only where an orphaned straggler is acceptable.
+enum AsyncFirstResolved {
+  static func run<T: Sendable>(
+    _ a: @escaping @Sendable () async -> T?,
+    _ b: @escaping @Sendable () async -> T?
+  ) async -> T? {
+    let resumed = OSAllocatedUnfairLock(initialState: false)
+    return await withCheckedContinuation { continuation in
+      let finish: @Sendable (T?) -> Void = { value in
+        let first = resumed.withLock { state -> Bool in
+          if state { return false }
+          state = true
+          return true
+        }
+        if first { continuation.resume(returning: value) }
+      }
+      Task { finish(await a()) }
+      Task { finish(await b()) }
+    }
+  }
+}