@edgehero/pi-dispatch 5.2.0 → 5.2.1

package/src/connection.mjs

@@ -2,8 +2,8 @@ import { AbstractConnector, Command, Redis } from "ioredis";
 import { Socket, connect as netConnect } from "node:net";
 import { connect as tlsConnect } from "node:tls";
 import { valkeyAuthRefusal } from "./valkey-auth.mjs";
-import { valkeySchemeOf } from "./podman-stack.mjs";
-import { decodedUserinfo, judgeValkeyAtStart as judgeEndpointAtStart, judgedEndpoint, killSwitchValkeyUrls, defaultValkeyContext, urlShown, useValkeyContext, valkeyClientContext, valkeyContextFromKeys, VALKEY_CONTEXT_KEYS, valkeyPasswordFor, valkeyDbRangeSentence, valkeyRefusal, valkeyUrlFor, valkeyUrlProblem } from "./valkey-endpoint.mjs";
+import { valkeySchemeOf, valkeyTarget } from "./podman-stack.mjs";
+import { DEFAULT_VALKEY_URL, decodedUserinfo, judgeValkeyAtStart as judgeEndpointAtStart, judgedEndpoint, killSwitchValkeyUrls, defaultValkeyContext, urlShown, useValkeyContext, valkeyClientContext, valkeyContextFromKeys, VALKEY_CONTEXT_KEYS, valkeyPasswordFor, valkeyDbRangeSentence, valkeyRefusal, valkeyUrlFor, valkeyUrlProblem } from "./valkey-endpoint.mjs";
 
 // Re-exported for the receiver and the admin, which import this module from the package (issues #464 and #468).
 export { killSwitchValkeyUrls, defaultValkeyContext, urlShown, useValkeyContext, valkeyClientContext, valkeyContextFromKeys, VALKEY_CONTEXT_KEYS, valkeyPasswordFor, valkeyUrlFor, valkeyUrlProblem };
@@ -89,6 +89,18 @@ if (!Redis.prototype[SCRUBS]) {
  */
 export const DB_REFUSED = Symbol.for("pi-dispatch.valkey-db-refused");
 const SELECT_HOOK = Symbol.for("pi-dispatch.valkey-select-refusal");
+
+/**
+ * The database a client holds a refusal of (`DB_REFUSED`), as `{ db }` (null where the client no longer says which), or
+ * null when it holds none. Issue #845: the refusal is held for the client's life, so only a restart of a long-lived
+ * process tries the database again, and the console says so on every page from this.
+ */
+export function refusedDatabaseOf(client) {
+	if (!client?.[DB_REFUSED]) return null;
+	const db = client.condition?.select ?? client.options?.db;
+	return { db: Number.isSafeInteger(db) ? db : null };
+}
+
 /** Whether `err` is a server's refusal of a SELECT for a database it does not have. */
 function isSelectRangeError(err) {
 	return Boolean(err) && typeof err === "object" && String(err.command?.name ?? "").toLowerCase() === "select" && /DB index is out of range|invalid DB index/i.test(String(err.message ?? ""));
@@ -172,16 +184,30 @@ export function givesUp(connection) {
  *
  * `freshContext` is for a persistent client of a long-running surface that names no context: each connect judges by the
  * context as it is then, not as it was at construction, so an operator's fix of the deployment's `.env` reaches a client
- * that has been refused since it started. Off by default, so a worker's judgement stays the one it booted on. The password
- * is still the one read at construction, since ioredis has settled it before the connector runs.
+ * that has been refused since it started. Off by default, so a worker's judgement stays the one it booted on. Its password
+ * is read again before each connect too (issue #845, `freshPassword` below), so a password rotated in that `.env`, or one
+ * a bad line kept from being read at start, is what the next connect sends. Not its URL: a changed `VALKEY_URL` is
+ * another Valkey, which a running client is never moved to (the console says it needs a restart for that instead).
+ *
+ * `commandTimeoutMs` (issue #867) is a bound on each command of a `failFast` client, for a one-shot BullMQ queue that
+ * must not wait for as long as a Valkey that is connected and stopped answering (`kill -STOP`, a partition) stays so:
+ * `failFast` refuses while nothing is connected, and a command already sent had no bound. A command past it rejects with
+ * ioredis' "Command timed out"; one that was sent may still run when Valkey wakes, so its error says so
+ * (`valkeyMayStillRun`, the hook below), and it is never sent again on a later connection. It needs `failFast`: that
+ * client has no offline queue, and on one that has, ioredis sends a command that timed out there once Valkey returns.
+ * `makeRedisClient` takes such a command out of its own queue (`BoundedRedis`), but BullMQ builds this client itself, so
+ * nothing could. Never for a Worker: its blocking reads wait longer than any bound by design, and its connection is a
+ * persistent one, which this refuses.
  */
-export function parseConnection(url, { failFast = false, servername = null, context = null, judge = null, withoutPassword = false, freshContext = false } = {}) {
+export function parseConnection(url, { failFast = false, servername = null, context = null, judge = null, withoutPassword = false, freshContext = false, commandTimeoutMs = null } = {}) {
 	const u = new URL(url);
 	// PR #478's gate: a path that is not a database number was `db: NaN`, and the SELECT ioredis then sent failed outside
 	// every caller's await (an unhandled rejection). Refused here, where every client of the project is made, as the
 	// configuration refusal it is; `judgeValkeyAtStart` says it first at each start.
 	const dbProblem = valkeyUrlProblem(url);
 	if (dbProblem) throw valkeyRefusal(dbProblem);
+	const bounded = Number.isSafeInteger(commandTimeoutMs) && commandTimeoutMs > 0;
+	if (bounded && !failFast) throw new TypeError("parseConnection: a command bound (commandTimeoutMs) is for a failFast client only, which has no offline queue to send a command that timed out from later");
 	const where = context ?? defaultValkeyContext();
 	// Issue #468: the password this client sends, by `valkeyPasswordFor`'s rule (the URL's own, else VALKEY_PASSWORD from
 	// the environment, else from the deployment `.env` for a loopback host). Here and nowhere else, so every client of the
@@ -194,7 +220,9 @@ export function parseConnection(url, { failFast = false, servername = null, cont
 		// reports. `context` is where the client stands (`valkeyClientContext`), the process's own when not given.
 		Connector: JudgedConnector,
 		// `judge` is a test seam only: the function asked for the address (judgedEndpoint when not given).
-		[JUDGE]: { url, context: where, ...(judge ? { judge } : {}), ...(freshContext && !context ? { freshContext: true } : {}), ...(failFast ? { failFast: true } : {}) },
+		// `freshPassword` (issue #845): a client that judges by the context as it is at each connect sends the password that
+		// context gives then, unless it was built to send none (`withoutPassword`, a probe of what another account sees).
+		[JUDGE]: { url, context: where, ...(judge ? { judge } : {}), ...(freshContext && !context ? { freshContext: true, ...(withoutPassword ? {} : { freshPassword: true }) } : {}), ...(failFast ? { failFast: true } : {}), ...(bounded ? { commandBound: true } : {}) },
 		// WHATWG URL keeps an IPv6 literal's brackets in `hostname` (`[::1]`), and net.connect then looks up the name
 		// "[::1]", which never resolves, so a `redis://[::1]:6379` VALKEY_URL never connected (issue #464, measured on
 		// Fedora 44: ETIMEDOUT). The address is the part inside them.
@@ -216,7 +244,42 @@ export function parseConnection(url, { failFast = false, servername = null, cont
 					retryStrategy: (attempts) => (attempts > 2 ? null : 200), // give up after ~2 tries
 				}
 			: {}),
+		// ioredis' resend of what was on a connection that died is off with the bound: the caller was told such a command
+		// failed, and a resend on the next connection would make it run after that.
+		...(bounded ? { commandTimeout: commandTimeoutMs, autoResendUnfulfilledCommands: false } : {}),
+	};
+}
+
+/**
+ * What `BoundedRedis` does for its own clients, done for a client `parseConnection` built with a command bound (issue
+ * #867), which BullMQ constructs itself as a plain ioredis client, so it cannot be a subclass. On the prototype, like the
+ * scrub above, and inert for every client without the bound (a worker's, a receiver's, every `makeRedisClient` client).
+ *
+ * Two things. The command's timer is unref'd, since ioredis' is ref'd and a one-shot that has said its last line must not
+ * wait out a bound on a command nobody awaits. And a command that was WRITTEN (it is the newest entry of the client's
+ * command queue right after the send; without an offline queue, one that was not is refused at once and never sent) and
+ * then rejected with anything but Valkey's own reply carries `valkeyMayStillRun`: it reached a socket, so Valkey may run
+ * it when it wakes, or ran it before its answer was lost. Measured against the pinned ioredis: a SET past the bound on a
+ * `kill -STOP`ed Valkey rejects with "Command timed out" and is applied once the process is continued. Besides the
+ * timeout that is "Connection is closed.", for a command on a connection whose retries ran out. A refusal this project
+ * raised itself (`valkeyRefused`, a database the server does not have) is no lost answer.
+ */
+const COMMAND_BOUND_HOOK = Symbol.for("pi-dispatch.valkey-command-bound");
+if (!Redis.prototype[COMMAND_BOUND_HOOK]) {
+	const sendCommand = Redis.prototype.sendCommand;
+	Redis.prototype.sendCommand = function sendCommandWithBound(command, stream) {
+		const answer = sendCommand.call(this, command, stream);
+		if (this.options?.[JUDGE]?.commandBound !== true) return answer;
+		command._commandTimeoutTimer?.unref?.();
+		if (this.commandQueue?.peekBack?.()?.command !== command) return answer;
+		answer?.catch?.((err) => {
+			if (!err || typeof err !== "object" || err.name === "ReplyError" || err.valkeyRefused) return;
+			if (err.message === "Command timed out") err.code ??= "ETIMEDOUT";
+			err.valkeyMayStillRun = true;
+		});
+		return answer;
 	};
+	Redis.prototype[COMMAND_BOUND_HOOK] = true;
 }
 
 /**
@@ -382,6 +445,60 @@ export function authRefusalFor(state, url, context) {
  */
 const JUDGE = "piDispatchValkeyJudge";
 
+/** The connector's method that reads a `freshPassword` client's password again (`JudgedConnector`, the hook below it). */
+const FRESH_PASSWORD = Symbol.for("pi-dispatch.valkey-fresh-password");
+
+/** Set on a connector whose last refresh declined a `.env` password other than the one its client holds (see there). */
+const PASSWORD_DECLINED = Symbol.for("pi-dispatch.valkey-password-declined");
+
+/**
+ * Whether two Valkey URLs name one Valkey server, by `valkeyTarget`'s host and port (the scheme alias, a database path
+ * and a trailing `/` aside): a password belongs to the server. False for one that does not parse. `localhost` and
+ * `127.0.0.1` are two names here, as for `valkeyEndpointTag`: which address a name reaches is the judge's to say.
+ */
+function sameValkeyServer(a, b) {
+	const x = valkeyTarget(a);
+	const y = valkeyTarget(b);
+	return !x.error && !y.error && x.host === y.host && x.port === y.port;
+}
+
+/**
+ * What a `freshPassword` client's refresh does with `context` as it is now (`JudgedConnector`'s method below has the
+ * rules): `{ take: true, password }` to send `password` (null: none) from the next connect on; `{ take: false, declined }`
+ * to keep the one it holds (`held`), where `declined` is true when the `.env` gives another password than `held` for a
+ * Valkey the client does not dial as it dials it, false when nothing is being held back, and null when the context
+ * cannot tell (it could not be read, finds no file, or is another deployment's). Pure: one rule for the refresh before
+ * each connect and for `passwordDeclinedOf`, so the two never disagree about what is held back.
+ */
+function freshPasswordVerdict(judge, context, held) {
+	if (!context || context.error || context.absent === true) return { take: false, declined: null };
+	if ((context.envPath ?? null) !== (judge?.context?.envPath ?? null)) return { take: false, declined: null };
+	const { password, from } = valkeyPasswordFor(judge.url, context);
+	const fromFile = from !== "VALKEY_URL" && from !== "the environment";
+	if (fromFile && !sameValkeyServer(context.url?.file ?? DEFAULT_VALKEY_URL, judge.url)) return { take: false, declined: (password ?? null) !== (held ?? null) };
+	return { take: true, password: password ?? null };
+}
+
+/**
+ * Issue #845, review of PR #878: whether a `freshPassword` client holds back a password the deployment's `.env` gives,
+ * other than the one it holds, because the file does not name the Valkey the client dials as it dials it. True only
+ * while a reconnect has declined one (recorded by the refresh, which runs on connect alone) AND the `.env` as it is now
+ * still gives such a password (`freshPasswordVerdict` over the context read now): a file put back to the held password,
+ * or changed to name the client's Valkey, clears it at once, with no reconnect, and so does a file that cannot be read
+ * now (the console says that instead). Reads the client's context once; touches no Valkey.
+ */
+export function passwordDeclinedOf(client) {
+	const connector = client?.connector;
+	if (connector?.[PASSWORD_DECLINED] !== true) return false;
+	const judge = connector.options?.[JUDGE];
+	if (judge?.freshPassword !== true) return false;
+	try {
+		return freshPasswordVerdict(judge, defaultValkeyContext(), connector.options.password).declined === true;
+	} catch {
+		return false;
+	}
+}
+
 /**
  * ioredis' connector for every client of this project (issue #464, gate round 2 follow-up): on each connect it asks
  * `judgedEndpoint` for the address, then dials that literal (with a `rediss:` URL's name kept as the TLS servername),
@@ -408,6 +525,57 @@ export class JudgedConnector extends AbstractConnector {
 		return !this[DB_REFUSED];
 	}
 
+	/**
+	 * Issue #845: a `freshPassword` client's password, as `valkeyPasswordFor` reads it from the context as it is now, put
+	 * where ioredis reads it for the connect about to start (the hook below). Here and not in `connect()`: by the time
+	 * ioredis asks the connector for a stream it has already built that connect's AUTH from `options.password`. The options
+	 * are the client's own object (ioredis hands its `options` to the Connector it constructs), so this is what the client
+	 * sends. A password from VALKEY_URL's userinfo comes back as it is, so it stays fixed. The last password is kept by a
+	 * context that:
+	 *   - throws, or names an `error` (a `.env` that cannot be read, or a line in it the service's loader reads
+	 *     differently): it cannot say which password the file holds, and dropping the one that worked would refuse a client
+	 *     that is fine;
+	 *   - finds no file (`absent`): a `.env` gone, for good or for the moment an editor replaces it, is not a file that
+	 *     sets no password, so it does not drop one either (the console says to put the file back before a restart);
+	 *   - would answer from the `.env` while that file does not name the Valkey this client dials: a password the file
+	 *     gives (or the lack of one) belongs to the Valkey the file's VALKEY_URL names, the default one when it names
+	 *     none, and a held client never moves to another Valkey. Review of PR #878, measured with two Valkeys: one
+	 *     deployment moving to another Valkey changes both lines together, a symlinked deployment folder repointed reads
+	 *     another deployment's file through the same path, and a shell that exports VALKEY_URL keeps the client on its URL
+	 *     whatever the file says; in each the new Valkey's password went to the old one, which refused it, and the pages
+	 *     lost the old Valkey too. The check is against the URL the client dials, not the context's own choice of URL
+	 *     (`valkeyUrlFor`, which prefers this shell's and so never moved), and by the server each names (`sameValkeyServer`:
+	 *     `valkeyTarget`'s host and port, so a scheme alias, a database path or a trailing `/` is the same Valkey, while
+	 *     `localhost` and `127.0.0.1` stay two names, as `valkeyEndpointTag` keeps them). A rotation keeps the file's URL,
+	 *     so it is taken, and so is a password a bad line hid at start once the line is fixed, when the file names the
+	 *     client's Valkey. A password declined here that is not the one the client holds is recorded (`PASSWORD_DECLINED`,
+	 *     `passwordDeclinedOf`), so the console names VALKEY_PASSWORD as needing a restart rather than going on refused in
+	 *     silence (a shell that exports `redis://localhost:6440` over a file's `redis://127.0.0.1:6440`, say);
+	 *   - is read from another `.env` path than the one the client was built with: the pi extension's context follows the
+	 *     deployment pointer, and that alone says the file is another deployment's.
+	 * A password from this process's environment, or from VALKEY_URL's own userinfo, is not the file's, and is taken as it
+	 * comes. A context that passes all of these and gives no password drops it, as a restart would.
+	 */
+	[FRESH_PASSWORD]() {
+		const judge = this.options?.[JUDGE];
+		if (judge?.freshPassword !== true) return;
+		let context;
+		try {
+			context = defaultValkeyContext();
+		} catch {
+			return;
+		}
+		const verdict = freshPasswordVerdict(judge, context, this.options.password);
+		if (!verdict.take) {
+			// Recorded only where the context could tell; `passwordDeclinedOf` reads it against the file as it is then.
+			if (verdict.declined !== null) this[PASSWORD_DECLINED] = verdict.declined;
+			return;
+		}
+		this[PASSWORD_DECLINED] = false;
+		if (verdict.password) this.options.password = verdict.password;
+		else delete this.options.password;
+	}
+
 	connect() {
 		const { options } = this;
 		// A database the server refused stays refused: no reconnect goes ready on another one.
@@ -445,6 +613,39 @@ export class JudgedConnector extends AbstractConnector {
 /** How `JudgedConnector` dials, net and tls: a seam, so a test sees the options a pinned connect is made with. */
 JudgedConnector.dial = { net: netConnect, tls: tlsConnect };
 
+/**
+ * Where a `freshPassword` client's password is read again (issue #845): before EVERY connect, its first and each
+ * reconnect, on the prototype like the hooks above, so a client ioredis or BullMQ duplicates keeps it too. Measured
+ * against the pinned ioredis 5.11.1 (`worker/test/valkey-clients.test.mjs` holds each line): `connect()` runs
+ * `_connect()`, which builds the connect's AUTH (`this.condition.auth`) from `this.options.password` before it asks the
+ * connector for a stream; a refused AUTH (WRONGPASS) and a refused ready check (NOAUTH) go to `recoverFromFatalError`,
+ * which disconnects to reconnect, and the reconnect timer calls `self.connect()`. So a rotated password reaches a client
+ * that has been refused since the rotation at its next try, by its own retry strategy, with no rebuild.
+ *
+ * Delegated to the client's connector, so the context read is the one of the copy of this module that built the client
+ * (a bundle carries its own copy beside the shared ioredis, and the first copy loaded installs this hook). Inert for every
+ * other client. A throw here would escape ioredis' reconnect timer, which does not catch one, so it is caught: the last
+ * password is kept.
+ *
+ * REJECTED: rebuilding the client when its password changes, which every holder of one (the console's audit copy, the
+ * fleet reader, a page's reads) would have to learn to swap; wrapping `connect` on each client `makeRedisClient` makes,
+ * which misses a duplicate and a client BullMQ builds from `parseConnection`'s options; and reading the password in
+ * `JudgedConnector.connect`, which is too late for that connect's AUTH (above).
+ */
+const FRESH_PASSWORD_HOOK = Symbol.for("pi-dispatch.valkey-fresh-password-hook");
+if (!Redis.prototype[FRESH_PASSWORD_HOOK]) {
+	const connect = Redis.prototype.connect;
+	Redis.prototype.connect = function connectWithFreshPassword(...args) {
+		try {
+			this.connector?.[FRESH_PASSWORD]?.();
+		} catch {
+			// The last password stays.
+		}
+		return connect.apply(this, args);
+	};
+	Redis.prototype[FRESH_PASSWORD_HOOK] = true;
+}
+
 /**
  * Whether `connection` (options for BullMQ, or an ioredis client) connects through `JudgedConnector`. `makeQueue` and the
  * worker refuse any other, so no Queue or Worker of this project can be built on an unjudged connection.

package/src/doctor.mjs

@@ -143,7 +143,7 @@ import { assignCheckIds, buildDoctorRecord, doctorIntervalHours, publishRedactor
 import { olderStateFindings as olderStateFindingsReal, VALKEY_CONTAINER } from "./older-state.mjs";
 import { DOCTOR_PUBLISH_SKIPPED_PREFIX } from "./doctor-spawner.mjs";
 import { extensionsNotHere } from "./loaded-record.mjs";
-import { buildHostLoads, flowProbes, flowTierOf, mcpRowsOf, pathIsThere, readOverlayExtensionRows, readOverlaySkillNames } from "./host-loads.mjs";
+import { buildHostLoads, FLOW_INPUT_FIELDS, flowBasisOf, flowInputOf, flowProbes, flowTierOf, mcpRowsOf, pathIsThere, readOverlayExtensionRows, readOverlaySkillNames } from "./host-loads.mjs";
 
 const NODE_FLOOR = [22, 19]; // pi's engine floor (22.19.0)
 
@@ -2191,7 +2191,8 @@ export async function collectChecks(shellVars, seams) {
 		const staged = readStagedSkills({ globalPiDir: env.PI_GLOBAL_PI_DIR, readFile: stagedProbes.readFile, fileExists: stagedProbes.fileExists, readDir: stagedProbes.readDir });
 		const groups = new Map();
 		for (const f of flows) {
-			const key = JSON.stringify([f.flow, f.folder, f.skillsDir, f.packages, f.excludeExtensions]);
+			// Keyed by every field `flowTierOf` reads, so a group shares one answer and one basis.
+			const key = JSON.stringify(FLOW_INPUT_FIELDS.map((field) => f[field]));
 			if (!groups.has(key)) groups.set(key, { ...f, labels: [], triggers: [] });
 			groups.get(key).labels.push(f.label);
 			groups.get(key).triggers.push(f.index);
@@ -2209,7 +2210,7 @@ export async function collectChecks(shellVars, seams) {
 					fix: "a flow name must match the skill charset (lowercase alphanumerics, - and _, 64 max), or no tier can ever hold it -- fix run.flow",
 				});
 				// No tier can hold it, and a name that fails the charset is not published.
-				for (const trigger of g.triggers) seams.flowRows.push({ trigger, flow: null, tier: "none", package: null, repo: "unknown" });
+				for (const trigger of g.triggers) seams.flowRows.push({ trigger, flow: null, tier: "none", package: null, repo: "unknown", basis: g.basis });
 				continue;
 			}
 			const probes = flowProbes({ fileExists, fs: flowFs });
@@ -2219,7 +2220,7 @@ export async function collectChecks(shellVars, seams) {
 			// trigger that withholds the packages did not, and another trigger's unreadable folder says nothing of this one's.
 			const blind = probes.blind() || (g.packages !== false && stagedProbes.blind());
 			const tier = found.tier === "none" && blind ? "unknown" : found.tier;
-			for (const trigger of g.triggers) seams.flowRows.push({ trigger, flow: g.flow, tier, package: found.package, repo: found.repo });
+			for (const trigger of g.triggers) seams.flowRows.push({ trigger, flow: g.flow, tier, package: found.package, repo: found.repo, basis: g.basis });
 			if (resolved) {
 				checks.push({ ok: true, label: `Trigger flow "${g.flow}" resolves (${at}: ${resolved})` });
 			} else {
@@ -6883,18 +6884,12 @@ function readTriggerFacts(env, fileExists, cwd, declaredWorkerName, versionTable
 			// two triggers naming the same flow with different skillsDirs are two different questions.
 			// The label is how a line names its trigger: cron entries by their id, id-less webhook
 			// entries by raw file position (the admin's trigger:<index> identity).
+			// Issue #869: what `flowTierOf` is asked and the basis each published row carries come from the one module the console
+			// computes its basis with (`flowInputOf`, `flowBasisOf`), from the trigger as the loader parsed it, so the two cannot
+			// read a field two ways. A command trigger and a disarmed one-shot name no flow and drop out here.
 			flows: triggers
-				.map((t, index) => ({
-					index,
-					label: triggerLabel(t, index),
-					flow: t.run.flow,
-					kind: t.run.kind,
-					folder: typeof t.run.folder === "string" ? t.run.folder : null,
-					skillsDir: typeof t.run.skillsDir === "string" ? t.run.skillsDir : null,
-					packages: t.run.packages !== false,
-					excludeExtensions: Array.isArray(t.run.excludeExtensions) ? t.run.excludeExtensions : [],
-				}))
-				.filter((f) => typeof f.flow === "string"),
+				.map((t, index) => ({ index, label: triggerLabel(t, index), kind: t.run.kind, ...flowInputOf(t), basis: flowBasisOf(t) }))
+				.filter((f) => f.flow !== null),
 			// Issue #800: each trigger's run.excludeExtensions, for the line that says a name is on neither side of this host.
 			excludedNames: triggers.flatMap((t, index) => (Array.isArray(t.run.excludeExtensions) ? [{ label: triggerLabel(t, index), names: t.run.excludeExtensions, packages: t.run.packages !== false }] : [])),
 			// Issue #501: every trigger that sets run.maxCostUsd, with the label the cap check names it by. The value
@@ -9804,7 +9799,12 @@ export function sizeSuggestionChecks({ projects = [], limits = [], env = {}, rec
 		const words = suggestionEvidence(s);
 		const size = `${formatMemory(current.memMiB)}, ${cpusText(current.cpuCenti)}`;
 		const call = suggestionCall(s, limits);
-		const facts = [words.memoryFact, words.cpuFact].filter(Boolean);
+		// Issue #865: `memoryCeiling` rides after the suggestion and BEFORE the two facts: it comes only with an OOM, whose
+		// line is a warning, and a warn or fail label (the first DOCTOR_DETAILED_MAX, 80, of a run) is published cut at
+		// DOCTOR_LABEL_MAX, so what a cut takes first is the facts (information with no call) and then this pointer's tail,
+		// never a held raise, a refusal or a budget note, which come before it, nor the call: a raise carries its call in
+		// its fix, and a lowering, an ok line with no model proposal, is published as its id and level only.
+		const facts = [words.memoryCeiling, words.memoryFact, words.cpuFact].filter(Boolean);
 		const factTail = facts.length > 0 ? `; ${facts.join("; ")}` : "";
 		const held = s.memory.suggested === null && s.memory.held !== null;
 		if (call === null && !held) {
@@ -9828,7 +9828,12 @@ export function sizeSuggestionChecks({ projects = [], limits = [], env = {}, rec
 		const note = totals.length > 0 ? ` (note: ${totals.join(" and ")}; its budget is off or unknown, so the worker admits it)` : "";
 		const raise = (s.memory.suggested ?? 0) > current.memMiB || (s.cpu.suggested ?? 0) > current.cpuCenti;
 		const suggests = parts.length > 0 ? `its runs in the last ${SUGGEST_WINDOW_DAYS} days suggest ${parts.join(" and ")}` : "";
-		const label = `project ${id}: size ${size}; ${[heldText ? `in the last ${SUGGEST_WINDOW_DAYS} days ${heldText}` : "", suggests].filter(Boolean).join("; ")}${over.length > 0 ? `, but ${over.join(" and ")}, so a job of it would never fit this host` : ""}${note}${factTail}`;
+		// The label without its facts, so a line that carries its call in the label (a lowering, below) prints the call
+		// right after the suggestion it applies, and the no-call facts after that (#865, review). Reading order in the
+		// terminal only: a lowering is an ok check with no model proposal, which `buildDoctorRecord` (doctor-results.mjs,
+		// INT-DOCTOR-RESULTS-KEY) publishes as its id and level, with no label, so no publish cut ever reaches it.
+		const head = `project ${id}: size ${size}; ${[heldText ? `in the last ${SUGGEST_WINDOW_DAYS} days ${heldText}` : "", suggests].filter(Boolean).join("; ")}${over.length > 0 ? `, but ${over.join(" and ")}, so a job of it would never fit this host` : ""}${note}`;
+		const label = `${head}${factTail}`;
 		// a size that would never fit is never offered as a call: applying it would turn a refusal into the same refusal.
 		const apply = call === null ? "" : over.length > 0 ? "" : `apply it in the admin panel with ${call} (an operator confirms it; nothing applies a size by itself)`;
 		const never = over.length > 0 ? "no call is offered: a job of that size would never fit this host" : "";
@@ -9839,7 +9844,7 @@ export function sizeSuggestionChecks({ projects = [], limits = [], env = {}, rec
 		} else if (raise || over.length > 0 || totals.length > 0) {
 			checks.push({ ok: false, warn: true, label, fix: apply || never });
 		} else {
-			checks.push({ ok: true, label: `${label}; ${apply.replace(/ \(an operator confirms it; nothing applies a size by itself\)$/, "")}` });
+			checks.push({ ok: true, label: `${head}; ${apply.replace(/ \(an operator confirms it; nothing applies a size by itself\)$/, "")}${factTail}` });
 		}
 	}
 	return checks;

package/src/env-allowlist.mjs

@@ -30,7 +30,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { findEnvKeys } from "@earendil-works/pi-ai/compat";
 import { getBuiltinProviders } from "@earendil-works/pi-ai/providers/all";
-import { codemodeWorkersOf, DEFAULT_JOB_SIZE } from "./job-size.mjs";
+import { codemodeWorkersOf, DEFAULT_JOB_SIZE, jobSizeEnv } from "./job-size.mjs";
 import { egressEnv } from "./egress.mjs";
 import { RECEIVER_ONLY_VARS, forgeSpec } from "./forges.mjs";
 import { apiKeyVariable } from "./provider-key.mjs";
@@ -637,6 +637,14 @@ export function buildContainerEnv({ size = DEFAULT_JOB_SIZE, provider, secondary
 	// env-internal PI_CODEMODE_MAX_WORKERS: written into the job's closed env map here, never read from the worker's environment.
 	env.PI_CODEMODE_MAX_WORKERS = String(codemodeWorkersOf(size.memMiB));
 
+	// Issue #865: the job's size, `PI_JOB_SIZE_CPUS` (its CPUs rounded up) and `PI_JOB_SIZE_MEMORY_MIB`, from the same
+	// resolved size as the container's flags (`jobSizeEnv`, which the sandbox shell shares). Inside the container a CPU
+	// count reads as the host ceiling (`availableParallelism()`) or the whole runtime (`nproc`), never the size, so these
+	// are the one place a flow or an image can size a per-CPU worker pool from. Information, not a bound, and read from
+	// no payload. Set after forwarding and secrets, for PI_CODEMODE_MAX_WORKERS' reason: both names are reserved in
+	// CONTAINER_ENV_NAMES, and this is the backstop if a refusal upstream is ever bypassed.
+	Object.assign(env, jobSizeEnv(size));
+
 	// Issue #500: the runner sets these in its own environment, for its child processes, and no value from outside
 	// may arrive first. Both lists refuse them upstream (config.mjs for PI_FORWARD_ENV, the triggers loader for
 	// run.secrets, through RUNNER_ENV_NAMES); this is the line that holds if either refusal is ever bypassed.

package/src/github-app-setup.mjs

@@ -49,6 +49,11 @@ const API_ROOT = "https://api.github.com";
 const USER_AGENT = "pi-dispatch-setup-github";
 // The repo homepage, shown on the App's about page — informational, not a trust anchor.
 const HOMEPAGE = "https://github.com/edgehero/pi-dispatch";
+// The webhook URL of an App made with --no-webhook (issue #874). GitHub requires one even for an inactive hook. A
+// `.invalid` name (RFC 6761) never resolves, so nothing GitHub sends there reaches any host: not the ping an inactive
+// hook still got at creation (in the measurement that `buildManifest`'s comment cites), and not an event if someone
+// ticks Active later without changing the URL. A real host would get both, and a domain can change owner.
+export const NO_WEBHOOK_URL = "https://no-webhook.invalid/";
 // GitHub app names are GLOBALLY unique and capped at 34 characters.
 const NAME_MAX = 34;
 
@@ -363,7 +368,11 @@ function printSummary(say, summary, { noWebhook }) {
 	say("\nNext:\n");
 	if (noWebhook) {
 		say("  the App was created with its webhook INACTIVE (--no-webhook) — the polling-ready shape.\n");
-		say("  Polling delivery is a follow-up; until it lands, forge triggers for this App will not fire on their own.\n");
+		say("  start the poller so events reach the queue: `pi-dispatch-receiver poll`. Under GITHUB_AUTH_SOURCE=app it\n");
+		say("  watches the repositories of the installation GITHUB_APP_INSTALLATION_ID names; POLL_REPOS names a list of\n");
+		say("  your own instead. See docs/polling.md.\n");
+		say(`  the App's webhook URL is a placeholder, ${NO_WEBHOOK_URL}, which nothing can receive. Moving to webhooks\n`);
+		say("  later takes a webhook secret and an order of steps: docs/polling.md, \"Moving to webhooks later\".\n");
 	} else {
 		say("  start the receiver so deliveries have somewhere to land: `pi-dispatch-receiver`\n");
 		say("  (or, where the folder holds deploy/docker-compose.yml, its receiver profile), reachable at the --webhook-url you gave GitHub.\n");
@@ -402,8 +411,12 @@ export function sanitizeAppName(raw) {
  * The manifest GitHub converts into the App — the narrowest shape this system needs
  * (SECURITY.md's auth-source ladder): write on exactly the three surfaces jobs touch, metadata read
  * because the API requires it, private, and only the event families the triggers file can name.
- * `hook_attributes` carries the receiver URL, or `active: false` under --no-webhook — the
- * no-public-URL shape the polling transport will consume.
+ * `hook_attributes` carries the receiver URL, or under --no-webhook an INACTIVE hook at `NO_WEBHOOK_URL`. GitHub
+ * refuses a manifest whose `hook_attributes` has no `url`, inactive or not ("url" wasn't supplied, issue #874), and one
+ * that leaves `hook_attributes` out while it subscribes events ("Hook url cannot be blank"). What it accepts was
+ * measured against github.com on 2026-11-09 by another project's throwaway Apps: a `.invalid` URL with
+ * `active: false` was accepted, only `localhost` and `127.0.0.1` were refused as not reachable over the public
+ * Internet, and the App with the inactive hook recorded one delivery, its creation's ping, and no event after it.
  *
  * `pull_request_review` (issue #66) is subscribed for every new App, armed trigger or not. That is the
  * posture `pull_request` already has for a label-only deployment: an unsubscribed event cannot be turned
@@ -415,7 +428,7 @@ export function buildManifest({ name, redirectUrl, webhookUrl }) {
 		name,
 		url: HOMEPAGE,
 		redirect_url: redirectUrl,
-		hook_attributes: webhookUrl ? { url: webhookUrl } : { active: false },
+		hook_attributes: webhookUrl ? { url: webhookUrl } : { url: NO_WEBHOOK_URL, active: false },
 		public: false,
 		default_permissions: { contents: "write", pull_requests: "write", issues: "write", metadata: "read" },
 		default_events: ["issues", "issue_comment", "pull_request", "pull_request_review"],

package/src/host-loads.mjs

@@ -14,9 +14,11 @@
  * charset, on the way in AND on the way out, since another host wrote what a reader parses. An overlay extension's first
  * path segment and whether it is a file or a folder; a skill's folder name; a server's name, transport, where it is
  * (`mcpServerWhere`: a url's host and port, or a command's base name, never a header, an argument or a value), exposure,
- * whether it is on, and the variable NAMES it references; a package's name and version; a trigger's position, flow name and
- * the tier it resolved in. No path, no value and no tool name: what a server or an extension offers is known only once it
- * runs, and the run's own record says that. These are the same facts the viewer's Connections page shows; a model's
+ * whether it is on, and the variable NAMES it references; a package's name and version; a trigger's position, flow name,
+ * the tier it resolved in and a short hex digest of the trigger fields that answer was judged from (`flowBasisOf`). No path,
+ * no value and no tool name: what a server or an extension offers is known only once it runs, and the run's own record says
+ * that. The digest holds a path (`run.folder`, `run.skillsDir`) only as a hash cut to 8 hex digits, which names nothing a
+ * reader can read back. These are the same facts the viewer's Connections page shows; a model's
  * projection (`modelConnections`) carries counts in place of `where` and the key names, and one of these rows gets the
  * same treatment when a tool reads it.
  *
@@ -27,6 +29,7 @@
  * folders on the host and runs nothing: a frontmatter `name:` rename is invisible, and what a run really loaded is its
  * own record's `loaded`. Where a read cannot say, it says so (`unread`), never an empty list that reads as none.
  */
+import { createHash } from "node:crypto";
 import * as nodeFs from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { DOCTOR_HOSTS, DOCTOR_HOSTS_MAX, DOCTOR_RESULTS_TTL_MS } from "./doctor-results.mjs";
@@ -73,6 +76,52 @@ const KEY_NAME_RE = /^[A-Z_][A-Z0-9_]{0,63}$/;
 const WHERE_RE = /^[A-Za-z0-9._:[\]-]{1,255}$/;
 const INDEX_MAX = 1_000_000;
 
+/**
+ * The trigger fields `flowTierOf` reads, by the names its first argument gives them (issue #869). A flow row's `basis` is a
+ * digest of exactly these, so a test holds this list to that argument's own names: a field `flowTierOf` came to read that
+ * this list left out would let an edit to it keep the console answering for the file as it was.
+ */
+export const FLOW_INPUT_FIELDS = Object.freeze(["flow", "folder", "skillsDir", "packages", "excludeExtensions"]);
+/**
+ * How long a basis is, in hex digits: 32 bits. A collision costs one stale answer read as current, which is what every edit
+ * cost before the basis, and the triggers file has no author but the operator, so nobody gains by aiming for one. Per edit the
+ * odds are one in about four billion. REJECTED: a longer digest, which a flow row carries 128 times over in a record that already
+ * trims its flow rows at its worst (`FIT_ORDER`), so each digit would put a trigger's answer out of the record on such a host.
+ */
+export const FLOW_BASIS_HEX = 8;
+const FLOW_BASIS_RE = new RegExp(`^[0-9a-f]{${FLOW_BASIS_HEX}}$`);
+
+/**
+ * What `flowTierOf` is asked of a trigger as the loader parsed it (`parseTriggers`' entry): doctor's flow lines and its published
+ * rows ask it this, and nothing else does. A field that is not there reads as `flowTierOf`'s own default. A disarmed one-shot is
+ * the loader's sentinel, whose `run` is empty, so it names no flow and doctor publishes no row for it.
+ */
+export function flowInputOf(trigger) {
+	const run = isObject(trigger?.run) ? trigger.run : {};
+	return {
+		flow: typeof run.flow === "string" ? run.flow : null,
+		folder: typeof run.folder === "string" ? run.folder : null,
+		skillsDir: typeof run.skillsDir === "string" ? run.skillsDir : null,
+		packages: run.packages !== false,
+		excludeExtensions: Array.isArray(run.excludeExtensions) ? run.excludeExtensions.filter((name) => typeof name === "string") : [],
+	};
+}
+
+/**
+ * The basis of a flow row (issue #869): a digest of what `flowTierOf` was asked of this trigger, from the trigger as the loader
+ * parsed it. Doctor writes it beside each answer, and the console computes it from its own parse of the file it reads, through
+ * this one function, so the two cannot compute it two ways. Where they differ, the answer was judged for another version of the file.
+ * `flowTierOf` only asks whether a name is in `excludeExtensions`, so the list's order and a repeat change nothing here either.
+ * REJECTED: leaving the list out under `"packages": false`, where `flowTierOf` does not look at it. An edit there would then keep
+ * the answer, at the price of a copy of `flowTierOf`'s branches here that would have to move with them, and the cost of not doing
+ * it is an answer read as unknown until doctor runs on the file as it is, the safe direction.
+ */
+export function flowBasisOf(trigger) {
+	const input = flowInputOf(trigger);
+	const canonical = FLOW_INPUT_FIELDS.map((field) => (field === "excludeExtensions" ? [...new Set(input[field])].sort() : input[field]));
+	return createHash("sha256").update(JSON.stringify(canonical)).digest("hex").slice(0, FLOW_BASIS_HEX);
+}
+
 /** A first path segment: the shape a run's record holds, less the two a folder listing never returns and a path could. */
 const extensionOf = (row) => (isObject(row) && typeof row.name === "string" && EXTENSION_NAME_RE.test(row.name) && row.name !== "." && row.name !== ".." && LOADS_EXTENSION_KINDS.includes(row.kind) ? { name: row.name, kind: row.kind } : null);
 const skillOf = (name) => (typeof name === "string" && SKILL_NAME_RE.test(name) ? name : null);
@@ -83,7 +132,10 @@ const flowOf = (row) => {
 	if (flow === null && row.flow !== null) return null;
 	const pkg = row.package === null ? null : isPackageName(row.package) ? row.package : undefined;
 	if (pkg === undefined || (pkg !== null && row.tier !== "package")) return null;
-	return { trigger: row.trigger, flow, tier: row.tier, package: pkg, repo: row.repo };
+	// Absent is a row from a release before issue #869, which a reader answers from as it did. Any other shape is refused, never
+	// read as absent: that would put a row of unknown basis back on the older rule, which answers whatever the file now says.
+	if (row.basis !== undefined && (typeof row.basis !== "string" || !FLOW_BASIS_RE.test(row.basis))) return null;
+	return { trigger: row.trigger, flow, tier: row.tier, package: pkg, repo: row.repo, ...(row.basis === undefined ? {} : { basis: row.basis }) };
 };
 /** One server's row, or null, with how many of its keys its cap left out. */
 const serverOf = (row) => {
@@ -346,6 +398,8 @@ export function hostsAgree(rows) {
  *   resolved, checked, unknown   the words of doctor's own line, which name folders and so are never published
  *
  * `repoFlowAtHead(folder, flow)` answers `present`, `absent` or anything else for not known. `staged` is `readStagedSkills`.
+ * The first argument is `flowInputOf`'s, and its names are `FLOW_INPUT_FIELDS`: a new one goes in both, or a flow row's basis
+ * would not change when it does (`worker/test/host-loads.test.mjs` reads them off this signature).
  */
 export async function flowTierOf({ flow, folder = null, skillsDir = null, packages = true, excludeExtensions = [] }, { repoFlowAtHead, fileExists, overlay = null, staged = { skills: [], unenumerable: [] } }) {
 	let tier = null;

package/src/job-size.mjs

@@ -106,6 +106,33 @@ export function codemodeWorkersOf(memMiB) {
 	return Math.max(1, Math.floor(memMiB / (2 * CODEMODE_WORKER_HEAP_MIB)));
 }
 
+/**
+ * Issue #865: a size's CPUs as a whole count, rounded UP (`1.5` is 2, `0.25` is 1), for a tool's `-j` or worker flag,
+ * which takes no fraction. Up, not down, so no size reads as 0 and a size between two counts gets the larger one: it is
+ * a pool size under a CPU WEIGHT, and the job may already use idle cores beyond its size (the `--cpus` ceiling above).
+ */
+export function wholeCpusOf(cpuCenti) {
+	return Math.ceil(cpuCenti / 100);
+}
+
+/**
+ * Issue #865: the job's size as its own processes can read it, `{ PI_JOB_SIZE_CPUS, PI_JOB_SIZE_MEMORY_MIB }`, both
+ * decimal strings. A job's CPU size is a weight that nothing inside the container can see: `os.availableParallelism()`
+ * reads the cgroup's `cpu.max`, which is the host ceiling (`--cpus`, the same for every job), and `nproc` reads the
+ * affinity mask, which is the whole runtime. So a tool that starts one worker per CPU it sees (jest and vitest by
+ * default) starts one per CEILING CPU, all inside the size's memory, which is the hard bound. These two values are what
+ * a flow, an image or the agent's commands size such a pool from instead.
+ *
+ * INFORMATION, NOT A BOUND: the size is resolved at pickup and enforced by the container's flags; nothing reads these
+ * back. One function, so the job's closed env map (`env-allowlist.mjs`) and the operator's sandbox shell
+ * (`sandbox.mjs`) cannot spell them two ways. Not `PI_JOB_CPUS` and `PI_JOB_MEMORY`: those name the DEPLOYMENT's default
+ * size in `.env`, and a project row can give a job another one.
+ */
+export function jobSizeEnv(size) {
+	assertJobSize(size);
+	return { PI_JOB_SIZE_CPUS: String(wholeCpusOf(size.cpuCenti)), PI_JOB_SIZE_MEMORY_MIB: String(size.memMiB) };
+}
+
 /** The scope prefix of a project row, as `scoped-limits.mjs` spells it (`PROJECT_SCOPE_PREFIX`; a test holds them equal). */
 const PROJECT_ROW_PREFIX = "project:";