feat(hooks): a hook is a command owned for an interval, and during_build

Adds the background command the feature was asked for — music that plays for
the length of the build and stops when it ends, optionally restarting — by
unifying it with the hooks that already existed rather than bolting a mode
onto them.

## The model

A hook is a command mcpp OWNS FOR AN INTERVAL. The event names the interval.

    build_start / build_finished / build_failed   opens at the event,
                                                  closes when the command exits
    during_build                                  opens before the build,
                                                  closes after it

The first three are SELF-CLOSING, and "synchronous" stops being a separate
mode: it is what an interval closed by its own command looks like. Everything
that would otherwise be a special case for `during_build` falls out of that one
difference instead of being declared:

  * `timeout_seconds` bounds one run, so it does not apply where the build
    already bounds it — and is rejected there rather than reinterpreted.
  * `loop` restarts a command that ended before its interval did, which a
    self-closing interval makes impossible — so it is rejected there too, with
    a message naming `during_build`.
  * `side_effect` is unchanged. For `during_build`, "failure" means could not
    start, or failed to stay up. Being stopped because the interval closed is
    not a failure.

`during_build` closes BEFORE the terminal hook, so a "build finished" sound is
not competing with the background music it replaces.

Spelling: every event value is a string or a table (`{ cmd, timeout_seconds }`
or `{ cmd, loop }`) — the string-or-table shape `[dependencies]` and
`[resources].version-info` already use, so no new parsing semantics.

## What it actually cost

The schema was the small half.

1. A PROCESS GROUP. `unix/bounded_process.cppm` killed the direct child, which
   is enough for `sh -c "sleep 5"` (the shell execs) and not enough for
   `sh -c 'player & wait'` — the shell dies and the player keeps the audio
   device. A background player that survives its build, from a process the user
   cannot name, is the worst failure this feature can have. POSIX now spawns
   with POSIX_SPAWN_SETPGROUP and stops with killpg; Windows already had the
   right shape in its job object. The same gap is why `mcpp test --timeout` and
   `[build] build_program_timeout` could leave grandchildren behind.

   The poller deliberately does NOT reap (waitid WNOWAIT): an unreaped leader
   is what keeps the group id from being recycled between the poll and the
   kill.

2. A SIGNAL HANDLER. Its own process group is what makes killpg possible AND
   what stops the terminal's SIGINT from reaching the child — so Ctrl-C would
   have killed mcpp and left the music playing. mcpp had no signal handling at
   all; there is now the minimum that is async-signal-safe (a
   `volatile sig_atomic_t` group id, killpg, re-raise). Windows gets a console
   handler, though its job object already covers process death.

3. A RESTART FLOOR. `loop` on a typo'd command is a fork bomb. 250 ms between
   runs, and five consecutive runs that end UNSUCCESSFULLY within a second stop
   the loop and report. Both halves matter: an early draft counted short runs
   regardless of exit code and killed the build after five restarts of a
   perfectly healthy `echo`.

A supervisor thread exists only when `loop = true`.

## Criteria

State, not log lines — "mcpp said it stopped the command" passes whether or not
anything stopped. The e2e asserts the heartbeat file grew and then did not grow
for a further second; that `loop` produces >= 2 runs where its absence produces
exactly 1; that a command which cannot stay up stops and is reported; that
`loop` on `build_start` is refused with a diagnostic naming `during_build`; and
that an interrupted build leaves nothing running. The writer is a GRANDCHILD of
the command mcpp starts, which is the case `kill(pid)` misses and `killpg`
catches. The Ctrl-C case is POSIX-only and prints its skip, because a test that
cannot fail on Windows would read as coverage.

Design: .agents/docs/2026-08-30-project-build-hooks-owned-intervals.md

Author: speak-agent

.agents/docs/2026-08-30-project-build-hooks-owned-intervals.md

@@ -0,0 +1,193 @@
+# Project build hooks as owned intervals (#496)
+
+## The question this design answers
+
+The first shape of `[hooks]` gave `mcpp build` three commands — `build_start`,
+`build_finished`, `build_failed` — each run to completion with a timeout, each
+judged by its exit code.
+
+The request that followed was a background command: music that plays *for the
+duration of the build* and stops when it ends, optionally restarting when the
+player exits. Written as a knob it looks like
+
+```toml
+build_start = { cmd = "play bgm.mp3", loop = true }
+```
+
+but `loop` is not the new thing. The new thing is that this command's life is
+**longer than the moment that started it**. Adding `background = true` to
+`build_start` would give that key two incompatible meanings and would silently
+change what `timeout_seconds` and `side_effect` mean for one of them — a table
+whose keys mean different things depending on a sibling key is the shape this
+design exists to avoid.
+
+## The model
+
+> A hook is a command mcpp **owns for an interval**. The event names the
+> interval. mcpp starts the command when the interval opens and ends it when
+> the interval closes.
+
+| Event | The interval opens | The interval closes |
+|---|---|---|
+| `build_start` | after preparation, before the build | when the command exits |
+| `build_finished` | after a build that succeeded | when the command exits |
+| `build_failed` | after a build that failed | when the command exits |
+| `during_build` | after preparation, before the build | after the build, before the terminal hook |
+
+The first three have **self-closing** intervals. "Synchronous" is not a
+separate mode in this model — it is what an interval closed by the command
+itself looks like. `during_build` is the one interval closed by something else,
+and everything that reads as a special case for it falls out of that single
+difference rather than being declared:
+
+- **`timeout_seconds` bounds one run of the command.** For a self-closing
+  interval that is the whole hook. For `during_build` the build already bounds
+  it, so the key is *rejected* there rather than accepted and reinterpreted —
+  a per-run cap would only be enforceable when `loop` is on (nothing is
+  polling otherwise), and a key that works under one sibling setting and not
+  another is the hole this design is trying not to dig.
+- **`loop` restarts a command that exits before its interval closes.** A
+  self-closing interval ends *when the command exits*, so `loop` can never fire
+  there. It is rejected on those events rather than accepted and ignored, with
+  a message naming `during_build`.
+- **`side_effect` is unchanged**: does a hook failure fail the build. For
+  `during_build`, "failure" means *failed to start*, or *failed to stay up*
+  (below). Being stopped because the interval closed is not a failure.
+
+Ordering inside the lifecycle:
+
+```text
+during_build opens
+build_start
+    ├─ build succeeds → during_build closes → build_finished
+    └─ build fails    → during_build closes → build_failed
+```
+
+`during_build` closes **before** the terminal hook, not after. A "build
+finished" sound playing over the background music it was supposed to replace is
+the whole reason the order is fixed rather than incidental.
+
+## Schema
+
+Every event value is a string or a table; the string is sugar.
+
+```toml
+[hooks]
+build_start    = "echo start"                              # = { cmd = "echo start" }
+build_finished = "notify-send 'build finished'"
+during_build   = { cmd = "mcpp-hooks-audioplayer bgm", loop = true }
+
+# Table-level, unchanged.
+timeout_seconds = 10
+enabled         = true
+side_effect     = true
+```
+
+Per-event table keys: `cmd` (required, non-empty), `timeout_seconds`
+(overrides the table default for this event), `loop` (`during_build` only).
+
+The string-or-table pattern is already how `[dependencies]` and
+`[resources].version-info` are spelled, so it introduces no new parsing
+semantics — Appendix A of docs/05 is satisfied for the same reason the first
+shape satisfied it: fixed keys, open values, and no key that duplicates an
+answer another section already gives.
+
+## What the feature actually costs
+
+The schema is the small half. A process whose life spans the build needs three
+things mcpp does not have.
+
+### 1. A process group, because SIGKILL on a pid is not enough
+
+`modules/platform/src/unix/bounded_process.cppm:216` kills the direct child:
+
+```cpp
+::kill(pid, SIGKILL);
+```
+
+For `sh -c "sleep 5"` that is sufficient — the shell execs the command. For
+`sh -c "while :; do play a.mp3; done"` it is not: the shell dies and `play`
+survives. **Music that cannot be stopped, from a process the user cannot name,
+is the worst failure this feature can have**, and it is the default outcome
+without process groups.
+
+So the POSIX side gains `posix_spawnattr_setpgroup` + `killpg`. Windows already
+has the right shape: a Job object with `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE`
+(`windows/bounded_process.cppm:205`), which takes the whole tree — and takes it
+even if mcpp dies, because the handle closes with the process.
+
+This is worth doing on its own terms: the same gap is why
+`mcpp test --timeout` and `[build] build_program_timeout` can leave
+grandchildren behind today.
+
+### 2. A signal handler, because a process group stops receiving Ctrl-C
+
+The two requirements fight each other. A child in its own process group no
+longer receives the terminal's SIGINT — which is what makes `killpg` possible
+and *also* what makes Ctrl-C leave the music playing. Both halves are needed:
+its own group, plus a SIGINT/SIGTERM handler in mcpp that stops the group
+before re-raising.
+
+mcpp installs no signal handlers today. The one added here is the minimum that
+is async-signal-safe: a `volatile sig_atomic_t` holding the process-group id, a
+handler that calls `killpg` (which is async-signal-safe) and re-raises the
+default action. It is installed only while a spanning hook is running.
+
+Windows needs no equivalent for correctness — the job object already covers
+process death — but `SetConsoleCtrlHandler` is installed for a clean stop.
+
+### 3. A restart floor, because `loop` on a typo is a fork bomb
+
+`loop = true` with `play /nonexistant` restarts thousands of times per second
+for the length of the build. Two bounds, both fixed in v1 rather than
+configurable, because a knob whose wrong value is a spin is not a knob:
+
+- **250 ms between runs.**
+- **Five consecutive runs that exited non-zero in under a second** stops the
+  loop and reports a hook failure: *"during_build command failed to stay up".*
+  Whether that fails the build is `side_effect`, as everywhere else.
+
+A supervisor thread exists **only when `loop = true`**. Without it, a spanning
+hook is a spawn and a stop, and no thread is created.
+
+## Stopping
+
+POSIX: `SIGTERM` to the group, a 2 s grace period, then `SIGKILL`. A player
+asked to stop should get to close its audio device.
+
+Windows: the job object is closed, which terminates the tree at once. There is
+no graceful equivalent that does not require enumerating the job's processes
+and posting window messages; the asymmetry is stated rather than hidden.
+
+## Output
+
+A self-closing hook inherits stdio, which is safe because nothing else is
+writing at that moment. A spanning hook writes **concurrently with ninja** and
+would interleave into the middle of a compiler diagnostic. Its output is
+therefore discarded by default, and inherited under `--verbose` — no new schema
+key, and the answer to "why is there no music" is one flag away.
+
+## Criteria
+
+The assertions this design has to earn are about *state*, not about log lines —
+"we called stop" is not evidence that anything stopped.
+
+1. **It runs during the build.** The command appends a heartbeat line every
+   200 ms; the file is non-empty when the build ends.
+2. **It is stopped.** Record the heartbeat file's size after `mcpp build`
+   returns, wait one second, read it again: unchanged. A log line saying
+   "stopped" would pass whether or not the process died.
+3. **`loop` restarts it.** A command that exits immediately produces a heartbeat
+   count that grows across the build; without `loop` it produces exactly one.
+4. **The whole tree dies, not just the shell.** The command is
+   `sh -c '... & wait'`, so the writer is a grandchild. This is the case
+   `kill(pid)` misses and `killpg` catches, and it is the only assertion that
+   distinguishes the fix from the bug.
+5. **The failure cap trips.** A command that fails instantly stops after five
+   attempts and reports; the heartbeat count is bounded, not "large".
+6. **Ctrl-C leaves nothing behind.** POSIX only: `mcpp build` in the
+   background, `kill -INT`, then criterion 2. Sending Ctrl-C to another process
+   on Windows needs a helper this suite does not have; the gap is declared
+   rather than papered over with a test that passes vacuously.
+7. **A self-closing event rejects `loop`.** Otherwise the key is accepted,
+   does nothing, and the user concludes the feature does not work.

docs/05-mcpp-toml.md

@@ -2096,55 +2096,98 @@ do`.
 
 ### 2.16 `[hooks]` — Project Build Lifecycle Commands
 
-`mcpp build` can run one host-shell command before the build and one command
-for its terminal result:
+A hook is a command `mcpp build` **owns for an interval**, and the event names
+the interval:
 
 ```toml
 [hooks]
 build_start = "echo build started"
 build_failed = "notify-send 'build failed'"
 build_finished = "notify-send 'build finished'"
 
+# Runs alongside the build and is stopped when it ends.
+during_build = { cmd = "mcpp-hooks-audioplayer bgm", loop = true }
+
 # Optional; these are the defaults.
 timeout_seconds = 10
 enabled = true
 side_effect = true
 ```
 
-| Key | Type | Default | Meaning |
+| Key | Type | Default | The interval it names |
 |---|---|---:|---|
-| `build_start` | string | — | Runs after project preparation, immediately before the build |
-| `build_failed` | string | — | Runs when the build exits unsuccessfully |
-| `build_finished` | string | — | Runs when the build exits successfully |
-| `timeout_seconds` | integer, 1–86400 | `10` | Maximum time for each command |
+| `build_start` | command | — | Opens after project preparation, closes when the command exits |
+| `build_finished` | command | — | Opens after a build that succeeded, closes when the command exits |
+| `build_failed` | command | — | Opens after a build that failed, closes when the command exits |
+| `during_build` | command | — | Opens before the build, closes after it |
+| `timeout_seconds` | integer, 1–86400 | `10` | Bounds one run of a command |
 | `enabled` | bool | `true` | Enables all commands in this table |
 | `side_effect` | bool | `true` | Whether a hook failure makes the overall build fail |
 
-Commands run synchronously through the host shell (`/bin/sh` or `cmd.exe`),
-with the **project root** as their working directory — not the directory
-`mcpp build` was typed in, so a relative path in a hook means the same thing
-wherever the build was started. Standard input/output/error keep their ordinary
-terminal behaviour. Missing event commands are skipped.
+The first three intervals are **self-closing** — they end when the command
+does. "Synchronous" is not a separate mode here; it is what a self-closing
+interval looks like. `during_build` is the one interval closed by something
+else, and the two keys that only make sense for one shape follow from that
+rather than being exceptions.
+
+A command is a string, or a table when it needs options:
+
+| Table key | Applies to | Meaning |
+|---|---|---|
+| `cmd` | every event | The command. Required. |
+| `timeout_seconds` | self-closing events | Overrides the table default for this event |
+| `loop` | `during_build` | Restart the command if it exits before the build ends |
+
+`loop` on a self-closing event and `timeout_seconds` on `during_build` are both
+**errors**, not ignored keys: a self-closing interval ends when its command
+exits, so there is nothing to restart, and `during_build` is already bounded by
+the build. A key that is accepted and does nothing reads as a broken feature.
+
+Commands run through the host shell (`/bin/sh` or `cmd.exe`), with the
+**project root** as their working directory — not the directory `mcpp build`
+was typed in, so a relative path in a hook means the same thing wherever the
+build was started. A self-closing command keeps ordinary terminal
+input/output. Missing event commands are skipped.
 
 The lifecycle is:
 
 ```text
+during_build opens
 build_start
-    ├─ build succeeds → build_finished
-    └─ build fails    → build_failed
+    ├─ build succeeds → during_build closes → build_finished
+    └─ build fails    → during_build closes → build_failed
 ```
 
+`during_build` closes **before** the terminal hook, so a "build finished" sound
+is not competing with the background music it replaces.
+
 `build_failed` and `build_finished` are mutually exclusive, and both are
 reachable only after `build_start` has run. A project that cannot be *prepared*
 — an invalid manifest, an unresolvable dependency, no usable toolchain — fires
 nothing: it has not started building, and its hook program may be exactly what
 preparation would have installed.
 
 A hook command that cannot start, returns non-zero, or exceeds its timeout is a
-hook failure. With `side_effect = false`, mcpp reports a warning and preserves
-the build's result; with `true`, it returns failure — but a build that failed on
-its own keeps its own exit code, so `mcpp build` never reports a compile error
-as a notifier problem. A hook's own failure does not trigger another hook.
+hook failure. For `during_build` there is one more: a looped command that
+**fails to stay up** — five consecutive runs ending unsuccessfully within a
+second — stops being restarted and is reported. (A command that finishes
+quickly and *successfully* is doing exactly what `loop` was asked to repeat,
+and is not a failure.) With `side_effect = false`, mcpp reports a warning and
+preserves the build's result; with `true`, it returns failure — but a build that
+failed on its own keeps its own exit code, so `mcpp build` never reports a
+compile error as a notifier problem. A hook's own failure does not trigger
+another hook.
+
+Two things are worth knowing about a `during_build` command specifically:
+
+- **Its output is discarded**, because it writes concurrently with the build
+  and would otherwise land in the middle of a compiler diagnostic. Run
+  `mcpp build --verbose` to see it.
+- **It is stopped as a process tree**, not as a process. `player & wait` makes
+  the player a grandchild of the command mcpp started, and stopping only the
+  latter would leave the audio device held after the build. mcpp puts the
+  command in its own process group (a job object on Windows) and stops that,
+  including when the build is interrupted with Ctrl-C.
 
 Scope, precisely:
 
@@ -2162,9 +2205,10 @@ Scope, precisely:
   already-current hooked project to cost a preparation pass rather than
   milliseconds.
 
-An unrecognised key in `[hooks]` is a warning (an error under `--strict`), so a
-manifest written for a newer mcpp still loads. An unrecognised *value* — a
-non-string command, a `timeout_seconds` outside 1–86400 — is a manifest error.
+An unrecognised key in `[hooks]`, or inside one event's table, is a warning (an
+error under `--strict`), so a manifest written for a newer mcpp still loads. An
+unrecognised *value* — a missing or non-string `cmd`, a `timeout_seconds`
+outside 1–86400, a key offered to the wrong interval — is a manifest error.
 
 > **A hook is code, and `mcpp.toml` is part of the repository.** Building a
 > freshly cloned project runs whatever its `[hooks]` say, with the privileges
@@ -2178,6 +2222,7 @@ than adding media handling to mcpp:
 
 ```toml
 [hooks]
+during_build = { cmd = "mcpp-hooks-audioplayer bgm", loop = true }
 build_finished = "mcpp-hooks-audioplayer niulai-mm"
 build_failed = "mcpp-hooks-audioplayer niulai-niulai"
 side_effect = false
@@ -2186,6 +2231,10 @@ side_effect = false
 deps = ["xim:mcpp-hooks-audioplayer@0.0.1"]
 ```
 
+Background music for the length of the build, a different sound for how it
+ended, and `side_effect = false` so that a missing audio device is a warning
+rather than a failed build.
+
 ## Appendix A. Schema Ownership Principle (admission criteria for new fields)
 
 > **Closed syntax, open vocabulary**: whoever owns the parsing semantics defines the keys; whoever owns the domain knowledge defines the values.