@edgehero/pi-dispatch 0.1.0

package/src/init.mjs

@@ -0,0 +1,77 @@
+/**
+ * `pi-dispatch init` — scaffold a deployment's config files in the current folder.
+ *
+ * Idempotent and non-destructive: an existing file is reported and left as-is, so re-running init
+ * never overwrites operator edits. The scaffolds mirror the empty templates the worker validates
+ * against — an empty triggers list disables cron/label/comment/PR, an empty windows list means no
+ * scoped pauses, an empty packages list stages nothing, an empty subscriptions list declares no plan
+ * prices — so a fresh deployment starts inert and is opted into feature by feature.
+ */
+import { existsSync, copyFileSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { join } from "node:path";
+
+const EMPTY_TRIGGERS = `${JSON.stringify({ triggers: [] }, null, 2)}\n`;
+const EMPTY_PAUSE_WINDOWS = `${JSON.stringify({ windows: [] }, null, 2)}\n`;
+// Pinned third-party pi packages staged into the global overlay (issue #58). Empty by default: staging
+// runs third-party code inside jobs, so it is opted into package by package, never scaffolded populated.
+const EMPTY_PACKAGES = `${JSON.stringify({ packages: [] }, null, 2)}\n`;
+// Operator-declared subscription plans (issue #53), read by the admin extension only — never at job
+// time. Versioned because a newer file must fail loud, and that cannot be retrofitted into a v1 reader.
+const EMPTY_SUBSCRIPTIONS = `${JSON.stringify({ version: 1, subscriptions: [] }, null, 2)}\n`;
+
+export function runInit(cwd = process.cwd(), deps = {}) {
+	const { fs = { existsSync, copyFileSync, writeFileSync }, out = (s) => process.stdout.write(s) } = deps;
+	const results = [];
+
+	// .env from the example. Prefer the copy in cwd (the clone's repo root); fall back to the copy
+	// SHIPPED with the worker package (worker/.env.example, kept byte-identical to the root example by
+	// worker/test/publish.test.mjs) so init works both from elsewhere in a checkout and from an npm
+	// install, where the repo root does not exist.
+	const envPath = join(cwd, ".env");
+	if (fs.existsSync(envPath)) {
+		results.push(["kept", ".env", "already exists — left untouched"]);
+	} else {
+		const cwdExample = join(cwd, ".env.example");
+		const source = fs.existsSync(cwdExample)
+			? cwdExample
+			: fileURLToPath(new URL("../.env.example", import.meta.url));
+		fs.copyFileSync(source, envPath);
+		results.push(["created", ".env", "from .env.example — set your provider key next"]);
+	}
+
+	scaffold(fs, results, join(cwd, "triggers.json"), EMPTY_TRIGGERS, "empty triggers list");
+	scaffold(fs, results, join(cwd, "pause-windows.json"), EMPTY_PAUSE_WINDOWS, "empty pause-windows list");
+	scaffold(fs, results, join(cwd, "pi-packages.json"), EMPTY_PACKAGES, "empty pi package list (stage with import-pi --with-packages)");
+	scaffold(fs, results, join(cwd, "subscriptions.json"), EMPTY_SUBSCRIPTIONS, "empty subscription list (declare plan prices for the admin's cost analytics)");
+
+	for (const [verb, name, note] of results) {
+		out(`${verb.padEnd(7)} ${name.padEnd(20)} ${note}\n`);
+	}
+	out(nextSteps());
+	return 0;
+}
+
+function scaffold(fs, results, path, content, note) {
+	const name = path.split(/[\\/]/).pop();
+	if (fs.existsSync(path)) {
+		results.push(["kept", name, "already exists — left untouched"]);
+	} else {
+		fs.writeFileSync(path, content);
+		results.push(["created", name, note]);
+	}
+}
+
+function nextSteps() {
+	return `
+Next:
+  1. docker pull ghcr.io/edgehero/pi-job:latest && docker tag ghcr.io/edgehero/pi-job:latest pi-job:latest
+                                                        # the prebuilt job image (or build image/Dockerfile)
+  2. docker compose -f deploy/docker-compose.yml up -d  # the durable queue (Valkey)
+  3. edit .env                                          # set ANTHROPIC_API_KEY (or your provider's key)
+  4. pi-dispatch doctor                                 # verify Docker, Valkey, image, and key
+  5. pi-dispatch worker                                 # drain the queue
+
+Operator panel (optional): pi install npm:@edgehero/pi-dispatch-admin   then   /dispatch
+`;
+}

package/src/job-id.mjs

@@ -0,0 +1,100 @@
+import { createHash } from "node:crypto";
+import { configError } from "./config.mjs";
+import { forgeSpec } from "./forges.mjs";
+
+/**
+ * A deterministic jobId for a local job. BullMQ's dedup is `EXISTS jobId`, so a double-invoke of
+ * the same task within the same minute produces the same id and the duplicate is ignored -- the
+ * local equivalent of REQ-DEDUP-BY-DELIVERY-GUID, guarding against a hasty second Enter
+ * double-spending, without blocking a deliberate re-run a minute later.
+ *
+ * Kept free of any bullmq import so the dedup logic is testable everywhere, not only where the
+ * queue's dependencies are installed.
+ */
+export function localJobId({ folder, flow, task, minute }) {
+	// NUL-delimited so {folder:'a',task:'bc'} and {folder:'ab',task:'c'} cannot collide.
+	const digest = createHash("sha256").update([folder, flow ?? "", task ?? "", minute].join("\0")).digest("hex");
+	return `local-${digest.slice(0, 16)}`;
+}
+
+/**
+ * The retry-idempotent jobId for a chained (outbox-requested) child job: `parent id + content-hash of
+ * (flow, task)`, with NO time component. BullMQ's dedup is `EXISTS jobId`, so a retried parent
+ * re-collects its outbox and re-enqueues IDENTICAL child ids -- the duplicate follow-up is rejected,
+ * so a retry cannot fan out extra paid jobs (INT-OUTBOX-CONTRACT, DES-JOB-OUTBOX-CHAINING).
+ *
+ * localJobId's minute component is deliberately ABSENT here: a retry crossing a minute boundary would
+ * otherwise mint a fresh id and double-chain. `parentJobId` is folded INTO the hash so two different
+ * parents requesting the same flow+task resolve to distinct ids and cannot collide; the `chain-`
+ * prefix carries no parent info of its own because the hash already binds it.
+ *
+ * Kept free of any bullmq import (mirrors localJobId/deliveryJobId) so the dedup key is derivable
+ * everywhere, not only where the queue's dependencies are installed.
+ */
+export function chainedJobId({ parentJobId, flow, task }) {
+	// NUL-delimited (localJobId's idiom) so distinct field splits cannot collide.
+	const digest = createHash("sha256").update([String(parentJobId), flow ?? "", task ?? ""].join("\0")).digest("hex");
+	return `chain-${digest.slice(0, 16)}`;
+}
+
+/**
+ * The deterministic jobId for a GitHub-triggered job: the `X-GitHub-Delivery` GUID, prefixed.
+ * BullMQ's dedup is `EXISTS jobId`, so a redelivered webhook (GitHub retries on timeout) carries
+ * the same GUID, resolves to the same id, and the duplicate paid run is rejected --
+ * REQ-DEDUP-BY-DELIVERY-GUID.
+ *
+ * Kept free of any bullmq import (mirrors localJobId) so the dedup key is derivable everywhere, not
+ * only where the queue's dependencies are installed. A missing GUID is a caller bug -- the receiver
+ * rejects a missing deliveryId before enqueue (D2) -- so this throws rather than inventing a random
+ * id, which would silently defeat dedup and let a redelivery double-spend.
+ */
+export function deliveryJobId(guid) {
+	return forgeDeliveryJobId("github", guid);
+}
+
+/**
+ * The same thing for a GitLab-triggered job: the `webhook-id` (or its older name `Idempotency-Key`),
+ * prefixed `gl-`. GitLab keeps that value CONSTANT across its own retries, which is the exact property
+ * REQ-DEDUP-BY-DELIVERY-GUID needs, so the guarantee is the same one -- and retention-bounded in the same
+ * way.
+ */
+export function gitlabDeliveryJobId(id) {
+	return forgeDeliveryJobId("gitlab", id);
+}
+
+/**
+ * The general form the two above are now spellings of: a forge kind plus that forge's own per-delivery
+ * id, prefixed from the forge table.
+ *
+ * The prefix is not decoration -- it keeps every forge's id space disjoint, so a delivery id that happened
+ * to collide across two forges could never silently suppress the other's job. One body rather than one per
+ * forge because the *policy* here (a missing id throws rather than inventing a random one, which would
+ * defeat dedup and let a redelivery double-spend) is a property of REQ-DEDUP-BY-DELIVERY-GUID, not of any
+ * one forge, and four copies of a policy is four chances to weaken it in three places.
+ *
+ * An unknown kind throws for a different reason than an empty id, and says so: reaching here with one
+ * means a forge was added to the trigger schema and not to the table.
+ *
+ * `replica` is the ONE seam that lets a single delivery become more than one job (REQ-REPLICA-RUNS). It is
+ * appended, so `gh-<guid>` becomes `gh-<guid>-r2`, and the dedup guarantee above survives intact: a
+ * REDELIVERY of that same GUID still resolves `-r2` for replica 2 and is still rejected, while replica 1
+ * and replica 2 can never suppress each other. Everything the harness keys off the jobId -- the container
+ * name, `PI_JOB_ID`, the `.log` and `.json` sidecars -- becomes replica-distinct for free. `-` is inside
+ * `sanitizeJobId`'s `[A-Za-z0-9._-]` allowlist (run-history.mjs) and inside docker's container-name
+ * grammar, so the longer id needs no new escaping anywhere. Absent leaves the id byte-identical.
+ */
+export function forgeDeliveryJobId(kind, id, replica) {
+	const spec = forgeSpec(kind);
+	if (!spec) {
+		throw configError(`forgeDeliveryJobId: ${JSON.stringify(kind)} is not a known forge -- add it to FORGES in worker/src/forges.mjs`);
+	}
+	if (typeof id !== "string" || id === "") {
+		throw configError(`forgeDeliveryJobId requires a non-empty ${spec.deliveryIdName} for a ${kind} delivery`);
+	}
+	const base = `${spec.jobIdPrefix}${id}`;
+	if (replica === undefined) return base;
+	if (!Number.isInteger(replica) || replica <= 0) {
+		throw configError(`forgeDeliveryJobId: replica must be a positive integer when present (got ${JSON.stringify(replica)})`);
+	}
+	return `${base}-r${replica}`;
+}

package/src/materialize.mjs

@@ -0,0 +1,138 @@
+import { execFile } from "node:child_process";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative } from "node:path";
+import { promisify } from "node:util";
+
+const exec = promisify(execFile);
+
+/**
+ * Materialise a serviced repo's `.pi/` (its persona and skills) from a pinned commit into a
+ * read-only `/job/pi/` directory the container mounts.
+ *
+ * This is security-critical: the content becomes the agent's SYSTEM PROMPT, and the repo is only
+ * trusted at maintainer level. Three properties, each PROVEN with a hostile fixture in the tests:
+ *
+ *   1. NO SYMLINK FOLLOWING. A `.pi/APPEND_SYSTEM.md` symlinked to the worker's `.env` or
+ *      `/etc/passwd` must never pull a host file into the prompt. We enumerate with `git ls-tree`
+ *      and REJECT any entry that is not a regular blob (mode 100644): symlinks are 120000,
+ *      submodules 160000. We never touch the working tree, so there is no link to follow.
+ *   2. NO PATH TRAVERSAL. Every output path is re-derived from the git tree path and asserted to
+ *      stay under the destination root; a crafted entry cannot escape `/job/pi/`.
+ *   3. NO EXECUTION. `git cat-file blob <oid>` dumps raw bytes by object id -- no working-tree
+ *      checkout, no smudge/clean filters, no hooks, no diff drivers. Nothing in the repo runs.
+ *
+ * The SHA is an input, resolved by the caller from a fresh default-branch API call -- NEVER a
+ * webhook field, and NEVER the triggering (possibly fork) branch.
+ */
+
+const PI_DIR = ".pi";
+const APPEND_SYSTEM = `${PI_DIR}/APPEND_SYSTEM.md`;
+// A skill directory name: lowercase kebab/underscore, 1-64 chars, no dots (so no "..") and no
+// slashes. This is what makes a traversal name impossible at the source. Matched against the
+// CAPTURED segment only, never the whole path.
+const SKILL_PATH_RE = /^\.pi\/skills\/([a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?)\/SKILL\.md$/;
+const SKILL_NAME_RE = /^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$/;
+
+/**
+ * Classify a git tree path into the destination we will WRITE, or null to reject.
+ *
+ * Critically, the returned `outRel` is built from a FIXED TEMPLATE using the validated skill name,
+ * never from the raw git path. gitshow-research proved `git ls-tree` can emit path strings
+ * containing literal `../` segments (git does not sanitise tree-entry names), so deriving the
+ * output path from git's string is unsafe even behind a containment check. The name is the only
+ * attacker-influenced input, and it is validated to a charset that cannot express traversal.
+ */
+export function classifyPiPath(path) {
+	if (path === APPEND_SYSTEM) return { outRel: "pi/APPEND_SYSTEM.md" };
+	const m = SKILL_PATH_RE.exec(path);
+	if (!m) return null;
+	const name = m[1];
+	if (!SKILL_NAME_RE.test(name)) return null; // redundant with the capture group; belt and braces
+	return { outRel: `pi/skills/${name}/SKILL.md` };
+}
+
+/** Back-compat predicate used by callers/tests that only care whether a path is accepted. */
+export function isAllowedPiPath(path) {
+	return classifyPiPath(path) !== null;
+}
+
+/**
+ * Parse `git ls-tree -r -z` output into entries, keeping ONLY regular blobs (100644) at allowed
+ * paths, each carrying its template-derived output path. Symlinks (120000), submodules (160000),
+ * executables (100755), and anything outside the allowlist are dropped here -- the single choke
+ * point for the reject-by-mode rule.
+ */
+export function selectEntries(lsTreeZ) {
+	const entries = [];
+	for (const record of lsTreeZ.split("\0")) {
+		if (!record) continue;
+		// "<mode> <type> <oid>\t<path>"
+		const tab = record.indexOf("\t");
+		if (tab === -1) continue;
+		const [mode, type, oid] = record.slice(0, tab).split(/\s+/);
+		const path = record.slice(tab + 1);
+		if (mode !== "100644" || type !== "blob") continue; // rejects symlink/submodule/exec
+		const classified = classifyPiPath(path);
+		if (!classified) continue;
+		entries.push({ oid, path, outRel: classified.outRel });
+	}
+	return entries;
+}
+
+/**
+ * Assert a resolved output path stays under root. Defence in depth behind the path allowlist.
+ * Uses path.relative rather than string-prefix so it is correct on Windows too -- the worker is
+ * cross-platform and destDir may be a Windows path with backslash separators.
+ */
+function safeJoin(root, ...segments) {
+	const resolved = join(root, ...segments);
+	const rel = relative(root, resolved);
+	if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+		throw new Error(`path escapes destination: ${segments.join("/")}`);
+	}
+	return resolved;
+}
+
+/**
+ * Materialise `.pi/` at `sha` from the clone at `gitDir` into `destDir` (which becomes /job/pi).
+ * Returns the list of relative paths written (under `pi/`), for logging.
+ *
+ * `git` is injected for tests; defaults to a thin wrapper over the real binary.
+ */
+export async function materializePiDir({ gitDir, sha, destDir, git = defaultGit }) {
+	const lsTreeZ = await git(gitDir, ["ls-tree", "-r", "-z", sha, `${PI_DIR}/`]);
+	const entries = selectEntries(lsTreeZ);
+
+	const written = [];
+	for (const { oid, outRel } of entries) {
+		const content = await git(gitDir, ["cat-file", "blob", oid], { raw: true });
+		// outRel is TEMPLATE-derived from a validated name, never the raw git path -- so it cannot
+		// contain traversal. safeJoin re-checks containment as defence in depth, and splits the posix
+		// outRel into host path segments so it is correct on Windows too.
+		const out = safeJoin(destDir, ...outRel.split("/"));
+		mkdirSync(dirname(out), { recursive: true });
+		writeFileSync(out, content, { mode: 0o444 });
+		// Report posix-style: this names a CONTAINER path (/job/pi/...), stable across host OSes.
+		written.push(outRel);
+	}
+	return written;
+}
+
+async function defaultGit(gitDir, args, { raw = false } = {}) {
+	// -c protecting against a hostile repo config: no hooks, no external filters, no pager.
+	const hardened = [
+		"-c",
+		"core.hooksPath=/dev/null",
+		"-c",
+		"core.fsmonitor=false",
+		"--no-pager",
+		"-C",
+		gitDir,
+		...args,
+	];
+	const { stdout } = await exec("git", hardened, {
+		encoding: raw ? "buffer" : "utf8",
+		maxBuffer: 16 * 1024 * 1024,
+	});
+	return stdout;
+}

package/src/outbox.mjs

@@ -0,0 +1,179 @@
+import * as nodeFs from "node:fs";
+import { join } from "node:path";
+import { readFlowGate as realReadFlowGate } from "./flow-gate.mjs";
+import { chainedJobId } from "./job-id.mjs";
+import { enqueueLocalJob } from "./queue.mjs";
+
+/**
+ * The outbox chain collector: the host-side reader of a completed LOCAL parent's `/outbox`, the
+ * container's ONLY signal channel back to the worker (INT-OUTBOX-CONTRACT, DES-JOB-OUTBOX-CHAINING).
+ * The worker is the only enqueuer; the container never learns the queue exists. Every field in a
+ * `request-<n>.json` is agent-authored and untrusted, so each is allowlist-validated host-side before
+ * a child is enqueued, the child folder is FORCED to the parent's own folder (the outbox `folder`
+ * field is ignored -- same-folder-only), and depth is HOST-computed, never read from the outbox.
+ *
+ * Fault isolation is the whole contract. The parent has already COMPLETED its own result before this
+ * runs; a throw here would flip a completed parent to failed/retryable and pay TWICE for one answer
+ * (CONST-RETRY-INFRA-ONLY). Therefore the entire body is wrapped in one try/catch and `collectChain`
+ * NEVER throws: any internal error is logged and the running `{ enqueued, refused }` counts are
+ * returned. This is a PRODUCER-only path -- no budget reserve, no container -- and the enqueued
+ * children pass `reserveBudget` consumer-side like any local job (CONST-BUDGET-BEFORE-TOKENS).
+ *
+ * Logs are PII-free by construction: every line carries `{ jobId, reason, index }` only, never the
+ * agent-authored `task`/`flow` content or file bytes (`no-pii-in-logs`). The `task` text is DATA that
+ * reaches the child's prompt.md but never a log line or the run-history record.
+ */
+
+// The skill-name charset: lowercase kebab/underscore, 1-64 chars, no dots (so no "..") and no
+// slashes. Mirrors flow-gate.mjs / materialize.mjs SKILL_NAME_RE -- keep in sync. Rejecting a bad
+// `flow` here, BEFORE the gate, is the traversal choke point: an untrusted name never reaches git.
+const SKILL_NAME_RE = /^[a-z0-9](?:[a-z0-9_-]{0,62}[a-z0-9])?$/;
+
+// One request file: `request-<n>.json`. The captured `<n>` orders the files numerically so the count
+// cap deterministically keeps the lowest-numbered requests.
+const REQUEST_RE = /^request-(\d+)\.json$/;
+
+// Per-file size cap (4 KiB), enforced BEFORE any read so a hostile file cannot inflate parse cost.
+const MAX_REQUEST_BYTES = 4096;
+
+export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGate = realReadFlowGate, config, fs = nodeFs, log = () => {} }) {
+	return async function collectChain({ job, prepared }) {
+		let enqueued = 0;
+		let refused = 0;
+		const refuse = (reason, index) => {
+			refused++;
+			log(reason, { jobId: job?.id, reason, index });
+		};
+
+		try {
+			// Belt-and-suspenders: a github parent has no /outbox mount at all (the request channel does not
+			// exist for it), but guard here too so a stray dir cannot chain off an untrusted issue author.
+			if (job?.data?.kind !== "local") return { enqueued: 0, refused: 0 };
+
+			const outboxDir = join(prepared.jobDir, "outbox");
+			let names;
+			try {
+				names = fs.readdirSync(outboxDir);
+			} catch {
+				return { enqueued: 0, refused: 0 }; // no outbox dir is the normal no-request case
+			}
+
+			const requests = names
+				.map((name) => {
+					const m = REQUEST_RE.exec(name);
+					return m ? { name, n: Number(m[1]) } : null;
+				})
+				.filter((r) => r !== null)
+				.sort((a, b) => a.n - b.n);
+
+			// Depth is host-computed from the parent's own chainDepth, NEVER read from the outbox. A
+			// chainDepthMax of 0 is the kill-switch: childDepth is always >= 1, so every request refuses.
+			const childDepth = (job.data.chainDepth ?? 0) + 1;
+
+			for (let i = 0; i < requests.length; i++) {
+				// Count cap first: only the lowest-numbered `chainMaxPerJob` files are ever read, so parse
+				// cost is bounded before any file is opened.
+				if (i >= config.chainMaxPerJob) {
+					refuse("chain-count-cap", i);
+					continue;
+				}
+
+				const filePath = join(outboxDir, requests[i].name);
+
+				// Size cap before reading/parsing.
+				let size;
+				try {
+					size = fs.statSync(filePath).size;
+				} catch {
+					refuse("chain-not-regular-file", i);
+					continue;
+				}
+				if (size > MAX_REQUEST_BYTES) {
+					refuse("chain-oversize", i);
+					continue;
+				}
+
+				// Regular-file-only: lstat (NOT stat) so a symlink is rejected on its own inode, not followed.
+				let isFile;
+				try {
+					isFile = fs.lstatSync(filePath).isFile();
+				} catch {
+					refuse("chain-not-regular-file", i);
+					continue;
+				}
+				if (!isFile) {
+					refuse("chain-not-regular-file", i);
+					continue;
+				}
+
+				// Read + JSON parse + object-root check.
+				let req;
+				try {
+					req = JSON.parse(fs.readFileSync(filePath, "utf8"));
+				} catch {
+					refuse("chain-parse-error", i);
+					continue;
+				}
+				if (typeof req !== "object" || req === null || Array.isArray(req)) {
+					refuse("chain-parse-error", i);
+					continue;
+				}
+
+				// Explicit property reads ONLY -- `req` is never spread into job data.
+				const flow = req.flow;
+				const task = req.task;
+
+				// Flow-name charset, BEFORE the gate: a bad name never reaches git.
+				if (typeof flow !== "string" || !SKILL_NAME_RE.test(flow)) {
+					refuse("chain-bad-flow-name", i);
+					continue;
+				}
+
+				// Host-computed depth cap.
+				if (childDepth > config.chainDepthMax) {
+					refuse("chain-depth-cap", i);
+					continue;
+				}
+
+				// ai-trigger gate at the parent's pre-agent SHA: only an exact `allow` passes.
+				const { gate } = await readFlowGate({ folder: prepared.workspace, flow, sha: prepared.sha });
+				if (gate !== "allow") {
+					refuse("chain-gate-deny", i);
+					continue;
+				}
+
+				// Enqueue an ordinary local job on the parent's OWN folder (folder is forced, not read from
+				// the outbox). The child id is retry-idempotent so a retried parent dedups instead of fanning out.
+				await enqueue(queue, {
+					folder: prepared.workspace,
+					flow,
+					task,
+					// The child runs the parent's OWN folder, so it needs the parent's toolchain by definition -- and
+					// this is where `image` differs from provider/model, which are deliberately NOT inherited. A
+					// fallback provider still runs the flow; a fallback IMAGE gives a child that cannot find its tools,
+					// writes a plausible report and exits 0, which is the queue-reports-success failure class arriving
+					// by the back door. Read off `job.data` -- the parent's own validated job data -- and NEVER off
+					// `req`: the agent cannot choose its child's image any more than it can choose its folder or depth
+					// (INT-OUTBOX-CONTRACT's explicit-property-reads rule). Undefined stays undefined, so a parent with
+					// no image chains a child whose data is byte-identical to today's.
+					image: job.data?.image,
+					chainDepth: childDepth,
+					parentJobId: job.id,
+					// chainedJobId deliberately does NOT take the image: the child's identity is (parent, flow, task).
+					// Folding the image in would let an operator's triggers.json edit fan out a duplicate paid child
+					// from a retried parent. The image is derived from the parent's own data, so it is already stable
+					// across that parent's retries.
+					jobId: chainedJobId({ parentJobId: job.id, flow, task }),
+				});
+				enqueued++;
+				log("chain-enqueued", { jobId: job.id, reason: "chain-enqueued", index: i });
+			}
+		} catch {
+			// Never propagate: a throw would flip a completed parent to retryable and double-spend. The
+			// reason is a fixed enum, never the raw error message, so no host path can leak into a log line.
+			log("chain-collect-error", { jobId: job?.id, reason: "chain-collect-error" });
+		}
+
+		return { enqueued, refused };
+	};
+}