AGENTS.md under Delegation says:
Wait in a background process, not in a poll loop.
The rule is right but stops one step short. A backgrounded wait whose command is broken emits nothing, and that looks exactly like a wait whose condition has not happened yet. A poll loop at least shows the agent every failure; backgrounding hides them.
Hit today in ESPHome-Config. A CI watcher polled gh pr checks <n> --json name,bucket. The installed gh is 2.46.0 and has no --json on that subcommand, so every poll wrote a usage error to stderr, exited non-zero, and the script's || echo '[]' fallback substituted an empty array. No stdout meant no events, for 25 minutes, while CI had been green for most of it. I kept reporting the watch was running and the maintainer kept saying it looks green. ESPHome-Config's own OPERATIONS.md already documented that this flag does not exist in the installed gh, which is what makes it an instruction gap rather than bad luck.
Clauses that would have caught it:
- Run the command once in the foreground and read its output before backgrounding it. A wait is only as good as the command inside it.
- Never let a fallback stand in for a failed command in a wait.
|| echo '[]', || true, and 2>/dev/null convert an error into "nothing yet". Same reasoning as the existing rule against suppressing the output of a write.
- Make the wait emit on failure as well as on success, so silence means "still running" and nothing else.
AGENTS.mdunder Delegation says:The rule is right but stops one step short. A backgrounded wait whose command is broken emits nothing, and that looks exactly like a wait whose condition has not happened yet. A poll loop at least shows the agent every failure; backgrounding hides them.
Hit today in ESPHome-Config. A CI watcher polled
gh pr checks <n> --json name,bucket. The installed gh is 2.46.0 and has no--jsonon that subcommand, so every poll wrote a usage error to stderr, exited non-zero, and the script's|| echo '[]'fallback substituted an empty array. No stdout meant no events, for 25 minutes, while CI had been green for most of it. I kept reporting the watch was running and the maintainer kept saying it looks green. ESPHome-Config's ownOPERATIONS.mdalready documented that this flag does not exist in the installed gh, which is what makes it an instruction gap rather than bad luck.Clauses that would have caught it:
|| echo '[]',|| true, and2>/dev/nullconvert an error into "nothing yet". Same reasoning as the existing rule against suppressing the output of a write.