throttle

throttle — register the pause, then stop

throttle <your-name> [--reason "..."]

Returns immediately. Then close your turn: no other task, no other command.

Why it works this way

Until 2026-07-30 the throttle was a contract you had to honour yourself: jht-throttle blocked your own process with a sleep loop, and if that process died you had to notice and re-block. Every failure we observed in production was born from that design. The worst one: an Analyst launched jht-throttle … & inside a compound command that the tool-call timeout killed after 60s. The detached child died with its parent, the agent closed its turn convinced the pause was running — and nobody ever woke it again. 2h15m of stall, with the watchdog reporting the session as idle = healthy.

Now the timer belongs to an engine that is not a child of your shell:

YOU                          ENGINE (daemon, outside your process)
 |                              |
 |-- throttle <me> ------------>|  reads the duration the Capitano calibrated
 |                              |  flags you IN_THROTTLE
 |   (you close the turn        |  arms the timer ON DISK
 |    and do NOTHING)           |
 |                              |
 |<-- [RIPRENDI] over tmux -----|  timer expired -> flag becomes NOTIFIED
 |                              |
 |-- throttle-ack <me> -------->|  YOU flip NOTIFIED -> ACTIVE
 |   (first act on waking)      |

A daemon restart loses nothing: the deadline is an absolute timestamp on disk, so there is no in-memory timer to re-arm.

The rules

• You never pass a number and you never see one. The duration lives in $JHT_HOME/config/throttle.json, the Capitano owns it, and the engine reads it when it arms the timer — so a recalibration bites on your next cycle without anyone having to tell you. Do not hardcode throttle 600 in your loop.
• END YOUR TURN after the call. The call returns in milliseconds precisely so that no tool-call timeout can kill it. If you keep working after it, you are running with no pause at all — which is what the throttle exists to prevent.
• NEVER background it (&, nohup, disown, a background task). There is nothing to background: it does not sleep.
• NEVER use raw sleep N for a throttle pause. Plain sleep is only for very short waits between retries (≤ 5 s), where logging would be noise.
• On waking, throttle-ack <your-name> is your first command — see the throttle-ack skill. Skip it and your flag stays on NOTIFIED, which the watchdog reads as proof that you are blocked, and it escalates to the Capitano about an agent that is perfectly fine.
• --reason is optional but useful: a short tag ("post-batch", "waiting for the critic") makes logs/throttle-engine.jsonl readable later.