Monitoring: shareable monitor link + read-only monitor view for workspace/pane

[danshapiro]

Background

tmux has a built-in monitor/attach story: you can start work, detach, and later attach to observe output.

In Freshell, the current reality is:

• The “real UI” is the browser.
• The agent API can create tabs/panes and broadcast ui.command updates.
• If you’re not already looking at the right UI instance, there isn’t a clear, reliable way to monitor or join what an agent/script started.

As Freshell is intended for remote use (LAN/VPN, phone access), a first-class monitor story matters.

Why This Matters (Freshell Use Cases)

Concrete workflows that should be smooth:

• Long-running commands: You kick off a build/test/deploy from your laptop, then later check progress from your phone.
• Agent-driven changes: An AI agent starts tasks (install deps, run migrations, run tests) and you want a second screen showing live output.
• Pairing / “ops window”: One browser is used for control, another is a read-only monitor that auto-scrolls and doesn’t steal focus.
• Multi-tab session organizer: You have many sessions; you want a “monitor this pane” link you can pin.

Core Requirements

• No token in URL (avoid leaks via history/logs/referrers). The user may still need to authenticate, but the monitor link itself should not embed secrets.
• Read-only monitor mode (cannot send keys by accident).
• Works cross-device (phone/laptop) and survives reconnect.

Proposal

Add a monitor feature built on stable workspaces.

Prerequisite

Depends on stable workspaceId (see #20). Monitor links should target a workspace, not an ephemeral WS connection.

UI: Monitor Route

Add a dedicated monitor route, e.g.:

• /monitor?workspaceId=<id>&paneId=<id>
• or /workspaces/<workspaceId>/panes/<paneId>/monitor

Behavior:

• Read-only xterm view (attach to terminal output, ignore all input)
• Autoscroll toggle
• Basic search/find-in-output
• Clear “MONITOR” banner so the user knows it’s not interactive

UI: Entry Points

• Pane header/context menu action: “Open Monitor” (opens a new window/tab)
• Pane header/context menu action: “Copy Monitor Link”

Server/Protocol

No new polling endpoints.

• Monitor view uses existing WS plumbing to attach to the same terminal stream.
• Optional: a monitor flag on terminal.attach so server can enforce “no input” semantics for that socket (belt and suspenders).

CLI Helper

Add a CLI command that prints a URL you can open/copy:

• freshell monitor -t <paneTarget> [--workspace <id>]
• Output: a monitor link without token

Optional future:

• --open to open in default browser (platform-dependent)

Open Questions / Design Decisions

• If multiple UIs join the same workspace, do they share focus/selection state or keep local selection?
• Should monitor windows join the workspace as “viewer” only (no layout writes / no ui.layout.sync)?

Test Plan

• Unit tests:
  • Monitor link builder (client)
  • WS attach in monitor mode does not send input
• Integration:
  • Open monitor route, attaches and receives output.
  • Copy link, open in another browser context, output appears after authentication.

Acceptance Criteria

• A user can reliably obtain a monitor link for a pane and view live output in a read-only UI.
• No secrets are embedded in the URL.
• Monitor works on a second device after reconnect (via workspaceId).

Related

• Workspaces: stable workspaceId for UI + agent API targeting #20 (stable workspaces)