@edgehero/pi-dispatch 1.10.1 → 1.10.3

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.1",
+  "version": "1.10.3",
   "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/host-registry.mjs

@@ -194,9 +194,9 @@ export function makeHostRegistry({ redis, name, now = () => Date.now(), ttlMs =
 
 		/**
 		 * Start beating. ONE `setInterval` -- the first in `worker/src`, every other timer here being a
-		 * `setTimeout` -- and `.unref()`'d so it can never hold the process open, which is the posture the
-		 * three `fs.watch` watchers already take. `stop` is registered as an extraCloser beside the runtime
-		 * queue, so a clean shutdown clears it before `process.exit`.
+		 * `setTimeout` -- and `.unref()`'d so it can never hold the process open. `close` is registered as an
+		 * extraCloser beside the runtime queue, so a clean shutdown clears it before `process.exit`; the three
+		 * `fs.watch` watchers take the same two-part posture since issue #295, unref'd AND closed.
 		 */
 		async start(fields = {}, { intervalMs = HOST_BEAT_MS } = {}) {
 			if (closed || timer) return; // a second start would leak the first interval

package/src/index.mjs

@@ -836,10 +836,30 @@ export function createWorker({ connection, name, stopContainer, containerName, h
 		// outlive the handler that was meant to stop them.
 		for (const w of workers) await Promise.resolve(w.cancelAllJobs?.("shutdown")).catch(() => {});
 		for (const w of workers) await w.close().catch(() => {});
-		// Close auxiliary resources (e.g. a cron scheduler) after the worker drains. Per-item catch
-		// so one failing or absent closer never strands the others or blocks exit -- matches the
-		// swallow posture on cancelAllJobs above.
-		await Promise.all(extraClosers.map((c) => Promise.resolve(c.close?.()).catch(() => {})));
+		// Close auxiliary resources (a cron scheduler, the live-edit file watchers) after the worker drains.
+		// Per-item catch so one failing or absent closer never strands the others or blocks exit -- matches
+		// the swallow posture on cancelAllJobs above. The try/catch is NOT redundant with the `.catch`:
+		// `Promise.resolve(x)` does not catch a SYNCHRONOUS throw from `x`, and `c.close` on a null entry
+		// throws before `Promise.resolve` is ever reached. Either would escape this callback, reject the whole
+		// shutdown and skip the `process.exit(0)` below. Jobs and containers are already stopped by then, so
+		// what a stranded loop leaks is the rest of the list: `registry.close()` is the DEL that keeps a
+		// stopped host from lingering as a ghost peer for its full TTL, and a ghost peer with a stale
+		// `fpCron` is what makes a later `reconcileGated` refuse a legitimate reconcile. The comment above
+		// promised this isolation before the code delivered it (issue #295). It bounds nothing, though: a
+		// closer that never settles still blocks exit, which no closer here does.
+		//
+		// Read LATE and deliberately: `start.mjs` pushes its live-edit watchers into this array AFTER handing
+		// it over, because they are armed after the boot reconcile. Anything here that snapshots or copies
+		// the array un-registers them in silence.
+		await Promise.all(
+			extraClosers.map((c) => {
+				try {
+					return Promise.resolve(c?.close?.()).catch(() => {});
+				} catch {
+					return Promise.resolve();
+				}
+			}),
+		);
 		process.exit(0);
 	};
 	process.once("SIGTERM", shutdown);

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 },

package/src/start.mjs

@@ -84,57 +84,144 @@ const WORKER_VERSION = (() => {
  * `reap()` NEVER throws: a missing docker binary or a down daemon is caught, logged as
  * `reaper_skipped`, and boot continues to the worker.
  */
+/**
+ * The stop handle every live-edit watch below hands back, so `startWorker` can register it in the same
+ * `extraClosers` list that already closes the queues and the host registry (`index.mjs` -> shutdown).
+ *
+ * A WATCH NOTHING CAN CLOSE IS NOT A DETAIL (issue #295). `watch(dir, cb).unref?.()` retained nothing, so
+ * the watch outlived the worker that armed it, and the reload it later fired ran through THAT boot's
+ * `log` closure: that boot's injected `write`, stamped with that boot's `workerName`. One process running
+ * one worker, that is a rounding error at exit. One process running forty boots, which is what a test file
+ * is, and a worker that shut down two tests ago writes into a live worker's capture under a host that is
+ * not running -- `every log line carries the host` went red in CI reading `runnervmejwal` where it
+ * asserted `mac-mini-1`.
+ *
+ * UNREF'D IS NOT CLEANED UP, and that difference is what hid this across three features. `unref` says only
+ * that a handle will not hold the event loop open; the watch stays armed either way.
+ * `INT-HOST-REGISTRY-CONTRACT` states the same distinction from the opposite side, where a bound's timer
+ * is deliberately NOT unref'd because an unref'd timer does not fire when the hung command is the last
+ * thing holding the loop.
+ *
+ * Three properties, each one a way the shutdown breaks without it:
+ *
+ * - It CLOSES the FSWatcher, which is the leak itself.
+ * - It CANCELS the debounce the watcher already armed. Closing a watcher does not cancel a `setTimeout`
+ *   the callback already set, and only the watcher was ever unref'd -- the 150ms timer never was. In a
+ *   real worker that costs nothing, because the shutdown ends in `process.exit(0)` either way; it is the
+ *   harness, where the loop is left to drain on its own, that the stray timer reaches.
+ * - Its `close()` NEVER THROWS for the handles its three callers build, and is idempotent -- by NULLING
+ *   what it closed rather than by an early return, which would be a guard with nothing behind it. Node's
+ *   own `FSWatcher.close()` is already both (measured: a second close returns early and neither throws),
+ *   but this closer must not
+ *   INHERIT that guarantee, it must MAKE it: the shutdown loop in `index.mjs` cannot catch a SYNCHRONOUS
+ *   throw from a closer, and the comment there carries the argument. The swallow is
+ *   `makeHostRegistry.close`'s posture rather than a new one.
+ *
+ * A watch that was never created -- the `catch` arm of each function below, a platform without `fs.watch`
+ * -- still gets a closer, so registration is unconditional and the list's shape never depends on the
+ * platform. That is why all three return from OUTSIDE their try/catch.
+ *
+ * WHAT IT CANNOT DO, because the list above would otherwise read as complete: cancel a reload that has
+ * ALREADY started. `reloadSchedules` is async and awaits a Valkey round trip, so a debounce that fired
+ * just before the close is still running after it -- and the watchers stay armed for the whole drain
+ * ahead of the closer loop, not merely 150ms. That reload cannot be recalled, so what is gated instead is
+ * its VOICE: `reloadLog` below goes quiet once `closed` is set, and every reload is handed that instead
+ * of the boot's own `log`, which is what the
+ * issue actually asks for -- a stopped worker writes no line. The reload's own Valkey work may still be
+ * cut off mid-flight by the queue closing beside it, leaving a scheduler set the next boot's reconcile
+ * repairs; that race predates this change and is not narrowed by it.
+ *
+ * EXPORTED for the reason `reloadScopedLimits` is: none of the three properties is observable through a
+ * real `fs.watch` without racing the filesystem, and a guarantee the shutdown rests on deserves a
+ * deterministic pin rather than a sleep.
+ */
+export function makeWatchCloser(handles, log) {
+	return {
+		// The reload's voice, and the reason this factory is handed the boot's `log` rather than only its
+		// handles. A reload already in flight cannot be recalled, so what the close gates is what it can
+		// still SAY: after `closed`, a line from this watch would carry the host of a worker that has
+		// stopped, which is the bleed the issue is about. The arming lines keep the real `log` -- they run
+		// before any close.
+		reloadLog: (event, fields) => {
+			if (!handles.closed) log(event, fields);
+		},
+		close() {
+			// `closed` FIRST, before anything is torn down: it is what gates `reloadLog` above and the watch
+			// callback below, so a callback or a reload landing mid-close is already silenced.
+			handles.closed = true;
+			clearTimeout(handles.timer);
+			handles.timer = null;
+			try {
+				handles.watcher?.close();
+			} catch {
+				// A close that failed has already stopped mattering, and a THROW here rejects the shutdown.
+			}
+			handles.watcher = null;
+		},
+	};
+}
+
 /**
  * Watch the DIRECTORY holding the triggers file (robust to the admin's atomic tmp+rename, which swaps the
  * inode a file-watch would lose), debounce, and re-reconcile the cron schedulers on change via
- * `reloadSchedules`. Best-effort and unref'd so it never blocks shutdown; a platform without `fs.watch`
- * logs and the worker keeps its boot-time schedulers.
+ * `reloadSchedules`. Best-effort: a platform without `fs.watch` logs and the worker keeps its boot-time
+ * schedulers. The FSWatcher is unref'd (the debounce it arms is NOT), and the returned closer is what
+ * `startWorker` registers so the watch dies with the worker that armed it (issue #295).
  */
 function watchTriggersFile(config, queue, log, ref, registry, tz, fleet) {
 	const path = config.triggersFile;
 	const dir = dirname(path) || ".";
 	const file = basename(path);
-	let timer = null;
+	const handles = { watcher: null, timer: null, closed: false };
+	const closer = makeWatchCloser(handles, log);
 	try {
-		watch(dir, (_event, changed) => {
+		handles.watcher = watch(dir, (_event, changed) => {
+			if (handles.closed) return; // see makeWatchCloser: by construction, not by a delivery rule
 			if (changed && changed !== file) return; // only our file (a null name -> reload to be safe)
-			clearTimeout(timer);
-			timer = setTimeout(() => void reloadSchedules(config, queue, { log, ref, registry, tz, fleet }), 150);
-		}).unref?.();
+			clearTimeout(handles.timer);
+			handles.timer = setTimeout(() => void reloadSchedules(config, queue, { log: closer.reloadLog, ref, registry, tz, fleet }), 150);
+		});
+		handles.watcher.unref?.();
 		log("triggers_watching", { path });
 	} catch (err) {
 		log("triggers_watch_unavailable", { reason: err?.message });
 	}
+	return closer;
 }
 
 /**
  * Watch the DIRECTORY holding the pause-windows file (same atomic-rename robustness as the triggers watch)
  * and hot-swap the in-memory windows in `ref.current` on change. A bad edit keeps the last-good windows in
- * effect (OQ-008 live-edit safety) — the pause gate never loses its config to a typo. Best-effort + unref'd.
+ * effect (OQ-008 live-edit safety) — the pause gate never loses its config to a typo. Best-effort; the
+ * FSWatcher is unref'd and the returned closer stops the watch with the worker (issue #295).
  */
 function watchPauseWindowsFile(config, ref, log) {
 	const path = config.pauseWindowsFile;
 	const dir = dirname(path) || ".";
 	const file = basename(path);
-	let timer = null;
+	const handles = { watcher: null, timer: null, closed: false };
+	const closer = makeWatchCloser(handles, log);
 	const reload = () => {
 		try {
 			ref.current = loadPauseWindows(config);
-			log("pause_windows_reloaded", { count: ref.current.length });
+			closer.reloadLog("pause_windows_reloaded", { count: ref.current.length });
 		} catch (err) {
-			log("pause_windows_reload_invalid", { reason: err?.message });
+			closer.reloadLog("pause_windows_reload_invalid", { reason: err?.message });
 		}
 	};
 	try {
-		watch(dir, (_event, changed) => {
+		handles.watcher = watch(dir, (_event, changed) => {
+			if (handles.closed) return; // see makeWatchCloser: by construction, not by a delivery rule
 			if (changed && changed !== file) return;
-			clearTimeout(timer);
-			timer = setTimeout(reload, 150);
-		}).unref?.();
+			clearTimeout(handles.timer);
+			handles.timer = setTimeout(reload, 150);
+		});
+		handles.watcher.unref?.();
 		log("pause_windows_watching", { path });
 	} catch (err) {
 		log("pause_windows_watch_unavailable", { reason: err?.message });
 	}
+	return closer;
 }
 
 /**
@@ -154,23 +241,28 @@ export function reloadScopedLimits(config, ref, log) {
 
 /**
  * Watch the scoped-limits file (issue #242) the way the pause-windows watcher above does: the DIRECTORY,
- * for atomic tmp+rename robustness, filtered to the one basename, debounced. Best-effort + unref'd.
+ * for atomic tmp+rename robustness, filtered to the one basename, debounced. Best-effort; the FSWatcher is
+ * unref'd and the returned closer stops the watch with the worker (issue #295).
  */
 function watchScopedLimitsFile(config, ref, log) {
 	const path = config.scopedLimitsFile;
 	const dir = dirname(path) || ".";
 	const file = basename(path);
-	let timer = null;
+	const handles = { watcher: null, timer: null, closed: false };
+	const closer = makeWatchCloser(handles, log);
 	try {
-		watch(dir, (_event, changed) => {
+		handles.watcher = watch(dir, (_event, changed) => {
+			if (handles.closed) return; // see makeWatchCloser: by construction, not by a delivery rule
 			if (changed && changed !== file) return;
-			clearTimeout(timer);
-			timer = setTimeout(() => reloadScopedLimits(config, ref, log), 150);
-		}).unref?.();
+			clearTimeout(handles.timer);
+			handles.timer = setTimeout(() => reloadScopedLimits(config, ref, closer.reloadLog), 150);
+		});
+		handles.watcher.unref?.();
 		log("scoped_limits_watching", { path });
 	} catch (err) {
 		log("scoped_limits_watch_unavailable", { reason: err?.message });
 	}
+	return closer;
 }
 
 /**
@@ -677,6 +769,18 @@ export async function startWorker(
 		reaps: backendReaps,
 	});
 
+	// The auxiliary handles the shutdown closes after the worker drains (`index.mjs` -> shutdown). A NAMED
+	// array rather than the literal it used to be, because up to three of its members do not exist yet: the
+	// live-edit watchers are armed at the END of boot, below, and deliberately after the boot reconcile --
+	// arming them earlier would let an operator edit run `reloadSchedules` concurrently with the boot
+	// `reconcileGated`, on a different queue handle, and reconcile's orphan prune is not safe against that.
+	//
+	// PUSHING AFTER THE HANDOFF IS SOUND FOR ONE REASON ONLY: `index.mjs` reads this array at SHUTDOWN time,
+	// not when it receives it, and so does the test harness at teardown. A refactor that COPIES it there --
+	// a spread, a freeze, a snapshot inside `createWorker` -- un-registers the watchers in SILENCE and puts
+	// issue #295 back. Append only: two tests pin `[0]` as the runtime queue and `[1]` as the registry.
+	const extraClosers = [runtimeQueue, registry, ...(cronQueue === runtimeQueue ? [] : [cronQueue])];
+
 	const worker = createWorkerFn({
 		connection: parseConnection(config.valkeyUrl),
 		// #227. The abort path's stop, resolved per job rather than hard-wired to docker. A container NAME is
@@ -696,7 +800,7 @@ export async function startWorker(
 		getSettings,
 		redis,
 		recordRun,
-		extraClosers: [runtimeQueue, registry, ...(cronQueue === runtimeQueue ? [] : [cronQueue])],
+		extraClosers,
 		// REQ-SCOPED-PAUSE-WINDOWS: the processor defers a job whose folder/repo is inside an active window.
 		// Reads the live-reloaded ref, so an operator edit takes effect on the next job without a restart.
 		pauseUntil: (job, now) => pauseUntilMs(pauseWindows.current, job, now),
@@ -931,20 +1035,21 @@ export async function startWorker(
 
 	// DES-CRON-VIA-BULLMQ-SCHEDULER live edit (OQ-008): watch the triggers file and re-reconcile schedulers
 	// on change, so an operator's add/edit/delete of a cron trigger takes effect without a worker restart.
-	// Only when a triggers file is configured; best-effort + unref'd; a bad edit keeps the running schedulers.
+	// Only when a triggers file is configured; best-effort; a bad edit keeps the running schedulers. The
+	// closer each of the three returns joins `extraClosers`, so the watch stops with the worker (issue #295).
 	if (config.triggersFile) {
-		watchTriggersFile(config, cronQueue, log, schedules, registry, hostTz, config.workerNameDeclared);
+		extraClosers.push(watchTriggersFile(config, cronQueue, log, schedules, registry, hostTz, config.workerNameDeclared));
 	}
 
 	// REQ-SCOPED-PAUSE-WINDOWS live edit: watch the pause-windows file and hot-swap the in-memory windows, so
 	// an operator's add/delete of a pause window takes effect without a worker restart. A bad edit is kept out.
 	if (config.pauseWindowsFile) {
-		watchPauseWindowsFile(config, pauseWindows, log);
+		extraClosers.push(watchPauseWindowsFile(config, pauseWindows, log));
 	}
 
 	// Issue #242 live edit: hot-swap the scoped limits on file change, keeping last-good on a bad edit.
 	if (config.scopedLimitsFile) {
-		watchScopedLimitsFile(config, scopedLimits, log);
+		extraClosers.push(watchScopedLimitsFile(config, scopedLimits, log));
 	}
 
 	log("worker_started", {