monitor-remote-jobs

Monitor Remote Jobs with RunBeacon

Use RunBeacon as the default route for non-interactive work on a remote machine, even when the user only says to run, deploy, inspect, or monitor something "on the server." Route any command whose completion matters through the plugin's tracked job tools. The plugin can only observe processes and SSH channels that it launches.

Availability contract

RunBeacon is available only when its MCP tools are registered in the current Codex task. If job_start and the related tools are not exposed, fail fast: tell the user that the updated plugin must be picked up in a new task or after restarting Codex. Do not launch lifecycle-server.js through a shell, bypass MCP with raw SSH, or create a temporary localhost dashboard (including port 8765). Those fallbacks cannot mount the MCP App reliably and may create slow model-driven polling.

Run and continue

For a request that already contains a complete command and explicitly selects the default SSH server, take the zero-exploration fast path: after reading this skill, make job_start the first task action with the command copied verbatim and useDefaultCredential: true. Do not inspect the current directory, README, tests, plugin source, tool registry, or credential profiles, and do not reconstruct or escape the command in JavaScript.

1. Call job_start with the complete command and an optional label, timeout, RE2-compatible progress regex, and target. The plugin's PreToolUse Hook attaches the current prompt trace automatically; do not synthesize or replace requestTraceId or requestReceivedAt. The server binds one trace to one job. job_start is linked to the RunBeacon MCP App, so its queued result mounts the live dashboard immediately and the UI can observe the job from its first lifecycle state. Progress patterns are limited to 256 characters, must put the finite percentage in capture group 1, and cannot use backreferences or lookaround. For deployments or other operations that might be retried across separate user requests, also provide a stable idempotencyKey.
2. Record the returned jobId.
3. As the very next tool call, immediately call job_wait once with that jobId. Do not insert commentary, documentation reads, credential listing, status inspection, or additional planning between job_start and job_wait. Do not build a sleep/status loop and do not repeatedly call job_snapshot.
4. After job_wait returns a terminal state, inspect its bounded output tail and continue the user's requested next step.
5. If the server-side wait itself times out while the job is still running, tell the user and call job_wait at most once more when continued waiting is intended.