@edgehero/pi-dispatch 0.1.1 → 0.2.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";
@@ -9,18 +10,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 +45,28 @@ 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,
+		// 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
@@ -141,6 +167,58 @@ 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, 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
+		// 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
+		}
+
+		// 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);
 
@@ -167,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/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 } };