@edgehero/pi-dispatch 2.1.0 → 3.0.0

package/src/outbox-plan.mjs

@@ -0,0 +1,218 @@
+import * as nodeFs from "node:fs";
+import { join } from "node:path";
+import { PLAN_MAX_BYTES, parsePlan } from "./priorities.mjs";
+
+/**
+ * The plan collector (issue #505, INT-OUTBOX-CONTRACT's second file, DES-JOB-OUTBOX-CHAINING's second kind): the host-side
+ * reader of a completed portfolio job's `/outbox/priorities.json`, which it hands to `applyPlan` (allocation.mjs) with
+ * the writer `{ kind: "portfolio-job", jobId, triggerId }`.
+ *
+ * A SEPARATE FILE, never a `request-<n>.json` with a `type` key: a plan would then share the chain count cap
+ * (`PI_CHAIN_MAX_PER_JOB`), and a worker too old to know the key would refuse it as `chain-bad-flow-name`, a reason that
+ * says nothing about plans. An older worker never opens a file it does not know.
+ *
+ * NEVER THROWS, the rule `makeCollectChain` keeps and for its reason: this runs after a completed, PAID container, so a
+ * throw would turn that completion into a retry and pay again for one answer (CONST-RETRY-INFRA-ONLY). Every fault is
+ * caught, logged as a fixed token, and recorded as `plan-collect-error`. A refused plan is a recorded outcome of a
+ * completed job, never a failed job.
+ *
+ * The ladder, failing closed at the first miss (each refusal a fixed token, `PLAN_COLLECT_REASONS`):
+ *   1. No `/outbox/priorities.json` (or no outbox: a forge job has none). Only ENOENT and ENOTDIR mean "no file", and
+ *      the answer waits for rung 2's three checks (issue #507). A job all three confirm as a portfolio job is refused as
+ *      `plan-absent`, recorded like every refusal below: the job exists to write a plan, so writing none is the
+ *      trigger's own attempt, and the operator and the next manager run (its `lastAttempt`) must see "wrote nothing"
+ *      rather than last week's answer. Every other job that writes no plan says `plan: null` and writes no row, so an
+ *      unflagged job is byte-identical to before (and a job whose flag went away while it ran is no longer asked for a
+ *      plan). Any other lstat answer (an outbox the job made unreadable) is judged by rung 2 first: a job that was never
+ *      a portfolio job then has no plan (`null`), and a confirmed one meets rung 4, which reads it again.
+ *   2. Portfolio authority, `plan-not-portfolio`: the job was a portfolio job AT PICKUP (the processor's `portfolio`
+ *      decision: the flag on the data, a cron `trigger`, no chain field, and the live file), it still has the flag, a
+ *      trigger and no chain field on its data, prepare AGREED (it wrote the snapshot, `prepared.portfolio`), and the
+ *      LIVE triggers file still flags that same entry NOW. All three, so an operator who removes the flag while the job
+ *      runs is obeyed, a job that ran without the facts writes no plan, and a flag added back mid-run grants nothing to
+ *      a job that started as an ordinary one.
+ *      WHERE it is recorded depends on who was refused. A job that was never a portfolio job at pickup (a manual run, a
+ *      chained child, an unflagged cron job) is refused in its run record and its log line ONLY: no audit row and
+ *      no `alloc:log` row, because `alloc:log` holds 500 rows, is the panel's revert history and the next manager's
+ *      `lastAttempt`, and any local job could otherwise wipe it one row per run. A job the pickup confirmed whose flag
+ *      went away later (at prepare or at collection) is the trigger's own attempt, so it is recorded like every other
+ *      refusal below.
+ *   3. Size, `plan-oversize`: more than 16 KiB (`PLAN_MAX_BYTES`), from `lstat`, before anything is opened.
+ *   4. A regular file, `plan-not-regular-file`: `lstat`, which never follows a link, so a symlink is refused on its own
+ *      inode. Then the file is OPENED with `O_NOFOLLOW` (a link swapped in after the lstat fails with ELOOP) and
+ *      `O_NONBLOCK` (a FIFO swapped in cannot hang the worker on open), and the OPEN descriptor is `fstat`ed: regular and
+ *      within the size again, so what is read is what was judged. At most `PLAN_MAX_BYTES + 1` bytes are read, so a
+ *      file that grows after the fstat is still refused as oversize. Any other fs fault is `plan-unreadable`.
+ *   5. JSON with an object root, `plan-parse-error`.
+ *   6. `applyPlan`, which judges the plan (`plan-invalid` naming one field) and applies the ladder of
+ *      DES-DELEGATED-ALLOCATION-INSIDE-ENVELOPE (`delegation-off` through `plan-busy`).
+ * Rung 1 (`plan-absent`), rung 2 (as above) and rungs 3 to 5 are recorded by `recordRefusal` (a file row and an
+ * `alloc:log` row, the reason and nothing of the body); rung 6 records its own. So no refusal of a portfolio job is
+ * silent, and the next snapshot's `lastAttempt` tells the next manager run. `plan-collect-error` means the outcome is UNKNOWN: a fault after the compare-and-set was
+ * sent (a lost reply) may hide a plan that applied, so the record carries the plan's id when it could be computed, and
+ * `alloc:plan` and the audit file are the truth.
+ *
+ * Returns the record's `plan`: `{ outcome, reason, planId, clamped }` (`outcome` one of `applied`, `duplicate`,
+ * `refused`), or null when there was no file and the job was not a confirmed portfolio job. The worker log line is
+ * `plan_collected { jobId, outcome, reason }`.
+ */
+
+/** The collector's own refusals, in ladder order, and the catch-all for a fault inside it. */
+export const PLAN_ABSENT = "plan-absent";
+export const PLAN_NOT_PORTFOLIO = "plan-not-portfolio";
+export const PLAN_OVERSIZE = "plan-oversize";
+export const PLAN_NOT_REGULAR_FILE = "plan-not-regular-file";
+export const PLAN_UNREADABLE = "plan-unreadable";
+export const PLAN_PARSE_ERROR = "plan-parse-error";
+export const PLAN_COLLECT_ERROR = "plan-collect-error";
+export const PLAN_COLLECT_REASONS = Object.freeze([PLAN_ABSENT, PLAN_NOT_PORTFOLIO, PLAN_OVERSIZE, PLAN_NOT_REGULAR_FILE, PLAN_UNREADABLE, PLAN_PARSE_ERROR, PLAN_COLLECT_ERROR]);
+
+/** The plan file's name in `/outbox`. */
+export const PLAN_FILE = "priorities.json";
+
+const HEX16_RE = /^[0-9a-f]{16}$/;
+const TOKEN_RE = /^[a-z][a-z0-9-]{0,63}$/;
+
+class Refusal extends Error {
+	constructor(reason) {
+		super(reason);
+		this.reason = reason;
+	}
+}
+
+/**
+ * Read the plan file under rungs 3 and 4, or throw a `Refusal`. Returns the text. `fs` needs `lstatSync`, `openSync`,
+ * `fstatSync`, `readSync`, `closeSync` and `constants`.
+ */
+function readPlanFile(fs, path) {
+	const pre = fs.lstatSync(path);
+	if (pre.size > PLAN_MAX_BYTES) throw new Refusal(PLAN_OVERSIZE);
+	if (!pre.isFile()) throw new Refusal(PLAN_NOT_REGULAR_FILE);
+	const { O_RDONLY, O_NOFOLLOW, O_NONBLOCK } = fs.constants ?? nodeFs.constants;
+	let fd;
+	try {
+		fd = fs.openSync(path, O_RDONLY | O_NOFOLLOW | O_NONBLOCK);
+	} catch (error) {
+		// ELOOP: a link was swapped in after the lstat. ENXIO: a socket. Both are files of the wrong kind.
+		if (error?.code === "ELOOP" || error?.code === "ENXIO") throw new Refusal(PLAN_NOT_REGULAR_FILE);
+		throw error;
+	}
+	try {
+		const st = fs.fstatSync(fd);
+		if (!st.isFile()) throw new Refusal(PLAN_NOT_REGULAR_FILE);
+		if (st.size > PLAN_MAX_BYTES) throw new Refusal(PLAN_OVERSIZE);
+		const buf = Buffer.alloc(PLAN_MAX_BYTES + 1);
+		let got = 0;
+		for (;;) {
+			const n = fs.readSync(fd, buf, got, buf.length - got, null);
+			if (n === 0) break;
+			got += n;
+			if (got > PLAN_MAX_BYTES) throw new Refusal(PLAN_OVERSIZE);
+		}
+		return buf.subarray(0, got).toString("utf8");
+	} finally {
+		try {
+			fs.closeSync(fd);
+		} catch {}
+	}
+}
+
+/**
+ * Build the collector. `allocation` is the worker's allocation state (`applyPlan`, `recordRefusal`), `governing()` this
+ * host's `{ envelope, digest }` or null, `projects()` the live parsed projects.json, `checkPortfolioFlag(jobData)` the
+ * live-file check (triggers-file.mjs). `now` is injected.
+ */
+export function makeCollectPlan({ allocation, governing = () => null, projects = () => [], checkPortfolioFlag = async () => false, fs = nodeFs, log = () => {}, now = () => new Date() }) {
+	return async function collectPlan({ job, prepared, portfolio = false }) {
+		const data = job?.data ?? {};
+		const jobId = job?.id ?? null;
+		const result = (outcome, reason, planId = null, clamped = false) => {
+			log("plan_collected", { jobId, outcome, reason });
+			return { outcome, reason, planId: typeof planId === "string" && HEX16_RE.test(planId) ? planId : null, clamped: clamped === true };
+		};
+		const writer = { kind: "portfolio-job", jobId, triggerId: typeof data.trigger?.id === "string" ? data.trigger.id : null };
+		// `audit: false` for a job that was never a portfolio job: the run record and the log line only.
+		const refuse = async (reason, at, { audit = true } = {}) => {
+			if (!audit) return result("refused", reason);
+			try {
+				await allocation.recordRefusal({ writer, reason, digest: governing()?.digest ?? null, now: at });
+			} catch (error) {
+				// The run record still says it; the audit row is what is lost, and the line says so.
+				log("plan_refusal_row_lost", { jobId, reason, code: typeof error?.code === "string" ? error.code : "error" });
+			}
+			return result("refused", reason);
+		};
+		let at;
+		let text = null;
+		try {
+			at = now();
+			if (data.kind !== "local" || typeof prepared?.jobDir !== "string") return null;
+			const path = join(prepared.jobDir, "outbox", PLAN_FILE);
+			// Rung 1: is there a file? lstat, so a dangling link is a file that is there (and refused below), not "none".
+			// Nothing is decided here (issue #507): whether "no file" is `null` or `plan-absent` depends on rung 2, and any
+			// other error is judged by rung 2 first too, then read again by rung 4.
+			let present = true;
+			let absent = false;
+			try {
+				fs.lstatSync(path);
+			} catch (error) {
+				absent = error?.code === "ENOENT" || error?.code === "ENOTDIR";
+				present = false;
+			}
+
+			// Rung 2: the pickup decision, prepare and the live file, all three.
+			const shaped = data.portfolio === true && data.trigger !== undefined && data.parentJobId === undefined && data.chainDepth === undefined;
+			// A job that was never a portfolio job, with no file PROVEN present (none, or an outbox that could not be read),
+			// has no plan: the record stays `plan: null`, so an unflagged job that writes no plan is byte-identical whatever
+			// its outbox.
+			if (portfolio !== true || !shaped) return present ? await refuse(PLAN_NOT_PORTFOLIO, at, { audit: false }) : null;
+			// A confirmed job whose flag went away at prepare or since, with no file: nobody asks it for a plan any more, so
+			// it has none to be refused. With a file, that file is the trigger's attempt, refused and recorded.
+			if (prepared.portfolio !== true) return absent ? null : await refuse(PLAN_NOT_PORTFOLIO, at);
+			const live = await Promise.resolve()
+				.then(() => checkPortfolioFlag(data))
+				.catch(() => false);
+			if (live !== true) return absent ? null : await refuse(PLAN_NOT_PORTFOLIO, at);
+			// All three agree and there is no file: the portfolio job wrote no plan, and it says so (issue #507).
+			if (absent) return await refuse(PLAN_ABSENT, at);
+
+			// Rungs 3 and 4.
+			try {
+				text = readPlanFile(fs, path);
+			} catch (error) {
+				if (error instanceof Refusal) return await refuse(error.reason, at);
+				return await refuse(PLAN_UNREADABLE, at);
+			}
+
+			// Rung 5. Never the parser's message: it quotes the agent's text.
+			let parsed;
+			try {
+				parsed = JSON.parse(text);
+			} catch {
+				return await refuse(PLAN_PARSE_ERROR, at);
+			}
+			if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) return await refuse(PLAN_PARSE_ERROR, at);
+
+			// Rung 6: the plan's own judgement and the apply ladder, recorded by applyPlan itself.
+			const g = governing() ?? null;
+			const applied = await allocation.applyPlan({ envelope: g?.envelope ?? null, digest: g?.digest ?? null, projects: projects(), text, writer, now: at });
+			const reason = typeof applied?.reason === "string" && TOKEN_RE.test(applied.reason) ? applied.reason : null;
+			if (applied?.outcome === "applied") return result("applied", null, applied.planId, applied.clamped);
+			if (applied?.outcome === "duplicate") return result("duplicate", reason, applied.planId);
+			// `apply-failed` (a CAS lost to another writer) is a refusal as `plan-stale`: the plan did not apply.
+			return result("refused", reason ?? PLAN_COLLECT_ERROR, applied?.planId ?? null);
+		} catch (error) {
+			// Infrastructure inside applyPlan (Valkey, the audit file) or a defect here: logged by its code, recorded as a
+			// refusal, and the completed job stays completed.
+			log("plan_collect_failed", { jobId, code: typeof error?.code === "string" ? error.code : "error" });
+			// The plan's id when the text is in hand, so a plan that applied behind a lost reply can still be found. The id
+			// is a property of the text alone (INT-PRIORITIES-PLAN-CONTRACT), so it is computed without the envelope and with
+			// the widest plan life, which only the validity of `validUntil` depends on.
+			let planId = null;
+			try {
+				if (typeof text === "string") planId = parsePlan(text, { now: at, maxPlanDays: 366 }).id ?? null;
+			} catch {}
+			return result("refused", PLAN_COLLECT_ERROR, planId);
+		}
+	};
+}

package/src/outbox.mjs

@@ -158,19 +158,36 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 
 				// 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.
+				// The folder AS THE PARENT NAMED IT (issue #504 part B), never `prepared.workspace`, which is now the folder
+				// resolved at prepare: the named spelling is what matched the parent's scoped-limits row, its project member and
+				// its folder mutex, and the child's own prepare resolves and judges it again.
 				await enqueue(queue, {
-					folder: prepared.workspace,
+					folder: job.data?.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.
+					// The child runs the parent's OWN folder, so it needs the parent's toolchain by definition: 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,
+					// Issue #502: provider, model and the allowed-model list are INHERITED, and they used not to be.
+					// The old reason was "a fallback provider still runs the flow", true while a model was only a
+					// preference. Once a trigger can name the models its jobs may call, a child on the deployment
+					// default is a child outside the parent's policy: a cheap-model triage trigger would chain a
+					// child on the dearest model, and a listed parent would chain an unlisted child. Off `job.data`
+					// (the parent's own trigger fields, before the overlay and env fill), never off `req`, so the
+					// agent can neither pick its child's model nor drop the list by omitting a key. A parent whose
+					// trigger named none chains a child that resolves the default at its own start, as before, and
+					// a parent on the deployment's PI_ALLOWED_MODELS chains a child the same env list governs.
+					provider: job.data?.provider,
+					model: job.data?.model,
+					models: job.data?.models,
+					// Issue #501's per-job dollar cap, by the same narrowing rule: a child that dropped it would run
+					// uncapped. Passed through whenever the parent's data carries it; absent stays absent.
+					maxCostUsd: job.data?.maxCostUsd,
 					// #227, and INHERITED for the reason `image` directly above is: a chained child continues its
 					// parent's work, so it belongs in the venue the parent's trigger chose, not silently back on
 					// the deployment default. Written down rather than left to inference because this file's
@@ -199,6 +216,9 @@ export function makeCollectChain({ queue, enqueue = enqueueLocalJob, readFlowGat
 					// it wrote for itself. The operator's grant was to the trigger they reviewed, not to whatever
 					// that job decides to queue next. A chained child that genuinely needs a secret gets it from a
 					// trigger of its own, which is an operator edit to a reviewed file.
+					// `portfolio` (issue #505) is ABSENT for the same reason, and more plainly: it is budget authority, granted
+					// to one cron trigger the operator reviewed. A child is an agent's request, so inheriting the flag would let
+					// a portfolio job queue a second plan writer of its own choosing.
 					chainDepth: childDepth,
 					parentJobId: job.id,
 					// chainedJobId deliberately does NOT take the image: the child's identity is (parent, flow, task).

package/src/output-cap.mjs

@@ -0,0 +1,157 @@
+/**
+ * Whether the runner's cost guard can bound a model's output (issue #507), asked from the worker side for doctor. The
+ * rule is the runner's (`completionsOwnServer` and `callCostBound`, image/runner/src/usage-meter.mjs): on
+ * openai-completions to a host outside the hosts below, only a cap sent as `max_tokens` bounds the output, so a
+ * priced model whose composed `compat.maxTokensField` is not `"max_tokens"` is refused at its first call under a
+ * dollar cap.
+ *
+ * COPIED, not imported: the job image ships `image/runner` alone and the worker package ships `src` alone, so neither
+ * can import the other (the same reason `FIRST_CALL_OVERHEAD_TOKENS` is a copy in doctor.mjs).
+ * `worker/test/output-cap.test.mjs` holds both lists equal to the runner's and the predicate to the runner's verdict.
+ * Pure, and it never imports pi: the builtin catalog lookups are handed in.
+ */
+
+import { composedCost, endpointsForModel, isZeroCost, modelEntryOf } from "./model-endpoints.mjs";
+
+/** The hosts pi's catalog serves openai-completions on: the runner's `COMPLETIONS_CATALOG_HOSTS`, copied. */
+export const COMPLETIONS_CATALOG_HOSTS = Object.freeze([
+	"api.ant-ling.com",
+	"api.cerebras.ai",
+	"api.cloudflare.com",
+	"api.deepseek.com",
+	"api.fireworks.ai",
+	"api.groq.com",
+	"api.individual.githubcopilot.com",
+	"api.moonshot.ai",
+	"api.moonshot.cn",
+	"api.together.ai",
+	"api.xiaomimimo.com",
+	"api.z.ai",
+	"gateway.ai.cloudflare.com",
+	"inference.baseten.co",
+	"integrate.api.nvidia.com",
+	"open.bigmodel.cn",
+	"opencode.ai",
+	"openrouter.ai",
+	"router.huggingface.co",
+	"token-plan-ams.xiaomimimo.com",
+	"token-plan-cn.xiaomimimo.com",
+	"token-plan-sgp.xiaomimimo.com",
+	"token-plan.ap-southeast-1.maas.aliyuncs.com",
+	"token-plan.cn-beijing.maas.aliyuncs.com",
+]);
+
+/** The runner's `COMPLETIONS_EXTRA_HOSTS`, copied: api.openai.com reads the field pi sends it. */
+export const COMPLETIONS_EXTRA_HOSTS = Object.freeze(["api.openai.com"]);
+
+/** The runner's `completionsOwnServer`, copied: `{ api, baseUrl }` on openai-completions to a host neither list names. */
+export function completionsOwnServer(model) {
+	if (model?.api !== "openai-completions") return false;
+	try {
+		const host = new URL(model.baseUrl).hostname;
+		return !COMPLETIONS_CATALOG_HOSTS.includes(host) && !COMPLETIONS_EXTRA_HOSTS.includes(host);
+	} catch {
+		return true;
+	}
+}
+
+/**
+ * The parts of a model the rule reads, composed as pi 0.99.1's provider-composer.js composes them from the overlay
+ * `models.json` (`models`, parsed, or null) and the builtin catalog (`builtinModel(provider, id)`, injected):
+ *   - a model the overlay DEFINES: its own `api` and `baseUrl`, else its provider's, else those of pi's DEFAULTS
+ *     model (`findModelDefaults`, mirrored in `definedDefaults`); its compat field from its `modelOverrides` entry,
+ *     else its own, else its provider's (a defined model takes no builtin compat);
+ *   - a BUILTIN model: its own `api`; the provider's `baseUrl` over its own; its compat field from the override, else
+ *     the provider's, else the catalog's.
+ * The cost is `composedCost`'s. Null when neither the overlay nor the catalog knows the model. `builtinChatModels`
+ * (the provider's catalog chat models, injected) feeds the defaults.
+ */
+export function outputCapView({ models, provider, modelId, builtinModel = () => null, builtinChatModels = () => [] }) {
+	const { entry, defined, override } = modelEntryOf(models, provider, modelId);
+	const builtin = typeof builtinModel === "function" ? builtinModel(provider, modelId) : null;
+	const field = (compat) => (compat !== null && typeof compat === "object" ? compat.maxTokensField : undefined);
+	const cost = composedCost({ models, provider, modelId, builtinModel });
+	if (defined) {
+		const composed = definedDefaults(entry, modelId, typeof builtinChatModels === "function" ? builtinChatModels(provider) : []);
+		return {
+			api: composed?.api,
+			baseUrl: composed?.baseUrl,
+			maxTokensField: field(override?.compat) ?? field(defined.compat) ?? field(entry?.compat),
+			cost,
+		};
+	}
+	if (builtin && typeof builtin === "object") {
+		return {
+			api: str(builtin.api),
+			baseUrl: str(entry?.baseUrl) ?? str(builtin.baseUrl),
+			maxTokensField: field(override?.compat) ?? field(entry?.compat) ?? field(builtin.compat),
+			cost,
+		};
+	}
+	return null;
+}
+
+const str = (v) => (typeof v === "string" ? v : undefined);
+
+/**
+ * The `{ api, baseUrl }` pi 0.99.1 composes for the overlay-defined model `modelId` (provider-composer.js
+ * `applyModelsJson`): the provider's chat models start as the catalog's (each on the provider's `baseUrl` when it sets
+ * one), and each definition in the file's order is composed and then replaces the model of its id or joins the list.
+ * A definition's `api` is its own, else the provider's, else its DEFAULTS model's, and its `baseUrl` likewise, where the
+ * defaults are `findModelDefaults` over the list so far: the model of the same id, else one of the definition's api,
+ * else the first openai-completions model, else the first. Null when no definition has that id.
+ */
+function definedDefaults(entry, modelId, catalogChat) {
+	const list = (Array.isArray(catalogChat) ? catalogChat : [])
+		.filter((m) => m !== null && typeof m === "object" && typeof m.id === "string" && (m.type ?? "chat") === "chat")
+		.map((m) => ({ id: m.id, api: str(m.api), baseUrl: str(entry?.baseUrl) ?? str(m.baseUrl) }));
+	let found = null;
+	for (const d of Array.isArray(entry?.models) ? entry.models : []) {
+		if (d === null || typeof d !== "object" || typeof d.id !== "string") continue;
+		const wanted = str(d.api) ?? str(entry.api);
+		const defaults = list.find((m) => m.id === d.id) ?? (wanted ? list.find((m) => m.api === wanted) : undefined) ?? list.find((m) => m.api === "openai-completions") ?? list[0];
+		const composed = { id: d.id, api: wanted ?? defaults?.api, baseUrl: str(d.baseUrl) ?? str(entry.baseUrl) ?? defaults?.baseUrl };
+		const at = list.findIndex((m) => m.id === d.id);
+		if (at >= 0) list[at] = composed;
+		else list.push(composed);
+		if (d.id === modelId) found = composed;
+	}
+	return found;
+}
+
+/**
+ * Is every priced call on this model refused under a dollar cap for its output cap? True for a view on
+ * openai-completions to an own server whose field is not `"max_tokens"`, unless its cost is all zeros (the runner
+ * bounds a zero-rated model at 0 before it asks about output). A cost that cannot be told counts as priced.
+ */
+export function outputUnboundable(view) {
+	if (!view || !completionsOwnServer(view)) return false;
+	if (view.maxTokensField === "max_tokens") return false;
+	return !(view.cost !== null && isZeroCost(view.cost));
+}
+
+/**
+ * The priced models a declared endpoint serves whose output the runner cannot bound (`outputUnboundable`), as
+ * `[{ provider, modelId }]` in the overlay's order: each model the overlay defines, then each builtin chat model of a
+ * provider it names (`builtinChatModels`, injected), which takes the provider's `baseUrl`. Only models
+ * `endpointsForModel` puts on a declared endpoint.
+ */
+export function ignoredOutputCapModels({ models, endpoints, builtinModel = () => null, builtinChatModels = () => [] }) {
+	const providers = models?.providers;
+	if (providers === null || typeof providers !== "object" || Array.isArray(providers) || !Array.isArray(endpoints) || endpoints.length === 0) return [];
+	const found = [];
+	for (const provider of Object.keys(providers)) {
+		const { entry } = modelEntryOf(models, provider, "");
+		if (entry === null) continue;
+		const defined = (Array.isArray(entry.models) ? entry.models : []).filter((m) => m !== null && typeof m === "object" && typeof m.id === "string");
+		const listed = typeof builtinChatModels === "function" ? builtinChatModels(provider) : [];
+		const builtins = (Array.isArray(listed) ? listed : []).filter((b) => b !== null && typeof b === "object" && typeof b.id === "string" && !defined.some((m) => m.id === b.id));
+		for (const modelId of [...defined.map((m) => m.id), ...builtins.map((b) => b.id)]) {
+			const lookup = (p, id) => (p === provider ? (builtins.find((b) => b.id === id) ?? (typeof builtinModel === "function" ? builtinModel(p, id) : null)) : null);
+			if (!outputUnboundable(outputCapView({ models, provider, modelId, builtinModel: lookup, builtinChatModels }))) continue;
+			if (endpointsForModel({ models, provider, modelId, endpoints }).length === 0) continue;
+			found.push({ provider, modelId });
+		}
+	}
+	return found;
+}

package/src/pause-windows.mjs

@@ -14,7 +14,9 @@
  */
 
 import { existsSync as fsExistsSync, readFileSync as fsReadFileSync } from "node:fs";
+import { isAbsolute } from "node:path";
 import { configError } from "./config.mjs";
+import { FORGE_KINDS, isForgeKind } from "./forges.mjs";
 
 // Sunday-first to match JS getUTCDay() and the Intl weekday index used in zonedParts().
 const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"];
@@ -77,6 +79,18 @@ function normalizeWindow(w, index, path) {
 	const at = `pause window at index ${index}`;
 	if (w === null || typeof w !== "object") throw configError(`${at}: must be an object: ${path}`);
 	if (!isNonEmptyString(w.scope)) throw configError(`${at}: scope must be a non-empty string: ${path}`);
+	// Issue #498: a qualified scope (`github:acme/web`) pauses one forge's repo, and a near miss (`gitub:acme/web`)
+	// is refused rather than kept as a window that pauses nothing. A bare or folder scope is stored exactly as it was.
+	let scope = w.scope.trim();
+	if (scope !== "*") {
+		let parsed;
+		try {
+			parsed = parseScopeString(scope);
+		} catch (error) {
+			throw configError(`${at}: ${error.message}: ${path}`);
+		}
+		if (parsed.type === "qualified") scope = `${parsed.kind}:${parsed.repo}`;
+	}
 
 	const fromMin = parseHHMM(w.from, "from", at, path);
 	const toMin = parseHHMM(w.to, "to", at, path);
@@ -105,7 +119,7 @@ function normalizeWindow(w, index, path) {
 	if (w.dateTo !== undefined) { assertDate(w.dateTo, "dateTo", at, path); dateTo = String(w.dateTo).trim(); }
 	if (dateFrom && dateTo && dateFrom > dateTo) throw configError(`${at}: dateFrom must be <= dateTo: ${path}`);
 
-	const norm = { scope: w.scope.trim(), from: w.from.trim(), to: w.to.trim(), fromMin, toMin, tz };
+	const norm = { scope, from: w.from.trim(), to: w.to.trim(), fromMin, toMin, tz };
 	if (days) norm.days = days;
 	if (dateFrom) norm.dateFrom = dateFrom;
 	if (dateTo) norm.dateTo = dateTo;
@@ -199,18 +213,83 @@ export function scopeOf(job) {
 	return job?.kind === "local" ? job?.folder : job?.repo;
 }
 
+/**
+ * The forge-qualified scope of a job (issue #498): `<kind>:<repo>` (NFC) for a forge job, such as `github:acme/web` or
+ * `forgejo:acme/web`, the folder unchanged for a local job, and null when a forge job has no `kind` or no `repo`.
+ * `scopeOf` keeps returning the bare repo, because existing pause windows and scoped-limit rows match on it; this is
+ * the second spelling a row may use to name exactly one forge's repo.
+ */
+export function qualifiedScopeOf(job) {
+	if (job?.kind === "local") return job?.folder ?? null;
+	if (!isNonEmptyString(job?.kind) || !isNonEmptyString(job?.repo)) return null;
+	return `${job.kind}:${job.repo}`.normalize("NFC");
+}
+
+/**
+ * One segment of a forge repo path: no `/`, `#`, `:` or control character, and no whitespace at its start or end.
+ * Whitespace INSIDE a segment is allowed for every forge, because Azure DevOps project and repository names may hold
+ * spaces (`Fabrikam Fiber/Web App`) and the receiver copies them verbatim. One rule for every kind is the simpler one;
+ * its cost is that `github:acme web` loads as a cap that guards nothing, as a mistyped bare row always has.
+ */
+const REPO_SEGMENT = "[^/\\s#:\\u0000-\\u001f\\u007f](?:[^/#:\\u0000-\\u001f\\u007f]*[^/\\s#:\\u0000-\\u001f\\u007f])?";
+/** A forge repo path: two or more `REPO_SEGMENT`s joined by single `/`, so none is empty. */
+const QUALIFIED_REPO = new RegExp(`^${REPO_SEGMENT}(?:/${REPO_SEGMENT})+$`, "u");
+
+/**
+ * Classify a scope as written in an operator file (issue #498): `{ type, kind, repo }` where `type` is
+ *   - `local`: an absolute folder path (platform-native `isAbsolute`), or a path with a one-letter drive prefix
+ *     (`C:\srv`), which keeps the handling it always had: verbatim, and inert on a POSIX worker;
+ *   - `qualified`: `<forge kind>:<repo>`, `kind` one of `FORGE_KINDS` and `repo` the NFC rest;
+ *   - `bare`: anything else, such as `owner/name`, which matches that repo on every forge.
+ * A `<word>:` prefix (no `/` before the first `:`) that is not a forge kind THROWS a `configError` naming the known
+ * kinds: `gitub:acme/web` would otherwise be a row that guards nothing while it reads as a cap. For the same reason a
+ * qualified repo must have a forge repo's shape (`QUALIFIED_REPO`): two or more `/`-separated segments, so no leading
+ * or trailing `/` and no `//`, no control character, `#` or `:` in any segment, and no whitespace at a segment's start
+ * or end (inside one it is allowed: Azure DevOps names may hold spaces). That refuses the
+ * likely slips (`github:acme/web/`, a `#12` pasted from a run target, a doubled `github:github:` prefix), each of which
+ * no delivery's repo can ever equal. The split is at the
+ * FIRST `:`, which is safe because no forge allows `:` in a repo or project path: GitHub, GitLab and Forgejo names
+ * are `[A-Za-z0-9._-]` segments, and Azure DevOps refuses `:` in project and repository names. `"*"` is the caller's
+ * business (pause windows accept it, scoped limits refuse it) and is not classified here. The message carries no path:
+ * the caller adds which entry and which file.
+ */
+export function parseScopeString(text) {
+	const scope = String(text).trim().normalize("NFC");
+	if (isAbsolute(scope) || /^[A-Za-z]:/.test(scope)) return { type: "local", kind: null, repo: null };
+	const m = /^([^/\\:]+):(.*)$/s.exec(scope);
+	if (m === null) return { type: "bare", kind: null, repo: null };
+	if (!isForgeKind(m[1])) throw configError(`scope ${JSON.stringify(scope)} starts with an unknown prefix "${m[1]}:" (a forge-qualified scope starts with one of ${FORGE_KINDS.join(", ")}, such as github:owner/name)`);
+	if (m[2].trim() === "") throw configError(`scope ${JSON.stringify(scope)} names a forge and no repo (write ${m[1]}:owner/name)`);
+	const repo = m[2].trim();
+	if (!QUALIFIED_REPO.test(repo)) throw configError(`scope ${JSON.stringify(scope)} is not a forge repo after "${m[1]}:" (write ${m[1]}:owner/name: segments separated by single "/", no "#", ":" or control characters, and no space at the start or end of a segment), so it would guard nothing`);
+	return { type: "qualified", kind: m[1], repo };
+}
+
+/**
+ * A row scope as a forge comment names it (issue #498): the repo without its forge prefix, so a refusal posted on
+ * `acme/web` reads "acme/web" whether the row was written bare or qualified. Any other scope is returned unchanged.
+ */
+export function unqualifiedScope(scope) {
+	if (typeof scope !== "string") return scope;
+	const colon = scope.indexOf(":");
+	return colon > 0 && isForgeKind(scope.slice(0, colon)) ? scope.slice(colon + 1) : scope;
+}
+
 /**
  * When, in epoch ms, the current pause for this job's scope ends — or `null` when the job is not paused. A
  * job is paused if `now` falls inside any scope-matching window (`scope === "*"` matches every scope); the
  * latest end among active windows is returned so a single deferral clears them all (re-checked on wake).
+ * A window matches on the RAW `scopeOf` value (so every existing bare window keeps matching every forge, as before)
+ * or on the job's `qualifiedScopeOf` (issue #498: `github:acme/web` pauses the GitHub job and not the Forgejo one).
  */
 export function pauseUntilMs(windows, job, nowMs) {
 	if (!Array.isArray(windows) || windows.length === 0) return null;
 	const scope = scopeOf(job);
 	if (!isNonEmptyString(scope)) return null;
+	const qualified = qualifiedScopeOf(job);
 	let end = null;
 	for (const w of windows) {
-		if (w.scope !== "*" && w.scope !== scope) continue;
+		if (w.scope !== "*" && w.scope !== scope && w.scope !== qualified) continue;
 		const e = windowEndAt(w, nowMs);
 		if (e !== null && (end === null || e > end)) end = e;
 	}

package/src/pi-model-loader.mjs

@@ -0,0 +1,77 @@
+/**
+ * pi's own model loader, from the pi-coding-agent installed beside the worker, for `doctor` (issue #502's open
+ * question: can the worker's view of the overlay `models.json` disagree with pi's?).
+ *
+ * THE CHOICE, and why. The issue suggests running pi's loader in the job image. Doctor does run that image already,
+ * for the egress canary, but a probe that mounts the operator's overlay into it needs the canary's venue, job-user and
+ * SELinux handling, and every doctor run would pay a container start for it. The worker and the job image are built
+ * from one lockfile, so the pi-coding-agent that a checkout of this repository installs at the workspace root after
+ * `npm ci` is the pi the image carries, and doctor asks that one, in-process. Its version is named on doctor's line.
+ * Where it is not installed (a worker installed on its own: the worker package depends on pi-ai only), doctor says
+ * the comparison was not made rather than guessing. And only the PINNED pi counts (PR #551's review): an `npm i -g`
+ * layout resolves whatever pi-coding-agent sits beside the worker, a global pi CLI of any version, so the loader
+ * reports the worker's pinned pi-ai (its exact dependency; pi-ai and pi-coding-agent are released in lockstep, and a
+ * test holds this pin equal to the runner's pi-coding-agent pin, which is the image's) and doctor compares nothing
+ * when the pi-coding-agent version differs from it.
+ *
+ * Its own module because it is the one place doctor's code must touch `process.env`: pi reads `PI_OFFLINE` from the
+ * process environment, and the runtime is created with it set so asking about models can never reach the network.
+ * It is restored straight after.
+ *
+ * NOTHING ON DISK (PR #551's review, round 2). The runtime is handed an in-memory credential store and an in-memory
+ * models store. With pi's file-backed defaults it wrote an `auth.json` into a temporary directory, and pi's file
+ * backend creates the parent directory before it writes, so a write landing after the cleanup brought the directory
+ * back (17 were found in a TMPDIR); the default models store would also have written `models-store.json` beside the
+ * operator's overlay file. Neither store holds anything the question needs: composition reads the config only.
+ */
+
+import { readFileSync } from "node:fs";
+
+/**
+ * `{ version, pinned, read(path) }`, or null when pi-coding-agent cannot be resolved from here. `version` is the
+ * resolved pi-coding-agent's, `pinned` the worker package's exact `@earendil-works/pi-ai` dependency. `read` answers
+ * `{ loads, has(provider, id) }`: `loads` is `ModelConfig.load(path).getError() === undefined`, and `has` asks a
+ * `ModelRuntime` created over the file (pi's provider composition included) for the model, with in-memory credential
+ * and models stores, so nothing is read from or written to disk beyond the file itself.
+ */
+export async function loadPiModelLoader({ resolveEntry = (name) => import.meta.resolve(name), workerPackage = new URL("../package.json", import.meta.url) } = {}) {
+	let ModelConfig;
+	let ModelRuntime;
+	let AuthStorage;
+	let InMemoryCodingAgentModelsStore;
+	let version;
+	let pinned = null;
+	try {
+		pinned = JSON.parse(readFileSync(workerPackage, "utf8"))?.dependencies?.["@earendil-works/pi-ai"] ?? null;
+	} catch {
+		// No pin to compare against: doctor then says it cannot tell, rather than comparing with any pi.
+	}
+	try {
+		const entry = resolveEntry("@earendil-works/pi-coding-agent");
+		({ ModelConfig } = await import(new URL("core/model-config.js", entry).href));
+		({ ModelRuntime } = await import(new URL("core/model-runtime.js", entry).href));
+		({ AuthStorage } = await import(new URL("core/auth-storage.js", entry).href));
+		({ InMemoryCodingAgentModelsStore } = await import(new URL("core/models-store.js", entry).href));
+		version = JSON.parse(readFileSync(new URL("../package.json", entry), "utf8")).version;
+	} catch {
+		return null;
+	}
+	return {
+		version,
+		pinned,
+		async read(path) {
+			const config = await ModelConfig.load(path);
+			const loads = config.getError() === undefined;
+			// env-internal PI_OFFLINE: pi's own switch, set here so asking pi about models never reaches the network.
+			const offline = process.env.PI_OFFLINE;
+			process.env.PI_OFFLINE = "1";
+			try {
+				const runtime = await ModelRuntime.create({ modelsPath: path, credentials: AuthStorage.inMemory(), modelsStore: new InMemoryCodingAgentModelsStore(), refreshOnCreate: false });
+				return { loads, has: (provider, id) => runtime.getModel(provider, id) !== undefined };
+			} finally {
+				if (offline === undefined) delete process.env.PI_OFFLINE;
+				else process.env.PI_OFFLINE = offline;
+			}
+		},
+	};
+}