Solo Run Processes

Run Solo Processes

Control existing process entries with smallest lifecycle action that achieves requested state.

Workflow

1. Establish identity and scope.
   • Call whoami first when running inside Solo-managed agent.
   • Otherwise call list_projects, then select_project when multiple projects exist.
   • Use Solo process IDs from Solo tools only; never substitute OS PIDs or another orchestrator’s IDs.
2. Inspect before mutating.
   • Call list_processes or get_project_status.
   • Call get_process_status for target.
   • Confirm process kind, state, trust, and whether user requested one process or command batch.
3. Confirm authority and ownership.
   • Control only current process and Solo descendants this process spawned.
   • Record every returned child process ID at spawn time; do not reconstruct ownership from later process lists.
   • Require explicit user/runbook authority for parent, sibling, unrelated, YAML-backed shared process, or another agent's descendants.
   • Never infer ownership from idle, stopped, failed, completed, or handed-off state.
4. Respect trust.
   • Start/restart only trusted command processes.
   • If command is untrusted, report blocker and direct user to Solo UI review.
   • Never weaken or bypass trust to complete lifecycle request.
5. Choose exact action.
   • Call start_process for stopped stored entry.
   • Call stop_process for running entry.
   • Call restart_process when latest saved configuration must relaunch.
   • Use start_all_commands, stop_all_commands, or restart_all_commands only for explicit project-wide command request.
   • Call spawn_process only to create new terminal or agent; do not use spawn to duplicate configured command.
   • Record returned child ID immediately with purpose and owner.
6. Interact only when requested and authorized.
   • Call send_input for terminal text or control bytes.
   • Use submit=false to type without Enter.
   • Use bytes 3, 4, or 27 for Ctrl+C, Ctrl+D, or Escape.
7. Verify result.
   • Poll get_process_status; do not infer success from request acceptance.
   • Read short rendered output tail when startup confirmation matters.
   • Use port-readiness tools only when user needs service ready, not merely process running.
8. Report target, authority basis, action, final state, recorded child IDs, and skipped/failed entries.

Runtime policy

• Treat auto_start as eligibility, not immediate launch. Project Auto Start, command flag, trust, and limits all gate startup.
• Use crash auto_restart only for commands expected to remain alive. Expect pause after 10 restarts in 60 seconds.
• Use restart_when_changed only when native watcher is insufficient. Keep globs narrow and project-root-relative.
• Keep crash restart and file-watch restart conceptually separate.
• Restart after shell environment or saved command configuration changes; existing child environment never updates in place.

Safety

• Stop only requested scope. Project-wide actions affect commands, not terminals or agents.
• Use close_process only to remove terminal or agent. Use stop/restart for commands.
• Pass confirm_self_close=true only when user explicitly asks current process to close itself.
• Apply same ownership gate to stop, restart, close, rename, input, output clearing, UI selection, and timer delivery.
• Do not delete project or process definition when stop is enough.
• Do not clear output during lifecycle work; retained failure output supports diagnosis.
• Reuse existing dev process instead of starting duplicate service.
• Leave Git, publishing, deployment, and integration to root/operator.

Boundary

• Hand initial repository/YAML architecture to project setup workflow.
• Hand agent setup, health, launch, resume, summaries, prompting, and cleanup to single-agent lifecycle workflow.
• Hand read-only URL, port, resource, and output inspection to service observation workflow.
• Hand repeated failure, environment mismatch, or unexplained state to troubleshooting workflow.

Reference

Read process lifecycle reference before bulk actions, trust-sensitive starts, auto-restart/file-watch configuration, spawning, closing, or raw input.