Skip to content

Autonomous development for real products. Governed agents build from specs you approve, follow the rules you set, and nothing merges until another agent proves it. Your decisions, judgement and taste are the bar that work must clear. Declare your vision and let agents build it.

docs(pool): describe local-only holds and status projection [C7]

Corey Olsonb9fc7e3a0c55
diff --git a/docs/api.md b/docs/api.md
index 34edf335..00dc6533 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -20,7 +20,7 @@ Release priority is separately opt-in with `"gate": { "queue": { "currentRelease
`pullboard init` and `pullboard resume` keep `pullboard view` running in the background, so pullboard.dev finds this computer's boards with no command. When no view answers on the view port (4890, or `PULLBOARD_VIEW_PORT`), they start one detached, writing its output to a private `view-<port>.log` beside the view's session record in `~/.pullboard`; a view already running is left alone, and a busy port is one line that fails neither command. init prints one line naming where the view runs, its log and the `kill <pid>` that stops it; resume prints that line only when it starts the view or cannot. Both JSON results carry `view` with `state` (`started`, `running`, `busy`, `off` or `failed`), `port` and, for a view, `pid`. It is on unless the machine sets `"view": { "background": false }` in `~/.pullboard/settings.json`; `PULLBOARD_VIEW_BACKGROUND=0` turns it off for one process tree, and the test runner sets it so tests leave no view behind.
-The memory hold is opt-in per machine with `"gate": { "memoryFloorMB": <n> }` in `~/.pullboard/settings.json`; absent, it is off and the pool admits by slots alone, as before. When set, before admitting a run the machine gate pool reads the machine's memory: on macOS the kernel's memory pressure level and free percentage, on Linux `MemAvailable` and the pressure stall averages in `/proc/pressure/memory`. The whole queue, landings included, waits in place while pressure is critical or free memory is under that many megabytes (`0` leaves only the pressure check). A held run prints one line naming why and the three biggest processes by memory, with pid, size and working directory, and starts once memory recovers. While the floor is set, `pullboard resources` prints the same line and returns it as `memory` in JSON; with no floor it reads no memory and `memory` is `null`. Where memory cannot be read, the pool admits by slots alone and prints one warning that memory is not checked there.
+The memory hold is opt-in per machine with `"gate": { "memoryFloorMB": <n> }` in `~/.pullboard/settings.json`; absent, it is off and the pool admits by slots alone, as before. When set, before admitting a run the machine gate pool reads the machine's memory: on macOS the kernel's memory pressure level and free percentage, on Linux `MemAvailable` and the pressure stall averages in `/proc/pressure/memory`. Only runs executing on this machine, including local landing and short-slot runs, wait while pressure is critical or free memory is under that many megabytes (`0` leaves only the pressure check). A compatible runner-bound run bypasses this local hold and waits for runner capacity instead; it does not acquire a local executor while the hold applies. A held run prints one line naming why and the three biggest processes by memory, with pid, size and working directory, and starts once memory recovers. While the floor is set, `pullboard resources` prints the same line and returns it as `memory` in JSON; with no floor it reads no memory and `memory` is `null`. Where memory cannot be read, the pool admits by slots alone and prints one warning that memory is not checked there. `pullboard resources` marks locally memory-held queue entries with `memoryHeld: true`. `pullboard status --json` adds optional `memoryHeld`, an array of current held runs (`agent`, `repo`, `item`, `kind`, `since`), empty when no runs are held or the floor is off, and `null` if that read is unavailable. Text status names each held run. This is a read-only resource-queue projection; it never migrates the pool.
Short gate slots are opt-in per machine with `pullboard settings gate.shortSlots <n>`, stored as `"gate": { "shortSlots": n }`; the default `0` keeps them off and the pool behaves as before. With `n` above `0`, up to `n` runs that name their test files (a `pullboard check` or a review whose check is a literal `node bin/run-tests.js` call over test files, or a direct `node bin/run-tests.js <files>`) are admitted on short slots while every gate slot is held. Whole suites, directories, landings, diagnostics and anything the parser cannot read never use them, and a child that does not name its files cannot reuse a short lease (`SHORT_SLOT_FULL_SUITE`). Short slots do not add to `gateSlots`, and browser runs still count against `browserSlots`. `pullboard settings` prints `gate.shortSlots`; `pullboard resources --json` reports `shortSlots`, each gate holder's `slot` (`gate` or `short`), and `requestedSlot: "short-eligible"` on a waiting run that may take one.