FamReynaBrain/projects/paseo_deep_research_2026-08-17.md

Date, Author, Status, Tags

Date	Author	Status	Tags
2026-08-17	Adolfo Reyna + Hermes	research verified against FamReynaServer `.110` and current upstream documentation	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:

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

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

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:

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
• Orchestration
• Agent lifecycle source documentation
• Workspaces
• Git worktrees and paseo.json
• Schedules from the CLI
• MCP reference
• Configuration
• Connectivity
• Security
• Providers
• Supported providers
• Orchestration 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.