Storage ownership

Separate the stores by owner #

The WebView asset protocol is scoped to media previews under the app cache only, so no private runtime file is reachable from the page.

Storage identity and execution identity differ #

An app-owned Codex profile has a stable opaque UUID that must be canonical lowercase text; an email address and a filesystem path are not profile identity. codex_session_links keys the link by app session and carries profile_id, codex_thread_id, a nullable rollout_path, and a status of available, profile_required, or unavailable, with a partial unique index that allows exactly one available link per thread and profile. Indexed and Exact are design names; in code one predicate decides: a link whose rollout path lies outside the runtime home is an external exact source, reads pass path and historySources only when a rollout path is supplied, and the wire storageFormat stays indexed either way. Both routes call thread/items/list on the Codex app-server, and an exact read adds path and historySources. An operation resolves its route once and keeps it.

Exact source access has deliberate limits #

Before a send or an attach, the desktop releases the thread from every other profile server it runs. That coordinates the bundled sidecars of this process; it does not prevent an unrelated external Codex process from writing the same source, so stop an external writer before continuing that conversation in PlanToCode.

The outbox uses an atomic identity claim #

workspace_chat_outbox
  session_id → entries_json, updated_at

workspace_chat_outbox_operation_identity
  (session_id, operation_id) → request_fingerprint

remote_rpc_idempotency
  scope_key → request_fingerprint, state, response_json, lease, expiry

codex_live_timeline_overlays
  timeline target → persisted overlay snapshot

codex_live_timeline_overlay_revisions
  singleton → one global revision sequence

codex_chat_operation_ledger
  (app_session_id, operation_id) → status, result_json

save_workspace_chat_outbox_with_operation_identity opens one transaction. Its INSERT … ON CONFLICT updates the identity row only when the existing fingerprint equals the submitted fingerprint. If that statement does not affect one row, the transaction rolls back. It then upserts the outbox entries JSON and commits. The identity row is keyed by the base session while the outbox JSON is saved under the alias session, so the same operation can be found from any alias in the scope.

The remote_rpc_idempotency table is the second ledger. It keeps the outcome of every listed remote mutation for 48 hours across desktop restarts, so a phone that retries after the desktop came back still gets the stored answer.

Project file access is a separate boundary #

Remote file reads run with the desktop user’s filesystem access. resolve_desktop_file_read_path expands a home shortcut, joins a relative path onto the canonical project directory, and canonicalizes the result; it does not enforce project containment, and the design note says so on purpose. allowExternalFile and allowExternalMedia only decide which resolver is tried first, so an authenticated companion can open paths outside the selected project either way. ensure_path_within_project, which rejects parent components and checks the canonical root, exists for desktop-local operations.

App-managed chat attachments live in pasted-images under the app data directory, and an external media read for an attachment must classify as image, video, audio, or document. The phone never uses its own home directory.