From 29e1d9acca85cd8cd4e5e8dff512b2d01c403792 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9=20Padez?= Date: Fri, 21 Aug 2026 02:54:42 +0000 Subject: [PATCH] a background job that prints nothing looks like a hung one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Officer shows a live panel per background job carrying that job's output, and the user watches it. A command that writes nothing until it finishes leaves that panel reading "Nothing written yet." for the whole run, which is exactly what a hung job looks like. Written after doing it twice in one session: plugin installs driven from a script printed nothing for two minutes, and the owner asked whether I was stuck. Both times the work was fine. So: verbose flags on, echo around each step when the tool has none, per-item output in a loop, and the result on the last line — that is the line still on screen when the panel stops. Plus the buffering trap, because a program that prints steadily still shows nothing through a pipe. Co-Authored-By: Claude Opus 5 --- affordances/officer/core/background-jobs.md | 25 +++++++++++++++++++++ 1 file changed, 25 insertions(+) create mode 100644 affordances/officer/core/background-jobs.md diff --git a/affordances/officer/core/background-jobs.md b/affordances/officer/core/background-jobs.md new file mode 100644 index 0000000..2c324d8 --- /dev/null +++ b/affordances/officer/core/background-jobs.md @@ -0,0 +1,25 @@ +--- +name: Background jobs report progress +description: Use when starting anything in the background, or any command that will take more than a few seconds. +version: 1 +--- + +**Officer shows a live panel for every background job, and it shows that job's output.** The user watches +it while the job runs. If the command writes nothing until it finishes, that panel says +`Nothing written yet.` for as long as the work takes — which is indistinguishable from a job that has +hung, and is read as one. + +So a background job has a second requirement beyond doing its work: **it must say what it is doing while +it does it.** + +- Prefer the verbose form of whatever you are running. Most tools have one, and it is off by default. +- If the tool cannot report progress, wrap it — `echo` before and after each step, so the panel shows the + step that is running and the step that finished. +- A long loop prints per item, not at the end. `12/50 done` beats one summary nobody sees for ten minutes. +- Make the **last** line the result. That is the line still on screen when the panel stops. + +Watch for buffering. Output through a pipe is block-buffered, so a program that prints steadily can still +produce nothing for minutes — `stdbuf -oL`, `--line-buffered`, or the tool's own unbuffered flag fixes it. + +None of this applies to a command that finishes quickly. It applies the moment you decide something is +long enough to background.