@edgehero/pi-dispatch-admin 0.4.0 → 0.5.0

package/README.md

@@ -13,7 +13,7 @@
 Every trigger produces the same job, through the same path: one queue, one container, one budget.
 
 ```
-   CLI  ·  cron  ·  GitHub issue / PR
+   CLI · cron · label / comment / PR on GitHub, GitLab, Forgejo or Azure DevOps
                 │  enqueue
                 ▼
         Valkey + BullMQ            durable queue: survives reboots, absorbs bursts
@@ -23,14 +23,32 @@ Every trigger produces the same job, through the same path: one queue, one conta
        per-job turn budget?
                 │  yes
                 ▼
-        docker run --rm            one ephemeral container per job:
-   --cap-drop=ALL · non-root       --no-new-privileges · /job mounted read-only
+        docker run --rm            one ephemeral container per job: --cap-drop=ALL,
+                                   --security-opt no-new-privileges, memory/CPU/pids
+                                   limits, /job mounted read-only
                 │
                 ▼
-     pi + your .pi/skills          edits your code in place, opens a PR, comments back
+     pi + your .pi/skills          edits your code in place, opens a PR or MR, comments back
 ```
 
-The container is the boundary (pi's missing permission system, enforced by Docker). Spend is checked before a container starts, so a runaway or a junk trigger costs a refusal, not a surprise bill. The job image is yours to shape, per deployment or per trigger, and it ships Playwright and Chromium so a flow can build a frontend, screenshot it, and iterate on the render.
+The container is the boundary (pi's missing permission system, enforced by Docker). Those isolation flags are built by the worker's own `docker run` argv, so nothing an image contains can weaken them; the non-root user is a property of the **image**, which is why an image has to meet the conformance checklist in [`docs/job-image.md`](https://github.com/edgehero/pi-dispatch/blob/main/docs/job-image.md). Spend is checked before a container starts, so a runaway or a junk trigger costs a refusal, not a surprise bill. The job image is yours to shape, per deployment or per trigger, and it ships Playwright and Chromium so a flow can build a frontend, screenshot it, and iterate on the render.
+
+## Triggers: what starts a job
+
+Every trigger is one `{ on, run }` entry in a single `triggers.json`, read live by the worker (cron) and the receiver (forge webhooks), and editable from the console. **`on` is what fires it; `run` is the skill it runs.**
+
+| `on.type` | Fires on | What narrows it | What the agent gets as its task |
+|---|---|---|---|
+| `cron` | your schedule | nothing: a schedule is its own condition | the `task` written in the file |
+| `label` | a label on an **issue** (or an Azure work item), never a pull request | a label predicate: `any`, `all`, or `none` (which can suppress a fire, never cause one) | the issue title and body |
+| `comment` | a comment containing your phrase, for example `@pi` | the phrase, and one comment trigger per forge | the comment body, plus the issue title and body |
+| `pull_request` | a PR or MR event | `action`, in your forge's own words, plus the same label predicate | the PR title and body |
+
+Four forges: GitHub, GitLab, Forgejo (and Gitea), Azure DevOps. **Who may fire a trigger is your forge's decision, not this service's**: on GitHub the label *is* the approval, because only collaborators can apply one, while GitLab, Forgejo and Azure resolve the actor's permission through their APIs. Each forge's action vocabulary is validated when the file loads, so a word from the wrong forge is refused instead of silently never matching.
+
+**Flows, and workflows.** `run.flow` names a skill committed to the target repo at `.pi/skills/<flow>/SKILL.md`, read from the **default branch**, so the repo owns the prompt and merging it is the repo's consent. A skill may call other skills, which is already a workflow. For typed multi-stage ones, a pi extension such as `@juicesharp/rpiv-workflow` can be staged into the deployment: pinned to an exact version, installed on your host (never at job time, since jobs run offline), loaded in every container, and declinable per trigger.
+
+**How a workflow gets triggered, in one line:** `label / comment / PR / cron` fires **one job in one container**, that job runs `run.flow`, and the flow drives whatever stages follow. Four consequences worth knowing before you build on it. A trigger names a **flow, never a workflow**, so which stages run is decided inside the job by that skill. A job is **not an interactive session** (the container hands pi one assembled prompt and reads the exit line), so a workflow extension's slash command has nobody to type it: in a job the flow's instructions drive the workflow, or a small extension you also staged calls its API from a lifecycle hook. One trigger is **one job, one budget slot and one turn budget**, so ten stages share the same `PI_MAX_TURNS` and per-job token budget, and exhausting either ends the job as a policy refusal that is never retried. And whether the workflow's own state survives depends on the trigger kind: a cron or CLI job has your folder mounted read-write so state persists between runs, while a forge job gets a fresh clone that is discarded with the container. Full reference: [`docs/workflows.md`](https://github.com/edgehero/pi-dispatch/blob/main/docs/workflows.md).
 
 ## The console: `/dispatch`
 
@@ -49,7 +67,7 @@ One command puts a live TUI over the whole deployment:
 
 - **Triggers, editable live.** cron, label, comment and pull_request triggers with colored drill-ins showing what fires each one, what it runs, and its trust model. Added, edited and deleted without a restart. 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.
-- **AI-operable, with a human gate.** Model-callable tools let an agent change limits and manage triggers and pause windows, but every write pops an operator confirmation the model cannot answer, and refuses when no operator is present. The bundled `operate-pi-dispatch` skill teaches the agent those gates.
+- **AI-operable, with a human gate.** Model-callable tools let an agent change limits 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). 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.
 
 ## Install
@@ -58,10 +76,12 @@ One command puts a live TUI over the whole deployment:
 pi install npm:@edgehero/pi-dispatch-admin   # then, in pi:  /dispatch
 ```
 
-**No deployment yet? The console builds one.** When `/dispatch` finds nothing, it offers `/dispatch setup`: pick a folder, consent to an npm install of the pinned runtime, watch `pi-dispatch up` run its own prompts, optionally install the worker as a service, and land in the panel. Every step asks first and can be declined; nothing is written into your repo and no credential passes through a dialog.
+**This is the default way to set up pi-dispatch.** With nothing configured, `/dispatch` takes you straight into guided setup, in this order: an opening choice, a deployment folder, a Docker check with per-OS pointers if it is missing, a consented npm install of the pinned runtime (Docker is checked **first** on purpose, so no bandwidth is spent on a host where `up` cannot work anyway), `pi-dispatch up` running its own prompts in your terminal, the deployment pointer that lets `/dispatch` find this deployment from any directory, a notice naming the file your provider key belongs in, an optional worker service, optional GitHub App credentials (`setup github`, the one step that mints a private key), an optional trigger edge (receiver service, docker compose profile, or the polling command), and an optional first **cron** trigger for the repo you are sitting in. Every step shows what it will do, asks first, and can be declined; nothing is written into your repo and no credential passes through a dialog. A deployment whose queue is merely down keeps the unreachable banner instead: setup appears when there is nothing, never over an outage.
 
 Already have a deployment? The panel finds it through the deployment pointer setup writes, or through the same env vars your worker uses (`VALKEY_URL`, `PI_LOGS_DIR`, `PI_SETTINGS_FILE`, `PI_TRIGGERS_FILE`, `PI_PAUSE_WINDOWS_FILE`, `PI_SUBSCRIPTIONS_FILE`). Your env always wins.
 
+`dispatch_run` is inert until you set one more variable yourself: `PI_DISPATCH_RUN_ROOTS` defaults to empty, and an empty allowlist refuses every folder. The deployment pointer deliberately cannot set it (the pointer carries paths, never capability grants), so widening that allowlist is always your own env edit.
+
 ## Get the whole thing
 
 ### → **https://github.com/edgehero/pi-dispatch**

package/dist/index.mjs

@@ -7952,6 +7952,11 @@ function validateResumeFlag(run, at, path) {
   if (run.resume !== void 0 && typeof run.resume !== "boolean") {
     throw configError(`${at}: run.resume must be true or false when present: ${path}`);
   }
+  if (run.resume === true && run.kind === "local") {
+    throw configError(
+      `${at}: run.resume is not yet covered for cron triggers (forge triggers only in this version) -- resolveSession is handed to the forge preparers only, so a local job would stage no transcript, mount no /session and promote nothing, then exit 0 as though it had; the local session key exists in session-key.mjs and nothing reaches it, so this is a gap to close, not a limit: ${path}`
+    );
+  }
   return run.resume;
 }
 function validateImageRef(run, at, path) {
@@ -37456,17 +37461,24 @@ var init_dashboard = __esm({
 // src/setup-wizard.ts
 var setup_wizard_exports = {};
 __export(setup_wizard_exports, {
+  RECEIVER_VERSION: () => RECEIVER_VERSION,
   RUNTIME_VERSION: () => RUNTIME_VERSION,
   detectDeployment: () => detectDeployment,
+  dockerHint: () => dockerHint,
   listRepoSkills: () => listRepoSkills,
   npmInstallArgs: () => npmInstallArgs,
+  npmInstallArgsFor: () => npmInstallArgsFor,
   npmSpawnOptions: () => npmSpawnOptions,
+  probeDocker: () => probeDocker,
+  readInstalledVersion: () => readInstalledVersion,
+  receiverInstallArgs: () => receiverInstallArgs,
   registerNudge: () => registerNudge,
   runAttached: () => runAttached,
-  runSetupWizard: () => runSetupWizard
+  runSetupWizard: () => runSetupWizard,
+  runtimeDirFor: () => runtimeDirFor
 });
 import * as nodeFs4 from "node:fs";
-import { spawn as nodeSpawn } from "node:child_process";
+import { execFileSync as execFileSync3, spawn as nodeSpawn } from "node:child_process";
 import { homedir as homedir2 } from "node:os";
 import { join as join6 } from "node:path";
 function envIsSet(env, key) {
@@ -37545,10 +37557,10 @@ ${title}
   const result = await custom.call(ctx.ui, factory, { overlay: true });
   return result ?? { code: null, error: new Error("the overlay closed before the command finished") };
 }
-function npmInstallArgs() {
+function npmInstallArgsFor(pkgName, version) {
   return [
     "install",
-    `@edgehero/pi-dispatch@${RUNTIME_VERSION}`,
+    `${pkgName}@${version}`,
     "--omit=dev",
     "--omit=optional",
     "--ignore-scripts",
@@ -37557,6 +37569,54 @@ function npmInstallArgs() {
     "--loglevel=error"
   ];
 }
+function npmInstallArgs() {
+  return npmInstallArgsFor(RUNTIME_PKG, RUNTIME_VERSION);
+}
+function receiverInstallArgs() {
+  return npmInstallArgsFor(RECEIVER_PKG, RECEIVER_VERSION);
+}
+function probeDocker(execFn = execFileSync3) {
+  try {
+    execFn("docker", ["version"], { stdio: "ignore", timeout: DOCKER_PROBE_TIMEOUT_MS });
+    return { ok: true };
+  } catch (err) {
+    if (err?.code === "ENOENT" || err?.errno === "ENOENT") return { missing: true };
+    if (typeof err?.status === "number") return { daemonDown: `\`docker version\` exited ${err.status}` };
+    return { daemonDown: err?.message ?? String(err) };
+  }
+}
+function dockerHint(platform) {
+  if (platform === "darwin") {
+    return "macOS: install and START Docker Desktop (docs.docker.com/desktop/install/mac-install) or OrbStack (orbstack.dev) \u2014 either one provides the `docker` CLI and a running daemon.";
+  }
+  if (platform === "win32") {
+    return "Windows: install and START Docker Desktop (docs.docker.com/desktop/install/windows-install) \u2014 it provides the `docker` CLI and a running daemon.";
+  }
+  return "Linux: install the docker engine from your distribution's own packages, following docs.docker.com/engine/install, then start and enable its daemon.";
+}
+async function ensureDocker(ui, notify, { platform, probeDockerFn }) {
+  for (let round = 1; ; round++) {
+    const probe = probeDockerFn();
+    if (probe.ok) return true;
+    const why = probe.missing ? "no `docker` on PATH" : `docker is installed but not answering (${probe.daemonDown})`;
+    notify?.(`docker check: ${why}. ${dockerHint(platform)}`, "warning");
+    if (round >= DOCKER_PROBE_ROUNDS) {
+      notify?.(
+        `docker still not ready after ${DOCKER_PROBE_ROUNDS} checks \u2014 stopping setup before anything was installed. Re-run /dispatch setup once \`docker version\` answers.`,
+        "error"
+      );
+      return false;
+    }
+    const choice = await ui.select("Docker is not ready", ["Re-check", "Continue anyway", "Stop"]);
+    if (choice === "Re-check") continue;
+    if (choice === "Continue anyway") {
+      notify?.("continuing without a docker answer \u2014 `up` runs its own docker checks and refuses there if it is still missing", "info");
+      return true;
+    }
+    notify?.("setup stopped before anything was installed \u2014 re-run /dispatch setup when docker is ready", "info");
+    return false;
+  }
+}
 function npmSpawnOptions(platform, dir) {
   return platform === "win32" ? { bin: "npm.cmd", options: { cwd: dir, shell: true } } : { bin: "npm", options: { cwd: dir } };
 }
@@ -37568,6 +37628,9 @@ function listRepoSkills(cwd, fs = nodeFs4) {
     return [];
   }
 }
+function runtimeDirFor(dir, pkg = "pi-dispatch") {
+  return join6(dir, "node_modules", "@edgehero", pkg);
+}
 function readInstalledVersion(fs, runtimeDir) {
   try {
     const pkg = JSON.parse(fs.readFileSync(join6(runtimeDir, "package.json"), "utf8"));
@@ -37576,6 +37639,13 @@ function readInstalledVersion(fs, runtimeDir) {
     return void 0;
   }
 }
+function ensureDeploymentPackageJson(fs, dir) {
+  const rootPkg = join6(dir, "package.json");
+  if (!fs.existsSync(rootPkg)) {
+    fs.writeFileSync(rootPkg, `${JSON.stringify({ name: "pi-dispatch-deployment", private: true }, null, 2)}
+`);
+  }
+}
 async function runSetupWizard(paths, ctx, notify, deps = {}) {
   const {
     fs = nodeFs4,
@@ -37591,14 +37661,16 @@ async function runSetupWizard(paths, ctx, notify, deps = {}) {
     writeTriggersFn = writeTriggers,
     resolvePathsFn = resolvePaths,
     listRepoSkillsFn = listRepoSkills,
-    existsSyncFn = (p) => fs.existsSync(p)
+    existsSyncFn = (p) => fs.existsSync(p),
+    probeDockerFn = probeDocker,
+    initialDetection
   } = deps;
   const ui = ctx?.ui;
   if (typeof ui?.input !== "function" || typeof ui?.select !== "function" || typeof ui?.confirm !== "function") {
     notify?.("setup needs dialogs (newer pi) \u2014 no input/select/confirm available", "warning");
     return;
   }
-  const det = await detectFn({ env, cwd: ctx?.cwd, fs });
+  const det = initialDetection ?? await detectFn({ env, cwd: ctx?.cwd, fs });
   notify?.(`pi-dispatch setup \u2014 detected: ${det.detail}`, "info");
   const intent = await ui.select("pi-dispatch setup", ["Guided setup", "Open the panel anyway", "Cancel"]);
   if (intent === "Open the panel anyway") {
@@ -37615,8 +37687,9 @@ async function runSetupWizard(paths, ctx, notify, deps = {}) {
     notify?.(`could not create ${dir}: ${err?.message ?? err} \u2014 setup cannot continue`, "error");
     return;
   }
-  const runtimeDir = join6(dir, "node_modules", "@edgehero", "pi-dispatch");
+  const runtimeDir = runtimeDirFor(dir);
   const cliPath = join6(runtimeDir, "src", "cli.mjs");
+  if (!await ensureDocker(ui, notify, { platform, probeDockerFn })) return;
   if (readInstalledVersion(fs, runtimeDir) === RUNTIME_VERSION) {
     notify?.(`runtime ${RUNTIME_VERSION} already installed in ${dir} \u2014 skipping npm install`, "info");
   } else {
@@ -37632,11 +37705,7 @@ async function runSetupWizard(paths, ctx, notify, deps = {}) {
     if (!okInstall) {
       notify?.(`install skipped \u2014 later steps assume the runtime at ${runtimeDir}`, "info");
     } else {
-      const rootPkg = join6(dir, "package.json");
-      if (!fs.existsSync(rootPkg)) {
-        fs.writeFileSync(rootPkg, `${JSON.stringify({ name: "pi-dispatch-deployment", private: true }, null, 2)}
-`);
-      }
+      ensureDeploymentPackageJson(fs, dir);
       const res = await runAttachedFn(ctx, {
         title: `npm install @edgehero/pi-dispatch@${RUNTIME_VERSION} \u2014 in ${dir}`,
         argv0: bin,
@@ -37738,6 +37807,7 @@ ${JSON.stringify(pointer, null, 2)}`);
   } else {
     notify?.(`later: node ${cliPath} setup github  (in ${dir})`, "info");
   }
+  await offerTriggerEdge(dir, ctx, ui, notify, { fs, platform, env, execPath, cliPath, runAttachedFn });
   if (typeof ctx?.cwd === "string" && ctx.cwd !== "" && existsSyncFn(ctx.cwd)) {
     await offerFirstTrigger(ctx.cwd, dir, ui, notify, { fs, listRepoSkillsFn, writeTriggersFn });
   }
@@ -37747,6 +37817,110 @@ ${JSON.stringify(pointer, null, 2)}`);
     await openDashboardFn(resolvePathsFn(env), ctx, notify);
   }
 }
+async function offerTriggerEdge(dir, ctx, ui, notify, { fs, platform, env, execPath, cliPath, runAttachedFn }) {
+  const choice = await ui.select("How should GitHub events reach the queue?", [
+    EDGE_SERVICE,
+    EDGE_COMPOSE,
+    EDGE_POLL,
+    "Skip"
+  ]);
+  if (choice === EDGE_SERVICE) {
+    const args = receiverInstallArgs();
+    const { bin, options } = npmSpawnOptions(platform, dir);
+    const unitHint = `node ${cliPath} service install --receiver  (in ${dir})`;
+    const ok = await ui.confirm(
+      "Install the webhook receiver",
+      `Run in ${dir}:
+  ${bin} ${args.join(" ")}
+
+then, in the same folder:
+  ${execPath} ${cliPath} service install --receiver
+
+(scripts disabled; installs the pinned ${RECEIVER_PKG}@${RECEIVER_VERSION}, then renders a user-level receiver unit for this host)`
+    );
+    if (!ok) {
+      notify?.(`receiver skipped \u2014 later: ${bin} ${args.join(" ")}  (in ${dir}), then ${unitHint}`, "info");
+      return;
+    }
+    ensureDeploymentPackageJson(fs, dir);
+    const res = await runAttachedFn(ctx, {
+      title: `npm install ${RECEIVER_PKG}@${RECEIVER_VERSION} \u2014 in ${dir}`,
+      argv0: bin,
+      args,
+      cwd: options.cwd,
+      shell: options.shell,
+      env
+    });
+    const installed = readInstalledVersion(fs, runtimeDirFor(dir, "pi-dispatch-receiver"));
+    if (installed !== RECEIVER_VERSION) {
+      const how = res?.error ? `npm could not run: ${res.error.message}` : `npm exited ${res?.code}`;
+      notify?.(
+        `${how}; installed receiver version is ${installed ?? "(absent)"}, not the pinned ${RECEIVER_VERSION} \u2014 skipping the receiver unit (the rest of the deployment is unaffected). Fix the install, then run: ${unitHint}`,
+        "error"
+      );
+      return;
+    }
+    await runAttachedFn(ctx, {
+      title: `pi-dispatch service install --receiver \u2014 in ${dir}`,
+      argv0: execPath,
+      args: [cliPath, "service", "install", "--receiver"],
+      cwd: dir,
+      env
+    });
+    return;
+  }
+  if (choice === EDGE_COMPOSE) {
+    const src = join6(runtimeDirFor(dir), "deploy", "docker-compose.yml");
+    const dest = join6(dir, "docker-compose.yml");
+    if (fs.existsSync(dest)) {
+      notify?.(`${dest} already exists \u2014 keeping yours as it is (setup never overwrites a compose file you may have edited)`, "info");
+    } else {
+      try {
+        fs.copyFileSync(src, dest);
+        notify?.(`copied the runtime's compose file to ${dest}`, "info");
+      } catch (err) {
+        notify?.(
+          `could not copy ${src}: ${err?.message ?? err} \u2014 the receiver profile needs that file; skipping this step (install the runtime first, or copy it by hand)`,
+          "error"
+        );
+        return;
+      }
+    }
+    const args = ["compose", "-f", dest, "--profile", "receiver", "up", "-d"];
+    const ok = await ui.confirm(
+      "Start the receiver container",
+      `Run in ${dir}:
+  docker ${args.join(" ")}
+
+the receiver profile reads ${join6(dir, ".env")} \u2014 WEBHOOK_SECRET and the forge credentials must be in there, or the container refuses to boot.`
+    );
+    if (!ok) {
+      notify?.(`later: docker ${args.join(" ")}  (in ${dir})`, "info");
+      return;
+    }
+    await runAttachedFn(ctx, {
+      title: `docker compose --profile receiver up -d \u2014 in ${dir}`,
+      argv0: "docker",
+      args,
+      cwd: dir,
+      env
+    });
+    return;
+  }
+  if (choice === EDGE_POLL) {
+    notify?.(
+      `polling needs no public URL, no DNS and no tunnel \u2014 two commands, in ${dir}:
+  1) node ${cliPath} setup github --no-webhook   (mints the App with its webhook INACTIVE \u2014 the polling-ready shape)
+  2) npx @edgehero/pi-dispatch-receiver poll   (the producer; run it from the deployment folder, under whatever keeps it alive)`,
+      "info"
+    );
+    return;
+  }
+  notify?.(
+    `trigger edge left for later \u2014 all three ways stay open from ${dir}: \`service install --receiver\` (a receiver unit on this host), \`docker compose --profile receiver up -d\` (a receiver container), or \`npx @edgehero/pi-dispatch-receiver poll\` (no public URL at all). Local cron triggers need none of them.`,
+    "info"
+  );
+}
 async function offerFirstTrigger(repoCwd, deployDir, ui, notify, { fs, listRepoSkillsFn, writeTriggersFn }) {
   const offer = await ui.select("First trigger", ["A cron trigger for this repo", "Skip"]);
   if (offer !== "A cron trigger for this repo") return;
@@ -37806,23 +37980,40 @@ function registerNudge(pi, deps = {}) {
     }
   });
 }
-var RUNTIME_VERSION, NUDGE_MARKER_BASENAME, CWD_SCAFFOLD_FILES, ENV_PATH_KEYS, CRON_ID_RE;
+var RUNTIME_VERSION, RECEIVER_VERSION, RUNTIME_PKG, RECEIVER_PKG, NUDGE_MARKER_BASENAME, CWD_SCAFFOLD_FILES, ENV_PATH_KEYS, DOCKER_PROBE_ROUNDS, DOCKER_PROBE_TIMEOUT_MS, CRON_ID_RE, EDGE_SERVICE, EDGE_COMPOSE, EDGE_POLL;
 var init_setup_wizard = __esm({
   "src/setup-wizard.ts"() {
     init_flow_gate();
     init_deployment_pointer();
     init_read_model();
     init_index();
-    RUNTIME_VERSION = "0.1.1";
+    RUNTIME_VERSION = "0.1.2";
+    RECEIVER_VERSION = "0.1.1";
+    RUNTIME_PKG = "@edgehero/pi-dispatch";
+    RECEIVER_PKG = "@edgehero/pi-dispatch-receiver";
     NUDGE_MARKER_BASENAME = "pi-dispatch-setup.nudged";
     CWD_SCAFFOLD_FILES = [".env", "triggers.json", "pause-windows.json", "subscriptions.json"];
     ENV_PATH_KEYS = POINTER_ENV_ALLOWLIST.filter((key) => key !== "VALKEY_URL");
+    DOCKER_PROBE_ROUNDS = 5;
+    DOCKER_PROBE_TIMEOUT_MS = 1e4;
     CRON_ID_RE = /^[A-Za-z0-9._-]+$/;
+    EDGE_SERVICE = "Install the webhook receiver as a service";
+    EDGE_COMPOSE = "Run the receiver with docker compose";
+    EDGE_POLL = "Show the polling command";
   }
 });
 
 // src/index.ts
+import { VERSION } from "@earendil-works/pi-coding-agent";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
+import * as nodeFs5 from "node:fs";
+function computePiVersionAdvisory(version, supported) {
+  if (version === supported || version === "0.0.0") return void 0;
+  return `pi-dispatch admin: running on pi ${version}, tested with pi ${supported} \u2014 things should work; report anything odd, and check for a newer @edgehero/pi-dispatch-admin`;
+}
+function _setPiVersionAdvisoryForTests(message) {
+  piVersionAdvisory = message;
+}
 function admin(pi) {
   for (const member of USED_API) {
     if (typeof pi[member] !== "function") {
@@ -37832,6 +38023,10 @@ function admin(pi) {
       return;
     }
   }
+  if (!piVersionCheckDone) {
+    piVersionCheckDone = true;
+    piVersionAdvisory = computePiVersionAdvisory(VERSION, SUPPORTED_PI_VERSION);
+  }
   try {
     applyDeploymentPointer();
   } catch {
@@ -38262,22 +38457,28 @@ async function dispatch(pi, args, ctx) {
   setGlyphs(paths.asciiGlyphs);
   const pnote = takePointerNotice();
   if (pnote) notify?.(pnote, "warning");
+  if (piVersionAdvisory) {
+    notify?.(piVersionAdvisory, "info");
+    piVersionAdvisory = void 0;
+  }
   if (sub === "") {
-    const { detectDeployment: detectDeployment2, runSetupWizard: runSetupWizard2 } = await Promise.resolve().then(() => (init_setup_wizard(), setup_wizard_exports));
+    const { detectDeployment: detectDeployment2, runSetupWizard: runSetupWizard2, readInstalledVersion: readInstalledVersion2, runtimeDirFor: runtimeDirFor2, RUNTIME_VERSION: RUNTIME_VERSION2 } = await Promise.resolve().then(() => (init_setup_wizard(), setup_wizard_exports));
     const det = await detectDeployment2({ env: process.env, cwd: ctx?.cwd });
     if (det.state === "none") {
-      if (typeof ctx?.ui?.confirm === "function") {
-        const ok = await ctx.ui.confirm(
-          "pi-dispatch setup",
-          "No deployment found (no pointer, no env, no config here, queue unreachable). Set one up now?"
+      await runSetupWizard2(paths, ctx, notify, { openDashboardFn: openDashboard, initialDetection: det });
+      return;
+    }
+    if (det.state === "pointer" && !runtimeSkewNoticed) {
+      const ptrRes = readPointer({ path: pointerPath(process.env) });
+      const deploymentDir = ptrRes.pointer?.deploymentDir;
+      const installed = deploymentDir ? readInstalledVersion2(nodeFs5, runtimeDirFor2(deploymentDir)) : void 0;
+      if (typeof installed === "string" && installed !== RUNTIME_VERSION2) {
+        runtimeSkewNoticed = true;
+        notify?.(
+          `deployment runtime ${installed}, this console pins ${RUNTIME_VERSION2} \u2014 run /dispatch setup to upgrade`,
+          "warning"
         );
-        if (ok) {
-          await runSetupWizard2(paths, ctx, notify, { openDashboardFn: openDashboard });
-          return;
-        }
       }
-      notify?.(`${USAGE} \u2014 run /dispatch setup when you are ready`, "info");
-      return;
     }
     if (det.state === "cwd" || det.state === "reachable") {
       notify?.(`using ${det.detail} \u2014 /dispatch setup can write a deployment pointer so this works from anywhere`, "info");
@@ -38846,7 +39047,7 @@ function completeArguments(prefix) {
   }
   return null;
 }
-var USED_API, SUPPORTED_PI_VERSION, CHANNEL, REBUILT_NOTICE, USAGE, KNOWN_SUBCOMMANDS, FORGE_PROMPT, PR_ACTION_VOCAB, COSTS_WINDOWS2, COSTS_USAGE, DAY_MS2, PRICING, VIEWPORT_LINES;
+var USED_API, SUPPORTED_PI_VERSION, piVersionAdvisory, piVersionCheckDone, runtimeSkewNoticed, CHANNEL, REBUILT_NOTICE, USAGE, KNOWN_SUBCOMMANDS, FORGE_PROMPT, PR_ACTION_VOCAB, COSTS_WINDOWS2, COSTS_USAGE, DAY_MS2, PRICING, VIEWPORT_LINES;
 var init_index = __esm({
   "src/index.ts"() {
     init_build();
@@ -38863,6 +39064,8 @@ var init_index = __esm({
     init_keys2();
     USED_API = ["registerCommand", "registerTool", "sendMessage", "on"];
     SUPPORTED_PI_VERSION = "0.80.7";
+    piVersionCheckDone = false;
+    runtimeSkewNoticed = false;
     CHANNEL = "pi-dispatch-admin";
     REBUILT_NOTICE = (reason) => `replaced invalid settings file (${reason}) \u2014 other keys were lost`;
     USAGE = "usage: /dispatch <status|pause|resume|run|runs|logs|budget|costs|triggers|settings|set|unset|setup>";
@@ -38899,7 +39102,9 @@ init_index();
 export {
   SUPPORTED_PI_VERSION,
   USED_API,
+  _setPiVersionAdvisoryForTests,
   buildTriggerEntry,
+  computePiVersionAdvisory,
   admin as default,
   handleDashboardAction
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch-admin",
-  "version": "0.4.0",
+  "version": "0.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",
@@ -54,7 +54,7 @@
     "ioredis": "5.11.1"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "0.80.7"
+    "@earendil-works/pi-coding-agent": "*"
   },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "0.80.7",