Terminals and the stage

Every agent runs in a terminal that pond-ptyd owns. Pond.app only shows it. Closing a window, quitting Pond or updating it never stops an agent.

The terminal window

The window is a native SwiftTerm view bound to one helper terminal.

• Open. Pond subscribes to the terminal. The helper replays its in-memory ring, then live output follows.
• Type. Your keys go to the helper's write operation. Pond.app is the only process whose writes count as your own keys.
• Resize. The grid size goes to the helper's resize operation.
• Close. The subscription ends and the agent keeps running. The view stays in memory for 30 seconds, so a quick reopen is instant, then it is freed.

Copy trims trailing spaces. Paste is cleaned and sent as a bracketed paste, and a large paste asks first.

Where the text lives

Terminal output lives only in the helper's memory, in a ring of 2 MB per terminal. It is never written to disk or to a log. When a terminal ends, the helper keeps it listed for 10 minutes so you can read the last output, then drops it and zeroes its buffer.

The helper also keeps a small amount of state per terminal without storing text:

• a count of input bytes since the last Enter, which tells Pond you have an unsent draft;
• whether Claude Code is working, showing its input box, or showing a dialog;
• dev-server URLs printed in the output, sent once per new origin so the browser tile can offer a preview.

The stage

Clicking a blob opens its terminal large in the middle of that display, between the sidebar and the edge strip.

• One terminal fills the stage. Two or three sit in columns, or one large with a stack. Four make a 2×2 grid.
• A fifth replaces the one you focused least recently.
• ⌘1 to ⌘4 focus a tile. Dragging a header swaps two tiles.
• Clicking an open tile's blob, ⌘W, the close button, or Esc twice sends the tile home. The rest re-tile.
• The pin takes a tile off the stage as its own window.

Tiles float over other apps. Pond remembers them in stage.json and restores them on relaunch.

The stage has no timers. It changes only on clicks, keys, drops, focus changes and display changes.

Running your own dev server

Run on a worktree row starts the project's run command in its own terminal. Only you set this command, with pond project add --run or Set run command… in the app. A repo file cannot set it, and neither can an agent.

The command gets a PORT that stays with that worktree, so several worktrees can run their servers at once. Pond probes ports on 127.0.0.1 and ::1 only, never on a wildcard address.

When the helper is gone

If pond-ptyd dies, its terminals die with it. Pond restarts the helper at most 3 times a minute, each try a little later. It then counts the agents that were lost and offers Resume for them, at most once per agent per hour. Pond never resumes a session whose process is still alive.