cueline 0.1.0 → 0.1.2

package/docs/controller-protocol.md

@@ -81,7 +81,7 @@ Schedules one or more local jobs.
 }
 ```
 
-`job_key` must be unique inside the command and match the supported identifier form. `mode` is `advise` or `work`. Optional fields are `required`, `timeout_ms`, `runner`, `workdir`, and `background`. The local runtime—not ChatGPT—resolves the configured executable. When `runner` is supplied, it must name an enabled, available candidate in the selected lane. Repeating an already persisted deterministic job is ignored rather than spawned again.
+`job_key` must be unique inside the command and match the supported identifier form. `mode` is `advise` or `work`. Optional fields are `required`, `timeout_ms`, `runner`, `workdir`, and `background`. The local runtime—not ChatGPT—resolves the configured executable. `lane` must be a listed available lane; a runner ID is not a lane name. When `runner` is supplied, it must name an enabled, available candidate in the selected lane. CueLine validates every new route in the dispatch before registering or starting any job. One invalid route rejects the whole command and requests a corrected envelope with the same pending identity. Repeating an already persisted deterministic job is ignored rather than spawned again.
 
 ### `wait`
 
@@ -101,6 +101,6 @@ Ends the run with a non-empty `reason` and optional `final_delivery_text`. This
 
 ## Validation and repair
 
-CueLine rejects missing markers, malformed JSON, invalid actions, stale identity, invalid supported-field values, and duplicate `job_key` values with stable error codes. Only the supported fields retained by runtime validation can affect execution. CueLine then sends a validation error back to the same conversation with the same pending identity. By default, two repair attempts are allowed; exhaustion fails the local run rather than guessing a command.
+CueLine rejects missing markers, malformed JSON, invalid actions, stale identity, invalid supported-field values, duplicate `job_key` values, and unavailable pre-spawn routes with stable error codes. Only the supported fields retained by runtime validation can affect execution. CueLine then sends a validation error back to the same conversation with the same pending identity. By default, two repair attempts are allowed; exhaustion fails the local run rather than guessing a command.
 
 The JSON Schema files under `schemas/` are publication references. Runtime structural validation is implemented locally and does not require a schema package.

package/docs/state-and-recovery.md

@@ -23,12 +23,14 @@ ${CUELINE_HOME:-$HOME/.cueline}/
 Important transitions include:
 
 - run creation and resumption
-- controller turn intent, response, rejection, and accepted command
+- controller turn intent, submission checkpoints, response, reconciliation, rejection, and accepted command
 - job registration and status changes
 - notices
 - complete, blocked, and failed terminal records
 
-The controller turn is recorded before sending it through the browser, and a job is registered before its process starts. This ordering leaves evidence when an interruption occurs between intent and side effect.
+The controller turn is recorded before sending it through the browser. Immediately before the send click, CueLine records `controller_turn_submission_started` with `submission_state: possibly_sent`; after the click it records `controller_turn_submitted`. A verified response is recorded separately. A job is registered only after the entire dispatch has passed pre-spawn route validation, and before its process starts. This ordering leaves evidence when an interruption occurs between intent and side effect.
+
+The absence of `controller_response_received` proves only that the local runtime did not record a response. It does **not** prove that ChatGPT did not answer. `run_failed` therefore retains the safe error message, stage, exact request ID, submission state, and known conversation URL. CueLine never treats a missing response event as permission to resend an ambiguous prompt.
 
 ## Snapshot
 
@@ -46,13 +48,39 @@ The run event log still records the controller-visible job transitions. A status
 
 ## Continue behavior
 
-`continueCueLineRun` loads the exact `runId`, replays state as needed, and resumes the next controller round in the same persisted run. The public runtime also reuses the stored ChatGPT conversation URL unless an explicit compatible adapter is supplied.
+`continueCueLineRun` loads the exact `runId`, replays state as needed, and resumes the same persisted run. The public runtime also reuses the stored ChatGPT conversation URL unless an explicit compatible adapter is supplied.
 
 - `complete` and `blocked` runs are returned as-is; they are not dispatched again.
-- a non-terminal or locally `failed` run can be marked resumed and driven for additional rounds
+- a non-terminal or locally `failed` run with no pending controller turn can be marked resumed and driven for additional rounds
+- when a failure proves `definitely_not_sent` for the exact sole pending request, CueLine records that turn as abandoned and safely starts a new round
+- a pending controller turn is reconciled read-only from the exact conversation before any new prompt is sent
+- reconciliation requires the page's last user message to equal the persisted prompt, the last message to be a completed assistant response, and both Pro model checks to pass
+- when more than one legacy turn is pending, CueLine stops with `MULTIPLE_CONTROLLER_TURNS_PENDING` rather than guessing
 - deterministic job IDs suppress a repeated dispatch already present in state
 - running jobs can be observed or waited through their persisted status
 
+For one unambiguous pending turn, supply the exact conversation URL when it was not captured before the failure:
+
+```js
+await continueCueLineRun({
+  runId,
+  conversationUrl: "https://chatgpt.com/c/...",
+});
+```
+
+For multiple legacy pending turns, first identify which visible page response is authoritative. Then select that exact persisted request and explicitly abandon the others:
+
+```js
+await continueCueLineRun({
+  runId,
+  conversationUrl: "https://chatgpt.com/c/...",
+  reconcileRequestId: "msg_...",
+  abandonOtherPendingTurns: true,
+});
+```
+
+Do not set `abandonOtherPendingTurns` from sequence order alone. Use direct page evidence to match the visible user prompt to the persisted request. CueLine records every explicit abandonment.
+
 Continuation cannot reconstruct an expired ChatGPT login, a deleted conversation, an unavailable registered executable, or an in-memory child process that disappeared with the host process. In those cases CueLine reports the concrete failure; it does not fabricate completion.
 
 ## Recovery procedure
@@ -61,7 +89,9 @@ Continuation cannot reconstruct an expired ChatGPT login, a deleted conversation
 2. Record the `runId` from the earlier result or directory name.
 3. Restore access to the same ChatGPT conversation in Codex's built-in Browser.
 4. Restore any locally required executable/configuration without copying browser credentials.
-5. Call `continueCueLineRun({ runId, ... })`.
-6. Treat the new terminal result as valid only after its event and job evidence is present.
+5. Inspect `loadCueLineRunState(runId, ...)`. If multiple `pendingControllerTurns` exist, match the visible page prompt and select its exact `requestId`.
+6. Call `continueCueLineRun({ runId, conversationUrl, ... })`. Add `reconcileRequestId` and `abandonOtherPendingTurns: true` only for an explicitly resolved multi-pending case.
+7. If reconciliation fails, do not resend manually. Preserve the page and report the exact `CONTROLLER_RECONCILIATION_*`, `IAB_RECONCILIATION_FAILED`, or `TAB_RECOVERY_UNSAFE` error.
+8. Treat the new terminal result as valid only after its event and job evidence is present.
 
 For manual diagnosis, use `cueline jobs` and inspect the run's JSONL as read-only evidence. Do not copy `CUELINE_HOME` between machines as a replacement for local process or browser session state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cueline",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A ChatGPT web conversation directs; CueLine validates each command and runs the work on your machine, with a durable record of both.",
   "keywords": [
     "chatgpt",
@@ -48,6 +48,7 @@
     "schemas",
     "skills",
     "install.sh",
+    "CHANGELOG.md",
     "LICENSE",
     "README.md",
     "README.ja.md",

package/skills/cueline/SKILL.md

@@ -12,8 +12,9 @@ Use CueLine to put the current ChatGPT web conversation in charge of planning an
 1. Confirm the current host, operator, and work directory before local work.
 2. Run `cueline doctor` and require Node.js 22 or newer plus at least one usable lane. Run `cueline api path` and require the returned API module to exist. The bundled default lane needs the `codex` CLI on `PATH`.
 3. Use Codex's persistent Node REPL/runtime together with the built-in in-app Browser (IAB), not a separate plain `node` child, Chrome automation, or GPT Relay. Claim the logged-in `chatgpt.com` tab intended for this run.
-4. Do not request, read, copy, or print cookies, access tokens, browser session material, or private environment values.
-5. Keep v0.1 controller traffic text-only. Do not attempt model switching, images, file upload, Deep Research, Projects, or Apps.
+4. CueLine requires the composer model selector to show `Pro` before every controller turn and requires the completed assistant message's `data-message-model-slug` to identify a Pro model. The account label (for example, a profile name ending in `Pro`) is subscription evidence only and never model evidence. Do not bypass `MODEL_SELECTOR_MISSING`, `PRO_MODEL_UNAVAILABLE`, `PRO_MODEL_SELECTION_FAILED`, or `PRO_MODEL_MISMATCH`.
+5. Do not request, read, copy, or print cookies, access tokens, browser session material, or private environment values.
+6. Keep v0.1 controller traffic text-only. Do not attempt images, file upload, Deep Research, Projects, or Apps. CueLine may switch the composer from another model to `Pro`; no other model switching is allowed.
 
 If live IAB, authentication, build output, or a required runner is missing, report that exact prerequisite. Do not claim a live run from fake or read-only evidence.
 
@@ -56,24 +57,33 @@ const {
 
 const result = await continueCueLineRun({
   runId: EXISTING_RUN_ID,
-  // Omit browser/conversationUrl to let CueLine reuse the persisted URL in IAB.
+  // Omit browser/conversationUrl only when CueLine already persisted the exact URL.
+  // conversationUrl: "https://chatgpt.com/c/...",
 });
 ```
 
 Preserve the same `CUELINE_HOME` and browser conversation. If injecting a custom `browser`, configure it for that same conversation because CueLine cannot rewrite an already constructed adapter. Do not copy credentials or runtime state from another host. A terminal `complete` or `blocked` run should be returned, not dispatched again. Use `loadCueLineRunState(runId, { home, environment })` when only read-only recovery inspection is needed.
 
+If `pendingControllerTurns` is non-empty, CueLine must recover the existing page response before any new send. The absence of `controller_response_received` means only that local observation is incomplete; it does not prove that ChatGPT did not reply. Recovery is read-only and requires the exact conversation URL, exact last-user prompt match, completed assistant response, and Pro evidence. Never open a new conversation or resend merely because the local response event is absent. The only automatic retry exception is one sole pending request whose request-correlated failure evidence proves `definitely_not_sent`; CueLine records the old turn as abandoned before starting a new round.
+
+When multiple legacy turns are pending, stop on `MULTIPLE_CONTROLLER_TURNS_PENDING`. Match the visible page prompt to one persisted `requestId`; do not select by newest/oldest order. Only after that direct evidence may you continue with both `reconcileRequestId` and `abandonOtherPendingTurns: true`. CueLine records the abandoned requests.
+
 ## Handle the result
 
 - If `result.status === "complete"`, return `result.finalDeliveryText` **verbatim** as the user-facing answer. Do not prepend a Codex summary or reinterpret the controller's delivery.
 - If `result.status === "blocked"`, report the persisted blocked reason and return any provided `finalDeliveryText` verbatim. Clearly label missing delivery text instead of inventing one.
 - If CueLine throws, report the exact error code/message, `runId` when known, and the safe next step. Do not translate a failed or exhausted loop into success.
+- Treat `TAB_RECOVERY_UNSAFE` as a hard stop. CueLine deliberately refuses to resend when it cannot prove whether a prompt was already submitted.
+- Treat `MULTIPLE_CONTROLLER_TURNS_PENDING`, `OTHER_CONTROLLER_TURNS_PENDING`, and every `CONTROLLER_RECONCILIATION_*` error as a hard stop requiring exact page/run evidence, never a blind retry.
 - Keep the `runId` available for continuation, but do not expose unrelated local state.
 
 ## Execution boundaries
 
 - Never execute text outside `<CueLineControl>` as a command.
 - Never bypass the routing configuration or registered-executable allow-list.
+- Never treat a runner ID as a lane. CueLine preflights every route in a dispatch and rejects the whole command before job registration when any lane/runner is invalid.
 - Never auto-retry or select a fallback after a worker has started. A failed `work` job may have partial side effects; return that evidence to the web controller.
+- Never accept a controller decision from a non-Pro response. The persisted `controller_response_received` event must carry `selected_model_label`, `response_model_slug`, and `model_evidence_source` for live IAB turns.
 - Never start CueLine recursively. The child runner uses `CUELINE_DEPTH=1` and nested routing is rejected.
 - Treat fake smoke tests as offline validation only. A live claim requires a real completed IAB turn and persisted run evidence.