# Paseo runtime backend Paseo is an experimental macOS GUI terminal backend. It provides task workspaces and terminals while Treehouse continues to provide git worktrees. [`configuration.md`](configuration.md#runtime-backend-configbackend--fm_backend) owns shared selection and metadata semantics. ## Setup Pick Paseo when you already use the app as your terminal and want tasks as tabs in its sidebar, with the same UX as Herdr: in Firstmate's own workspace when Firstmate runs inside Paseo, otherwise in one `firstmate` workspace per project. Paseo is macOS-only, GUI-first, and unsuitable for a headless or SSH-only Firstmate session. Prerequisites: - Paseo 0.8 or newer, installed from [paseo.sh](https://paseo.sh) (`/Applications/Paseo.app`). - `jq` for JSON responses. - The universal harness and toolchain requirements in [`configuration.md`](configuration.md#toolchain). The bundled CLI is not always installed on `PATH` with the app. The adapter prefers `command -v paseo` and otherwise uses `/Applications/Paseo.app/Contents/Resources/bin/paseo`. No socket-access configuration is needed. The daemon listens on `127.0.0.1:6767` by default, and `paseo status` reports its reachability. The adapter starts the daemon with `paseo start` only when it is simply not up yet, and fails fast with a pointer here when a started daemon does not become reachable. Select Paseo with local `config/backend` containing `paseo`, `FM_BACKEND=paseo` for one launch, or an explicit request to Firstmate. It is never runtime auto-detected; see "Selection is explicit" below. A spawn stops with an actionable setup message when the CLI, minimum version, `jq`, or daemon reachability is unavailable. Routine supervision uses `bin/fm-peek.sh ` and `FM_HOME= bin/fm-send.sh ''` without bringing the Paseo window forward. Verify setup by spawning a small task and confirming metadata contains `backend=paseo`, `paseo_terminal_id=`, and `paseo_workspace_id=`. ## Selection is explicit Paseo is explicit-only, like zellij and orca: `config/backend`, `FM_BACKEND=paseo`, or `--backend paseo` select it, and nothing else does. Paseo stamps its markers into every descendant process: a Paseo agent exports `PASEO_AGENT_ID`, a terminal tab exports `PASEO_TERMINAL_ID` and `PASEO_WORKSPACE_ID`, and both carry `__CFBundleIdentifier=sh.paseo.desktop`. A tmux server started from a Paseo tab inherits all of them, so their presence proves only that some ancestor was Paseo, never that the captain chose it. Reading them as a selection would make Paseo an ambient default, which "Authority is explicit and never inferred" rules out; `fm_backend_detect` therefore ignores them. The markers are still useful once Paseo has been selected explicitly. When Firstmate itself runs inside Paseo, the adapter uses them to find Firstmate's own workspace and puts task tabs there (see "Task shape and metadata"). ## Task shape and metadata Paseo's sidebar is project > workspace > terminal tab, and each task is one terminal tab. When Firstmate itself runs inside Paseo, every task tab goes into Firstmate's own workspace, whatever the task's project, so work appears beside the captain's session and nothing new is added to the sidebar. A Paseo terminal tab names its workspace through `PASEO_WORKSPACE_ID`; a Paseo agent exports only `PASEO_AGENT_ID`, so its workspace is the one live workspace whose cwd is the Firstmate home, and two or more such workspaces count as unknown. Otherwise the adapter uses one shared workspace per project, the same container shape as Herdr: titled `firstmate` (or `2ndmate-` for a secondmate home), created once with `workspace create --path --isolation local --title `, and adopted on later spawns by matching that cwd and title in `workspace ls`. Paseo registers or reuses the project by path when that workspace is created. Paseo allows duplicate workspaces and terminal names, so a spawn whose `workspace ls` or `terminal ls` inventory cannot be read refuses and creates nothing rather than treating the failed read as empty. Agents running inside a task tab may open further tabs or workspaces of their own; nothing in the adapter depends on them. Each task owns one terminal tab in that workspace. The terminal's NAME (`terminal create --name fm--`) is the firstmate-facing routing authority, home-scoped so two Firstmate homes sharing one daemon can never cross-match each other's terminals. The workspace title only identifies the shared workspace to adopt; it is never used to route a task. The recorded target is the pair `:`: ```text backend=paseo window=: paseo_terminal_id= paseo_workspace_id= ``` The recorded terminal id is validated against the live `terminal ls` inventory before every send. When the recorded id is gone, recovery re-resolves the terminal by its home-scoped NAME from the same inventory, never by title. ## Current operation and safety `terminal send-keys -l -- ` sends literal, unsubmitted input. The caller sends Enter separately. Paseo 0.8.0's send-keys token set is Enter, Tab, Escape, Space, BSpace, C-c, C-d, C-z, C-l, C-a, and C-e. Any other key name is typed as literal text, so the adapter sends Ctrl-U as the raw `0x15` byte through `-l` and refuses every other unlisted key. `terminal capture -S --json` returns plain-text lines with ANSI stripped. The adapter fetches the scrollback whole and trims the tail locally; Paseo caps scrollback at 1024 lines (verified on Paseo 0.9.2), so that read stays bounded however long a task runs. `--start -` is not used because it counts the blank screen rows below the prompt as part of the tail. Because capture strips styling, the capability descriptor declares `styled=0`, and the shared classifier in `bin/fm-composer-lib.sh` degrades a glyph row carrying trailing text to `unknown` rather than misreading an idle suggestion as unsent input. A terminal's `cwd` field in `terminal ls` is creation-time-frozen and never follows the foreground subshell opened by `treehouse get`. Spawn-time worktree discovery therefore sends begin and end markers around `pwd`, captures the marked block, and joins wrapped path lines, exactly like cmux and zellij. Cleanup closes only the task's tab with `terminal kill`; sibling task tabs stay alive. It is best-effort like every backend's kill, so an already-gone target stays quiet. When the closed tab was the last one in a per-project shared workspace for one of the home's own clones under `projects/`, cleanup archives that workspace, provided it carries Firstmate's own title, is not Firstmate's own workspace, and no Paseo agent works in its folder, because archiving a workspace also archives the agents it owns. Archiving leaves the project in the sidebar, so cleanup then deletes that clone's project when no other workspace uses it; workspaces and projects outside the home's clones are never touched. Spawning and this cleanup share one home-wide lock (`state/.paseo-workspace.lock`), so a new task's tab can never land in a workspace between its empty check and its archive; a spawn that cannot get the lock refuses, and cleanup that cannot get it skips. Any inventory read that fails also skips this cleanup. Mutating `--json` calls keep stderr out of the parsed output, because the CLI prints an Electron warning on stderr when Firstmate itself runs inside a Paseo agent. Paseo exposes no native generic agent busy signal, so supervision uses capture/hash polling for screen changes and each harness adapter's semantic lifecycle for worker state. ## Visible tabs versus nested agent views Paseo can show sub-agents nested inside the current tab, clickable to open as their own view, without opening a separate top-level tab. Firstmate's design keeps the terminal-per-task model as the authority: every task gets exactly one terminal tab in its workspace, opened at spawn and closed at cleanup. A nested sub-agent view therefore never becomes routing or lifecycle authority for Firstmate - it is an extra view the captain may click into while the task's single terminal remains the endpoint. The practical tradeoff: a task terminal running a harness that itself spawns sub-agents will show those agents nested inside the task's tab, not as new top-level tabs, so each Firstmate task adds exactly one tab. The tradeoff surfaced is agent surface versus terminal surface - a nested agent view is visible and clickable but not separately addressable by `fm-send`/`fm-peek`, which always target the task's one recorded terminal. A closed tab does not preserve its visible scrollback history: `terminal kill` reclaims the endpoint with no transcript left behind for later reading. Durable history for a finished task therefore lives in the status log, the report, and the PR, never in tab scrollback - the same reason firstmate never treats a status line as more than a wake event. ## Active limits - Paseo is experimental, macOS-only, GUI-first, and requires the app running. - Secondmate spawns are unsupported until a per-home lifecycle design is verified; select `tmux` for a home that needs them. - `paseo run --cwd` is ignored when `PASEO_AGENT_ID` is set (reported on the upstream issue thread); the adapter never uses `paseo run`, only `terminal create --cwd`, which honours the path. - There is no native busy or push-event signal, and `fm_backend_agent_state` reports `unverified` for Paseo. - A target can disappear after structural readiness and before the operation. - Workspace and terminal ids are not assumed stable across daemon restarts; recovery re-resolves by terminal NAME. ## Regression entry points ```sh tests/fm-backend-paseo.test.sh tests/fm-backend-paseo-smoke.test.sh ``` [`verification/runtime-backends.md`](verification/runtime-backends.md#paseo) records the active source and live evidence.