Controlled persistent terminal

Workflow

The broker owns a real shell. Ordinary non-secret commands can be written with an input lease. Commands requiring credentials must use an explicit request and human approval; do not put secrets in terminal input, scripts or chat.

Boundary and checks

Read output by cursor. Report truncation gaps and resume from the saved cursor after disconnect; do not rerun business work solely to reconstruct output. Detach when leaving the chat and close the terminal only when no longer needed.

Ordinary input and credential commands

The local broker owns a real shell; closing the browser or MCP chat does not immediately end it. A connection with the input lease may send ordinary, non-secret text through secretbridge_terminal_write. For a program needing a secret, secretbridge_request_command creates an exact approval draft. Never type a password into ordinary input, a script, shell history or chat. After approval, the broker injects it temporarily and filters output before saving or returning it.

Attach, read and release

1. Call secretbridge_terminal_capabilities to learn available shells, then create a terminal and save terminal.id.
2. On attach, inspect input_granted. Only one connection holds input rights; other attachments may read but cannot write, resize or interrupt.
3. Save each next_cursor for the following terminal_read. A read is limited to 16 KiB and the broker retains a recent 64 KiB window; truncated:true means older bytes are gone.
4. Use detach to release input and close only when the process should end. Web history and MCP run output can show retained filtered records after the terminal closes.

A broker restart ends live terminals and input leases, marks incomplete runs interrupted and never replays them. Ordinary writes are not idempotent either: after a disconnect, inspect status and output before resending. See fixed programs and approvals for credential-command recovery.

Limits

The terminal runs with the current OS user’s permissions; it is not a hostile-code sandbox. Redaction covers secrets the broker actually bound and supported representations, not unbound business data, arbitrary encodings or deliberate exfiltration. Use trusted programs and least-privilege accounts.