ruvnet / ruos-host-run

Run a ruflo agent on a ruOS desktop (session path, ADR-405)

Transport rules — non-negotiable:

• Use ONLY the fleet MCP tools (mcp__ruos__*, or the claude.ai ruOS connector's
  equivalents) or the plugin CLI. Never call a desktop on port 17870 and never set a
  Host header yourself (ruOS ADR-070: that executor has no per-tenant auth).

• Send ONLY the command strings printed by cli.mjs build. Never compose a
  desktop_exec command from task text.

CLI below is node "${CLAUDE_PLUGIN_ROOT}/scripts/cli.mjs".

desktop_exec output is framed: the first line echoes your command (▶ run: …), and the
last lines are ✓ SUCCESS… and 📝 transcript:. Every marker the desktop prints is
RUOS<nonce>_NAME, on its own line, where <nonce> is the nonce from CLI build. That
token never appears in the echoed command, so match only complete lines that start with it.
Output is capped at about 4 KiB, so poll returns 2 KiB slices.
Never call desktop_delete or secret_delete; deleting is the user's job.

1. Pick the host. Call desktop_status. Resolve the user's desktop by machine_id,
   fly_machine_id or exact display_name; if it is not in that list, stop. Save the raw
   JSON to a temp file (status.json) for step 4.

2. Liveness. A desktop is up only if heartbeat_status is not asleep/missing/stale
   and last_heartbeat_at is recent. If it is down, ask before desktop_start (billable),
   then re-poll desktop_status until the heartbeat advances.

3. Auto-stop. CLI status prints nextAutoStop (weekday 23:00 America/Toronto). If the
   run could cross it, tell the user and stop unless they accept. desktop_keepawake blocks
   idle autosleep only; it does not override the 23:00 stop.

4. Build + record. Write the task to a file, then:

   • CLI build --prompt-file task.txt [--model sonnet] → JSON with runId, steps[],
     poll, stop, promptSha256.

   • CLI record start --run <runId> --desktop "<ref>" --desktop-status-file status.json --task "<one-line summary>"
     — registers the agent through ruflo's agent_spawn (with config.host) and claims
     ruos-run-<runId> via claims_claim.

   Before launching, call llm_route_get. Stop if the desktop has no route. If the gateway is
   "unconfigured" but the route is "shared", warn and continue.

5. Launch. Call desktop_exec with each steps[i] in order (machine = the desktop's
   fly_machine_id). The last step prints RUOS<nonce>_SHA:<hash> — it must equal
   promptSha256, else desktop_exec the stop string and abort. RUOS<nonce>_NO_RUNNER means
   claude is not installed there.

6. Stream. Call desktop_exec with poll (rebuild with CLI build --run <runId> --nonce <nonce> --offset <n> ...
   as the offset grows, or use CLI run for automatic polling). Output is
   RUOS<nonce>_POLL:<exit|->:<size>:<alive 0|1>:<base64>; pass the base64 to
   CLI record output --run <runId> --b64 <b64> and show the decoded text. Back off 1s→5s
   between empty polls — each poll is audited on ruOS and serialises behind the desktop's
   run lock.

7. Finish. When exit is not - and all bytes are read:
   CLI record end --run <runId> --exit <code> (agent → idle, claim released).
   On failure, check desktop_status: a stopped desktop means it was auto-stopped mid-run.

8. Stop early only on the user's request: desktop_exec the stop string.

For unattended runs from a terminal, CLI run --desktop "<ref>" --prompt-file task.txt
does steps 1–7 itself (needs RUOS_MCP_URL + RUOS_MCP_TOKEN, or --transport ssh with
RUOS_SSH_KEY when ruflo runs on a same-tenant ruOS desktop).