codex-chatgpt-control 0.5.0-alpha.1 → 0.5.1-alpha.2

package/dist/src/scripts/release-canary-module.d.ts

@@ -0,0 +1,20 @@
+import type { BrowserLike } from "../types.js";
+import type { LiveSmokeScenarioResult } from "./live-smoke/types.js";
+export type ReleaseCanaryOptions = {
+    tabId: string;
+    reportDir?: string;
+    includeUpload?: boolean;
+};
+export type ReleaseCanaryResult = {
+    ok: boolean;
+    profilePaths: string[];
+    reportPath?: string;
+    results: LiveSmokeScenarioResult[];
+    failures: string[];
+};
+type ReleaseCanaryRuntime = {
+    agent?: unknown;
+    browser?: BrowserLike;
+};
+export declare function runReleaseCanary(runtime: ReleaseCanaryRuntime, options: ReleaseCanaryOptions): Promise<ReleaseCanaryResult>;
+export {};

package/dist/src/scripts/release-canary-module.js

@@ -0,0 +1,86 @@
+import { mkdir } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { main as captureSurfaceProfile } from "./capture-surface-profile.js";
+import { filterScenarios, runLiveSmoke } from "./live-smoke/harness.js";
+import { optionalScenarios, requiredScenarios } from "./live-smoke/scenarios.js";
+const CORE_SCENARIOS = [
+    "chat-work-expansion",
+    "configuration-mutate-restore",
+    "download-generated-file",
+];
+export async function runReleaseCanary(runtime, options) {
+    if (runtime.agent === undefined || runtime.agent === null) {
+        throw new Error("runReleaseCanary must run in a Codex bridge-hosted JavaScript context.");
+    }
+    if (options.tabId.trim().length === 0) {
+        throw new Error("runReleaseCanary requires an exact dedicated ChatGPT tab id.");
+    }
+    const reportDir = resolve(options.reportDir ?? join(process.cwd(), "reports", "release-canary"));
+    const profileDir = join(reportDir, "surface-profiles");
+    await mkdir(profileDir, { recursive: true });
+    const stamp = new Date().toISOString().replaceAll(":", "-").replaceAll(".", "-");
+    const profilePaths = [
+        join(profileDir, `${stamp}-chat.json`),
+        join(profileDir, `${stamp}-work.json`),
+    ];
+    try {
+        for (const [index, experience] of ["chat", "work"].entries()) {
+            const exitCode = await captureSurfaceProfile([
+                "--id", `release-canary-${experience}`,
+                "--experience", experience,
+                "--tab-id", options.tabId,
+                "--if-missing", "block",
+                "--out", profilePaths[index],
+                "--provenance", "Sanitized release canary capture from a dedicated visible ChatGPT tab."
+            ], runtime);
+            if (exitCode !== 0) {
+                return {
+                    ok: false,
+                    profilePaths: profilePaths.slice(0, index),
+                    results: [],
+                    failures: [`surface-profile-${experience}`]
+                };
+            }
+        }
+    }
+    finally {
+        await closeDedicatedProfileTab(runtime.browser, options.tabId);
+    }
+    const names = options.includeUpload === true
+        ? [...CORE_SCENARIOS, "attach-one-file"]
+        : CORE_SCENARIOS;
+    const context = {
+        agent: runtime.agent,
+        ...(runtime.browser === undefined ? {} : { browser: runtime.browser }),
+        reportDir: join(reportDir, "live-smoke"),
+        env: {
+            CHATGPT_E2E_CONFIGURATION_MUTATION: "1",
+            CHATGPT_E2E_DOWNLOAD: "1",
+        }
+    };
+    const scenarios = filterScenarios([...requiredScenarios, ...optionalScenarios], names.join(","));
+    if (scenarios.length !== names.length) {
+        throw new Error(`Release canary scenario registration drift: expected ${names.length}, found ${scenarios.length}.`);
+    }
+    const smoke = await runLiveSmoke(context, scenarios);
+    const failures = smoke.results.filter(result => result.status !== "pass").map(result => result.name);
+    return {
+        ok: failures.length === 0,
+        profilePaths,
+        reportPath: smoke.reportPath,
+        results: smoke.results,
+        failures
+    };
+}
+async function closeDedicatedProfileTab(browser, tabId) {
+    const tabs = browser?.tabs;
+    const get = tabs?.get;
+    if (tabs === undefined || typeof get !== "function") {
+        throw new Error("Release canary requires browser.tabs.get so its dedicated profile tab can be closed before behavior tests.");
+    }
+    const tab = await get.call(tabs, tabId);
+    if (typeof tab.close !== "function") {
+        throw new Error("Release canary dedicated profile tab does not expose close().");
+    }
+    await tab.close();
+}

package/dist/src/types.d.ts

@@ -432,6 +432,17 @@ export type DownloadLatestArgs = {
     };
     timeoutMs?: number;
 };
+export type StopGenerationArgs = {
+    /** Required acknowledgement because stopping changes the visible Chat turn. */
+    confirmStop?: boolean;
+    timeoutMs?: number;
+};
+export type StopGenerationData = {
+    wasGenerating: boolean;
+    stopped: boolean;
+    signalsBefore: string[];
+    signalsAfter: string[];
+};
 export type DownloadedFile = {
     path: string;
     suggestedFilename?: string;
@@ -767,6 +778,10 @@ export type SequenceStep = {
     id: string;
     command: "messages.status";
     args?: MessageStatusArgs;
+} | {
+    id: string;
+    command: "messages.stop";
+    args: StopGenerationArgs;
 } | {
     id: string;
     command: "messages.waitAndRead";
@@ -869,27 +884,33 @@ export type BrowserUserTabInfo = {
     title?: string;
     url?: string;
 };
+export type BrowserOperationOptions = {
+    timeoutMs?: number;
+};
 export type LocatorLike = {
-    click?: (options?: unknown) => Promise<void>;
+    click?: (options?: BrowserOperationOptions & Record<string, unknown>) => Promise<void>;
+    press?: (key: string, options?: unknown) => Promise<void>;
     fill?: (value: string, options?: unknown) => Promise<void>;
     textContent?: (options?: unknown) => Promise<string | null>;
     innerText?: (options?: unknown) => Promise<string>;
     innerHTML?: (options?: unknown) => Promise<string>;
     count?: () => Promise<number>;
+    allTextContents?: (options?: BrowserOperationOptions) => Promise<string[]>;
     nth?: (index: number) => LocatorLike;
     first?: () => LocatorLike;
     last?: () => LocatorLike;
     isVisible?: (options?: unknown) => Promise<boolean>;
-    evaluate?: <T>(fn: (element: Element) => T) => Promise<T>;
+    evaluate?: <T>(fn: (element: Element) => T, arg?: unknown, options?: BrowserOperationOptions) => Promise<T>;
     locator?: (selector: string) => LocatorLike;
     filter?: (options: Record<string, unknown>) => LocatorLike;
     getByRole?: (role: string, options?: Record<string, unknown>) => LocatorLike;
     getByText?: (text: string | RegExp, options?: Record<string, unknown>) => LocatorLike;
-    setInputFiles?: (paths: string[]) => Promise<void>;
+    setInputFiles?: (paths: string[], options?: BrowserOperationOptions) => Promise<void>;
 };
 export type FileChooserLike = {
+    element?: () => LocatorLike | Promise<LocatorLike>;
     isMultiple?: () => boolean | Promise<boolean>;
-    setFiles: (paths: string[]) => Promise<void>;
+    setFiles: (paths: string[], options?: BrowserOperationOptions) => Promise<void>;
 };
 export type WaitForEventOptions = {
     timeout?: number;
@@ -922,11 +943,14 @@ export type PageLike = {
             y: number;
             button?: number;
         }) => Promise<void> | void;
+        keypress?: (options: {
+            keys: string[];
+        }) => Promise<void> | void;
     };
     waitForTimeout?: (ms: number) => Promise<void>;
     waitForEvent?: (event: string, optionsOrCallback?: WaitForEventOptions | unknown) => Promise<unknown>;
-    evaluate?: <T, A = unknown>(fn: (arg: A) => T | Promise<T>, arg?: A) => Promise<T>;
-    content?: () => Promise<string>;
+    evaluate?: <T, A = unknown>(fn: (arg: A) => T | Promise<T>, arg?: A, options?: BrowserOperationOptions) => Promise<T>;
+    content?: (options?: BrowserOperationOptions) => Promise<string>;
     close?: () => Promise<void>;
     capabilities?: {
         get?: (id: string) => Promise<unknown> | unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-chatgpt-control",
-  "version": "0.5.0-alpha.1",
+  "version": "0.5.1-alpha.2",
   "description": "Unofficial SDK for controlling visible ChatGPT Chat and Work sessions.",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,8 @@
     "bundle": "esbuild src/index.ts --bundle --platform=node --format=esm --outfile=dist/codex-chatgpt-control.bundle.mjs",
     "bundle:backend": "esbuild src/scripts/backend-server.ts --bundle --platform=node --format=esm --outfile=dist/codex-chatgpt-control-backend.mjs",
     "bundle:live-smoke": "esbuild src/scripts/live-smoke-module.ts --bundle --platform=node --format=esm --outfile=dist/codex-chatgpt-control-live-smoke.bundle.mjs",
+    "bundle:release-canary": "esbuild src/scripts/release-canary-module.ts --bundle --platform=node --format=esm --outfile=dist/codex-chatgpt-control-release-canary.bundle.mjs",
+    "contract:generate": "node scripts/generate-contract-fixtures.mjs",
     "contract:validate": "node scripts/validate-contract.mjs",
     "docs:drift": "tsx src/scripts/check-surface-drift.ts",
     "parity:fixtures": "node scripts/check-parity-fixtures.mjs",
@@ -34,11 +36,15 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "thread": "tsx src/scripts/continue-thread.ts",
+    "capture:intelligence-locales": "tsx src/scripts/capture-intelligence-locales.ts",
+    "capture:intelligence-locales:queue": "tsx src/scripts/capture-intelligence-locales.ts --print-queue",
     "capture:surface-profile": "tsx src/scripts/capture-surface-profile.ts",
+    "apply:intelligence-locales": "tsx src/scripts/apply-intelligence-locale-captures.ts",
     "smoke:hi": "tsx src/scripts/smoke-hi.ts",
     "smoke:search": "tsx src/scripts/smoke-search-open-read.ts",
     "smoke:attach": "tsx src/scripts/smoke-attach-file.ts",
-    "smoke:live": "tsx src/scripts/live-smoke.ts"
+    "smoke:live": "tsx src/scripts/live-smoke.ts",
+    "smoke:release:build": "npm run bundle:release-canary"
   },
   "exports": {
     ".": {

package/references/2026-07-16-chat-work-surfaces.md

@@ -50,6 +50,19 @@ Legacy `modes.set/get` and runner `mode` inputs remain supported. They preserve
 their pre-0.5 warning-oriented behavior. New code requiring a verified
 postcondition should use `configuration.apply({ strict: true })`.
 
+## Surface Transitions
+
+On the current home surface, ChatGPT exposes Chat and Work as a radio group in
+the page banner. The checked radio is the strongest experience signal; the
+textbox accessible name is shared and cannot classify the surface by itself.
+Older button, tab, link, and menu-item controls remain compatibility fallbacks.
+
+An active Work task may remove the home radio group while retaining the Work
+model-plus-effort opener, such as `5.5 Light`. That compound control is a Work
+continuation signal. To switch panes from an active conversation, the SDK
+returns to the stable ChatGPT home surface and selects the requested radio; it
+does not infer or navigate to a private Work route.
+
 ## Work Lifecycle
 
 `work.start` defaults to `newTask: true`. If messages are already loaded and a

package/references/2026-08-08-model-selection-locale-sweep.md

@@ -0,0 +1,32 @@
+---
+title: Model Selection Locale Sweep
+date: 2026-08-08
+type: review
+status: complete
+---
+
+# Model Selection Locale Sweep
+
+English plus all 64 non-English languages advertised in ChatGPT Settings were
+captured from one authenticated live account against the current selector UI.
+
+The latest record for every locale passed these gates:
+
+- rendered `html lang` matched the requested language;
+- Chat exposed Power plus ordered Model/Effort rows;
+- Work exposed Power plus ordered Model/Effort/Speed rows;
+- Chat contained 3 model and 5 effort options;
+- Work contained 4 model, 6 effort, and 2 speed options;
+- captured labels were non-empty;
+- Chat and the initial rendered language were restored.
+
+The append-only private-source evidence contains 77 attempts: 65 latest
+successes and 12 earlier blocked attempts retained for diagnostics. Every
+blocked locale was subsequently recaptured successfully. The reviewed apply
+updated all 64 non-English locale contributions and was idempotent on a second
+run.
+
+This is point-in-time evidence for the account and rollout observed on
+2026-08-08. It does not guarantee identical model inventory for every plan,
+region, workspace, or experiment. Generation-state, project, and plugin labels
+were outside this no-prompt sweep.

package/references/backend-protocol.md

@@ -71,6 +71,10 @@ Browser-control blockers are not protocol errors. They are normal command or run
 
 Use `messages.status({ maxPreviewChars })` for a compact latest-assistant progress snapshot when a host tool-call ceiling is shorter than the expected ChatGPT generation. It returns counts, latest-assistant preview length, `completionState`, `generationActive`, and generation signals without treating partial text as final, and without the cost of a full `readLatest`/`wait` probe.
 
+Use `messages.stop({ confirmStop: true })` only after the caller explicitly decides that the current visible response should stop. It clicks one uniquely scoped, visible stop control and succeeds only after generation is observed inactive. Without the exact boolean `confirmStop: true`, it returns `needs_confirmation`; if generation is observably inactive, it is a no-op. An unavailable or ambiguous control, an uninspectable generation state, or an unverified postcondition fails closed.
+
+If the Stop activation starts but its completion races the command deadline, the result is `status: "timeout"` with blocker code `stop_generation_unverified` and `resumable: false`. The browser-native deadline terminates the request before the command returns, so it cannot click later; the click may already have taken effect before termination. Inspect the current visible generation state and never retry Stop automatically.
+
 ## Streaming
 
 Streaming commands emit backend event lines until `completed` or `error`.
@@ -134,6 +138,10 @@ Use `files.preflight` for non-mutating local validation before browser upload wo
 
 `files.attach` accepts `includeDiagnostics: true` to return metadata-only upload diagnostics in `data.diagnostics`: the preflight result plus the browser input's selected file names and sizes when the DOM exposes them. Pair `includeDiagnostics: true` with `includeHashes: true` when diagnosing whether a non-empty local file became an empty browser-side `File`; do not persist these diagnostics in public reports unless the user has approved content fingerprint metadata.
 
+Once the native file handoff starts, any timeout, bridge error, or missing post-handoff composer evidence is indeterminate: `files.attach` returns `status: "partial"`, blocker code `attachment_outcome_indeterminate`, and `resumable: false`. Browser-native deadlines terminate the handoff request before the command returns, so it cannot mutate later; the file may already be present. Inspect the current composer, do not submit, and never retry the attachment automatically.
+
+The Codex Chrome chooser intentionally exposes `isMultiple()` and `setFiles()` but no backing-element accessor. Before accepting that opaque chooser, the Node runtime proves the initiating input or control belongs to the unique active composer; the CDP fallback independently resolves and clicks that exact unique input. Browser providers that expose a chooser backing element receive an additional identity cross-check before handoff.
+
 ## Project Sources
 
 Project Sources V1 is a narrow visible-UI surface for ChatGPT Project URLs such as `https://chatgpt.com/g/g-p-.../project`.
@@ -164,9 +172,16 @@ capability to inventory and bundle the latest non-SVG image asset. This is an
 implementation detail of the TypeScript runtime; the wire command and result
 shape are unchanged.
 
-`files.downloadLatest` preserves the existing file-link behavior and falls back
-to generated-artifact download only when no conventional ChatGPT file affordance
-is visible. Artifact failures are reported as structured blockers such as
+`files.downloadLatest` preserves the existing file-link behavior, recognizes
+filename-labelled buttons in the latest assistant turn, opens ChatGPT's artifact
+preview, and then activates its visible Download control. `filenamePattern` is
+an optional case-insensitive regular expression that prevents a different file
+or image fallback from being accepted as the requested output. When the browser
+bridge exposes only a completed local download `path()`, the runtime copies that
+file into `destDir`; bridges exposing `saveAs()` remain supported. Without a
+filename pattern, the command falls back to generated-artifact download only
+when no conventional ChatGPT file affordance is visible. Artifact failures are
+reported as structured blockers such as
 `artifact_unavailable`, `artifact_selector_drift`, or
 `artifact_download_unavailable`, not protocol errors.
 
@@ -220,13 +235,13 @@ For live browser control, the backend process must have access to a compatible b
 - Explicit `RuntimeEnv.browser` or `RuntimeEnv.page` in a future embedding.
 - A future Python-native/native-host/CDP backend that implements this same protocol.
 
-Important: in Codex, `globalThis.agent` is not present until the Chrome plugin runtime is bootstrapped. Do not diagnose bridge availability by checking `globalThis.agent` in an ordinary shell or before calling the Chrome plugin's `setupBrowserRuntime({ globals: globalThis })`.
+Important: in Codex, `globalThis.agent` is not present until the Chrome plugin runtime is bootstrapped. Do not diagnose bridge availability by checking `globalThis.agent` in an ordinary shell or before assigning the object returned by the Chrome plugin's `setupBrowserRuntime()`.
 
 The live Chrome bootstrap is:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
-await setupBrowserRuntime({ globals: globalThis });
+const { setupBrowserRuntime } = await import("/absolute/path/to/the/current/chrome/scripts/browser-client.mjs");
+globalThis.agent = await setupBrowserRuntime();
 globalThis.browser = await agent.browsers.get("extension");
 ```
 
@@ -270,7 +285,7 @@ python scripts/live_smoke.py \
   --backend-command "node scripts/http_stdio_relay.mjs"
 ```
 
-The bridge-hosted JS execution must remain active for the duration of the Python smoke. The relay path is:
+Create the backend server and wait on it in the **same** bridge-hosted JS execution. A server created in one Node REPL call cannot be kept bridge-capable by waiting in a second call. That single execution must remain active for the duration of the Python smoke. The relay path is:
 
 ```text
 Python SDK -> stdio relay -> bridge-hosted Node backend -> Codex Chrome bridge -> ChatGPT

package/references/language-coverage.md

@@ -5,12 +5,10 @@ The full set of languages ChatGPT exposes in **Settings → General → Language
 localization rollout described in [`localization.md`](./localization.md). Strings are
 stored per-locale under `src/dom/locale/<bcp47>.ts`.
 
-The status table covers the pre-existing Chat/localization registry, not the new
-Chat/Work profile graph introduced in July 2026. Work composer,
-experience-switch, configuration-axis, and configuration-option coverage is
-currently verified only for the sanitized English profiles. Do not interpret a
-green row below as full Work support until that locale has matching profile
-evidence.
+The status table began as the pre-existing Chat/localization registry. On
+2026-08-08, English plus all 64 non-English entries were recaptured against the
+current Chat and Work Power/Advanced selector graph. The latest record for
+every locale passed; see the [reviewed sweep summary](./2026-08-08-model-selection-locale-sweep.md).
 
 - Speaker counts are **crude guesstimates** (native + second-language, rounded), not
   researched figures. They exist only to prioritize the rollout.
@@ -124,21 +122,33 @@ For a single current Chat or Work surface, generate a sanitized, unverified
 profile draft from an already-open authorized tab:
 
 ```bash
-npm run capture:surface-profile -- --id work-basic-en --locale en-US
+npm run capture:surface-profile -- --id work-basic-en --locale en-US --experience work
 ```
 
-This command does not submit a prompt or change configuration. It opens visible
-menus for inspection, normalizes any conversation URL to `/c/sanitized`, and
+This command does not submit a prompt or change model configuration. When
+`--experience` is supplied it visibly selects Chat or Work and restores the
+prior pane by default. It opens visible menus for inspection, normalizes any conversation URL to `/c/sanitized`, and
 writes only bounded composer/configuration structure under
 `outputs/surface-profiles/`.
 
 Use the repository capture script to drive the visible ChatGPT UI through Settings → General
-→ Language, then open the composer Intelligence picker and record the localized labels:
+→ Language, then open the current composer selector and record localized labels:
 
 ```bash
 npm run capture:intelligence-locales -- --auto-switch --all --if-missing open
 ```
 
+For a complete current selector sweep, add `--capture-surfaces`. This reads the
+two ordered pane radios, both Power controls, both Advanced labels, Chat's
+ordered Model/Effort rows, Work's ordered Model/Effort/Speed rows, and every
+visible submenu option. It restores the original compact/advanced state, Chat
+pane, and initial rendered language:
+
+```bash
+npm run capture:intelligence-locales -- \
+  --auto-switch --all --capture-surfaces --if-missing open
+```
+
 To also capture localized running-generation controls such as `stopControl`, run the same
 sweep with the bounded generation probe enabled:
 
@@ -166,9 +176,10 @@ changes the settings or picker DOM, the run should emit a blocker record instead
 
 1. Switch ChatGPT **Settings → General → Language** to the target, reload, and confirm via
    `document.documentElement.lang` + visible text.
-2. Read static controls (composer, add-files, new chat, current model label) via JS.
-3. Open the model switcher and the `+` menu with **real** clicks (Radix menus ignore
-   synthetic `.click()`) and read the menu items → mode + tool labels.
+2. Read static controls (composer, add-files, new chat, current selector label) via JS.
+3. Open the selector with a **real** click, record the Power slider, expand
+   Advanced when needed, and read the ordered Chat Model/Effort or Work
+   Model/Effort/Speed menus. Restore the initial compact/advanced state.
 4. Open search → placeholder; observe a conversation → copy-response + response-actions.
    `stopControl` is present only mid-generation and should be captured with
    `--capture-generation-state`; login/captcha/rate-limit copy needs a logged-out/limited

package/references/localization.md

@@ -71,7 +71,7 @@ Localized — lives in `src/dom/locale/en.ts` (English) and per-locale files, sa
 | `workComposerTextbox` | Work composer textbox | `aria-label` / placeholder |
 | `newWork` | start-another-Work-task control | visible button or link text |
 | `experienceOptions.chat` / `.work` | Chat/Work switch controls | visible button, tab, link, or menu text |
-| `configurationAxes.*` | model/intelligence/effort/speed/advanced rows | visible row text |
+| `configurationAxes.*` | power/model/intelligence/effort/speed/advanced controls | visible or accessible text |
 | `configurationOptions.*` | Chat and Work configuration values | visible menu text |
 | `sendButton` | send button | `aria-label` |
 | `searchChatsButton` | search-chats button | `aria-label` |
@@ -106,18 +106,19 @@ Localized — lives in `src/dom/locale/en.ts` (English) and per-locale files, sa
 The type definitions for `LocaleStrings` (complete) and `LocaleContribution` (partial, for
 non-English files) live in [`src/dom/locale/types.ts`](../src/dom/locale/types.ts).
 
-The first Chat/Work profile fixtures are English evidence. The nested locale
-combiner lets existing locale files omit the new groups without breaking
-compilation, but that is not proof that Work configuration is localized in
-those languages. Add observed labels and a sanitized surface-profile fixture
-before claiming support for a new locale/profile combination.
+English plus all 64 advertised non-English Settings languages were recaptured
+against the current Chat and Work Power/Advanced selector graph on 2026-08-08.
+That proves the reviewed labels for the observed account and rollout, not every
+plan, region, workspace, or staged experiment. Keep capability discovery and
+fail-closed shape checks even when a locale is present in the registry.
 
 Create a read-only draft from an already-open authorized ChatGPT tab:
 
 ```bash
 npm run capture:surface-profile -- \
   --id work-basic-de \
-  --locale de-DE
+  --locale de-DE \
+  --experience work
 ```
 
 The command defaults region, plan, account, and workspace metadata to
@@ -127,6 +128,23 @@ identifiers, and excludes prompt/response/sidebar text. Review the draft under
 then move a sanitized fixture into `contracts/v1/fixtures/` and update the
 manifest/parity matrix.
 
+To refresh every language in one visible-session sweep, use the existing
+Settings language loop with structural Chat/Work capture enabled:
+
+```bash
+npm run capture:intelligence-locales -- \
+  --auto-switch --all --capture-surfaces --if-missing open
+```
+
+Review the JSONL evidence, then apply it only with the explicit review gate:
+
+```bash
+npm run apply:intelligence-locales -- --in <capture.jsonl> --reviewed
+```
+
+The applier keeps older locale contributions valid, adds only observed
+non-English labels, and refuses incomplete surface captures instead of guessing.
+
 ## Adding a new language
 
 ### Step 1 — put a real ChatGPT session into the target language
@@ -186,11 +204,13 @@ Leave the canonical English first (it comes from `en.ts`), and leave the API key
 (`web_search`, `modeOptions.pro`, `modeOptions.high`, and the other semantic ids)
 unchanged.
 
-Newer ChatGPT rollouts may expose `Medium`, `High`, `Extra High`, and `Pro`
-under an `Intelligence` picker. Add localized equivalents only after observing
-those exact labels in the target locale. Put broad picker/opening labels in
-`modeLabels`, but put selectable labels under `modeOptions.<semantic-id>` so
-short labels such as `Pro` cannot match unrelated rows like `Move to project`.
+Current ChatGPT rollouts may expose a basic Power control and nested Advanced
+Model/Effort/Speed rows. Add localized equivalents only after observing those
+exact labels in the target locale. Put legacy broad picker/opening labels in
+`modeLabels`, selectable Chat effort labels under
+`modeOptions.<semantic-id>`, and current selector labels under
+`configurationAxes` / `configurationOptions` so short labels such as `Pro`
+cannot match unrelated rows like `Move to project`.
 
 Then open [`src/dom/locale/index.ts`](../src/dom/locale/index.ts) and register the new
 locale:
@@ -274,8 +294,10 @@ Notes:
   fixture, or protocol change, because API keys and wire shapes are unchanged.
 - All consumer import paths (`from "../dom/locale-labels.js"`) are unchanged — the barrel
   `locale-labels.ts` re-exports everything from `locale/index.ts`.
-- `doctor({ check: ["localization"] })` verifies that the registry is populated and
-  canonical English values are present. It also reports running-state localization coverage
+- `doctor({ check: ["localization"] })` verifies that the legacy selector,
+  tool, mode-option, configuration-axis (including Power/Advanced), and
+  configuration-option registries are populated and canonical English values
+  are present. It also reports running-state localization coverage
   separately from the flattened selector list, because `stopControl` and
   `stoppedAssistant` require a live mid-generation capture. It does not yet prove full
   localized selector coverage; treat localized workflow failures as selector-wiring work

package/references/python-parity.md

@@ -34,6 +34,10 @@ Incomplete response capture is also shared contract behavior. Python must preser
 
 For long-answer polling, Python forwards `response_content="metadata"` to the shared wire field `responseContent: "metadata"` on `messages.wait`. The TypeScript backend then omits assistant text from wait results and returns compact metadata such as `data.responseChars` and `data.responseSha256`; Python must preserve those fields without trying to reconstruct omitted content.
 
+Python exposes the explicit stop primitive as `chatgpt.messages.stop(confirm_stop=True)`, mapping to `messages.stop` with `confirmStop: true`. The TypeScript backend owns visible-control selection, the single operation deadline, and inactive-state verification; Python adds no independent browser behavior.
+
+Python preserves the backend's indeterminate Stop result exactly: `status == "timeout"`, blocker code `stop_generation_unverified`, and `resumable == False`. The browser request is terminated at its native deadline and cannot click later, but the click may already have taken effect. Python callers must inspect the visible state and must not retry automatically.
+
 Generated-image behavior stays owned by the TypeScript runtime. Python exposes
 the same backend commands through `chatgpt.artifacts.list_latest(...)`,
 `chatgpt.artifacts.wait(...)`, and `chatgpt.artifacts.download_latest(...)`.
@@ -63,6 +67,8 @@ Python does not reinterpret attachment paths. It sends the path string to the No
 
 Python exposes the backend-visible `files.preflight` command as `chatgpt.files.preflight(...)`. It returns the same `CommandResult` as TypeScript and can be decoded with `FilePreflightData` when callers want typed metadata. The command validates paths, readability, file-vs-directory status, size limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses without opening ChatGPT or reading file contents for MIME detection. Zero-byte files are blocked before browser interaction. Optional `include_hashes=True` / wire `includeHashes: true` adds SHA-256 metadata to `FilePreflightFile.sha256` for local diagnostics; file contents are never returned.
 
+Python also preserves a post-handoff attachment uncertainty as `status == "partial"`, blocker code `attachment_outcome_indeterminate`, and `resumable == False`. Callers must inspect the current composer, must not submit, and must not automatically repeat the file handoff.
+
 ## Project Sources
 
 Python exposes the protocol-visible Project Sources commands through `chatgpt.projects.sources`:
@@ -211,8 +217,8 @@ python scripts/live_smoke.py --mode browser-bridge
 When the live backend is hosted inside the Codex Chrome plugin runtime, do not test bridge availability from a normal shell or an unbootstrapped Node REPL. First initialize the Chrome runtime:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
-await setupBrowserRuntime({ globals: globalThis });
+const { setupBrowserRuntime } = await import("/absolute/path/to/the/current/chrome/scripts/browser-client.mjs");
+globalThis.agent = await setupBrowserRuntime();
 globalThis.browser = await agent.browsers.get("extension");
 ```
 
@@ -225,7 +231,7 @@ python scripts/live_smoke.py \
   --backend-command "node scripts/http_stdio_relay.mjs"
 ```
 
-Keep the bridge-hosted JS execution active while Python runs. If that JS execution returns first, the browser client no longer has an active execution context and operations can fail with `node_repl exec context not found`.
+Create the backend server and wait on it in the **same** bridge-hosted JS execution. Starting the server in one Node REPL call and trying to keep it alive with a second call does not preserve the first call's browser execution context. Keep that single execution active while Python runs. If it returns first, the browser client no longer has an active execution context and operations can fail with `node_repl exec context not found`.
 
 This is the intended live test chain:
 

package/references/troubleshooting.md

@@ -33,8 +33,8 @@ Use `chatgpt.explainBlocker(result)` or Python `explain_blocker(result)` when re
 Do not conclude that Chrome or the extension is broken from a plain shell result, or from checking `globalThis.agent` before the Chrome plugin runtime is initialized. For a true Codex Chrome-plugin live run, bootstrap the runtime first:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
-await setupBrowserRuntime({ globals: globalThis });
+const { setupBrowserRuntime } = await import("/absolute/path/to/the/current/chrome/scripts/browser-client.mjs");
+globalThis.agent = await setupBrowserRuntime();
 globalThis.browser = await agent.browsers.get("extension");
 ```
 
@@ -49,7 +49,7 @@ python scripts/live_smoke.py \
   --backend-command "node scripts/http_stdio_relay.mjs"
 ```
 
-Keep the bridge-hosted JS execution active while Python runs. If that call returns first, browser operations can fail with `node_repl exec context not found`.
+Create the backend server and wait on it in the **same** bridge-hosted JS execution. Starting it in one Node REPL call and waiting in another loses the first call's browser execution context. Keep that single call active while Python runs. If it returns first, browser operations can fail with `node_repl exec context not found`.
 
 ## `login_required`
 
@@ -80,6 +80,13 @@ loaded and the SDK refused to append. Pass `newTask: false` only when the user
 intends to continue that exact task. If a Work submission returns partial or
 timeout, use `work.status`, `work.wait`, or `work.readLatest`; do not resubmit.
 
+On the current home page, inspect the `Select chat surface` Chat/Work radio
+group before diagnosing Work as unavailable. Once a Work task is active, that
+radio group can disappear; the compound model-plus-effort opener is the SDK's
+continuation evidence, while the visible Work task chrome can corroborate a
+manual diagnosis. `experience.open` returns to the home selector before
+changing panes from an active task.
+
 ## Existing Tab Not Found Or Ambiguous
 
 When `existingTab` targeting cannot select one already-open tab, inspect `blocker.diagnostics.existingTab` or the rendered blocker explanation. Diagnostics are metadata-only: requested target, whether user-open tabs were available, candidate tab IDs, URLs, titles, conversation IDs, omitted candidate count, and mismatch reason. They must not include page text or chat content.
@@ -144,6 +151,14 @@ const final = await chatgpt.messages.readLatest({ format: "markdown" });
 
 Active generation may appear as a visible or accessible-name control such as `Stop answering`, `Stop generating`, or `Stop streaming`. Stopped generation may appear as `Stopped thinking`. Treat all of those as incomplete states.
 
+If the caller explicitly supersedes a running request, use `messages.stop({ confirmStop: true })`. The command does nothing when generation is observably inactive and fails closed when it cannot inspect the state, uniquely activate the visible composer stop control, or verify the inactive postcondition. Do not use it as an automatic timeout-recovery retry mechanism.
+
+If Stop returns `stop_generation_unverified` with `resumable: false`, the activation began but its outcome is unknown. The browser request has been terminated and cannot click later, although the click may already have taken effect. Inspect the visible generation state before any further action; never retry Stop automatically.
+
+If attachment returns `attachment_outcome_indeterminate` with `resumable: false`, the native handoff began but the file's composer state is unknown. The browser request has been terminated and cannot attach later, although the file may already be present. Inspect the current composer, do not submit, and do not retry automatically.
+
+The Codex Chrome file chooser does not expose its backing input. This is expected: the SDK proves the unique active-composer trigger before opening the chooser and uses any provider-specific backing-element accessor only as an additional cross-check. A missing chooser `element()` method by itself is not an upload failure.
+
 When the outer host tool-call ceiling is short, poll in bounded chunks instead of issuing a single very long wait:
 
 ```ts
@@ -161,7 +176,14 @@ When ChatGPT exposes previous/next response controls, `readLatest` and `copyLate
 
 ## Download Unavailable
 
-The command only downloads visible files with a download affordance. If no download control exists, ask ChatGPT to create or expose the file again.
+The command only downloads visible files with a download affordance. Current
+ChatGPT file answers may first expose a filename-labelled button; the SDK opens
+that artifact preview and then uses its visible Download control. When the
+expected filename is known, pass a case-insensitive regular expression such as
+`filenamePattern: "^report\\.csv$"`. A `download_filename_not_found` blocker
+means no visible assistant file matched; the SDK deliberately did not accept an
+unrelated image fallback. If no download control exists, ask ChatGPT to create
+or expose the file again.
 
 ## Redacted Reports