FamReynaBrain/projects/paseo_deep_research_2026-08-17.md

---
Date: 2026-08-17
Author: Adolfo Reyna + Hermes
Status: research verified against FamReynaServer `.110` and current upstream documentation
Tags: [paseo, agents, orchestration, workspaces, software-factory, research]
---

# Paseo Deep Research — Agents, Options, and Factory Design

## Bottom line

Paseo is a **local-first agent execution control plane**. A daemon runs on each machine that should execute coding agents. Desktop, mobile, web, CLI, and agent-to-agent orchestration are clients of that daemon. It does not itself supply an AI model; it launches and supervises authenticated provider CLIs such as Codex, OpenCode, Claude Code, and Pi.

For the family software factory, the useful model is:

```text
Paseo Desktop on laptop (interactive control client)
                      │ encrypted relay pairing
                      ▼
FamReynaServer .110 Paseo daemon (shared execution/control node)
                      │ local process supervision + project workspaces
                      ▼
Codex / OpenCode / Pi agents, worktrees, terminals, scripts, schedules
```

Other servers become execution nodes only when they independently run compatible Paseo daemons and are paired or securely targeted. A link to `.110` gives the laptop control over `.110`; it does not automatically turn every LAN host into a worker.

## 1. Live verification: FamReynaServer `.110`

All statements in this table were checked through SSH on 2026-08-17.

| Capability | Verified result | Meaning |
|---|---|---|
| Paseo CLI + daemon | `0.4.0` | Current server control plane is real, not a proposed install |
| Health | `GET 127.0.0.1:6767/api/health` → `{"status":"ok"}` | daemon is listening locally and healthy |
| Listener | `127.0.0.1:6767` only | good default: no LAN exposure |
| Relay | enabled; connected to `wss://relay.paseo.sh:443` | laptop connection can remain outbound/E2E encrypted |
| Laptop connection | one active external relay client, Paseo app version `0.4.0` | attached client has fetched agent/workspace/project state |
| Current agents/workspaces/terminals | all empty | clean factory starting point, not a hidden active fleet |
| Current schedules / pending permissions | both empty | no autonomous or blocked work is running |
| Hub relationship | `not_connected` | normal; Hub is optional and distinct from Desktop/relay pairing |
| Ready providers | Codex `0.141.0`, OpenCode `1.18.13`, Pi | usable local agent runners; Claude currently unavailable |

The CLI status output contains a misleading daemon-detail note despite the direct health endpoint, live local CLI requests, and relay session all succeeding. Treat the actual health endpoint and live command results as the source of truth until that display inconsistency is resolved.

## 2. Architecture: what belongs to what

### Daemon

The daemon owns:

- agent lifecycle, persistence, timelines, provider subprocesses, and permissions;
- workspaces and managed Git worktrees;
- supervised terminals and `paseo.json` scripts/services;
- schedules/heartbeats; and
- relay/direct client connections.

A daemon may run on a laptop, Mac mini, Linux server, VPS, or container. It must be installed and authenticated separately on every host intended to execute work.

### Client

Paseo Desktop, a mobile app, a terminal CLI, a web UI, and an orchestrating agent are all clients. They do not execute the coding work themselves unless they are also attached to a local daemon that launches it.

### Project → workspace → session

```text
Project (repository or directory on the daemon host)
  └── Workspace (stable task container; local directory or Git worktree)
       ├── Agent session(s)
       ├── Managed terminal(s)
       ├── named paseo.json scripts/services
       └── browser session(s), when enabled and a host is present
```

A **workspace** decides *where* work happens. **Agent parentage** decides *who owns* delegated work. These are independent: a subagent can be placed in another workspace while remaining its parent agent's child.

## 3. The installed v0.4.0 command surface

This is the command surface exposed by the actual CLI on `.110`, not an assumed older version. Most commands accept `--host`, `--json`, and the documented host target can be a direct daemon endpoint or a pairing offer URL.

| Area | Commands verified locally | Factory relevance |
|---|---|---|
| Top-level agent operations | `ls`, `run`, `import`, `clone`, `attach`, `logs`, `stop`, `delete`, `send`, `inspect`, `wait`, `archive` | core task execution and evidence |
| Advanced agent operations | `agent ls/run/import/attach/logs/open/stop/delete/send/inspect/wait/mode/archive/reload/detach/update` | lifecycle, recovery, provider mode, cross-client ownership |
| Workspaces | `workspace create/ls/rename/archive` | local vs worktree task boundaries |
| Managed terminals | `terminal ls/create/kill/capture/send-keys` | inspect and control daemon-host shell sessions |
| Workspace scripts | `script ls/start/stop` | repeatable test/build/dev/health commands in `paseo.json` |
| Recurrence | `schedule create/ls/inspect/logs/pause/resume/delete/run-once/update`; `heartbeat create/update/delete` | fresh-agent cron jobs vs same-agent continuation |
| Providers | `provider ls/models/diagnostic` | discover real models/modes, not guessed names |
| Permission checkpoints | `permit ls/allow/deny` | explicit approval of provider permission requests |
| Daemon / connectivity | `daemon start/pair/status/stop/restart/set-password`; `status`, `start`, `restart` aliases | lifecycle and remote pairing |
| Hub | `hub login/init/connect/status/disconnect/projects/deploy/logout` | optional hosted/self-hosted event/workflow product, not required for the pilot |
| Other | `hooks`, `speech` | present in help; no subcommands exposed by the installed build |

### Critical version caveat

Upstream current docs describe additional CLI namespaces including `project`, `plugin`, `reload`, and a newer CLI reference. They also document an agent loop pattern. **Those are not exposed by the installed 0.4.0 CLI on `.110`**: `paseo project`, `paseo plugin`, `paseo reload`, `paseo loop`, and `paseo chat` currently fall back to top-level help rather than providing a command.

Therefore:

1. Use `paseo <command> --help` on the target host as the operational truth.
2. Do not write factory automation around upstream-only commands until an upgrade has been tested.
3. The pilot can still use all essential primitives: worktrees, agents, scripts, schedules, terminals, permissions, and provider diagnostics.

## 4. Agent model — how agents actually work

### Lifecycle

```text
initializing → idle → running → idle
                        └────→ error → closed
```

- `idle` means an agent has finished its current turn and can receive a follow-up.
- `closed` is durable and resumable: provider runtime resources are released, but the agent ID, timeline, workspace, labels, and parent relationship remain.
- `archive` is a global **soft delete**: it closes the runtime and removes the agent from active lists but preserves its record/history.
- `delete` is a CLI hard-delete operation; do not use it for factory audit trails.
- `reload` restarts the agent's provider process; it is a recovery action, not a normal “continue” mechanism.

### Root agents, Paseo subagents, and provider-native subagents

| Kind | Provider | Lifecycle owner | Best use |
|---|---|---|---|
| Root Paseo agent | any configured provider | Paseo daemon | a discrete plan, implement, review, or release task |
| Paseo subagent | any configured provider; may differ from parent | Paseo daemon | cross-provider delegation and explicit workspace placement |
| Native provider subagent | same provider as parent | provider CLI | short provider-native decomposition inside a single session |

When a Paseo agent runs `paseo run` or uses `create_agent` without specifying a workspace, the child defaults to the **parent's workspace and subagent track**. Supplying a workspace changes placement but not parentage.

`paseo agent detach <id>` is intentionally explicit: it makes a child independent without stopping, moving, restarting, or archiving it. It should be a human operator decision, not a routine agent action.

### Consequences for a software factory

- Use one short-lived **root orchestration agent** for a change lane only when it adds value; do not create a forever-parent that accumulates unbounded children.
- Use **Paseo subagents** for planner → implementer → reviewer roles when cross-provider separation matters.
- Use **native subagents** only as the implementation provider's internal tactic; they are not interchangeable with independently controllable Paseo agents.
- Archive finished task agents after their evidence is recorded. Preserve the worktree/branch until review and merge/rejection are complete.
- Never infer that `idle` means provider background jobs are still alive. Provider runtime crashes can strand background work; require explicit command evidence for builds/tests.

## 5. Starting agents safely

A top-level `paseo run` starts an agent; from a normal human shell it creates a new local workspace for the current directory unless placement is specified.

The high-value options are:

| Option | What it controls | Factory policy |
|---|---|---|
| `--provider`, `--model`, `--thinking`, `--mode` | actual execution model and permission mode | discover available values with `provider ls/models` first |
| `--new-workspace worktree` | task isolation | default for source-changing work |
| `--worktree-mode branch-off` + `--new-branch` + `--base origin/main` | branch origin | use for new changes; prefer `origin/main`, not stale local `main` |
| `--workspace <id>` | existing task container | use to add review/test agents to a known worktree |
| `--background` | immediate return while task runs | use only when the orchestrator can later `wait`, inspect, or attach |
| `--output-schema` | structured final JSON | use for narrow, machine-consumable plan/review verdicts; cannot combine with `--background` |
| `--cwd` | daemon-local working directory | always explicit for server automation / remote targets |
| `--env` | agent process environment | avoid secrets in prompts/logs; prefer approved node credential stores |
| `--label` | traceability metadata | label tasks with project, lane, change ID, and role |
| `--host` | remote daemon or pairing offer target | use pairing offers/relay or a secured direct path; never open an unauthenticated LAN port casually |

## 6. Workspaces, worktrees, scripts, and services

### Isolation

- **Local workspace**: uses an existing directory. Good for read-only audits, planning, or one carefully coordinated task on a main checkout.
- **Worktree workspace**: creates/opens a managed Git worktree on its own branch. Use for every source-changing factory change, parallel agent, or review requiring clean context.

Worktrees are stored under `$PASEO_HOME/worktrees/` by default. Paseo removes the managed worktree only after its final workspace reference is archived. The factory must not archive a worktree before review/merge evidence is retained.

### `paseo.json`

A committed root `paseo.json` can define:

- one-time worktree `setup` and `teardown` commands;
- plain scripts such as `lint`, `typecheck`, `test`, `build`, and `health`; and
- long-running service scripts with supervised terminals, a distinct `$PASEO_PORT`, proxy URL, and health metadata.

This file is a factory contract: it turns “run whatever seems right” into stable project commands. Important caveat: setup/teardown scripts execute with the permissions of the daemon user and can copy `.env` files or run migrations. Keep them minimal and audited; do not copy production secrets into general-purpose worktrees.

## 7. Recurrence: schedules versus heartbeats

| Mechanism | Target | Agent state | Use | Safety pattern |
|---|---|---|---|---|
| **Schedule** | a fresh agent each run | no retained chat context | nightly CI audit, daily issue triage, dependency check | explicit `--cwd`, provider, `--max-runs` and/or `--expires-in`; start read-only |
| **Heartbeat** | the current existing agent | continues same conversation | bounded CI babysitting or deployment observation | only inside an agent (`PASEO_AGENT_ID` required); raw cron; stop condition and expiry |

Schedules support inspect/logs/pause/resume/update/run-once. Heartbeats in the installed CLI support create/update/delete; their prompt and target are fixed after creation. A heartbeat is **not** a global cron worker.

The older Paseo `loop` helper is not exposed in the installed server CLI. For now, use a bounded agent workflow with explicit test scripts, a fresh verifier agent, or a finite schedule. Do not create an unbounded shell loop or self-healing scheduled agent as the first factory experiment.

## 8. Permissions and human gates

Paseo surfaces permission requests via `paseo permit ls`; an operator can allow or deny a particular request, or all pending requests for an agent. Permissions are a checkpoint, not proof that the original task completed.

Factory policy:

1. Planning/review agents run no-edit and no-side-effect instructions.
2. Implementation agents may edit **only their isolated worktree**.
3. Testing/build scripts may run only predeclared local commands.
4. Merge, deployment, service restart, outbound publish/send, credential changes, and data migrations always stop for explicit human approval.
5. `permit allow --all` is not a standing policy; inspect a pending request and its scope first.

## 9. Connectivity and security choices

### Recommended: existing relay pairing

Relay pairing allows the daemon to stay at `127.0.0.1:6767`; the daemon makes an outbound connection and the laptop/client meets it through the relay. Paseo documents Curve25519 ECDH setup and XSalsa20-Poly1305 authenticated encryption for subsequent traffic. Pairing links/QR codes are trust anchors and must be treated like passwords.

### Other supported options

| Transport | Appropriate use | Required guardrails |
|---|---|---|
| loopback | CLI and agents running on same node | current `.110` default; safest local baseline |
| relay | laptop/mobile/remote control | protect offer link; revoke/rotate if exposed |
| Tailscale/VPN direct path | controlled private-network access | bind only to VPN address and configure password auth |
| LAN / `0.0.0.0` | avoid for family factory | only with firewall, hostname allowlist, password auth, and a specific reason |
| Docker | contained per-project agent executor | restrict repo mounts and protect `PASEO_HOME`; container isolation does not protect mounted credentials |

A standalone Hub is a separate product: it supports organization login, daemon enrollment, and Hub workflow bundles. Desktop multi-host management and relay pairing do **not** require a Hub. Current `.110` Hub state is intentionally `not_connected`.

## 10. Provider inventory and routing

The daemon's provider diagnostics prove what the daemon process can actually execute:

| Provider | Live status | Models exposed | Recommended role now |
|---|---|---|---|
| Codex | Ready; CLI `0.141.0` | GPT-5.5, GPT-5.4, GPT-5.4-Mini | implementation, deep review, structured planning |
| OpenCode | Ready; CLI `1.18.13` | 7 configured models | contrasting implementation/review, lower-cost experiments |
| Pi | Available | multiple GPT-5.1–5.4 configurations | lightweight tasks and exploration |
| Claude | unavailable | none | do not select until diagnostic reports Ready |
| Copilot / OMP | unavailable / disabled | none | no factory role today |

Before every dispatch, the orchestrator should query the target's `paseo provider ls` and `paseo provider models <provider>`. A model that is visible on the Mac mini does not imply it is authenticated or available on `.110`.

## 11. Recommended first software-factory operating procedure

### Pilot scope

Pick one low-risk repository that already has deterministic tests. It must reside on `.110` or be explicitly cloned/registered there; a remote `--host` command interprets `--cwd` on the **target daemon host**, not on the laptop.

### Change lane

1. **Register/prepare** the source checkout and add an audited `paseo.json` with `lint`, `typecheck`, `test`, and `build` scripts.
2. **Plan**: launch a no-edit planner agent that identifies acceptance criteria, files, risks, and exact test commands.
3. **Isolate**: create a worktree from `origin/main` and name the branch for the change.
4. **Implement**: launch a Codex or OpenCode agent in that workspace with allowed paths, predeclared scripts, and explicit no-merge/no-deploy limits.
5. **Verify**: run the named scripts, then launch a different-provider review agent in the same workspace to examine the diff and evidence.
6. **Approval**: present branch/diff, command exit outcomes, review findings, and rollback notes to the human.
7. **After approval only**: merge/deploy through the project-specific release path. Use a bounded read-only schedule only after the manual lane has proven useful.

### Agent prompt contract

Every executable factory task should contain:

```text
Goal and acceptance criteria
Confirmed workspace path and branch
Allowed files/directories and commands
Named paseo.json checks to run
Forbidden actions: merge, deploy, restart, publish, send, credential changes
Expected final evidence: changed files, commands, exit status, unresolved risks
```

## 12. Direct answers to likely operating questions

- **Can the laptop control `.110` now?** Yes. A verified encrypted relay client is attached to the live `.110` daemon.
- **Can `.110` run agents itself?** Yes: Codex, OpenCode, and Pi are ready.
- **Can that one link control every server?** No. Each execution host needs a daemon/pairing or a deliberately secured remote target.
- **Should we enable Hub now?** No. It is not needed for the first factory lane and adds organizational/workflow infrastructure.
- **Should we enable automatic repair schedules now?** No. First prove a manual, bounded worktree/verify/review lane; start schedules as read-only quality checks.
- **Should agents share the main checkout?** Only for read-only exploration or deliberate single-task coordination. Source changes should use worktree isolation.

## Sources

Official current documentation consulted:

- [CLI reference](https://paseo.sh/docs/cli)
- [Orchestration](https://paseo.sh/docs/orchestration)
- [Agent lifecycle source documentation](https://github.com/getpaseo/paseo/blob/main/docs/agent-lifecycle.md)
- [Workspaces](https://paseo.sh/docs/workspaces)
- [Git worktrees and `paseo.json`](https://paseo.sh/docs/worktrees)
- [Schedules from the CLI](https://paseo.sh/docs/schedules-cli)
- [MCP reference](https://paseo.sh/docs/mcp)
- [Configuration](https://paseo.sh/docs/configuration)
- [Connectivity](https://paseo.sh/docs/connectivity)
- [Security](https://paseo.sh/docs/security)
- [Providers](https://paseo.sh/docs/providers)
- [Supported providers](https://paseo.sh/docs/supported-providers)
- [Orchestration skills](https://paseo.sh/docs/skills)

The report additionally uses live, read-only CLI, health, provider-diagnostic, relay-session, and configuration evidence gathered from FamReynaServer `.110` on 2026-08-17.