# Code Remote Manager Roadmap

## Vision

Operate local Codex safely from a phone without uploading credentials or replacing Codex's durable local thread history. The PWA provides a compact mobile control surface while the Windows PC remains the execution host.

## Pre-Release Gate

Status as of 2026-08-01: public distribution is **NO-GO** for the Windows host,
Tailscale remote-control surface, Google Play and Apple App Store. See the
[dated audit](docs/audits/2026-07-17-pre-release-audit.md), the
[active checklist](docs/PRE_RELEASE_CHECKLIST.md) and the
[documentation guide](docs/README.md).

The 2026-07-12 internal correctness gate remains a regression baseline, not
public-release approval. The following issues were implemented and covered by
automated regression tests at that checkpoint:

- Restored or externally watched sessions keep queued work blocked until an
  explicit operator action.
- Every queued message preserves the execution account selected when it was
  queued, including safe cross-account handoff.
- PWA send, upload, approval, account, and Changes results are scoped by session
  and request so late responses cannot replace another active Chat's state.
- Unknown-workspace Chats require an explicit workspace choice before sending,
  and partial refresh failures preserve the selected execution account.
- Approval decisions update state consistently and are serialized so duplicate
  or conflicting decisions cannot reach the runtime.
- Removing the last visible account persists an empty account configuration that
  remains valid after backend restart.
- History, session, SSE, Changes, error, tool-call, and persisted data pass the
  final safe projection. Live local API and SSE responses exposed no absolute
  path or credential patterns during the target-device rehearsal.
- Safe-runtime source copying combines explicit credential/runtime exclusions
  with the repository's actual Git ignore rules.
- Safe-runtime waits for child shutdown, allows enough time for real account
  app-server startup, verifies rollback recovery, and keeps bounded redacted
  logs.

Internal target-device evidence completed on 2026-07-12:

- Regression tests for every gate above, followed by the full required suite.
- Configured Tailscale Serve exposed the PWA port while the backend port remained
  absent from the Serve configuration, and the exact HTTPS URL returned the PWA
  without a Vite host-allowlist rejection.
- Safe-runtime install, verified update, previous-release rollback, service
  recovery, and reapplication all completed with the real local configuration.
- A temporary backup and isolated recovery of local configuration and runtime
  data produced matching hashes for every copied file; rehearsal copies were
  removed afterward and private data remained outside release copies and logs.

The 2026-07-17 audit adds public-release blockers that the earlier regression
gate did not cover: app-level authentication and a permission ceiling,
message/approval idempotency, Windows installed-layout dependencies and safe
configuration migration, signed and reproducible artifacts, attachment/log/data
lifecycle controls, public legal/support pages, and synthetic store-review access.

Windows and Android `0.2.0` release baselines now exist, and the source metadata is
aligned for the free `1.0.0` launch. The unsigned Windows
candidate passed clean-user install, upgrade, restart and uninstall rehearsal. A
signed Android candidate passed manifest, SDK, four-ABI, 64-bit, 16 KB and real-device
connection checks. The later synthetic store-review source is verified but has not
yet been folded into a final signed package. Store copy remains an
[unapproved draft](docs/STORE_LISTING.md).

P0 authentication, permission ceilings, idempotency, attachment and data lifecycle,
redaction, Tailnet restrictions, installed-layout checks, public policy links and review
access are regression baselines. The active execution order lives only in the
[pre-release checklist](docs/PRE_RELEASE_CHECKLIST.md). The Android `1.0.0` launch is a
free download with one optional non-consumable Google Play purchase: Pro unlocks up to
five configured execution accounts while the free app keeps every Codex remote-control
capability and one execution account. It has no CRM membership account or Google Sign-In.
The approved security and operations design must be implemented before fresh packaging,
signing, purchase and restore tests, new-install device smoke, policy alignment and
explicit store-submission approval.

Subscriptions remain deferred until after the first Android launch and require their own
recurring value and security design. Any later CRM identity must remain separate from
every OpenAI/Codex execution account. The first Android Pro purchase uses Play purchase
restoration and a purchase-token verifier without a Code Remote membership account. The
verifier never authorizes public exposure of the local Codex backend or history. iOS
application implementation, StoreKit, signing and submission remain a separate later
macOS/Xcode project.

## Current State

The local development MVP is operational.

- Account-scoped Codex homes, in-app device-code login, safe account identity/status, and explicit execution-account selection.
- Unified, newest-first Chats from visible and history-only sources, with partial-source failure handling, search, pagination, project grouping, pin, rename, and archive.
- Logical Chat continuity across execution-account changes: only visible conversation context is handed to a new account-owned thread, while internal thread references remain grouped as one Chat.
- Desktop Codex history projection with safe project labels and readable unknown-workspace history; sending requires an attached allowlisted workspace.
- Durable `thread/start`, `thread/list`, `thread/read`, lazy `thread/resume`, external-thread polling while viewed, and turn interruption.
- Runtime session persistence without automatic work execution after backend restart. Active states restore as interrupted and queued messages remain explicit.
- Streaming turns with compact activity, elapsed time, plans, commands, file changes, safe reasoning summaries, queued messages, and explicit steering/deletion.
- Composer capability discovery for models, permissions, plugins, and skills; model/effort controls, permission presets, plan mode, multi-image input, draft recovery, auto-resize, and browser speech input.
- Real command, file-change, and additional-permission approvals.
- Changed-file and diff views for allowlisted workspaces.
- Account quota/reset, active-thread context use, cross-chat approval/completion notifications, and per-chat status indicators.
- Quick project discovery and creation under configured `projectsRoot`, plus opaque-ID PC folder browsing for explicitly registering another workspace without exposing absolute paths.
- Installable PWA metadata and shell caching.
- Feature-owned PWA components, hooks, API adapters, state, and CSS; `App.jsx` remains the composition root.
- Mobile `100dvh` shell, internal conversation scrolling, safe-area composer, 16px inputs, and 48px touch targets.
- Setup-issued QR/code device pairing, per-device credential persistence/rotation/revocation, and
  authenticated HTTP/SSE access with browser CSRF and exact-Origin enforcement.
- A Backend-enforced local permission ceiling; installed defaults allow every built-in mode while
  each new Chat still starts with workspace write and approval on request.
- Durable bounded action receipts for messages, queued steer/delete actions and approvals; PWA
  retries keep the same action identity while new operator actions receive a new UUID.
- Server-validated image attachments with bounded message quotas, restart recovery, per-file
  deletion, abandoned-upload cleanup and opaque browser-visible references.
- Bounded redacted production logs plus explicit device-local and installed-PC application-data
  reset boundaries that do not delete Codex or external account data.

## Runtime Topology

```text
Phone browser
  -> manually configured Tailscale Serve / local Vite (127.0.0.1:43111)
  -> same-origin /api proxy
  -> Node backend (127.0.0.1:43110)
  -> selected account's Codex app-server
  -> account CODEX_HOME + allowlisted workspace
```

Codex app-server owns durable thread history. Backend session JSON is a runtime/SSE/approval cache plus logical Chat linkage; it must not restart work automatically.

## Current HTTP API

Except for `GET /health`, `POST /auth/pair`, and CORS preflight, the API requires a paired-device
credential. Browser mutations also require CSRF and exact-Origin checks; both SSE streams require
an exact Origin.

- Health/context: `GET /health`, `/codex/health`, `/accounts`, `/workspaces`, `/project-folders`
- Account management: `POST /accounts`, `POST /accounts/:id/login`, `PATCH|PUT|DELETE /accounts/:id`
- Usage/capabilities: `GET /accounts/:id/usage`, `GET /accounts/:id/capabilities`
- History: `GET /threads`, `GET /accounts/:id/threads`, thread open, rename, pin, and archive routes
- Projects: `POST /workspaces`
- Sessions: list/create/read, SSE events, messages, stop, queued-message steer/delete, image attachments, approvals, files, and diff routes

## Ordered Next Stages

### 1. Runtime and Security Hardening

- Keep persisted message, queue and approval idempotency covered as the runtime and PWA evolve.
- Add end-to-end coverage for account handoff, unified history, external-thread continuation, approvals, and 390x844 layout; keep the completed attachment restart/lifecycle integration as a regression gate.
- Keep every HTTP, SSE, persisted-error, approval, app-server and operational-log failure path covered for credential and local-path redaction.
- Validate account/workspace context consistently, including history-only execution attempts and stale local configuration.
- Resolve remaining mixed-language and technical `thread` copy in user-facing screens.

Definition of done: security invariants are covered by reproducible tests, real Codex runtime checks pass, and browser-visible failures expose no credential or unapproved local-path data.

### 2. Windows Operation

- Keep the experimental safe-development supervisor separate from the public
  release path; it can run an independent copy, accept manual updates, restart
  failed processes, and roll back failed health checks.
- Make the existing packaged host self-contained and require an isolated
  installed-layout health smoke before producing an installer.
- Run Backend and PWA as one supervised packaged process or another explicitly
  designed managed Windows topology.
- Add startup-on-login, health monitoring, controlled restart, and bounded local log retention.
- Keep interrupted work recoverable without automatic re-execution.

Definition of done: closing development terminals or rebooting Windows does not permanently stop remote access; failures are observable and safely recoverable.

### 3. Remote Transport

- Keep Tailscale Serve as the baseline private transport and move machine-specific host configuration out of tracked source.
- Evaluate another tunnel or relay only with explicit authentication, authorization, TLS, CSRF, rate-limit, and secret-management design.
- Preserve the current thread/session API boundary so transport can change independently.

Definition of done: the chosen transport has a documented threat model and remote access works without exposing backend ports or credentials publicly.

### 4. Packaging and Onboarding

- Repair the existing Windows installer payload, configuration migration,
  rollback, signing and license inventory.
- Turn the existing Android Capacitor project into an asset-synchronized, signed
  and device-verified release pipeline.
- Replace hand-edited paths and Vite host settings with onboarding for Codex CLI, account homes, Desktop history, project root, workspace allowlist, and transport.
- Add safe config validation and diagnostics.

Definition of done: a clean Windows machine can install, upgrade, authenticate,
configure, operate and uninstall the host without source edits or configuration
loss, and the target mobile package connects through the reviewed onboarding flow.

### 5. Free 1.0.0 Launch

- Build one verified source, Windows and Android candidate set from the synchronized
  `1.0.0` metadata and Android `versionCode`.
- Repackage and sign the final Android bundle, then verify a new installation on a real
  device and align the store-review instructions with that exact binary.
- Keep the current store listing and public policies accurate for a free app with no
  in-app purchase or CRM membership account.

Definition of done: the final free `1.0.0` candidate passes manifest, installed-layout,
clean-user, signed Android device, review-demo and store-submission gates.

### 6. App Subscription Foundation

- Sell subscriptions only inside the mobile apps, beginning with Android Play Billing.
- Keep CRM identity and entitlement data separate from Codex accounts, credentials, local
  threads and workspaces; complete a dedicated hosted-service security design first.
- Use a common entitlement state model and platform adapter so a later iOS StoreKit
  implementation does not require rewriting Android or Windows authorization.
- Let Windows consume only a minimal server-verified entitlement projection and never trust
  a client-provided paid flag, receipt or purchase token.

Definition of done: the product rules, identity lifecycle, threat model, store verification,
restore, refund, grace, expiry, offline and deletion behavior are approved and represented by
the ordered patches in the active checklist.

### 7. Release Maintenance

- Define backup/migration for session metadata, thread preferences, attachments, and local configuration.
- Review dependency pinning and update policy.
- Add safe failure telemetry only if it preserves the personal/local security boundary.

Definition of done: upgrades are reproducible and preserve local history and configuration without expanding data exposure.

## Known Limits

- The verified Windows and Android `0.2.0` artifacts are baselines, not the final free
  `1.0.0` package. Fresh packaging, signing and device smoke remain release gates.
- Tailscale Serve and Vite host allowlisting are manual local setup and not verified by the automated suite.
- The service worker caches the application shell only; Codex work is not available offline.
- Speech input depends on browser support.
- Service-tier, personality, and plugin controls are not exposed, and reported skill selection lacks verified end-to-end invocation.
- Historical inactive chats may show context usage as `Unavailable` until app-server supplies usage.
- Physical-device packet-loss/reconnect and clean-machine runtime rehearsals remain manual gates.
- This is a personal single-operator system with paired-device authentication, not a public
  multi-user identity or tenancy system.

## Explicit Non-Goals for the Local MVP

- Public unauthenticated hosting.
- iOS/App Store delivery as part of the local MVP; it remains a separate later project.
- Shared workspaces, public Codex tenancy, or using CRM subscription identity as a Codex account.
- Cloud relay storage of Codex history or credentials.
- Automatic approval of commands, permissions, or file changes.
- Automated PR or deployment execution.
