fix(queue): confirm submission and terminal turns before advancing (#43)

content.js

@@ -165,7 +165,34 @@
 
         case 'CHECK_GENERATION_STATE': {
           const state = this.getGenerationState();
-          sendResponse({ state });
+          let responseState = null;
+          if (this.provider && typeof this.provider.getCommandResponseState === 'function') {
+            responseState = this.provider.getCommandResponseState(document, message.commandBinding || {});
+          }
+          sendResponse({ state, responseState });
+          break;
+        }
+
+        case 'GET_COMMAND_TURN_SNAPSHOT': {
+          if (this.provider && typeof this.provider.getCommandTurnSnapshot === 'function') {
+            const snapshot = this.provider.getCommandTurnSnapshot(document, {
+              expectedText: message.expectedText,
+              expectedFingerprint: message.expectedFingerprint
+            });
+            sendResponse({ ok: true, snapshot });
+            break;
+          }
+          sendResponse({ ok: false, error: 'Turn snapshot is unavailable.' });
+          break;
+        }
+
+        case 'GET_COMMAND_RESPONSE_STATE': {
+          if (this.provider && typeof this.provider.getCommandResponseState === 'function') {
+            const responseState = this.provider.getCommandResponseState(document, message.commandBinding || {});
+            sendResponse({ ok: true, responseState });
+            break;
+          }
+          sendResponse({ ok: false, error: 'Command response state is unavailable.' });
           break;
         }
 

docs/project-memory/architecture.md

@@ -4,7 +4,7 @@
 - `background.js` owns per-tab queue jobs in a `Map`, accepts runtime messages for start, enqueue, retry, stop, status, and diagnostics, injects prompt scripts into the selected tab, waits for response state with a finite retry/wait policy, and records durable queue state including retry and Deep Research wait metadata in local storage.
 - `popup.js` selects supported provider tabs through provider-neutral discovery, stores reusable messages and sequences in local storage, stores optimizer and queue settings in sync storage, resolves placeholders, and renders queue instances, status, and diagnostics through runtime messages.
 - `content.js` owns Enter-to-queue on supported providers and the optimizer on ChatGPT only. It discovers conversation turns through primary and fallback selectors, hides older messages, lazily restores images, adds a load-more banner, observes DOM changes, and can queue Enter-submitted text while the provider is generating.
-- Queue response detection in `background.js` is DOM-driven through injected functions and provider adapters. It recognizes generating/streaming indicators, selected error markers, and deep-research progress; prompt submission finds a contenteditable input and a supported send-button selector for the active provider.
+- Queue response detection in `background.js` is DOM-driven through injected functions and provider adapters. It requires a confirmed user turn before treating a send as submitted, then waits for a command-bound terminal assistant turn. Generating/streaming/status/error markers remain activity signals, but idle gaps are non-terminal unless the current command's assistant turn is confirmed.
 - `provider-adapter.js` defines the `ProviderAdapter` interface plus `ChatGPTAdapter`, `GeminiAdapter`, and `ClaudeAdapter`, centralizing site-specific selectors, conversation identity resolution, generation state checks, composer extraction/clearing, and message discovery. Gemini and Claude set `supportsOptimizer: false`.
 - Local and CI verification is `npm run check`: Node tests, correctness-focused ESLint, and checked-JavaScript/JSDoc analysis. The Manifest V3 extension still loads unpacked from the repository root with no transpile or bundle step.
 - `Installers/install_chatgpt_queue_optimizer.py` copies the extension source for packaging, creates a Firefox-specific Manifest V2 source from the Manifest V3 input, builds browser packages, and attempts persistent or temporary browser installation paths.

docs/project-memory/decisions.md

@@ -1,8 +1,8 @@
 # Decisions
 
 - Queue ownership is keyed by tab ID, allowing independent queues while preventing a second sequence from starting on a tab that already has a running or paused queue (`background.js`).
-- A command is not completed until `waitForTabResponse()` observes the response cycle or applies its explicit fallback. Failed send/wait phases pause the queue after a finite default of three automatic retries with exponential backoff. `queueUnlimitedRetryWait` is the only explicit unlimited wait/retry mode and still uses a non-zero delay; Deep Research awareness may use a longer progress-aware wait but cannot remove the final bound (`background.js`).
-- Queue state is persisted in local storage and periodically woken with an alarms entry. Non-critical snapshots are coalesced and unchanged snapshots are skipped, while start, enqueue, send/recovery, pause, stop, completion, tab removal, and worker-wake boundaries force durable writes. Snapshots include retry budget and Deep Research wait/progress timestamps so a worker wake does not reset them. On worker wake, an unconfirmed `sending` command is put back at the front; `retry-wait` keeps the current command and remaining delay (`background.js`).
+- A command is not completed until a new matching user turn is acknowledged and `waitForTabResponse()` confirms a command-bound terminal assistant turn. Transient idle after generation is non-terminal. Failed send/wait phases pause the queue after a finite default of three automatic retries with exponential backoff. `queueUnlimitedRetryWait` is the only explicit unlimited wait/retry mode and still uses a non-zero delay; Deep Research awareness may use a longer progress-aware wait but cannot remove the final bound (`background.js`).
+- Queue state is persisted in local storage and periodically woken with an alarms entry. Non-critical snapshots are coalesced and unchanged snapshots are skipped, while start, enqueue, send/recovery, pause, stop, completion, tab removal, and worker-wake boundaries force durable writes. Snapshots include retry budget, Deep Research wait/progress timestamps, and per-command delivery acknowledgement metadata (phase, user/assistant turn ids, ack sources) so a worker wake does not reset them or drop/resend the wrong command. On worker wake, an unconfirmed `sending`/`awaiting-submission-ack` command is put back at the front; a confirmed submission resumes waiting; `retry-wait` keeps the current command and remaining delay (`background.js`).
 - Queue debug logs remain ordered and bounded while buffered entries flush in batches; logical reads flush pending entries, and clear operations use a generation barrier so an older pending batch cannot repopulate cleared logs (`background.js`).
 - The optimizer uses layered selectors and fallback discovery because the page is controlled by ChatGPT. Its windowing keeps at least eight recent messages visible and caps the discovered message set at 1,200 (`content.js`).
 - Extension API helpers try callback and promise forms so popup, content, and background code can use the same operations across supported browser API variants (`popup.js`, `content.js`, `background.js`).

docs/project-memory/known-failures.md

@@ -1,8 +1,8 @@
 # Known failures and limits
 
 - Prompt submission depends on each provider’s current contenteditable and send-button selectors. If either is absent or disabled, the injected send operation returns an error and the queue pauses (`background.js`, `provider-adapter.js`).
-- Response detection depends on provider generating, streaming, status, and error markers. An injected-script failure, a detected error/retry state, a stalled Deep Research wait, or a finite wait timeout pauses the queue after the automatic retry budget is exhausted (`background.js`).
-- In the default wait mode, if no generating indicator appears for five seconds, the worker records that it assumed completion and advances. This is an intentional fallback but can misclassify a response when the page exposes no recognized indicator (`background.js`).
+- Response detection depends on provider generating, streaming, status, error, and command-bound turn markers. An injected-script failure, a detected error/retry/interrupted/waiting-for-user state, a stalled Deep Research wait, an unconfirmed send, or a finite wait timeout pauses the queue after the automatic retry budget is exhausted (`background.js`).
+- After an accepted submission, missing generating indicators are treated as pending until a command-bound terminal acknowledgement or a bounded timeout with a specific reason. The queue does not assume completion from click success or a short idle gap (`background.js`).
 - Deep-research-aware waiting uses a longer finite maximum duration and a stale-progress timeout. Progress updates reset the stale timer, but only explicit unlimited retry/wait removes the final bound (`background.js`).
 - If a worker restart finds only legacy running-job state and no recoverable durable queue, it records that the in-memory queue was lost and clears the stale state (`background.js`).
 - Gemini and Claude optimizer/message-window support is intentionally unsupported; queue Enter interception still runs on those providers (`provider-adapter.js`, `content.js`).