Storage ownership

Separate the stores by owner #

Each agent saves its own conversations. HB Code stores the link from a session to the agent’s conversation, the outbox, and live state. It reads a conversation only through the agent’s own interface: the Codex app-server protocol, or the Claude Agent SDK in the agent host.

The figure shows the desktop computer only. Two stores are off the desktop: the server database and the phone. The last two rows of the next table name what each holds. Neither holds a transcript.

Every Claude transcript read runs with the main folder, whichever account is active. A saved transcript needs no sign-in, and every account saves into the same projects folder. HB Code creates that folder in the main folder before it links an account. If the projects link fails, the account setup fails with an error. A failed link for any other entry only writes a warning to the log.

The agent host opens three kinds of Claude files directly, because the SDK does not return them: the meta.json file beside a subagent transcript, the workflow run record, and the effort field of a subagent’s first saved assistant turn. It reads them and never writes them.

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 #

The column sessions.chat_agent holds codex or claude. It is set when the session is created, and a session update keeps it. It decides which identity tables a session uses.

An app-owned Codex profile has a stable opaque UUID in canonical lowercase text. An email address and a filesystem path are not profile identity. The codex_profiles table holds one row for each profile with a status of signed_out, authenticated, or unavailable and the account columns that the app-server reported.

Indexed and Exact are design names for the two Codex read routes. In code one predicate decides: a link whose rollout path lies outside the runtime home is an external exact source. Both routes call thread/items/list on the Codex app-server. An exact read adds path and historySources. The wire storageFormat of a Codex session stays indexed on both routes. An operation resolves its route once and keeps it.

A Claude session has no profile link, because every Claude account reads the same transcripts. HB Code does not store whether a transcript exists. The host answers missing for a conversation that Claude has not saved yet, and the desktop then shows an empty timeline. The UUID in claude_operations is the UUID of the user message that the desktop sends, which is how the desktop finds that message in the transcript. The row also keeps the message text and the attachments.

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. Stop an external writer before you continue that conversation in HB Code.

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

chat_operation_ledger
  (app_session_id, operation_id) → status, result_json

chat_session_messages
  operation_id → recipient, sender, sender_call_id, sender_run_id, sender_thread_id, chain_id, hop, delivery

chat_live_timeline_overlays
  (app_session_id, timeline_target_id) → revision, snapshot_json

chat_live_timeline_overlay_revisions
  singleton → one global revision sequence

chat_pending_terminal_overlay_cleanups
  (app_session_id, run_id)

agent_usage_samples
  agent, account_key, window_kind → used_percent, resets_at, sampled_at

Five tables carry the chat_ prefix, and they serve Codex and Claude sessions alike. Four of them had the codex_ prefix until a rename migration. chat_session_messages is newer. Tables that only Codex uses keep the codex_ prefix, for example codex_session_links and codex_command_outputs.

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. For a message from another session it also inserts the chat_session_messages row, and a row with the same operation ID stays as it is. Then it commits. A session message is never queued without its record and never recorded without its queue entry. 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.

agent_usage_samples keeps plan-limit readings for both agents. The account key is the active Codex profile ID, or the Claude account ID, which is default or a UUID. A reading is skipped when the newest reading of the same window is younger than 10 minutes, has the same reset time, and differs by less than 0.5 percent. Readings older than 35 days are deleted.

What a session delete removes #

delete_session_with_scoped_references removes the HB Code rows of a session in one SQLite transaction. The delete sends no request to Codex and none to Claude. The agent’s transcript stays where the agent saved it.

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.