@patronage/software-factory 1.0.0-alpha.26 → 1.0.0-alpha.27

package/dist/index.js

@@ -1,12 +1,10 @@
-#!/usr/bin/env node
 import { t as __exportAll } from "./chunk-pbuEa-1d.js";
-import { appendFileSync, constants, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { pathToFileURL } from "node:url";
 import { Command, InvalidArgumentError } from "commander";
 import path from "node:path";
 import crypto, { createHash, randomBytes, randomUUID } from "node:crypto";
 import { z } from "zod";
 import { execFileSync, spawnSync } from "node:child_process";
+import { appendFileSync, constants, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { Buffer as Buffer$1 } from "node:buffer";
 import picomatch from "picomatch";
 import { link, lstat, mkdir, open, readFile, readdir, realpath, rename, stat, unlink } from "node:fs/promises";
@@ -16,9 +14,27 @@ import { setImmediate as setImmediate$1, setTimeout as setTimeout$1 } from "node
 import { Worker } from "node:worker_threads";
 import { parse } from "yaml";
 import { promisify } from "node:util";
-import { FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, mintInstallationToken, previewProofInventory, productionImpactTargetOutput, readVitestProfileDocument } from "@patronage/factory-ci";
+import { FACTORY_APP_BROKER_ORIGIN, FACTORY_APP_BROKER_PATH, FACTORY_CURSOR_OIDC_AUDIENCE, FACTORY_PROOF_GATE_APP_ID, FACTORY_PROOF_GATE_STEP_NAME, GitHubApiError, mintInstallationToken, previewProofInventory, productionImpactTargetOutput, readVitestProfileDocument } from "@patronage/factory-ci";
+import http from "node:http";
+import { pathToFileURL } from "node:url";
 //#region package.json
-var version = "1.0.0-alpha.26";
+var version = "1.0.0-alpha.27";
+//#endregion
+//#region src/cli-entry.ts
+/**
+* The path of the module that runs a factory command.
+*
+* The package publishes two dist entries (#386). `index.js` is the library
+* export: consumers import it, so it runs nothing. `cli.js` is the bin, and it
+* is the only entry that runs a command. A spawned follow-up that names
+* `index.js` therefore exits 0 having done nothing.
+*
+* Every caller that needs the runnable entry resolves it here, so there is one
+* place to get it wrong rather than one per call site. The entry is this
+* module's sibling and carries this module's extension — `cli.ts` under tsx in
+* development, `cli.js` in the built package.
+*/
+const factoryCliEntry = () => path.join(import.meta.dirname, `cli${path.extname(import.meta.filename)}`);
 //#endregion
 //#region src/review-rungs.ts
 const EVIDENCE_REVIEW_RUNGS = [
@@ -1261,11 +1277,52 @@ function currentHeadSha(cwd) {
 function repositoryRoot(cwd) {
 	return runCapture("git", ["rev-parse", "--show-toplevel"], cwd).stdout.trim();
 }
-function showFileAtRef(cwd, ref, absolutePath) {
-	const rel = path.relative(cwd, absolutePath);
-	const spec = rel.startsWith(".") ? rel : `./${rel}`;
+/** A path handed to a git object read that is not repository-relative. */
+var RepositoryRelativePathError = class extends Error {
+	name = "RepositoryRelativePathError";
+};
+/**
+* The repository-relative contract, enforced before a path reaches git.
+*
+* git resolves `<ref>:<path>` from the repository root ONLY for a bare name.
+* Measured against real git from a package subdirectory, `HEAD:./package.json`
+* and `HEAD:../software-factory/package.json` both resolve — the first against
+* the working directory, the second by traversal. So a caller that passes
+* either form silently addresses a different file depending on where the
+* command ran, which is the whole defect class this contract exists to close
+* (#922, #1004 review cycles 2 to 4).
+*
+* Every current call site already passes a bare name; this makes the promise
+* enforced rather than documented. It throws instead of returning a value,
+* because a control that cannot answer must fail loudly, and callers that
+* tolerate a missing file must not silently tolerate a mis-addressed one.
+*/
+function assertRepositoryRelativePath(repositoryRelativePath, caller) {
+	const refuse = (reason) => {
+		throw new RepositoryRelativePathError(`${caller} requires a repository-relative path, but received ${JSON.stringify(repositoryRelativePath)}: ${reason}. git resolves "<ref>:<path>" from the repository root only for a bare name, so a "./", "../", or absolute form addresses a different file depending on the working directory.`);
+	};
+	if (repositoryRelativePath.length === 0) return refuse("it is empty");
+	if (repositoryRelativePath.startsWith("/") || path.isAbsolute(repositoryRelativePath)) return refuse("it is absolute");
+	if (repositoryRelativePath.split("/").some((segment) => segment === "." || segment === "..")) return refuse("it contains a \".\" or \"..\" segment");
+	return repositoryRelativePath;
+}
+/**
+* A file's content at a ref, addressed the way git addresses it (#922).
+*
+* `repositoryRelativePath` is repository-relative, NOT relative to `cwd`.
+* git resolves `<ref>:<path>` from the repository ROOT unless the path starts
+* with `./` or `../`, so a repository-relative name is correct from every
+* working directory inside the checkout, including one reached through a
+* symlink. `cwd` is still passed so git discovers the same repository.
+*
+* This used to relativize an absolute path against `cwd` and prefix `./`,
+* which made the address cwd-relative and therefore wrong from any
+* subdirectory (#1004 review cycles 2 and 3).
+*/
+function showFileAtRef(cwd, ref, repositoryRelativePath) {
+	assertRepositoryRelativePath(repositoryRelativePath, "showFileAtRef");
 	try {
-		return runCapture("git", ["show", `${ref}:${spec}`], cwd).stdout;
+		return runCapture("git", ["show", `${ref}:${repositoryRelativePath}`], cwd).stdout;
 	} catch {
 		return;
 	}
@@ -5483,7 +5540,7 @@ const analyzeSourcePaths = (sourceFiles, targets, profilePath, inertGlobs) => {
 		};
 		if (file === profilePath) return {
 			kind: "conservative",
-			reason: `changed source path "${file}" is the impact profile being evaluated; fail closed to full impact`
+			reason: `changed source path "${file}" is the impact profile being evaluated; fail closed to full impact. A profile migration waives each retired target's required-check demand (see the admission skill).`
 		};
 	}
 	return {
@@ -6009,6 +6066,75 @@ function generationOrderMs(value) {
 	return Number.isFinite(parsed) ? parsed : Number.NEGATIVE_INFINITY;
 }
 //#endregion
+//#region src/cursor-oidc-mint.ts
+const DEFAULT_CURSOR_AGENT_SOCKET = "/run/cursor/api.sock";
+const DEFAULT_TIMEOUT_MS = 5e3;
+const cursorAgentSocketPath = (env = process.env) => {
+	const fromEnv = env.CURSOR_AGENT_SOCKET;
+	return fromEnv !== void 0 && fromEnv.length > 0 ? fromEnv : DEFAULT_CURSOR_AGENT_SOCKET;
+};
+const isCursorManagedVm = (env = process.env, exists = existsSync) => {
+	if (env.CURSOR_AGENT_SOCKET !== void 0 && env.CURSOR_AGENT_SOCKET.length > 0) return true;
+	return exists(DEFAULT_CURSOR_AGENT_SOCKET);
+};
+var CursorOidcMintError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "CursorOidcMintError";
+	}
+};
+/**
+* Mint a Cursor OIDC JWT from the local agent socket. No nonce: the broker
+* does not run a nonce protocol (#949).
+*/
+const mintCursorOidcToken = (options = {}) => new Promise((resolve, reject) => {
+	const socketPath = options.socketPath ?? cursorAgentSocketPath();
+	const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+	const body = JSON.stringify({ aud: options.audience ?? FACTORY_CURSOR_OIDC_AUDIENCE });
+	const req = http.request({
+		headers: {
+			"Content-Length": String(Buffer.byteLength(body)),
+			"Content-Type": "application/json"
+		},
+		method: "POST",
+		path: "/v1/tokens/oidc",
+		socketPath
+	}, (response) => {
+		const chunks = [];
+		response.on("data", (chunk) => {
+			chunks.push(chunk);
+		});
+		response.on("end", () => {
+			const text = Buffer.concat(chunks).toString("utf-8");
+			if (response.statusCode !== 200) {
+				reject(new CursorOidcMintError(`Cursor OIDC mint failed: ${String(response.statusCode)}`));
+				return;
+			}
+			let parsed;
+			try {
+				parsed = JSON.parse(text);
+			} catch {
+				reject(new CursorOidcMintError("Cursor OIDC mint returned invalid JSON"));
+				return;
+			}
+			if (parsed === null || typeof parsed !== "object" || typeof parsed.token !== "string") {
+				reject(new CursorOidcMintError("Cursor OIDC mint omitted token"));
+				return;
+			}
+			resolve(parsed.token);
+		});
+	});
+	req.on("error", (error) => {
+		reject(new CursorOidcMintError(`Cursor OIDC mint failed: ${error instanceof Error ? error.message : String(error)}`));
+	});
+	req.setTimeout(timeoutMs, () => {
+		req.destroy();
+		reject(new CursorOidcMintError("Cursor OIDC mint timed out"));
+	});
+	req.write(body);
+	req.end();
+});
+//#endregion
 //#region src/pr-verify-status.ts
 const PR_VERIFY_STATUS_CONTEXT = "patronage-factory/pr-verify";
 const GITHUB_PUBLISH_TIMEOUT_MS = 5e3;
@@ -6067,6 +6193,143 @@ function createGhCommitStatusPoster(output, run = runGhStatus) {
 	};
 }
 //#endregion
+//#region src/factory-app-broker-client.ts
+const FACTORY_APP_BROKER_URL = `${FACTORY_APP_BROKER_ORIGIN}${FACTORY_APP_BROKER_PATH}`;
+var FactoryAppBrokerError = class extends Error {
+	status;
+	constructor(message, status) {
+		super(message);
+		this.name = "FactoryAppBrokerError";
+		if (status !== void 0) this.status = status;
+	}
+};
+const factoryAppBrokerUrl = (env = process.env) => {
+	const override = env.FACTORY_APP_BROKER_URL;
+	return override !== void 0 && override.length > 0 ? override : FACTORY_APP_BROKER_URL;
+};
+/**
+* Exchange a Cursor OIDC JWT for a repo-scoped Factory App installation token.
+* Missing or refused exchange fails closed — no token is invented.
+*/
+const exchangeFactoryAppInstallationToken = async (input) => {
+	const request = input.fetch ?? fetch;
+	const url = input.url ?? FACTORY_APP_BROKER_URL;
+	let response;
+	try {
+		response = await request(url, {
+			body: JSON.stringify({
+				owner: input.owner,
+				repo: input.repo
+			}),
+			headers: {
+				Authorization: `Bearer ${input.oidc}`,
+				"Content-Type": "application/json"
+			},
+			method: "POST",
+			signal: AbortSignal.timeout(input.timeoutMs ?? 5e3)
+		});
+	} catch (error) {
+		throw new FactoryAppBrokerError(`Factory App broker exchange failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!response.ok) throw new FactoryAppBrokerError(`Factory App broker exchange failed: ${String(response.status)}`, response.status);
+	const body = await response.json();
+	if (body === null || typeof body !== "object" || typeof body.token !== "string" || body.token.length === 0) throw new FactoryAppBrokerError("Factory App broker exchange omitted token");
+	return body.token;
+};
+//#endregion
+//#region src/github-app-access.ts
+const NO_APP_SKIP_MESSAGE = "no factory GitHub App configured; skipping durable check-run republish.\n";
+const exchangeFromCursorVm = async (repository, dependencies, env, request, timeoutMs) => {
+	const mint = dependencies.mintCursorOidc ?? mintCursorOidcToken;
+	const exchange = dependencies.exchangeBroker ?? exchangeFactoryAppInstallationToken;
+	let oidc;
+	try {
+		oidc = await mint({
+			socketPath: cursorAgentSocketPath(env),
+			timeoutMs
+		});
+	} catch (error) {
+		return {
+			failClosed: true,
+			kind: "unavailable",
+			message: `Cursor OIDC mint failed: ${error instanceof Error ? error.message : String(error)}\n`
+		};
+	}
+	try {
+		return {
+			appId: FACTORY_PROOF_GATE_APP_ID,
+			kind: "ok",
+			token: await exchange({
+				fetch: request,
+				oidc,
+				owner: repository.owner,
+				repo: repository.repo,
+				timeoutMs,
+				url: factoryAppBrokerUrl(env)
+			})
+		};
+	} catch (error) {
+		return {
+			failClosed: true,
+			kind: "unavailable",
+			message: `Factory App broker exchange failed: ${error instanceof Error ? error.message : String(error)}\n`
+		};
+	}
+};
+/**
+* Resolve a Factory App installation token for App-owned GitHub writes.
+*
+* Order: caller token, `FACTORY_GITHUB_APP_TOKEN` (Actions), local PEM mint,
+* Cursor OIDC broker exchange. A Cursor-managed VM with no PEM must succeed
+* the exchange; missing mint or publication fails closed (#949).
+*/
+const resolveFactoryAppAccess = async (repository, dependencies = {}) => {
+	const env = dependencies.env ?? process.env;
+	if (dependencies.token) return {
+		appId: FACTORY_PROOF_GATE_APP_ID,
+		kind: "ok",
+		token: dependencies.token
+	};
+	const workflowToken = env.FACTORY_GITHUB_APP_TOKEN;
+	if (workflowToken !== void 0 && workflowToken.length > 0) return {
+		appId: FACTORY_PROOF_GATE_APP_ID,
+		kind: "ok",
+		token: workflowToken
+	};
+	const config = dependencies.githubApp ?? tryUserConfig({ env })?.config.githubApp;
+	const request = dependencies.fetch ?? fetch;
+	const timeoutMs = dependencies.timeoutMs ?? 5e3;
+	if (config) try {
+		const token = await mintInstallationToken({
+			credentials: config,
+			owner: repository.owner,
+			repo: repository.repo
+		}, {
+			fetch: request,
+			now: dependencies.now ?? Date.now,
+			timeoutMs,
+			...dependencies.transportAttempts === void 0 ? {} : { transportAttempts: dependencies.transportAttempts }
+		});
+		return {
+			appId: String(config.appId),
+			kind: "ok",
+			token
+		};
+	} catch (error) {
+		return {
+			failClosed: true,
+			kind: "unavailable",
+			message: `unable to mint Factory App token: ${error instanceof Error ? error.message : String(error)}\n`
+		};
+	}
+	if (isCursorManagedVm(env, dependencies.existsSync)) return exchangeFromCursorVm(repository, dependencies, env, request, timeoutMs);
+	return {
+		failClosed: false,
+		kind: "unavailable",
+		message: NO_APP_SKIP_MESSAGE
+	};
+};
+//#endregion
 //#region src/github-app-client.ts
 const readExchange = async (request, url, init, timeoutMs) => {
 	const response = await request(url, {
@@ -6159,14 +6422,10 @@ const OUTCOMES = ["aborted", "passed"];
 const isOutcome = (value) => OUTCOMES.includes(value);
 /**
 * The payload's outcome must agree with the check run's own conclusion, which
-* comes from `verifyProofPassed`: a schemaVersion 1 proof predates the
-* `outcome` field and counts as passing for the compatibility window. Any other
-* proof with no recorded outcome is unfinished (fail closed).
+* comes from `verifyProofPassed`: a proof with no recorded outcome is
+* unfinished (fail closed).
 */
-const outcomeFor = (value) => {
-	if (isOutcome(value.outcome)) return value.outcome;
-	return value.schemaVersion === 1 ? "passed" : "aborted";
-};
+const outcomeFor = (value) => isOutcome(value.outcome) ? value.outcome : "aborted";
 const asClassification = (value) => DIFF_CLASSIFICATIONS.includes(value) ? value : "unknown";
 /**
 * Project a local pr:verify proof onto the durable check-run payload. Accepts
@@ -6394,7 +6653,7 @@ async function postFactoryCheckRun({ config, deadlineMs, dependencies, detailsUr
 	const request = dependencies.fetch ?? fetch;
 	const timeoutMs = dependencies.timeoutMs ?? 5e3;
 	try {
-		const token = await installationToken(input, config, request, (dependencies.now ?? Date.now)(), {
+		const token = dependencies.token ?? await installationToken(input, config, request, (dependencies.now ?? Date.now)(), {
 			timeoutMs,
 			transportAttempts: 1
 		});
@@ -6488,7 +6747,7 @@ async function resolveDetailsUrlSafely(input, dependencies, onDiagnostic) {
 async function servedFactoryCheckRun(input, config, dependencies) {
 	const request = dependencies.fetch ?? fetch;
 	const timeoutMs = dependencies.timeoutMs ?? 5e3;
-	const token = await installationToken(input, config, request, (dependencies.now ?? Date.now)(), { timeoutMs });
+	const token = dependencies.token ?? await installationToken(input, config, request, (dependencies.now ?? Date.now)(), { timeoutMs });
 	const query = new URLSearchParams({
 		app_id: String(config.appId),
 		check_name: FACTORY_CHECK_NAMES[input.gate],
@@ -6621,10 +6880,12 @@ async function confirmPublishedCheckRun({ config, createdId, dependencies, input
 * the head SHA visible on GitHub (pushed the branch, created the PR) can make
 * the proof reliably present for that SHA before it returns (#247).
 *
-* Never throws and never posts a commit-status fallback: the commit status is a
-* human-readable mirror, not a proof surface, so a caller that needs an
-* App-verified check run must be told plainly whether it got one. Returns
-* `true` only when the App-owned check run landed.
+* Never posts a commit-status fallback: the commit status is a human-readable
+* mirror, not a proof surface, so a caller that needs an App-verified check
+* run must be told plainly whether it got one. Returns `true` only when the
+* App-owned check run landed. Throws when Factory App access is fail-closed
+* (missing mint or Cursor OIDC exchange, #949): `pr:ready` must not notice
+* that miss and exit 0. An optional-App skip still returns `false`.
 *
 * "Landed" means GitHub serves it, not that the POST was accepted (#520). On
 * PR #519 the POST was accepted, `pr:ready` reported ready and armed, and the
@@ -6650,18 +6911,28 @@ async function confirmPublishedCheckRun({ config, createdId, dependencies, input
 */
 async function ensureFactoryCheckRunPublished(input, dependencies = {}) {
 	const { onDiagnostic } = dependencies;
+	const checkName = FACTORY_CHECK_NAMES[input.gate];
+	const access = await resolveFactoryAppAccess(input, dependencies);
+	if (access.kind !== "ok") {
+		onDiagnostic?.(`${checkName}: ${access.message}`);
+		if (access.failClosed) throw new Error(`${checkName}: ${access.message.trim()}`);
+		return false;
+	}
 	try {
-		const config = dependencies.githubApp ?? tryUserConfig()?.config.githubApp;
-		if (!config) {
-			onDiagnostic?.(`${FACTORY_CHECK_NAMES[input.gate]}: no factory GitHub App configured; skipping durable check-run republish.\n`);
-			return false;
-		}
+		const config = dependencies.githubApp ?? tryUserConfig()?.config.githubApp ?? {
+			appId: access.appId,
+			privateKeyPath: "factory-app-broker"
+		};
+		const tokenDependencies = {
+			...dependencies,
+			token: access.token
+		};
 		const detailsUrl = await resolveDetailsUrlSafely(input, dependencies, onDiagnostic);
 		const created = await postFactoryCheckRun({
 			config,
 			dependencies: {
 				retry: DURABLE_CHECK_RUN_RETRY,
-				...dependencies
+				...tokenDependencies
 			},
 			detailsUrl,
 			input
@@ -6669,7 +6940,7 @@ async function ensureFactoryCheckRunPublished(input, dependencies = {}) {
 		return await confirmPublishedCheckRun({
 			config,
 			createdId: typeof created.id === "number" ? created.id : void 0,
-			dependencies,
+			dependencies: tokenDependencies,
 			input,
 			onDiagnostic
 		});
@@ -6708,15 +6979,26 @@ function createFactoryCheckPublisher(output, dependencies = {}) {
 					output.stderr.write(`${checkName}: unable to post fallback status: ${message}\n`);
 				}
 			};
-			const config = dependencies.githubApp ?? tryUserConfig()?.config.githubApp;
-			if (!config) {
-				postFallback();
+			const access = await resolveFactoryAppAccess(input, {
+				...dependencies,
+				transportAttempts: 1
+			});
+			if (access.kind !== "ok") {
+				output.stderr.write(`${checkName}: ${access.message}`);
+				if (!access.failClosed) postFallback();
 				return;
 			}
+			const config = dependencies.githubApp ?? tryUserConfig()?.config.githubApp ?? {
+				appId: access.appId,
+				privateKeyPath: "factory-app-broker"
+			};
 			try {
 				await postFactoryCheckRun({
 					config,
-					dependencies,
+					dependencies: {
+						...dependencies,
+						token: access.token
+					},
 					detailsUrl,
 					input
 				});
@@ -6733,6 +7015,77 @@ function createFactoryCheckPublisher(output, dependencies = {}) {
 	};
 }
 //#endregion
+//#region src/repository-profile-path.ts
+/**
+* `git rev-parse --show-toplevel` answers with a real path, while a caller's
+* `cwd` may reach the same directory through a symlink (every macOS temporary
+* directory does). Both sides are resolved before they are compared, so a
+* symlinked checkout is not mistaken for a profile outside the repository.
+*/
+const realPath = (value) => {
+	try {
+		return realpathSync(value);
+	} catch {
+		return value;
+	}
+};
+/**
+* The repository top level for `cwd`, or `cwd` itself when it is not a git
+* checkout. Never throws: a caller rooting a path has a usable answer either
+* way, and the checkout-less case keeps the previous cwd-rooted behavior.
+*/
+const repositoryRootOrCwd = ({ cwd, readRepositoryRoot = repositoryRoot }) => {
+	try {
+		return readRepositoryRoot(cwd);
+	} catch {
+		return cwd;
+	}
+};
+/**
+* The repository-relative, POSIX-separated path of `profilePath`.
+*
+* A cwd that is not a git checkout, and a profile the repository top level
+* does not contain, both fall back to the cwd-relative path: this function
+* makes a path more portable, and it must never invent one. Callers that
+* require the profile to be inside the trusted checkout keep enforcing that
+* themselves.
+*/
+const repositoryRelativeProfilePath = ({ cwd, profilePath, readRepositoryRoot = repositoryRoot }) => {
+	const cwdRelative = path.relative(cwd, profilePath).split(path.sep).join("/");
+	const root = repositoryRootOrCwd({
+		cwd,
+		readRepositoryRoot
+	});
+	const rootRelative = path.relative(realPath(root), realPath(profilePath)).split(path.sep).join("/");
+	return rootRelative.length > 0 && !rootRelative.startsWith("../") ? rootRelative : cwdRelative;
+};
+/** A path that names no file inside the root it was measured from. */
+const escapesRoot = (relativePath) => relativePath.length === 0 || relativePath === ".." || relativePath.startsWith("../") || path.isAbsolute(relativePath);
+/**
+* The same path, for a caller that must REFUSE a profile the repository does
+* not contain.
+*
+* Containment is measured from the repository top level, not from `cwd`.
+* Measuring it from `cwd` refuses the repository-root profile whenever the
+* command runs in a package subdirectory — a profile that is plainly inside
+* the trusted checkout — and it refused before the conversion above could run
+* (cycle-1 review finding on PR #1004).
+*
+* Fail-closed is unchanged. A profile genuinely outside the repository root
+* falls back to the cwd-relative path, which still escapes, and throws here.
+* A cwd that is not a git checkout has no root to measure from and keeps the
+* previous cwd-relative rule exactly.
+*/
+const repositoryContainedProfilePath = ({ cwd, profilePath, readRepositoryRoot = repositoryRoot }) => {
+	const relativePath = repositoryRelativeProfilePath({
+		cwd,
+		profilePath,
+		readRepositoryRoot
+	});
+	if (escapesRoot(relativePath)) throw new Error("The readiness profile must be inside the trusted checkout.");
+	return relativePath;
+};
+//#endregion
 //#region src/pr-classification.ts
 const MISSING_STAMP_REASON = "impact stamp is missing; fail closed to non-trivial";
 function ownershipFromStamp(stamp, file) {
@@ -6758,7 +7111,10 @@ function reasonForOwnership(file, ownership) {
 	}
 }
 function relativeProfilePath(options) {
-	return path.relative(options.cwd, options.profilePath).split(path.sep).join("/");
+	return repositoryRelativeProfilePath({
+		cwd: options.cwd,
+		profilePath: options.profilePath
+	});
 }
 function applyProfileEditGuard(files, relativeProfile, profilePath, base) {
 	if (!files.some((file) => file === relativeProfile || file === profilePath)) return base;
@@ -6990,9 +7346,7 @@ const planVerificationBattery = ({ commands, stamp, vetoedTargets }) => {
 *     skip this epic forbids.
 *
 * Rule 4 is scoped to `outcome: "passed"` because an ABORTED proof legitimately
-* records partial execution — the run stopped at the failing command. It is
-* also scoped to schemaVersion >= 4: `executedCommands` postdates v1–v3, so a
-* legacy proof that never recorded it is not making a false completeness claim.
+* records partial execution — the run stopped at the failing command.
 *
 * The check is one-directional on purpose. Every SELECTED command must be
 * accounted for, but `executedCommands` may legitimately carry MORE than the
@@ -7035,7 +7389,7 @@ const assertBatteryCompleteness = (proof, context) => {
 		});
 		seen.add(entry.name);
 	}
-	if (proof.outcome !== "passed" || proof.schemaVersion < 4) return;
+	if (proof.outcome !== "passed") return;
 	const disposed = new Set([...executed, ...seen]);
 	const undisposed = selected.filter((name) => !disposed.has(name));
 	if (undisposed.length > 0) context.addIssue({
@@ -7045,7 +7399,7 @@ const assertBatteryCompleteness = (proof, context) => {
 	});
 };
 /**
-* The stamp-authorization control: a passed v4 proof may only claim a command
+* The stamp-authorization control: a passed proof may only claim a command
 * was NOT REQUIRED if its own recorded stamp says so.
 *
 * `assertBatteryCompleteness` proves the two lists partition the selected
@@ -7068,8 +7422,8 @@ const assertBatteryCompleteness = (proof, context) => {
 *     provably released.
 *
 * The proof is one artifact and a determined forger controls all of it; this
-* is internal-coherence belt-and-braces in the same trust domain as the
-* version guards, and write-time truth stays `pr:verify`'s job.
+* is internal-coherence belt-and-braces in the same trust domain as the rest
+* of the proof, and write-time truth stays `pr:verify`'s job.
 *
 * The authorizing evidence is the proof's OWN `impactStamp` — the same stamp
 * `pr:verify` computed for this candidate's identity triple and recorded here,
@@ -7082,14 +7436,13 @@ const assertBatteryCompleteness = (proof, context) => {
 * self-contradictory stamp, an unclassified name, or an `affected` verdict all
 * fail the same way scoping itself would.
 *
-* Scoped to `outcome: "passed"` and schemaVersion >= 4 for the same reasons as
-* the completeness rule: an aborted run records partial execution, and a
-* legacy proof predates both fields, so neither is making a false completeness
+* Scoped to `outcome: "passed"` for the same reason as the completeness rule:
+* an aborted run records partial execution, so it makes no false completeness
 * claim.
 */
 const assertNotRequiredStampAuthorization = (proof, context) => {
 	const notRequired = proof.notRequiredCommands ?? [];
-	if (proof.outcome !== "passed" || proof.schemaVersion < 4 || notRequired.length === 0) return;
+	if (proof.outcome !== "passed" || notRequired.length === 0) return;
 	const { impactStamp } = proof;
 	if (impactStamp === void 0) {
 		context.addIssue({
@@ -7138,36 +7491,6 @@ const batteryScopeSummaryLines = (plan) => {
 //#endregion
 //#region src/pr-verify-proof-rules.ts
 const assertPrVerifyProofRules = (proof, context) => {
-	if (proof.schemaVersion >= 4 && proof.authoringSession === void 0) context.addIssue({
-		code: "custom",
-		message: "schemaVersion 4 pr:verify proof requires authoringSession (the recorded authoring identity, or the `unknown` sentinel).",
-		path: ["authoringSession"]
-	});
-	if (proof.schemaVersion < 4 && proof.authoringSession !== void 0) context.addIssue({
-		code: "custom",
-		message: "authoringSession is a schemaVersion>=4 field; a v1–v3 pr:verify proof must not carry it.",
-		path: ["authoringSession"]
-	});
-	if (proof.schemaVersion < 4 && proof.impactStamp !== void 0) context.addIssue({
-		code: "custom",
-		message: "impactStamp is a schemaVersion>=4 field; a v1–v3 pr:verify proof must not carry it.",
-		path: ["impactStamp"]
-	});
-	if (proof.schemaVersion < 4 && proof.notRequiredCommands !== void 0) context.addIssue({
-		code: "custom",
-		message: "notRequiredCommands is a schemaVersion>=4 field; a v1–v3 pr:verify proof must not carry it.",
-		path: ["notRequiredCommands"]
-	});
-	if (proof.schemaVersion < 4 && proof.catchUpRecognition !== void 0) context.addIssue({
-		code: "custom",
-		message: "catchUpRecognition is a schemaVersion>=4 field; a v1–v3 pr:verify proof must not carry it.",
-		path: ["catchUpRecognition"]
-	});
-	if (proof.schemaVersion < 4 && proof.notDemandedRecords !== void 0) context.addIssue({
-		code: "custom",
-		message: "notDemandedRecords is a schemaVersion>=4 field; a v1–v3 pr:verify proof must not carry it.",
-		path: ["notDemandedRecords"]
-	});
 	if (proof.notDemandedRecords !== void 0 && proof.impactStamp === void 0) context.addIssue({
 		code: "custom",
 		message: "notDemandedRecords requires impactStamp; package-level not-demanded records are bound to the stamp identity.",
@@ -7176,14 +7499,15 @@ const assertPrVerifyProofRules = (proof, context) => {
 	assertBatteryCompleteness(proof, context);
 	assertNotRequiredStampAuthorization(proof, context);
 };
-//#endregion
-//#region src/pr-verify-proof-contract.ts
-const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS = [
-	1,
-	2,
-	3,
-	4
-];
+/**
+* The pr:verify proof versions a reader accepts: the current one only (#920
+* item 1). #917 narrowed the pr:ready reader the same way. A pr:verify proof
+* is per-candidate and short-lived — it is rewritten on every head — so no
+* stored v1–v3 proof can outlive the release that drops it. Pre-1.0 posture
+* applies: one current contract, no compat reader. A consumer on an older
+* factory must adopt this release before HQ ingests its pr:verify proofs.
+*/
+const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS = [4];
 const executedCommandSchema = z.object({
 	command: z.string().min(1),
 	counts: z.object({
@@ -7194,7 +7518,6 @@ const executedCommandSchema = z.object({
 	exitCode: z.number(),
 	name: z.string().min(1),
 	scope: z.enum([
-		"always",
 		"docs-only",
 		"trivial",
 		"full"
@@ -7209,9 +7532,9 @@ const notDemandedRecordSchema = z.object({
 	basis: z.string().min(1),
 	name: z.string().min(1)
 });
-const prVerifySchemaVersionSchema = z.number().refine((value) => SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS.includes(value), { message: `schemaVersion must be one of: ${SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS.join(", ")}` });
+const prVerifySchemaVersionSchema = z.literal(4);
 const prVerifyProofSchema = z.object({
-	authoringSession: z.string().trim().min(1).optional(),
+	authoringSession: z.string().trim().min(1),
 	base: z.string().min(1),
 	baselineFullProofs: z.array(z.object({
 		base: z.string().min(1),
@@ -7257,7 +7580,6 @@ const prVerifyProofSchema = z.object({
 		impactTarget: z.string().min(1).optional(),
 		name: z.string().min(1),
 		scope: z.enum([
-			"always",
 			"docs-only",
 			"trivial",
 			"full"
@@ -7288,7 +7610,7 @@ var verification_proof_exports = /* @__PURE__ */ __exportAll({
 function readPrVerifyProof(filePath) {
 	return readProofFromPath(validatePrVerifyProof, filePath);
 }
-const verifyProofPassed = (proof) => proof.outcome === "passed" || proof.outcome === void 0 && proof.schemaVersion === 1;
+const verifyProofPassed = (proof) => proof.outcome === "passed";
 const prVerifyProofHeadShas = (proof, creditedHeadSha = proof?.headSha) => {
 	if (!proof || !verifyProofPassed(proof)) return {
 		docsOnlyVerifiedHeadShas: [],
@@ -7317,7 +7639,7 @@ const verifyProofHeadMatches = ({ headSha, proof }) => Boolean(proof && evidence
 	recorded: { headSha: proof.headSha },
 	rule: "patch-id-or-head-sha"
 }));
-const verifyProofIdentityMatches = ({ currentIdentity, proof }) => Boolean(proof && verifyProofPassed(proof) && proof.schemaVersion >= 3 && evidenceFresh({
+const verifyProofIdentityMatches = ({ currentIdentity, proof }) => Boolean(proof && verifyProofPassed(proof) && evidenceFresh({
 	candidate: { patchId: currentIdentity?.patchId },
 	recorded: { patchId: proof.patchId },
 	rule: "patch-id"
@@ -7336,7 +7658,6 @@ const verifyProofIdentityMatches = ({ currentIdentity, proof }) => Boolean(proof
 */
 const trustedImpactStamp = ({ candidate, proof }) => {
 	if (!proof || !verifyProofPassed(proof)) return;
-	if (proof.schemaVersion < 4) return;
 	const headBound = sameHeadSha(candidate.headSha, proof.headSha);
 	const patchBound = evidenceFresh({
 		candidate: { patchId: candidate.patchId },
@@ -7348,13 +7669,13 @@ const trustedImpactStamp = ({ candidate, proof }) => {
 /**
 * #833: the recorded catch-up recognition, consumed ONLY when it is
 * identity-bound to the current candidate under exactly the rules
-* `trustedImpactStamp` applies — the proof passed, is v4+, and its recorded
+* `trustedImpactStamp` applies — the proof passed, and its recorded
 * headSha AND patchId both name this candidate. The recognition withdraws
 * review and preview demands, so it earns the same strict double binding and
 * the same fail-closed answer (`undefined`) on every other state.
 */
 const trustedCatchUpRecognition = ({ candidate, proof }) => {
-	if (!proof || !verifyProofPassed(proof) || proof.schemaVersion < 4) return;
+	if (!proof || !verifyProofPassed(proof)) return;
 	const headBound = sameHeadSha(candidate.headSha, proof.headSha);
 	const patchBound = evidenceFresh({
 		candidate: { patchId: candidate.patchId },
@@ -7693,13 +8014,12 @@ const assertCleanInstallResolution = (repoRoot, dependencies = {}) => {
 };
 //#endregion
 //#region src/pr-verify.ts
-const PR_VERIFY_SCHEMA_VERSION = 4;
 const DEFAULT_PR_VERIFY_PROOF_PATH = ".factory-memory/pr-verify.json";
 const PR_VERIFY_PROOF_DESCRIPTOR$1 = {
 	defaultPath: DEFAULT_PR_VERIFY_PROOF_PATH,
 	label: "pr:verify proof",
 	parse: validatePrVerifyProof,
-	schemaVersion: PR_VERIFY_SCHEMA_VERSION
+	schemaVersion: 4
 };
 const VERIFY_SCOPE_RANK = {
 	"docs-only": 0,
@@ -7786,7 +8106,7 @@ function buildPrVerifyProof({ authoringSession, base, baselineFullProofs, catchU
 		profilePath,
 		projectKey,
 		repository,
-		schemaVersion: PR_VERIFY_SCHEMA_VERSION,
+		schemaVersion: 4,
 		startedAt: startedAt.toISOString(),
 		verificationCommands: commands
 	};
@@ -7845,7 +8165,10 @@ function runPrVerify(args, dependencies = {}) {
 		profilePath: args.profilePath
 	});
 	const files = git.changedFiles(cwd, args.base);
-	const relativeProfile = path.relative(cwd, profilePath).split(path.sep).join("/");
+	const relativeProfile = repositoryRelativeProfilePath({
+		cwd,
+		profilePath
+	});
 	const { headSha, mergeBaseSha: proofMergeBaseSha, patchId } = resolveCandidateIdentity({
 		base: args.base,
 		cwd,
@@ -7863,7 +8186,7 @@ function runPrVerify(args, dependencies = {}) {
 			changedFiles: files,
 			profile,
 			profilePath: relativeProfile,
-			readLockfile: (side) => readLockfileAtRef(cwd, side === "base" ? proofMergeBaseSha : headSha, path.resolve(cwd, LOCKFILE_PATH))
+			readLockfile: (side) => readLockfileAtRef(cwd, side === "base" ? proofMergeBaseSha : headSha, LOCKFILE_PATH)
 		});
 	} catch (error) {
 		if (error instanceof ImpactStampConfigError) throw error;
@@ -10415,35 +10738,38 @@ const writeGithubOutputs$1 = (outputPath, decision) => {
 	appendFileSync(outputPath, `${lines.join("\n")}\n`, "utf-8");
 };
 /**
-* Classify candidate impact from one exact base/head identity. The delta is
-* the merge-base-to-head diff, and the lockfile sides are read at exactly the
-* merge base and head — the same inputs `pr:verify` gives the impact stamp
-* for the same candidate commits. The result may withdraw hosted routing
-* work only; every doubt path returns a refused decision whose known targets
-* remain demanded.
+* The candidate impact classifier: one exact base/head identity in, one impact
+* stamp out. The delta is the merge-base-to-head diff, and the lockfile sides
+* are read at exactly the merge base and head — the same inputs `pr:verify`
+* gives the impact stamp for the same candidate commits.
+*
+* It is the authority on which required checks a candidate owes (#963), so
+* every surface that states that demand calls this rather than matching paths
+* itself. Every doubt path refuses with its reason; a refusal never withdraws
+* anything.
 */
-const runCandidateImpact = (args) => {
+const classifyCandidateImpact = (args) => {
 	const cwd = path.resolve(args.cwd ?? process.cwd());
 	let profile;
-	let profilePath;
 	let relativeProfile;
-	let decision;
 	try {
-		const { path: loadedPath, profile: loadedProfile } = loadProjectProfile({
+		const { path: profilePath, profile: loadedProfile } = loadProjectProfile({
 			cwd,
 			profilePath: args.profilePath
 		});
 		profile = loadedProfile;
-		profilePath = loadedPath;
-		relativeProfile = path.relative(cwd, profilePath).split(path.sep).join("/");
+		relativeProfile = repositoryRelativeProfilePath({
+			cwd,
+			profilePath
+		});
 		const base = assertCommitIdentity$1(args.base, "base");
 		const head = assertCommitIdentity$1(args.head, "head");
 		assertReachableCommit$1(cwd, base, "base");
 		assertReachableCommit$1(cwd, head, "head");
 		const checkedOutHead = runCapture("git", ["rev-parse", "HEAD"], cwd).stdout.trim().toLowerCase();
 		if (checkedOutHead !== head) throw new Error(`head commit ${head} is not the checked-out HEAD ${checkedOutHead}; refusing to mix commit identities with declarations from another tree`);
-		const relativeProfilePath = path.relative(cwd, profilePath);
-		const committedProfile = showFileAtRef(cwd, head, profilePath);
+		const relativeProfilePath = relativeProfile;
+		const committedProfile = showFileAtRef(cwd, head, relativeProfile);
 		if (committedProfile === void 0) throw new Error(`profile ${relativeProfilePath} is not readable at head commit ${head}; refusing to classify from declarations the head does not carry`);
 		if (canonicalJson(committedProfile) === void 0 || canonicalJson(committedProfile) !== canonicalJson(readFileSync(profilePath, "utf-8"))) throw new Error(`profile ${relativeProfilePath} on disk differs from head commit ${head}; refusing to classify from declarations the head does not carry`);
 		const mergeBase = runCapture("git", [
@@ -10462,12 +10788,43 @@ const runCandidateImpact = (args) => {
 		const stamp = computeImpactStamp({
 			changedFiles,
 			profile,
-			profilePath: path.relative(cwd, profilePath),
-			readLockfile: (side) => showFileAtRef(cwd, side === "base" ? mergeBase : head, path.join(cwd, LOCKFILE_PATH))
+			profilePath: relativeProfile,
+			readLockfile: (side) => showFileAtRef(cwd, side === "base" ? mergeBase : head, LOCKFILE_PATH)
 		});
-		const core = {
+		return {
 			baseSha: base,
+			changedFiles,
 			headSha: head,
+			kind: "classified",
+			mergeBaseSha: mergeBase,
+			profile,
+			relativeProfilePath: relativeProfile,
+			stamp
+		};
+	} catch (error) {
+		return {
+			kind: "refused",
+			...profile ? { profile } : {},
+			reason: `candidate impact classification refused: ${error instanceof Error ? error.message : String(error)}`,
+			...relativeProfile ? { relativeProfilePath: relativeProfile } : {}
+		};
+	}
+};
+/**
+* Classify candidate impact from one exact base/head identity, as the routing
+* decision the hosted plane consumes. The result may withdraw hosted routing
+* work only; every doubt path returns a refused decision whose known targets
+* remain demanded.
+*/
+const runCandidateImpact = (args) => {
+	const cwd = path.resolve(args.cwd ?? process.cwd());
+	const classification = classifyCandidateImpact(args);
+	let decision;
+	if (classification.kind === "classified") {
+		const { baseSha, changedFiles, headSha, mergeBaseSha: mergeBase, stamp } = classification;
+		const core = {
+			baseSha,
+			headSha,
 			inertPaths: stamp.inertPaths,
 			mergeBaseSha: mergeBase,
 			schemaVersion: CANDIDATE_IMPACT_DECISION_SCHEMA_VERSION,
@@ -10500,16 +10857,15 @@ const runCandidateImpact = (args) => {
 				state: "demanded"
 			}))
 		};
-	} catch (error) {
-		decision = refusal$1({
-			base: args.base,
-			head: args.head,
-			profile,
-			reason: `candidate impact classification refused: ${error instanceof Error ? error.message : String(error)}`
-		});
-	}
+	} else decision = refusal$1({
+		base: args.base,
+		head: args.head,
+		...classification.profile ? { profile: classification.profile } : {},
+		reason: classification.reason
+	});
 	if (args.emitRunContext) {
 		const fullSuiteBaseRef = emptyTreeHash(cwd);
+		const relativeProfile = classification.relativeProfilePath;
 		const { env } = createVerificationRunContext({
 			baseRef: decision.mergeBaseSha ?? fullSuiteBaseRef,
 			changedFiles: decision.basis.changedFiles,
@@ -13067,6 +13423,60 @@ const reviewProofCheck = ({ candidate, candidateError, proof, reviewModes }) =>
 		status: accepted ? "ok" : "warning"
 	};
 };
+/**
+* Resolve the demand this candidate actually owes.
+*
+* The `pr:verify` stamp wins when one binds this candidate: readiness admits
+* on that stamp and nothing else, so the checklist must not tell a different
+* story about an already-verified candidate. Before `pr:verify` has stamped
+* anything there is no trusted stamp to read, and that is exactly the state
+* #963 reports from — so preflight runs the classifier itself. Preflight
+* never gates, so a stamp it computed can only inform; it never becomes
+* evidence, and readiness still requires the verified one.
+*/
+const resolveRequiredCheckDemand = ({ candidate, cwd, profile, profilePath, verifyProof }) => {
+	const stamped = trustedImpactStamp({
+		candidate: {
+			headSha: candidate.headSha,
+			patchId: candidate.patchId
+		},
+		proof: verifyProof
+	});
+	if (stamped) return {
+		basis: `the pr:verify proof's impact stamp for this candidate — ${impactStampSummaryLines(stamped)[0]}`,
+		kind: "resolved",
+		stamp: stamped
+	};
+	if ((profile.impact?.targets ?? []).length === 0) return {
+		basis: "the profile declares no impact targets, so every required check is unconditional",
+		kind: "resolved"
+	};
+	const classification = classifyCandidateImpact({
+		base: candidate.mergeBaseSha,
+		cwd,
+		head: candidate.headSha,
+		profilePath
+	});
+	if (classification.kind === "refused") return {
+		kind: "unresolved",
+		reason: classification.reason
+	};
+	return {
+		basis: `candidate:impact over ${candidate.mergeBaseSha}..${candidate.headSha} — ${impactStampSummaryLines(classification.stamp)[0]}`,
+		kind: "resolved",
+		stamp: classification.stamp
+	};
+};
+/** The row that names the authority on what this candidate owes (#963). */
+const requiredCheckDemandCheck = (resolution) => resolution.kind === "resolved" ? {
+	message: `Required-check demand is resolved against this candidate by ${resolution.basis}. Rows below state their own resolution; a check reported as not demanded is not owed on this candidate.`,
+	name: "admission:required-check-demand",
+	status: "ok"
+} : {
+	message: `Required-check demand is NOT resolvable for this candidate (${resolution.reason}), so every declared required check below is shown in force (fail closed). Resolve the refusal, or read candidate:impact directly, before treating the rows below as the demand set.`,
+	name: "admission:required-check-demand",
+	status: "warning"
+};
 const requiredCheckMessage = (outcome) => {
 	if (outcome.status === "out-of-scope") return `Not demanded for this candidate: ${outcome.scopeReason}.`;
 	if (outcome.status === "satisfied") return `Satisfied by a ${outcome.checkType}-type evidence envelope${outcome.matchedPath ? ` (${outcome.matchedPath})` : ""}.`;
@@ -13078,7 +13488,7 @@ const requiredCheckMessage = (outcome) => {
 * readiness's own `evaluateRequiredChecks`, so scoping, freshness and
 * independence stay exactly one implementation.
 */
-const requiredCheckChecks = ({ candidate, candidateError, cwd, profile, verifyProof }) => {
+const requiredCheckChecks = ({ candidate, candidateError, cwd, profile, profilePath, verifyProof }) => {
 	const requiredChecks = resolveProfileRequiredChecks(profile);
 	if (requiredChecks.length === 0) return [{
 		message: "Profile declares no requiredChecks; no external evidence envelope (including a preview-deploy proof) is demanded.",
@@ -13090,13 +13500,14 @@ const requiredCheckChecks = ({ candidate, candidateError, cwd, profile, verifyPr
 		name: "admission:required-checks",
 		status: "warning"
 	}];
-	const impactStamp = trustedImpactStamp({
-		candidate: {
-			headSha: candidate.headSha,
-			patchId: candidate.patchId
-		},
-		proof: verifyProof
+	const demand = resolveRequiredCheckDemand({
+		candidate,
+		cwd,
+		profile,
+		profilePath,
+		verifyProof
 	});
+	const impactStamp = demand.kind === "resolved" ? demand.stamp : void 0;
 	const { outcomes } = evaluateRequiredChecks({
 		authoringSessionIds: resolveAuthoringSessionIds({ recorded: verifyProof?.authoringSession }),
 		candidate: {
@@ -13111,11 +13522,11 @@ const requiredCheckChecks = ({ candidate, candidateError, cwd, profile, verifyPr
 			...impactStamp ? { impactStamp } : {}
 		}
 	});
-	return outcomes.map((outcome) => ({
+	return [requiredCheckDemandCheck(demand), ...outcomes.map((outcome) => ({
 		message: requiredCheckMessage(outcome),
 		name: `admission:required-check:${outcome.name}`,
 		status: outcome.status === "unmet" ? "warning" : "ok"
-	}));
+	}))];
 };
 /**
 * The full admission checklist for the current repository and candidate, in the
@@ -13124,7 +13535,7 @@ const requiredCheckChecks = ({ candidate, candidateError, cwd, profile, verifyPr
 * requirement is reported by the doctor `github-app` check, which states the
 * consequence of its absence.
 */
-const admissionPreflightChecks = ({ base = "origin/main", cwd, env = process.env, hqIngestCredentials, profile, reviewProofPath = DEFAULT_PR_REVIEW_PROOF_PATH, verifyProofPath = DEFAULT_PR_VERIFY_PROOF_PATH }) => {
+const admissionPreflightChecks = ({ base = "origin/main", cwd, env = process.env, hqIngestCredentials, profile, profilePath, reviewProofPath = DEFAULT_PR_REVIEW_PROOF_PATH, verifyProofPath = DEFAULT_PR_VERIFY_PROOF_PATH }) => {
 	const resolvedVerifyProofPath = path.resolve(cwd, verifyProofPath);
 	const preread = tryReadProof(readPrVerifyProof, resolvedVerifyProofPath);
 	const resolved = resolveCandidate({
@@ -13154,6 +13565,7 @@ const admissionPreflightChecks = ({ base = "origin/main", cwd, env = process.env
 			candidateError,
 			cwd,
 			profile,
+			profilePath,
 			verifyProof: preread.proof
 		}),
 		hqIngestCredentialCheck({
@@ -13239,6 +13651,7 @@ async function doctorProjectProfile(input = {}) {
 	}, input.hqSpoolDependencies);
 	const checks = [
 		...buildProfileChecks(profile, cwd, {
+			env,
 			userConfig: userConfig.loaded?.config,
 			userConfigCheck: userConfig.check
 		}),
@@ -13317,17 +13730,24 @@ function buildProfileChecks(profile, cwd, userConfigInput) {
 		},
 		reviewLadderCheck(),
 		userConfigInput.userConfigCheck,
-		githubAppCheck(userConfigInput.userConfig),
+		githubAppCheck(userConfigInput.userConfig, userConfigInput.env),
 		gitRemoteCheck(profile, cwd)
 	];
 }
-function githubAppCheck(userConfig) {
+function githubAppCheck(userConfig, env) {
 	const app = userConfig?.githubApp;
-	if (!app) return {
-		message: "Patronage Factory GitHub App credentials are not configured; gate publishing will use user-token commit statuses with Details links. Proof bindings cannot publish, so hosted required checks cannot be satisfied by local proof and must go green by their own means.",
-		name: "github-app",
-		status: "warning"
-	};
+	if (!app) {
+		if (env.CURSOR_AGENT_SOCKET !== void 0 && env.CURSOR_AGENT_SOCKET.length > 0) return {
+			message: "Patronage Factory GitHub App PEM is not configured; this Cursor-managed VM publishes patronage-factory/pr-ready through the Factory App broker (Cursor OIDC, audience Factory). Missing exchange fails closed.",
+			name: "github-app",
+			status: "warning"
+		};
+		return {
+			message: "Patronage Factory GitHub App credentials are not configured; gate publishing will use user-token commit statuses with Details links. Proof bindings cannot publish, so hosted required checks cannot be satisfied by local proof and must go green by their own means.",
+			name: "github-app",
+			status: "warning"
+		};
+	}
 	if (!existsSync(app.privateKeyPath)) return {
 		message: `Patronage Factory GitHub App id ${app.appId} is configured, but private key ${app.privateKeyPath} was not found.`,
 		name: "github-app",
@@ -13391,7 +13811,7 @@ function repositoryUrlMatches(origin, profile) {
 //#endregion
 //#region src/commands/doctor.ts
 function createDoctorCommand(output) {
-	return markCwdOptionDefault(new Command("doctor").description("Validate a project profile without mutating GitHub or local files").option("--base <ref>", "base branch or ref for --preflight", "origin/main").option("--cwd <path>", "working directory to validate", collectCwdOption).option("--json", "print the doctor report as JSON").option("--preflight", "also list the pre-checkable admission requirements for the current candidate (read-only; never blocks); findings-file shape and wave membership have no read-only pre-check").option("--profile <path>", "path to the project profile JSON file").action(async (options) => {
+	return markCwdOptionDefault(new Command("doctor").description("Validate a project profile without mutating GitHub or local files").option("--base <ref>", "base branch or ref for --preflight", "origin/main").option("--cwd <path>", "working directory to validate", collectCwdOption).option("--json", "print the doctor report as JSON").option("--preflight", "also list the pre-checkable admission requirements for the current candidate (read-only; never blocks); each required check states whether this candidate is demanded to satisfy it, resolved by candidate:impact; findings-file shape and wave membership have no read-only pre-check").option("--profile <path>", "path to the project profile JSON file").action(async (options) => {
 		const report = await doctorProjectProfile({
 			base: options.base,
 			cwd: resolveCwdOption(options.cwd),
@@ -16187,10 +16607,10 @@ function defaultPrReadyGit() {
 			], cwd);
 		},
 		mergeBaseSha,
-		objectIdAtRef: (cwd, ref, absolutePath) => {
-			const relativePath = path.relative(cwd, absolutePath);
+		objectIdAtRef: (cwd, ref, repositoryRelativePath) => {
+			assertRepositoryRelativePath(repositoryRelativePath, "objectIdAtRef");
 			try {
-				return runCapture("git", ["rev-parse", `${ref}:${relativePath}`], cwd).stdout.trim();
+				return runCapture("git", ["rev-parse", `${ref}:${repositoryRelativePath}`], cwd).stdout.trim();
 			} catch {}
 		},
 		resolveCommitSha: (cwd, ref) => {
@@ -16425,9 +16845,9 @@ const resolveExternalEvidenceInputs = ({ args, cwd, recordedAuthoringSession, re
 		externalRequiredChecks: requiredChecks
 	};
 };
-function policyProfileAtCommittedHead({ cwd, git, headSha, profilePath }) {
-	const content = git.showFileAtRef(cwd, headSha, profilePath);
-	const blobSha = git.objectIdAtRef(cwd, headSha, profilePath);
+function policyProfileAtCommittedHead({ cwd, git, headSha, repositoryRelativeProfile }) {
+	const content = git.showFileAtRef(cwd, headSha, repositoryRelativeProfile);
+	const blobSha = git.objectIdAtRef(cwd, headSha, repositoryRelativeProfile);
 	const committedProfile = content ? tryParseProfileContent(content) : void 0;
 	if (!(committedProfile && blobSha && /^[0-9a-f]{40}$/u.test(blobSha))) throw new Error("Could not read, validate, and identify readiness policy from the committed PR head; fetch the head and re-run pr:ready.");
 	return {
@@ -16435,11 +16855,6 @@ function policyProfileAtCommittedHead({ cwd, git, headSha, profilePath }) {
 		profile: committedProfile
 	};
 }
-function checkoutRelativeProfilePath(cwd, profilePath) {
-	const relativePath = path.relative(cwd, profilePath);
-	if (relativePath.length === 0 || relativePath === ".." || relativePath.startsWith(`..${path.sep}`) || path.isAbsolute(relativePath)) throw new Error("The readiness profile must be inside the trusted checkout.");
-	return relativePath.split(path.sep).join("/");
-}
 function readinessProfilePath(cwd, requestedPath) {
 	return path.resolve(cwd, requestedPath ?? "software-factory.profile.json");
 }
@@ -16499,15 +16914,18 @@ async function runPrReady(args, dependencies = {}) {
 		hudMergeBaseSha = resolvedMergeBaseSha;
 		hudPatchId = patchId;
 		const files = git.changedFiles(cwd, authoritativeBaseSha, pr.headRefOid);
+		const committedProfilePath = repositoryContainedProfilePath({
+			cwd,
+			profilePath
+		});
 		const committedPolicy = policyProfileAtCommittedHead({
 			cwd,
 			git,
 			headSha: pr.headRefOid,
-			profilePath
+			repositoryRelativeProfile: committedProfilePath
 		});
 		const policyProfile = committedPolicy.profile;
 		if (repositorySlug(policyProfile.repository) !== checkoutRepositorySlug) throw new Error(`Committed readiness profile repository ${repositorySlug(policyProfile.repository)} does not match trusted checkout repository ${checkoutRepositorySlug}.`);
-		const committedProfilePath = checkoutRelativeProfilePath(cwd, profilePath);
 		const policy = resolveReviewDemand({
 			authority: dependencies.basePolicy ?? defaultBaseReviewPolicyAuthority(),
 			callerBaseRef: pr.baseRefName,
@@ -16740,7 +17158,12 @@ async function runPrReady(args, dependencies = {}) {
 				repo: repository.name,
 				sha: presentedHeadSha
 			};
-			if (!await (dependencies.publishFinalCheckRun ? dependencies.publishFinalCheckRun(failureCheckInput) : ensureFactoryCheckRunPublished(failureCheckInput, { onDiagnostic: (diagnostic) => process.stderr.write(diagnostic) }))) console.warn(`pr:ready could not publish the failing ${FACTORY_CHECK_NAMES["pr-ready"]} check run for ${presentedHeadSha}; the required check is absent rather than red.`);
+			try {
+				if (!await (dependencies.publishFinalCheckRun ? dependencies.publishFinalCheckRun(failureCheckInput) : ensureFactoryCheckRunPublished(failureCheckInput, { onDiagnostic: (diagnostic) => process.stderr.write(diagnostic) }))) console.warn(`pr:ready could not publish the failing ${FACTORY_CHECK_NAMES["pr-ready"]} check run for ${presentedHeadSha}; the required check is absent rather than red.`);
+			} catch (publishError) {
+				const publishMessage = publishError instanceof Error ? publishError.message : String(publishError);
+				console.warn(`pr:ready could not publish the failing ${FACTORY_CHECK_NAMES["pr-ready"]} check run for ${presentedHeadSha}; the required check is absent rather than red. ${publishMessage}`);
+			}
 			await presentHud();
 		}
 		throw error;
@@ -17149,7 +17572,7 @@ const readCodingStandardsAtHead = ({ cwd, git, headSha }) => {
 	} catch {
 		return;
 	}
-	return (git?.showFileAtRef ?? showFileAtRef)(root, headSha, path.join(root, CODING_STANDARDS_FILE));
+	return (git?.showFileAtRef ?? showFileAtRef)(root, headSha, CODING_STANDARDS_FILE);
 };
 const codingStandardsSegment = ({ contents, headSha }) => {
 	const text = contents?.replace(/\n+$/u, "");
@@ -17474,7 +17897,10 @@ const reviewPolicyIdentity = ({ args, changedFiles: files, cwd, dependencies, gi
 	changedFiles: files,
 	cwd,
 	lookupPullRequest: dependencies.lookupPullRequest ?? lookupCandidatePullRequest,
-	profilePath: path.relative(cwd, profilePath).split(path.sep).join("/"),
+	profilePath: repositoryRelativeProfilePath({
+		cwd,
+		profilePath
+	}),
 	readCheckoutRepository: git.checkoutRepository ?? checkoutRepository
 });
 /**
@@ -17839,11 +18265,7 @@ const defaultFollowUpRunner = (factoryCliInvocation) => (followUp, cwd) => {
 	const [command, ...args] = resolveFollowUpArgv(followUp, factoryCliInvocation);
 	runCapture(command, args, cwd);
 };
-const defaultPrPublishCliInvocation = () => {
-	const moduleExtension = path.extname(import.meta.filename);
-	return defaultFactoryCliInvocation(path.join(import.meta.dirname, `index${moduleExtension}`));
-};
-const prPublishCliInvocation = (explicit) => explicit ?? defaultPrPublishCliInvocation();
+const prPublishCliInvocation = (explicit) => explicit ?? defaultFactoryCliInvocation(factoryCliEntry());
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 /**
 * GitHub creates a pull request against a branch name, while the rest of the
@@ -18704,8 +19126,11 @@ const runProductionImpact = (args) => {
 		const stamp = computeImpactStamp({
 			changedFiles,
 			profile,
-			profilePath: path.relative(cwd, profilePath),
-			readLockfile: (side) => showFileAtRef(cwd, side === "base" ? before : after, path.join(cwd, LOCKFILE_PATH))
+			profilePath: repositoryRelativeProfilePath({
+				cwd,
+				profilePath
+			}),
+			readLockfile: (side) => showFileAtRef(cwd, side === "base" ? before : after, LOCKFILE_PATH)
 		});
 		const core = {
 			afterSha: after,
@@ -19496,7 +19921,7 @@ function formatScratchFileCheckSummary(check) {
 //#endregion
 //#region src/index.ts
 function createProgram(options = {}) {
-	const factoryCliInvocation = options.factoryCliInvocation ? FactoryCliInvocationSchema.parse(options.factoryCliInvocation) : defaultFactoryCliInvocation(import.meta.filename);
+	const factoryCliInvocation = options.factoryCliInvocation ? FactoryCliInvocationSchema.parse(options.factoryCliInvocation) : defaultFactoryCliInvocation(factoryCliEntry());
 	const output = options.output ?? {
 		stderr: process.stderr,
 		stdout: process.stdout
@@ -19526,24 +19951,18 @@ function createProgram(options = {}) {
 	program.addCommand(createDemandWaiveCommand(output, options.actions?.demandWaive));
 	return program;
 }
-async function run(argv = process.argv) {
+/**
+* Parse `argv` and run the matching command. `cliEntry` is the path of the
+* runnable bin module, which follow-up commands spawn; the bin entry passes its
+* own path. This function never runs itself — `./cli.js` is the only caller
+* that does (#386).
+*/
+async function run(argv = process.argv, cliEntry = factoryCliEntry()) {
 	try {
-		await createProgram({ factoryCliInvocation: defaultFactoryCliInvocation(import.meta.filename) }).parseAsync(argv);
+		await createProgram({ factoryCliInvocation: defaultFactoryCliInvocation(cliEntry) }).parseAsync(argv);
 	} finally {
 		await awaitPendingHqIngest();
 	}
 }
-function isDirectCliExecution() {
-	const [, entryPath] = process.argv;
-	if (!entryPath) return false;
-	return import.meta.url === pathToFileURL(realpathSync(entryPath)).href;
-}
-if (isDirectCliExecution()) try {
-	await run();
-} catch (error) {
-	if (error instanceof PrPublishFollowUpError) console.error(JSON.stringify(error.result, null, 2));
-	else console.error("\nError:", error instanceof Error ? error.message : String(error));
-	process.exit(1);
-}
 //#endregion
 export { DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, DEFAULT_ROOT_SHARED_GLOBS, DemandWaiveRefusalError, EMPTY_TREE_OBJECT_HASH, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, EpicStructureValidationError, FACTORY_BASE_REF_ENV, FACTORY_CHANGED_FILES_ENV, FACTORY_CHANGED_FILES_FILE_ENV, FactoryCliInvocationSchema, FollowUpActionSchema, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, PrPublishFollowUpError, REVIEW_FOCUS_SECTION, WorkerCheckoutGuardError, appendReviewLadderStageTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertFactoryPrStatusIdentity, assertWorkerCheckoutAllowed, authorizeDemandWaiver, batteryScopeSummaryLines, blockingLadderFindings, boundary_manifest_exports as boundaryManifest, boundary_review_proof_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildReviewGateNotRequiredTraceEvent, buildReviewLadderStageTraceEvent, comment_provenance_exports as commentProvenance, createGitHubCheckRunMergeFreezeStore, createLocalJsonlTraceSink, createProgram, createVerificationRunContext, doctorProjectProfile, epicStructureEventId, evaluateReviewLadder, evidenceEnvelopeFilename, findingKey, followUpFromArgv, impactStampScopeDecision, inferFixedInThreadDispositions, isProductionHqUrl, loadProjectProfile, normalizeIssueComments, openLadderFindings, planFactoryPrStatusHud, planPreviewLifecycle, planPublishFollowUp, planVerificationBattery, readiness_evaluation_exports as prReadinessEvaluation, external_evidence_exports as prReadinessExternalEvidence, pr_body_renderer_exports as prReadinessPrBodyRenderer, proof_identity_exports as prReadinessProofIdentity, review_proof_exports as prReadinessReviewProof, status_check_rollup_exports as prReadinessStatusChecks, verification_proof_exports as prReadinessVerificationProof, presentFactoryPrStatusHud, previewLifecycleTargets, publishEpicStructure, readDemandWaivers, readFactoryPrStatusSources, readPrReadyProof, readPrReviewProof, refreshFactoryPrStatusHud, refreshFactoryPrStatusHudSafely, renderFactoryPrStatusHud, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, selectWaiversForCandidate, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, validatePreviewLifecyclePlan, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_exports as worktreeScratchFiles };