A run by hand and the console's "fix this" are the run of the same person's click less than a minute before, as a webhook's blind retry is, not the run of the clock's minute; a firing is admitted against its caps under the trigger's row lock (and, on a repository, one lock for every repository cap), a failed run's retry included; and a run that has had no session for ten minutes is ended failed, with the reason, and audited¶
Decision 930 · accepted · 2026-10-23 · supersedes 914, 917
A click is the run of the click a minute before, a cap is counted under a lock, and a run with no session is ended¶
It replaces the minute of a run by hand in Decision 914 and of "fix this" in Decision 917; the rest of those two stands.
Context¶
- The clock's minute.
admin.trigger.runkeyed a run onmanual:<trigger>:<subject>:<minute>and the console's "fix this" onfix:<trigger>:<issue>:<subject>:<minute>. A click at :59 and a second one a moment later, or a retry of a call whose answer was lost, were two runs, the second skipped under the cap the first held. - Counted apart.
start/3counted live runs and wroteskippedoutside any lock. Two firings with keys of their own that raced on one trigger with a concurrency of 1 each wrote its run, then each counted the other's (stillcreated, no session) as live, and both were skipped: nothing ran. A run on a repository counts against its profile's and its team's caps across triggers too, which no one trigger's row covers. - A failed create's retry went to
create/3without counting, so a run that failed while another took its place made a second session past a concurrency of 1. - A run left with no session, by a request that crashed or a replica that went down
between the run's row and its session, stayed
createdwith no session. It counted as live in every cap for good, and every repeat of it waited five seconds and was answered409. Nothing ended it.
Decision¶
- A window of the person's.
Triggers.fire_by_hand/5firesmanualunder a window the caller names, the wayfire_in_window/5does for a webhook: under the trigger's row lock it looks for a run of the trigger keyed under the window that fired less than a minute before now, or after it, and repeats that run; only if there is none does it write one, keyed with the window and the instant. A run by hand's window ismanual:<trigger>:<subject>:, "fix this"'sfix:<trigger>:<issue>:<subject>:: the prefixes the minute keys had, so a click from just before an upgrade is found. What follows the window must read as an instant, so a subject that is another's and more (ab,ab:c) is a window of its own; the window is escaped forLIKE. - Admitted under a lock. Whether a run starts or is skipped is decided in one
transaction that takes the trigger's row (
FOR UPDATE) and, for a trigger on a GitHub repository, one transaction-level advisory lock that every repository cap is counted under; the skip is written inside it. Firings that race are decided one after another: the first counts the others' undecided runs as live and is skipped, the next counts a skipped run as nothing, and one of them starts. A run admitted stayscreatedand live until its session is made or its create fails. - A failed create's retry is a firing for the caps: it is admitted as a new one is,
set back to
createdunder the lock if it starts, andskippedwith the cap's reason if it does not. - A run with no session for ten minutes is ended.
Triggers.end_unmade/1, run on every tick of the scheduler (the plane's one periodic worker for triggers), sets a run that iscreated, has no session, and has not changed for ten minutes tofailed, with the reason on the row, logs it, and audits it astrigger.run.endbyscheduleron<team>/<trigger>with the run's id. The update is conditional on the row still having no session, so a create that finished late keeps its session. The next call with the run's key makes its session, as after any create that failed. Ten minutes because a create is a few writes and a placement that gives up after fifteen seconds.
Choices not taken¶
- Keep the minute and also look in the minute before. Two clicks either side of :00 each look before the other has written; as in Decision 927, a window needs the lock.
- Hold the row lock across the create, so a cap is counted and the session made in one step. A create is a harness call that places the session on a pod; inside the transaction the session row would be invisible to the pod until commit, and a slow pod would hold every firing of the trigger.
- One advisory lock per repository or per team. The profile's cap counts runs on every team's repositories, and the team's every repository; a lock narrower than the plane's repository runs would leave one of the two counted apart. Firings on repositories are few; one lock held for two counts costs nothing measurable.
- End a sessionless run by
fired_at. A failed run retried now iscreatedagain with its oldfired_at;updated_atis when it was last decided.
Governs: apps/troupe_plane/lib/troupe/plane/triggers.ex, apps/troupe_plane/lib/troupe/plane/triggers/scheduler.ex, apps/troupe_plane/lib/troupe/plane/admin.ex, apps/troupe_plane/lib/troupe/plane/github/issues.ex