@edgehero/pi-dispatch 1.10.0 → 1.10.2

package/.env.example

@@ -86,12 +86,22 @@ PI_JOB_IMAGE=pi-job:latest          # the DEFAULT job image. Any trigger may nam
 # 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
+# PI_DISPATCH_DEPLOYMENT_FILE=      # ABSOLUTE path to the deployment pointer the /dispatch panel reads to find a deployment built elsewhere
+                                    # (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_GRAPH_DIR=                     # where `/dispatch insights` writes its HTML artifact (default: under the OS temp dir). Admin extension only. See docs/insights.md
 
 # --- 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_CODING_AGENT_DIR=              # where YOUR pi setup lives on this host (default: ~/.pi/agent). `pi-dispatch import-pi` reads its models.json,
+                                    # skills and APPEND_SYSTEM.md from here, and the panel looks here for the deployment pointer.
+                                    # It is also read AT JOB TIME: with no provider key in the environment the worker reads this directory's auth.json
+                                    # for one (on by default; PI_AUTH_FROM_PI=0 turns it off), so pointing this at the wrong place makes every job
+                                    # refuse pre-spend with no credential for the provider. It is the SOURCE that gets staged, never the thing mounted:
+                                    # PI_GLOBAL_PI_DIR above is what a job actually sees. Set it if your pi lives somewhere other than your home directory
 # 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.
@@ -166,6 +176,12 @@ RECEIVER_BIND=0.0.0.0
 GITHUB_AUTH_SOURCE=gh
 # For GITHUB_AUTH_SOURCE=pat: a repo-scoped, short-expiry fine-grained PAT
 GITHUB_PAT=
+# GITHUB_PAT_VAR=                   # which variable above actually holds the PAT. Default GITHUB_PAT; set this only if your
+                                    # secrets manager insists on its own name and you would rather not copy the value to a second key.
+                                    # The NAME is not checked against anything: whatever you put here is read verbatim, so a typo
+                                    # reads an empty variable and the worker refuses at boot naming the name you chose. Pointing it
+                                    # at a variable that holds something else (GITHUB_APP_PRIVATE_KEY, say) is the mistake worth
+                                    # knowing about, because nothing stops it and the PAT path would then send that value to GitHub.
 # 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=
@@ -176,6 +192,23 @@ GITHUB_APP_PRIVATE_KEY_PATH=
 # escapes both work. Never list it in PI_FORWARD_ENV: it mints tokens for every repo the App is on.
 GITHUB_APP_PRIVATE_KEY=
 
+# --- Polling ingest, instead of a webhook (GitHub only) --- issue #282
+# `pi-dispatch-receiver poll` fetches issue events, comments and pull requests over TLS with your own
+# credential, so a deployment with no public URL, no DNS and no tunnel still fires triggers. Same gates and
+# same queue as the webhook path; about a minute of latency instead of a second. Nothing here is read by
+# `pi-dispatch-receiver serve`, and no WEBHOOK_SECRET is needed to poll: there is no inbound delivery to
+# verify, because the poller originates every request itself. See docs/polling.md.
+# POLL_REPOS=                       # WHICH repos to watch: comma-separated owner/name (e.g. acme/web,acme/api). Duplicates are dropped.
+                                    # Each entry must be exactly owner/name -- one slash, no spaces -- or the receiver refuses at boot naming the bad entry.
+                                    # Leave it UNSET only with GITHUB_AUTH_SOURCE=app: the poller then lists the App installation's own repos and
+                                    # re-lists every tenth cycle, so installing the App on a new repo starts polling it without an edit here.
+                                    # Unset under any other auth source is a boot refusal, deliberately: a PAT names no repo set, and a poller
+                                    # watching nothing looks exactly like a poller that is working.
+# POLL_INTERVAL_SECONDS=            # seconds between cycles. Default 60, floored at 30: a positive value BELOW the floor is raised to it,
+                                    # while 0, a negative, a fraction or junk still refuses at boot.
+                                    # GitHub asks pollers to respect its own x-poll-interval hint, which is honored as a MINIMUM when it arrives,
+                                    # so a busy hour slows the loop down rather than the loop hammering the API. A typo'd 1 must not turn this into a hammer.
+
 # --- 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.
@@ -184,6 +217,13 @@ GITHUB_APP_PRIVATE_KEY=
 # 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=
+# GITLAB_AUTH_SOURCE=               # accepts exactly one value, "pat", which is also the default, so there is nothing to set here.
+                                    # It exists to REFUSE the wrong assumption rather than to offer a choice: GITHUB_AUTH_SOURCE has
+                                    # three sources, and an operator who reasons by symmetry and writes app here gets a sentence at
+                                    # boot saying GitLab has no App equivalent, instead of a knob that is silently ignored.
+                                    # The refusal needs GITLAB_TOKEN to be set: with no token there is no GitLab to configure, the
+                                    # whole block is skipped, and a stray app here really is ignored. Same for the two below.
+                                    # FORGEJO_AUTH_SOURCE and AZURE_AUTH_SOURCE are the same variable for the same reason.
 # 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
@@ -205,6 +245,7 @@ FORGEJO_URL=
 # expire: there is no App or installation token, so rotation is the whole mitigation
 # (CONST-TOKEN-SCOPED-PER-JOB).
 FORGEJO_TOKEN=
+# FORGEJO_AUTH_SOURCE=              # only "pat", the default. See GITLAB_AUTH_SOURCE above for why it exists at all.
 # 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
@@ -223,6 +264,7 @@ AZURE_ORG_URL=
 # 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=
+# AZURE_AUTH_SOURCE=                # only "pat", the default. See GITLAB_AUTH_SOURCE above for why it exists at all.
 # 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
@@ -232,3 +274,41 @@ AZURE_WEBHOOK_MODE=
 AZURE_WEBHOOK_SECRET=
 # Required only when AZURE_WEBHOOK_MODE=header.
 AZURE_WEBHOOK_HEADER=
+
+# --- 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
+# that is read and appears in neither is the failure this section exists to prevent, because an operator has
+# no way to discover it and no way to find out that setting it did nothing.
+#
+#   The worker's own inputs to a job container: PI_JOB_ID, PI_FLOW, PI_COMMAND, PI_PACKAGES, PI_SESSION_FILE,
+#   PI_OFFLINE, and the three PLAYWRIGHT_ names. The container's environment is BUILT, not inherited: the worker
+#   passes exactly the map it composed, so a value set here never reaches a job to be overridden in the first
+#   place. Several of them are also conditional, present only when the job has a flow, a command, staged
+#   packages or a session to resume. These are the container's side of INT-CONTAINER-RUNTIME-CONTRACT
+#   (specs/interfaces.md, docs/job-image.md), and run.secrets refuses the names at load so a trigger cannot
+#   bind one either. PI_FORWARD_ENV is NOT checked against these names, and it is applied after the worker's
+#   own map, so naming one there does override it. Not everything is: run.secrets, the egress variables and
+#   the minted forge token are all written later still and win over a forwarded value. A real edge, not a
+#   recommendation.
+#
+#   PI_ENV_SETUP is an argument to `pi-dispatch service render|install --env-setup <absolute path>`, never a
+#   key. The service wrappers capture it BEFORE they source ./.env, precisely so that anything able to write
+#   this file cannot name a script the wrapper will run as the worker. A line here is honored by nothing, and
+#   that is the point rather than an oversight (docs/secrets.md, REQ-DEPLOYMENT-BOOTSTRAP).
+#
+#   PI_RETRY_MAX (default 2) and PI_RETRY_BASE_MS (default 2000) are read by the runner INSIDE the container,
+#   and nothing on the host writes them, so a line here sets them on this machine and never reaches a job.
+#   PI_FORWARD_ENV is what carries a host value into a container, and is how you would actually change them.
+#
+#   Provider key names are pi's, not ours. The worker asks pi which variable your PI_PROVIDER expects, so the
+#   provider block at the top of this file lists the common ones as examples and is not the whole set: pi
+#   supports around thirty providers and the answer travels with pi rather than with this file.
+#
+#   Read from the surrounding system, not from a deployment: TMPDIR and TEMP (where the default job, log,
+#   graph and settings paths go), USER (the account a rendered service unit runs as), and TERM, SSH_CONNECTION,
+#   SSH_TTY, DISPLAY, WAYLAND_DISPLAY (how the panel decides whether it can open a browser for you).
+#
+#   PI_DISPATCH_REQUIRE_LOADER_TESTS, PI_DISPATCH_REQUIRE_WORKER_TESTS, PI_DISPATCH_REQUIRE_RECEIVER_TESTS and
+#   VALKEY_TEST_URL turn locally skipped integration tests into required ones. They are read by the test files
+#   themselves and by CI, never by the worker, the receiver or the panel.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "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": [

package/src/config.mjs

@@ -498,6 +498,9 @@ export function loadGitHubAuth(env, fileExists) {
 	return { source, patVar, appId, installationId, privateKeyPath, privateKey };
 }
 
+// env-internal TMPDIR, TEMP: the OS temp dir, read to place the default job, log, graph and settings
+// paths below. Not a variable of this project's and not a deployment knob: PI_JOBS_DIR, PI_LOGS_DIR,
+// PI_GRAPH_DIR and PI_SETTINGS_FILE are how an operator moves any of them, and .env.example says so.
 function defaultJobsDir() {
 	// Under the OS temp dir by default. Holds only the read-only /job inputs (prompt + .pi/); the
 	// workspace for a local job is the operator's own folder, not here.

package/src/doctor.mjs

@@ -2072,6 +2072,9 @@ async function envSetupChecks(env, seams) {
 		}
 	}
 
+	// env-internal PI_ENV_SETUP: unit configuration, deliberately never an .env key. The wrappers capture
+	// it BEFORE they source ./.env so that nothing able to write that file can name a script they run
+	// (REQ-DEPLOYMENT-BOOTSTRAP). doctor reads it here only to answer for a host whose unit names none.
 	const fromEnv = (env.PI_ENV_SETUP ?? "").trim();
 	if (sources.size === 0 && fromEnv) sources.set(fromEnv, "PI_ENV_SETUP in this environment");
 

package/src/index.mjs

@@ -693,12 +693,23 @@ export function makeProcessor({ cancelJob, stopContainer, containerName = (job)
 				// job.data with no `.id` -- and the real wrapper is only in scope here, so inject it as
 				// `queueJobId`, mirroring the collectChain injection above. Omitted when unwired so a bare
 				// processor keeps runJob's plain (job, token) call.
-				...(deps.prepareWorkspace ? { prepareWorkspace: (j, t) => deps.prepareWorkspace(j, t, { queueJobId: job.id }) } : {}),
+				// The third argument is EXTENDED, never replaced. `runJob` calls this as
+				// `prepareWorkspace(job, token, { piVersion })`, so a wrapper passing only `{ queueJobId }`
+				// dropped it -- and `piVersion` defaults to `null`, which `readCanonical` treats as
+				// "never resume": `if (piVersion === null) return COLD("pi-version-changed")`. So EVERY
+				// `run.resume` cold-started, on every wired worker, while reporting success. The stamp
+				// `promoteSession` writes was correct the whole time; the comparison simply never happened.
+				// The processor tests inject `prepareWorkspace` directly and never see this wrapper, which is
+				// why nothing caught it (REQ-RESUMABLE-SESSION).
+				...(deps.prepareWorkspace ? { prepareWorkspace: (j, t, opts) => deps.prepareWorkspace(j, t, { ...opts, queueJobId: job.id }) } : {}),
 				// The one-shot pre-spend check (issue #231) needs the REAL BullMQ job's `.id` to excuse this
 				// delivery's own earlier attempt -- runJob's effectiveJob has no `.id`, prepareWorkspace's
 				// own injection above states why, and this one mirrors it. Omitted when unwired so a bare
 				// processor keeps runJob's admit-everything default.
-				...(deps.checkOnceSpent ? { checkOnceSpent: (j) => deps.checkOnceSpent(j, { queueJobId: job.id }) } : {}),
+				// Same extend-don't-replace shape as `prepareWorkspace` above, for its reason: `runJob` passes
+				// this one no options today, so there is nothing to lose yet -- and the day it does, a
+				// replacing wrapper would lose it in the same silence.
+				...(deps.checkOnceSpent ? { checkOnceSpent: (j, opts) => deps.checkOnceSpent(j, { ...opts, queueJobId: job.id }) } : {}),
 			});
 			recordRun({ job, result, startedAt, endedAt: new Date().toISOString() });
 			return result;

package/src/sandbox-cli.mjs

@@ -140,6 +140,8 @@ export async function runSandbox(argv = [], { env = process.env, deps = {} } = {
 		workspace: resolved.manifest.workspace,
 		jobDir: resolved.manifest.dir,
 		publish,
+		// env-internal TERM: the operator's own terminal type, forwarded so the sandbox shell renders the
+		// way their terminal does. Nothing a deployment declares.
 		term: env.TERM,
 		idleSeconds: config.sandboxIdleMinutes * 60,
 		network,

package/src/service.mjs

@@ -265,6 +265,8 @@ export async function runService(argv = [], deps = {}) {
 		moduleDir = MODULE_DIR,
 		resolveReceiver = resolveReceiverStart,
 		home = homedir(),
+		// env-internal USER: whose account a rendered unit runs as, taken from the login already running
+		// this command. An operator changes it by running the command as someone else, not by declaring it.
 		user = env.USER || userInfo().username,
 		tmp = tmpdir(),
 		fs = { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync },