@edgehero/pi-dispatch-admin 0.1.3 → 0.1.5

package/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/banner.png" alt="pi-dispatch — run the pi coding agent as a self-hosted service" width="880">
+  <img src="https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/banner.png?v=0.4.0" alt="pi-dispatch — run the pi coding agent as a self-hosted service" width="880">
 </p>
 
 # pi-dispatch — run the pi coding agent as a self-hosted service
@@ -32,7 +32,7 @@ Every trigger produces the same job, through the same path — one queue, one co
 
 - **The container is the boundary.** pi ships no permission system, so every job runs `--cap-drop=ALL`, non-root, ephemeral, with its instructions mounted read-only. That *is* the missing permission system — enforced by Docker, not hoped for.
 - **Spend is bounded before tokens.** A per-job turn budget plus daily / weekly / monthly caps, checked *before* a container starts. A runaway or a junk trigger costs you a refusal, not a surprise bill.
-- **Three triggers, one job.** A CLI command, a cron schedule, or a GitHub issue/PR — same queue, same box, same budget. Cron is the unattended one: recurring work on your own hardware, in an image you control.
+- **Three triggers, one job.** A CLI command, a cron schedule, or a GitHub issue/PR — same queue, same box, same budget. Cron is the unattended one: recurring work on your own hardware, in an image you control — one per deployment, or one per trigger.
 - **Your image, your tools.** Bake a project's toolchain into the Dockerfile; it ships **Playwright + Chromium**, so a flow can build a frontend, screenshot it, and iterate on the rendered result.
 
 ## The console — `/dispatch`
@@ -40,11 +40,13 @@ Every trigger produces the same job, through the same path — one queue, one co
 This extension puts a live TUI over the whole deployment in one command:
 
 <p align="center">
-  <img src="https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/dispatch-dashboard.png" alt="The /dispatch panel: status, spend meters, triggers, runs, and settings" width="820">
+  <img src="https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/dispatch-dashboard.png?v=0.4.0" alt="The /dispatch panel: status, spend meters, triggers, runs, and settings" width="820">
 </p>
 
 - **Status & spend.** Queue and worker state, day/week/month **spend meters** + a daily token counter, and a run-history table with per-job token & cost.
 - **Triggers, editable live.** cron / label / comment / pull_request, with colored drill-ins showing *what fires* each one, *what it runs*, and its *trust model* — added, edited, and deleted without a restart.
+- **You can see which triggers run third-party code.** A trigger loads the pi packages you pinned into your global overlay **unless** it carries `run.packages: false`, so the ones that do get a **`[packages]`** badge in the trigger list, and their **trust model** names the staged `name@version` set plus the one-line consequence — third-party code, on adversarial input, with open network egress. Declining is deliberately *not* a panel action: it stays an edit to the reviewed `triggers.json`, which neither the console nor a model-callable tool will make for you.
+- **You can see which image each trigger runs.** A trigger may name its own container image with `run.image` (absent = the deployment default), and the trigger list shows the tag while the drill-in states it either way — because which image a job runs *is* which code it runs. Like `packages`, it is display-only: naming an image 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 a scope's runs **between certain times** — recurring daily, weekday- and date-bounded, 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 can't answer**, and is refused when no operator is present. The bundled `operate-pi-dispatch` **skill** teaches the agent to use those gates.
 - **Logs stay put.** Raw container output renders only in the overlay viewer, never into model context.
@@ -55,7 +57,7 @@ This extension puts a live TUI over the whole deployment in one command:
 pi install npm:@edgehero/pi-dispatch-admin
 ```
 
-Then run pi and open `/dispatch`. Point it at your deployment with `VALKEY_URL` / `PI_LOGS_DIR` / `PI_SETTINGS_FILE` / `PI_TRIGGERS_FILE` / `PI_PAUSE_WINDOWS_FILE` — the same values your worker uses. It reads that deployment's queue and run history; on its own it will just say "queue unreachable."
+Then run pi and open `/dispatch`. Point it at your deployment with `VALKEY_URL` / `PI_LOGS_DIR` / `PI_SETTINGS_FILE` / `PI_TRIGGERS_FILE` / `PI_PAUSE_WINDOWS_FILE` / `PI_GLOBAL_PI_DIR` — the same values your worker uses. It reads that deployment's queue and run history; on its own it will just say "queue unreachable."
 
 ## Get the whole thing
 

package/dist/index.mjs

@@ -4220,15 +4220,92 @@ __export(typebox_exports, {
 
 // src/read-model.mjs
 import * as nodeFs2 from "node:fs";
-import { join, delimiter, sep } from "node:path";
+import { join as join2, delimiter, sep } from "node:path";
 import { execFileSync as execFileSync2 } from "node:child_process";
 
+// ../worker/src/forges.mjs
+var FORGES = {
+  github: {
+    jobIdPrefix: "gh-",
+    deliveryIdName: "X-GitHub-Delivery GUID",
+    pullRequestSep: "#",
+    tokenVars: ["GITHUB_TOKEN", "GH_TOKEN"],
+    hostVar: null,
+    prLabelAction: "labeled"
+  },
+  gitlab: {
+    jobIdPrefix: "gl-",
+    deliveryIdName: "webhook-id / Idempotency-Key",
+    pullRequestSep: "!",
+    tokenVars: ["GITLAB_TOKEN", "GL_TOKEN"],
+    hostVar: "GITLAB_HOST",
+    // A label added to a merge request arrives as a plain `update`, indistinguishable from any other
+    // edit, so there is no action for a positive-selector rule to attach to. (Separately, a GitLab label
+    // is not an approval at all -- a Guest can set one at issue creation -- which is why every gitlab
+    // trigger is gated on the actor's resolved access level.)
+    prLabelAction: null
+  },
+  forgejo: {
+    // Forgejo's webhook transport is byte-compatible with GitHub's -- it signs the raw body HMAC-SHA256
+    // and sends X-Hub-Signature-256, X-GitHub-Delivery and X-GitHub-Event. So the delivery id is a GUID
+    // with the same across-retry stability GitHub's has, and REQ-DEDUP-BY-DELIVERY-GUID transfers
+    // unchanged. Only the PREFIX differs, and only so the id spaces stay disjoint.
+    jobIdPrefix: "fj-",
+    deliveryIdName: "X-GitHub-Delivery GUID",
+    // Forgejo numbers issues and pull requests from ONE per-repository sequence, exactly as GitHub does
+    // -- an issue and a PR cannot share an index. So `#` names one thing and no discriminator is needed.
+    pullRequestSep: "#",
+    // `tea` reads GITEA_SERVER_TOKEN; the unprefixed name is what the API examples and most scripts use.
+    tokenVars: ["FORGEJO_TOKEN", "GITEA_SERVER_TOKEN"],
+    hostVar: "FORGEJO_HOST",
+    // Forgejo names the action, so the positive-selector rule applies exactly as it does on GitHub.
+    // Note this is HYGIENE, not the gate: unlike GitHub, every forgejo trigger is additionally gated on
+    // the actor's resolved repository permission -- see filter-forgejo.mjs for why that is not
+    // redundant belt-and-braces but the only claim about Forgejo this project is willing to make.
+    prLabelAction: "label_updated"
+  },
+  azure: {
+    // Azure Service Hooks send NO delivery-id header at all, so this id comes from the body's top-level
+    // `id` GUID -- the one departure `verify-gitlab.mjs` explicitly refuses to make, taken here because
+    // the refusal is right for a forge that HAS a header and inapplicable to one that has none.
+    // (Issue #43 proposes `notificationId`, which is a per-subscription integer sequence: two
+    // subscriptions collide on delivery 1.)
+    jobIdPrefix: "az-",
+    deliveryIdName: "service hook payload id",
+    // Azure numbers work items and pull requests from SEPARATE sequences -- work item ids are
+    // organization-scoped, pull request ids are not -- so `project/repo#123` and `project/repo!123` are
+    // different objects and would collide on one separator, exactly as GitLab's issue #5 and MR !5 do.
+    pullRequestSep: "!",
+    // `az repos` reads AZURE_DEVOPS_EXT_PAT; SYSTEM_ACCESSTOKEN is what a pipeline-shaped script expects.
+    tokenVars: ["AZURE_DEVOPS_EXT_PAT", "SYSTEM_ACCESSTOKEN"],
+    hostVar: "AZURE_DEVOPS_ORG_URL",
+    // Azure attaches no labels to a pull request at all, so there is no action to attach the rule to and
+    // a predicated PR rule could never match. The loader refuses one rather than letting it load dead.
+    prLabelAction: null
+  }
+};
+var FORGE_KINDS = Object.freeze(Object.keys(FORGES));
+var RUN_KINDS = Object.freeze(["local", ...FORGE_KINDS]);
+function isForgeKind(kind) {
+  return typeof kind === "string" && Object.hasOwn(FORGES, kind);
+}
+function forgeSpec(kind) {
+  return isForgeKind(kind) ? FORGES[kind] : void 0;
+}
+var MINTED_TOKEN_VARS = new Set(FORGE_KINDS.flatMap((kind) => FORGES[kind].tokenVars));
+
 // ../worker/src/config.mjs
 function configError(message) {
   const error = new Error(message);
   error.piDispatchConfig = true;
   return error;
 }
+function defaultJobsDir() {
+  return `${process.env.TMPDIR ?? process.env.TEMP ?? "/tmp"}/pi-dispatch/jobs`.replace(/\\/g, "/");
+}
+function defaultSandboxDir(env = process.env) {
+  return `${env.PI_JOBS_DIR ?? defaultJobsDir()}/sandboxes`.replace(/\\/g, "/");
+}
 function defaultLogsDir() {
   return `${process.env.TMPDIR ?? process.env.TEMP ?? "/tmp"}/pi-dispatch/logs`.replace(/\\/g, "/");
 }
@@ -4371,8 +4448,20 @@ function windowState(reserved, cap, softHoldPct = null) {
 
 // ../worker/src/triggers.mjs
 var ON_TYPES = /* @__PURE__ */ new Set(["cron", "label", "comment", "pull_request"]);
-var RUN_KINDS = /* @__PURE__ */ new Set(["local", "github"]);
-var PR_ACTIONS = /* @__PURE__ */ new Set(["labeled", "opened", "synchronize", "reopened"]);
+var PR_ACTIONS = {
+  github: /* @__PURE__ */ new Set(["labeled", "opened", "synchronize", "reopened"]),
+  gitlab: /* @__PURE__ */ new Set(["open", "update", "reopen", "approved"]),
+  // Forgejo's own spellings. `label_updated` is its `labeled` and `synchronized` its `synchronize` -- a
+  // one-letter difference that an operator would otherwise discover as a trigger that loads clean and
+  // never fires. `label_cleared` is deliberately ABSENT and always will be: REMOVING a label must never
+  // start a paid run, and it has no GitHub counterpart to inherit that rule from.
+  forgejo: /* @__PURE__ */ new Set(["label_updated", "opened", "synchronized", "reopened"]),
+  // Azure's Service Hook events reduced to the two that leave something to act on. `git.pullrequest.merged`
+  // is omitted for the same reason GitLab's `merge` and `close` are: a job started by a merge has nothing
+  // left to do. There is no label action at all -- Azure attaches tags to WORK ITEMS, never to pull
+  // requests -- which is why azure's `prLabelAction` is null and a predicated PR rule is refused below.
+  azure: /* @__PURE__ */ new Set(["created", "updated"])
+};
 var ID_CHARSET = /^[A-Za-z0-9._-]+$/;
 function isNonEmptyString2(value) {
   return typeof value === "string" && value.trim() !== "";
@@ -4388,7 +4477,7 @@ function parseTriggers(text, path) {
   if (!Array.isArray(entries)) {
     throw configError(`triggers file must have a "triggers" array: ${path}`);
   }
-  const state = { seenCronIds: /* @__PURE__ */ new Set(), commentCount: 0 };
+  const state = { seenCronIds: /* @__PURE__ */ new Set(), commentCounts: {} };
   return entries.map((entry, index) => normalizeTrigger(entry, index, path, state));
 }
 function normalizeTrigger(entry, index, path, state) {
@@ -4406,8 +4495,8 @@ function normalizeTrigger(entry, index, path, state) {
   if (!ON_TYPES.has(on.type)) {
     throw configError(`${at}: on.type must be one of cron|label|comment|pull_request (got ${JSON.stringify(on.type)}): ${path}`);
   }
-  if (!RUN_KINDS.has(run.kind)) {
-    throw configError(`${at}: run.kind must be one of local|github (got ${JSON.stringify(run.kind)}): ${path}`);
+  if (!RUN_KINDS.includes(run.kind)) {
+    throw configError(`${at}: run.kind must be one of ${RUN_KINDS.join("|")} (got ${JSON.stringify(run.kind)}): ${path}`);
   }
   if (on.type === "cron") {
     if (run.kind !== "local") {
@@ -4415,8 +4504,8 @@ function normalizeTrigger(entry, index, path, state) {
     }
     return normalizeCron(on, run, index, path, state);
   }
-  if (run.kind !== "github") {
-    throw configError(`${at}: a ${on.type} trigger produces a github job; run.kind must be "github" (got ${JSON.stringify(run.kind)}): ${path}`);
+  if (!isForgeKind(run.kind)) {
+    throw configError(`${at}: a ${on.type} trigger is webhook-driven and produces a forge job; run.kind must be one of ${FORGE_KINDS.join("|")} (got ${JSON.stringify(run.kind)}): ${path}`);
   }
   if (on.type === "label") return normalizeLabel(on, run, index, path);
   if (on.type === "comment") return normalizeComment(on, run, index, path, state);
@@ -4455,11 +4544,43 @@ function normalizeCron(on, run, index, path, state) {
   if (!isNonEmptyString2(run.task)) {
     throw configError(`cron trigger "${id}": run.task must be a non-empty string: ${path}`);
   }
+  if (run.github !== void 0 && typeof run.github !== "boolean") {
+    throw configError(`cron trigger "${id}": run.github must be true or false when present: ${path}`);
+  }
+  const packages = validatePackagesFlag(run, `cron trigger "${id}"`, path);
+  const image = validateImageRef(run, `cron trigger "${id}"`, path);
+  const resume = validateResumeFlag(run, `cron trigger "${id}"`, path);
   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 }
+    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 }
   };
 }
+function validatePackagesFlag(run, at, path) {
+  if (run.packages !== void 0 && typeof run.packages !== "boolean") {
+    throw configError(`${at}: run.packages must be true or false when present: ${path}`);
+  }
+  return run.packages;
+}
+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}`);
+  }
+  return run.resume;
+}
+function validateImageRef(run, at, path) {
+  const image = run.image;
+  if (image === void 0) return void 0;
+  if (typeof image !== "string" || image.trim() === "") {
+    throw configError(`${at}: run.image must be a non-empty string when present: ${path}`);
+  }
+  if (image !== image.trim()) {
+    throw configError(`${at}: run.image must not have leading or trailing whitespace (got ${JSON.stringify(image)}): ${path}`);
+  }
+  if (image.startsWith("-")) {
+    throw configError(`${at}: run.image must not start with "-" -- it is passed as the image positional in the docker argv, where a leading dash parses as a flag (got ${JSON.stringify(image)}): ${path}`);
+  }
+  return image;
+}
 function validatePredicate(on, index, path, requirePositive) {
   const at = `trigger at index ${index}`;
   for (const key of ["any", "all", "none"]) {
@@ -4474,13 +4595,35 @@ function validatePredicate(on, index, path, requirePositive) {
   }
   return { any: on.any, all: on.all, none: on.none };
 }
+function validateRepository(run, onType, at, path) {
+  const needed = run.kind === "azure" && (onType === "label" || onType === "comment");
+  const raw = run.repository;
+  if (raw === void 0) {
+    if (!needed) return void 0;
+    throw configError(`${at}: an azure ${onType} trigger must set run.repository -- a work item belongs to a project, not a repository, so nothing in the delivery says where to clone: ${path}`);
+  }
+  if (!needed) {
+    throw configError(`${at}: run.repository is only meaningful on an azure label or comment trigger (a pull request names its own repository): ${path}`);
+  }
+  if (!isNonEmptyString2(raw) || raw !== raw.trim() || raw.includes("/")) {
+    throw configError(`${at}: run.repository must be a non-empty repository NAME within the project, with no slashes and no surrounding whitespace (got ${JSON.stringify(raw)}): ${path}`);
+  }
+  return raw;
+}
 function normalizeLabel(on, run, index, path) {
   const at = `trigger at index ${index}`;
   const predicate = validatePredicate(on, index, path, true);
   if (!isNonEmptyString2(run.flow)) {
     throw configError(`${at}: label trigger run.flow must be a non-empty string: ${path}`);
   }
-  return { on: { type: "label", any: predicate.any, all: predicate.all, none: predicate.none }, run: { kind: "github", flow: run.flow } };
+  const packages = validatePackagesFlag(run, at, path);
+  const image = validateImageRef(run, at, path);
+  const resume = validateResumeFlag(run, at, path);
+  const repository = validateRepository(run, "label", at, path);
+  return {
+    on: { type: "label", any: predicate.any, all: predicate.all, none: predicate.none },
+    run: { kind: run.kind, flow: run.flow, packages, image, resume, ...repository !== void 0 && { repository } }
+  };
 }
 function normalizeComment(on, run, index, path, state) {
   const at = `trigger at index ${index}`;
@@ -4490,11 +4633,18 @@ function normalizeComment(on, run, index, path, state) {
   if (!isNonEmptyString2(run.flow)) {
     throw configError(`${at}: comment trigger run.flow (the default flow) must be a non-empty string: ${path}`);
   }
-  state.commentCount += 1;
-  if (state.commentCount > 1) {
-    throw configError(`${at}: at most one comment trigger is allowed: ${path}`);
+  state.commentCounts[run.kind] = (state.commentCounts[run.kind] ?? 0) + 1;
+  if (state.commentCounts[run.kind] > 1) {
+    throw configError(`${at}: at most one ${run.kind} comment trigger is allowed: ${path}`);
   }
-  return { on: { type: "comment", phrase: on.phrase }, run: { kind: "github", flow: run.flow } };
+  const packages = validatePackagesFlag(run, at, path);
+  const image = validateImageRef(run, at, path);
+  const resume = validateResumeFlag(run, at, path);
+  const repository = validateRepository(run, "comment", at, path);
+  return {
+    on: { type: "comment", phrase: on.phrase },
+    run: { kind: run.kind, flow: run.flow, packages, image, resume, ...repository !== void 0 && { repository } }
+  };
 }
 function normalizePullRequest(on, run, index, path) {
   const at = `trigger at index ${index}`;
@@ -4502,19 +4652,29 @@ function normalizePullRequest(on, run, index, path) {
   if (!Array.isArray(actions) || actions.length === 0) {
     throw configError(`${at}: pull_request on.action must be a non-empty array: ${path}`);
   }
+  const allowed = PR_ACTIONS[run.kind];
+  const expected = [...allowed].join("|");
   for (const a of actions) {
-    if (!PR_ACTIONS.has(a)) {
-      throw configError(`${at}: pull_request on.action has an unsupported action ${JSON.stringify(a)} (expected labeled|opened|synchronize|reopened): ${path}`);
+    if (!allowed.has(a)) {
+      throw configError(`${at}: pull_request on.action has an unsupported ${run.kind} action ${JSON.stringify(a)} (expected ${expected}): ${path}`);
     }
   }
-  const requirePositive = actions.includes("labeled");
+  const labelAction = forgeSpec(run.kind)?.prLabelAction;
+  const requirePositive = typeof labelAction === "string" && actions.includes(labelAction);
+  if (run.kind === "azure" && (on.any !== void 0 || on.all !== void 0 || on.none !== void 0)) {
+    throw configError(`${at}: an azure pull_request trigger cannot carry a label predicate -- Azure DevOps attaches tags to work items, never to pull requests, so any/all/none could never match: ${path}`);
+  }
   const predicate = validatePredicate(on, index, path, requirePositive);
   if (!isNonEmptyString2(run.flow)) {
     throw configError(`${at}: pull_request trigger run.flow must be a non-empty string: ${path}`);
   }
+  const packages = validatePackagesFlag(run, at, path);
+  const image = validateImageRef(run, at, path);
+  const resume = validateResumeFlag(run, at, path);
+  validateRepository(run, "pull_request", at, path);
   return {
     on: { type: "pull_request", action: [...actions], any: predicate.any, all: predicate.all, none: predicate.none },
-    run: { kind: "github", flow: run.flow }
+    run: { kind: run.kind, flow: run.flow, packages, image, resume }
   };
 }
 
@@ -4690,7 +4850,7 @@ var QUEUE = "pi-jobs";
 function makeQueue(connection) {
   return new Queue(QUEUE, { connection });
 }
-async function enqueueLocalJob(queue, { folder, flow, task, provider, model, maxTurns, chainDepth, parentJobId, jobId, now = /* @__PURE__ */ new Date() }) {
+async function enqueueLocalJob(queue, { folder, flow, task, provider, model, maxTurns, image, chainDepth, parentJobId, jobId, now = /* @__PURE__ */ new Date() }) {
   const minute = now.toISOString().slice(0, 16);
   const id = jobId ?? localJobId({ folder, flow, task, minute });
   const data = {
@@ -4701,6 +4861,7 @@ async function enqueueLocalJob(queue, { folder, flow, task, provider, model, max
     provider,
     model,
     maxTurns,
+    ...image !== void 0 && { image },
     ...chainDepth !== void 0 && { chainDepth },
     ...parentJobId !== void 0 && { parentJobId }
   };
@@ -4755,15 +4916,111 @@ async function defaultGit(gitDir, args, { raw = false } = {}) {
 
 // ../worker/src/git-dirty.mjs
 import { execFileSync } from "node:child_process";
-function gitDirty(folder, { exec: exec2 = execFileSync } = {}) {
+function gitDirty(folder, { exec: exec3 = execFileSync } = {}) {
   try {
-    const out = exec2("git", ["-C", folder, "status", "--porcelain"], { encoding: "utf8" });
+    const out = exec3("git", ["-C", folder, "status", "--porcelain"], { encoding: "utf8" });
     return out.trim().length > 0;
   } catch {
     return null;
   }
 }
 
+// ../worker/src/packages.mjs
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+// ../worker/src/import-pi.mjs
+import { execFile as execFile2 } from "node:child_process";
+import { promisify as promisify2 } from "node:util";
+var ENTRY_NAME_RE = /^[a-z0-9](?:[a-z0-9_.-]{0,62}[a-z0-9])?$/i;
+var execFileAsync = promisify2(execFile2);
+
+// ../worker/src/docker-run.mjs
+var CONTAINER_GLOBAL_PI_DIR = "/opt/pi-global";
+var CONTAINER_SESSION_DIR = "/session";
+var CONTAINER_SESSION_FILE = `${CONTAINER_SESSION_DIR}/current.jsonl`;
+var ISOLATION_FLAGS = [
+  // The image must ALREADY be on this host. `docker run` defaults to --pull=missing, so an unknown name is
+  // a registry FETCH: a typo in the operator's image config would otherwise pull and execute a stranger's
+  // image under a name that looks like theirs. Every other flag here bounds what a chosen image may DO;
+  // this one bounds which image is chosen at all, which is why it leads. The same make-it-unreachable move
+  // PI_OFFLINE=1 makes one layer up, and it costs nothing the documented flow was using: the README's
+  // install step is an explicit `docker pull && docker tag`, and `pi-job:latest` is a local-only tag with
+  // no registry behind it. A readable diagnosis is the preflight's job (image-preflight.mjs); this is the
+  // part that cannot be raced.
+  "--pull=never",
+  "--rm",
+  // ephemeral: gone after the run
+  "--init",
+  // reap zombies (Chromium spawns many); node is PID 1 and does not reap
+  "--cap-drop=ALL",
+  // pi would otherwise inherit the launching user's capabilities
+  "--security-opt",
+  "no-new-privileges",
+  "--pids-limit=512",
+  // bound a fork bomb (UNVERIFIED figure; measured headroom ~4.5x, see spec)
+  "--shm-size=1g"
+  // Chromium OOMs on the default 64MB /dev/shm; NOT --ipc=host (shares host ns)
+];
+function buildDockerRunArgs({
+  image,
+  env,
+  jobDir,
+  workspace,
+  outboxDir,
+  sessionDir,
+  globalPiDir,
+  name,
+  memory = "4g",
+  cpus = "2",
+  extraFlags = []
+}) {
+  if (!image) throw new Error("docker run: image is required");
+  if (!name) throw new Error("docker run: container name is required");
+  if (!workspace) throw new Error("docker run: workspace mount is required");
+  const args = ["run", `--name=${name}`, ...ISOLATION_FLAGS, `--memory=${memory}`, `--cpus=${cpus}`, ...extraFlags];
+  for (const [k, v] of Object.entries(env ?? {})) {
+    if (v === void 0 || v === null) continue;
+    args.push("-e", `${k}=${v}`);
+  }
+  if (jobDir) args.push("-v", `${jobDir}:/job:ro`);
+  args.push("-v", `${workspace}:/workspace`);
+  if (outboxDir) args.push("-v", `${outboxDir}:/outbox`);
+  if (sessionDir) args.push("-v", `${sessionDir}:${CONTAINER_SESSION_DIR}`);
+  if (globalPiDir) args.push("-v", `${globalPiDir}:${CONTAINER_GLOBAL_PI_DIR}:ro`);
+  args.push(image);
+  return args;
+}
+
+// ../worker/src/packages.mjs
+var PACKAGES_SUBDIR = "packages";
+var STAGE_MANIFEST = "packages.json";
+var CONTAINER_PACKAGES_ROOT = `${CONTAINER_GLOBAL_PI_DIR}/${PACKAGES_SUBDIR}`;
+var MAX_DIR_LENGTH = 64;
+function isNonEmptyString4(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+function readStageManifest({ globalPiDir, readFile = readFileSync, fileExists = existsSync } = {}) {
+  if (!globalPiDir) return null;
+  const path = join(globalPiDir, PACKAGES_SUBDIR, STAGE_MANIFEST);
+  try {
+    if (!fileExists(path)) return null;
+    const parsed = JSON.parse(readFile(path, "utf8"));
+    if (parsed === null || typeof parsed !== "object" || !Array.isArray(parsed.packages)) return null;
+    const packages = [];
+    for (const entry of parsed.packages) {
+      if (entry === null || typeof entry !== "object") return null;
+      const { name, version, dir } = entry;
+      if (!isNonEmptyString4(name) || !isNonEmptyString4(version) || !isNonEmptyString4(dir)) return null;
+      if (!ENTRY_NAME_RE.test(dir) || dir.length > MAX_DIR_LENGTH) return null;
+      packages.push({ name, version, dir });
+    }
+    return { stagedAt: typeof parsed.stagedAt === "string" ? parsed.stagedAt : null, packages };
+  } catch {
+    return null;
+  }
+}
+
 // src/read-model.mjs
 function resolvePaths(env = process.env) {
   return {
@@ -4772,7 +5029,18 @@ function resolvePaths(env = process.env) {
     settingsFile: settingsFilePath(env),
     triggersPath: env.PI_TRIGGERS_FILE ?? "deploy/triggers.json",
     pauseWindowsPath: env.PI_PAUSE_WINDOWS_FILE ?? "deploy/pause-windows.json",
+    // The operator's global pi overlay dir (REQ-GLOBAL-PI-OVERLAY), where the staged third-party pi
+    // packages live under `packages/`. `|| null` so unset AND empty both read as "no overlay" -- the
+    // normal deployment, in which no trigger can arm any package.
+    globalPiDir: env.PI_GLOBAL_PI_DIR || null,
     captureJobLogs: env.PI_CAPTURE_JOB_LOGS === "1",
+    // REQ-RESURRECTABLE-SANDBOX: where finished runs' directories are retained, and for how long. Read
+    // from env for the same reason as everything above -- never loadConfig. The `0` here means retention
+    // OFF (the panel then says so rather than offering a key that always refuses), which is the opposite
+    // of the log/session sentinels; worker/src/config.mjs carries the full reasoning.
+    sandboxDir: env.PI_SANDBOX_DIR || defaultSandboxDir(env),
+    sandboxRetentionHours: parseNonNegInt(env.PI_SANDBOX_RETENTION_HOURS, 24),
+    sandboxIdleMinutes: parseNonNegInt(env.PI_SANDBOX_IDLE_MINUTES, 30),
     // 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
     // private to the worker's config, so the same shapes are reimplemented here. Default roots [] fails
@@ -4820,9 +5088,9 @@ async function setQueuePaused({ url, paused, makeQueueFn = makeQueue, parseConne
   }
 }
 var DISPATCH_RUN_TTL_SECONDS = 2 * 60 * 60;
-function revParseHead(folder, { exec: exec2 = execFileSync2 } = {}) {
+function revParseHead(folder, { exec: exec3 = execFileSync2 } = {}) {
   try {
-    const out = exec2("git", ["-C", folder, "rev-parse", "HEAD"], { encoding: "utf8" });
+    const out = exec3("git", ["-C", folder, "rev-parse", "HEAD"], { encoding: "utf8" });
     const sha = out.trim();
     return sha.length > 0 ? sha : null;
   } catch {
@@ -5058,19 +5326,19 @@ function listRuns({ logsDir, limit = 10, fs = nodeFs2 }) {
   const records = [];
   for (const name of names) {
     if (!name.endsWith(".json")) continue;
-    const record = readJsonFile(join(logsDir, name), fs);
+    const record = readJsonFile(join2(logsDir, name), fs);
     if (record && typeof record === "object") records.push(record);
   }
   records.sort(byEndedAtDesc);
   return records.slice(0, cap);
 }
 function readRun({ logsDir, jobId, fs = nodeFs2 }) {
-  return readJsonFile(join(logsDir, `${sanitizeJobId(jobId)}.json`), fs);
+  return readJsonFile(join2(logsDir, `${sanitizeJobId(jobId)}.json`), fs);
 }
 function readLogTail({ logsDir, jobId, lines = 200, fs = nodeFs2 }) {
   let text;
   try {
-    text = fs.readFileSync(join(logsDir, `${sanitizeJobId(jobId)}.log`), "utf8");
+    text = fs.readFileSync(join2(logsDir, `${sanitizeJobId(jobId)}.log`), "utf8");
   } catch {
     return { missing: true };
   }
@@ -5114,6 +5382,10 @@ function normalizeTriggerForDisplay(entry) {
   if (on === null || typeof on !== "object") return null;
   const run = entry.run !== null && typeof entry.run === "object" ? entry.run : {};
   const flow = typeof run.flow === "string" ? run.flow : null;
+  const packages = run.packages !== false;
+  const image = typeof run.image === "string" && run.image.trim() !== "" ? run.image : null;
+  const resume = run.resume === true;
+  const forge = typeof run.kind === "string" && run.kind.trim() !== "" ? run.kind : null;
   switch (on.type) {
     case "cron":
       return {
@@ -5124,12 +5396,15 @@ function normalizeTriggerForDisplay(entry) {
         flow,
         // Optional per-cron model override (passthrough into job.data); null when the entry resolves the
         // deployment default. Surfaced so the drill-in shows which schedules pin their own model.
-        model: typeof run.model === "string" ? run.model : null
+        model: typeof run.model === "string" ? run.model : null,
+        packages,
+        image,
+        resume
       };
     case "label":
-      return { type: "label", any: normalizeSelector(on.any), all: normalizeSelector(on.all), none: normalizeSelector(on.none), flow };
+      return { type: "label", any: normalizeSelector(on.any), all: normalizeSelector(on.all), none: normalizeSelector(on.none), flow, packages, image, resume, forge };
     case "comment":
-      return { type: "comment", phrase: typeof on.phrase === "string" ? on.phrase : null, flow };
+      return { type: "comment", phrase: typeof on.phrase === "string" ? on.phrase : null, flow, packages, image, resume, forge };
     case "pull_request":
       return {
         type: "pull_request",
@@ -5137,7 +5412,11 @@ function normalizeTriggerForDisplay(entry) {
         any: normalizeSelector(on.any),
         all: normalizeSelector(on.all),
         none: normalizeSelector(on.none),
-        flow
+        flow,
+        packages,
+        image,
+        resume,
+        forge
       };
     default:
       return null;
@@ -5147,6 +5426,28 @@ function normalizeSelector(value) {
   if (!Array.isArray(value)) return [];
   return value.filter((member) => typeof member === "string");
 }
+function readStagedPackages({ globalPiDir, fs = nodeFs2, readManifest: readManifest2 = readStageManifest } = {}) {
+  const empty = { stagedAt: null, packages: [] };
+  if (typeof globalPiDir !== "string" || globalPiDir === "") return empty;
+  let manifest;
+  try {
+    manifest = readManifest2({
+      globalPiDir,
+      readFile: (path) => fs.readFileSync(path, "utf8"),
+      fileExists: (path) => fs.existsSync(path)
+    });
+  } catch {
+    return empty;
+  }
+  const entries = Array.isArray(manifest?.packages) ? manifest.packages : [];
+  return {
+    stagedAt: typeof manifest?.stagedAt === "string" ? manifest.stagedAt : null,
+    packages: entries.filter((p) => p && typeof p.name === "string").map(nameAtVersion)
+  };
+}
+function nameAtVersion(pkg) {
+  return typeof pkg.version === "string" && pkg.version !== "" ? `${pkg.name}@${pkg.version}` : pkg.name;
+}
 function listRunIds({ logsDir, fs = nodeFs2 }) {
   let names;
   try {
@@ -5186,6 +5487,75 @@ function clampLines(lines) {
   return Math.min(2e3, Math.max(1, n));
 }
 
+// ../worker/src/sandbox.mjs
+import { execFile as execFile3, spawn } from "node:child_process";
+import { existsSync as existsSync2 } from "node:fs";
+import { promisify as promisify3 } from "node:util";
+
+// ../worker/src/sandbox-store.mjs
+import { lstatSync, mkdirSync, readFileSync as readFileSync2, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { isAbsolute, join as join3, relative } from "node:path";
+var SANDBOX_MANIFEST = "manifest.json";
+var defaultFs = { lstatSync, mkdirSync, readFileSync: readFileSync2, readdirSync, renameSync, rmSync, writeFileSync };
+function readManifest({ sandboxDir, jobId, fs = defaultFs }) {
+  if (!sandboxDir || jobId === void 0 || jobId === null) return null;
+  const dir = join3(sandboxDir, sanitizeJobId(jobId));
+  try {
+    const manifest = JSON.parse(fs.readFileSync(join3(dir, SANDBOX_MANIFEST), "utf8"));
+    return { ...manifest, dir };
+  } catch {
+    return null;
+  }
+}
+
+// ../worker/src/sandbox.mjs
+var exec2 = promisify3(execFile3);
+var SANDBOX_NAME_PREFIX = "pi-sandbox-";
+function sandboxContainerName(jobId) {
+  return `${SANDBOX_NAME_PREFIX}${sanitizeJobId(jobId)}`;
+}
+function buildSandboxRunArgs({ image, name, workspace, jobDir, publish = [], term, idleSeconds = 0 }) {
+  return buildDockerRunArgs({
+    image,
+    name,
+    workspace,
+    jobDir,
+    // The ONLY two variables, and neither is a credential. TERM so the shell renders; TMOUT so a
+    // forgotten session closes itself. `buildDockerRunArgs` skips undefined, so an unset TERM or a
+    // disabled idle timeout emits nothing rather than an empty string.
+    env: {
+      TERM: term || void 0,
+      TMOUT: idleSeconds > 0 ? String(idleSeconds) : void 0
+    },
+    // Ahead of the env and the mounts, and well ahead of the image, which buildDockerRunArgs keeps as
+    // the final positional. `--entrypoint` also clears the image's CMD; this repo's Dockerfile sets
+    // none, so `bash` runs bare and `-it` makes it interactive, in the baked WORKDIR as the baked
+    // non-root USER.
+    extraFlags: ["-i", "-t", "--entrypoint", "bash", ...publish]
+  });
+}
+function resolveSandbox({ jobId, sandboxDir, retentionHours, publish = [], fs, fileExists = existsSync2 }) {
+  if (!jobId) return { refused: "no-job-id", message: "a job id is required (see `pi-dispatch sandbox --list`)" };
+  const manifest = readManifest({ sandboxDir, jobId, ...fs ? { fs } : {} });
+  if (!manifest) {
+    return retentionHours === 0 ? { refused: "retention-off", message: "workspace retention is off \u2014 set PI_SANDBOX_RETENTION_HOURS to a positive number to make future runs resurrectable" } : { refused: "absent", message: `no retained workspace for ${jobId} \u2014 it was swept after ${retentionHours}h, or the run predates retention (\`pi-dispatch sandbox --list\` shows what is left)` };
+  }
+  if (!manifest.image) {
+    return { refused: "no-image", message: `the manifest for ${jobId} names no image, so the sandbox cannot reproduce the run` };
+  }
+  if (!manifest.workspace || !fileExists(manifest.workspace)) {
+    return { refused: "workspace-gone", message: `the workspace for ${jobId} is no longer at ${manifest.workspace} \u2014 a local folder that moved cannot be re-opened` };
+  }
+  return { manifest, name: sandboxContainerName(jobId), publish };
+}
+function launchSandbox({ args, spawnFn = spawn }) {
+  return new Promise((resolve) => {
+    const child = spawnFn("docker", args, { stdio: "inherit" });
+    child.on("error", (err) => resolve({ code: null, error: err }));
+    child.on("close", (code) => resolve({ code }));
+  });
+}
+
 // src/render.mjs
 var SETTINGS_KEYS = ["model", "provider", "maxTurns", "dailyCap", "weeklyCap", "monthlyCap", "maxTokens", "dailyTokenCap", "concurrency", "softHoldPct"];
 var BUDGET_WINDOWS = [
@@ -5279,17 +5649,21 @@ function renderTriggers({ schedulers, triggers } = {}) {
 }
 function triggerLine(t) {
   const flow = t?.flow ?? "-";
+  const forge = t?.forge && t.forge !== "github" ? `  [${t.forge}]` : "";
+  const pkgs = t?.packages === true ? "  [packages]" : "";
+  const img = t?.image ? `  [image ${t.image}]` : "";
+  const res = t?.resume === true ? "  [resume]" : "";
   switch (t?.type) {
     case "cron":
-      return `cron  ${t.id ?? "-"}  ${t.pattern ?? "-"} \u2192 ${t.folder ?? "-"}/${flow}`;
+      return `cron  ${t.id ?? "-"}  ${t.pattern ?? "-"} \u2192 ${t.folder ?? "-"}/${flow}${forge}${pkgs}${img}${res}`;
     case "label":
-      return `label  ${ruleClauses(t) || "(no selector)"} \u2192 ${flow}`;
+      return `label  ${ruleClauses(t) || "(no selector)"} \u2192 ${flow}${forge}${pkgs}${img}${res}`;
     case "comment":
-      return `comment  "${t.phrase ?? "-"}" \u2192 ${flow}`;
+      return `comment  "${t.phrase ?? "-"}" \u2192 ${flow}${forge}${pkgs}${img}${res}`;
     case "pull_request": {
       const clauses = ruleClauses(t);
       const action = `action[${(t.action ?? []).join(",")}]`;
-      return `pull_request  ${action}${clauses ? ` ${clauses}` : ""} \u2192 ${flow}`;
+      return `pull_request  ${action}${clauses ? ` ${clauses}` : ""} \u2192 ${flow}${forge}${pkgs}${img}${res}`;
     }
     default:
       return "(unknown trigger)";
@@ -5571,6 +5945,11 @@ function createDashboardDeps(paths) {
         settings: readSettingsView({ settingsFile: paths.settingsFile }),
         triggers: readTriggers({ triggersPath: paths.triggersPath }),
         pauseWindows: readPauseWindows({ pauseWindowsPath: paths.pauseWindowsPath }),
+        // The operator's staged third-party pi packages (REQ-GLOBAL-PI-OVERLAY), for the armed triggers'
+        // trust model. Like the four reads above it is a plain file read whose fs access lives entirely in
+        // read-model.mjs -- this module never touches the filesystem -- and it degrades to a safe empty
+        // shape rather than throwing, so a broken overlay cannot take the whole snapshot down.
+        stagedPackages: readStagedPackages({ globalPiDir: paths.globalPiDir }),
         // 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
@@ -5610,6 +5989,7 @@ function makeDashboard({
   let view = "LIST";
   let selected = 0;
   let detailRun = null;
+  let detailSandbox = null;
   let detailTrigger = null;
   let tailJobId = null;
   let tail = null;
@@ -5668,7 +6048,9 @@ function makeDashboard({
         tailJobId,
         tail,
         tailTop,
-        tailAvailable: typeof deps?.tailLog === "function"
+        tailAvailable: typeof deps?.tailLog === "function",
+        detailSandbox,
+        sandboxAvailable: typeof deps?.launchSandbox === "function"
       }, styler);
     },
     invalidate() {
@@ -5677,7 +6059,24 @@ function makeDashboard({
       if (view === "RUN_DETAIL") {
         if (matchesKey(data, "escape")) {
           view = "LIST";
+          detailSandbox = null;
           tui?.requestRender?.();
+          return;
+        }
+        if (data === "b" || data === "B") {
+          if (typeof deps?.launchSandbox !== "function" || !detailRun?.jobId) return;
+          if (detailSandbox && detailSandbox.retained === false) return;
+          void (async () => {
+            tui?.stop?.();
+            try {
+              await deps.launchSandbox({ jobId: detailRun.jobId });
+            } catch {
+            } finally {
+              tui?.start?.();
+              tui?.requestRender?.(true);
+            }
+          })();
+          return;
         }
         return;
       }
@@ -5743,6 +6142,7 @@ function makeDashboard({
           void refresh();
         } else {
           detailRun = row.record;
+          detailSandbox = typeof deps?.sandboxInfo === "function" ? deps.sandboxInfo({ jobId: row.record?.jobId }) : null;
           view = "RUN_DETAIL";
           tui?.requestRender?.();
         }
@@ -5803,7 +6203,7 @@ function budgetMeters(budget, settings2, width) {
   return out;
 }
 function renderPanel(snapshot, width, state, styler) {
-  const { view, selected, detailRun, detailTrigger, tailJobId, tail, tailTop, tailAvailable } = state;
+  const { view, selected, detailRun, detailTrigger, tailJobId, tail, tailTop, tailAvailable, detailSandbox, sandboxAvailable } = state;
   const framed = Number.isFinite(width) && Math.trunc(width) >= MIN_WIDTH2;
   const inner = Math.trunc(width) - 4;
   const title = "pi-dispatch";
@@ -5812,7 +6212,7 @@ function renderPanel(snapshot, width, state, styler) {
     const detailTitle = `trigger \xB7 ${t?.type ?? "?"}`;
     const dw = framed ? Math.min(Math.trunc(width), DRILL_WIDTH) : Math.trunc(width);
     const sched = cronSchedInfo(t, snapshot);
-    const lines = renderTriggerDetail(t, framed ? dw - 4 : 24, styler, sched);
+    const lines = renderTriggerDetail(t, framed ? dw - 4 : 24, styler, sched, snapshot?.stagedPackages);
     if (!framed) return [detailTitle, "", ...lines.map((l) => styler.stripAnsi(l)), "", "e edit \xB7 x delete \xB7 esc back"];
     const boxed = frame(styler, { title: detailTitle, width: dw, lines, footer: triggerDetailHints(dw - 4, styler) });
     return centerBlock(boxed, Math.trunc(width), dw);
@@ -5821,9 +6221,10 @@ function renderPanel(snapshot, width, state, styler) {
     const detailTitle = `run ${detailRun?.jobId ?? "-"}`;
     const dw = framed ? Math.min(Math.trunc(width), DRILL_WIDTH) : Math.trunc(width);
     const allRuns = Array.isArray(snapshot?.runs) ? snapshot.runs : [];
-    const lines = renderRunDetail(detailRun, framed ? dw - 4 : 24, styler, allRuns);
-    if (!framed) return [detailTitle, "", ...lines.map((l) => styler.stripAnsi(l)), "", "esc back"];
-    const boxed = frame(styler, { title: detailTitle, width: dw, lines, footer: runDetailHints(dw - 4, styler) });
+    const canOpen = Boolean(sandboxAvailable && detailSandbox?.retained);
+    const lines = renderRunDetail(detailRun, framed ? dw - 4 : 24, styler, allRuns, detailSandbox);
+    if (!framed) return [detailTitle, "", ...lines.map((l) => styler.stripAnsi(l)), "", canOpen ? "b sandbox \xB7 esc back" : "esc back"];
+    const boxed = frame(styler, { title: detailTitle, width: dw, lines, footer: runDetailHints(dw - 4, styler, canOpen) });
     return centerBlock(boxed, Math.trunc(width), dw);
   }
   if (view === "LIVE_TAIL") {
@@ -5984,7 +6385,10 @@ function triggerRow(t, sel, inner, styler) {
   const cursor = sel ? styler.fg("accent", "\u203A") : " ";
   const kind = t?.type ?? "?";
   const badge = styler.cell(kind, KIND_WIDTH, { color: KIND_COLOR[kind] ?? "muted" });
-  return fitLine(`${cursor} ${badge} ${matchColored(t, styler)} ${targetColored(t, styler)}`, inner, styler);
+  const pkgs = t?.packages === true ? " " + styler.fg("warning", "[packages]") : "";
+  const img = t?.image ? " " + styler.fg("accent", `[${t.image}]`) : "";
+  const res = t?.resume === true ? " " + styler.fg("warning", "[resume]") : "";
+  return fitLine(`${cursor} ${badge} ${matchColored(t, styler)} ${targetColored(t, styler)}${pkgs}${img}${res}`, inner, styler);
 }
 function matchColored(t, styler) {
   switch (t?.type) {
@@ -6013,7 +6417,7 @@ function targetColored(t, styler) {
     const folderPart = base ? styler.fg("muted", base) + styler.fg("dim", "/") : "";
     return `${arrow} ${styler.fg("success", "local")} ${folderPart}${flow}`;
   }
-  return `${arrow} ${styler.fg("accent", "github")} ${flow}`;
+  return `${arrow} ${styler.fg("accent", t?.forge ?? "github")} ${flow}`;
 }
 function pauseLines(pauseWindows, inner, styler) {
   const lines = [];
@@ -6084,7 +6488,7 @@ function settingsLines(settings2, inner, styler) {
   const l2 = [kv("dailyCap", o.dailyCap), tk("dailyTokenCap", o.dailyTokenCap), kv("concurrency", o.concurrency), styler.fg("muted", "softHold") + " " + styler.fg("text", pctVal)].join(gap);
   return [fitLine(l1, inner, styler), fitLine(l2, inner, styler)];
 }
-function renderTriggerDetail(t, inner, styler, sched = null) {
+function renderTriggerDetail(t, inner, styler, sched = null, staged = null) {
   if (!t) return [styler.cell("(no trigger)", inner, { color: "dim" })];
   const out = [];
   const kv = (k, v, color = "text") => fitLine(styler.cell(k, 12, { color: "muted" }) + " " + styler.fg(color, v), inner, styler);
@@ -6122,38 +6526,72 @@ function renderTriggerDetail(t, inner, styler, sched = null) {
     out.push(kv("folder", `${t.folder ?? "-"}`, "success"));
     out.push(kv("model", t.model ?? "deployment default", t.model ? "accent" : "dim"));
   } else {
-    out.push(kv("job", "github", "accent"));
-    out.push(kv("target", "the triggering repo#issue / PR", "accent"));
+    out.push(kv("job", t.forge ?? "-", "accent"));
+    out.push(kv("target", forgeTargetLabel(t?.forge), "accent"));
     out.push(kv("model", "deployment default", "dim"));
   }
+  out.push(kv("image", t.image ?? "deployment default", t.image ? "accent" : "dim"));
+  out.push(kv("resume", t.resume === true ? "continues the previous session" : "cold start", t.resume === true ? "warning" : "dim"));
   blank();
   section("trust model");
   for (const line of trustModel(t)) out.push(fitLine(styler.fg("border", "\xB7 ") + styler.fg("text", line), inner, styler));
+  if (t.packages === true) {
+    const loads = (text) => out.push(fitLine(styler.fg("border", "\xB7 ") + styler.fg("warning", text), inner, styler));
+    loads(`packages loaded \xB7 ${stagedNames(staged)}`);
+    loads("third-party code on adversarial input, open network egress");
+  }
+  if (t.resume === true) {
+    const keeps = (text) => out.push(fitLine(styler.fg("border", "\xB7 ") + styler.fg("warning", text), inner, styler));
+    keeps("persists the agent transcript to PI_SESSIONS_DIR");
+    keeps("issue text, file contents, tool output, the agent's own reasoning");
+    keeps("replayed into the next job on the same branch; forks never resume");
+  }
   return out;
 }
+function stagedNames(staged) {
+  const list = Array.isArray(staged?.packages) ? staged.packages : [];
+  return list.length > 0 ? list.join(" \xB7 ") : "(none staged in the overlay)";
+}
+function forgeTargetLabel(forge) {
+  if (forge === "gitlab") return "the triggering project#issue / !MR";
+  if (forge === "azure") return "the triggering project/repo#work-item / !PR";
+  return "the triggering repo#issue / PR";
+}
 function trustModel(t) {
-  switch (t?.type) {
-    case "cron":
+  if (t?.type === "cron") {
+    return [
+      "authorized by the operator's triggers file, at boot",
+      "dedup by time \u2014 deterministic repeat:<id>:<millis> id",
+      "lives in the worker \xB7 task is operator-authored"
+    ];
+  }
+  const subject = t?.type === "comment" ? "adversarial comment text" : "adversarial issue/PR text";
+  const where = `lives in the receiver \xB7 task is ${subject}`;
+  switch (t?.forge) {
+    case "gitlab":
       return [
-        "authorized by the operator's triggers file, at boot",
-        "dedup by time \u2014 deterministic repeat:<id>:<millis> id",
-        "lives in the worker \xB7 task is operator-authored"
+        "authorized by the actor's resolved project access level (>= Developer) \u2014 a label is NOT approval here",
+        "HMAC over the body (19.0+) or a bare X-Gitlab-Token \xB7 dedup by webhook-id",
+        where
       ];
-    case "label":
-    case "pull_request":
+    case "forgejo":
       return [
-        "authorized by a collaborator's label + HMAC webhook + author gate",
-        "dedup by X-GitHub-Delivery GUID (redelivery-safe)",
-        "lives in the receiver \xB7 task is adversarial issue/PR text"
+        "authorized by the actor's resolved repository permission (admin|write), on every trigger type",
+        "HMAC over the body (GitHub-compatible) \xB7 dedup by X-GitHub-Delivery GUID",
+        where
       ];
-    case "comment":
+    case "azure":
       return [
-        "authorized by a collaborator comment (author_association) + HMAC",
-        "dedup by X-GitHub-Delivery GUID",
-        "lives in the receiver \xB7 task is adversarial comment text"
+        "authorized by the actor's resolved project membership \u2014 work items name the actor only by email",
+        "NO HMAC: a shared secret that covers no bytes \xB7 dedup by the payload's own id (OQ-015)",
+        where
       ];
     default:
-      return [];
+      return [
+        t?.type === "comment" ? "authorized by a collaborator comment (author_association) + HMAC" : "authorized by a collaborator's label + HMAC webhook + author gate",
+        "dedup by X-GitHub-Delivery GUID (redelivery-safe)",
+        where
+      ];
   }
 }
 function triggerDetailHints(inner, styler) {
@@ -6225,7 +6663,7 @@ function renderLiveTail({ snapshot, framed, width, tailJobId, tail, tailTop, tai
   if (!framed) return [boxTitle, "", ...lines, "", footer];
   return box({ title: boxTitle, footer, width, sections: [{ lines }] });
 }
-function renderRunDetail(record, inner, styler, allRuns = []) {
+function renderRunDetail(record, inner, styler, allRuns = [], sandbox = null) {
   const r = record ?? {};
   const show = (v) => v === null || v === void 0 ? "-" : String(v);
   const out = [];
@@ -6248,12 +6686,20 @@ function renderRunDetail(record, inner, styler, allRuns = []) {
   out.push(kv("turns", turnBits.join(" \xB7 ")));
   const cost = typeof r.tokens?.cost === "number" ? ` \xB7 $${r.tokens.cost.toFixed(4)}` : "";
   out.push(kv("tokens", `${show(r.tokens?.total)}${cost}`));
+  const otherTotal = r.tokens?.otherTotal;
+  if (typeof otherTotal === "number" && Number.isFinite(otherTotal) && otherTotal > 0) {
+    out.push(kv("of which", `subagents: ${otherTotal}`, "dim"));
+  }
   const children = (Array.isArray(allRuns) ? allRuns : []).filter((x) => x?.parentJobId && r.jobId && x.parentJobId === r.jobId);
   const chainBits = [r.parentJobId ? `child of ${r.parentJobId}` : "root"];
   if (r.chainDepth !== null && r.chainDepth !== void 0) chainBits.push(`depth ${r.chainDepth}`);
   if (children.length > 0) chainBits.push(`spawned ${children.length} \u2192 ${children.map((c) => c.jobId).join(", ")}`);
   if (r.chainRefused) chainBits.push(`${r.chainRefused} refused`);
   out.push(kv("chain", chainBits.join(" \xB7 ")));
+  if (sandbox) {
+    const state = sandbox.retained ? `${sandbox.running ? "running" : "retained"}${sandbox.expiresIn ? ` \xB7 ${sandbox.expiresIn} left` : ""}` : sandbox.reason ?? "swept";
+    out.push(kv("sandbox", state, sandbox.retained ? "success" : "dim"));
+  }
   out.push(styler.cell("", inner));
   out.push(styler.divider("post-mortem", null, inner));
   out.push(fitLine(styler.fg("dim", "container torn down at job end \xB7 stored PII-free fields + optional raw-log overlay only"), inner, styler));
@@ -6291,8 +6737,10 @@ function formatDuration(ms) {
   const h = Math.floor(m / 60);
   return `${h}h ${m % 60}m`;
 }
-function runDetailHints(inner, styler) {
-  return fitLine(styler.fg("accent", "esc") + " " + styler.fg("dim", "back"), inner, styler);
+function runDetailHints(inner, styler, canOpen = false) {
+  const k = (key, label) => styler.fg("accent", key) + " " + styler.fg("dim", label);
+  const bits = canOpen ? [k("b", "sandbox"), k("esc", "back")] : [k("esc", "back")];
+  return fitLine(bits.join(styler.fg("dim", "  \xB7  ")), inner, styler);
 }
 
 // src/index.ts
@@ -6465,11 +6913,12 @@ function registerTools(pi) {
   pi.registerTool({
     name: "dispatch_trigger_add",
     label: "pi-dispatch add trigger",
-    description: "Adds a trigger to triggers.json and applies it live. The operator MUST approve a confirm dialog showing the entry; with no interactive operator it is refused. `flow` is the .pi/skills/<name> skill the job runs (its SKILL.md is the agent's instructions). `kind` = cron|label|comment|pull_request. cron (local) needs id, pattern, `folder` (absolute host path the job runs in), `flow`, and `task` (the prompt text handed to the agent), and may set optional model/provider/maxTurns for that schedule (omit = deployment default). label needs labels[]+flow; comment needs phrase+flow; pull_request needs action[] (+ optional labels[]) + flow. For github triggers the repo and the task come from the triggering issue/PR event \u2014 set only the match + flow \u2014 and they run under the deployment default model.",
+    description: "Adds a trigger to triggers.json and applies it live. The operator MUST approve a confirm dialog showing the entry; with no interactive operator it is refused. `flow` is the .pi/skills/<name> skill the job runs (its SKILL.md is the agent's instructions). `kind` = cron|label|comment|pull_request. cron (local) needs id, pattern, `folder` (absolute host path the job runs in), `flow`, and `task` (the prompt text handed to the agent), and may set optional model/provider/maxTurns for that schedule (omit = deployment default). label needs labels[]+flow; comment needs phrase+flow; pull_request needs action[] (+ optional labels[]) + flow. Webhook triggers take an optional `forge` = github (default) | gitlab, which also decides which action words pull_request accepts: github is labeled|opened|synchronize|reopened, gitlab is open|update|reopen|approved. For webhook triggers the repo and the task come from the triggering issue/PR event \u2014 set only the match + flow \u2014 and they run under the deployment default model.",
     executionMode: "sequential",
     parameters: typebox_exports.Object({
       kind: typebox_exports.String(),
       flow: typebox_exports.String(),
+      forge: typebox_exports.Optional(typebox_exports.String()),
       id: typebox_exports.Optional(typebox_exports.String()),
       pattern: typebox_exports.Optional(typebox_exports.String()),
       folder: typebox_exports.Optional(typebox_exports.String()),
@@ -6674,6 +7123,13 @@ function triggerList(paths) {
   const t = readTriggers({ triggersPath: paths.triggersPath });
   return Array.isArray(t?.triggers) ? t.triggers : [];
 }
+var FORGE_PROMPT = "forge \u2014 github, gitlab, forgejo or azure";
+var PR_ACTION_VOCAB = {
+  github: { hint: "labeled opened synchronize reopened", dflt: "labeled" },
+  gitlab: { hint: "open update reopen approved", dflt: "update" },
+  forgejo: { hint: "label_updated opened synchronized reopened", dflt: "label_updated" },
+  azure: { hint: "created updated", dflt: "updated" }
+};
 function buildTriggerEntry(kind, f) {
   if (kind === "cron") {
     const run = { kind: "local", folder: f.folder, flow: f.flow, task: f.task };
@@ -6685,13 +7141,16 @@ function buildTriggerEntry(kind, f) {
     if (maxTurns !== void 0) run.maxTurns = maxTurns;
     return { on: { type: "cron", id: f.id, pattern: f.pattern }, run };
   }
-  if (kind === "label") return { on: { type: "label", any: asWords(f.labels ?? f.any) }, run: { kind: "github", flow: f.flow } };
-  if (kind === "comment") return { on: { type: "comment", phrase: f.phrase }, run: { kind: "github", flow: f.flow } };
+  const forge = optStr(f.forge) ?? "github";
+  const repository = optStr(f.repository);
+  const forgeRun = (rest) => ({ kind: forge, ...rest, ...repository ? { repository } : {} });
+  if (kind === "label") return { on: { type: "label", any: asWords(f.labels ?? f.any) }, run: forgeRun({ flow: f.flow }) };
+  if (kind === "comment") return { on: { type: "comment", phrase: f.phrase }, run: forgeRun({ flow: f.flow }) };
   if (kind === "pull_request") {
     const on = { type: "pull_request", action: asWords(f.action) };
     const any = asWords(f.labels ?? f.any);
     if (any.length > 0) on.any = any;
-    return { on, run: { kind: "github", flow: f.flow } };
+    return { on, run: { kind: forge, flow: f.flow } };
   }
   return null;
 }
@@ -6825,7 +7284,13 @@ async function openDashboard(paths, ctx, notify) {
     deps: {
       ...createDashboardDeps(paths),
       // log read stays here; overlay-only, returns readLogTail's result verbatim
-      tailLog: ({ jobId, lines }) => readLogTail({ logsDir: paths.logsDir, jobId, lines })
+      tailLog: ({ jobId, lines }) => readLogTail({ logsDir: paths.logsDir, jobId, lines }),
+      // REQ-RESURRECTABLE-SANDBOX, both seams. The fs read and the spawn live HERE for the same reason
+      // tailLog does: dashboard.ts renders and holds the tui, and touches no filesystem and no child
+      // process of its own. It brackets the launch with tui.stop()/tui.start(); this side only builds
+      // the argv and runs it attached to the terminal.
+      sandboxInfo: ({ jobId }) => readSandboxInfo(paths, jobId),
+      launchSandbox: ({ jobId }) => openSandboxSession(paths, jobId)
     }
   });
   const opts = { overlay: true, overlayOptions: { width: "75%", maxHeight: "90%", anchor: "center" } };
@@ -6835,6 +7300,54 @@ async function openDashboard(paths, ctx, notify) {
     await handleDashboardAction(result, paths, ctx);
   }
 }
+function readSandboxInfo(paths, jobId) {
+  if (!jobId) return null;
+  if (!paths?.sandboxRetentionHours) return { retained: false, reason: "retention off" };
+  const manifest = readManifest({ sandboxDir: paths.sandboxDir, jobId });
+  if (!manifest) return { retained: false, reason: "swept" };
+  const keepUntil = Date.parse(manifest.keepUntil ?? "");
+  const createdAt = Date.parse(manifest.createdAt ?? "");
+  const until = Number.isFinite(keepUntil) ? keepUntil : createdAt + paths.sandboxRetentionHours * 36e5;
+  if (!Number.isFinite(until)) return { retained: true };
+  const hours = Math.max(0, Math.round((until - Date.now()) / 36e5));
+  return { retained: true, pinned: Number.isFinite(keepUntil), expiresIn: hours < 48 ? `${hours}h` : `${Math.round(hours / 24)}d` };
+}
+async function openSandboxSession(paths, jobId) {
+  const resolved = resolveSandbox({
+    jobId,
+    sandboxDir: paths.sandboxDir,
+    retentionHours: paths.sandboxRetentionHours
+  });
+  if (resolved.refused) {
+    process.stdout.write(`
+cannot open a sandbox for ${jobId}: ${resolved.message}
+`);
+    await pauseForMessage();
+    return;
+  }
+  const args = buildSandboxRunArgs({
+    image: resolved.manifest.image,
+    name: resolved.name,
+    workspace: resolved.manifest.workspace,
+    jobDir: resolved.manifest.dir,
+    term: process.env.TERM,
+    idleSeconds: (paths.sandboxIdleMinutes ?? 0) * 60
+  });
+  process.stdout.write(`
+opening ${sandboxContainerName(jobId)} \u2014 image ${resolved.manifest.image}
+`);
+  process.stdout.write("no credentials are set in this container. exit the shell to return to the panel.\n\n");
+  const { error } = await launchSandbox({ args });
+  if (error) {
+    process.stdout.write(`
+could not start docker: ${error.message}
+`);
+    await pauseForMessage();
+  }
+}
+function pauseForMessage() {
+  return new Promise((resolve) => setTimeout(resolve, 2500));
+}
 function splitWords(s) {
   return String(s ?? "").split(/\s+/).map((w) => w.trim()).filter(Boolean);
 }
@@ -6965,25 +7478,36 @@ async function addTriggerViaDialogs(paths, ui, notify) {
     if (maxTurns === void 0) return;
     entry = buildTriggerEntry("cron", { id, pattern, folder, flow, task, model, provider, maxTurns });
   } else if (kind === "label") {
-    const labels = await ui.input("labels \u2014 space-separated, any-of (a collaborator applies one to fire)", "pi:fix");
+    const forge = await ui.input(FORGE_PROMPT, "github");
+    if (forge === void 0) return;
+    const labels = await ui.input("labels \u2014 space-separated, any-of (a project member applies one to fire)", "pi:fix");
     if (labels === void 0) return;
     const flow = await ui.input("flow \u2014 the .pi/skills/<name> skill to run (the issue text is the task)", "fix");
     if (flow === void 0) return;
-    entry = buildTriggerEntry("label", { labels, flow });
+    const repository = forge === "azure" ? await ui.input("repository \u2014 the repo within the project to clone (azure work items name none)", "") : void 0;
+    if (repository === void 0 && forge === "azure") return;
+    entry = buildTriggerEntry("label", { labels, flow, forge, repository });
   } else if (kind === "comment") {
+    const forge = await ui.input(FORGE_PROMPT, "github");
+    if (forge === void 0) return;
     const phrase = await ui.input("trigger phrase \u2014 a comment containing this fires the flow (e.g. @pi)", "@pi");
     if (phrase === void 0) return;
     const flow = await ui.input("flow \u2014 the .pi/skills/<name> skill to run (the comment/issue text is the task)", "fix");
     if (flow === void 0) return;
-    entry = buildTriggerEntry("comment", { phrase, flow });
+    const repository = forge === "azure" ? await ui.input("repository \u2014 the repo within the project to clone (azure work items name none)", "") : void 0;
+    if (repository === void 0 && forge === "azure") return;
+    entry = buildTriggerEntry("comment", { phrase, flow, forge, repository });
   } else {
-    const action = await ui.input("PR actions \u2014 space-separated: labeled opened synchronize reopened", "labeled");
+    const forge = await ui.input(FORGE_PROMPT, "github");
+    if (forge === void 0) return;
+    const vocab = PR_ACTION_VOCAB[forge] ?? PR_ACTION_VOCAB.github;
+    const action = await ui.input(`MR/PR actions \u2014 space-separated: ${vocab.hint}`, vocab.dflt);
     if (action === void 0) return;
-    const labels = await ui.input("labels for 'labeled' \u2014 space-separated (blank for the auto actions)", "pi:review");
+    const labels = forge === "azure" ? "" : await ui.input("labels for 'labeled' \u2014 space-separated (blank for the auto actions)", "pi:review");
     if (labels === void 0) return;
     const flow = await ui.input("flow \u2014 the .pi/skills/<name> skill to run (the PR text is the task)", "review");
     if (flow === void 0) return;
-    entry = buildTriggerEntry("pull_request", { action, labels, flow });
+    entry = buildTriggerEntry("pull_request", { action, labels, flow, forge });
   }
   const res = writeTriggers({ triggersPath: paths.triggersPath, mutate: (list) => [...list, entry] });
   notify?.(res.ok ? `trigger added (live) \u2014 ${kind} \u2192 ${entry.run.flow}` : `add rejected: ${res.invalid}`, res.ok ? "info" : "error");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@edgehero/pi-dispatch-admin",
-  "version": "0.1.3",
-  "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 triggers (cron/label/comment/PR), and scheduled pause windows — plus AI-operable, human-confirmed controls. Runs against a live pi-dispatch deployment.",
+  "version": "0.1.5",
+  "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",
     "pi-extension",
@@ -11,6 +11,11 @@
     "ai-agent",
     "autonomous-agents",
     "self-hosted",
+    "github",
+    "gitlab",
+    "forgejo",
+    "gitea",
+    "azure-devops",
     "job-queue",
     "cron",
     "tui",
@@ -37,7 +42,7 @@
     "skills": [
       "./skills"
     ],
-    "image": "https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/banner.png"
+    "image": "https://raw.githubusercontent.com/edgehero/pi-dispatch/main/docs/images/banner.png?v=0.3.0"
   },
   "scripts": {
     "build": "node build.mjs",

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

@@ -49,3 +49,79 @@ Use them like this:
    the change can't be made without an operator at the terminal — it is not a bug to work around.
 
 The confirm is the approval step. Treat a decline as a final, legitimate answer.
+
+## Staged packages — `run.packages`, and why you cannot set it
+
+When a trigger fires, the job loads the third-party **pi packages the operator staged** into their global
+overlay dir (`PI_GLOBAL_PI_DIR`, under `packages/`, pinned by version). `run.packages` is an **opt-out**:
+absent and `true` both load them, and only an explicit `run.packages: false` withholds them from that one
+trigger. So the question to answer for a user is never "is this trigger armed" — it is "did this trigger
+decline".
+
+It matters because a loading trigger runs pinned third-party code against adversarial input (issue/PR/comment
+text) with open network egress. So the panel makes it visible: a loading trigger is badged `[packages]` in
+the trigger list, and its trust-model drill-in names the staged `name@version` set.
+
+**Which packages are staged, and whether a trigger declines them, are both operator edits to reviewed files
+— never a panel action and never a tool call.** This is deliberate, not a gap:
+
+- `dispatch_triggers` shows you *whether* a trigger loads them. The `/dispatch` panel displays it too, and
+  has no key that sets it.
+- `dispatch_trigger_add` and `dispatch_trigger_edit` **have no `packages` parameter**. You can change it in
+  neither direction — you cannot make a trigger load packages and you cannot make one decline them — the
+  same reason `dispatch_run` withholds the provider and model from you.
+
+So if a user asks you to change a trigger's packages flag, or to stage a package: **say plainly that you
+cannot, and that it is an edit they make to `triggers.json` (and to their overlay dir) themselves.** Do not
+attempt it through `dispatch_trigger_edit`, do not write the triggers file by another route, and do not treat
+the missing parameter as a bug to work around. Reporting which triggers load the staged set and explaining
+the change they would make is the whole of your part.
+
+## The job image — `run.image`, and why you cannot set it
+
+A trigger may carry `run.image`: the container image that trigger's jobs run in. Absent means the
+deployment default (`PI_JOB_IMAGE`). It exists so one flow can have a Python toolchain and another Node +
+Playwright, without one image carrying the union of both.
+
+Report it when asked, and be precise about what it does and does not decide. **Which image a job runs is
+which code it runs** — the pi version, the runner, the guardrail floor and the loader's discovery posture
+all come from the image. What it does *not* decide is what the container may do: `--cap-drop=ALL`, the
+non-root user, the read-only `/job` and the closed env allowlist are built by the worker for every image
+alike. The panel shows the tag in the trigger list and states it in the drill-in either way.
+
+**You cannot change it, in either direction.** `dispatch_trigger_add` and `dispatch_trigger_edit` have **no
+`image` parameter**, `dispatch_run` has none, and there is no allowlist for you to consult — because there
+is nothing model-callable to bound. Naming an image is an operator edit to the reviewed `triggers.json`,
+exactly like `run.packages`.
+
+So if a user asks you to point a trigger at a different image, or to build one: **say plainly that you
+cannot, and that it is an edit they make to `triggers.json` themselves.** Do not route around it via
+`dispatch_trigger_edit`, which changes the flow only. Two useful things you *can* say: the image must be
+built or pulled on the worker's own host, because jobs run with `--pull=never` and nothing is fetched at
+job time; and `pi-dispatch doctor` lists every image their triggers name and flags one that is missing.
+
+## The forge a trigger listens to — `run.kind`
+
+A webhook trigger names its forge: `"kind": "github"` or `"kind": "gitlab"`. Everything else about the
+trigger is the same — the `on.type`, the `{any, all, none}` label predicate, `flow`, `packages`, `image`.
+
+Two things are NOT the same, and both refuse at load rather than misbehaving quietly:
+
+- **`pull_request` actions are the forge's own words.** GitHub takes
+  `labeled | opened | synchronize | reopened`; GitLab takes `open | update | reopen | approved`. A word
+  from the wrong forge is refused when the file is written. It would not break anything otherwise — it
+  would simply never match an event, and the trigger would look configured while doing nothing.
+- **One `comment` trigger per forge.** Two GitHub comment triggers are refused; one GitHub and one GitLab
+  are fine.
+
+`dispatch_trigger_add` takes an optional `forge` parameter, defaulting to `github`. Unlike `image`, this
+one IS offered to the model — a model that can already add a GitHub trigger can already arm a paid run,
+and naming GitLab instead does not widen that. Both paths stay behind the same operator confirm.
+
+If you are asked why a GitLab trigger did not fire, the usual answers in order:
+
+1. **The actor was not a Developer.** Every GitLab trigger is gated on the actor's project access level,
+   including label triggers — a GitLab label is not an approval the way a GitHub one is.
+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.