basicagent.org

Office

ProvenanceOS: Persistent Browser Workspace

A persistent browser workspace for phone-first terminal sessions that survive reconnects without “reload to recover.”

Published: 2026-01-02 · Last updated: 2026-01-04

Scope

This page describes the design constraints and mechanisms behind a persistent browser workspace: a persistent terminal surface that can run a real terminal session from a phone or laptop and survive disconnects without turning “reload the page” into the recovery plan.

It covers: session identity, connection continuity, output replay, resizing, minimal file browsing, and operational boundaries.

It excludes: production deployment recipes, credential handling, and any end-to-end wiring that would be copy/pasted into an exposed service.

Baseline: why “web terminals” fail in real use

The baseline we are targeting is not “slow rendering.” It is state loss and recovery friction:

  1. Disconnect = reset
  • The connection drops and the terminal becomes unrecoverable.
  • The only way to continue is to refresh and re-run everything.
  1. No output continuity
  • The browser only sees output that arrived while it was connected.
  • If the phone suspends the tab or the network blips, output is lost.
  1. Resizing is an afterthought
  • Rotation and viewport changes corrupt the terminal layout.
  • Terminal size is not updated, so wraps and full-screen UIs break.
  1. No admin surface
  • Stuck sessions accumulate.
  • There is no way to list sessions, drop one, or reason about resource use.

The impact is not abstract. It increases time-to-fix and increases error rates because operators repeat steps under uncertainty.

Mechanism: what makes a browser workspace persistent

The durable pattern is a small set of explicit contracts.

1) Stable session identity

Every terminal is keyed by a stable session_id. If the UI reconnects to the same session_id, it must attach to the same underlying session state (or a controlled replacement).

This is the difference between “a terminal in a page” and “a workstation surface.”

2) Minimal streaming contract

Treat the terminal as a byte stream. Keep the protocol minimal and explicit:

Input(text)   -> server writes to the terminal session
Output(bytes) <- server streams terminal output
Resize(c,r)   -> server updates session geometry

Anything more complicated tends to leak environment details or create browser-only assumptions.

3) Output buffering + replay on reconnect

Mobile networks drop. Tabs get suspended. Reconnect must be expected.

A practical baseline is a bounded ring buffer of recent output:

  • server buffers the last K output chunks per session
  • on reconnect, server replays the buffer, then switches to live streaming

This preserves continuity without turning the terminal into a log archive.

4) Resizing as a first-class event

Viewport changes must trigger a Resize(cols, rows) message, and the server must apply it to the session.

If you do not do this, the “phone terminal” will look correct only when it is idle.

5) Minimal file surface (optional)

A workspace becomes more usable with a constrained file surface:

  • list directory entries (bounded, safe root)
  • preview file content (read-only, size-limited)

The goal is support for navigation and verification, not a remote IDE.

Results (no invented numbers)

When these contracts hold, the improvement is measurable in workflow terms, even if your exact numbers differ.

Metric: Recovery time after a disconnect

  • Baseline: t_recover_base (re-run context; re-open sessions; re-issue commands)
  • Persistent: t_recover_persist (reconnect; replay; continue)
  • Interpretation: The delta is dominated by state continuity, not network speed.

Metric: Lost output rate (operator-visible)

  • Baseline: p_lost_output_base (output that occurs while disconnected is lost)
  • Persistent: p_lost_output_persist (buffer replay makes recent output visible)
  • Interpretation: Lower loss reduces rework and reduces “did it finish?” uncertainty.

Metric: Terminal correctness under rotation

  • Baseline: p_layout_break_base (wrap/curses corruption after rotate)
  • Persistent: p_layout_break_persist (explicit resize)
  • Interpretation: A phone-first tool must treat resize as normal traffic.

Boundaries (security + scope)

This is a workstation surface. Treat it like one.

  • Do not expose an unauthenticated terminal on a public interface.
  • Constrain filesystem access; prefer a safe root + allowlist patterns.
  • Use TLS; assume hostile networks.
  • Implement session reaping/limits; assume users will forget tabs.
  • Avoid presenting an end-to-end “deploy this exact stack” recipe on a public page.

Continuity pillars

Phone terminal CTA