obsidian-vault/work/projects/cpm-web-extension-breakage-findings.md

---
title: CPM Web Extension Breakage Findings
date: '2026-09-08'
status: investigation
tags:
  - work
  - cpm
  - webkit
  - web-extension
---
# CPM Web Extension Breakage Findings

> Investigation summary as of 2026-09-08. This note distinguishes confirmed code paths from hypotheses that still need production evidence.

## Executive summary

The same visible symptom, CPM no longer managing consent, can come from three materially different failures:

| Failure mode | Scope | Expected recovery | Confidence |
|---|---|---|---|
| CPM content script misses a document | Current document | A navigation or reload after the extension finishes loading | Confirmed |
| WebKit loses routing for an individual tab | Tab or WebContent process | A fresh tab/window, or rebuilding the affected tab | Confirmed historically; the known app lifecycle cause is fixed |
| WebKit retains a background service worker that failed to load | Extension context/controller | No ordinary message can recover it; the context must be unloaded or the failed background view cleaned up | Confirmed WebKit state machine; natural production trigger remains unknown |

The debug-menu simulation enters the third state deliberately. It proves the health detection and failure shape, but its exact trigger cannot happen naturally in the same way because only the debug delegate closes the newly created background web view in that synchronous interval.

The strongest production hypothesis is therefore narrower than “a race”: the extension service-worker registration must fail, and WebKit must keep the failed background web view attached. We have not yet established which real system condition makes registration fail.

## CPM architecture

The bundled extension is Manifest V3:

- Background entry point: `public/js/background-embedded.js`
- CPM content script: `public/js/content-scripts/cpm.js`
- Injection: `document_start`, isolated world, all frames
- Content-to-background transport: `chrome.runtime.sendMessage`
- Background receiver: `runtime.onMessage`, registered by `MessageRouter`

The content script sends an `autoconsent` message to the background service worker. The background routes that message and, where required, forwards it through native messaging.

## Normal message path

The relevant WebKit path is:

1. CPM content code calls `chrome.runtime.sendMessage(...)`.
2. The WebProcess implementation enters `WebExtensionAPIRuntime::sendMessage`.
3. IPC sends `Messages::WebExtensionContext::RuntimeSendMessage` to the UIProcess.
4. `WebExtensionContext::runtimeSendMessage` resolves the sender with `getTab(senderParameters.pageProxyIdentifier)`.
5. WebKit calls `wakeUpBackgroundContentIfNecessaryToFireEvents(RuntimeOnMessage)`.
6. When the background is available, WebKit dispatches `WebExtensionContextProxy::DispatchRuntimeMessageEvent`.
7. The service worker's `runtime.onMessage` listener receives and routes the CPM message.

This gives four distinct failure boundaries:

- The content script was never injected into the document.
- The sender's page identifier no longer resolves to a registered WebExtension tab.
- WebKit decides there is no listener to wake, or cannot load the worker.
- The worker receives the message but the extension/native handler fails afterward.

Those cases should not be treated as interchangeable.

## Retained failed background worker

This is the persistent WebKit state reproduced by the debug menu.

### First message or initial load

The handler chain is:

1. `wakeUpBackgroundContentIfNecessary`
2. Append the pending operation to `m_actionsToPerformAfterBackgroundContentLoads`
3. `loadBackgroundWebViewIfNeeded`
4. `loadBackgroundWebView`
5. Assign `m_backgroundWebView`
6. Call `_loadServiceWorker`

The service-worker registration then follows:

1. `WebPageProxy::loadServiceWorker`
2. Generated page invokes `navigator.serviceWorker.register(...)`
3. `ServiceWorkerContainer::register`
4. Registration job settles
5. `ServiceWorkerContainer::willSettleRegistrationPromise(success)`
6. `WebLocalFrameLoaderClient::didFinishServiceWorkerPageRegistration(success)`
7. IPC reaches `WebPageProxy::didFinishServiceWorkerPageRegistration`
8. Completion returns to `WebExtensionContext::loadBackgroundWebView`

### Failure state

When registration returns `success == false`, WebKit records `BackgroundContentFailedToLoad` and returns. In this path it does not call `unloadBackgroundWebView()`.

The important retained state is:

- `m_backgroundWebView` is still non-null.
- Pending actions have not been dispatched.
- The service worker is not running.

Every later CPM message appends another pending action, calls `loadBackgroundWebViewIfNeeded`, and immediately returns because `m_backgroundWebView` already exists. The pending actions therefore never run and the worker is never replaced.

That is a stable stuck state, not merely a slow startup.

### Normal cleanup paths

These paths do clean up the background web view:

- Navigation failure: `didFailNavigation` records the error and calls `unloadBackgroundWebView`.
- WebContent process termination: `webViewWebContentProcessDidTerminate` calls `unloadBackgroundWebView`.
- Normal nonpersistent-worker eviction: `unloadBackgroundContentIfPossible` calls `unloadBackgroundWebView`.

Consequently, ordinary idle eviction, memory pressure, or a conventional process crash alone do not explain the retained failed-view state.

## Debug simulation

The debug command performs this exact sequence:

1. Reload the CPM extension context.
2. WebKit creates its background web view.
3. The private delegate callback `_webExtensionController:didCreateBackgroundWebView:forExtensionContext:` runs synchronously after creation and before `_loadServiceWorker`.
4. The debug implementation removes the navigation delegate and closes the page with `_close`.
5. `_loadServiceWorker` sees a closed `WebPageProxy` and completes with `false`.
6. Because the normal navigation/process callbacks were suppressed, WebKit retains the failed `m_backgroundWebView`.

The following CPM message encounters the retained state. This explains why failure becomes visible one page load after activating the command.

This is a useful deterministic simulation, but not proof that production closes the page at that point.

## Possible production entry

From the inspected WebKit code, `_loadServiceWorker` can return failure when:

- The `WebPageProxy` is already closed.
- A service-worker launch completion handler is unexpectedly already present.
- The actual `navigator.serviceWorker.register` job settles as a failure.

The first condition is manufactured by the debug command. The natural production candidate is therefore a real registration failure, potentially involving script/resource loading, service-worker registration storage, or the Network process. The source establishes that these categories can fail; it does not identify which one occurred in reported sessions.

A re-entrancy problem involving an already-present launch completion handler is also possible from the API shape, but there is currently no observed production sequence proving it.

## Known transient paths

### Startup and state restoration

The app initializes the WebExtension manager before state restoration, but extension synchronization and loading continue asynchronously:

1. `AppDelegate.applicationDidFinishLaunching`
2. `setupWebExtensions()`
3. Manager/controller creation
4. Async `coordinator.loadAndSync()`
5. `stateRestorationManager.applicationDidFinishLaunching()`
6. Restored tabs and web views are created with the shared controller
7. A restored document may commit before extension loading reaches `addInjectedContent`

The WebKit extension-load side is:

1. `WebExtensionLoader.loadWebExtension`
2. `WKWebExtensionController.load(context)`
3. `WebExtensionController::load`
4. `WebExtensionContext::load`
5. Storage migration completion
6. `m_safeToInjectContent = true`
7. Background loading and `dispatchDidLoad`
8. `addInjectedContent`

If the restored page has already committed, its `document_start` opportunity is gone. A later reload injects CPM and recovers. This explains the reproduced startup miss, but not a permanently stuck extension.

### WebKit dropped-first-message bug

[WebKit bug 317981](https://bugs.webkit.org/show_bug.cgi?id=317981) describes a first message being silently dropped when persisted listener state is empty before the background has loaded once.

Before the fix, `wakeUpBackgroundContentIfNecessaryToFireEvents` interpreted the empty set as “no listener” instead of “listener state not known yet,” so it did not wake or queue the message. The fix introduced `m_backgroundContentHasLoadedOnce` and treats the pre-first-load listener state as unknown.

This is another transient startup failure. It does not retain a failed background web view and therefore does not explain cross-navigation stuck behavior.

### Scriptlet extension reload

The scriptlet update path unloads the old context and loads a newly created one. During that interval:

- Existing documents may still have old JavaScript whose extension context proxy has been removed.
- A navigation can commit before the replacement context adds its injected content.

A navigation after the new context finishes loading should recover. This becomes persistent only if the replacement service worker itself enters the retained failed-load state.

### Fire

Fire unloads extension contexts, clears website data, may reopen a window, and only then reloads extensions. A reopened page can commit while there is no loaded CPM extension context and miss `document_start`.

Again, a later navigation should recover unless the new background-worker load fails persistently.

### Application or embedded-extension update

Extension replacement previously had lifecycle windows in which an old context was removed before its replacement was ready. That known app-side lifecycle problem was fixed in `60dc9c2795` and is historical context only; this note intentionally does not preserve its detailed sequence.

## Window-scope implication

DuckDuckGo attaches the same `webExtensionManager.controller` to tab configurations across browser windows.

Opening another window reports `didOpenWindow` to the controller/context and registers the new window and tabs. It does not normally reload the extension context.

Therefore, if WebKit truly retains one globally failed background view in that shared context, the failure should normally affect every window using the controller. The observation that a new window works while the original remains broken points more strongly to per-tab or per-WebContent-process routing than to the global retained-worker state.

A decisive manual discriminator is:

1. Make the original window fail.
2. Confirm CPM works in a new window.
3. Return to the original window and navigate again.
4. If only the original remains broken, inspect tab/page registration.
5. If the original also recovers, the new-window event caused some global recovery and that handler chain must be traced separately.

This implication is based on controller ownership in the app and WebKit. The exact cause of the observed window behavior is not yet proven.

## Scenarios not supported by current evidence

The following ideas do not yet have a traced path into a stable stuck state:

- Multiple installed browser versions
- Sleep/wake by itself
- Memory pressure by itself
- Normal service-worker idle termination
- A routine WebContent-process crash
- Compiled content-rule cache corruption

They may alter timing or storage pressure, but should not be presented as reproduction scenarios without a corresponding failing handler sequence or production trace.

Safari 26.6 includes a fix for service-worker registration database files accumulating on launch, and WebKit has also fixed cold-launch cleanup that delayed extension content injection. These can widen or shrink startup timing windows, but neither source demonstrates the retained failed-background state.

## Evidence needed next

The next useful instrumentation should classify the failure before attempting more scenarios:

- Inspect `WKWebExtensionContext.errors` for `WKWebExtensionContextErrorBackgroundContentFailedToLoad`.
- Invoke `loadBackgroundContent(completionHandler:)` diagnostically after health detection.
- A failure or completion that never arrives points to the background load/pending-action path.
- A successful background load while CPM messaging still fails points to tab/content-process routing.
- Capture WebKit logs around “Tab not found for message for content script message.”
- Correlate “Loading background content” with a missing “Background content loaded” and any registration error.

Without that split, repeated UI scenarios can reproduce the symptom while exercising unrelated failure modes.

## Source locations

Local WebKit sparse checkout:

- `Source/WebKit/UIProcess/Extensions/Cocoa/WebExtensionContextCocoa.mm`
- `Source/WebKit/UIProcess/Extensions/WebExtensionContext.cpp`
- `Source/WebKit/UIProcess/WebPageProxy.cpp`
- `Source/WebCore/workers/service/ServiceWorkerContainer.cpp`
- `Source/WebKit/WebProcess/WebCoreSupport/WebLocalFrameLoaderClient.cpp`

References:

- [WebKit bug 317981: first runtime message not waking the background worker](https://bugs.webkit.org/show_bug.cgi?id=317981)
- [WebKit bug 292378: content scripts stopping after back/forward navigation](https://bugs.webkit.org/show_bug.cgi?id=292378)
- [Safari 26.6 release notes](https://developer.apple.com/documentation/safari-release-notes/safari-26_6-release-notes)
- [WebKit cold-launch extension cleanup fix](https://chromium.googlesource.com/external/github.com/WebKit/webkit/+/7f8d70c0622228116a14f5100cf0e3e6fd333de7)


## Queue and delivery failure taxonomy

The visible symptom does not by itself prove that one queue stopped. CPM messaging can fail at four different stages:

1. The WebKit background wake-up queue is entered but never drained.
2. Listener bookkeeping prevents messages from entering the wake-up queue.
3. The worker loads, but WebKit finds no process to receive the event.
4. The content-to-background message succeeds, but the background-to-tab `initResp` is lost.

There is also a CPM-owned JavaScript state queue. Its failure characteristics are described separately below.

### Literal WebKit wake-up queue

The literal queue is `m_actionsToPerformAfterBackgroundContentLoads`.

It is stuck when all of the following remain true:

```text
m_actionsToPerformAfterBackgroundContentLoads is non-empty
backgroundContentIsLoaded() is false
performTasksAfterBackgroundContentLoads() never runs
the extension context is not unloaded
```

Only `performTasksAfterBackgroundContentLoads()` executes the queued actions. Extension-context unload clears them without executing them.

#### The load gate never opens

`m_safeToLoadBackgroundContent` remains false until `moveLocalStorageIfNeeded` completes. When the extension base URL changed, that operation waits for the website-data store's `_renameOrigin` completion.

If the rename operation remains alive but never replies, `loadBackgroundWebViewIfNeeded` keeps returning before creating a background view. Work already queued through `wakeUpBackgroundContentIfNecessary` cannot run.

A normal Network-process disconnection should cancel the async IPC reply and invoke its completion. The problematic condition is an operation that remains pending without the connection being invalidated.

#### Service-worker launch completes with failure

`WebPageProxy::loadServiceWorker` can complete with `false` when:

- Its page is already closed.
- `serviceWorkerLaunchCompletionHandler` is already occupied.
- Service-worker registration is rejected.
- The worker script cannot be fetched.
- Its MIME type, scope, origin, or response is invalid.
- The worker script fails to start.
- The Network process disconnects while registration is pending.

A Network-process disconnection during registration follows this exact chain:

```text
NetworkProcessConnection::didClose
-> WebSWClientConnection::connectionToServerLost
-> WebSWClientConnection::clear
-> SWClientConnection::clearPendingJobs
-> ServiceWorkerJob::failedWithException
-> ServiceWorkerContainer::jobFailedWithException
-> ServiceWorkerContainer::willSettleRegistrationPromise(false)
-> WebLocalFrameLoaderClient::didFinishServiceWorkerPageRegistration(false)
-> WebPageProxy::didFinishServiceWorkerPageRegistration(false)
-> _loadServiceWorker completion(false)
-> WebExtensionContext records BackgroundContentFailedToLoad
-> return without performTasksAfterBackgroundContentLoads
-> return without unloadBackgroundWebView
```

At that point the queued actions and background web view are both retained.

#### Service-worker launch never completes

The launch completion can also be lost rather than called with `false`:

- `ServiceWorkerContainer::addRegistration` rejects through an early validation branch that does not call `willSettleRegistrationPromise(false)`. These branches cover a stopped container, Trusted Types rejection, empty or invalid URL, CSP rejection, invalid scheme, encoded slash/backslash, and invalid scope.
- `startScriptFetchForJob` finds no `ScriptExecutionContext`, notifies the server, destroys the job, and does not call `willSettleRegistrationPromise`.
- `ServiceWorkerContainer::stop` removes pending jobs without directly notifying the service-worker-page launch completion. This becomes a stall only when the associated WebPage failure/reset does not independently complete the launch.
- `willSettleRegistrationPromise` returns because it finds no document, no page, a page no longer marked as a service-worker page, or no local main frame.
- `WebLocalFrameLoaderClient::didFinishServiceWorkerPageRegistration` finds no `WebPage`.
- The `DidFinishServiceWorkerPageRegistration` IPC cannot be delivered while the UIProcess continues retaining the page.
- Origin import, registration-domain validation, script fetch, or worker startup remains pending without a process disconnection.
- `SWServerJobQueue` receives a callback after its registration or pre-installation worker disappeared and returns through one of its invariant-failure branches without resolving or rejecting the client job.

These paths leave `serviceWorkerLaunchCompletionHandler` installed and prevent `performTasksAfterBackgroundContentLoads`.

### Messages bypass the wake-up queue

A message can be discarded before anything is queued:

- On WebKit before fix `7682d9817b`, an empty persisted `m_backgroundContentEventListeners` set was interpreted as “no listener,” even before the background had loaded once. `runtime.sendMessage` completed without waking the worker.
- On current WebKit, after `m_backgroundContentHasLoadedOnce == true`, an absent `RuntimeOnMessage` entry is considered authoritative. Every later message completes without waking the worker.
- A content-script message whose `pageProxyIdentifier` does not resolve through `getTab` fails with `tab not found` before background wake-up.

The second condition can become extension-wide if `RuntimeOnMessage` was lost from the shared background-listener bookkeeping. The third condition is normally tab-local.

### Worker loaded, but no receiving process

After wake-up, `runtimeSendMessage` obtains `processes(RuntimeOnMessage, Main)`. The set is empty when:

- `m_eventListenerFrames` has no matching entry.
- Its weak listener frame has expired.
- The frame no longer has a page.
- The process cannot send messages.
- Session/private-data filtering excludes the page.
- The listener is registered under a different context proxy.

WebKit then completes the call with an empty response and does not retry.

If the set contains a process but that process remains alive and unresponsive, the async reply remains pending. IPC invalidation cancels it; an indefinitely unresponsive connection is the condition that makes it an indefinite wait.

A JavaScript listener can similarly retain the reply by returning `true` without calling `sendResponse`, or by returning a promise that never settles.

### Background-to-tab init response

The CPM handshake is bidirectional:

```text
content script: chrome.runtime.sendMessage(init)
background: chrome.tabs.sendMessage(tabId, initResp, { frameId })
```

The second leg does not deliver when:

- `getTab(tabIdentifier)` fails.
- The tab has no `WKWebView`.
- `tab->processes(RuntimeOnMessage, ContentScript)` is empty.
- The target frame identifier belongs to the previous document after navigation.
- The frame/document target no longer matches.
- The content-script listener mapping is absent from the tab's WebContent process.

The extension does not await or catch this `tabs.sendMessage(initResp)`. Therefore the original `init` can finish successfully while the content script never receives configuration. This is a strong explanation for a failure confined to one tab or one WebContent process.

### CPM JavaScript state queue

CPM serializes state mutations through `_stateQueue`:

```text
previous _stateQueue
-> getCpmState()
-> mutation callback
-> updateCpmState()
```

It remains pending if:

- `storage.session.get("cpmState")` never settles.
- `storage.session.set(...)` never settles.
- A mutation callback awaits another method that calls `modifyCpmState`, causing a self-deadlock.
- A callback returns another permanently pending promise.

Current mutation callbacks are synchronous and do not contain the nested-await error. Native messaging is protected by a 20-second timeout.

The normal enabled `init` path does not await its dashboard-state update before sending `initResp`. A stuck `_stateQueue` can break diagnostics and state persistence, but does not normally explain total consent-management failure.

## Exact all-tabs extension freeze sequence

The following is the exact sequence for the extension-context-wide freeze reproduced by the failed-background-load simulation. It applies to all tabs that share the same `WKWebExtensionController` and `WKWebExtensionContext`.

### Entry

1. The MV3 background service worker is not currently loaded.
2. A CPM content script sends `chrome.runtime.sendMessage({ messageType: "autoconsent", ... })`.
3. WebProcess sends `RuntimeSendMessage` to `WebExtensionContext::runtimeSendMessage`.
4. Sender-tab lookup succeeds. This is important: a failed lookup would be a tab-local failure instead.
5. Listener gating accepts `RuntimeOnMessage`.
6. `wakeUpBackgroundContentIfNecessary` sees `backgroundContentIsLoaded() == false`.
7. It appends the message-dispatch closure to `m_actionsToPerformAfterBackgroundContentLoads`.
8. `loadBackgroundWebViewIfNeeded` creates `m_backgroundWebView`.
9. `_loadServiceWorker` begins registration.
10. Registration either completes with `false` or never completes through one of the paths listed above.
11. `performTasksAfterBackgroundContentLoads` is not called.
12. No cleanup path calls `unloadBackgroundWebView`.
13. The first CPM dispatch closure remains queued.

The retained state is:

```text
m_backgroundWebView != nil
m_backgroundContentIsLoaded == false
m_actionsToPerformAfterBackgroundContentLoads is non-empty
```

For a lost-completion variant, `serviceWorkerLaunchCompletionHandler` is also still installed.

### Every later tab

For each later CPM message from any tab sharing that context:

1. `runtimeSendMessage` resolves that tab normally.
2. Listener gating accepts `RuntimeOnMessage`.
3. `wakeUpBackgroundContentIfNecessary` again sees the background as not loaded.
4. It appends another dispatch closure to the same shared action vector.
5. `loadBackgroundWebViewIfNeeded` sees `m_backgroundWebView != nil` and returns.
6. No replacement worker is created.
7. No dispatch closure runs.
8. The content script's `runtime.sendMessage` promise remains pending.
9. The background never handles the CPM `init`.
10. The background never sends `tabs.sendMessage(initResp)`.
11. Consent management does not start in that tab.

Because the queue and background view belong to the shared extension context, this repeats for every existing and newly created tab attached to the same controller. A page reload cannot repair it.

### Recovery

This state ends only when something calls `unloadBackgroundWebView` or unloads/reloads the entire extension context. Relevant cleanup paths are:

- Background WebContent-process termination callback
- Background navigation failure callback
- Explicit extension-context unload/reload
- App process restart

The ordinary 30-second nonpersistent-background eviction does not recover the failed-first-load sequence. The wake-up call tries to schedule eviction before the background view is created, so it returns without creating a timer; the failure path never schedules the timer afterward.

Opening an ordinary new browser window does not itself unload or reload the shared extension context. Therefore:

- If a new window works while the original remains broken, this exact all-tabs freeze is not the state currently being observed; the failure is more likely tab/process routing.
- If creating a new window reloads or replaces the extension context in the app's surrounding lifecycle, the new window can work because it is no longer using the poisoned context.
- The discriminator is whether previously broken tabs recover after the new window starts working.

### Alternative extension-wide freeze without queued actions

A separate extension-wide failure is possible when the shared listener bookkeeping says `RuntimeOnMessage` is absent:

```text
background worker was unloaded
m_backgroundContentHasLoadedOnce == true
RuntimeOnMessage absent from m_backgroundContentEventListeners
```

Every tab then follows:

```text
runtimeSendMessage
-> wakeUpBackgroundContentIfNecessaryToFireEvents
-> listener considered absent
-> completionHandler called without waking worker
-> no background CPM handler
-> no initResp
```

This freezes CPM across all tabs without growing `m_actionsToPerformAfterBackgroundContentLoads`. It recovers only when another event loads the worker and repairs listener registration, or when the extension context is reloaded.

On WebKit versions before `7682d9817b`, the same sequence can occur before the first successful background load because an empty persisted listener set was incorrectly considered authoritative.