@edgehero/pi-dispatch-admin 1.5.0 → 1.6.1

package/README.md

@@ -69,6 +69,7 @@ One command puts a live TUI over the whole deployment:
 - **Triggers, editable live.** cron, label, comment, pull_request and issue triggers with colored drill-ins showing what fires each one, what it runs, and its trust model. Added, edited and deleted without a restart. A one-shot (`once: true`) shows armed or spent in its drill-in: a spent entry stays in the list, matches nothing, and re-arms when the operator deletes its `on.disarmed` mark from the file. Triggers that run third-party code or a custom image are badged; opting in or out of either stays an edit to the reviewed `triggers.json`, which neither the console nor a model-callable tool will make for you.
 - **Quiet hours.** Scheduled pause windows per folder or repo: defer runs between certain times, timezone-aware, and resume automatically. Deferred, never dropped, at zero budget cost.
 - **Scoped limits.** Per-repo or per-folder job caps (day, week, month) refused before any spend, plus a per-scope concurrency ceiling enforced by deferral. Local jobs also hold a one-job-per-folder guard that is always on and has no switch (it lives in the worker process, and one worker per docker daemon is the supported shape), because two agents editing one working tree race each other with no gate and no undo.
+- **Held jobs, with what they are waiting for.** A trigger carrying `run.waitFor` holds its job in the queue, unstarted and unbilled, until an instant passes or a check script the operator wrote exits 0. The panel grows a **held** section while anything waits (the target, the condition, and how long it has waited) and hides it again when nothing does, so a wait stops being an anonymous entry in the delayed count. `dispatch_waits` lists them and `dispatch_wait_cancel` stops one behind the operator confirm, which is the only way to cancel a held job short of editing redis by hand ([`docs/wait-for.md`](https://github.com/edgehero/pi-dispatch/blob/main/docs/wait-for.md)).
 - **AI-operable, with a human gate.** Model-callable tools let an agent change limits (global and scoped) and manage triggers and pause windows, and every **config** write pops an operator confirmation the model cannot answer, refusing outright when no operator is present. Two tools sit outside that gate on purpose: `dispatch_pause` and `dispatch_resume` write durable queue state but are reversible and spend nothing, so they carry no confirm. One more sits outside it and is **not** money-safe: `dispatch_run` enqueues a **paid** run that edits a local folder in place with no undo, bounded instead by six independent limits (the `PI_DISPATCH_RUN_ROOTS` folder allowlist, a committed per-flow `ai-trigger: allow` opt-in read at a pre-agent SHA, a dirty-tree refusal with no force option, no spend knobs on the tool, a per-hour rate limit, and the worker's daily cap). Commands sit outside its reach entirely: `dispatch_run` speaks flows only, and a chained job's request naming a `command` is refused outright, with no opt-in. Read [`SECURITY.md`](https://github.com/edgehero/pi-dispatch/blob/main/SECURITY.md) on that one before you enable it. The bundled `operate-pi-dispatch` skill teaches the agent those gates.
 - **Logs stay put.** Raw container output renders only in the overlay viewer, never into model context.
 

package/dist/index.mjs

@@ -7687,6 +7687,33 @@ var init_secret_profiles = __esm({
   }
 });
 
+// ../worker/src/wait-for.mjs
+function parseAfterInstant(text) {
+  if (typeof text !== "string" || !AFTER_INSTANT.test(text)) return { error: "shape" };
+  const ms = Date.parse(text);
+  if (!Number.isFinite(ms)) return { error: "calendar" };
+  const [year, month, day] = text.slice(0, 10).split("-").map(Number);
+  const probe = new Date(Date.UTC(year, month - 1, day));
+  if (year < 100) probe.setUTCFullYear(year);
+  if (probe.getUTCFullYear() !== year || probe.getUTCMonth() !== month - 1 || probe.getUTCDate() !== day) {
+    return { error: "calendar" };
+  }
+  return { ms };
+}
+function afterInstantMs(text) {
+  const parsed = parseAfterInstant(text);
+  return parsed.error ? null : parsed.ms;
+}
+var WAIT_CONDITION_KEYS, WAIT_CONDITION_MAX, WAIT_AFTER_MAX_DEFAULT_MS, AFTER_INSTANT;
+var init_wait_for = __esm({
+  "../worker/src/wait-for.mjs"() {
+    WAIT_CONDITION_KEYS = ["after", "profile"];
+    WAIT_CONDITION_MAX = 4;
+    WAIT_AFTER_MAX_DEFAULT_MS = 30 * 24 * 3600 * 1e3;
+    AFTER_INSTANT = /^\d{4}-\d{2}-\d{2}[Tt]([01]\d|2[0-3]):[0-5]\d(:[0-5]\d(\.\d+)?)?([Zz]|[+-]\d{2}:\d{2})$/;
+  }
+});
+
 // ../worker/src/config.mjs
 function configError(message) {
   const error = new Error(message);
@@ -7714,6 +7741,7 @@ var init_config2 = __esm({
     init_egress();
     init_forges();
     init_secret_profiles();
+    init_wait_for();
     CHAIN_DEPTH_MAX_DEFAULT = 1;
     CHAIN_MAX_PER_JOB_DEFAULT = 2;
     WORKER_ONLY_SECRET_VARS = /* @__PURE__ */ new Set(["GITHUB_APP_PRIVATE_KEY"]);
@@ -8114,6 +8142,18 @@ var init_scoped_limits = __esm({
   }
 });
 
+// ../worker/src/wait-state.mjs
+var LEASE_SLACK_MS, LEASE_MIN_MS, HELD_SET, jobKey, SATISFIED_MS;
+var init_wait_state = __esm({
+  "../worker/src/wait-state.mjs"() {
+    LEASE_SLACK_MS = 60 * 60 * 1e3;
+    LEASE_MIN_MS = 5 * 60 * 1e3;
+    HELD_SET = "wait:held";
+    jobKey = (jobId) => `wait:job:${jobId}`;
+    SATISFIED_MS = 15 * 60 * 1e3;
+  }
+});
+
 // ../worker/src/subscriptions.mjs
 function isNonEmptyString4(value) {
   return typeof value === "string" && value.trim() !== "";
@@ -8466,6 +8506,7 @@ function normalizeCron(on, run, index, path, state) {
   validateDisarmed(on, `cron trigger "${id}"`, path, { onType: "cron" });
   const secrets = validateSecrets(run, `cron trigger "${id}"`, path);
   const secretsProfile = validateSecretsProfile(run, `cron trigger "${id}"`, path);
+  validateWaitFor(on, run, `cron trigger "${id}"`, path, { onType: "cron" });
   return {
     on: { type: "cron", id, pattern },
     run: { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages, image, resume, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...secrets !== void 0 && { secrets }, ...secretsProfile !== void 0 && { secretsProfile } }
@@ -8715,6 +8756,81 @@ function validateSecretsProfile(run, at, path) {
   }
   return profile;
 }
+function validateWaitFor(on, run, at, path, { onType }) {
+  for (const [label, source, exactIsLegal] of [
+    ["run", run, true],
+    ["on", on, false]
+  ]) {
+    for (const key of Object.keys(source ?? {})) {
+      if (exactIsLegal && key === "waitFor") continue;
+      if (key.replace(/[^a-z0-9]/gi, "").toLowerCase() !== "waitfor") continue;
+      throw configError(`${at}: ${label}.${key} is not a field -- did you mean run.waitFor? A wait condition the loader drops holds nothing while the file reads as though it does, so a near miss is refused rather than dropped: ${path}`);
+    }
+  }
+  const waitFor = run.waitFor;
+  if (waitFor === void 0) return void 0;
+  if (onType === "cron") {
+    throw configError(`${at}: run.waitFor is not yet covered on a cron trigger -- the scheduler advances at pickup, so a held occurrence outlives the teardown that would delete it and still pays, and its surviving job hash can fail worker boot with a scheduler id collision; bounding that needs delayed-set-aware teardown, which is a gap to close, not a limit: ${path}`);
+  }
+  if (on?.once === true) {
+    throw configError(`${at}: run.waitFor and on.once cannot be combined -- the one-shot disarms on every run record, so a wait that never cleared would spend the one-shot with no container ever started and no way to re-arm it but editing this file: ${path}`);
+  }
+  if (run.replicas !== void 0) {
+    throw configError(`${at}: run.waitFor and run.replicas cannot be combined -- replicas fan out at enqueue, so each one would hold and poll the same external condition independently, multiplying the checks by ${run.replicas} for one answer: ${path}`);
+  }
+  if (!Array.isArray(waitFor) || waitFor.length === 0) {
+    throw configError(`${at}: run.waitFor must be a non-empty array of conditions when present (got ${JSON.stringify(waitFor)}): ${path}`);
+  }
+  if (waitFor.length > WAIT_CONDITION_MAX) {
+    throw configError(`${at}: run.waitFor names ${waitFor.length} conditions, over the ${WAIT_CONDITION_MAX} cap -- each profile condition is a subprocess run before the container, holding a concurrency slot while it runs: ${path}`);
+  }
+  const expected = WAIT_CONDITION_KEYS.join("|");
+  const normalized = [];
+  const profiles = /* @__PURE__ */ new Set();
+  let seenAfter = false;
+  for (let i = 0; i < waitFor.length; i += 1) {
+    const condition = waitFor[i];
+    const where = `${at}: run.waitFor[${i}]`;
+    if (condition === null || typeof condition !== "object" || Array.isArray(condition)) {
+      throw configError(`${where} must be an object naming exactly one condition (got ${JSON.stringify(condition)}): ${path}`);
+    }
+    const keys = Object.keys(condition);
+    if (keys.length !== 1) {
+      throw configError(`${where} must name exactly one condition (expected ${expected}), got ${keys.length === 0 ? "an empty object" : JSON.stringify(keys)}: ${path}`);
+    }
+    const key = keys[0];
+    if (key === "exclusive") {
+      throw configError(`${where}: exclusive is no longer a condition you write -- the worker already holds at most one local job per folder, always on, with no configuration and no off switch, and scoped-limits.json bounds any scope further: ${path}`);
+    }
+    if (!WAIT_CONDITION_KEYS.includes(key)) {
+      throw configError(`${where} has an unsupported condition ${JSON.stringify(key)} (expected ${expected}) -- an unknown condition here is a term of the gate that would silently do nothing, so it is refused rather than dropped: ${path}`);
+    }
+    if (key === "after") {
+      if (seenAfter) {
+        throw configError(`${where}: run.waitFor names a second "after" -- the conditions are a conjunction, so two instants mean the later one and the file would read as though both mattered: ${path}`);
+      }
+      if (afterInstantMs(condition.after) === null) {
+        throw configError(`${where}: after must be an ISO-8601 instant carrying its own zone, like "2026-09-01T09:00:00Z" or "2026-09-01T11:00:00+02:00" (got ${JSON.stringify(condition.after)}) -- without a zone the same file would hold for a different instant on a worker in a different timezone: ${path}`);
+      }
+      seenAfter = true;
+      normalized.push({ after: condition.after });
+      continue;
+    }
+    const profile = condition.profile;
+    if (!isNonEmptyString5(profile)) {
+      throw configError(`${where}: profile must be a non-empty string naming one of the wait profiles this deployment declares (got ${JSON.stringify(profile)}): ${path}`);
+    }
+    if (!ID_CHARSET.test(profile)) {
+      throw configError(`${where}: profile ${JSON.stringify(profile)} may use letters, digits, dot, dash and underscore only -- PI_WAIT_PROFILES is a comma-separated list of name:path pairs, so a name carrying either separator cannot be declared: ${path}`);
+    }
+    if (profiles.has(profile)) {
+      throw configError(`${where}: run.waitFor names the profile ${JSON.stringify(profile)} twice -- the conditions are a conjunction, so the second one can never change the answer while it doubles the subprocesses: ${path}`);
+    }
+    profiles.add(profile);
+    normalized.push({ profile });
+  }
+  return normalized;
+}
 function normalizeLabel(on, run, index, path) {
   const at = `trigger at index ${index}`;
   const predicate = validatePredicate(on, index, path, true);
@@ -8735,9 +8851,10 @@ function normalizeLabel(on, run, index, path) {
   const replicas = validateReplicas(run, at, path);
   const secrets = validateSecrets(run, at, path);
   const secretsProfile = validateSecretsProfile(run, at, path);
+  const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
   return {
     on: { type: "label", any: predicate.any, all: predicate.all, none: predicate.none },
-    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...repository !== void 0 && { repository }, ...secrets !== void 0 && { secrets }, ...secretsProfile !== void 0 && { secretsProfile } }
+    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...repository !== void 0 && { repository }, ...secrets !== void 0 && { secrets }, ...secretsProfile !== void 0 && { secretsProfile }, ...waitFor !== void 0 && { waitFor } }
   };
 }
 function normalizeComment(on, run, index, path, state) {
@@ -8766,9 +8883,10 @@ function normalizeComment(on, run, index, path, state) {
   const replicas = validateReplicas(run, at, path);
   const secrets = validateSecrets(run, at, path);
   const secretsProfile = validateSecretsProfile(run, at, path);
+  const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
   return {
     on: { type: "comment", phrase: on.phrase },
-    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...repository !== void 0 && { repository }, ...secrets !== void 0 && { secrets }, ...secretsProfile !== void 0 && { secretsProfile } }
+    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...repository !== void 0 && { repository }, ...secrets !== void 0 && { secrets }, ...secretsProfile !== void 0 && { secretsProfile }, ...waitFor !== void 0 && { waitFor } }
   };
 }
 function normalizeIssue(on, run, index, path) {
@@ -8807,6 +8925,7 @@ function normalizeIssue(on, run, index, path) {
   const replicas = validateReplicas(run, at, path);
   const secrets = validateSecrets(run, at, path);
   const secretsProfile = validateSecretsProfile(run, at, path);
+  const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
   return {
     on: {
       type: "issue",
@@ -8816,7 +8935,7 @@ function normalizeIssue(on, run, index, path) {
       ...number !== void 0 && { number },
       ...once !== void 0 && { once }
     },
-    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...secrets !== void 0 && { secrets }, ...secretsProfile !== void 0 && { secretsProfile } }
+    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...secrets !== void 0 && { secrets }, ...secretsProfile !== void 0 && { secretsProfile }, ...waitFor !== void 0 && { waitFor } }
   };
 }
 function normalizePullRequest(on, run, index, path) {
@@ -8864,6 +8983,7 @@ function normalizePullRequest(on, run, index, path) {
   const replicas = validateReplicas(run, at, path);
   const secrets = validateSecrets(run, at, path);
   const secretsProfile = validateSecretsProfile(run, at, path);
+  const waitFor = validateWaitFor(on, run, at, path, { onType: on.type });
   return {
     on: {
       type: "pull_request",
@@ -8878,7 +8998,7 @@ function normalizePullRequest(on, run, index, path) {
       ...number !== void 0 && { number },
       ...once !== void 0 && { once }
     },
-    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...secrets !== void 0 && { secrets }, ...secretsProfile !== void 0 && { secretsProfile } }
+    run: { kind: run.kind, flow: run.flow, packages, image, resume, replicas, ...command !== void 0 && { command }, ...skillsDir !== void 0 && { skillsDir }, ...instructions !== void 0 && { instructions }, ...secrets !== void 0 && { secrets }, ...secretsProfile !== void 0 && { secretsProfile }, ...waitFor !== void 0 && { waitFor } }
   };
 }
 function validateReviewState(on, actions, run, at, path) {
@@ -8907,6 +9027,7 @@ var init_triggers = __esm({
     init_flow_gate();
     init_forges();
     init_reserved_env();
+    init_wait_for();
     ON_TYPES = /* @__PURE__ */ new Set(["cron", "label", "comment", "pull_request", "issue"]);
     DISARMED_TYPE = "disarmed";
     PR_ACTIONS = {
@@ -10751,6 +10872,98 @@ async function readScopedBudget({ url, limits, redisFn = makeRedisClient, timeou
     }
   }
 }
+async function readHeldJobs({ url, limit = 20, redisFn = makeRedisClient, timeoutMs = 2500, now = () => Date.now() } = {}) {
+  let redis;
+  try {
+    parseConnection(url, { failFast: true });
+    redis = redisFn(url);
+    const settled = (async () => {
+      const ids = await redis.smembers(HELD_SET);
+      const hydrated = await Promise.all(
+        ids.slice(0, HELD_HYDRATE_MAX).map(async (jobId) => {
+          try {
+            const h = await redis.hgetall(jobKey(jobId));
+            if (!h || !h.since) {
+              await redis.srem(HELD_SET, jobId).catch(() => {
+              });
+              return null;
+            }
+            const since = Number(h.since);
+            return {
+              jobId,
+              target: h.target || null,
+              label: h.label || null,
+              waitedMs: Number.isFinite(since) && since > 0 ? Math.max(0, now() - since) : null,
+              checks: Number(h.checks) || 0
+            };
+          } catch {
+            return null;
+          }
+        })
+      );
+      const rows = hydrated.filter(Boolean);
+      rows.sort((a, b) => (b.waitedMs ?? -1) - (a.waitedMs ?? -1));
+      return {
+        rows: rows.slice(0, limit),
+        more: Math.max(0, rows.length - limit),
+        // True when the index itself was longer than this reader will hydrate: `more` is then a floor, and
+        // a caller that renders a total must say so rather than state a number it cannot know.
+        truncated: ids.length > HELD_HYDRATE_MAX
+      };
+    })();
+    return await withTimeout(settled, timeoutMs, { unreachable: "timed out reaching the queue" });
+  } catch (err) {
+    return { unreachable: err?.message ?? String(err) };
+  } finally {
+    if (redis) {
+      try {
+        redis.disconnect();
+      } catch {
+      }
+    }
+  }
+}
+async function cancelHeldJob({ url, jobId, redisFn = makeRedisClient, queueFn = makeQueue, timeoutMs = 2500 } = {}) {
+  if (typeof jobId !== "string" || jobId === "") return { invalid: "a job id is required" };
+  let redis;
+  let queue;
+  try {
+    parseConnection(url, { failFast: true });
+    redis = redisFn(url);
+    queue = queueFn(parseConnection(url, { failFast: true }));
+    const settled = (async () => {
+      const hash = await redis.hgetall(jobKey(jobId));
+      if (!hash || !hash.since) return { invalid: `job ${jobId} is not waiting on a condition` };
+      const job = await queue.getJob(jobId);
+      if (!job) return { invalid: `job ${jobId} is no longer in the queue` };
+      const state = await job.getState().catch(() => null);
+      if (state !== "delayed" && state !== "waiting" && state !== "prioritized") {
+        return { invalid: `job ${jobId} is ${state ?? "in an unknown state"}, not waiting -- it has already left the hold` };
+      }
+      await redis.del(jobKey(jobId));
+      await redis.srem(HELD_SET, jobId).catch(() => {
+      });
+      if (hash.dedupId) {
+        const holder = await redis.get(`wait:key:${hash.dedupId}`);
+        if (holder === jobId) await redis.del(`wait:key:${hash.dedupId}`);
+      }
+      await job.remove();
+      return { ok: true, jobId };
+    })();
+    return await withTimeout(settled, timeoutMs, { invalid: "timed out reaching the queue" });
+  } catch (err) {
+    return { invalid: err?.message ?? String(err) };
+  } finally {
+    try {
+      redis?.disconnect?.();
+    } catch {
+    }
+    try {
+      await queue?.close?.();
+    } catch {
+    }
+  }
+}
 function readSubscriptions({ subscriptionsPath, fs = nodeFs3 }) {
   if (subscriptionsPath === null || subscriptionsPath === void 0) return { missing: true };
   let text;
@@ -11382,7 +11595,7 @@ function clampLines(lines) {
   const n = Number.isFinite(lines) ? Math.floor(lines) : 200;
   return Math.min(2e3, Math.max(1, n));
 }
-var DISPATCH_RUN_TTL_SECONDS, SCAN_WINDOW_MAX_DAYS, GRAPH_LIMITS, GRAPH_LS_TREE_MAX_BYTES;
+var DISPATCH_RUN_TTL_SECONDS, HELD_HYDRATE_MAX, SCAN_WINDOW_MAX_DAYS, GRAPH_LIMITS, GRAPH_LS_TREE_MAX_BYTES;
 var init_read_model = __esm({
   "src/read-model.mjs"() {
     init_config2();
@@ -11391,6 +11604,7 @@ var init_read_model = __esm({
     init_budget();
     init_pause_windows();
     init_scoped_limits();
+    init_wait_state();
     init_subscriptions();
     init_connection();
     init_queue();
@@ -11403,6 +11617,7 @@ var init_read_model = __esm({
     init_costs();
     init_triggers_file();
     DISPATCH_RUN_TTL_SECONDS = 2 * 60 * 60;
+    HELD_HYDRATE_MAX = 200;
     SCAN_WINDOW_MAX_DAYS = 92;
     GRAPH_LIMITS = Object.freeze({
       maxFoldersScanned: 16,
@@ -39505,6 +39720,25 @@ function renderBudget({ budget, settings: settings2 } = {}) {
   if (pct !== null) lines.push(`  soft-hold band: ${pct}%`);
   return lines.join("\n");
 }
+function renderHeldJobs({ held } = {}) {
+  if (!held) return null;
+  if (held.unreachable) return `unreadable (${held.unreachable})`;
+  const rows = Array.isArray(held.rows) ? held.rows : [];
+  if (rows.length === 0) return null;
+  const more = Number(held.more) || 0;
+  const lines = rows.map((r) => `${r.target ?? r.jobId ?? "-"}  ${r.label ?? "-"}  waited ${plainDuration(r.waitedMs)}`);
+  if (more > 0) lines.push(`... and ${more} more`);
+  return lines.join("\n");
+}
+function plainDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "?";
+  const s = Math.floor(ms / 1e3);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  return h < 24 ? `${h}h${m % 60}m` : `${Math.floor(h / 24)}d${h % 24}h`;
+}
 function renderScopedLimits({ limits, scopedBudget } = {}) {
   if (limits?.invalid) return `Scoped limits: file invalid (${limits.invalid})`;
   const list = Array.isArray(limits?.limits) ? limits.limits : [];
@@ -39869,6 +40103,34 @@ function centerBlock(lines, overlayWidth, blockWidth) {
   const prefix = " ".repeat(pad2);
   return lines.map((l) => prefix + l);
 }
+async function heldJobs(redis) {
+  const ids = await redis.smembers("wait:held");
+  const at = Date.now();
+  const hydrated = await Promise.all(
+    ids.slice(0, HELD_HYDRATE_MAX2).map(async (jobId) => {
+      try {
+        const h = await redis.hgetall(`wait:job:${jobId}`);
+        if (!h || !h.since) {
+          await redis.srem("wait:held", jobId).catch(() => {
+          });
+          return null;
+        }
+        const since = Number(h.since);
+        return {
+          jobId,
+          target: h.target || null,
+          label: h.label || null,
+          waitedMs: Number.isFinite(since) && since > 0 ? Math.max(0, at - since) : null
+        };
+      } catch {
+        return null;
+      }
+    })
+  );
+  const rows = hydrated.filter(Boolean);
+  rows.sort((a, b) => (b.waitedMs ?? -1) - (a.waitedMs ?? -1));
+  return { rows: rows.slice(0, HELD_LIMIT), more: Math.max(0, rows.length - HELD_LIMIT), truncated: ids.length > HELD_HYDRATE_MAX2 };
+}
 function createDashboardDeps(paths) {
   const queue = makeQueue(parseConnection(paths.valkeyUrl, { failFast: true }));
   const redis = makeRedisClient(paths.valkeyUrl);
@@ -39906,7 +40168,9 @@ function createDashboardDeps(paths) {
           })
         )
       };
+      const held = await heldJobs(redis).catch((err) => ({ unreachable: err?.message ?? String(err) }));
       return {
+        held,
         scopedLimits,
         scopedBudget,
         queue: { pausedState, counts, workers },
@@ -40378,6 +40642,8 @@ function renderPanel(snapshot, width, state, styler) {
   ];
   const scopedText = renderScopedLimits({ limits: snapshot.scopedLimits, scopedBudget: snapshot.scopedBudget });
   if (scopedText) sections.splice(2, 0, { title: "SCOPED LIMITS", lines: toLines(scopedText) });
+  const heldText = renderHeldJobs({ held: snapshot.held });
+  if (heldText) sections.push({ title: "HELD", lines: toLines(heldText) });
   const plain = [title];
   for (const section of sections) plain.push(section.title, ...section.lines);
   plain.push(KEY_HINTS);
@@ -40417,6 +40683,7 @@ function buildListLines(snapshot, selected, inner, styler, runSort = "time", ava
     // collapse budget. The key hint lives in this divider, not the footer -- the footer's width
     // arithmetic has no headroom for another hint (its own comment), the s/o/Tab precedent.
     { key: "limits", head: ["scoped limits", `${sl.count} \xB7 m manage`], body: sl.lines, priority: 0, viewKey: "m" },
+    ...heldSection(snapshot.held, inner, styler),
     { key: "runs", head: ["runs", `last ${runCount} \xB7 o ${runSort}`], body: runLines(runRows, selected - trg.count, inner, styler) },
     { key: "settings", head: ["settings", "s edit"], body: settingsLines(snapshot.settings, inner, styler), priority: 2, viewKey: "s" }
   ];
@@ -40432,7 +40699,7 @@ function buildListLines(snapshot, selected, inner, styler, runSort = "time", ava
   sections.forEach((s, i) => {
     if (i > 0) lines.push(RULE);
     if (collapsed.has(s.key)) {
-      lines.push(styler.divider(s.head[0], `(${s.body.length} hidden \u2014 ${s.viewKey} to view)`, inner));
+      lines.push(styler.divider(s.head[0], s.viewKey ? `(${s.body.length} hidden \u2014 ${s.viewKey} to view)` : `(${s.body.length} hidden)`, inner));
       return;
     }
     if (s.head) lines.push(styler.divider(s.head[0], s.head[1], inner));
@@ -40440,6 +40707,37 @@ function buildListLines(snapshot, selected, inner, styler, runSort = "time", ava
   });
   return lines;
 }
+function heldSection(held, inner, styler) {
+  if (!held) return [];
+  if (held.unreachable) {
+    return [{ key: "held", priority: 5, head: ["held", "waiting on conditions"], body: [styler.cell(`unreadable (${held.unreachable})`, inner, { color: "error" })] }];
+  }
+  const rows = Array.isArray(held.rows) ? held.rows : [];
+  if (rows.length === 0) return [];
+  const shown = rows.slice(0, HELD_ON_DASHBOARD);
+  const hidden = rows.length - shown.length + (Number(held.more) || 0);
+  const body = shown.map((r) => heldRow(r, inner, styler));
+  if (hidden > 0) body.push(styler.cell(styler.fg("dim", `\u2193 ${hidden} more`), inner));
+  const total = rows.length + (Number(held.more) || 0);
+  return [{ key: "held", priority: 5, head: ["held", `${total}${held.truncated ? "+" : ""} waiting on conditions`], body }];
+}
+function heldRow(r, inner, styler) {
+  const bits = [
+    `${styler.fg("dim", "\u25CB")} ${styler.fg("accent", r.target ?? r.jobId ?? "-")}`,
+    styler.fg("text", r.label ?? "-"),
+    styler.fg("dim", `waited ${fmtDuration(r.waitedMs)}`)
+  ];
+  return fitLine(bits.join(styler.fg("dim", " \xB7 ")), inner, styler);
+}
+function fmtDuration(ms) {
+  if (!Number.isFinite(ms) || ms < 0) return "?";
+  const s = Math.floor(ms / 1e3);
+  if (s < 60) return `${s}s`;
+  const m = Math.floor(s / 60);
+  if (m < 60) return `${m}m`;
+  const h = Math.floor(m / 60);
+  return h < 24 ? `${h}h${m % 60}m` : `${Math.floor(h / 24)}d${h % 24}h`;
+}
 function statusHeader(queue, inner, styler) {
   if (!queue || queue.unreachable) {
     return styler.cell(`queue unreachable (${queue?.unreachable ?? "?"})`, inner, { color: "error" });
@@ -41048,7 +41346,7 @@ function runDetailHints(inner, styler, canOpen = false, canCopy = false, copiedN
   if (copiedNote) return fitLine(styler.fg("success", copiedNote) + styler.fg("dim", "  \xB7  ") + line, inner, styler);
   return fitLine(line, inner, styler);
 }
-var KEY_HINTS, RUNS_ON_DASHBOARD, RUNS_VIEWPORT, RUN_SORTS, REFRESH_MS, TAIL_LINES, TAIL_VIEWPORT, MIN_WIDTH2, DRILL_WIDTH, KIND_COLOR, KIND_WIDTH, FRAME_CHROME_ROWS;
+var KEY_HINTS, RUNS_ON_DASHBOARD, RUNS_VIEWPORT, RUN_SORTS, REFRESH_MS, TAIL_LINES, TAIL_VIEWPORT, MIN_WIDTH2, DRILL_WIDTH, HELD_LIMIT, HELD_HYDRATE_MAX2, KIND_COLOR, KIND_WIDTH, FRAME_CHROME_ROWS, HELD_ON_DASHBOARD;
 var init_dashboard = __esm({
   "src/dashboard.ts"() {
     init_budget();
@@ -41071,9 +41369,12 @@ var init_dashboard = __esm({
     TAIL_VIEWPORT = 20;
     MIN_WIDTH2 = 8;
     DRILL_WIDTH = 70;
+    HELD_LIMIT = 20;
+    HELD_HYDRATE_MAX2 = 200;
     KIND_COLOR = { cron: "accent", label: "syntaxType", comment: "syntaxKeyword", pull_request: "syntaxFunction", issue: "syntaxString" };
     KIND_WIDTH = 13;
     FRAME_CHROME_ROWS = 4;
+    HELD_ON_DASHBOARD = 3;
   }
 });
 
@@ -41607,8 +41908,8 @@ var init_setup_wizard = __esm({
     init_deployment_pointer();
     init_read_model();
     init_index();
-    RUNTIME_VERSION = "1.5.0";
-    RECEIVER_VERSION = "1.3.0";
+    RUNTIME_VERSION = "1.6.1";
+    RECEIVER_VERSION = "1.4.0";
     RUNTIME_PKG = "@edgehero/pi-dispatch";
     RECEIVER_PKG = "@edgehero/pi-dispatch-receiver";
     NUDGE_MARKER_BASENAME = "pi-dispatch-setup.nudged";
@@ -42106,6 +42407,41 @@ ${JSON.stringify(before)}
       return toolText(JSON.stringify(rows));
     }
   });
+  pi.registerTool({
+    name: "dispatch_waits",
+    label: "pi-dispatch held jobs",
+    description: "Read-only. Lists the jobs the worker is currently HOLDING on a trigger's run.waitFor condition: the job id, an id-only target, the operator's own words for what it is waiting on, and how long it has waited. A held job has reserved no budget slot and started no container. This is a different set from the queue's `delayed` count, which also mixes cron next-occurrences, retry backoff and quiet hours; only waits appear here. Use the job id for dispatch_wait_cancel.",
+    parameters: typebox_exports.Object({}),
+    async execute() {
+      const paths = resolvePaths(process.env);
+      const held = await readHeldJobs({ url: paths.valkeyUrl });
+      return toolText(JSON.stringify(held));
+    }
+  });
+  pi.registerTool({
+    name: "dispatch_wait_cancel",
+    label: "pi-dispatch cancel a held job",
+    description: "Removes a job that is waiting on a run.waitFor condition, so it never runs. The operator MUST approve a confirm dialog naming the job and what it was waiting on; refused with no interactive operator. Use dispatch_waits for the job id. This is the ONLY way to stop a held job short of editing redis: a held job has spent nothing, so no budget cap will ever stop it, and deleting the trigger does not reach a job already enqueued. Cancelling writes no run record, because the job never ran.",
+    executionMode: "sequential",
+    parameters: typebox_exports.Object({ jobId: typebox_exports.String({ minLength: 1 }) }),
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      const paths = resolvePaths(process.env);
+      const held = await readHeldJobs({ url: paths.valkeyUrl });
+      if (held.unreachable) throw new Error(`queue unreachable: ${held.unreachable}`);
+      const row = (held.rows ?? []).find((r) => r.jobId === params.jobId);
+      if (!row) throw new Error(`no held job ${params.jobId} (dispatch_waits lists the ids that are waiting)`);
+      const result = await confirmedWrite(
+        ctx,
+        { title: `Cancel held job ${row.jobId}`, message: `Cancel ${row.target ?? row.jobId}, waiting on ${row.label ?? "a condition"}. It will never run.` },
+        async () => {
+          const res = await cancelHeldJob({ url: paths.valkeyUrl, jobId: params.jobId });
+          if (res.invalid) throw new Error(`rejected: ${res.invalid}`);
+          return { applied: true, jobId: params.jobId };
+        }
+      );
+      return toolText(JSON.stringify(result));
+    }
+  });
   pi.registerTool({
     name: "dispatch_limit_add",
     label: "pi-dispatch add scoped limit",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-admin",
-  "version": "1.5.0",
+  "version": "1.6.1",
   "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_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`
@@ -242,6 +248,28 @@ If you are asked why a GitLab trigger did not fire, the usual answers in order:
    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