@edgehero/pi-dispatch-admin 1.3.0 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-admin",
-  "version": "1.3.0",
+  "version": "1.5.0",
   "description": "Operator console (a pi extension) + skill for pi-dispatch: run the pi coding agent as a self-hosted service. A /dispatch TUI for the queue, spend caps, run history, editable GitHub, GitLab, Forgejo and Azure DevOps triggers (cron/label/comment/PR/MR/work item), and scheduled pause windows — plus AI-operable, human-confirmed controls. Runs against a live pi-dispatch deployment.",
   "keywords": [
     "pi-package",

package/skills/operate-pi-dispatch/SKILL.md

@@ -41,6 +41,12 @@ dialog before it takes effect**:
   (per folder/repo "quiet hours": runs for a scope are deferred between certain times and auto-resume after;
   `dispatch_pauses` lists them with their index). `dispatch_pause_edit` is a partial change — pass the index
   plus only the fields to alter. Deferring never drops a job and costs no budget.
+- `dispatch_limit_add` / `dispatch_limit_edit` / `dispatch_limit_delete` — manage scoped limits (per
+  repo/folder budget caps and concurrency: `day`/`week`/`month` job-count caps refuse a job pre-spend with
+  reason `scope-cap`, never retried; `concurrent` defers the excess, never drops it; `dispatch_limits`
+  lists them with their index and used counts). `dispatch_limit_edit` is a partial change — pass the index
+  plus only the fields to alter. Scopes match exactly (a repo `owner/name` or an ABSOLUTE folder path, no
+  globs).
 
 Use them like this:
 
@@ -159,11 +165,14 @@ about the trigger is the same — the `on.type`, the `{any, all, none}` label pr
 Three things are NOT the same, and all of them refuse at load rather than misbehaving quietly:
 
 - **`pull_request` actions are the forge's own words.** GitHub takes
-  `labeled | opened | synchronize | reopened | review_submitted`; GitLab takes
-  `open | update | reopen | approved`; Forgejo takes
-  `label_updated | opened | synchronized | reopened`; Azure takes `created | updated`. A word
+  `labeled | opened | synchronize | reopened | review_submitted | closed`; GitLab takes
+  `open | update | reopen | approved | close`; Forgejo takes
+  `label_updated | opened | synchronized | reopened | closed`; Azure takes `created | updated` and has
+  no close word (a close trigger on azure is refused at load — not yet covered, not declined). A word
   from the wrong forge is refused when the file is written. It would not break anything otherwise — it
   would simply never match an event, and the trigger would look configured while doing nothing.
+  The close word rides **alone**: a rule mixing it with other actions is refused, because a close is
+  gated on the actor who closed the item where every other action gates on the author or a label.
   `review_submitted` is GitHub's `pull_request_review` event: it fires on **every** submitted review, so
   add `reviewState` (`approved | changes_requested | commented`) to narrow which verdicts are worth paying
   for. That field is github-only and legal only beside `review_submitted`; anywhere else it refuses at
@@ -176,6 +185,32 @@ Three things are NOT the same, and all of them refuse at load rather than misbeh
   requests, so `any`/`all`/`none` could never match and a rule that loads clean and never fires reads as a
   broken harness.
 
+## Close triggers and one-shots — `on.once`, and the re-arm
+
+Two shapes fire on a close: the `issue` trigger type (an issue closing, `on.action` in the forge's close
+word), and a `pull_request` rule whose only action is the close word (on GitHub and Forgejo a merged PR
+counts as closed; on GitLab only an explicit close fires it). Both
+may carry `on.number` to pin one specific item, and `once: true` (which requires `number`) makes the rule
+a **one-shot**: after one run the worker marks the entry spent by adding
+`on.disarmed: { at, jobId }` to it in `triggers.json`. The entry is never deleted — run history
+attributes by array position — so `dispatch_triggers` and the panel keep showing it, marked spent,
+matching nothing.
+
+Four things to say when an operator asks:
+
+- **A failed run still spends it.** "Fired" means "produced a run record", so a one-shot whose job failed
+  is spent too. The fix is the re-arm below, after they have read why it failed.
+- **Re-arming is deleting `on.disarmed` from the entry** in `triggers.json`, nothing else. It is an
+  operator file edit: no tool and no panel key writes or removes that mark, so say so plainly rather than
+  reaching for `dispatch_trigger_edit` (which changes the flow only).
+- **Authoring one**: `dispatch_trigger_add` takes `kind: issue` (plus `number` and `once`), behind the
+  same confirm dialog as every trigger write, and a close-only `pull_request` rule accepts the same two
+  fields. The shared validator refuses anything malformed, and `once` requires `number`.
+- **Both services must read the same file.** The disarm is a worker write, so a receiver pointed at a
+  different `triggers.json` stays armed; `PI_TRIGGERS_FILE` set to one absolute path is the fix, and
+  `pi-dispatch doctor` warns about it. In the compose topology the receiver's read-only mount lags a
+  disarm until restart, and the worker's own pre-spend check is what prevents a second run meanwhile.
+
 ## Racing two agents on one event — `run.replicas`
 
 `"replicas": 2` on a `label`, `comment` or `pull_request` trigger turns one delivery into **two independent
@@ -190,9 +225,10 @@ Three things to say when an operator asks about it:
 - **You cannot set it from here.** There is no `replicas` parameter on `dispatch_trigger_add` or
   `_edit`, and no panel key. It is a reviewed edit to `triggers.json`, deliberately: a spend multiplier is
   plainly a capability a model should not gain. Say so rather than looking for a way around it.
-- **It refuses on cron, and beside `resume`.** A local job's `/workspace` IS the operator's folder, so two
-  replicas would edit one working tree with no gate and no undo. And a resumed run continues one lineage
-  where replicas exist to fork it.
+- **It refuses on cron, beside `resume`, and beside `once: true`.** A local job's `/workspace` IS the
+  operator's folder, so two replicas would edit one working tree with no gate and no undo. A resumed run
+  continues one lineage where replicas exist to fork it. And a one-shot promises exactly one run, which N
+  racing sandboxes contradict.
 
 `dispatch_trigger_add` takes an optional `forge` parameter, defaulting to `github`. Unlike `image`, this
 one IS offered to the model — a model that can already add a GitHub trigger can already arm a paid run,
@@ -205,3 +241,28 @@ If you are asked why a GitLab trigger did not fire, the usual answers in order:
 2. **No label was added by that event.** GitLab has no `labeled` action; the trigger fires on the labels
    an event *added*, so editing an already-labelled issue does nothing. This is deliberate.
 3. **The action word belongs to the other forge.** See above.
+
+## Scoped limits — and the folder mutex you cannot turn off
+
+`scoped-limits.json` holds per-scope bounds beside the deployment-global ones: `day`/`week`/`month` cap
+how many jobs a repo or folder may run per window (refused pre-spend, reason `scope-cap`, never retried,
+the scope's own counter still counts the refusal), and `concurrent` caps how many run at once (the excess
+is deferred to the delayed set and runs when a slot frees — never dropped, no budget spent while waiting).
+Edits apply live: the worker hot-reloads the file and keeps the last good version on a bad edit.
+
+Separate from all of that, **local jobs carry a built-in one-job-per-folder mutex: at most one job per
+folder at a time, always on, with NO configuration, NO tool, and NO panel key.** If an operator asks to
+disable it, say plainly that there is no switch, deliberately: two agents editing one working tree race
+each other with no gate and no undo, and an off switch's only use is re-opening that race. A `concurrent`
+value on a folder scope can never raise the mutex's one-at-a-time (the lower bound always wins).
+
+Three more things to say when asked:
+
+- **A `scope-cap` refusal is final for that window.** The counter is not resettable from any tool; the
+  window rolls over on its own (day/week/month, UTC). Raising the cap via `dispatch_limit_edit` takes
+  effect at the next job.
+- **Deferrals are visible only as the queue's delayed count** (the panel's status line shows it when it
+  is nonzero). That count also includes cron next-occurrences and retry backoff — a nonzero number is
+  normal on any deployment with schedules.
+- **Per-scope in-flight is not displayed anywhere.** The panel and `dispatch_limits` show `concurrent` as
+  configuration only; the live count lives inside the worker process and no reader can see it.