@edgehero/pi-dispatch-admin 1.4.0 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-admin",
-  "version": "1.4.0",
+  "version": "1.6.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,18 @@ 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_waits` — list the jobs the worker is HOLDING on a trigger's `run.waitFor` condition: job id,
+  an id-only target, the operator's own words for what it waits on, and how long it has waited. Different
+  from the queue's `delayed` count, which also mixes cron next-occurrences, retry backoff and quiet hours.
+- `dispatch_wait_cancel` — remove a held job so it never runs (confirm-gated). It is the only lever that
+  reaches one: a held job has spent nothing, so no budget cap will ever refuse it, and deleting the trigger
+  does not reach a job already enqueued.
+- `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:
 
@@ -235,3 +247,50 @@ 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.
+
+## Held jobs — what `waitFor` looks like from here
+
+A trigger may carry `run.waitFor`, and a job whose conditions have not cleared is **held**: deferred, with
+no budget slot reserved, no kill timer armed, no retry attempt consumed, and no run record written. It runs
+exactly once when every condition clears.
+
+What that means when you are asked about a job that "has not run":
+
+- **Look at `dispatch_waits` before the queue counts.** A held job is not `waiting` and not `active`. It is
+  in the delayed set, which also holds every cron trigger's next occurrence, so the panel's `delayed` number
+  is not an answer to "what is stuck".
+- **A held job has cost nothing yet.** Do not reason about it against the spend caps: they count container
+  starts, and this job has started none. The bounds that apply to it are its own (`PI_WAIT_MAX_MS`,
+  `PI_WAIT_MAX_CHECKS`), and when one is reached the job terminates with a run record naming the reason.
+- **The terminal reasons say what to do.** `wait-refused` means the operator's check reported the condition
+  will never clear. `wait-unanswerable` means the check could not answer repeatedly, which usually means the
+  script is broken rather than the condition slow. `wait-expired` means a bound was reached.
+  `wait-skew` / `wait-unreadable` mean two services in the deployment disagree about the field and one needs
+  upgrading or restarting.
+- **Cancelling is an operator decision.** `dispatch_wait_cancel` needs a confirm, writes no run record (the
+  job never ran), and cannot be undone: the delivery is gone, and a webhook does not resend itself.
+
+## 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.