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. The role configuration is bundled at 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 <deadline> bash -lc <shell-quoted-command>, capture the Bash SECONDS value. After timeout returns, capture $?, compute the total elapsed seconds, print one LONG_WAIT_RESULT exit_code=<code> duration_seconds=<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:

   {
     "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.