[anakanemison]

Part 21 of 23 of a stacked series (tracking issue: #35). Based on D3-narrow-the-stop, the previous part: review and merge that first.

Kind: discussion. Lab proposal: P12.

What the migration runs showed

The first wording ("in the background and poll them") cost 232 waiting minutes across ten runs, including a 74-minute self-matching pgrep -f wait. With the revised text, waiting after work ended fell from 153 minutes to 6 across six projects, and qgis took 121 minutes instead of 206 (runs 091-096).

The change

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.

Testing

pytest tests/ at this commit: 196 passed (130 on main).

🤖 Generated with Claude Code