@edgehero/pi-dispatch 0.1.2 → 0.3.0

package/src/prepare.mjs

@@ -1,4 +1,4 @@
-import { mkdirSync, mkdtempSync } from "node:fs";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
 import { rm } from "node:fs/promises";
 import { join } from "node:path";
 import { resolveJobImage } from "./image-preflight.mjs";
@@ -11,6 +11,17 @@ import { buildGitLabPrompt } from "./gitlab-prompt.mjs";
 import { buildForgejoPrompt } from "./forgejo-prompt.mjs";
 import { buildAzurePrompt } from "./azure-prompt.mjs";
 import { prepareLocalWorkspace } from "./prepare-local.mjs";
+import { copySkillTree } from "./copy-tree.mjs";
+
+/**
+ * The subdirectory of the per-job dir a trigger's injected skills are copied into, so they reach the
+ * container at `/job/trigger-skills` on the `/job:ro` bind that already exists.
+ *
+ * The runner spells the same last segment from its own side (TRIGGER_SKILLS_DIR in
+ * image/runner/src/loader.mjs). It is not on this host and this file is not in that container, so the
+ * duplication is forced. CHANGE BOTH, IN THE SAME COMMIT.
+ */
+export const TRIGGER_SKILLS_SUBDIR = "trigger-skills";
 
 /**
  * The `prepareWorkspace` dispatcher the processor injects. Creates a per-job dir under `jobsDir`
@@ -45,10 +56,34 @@ export function makePrepareWorkspace({
 	// Keyed by `job.kind`, so a new forge is one entry rather than a new `if`. A kind with no entry falls
 	// through to the throw below, which is what makes an unrouted job loud instead of a silent no-op.
 	preparers = { github: prepareGithubWorkspace },
+	// REQ-PER-TRIGGER-SKILLS. Injected so the copy is testable without a real host tree, and defaulted so
+	// an unwired dispatcher behaves exactly as it did: a job with no `run.skillsDir` never calls it.
+	injectSkills = copySkillTree,
+	log = () => {},
 }) {
 	mkdirSync(jobsDir, { recursive: true });
 	return async function prepareWorkspace(job, token, { queueJobId, piVersion = null } = {}) {
 		const jobDir = mkdtempSync(join(jobsDir, "job-"));
+		// The trigger's injected skills (REQ-PER-TRIGGER-SKILLS, issue #60), COPIED here rather than
+		// mounted, and copied ONCE for every job kind because this is where local and forge converge.
+		//
+		// Copied, not bind-mounted, and that is the decision rather than the implementation. `:ro` bounds
+		// the CONTAINER, not the host, and pi reads a skill's body on demand through the read tool, so a
+		// live bind could change under a running agent -- the copy is what pins the instruction set for the
+		// life of the job, exactly as materialising .pi/ at a fixed sha does for the repo's own. It also
+		// answers symlinks once, on the side that can (copy-tree.mjs), instead of handing pi a tree whose
+		// links it would follow. And it adds NO mount, so CONST-ISOLATION-CONTAINER-PER-JOB's enumeration
+		// is untouched -- the same trade DES-OPERATOR-GLOBAL-OVERLAY made for staged packages.
+		if (job.skillsDir) {
+			const injected = injectSkills(job.skillsDir, join(jobDir, TRIGGER_SKILLS_SUBDIR));
+			if (injected?.refused) {
+				rmSync(jobDir, { recursive: true, force: true });
+				return { outcome: "policy", reason: injected.refused };
+			}
+			// Counts only. `injected` carries no name and no path by construction, so this line cannot grow
+			// a host path by a later edit (the same shape packages.mjs's `dropped` record has).
+			log("trigger_skills_injected", { dirs: injected.dirs, files: injected.files, bytes: injected.bytes });
+		}
 		// What `cleanup` needs to retain this run's directory, stamped here because this is the only place
 		// that holds all three at once. Applied to the RESULT rather than mutated in, so a preparer's
 		// `{ outcome: "policy" }` refusal -- which carries no jobDir -- is passed through untouched.
@@ -63,23 +98,26 @@ export function makePrepareWorkspace({
 				? `Use the "${job.flow}" skill for this task.\n\n${pointer}${job.task ?? ""}`
 				: `${pointer}${job.task ?? ""}`;
 			const event = localEventContext(job, queueJobId, findPreviousRun);
-			return stampSandbox(await prepareLocal({ folder: job.folder, task, jobDir, event }), sandbox);
+			return discardOnPolicy(stampSandbox(await prepareLocal({ folder: job.folder, task, jobDir, event }), sandbox), jobDir);
 		}
 		const prepare = preparers[job.kind];
 		if (prepare) {
 			const host = forgeFor?.(job)?.host;
-			return stampSandbox(
-				await prepare(job, token, {
-					jobDir,
-					resolveDefaultBranchSha: host?.resolveDefaultBranchSha,
-					// The head ref a pull/merge-request job keys on comes from the FORGE API, never the webhook
-					// payload: an issue_comment on a PR carries no head at all, and a payload-supplied head repo
-					// is attacker-controlled data that must not decide which transcript a job is handed.
-					resolvePullRequestHead: host?.resolvePullRequestHead,
-					resolveSession,
-					piVersion,
-				}),
-				sandbox,
+			return discardOnPolicy(
+				stampSandbox(
+					await prepare(job, token, {
+						jobDir,
+						resolveDefaultBranchSha: host?.resolveDefaultBranchSha,
+						// The head ref a pull/merge-request job keys on comes from the FORGE API, never the webhook
+						// payload: an issue_comment on a PR carries no head at all, and a payload-supplied head repo
+						// is attacker-controlled data that must not decide which transcript a job is handed.
+						resolvePullRequestHead: host?.resolvePullRequestHead,
+						resolveSession,
+						piVersion,
+					}),
+					sandbox,
+				),
+				jobDir,
 			);
 		}
 		throw new Error(`unknown job kind: ${job.kind}`);
@@ -131,6 +169,27 @@ function stampSandbox(prepared, sandbox) {
 	return { ...prepared, sandbox };
 }
 
+/**
+ * Remove the mkdtemp'd job dir when the preparer REFUSED, because nothing downstream will.
+ *
+ * A determinate refusal carries no `jobDir` (see stampSandbox), and both teardown paths -- `cleanup`
+ * and `makeCleanup`'s retention branch -- guard on `prepared?.jobDir`. So the directory this function
+ * created two dozen lines up, which by then may hold a partial clone, was simply left on disk: one
+ * per refusal, forever. That has been true of `sha-gone` since it shipped and was only ever invisible
+ * because refusals are rare; issue #60 adds cap refusals that a misconfigured repo hits on EVERY
+ * delivery, which turns a slow leak into a fast one.
+ *
+ * Deliberately not folded into stampSandbox: that function's job is to decide what a RESULT carries,
+ * and a filesystem side effect hidden inside it would be the kind of thing the next reader has to
+ * discover. Deliberately `rmSync` rather than the async `rm`, so the directory is gone before the
+ * refusal is returned and no teardown ordering has to be reasoned about.
+ */
+function discardOnPolicy(prepared, jobDir) {
+	if (prepared?.outcome !== "policy") return prepared;
+	rmSync(jobDir, { recursive: true, force: true });
+	return prepared;
+}
+
 /** Remove a per-job dir after the run. The workspace (the operator's folder) is never touched here. */
 export async function cleanup(prepared) {
 	if (prepared?.jobDir) await rm(prepared.jobDir, { recursive: true, force: true });

package/src/processor.mjs

@@ -1,3 +1,4 @@
+import { lstatSync } from "node:fs";
 import { checkTokenCap, recordTokenSpend, releaseBudget, reserveBudget } from "./budget.mjs";
 import { configError } from "./config.mjs";
 import { EXIT_COMPLETED, EXIT_INFRA, EXIT_POLICY } from "./exit-code.mjs";
@@ -55,6 +56,17 @@ export async function runJob(job, deps) {
 		// 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,
+		// REQ-PER-TRIGGER-SKILLS. Injected so the pre-spend gate is testable without a real directory, and
+		// lstat rather than stat so a symlinked skillsDir is judged on its own inode -- the habit copy-tree.mjs,
+		// outbox.mjs and sandbox-store.mjs all keep. A throw is a refusal: an unreadable path is still absent
+		// as far as this job is concerned.
+		isReadableDir = (p) => {
+			try {
+				return lstatSync(p).isDirectory();
+			} catch {
+				return false;
+			}
+		},
 		// (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
@@ -156,8 +168,8 @@ export async function runJob(job, deps) {
 		}
 
 		// 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
+		// NAMES itself -- absent, expired, too-large, unparseable, locked, promote-failed -- 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
@@ -190,6 +202,23 @@ export async function runJob(job, deps) {
 			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
 		}
 
+		// REQ-PER-TRIGGER-SKILLS. A trigger that named a skills directory the worker cannot see would run
+		// its flow WITHOUT the skills it was written against, produce a plausible report, and exit 0. Free
+		// and determinate -- one lstat, no credential needed to know the answer -- so it belongs among the
+		// free refusals and strictly before anything that spends: before the mint (no token is created only
+		// to be discarded), before the clone, before the token-cap read and before reserveBudget
+		// (CONST-BUDGET-BEFORE-TOKENS). Last among the free gates because it is the NARROWEST: a missing
+		// image blocks every job on this host, an unset sessions dir blocks every armed trigger, a bad
+		// skillsDir blocks one trigger.
+		if (job.skillsDir && !isReadableDir(job.skillsDir)) {
+			await comment(job, "Refused: this trigger set `run.skillsDir`, and that path is absent or is not a directory on the worker host. The job would have run without the skills the flow was written against. Not run.");
+			// The FIELD name, never its value. `comment` posts publicly on the issue, so a host path here
+			// would publish the operator's filesystem layout to anyone reading the thread; the log line is
+			// the same restraint refused_sessions_dir_unset keeps.
+			log("refused_skills_dir_missing", { kind: job.kind ?? null });
+			return { outcome: "policy", reason: "skills-dir-missing", 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);
 
@@ -216,8 +245,9 @@ export async function runJob(job, deps) {
 
 		prepared = await prepareWorkspace(job, token, { piVersion }); // resolves SHA, clones, materialises .pi/, writes prompt
 
-		// A determinate prepare refusal (e.g. sha-gone: the default branch advanced past the resolved
-		// tip) is POLICY -- return before reserveBudget so it burns no cap slot and is never retried.
+		// A determinate prepare refusal -- sha-gone (the default branch advanced past the resolved tip),
+		// or a `pi-*` materialiser cap breach (the repo's .pi/ is too large to place in /job, issue #60)
+		// -- is POLICY: return before reserveBudget so it burns no cap slot and is never retried.
 		// Mirrors the branch-protection policy return above. Spread-plus-attribution: the prepare
 		// result keeps its own reason and fields, and the host-effective provider/model land beside
 		// them exactly as on every other terminal result.

package/src/queue.mjs

@@ -16,7 +16,7 @@ export function makeQueue(connection) {
  * removeOnComplete keeps the dedup window ~= the retention. Unlike webhooks, local jobs are not
  * redelivered, so a modest window is enough.
  */
-export async function enqueueLocalJob(queue, { folder, flow, task, provider, model, maxTurns, image, chainDepth, parentJobId, jobId, now = new Date() }) {
+export async function enqueueLocalJob(queue, { folder, flow, task, provider, model, maxTurns, image, skillsDir, chainDepth, parentJobId, jobId, now = new Date() }) {
 	const minute = now.toISOString().slice(0, 16); // YYYY-MM-DDTHH:MM -- the dedup window
 	// A caller-supplied jobId (the outbox collector's retry-idempotent chainedJobId) wins; otherwise the
 	// minute-windowed localJobId is the dedup key.
@@ -33,6 +33,11 @@ export async function enqueueLocalJob(queue, { folder, flow, task, provider, mod
 		model,
 		maxTurns,
 		...(image !== undefined && { image }),
+		// The host directory of operator-authored skills this trigger injects (REQ-PER-TRIGGER-SKILLS).
+		// Conditional like `image`, so an unflagged job's data stays byte-identical, and at JOB level rather
+		// than inside `trigger` because a worker-host path is an execution knob, not a fact about the
+		// delivery -- and `trigger` is the object copied into /job/event.json.
+		...(skillsDir !== undefined && { skillsDir }),
 		...(chainDepth !== undefined && { chainDepth }),
 		...(parentJobId !== undefined && { parentJobId }),
 	};
@@ -110,7 +115,7 @@ export async function enqueueGitLabJob(queue, fields) {
  * window, replicas never coalesce against each other, and an unflagged job's dedup id is the same string it
  * has always been.
  */
-export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, trigger, provider, model, maxTurns, packages, image, resume, replica, replicas }) {
+export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, target, flow, trigger, provider, model, maxTurns, packages, image, skillsDir, instructions, resume, replica, replicas }) {
 	const jobId = forgeDeliveryJobId(kind, trigger?.deliveryId, replica);
 	// `packages` (whether to load the operator-staged pi packages) and `image` (which container image to run)
 	// come off the MATCHED trigger (INT-TRIGGERS-FILE-CONTRACT / REQ-GLOBAL-PI-OVERLAY) and land on `data`
@@ -133,6 +138,15 @@ export async function enqueueForgeJob(queue, kind, { repo, projectId, azure, tar
 		maxTurns,
 		...(packages !== undefined && { packages }),
 		...(image !== undefined && { image }),
+		// The host directory of operator-authored skills this trigger injects (REQ-PER-TRIGGER-SKILLS).
+		// Conditional like `image`, so an unflagged job's data stays byte-identical, and at JOB level rather
+		// than inside `trigger` because a worker-host path is an execution knob, not a fact about the
+		// delivery -- and `trigger` is the object copied into /job/event.json.
+		...(skillsDir !== undefined && { skillsDir }),
+		// The operator's standing instruction for this trigger (REQ-PER-TRIGGER-INSTRUCTION). Conditional like
+		// the rest, and at JOB level rather than inside `trigger`: it is operator config, not a fact about the
+		// delivery, and `trigger` is what /job/event.json is built from.
+		...(instructions !== undefined && { instructions }),
 		...(resume !== undefined && { resume }),
 		// Conditional for the same reason packages/image/resume are: an unflagged job's data must keep
 		// exactly the keys it has today. `replica` is this job's 1-based index and `replicas` the set size;

package/src/run-container.mjs

@@ -33,7 +33,10 @@ export function makeRunContainer({
 	spawnFn = spawn,
 	globalPiDir = null, // REQ-GLOBAL-PI-OVERLAY: operator's global pi overlay dir, mounted :ro; null = off
 	allowGlobalExtensions = true, // REQ-GLOBAL-PI-OVERLAY: the staged overlay's extensions load unless PI_GLOBAL_ALLOW_EXTENSIONS=0
-	packagePaths = [], // REQ-GLOBAL-PI-OVERLAY: container paths of the operator-staged packages, resolved once at boot
+	// REQ-GLOBAL-PI-OVERLAY: container paths of the operator-staged packages. An array, or a RESOLVER called
+	// once per job (issue #102): the wired worker passes a resolver so a re-stage lands on the next job with
+	// no restart, while the array form stays valid for every caller that has a fixed set.
+	packagePaths = [],
 	forwardEnv = [],
 	authFromPi = false, // fall back to ~/.pi/agent/auth.json for the provider key when the env has none
 	forgeHosts = {}, // per-forge self-hosted instance URLs, so a forge CLI in the container talks to the right one
@@ -63,7 +66,9 @@ export function makeRunContainer({
 			// (INT-TRIGGERS-FILE-CONTRACT). The strictness that used to live in this `=== true` did not
 			// disappear, it moved: parseTriggers refuses any non-boolean run.packages fail-loud at load, so a
 			// hand-edited string "false" never becomes job data this comparison could misread as an opt-out.
-			packagePaths: job.packages === false ? [] : packagePaths,
+			// The opt-out short-circuits BEFORE the resolver runs: a trigger that withheld the staged set has no
+			// reason to make the worker read the manifest on its behalf.
+			packagePaths: job.packages === false ? [] : typeof packagePaths === "function" ? packagePaths() : packagePaths,
 			forwardEnv, // extra host var names to forward (e.g. a custom provider's key)
 			// REQ-RESUMABLE-SESSION: the fixed container path, emitted only when this job HAS a transcript.
 			// The constant is imported rather than re-typed so the mount below and this variable name one

package/src/run-history.mjs

@@ -295,6 +295,19 @@ export function buildRecord({ job, result, error, startedAt, endedAt }) {
 		// deliberately not stored, for the reason `session` states one group below.
 		replica: data.replica ?? null,
 		replicas: data.replicas ?? null,
+		// Trigger attribution (INT-RUN-HISTORY-FILE-CONTRACT, issue #54): additive and nullable, explicit
+		// literals beside the replica fields whose admissibility argument they reuse, no spread. Both read
+		// the receiver's harness-computed `matched` from this job's own `job.data.trigger`: `index` is the
+		// raw triggers-array position of the entry that fired (cron entries counted) and `type` that entry's
+		// `on.type` -- an INTEGER and a FIXED ENUM ("label" | "comment" | "pull_request"), nothing
+		// attacker-chosen. The third `matched` key (`label`/`phrase`/`action`) is DELIBERATELY absent:
+		// a label that satisfied an `any` predicate is collaborator-applied payload text, and `type`
+		// already names the route. Cron jobs carry `trigger: { id, pattern }` with no `matched`, so both
+		// stay null there on purpose -- a cron run's attribution is already exact via its
+		// `repeat:<id>:<millis>` jobId (see makeFindPreviousRun), and that join also works retroactively
+		// over the whole retention window, which a new record field cannot.
+		triggerIndex: data.trigger?.matched?.index ?? null,
+		triggerType: data.trigger?.matched?.type ?? null,
 		// Session telemetry (INT-RUN-HISTORY-FILE-CONTRACT): additive, nullable, an explicit literal, no
 		// spread. `{ resumed, reason, bytes }` -- a boolean, a fixed enum and an integer. THE KEY AND THE
 		// BRANCH NAME ARE DELIBERATELY ABSENT: this record's PII-free-by-construction property rests on it

package/src/schedules.mjs

@@ -13,6 +13,7 @@
  */
 
 import { existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import { configError } from "./config.mjs";
 import { parseTriggers } from "./triggers.mjs";
 
@@ -42,6 +43,20 @@ function normalizeCronSchedule({ on, run }, path, existsSync) {
 		throw configError(`cron trigger "${on.id}": run.folder does not exist: ${run.folder} (${path})`);
 	}
 
+	// `run.skillsDir` gets the same treatment, and for the same reason (REQ-PER-TRIGGER-SKILLS): the pure
+	// validator cannot check a host path, because the RECEIVER parses the same file and may run on another
+	// machine entirely. Absoluteness is checked here rather than there for a second reason -- `isAbsolute`
+	// is OS-dependent, so a shared check would let a Windows worker and a Linux receiver disagree about the
+	// same reviewed file. A broken cron trigger refuses the worker's BOOT rather than failing at 03:00.
+	if (run.skillsDir !== undefined) {
+		if (!isAbsolute(run.skillsDir)) {
+			throw configError(`cron trigger "${on.id}": run.skillsDir must be an absolute path: ${run.skillsDir} (${path})`);
+		}
+		if (!existsSync(run.skillsDir)) {
+			throw configError(`cron trigger "${on.id}": run.skillsDir does not exist: ${run.skillsDir} (${path})`);
+		}
+	}
+
 	// Absent provider/model/maxTurns stay absent (undefined) so the value resolves at job start against the
 	// settings overlay/env, not a default frozen here (INT-CONFIG-OVERLAY-CONTRACT). data key order matches
 	// queue.mjs -- the shape the processor's runJob consumes. The three per-trigger fields ride along the same
@@ -53,7 +68,7 @@ function normalizeCronSchedule({ on, run }, path, existsSync) {
 	// cron-only field: it is carried into the local `/job/event.json` (INT-CONTAINER-JOB-INPUTS) so a
 	// scheduled job can name its own trigger; the INT-TRIGGERS-FILE-CONTRACT byte-match acceptance is
 	// amended for exactly this field.
-	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, resume: run.resume, trigger: { id: on.id, pattern: on.pattern } };
+	const data = { kind: "local", folder: run.folder, flow: run.flow, task: run.task, provider: run.provider, model: run.model, maxTurns: run.maxTurns, github: run.github, packages: run.packages, image: run.image, ...(run.skillsDir !== undefined && { skillsDir: run.skillsDir }), resume: run.resume, trigger: { id: on.id, pattern: on.pattern } };
 	// Retention only; the deterministic repeat:<id>:<millis> jobId supplies dedup, so no jobId here, and
 	// scheduler jobs are not retried (DES-CRON-VIA-BULLMQ-SCHEDULER) so no attempts/backoff.
 	const opts = { removeOnComplete: { age: 24 * 3600 }, removeOnFail: { age: 7 * 24 * 3600 } };

package/src/session-store.mjs

@@ -115,6 +115,12 @@ export function makeSessionStore({
 	 * agents' turns into one transcript.
 	 */
 	function promoteSession(session, { piVersion = null } = {}) {
+		// The second DI-seam backstop, and unreachable for the same reason as the `!sessionsDir` return
+		// above: sessionKeyFor is total and binary (null, or 32 hex chars), so resolveSession returns null
+		// rather than a keyless session, and processor.mjs only calls this when prepare handed it one. Kept
+		// because the store and the preparer are separately injected and neither can assume the other. It is
+		// NOT in INT-RUN-HISTORY-FILE-CONTRACT's session.reason enum, deliberately: a token no wired worker
+		// can emit does not belong in the record's vocabulary, and `promote-failed` below does.
 		if (!session?.key) return { promoted: false, reason: "no-key" };
 		try {
 			const staged = join(session.hostDir, SESSION_FILE_NAME);

package/src/start.mjs

@@ -320,14 +320,51 @@ export async function startWorker(
 	// (CONST-RETRY-INFRA-ONLY). The processor calls it as the sole COMPLETED-path chain step.
 	const collectChain = makeCollectChain({ queue: runtimeQueue, config, log });
 
-	// REQ-GLOBAL-PI-OVERLAY staged packages: read the operator's stage manifest ONCE at boot. The staged set
-	// is deploy-time state under the :ro overlay -- identical for every job -- so a per-job re-read would buy
-	// nothing and put a filesystem read on the hot path. A missing or unreadable manifest yields [] plus one
-	// log line and NEVER a boot failure: a deployment that never opted into packages must not be blocked by
-	// it, and `pi-dispatch doctor` is what fails loud on a mismatch between the overlay and the triggers.
-	const stagedPackages = config.globalPiDir ? readStageManifest({ globalPiDir: config.globalPiDir }) : null;
-	const packagePaths = stagedPackages ? containerPackagePaths(stagedPackages) : [];
-	if (config.globalPiDir && !stagedPackages) log("packages_manifest_absent", { overlay: config.globalPiDir });
+	// REQ-GLOBAL-PI-OVERLAY staged packages: read the operator's stage manifest at EACH job start, like
+	// getSettings above and the pause-window ref below.
+	//
+	// This was a boot-time read until issue #102, and the argument for that was sound while it held: the
+	// staged set was deploy-time state under a :ro mount, identical for every job, so a per-job read bought
+	// nothing. What changed is that `import-pi --with-packages` now discovers what the operator installed in
+	// pi, which makes `pi install X` then re-stage a ROUTINE act rather than a rare one. Under the boot read
+	// the jobs after such a re-stage keep the old set until someone restarts the worker, and when the re-stage
+	// DROPS a package the symptom is worse than staleness: the runner refuses a missing staged dir at
+	// container start (exit 2), and budget is reserved before the container, so every job burns a daily-cap
+	// slot until the restart. A free filesystem read that prevents a reserved-and-wasted slot is exactly what
+	// CONST-BUDGET-BEFORE-TOKENS asks for.
+	//
+	// Last-known-good on a failed read, never []: an empty set emits no PI_PACKAGES at all, so the runner's
+	// assertPackagePathsExist has nothing to refuse and the job would run WITHOUT its tools and still exit 0.
+	// That is the silent no-op this project refuses. And never a throw: a transient overlay fault must not
+	// become a queue retry (CONST-RETRY-INFRA-ONLY).
+	let lastGoodPackagePaths = [];
+	let lastPackageKey = null;
+	// Logged once per CHANGE, not once per job: a line every job would drown the log it is meant to serve.
+	// EVERY resolved read records its key, including the empty one, so "nothing staged" becoming "one package
+	// staged" is the change it obviously is rather than a first read that logs nothing.
+	const notePackageKey = (key) => {
+		if (lastPackageKey !== null && key !== lastPackageKey) log("packages_stage_changed", { count: key === "" ? 0 : key.split(":").length });
+		lastPackageKey = key;
+	};
+	const getPackagePaths = () => {
+		if (!config.globalPiDir) return [];
+		const staged = readStageManifest({ globalPiDir: config.globalPiDir });
+		if (!staged) {
+			if (lastGoodPackagePaths.length > 0) {
+				log("packages_manifest_unreadable", { overlay: config.globalPiDir, keeping: lastGoodPackagePaths.length });
+				return lastGoodPackagePaths;
+			}
+			notePackageKey("");
+			return [];
+		}
+		const paths = containerPackagePaths(staged);
+		notePackageKey(paths.join(":"));
+		lastGoodPackagePaths = paths;
+		return paths;
+	};
+	// One read at boot, for the same log line the boot read always emitted, and to seed last-known-good.
+	if (config.globalPiDir && !readStageManifest({ globalPiDir: config.globalPiDir })) log("packages_manifest_absent", { overlay: config.globalPiDir });
+	getPackagePaths();
 
 	const worker = createWorkerFn({
 		connection: parseConnection(config.valkeyUrl),
@@ -363,7 +400,10 @@ export async function startWorker(
 				openJobLog,
 				globalPiDir: config.globalPiDir, // REQ-GLOBAL-PI-OVERLAY: :ro overlay mount when configured
 				allowGlobalExtensions: config.allowGlobalExtensions,
-				packagePaths, // REQ-GLOBAL-PI-OVERLAY: staged package paths; every job receives them unless its trigger set packages:false
+				// REQ-GLOBAL-PI-OVERLAY: staged package paths; every job receives them unless its trigger set
+				// packages:false. A RESOLVER, not the array: the factory is still constructed exactly once, only
+				// the value it reads became a call, so a re-stage takes effect on the next job without a restart.
+				packagePaths: getPackagePaths,
 				forwardEnv: config.forwardEnv,
 				authFromPi: config.authFromPi, // source the provider key from ~/.pi/agent/auth.json when env has none
 				// Self-hosted instance URLs, keyed by forge. A MAP rather than one scalar per forge: the table says