@edgehero/pi-dispatch 1.10.3 → 2.0.0

package/README.md

@@ -0,0 +1,50 @@
+# @edgehero/pi-dispatch
+
+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.
+
+The worker takes jobs from a durable queue (Valkey with BullMQ). It checks the spend caps before
+anything is spent, starts one locked down container per job (Docker or Podman), gives the agent the
+job, records 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.
+
+## Start
+
+You need Docker or Podman, Node 22.19 or newer, and an API key for a model provider that pi supports.
+
+```bash
+mkdir my-dispatch && cd my-dispatch
+npx @edgehero/pi-dispatch up        # job image, Valkey with a password, egress proxy, config files, doctor
+#  edit .env and set your provider key
+npx @edgehero/pi-dispatch worker    # run jobs
+npx @edgehero/pi-dispatch run ./my-project --task "add type hints" --flow tidy
+```
+
+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`.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `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 |
+| `worker` | run jobs from the queue |
+| `run <folder> --task "..."` | queue one job against a local folder |
+| `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) |
+| `setup github` | create a GitHub App in one browser click |
+| `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 |
+
+Before you rely on it, read [`SECURITY.md`](https://github.com/edgehero/pi-dispatch/blob/main/SECURITY.md).
+In short: the agent can read the provider key and the forge token inside its container, and the
+guardrails that tell it not to leak them are prompt text. The default GitHub source (`gh`) forwards your
+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
+[main README](https://github.com/edgehero/pi-dispatch#readme). MIT licensed.

package/deploy/com.pi-dispatch.worker.plist

@@ -37,9 +37,15 @@
   One worker per host (DES-CONCURRENCY-3): parallelism is PI_CONCURRENCY inside the one process.
   Requires the AOF-enabled Valkey from deploy/docker-compose.yml.
 
-  PI_LOGS_DIR (run-history records; default OS-temp /pi-dispatch/logs) is created and written by the
-  worker at boot, so it must be writable by the account the daemon runs as. Set via `.env` (the wrapper),
-  not a plist change; its default is distinct from the StandardOutPath worker.out.log below.
+  PI_LOGS_DIR (run-history records) and PI_SETTINGS_FILE (the settings overlay) default to
+  ~/.pi-dispatch, which is DURABLE across a reboot, and are created and written by the worker at boot,
+  so they must be writable by the account the daemon runs as. SET BOTH EXPLICITLY via `.env` (the
+  wrapper), not a plist change: the default is per USER, so a daemon running as another account writes
+  a different directory than the panel reads, and the run list then shows nothing while panel-set caps
+  land where the worker never looks. `pi-dispatch up` writes both into `.env` for you, as the account
+  default resolved by whoever ran it; if this daemon runs as another account, check it can write there.
+  Keep PI_LOGS_DIR
+  distinct from the StandardOutPath worker.out.log below: the retention sweep would delete it.
 -->
 <plist version="1.0">
 <dict>

package/deploy/docker-compose.yml

@@ -8,23 +8,52 @@
 # stays first-class. The `receiver` profile keeps the container OPT-IN: a plain `up` stays Valkey-only,
 # so worker-on-host deployments that already run the receiver on the host gain no second copy.
 #
-#   docker compose -f deploy/docker-compose.yml up -d                     # start Valkey (default)
-#   docker compose -f deploy/docker-compose.yml --profile receiver up -d  # Valkey + receiver container
-#   pi-dispatch worker                                                    # drain the queue (host)
+#   docker compose --env-file .env -f deploy/docker-compose.yml up -d                     # start Valkey (default)
+#   docker compose --env-file .env -f deploy/docker-compose.yml --profile receiver up -d  # Valkey + receiver container
+#   pi-dispatch worker                                                                    # drain the queue (host)
+#
+# `--env-file .env` (run from the deployment folder) is how compose reads VALKEY_PASSWORD for the Valkey below (issue
+# #468). Without it compose looks for a .env beside THIS file, finds none, and starts Valkey with no password, which
+# any local account can then read and feed; doctor warns about exactly that.
+#
+# On rootful Podman, run the same commands with the real docker CLI pointed at Podman's socket through a docker
+# context (docs/podman.md). Measured with the egress profile on Podman 5.8.2; podman-docker is not the supported route.
+# Measured again on a real host (issue #355): Podman 5.8.1 on Fedora 44 with SELinux enforcing, netavark on nftables
+# and health checks run by systemd timers. The proxy reached healthy with the `z` labels below and no manual help.
+#
+# Why `z` on the single config files below: with SELinux enforcing, a bind mount carries its host label into the
+# container, and a file under a checkout is not container_file_t, so the container may not read it. Measured on
+# Fedora 44, squid crash-looped with "Unable to open configuration file: /etc/squid/squid.conf: (13) Permission
+# denied". `z` (shared, lower case) relabels that one file container_file_t so any container may read it, and is a
+# no-op where SELinux is off. Never `Z`: that label is private to one container, so it would lock the other
+# services out of the same file. The host's own tools, the worker included, run unconfined and still read it.
 
 services:
   valkey:
     image: valkey/valkey:8
-    # AOF on: the wait-list must survive a reboot (REQ-QUEUE-BURST-NO-DROP).
-    command: valkey-server --appendonly yes
-    # Bound to localhost only -- the queue is not a public surface.
+    # 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.
+    environment:
+      VALKEY_PASSWORD: ${VALKEY_PASSWORD:-}
+    # AOF on: the wait-list must survive a reboot (REQ-QUEUE-BURST-NO-DROP). The password reaches valkey-server as
+    # configuration on stdin (`valkey-server -`), written by the shell's own echo builtin to a 0600 temp file that is
+    # opened and deleted before the image's entrypoint runs. `$$` is compose's escape for a literal `$`: the shell in the
+    # container expands these, never compose. The same script as the Quadlet unit and `pi-dispatch up`'s docker run.
+    command: ["sh", "-c", 'set -eu; if [ -n "$${VALKEY_PASSWORD:-}" ]; then umask 077; f=$$(mktemp); echo "requirepass $$VALKEY_PASSWORD" >"$$f"; exec 0<"$$f"; rm -f "$$f"; set -- -; else set --; fi; unset VALKEY_PASSWORD; exec docker-entrypoint.sh valkey-server "$$@" --appendonly yes']
+    # Bound to localhost only -- the queue is not a public surface. On VALKEY_URL's port: PI_VALKEY_PORT, which
+    # `pi-dispatch up` and the setup wizard set from VALKEY_URL when they run this file, and which a deployment on a port
+    # other than 6379 puts in its .env for a compose command run by hand (PR #475's review: the port was 6379 whatever
+    # VALKEY_URL said, so the queue could move away from the worker).
     ports:
-      - "127.0.0.1:6379:6379"
+      - "127.0.0.1:${PI_VALKEY_PORT:-6379}:6379"
     volumes:
       - valkey-data:/data
     restart: unless-stopped
     healthcheck:
-      test: ["CMD", "valkey-cli", "ping"]
+      # Healthy only when Valkey answers PONG to this deployment's password (valkey-cli reads REDISCLI_AUTH from its
+      # environment); a bare `valkey-cli ping` exits 0 on NOAUTH too.
+      test: ["CMD-SHELL", 'if [ -n "$${VALKEY_PASSWORD:-}" ]; then REDISCLI_AUTH="$$VALKEY_PASSWORD"; export REDISCLI_AUTH; fi; valkey-cli ping | grep -q PONG']
       interval: 10s
       timeout: 3s
       retries: 5
@@ -39,7 +68,7 @@ services:
     profiles: ["receiver"]
     image: ghcr.io/edgehero/pi-dispatch-receiver:latest
     # The operator's .env at the repo root, same file the host services read (WEBHOOK_SECRET, github
-    # auth, forge blocks). Compose refuses to start the profile when it is missing -- correctly: a
+    # auth, forge blocks, and VALKEY_PASSWORD, which the receiver sends to the Valkey above). Compose refuses to start the profile when it is missing -- correctly: a
     # receiver without WEBHOOK_SECRET refuses to boot anyway, so fail at the clearer message.
     env_file: ../.env
     # `environment` OVERRIDES env_file, deliberately: a host .env says redis://127.0.0.1:6379, which
@@ -55,7 +84,8 @@ services:
     # invisible in here until the container restarts, and the worker's own pre-spend check is what
     # keeps a spent one-shot from running again in the meantime. A restart picks up the current file.
     volumes:
-      - ../triggers.json:/config/triggers.json:ro
+      # `z` for the SELinux reason at the top of this file: unlabelled, the receiver cannot read it on an enforcing host.
+      - ../triggers.json:/config/triggers.json:ro,z
     # Loopback only, like Valkey's port above: the operator's reverse proxy or tunnel (TLS, public
     # hostname) is what faces the internet -- never this port raw. Assumes the in-container default
     # RECEIVER_PORT=3000; if your .env overrides it, adjust the right-hand side to match.
@@ -70,11 +100,12 @@ services:
   # above: a plain `up` stays Valkey-only, and a deployment that has not turned PI_EGRESS on never needs
   # this service at all.
   #
-  #   docker compose -f deploy/docker-compose.yml --profile egress up -d
+  #   docker compose --env-file .env -f deploy/docker-compose.yml --profile egress up -d
   #
   # It sits on ONE network here, the upstream one. The networks that matter are created by the WORKER, one
   # per job, `--internal`, and this container is attached to each for the life of that job and detached
-  # after (worker/src/egress.mjs). Per-job rather than one shared network because a shared network is a
+  # after (worker/src/egress.mjs), or by the next boot's reaper when a worker died before it could detach
+  # (issue #357). Per-job rather than one shared network because a shared network is a
   # shared L2 segment: at DES-CONCURRENCY-3 that is three mutually-untrusting issue authors who can reach
   # each other. `enable_icc=false` cannot fix that -- ICC governs every container pair on the bridge and
   # this proxy is a container, so it would block the very path the design depends on.
@@ -95,12 +126,14 @@ services:
     # name and the two literals would disagree -- silently, and only on a deployment that renamed nothing.
     container_name: pi-dispatch-egress-proxy
     volumes:
-      # The RULES, shipped and not edited. Relative paths resolve against THIS FILE's directory.
-      - ./egress-proxy.conf:/etc/squid/squid.conf:ro
+      # The RULES, shipped and not edited. Relative paths resolve against THIS FILE's directory. Both mounts
+      # here carry `z` for the SELinux reason at the top of this file: without it squid crash-loops on an
+      # enforcing host, unable to open its own configuration.
+      - ./egress-proxy.conf:/etc/squid/squid.conf:ro,z
       # The LIST, yours. `pi-dispatch init` scaffolds it next to your .env; it is create-only, so a re-run
       # never clobbers an edited allowlist. Mounting a path that does not exist makes Docker create it as a
       # DIRECTORY and squid then fails confusingly, which is why init writes it first.
-      - ../egress-allowlist.conf:/etc/pi-dispatch/allowlist.conf:ro
+      - ../egress-allowlist.conf:/etc/pi-dispatch/allowlist.conf:ro,z
     networks:
       - egress-out
     restart: unless-stopped
@@ -121,7 +154,7 @@ services:
 
 networks:
   # The proxy's route out. Only the proxy is ever on it: job containers live on their own per-job
-  # `--internal` networks, which have no route anywhere except to this container.
+  # `--internal` networks, whose only other member is this container and which have no route off this host.
   egress-out:
     name: pi-dispatch-egress-out
 

package/deploy/egress-proxy.conf

@@ -7,7 +7,8 @@
 #
 # What this policy is, and is not:
 #   - Hostname filtering on CONNECT, to port 443 only. The provider, the forge and the registry are
-#     ordinary entries in the allowlist; there is no address-based rule anywhere and nothing is special.
+#     ordinary entries in the allowlist, and nothing is special. The one address-based rule is a DENY:
+#     a listed name that resolves to a fixed loopback or link-local address of this host is refused.
 #   - TLS is NEVER terminated. This proxy sees the name a client asks for and no byte inside the tunnel,
 #     so it cannot read a credential and cannot account for a token. A proxy that decrypts provider
 #     traffic is OQ-011's mechanism, a materially larger change, and it is not this.
@@ -20,12 +21,41 @@
 http_port 3128
 
 # The operator's list. Bare hostnames, one per line; a leading dot matches subdomains (.github.com).
-acl allowed dstdomain "/etc/pi-dispatch/allowlist.conf"
+# `-n` (issue #428): without it squid answers an IP-literal request (CONNECT 93.184.215.14:443, or an
+# IPv6 literal) that matches no entry by a REVERSE lookup of that address, and matches the name it
+# gets back (measured: a PTR query per literal, then 403). A job choosing the address chooses whose
+# reverse zone is asked, which is a DNS channel out. With `-n` no lookup is made: the request's host
+# is compared as written, so a literal is still refused unless the list names that literal itself.
+acl allowed dstdomain -n "/etc/pi-dispatch/allowlist.conf"
 
 acl SSL_ports port 443
 acl CONNECT method CONNECT
 
+# The host's own services, by address (issue #428). On rootless Podman an account's containers.conf
+# (pasta_options such as --map-host-loopback 169.254.1.2, or slirp4netns's allow_host_loopback=true,
+# which answers on 10.0.2.2) gives the network this proxy sits on the host's 127.0.0.1 services, the
+# job queue's Valkey among them, and a name in the allowlist that resolves (or is rebound) to one of
+# these addresses would then reach them on a job's behalf. 0.0.0.0 and :: are loopback too on Linux.
+# 10.0.2.2 is slirp4netns's host alias and only means the host there; elsewhere it is an ordinary
+# private address, and an allowlisted service that really lives at it is refused (move it, or drop
+# this entry in a copy you maintain).
+# DEFENCE IN DEPTH, not the closure, and only for the FIXED addresses: the host can be mapped to any
+# address (--map-host-loopback <address>, slirp4netns's cidr=, and --map-gw, which uses the default
+# gateway's), and no fixed rule names those. The closure is the worker's: its podman venue refuses
+# every job while the account's containers.conf sets pasta_options, network_cmd_options, annotations
+# or env. That refusal reads the conf, not the live network: after a key is removed, a proxy started
+# under the old conf keeps the old options until the account's containers on a bridge network restart,
+# which the refusal's own text tells the operator to do.
+acl to_host_local dst 127.0.0.0/8 0.0.0.0/32 169.254.0.0/16 10.0.2.2/32 ::1 ::/128 fe80::/10
+
 # Order is the design, not a detail. Read top to bottom, first match wins.
+# The deny names `allowed` FIRST, and that order is load-bearing: squid evaluates an http_access line's
+# ACLs left to right and stops at the first that does not match, and `dst` resolves the requested name.
+# A bare `deny to_host_local` resolved EVERY name a job asked for, listed or not (measured with
+# debug_options 78,3: a CONNECT to an unlisted name sent a DNS query, where without the rule it sent
+# none), which is a DNS channel out of an egress-armed job. With `allowed` first, only a listed name
+# is ever resolved here, and it is the only kind the allows below could let through anyway.
+http_access deny allowed to_host_local
 http_access deny CONNECT !SSL_ports
 http_access allow CONNECT allowed
 http_access allow allowed

package/deploy/nssm-install.cmd

@@ -20,13 +20,19 @@ REM multiple services. Requires the AOF-enabled Valkey from deploy/docker-compos
 REM
 REM Per-host PLACEHOLDERS: set SERVICE / REPO / LOGDIR below for your host before running.
 REM
-REM PI_LOGS_DIR (run-history records; default OS-temp \pi-dispatch\logs) is created and written by the
-REM worker at boot, so it must be writable by the service account. Set via `.env` (the wrapper), not a
-REM change here; its default avoids colliding with the nssm LOGDIR worker.out log set below.
+REM PI_LOGS_DIR (run-history records) and PI_SETTINGS_FILE (the settings overlay) default to
+REM %USERPROFILE%\.pi-dispatch, which is DURABLE across a reboot. Both are created and written by the
+REM worker at boot, so they must be writable by the service account.
 REM
-REM PI_SETTINGS_FILE is the runtime-tunable settings overlay (default under OS temp, which may be wiped
-REM on reboot) -- point it at a durable path in production. Set via `.env` (the wrapper), not a change
-REM here; it is worker-owned and never belongs in the container env allowlist.
+REM SET BOTH EXPLICITLY via `.env` (the wrapper), not a change here. The default is per USER, and a
+REM service running as LocalSystem resolves it under the system profile, not yours -- so the worker and
+REM your /dispatch panel would read different directories, the run list would show nothing, and caps set
+REM from the panel would land where the worker never looks. `pi-dispatch up` writes both into `.env`,
+REM as the account default resolved by whoever ran it; a service running as LocalSystem is very likely
+REM NOT that account, so check it can write there.
+REM Keep PI_LOGS_DIR away from the nssm LOGDIR worker.out log set below: the retention sweep deletes
+REM every .log and .json past its window. Both are worker-owned and never belong in the container env
+REM allowlist.
 
 setlocal
 

package/deploy/pi-dispatch-egress-out.network

@@ -0,0 +1,10 @@
+# Quadlet network for the egress proxy's route out on the native rootless `podman` venue (issue #430,
+# docs/podman.md): the compose file's `egress-out` network, named exactly as there.
+#
+# Installed with pi-dispatch-egress-proxy.container, only while the egress policy is armed. Podman's generator turns
+# it into pi-dispatch-egress-out-network.service, which the proxy's unit requires. NetworkName= gives the network
+# exactly this name (measured on Podman 5.8.1). Only the proxy is ever on it: job containers live on their own
+# per-job `--internal` networks, which the WORKER creates and attaches the proxy to by name.
+
+[Network]
+NetworkName=pi-dispatch-egress-out

package/deploy/pi-dispatch-egress-proxy.container

@@ -0,0 +1,50 @@
+# Quadlet unit for the egress policy's allowlist proxy on the native rootless `podman` venue (REQ-EGRESS-ALLOWLIST,
+# issue #430, docs/podman.md): deploy/docker-compose.yml's `egress-proxy` service, for a host whose jobs run under
+# this account's own rootless Podman.
+#
+# Installed by `pi-dispatch service install` (user scope, with podman in PI_BACKENDS and PI_EGRESS armed) and by
+# `pi-dispatch up`. Unlike the Valkey unit this one is RENDERED: the two /opt/pi-dispatch paths below are
+# placeholders, replaced with an account-owned copy of the package's egress-proxy.conf (written beside this account's
+# config, because `z` cannot relabel a root-owned package file: measured, exit 126) and with the deployment folder's
+# egress-allowlist.conf. Never `systemctl --user enable` it (a generated unit refuses that); the [Install] section is
+# read by the generator itself.
+#
+# A RESTART DROPS EVERY PER-JOB NETWORK (measured on Podman 5.8.1). The generated unit runs `podman run --replace
+# --rm`, so `systemctl --user restart` makes a NEW container, and the per-job `--internal` networks the worker had
+# connected to the old one are gone from it. A job started afterwards connects the new proxy at its start and is
+# fine; a job already running when the proxy restarts has lost its only route out for the rest of that run.
+#
+# A STOP TAKES 10 s: squid does not exit on SIGTERM, so systemd waits out podman's stop timeout, kills it, and the
+# unit ends `failed` with exit 137 (measured). Harmless; `pi-dispatch service uninstall` clears the failed state.
+
+[Unit]
+Description=pi-dispatch egress allowlist proxy (rootless Podman, Quadlet)
+
+[Container]
+# The compose file's digest, fully qualified. A test holds the two equal: this container IS the allowlist, so a
+# digest bumped in one file only would give the two venues two different policies.
+Image=docker.io/ubuntu/squid@sha256:6a097f68bae708cedbabd6188d68c7e2e7a38cedd05a176e1cc0ba29e3bbe029
+# The name the worker attaches to each job network. A deployment that sets PI_EGRESS_PROXY to another name runs its
+# own proxy, and neither `service install` nor `up` installs this unit for it: `--replace` would otherwise remove
+# whatever container of that name the operator runs.
+ContainerName=pi-dispatch-egress-proxy
+Network=pi-dispatch-egress-out.network
+# The RULES (shipped) and the LIST (yours). `z` for the SELinux reason the compose file records: unlabelled, squid
+# cannot read its own configuration on an enforcing host and crash-loops. Shared `z`, never private `Z`, as there:
+# on a host that also runs the compose proxy the same allowlist file is mounted by both.
+Volume=/opt/pi-dispatch/deploy/egress-proxy.conf:/etc/squid/squid.conf:ro,z
+Volume=/opt/pi-dispatch/egress-allowlist.conf:/etc/pi-dispatch/allowlist.conf:ro,z
+# The exec form, a JSON array, for the reason the compose file gives: a plain string runs under /bin/sh, which on
+# this image is dash, where /dev/tcp does not exist and the check would fail forever while squid serves.
+HealthCmd=["bash", "-c", "exec 3<>/dev/tcp/127.0.0.1/3128"]
+HealthInterval=30s
+HealthTimeout=3s
+HealthRetries=3
+HealthStartPeriod=10s
+
+[Service]
+TimeoutStartSec=900
+Restart=on-failure
+
+[Install]
+WantedBy=default.target

package/deploy/pi-dispatch-netns-keeper.container

@@ -0,0 +1,80 @@
+# Quadlet unit for the rootless network keeper on the native rootless `podman` venue (issue #458, docs/podman.md):
+# one idle container that holds this account's shared rootless network helper open, so the egress proxy keeps its
+# route out after a job's network is torn down.
+#
+# WHY IT EXISTS. On Podman 4.9 (Ubuntu 24.04's), `podman network disconnect` of the proxy from a per-job network
+# tears down the account's shared rootless network namespace and its slirp4netns WHILE THE PROXY STILL RUNS, whenever
+# no other running container is on a bridge network: v4.9.3's libpod/networking_linux.go counts the disconnecting
+# container as the caller and cleans up at one. The next bridge container then starts a new namespace, the proxy's
+# eth0 goes with the old one, and every later egress job gets 503 from the proxy until it restarts (measured: job 1
+# 200, jobs 2 to 5 503). Podman 5.0's rootless network rewrite (containers/podman#20772, containers/common#1761)
+# counts attachments instead, and 5.8.1 was measured unaffected. With this container running on a bridge network of
+# its own, 4.9.3 gave 5 sequential egress jobs 200 each, and the two-network teardown `doctor --live` does stayed
+# clean. It is installed on every Podman version, because on 5.x it is one idle container and nothing else
+# (measured harmless on 5.8.1), and one rule is simpler than a version read at install time.
+#
+# Installed by `pi-dispatch service install` (user scope, with podman in PI_BACKENDS and PI_EGRESS armed) and by
+# `pi-dispatch up`, which copy it unchanged into ~/.config/containers/systemd/. Never `systemctl --user enable` it
+# (a generated unit refuses that); the [Install] section is read by the generator itself.
+#
+# IT MUST STAY RUNNING: it protects only while it runs. Stopped, the next job teardown breaks the proxy again (measured).
+#
+# IT WIDENS NOTHING. No published port, no mount, no capability, a read-only root, no new privileges, the nobody
+# uid, and a network with no route out and no DNS: inside it, the proxy and 1.1.1.1 were both unreachable (measured).
+
+[Unit]
+Description=pi-dispatch rootless network keeper (holds this account's rootless netns open; rootless Podman, Quadlet)
+# No start limit: with Restart=always a keeper that cannot start (its network pruned, say) would otherwise use up
+# systemd's default 5 starts in 10 s and stay `failed` for good. Measured on 4.9.3: the generator passes this through,
+# 10 quick kills in a row and 15 s of a keeper that could not start never ended `failed`.
+StartLimitIntervalSec=0
+
+[Container]
+# The proxy's own image and digest, so this unit pulls nothing the egress stack has not already pulled and adds no
+# pin to keep in step: it only runs `sleep`, which the image has. A test holds the digest equal to the proxy's.
+Image=docker.io/ubuntu/squid@sha256:6a097f68bae708cedbabd6188d68c7e2e7a38cedd05a176e1cc0ba29e3bbe029
+# Outside every prefix a pi-dispatch sweep removes (pi-job-, pi-sandbox-, pi-dispatch-live-, pi-dispatch-egress-doctor-,
+# pi-dispatch-egress-probe-): a test holds that, since a sweep that removed it would bring the defect back unseen.
+ContainerName=pi-dispatch-netns-keeper
+# Its OWN network, never the proxy's or a job's: it has to be a running member of SOME bridge network, and on one of
+# its own it is reachable from nothing.
+Network=pi-dispatch-netns-keeper.network
+ReadOnly=true
+DropCapability=all
+NoNewPrivileges=true
+User=65534
+Group=65534
+# catatonit as PID 1 (`--init`), so a stop ends `sleep` at once rather than after podman's 10 s timeout (measured on
+# 4.9.3: 123 ms); a job's argv carries the same flag, so the venue already needs catatonit.
+RunInit=true
+# Two spellings Quadlet 4.9 has no key for. `--entrypoint=sleep` with `Exec=infinity`: 4.9.3's generator refuses an
+# `Entrypoint=` key ("unsupported key", measured), and a JSON array in PodmanArgs (`--entrypoint=["sleep","infinity"]`)
+# came through as `--entrypoint=[sleep,infinity]`, which catatonit could not exec (measured). `--image-volume=ignore`:
+# the squid image declares VOLUMEs, which would otherwise make two anonymous volumes on every start.
+PodmanArgs=--entrypoint=sleep --image-volume=ignore
+Exec=infinity
+
+[Service]
+TimeoutStartSec=900
+# Its network, made again before every start, with exactly the flags its .network unit's own `podman network create`
+# carries (--ignore makes it a no-op while the network exists). That unit runs once and stays `active`, so without
+# this a network pruned (or removed) under a stopped keeper kept every later start failing until someone restarted
+# both units by hand; measured on 4.9.3, with this line a start after `podman network prune` recreated the network
+# (internal, no DNS) and the keeper came up.
+ExecStartPre=/usr/bin/podman network create --ignore --disable-dns --internal pi-dispatch-netns-keeper
+# always, not the proxy's on-failure: a keeper that is not running is the whole defect, and `sleep infinity` never
+# exits on its own, so any exit at all is one to undo. An explicit `systemctl --user stop` still stops it; a `podman
+# stop` or `podman rm -f` behind systemd's back does not (measured: it is running again after RestartSec).
+Restart=always
+# One second, not systemd's 100 ms default, so a keeper that cannot start retries at a calm pace (the start limit is
+# off above). Measured on 4.9.3: back on its bridge network 1.2 to 1.3 s after a kill; 250 ms gave 0.45 s, and was not
+# taken, because a keeper that came back more than the grace (15 s) after the proxy started is already treated as
+# damage by the worker and doctor (a proxy restart is asked for, whatever the gap), so a shorter gap buys nothing there, and a
+# keeper that cannot start would retry four times a second.
+RestartSec=1s
+# A stop ends `sleep` with SIGTERM, which the unit sees as exit 143 and, without this line, as a failure (measured on
+# Podman 4.9.3: every clean `systemctl --user stop` left the unit `failed`).
+SuccessExitStatus=143
+
+[Install]
+WantedBy=default.target

package/deploy/pi-dispatch-netns-keeper.network

@@ -0,0 +1,18 @@
+# Quadlet network for the rootless network keeper on the native rootless `podman` venue (issue #458,
+# docs/podman.md): a network of the keeper's OWN, with nothing else ever on it.
+#
+# Installed with pi-dispatch-netns-keeper.container, while the egress policy is armed. Podman's generator turns it
+# into pi-dispatch-netns-keeper-network.service, which the keeper's unit requires. Internal= gives it no route out
+# and DisableDNS= no aardvark-dns entry, so the one container on it can reach nothing at all, not even the proxy:
+# jobs live on their own per-job `--internal` networks, which have no route to this subnet.
+#
+# NEVER REMOVE IT. Measured on Podman 4.9.3: `podman network rm -f` of this network kills the keeper, and a `podman
+# network prune` or `podman system prune` run while the keeper is stopped removes it (with the keeper running, both
+# leave it). Either way the keeper's unit cannot start again while this network's unit stays `active` (it ran once and
+# exited), until `systemctl --user reset-failed` and a restart of both units. Its name is outside every prefix a
+# pi-dispatch sweep removes.
+
+[Network]
+NetworkName=pi-dispatch-netns-keeper
+Internal=true
+DisableDNS=true

package/deploy/pi-dispatch-valkey.container

@@ -0,0 +1,51 @@
+# Quadlet unit for Valkey on the native rootless `podman` venue (issue #430, docs/podman.md): the same component
+# deploy/docker-compose.yml's `valkey` service and `pi-dispatch up`'s docker path start, for a host that runs jobs
+# under this account's own rootless Podman instead of a docker daemon.
+#
+# Installed by `pi-dispatch service install` (user scope, with podman in PI_BACKENDS) and by `pi-dispatch up`, which
+# copy it into ~/.config/containers/systemd/ unchanged but for a VALKEY_URL port other than 6379, with the password
+# file it reads beside it. Podman's systemd generator turns it into
+# pi-dispatch-valkey.service. Never `systemctl --user enable` it: a generated unit refuses that ("transient or
+# generated"); the [Install] section below is read by the generator itself, which links it into default.target
+# (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.
+
+[Unit]
+Description=pi-dispatch Valkey (the job queue; rootless Podman, Quadlet)
+
+[Container]
+Image=docker.io/valkey/valkey:8
+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
+# Bound to localhost only, as in the compose file: the queue is not a public surface. The worker reaches it at
+# redis://127.0.0.1:6379, the default VALKEY_URL.
+PublishPort=127.0.0.1:6379:6379
+# The same named volume `pi-dispatch up` creates on docker, so the wait-list survives a restart and a reboot.
+Volume=pi-dispatch-valkey-data:/data
+# The password (issue #468): VALKEY_PASSWORD from a 0600 file `service install` and `up` write from the deployment's
+# .env, into the container's ENVIRONMENT. Never `--requirepass` on a command line: the image's PID 1 is tini, which keeps
+# its whole argv for the life of the container, and any account on the host reads it in /proc/<pid>/cmdline (measured
+# on Podman 5.8.1 and 4.9.3). Quadlet also loads this file into the unit's own environment, where systemd would expand a
+# bare $VALKEY_PASSWORD in the command below into the password itself: every $ below is written $$ for that reason.
+EnvironmentFile=%h/.config/pi-dispatch/valkey.env
+# AOF on: the wait-list must survive a reboot (REQ-QUEUE-BURST-NO-DROP). The password reaches valkey-server as
+# configuration on stdin (`valkey-server -`), written by the shell's own echo builtin to a 0600 temp file that is opened
+# and deleted before the image's entrypoint runs; with VALKEY_PASSWORD empty it starts with none, as before.
+Exec=sh -c 'set -eu; if [ -n "$${VALKEY_PASSWORD:-}" ]; then umask 077; f=$$(mktemp); echo "requirepass $$VALKEY_PASSWORD" >"$$f"; exec 0<"$$f"; rm -f "$$f"; set -- -; else set --; fi; unset VALKEY_PASSWORD; exec docker-entrypoint.sh valkey-server "$$@" --appendonly yes'
+# Healthy only when Valkey answers PONG to this deployment's password (valkey-cli reads REDISCLI_AUTH from its
+# environment); a bare `valkey-cli ping` exits 0 on NOAUTH too.
+HealthCmd=if [ -n "$${VALKEY_PASSWORD:-}" ]; then REDISCLI_AUTH="$$VALKEY_PASSWORD"; export REDISCLI_AUTH; fi; valkey-cli ping | grep -q PONG
+HealthInterval=10s
+HealthTimeout=3s
+HealthRetries=5
+
+[Service]
+# The first start pulls the image, which can outlast systemd's default 90 s start timeout on a slow link.
+TimeoutStartSec=900
+Restart=on-failure
+
+[Install]
+WantedBy=default.target

package/deploy/pi-dispatch-valkey.network

@@ -0,0 +1,16 @@
+# Quadlet network for Valkey on the native rootless `podman` venue (issue #430, docs/podman.md).
+#
+# `pi-dispatch service install` (user scope, with podman in PI_BACKENDS) and `pi-dispatch up` copy this file
+# unchanged into ~/.config/containers/systemd/, where Podman's systemd generator turns it into
+# pi-dispatch-valkey-network.service. NetworkName= gives the network exactly this name, with no `systemd-` prefix
+# (measured on Podman 5.8.1).
+#
+# Why Valkey gets a bridge network of its own rather than no Network= at all: a containers.conf that sets
+# `netns = "host"` puts a container started WITHOUT a network option into the host's network namespace (measured),
+# where the port mapping below means nothing and Valkey would listen on every host interface. An explicit Network=
+# is the only thing that wins over that key. `Network=pasta` would also win, but Podman 4.9 (Ubuntu 24.04) defaults
+# to slirp4netns and ships without passt on some hosts, so a named bridge is the one spelling both 4.9 and 5.x run.
+# Its own network, not the proxy's: nothing on the egress side has any business reaching the queue.
+
+[Network]
+NetworkName=pi-dispatch-valkey

package/deploy/receiver.service

@@ -23,6 +23,12 @@ Wants=network-online.target
 # trying. The worker unit has carried this since it shipped; the receiver did not, and the gap is not
 # cosmetic -- the receiver is the process that dies on a triggers file it cannot parse, and it dies on
 # EVERY start. Pairs with Restart=on-failure below.
+#
+# This bounds CRASH loops (a process dying in milliseconds), not transient outages (issue #318): a
+# transient identity failure at boot retries INSIDE the process for RECEIVER_IDENTITY_RETRY_SECONDS
+# (default 600, floored at 60 -- see .env.example) before exiting 1, so a retrying boot exits at most
+# once per window and can never place StartLimitBurst starts inside this interval. Keep these values
+# and widen the env key instead: raising the burst here would only re-open the crash-loop hole.
 StartLimitIntervalSec=60
 StartLimitBurst=5
 

package/deploy/worker-env-wrapper.cmd

@@ -46,8 +46,18 @@ REM loaded, on purpose: the path is SERVICE configuration, and a `.env` line mus
 REM a script this wrapper then runs.
 set "ENV_SETUP=%PI_ENV_SETUP%"
 
+REM NOTHING THIS WRAPPER READS IS LEFT WHERE .env CAN ASSIGN IT (issue #470). Every .env line is a `set`, and
+REM set ignores case, so an `ENV_SETUP=` (or `env_setup=`) line replaced the copy above and named a script
+REM this wrapper then ran, and an `ERRORLEVEL=` line shadows the dynamic %ERRORLEVEL% (`set /?`: a variable
+REM defined under one of those names overrides it), so the exit-code conversion below would read the file's
+REM number. So after the load the wrapper re-asserts its own: ENV_SETUP and PI_ENV_SETUP from
+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.
 if exist ".env" (
   for /f "usebackq eol=# tokens=1,* delims==" %%A in (".env") do set "%%A=%%B"
+  set "ENV_SETUP=%PI_ENV_SETUP%"
+  set "PI_ENV_SETUP=%PI_ENV_SETUP%"
 ) else (
   if not defined ENV_SETUP (
     echo worker-env-wrapper: .env not found in "%CD%" -- this wrapper must be started in the deployment folder, the service's nssm AppDirectory; it no longer guesses a location from its own path 1>&2
@@ -82,6 +92,7 @@ REM closed.
 REM
 REM The argv runs verbatim -- absolute node, absolute script, composed by `pi-dispatch service` (see
 REM the .sh twin for the whole contract).
+set "ERRORLEVEL="
 %*
 set "RC=%ERRORLEVEL%"