feat(pause): per-folder/repo scheduled pause windows (quiet hours), defer + auto-resume

Add scoped, time-bounded pauses: hold a folder's (local) or repo's (github) runs
"between certain times" and resume automatically after — recurring daily, with
optional weekday and date-range bounds and a per-window IANA timezone (default
UTC, DST-correct via built-in Intl, no new dependency).

Enforcement — defer, don't drop (DES-SCOPED-PAUSE-VIA-MOVE-TO-DELAYED)
- worker/src/pause-windows.mjs: pure, fs-injectable validator (parsePauseWindows),
  loader (loadPauseWindows), and the timezone-aware predicate (pauseUntilMs +
  windowEndAt). Fully unit-testable with injected `now`.
- The processor gate is FIRST in the wrapper, before the kill timer and the budget
  reservation: if the job's scope is in an active window, job.moveToDelayed(end,
  token) + throw DelayedError. The job keeps its dedup identity, survives restart,
  reserves NO budget slot, and auto-resumes when BullMQ re-picks it. Consistent
  with CONST-BUDGET-BEFORE-TOKENS (a deferral is not a job start).
- pause-windows.json (PI_PAUSE_WINDOWS_FILE) is boot-loaded fail-loud and
  live-reloaded via the same dir-watch machinery as triggers.json; a bad edit keeps
  the last-good windows.

Admin control (mirrors the confirm-gated triggers CRUD)
- read/writePauseWindows (shared validator, atomic, fail-closed); resolvePaths gains
  pauseWindowsPath. Tools: dispatch_pauses (read) + dispatch_pause_add/_delete
  (confirm-gated, fail-closed without an operator). Operator `w` key -> add/delete
  dialogs. A PAUSES panel section marks each window ● paused (with a resume
  countdown) or ○ open. The operate-pi-dispatch skill documents the gate.

Specs: REQ-SCOPED-PAUSE-WINDOWS, DES-SCOPED-PAUSE-VIA-MOVE-TO-DELAYED,
INT-PAUSE-WINDOWS-FILE-CONTRACT, a constitution changelog note (before-budget
placement), and a job-budget rule pause-gate-before-budget.

Tests: worker 432 pass (pause-windows predicate matrix incl. overnight/days/dates/
non-UTC tz; pause-gate defers-before-budget + identity preservation), admin 167
pass (gate tests + panel section), receiver unaffected.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01D3npQvQXLWsW6qsrRMAmNL

Author: edgehero

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

@@ -30,6 +30,9 @@ dialog before it takes effect**:
 - `dispatch_set` — change a limit/setting (e.g. `dailyCap`, `weeklyCap`, `maxTurns`, `model`). Omit `value`
   to unset.
 - `dispatch_trigger_add` / `dispatch_trigger_edit` / `dispatch_trigger_delete` — manage triggers.
+- `dispatch_pause_add` / `dispatch_pause_delete` — manage scheduled pause windows (per folder/repo "quiet
+  hours": runs for a scope are deferred between certain times and auto-resume after; `dispatch_pauses` lists
+  them). Deferring never drops a job and costs no budget.
 
 Use them like this:
 

admin/src/dashboard.ts

@@ -22,7 +22,8 @@ import { dayKey, weekKey, monthKey, tokenDayKey, windowState } from "@pi-dispatc
 import { parseConnection, makeRedisClient } from "@pi-dispatch/worker/connection";
 import { makeQueue } from "@pi-dispatch/worker/queue";
 import { STALL_KEY } from "@pi-dispatch/worker/scheduler-stall-guard";
-import { listRuns, readSettingsView, mapSchedulers, readTriggers } from "./read-model.mjs";
+import { windowEndAt } from "@pi-dispatch/worker/pause-windows";
+import { listRuns, readSettingsView, mapSchedulers, readTriggers, readPauseWindows } from "./read-model.mjs";
 import { renderStatus, renderBudget, renderTriggers, renderSettingsView } from "./render.mjs";
 import { matchesKey } from "./keys.mjs";
 import { box, meter, clip } from "./panel.mjs";
@@ -85,6 +86,7 @@ export function createDashboardDeps(paths: any) {
         runs: listRuns({ logsDir: paths.logsDir, limit: RUNS_ON_DASHBOARD }),
         settings: readSettingsView({ settingsFile: paths.settingsFile }),
         triggers: readTriggers({ triggersPath: paths.triggersPath }),
+        pauseWindows: readPauseWindows({ pauseWindowsPath: paths.pauseWindowsPath }),
         // ONLY the id off the active Job -- a Job's `.data` holds issue title/body/username (PII), so it
         // never enters the snapshot (no-pii-in-logs, INT-RUN-HISTORY-FILE-CONTRACT).
         activeJobId: activeList?.[0]?.id ?? null,
@@ -308,6 +310,10 @@ export function makeDashboard({
         void dispose().finally(() => done({ action: "editSettings" }));
         return;
       }
+      if (data === "w" || data === "W") {
+        void dispose().finally(() => done({ action: "managePauses" }));
+        return;
+      }
       if (matchesKey(data, "up")) {
         selected = Math.max(0, selected - 1);
         tui?.requestRender?.();
@@ -465,6 +471,11 @@ function buildListLines(snapshot: any, selected: number, inner: number, styler:
   for (const l of trg.lines) lines.push(l);
   lines.push(RULE);
 
+  const pw = pauseLines(snapshot.pauseWindows, inner, styler);
+  lines.push(styler.divider("pause windows", `${pw.count} · w manage`, inner));
+  for (const l of pw.lines) lines.push(l);
+  lines.push(RULE);
+
   // Active + run rows follow the triggers in buildRows, so offset the selection index by the trigger count.
   const runRows = buildRows(snapshot).slice(trg.count);
   const runCount = Array.isArray(snapshot.runs) ? snapshot.runs.length : 0;
@@ -612,6 +623,31 @@ function targetColored(t: any, styler: any): string {
   return `${arrow} ${styler.fg("accent", "github")} ${flow}`;
 }
 
+/** The scheduled pause windows as colored rows, each marked `●` (paused now, with a resume countdown) or `○`. */
+function pauseLines(pauseWindows: any, inner: number, styler: any): { count: number; lines: string[] } {
+  const lines: string[] = [];
+  if (pauseWindows && pauseWindows.missing) { lines.push(styler.cell("(no pause windows · w to manage)", inner, { color: "dim" })); return { count: 0, lines }; }
+  if (pauseWindows && pauseWindows.invalid) { lines.push(styler.cell(`(pause-windows file invalid: ${pauseWindows.invalid})`, inner, { color: "error" })); return { count: 0, lines }; }
+  const list = (pauseWindows && pauseWindows.windows) ?? [];
+  if (list.length === 0) { lines.push(styler.cell("(no pause windows · w to manage)", inner, { color: "dim" })); return { count: 0, lines }; }
+  const now = Date.now();
+  for (const w of list) lines.push(pauseRow(w, now, inner, styler));
+  return { count: list.length, lines };
+}
+
+function pauseRow(w: any, now: number, inner: number, styler: any): string {
+  const until = windowEndAt(w, now); // ms when this window resumes, or null when not active now
+  const dot = until ? styler.fg("warning", "●") : styler.fg("dim", "○");
+  const bits = [
+    `${dot} ${styler.fg("accent", w.scope ?? "-")}`,
+    styler.fg("text", `${w.from ?? "-"}–${w.to ?? "-"}`) + " " + styler.fg("dim", w.tz ?? "UTC"),
+  ];
+  if (w.days) bits.push(styler.fg("muted", `[${w.days.join(",")}]`));
+  if (w.dateFrom || w.dateTo) bits.push(styler.fg("dim", `${w.dateFrom ?? "…"}→${w.dateTo ?? "…"}`));
+  if (until) bits.push(styler.fg("warning", `resumes in ${humanizeMs(until - now) || "<1m"}`));
+  return fitLine(bits.join(styler.fg("dim", "  ")), inner, styler);
+}
+
 /** The interactive RUNS list, colored: cursor, id, target, flow, outcome (✔/⚠/✘), turns, tokens. */
 function runLines(rows: any[], selected: number, inner: number, styler: any): string[] {
   if (!Array.isArray(rows) || rows.length === 0) return [styler.cell("(no runs)", inner, { color: "dim" })];
@@ -760,7 +796,7 @@ function triggerDetailHints(inner: number, styler: any): string {
 /** The colored key-hint footer. */
 function keyHints(inner: number, styler: any): string {
   const k = (key: string, label: string) => styler.fg("accent", key) + " " + styler.fg("dim", label);
-  const hints = [k("↑↓", "select"), k("↵", "open"), k("a", "add"), k("l", "logs"), k("p", "pause"), k("r", "resume"), k("q", "quit")].join(styler.fg("dim", " · "));
+  const hints = [k("↑↓", "select"), k("↵", "open"), k("a", "add"), k("w", "pauses"), k("l", "logs"), k("p", "pause"), k("r", "resume"), k("q", "quit")].join(styler.fg("dim", " · "));
   return fitLine(hints, inner, styler);
 }
 

admin/src/index.ts

@@ -47,10 +47,12 @@ import {
   readLogTail,
   readSettingsView,
   readTriggers,
+  readPauseWindows,
   listRunIds,
   setQueuePaused,
   writeSettings,
   writeTriggers,
+  writePauseWindows,
   enqueueDispatchRun,
   KNOWN_KEYS,
 } from "./read-model.mjs";
@@ -366,6 +368,83 @@ function registerTools(pi: ExtensionAPI): void {
     },
   });
 
+  pi.registerTool({
+    name: "dispatch_pauses",
+    label: "pi-dispatch pause windows",
+    description:
+      "Read-only. Lists the scheduled pause windows (per folder/repo quiet hours) with their array index. " +
+      "Use the index for dispatch_pause_delete.",
+    parameters: Type.Object({}),
+    async execute() {
+      const paths = resolvePaths(process.env);
+      const p = readPauseWindows({ pauseWindowsPath: paths.pauseWindowsPath });
+      const data = Array.isArray(p?.windows) ? p.windows.map((w: any, index: number) => ({ index, ...w })) : p;
+      return toolText(JSON.stringify(data));
+    },
+  });
+
+  pi.registerTool({
+    name: "dispatch_pause_add",
+    label: "pi-dispatch add pause window",
+    description:
+      "Adds a scheduled pause window and applies it live: runs for `scope` (a repo \"owner/name\", a local " +
+      "folder path, or \"*\" for all) are DEFERRED between `from` and `to` (\"HH:MM\" 24h; from>to = overnight) " +
+      "and resume automatically after — nothing is dropped, and deferring costs no budget. Optional `tz` (IANA, " +
+      "default UTC), `days` (mon..sun), `dateFrom`/`dateTo` (\"YYYY-MM-DD\"). The operator MUST approve a confirm " +
+      "dialog showing the window; refused with no interactive operator.",
+    executionMode: "sequential",
+    parameters: Type.Object({
+      scope: Type.String(),
+      from: Type.String(),
+      to: Type.String(),
+      tz: Type.Optional(Type.String()),
+      days: Type.Optional(Type.Array(Type.String())),
+      dateFrom: Type.Optional(Type.String()),
+      dateTo: Type.Optional(Type.String()),
+    }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const paths = resolvePaths(process.env);
+      const w = buildPauseWindow(params);
+      const result = await confirmedWrite(
+        ctx,
+        { title: "Add pause window", message: `Add to pause-windows.json:\n${JSON.stringify(w)}` },
+        () => {
+          const res = writePauseWindows({ pauseWindowsPath: paths.pauseWindowsPath, mutate: (list: any[]) => [...list, w] });
+          if (res.invalid) throw new Error(`rejected: ${res.invalid}`);
+          return { applied: true, added: w };
+        },
+      );
+      return toolText(JSON.stringify(result));
+    },
+  });
+
+  pi.registerTool({
+    name: "dispatch_pause_delete",
+    label: "pi-dispatch delete pause window",
+    description:
+      "Removes a scheduled pause window (by array index from dispatch_pauses) and applies it live. The operator " +
+      "MUST approve a confirm dialog showing the window; refused with no interactive operator.",
+    executionMode: "sequential",
+    parameters: Type.Object({ index: Type.Integer({ minimum: 0 }) }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const paths = resolvePaths(process.env);
+      const p = readPauseWindows({ pauseWindowsPath: paths.pauseWindowsPath });
+      const list = Array.isArray(p?.windows) ? p.windows : [];
+      const cur = list[params.index];
+      if (!cur) throw new Error(`no pause window at index ${params.index} (have ${list.length})`);
+      const result = await confirmedWrite(
+        ctx,
+        { title: `Delete pause window #${params.index + 1}`, message: `Remove pause window #${params.index + 1}: ${cur.scope} ${cur.from}-${cur.to} ${cur.tz}` },
+        () => {
+          const res = writePauseWindows({ pauseWindowsPath: paths.pauseWindowsPath, mutate: (l: any[]) => l.filter((_, i) => i !== params.index) });
+          if (res.invalid) throw new Error(`rejected: ${res.invalid}`);
+          return { applied: true, deletedIndex: params.index };
+        },
+      );
+      return toolText(JSON.stringify(result));
+    },
+  });
+
   pi.registerTool({
     name: "dispatch_trigger_delete",
     label: "pi-dispatch delete trigger",
@@ -455,6 +534,26 @@ function buildTriggerEntry(kind: string, f: any): any {
   return null;
 }
 
+/**
+ * Build one pause-window entry from a kind-less field bag (shared by the `dispatch_pause_add` tool and the
+ * operator dialog). Required scope/from/to; optional tz/days/dateFrom/dateTo included only when non-blank so
+ * an omitted field drops out of the JSON. `days` accepts an array (tool) or a space-separated string (dialog).
+ * All value validation (time format, IANA tz, weekday names, date format) lives in the shared
+ * `parsePauseWindows`, which the write goes through — a bad value is rejected there, never written.
+ */
+function buildPauseWindow(f: any): any {
+  const w: any = { scope: String(f.scope ?? "").trim(), from: String(f.from ?? "").trim(), to: String(f.to ?? "").trim() };
+  const tz = optStr(f.tz);
+  const days = asWords(f.days);
+  const dateFrom = optStr(f.dateFrom);
+  const dateTo = optStr(f.dateTo);
+  if (tz) w.tz = tz;
+  if (days.length > 0) w.days = days;
+  if (dateFrom) w.dateFrom = dateFrom;
+  if (dateTo) w.dateTo = dateTo;
+  return w;
+}
+
 /** Normalise a labels/action field to a trimmed non-empty string list, accepting an array or a string. */
 function asWords(x: any): string[] {
   if (Array.isArray(x)) return x.map((s) => String(s).trim()).filter(Boolean);
@@ -638,9 +737,56 @@ export async function handleDashboardAction(result: any, paths: any, ctx: any):
       return deleteTriggerEntry(paths, ui, notify, result.index);
     case "editSettings":
       return editSettingsViaDialogs(paths, ui, notify);
+    case "managePauses":
+      return managePausesViaDialogs(paths, ui, notify);
   }
 }
 
+/** Pause-window management: pick add or delete, then run the matching dialog. Keeps one overlay key (`w`). */
+async function managePausesViaDialogs(paths: any, ui: any, notify: Notify): Promise<void> {
+  const action = await ui.select("Pause windows", ["Add a pause window", "Delete a pause window"]);
+  if (!action) return;
+  if (action.startsWith("Add")) return addPauseWindowViaDialogs(paths, ui, notify);
+  return deletePauseWindowViaDialogs(paths, ui, notify);
+}
+
+/** Add a pause window: scope + from/to, then the optional tz/days/date bounds (blank = omit). Validated + live. */
+async function addPauseWindowViaDialogs(paths: any, ui: any, notify: Notify): Promise<void> {
+  const scope = await ui.input("scope — a repo \"owner/name\", a local folder path, or \"*\" for all", "");
+  if (scope === undefined || scope.trim() === "") return;
+  const from = await ui.input("from — pause start \"HH:MM\" 24h (from > to = overnight)", "22:00");
+  if (from === undefined) return;
+  const to = await ui.input("to — resume time \"HH:MM\" 24h", "06:00");
+  if (to === undefined) return;
+  const tz = await ui.input("tz — IANA timezone (blank = UTC), e.g. Europe/Amsterdam", "");
+  if (tz === undefined) return;
+  const days = await ui.input("days — space-separated weekdays to restrict to (blank = every day), e.g. mon tue", "");
+  if (days === undefined) return;
+  const dateFrom = await ui.input("dateFrom — only on/after \"YYYY-MM-DD\" (blank = no bound)", "");
+  if (dateFrom === undefined) return;
+  const dateTo = await ui.input("dateTo — only on/before \"YYYY-MM-DD\" (blank = no bound)", "");
+  if (dateTo === undefined) return;
+  const w = buildPauseWindow({ scope, from, to, tz, days, dateFrom, dateTo });
+  const res = writePauseWindows({ pauseWindowsPath: paths.pauseWindowsPath, mutate: (list: any[]) => [...list, w] });
+  notify?.(res.ok ? `pause window added (live) — ${w.scope} ${w.from}-${w.to}` : `add rejected: ${res.invalid}`, res.ok ? "info" : "error");
+}
+
+/** Delete a pause window: select which (by a scope/time label), confirm, remove. */
+async function deletePauseWindowViaDialogs(paths: any, ui: any, notify: Notify): Promise<void> {
+  const p = readPauseWindows({ pauseWindowsPath: paths.pauseWindowsPath });
+  const list: any[] = Array.isArray(p?.windows) ? p.windows : [];
+  if (list.length === 0) { notify?.("no pause windows to delete", "info"); return; }
+  const labels = list.map((w, i) => `#${i + 1}  ${w.scope}  ${w.from}-${w.to} ${w.tz}${w.days ? ` [${w.days.join(",")}]` : ""}`);
+  const picked = await ui.select("Delete which pause window", labels);
+  if (!picked) return;
+  const index = labels.indexOf(picked);
+  if (index < 0) return;
+  const ok = await ui.confirm("Delete pause window", `Remove ${labels[index]}?`);
+  if (!ok) return;
+  const res = writePauseWindows({ pauseWindowsPath: paths.pauseWindowsPath, mutate: (l: any[]) => l.filter((_, i) => i !== index) });
+  notify?.(res.ok ? `pause window #${index + 1} deleted (live)` : `delete rejected: ${res.invalid}`, res.ok ? "info" : "error");
+}
+
 /** Add a trigger: kind-first (the on x run diagonal is locked by construction), then the per-kind fields. */
 async function addTriggerViaDialogs(paths: any, ui: any, notify: Notify): Promise<void> {
   const kind = await ui.select("Add trigger — kind", ["cron", "label", "comment", "pull_request"]);

admin/src/read-model.mjs

@@ -23,6 +23,7 @@ import { settingsFilePath, readOverlay, writeOverlay, KNOWN_KEYS } from "@pi-dis
 import { sanitizeJobId } from "@pi-dispatch/worker/run-history";
 import { dayKey, weekKey, monthKey } from "@pi-dispatch/worker/budget";
 import { parseTriggers } from "@pi-dispatch/worker/triggers";
+import { parsePauseWindows } from "@pi-dispatch/worker/pause-windows";
 import { parseConnection, makeRedisClient } from "@pi-dispatch/worker/connection";
 import { makeQueue, enqueueLocalJob } from "@pi-dispatch/worker/queue";
 import { readFlowGate } from "@pi-dispatch/worker/flow-gate";
@@ -44,6 +45,7 @@ export function resolvePaths(env = process.env) {
     logsDir: env.PI_LOGS_DIR || defaultLogsDir(),
     settingsFile: settingsFilePath(env),
     triggersPath: env.PI_TRIGGERS_FILE ?? "deploy/triggers.json",
+    pauseWindowsPath: env.PI_PAUSE_WINDOWS_FILE ?? "deploy/pause-windows.json",
     captureJobLogs: env.PI_CAPTURE_JOB_LOGS === "1",
     // The two dispatch_run bounds the extension enforces producer-side, read DIRECTLY from env (never
     // loadConfig, which throws on unrelated GitHub-auth problems). `delimitedList`/`nonNegativeInt` are
@@ -307,6 +309,54 @@ export function writeTriggers({ triggersPath, mutate, fs = nodeFs }) {
   return { ok: true };
 }
 
+/**
+ * Read + validate the pause-windows file for display (REQ-SCOPED-PAUSE-WINDOWS). Returns `{ windows }` of
+ * normalized entries (with `fromMin`/`toMin`), or `{ missing }` / `{ invalid }` so the viewer degrades rather
+ * than throwing. Uses the SHARED `parsePauseWindows`, so the admin and the worker cannot drift on the schema.
+ */
+export function readPauseWindows({ pauseWindowsPath, fs = nodeFs }) {
+  let text;
+  try {
+    text = fs.readFileSync(pauseWindowsPath, "utf8");
+  } catch {
+    return { missing: true };
+  }
+  try {
+    return { windows: parsePauseWindows(text, pauseWindowsPath) };
+  } catch (e) {
+    return { invalid: e?.message ?? String(e) };
+  }
+}
+
+/**
+ * Read-modify-write the pause-windows file (mirrors `writeTriggers`): `mutate(windows)` receives a copy of the
+ * current raw `windows` array and returns the new array; the result is re-serialized, VALIDATED through the
+ * SHARED `parsePauseWindows` (fail-closed — a rejected result is NEVER written, so the worker loader can always
+ * parse it), and written ATOMICALLY (tmp + rename) so the live-reload watcher never sees a half-written file.
+ * Reached from operator-typed `/dispatch pause …` handlers AND the confirm-gated `dispatch_pause_*` tools; the
+ * tools route through `confirmedWrite` (an operator approves before this runs). Returns `{ ok }` or `{ invalid }`.
+ */
+export function writePauseWindows({ pauseWindowsPath, mutate, fs = nodeFs }) {
+  let current = [];
+  try {
+    const raw = JSON.parse(fs.readFileSync(pauseWindowsPath, "utf8"));
+    if (Array.isArray(raw?.windows)) current = raw.windows;
+  } catch {
+    // Missing/invalid file: start from empty; the validated atomic write below repairs it.
+  }
+  const next = mutate(current.map((w) => ({ ...w })));
+  const text = `${JSON.stringify({ windows: next }, null, 2)}\n`;
+  try {
+    parsePauseWindows(text, pauseWindowsPath); // the loader's own validator -- never write a file it would reject
+  } catch (e) {
+    return { invalid: e?.message ?? String(e) };
+  }
+  const tmp = `${pauseWindowsPath}.tmp`;
+  fs.writeFileSync(tmp, text, { mode: 0o644 });
+  fs.renameSync(tmp, pauseWindowsPath);
+  return { ok: true };
+}
+
 async function readWorkerCount(queue) {
   try {
     const list = await queue.getWorkers();