@edgehero/pi-dispatch 4.3.1 → 5.0.0

package/.env.example

@@ -26,15 +26,23 @@
 #   OpenAI:    OPENAI_API_KEY     Google: GEMINI_API_KEY     Groq: GROQ_API_KEY   ... etc.
 # You can LEAVE THIS BLANK if you are already logged into pi: when the env has no key, the worker reads the
 # API key from ~/.pi/agent/auth.json (host-side) and env-injects it -- on by default, nothing to set.
-# API-key logins only; an OAuth/subscription login is refused (it expires; use an API key for a service).
+# Stored pi logins remain API-key only. For host-owned subscription authentication use docs/subscription-auth.md.
 ANTHROPIC_API_KEY=
 # uncomment to force env-only (fail loudly on a missing env key instead of using your pi login)
 # PI_AUTH_FROM_PI=0
+# Explicit subscription bindings own their providers, with no API-key fallback.
+# PI_AUTH_CONNECTIONS_FILE=/absolute/path/auth-connections.json
+# Host-private credentials, never under the global overlay or job/sandbox directories.
+# PI_AUTH_STORE_DIR=/absolute/private/path/subscription-auth
 
 # --- Which provider/model to run by default (override per job with --provider / --model) ---
+# A provider id: 1 to 64 letters, digits, dots, dashes and underscores, starting with a letter or digit.
+# Leave it out for the default; a value outside this shape, or an empty one, stops the worker at boot.
 PI_PROVIDER=anthropic
 # Name an exact model version (claude-sonnet-5-5, or a dated id such as claude-sonnet-4-5-20250929); an alias
 # that moves to a newer model can change cost.
+# A model id: 1 to 64 letters, digits and . _ - : / @, starting with a letter or digit (or one ~ or @ then
+# one), no spaces. Case is kept. A value outside this shape, or an empty one, stops the worker at boot.
 PI_MODEL=claude-sonnet-5-5
 # optional: the only models a job may call, comma-separated provider/model (at most 16). A trigger's own
 # run.models replaces this list for its jobs. The default model must be on it, or every job that uses the
@@ -161,8 +169,24 @@ PI_JOB_IMAGE=pi-job:latest
 # PI_LOGS_DIR=
 # default 0; set 1 to ALSO write raw container output to logs/<jobId>.log -- PII-bearing (issue/comment text), host-only (never mounted into the container), off by default (opt-in)
 # PI_CAPTURE_JOB_LOGS=
+# default on; set 0 to stop publishing each running job's transcript to Valkey (issue #643), where the console and the /dispatch panel on any host read it live
+# What leaves the host is the transcript only (never the raw log), redacted of this job's own secrets and known token shapes, capped at 2,000 entries per job, and removed 24h after the run ends (7 days if a worker dies mid-run)
+# PII: it carries issue text and tool output, so anyone who can read this Valkey (and every console operator) can read it; a secret the agent re-encodes is not caught. Any value but 0, 1 or empty refuses to boot
+# PI_LIVE_TRANSCRIPTS=
+# default on; set 0 to stop reading each running job's progress from its transcript (issue #644): turn, steps, failed steps and the tool running, to Valkey for the console and the /dispatch panel, plus a summary of integers in the run record
+# A trigger with run.progress also reports named phases (shown to console operators only, redacted); one with run.statusComment gets a forge comment edited as it runs (numbers only, never model text)
+# Independent of PI_LIVE_TRANSCRIPTS: with that at 0 and this on, no transcript text is published. 0 also stops the record field and the status comment. Any value but 0, 1 or empty refuses to boot
+# PI_RUN_PROGRESS=
 # default 30; prunes logs older than N days at boot AND on the retention timer below; 0 = keep forever
 # PI_LOG_RETENTION_DAYS=
+# default: PI_LOG_RETENTION_DAYS's value; prunes the console audit trail's month files (console-audit/ in PI_LOGS_DIR) older than N days, at boot and on the retention timer below; 0 = keep forever
+# Its own setting so that shortening the run history for privacy does not shorten the security trail. The newest month file is never pruned (it holds the chain's head)
+# Read by the worker, which runs the sweep (the console never prunes); set the same value on every host that shares PI_LOGS_DIR, where the shortest one wins. A value that is not a non-negative integer refuses to boot
+# A worker from before this setting that shares PI_LOGS_DIR prunes console-audit/ by PI_LOG_RETENTION_DAYS, so upgrade every host before relying on a longer audit retention
+# PI_CONSOLE_AUDIT_RETENTION_DAYS=
+# default 5000; how many runs the shared run index keeps (the run mirror in Valkey that a worker with PI_WORKER_NAME writes, read by the console, the /dispatch panel and capacity); an integer 1000-20000, anything else refuses to boot
+# Set the same value on every host: each worker trims the shared index to its own setting, so in a fleet the lowest one wins, and a worker from before this setting trims at 5000. Each trim is recorded, so a report shows the cut, never idle time
+# PI_RUN_MIRROR_MAX_RUNS=
 # default 24; how often the three retention sweeps (logs, sandboxes, sessions) re-run while the worker is up
 # The sandbox one covers two things since issue #337: the retained directories, and the pi-sandbox-<id>-net network of a run whose directory is already gone
 # 0 = BOOT-ONLY, which is what every version before this one did: a worker that never restarts never re-sweeps, so a configured window described nothing
@@ -170,10 +194,26 @@ PI_JOB_IMAGE=pi-job:latest
 # The window is a FLOOR, not a ceiling: a file dies on the first sweep AFTER its window closes, so the real ceiling is its window plus this interval (up to 48h for a sandbox at both defaults)
 # Refused above 168 (one week): setInterval clamps a longer delay to 1ms, and a sweep slower than a week is 0 with extra steps
 # PI_SWEEP_INTERVAL_HOURS=
+# default 24; how often the worker runs `pi-dispatch doctor --publish` itself (the first run a minute after boot), so the console and the /dispatch panel show each host's checks (issue #712)
+# What is published to Valkey is each check's level, and for a warning or a failure its label and fix with paths and URLs cut to <path> and scheme://host and secret-named values and known token shapes redacted; kept 7 days per host
+# A doctor you run by hand publishes the same way (pass --no-publish to skip it). 0 = the worker runs no doctor of its own; refused above 168 (one week)
+# PI_DOCTOR_INTERVAL_HOURS=
+# 1 = this host looks once a day for a newer pi and newer staged extensions, for the console's Updates page. Off by default.
+# It reads registry.npmjs.org and this project's public check runs on api.github.com, from the worker host and never from a job.
+# It sends the names of your staged packages to that registry, and changes nothing: trying or adopting a version is always a person.
+# PI_UPDATES_LOOK=
+# a proxy for the look's requests, with no direct fallback (http or https URL). Unset, the look connects directly.
+# PI_UPDATES_PROXY=
+# a registry to ask instead of registry.npmjs.org, such as a private mirror, so that private package names stay inside.
+# PI_UPDATES_REGISTRY=
 # where a finished run's directory is kept so you can re-open it (default: <PI_JOBS_DIR>/sandboxes, mode 0700)
 # `pi-dispatch sandbox <jobId>` starts a fresh container from the same image with the same workspace and NO credentials (docs/sandbox.md)
 # A retained directory holds the run's clone plus its prompt.md/event.json -- so issue text. Host-only; never mounted into a job
 # PI_SANDBOX_DIR=
+# Operator-only Fleet terminal mappings; the console defaults to <deployment>/sandbox-hosts.json
+# PI_SANDBOX_HOSTS_FILE=
+# Optional browser gateway enrollment, hand-owned and off when absent. See docs/sandbox-gateway.md.
+# PI_SANDBOX_GATEWAYS_FILE=sandbox-gateways.json
 # default 24. NOTE: 0 means OFF here -- nothing is retained and cleanup deletes as it always did
 # This is the OPPOSITE of PI_LOG_RETENTION_DAYS/PI_SESSIONS_TTL_DAYS, where 0 means keep forever
 # There is deliberately no keep-forever value: one repo clone per run with no ceiling is a disk bomb. Use --pin for the one run worth keeping
@@ -212,6 +252,10 @@ PI_JOB_IMAGE=pi-job:latest
 # That source is your whole gh login: full-scope and non-expiring, and a transcript is a FILE -- any command that echoed an auth header persists it
 # Prefer GITHUB_AUTH_SOURCE=app or a short-expiry fine-grained PAT. Set exactly 1 to accept the trade explicitly (SECURITY.md, docs/sessions.md)
 # PI_SESSIONS_ALLOW_GH_SOURCE=
+# default <PI_SESSIONS_DIR>/.checkpoints; where workspace checkpoints of durable runs live, unset with no PI_SESSIONS_DIR = nowhere
+# A checkpoint holds a job's workspace, so the same rules as transcripts apply: mode 0700, owned by the worker, never under a temp dir
+# It must not be PI_SESSIONS_DIR itself, contain it, or sit inside one of its session folders: the worker refuses that at start
+# PI_CHECKPOINTS_DIR=
 # ABSOLUTE path to the unified triggers.json, read by BOTH worker and receiver (a relative path resolves against the service's WorkingDirectory).
 # Unset = cron disabled for the worker; the receiver falls back to ./triggers.json in the folder it starts from (what `pi-dispatch init` scaffolds)
 # and refuses to start when neither exists (it holds the label/comment/pull_request trigger config)
@@ -248,8 +292,6 @@ PI_JOB_IMAGE=pi-job:latest
 # (default: <your pi agent dir>/pi-dispatch-deployment.json). Read by the ADMIN EXTENSION only; the worker and receiver never look at it.
 # Your own environment still wins key by key, so this points the panel at a deployment, it does not override one
 # PI_DISPATCH_DEPLOYMENT_FILE=
-# where `/dispatch insights` writes its HTML artifact (default: <OS temp dir>/pi-dispatch-<your uid>/graph). Admin extension only. See docs/insights.md
-# PI_GRAPH_DIR=
 
 # --- Reuse your existing pi setup in every job (see docs/global-pi-overlay.md) ---
 # dir with your host pi setup (models.json/skills/APPEND_SYSTEM.md), mounted /opt/pi-global:ro into every job, layered UNDER each repo's .pi/. Unset = off. Stage it with: pi-dispatch import-pi
@@ -286,6 +328,13 @@ PI_JOB_IMAGE=pi-job:latest
 # PI_SECRET_RESOLVER_ROOTS=
 # default 10000, per reference. Sits before a paid container and is multiplied by the reference count, so tighter than doctor's 30s.
 # PI_SECRET_RESOLVE_TIMEOUT_MS=
+# Project secret bundles (docs/secrets.md Recipe D, issue #704): a project's whole environment, granted ONCE in
+# triggers.json ("secretBundles": { "shop": { "profile": "shop-env", "ref": "shop", "project": "shop" } }). The worker
+# runs YOUR script once per job start, on the HOST, and it prints every variable of that environment.
+# name:/absolute/path:format, comma separated; format is dotenv (strict NAME=value lines) or json (one object of strings),
+# required, never guessed. A plain file needs no manager: `exec cat "/etc/pi-dispatch/bundles/$1.env"` with :dotenv.
+# Same exit codes as above. Bounded by PI_SECRET_RESOLVER_ROOTS for panel-declared ones. Unset = no bundle resolves here.
+# PI_SECRET_BUNDLES=
 
 # --- Holding a job until something else happens (docs/wait-for.md, issue #230) ---
 # A trigger may carry "waitFor": [{ "after": "2026-09-01T09:00:00Z" }, { "profile": "jira" }]. The job is
@@ -345,6 +394,16 @@ PI_SCHEDULER_STALL_MAX=2
 # `pi-dispatch doctor` prints enforced quietly, asserted as a warning naming who asserts it, and absent as a failure.
 # Env-only, deliberately: a bound that can be widened from the surface it bounds is not a bound.
 # PI_BACKEND_FLOOR=
+# openshell (an NVIDIA OpenShell sandbox per job, docs/backends.md) is blessable since issue #684: name it in PI_BACKENDS.
+# While PI_BACKENDS names it the worker reads these two at boot (a bad value refuses the boot), refuses PI_EGRESS=0, and
+# refuses an openshell CLI or gateway not at the tested release; `pi-dispatch doctor --openshell` checks the host first.
+# openshell-bind is the same venue in bind mode (issue #686): the job's directories bind-mounted, which brings back folder
+# and cron-folder jobs, /inbox steering and run.recover. Opt-in: the gateway's gateway.toml must allow driver config and
+# bind mounts (docs/backends.md, "Bind mode"), docker driver only. It shares the two settings below; name it in PI_BACKENDS.
+# the gateway's compute driver, docker (default) or podman, whose store the job image is read from
+# PI_OPENSHELL_ENGINE=
+# a registered gateway's name (`openshell gateway list`); unset uses the CLI's active gateway
+# PI_OPENSHELL_GATEWAY=
 
 # --- Egress policy: what a job container may reach on the network (docs/egress.md) ---
 # ON by default. Every job runs on its own --internal Docker network whose only other member is an allowlist
@@ -509,6 +568,28 @@ AZURE_WEBHOOK_SECRET=
 # Required only when AZURE_WEBHOOK_MODE=header.
 AZURE_WEBHOOK_HEADER=
 
+# --- The operator console, a web page served by `pi-dispatch-console serve` (docs/console.md, issue #640) ---
+# Nothing listens until you run serve, and serve refuses to start before `pi-dispatch-console token add --name <you> --role operator`.
+# default 127.0.0.1:4790. Also [::1]:<port> or unix:/abs/path (a 0600 socket in a folder only you can open, which no job can reach).
+# IP literals only: a hostname could resolve somewhere you did not mean.
+# The /dispatch panel reads it too: `/dispatch insights` and the `i` key print the console's insights page at this address (docs/insights.md).
+# PI_CONSOLE_LISTEN=
+# default console-tokens.json, relative to this folder. Hashes only, mode 0600, yours; serve refuses anything looser.
+# PI_CONSOLE_TOKENS_FILE=
+# default none. Extra Host names the console answers to, comma separated; any port is accepted, so an ssh -L tunnel needs nothing here.
+# host.docker.internal and the other container gateway names are refused: they are how a job would reach the console.
+# PI_CONSOLE_ALLOWED_HOSTS=
+# default off. 1 answers every write 403 and leaves reads and sign-in on -- for a console you only want to look at.
+# PI_CONSOLE_READ_ONLY=
+# default off. 1 allows a non-loopback IP in PI_CONSOLE_LISTEN, and doctor warns every time: the console has no TLS, use ssh -L instead.
+# PI_CONSOLE_BIND_PUBLIC=
+# default 60, 5 to 1440. Minutes without a request before a session ends.
+# PI_CONSOLE_IDLE_MINUTES=
+# default 12, 1 to 168. Hours after sign-in before a session ends however busy, so a forgotten tab does not stay signed in.
+# PI_CONSOLE_MAX_HOURS=
+# default 4, 1 to 32. Live streams one token may hold across its sign-ins, so no one can hold every connection.
+# PI_CONSOLE_MAX_STREAMS=
+
 # --- What is deliberately NOT a key in this file --- issue #282
 # The rule, and it is checked by a test (worker/test/env-docs.test.mjs): every environment variable this
 # project's loaders read is either a key above, or named here with the reason it cannot be one. A variable

package/README.md

@@ -2,13 +2,15 @@
 
 The worker and the `pi-dispatch` command line tool of
 **[pi-dispatch](https://github.com/edgehero/pi-dispatch)**, which runs the
-[pi](https://github.com/earendil-works/pi) coding agent as a self hosted background service.
+[pi](https://github.com/earendil-works/pi) coding agent for you in the background, in a sealed box for each job, up to the spending limit
+you set, and shows it all on one web page. Most people want the
+[main README](https://github.com/edgehero/pi-dispatch#readme) first: it explains why and how to use it.
 
 The worker takes jobs from a durable queue (Valkey with BullMQ). Before anything is spent it checks every
 cap that applies: job counts and a daily token count for the whole deployment, job counts per repo, folder
 or project, and dollars per day, week or month for the deployment and per repo, folder, project or model,
 plus each project's share of the budget split. It then starts one locked down container per job (Docker or
-Podman), holds the job to its own dollar cap when one is set, gives the agent the job, records what it did
+Podman), holds the job to its own dollar cap when one is set, gives the agent the job, records what it loaded, what it did
 and what it cost, and removes the container. Jobs come from the command line, from cron triggers, or from
 forge events that the
 [receiver](https://www.npmjs.com/package/@edgehero/pi-dispatch-receiver) queues.
@@ -27,6 +29,10 @@ npx @edgehero/pi-dispatch worker    # run jobs
 npx @edgehero/pi-dispatch run ./my-project --task "add type hints" --flow tidy
 ```
 
+On the NVIDIA OpenShell venue (`PI_BACKENDS=openshell` in `.env`), `up` also checks its gateway, offers to start
+and register it (it never installs OpenShell), and puts the job image into the gateway's engine
+([backends](https://github.com/edgehero/pi-dispatch/blob/main/docs/backends.md#the-openshell-venue)).
+
 A local job edits your folder **in place**, and there is no undo, so commit first. The worker refuses a
 folder with uncommitted changes unless you pass `--force`. The folder must be the root of a git repository
 with at least one commit, and `run` refuses any other folder before it queues anything.
@@ -37,15 +43,22 @@ with at least one commit, and `run` refuses any other folder before it queues an
 |---|---|
 | `init` | write `.env` and the config files into this folder (never overwrites) |
 | `up` | one pass that asks before each container action: image, Valkey, egress proxy, `init`, `doctor` |
-| `doctor [--fix] [--live]` | check the whole setup; `--live` reads the isolation guarantees back from real containers |
+| `doctor [--fix] [--live] [--openshell] [--secrets] [--no-publish]` | check the whole setup; `--live` reads the isolation guarantees back from real containers; each run publishes its checks (paths, URLs and secret values cut out) for the console and the panel, unless `--no-publish` |
 | `worker` | run jobs from the queue |
 | `run <folder> --task "..."` | queue one job against a local folder |
 | `run --trigger <id>` | fire one cron trigger from the triggers file now, once, as its schedule would |
-| `status`, `pause`, `resume`, `cancel <jobId>` | steer the running worker from any terminal |
-| `service render\|install\|status\|restart` | run the worker (or `--receiver`) as a service (user level on macOS and Linux, nssm on Windows) |
+| `status`, `pause`, `resume`, `cancel <jobId>` | control the running worker from any terminal |
+| `steer <jobId> "..."` | send a running job a message, which the agent reads between its steps (`--later` once it would otherwise stop) |
+| `capacity` | how busy each host was over the last day, week or thirty days, read from the run records |
+| `service render\|install\|uninstall\|status\|start\|stop\|restart` | run the worker (or `--receiver`, or `--console` for the operator console) as a service (user level on macOS and Linux, nssm on Windows) |
 | `setup github` | create a GitHub App in one browser click |
+| `auth` | manage host owned subscription authentication: `status`, `login`, `logout`, `usage`, `trial` |
+| `canary` | replay up to three retained jobs on another model in disposable workspaces, under one experiment cap |
+| `updates` | which pi and which extensions jobs run, what is newer, and adopting it |
+| `opener install` | register `pi-dispatch-open`, so the console can open a sandbox in your own terminal |
 | `import-pi` | stage your own pi setup (models, skills, persona) for every job, without credentials |
-| `sandbox <jobId>` | reopen a finished run's workspace in a fresh container with no credentials |
+| `chat <jobId \| url \| key>` | follow and steer a running job, answer a parked one, or fork a finished one into your own pi (`--fork-as-job` to run it as a job), through the operator console |
+| `sandbox <jobId>` | reopen a finished run's workspace in a fresh container with no credentials; `--list`, `--attach` and `--new` to see, return to or prepare one |
 | `egress render` | write `model-endpoints.conf` from `model-endpoints.json`, then print the command that reloads the egress proxy |
 
 Before you rely on it, read [`SECURITY.md`](https://github.com/edgehero/pi-dispatch/blob/main/SECURITY.md).
@@ -54,5 +67,5 @@ guardrails that tell it not to leak them are prompt text. The default GitHub sou
 whole login, full scope and never expiring. pi-dispatch never merges anything, but the job's token can,
 so branch protection on your default branch is the real control.
 
-The full guide, with triggers, providers, the admin panel and every forge, is the
+The full guide, with the console, triggers, providers, the panel and every forge, is the
 [main README](https://github.com/edgehero/pi-dispatch#readme). MIT licensed.

package/deploy/console.service

@@ -0,0 +1,52 @@
+# UNTESTED EXAMPLE (DES-OPERATOR-CONSOLE) -- a starting point, not a shipped, verified unit. Adapt it.
+#
+# The operator console (`pi-dispatch-console serve`, issue #640) as a service, so it keeps running after the terminal
+# that started it closes (issue #708). `pi-dispatch service install --console` renders this file for THIS host: the
+# node, the console package's own entry (admin/dist/console.mjs of @edgehero/pi-dispatch-admin, wherever npm put it)
+# and the deployment folder are substituted, so prefer that to adapting it by hand.
+#
+# The console listens on PI_CONSOLE_LISTEN (default 127.0.0.1:4790, loopback only) and reads its tokens file
+# (PI_CONSOLE_TOKENS_FILE, default console-tokens.json in the deployment folder). It never needs Docker or Podman, so
+# this unit is ordered after nothing but the network and has no Quadlet companion. Reach it from another machine
+# with ssh -L, never by binding a public address: it speaks plain HTTP (docs/console.md).
+#
+# NO EnvironmentFile= on purpose: `serve --deployment` reads the deployment's `.env` itself, takes only its own
+# PI_CONSOLE_* keys and the Valkey keys it needs from it, and refuses a `.env` another account can change. Loading the
+# whole file into the process environment would hand it every worker secret (the provider key, the forge token) and
+# would make each of those keys read as this shell's, which wins over the file and skips that trust check.
+# WorkingDirectory / User / node path below are PLACEHOLDERS: set them to wherever your deployment folder is and
+# whoever owns it (the tokens file must be owned by that account, mode 0600, or serve refuses).
+
+[Unit]
+Description=pi-dispatch operator console (the web console over the queue, runs and spend; loopback by default)
+# For a system unit. In a --user unit these two are inert (the user manager has no network-online.target), which is
+# harmless: the console binds loopback or a socket, and its Valkey reads retry on their own.
+After=network-online.target
+Wants=network-online.target
+# Crash-loop bound, as the worker and receiver units carry it: at most StartLimitBurst restarts within
+# StartLimitIntervalSec, then systemd stops trying. Pairs with Restart=on-failure below.
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+[Service]
+Type=simple
+User=pi
+WorkingDirectory=/opt/pi-dispatch
+ExecStart=/usr/bin/node /usr/lib/node_modules/@edgehero/pi-dispatch-admin/dist/console.mjs serve --deployment /opt/pi-dispatch
+Restart=on-failure
+RestartSec=5
+# Exit 2 is the console's refusal: no tokens file, no operator token in it, an unusable PI_CONSOLE_LISTEN, or the
+# single-instance lock held by another console of this deployment. The next start reads the same files and fails
+# the same way, so it is never restarted; add a token (`pi-dispatch-console token add`) or fix the setting, then
+# start the unit again.
+# A crash leaves the lock (<PI_LOGS_DIR>/console-audit/.console.lock) behind holding a dead pid, which the next start
+# takes over. But if that pid has since been reused by another process (or by another account's, which reads as
+# alive), every start refuses with exit 2 and the unit stays stopped: when the pid the refusal names is not a console,
+# remove the lock file and start the unit again.
+RestartPreventExitStatus=2
+# serve handles SIGTERM: it ends the open streams, closes the listener and releases the lock, then exits.
+KillSignal=SIGTERM
+TimeoutStopSec=30
+
+[Install]
+WantedBy=multi-user.target

package/deploy/docker-compose.yml

@@ -30,7 +30,9 @@
 
 services:
   valkey:
-    image: valkey/valkey:8
+    # Pinned to a minor, never a floating major (issue #761): VALKEY_IMAGE in worker/src/valkey-auth.mjs says why, and a
+    # test holds this line to it.
+    image: valkey/valkey:8.1
     # The password (issue #468), from the deployment's .env through `--env-file .env`, into the container's ENVIRONMENT
     # and never onto a command line: the image's PID 1 is tini, which keeps its whole argv for the life of the container,
     # readable by every account on the host in /proc (measured). Empty or unset starts Valkey without one, as before.

package/deploy/pi-dispatch-valkey.container

@@ -10,13 +10,15 @@
 # (measured on Podman 5.8.1: with linger on it came up 25 s after a reboot with nobody logged in).
 #
 # Fully qualified image names throughout: under short-name enforcement a unit cannot answer the prompt a short
-# name raises, so `valkey/valkey:8` could fail to start where Docker quietly assumed docker.io.
+# name raises, so `valkey/valkey:8.1` could fail to start where Docker quietly assumed docker.io. Pinned to a minor,
+# never a floating major (issue #761): VALKEY_IMAGE in worker/src/valkey-auth.mjs says why, and a test holds the
+# Image= line to it. A changed line restarts Valkey when `service install --force` writes it; the volume is kept.
 
 [Unit]
 Description=pi-dispatch Valkey (the job queue; rootless Podman, Quadlet)
 
 [Container]
-Image=docker.io/valkey/valkey:8
+Image=docker.io/valkey/valkey:8.1
 ContainerName=pi-dispatch-valkey
 # EXPLICIT, see pi-dispatch-valkey.network for why a container here must never rely on the default network.
 Network=pi-dispatch-valkey.network

package/deploy/sandbox-gateway.service

@@ -0,0 +1,23 @@
+# Optional example, installed by hand only. See docs/sandbox-gateway.md (#754).
+# Run as the account owning the sandbox runtime, never add privileges for the gateway.
+# No EnvironmentFile: the program reads only its explicit deployment key allowlist.
+[Unit]
+Description=pi-dispatch sandbox browser gateway
+After=network-online.target
+Wants=network-online.target
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+[Service]
+Type=simple
+User=pi
+WorkingDirectory=/opt/pi-dispatch
+ExecStart=/usr/bin/node /usr/lib/node_modules/@edgehero/pi-dispatch-sandbox-gateway/dist/cli.mjs --config /opt/pi-dispatch/sandbox-gateway.json
+Restart=on-failure
+RestartSec=5
+NoNewPrivileges=yes
+KillSignal=SIGTERM
+TimeoutStopSec=30
+
+[Install]
+WantedBy=multi-user.target

package/deploy/worker-env-wrapper.cmd

@@ -54,6 +54,10 @@ REM number. So after the load the wrapper re-asserts its own: ENV_SETUP and PI_E
 REM %PI_ENV_SETUP%, which cmd expands when it READS this parenthesized block, before its first line runs
 REM (`set /?`, the reason delayed expansion exists), so the value is the unit's and no .env line reaches it;
 REM and ERRORLEVEL cleared just before the command runs. RC is assigned after the command, before it is read.
+REM PI_WRAPPER_NO_DOTENV=1 (issue #708): the command reads the deployment's .env ITSELF and takes only the keys it
+REM owns (the operator console, `serve --deployment`), so .env is neither loaded nor required here; see
+REM worker-env-wrapper.sh for why. Read before the load, from the service's own environment, and cleared after it.
+if "%PI_WRAPPER_NO_DOTENV%"=="1" goto wrapper_env_loaded
 if exist ".env" (
   for /f "usebackq eol=# tokens=1,* delims==" %%A in (".env") do set "%%A=%%B"
   set "ENV_SETUP=%PI_ENV_SETUP%"
@@ -65,6 +69,8 @@ if exist ".env" (
   )
   echo worker-env-wrapper: no .env in "%CD%" -- the environment comes from "%ENV_SETUP%" ^(PI_ENV_SETUP^) 1>&2
 )
+:wrapper_env_loaded
+set "PI_WRAPPER_NO_DOTENV="
 
 REM AFTER .env, deliberately: the manager is the newer source of truth, so a stale key left in the file
 REM loses instead of silently shadowing the managed one (mirrors the .sh twin). A missing or failing

package/deploy/worker-env-wrapper.sh

@@ -77,7 +77,15 @@ trap wrapper_stopped_early TERM INT
 # until the `shift` below.
 set -- "${PI_ENV_SETUP:-}" "$@"
 
-if [ -f ./.env ]; then
+# PI_WRAPPER_NO_DOTENV=1 (issue #708) is set by the unit for a command that reads the deployment's .env ITSELF and
+# takes only the keys it owns: the operator console (`serve --deployment`), which also refuses a .env another account
+# can change. Sourcing the whole file here would hand that process every worker secret and make each key read as its
+# own shell's, which wins over the file and skips that check. So ./.env is not sourced and not required. Tested
+# before the load, from the unit's environment, so no .env line can set it; PI_ENV_SETUP is honoured exactly as
+# without it (an operator who configured a script asked for it). Unset after, so the command never sees it.
+if [ "${PI_WRAPPER_NO_DOTENV:-}" = "1" ]; then
+	:
+elif [ -f ./.env ]; then
 	set -a; . ./.env; set +a
 elif [ -z "$1" ]; then
 	echo "worker-env-wrapper: .env not found in $PWD -- this wrapper must be started in the deployment folder (the unit's WorkingDirectory / nssm AppDirectory); it no longer guesses a location from its own path" >&2
@@ -90,6 +98,7 @@ fi
 # AFTER THE LOAD, every variable this wrapper reads is assigned, so no assignment line of ./.env
 # reaches one. The worker sees the unit's PI_ENV_SETUP too, never one the file set (the setup script,
 # which is unit configuration, may still set its own).
+unset PI_WRAPPER_NO_DOTENV
 env_setup=$1
 shift
 if [ -n "$env_setup" ]; then

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "4.3.1",
+  "version": "5.0.0",
   "type": "module",
-  "description": "The pi-dispatch worker and CLI: runs the pi coding agent as a self-hosted service, one locked down Docker or Podman container per job, with spend caps checked before anything is spent, plus init, up, doctor and service install.",
+  "description": "The pi-dispatch worker and CLI: go from one AI coding agent to many in the background, running the pi coding agent as a self-hosted service, one locked down Docker or Podman container per job, with spend caps checked before anything is spent, plus init, up, doctor and service install.",
   "keywords": [
     "pi",
     "pi-coding-agent",
@@ -41,11 +41,46 @@
     "pi-dispatch": "src/cli.mjs"
   },
   "exports": {
+    "./receiver-status": "./src/receiver-status.mjs",
+    "./setup-contract": "./src/setup-contract.mjs",
+    "./auth-policy": "./src/auth-policy.mjs",
+    "./setup-host-entry": "./src/setup-host-entry.mjs",
+    "./setup-lock": "./src/setup-lock.mjs",
+    "./provider-key": "./src/provider-key.mjs",
     ".": "./src/index.mjs",
     "./config": "./src/config.mjs",
     "./exit-code": "./src/exit-code.mjs",
     "./entry": "./src/entry.mjs",
     "./git-hardening": "./src/git-hardening.mjs",
+    "./http-body": "./src/http-body.mjs",
+    "./console-tokens": "./src/console-tokens.mjs",
+    "./console-probe": "./src/console-probe.mjs",
+    "./console-audit": "./src/console-audit.mjs",
+    "./console-answer": "./src/console-answer.mjs",
+    "./steer-inbox": "./src/steer-inbox.mjs",
+    "./steer-framing": "./src/steer-framing.mjs",
+    "./inbox-relay": "./src/inbox-relay.mjs",
+    "./held-replies": "./src/held-replies.mjs",
+    "./live-transcript": "./src/live-transcript.mjs",
+    "./run-progress": "./src/run-progress.mjs",
+    "./reserve-estimate": "./src/reserve-estimate.mjs",
+    "./endpoint-status": "./src/endpoint-status.mjs",
+    "./model-endpoints": "./src/model-endpoints.mjs",
+    "./egress-allowlist": "./src/egress-allowlist.mjs",
+    "./egress": "./src/egress.mjs",
+    "./openshell-policy": "./src/openshell-policy.mjs",
+    "./model-catalog": "./src/model-catalog.mjs",
+    "./output-cap": "./src/output-cap.mjs",
+    "./model-roles": "./src/model-roles.mjs",
+    "./model-status": "./src/model-status.mjs",
+    "./model-observation": "./src/model-observation.mjs",
+    "./model-cooldowns": "./src/model-cooldowns.mjs",
+    "./model-proposal-protocol": "./src/model-proposal-protocol.mjs",
+    "./model-ref": "./src/model-ref.mjs",
+    "./model-failover-protocol": "./src/model-failover-protocol.mjs",
+    "./model-failover": "./src/model-failover.mjs",
+    "./model-attempts": "./src/model-attempts.mjs",
+    "./schedules": "./src/schedules.mjs",
     "./env-file": "./src/env-file.mjs",
     "./service-env": "./src/service-env.mjs",
     "./podman-stack": "./src/podman-stack.mjs",
@@ -56,28 +91,41 @@
     "./queue": "./src/queue.mjs",
     "./capabilities": "./src/capabilities.mjs",
     "./parked": "./src/parked.mjs",
+    "./approval-policy": "./src/approval-policy.mjs",
+    "./approval-state": "./src/approval-state.mjs",
     "./connection": "./src/connection.mjs",
     "./valkey-auth": "./src/valkey-auth.mjs",
     "./job-id": "./src/job-id.mjs",
     "./forges": "./src/forges.mjs",
+    "./fleet-lease": "./src/fleet-lease.mjs",
     "./backend-local": "./src/backend-local.mjs",
-		"./backends": "./src/backends.mjs",
-		"./backend-registry": "./src/backend-registry.mjs",
-		"./container-spec": "./src/container-spec.mjs",
-		"./job-size": "./src/job-size.mjs",
-		"./size-suggest": "./src/size-suggest.mjs",
-		"./capacity": "./src/capacity.mjs",
-		"./capacity-records": "./src/capacity-records.mjs",
-		"./capacity-cli": "./src/capacity-cli.mjs",
-		"./live-jobs": "./src/live-jobs.mjs",
-		"./size-records": "./src/size-records.mjs",
-		"./host-budget": "./src/host-budget.mjs",
-		"./backend-conformance": "./src/backend-conformance.mjs",
-		"./live-probes": "./src/live-probes.mjs",
-		"./triggers": "./src/triggers.mjs",
+    "./container-names": "./src/container-names.mjs",
+    "./backends": "./src/backends.mjs",
+    "./backend-registry": "./src/backend-registry.mjs",
+    "./container-spec": "./src/container-spec.mjs",
+    "./job-size": "./src/job-size.mjs",
+    "./size-suggest": "./src/size-suggest.mjs",
+    "./capacity": "./src/capacity.mjs",
+    "./capacity-records": "./src/capacity-records.mjs",
+    "./touch-state": "./src/touch-state.mjs",
+    "./touch-outbox": "./src/touch-outbox.mjs",
+    "./zero-touch": "./src/zero-touch.mjs",
+    "./capacity-cli": "./src/capacity-cli.mjs",
+    "./live-jobs": "./src/live-jobs.mjs",
+    "./host-telemetry": "./src/host-telemetry.mjs",
+    "./size-records": "./src/size-records.mjs",
+    "./host-budget": "./src/host-budget.mjs",
+    "./backend-conformance": "./src/backend-conformance.mjs",
+    "./live-probes": "./src/live-probes.mjs",
+    "./triggers": "./src/triggers.mjs",
     "./mcp-config": "./src/mcp-config.mjs",
+    "./mcp-preflight": "./src/mcp-preflight.mjs",
     "./triggers-file": "./src/triggers-file.mjs",
+    "./file-expect": "./src/file-expect.mjs",
     "./packages": "./src/packages.mjs",
+    "./updates": "./src/updates.mjs",
+    "./package-canary-record": "./src/package-canary-record.mjs",
+    "./updates-subscription-adapters": "./src/updates-subscription-adapters.mjs",
     "./pause-windows": "./src/pause-windows.mjs",
     "./scoped-limits": "./src/scoped-limits.mjs",
     "./projects": "./src/projects.mjs",
@@ -88,6 +136,10 @@
     "./wait-state": "./src/wait-state.mjs",
     "./cancel-state": "./src/cancel-state.mjs",
     "./host-registry": "./src/host-registry.mjs",
+    "./hook-runs": "./src/hook-runs.mjs",
+    "./doctor-results": "./src/doctor-results.mjs",
+    "./host-loads": "./src/host-loads.mjs",
+    "./loaded-record": "./src/loaded-record.mjs",
     "./identity": "./src/identity.mjs",
     "./gitlab-identity": "./src/gitlab-identity.mjs",
     "./forgejo-identity": "./src/forgejo-identity.mjs",
@@ -95,17 +147,57 @@
     "./get-token": "./src/get-token.mjs",
     "./octokit-log": "./src/octokit-log.mjs",
     "./runtime-settings": "./src/runtime-settings.mjs",
+    "./secret-profiles": "./src/secret-profiles.mjs",
     "./run-history": "./src/run-history.mjs",
+    "./reason-catalog": "./src/reason-catalog.mjs",
     "./run-mirror": "./src/run-mirror.mjs",
+    "./run-budget-ledger": "./src/run-budget-ledger.mjs",
+    "./recovery-queue": "./src/recovery-queue.mjs",
+    "./run-checkpoint": "./src/run-checkpoint.mjs",
+    "./session-key": "./src/session-key.mjs",
+    "./fork-store": "./src/fork-store.mjs",
+    "./fork-policy": "./src/fork-policy.mjs",
+    "./fork-job": "./src/fork-job.mjs",
+    "./chat-mode": "./src/chat-mode.mjs",
+    "./chat-fork": "./src/chat-fork.mjs",
+    "./console-client": "./src/console-client.mjs",
+    "./workspace-checkpoint": "./src/workspace-checkpoint.mjs",
     "./sandbox": "./src/sandbox.mjs",
+    "./sandbox-policy": "./src/sandbox-policy.mjs",
+    "./openshell-cli": "./src/openshell-cli.mjs",
     "./sandbox-store": "./src/sandbox-store.mjs",
+    "./sandbox-gateway-protocol": "./src/sandbox-gateway-protocol.mjs",
+    "./opener-protocol": "./src/opener-protocol.mjs",
+    "./sandbox-hosts": "./src/sandbox-hosts.mjs",
+    "./sandbox-prepare": "./src/sandbox-prepare.mjs",
+    "./sandbox-prepare-requests": "./src/sandbox-prepare-requests.mjs",
+    "./sandbox-inventory": "./src/sandbox-inventory.mjs",
+    "./sandbox-sessions": "./src/sandbox-sessions.mjs",
+    "./sandbox-session-watch": "./src/sandbox-session-watch.mjs",
     "./subscriptions": "./src/subscriptions.mjs",
+    "./subscription-status": "./src/subscription-status.mjs",
     "./budget": "./src/budget.mjs",
     "./pricing": "./src/pricing.mjs",
     "./money": "./src/money.mjs",
     "./dollar-budget": "./src/dollar-budget.mjs",
     "./scheduler-stall-guard": "./src/scheduler-stall-guard.mjs",
-    "./watch-closer": "./src/watch-closer.mjs"
+    "./watch-closer": "./src/watch-closer.mjs",
+    "./defer-reasons": "./src/defer-reasons.mjs",
+    "./bullmq-internals": "./src/bullmq-internals.mjs",
+    "./store-version": "./src/store-version.mjs",
+    "./job-data-version": "./src/job-data-version.mjs",
+    "./retention": "./src/retention.mjs",
+    "./record-reason": "./src/record-reason.mjs",
+    "./watch-contract": "./src/watch-contract.mjs",
+    "./watch-store": "./src/watch-store.mjs",
+    "./watch-decision": "./src/watch-decision.mjs",
+    "./watch-board": "./src/watch-board.mjs",
+    "./watch-trace": "./src/watch-trace.mjs",
+    "./answerer": "./src/answerer.mjs",
+    "./answerer-runtime": "./src/answerer-runtime.mjs",
+    "./question-groups": "./src/question-groups.mjs",
+    "./question-group-runtime": "./src/question-group-runtime.mjs",
+    "./zero-touch-fixes": "./src/zero-touch-fixes.mjs"
   },
   "engines": {
     "node": ">=22.19.0"
@@ -115,10 +207,16 @@
     "start": "node src/cli.mjs worker"
   },
   "dependencies": {
-    "@earendil-works/pi-ai": "1.2.0",
+    "@earendil-works/pi-ai": "1.5.0",
+    "@earendil-works/pi-tui": "1.5.0",
     "@octokit/auth-app": "8.2.0",
     "@octokit/rest": "22.0.1",
     "bullmq": "5.80.4",
-    "ioredis": "5.11.1"
+    "ioredis": "5.11.1",
+    "jiti": "2.7.0",
+    "jose": "6.2.14",
+    "proper-lockfile": "4.1.2",
+    "undici": "8.10.2",
+    "yaml": "2.9.0"
   }
 }