@edgehero/pi-dispatch 0.1.0

package/.env.example

@@ -0,0 +1,160 @@
+# Copy to .env and fill in. Never commit a real .env (it is gitignored).
+
+# --- Provider credential ---
+# pi supports ~30 providers; set the key for the one you use, under the variable name pi expects.
+# The worker forwards ONLY the configured provider's key into the job container -- nothing else.
+#   Anthropic: ANTHROPIC_API_KEY  (or ANTHROPIC_OAUTH_TOKEN, which takes precedence)
+#   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).
+ANTHROPIC_API_KEY=
+# PI_AUTH_FROM_PI=0   # uncomment to force env-only (fail loudly on a missing env key instead of using your pi login)
+
+# --- Which provider/model to run by default (override per job with --provider / --model) ---
+PI_PROVIDER=anthropic
+# A DATED model id is deterministic; a floating alias (e.g. claude-sonnet-4-5) can change cost.
+PI_MODEL=claude-sonnet-4-5-20250929
+
+# --- Spend + concurrency guards (money bounds; all have conservative defaults) ---
+PI_MAX_TURNS=30        # per-job turn cap -- pi has none of its own, so the harness imposes one
+PI_DAILY_CAP=25        # max job containers started per day (mandatory window)
+# PI_WEEKLY_CAP=100    # optional weekly ceiling on container starts; unset = weekly window disabled
+# PI_MONTHLY_CAP=400   # optional monthly ceiling on container starts; unset = monthly window disabled
+# PI_SOFT_HOLD_PCT=80  # optional soft-hold band (1-99): once any window hits this % of its cap, new starts
+                       # pause (in-flight jobs finish) and the panel meter turns amber; unset = disabled
+# PI_MAX_TOKENS=       # optional per-job token budget: the runner aborts the agent once cumulative usage exceeds it.
+                       # LAGGING (spends before it can see the total) -- a single-job runaway backstop, not before-the-spend;
+                       # PI_MAX_TURNS stays the proactive lever. Unset = per-job token budget disabled (usage is still recorded).
+# PI_DAILY_TOKEN_CAP=  # optional daily token cap: once a day's recorded spend reaches it, the NEXT job is refused pre-container.
+                       # Check-AFTER by nature (token cost is only known post-run), unlike PI_DAILY_CAP; unset = disabled
+PI_CONCURRENCY=3       # how many jobs run in parallel
+
+# --- Infrastructure ---
+VALKEY_URL=redis://127.0.0.1:6379
+PI_JOB_IMAGE=pi-job:latest          # the DEFAULT job image. Any trigger may name its own with "image" in triggers.json (docs/job-image.md)
+                                    # Jobs run with --pull=never: pull or BUILD every image you name -- the worker never fetches one at job time, and doctor checks presence
+                                    # docker pull ghcr.io/edgehero/pi-job:latest && docker tag ghcr.io/edgehero/pi-job:latest pi-job:latest  (or build image/Dockerfile)
+# PI_JOBS_DIR=                      # where per-job /job inputs live (default: your OS temp dir)
+# PI_LOGS_DIR=                      # where per-job status records (and optional raw logs) land (default: OS temp /pi-dispatch/logs)
+# PI_CAPTURE_JOB_LOGS=              # 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_LOG_RETENTION_DAYS=            # default 30; boot-time prune of logs older than N days; 0 = keep forever
+# PI_SANDBOX_DIR=                   # 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_RETENTION_HOURS=       # 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
+# PI_SANDBOX_PIN_DAYS=              # default 7; `pi-dispatch sandbox <jobId> --pin` extends THAT run to now + this many days. Still swept afterwards
+# PI_SANDBOX_IDLE_MINUTES=          # default 30; bash's own TMOUT inside a sandbox, so a forgotten shell closes itself; 0 = no idle logout
+#                                     Honest gap: TMOUT does not tick while a foreground command runs, so a sandbox left serving an app stays up (`pi-dispatch sandbox --list` finds it)
+# PI_SESSIONS_DIR=                  # NO DEFAULT, on purpose. Where persisted agent transcripts live, so a trigger with "resume": true can continue the session that opened the PR (docs/sessions.md)
+                                    # Unset = the feature is unavailable and an armed trigger refuses PRE-SPEND rather than running unpersisted and looking like it worked
+                                    # A transcript is the most PII-bearing thing this system stores -- issue text, file contents, tool output, the agent's own reasoning. Mode 0700, host-only, OUTSIDE any git repo
+                                    # Deliberately not defaulted into the OS temp dir the way PI_LOGS_DIR is: that is mode 1777 on POSIX
+# PI_SESSIONS_TTL_DAYS=             # default 14; a transcript older than this is not resumed AND is swept at boot; 0 = keep forever
+                                    # Enforced at OPEN as well as at boot: a stale transcript is a live input to a future job, not debris
+# PI_SESSION_MAX_BYTES=             # default 8388608 (8 MiB); a transcript larger than this is not resumed; 0 = no cap
+                                    # Not disk hygiene -- an oversized transcript is a prefill nobody sized PI_MAX_TOKENS for
+# PI_SESSIONS_ALLOW_GH_SOURCE=      # unset = a run.resume job REFUSES to mint under GITHUB_AUTH_SOURCE=gh, pre-spend
+                                    # 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)
+                                    # Not disk hygiene -- an oversized transcript is a prefill nobody sized PI_MAX_TOKENS for
+# PI_TRIGGERS_FILE=                 # 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)
+# PI_PAUSE_WINDOWS_FILE=            # ABSOLUTE path to pause-windows.json — "quiet hours" per folder/repo (pause runs between certain times/days/dates, auto-resume). Unset = feature off. See docs/pause-windows.md
+# PI_SUBSCRIPTIONS_FILE=            # path to subscriptions.json — operator-declared subscription plan prices (the admin defaults to ./subscriptions.json in its working directory). Read by the ADMIN EXTENSION only, never at job time.
+                                    # Subscription-backed providers bill 0 per run (their rate tables are all zeros), so this file is where the real price lives — cost analytics only; it changes no routing, auth, or job behavior
+# PI_SETTINGS_FILE=                 # ABSOLUTE path to the runtime settings overlay (default: OS temp /pi-dispatch/settings.json); edited by the admin extension, read by the worker per job
+
+# --- Reuse your existing pi setup in every job (see docs/global-pi-overlay.md) ---
+# PI_GLOBAL_PI_DIR=                  # 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
+# PI_GLOBAL_ALLOW_EXTENSIONS=       # the overlay's extensions LOAD by default (staging them with import-pi, which prints each one, is the vetting step). Set exactly 0 to keep them staged but dormant.
+                                    # Unset, empty and the legacy 1 all mean LOAD. ANY other value refuses to boot -- a typo must never silently leave code running against adversarial input with open egress.
+                                    # This knob covers the OVERLAY only. A serviced repo's own /workspace/.pi/extensions load regardless (they are default-branch, merge-gated) -- see SECURITY.md.
+# PI_PACKAGES_FILE=                 # path to pi-packages.json (default: ./pi-packages.json; --packages-file wins). Read ONLY by `pi-dispatch import-pi --with-packages`, never at job time.
+                                    # Staged packages/ rides INSIDE PI_GLOBAL_PI_DIR -- no separate mount, no separate env dir -- and loads for EVERY job once staged; decline it PER TRIGGER with "packages": false in triggers.json, NOT by an env flag.
+                                    # Versions must be EXACT (no ^ ~ * or latest); staging uses --ignore-scripts, so a package needing a build step is staged INCOMPLETE and import-pi warns.
+# PI_FORWARD_ENV=                   # comma-separated extra env var NAMES to forward into the container (e.g. a CUSTOM provider's key). Explicit allowlist, not a pass-through.
+                                    # GITHUB_TOKEN/GH_TOKEN are refused here -- the worker mints per-job tokens
+
+PI_SCHEDULER_STALL_MAX=2            # tear down a scheduler after N consecutive stalls (money backstop)
+# PI_DISPATCH_RUN_ROOTS=            # OS-path-delimited allowlist (; on Windows, : elsewhere) of folders the model-callable dispatch_run may target; default empty = fail-closed (dispatch_run refuses every folder until you opt in)
+# PI_DISPATCH_RUN_PER_HOUR=3       # per-hour cap on model-invoked dispatch_run enqueues; 0 disables the tool
+# PI_DISPATCH_ASCII=               # set 1 to render the admin extension's views with plain ASCII instead of box-drawing/sparkline-ramp glyphs (for glyph-width-hostile terminals); read at extension load
+# PI_CHAIN_DEPTH_MAX=1             # max follow-up chain depth from a job's /outbox; 0 = chaining kill-switch
+# PI_CHAIN_MAX_PER_JOB=2           # max request-<n>.json collected per completed job
+
+# --- GitHub trigger (receiver + worker auth) ---
+# Webhook receiver
+WEBHOOK_SECRET=
+RECEIVER_PORT=3000
+RECEIVER_BIND=0.0.0.0
+# Worker GitHub auth: source is gh | pat | app (default gh)
+# gh = your full login scopes reach token-carrying jobs (doctor warns and names them); pat/app = narrower
+GITHUB_AUTH_SOURCE=gh
+# For GITHUB_AUTH_SOURCE=pat: a repo-scoped, short-expiry fine-grained PAT
+GITHUB_PAT=
+# For GITHUB_AUTH_SOURCE=app (optional; required for multi-tenant)
+# `pi-dispatch setup github` fills all three in one browser click (App Manifest flow) and writes the PEM 0600
+GITHUB_APP_ID=
+GITHUB_APP_INSTALLATION_ID=
+GITHUB_APP_PRIVATE_KEY_PATH=
+
+# --- GitLab trigger (receiver + worker auth) ---
+# Optional. Set these only to service GitLab projects; leaving GITLAB_TOKEN unset means no /gitlab
+# endpoint exists at all, rather than one that answers 401. See docs/gitlab.md.
+#
+# A PROJECT access token with the `api` scope and the Developer role or above. `api` is the narrowest
+# scope that can post a note -- GitLab offers no contents-vs-issues split -- so scope it to one project
+# and rotate it (CONST-TOKEN-SCOPED-PER-JOB). A GROUP token reaches every project in the group.
+GITLAB_TOKEN=
+# Your instance root. Only for self-hosted GitLab.
+GITLAB_URL=https://gitlab.com
+# How the receiver verifies a delivery. REQUIRED once any GITLAB_* variable is set, and deliberately not
+# defaulted -- the two are not equally strong, so it must be a choice somebody made:
+#   signature  HMAC-SHA256 over the body. Needs GitLab 19.0+. Use this if you can.
+#   token      a shared-secret compare. Works on any version, and proves nothing about the body.
+GITLAB_WEBHOOK_MODE=
+# The signing token (signature mode) or the secret token (token mode) from the webhook's settings.
+GITLAB_WEBHOOK_SECRET=
+
+# --- Forgejo / Gitea trigger (receiver + worker auth) --- issue #61
+# Forgejo's webhook transport is byte-compatible with GitHub's (HMAC-SHA256 over the raw body,
+# X-Hub-Signature-256), so there is no mode to choose here: there is one mechanism and it is the strong one.
+# Point the webhook at /forgejo -- NOT at / -- because Forgejo also sends X-GitHub-* headers, so the path is
+# the only thing that can tell the two apart, and a sender must never choose which gate it faces.
+FORGEJO_URL=
+# A REPOSITORY-scoped token ("Specific repositories") carrying only write:repository and write:issue.
+# Narrower than GitLab's equivalent -- Forgejo has no all-or-nothing `api` scope. What it cannot do is
+# expire: there is no App or installation token, so rotation is the whole mitigation
+# (CONST-TOKEN-SCOPED-PER-JOB).
+FORGEJO_TOKEN=
+# The harness account's NUMERIC id. Required when the token above is repository-scoped, because such a
+# token may not carry read:user and therefore cannot call GET /user. The receiver refuses to boot without an
+# identity from one source or the other: the bot-loop guard compares against it, and an unresolved identity
+# never matches -- so it would fail open silently and the harness's own comments would start more jobs.
+FORGEJO_BOT_ID=
+FORGEJO_WEBHOOK_SECRET=
+
+# --- Azure DevOps trigger (receiver + worker auth) --- issue #43
+# READ docs/azure-devops.md BEFORE ENABLING. Azure Service Hooks offer no HMAC of any kind: the credential
+# proves the sender knew a secret and covers no bytes, there is no delivery-id header (the dedup key comes
+# from the body), and there is no signed timestamp and so no replay window. OQ-015 records the residual.
+# HTTPS is not optional here -- over plain HTTP the credential is on the wire in base64.
+AZURE_ORG_URL=
+# A PAT for a DEDICATED identity. Azure gives you a real expiry and cannot scope below the organization
+# (vso.code_write reaches every repo in the org), so the bound comes from that identity's per-repository
+# permissions in Project Settings -- not from the token's scopes. It also needs vso.graph, to resolve the
+# actor's project membership before a job may be enqueued.
+AZURE_TOKEN=
+# REQUIRED once any AZURE_* variable is set, and deliberately not defaulted: both modes are shared-secret
+# compares that cover no bytes, so which header carries the secret must be a choice somebody made.
+#   basic  -- Authorization: Basic <base64>, the credential you set on the subscription
+#   header -- one custom header, named below
+AZURE_WEBHOOK_MODE=
+# For basic: the base64 of "user:password" exactly as the subscription sends it.
+AZURE_WEBHOOK_SECRET=
+# Required only when AZURE_WEBHOOK_MODE=header.
+AZURE_WEBHOOK_HEADER=

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

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<!--
+  UNTESTED EXAMPLE: a starting point for the macOS (launchd) worker daemon, not a shipped, verified
+  unit. Adapt it. The Linux/systemd equivalent is deploy/worker.service.
+
+  ProgramArguments points at deploy/worker-env-wrapper.sh; that wrapper is what loads `.env`, because
+  launchd has no EnvironmentFile mechanism. NO secrets are inlined here: there is deliberately no
+  EnvironmentVariables dict, since that would commit credentials into this file. The wrapper reads
+  `.env` at runtime instead (note the ANTHROPIC_OAUTH_TOKEN over ANTHROPIC_API_KEY precedence trap
+  documented in the wrapper).
+
+  Graceful shutdown needs NO macOS-specific code: `launchctl bootout` sends SIGTERM, which the wrapper
+  forwards to node (a trap + kill; its former `exec` is gone, see the wrapper's own comments), and the
+  worker drains in-flight work on SIGTERM. ExitTimeOut 30 gives it room (at least the 5s docker-stop
+  grace) before launchd escalates to SIGKILL.
+
+  KeepAlive restarts on a crash (SuccessfulExit false) but NOT on a clean exit, so a deliberate stop
+  stays stopped. KeepAlive cannot exclude a single exit code the way systemd's
+  RestartPreventExitStatus=2 and nssm's `AppExit 2 Exit` do, so the wrapper converts EXIT_POLICY
+  (exit 2, a determinate config/budget refusal) into a clean exit 0: a policy refusal stays stopped
+  instead of relaunch-looping against a paid provider.
+
+  Per-host PLACEHOLDERS: replace /opt/pi-dispatch (the repo root, used in ProgramArguments and
+  WorkingDirectory) and /opt/pi-dispatch/logs (StandardOutPath, StandardErrorPath) with your paths.
+
+  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.
+-->
+<plist version="1.0">
+<dict>
+	<key>Label</key>
+	<string>com.pi-dispatch.worker</string>
+
+	<key>ProgramArguments</key>
+	<array>
+		<string>/bin/sh</string>
+		<string>/opt/pi-dispatch/deploy/worker-env-wrapper.sh</string>
+	</array>
+
+	<key>WorkingDirectory</key>
+	<string>/opt/pi-dispatch</string>
+
+	<key>RunAtLoad</key>
+	<true/>
+
+	<key>KeepAlive</key>
+	<dict>
+		<key>SuccessfulExit</key>
+		<false/>
+	</dict>
+
+	<key>ExitTimeOut</key>
+	<integer>30</integer>
+
+	<key>StandardOutPath</key>
+	<string>/opt/pi-dispatch/logs/worker.out.log</string>
+
+	<key>StandardErrorPath</key>
+	<string>/opt/pi-dispatch/logs/worker.err.log</string>
+</dict>
+</plist>

package/deploy/nssm-install.cmd

@@ -0,0 +1,59 @@
+@echo off
+REM UNTESTED EXAMPLE -- a starting point for the Windows worker service, not a shipped, verified unit.
+REM Adapt it. The Linux/systemd equivalent is deploy/worker.service; the macOS one is
+REM deploy/com.pi-dispatch.worker.plist.
+REM
+REM Registers the pi-dispatch worker as a Windows service via nssm (the Non-Sucking Service Manager).
+REM nssm is an operator-downloaded binary (https://nssm.cc) -- it is documented here, NOT vendored into
+REM this repo; put nssm.exe on PATH before running this. The service's Application is the `.cmd` wrapper
+REM (deploy/worker-env-wrapper.cmd), which loads `.env` at runtime -- so NO secrets are inlined here or
+REM passed via AppEnvironmentExtra. `.env` is gitignored; nothing in this file is a credential.
+REM
+REM Why nssm over Task Scheduler: Task Scheduler stops a task with TerminateProcess (a hard kill), which
+REM gives the worker no chance to drain the in-flight job -- it then relies on the queue's boot reaper to
+REM recover the orphaned container. nssm's AppStopMethodConsole sends a real Ctrl-C first, which node
+REM receives as SIGINT for a graceful drain. Task Scheduler is a weaker fallback, not the recommended
+REM path.
+REM
+REM One worker per host (DES-CONCURRENCY-3): parallelism is PI_CONCURRENCY inside the one process, not
+REM multiple services. Requires the AOF-enabled Valkey from deploy/docker-compose.yml.
+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
+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.
+
+setlocal
+
+set "SERVICE=pi-dispatch-worker"
+set "REPO=C:\pi-dispatch"
+set "LOGDIR=C:\pi-dispatch\logs"
+
+REM Application is the wrapper (loads `.env`), not node directly and not an env dict with real values.
+nssm install %SERVICE% "%REPO%\deploy\worker-env-wrapper.cmd"
+nssm set %SERVICE% AppDirectory "%REPO%"
+nssm set %SERVICE% AppStdout "%LOGDIR%\worker.out.log"
+nssm set %SERVICE% AppStderr "%LOGDIR%\worker.err.log"
+
+REM Stop = send Ctrl-C (node SIGINT, graceful drain), wait 15000ms (>= the 5s docker-stop grace) before
+REM nssm escalates to a hard kill.
+nssm set %SERVICE% AppStopMethodConsole 15000
+
+REM StartLimit analogue: pause 5000ms between restarts so a crash loop does not spin the provider bill
+REM (mirrors StartLimitIntervalSec/StartLimitBurst + RestartSec in deploy/worker.service).
+nssm set %SERVICE% AppThrottle 5000
+
+REM Restart on a crash by default...
+nssm set %SERVICE% AppExit Default Restart
+REM ...but exit 2 is EXIT_POLICY: a determinate config/budget refusal, never retried. Do NOT restart it
+REM (mirrors RestartPreventExitStatus=2 in deploy/worker.service).
+nssm set %SERVICE% AppExit 2 Exit
+
+echo Installed service "%SERVICE%". Start it with:  nssm start %SERVICE%
+
+endlocal

package/deploy/receiver.service

@@ -0,0 +1,36 @@
+# UNTESTED EXAMPLE (DES-WORKER-ON-HOST) -- a starting point, not a shipped, verified unit. Adapt it.
+#
+# The receiver runs on the HOST as the public edge: it verifies GitHub deliveries and enqueues jobs.
+# Requires node >=22.19.0 on PATH for User=pi -- or pin an absolute `ExecStart=/usr/bin/node ...`.
+# This is a Linux/systemd unit. The worker ships cross-platform daemon artifacts under deploy/
+# (com.pi-dispatch.worker.plist for launchd, nssm-install.cmd for Windows); receiver daemonization is
+# out of scope, but a launchd/nssm receiver would follow the same .env-wrapper pattern those use.
+#
+# NAT / tunnel: the receiver binds `RECEIVER_BIND` (default 0.0.0.0) and must be reachable by GitHub's
+# webhook delivery. On a home machine behind NAT, put it behind a tunnel (cloudflared / ngrok /
+# tailscale funnel) or a reverse proxy with TLS -- do not port-forward it raw without one.
+# `WEBHOOK_SECRET` is what authenticates deliveries; without a public URL GitHub cannot deliver.
+#
+# Env vars come from your `.env` (see `.env.example`) via EnvironmentFile -- never commit real secrets.
+# WorkingDirectory / EnvironmentFile / User / node path below are PLACEHOLDERS: set them to wherever
+# you cloned the repo and whoever owns it.
+
+[Unit]
+Description=pi-dispatch webhook receiver (public edge: verifies GitHub deliveries and enqueues jobs)
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=pi
+WorkingDirectory=/opt/pi-dispatch
+EnvironmentFile=/opt/pi-dispatch/.env
+ExecStart=/usr/bin/node receiver/src/start.mjs
+Restart=on-failure
+RestartSec=5
+# The receiver handles SIGTERM: it closes the HTTP server and the queue connection, then exits.
+KillSignal=SIGTERM
+TimeoutStopSec=30
+
+[Install]
+WantedBy=multi-user.target

package/deploy/worker-env-wrapper.cmd

@@ -0,0 +1,50 @@
+@echo off
+REM UNTESTED EXAMPLE -- a starting point for a Windows service, not a shipped, verified unit. Adapt it.
+REM
+REM pi-dispatch launcher for Windows service managers (nssm; see deploy/nssm-install.cmd). Windows
+REM services have no `.env` mechanism, so this wrapper loads `.env` from the repo root itself, then
+REM launches node. It reads ONLY the declared `.env` (see `.env.example`), never the host user profile:
+REM the container-boundary rules require an explicit, auditable variable set. Nothing here contains a
+REM credential -- the secrets live in `.env`, which is gitignored and read at runtime.
+REM
+REM TRAP: inside pi, ANTHROPIC_OAUTH_TOKEN silently takes precedence over ANTHROPIC_API_KEY. Set exactly
+REM one in `.env`.
+REM
+REM `.env` FORMAT for this loader: KEY=VALUE, one per line. Values MUST be UNQUOTED -- cmd's `set` keeps
+REM surrounding quotes as part of the value. `eol=#` skips `#` comment lines; blank lines are ignored.
+REM `tokens=1,* delims==` splits on the FIRST `=` only, so values containing `=` (base64, API keys)
+REM survive intact.
+REM
+REM One worker per host (DES-CONCURRENCY-3): parallelism is PI_CONCURRENCY inside the single process, not
+REM multiple services. Requires the AOF-enabled Valkey from deploy/docker-compose.yml.
+
+setlocal
+
+REM Resolve repo root relative to this script (deploy\ is one level down).
+cd /d "%~dp0.." || exit /b 1
+
+if not exist ".env" (
+  echo worker-env-wrapper: .env not found in "%CD%" 1>&2
+  exit /b 1
+)
+
+for /f "usebackq eol=# tokens=1,* delims==" %%A in (".env") do set "%%A=%%B"
+
+REM One wrapper serves both daemons (see the .sh twin): no argument runs the worker; `receiver`
+REM (passed by `pi-dispatch service --receiver`) runs the webhook receiver.
+if "%~1"=="receiver" (
+  node receiver\src\start.mjs
+) else (
+  node worker\src\cli.mjs worker
+)
+set "RC=%ERRORLEVEL%"
+
+REM Exit 2 is EXIT_POLICY (worker\src\exit-code.mjs): a determinate config/budget refusal. nssm's
+REM `AppExit 2 Exit` already refuses to restart it, but converting to a clean 0 here keeps ANY service
+REM manager pointed at this wrapper from relaunch-looping a refusal into a provider bill (mirrors the
+REM .sh twin, which exists for launchd's KeepAlive that cannot exclude a single exit code).
+if "%RC%"=="2" (
+  echo worker-env-wrapper: policy refusal, exit 2: not restarting; fix the config and start the service again 1>&2
+  exit /b 0
+)
+exit /b %RC%

package/deploy/worker-env-wrapper.sh

@@ -0,0 +1,63 @@
+#!/bin/sh
+# pi-dispatch launcher for daemon managers that have NO EnvironmentFile mechanism. systemd reads
+# `.env` for you via `EnvironmentFile=` (see deploy/worker.service); launchd (macOS) has no equivalent --
+# a plist's ProgramArguments cannot name a `.env`. This wrapper closes that gap: launchd execs THIS
+# script, which loads the explicit `.env` from the repo root and then runs node. Its exit-code
+# conversion and signal forwarding are exercised under `sh` by worker/test/service.test.mjs.
+#
+# It sources ONLY the declared `.env` (see `.env.example`), never the host login shell: the
+# container-boundary rules require an explicit, auditable variable set, not whatever the operator's
+# profile happens to export. Nothing here contains a credential -- the secrets live in `.env`, which is
+# gitignored and read at runtime.
+#
+# TRAP: inside pi, `ANTHROPIC_OAUTH_TOKEN` silently takes precedence over `ANTHROPIC_API_KEY`. Set exactly
+# one in `.env`; this wrapper only ADDS the `.env` vars on top of the current environment, it does not
+# clear a stray pre-existing one, so a leaked host `ANTHROPIC_OAUTH_TOKEN` would still win.
+#
+# One worker per host (DES-CONCURRENCY-3): parallelism is PI_CONCURRENCY inside the single process, not
+# multiple daemons. Requires the AOF-enabled Valkey from deploy/docker-compose.yml.
+
+# Resolve repo root relative to this script (deploy/ is one level down).
+cd "$(dirname "$0")/.." || exit 1
+if [ ! -f .env ]; then echo "worker-env-wrapper: .env not found in $(pwd)" >&2; exit 1; fi
+set -a; . ./.env; set +a
+
+# One wrapper serves both daemons, because the gap it closes (no EnvironmentFile under launchd/nssm)
+# is identical for both: no argument runs the worker; `receiver` (passed by the derived receiver
+# units `pi-dispatch service` renders) runs the webhook receiver.
+if [ "$1" = "receiver" ]; then
+	set -- node receiver/src/start.mjs
+else
+	set -- node worker/src/cli.mjs worker
+fi
+
+# `exec` is deliberately GONE here (it used to hand this shell's pid straight to node): intercepting
+# the exit code needs a parent still alive after node exits. launchd's KeepAlive/SuccessfulExit=false
+# relaunches ANY nonzero exit -- including EXIT_POLICY (2, worker/src/exit-code.mjs), the determinate
+# config/budget refusal that systemd (RestartPreventExitStatus=2) and nssm (AppExit 2 Exit) both
+# deliberately never retry. A relaunch loop against a paid provider is a bill, so the conversion at
+# the bottom turns exit 2 into the clean exit KeepAlive leaves stopped.
+#
+# SIGTERM still reaches node without exec: the trap forwards TERM/INT to the child, and `wait` (unlike
+# a foreground command in sh, which blocks trap delivery) is interruptible by a trapped signal, so the
+# forwarding is immediate and node gets its full graceful drain.
+signaled=0
+trap 'signaled=1; kill -TERM "$child" 2>/dev/null' TERM INT
+"$@" &
+child=$!
+wait "$child"
+rc=$?
+# The double wait is load-bearing: a trapped signal interrupts the FIRST wait early (rc = 128+signum)
+# while node is still draining, so a SECOND wait is needed to collect node's real exit code. Guarded
+# on both conditions so a normal exit never waits twice -- re-waiting on an already-reaped pid would
+# read as 127, clobbering the true code.
+if [ "$signaled" -eq 1 ] && [ "$rc" -ge 128 ]; then
+	wait "$child"
+	rc=$?
+fi
+
+if [ "$rc" -eq 2 ]; then
+	echo "worker-env-wrapper: policy refusal (exit 2): not restarting; fix the config and start the service again" >&2
+	exit 0
+fi
+exit "$rc"

package/deploy/worker.service

@@ -0,0 +1,55 @@
+# TEMPLATE — verified structure (systemd-analyze); set the <PLACEHOLDER> values for your host.
+#
+# The worker runs on the HOST, not in a container (DES-WORKER-ON-HOST): it drives the `docker` CLI to
+# launch one job container per job, and the CLI is what translates bind-mount paths cross-platform.
+# Compose runs only Valkey; this unit runs the worker beside it.
+#
+# Requires node >=22.19.0 (worker/package.json engines) on PATH for User=pi -- or pin an absolute
+# `ExecStart=/usr/bin/node ...` if PATH is not reliable under systemd. This is a Linux/systemd unit;
+# the launchd (macOS) equivalent is deploy/com.pi-dispatch.worker.plist and the Windows (nssm) one is
+# deploy/nssm-install.cmd.
+#
+# Env vars come from your `.env` (see `.env.example`) via EnvironmentFile -- never commit real secrets.
+# WorkingDirectory / EnvironmentFile / User / node path below are PLACEHOLDERS: set them to wherever
+# you cloned the repo and whoever owns it.
+#
+# 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 User= (pi) -- do NOT pre-create it as root, or the non-root
+# worker hits EACCES at boot. Set via `.env` (EnvironmentFile), no unit change needed; the default path
+# avoids colliding with the daemon's own logs/worker.out.log.
+#
+# PI_SETTINGS_FILE is the runtime-tunable settings overlay (default under OS temp, which may be wiped on
+# reboot) -- point it at a durable path in production. Set via `.env` (EnvironmentFile), no unit change
+# needed; it is worker-owned and never belongs in the container env allowlist.
+
+[Unit]
+Description=pi-dispatch worker (drains the job queue on the host; launches job containers via docker)
+After=network-online.target docker.service
+Wants=network-online.target
+# Valkey must be reachable (docker compose -f deploy/docker-compose.yml up -d), but it is a separate
+# unit/container -- not ordered here since it may be remote.
+# Crash-loop bound: at most StartLimitBurst restarts within StartLimitIntervalSec, then systemd stops
+# trying. A restart loop against a paid provider is a bill, not just log noise. Pairs with
+# Restart=on-failure below.
+StartLimitIntervalSec=60
+StartLimitBurst=5
+
+[Service]
+Type=simple
+User=pi
+WorkingDirectory=/opt/pi-dispatch
+EnvironmentFile=/opt/pi-dispatch/.env
+ExecStart=/usr/bin/node worker/src/cli.mjs worker
+Restart=on-failure
+RestartSec=5
+# Exit 2 is EXIT_POLICY (worker/src/exit-code.mjs): a determinate config/budget refusal, not infra.
+# Never restart it -- retrying pays again for the same broken config. Only infra failures are worth a
+# restart, and Restart=on-failure already covers those.
+RestartPreventExitStatus=2
+# The worker handles SIGTERM: it stops accepting new jobs and lets the in-flight container finish or
+# abort cleanly. Give it room before SIGKILL.
+KillSignal=SIGTERM
+TimeoutStopSec=30
+
+[Install]
+WantedBy=multi-user.target

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@edgehero/pi-dispatch",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Self-hosted job harness for the pi coding agent: a BullMQ worker that drains the queue, mints scoped forge tokens, and runs one container per job — plus the pi-dispatch CLI (init, up, doctor, service).",
+  "keywords": [
+    "pi",
+    "pi-coding-agent",
+    "coding-agent",
+    "ai-agent",
+    "autonomous-agents",
+    "self-hosted",
+    "github",
+    "gitlab",
+    "forgejo",
+    "gitea",
+    "azure-devops",
+    "job-queue",
+    "bullmq",
+    "cron",
+    "docker",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Rob Boerman",
+  "homepage": "https://github.com/edgehero/pi-dispatch/tree/main/worker",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/edgehero/pi-dispatch.git",
+    "directory": "worker"
+  },
+  "bugs": "https://github.com/edgehero/pi-dispatch/issues",
+  "files": [
+    "src",
+    ".env.example",
+    "deploy"
+  ],
+  "main": "src/index.mjs",
+  "bin": {
+    "pi-dispatch": "src/cli.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./config": "./src/config.mjs",
+    "./exit-code": "./src/exit-code.mjs",
+    "./flow-gate": "./src/flow-gate.mjs",
+    "./git-dirty": "./src/git-dirty.mjs",
+    "./queue": "./src/queue.mjs",
+    "./connection": "./src/connection.mjs",
+    "./job-id": "./src/job-id.mjs",
+    "./forges": "./src/forges.mjs",
+    "./triggers": "./src/triggers.mjs",
+    "./packages": "./src/packages.mjs",
+    "./pause-windows": "./src/pause-windows.mjs",
+    "./identity": "./src/identity.mjs",
+    "./gitlab-identity": "./src/gitlab-identity.mjs",
+    "./forgejo-identity": "./src/forgejo-identity.mjs",
+    "./azure-identity": "./src/azure-identity.mjs",
+    "./get-token": "./src/get-token.mjs",
+    "./runtime-settings": "./src/runtime-settings.mjs",
+    "./run-history": "./src/run-history.mjs",
+    "./sandbox": "./src/sandbox.mjs",
+    "./sandbox-store": "./src/sandbox-store.mjs",
+    "./subscriptions": "./src/subscriptions.mjs",
+    "./budget": "./src/budget.mjs",
+    "./pricing": "./src/pricing.mjs",
+    "./scheduler-stall-guard": "./src/scheduler-stall-guard.mjs"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/*.test.mjs\"",
+    "start": "node src/cli.mjs worker"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "0.80.7",
+    "@octokit/auth-app": "8.2.0",
+    "@octokit/rest": "22.0.1",
+    "bullmq": "5.80.4",
+    "ioredis": "5.11.1"
+  }
+}

package/src/azure-auth.mjs

@@ -0,0 +1,61 @@
+/**
+ * Azure DevOps authentication for the worker, yielding the identical `{ mintToken, selfId, source }` shape
+ * every other forge does.
+ *
+ * CONST-TOKEN-SCOPED-PER-JOB, and the interesting thing here is the SYMMETRY with Forgejo: the two new
+ * forges fail OPPOSITE halves of this constraint.
+ *
+ *   - short-lived         YES, and better than Forgejo's or GitLab's: an Azure PAT carries a real expiry
+ *                         the operator chooses, up to a year, and the organization can cap it by policy.
+ *   - repo-scoped         NO, not by the token. PAT scopes are ORGANIZATION-wide -- `vso.code_write` grants
+ *                         write to every repository in the org, and there is no per-repository scope to
+ *                         select. The bound has to come from somewhere else.
+ *   - host-held           YES; it lives in the worker's env and reaches a container only as an env value.
+ *   - env-injected        YES; never written to /workspace, .git/config, argv, or a log.
+ *   - not merge-capable   YES in practice; branch policies are the barrier and no completion API is called.
+ *   - minimally-permissioned  Partly. The scopes are coarse, but they ARE separable: `vso.code_write` does
+ *                         not imply `vso.work_write`, unlike GitLab's all-or-nothing `api`.
+ *
+ * SO THE OPERATOR OBLIGATION IS DIFFERENT IN KIND, and the docs have to say which. On GitLab and Forgejo it
+ * is "rotate it, because nothing expires it". On Azure the expiry is fine and the SCOPE is the gap: the
+ * token must belong to a dedicated identity whose per-repository permissions are set in Project Settings,
+ * because that identity's own access -- not the token's scopes -- is what bounds the blast radius.
+ *
+ * All side-effecting collaborators are INJECTED, so the module is testable offline with no Azure.
+ */
+
+import { configError } from "./config.mjs";
+import { resolveAzureSelfId } from "./azure-identity.mjs";
+
+/** Build the auth surface for `cfg = { source, orgUrl, tokenVar }`. Fails CLOSED at construction. */
+export async function makeAzureAuth(cfg, deps = {}) {
+	const { env = process.env, fetchFn = fetch } = deps;
+	const source = cfg?.source;
+	if (source !== "pat") {
+		throw configError(`makeAzureAuth: unknown or missing source: ${JSON.stringify(source)} (only "pat" is supported -- Azure DevOps has no App or installation-token equivalent)`);
+	}
+
+	const tokenVar = cfg.tokenVar ?? "AZURE_TOKEN";
+	const token = requireToken(env[tokenVar], tokenVar);
+	const selfId = await resolveAzureSelfId({ orgUrl: cfg.orgUrl, token, fetchFn });
+
+	// Ignores the job by design: one operator-supplied token serves every project this deployment services,
+	// exactly as the other forges' pat sources do. The parameter exists so the shape matches.
+	const mintToken = async () => requireToken(token, tokenVar);
+	return { mintToken, selfId, source };
+}
+
+/**
+ * The money-hole invariant, mirrored from get-token.mjs: return a trimmed non-empty token, or throw.
+ *
+ * An empty credential would reach env-allowlist's truthiness check as falsy, the token would be OMITTED
+ * from the container env entirely, and the job would run anonymously -- a silent, paid, useless run rather
+ * than an error.
+ */
+function requireToken(raw, what) {
+	const token = typeof raw === "string" ? raw.trim() : "";
+	if (token === "") {
+		throw configError(`${what} is empty or unset; refusing to hand a job an empty Azure DevOps credential`);
+	}
+	return token;
+}