@edgehero/pi-dispatch 0.1.1 → 0.1.2

package/.env.example

@@ -87,7 +87,8 @@ PI_SCHEDULER_STALL_MAX=2            # tear down a scheduler after N consecutive
 # PI_CHAIN_MAX_PER_JOB=2           # max request-<n>.json collected per completed job
 
 # --- GitHub trigger (receiver + worker auth) ---
-# Webhook receiver
+# Webhook receiver. Required only when your triggers name github (or GITHUB_AUTH_SOURCE is set): every forge arm is
+# conditional, so a gitlab/forgejo/azure-only deployment needs no value here and answers 404 on the github endpoint
 WEBHOOK_SECRET=
 RECEIVER_PORT=3000
 RECEIVER_BIND=0.0.0.0

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

@@ -5,10 +5,18 @@
   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).
+  launchd has no EnvironmentFile mechanism. The wrapper's contract (issue #96; see its header): it
+  sources ./.env from the WorkingDirectory below (which makes that key load-bearing, not a nicety)
+  and then runs the REST of ProgramArguments as the command. When hand-editing this template, append
+  the command after the wrapper path, e.g.
+      <string>/usr/bin/node</string>
+      <string>/opt/pi-dispatch/worker/src/cli.mjs</string>
+      <string>worker</string>
+  (`pi-dispatch service render` composes exactly that argv with this host's real paths; the wrapper
+  refuses an empty argv rather than guessing what to run). 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
@@ -21,8 +29,10 @@
   (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.
+  Per-host PLACEHOLDERS: replace /opt/pi-dispatch (the deployment folder, used in ProgramArguments and
+  WorkingDirectory; the folder that holds your `.env`) and /opt/pi-dispatch/logs (StandardOutPath,
+  StandardErrorPath; create the directory yourself, launchd will not) with your paths, and append the
+  command argv to ProgramArguments as described above.
 
   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.

package/deploy/docker-compose.yml

@@ -0,0 +1,66 @@
+# pi-dispatch's worker runs on the HOST, not in a container: it drives the `docker` CLI to launch
+# job containers, and the CLI is what translates bind-mount paths cross-platform (Windows/macOS/
+# Linux) -- see DES-WORKER-ON-HOST. That is settled doctrine, and it is why no service here mounts
+# docker.sock: a socket mount is root-equivalent access to the host, and nothing in this stack needs it.
+#
+# The RECEIVER may run either way. It is the one internet-facing process and needs no Docker access at
+# all, so a container suits it -- but the host mode (`pi-dispatch-receiver`, deploy/receiver.service)
+# 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)
+
+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.
+    ports:
+      - "127.0.0.1:6379:6379"
+    volumes:
+      - valkey-data:/data
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "valkey-cli", "ping"]
+      interval: 10s
+      timeout: 3s
+      retries: 5
+
+  # The containerized receiver (issue #82): the always-on webhook edge, prebuilt for amd64+arm64.
+  # Build locally instead with:  docker build -f receiver/Dockerfile -t pi-dispatch-receiver .
+  #
+  # Relative paths below resolve against THIS FILE's directory (deploy/), not the caller's cwd --
+  # that is the Compose spec for both env_file and bind mounts -- so `../` reaches the repo root
+  # regardless of where `docker compose -f deploy/docker-compose.yml ...` is run from.
+  receiver:
+    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
+    # 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
+    # inside a container is the container itself. Service DNS is the container-side truth.
+    environment:
+      VALKEY_URL: redis://valkey:6379
+      PI_TRIGGERS_FILE: /config/triggers.json
+    # The repo-root triggers.json (`pi-dispatch init` scaffolds it -- run that first: mounting a path
+    # that does not exist makes Docker create it as a DIRECTORY and the boot fails confusingly).
+    # Read-only: the receiver live-reloads this file on change; it never writes it.
+    volumes:
+      - ../triggers.json:/config/triggers.json:ro
+    # 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.
+    ports:
+      - "127.0.0.1:3000:3000"
+    depends_on:
+      valkey:
+        condition: service_healthy
+    restart: unless-stopped
+
+volumes:
+  valkey-data:

package/deploy/worker-env-wrapper.cmd

@@ -2,10 +2,21 @@
 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 services have no `.env` mechanism, so this wrapper loads `.env` from the current directory itself,
+REM then runs the command it was handed. It reads ONLY the declared `.env` (see `.env.example`), never
+REM the host user profile: the container-boundary rules require an explicit, auditable variable set.
+REM Nothing here contains a credential -- the secrets live in `.env`, which is gitignored and read at
+REM runtime.
+REM
+REM CONTRACT (issue #96 -- mirrors the .sh twin; nothing is guessed from this script's location):
+REM   - The current directory IS the deployment folder. nssm's AppDirectory guarantees it, set both by
+REM     deploy/nssm-install.cmd and by `pi-dispatch service install`. The old `cd /d "%~dp0.."`
+REM     self-guess was right only in a repo checkout; under `npm install` this script lives at
+REM     node_modules\@edgehero\pi-dispatch\deploy\, whose parent is the package -- no `.env` there.
+REM   - The arguments ARE the command, e.g.:  C:\path\to\node.exe C:\...\src\cli.mjs worker
+REM     `pi-dispatch service install` passes them via nssm AppParameters. This wrapper no longer
+REM     decides WHAT to run -- only the env it runs in and what its exit code means -- so an empty
+REM     argument list is a configuration error, refused below.
 REM
 REM TRAP: inside pi, ANTHROPIC_OAUTH_TOKEN silently takes precedence over ANTHROPIC_API_KEY. Set exactly
 REM one in `.env`.
@@ -20,23 +31,21 @@ REM multiple services. Requires the AOF-enabled Valkey from deploy/docker-compos
 
 setlocal
 
-REM Resolve repo root relative to this script (deploy\ is one level down).
-cd /d "%~dp0.." || exit /b 1
+if "%~1"=="" (
+  echo worker-env-wrapper: no command given -- expected: worker-env-wrapper.cmd node-path script-path [args...]; re-render with: pi-dispatch service render 1>&2
+  exit /b 1
+)
 
 if not exist ".env" (
-  echo worker-env-wrapper: .env not found in "%CD%" 1>&2
+  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
   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
-)
+REM The argv runs verbatim -- absolute node, absolute script, composed by `pi-dispatch service` (see
+REM the .sh twin for the whole contract).
+%*
 set "RC=%ERRORLEVEL%"
 
 REM Exit 2 is EXIT_POLICY (worker\src\exit-code.mjs): a determinate config/budget refusal. nssm's

package/deploy/worker-env-wrapper.sh

@@ -1,9 +1,20 @@
 #!/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.
+# a plist's ProgramArguments cannot name a `.env`. This wrapper closes that gap: it sources `./.env`
+# from the directory it is STARTED IN, then runs the command it was handed. Its exit-code conversion
+# and signal forwarding are exercised under `sh` by worker/test/service.test.mjs.
+#
+# CONTRACT (issue #96 -- nothing here is guessed from this script's own location any more):
+#   - The current directory IS the deployment folder. The daemon manager guarantees it: launchd sets
+#     the plist's WorkingDirectory, nssm sets AppDirectory. The old `cd "$(dirname "$0")/.."` self-guess
+#     was right only in a repo checkout; under `npm install` this script lives at
+#     node_modules/@edgehero/pi-dispatch/deploy/, whose parent is the package -- no `.env` there, ever.
+#   - "$@" IS the command, e.g.:  /path/to/node /abs/path/to/src/cli.mjs worker
+#     `pi-dispatch service` composes it with absolute paths (the same node that rendered, the worker
+#     package's own cli.mjs or the receiver package's start.mjs) and puts it in the unit's
+#     ProgramArguments / AppParameters. This wrapper no longer decides WHAT to run -- only the env it
+#     runs in and what its exit code means -- so an empty argv is a configuration error, refused below.
 #
 # 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
@@ -17,19 +28,15 @@
 # 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
+if [ "$#" -eq 0 ]; then
+	echo "worker-env-wrapper: no command given -- expected: worker-env-wrapper.sh /path/to/node /path/to/script [args...]; the unit's ProgramArguments/AppParameters carry these (re-render with: pi-dispatch service render)" >&2
+	exit 1
 fi
+if [ ! -f ./.env ]; then
+	echo "worker-env-wrapper: .env not found in $PWD -- this wrapper must be started in the deployment folder (the unit's WorkingDirectory / nssm AppDirectory); it no longer guesses a location from its own path" >&2
+	exit 1
+fi
+set -a; . ./.env; set +a
 
 # `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edgehero/pi-dispatch",
-  "version": "0.1.1",
+  "version": "0.1.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/doctor.mjs

@@ -859,6 +859,47 @@ export async function collectChecks(env, seams) {
 		});
 	}
 
+	// REQ-SCOPED-PAUSE-WINDOWS, the panel-writes-what-the-worker-ignores trap (issue #99). Three defaults
+	// that are individually defensible and together silent:
+	//
+	//   - `pi-dispatch init` SCAFFOLDS ./pause-windows.json and leaves PI_PAUSE_WINDOWS_FILE commented out;
+	//   - the admin panel defaults to ./pause-windows.json in its OWN cwd, so `w` reads and WRITES that file
+	//     and reports every window it adds as applied live;
+	//   - the worker has NO cwd default (config.mjs: `?? null`, and null means the feature is off).
+	//
+	// So an operator adds quiet hours in the panel, is told it is live, and nothing ever pauses -- the one
+	// failure mode where the UI actively asserts the opposite of the truth. The worker's fail-closed default
+	// is deliberate and is NOT changed here: a worker must not start honouring a file nobody pointed it at,
+	// least of all one that stops paid work. The mismatch is a deployment fact, so doctor is where it
+	// belongs. Warn, never fail, like every other setup-shaped check: a deployment can legitimately be
+	// mid-setup, and a scaffolded file the operator never intended to use is not a fault.
+	//
+	// Empty counts as unset, mirroring `if (config.pauseWindowsFile)` at the worker's own load site.
+	//
+	// NEVER TIER, deliberately no fixAction: doctor cannot know which path the operator meant. This cwd is
+	// doctor's, not necessarily the worker's (a service manager sets its own), and writing an env line into
+	// .env would be doctor guessing a semantic value -- the same refusal PI_GLOBAL_ALLOW_EXTENSIONS gets.
+	// The fix line names the variable and the absolute path, and the operator decides.
+	//
+	// SUBSCRIPTIONS GET NO SUCH CHECK, checked rather than assumed: ./subscriptions.json is scaffolded by the
+	// same init and PI_SUBSCRIPTIONS_FILE is commented out the same way, but the admin extension is its ONLY
+	// reader and writer (nothing reads it at job time), and the admin's own default IS ./subscriptions.json
+	// (admin/src/read-model.mjs) -- so with the variable unset the one component that cares already finds the
+	// scaffolded file. There is no second reader to disagree with, hence no trap, hence no warn: a line that
+	// fires where nothing is broken teaches operators to skim past the ones that matter.
+	{
+		const pauseWindowsFile = env.PI_PAUSE_WINDOWS_FILE;
+		const scaffolded = join(cwd, "pause-windows.json");
+		if ((typeof pauseWindowsFile !== "string" || pauseWindowsFile.trim() === "") && fileExists(scaffolded)) {
+			checks.push({
+				ok: false,
+				warn: true,
+				label: `${scaffolded} exists but PI_PAUSE_WINDOWS_FILE is unset -- the worker ignores it, so scoped pauses are OFF`,
+				fix: `set PI_PAUSE_WINDOWS_FILE=${scaffolded} in .env and restart the worker -- unset means the worker loads no windows at all, while the admin panel defaults to this same file and reports each window it writes as applied live; delete the file if this deployment has no quiet hours`,
+			});
+		}
+	}
+
 	// REQ-RESURRECTABLE-SANDBOX. A warning, never a failure: retention is a convenience, and the only thing
 	// worth surfacing is that finished runs' directories -- a repository clone plus the run's prompt.md and
 	// event.json, so issue text -- are sitting on disk, and how many. An operator who never opens a sandbox

package/src/processor.mjs

@@ -9,18 +9,21 @@ import { EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY } from "./exit-code.mjs";
  * The order is the contract, and every step before `runContainer` must be free of provider spend:
  *
  *   0. refuse a job image this host does not have  -- INT-CONTAINER-RUNTIME-CONTRACT
- *   1. mint a scoped token (GitHub jobs, and local jobs opted in via `github: true`)
+ *   1. REFUSE an armed `run.resume` with no session store to persist into (the one fail-CLOSED case)
+ *                                                 -- REQ-RESUMABLE-SESSION
+ *   2. mint a scoped token (GitHub jobs, and local jobs opted in via `github: true`)
  *                                                 -- CONST-TOKEN-SCOPED-PER-JOB
- *   2. REFUSE an unprotected default branch (GitHub jobs only -- a local job has no repo)
+ *   3. REFUSE an unprotected default branch (GitHub jobs only -- a local job has no repo)
  *                                                 -- REQ-BRANCH-PROTECTION-PRECONDITION
- *   3. resolve the default-branch SHA (fresh API), clone at it, materialise .pi/, write the prompt
- *   4. reserve a budget slot                      -- CONST-BUDGET-BEFORE-TOKENS
- *   5. ONLY NOW run the container (the only step that spends provider tokens)
- *   6. map the container exit code to retry-vs-success
+ *   4. resolve the default-branch SHA (fresh API), clone at it, materialise .pi/, write the prompt
+ *   5. reserve a budget slot                      -- CONST-BUDGET-BEFORE-TOKENS
+ *   6. ONLY NOW run the container (the only step that spends provider tokens)
+ *   7. map the container exit code to retry-vs-success
  *
  * Budget is reserved as late as possible but strictly before the container, so a refusal from an
- * earlier free gate (unprotected repo, clone failure) never consumes a daily slot. The container
- * is the only thing that spends money, so "before tokens" means "before this line".
+ * earlier free gate (unprotected repo, an armed resume with no store, clone failure) never consumes a
+ * daily slot. The container is the only thing that spends money, so "before tokens" means "before this
+ * line".
  *
  * Returns a result object on a non-retryable outcome; THROWS on a retryable (infra) one so BullMQ
  * retries per `attempts`. The caller (the BullMQ processor) turns the thrown/returned distinction
@@ -41,6 +44,17 @@ export async function runJob(job, deps) {
 		// the store, on a COMPLETED exit only. Never throws. The default is a no-op so a wiring that omits
 		// it behaves exactly as before -- no store, no promotion, no session in the record.
 		promoteSession = () => null,
+		// The session store's root, or null when the feature is unavailable (REQ-RESUMABLE-SESSION). Read
+		// ONLY to answer the fail-closed gate below -- nothing here opens it, and it never reaches the
+		// container env (docker-run.mjs mounts a per-job COPY, never the store).
+		//
+		// The default is the env read config.mjs itself performs (`env.PI_SESSIONS_DIR || null`) rather than
+		// a bare `null`, and the difference is not cosmetic. A `null` default would make the gate refuse
+		// EVERY armed job under any wiring that does not pass this key -- a false refusal that looks exactly
+		// like the true one -- whereas the env is the single source both readers derive from, so the two
+		// cannot disagree about whether a store exists. A wiring may still pass `sessionsDir` explicitly to
+		// make the seam visible; it resolves to the same value.
+		sessionsDir = process.env.PI_SESSIONS_DIR || null,
 		// (job) => scoped short-lived token. Takes the JOB, not the repo: which forge mints -- and therefore
 		// which credential the container gets -- is a property of `job.kind`, and only the wiring knows the
 		// map. Called for forge-backed jobs and for local jobs opted in via `github: true`; unflagged local
@@ -141,6 +155,41 @@ export async function runJob(job, deps) {
 			throw new InfraRetry("docker unavailable, image preflight could not run", { reason: "container-never-started", provider: job.provider ?? null, model: job.model ?? null });
 		}
 
+		// REQ-RESUMABLE-SESSION's one fail-CLOSED case. Everything else in that feature fails OPEN and
+		// NAMES itself -- absent, expired, too-large, unparseable, locked, no key -- because a cold start is
+		// a correct run. This one cannot be: with no `sessionsDir`, resolveSession returns null
+		// (session-store.mjs), so nothing is staged, no /session is mounted, the transcript dies with the
+		// container, and the NEXT job on that key cold-starts too. The job would exit 0 and look like the
+		// feature worked. That is an operator who believes a disclosure is on while it is off, with a green
+		// run to confirm the belief -- the inversion validatePackagesFlag's comment describes one flag over,
+		// arriving from the other direction.
+		//
+		// PLACEMENT IS THE POINT. Free, determinate, credential-less and I/O-less -- the answer is two
+		// values already in hand -- so it belongs among the free policy refusals and strictly before
+		// anything that spends: before the mint (no credential is needed to know the answer, so none is
+		// created only to be discarded), before the branch check's API call, before prepareWorkspace's
+		// clone, before checkTokenCap's read and before reserveBudget's INCR -- hence `budgetReserved:
+		// false`. It sits AFTER the image preflight for the reporting reason the token-cap comment below
+		// already states: a missing image blocks EVERY job of EVERY kind on this host, so it is the one an
+		// operator must fix first either way, while this blocks only the triggers that armed the flag.
+		//
+		// Strict `=== true`, the same test prepare-github.mjs uses to decide whether to resolve a session at
+		// all, so the gate and the feature cannot disagree about what "armed" means. Kind-agnostic on
+		// purpose: only forge jobs can arm the flag today (triggers.mjs refuses it on cron, and a CLI or
+		// chained job has no trigger entry that could set it), but a gate written as an enumeration of kinds
+		// is a gate the next kind skips silently.
+		if (job.resume === true && !sessionsDir) {
+			await comment(job, "Refused: this trigger set `run.resume` but PI_SESSIONS_DIR is unset, so there is nowhere to persist the transcript -- the job would run with no session and still report success. Set PI_SESSIONS_DIR to a private directory outside every repo, or drop `run.resume` from this trigger. Not run.");
+			// The variable NAME, never a value: there is no path to print here (its absence IS the refusal),
+			// and the store's path is the one setting SECURITY.md calls a PII store. `kind` is host-assigned,
+			// the same PII class as the `repo` on the branch refusal below.
+			log("refused_sessions_dir_unset", { kind: job.kind ?? null });
+			// exitCode/turns/tokens null and budgetReserved false: refused pre-container AND pre-reserve,
+			// exactly as the image refusals above. RETURNED, not thrown: an unset environment variable is
+			// determinate, and no number of retries sets it (CONST-RETRY-INFRA-ONLY).
+			return { outcome: "policy", reason: "sessions-dir-unset", exitCode: null, turns: null, tokens: null, provider: job.provider ?? null, model: job.model ?? null, budgetReserved: false }; // return => not retried
+		}
+
 		if (wantsForgeToken) {
 			token = await mintToken(job);
 

package/src/service.mjs

@@ -3,12 +3,27 @@
  *
  * Durable running used to mean hand-editing the per-OS examples in deploy/. This module reads those
  * SAME files from the package and substitutes a documented table of their known literals —
- * `/usr/bin/node` → `process.execPath`, `/opt/pi-dispatch` → the real repo root — rather than
+ * `/usr/bin/node` → `process.execPath`, `/opt/pi-dispatch` → the deployment folder — rather than
  * introducing a `{{placeholder}}` dialect. That keeps the deploy/ files byte-usable examples (and
  * deploy-lint keeps parsing exactly what ships); TEMPLATE_PINS below is the table's enforcement — the
  * test suite asserts every literal is still present in every template, so template drift breaks the
  * build loudly instead of breaking the render silently.
  *
+ * Path doctrine (issue #96): this module used to derive a REPO_ROOT from its own location ("../..").
+ * Right in a checkout; WRONG under `npm install`, where src/ lives at
+ * node_modules/@edgehero/pi-dispatch/src and "../.." is the @edgehero SCOPE directory — every rendered
+ * unit pointed at files that do not exist. Three anchors replace it, each correct in BOTH layouts:
+ *   - deployDir     the deployment folder = the cwd `service` is invoked from. Owns everything
+ *                   host-side: WorkingDirectory, EnvironmentFile (<deployDir>/.env) and the daemon
+ *                   logs (<deployDir>/logs/, created at install time) — never the package dir, which
+ *                   npm may replace wholesale on update.
+ *   - cliPath       join(moduleDir, "cli.mjs"): cli.mjs sits beside this module in src/ in both
+ *                   layouts, so the worker ExecStart needs no repo root at all.
+ *   - receiverStart import.meta.resolve("@edgehero/pi-dispatch-receiver/start"): the receiver
+ *                   package's own exported entry, wherever npm (or the workspace symlink) put it.
+ *                   null when the package is not installed — receiver renders refuse loudly instead
+ *                   of writing a unit that would crash-loop at boot.
+ *
  * Scope doctrine:
  *   - User-level by default, everywhere. macOS REFUSES root outright (a LaunchAgent is per-user, and a
  *     root agent could not see the login session's Docker Desktop anyway — the svc.sh precedent).
@@ -32,12 +47,26 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs } from "node:util";
 
-// Deploy templates resolved relative to this module (the init.mjs pattern): worker/deploy is SHIPPED
-// in the npm tarball and kept byte-identical to the repo-root deploy/ (the documented source) by
-// worker/test/publish.test.mjs — so `service` renders the same templates from a checkout and from an
-// npm install, no matter where the CLI is invoked from.
-const DEPLOY_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "deploy");
-const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+// src/ is where this module lives in BOTH layouts (worker/src in a checkout,
+// node_modules/@edgehero/pi-dispatch/src under npm). Deploy templates resolve one level up from it
+// (the init.mjs pattern): worker/deploy is SHIPPED in the npm tarball and kept byte-identical to the
+// repo-root deploy/ (the documented source) by worker/test/publish.test.mjs — so `service` renders
+// the same templates from a checkout and from an npm install, no matter where the CLI is invoked from.
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+
+/**
+ * The receiver's entry point comes from the receiver PACKAGE (its ./start export), wherever module
+ * resolution finds it from here — the workspace symlink in a checkout, the sibling install under the
+ * deployment folder's node_modules in production. Never a path guessed off this module: that guess is
+ * exactly what issue #96 is about. null = not installed, and the receiver renders refuse on it.
+ */
+function resolveReceiverStart() {
+	try {
+		return fileURLToPath(import.meta.resolve("@edgehero/pi-dispatch-receiver/start"));
+	} catch {
+		return null;
+	}
+}
 
 /**
  * The whole substitution surface, template by template. The render replaces ONLY these literals (plus
@@ -47,9 +76,9 @@ const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
  */
 export const TEMPLATE_PINS = {
 	"worker.service": [
-		"ExecStart=/usr/bin/node worker/src/cli.mjs worker", // /usr/bin/node → process.execPath
-		"WorkingDirectory=/opt/pi-dispatch", // /opt/pi-dispatch → the real repo root
-		"EnvironmentFile=/opt/pi-dispatch/.env",
+		"ExecStart=/usr/bin/node worker/src/cli.mjs worker", // the WHOLE line → `<execPath> <cliPath> worker` (cli.mjs sits beside this module in src/ in both layouts)
+		"WorkingDirectory=/opt/pi-dispatch", // /opt/pi-dispatch → the deployment folder (the cwd `service` runs from)
+		"EnvironmentFile=/opt/pi-dispatch/.env", // → <deployDir>/.env — the operator's .env lives beside the units, never inside the package
 		"\nUser=pi\n", // the DIRECTIVE line (the header comment also says User=pi mid-line, hence the \n anchors): stripped for --user scope; rewritten to the invoking user for --system
 		"WantedBy=multi-user.target", // → default.target in user scope (multi-user.target never runs there)
 		// Byte-for-byte survivors — semantics the render must not lose:
@@ -60,7 +89,7 @@ export const TEMPLATE_PINS = {
 		"TimeoutStopSec=30",
 	],
 	"receiver.service": [
-		"ExecStart=/usr/bin/node receiver/src/start.mjs",
+		"ExecStart=/usr/bin/node receiver/src/start.mjs", // the WHOLE line → `<execPath> <receiverStart>` (the receiver package's resolved ./start export)
 		"WorkingDirectory=/opt/pi-dispatch",
 		"EnvironmentFile=/opt/pi-dispatch/.env",
 		"\nUser=pi\n",
@@ -70,9 +99,9 @@ export const TEMPLATE_PINS = {
 	],
 	"com.pi-dispatch.worker.plist": [
 		"<string>com.pi-dispatch.worker</string>", // → com.pi-dispatch.receiver for --receiver
-		"<string>/opt/pi-dispatch/deploy/worker-env-wrapper.sh</string>", // gains a `receiver` argument for --receiver
-		"<key>WorkingDirectory</key>\n\t<string>/opt/pi-dispatch</string>", // anchor for the PATH injection below
-		"<string>/opt/pi-dispatch/logs/worker.out.log</string>",
+		"<string>/opt/pi-dispatch/deploy/worker-env-wrapper.sh</string>", // → the PACKAGE's wrapper copy, followed by the exec argv (<node> <script> …) the wrapper now runs verbatim
+		"<key>WorkingDirectory</key>\n\t<string>/opt/pi-dispatch</string>", // → the deployment folder (load-bearing: the wrapper sources ./.env there); also the anchor for the PATH injection below
+		"<string>/opt/pi-dispatch/logs/worker.out.log</string>", // → <deployDir>/logs/… (install creates the dir; launchd will not)
 		"<string>/opt/pi-dispatch/logs/worker.err.log</string>",
 		"<key>SuccessfulExit</key>", // the KeepAlive shape the wrapper's exit-2 conversion pairs with
 		"<integer>30</integer>", // ExitTimeOut — room for the SIGTERM drain
@@ -82,8 +111,8 @@ export const TEMPLATE_PINS = {
 	// the two cannot drift apart — especially the AppExit pair, which is the EXIT_POLICY never-retry.
 	"nssm-install.cmd": [
 		"pi-dispatch-worker",
-		"C:\\pi-dispatch", // the REPO placeholder → the real repo root
-		"deploy\\worker-env-wrapper.cmd",
+		"C:\\pi-dispatch", // the REPO placeholder → the deployment folder (cwd)
+		"deploy\\worker-env-wrapper.cmd", // the sequence points at the PACKAGE's wrapper copy and passes the exec argv behind it
 		"AppStopMethodConsole 15000",
 		"AppThrottle 5000",
 		"AppExit Default Restart",
@@ -116,7 +145,11 @@ export async function runService(argv = [], deps = {}) {
 		platform = process.platform,
 		euid = typeof process.geteuid === "function" ? process.geteuid() : null,
 		execPath = process.execPath,
-		repoRoot = REPO_ROOT,
+		// The deployment folder: where the operator ran `service`, where .env lives, where logs/ goes.
+		cwd = process.cwd(),
+		// Injectable so tests can render as if from an npm install without installing anything.
+		moduleDir = MODULE_DIR,
+		resolveReceiver = resolveReceiverStart,
 		home = homedir(),
 		user = env.USER || userInfo().username,
 		tmp = tmpdir(),
@@ -162,12 +195,22 @@ export async function runService(argv = [], deps = {}) {
 	}
 	if (!["darwin", "linux", "win32"].includes(platform)) return fail(err, `unsupported platform: ${platform}`);
 
+	// The templates dir is module-relative like moduleDir itself: worker/deploy in a checkout,
+	// <pkg>/deploy under npm — the SHIPPED copies, correct in both layouts (unlike the old repo root).
+	const templatesDir = resolve(moduleDir, "..", "deploy");
 	const ctx = {
 		env,
 		platform,
 		euid,
 		execPath,
-		repoRoot,
+		deployDir: cwd,
+		cliPath: join(moduleDir, "cli.mjs"),
+		templatesDir,
+		wrapperSh: join(templatesDir, "worker-env-wrapper.sh"),
+		wrapperCmd: join(templatesDir, "worker-env-wrapper.cmd"),
+		// Resolved only when asked for: worker-only invocations must not care whether the receiver
+		// package exists here at all.
+		receiverStart: values.receiver ? resolveReceiver() : null,
 		home,
 		user,
 		tmp,
@@ -240,7 +283,20 @@ function unitPaths(ctx) {
 }
 
 function readTemplate(ctx, name) {
-	return ctx.fs.readFileSync(join(DEPLOY_DIR, name), "utf8");
+	return ctx.fs.readFileSync(join(ctx.templatesDir, name), "utf8");
+}
+
+/**
+ * The receiver refusal, shared by render and install: a null receiverStart means the receiver package
+ * is not resolvable from this worker install. Refusing beats rendering — a unit pointing at a
+ * nonexistent start.mjs would install cleanly and then crash-loop at boot, which is exactly the failure
+ * mode issue #96 shipped for every path.
+ */
+function refuseMissingReceiver(ctx) {
+	return fail(
+		ctx.err,
+		"the receiver package is not installed here — run: npm install @edgehero/pi-dispatch-receiver (from the deployment folder)",
+	);
 }
 
 /**
@@ -250,12 +306,23 @@ function readTemplate(ctx, name) {
  */
 function renderLinuxUnit(ctx) {
 	const template = ctx.which === "receiver" ? "receiver.service" : "worker.service";
+	// The ExecStart line is replaced WHOLE, not path-by-path: the template's script path is relative
+	// to a repo-root WorkingDirectory that only a checkout has. The rendered unit points at absolute
+	// entries that exist in both layouts — cliPath beside this module; the receiver package's ./start
+	// export — so ExecStart works no matter what WorkingDirectory is.
+	const execStart =
+		ctx.which === "receiver"
+			? ["ExecStart=/usr/bin/node receiver/src/start.mjs", `ExecStart=${ctx.execPath} ${ctx.receiverStart}`]
+			: ["ExecStart=/usr/bin/node worker/src/cli.mjs worker", `ExecStart=${ctx.execPath} ${ctx.cliPath} worker`];
 	// The banner outranks the template's own "TEMPLATE/UNTESTED EXAMPLE — set the PLACEHOLDERs" header,
 	// which renders through below (the no-markers design keeps templates byte-usable, so their prose
 	// survives): a reader of the rendered unit should know the placeholders are already substituted.
 	let unit = `# rendered by \`pi-dispatch service\` — paths computed for this host from deploy/${template};\n# the template's PLACEHOLDER prose below is already substituted.\n` +
 		readTemplate(ctx, template)
-		.replaceAll("/opt/pi-dispatch", ctx.repoRoot)
+		.replace(execStart[0], execStart[1])
+		// /opt/pi-dispatch → the deployment folder (the cwd this render ran from): WorkingDirectory and
+		// EnvironmentFile stay operator territory, never the package dir npm may wipe on update.
+		.replaceAll("/opt/pi-dispatch", ctx.deployDir)
 		.replaceAll("/usr/bin/node", ctx.execPath);
 	if (ctx.scope === "user") {
 		// A systemd --user unit always runs as the invoking user, and systemd REJECTS a User= line in
@@ -279,48 +346,67 @@ function renderLinuxUnit(ctx) {
 
 /**
  * Render the launchd plist for this host. For --receiver the worker plist is DERIVED, not a second
- * template: same KeepAlive/ExitTimeOut shape, label and log names swapped, and the shared wrapper told
- * (via its one argument) to run the receiver. The wrapper's exit-2 conversion is a no-op for the
+ * template: same KeepAlive/ExitTimeOut shape, label and log names swapped, and the shared wrapper given
+ * the receiver's exec argv instead of the worker's. The wrapper's exit-2 conversion is a no-op for the
  * receiver — it has no EXIT_POLICY — and harmless.
  */
 function renderPlist(ctx) {
 	let plist = readTemplate(ctx, "com.pi-dispatch.worker.plist");
+	// One wrapper, two daemons: the exec argv IS the difference now. The wrapper sources ./.env in the
+	// unit's WorkingDirectory and runs exactly these arguments — no `receiver` selector flag, no paths
+	// guessed inside the wrapper (issue #96: the wrapper's self-relative guess broke under npm install).
+	const execArgv = ctx.which === "receiver" ? [ctx.execPath, ctx.receiverStart] : [ctx.execPath, ctx.cliPath, "worker"];
 	if (ctx.which === "receiver") {
 		plist = plist
 			.replace("<string>com.pi-dispatch.worker</string>", "<string>com.pi-dispatch.receiver</string>")
-			.replace(
-				"<string>/opt/pi-dispatch/deploy/worker-env-wrapper.sh</string>",
-				"<string>/opt/pi-dispatch/deploy/worker-env-wrapper.sh</string>\n\t\t<!-- the argument that makes the shared .env wrapper run the receiver instead of the worker -->\n\t\t<string>receiver</string>",
-			)
 			.replaceAll("worker.out.log", "receiver.out.log")
 			.replaceAll("worker.err.log", "receiver.err.log");
 	}
-	// launchd's default PATH is /usr/bin:/bin — an nvm or Homebrew node is invisible to it, and the
-	// wrapper invokes bare `node`. Prepend the directory of the node that ran this render so the
-	// service runs the SAME binary, no guessing. PATH is configuration, not a secret: the template's
-	// deliberate no-EnvironmentVariables stance is about credentials, which still live only in .env.
+	// The template's two-element ProgramArguments (sh + wrapper) becomes sh + the PACKAGE's wrapper +
+	// the command: absolute node, absolute script. The wrapper path is module-relative (templatesDir),
+	// so it exists in a checkout AND under node_modules — unlike the old repo-root guess.
+	plist = plist.replace(
+		"<string>/opt/pi-dispatch/deploy/worker-env-wrapper.sh</string>",
+		[
+			`<string>${ctx.wrapperSh}</string>`,
+			"<!-- the command the wrapper execs after sourcing ./.env in WorkingDirectory - absolute paths, nothing guessed -->",
+			...execArgv.map((a) => `<string>${a}</string>`),
+		].join("\n\t\t"),
+	);
+	// launchd's default PATH is /usr/bin:/bin — an nvm or Homebrew node is invisible to it. The exec
+	// argv above pins THIS node absolutely, but the worker's own children (npx-style hooks, tooling
+	// that spawns bare `node`) still resolve via PATH; prepending the render node's directory keeps
+	// them on the SAME binary. PATH is configuration, not a secret: the template's deliberate
+	// no-EnvironmentVariables stance is about credentials, which still live only in .env.
 	plist = plist.replace(
 		"<key>WorkingDirectory</key>\n\t<string>/opt/pi-dispatch</string>",
-		"<key>WorkingDirectory</key>\n\t<string>/opt/pi-dispatch</string>\n\n\t<!-- Injected by `pi-dispatch service`: launchd's default PATH cannot see an nvm/Homebrew node,\n\t     and the wrapper calls bare `node`. Not a secrets dict - credentials still live only in .env\n\t     (see the header comment). -->\n\t<key>EnvironmentVariables</key>\n\t<dict>\n\t\t<key>PATH</key>\n\t\t<string>" +
+		"<key>WorkingDirectory</key>\n\t<string>/opt/pi-dispatch</string>\n\n\t<!-- Injected by `pi-dispatch service`: launchd's default PATH cannot see an nvm/Homebrew node,\n\t     and child processes may call bare `node`. Not a secrets dict - credentials still live only\n\t     in .env (see the header comment). -->\n\t<key>EnvironmentVariables</key>\n\t<dict>\n\t\t<key>PATH</key>\n\t\t<string>" +
 			`${dirname(ctx.execPath)}:/usr/bin:/bin:/usr/sbin:/sbin</string>\n\t</dict>`,
 	);
-	return plist.replaceAll("/opt/pi-dispatch", ctx.repoRoot);
+	// Everything left standing on /opt/pi-dispatch — WorkingDirectory, the log paths, comment prose —
+	// belongs to the deployment folder.
+	return plist.replaceAll("/opt/pi-dispatch", ctx.deployDir);
 }
 
 /**
- * The nssm command sequence — deploy/nssm-install.cmd's exact steps with computed paths. Values that
- * carry semantics (AppStopMethodConsole 15000, AppThrottle 5000, AppExit Default Restart, AppExit 2
- * Exit) mirror the template byte-for-byte and are pinned. Backslashes on purpose: this argv reaches
- * nssm on a real Windows host, where repoRoot is already a Windows path.
+ * The nssm command sequence — deploy/nssm-install.cmd's exact steps with computed paths: the service
+ * Application is the PACKAGE's .cmd wrapper, its AppParameters are the exec argv (<node> <script> …)
+ * the wrapper now runs verbatim, and AppDirectory is the deployment folder so the wrapper finds ./.env
+ * there (the same WorkingDirectory contract as launchd). Values that carry semantics
+ * (AppStopMethodConsole 15000, AppThrottle 5000, AppExit Default Restart, AppExit 2 Exit) mirror the
+ * template byte-for-byte and are pinned. Backslashes on purpose where paths are BUILT here: this argv
+ * reaches nssm on a real Windows host, where deployDir is already a Windows path (wrapperCmd and
+ * cliPath come from win32 path.join and need no help).
  */
 function nssmSequence(ctx) {
 	const service = `pi-dispatch-${ctx.which}`;
-	const logDir = `${ctx.repoRoot}\\logs`;
+	const logDir = `${ctx.deployDir}\\logs`;
+	const execArgv = ctx.which === "receiver" ? [ctx.execPath, ctx.receiverStart] : [ctx.execPath, ctx.cliPath, "worker"];
 	return {
 		service,
 		commands: [
-			["install", service, `${ctx.repoRoot}\\deploy\\worker-env-wrapper.cmd`, ...(ctx.which === "receiver" ? ["receiver"] : [])],
-			["set", service, "AppDirectory", ctx.repoRoot],
+			["install", service, ctx.wrapperCmd, ...execArgv],
+			["set", service, "AppDirectory", ctx.deployDir],
 			["set", service, "AppStdout", `${logDir}\\${ctx.which}.out.log`],
 			["set", service, "AppStderr", `${logDir}\\${ctx.which}.err.log`],
 			["set", service, "AppStopMethodConsole", "15000"],
@@ -332,12 +418,13 @@ function nssmSequence(ctx) {
 }
 
 function doRender(ctx) {
+	if (ctx.which === "receiver" && !ctx.receiverStart) return refuseMissingReceiver(ctx);
 	const paths = unitPaths(ctx);
 	if (ctx.platform === "darwin") {
 		ctx.out(`# → ${paths.installPath}\n`);
 		ctx.out(renderPlist(ctx));
 		ctx.out(
-			"\n# note: ProgramArguments runs deploy/worker-env-wrapper.sh — launchd has no EnvironmentFile,\n# so the wrapper loads .env at runtime. The wrapper also converts a policy refusal (exit 2,\n# EXIT_POLICY) into a clean exit, so KeepAlive never relaunch-loops a refusal into a provider bill.\n",
+			"\n# note: ProgramArguments runs the package's worker-env-wrapper.sh, which sources ./.env in the\n# WorkingDirectory above and then runs the argv that follows it — launchd has no EnvironmentFile.\n# The wrapper also converts a policy refusal (exit 2, EXIT_POLICY) into a clean exit, so KeepAlive\n# never relaunch-loops a refusal into a provider bill.\n",
 		);
 		return 0;
 	}
@@ -354,6 +441,7 @@ function doRender(ctx) {
 }
 
 async function doInstall(ctx) {
+	if (ctx.which === "receiver" && !ctx.receiverStart) return refuseMissingReceiver(ctx);
 	const paths = unitPaths(ctx);
 
 	// THE refusal, worker only: one worker per docker daemon (DES-CONCURRENCY-3). The worker's boot
@@ -396,6 +484,9 @@ async function installDarwin(ctx, paths) {
 		await run(ctx, "launchctl", ["bootout", `gui/${ctx.euid}/${paths.name}`]);
 	}
 	ctx.fs.mkdirSync(dirname(paths.installPath), { recursive: true });
+	// launchd creates the StandardOutPath FILES but not their parent directory: without this the job
+	// spawns and dies with its error unwritable. Done at install, not render — render stays read-only.
+	ctx.fs.mkdirSync(join(ctx.deployDir, "logs"), { recursive: true });
 	ctx.fs.writeFileSync(paths.installPath, renderPlist(ctx));
 	const bootstrap = await run(ctx, "launchctl", ["bootstrap", `gui/${ctx.euid}`, paths.installPath]);
 	if (bootstrap !== 0) {
@@ -459,6 +550,10 @@ async function installWindows(ctx) {
 		const removed = await run(ctx, "nssm", ["remove", service, "confirm"]);
 		if (removed !== 0) return fail(ctx.err, `nssm remove ${service} confirm failed (exit ${removed})`);
 	}
+	// nssm, like launchd, does not create the AppStdout/AppStderr directory. join(), not the
+	// sequence's literal backslashes: this branch runs on the actual Windows host, where join is
+	// win32-flavoured anyway.
+	ctx.fs.mkdirSync(join(ctx.deployDir, "logs"), { recursive: true });
 	for (const args of commands) {
 		const code = await run(ctx, "nssm", args);
 		if (code !== 0) return fail(ctx.err, `nssm ${args.join(" ")} failed (exit ${code})`);

package/src/session-store.mjs

@@ -32,9 +32,12 @@ import { sessionKeyFor } from "./session-key.mjs";
  *
  * NEVER THROWS. Every path returns `{ resume, reason, ... }` or null-ish, because a disk fault must not
  * fail a prepare that only asked whether there was a transcript -- the posture makeFindPreviousRun
- * already sets. The one fail-CLOSED case lives in the processor, not here: a trigger that armed
- * run.resume while PI_SESSIONS_DIR is unset is a pre-spend policy refusal, because running it silently
- * without persistence is the failure validatePackagesFlag's own comment describes.
+ * already sets. The one fail-CLOSED case lives in the processor, not here, and it is a gate this module is
+ * never asked: runJob returns a `sessions-dir-unset` policy refusal for a job whose trigger armed
+ * `run.resume` while `sessionsDir` is null (processor.mjs, before the mint and before reserveBudget), so a
+ * job that reaches `resolveSession` at all has already been proven to have somewhere to persist to.
+ * Refused rather than run, because running it silently without persistence is the failure
+ * validatePackagesFlag's own comment describes.
  */
 
 /** Container-side name, fixed. Nothing key-derived crosses the boundary -- see makeSessionStore. */
@@ -68,7 +71,13 @@ export function makeSessionStore({
 	 */
 	function resolveSession(job, { jobDir, resolved = {}, piVersion = null } = {}) {
 		try {
-			if (!sessionsDir) return null; // feature unavailable; the processor refuses armed triggers earlier
+			// Unreachable in a wired worker, and deliberately kept: resolveSession is only ever called for a
+			// job that armed run.resume (prepare-github.mjs), and processor.mjs refuses exactly that job
+			// pre-spend when this is null -- the `sessions-dir-unset` policy return. This stays as the
+			// DI-seam backstop, because both the store and the preparer are injected and neither can assume
+			// the caller came through that gate; a null here is the same no-mount, nothing-written shape a
+			// pre-feature job had.
+			if (!sessionsDir) return null;
 			const key = sessionKeyFor(job, resolved);
 			// No key is not a failure and not a degradation: this job has no durable identity (a fork PR, a
 			// CLI run, an unresolvable head ref), so it gets no mount and no transcript on disk.

package/src/start.mjs

@@ -352,6 +352,11 @@ export async function startWorker(
 			// Completed-only, so a policy or infra exit leaves the canonical transcript byte-identical and a
 			// retry starts from what the first attempt did (CONST-RETRY-INFRA-ONLY).
 			promoteSession: sessionStore.promoteSession,
+			// The same value the store above was built from, passed explicitly so the processor's fail-closed
+			// `run.resume` gate answers from THIS config rather than from its own env default. Identical on the
+			// real path; the difference shows under an injected env, where the store would be built from the
+			// synthetic value while the gate read the process one.
+			sessionsDir: config.sessionsDir,
 			runContainer: makeRunContainerFn({
 				image: config.jobImage,
 				hostEnv: env,

package/src/triggers.mjs

@@ -183,6 +183,10 @@ function normalizeCron(on, run, index, path, state) {
 
 	const packages = validatePackagesFlag(run, `cron trigger "${id}"`, path);
 	const image = validateImageRef(run, `cron trigger "${id}"`, path);
+	// RETURNED, not discarded like validateReplicas below, because `resume` still has a legal value on a
+	// cron entry: only `true` is refused (the local path has nothing to resume with), so what survives is
+	// `false` or absent. Both must keep reaching the job payload unchanged -- an operator who wrote down
+	// today's default must not get a `data` that disagrees with the file they reviewed.
 	const resume = validateResumeFlag(run, `cron trigger "${id}"`, path);
 	// Called and DISCARDED: on a cron trigger this can only refuse, and the refusal is the point. The
 	// returned `run` below deliberately grows no `replicas` key -- a cron entry can never carry one.
@@ -230,9 +234,25 @@ function validatePackagesFlag(run, at, path) {
  * to host disk and replayed into a later job on the same key. Disclosures default off. Absent and `false`
  * both mean today's behaviour, with not one byte written to disk and no /session mount in the argv.
  *
- * Carried on all four kinds for `run.image`'s reason rather than cron-only like `run.github`: continuing a
- * conversation is a property of the FLOW, and a cron trigger's flow is a flow. A cron job keys on its own
- * scheduler id (session-key.mjs), which is the one key in this feature chosen by nobody untrusted.
+ * REFUSED on a CRON trigger, and the refusal is the honest half of this validator rather than a limit of
+ * the feature. `resolveSession` is handed to the FORGE preparers only (prepare.mjs); the local branch
+ * returns before it is ever in scope, and prepare-local.mjs contains no session code at all -- so an armed
+ * cron trigger stages no transcript, mounts no /session, promotes nothing, and then exits 0 as though it
+ * had. `validateReplicas` states the argument in one line and it applies verbatim here: a field accepted
+ * where it does nothing is how an operator comes to trust one that does nothing.
+ *
+ * "NOT YET COVERED", not impossible -- validateReplicas' own distinction, kept because the two are
+ * different facts and an operator planning work needs the right one. The local key already exists and is
+ * the strongest key in this feature: session-key.mjs keys a cron job on its scheduler id, which is
+ * operator-authored, unique across the file, stable across fires, and chosen by nobody untrusted. Nothing
+ * reaches it. Wiring `resolveSession` into the local path is a feature, and this line is what stops the
+ * flag from pretending that feature landed in the meantime.
+ *
+ * Only `true` is refused, and the asymmetry with validateReplicas -- which refuses ANY value on cron -- is
+ * deliberate. `run.replicas: 1` is refused because a one-member replica set is a flag that does nothing,
+ * so the field has no legal no-op value; `run.resume: false` IS the documented default, so refusing it
+ * would refuse an operator for writing down the behaviour they already have, and would change a normalized
+ * shape that has to stay byte-identical.
  *
  * Strictly boolean and fail-loud, the house rule -- and here the damaging misreading is a truthy `"false"`
  * string, which reads to an operator as an opt-out and would arm the disclosure instead. That is the exact
@@ -240,7 +260,9 @@ function validatePackagesFlag(run, at, path) {
  *
  * Type here, reality at job start, exactly as `run.image` splits it: this cannot know whether
  * PI_SESSIONS_DIR is set, whether a key resolves, or whether a transcript exists. Those are the worker's
- * to answer, and all but the first degrade to a cold start rather than refusing.
+ * to answer, and all but the first degrade to a cold start rather than refusing -- the first is the one
+ * pre-spend policy refusal, `sessions-dir-unset` in processor.mjs (REQ-RESUMABLE-SESSION fails CLOSED
+ * there and only there).
  *
  * `at` is the caller's message prefix. Returns the flag, undefined when absent, so an unflagged trigger
  * normalizes byte-identically to today's.
@@ -249,6 +271,14 @@ function validateResumeFlag(run, at, path) {
 	if (run.resume !== undefined && typeof run.resume !== "boolean") {
 		throw configError(`${at}: run.resume must be true or false when present: ${path}`);
 	}
+	// `run.kind === "local"` IS "this is a cron trigger": normalizeTrigger has already refused every other
+	// pairing of on.type and run.kind, so the matrix makes the two synonyms. The same test validateReplicas
+	// keys its first refusal on, for the same reason -- neither wants to be re-taught the matrix.
+	if (run.resume === true && run.kind === "local") {
+		throw configError(
+			`${at}: run.resume is not yet covered for cron triggers (forge triggers only in this version) -- resolveSession is handed to the forge preparers only, so a local job would stage no transcript, mount no /session and promote nothing, then exit 0 as though it had; the local session key exists in session-key.mjs and nothing reaches it, so this is a gap to close, not a limit: ${path}`,
+		);
+	}
 	return run.resume;
 }