From 9cb8ee271540007ccf88ed0b00e66317fd806e79 Mon Sep 17 00:00:00 2001
From: Mark Schaller <mjschal@gmail.com>
Date: Sat, 26 Sep 2026 02:32:16 -0400
Subject: [PATCH] Run long commands so that waiting ends with the command (for
 discussion)

Agents lose time to commands that block: a built program waiting on stdin,
a Bazel command queued behind another on the same server lock, and above
all waiting on a long build. Large projects make each more expensive, and
done now requires a clean build from a fresh output base.

The procedure's working-directory note gains a "Long commands" paragraph:
- Run a build or test suite in the foreground, with a timeout long enough
  for it, when the command tool allows that long; it returns the moment the
  command ends.
- If it may take longer, start it in the background with its log and PID
  outside the workspace (so the log is not migrated), and wait with a loop
  on `kill -0` of the saved PID, in 15-second slices, which ends as soon as
  the command does.
- Never wait with `pgrep -f <name>`: the waiting command's own command line
  contains the name, so it always finds itself. Don't sleep a fixed time on
  a guess either.
- A second Bazel command in the same workspace waits for the first; run
  built programs with </dev/null and a timeout.
It does not state the command tool's time limit: that is 10 minutes by
default in Claude Code, and settings raise it.

Measured in any2bazel-lab, on an earlier wording of this change ("run builds
and test suites that may take minutes in the background and poll them"):
agents followed it in eight of ten runs and waited badly. One waited 74
minutes on `while pgrep -f "yb_build.sh"`, which matched its own command
line, for a configure that had finished in 16 seconds. Four others spent 8
to 133 minutes in fixed sleeps of up to 700 s on builds that had already
finished. In all, 232 of the ten runs' minutes were commands still waiting
after their work had ended.

With the wording above, in six re-runs of the same projects, no agent
waited on `pgrep -f`, no sleep was longer than 60 s, and no waiting command
outlasted its work by more than 14 seconds. Waiting after work fell from 153
minutes to 6, and the QGIS migration took 121 minutes instead of 206. The
time-limit sentence was revised after those runs.

This is a proposal for discussion: how an agent should wait on long
commands is partly a property of the agent's tools, which the maintainers
may prefer to leave to them.

Lab-Proposal: P12
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 SKILL.md | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/SKILL.md b/SKILL.md
index 834ab02..a925e45 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -204,6 +204,20 @@ the reference build or bazel.
 > repo root** (the Bazel workspace). Only the `$SKILL_DIR/scripts/*.py` helpers
 > live elsewhere.
 >
+> **Long commands.** Run a build or test suite in the foreground, with a
+> `timeout` long enough for it, when your command tool allows that long (its
+> maximum timeout is in its description; 10 minutes by default in Claude Code):
+> it returns the moment the command ends. If it may
+> take longer, start it in the background as
+> `cmd > /tmp/cmd.log 2>&1 & echo $! > /tmp/cmd.pid` (outside the workspace, so
+> the log is not migrated) and wait in slices that end as soon as it does,
+> repeating until it has ended:
+> `for i in $(seq 36); do kill -0 "$(cat /tmp/cmd.pid)" 2>/dev/null || break; sleep 15; done; tail -5 /tmp/cmd.log`.
+> Never wait with `pgrep -f <name>`: the waiting command's own command line
+> contains the name, so it always finds itself. Don't sleep a fixed long time
+> on a guess, either. A second Bazel command in the same workspace waits for
+> the first. Run built programs with `</dev/null` and a `timeout`.
+>
 > **`<repo_root>` placeholder:** the project's source/workspace root. It MUST be
 > **identical** in the reference extractor (`extract_<frontend>.py`) and
 > `extract_bazel.py` calls: both key translation units by their path relative