codex-chatgpt-control 0.2.0-alpha.1 → 0.5.0-alpha.1

package/dist/src/types.d.ts

@@ -1,4 +1,6 @@
 export type CommandStatus = "ok" | "partial" | "timeout" | "blocked" | "needs_confirmation" | "not_found" | "unsupported" | "error";
+export type SubmissionState = "not_submitted" | "submitted" | "submitted_unconfirmed" | "submitted_generating";
+export type CompletionState = "complete" | "generating" | "stopped" | "partial" | "unknown";
 export type BlockerKind = "browser_bridge_unavailable" | "login_required" | "captcha" | "rate_limit" | "modal" | "permission" | "confirmation" | "selector_drift" | "artifact_unavailable" | "artifact_selector_drift" | "artifact_download_unavailable" | "download_unavailable" | "upload_failed" | "not_found" | "unknown";
 export type CommandContext = {
     url?: string;
@@ -6,6 +8,8 @@ export type CommandContext = {
     title?: string;
     turnCount?: number;
     assistantTurnCount?: number;
+    experience?: ChatGPTExperience;
+    selectorProfile?: SurfaceSelectorProfile;
     browserName?: string;
     tabId?: string;
     timestamp: string;
@@ -174,6 +178,10 @@ export type SubmitData = {
     submitted: boolean;
     userTurnText?: string;
     turnCount?: number;
+    submissionState?: SubmissionState;
+    completionState?: CompletionState;
+    generationActive?: boolean;
+    generationSignals?: string[];
 };
 export type WaitArgs = {
     afterTurnCount?: number;
@@ -183,12 +191,19 @@ export type WaitArgs = {
     stableMs?: number;
     pollMs?: number;
     mode?: "normal" | "deep_research";
+    responseContent?: "include" | "metadata";
 };
 export type WaitData = {
     complete: boolean;
     responseText?: string;
+    responseChars?: number;
+    responseSha256?: string;
+    responseContent?: "include" | "metadata";
     assistantTurnCount: number;
     elapsedMs: number;
+    completionState?: CompletionState;
+    generationActive?: boolean;
+    generationSignals?: string[];
 };
 export type ResponseFormat = "markdown" | "text" | "normalized_text" | "visible_text" | "html" | "blocks" | "all";
 export type ResponseCitation = {
@@ -273,10 +288,14 @@ export type ReadLatestData = {
     actions?: ResponseAction[];
     thoughtDurationText?: string;
     sourcesAvailable?: boolean;
+    completionState?: CompletionState;
+    generationActive?: boolean;
+    generationSignals?: string[];
 };
 export type WaitAndReadArgs = WaitArgs & ReadLatestArgs;
 export type AskArgs = {
-    text: string;
+    text?: string;
+    prompt?: string;
     wait?: boolean | WaitArgs;
     read?: boolean | ReadLatestArgs;
     timeoutMs?: number;
@@ -287,10 +306,30 @@ export type AskReadData = {
     complete?: boolean;
     conversationId?: string;
     title?: string;
+    submissionState?: SubmissionState;
+    completionState?: CompletionState;
+    generationActive?: boolean;
+    generationSignals?: string[];
+};
+export type MessageStatusArgs = {
+    maxPreviewChars?: number;
+};
+export type MessageStatusData = {
+    turnCount?: number;
+    assistantTurnCount: number;
+    latestAssistantTurnIndex?: number;
+    latestAssistantText?: string;
+    latestAssistantPreview?: string;
+    latestAssistantTextLength?: number;
+    completionState: CompletionState;
+    generationActive: boolean;
+    generationSignals: string[];
 };
 export type AttachFilesArgs = {
     paths: string[];
     timeoutMs?: number;
+    includeDiagnostics?: boolean;
+    includeHashes?: boolean;
 };
 export type AttachedFile = {
     path: string;
@@ -302,11 +341,13 @@ export type FilePreflightArgs = {
     paths: string[];
     maxBytesPerFile?: number;
     maxTotalBytes?: number;
+    includeHashes?: boolean;
 };
 export type FilePreflightFile = AttachedFile & {
     extension: string;
     mimeType: string;
     category: FileCategory;
+    sha256?: string;
 };
 export type FilePreflightData = {
     files: FilePreflightFile[];
@@ -314,6 +355,20 @@ export type FilePreflightData = {
 };
 export type AttachFilesData = {
     files: AttachedFile[];
+    diagnostics?: FileUploadDiagnostics;
+};
+export type BrowserInputFileDiagnostic = {
+    name: string;
+    size: number;
+    type?: string;
+    lastModified?: number;
+};
+export type BrowserInputDiagnostic = {
+    files: BrowserInputFileDiagnostic[];
+};
+export type FileUploadDiagnostics = {
+    preflight: FilePreflightData;
+    browserInput?: BrowserInputDiagnostic;
 };
 export type ProjectSourceStatus = "ready" | "processing" | "failed" | "unknown";
 export type ProjectSource = {
@@ -460,6 +515,178 @@ export type SetModeArgs = {
     version?: string;
     timeoutMs?: number;
 };
+export type GetModeArgs = {
+    timeoutMs?: number;
+};
+export type GetModeData = {
+    modes: string[];
+};
+export type ChatGPTExperience = "chat" | "work" | "unknown";
+export type SurfaceSelectorProfile = "chat_legacy_v1" | "chat_simplified_v1" | "work_basic_v1" | "work_advanced_v1" | "unknown";
+export type SurfaceProfileSupportState = "current" | "compatibility" | "unverified" | "retired";
+export type SurfaceProfileObservation = {
+    observedAt: string;
+    provenance: string;
+    locale: string;
+    region: string;
+    accountScope: string;
+    planScope: string;
+    workspaceScope: string;
+    supportState: SurfaceProfileSupportState;
+};
+export type ExperienceConfidence = "high" | "medium" | "low";
+export type ExperienceEvidence = {
+    source: "url" | "composer" | "control" | "menu" | "heading";
+    label: string;
+};
+export type DetectExperienceArgs = {
+    timeoutMs?: number;
+};
+export type DetectExperienceData = {
+    experience: ChatGPTExperience;
+    selectorProfile: SurfaceSelectorProfile;
+    confidence: ExperienceConfidence;
+    evidence: ExperienceEvidence[];
+};
+export type OpenExperienceArgs = {
+    experience: Exclude<ChatGPTExperience, "unknown">;
+    timeoutMs?: number;
+};
+export type OpenExperienceData = {
+    experience: Exclude<ChatGPTExperience, "unknown">;
+    previousExperience: ChatGPTExperience;
+    changed: boolean;
+    selectorProfile: SurfaceSelectorProfile;
+};
+export type ConfigurationAxis = "model" | "intelligence" | "effort" | "speed" | "modelVersion";
+export type SurfaceProfileFixture = SurfaceProfileObservation & {
+    schemaVersion: "chatgpt.browser_control.surface_profile.v1";
+    id: string;
+    snapshot: {
+        url: string;
+        composerLabels: string[];
+        mainControls: string[];
+        mainText: string;
+    };
+    panel: {
+        openerLabel?: string;
+        axisRows: Array<{
+            axis: ConfigurationAxis;
+            label: string;
+            value?: string;
+        }>;
+        advancedVisible: boolean;
+    };
+    menuItems: Array<{
+        label: string;
+        normalized: string;
+        role?: string;
+        checked?: boolean;
+        expanded?: boolean;
+        hasPopup?: boolean;
+        testId?: string;
+        ariaLabel?: string;
+    }>;
+    expected: {
+        experience: ChatGPTExperience;
+        selectorProfile: SurfaceSelectorProfile;
+        availableAxes: ConfigurationAxis[];
+        active: Partial<Record<ConfigurationAxis, string>>;
+    };
+};
+export type ConfigurationOption = {
+    id: string;
+    label: string;
+    selected: boolean;
+    disabled?: boolean;
+    description?: string;
+    hasSubmenu?: boolean;
+};
+export type ConfigurationSelection = {
+    model?: string;
+    intelligence?: string;
+    effort?: string;
+    speed?: string;
+    modelVersion?: string;
+    /** Backward-compatible alias for modelVersion. */
+    version?: string;
+};
+export type InspectConfigurationArgs = {
+    experience?: Exclude<ChatGPTExperience, "unknown">;
+    includeOptions?: boolean;
+    timeoutMs?: number;
+};
+export type ConfigurationInspectionData = {
+    experience: ChatGPTExperience;
+    selectorProfile: SurfaceSelectorProfile;
+    availableAxes: ConfigurationAxis[];
+    active: Partial<Record<ConfigurationAxis, string>>;
+    options: Partial<Record<ConfigurationAxis, ConfigurationOption[]>>;
+    verified: boolean;
+    evidence: ExperienceEvidence[];
+};
+export type ApplyConfigurationArgs = {
+    experience?: Exclude<ChatGPTExperience, "unknown">;
+    desired: ConfigurationSelection;
+    strict?: boolean;
+    timeoutMs?: number;
+};
+export type AppliedConfigurationSelection = {
+    axis: ConfigurationAxis;
+    requested: string;
+    selected: string;
+};
+export type ApplyConfigurationData = {
+    requested: ConfigurationSelection;
+    selected: AppliedConfigurationSelection[];
+    before: ConfigurationInspectionData;
+    after: ConfigurationInspectionData;
+    verified: boolean;
+};
+export type WorkTaskRef = {
+    url?: string;
+    conversationId?: string;
+    title?: string;
+    baselineTurnCount?: number;
+    baselineAssistantTurnCount?: number;
+};
+export type StartWorkArgs = {
+    prompt: string;
+    /** Start from a blank Work task when possible. Defaults to true. */
+    newTask?: boolean;
+    files?: string[];
+    configuration?: ConfigurationSelection;
+    wait?: boolean | WaitArgs;
+    read?: boolean | ReadLatestArgs;
+    timeoutMs?: number;
+};
+export type StartWorkData = {
+    task: WorkTaskRef;
+    submitted: SubmitData;
+    configuration?: ApplyConfigurationData;
+    wait?: WaitData;
+    response?: ReadLatestData;
+};
+export type WorkStatusArgs = MessageStatusArgs & {
+    includeArtifacts?: boolean;
+};
+export type WorkStatusData = {
+    experience: "work";
+    task: WorkTaskRef;
+    message: MessageStatusData;
+    artifacts?: ArtifactListData;
+};
+export type WorkWaitArgs = WaitArgs;
+export type WorkWaitData = WaitData;
+export type SteerWorkArgs = {
+    prompt: string;
+    wait?: boolean | WaitArgs;
+    read?: boolean | ReadLatestArgs;
+    timeoutMs?: number;
+};
+export type SteerWorkData = AskReadData;
+export type ReadWorkLatestArgs = ReadLatestArgs;
+export type ReadWorkLatestData = ReadLatestData;
 export type SelectToolArgs = {
     tool: "web_search" | "deep_research" | "create_image" | string;
     timeoutMs?: number;
@@ -468,6 +695,42 @@ export type SequenceStep = {
     id: string;
     command: "session.bootstrap";
     args?: BootstrapArgs;
+} | {
+    id: string;
+    command: "experience.detect";
+    args?: DetectExperienceArgs;
+} | {
+    id: string;
+    command: "experience.open";
+    args: OpenExperienceArgs;
+} | {
+    id: string;
+    command: "configuration.inspect";
+    args?: InspectConfigurationArgs;
+} | {
+    id: string;
+    command: "configuration.apply";
+    args: ApplyConfigurationArgs;
+} | {
+    id: string;
+    command: "work.start";
+    args: StartWorkArgs;
+} | {
+    id: string;
+    command: "work.status";
+    args?: WorkStatusArgs;
+} | {
+    id: string;
+    command: "work.wait";
+    args?: WorkWaitArgs;
+} | {
+    id: string;
+    command: "work.steer";
+    args: SteerWorkArgs;
+} | {
+    id: string;
+    command: "work.readLatest";
+    args?: ReadWorkLatestArgs;
 } | {
     id: string;
     command: "threads.search";
@@ -500,6 +763,10 @@ export type SequenceStep = {
     id: string;
     command: "messages.readLatest";
     args?: ReadLatestArgs;
+} | {
+    id: string;
+    command: "messages.status";
+    args?: MessageStatusArgs;
 } | {
     id: string;
     command: "messages.waitAndRead";
@@ -571,6 +838,7 @@ export type RuntimeEnv = {
     page?: PageLike;
     clipboard?: ClipboardLike;
     now?: () => Date;
+    expectedTabId?: string;
 };
 export type ClipboardLike = {
     read: () => Promise<string>;
@@ -628,6 +896,8 @@ export type WaitForEventOptions = {
     timeoutMs?: number;
 };
 export type PageLike = {
+    id?: string;
+    tabId?: string;
     url?: () => string | Promise<string>;
     goto?: (url: string, options?: unknown) => Promise<unknown>;
     title?: () => Promise<string>;
@@ -666,7 +936,8 @@ export type PageLike = {
         [key: string]: unknown;
     };
 };
-export type AskHelperArgs = AskArgs & {
+export type AskHelperArgs = Omit<AskArgs, "text" | "prompt"> & {
+    text: string;
     thread?: ThreadTarget;
 };
 export type AskInThreadArgs = AskHelperArgs & {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codex-chatgpt-control",
-  "version": "0.2.0-alpha.1",
-  "description": "Unofficial SDK for Codex agents controlling visible ChatGPT web sessions.",
+  "version": "0.5.0-alpha.1",
+  "description": "Unofficial SDK for controlling visible ChatGPT Chat and Work sessions.",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -34,6 +34,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "thread": "tsx src/scripts/continue-thread.ts",
+    "capture:surface-profile": "tsx src/scripts/capture-surface-profile.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",
@@ -74,7 +75,7 @@
   "devDependencies": {
     "@types/node": "^24.13.1",
     "ajv": "^8.17.1",
-    "esbuild": "^0.28.0",
+    "esbuild": "^0.28.1",
     "tsx": "^4.20.0",
     "typescript": "^5.8.0",
     "vitest": "^4.1.8"

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

@@ -0,0 +1,87 @@
+---
+title: Chat and Work Surfaces
+date: 2026-07-16
+type: reference
+status: draft
+---
+
+# Chat and Work Surfaces
+
+The SDK models visible ChatGPT as capabilities discovered from the active
+composer, controls, and URL—not as one flat model picker.
+
+## Experiences And Profiles
+
+Experiences:
+
+- `chat`
+- `work`
+- `unknown`
+
+Observed selector profiles:
+
+- `chat_legacy_v1`
+- `chat_simplified_v1`
+- `work_basic_v1`
+- `work_advanced_v1`
+- `unknown`
+
+Profiles describe UI shape. They must not be presented as subscription plans,
+entitlements, regions, or guaranteed underlying models. Sanitized fixtures
+store observed date, locale, provenance, scoped surface evidence, visible
+configuration, and expected semantic output without conversation content.
+
+## Configuration
+
+Chat may expose intelligence and nested model/version controls. Work exposes
+model, effort, and speed axes. Inspection reports available axes, active values,
+visible options, selector profile, and evidence.
+
+Strict application:
+
+1. detects or opens the requested experience;
+2. inspects the current state;
+3. changes only requested axes;
+4. reopens nested controls as required;
+5. inspects again;
+6. blocks if every requested value is not visibly verified.
+
+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 })`.
+
+## Work Lifecycle
+
+`work.start` defaults to `newTask: true`. If messages are already loaded and a
+unique new-task control cannot be verified, it blocks rather than submitting
+into the current task. `newTask: false` is an explicit request to continue the
+currently visible task.
+
+Submission uses matching-turn recovery. A no-op send click may be retried only
+while the prompt remains in the composer and no matching user turn exists.
+After a partial or timeout result, callers must preserve the task/thread
+identity and use:
+
+- `work.status`
+- `work.wait`
+- `work.steer`
+- `work.readLatest`
+- `work.artifacts.*`
+
+The original prompt must not be blindly resubmitted.
+
+## Locale And Rollout Policy
+
+Shared semantic types and profile fixtures make locale and rollout support
+incremental. New labels require sanitized evidence plus locale-registry and
+fixture updates. Unknown or absent controls return structured capability or
+selector-drift results.
+
+Use `npm run capture:surface-profile -- --id <normalized-id>` against an
+already-open authorized tab to create a local `unverified` draft. The capture
+is read-only with respect to configuration, strips conversation identity and
+content, and requires explicit normalized metadata before a fixture can be
+promoted to `current` or `compatibility`.
+
+The SDK does not spoof regions, guess account plans, infer effective models from
+one label, or claim support for a native desktop surface from web fixtures.

package/references/agents-runner.md

@@ -11,11 +11,14 @@ const chatgpt = createChatGPT({ agent: globalThis.agent });
 const reviewer = chatgpt.agent({ name: "reviewer", instructions: "Review deeply." });
 const plan = chatgpt.runner.plan(reviewer, {
   input: "Review this design.",
-  thread: { type: "new" }
+  thread: { type: "new" },
+  experience: "chat"
 });
 const result = await chatgpt.runner.run(reviewer, {
   input: "Review this design.",
-  thread: { type: "new" }
+  thread: { type: "new" },
+  experience: "chat",
+  configuration: { intelligence: "Pro" }
 });
 ```
 
@@ -27,6 +30,14 @@ const result = await chatgpt.runner.run(reviewer, {
 
 `runner.run()` returns a `ChatGPTRunResult` with `output_text`, `finalOutput`, `output`, `interruptions`, and `state`. Browser-control blockers are surfaced as resumable interruptions when the underlying command can be retried after user approval, login, or permission repair.
 
+`experience` and `configuration` are visible product preferences. When present,
+the plan emits `experience.open` and strict `configuration.apply` steps before
+the prompt. Successful results expose `experience.opened` and
+`configuration.applied` milestone items. The legacy `mode` input remains
+supported, but new callers should use the surface-aware fields. If both are
+present, `configuration` takes precedence and the legacy `mode` request is not
+executed.
+
 For milestone streaming, call `chatgpt.runner.run(agent, input, { stream: true })` and iterate events before awaiting `stream.completed`. This is milestone streaming only, not token-delta streaming.
 
 Do not pass API-only model controls such as `temperature`, `logprobs`, `seed`, or hidden system instructions.

package/references/backend-protocol.md

@@ -67,7 +67,9 @@ Current protocol error codes are:
 
 Browser-control blockers are not protocol errors. They are normal command or runner results with `status: "blocked"`, `status: "partial"`, or `status: "needs_confirmation"` plus blocker/interruption details.
 
-`status: "partial"` is the required result for incomplete response capture. A partial result may still include `output_text` and `data.responseText`, but consumers must treat that text as incomplete until a later wait confirms completion. Common causes are wait timeout after partial assistant text, active generation controls such as `Stop answering`, stopped-generation markers such as `Stopped thinking`, or a read fallback after the wait step could not confirm completion. Intentional capture clipping uses `data.captureLimit` plus warnings; it is separate from ChatGPT generation length.
+`status: "partial"` is the required result for incomplete response capture. A partial result may still include `output_text` and `data.responseText`, but consumers must treat that text as incomplete until a later wait confirms completion. Common causes are wait timeout after partial assistant text, active generation controls such as `Stop answering`, stopped-generation markers such as `Stopped thinking`, or a read fallback after the wait step could not confirm completion. Message command data may include `submissionState`, `completionState`, `generationActive`, and `generationSignals`; `completionState: "generating"` or `generationActive: true` is explicit evidence that the visible ChatGPT turn is still running. For status-only polling, `messages.wait` accepts `responseContent: "metadata"`; partial and completed wait results then omit assistant text and instead return compact metadata such as `data.responseChars` and `data.responseSha256`. Intentional capture clipping uses `data.captureLimit` plus warnings; it is separate from ChatGPT generation length.
+
+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.
 
 ## Streaming
 
@@ -78,9 +80,10 @@ Streaming commands emit backend event lines until `completed` or `error`.
   "schemaVersion": "chatgpt.browser_control.backend_event.v1",
   "requestId": "req_stream",
   "type": "run_item_stream_event",
-  "name": "message_completed",
+  "name": "message_in_progress",
   "item": {
-    "type": "message.completed"
+    "type": "message.in_progress",
+    "completionState": "generating"
   }
 }
 ```
@@ -99,7 +102,7 @@ The final event contains a normal runner result:
 }
 ```
 
-Streaming is milestone streaming only. It does not promise token deltas or OpenAI API stream-event parity.
+Streaming is milestone streaming only. It does not promise token deltas or OpenAI API stream-event parity. Partial assistant text is emitted as `message_in_progress`; only completion-confirmed output is emitted as `message_completed`.
 
 ## Required Backend Commands
 
@@ -112,7 +115,14 @@ The backend must support:
 - diagnostics: `doctor`
 - reports: `createReport`, `reports.create`, `reports.redact`, `reports.summarize`
 - command discovery: `commands`, `describe`, `help`
-- primitives: `session.bootstrap`, `threads.*`, `messages.*`, `artifacts.*`, `files.preflight`, `files.attach`, `files.downloadLatest`, `projects.sources.list`, `projects.sources.planAdd`, `projects.sources.add`, `modes.set`, `tools.select`, `response.copy`
+- primitives: `session.bootstrap`, `experience.detect`, `experience.open`, `configuration.inspect`, `configuration.apply`, `work.start`, `work.status`, `work.wait`, `work.steer`, `work.readLatest`, `threads.*`, `messages.*`, `artifacts.*`, `files.preflight`, `files.attach`, `files.downloadLatest`, `projects.sources.list`, `projects.sources.planAdd`, `projects.sources.add`, `modes.set`, `modes.get`, `tools.select`, `response.copy`
+
+`experience.detect` and `configuration.inspect` are non-mutating capability
+discovery. `configuration.apply` is strict by default and must verify the final
+visible state. `work.start` defaults to a fresh task and must not append to a
+loaded task unless the caller explicitly passes `newTask: false`. A partial or
+timeout Work result is recovered through status/wait/read on the same task, not
+by resubmitting the original prompt.
 
 `doctor` returns a normal `CommandResult` whose `data.checks` map is extensible. Scenario checks such as `existing_tab`, `artifacts`, `file_preflight`, `localization`, and `reports` may add optional `code`, `blockerKind`, `nextCommand`, and JSON `details` fields to individual check entries while preserving the existing `status`, `message`, and `remediation` fields.
 
@@ -120,7 +130,9 @@ The backend must support:
 
 Attachment paths are interpreted on the machine running the Node backend. Use an absolute path in that host operating system's native form. On macOS/Linux/WSL, use paths such as `/example/user/file.pdf`, `/home/you/file.pdf`, or `/mnt/c/example/user/file.pdf`. On Windows backend hosts, use fully qualified paths such as `C:\Users\you\file.pdf` or UNC paths such as `\\server\share\file.pdf`. Drive-relative paths like `C:Users\you\file.pdf`, root-relative paths like `\tmp\file.pdf`, and Windows-looking paths sent to a POSIX backend are rejected before filesystem access.
 
-Use `files.preflight` for non-mutating local validation before browser upload workflows. It validates absolute paths, existence, readability, file-vs-directory status, configurable per-file and total byte limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses. It does not open ChatGPT, perform a live upload, or read file contents for MIME detection. `askWithFiles` and `files.attach` run the same preflight before upload attempts so obvious local file failures stop before browser interaction.
+Use `files.preflight` for non-mutating local validation before browser upload workflows. It validates absolute paths, existence, readability, file-vs-directory status, configurable per-file and total byte limits, duplicate basenames, duplicate resolved paths, zero-byte files, and extension-based MIME/category guesses. Zero-byte files are blocked before browser interaction because ChatGPT rejects empty attachments. By default the command does not open ChatGPT, perform a live upload, read file contents for MIME detection, or return file-content fingerprints. Callers may pass `includeHashes: true` to include SHA-256 metadata for local diagnostics; file contents are never returned. `askWithFiles` and `files.attach` run the same preflight before upload attempts so obvious local file failures stop before browser interaction.
+
+`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.
 
 ## Project Sources
 
@@ -213,7 +225,7 @@ Important: in Codex, `globalThis.agent` is not present until the Chrome plugin r
 The live Chrome bootstrap is:
 
 ```js
-const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/26.602.40724/scripts/browser-client.mjs");
+const { setupBrowserRuntime } = await import("/example/user/.codex/plugins/cache/openai-bundled/chrome/latest/scripts/browser-client.mjs");
 await setupBrowserRuntime({ globals: globalThis });
 globalThis.browser = await agent.browsers.get("extension");
 ```

package/references/language-coverage.md

@@ -5,6 +5,13 @@ 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.
+
 - Speaker counts are **crude guesstimates** (native + second-language, rounded), not
   researched figures. They exist only to prioritize the rollout.
 - `bcp47` is the suggested per-locale file name. Regional variants ChatGPT lists separately
@@ -113,6 +120,18 @@ guesstimate; the tail (≈#11–15) is close and easily reordered.
 
 ## Automated capture
 
+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
+```
+
+This command does not submit a prompt or change configuration. 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:
 
@@ -120,6 +139,23 @@ Use the repository capture script to drive the visible ChatGPT UI through Settin
 npm run capture:intelligence-locales -- --auto-switch --all --if-missing open
 ```
 
+To also capture localized running-generation controls such as `stopControl`, run the same
+sweep with the bounded generation probe enabled:
+
+```bash
+npm run capture:intelligence-locales -- \
+  --auto-switch \
+  --all \
+  --capture-generation-state \
+  --generation-timeout-ms 12000 \
+  --if-missing open
+```
+
+The generation-state probe submits one short real prompt per locale in the visible ChatGPT
+session, waits for the localized stop control, stops generation, and records only compact
+control/status labels. Use it only when operating the user's visible ChatGPT session is
+acceptable.
+
 The script uses the native language names from this tracker, verifies the rendered
 `document.documentElement.lang`, writes JSONL evidence under
 `outputs/intelligence-locale-captures/`, and restores the initially selected language by
@@ -134,9 +170,10 @@ changes the settings or picker DOM, the run should emit a blocker record instead
 3. Open the model switcher and the `+` menu with **real** clicks (Radix menus ignore
    synthetic `.click()`) and read the menu items → mode + tool labels.
 4. Open search → placeholder; observe a conversation → copy-response + response-actions.
-   `stopControl` is only present mid-generation; login/captcha/rate-limit copy needs a
-   logged-out/limited state — these may lag and rely on the English fallback + the
-   `selector_drift` safety net until captured.
+   `stopControl` is present only mid-generation and should be captured with
+   `--capture-generation-state`; login/captcha/rate-limit copy needs a logged-out/limited
+   state — these may lag and rely on the English fallback + the `selector_drift` safety net
+   until captured.
 5. Write the verified strings to `src/dom/locale/<bcp47>.ts` and register it in
    `src/dom/locale/index.ts`. Build + test + bundle + sync.
 6. Restore the account language to English (US) when the run is complete.