nonblocking-agent-execution

Prevents "agent stopped responding / stuck / no output" failures in sandboxed agent runtimes (Arena Agent Mode, OpenClaw, Codex) where a single long tool call blocks the turn and stdin is closed so interactive prompts hang forever. Provides the detach → bounded-poll → durable-state pattern plus a ready-to-use jobctl.sh runner. Use when: a build/download/model-inference/mass-install takes minutes, a CLI may prompt for input, or the user reports the agent freezing mid-task.

Field-authored in Arena Agent Mode (2026-07) after a real 173-skill install + llama.cpp build froze the session. Synthesizes lessons from ClawHub skills @aowind/long-running-harness, @wonko6x9/durable-task-runner, @skywalker-lili/polling-best-practices, @liyooyin/task-progress-stream, @nyxun123/agent-heartbeat, @hollis9087/long-task-handoff.

The three real causes of "agent not responding"

Cause	Symptom	Fix
Blocking tool call — one bash call runs 20 min	UI shows nothing, user aborts	Detach the work; poll in ≤30 s bursts
Interactive prompt with closed stdin	Hangs forever, never times out	--yes / --no-input shims + always wrap in timeout
Aborted turn kills the child process	Work silently lost, half-done state	Detach with setsid, persist state to disk

Core rules

1. No tool call over ~60 s. Long work is launched, not awaited.
2. setsid nohup … < /dev/null & — survives the turn being cancelled; plain & does not.
3. Bounded wait only. A poll helper that always returns within N seconds. Never wait.
4. Every external command gets timeout N. No exceptions for network CLIs.
5. Non-interactive flags always (--yes, --no-input, -y, DEBIAN_FRONTEND=noninteractive).
6. State on disk, not in context — pid, exit_code, log, started_at per job, so any context reset or new turn can resume by reading files.
7. Report progress every poll ([k/N] item) so the user sees liveness instead of silence.
8. Idempotent resume: recompute what is missing and redo only that, never restart from zero.

The runner

bash

./jobctl.sh start <name> '<command>'   # detached, returns instantly
./jobctl.sh status <name>              # RUNNING pid=… elapsed=…s | DONE exit=0 | DIED
./jobctl.sh wait <name> [max_sec=25]   # bounded — ALWAYS returns
./jobctl.sh log <name> [n]             # tail live output
./jobctl.sh list                       # every job's state

State lives in ~/.jobs/<name>/{cmd,pid,log,exit_code,started_at,finished_at}.

Agent loop

text

start job  →  status (2 s)  →  do other useful work  →  wait 25 s  →  report "[k/N]"  →  repeat  →  verify exit=0

Parallelize independent jobs in one message; only serialize true dependencies.

Resume-after-reset recipe

bash

comm -13 <(ls installed | sort) <(sort wanted.txt) > missing.txt   # diff, don't restart
./jobctl.sh start fill 'while read x; do timeout 120 install "$x"; done < missing.txt'

Verify with a byte-exact or hash-exact assertion, never with "it looked fine".