# ChatGPT Orchestrator — Implementation Plan

Status: active  
Date: 2026-08-19  
Authoritative spec: `SPEC.md`

## Outcome

Deliver a private TypeScript monorepo with:

- an MCP orchestration server for root/worker ChatGPT conversations;
- a durable manager/worker/event control plane;
- a Firefox-first, Chromium-compatible WebExtension as the ChatGPT-Web executor;
- an isolated ChatGPT DOM adapter;
- verification that never touches the user's active workstation browser display.

## Working rules

1. Spec-first: implementation conforms to `SPEC.md`; amend spec/plan before changing boundaries.
2. Do not touch the user's active Firefox/ChatGPT session for tests.
3. Browser/live E2E runs only on isolated buildbox displays/profiles (`debian1/2/3`) or another explicitly isolated environment.
4. Do not use private ChatGPT backend endpoints as the product seam.
5. Keep extension permissions narrow and control managed tabs only.
6. Push coherent milestones so interrupted work is recoverable.
7. Do not add Playwright/Selenium/CDP as a runtime dependency or product control path.

## Phase 0 — Repository + authoritative docs

### P0.1 Specification/plan

- [x] Define runtime topology and seams.
- [x] Define logical-worker/executor split.
- [x] Define MCP v0 surface.
- [x] Define extension executor protocol.
- [x] Define Firefox-first/Chromium-compatible posture.
- [x] Define security/reliability/testing boundaries.

### P0.2 Repository

- [ ] Create private `platform-modules/chatgpt-orchestrator`.
- [ ] Initialize `main` with plan/spec.
- [ ] Push docs before implementation starts.

Acceptance: private origin exists and docs commit is reachable at `origin/main`.

## Phase 1 — Monorepo skeleton + protocol

### P1.1 Workspace bootstrap

Create root `package.json`, `pnpm-workspace.yaml`, strict TS config, `.gitignore`, README, and package/app directories.

Baseline: Node.js 22+ and pnpm 11, matching the existing ChatGPT MCP stack unless a hard requirement forces a newer floor.

### P1.2 `packages/protocol`

Implement schemas/types for IDs, run/worker states, assignments/messages/events, executor commands/events, stable error codes, and protocol versioning.

Tests cover valid round trips, invalid IDs/states, version mismatch, deadlines, and idempotency requirements.

Acceptance: no MCP/browser dependency in protocol.

## Phase 2 — Orchestration core + persistence

### P2.1 State machine

Implement guarded transitions for run lifecycle, worker spawn/attach/progress/completion/failure, follow-up/reopen, interrupt/cancel, and messaging.

Every mutation emits a domain event transactionally through persistence.

### P2.2 Persistence

Implement a durable local adapter behind an interface. Prefer dependency-light storage and do not leak persistence types into the domain.

Tests cover restart recovery, monotonic event cursors, idempotency uniqueness, atomic mutation + event append, concurrent worker updates, and durable delivery to inactive recipients.

### P2.3 Wait broker

Implement bounded wait:

```text
wait(runId, afterCursor, timeoutMs)
 -> returns when cursor advances
 -> or timedOut=true at deadline
```

No busy loop.

Acceptance: synthetic root spawns workers, waits, receives child message, replies, and observes completion using core APIs only.

## Phase 3 — MCP server

### P3.1 Composition

Create `apps/mcp-server` using the MCP Node packages already proven by `chatgpt-mcp`.

Tools:

- `run.create/get/cancel`;
- `worker.spawn/attach/list/progress/complete/fail/interrupt/followup`;
- `message.send/broadcast`;
- `events.wait/list`.

### P3.2 Contracts

Every tool validates with shared schemas, returns structured output, has stable errors, and uses accurate annotations. Browser-specific details never leak into agent-facing tool contracts.

### P3.3 Bootstrap

Generate a versioned minimal worker bootstrap. Executor auth tokens/full assignment bodies never enter DOM prompts.

Acceptance: root/child lifecycle integration passes without a browser.

## Phase 4 — Executor bridge

### P4.1 Authenticated local endpoint

Add loopback WebSocket endpoint with high-entropy token, protocol-version handshake, executor instance ID, heartbeat/lease, command ACK + terminal result, reconnect/replay, and idempotent dispatch.

### P4.2 Queue

Map worker launch/follow-up actions into executor commands without introducing browser semantics into core worker state.

Acceptance: fake executor disconnects after ACK, reconnects, and completes without duplicate create/send.

## Phase 5 — Firefox-first WebExtension shell

### P5.1 Build

Create `apps/extension` with shared TS, generated Firefox/Chromium manifests, Mozilla WebExtension polyfill, background runtime, `chatgpt.com` content script, and minimal options/status page.

Outputs:

```text
dist/firefox/
dist/chromium/
```

### P5.2 Background executor

Implement authenticated connection, heartbeat/reconnect, managed tab registry, worker binding, command idempotency journal, and create/send/inspect/close routing.

Tests use mocked WebExtension APIs only.

### P5.3 Permission audit

Document manifest differences and keep permissions to the minimum required.

Acceptance: both distributions build/validate; background integration passes with fake content script.

## Phase 6 — ChatGPT Web adapter

### P6.1 DOM fixtures

Create sanitized/synthetic fixtures for new-chat-ready, generating, idle, conversation URL assigned, recoverable error, and changed/missing UI. Commit no personal conversation content.

### P6.2 Adapter

Implement semantic composer location, text insertion, submit, generation/idle detection, conversation-ID extraction, and fail-closed `HOST_UI_CHANGED` handling.

Rules: bounded MutationObserver, no eval/private network interception, no approximate clicking after invariant failure.

### P6.3 Content-script boundary

Expose typed adapter operations only. No generic arbitrary-DOM execution command.

Acceptance: all locator/failure paths covered by fixture tests without launching a browser.

## Phase 7 — Managed conversation lifecycle

### P7.1 Fresh launch

- open inactive ChatGPT tab;
- wait for content script ready;
- submit bootstrap exactly once;
- observe conversation identity;
- report binding/state.

### P7.2 Wake/resume

- queue while generating;
- send standard wake prompt when idle;
- preserve worker/conversation binding;
- report exactly-once delivery.

### P7.3 Recovery

Restore binding journal after extension restart; verify tabs/origins; report missing tabs; never adopt unrelated tabs by guess.

Acceptance: mocked create -> attach -> complete -> follow-up wake flow has no duplicate sends.

## Phase 8 — Isolated browser qualification

### P8.1 Buildbox browser environment

Use `debian1/2/3` only. Provision disposable Firefox profile/display with no workstation-browser impact.

### P8.2 Extension smoke without account

Prove package load, executor connection, tab management, controlled content-script injection, and fail-closed errors.

### P8.3 Deliberate authenticated ChatGPT smoke

After an isolated authenticated profile exists, create two real worker chats, verify bootstrap submission/binding, verify independent concurrent turns, and verify a wake prompt resumes an idle worker.

Store only IDs/state receipts, not arbitrary chat history.

### P8.4 Chromium smoke

Load Chromium build in isolated profile and prove create/send/bind flow.

Acceptance: no live test touches workstation display/session.

## Phase 9 — Full manager/worker proof

Scenario:

1. Root creates one run with two independent workers.
2. Extension launches both chats automatically.
3. Workers attach and retrieve different assignments.
4. Worker A asks root a question via MCP.
5. Root receives it through `events.wait` and replies.
6. Worker A receives the reply and completes.
7. Worker B completes independently.
8. Root issues follow-up work; extension wakes the correct idle existing chat.
9. Root waits for all terminal workers and synthesizes the result.

Acceptance: durable event trace proves all mappings; no manual chat creation/prompt copying.

## Phase 10 — Hardening/release

- concurrency/backpressure;
- executor token rotation;
- retention cleanup;
- crash/reconnect torture tests;
- extension permission review;
- stale DOM fail-closed tests;
- install/setup runbook;
- Firefox and Chromium packaged artifacts;
- compatibility matrix;
- README architecture/first-run guide.

MVP release is blocked on `SPEC.md` acceptance criteria.

## Immediate execution order

1. Finish P0 repository creation and push docs.
2. Bootstrap monorepo.
3. Implement/test `protocol`.
4. Implement core seam + persistence interface.
5. Implement first MCP vertical slice: `run.create`, `worker.spawn`, `worker.attach`, `events.wait`.
6. Commit/push that slice.
7. Add executor protocol/fake executor.
8. Start Firefox extension shell.

## Durable progress log

- 2026-08-19: specification and plan authored locally before repository creation.