# Long Wait > Run and monitor non-interactive local commands expected to take more than five minutes with a fresh low-effort subagent, hourly progress checkpoints, and immediate real exit-code reporting while minimizing main-thread token use. Use for long experiments, builds, analyses, training, exports, or whenever the user explicitly requests long-wait or monitor-agent execution. - Skill: `le876/long-wait` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add le876/long-wait` - Raw SKILL.md: https://api.skillmd.com/api/skills/le876/long-wait/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: le876 (https://skillmd.com/u/le876) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/le876/long-wait --- # Long Wait Delegate terminal ownership to a fresh, clean-context monitor. Keep ordinary terminal polling inside that monitor and wake the main thread only for scheduled checkpoints or terminal completion. ## Input contract Determine these values before spawning: - `command`: exact non-interactive command to execute once. - `workdir`: command working directory. - `success_condition`: expected exit status or completion artifact. - `report_target`: parent agent's canonical task path. - `result_paths`: optional exact paths to report at completion. - `log_path`: optional detailed log path. - `deadline`: optional duration; default to 24 hours. - `checkpoint_interval_seconds`: optional; default to 3600 seconds. - `expected_duration_seconds`: optional performance budget. Crossing it requests diagnosis but never stops the command. - `progress_probe`: optional exact read-only shell command. It must finish within 30 seconds and may emit one compact JSON object with `status`, `phase`, `completed`, `total`, `eta_seconds`, and `message`. Do not start the command until a fresh monitor slot is available. ## Prepare a slot 1. Inspect available capacity with `list_agents` once when exposed; otherwise attempt the fresh spawn and handle a capacity response through event waiting. 2. If capacity is available, spawn the monitor immediately. 3. Never interrupt a working agent to obtain a slot. 4. If capacity is full, wait for an agent event. A non-terminal checkpoint does not release a slot; consume it and return to event waiting without dense status polling. 5. When a terminal event releases capacity, attempt the fresh monitor spawn. Never reuse an existing thread. ## Setup and select a monitor For installation or a missing role, read [setup](references/setup.md). The role configuration is bundled at [assets/long-wait-monitor.toml](assets/long-wait-monitor.toml), including its execution instructions. Installing the skill folder alone does not register a custom agent in the host. Inspect the actual tool schema and available models; choose a supported path: - **Registered role (preferred):** select `long_wait_monitor` through the host's role selector, for example `agent_type="long_wait_monitor"`. The field name may differ. Let the role supply its model and reasoning settings when they are locked. - **Explicit configuration:** when custom-role selection is unavailable, create a fresh child using the host's explicit model and reasoning parameters. Prefer `model="gpt-5.6-terra"`, `reasoning_effort="low"`; use another available lightweight model or supported effort when needed. Read the bundled TOML and include its `developer_instructions` text, the input contract, and the protocol below in the child's self-contained message. This is a configured monitor, not a registered role; report the selected path and settings accurately. Both paths require a fresh context: use `fork_turns="none"` or the host's documented fresh-context equivalent, a unique task name, terminal ownership, and event/message reporting to the parent. A nickname never proves role selection. Do not silently inherit the parent's full history or model when explicit configuration is needed. Honor stronger project or host requirements; this skill does not override them. If neither path can provide a fresh configured child with terminal and reporting capabilities, explain the missing capability before launch. Offer the concrete setup steps or a supported local client; do not pretend installation changes the current tool schema. Ordinary parent-owned execution is a different workflow. Send only the input contract and monitor instructions, not the parent conversation. Once the monitor starts the command, never rerun it. A failed monitor may be replaced only through read-only recovery when an independent launcher owns the live task. ## Monitor execution protocol Instruct the monitor to: 1. Shell-quote the original command and launch it exactly once inside one outer Bash wrapper. Immediately before `timeout --signal=TERM --kill-after=30s bash -lc `, capture the Bash `SECONDS` value. After `timeout` returns, capture `$?`, compute the total elapsed seconds, print one `LONG_WAIT_RESULT exit_code= duration_seconds=` sentinel, and exit with the captured code. Use 24 hours when `deadline` is omitted. Apply the timeout to the entire foreground command chain. With a detached launcher, this bounds monitoring only; bind an exact read-only launcher status command and task identity before launch. 2. Start one terminal session with `yield_time_ms=1000` and `max_output_tokens=2000`, retain its `session_id`, and poll only that session until the process exits. When terminal tools are nested under `functions.exec`, reuse the same terminal session and use `functions.wait` only to resume a yielded exec cell. 3. Poll with empty input and `max_output_tokens=2000`. Set `yield_time_ms` to the smaller of 300000, the host's permitted wait limit, and the milliseconds remaining before the next checkpoint. Keep normal polls inside the monitor; do not wake the parent. 4. At each checkpoint interval, run `progress_probe` once when supplied, with a 30-second timeout. Sample only exact `log_path` and `result_paths` metadata. Do not recursively scan directories, read source files, or read full logs. Treat probe errors or invalid output as `unknown` until the next scheduled checkpoint. 5. Classify checkpoints as: - `progressing` when structured progress advances, the phase changes, or an exact result artifact changes; - `unknown` for the first interval without enough evidence; - `attention` with `attention_kind="task_attention"` when a successful structured probe explicitly reports task failure, `expected_duration_seconds` is exceeded, or two consecutive checkpoints show no observable change. Use `attention_kind=null` for `progressing` and `unknown`. Only the parent may emit `monitor_attention` for a missing checkpoint or failed monitor. 6. Use a probe-provided ETA when available. Otherwise estimate it only from two advancing `completed`/`total` checkpoints. Report `eta_seconds=null` when neither is available. Never infer completion from CPU use, liveness, terminal output, or log growth. 7. Send one compact checkpoint to `report_target`: ```json { "type": "long_wait_checkpoint", "task": "task_name", "elapsed_seconds": 7200, "state": "progressing|unknown|attention", "attention_kind": null, "phase": null, "completed": null, "total": null, "eta_seconds": null, "reason": "short explanation" } ``` 8. Continue owning the same terminal after every checkpoint. Send at most one scheduled checkpoint per interval, including when the evidence is unchanged. 9. Treat exit code `124` as foreground `timed_out`. For a detached launcher, query the bound status command once with a 30-second timeout and report `task_status` and `task_exit_code` separately, using unknown if identity cannot be verified. Monitoring timeout does not prove the worker stopped. Never restart the command. On failure, read at most the final 50 lines of the exact log path when supplied. 10. Read the real exit code and total duration from `LONG_WAIT_RESULT`. Never substitute one poll's `wall_time_seconds` for total command duration. 11. On terminal completion, immediately return only `status`, `exit_code`, `duration`, `result_paths`, and a short failure tail when applicable. Finish so the terminal event wakes the parent. ## Parent waiting protocol 1. After the valid spawn, wait for an agent event (for example `wait_agent(timeout_ms=3600000)`). Respect the host's supported wait limits and higher-priority responsiveness requirements; use the longest permitted event wait. 2. On `progressing` or first-interval `unknown`, return to event waiting. Surface routine progress only when requested; always surface meaningful changes, completion, failure, or required user action. 3. On `task_attention`, perform one bounded read-only diagnosis using the supplied status command, exact process state, exact artifact/log timestamps, and at most 50 log lines. Do not repeat it while the reason and evidence are unchanged. Never stop, restart, or change the task without user authorization. 4. If a full checkpoint interval elapses without a checkpoint or terminal event, inspect the agent once (using `list_agents` when available) and classify this as `monitor_attention`. A shorter host-limited wait timeout alone is not a missed checkpoint. This measures the monitoring channel, not task progress. Inspect the monitor once and return to event waiting without short polls. 5. Return early for user steering or an approval requirement. Otherwise consume the real terminal result and report the compact outcome. 6. If the monitor fails after launch, report `monitor_attention`, inspect the independent project launcher once, and apply the monitor-only recovery protocol below. Never rerun the command automatically. ## Monitor-only recovery Recover only the monitoring channel; never recover by restarting computation. 1. After an observed monitor failure, call `list_agents` once and inspect the independent project launcher once. 2. Reattach only when the launcher explicitly identifies the same canonical task as running and no valid monitor still owns it. 3. Use a fresh monitor through either supported setup path above. Its only command must be the project-owned read-only blocking wait entry point; never repeat `start` or the original command. Treat its first successful progress probe as a new baseline. 4. Monitor-only recovery has no fixed retry limit while those conditions remain true. Communication-layer failures such as a response-stream disconnect may therefore be recovered repeatedly without user intervention. 5. Recovery remains event-driven: perform at most one reattachment for each observed monitor failure and never spawn in a tight retry loop. 6. Stop and request user direction when launcher state or task identity is ambiguous, the canonical task is no longer running, recovery would mutate task state, or a locally fixable helper/probe defect has not been corrected. ## Invariants - Execute the command at most once. - Use a fresh configured monitor with no inherited conversation history. - Each monitor keeps one terminal session for its lifetime. A replacement monitor may own only the project launcher's read-only blocking wait command. - Keep ordinary polls inside the clean-context monitor and limit each poll to 300 seconds. - Attempt one checkpoint per configured interval; default to 3600 seconds. - Report completion and failure immediately with the real exit code. - Never stop, restart, mutate, or rerun the task automatically. Repeated monitor-only reattachment is allowed only under the recovery checks above.