@patronage/software-factory 1.0.0-alpha.36 → 1.0.0-alpha.38

package/dist/index.d.ts

@@ -1,9 +1,112 @@
 import { Command } from "commander";
-import { z } from "zod";
 import { existsSync, readFileSync, rmSync } from "node:fs";
+import { z } from "zod";
 import { PreviewProofRegistration } from "@patronage/factory-ci";
 import { JsonValue, Questions, SystemOneRequest, choice, noul, score } from "@typesafe-ai/sdk";
 
+//#region src/factory-app-broker-client.d.ts
+/**
+ * The opt-in broker permission set (#1360): `pull_requests: write`,
+ * `issues: read`, and `contents: read` on the requesting repository. The
+ * read-only contents grant is there because GitHub's pull request create
+ * reads the head and base refs (#1327, #1375). The CLI asks for the scope by
+ * name and the broker decides its permissions. A request without a scope is
+ * the `checks: write` mint, unchanged.
+ */
+declare const FACTORY_APP_BROKER_ADMISSION_SCOPE = "admission";
+//#endregion
+//#region src/user-config.d.ts
+declare const githubAppConfigSchema: z.ZodObject<{
+  appId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+  installationId: z.ZodOptional<z.ZodNumber>;
+  privateKeyPath: z.ZodString;
+}, z.core.$strip>;
+type GithubAppConfig = z.infer<typeof githubAppConfigSchema>;
+declare const factoryUserConfigSchema: z.ZodObject<{
+  githubApp: z.ZodOptional<z.ZodObject<{
+    appId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+    installationId: z.ZodOptional<z.ZodNumber>;
+    privateKeyPath: z.ZodString;
+  }, z.core.$strip>>;
+  hqAllowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  hqIngestCredentials: z.ZodOptional<z.ZodObject<{
+    clientIdRef: z.ZodString;
+    clientSecretRef: z.ZodString;
+  }, z.core.$strip>>;
+  schemaVersion: z.ZodLiteral<2>;
+}, z.core.$strip>;
+type FactoryUserConfig = z.infer<typeof factoryUserConfigSchema>;
+interface LoadUserConfigResult {
+  path: string;
+  config: FactoryUserConfig;
+  ignoredKeys?: string[];
+}
+//#endregion
+//#region src/github-app-access.d.ts
+interface FactoryAppAccessDependencies {
+  env?: NodeJS.ProcessEnv;
+  existsSync?: (path: string) => boolean;
+  exchangeBroker?: (input: {
+    fetch?: typeof fetch;
+    oidc: string;
+    owner: string;
+    repo: string;
+    scope?: typeof FACTORY_APP_BROKER_ADMISSION_SCOPE;
+    timeoutMs?: number;
+    url?: string;
+  }) => Promise<string>;
+  fetch?: typeof fetch;
+  githubApp?: GithubAppConfig;
+  mintCursorOidc?: (input: {
+    audience?: string;
+    signal?: AbortSignal;
+    socketPath?: string;
+    timeoutMs?: number;
+  }) => Promise<string>;
+  now?: () => number;
+  /**
+   * Cancels the Cursor OIDC mint (#1322). Fetch-based calls are cancelled
+   * through the `fetch` the caller passes, which joins its own signal.
+   */
+  signal?: AbortSignal;
+  timeoutMs?: number;
+  token?: string;
+  transportAttempts?: number;
+}
+//#endregion
+//#region src/admission-credential.d.ts
+/**
+ * The GitHub calls a Cursor VM's own `gh` credential cannot make (#1327).
+ * Cursor mints the VM token without `pull_requests: write` or `issues`, so on
+ * a Cursor managed runtime these, and only these, run on the broker's
+ * `admission` token (#1360): `pull_requests: write`, `issues: read`, and
+ * `contents: read`, which creating a pull request needs because GitHub reads
+ * the head and base refs (#1375). Push,
+ * marking ready, arming auto-merge, check runs, and every other call keep
+ * their own credential.
+ */
+type AdmissionOperation = "create-pull-request" | "edit-pull-request-body" | "read-issue" | "read-pull-request-for-status-hud";
+/** The one repository the admission token is minted for. */
+interface AdmissionRepository {
+  owner: string;
+  repo: string;
+}
+interface AdmissionCredential {
+  /**
+   * The environment overlay for ONE `gh` subprocess that performs
+   * `operation`. `undefined` off a Cursor managed runtime: nothing is minted
+   * and the subprocess environment is untouched. On one, `{ GH_TOKEN }` with
+   * the admission token. Throws {@link AdmissionCredentialError} when the mint
+   * fails.
+   */
+  ghEnv: (operation: AdmissionOperation, repository: AdmissionRepository) => Promise<Readonly<Record<string, string>> | undefined>;
+  /**
+   * The same token for one direct REST request, or `undefined` off a Cursor
+   * managed runtime.
+   */
+  token: (operation: AdmissionOperation, repository: AdmissionRepository) => Promise<string | undefined>;
+}
+//#endregion
 //#region src/review-rungs.d.ts
 declare const EVIDENCE_REVIEW_RUNGS: readonly ["independent-model", "oracle", "human"];
 type EvidenceReviewRung = (typeof EVIDENCE_REVIEW_RUNGS)[number];
@@ -332,6 +435,32 @@ declare const authorizeDemandWaiver: ({
   session: string | undefined;
 }) => AuthorizeDemandWaiverResult;
 //#endregion
+//#region src/hq-credentials.d.ts
+/**
+ * Why a reference did not resolve. Each value names a different remedy, and
+ * none of them can be inferred from a value-or-nothing result:
+ *
+ * - `resolver-missing` — no secret-manager binary on PATH.
+ * - `resolver-blocked` — a binary exists but this session may not execute it
+ *   (a sandbox denying exec). The command belongs outside the sandbox.
+ * - `resolver-timeout` — the probe expired: a desktop agent waiting on an
+ *   approval nobody can give here.
+ * - `resolver-refused` — the binary ran and produced no value. Its store is
+ *   unreachable from this session (a sandbox with no keychain access) or the
+ *   reference is not readable. These two stay one status on purpose: telling
+ *   them apart would mean reading resolver output.
+ */
+type SecretResolutionFailure = "resolver-blocked" | "resolver-missing" | "resolver-refused" | "resolver-timeout";
+/** A structured resolution outcome. The value travels only when resolved. */
+type SecretResolution = {
+  status: "resolved";
+  value: string;
+} | {
+  status: SecretResolutionFailure;
+};
+/** Resolves a secret reference. Injected so tests stay offline. */
+type SecretReferenceResolver = (reference: string) => SecretResolution;
+//#endregion
 //#region src/hq-ingest-sink.d.ts
 interface HqIngestDependencies {
   /**
@@ -344,6 +473,12 @@ interface HqIngestDependencies {
   fetch?: typeof fetch;
   now?: () => Date;
   randomUUID?: () => string;
+  /**
+   * Resolves one `hqIngestCredentials` reference on an operator machine
+   * (#1313). Injected so tests stay offline; production asks `op-fast`, then
+   * `op`.
+   */
+  resolveSecret?: SecretReferenceResolver;
   /**
    * Ceiling for persisting a failure after the transport leg (default
    * `HQ_JOURNAL_FLUSH_BUDGET_MS`). Injectable for the same reason as
@@ -458,6 +593,12 @@ interface HqSpoolWorkCount {
   oldestQueuedAt?: string;
   /** Spooled events waiting in the locations below. */
   pending: number;
+  /**
+   * How many pending events carry each recorded spool reason (#1317). Present
+   * only when the caller asked for `reasons`. An event whose file could not be
+   * read or parsed within budget is counted in `pending` and absent here.
+   */
+  reasons?: Record<string, number>;
   /** Locations that exist and hold spooled work. */
   spools: string[];
   /**
@@ -477,7 +618,9 @@ interface HqSpoolWorkCount {
  * same locations `flushHqSpool` drains are inspected here, read-only: no
  * directory is created, nothing is secured, and nothing is delivered.
  */
-declare function countHqSpoolWork(input: Pick<HqSpoolFlushInput, "explicitDirectories" | "repository">, dependencies?: {
+declare function countHqSpoolWork(input: Pick<HqSpoolFlushInput, "explicitDirectories" | "repository"> & {
+  /** Also read each pending event's recorded reason (#1317). */reasons?: boolean;
+}, dependencies?: {
   budgetMs?: number;
   env?: NodeJS.ProcessEnv;
 }): Promise<HqSpoolWorkCount>;
@@ -948,10 +1091,18 @@ declare const blockedReasonSchema: z.ZodObject<{
 type BlockedReason = z.infer<typeof blockedReasonSchema>;
 //#endregion
 //#region src/arm-auto-merge.d.ts
+/**
+ * How GitHub merges the candidate. `pr:ready` chooses `merge` for a
+ * recognized faithful catch-up merge (ADR 0028), because a squash drops the
+ * second parent and the target loses the merged base as an ancestor (#829).
+ * Every other candidate is squashed.
+ */
+type AutoMergeMethod = "merge" | "squash";
 interface ArmAutoMergeInput {
   cwd: string;
   /** The validated PR head this arming is a compare-and-set against. */
   headSha: string;
+  mergeMethod: AutoMergeMethod;
   owner: string;
   pr: number;
   repo: string;
@@ -1242,58 +1393,6 @@ declare const followUpFromArgv: (argv: string[]) => FollowUpAction;
 /** Canonical zod schema for the optional follow-up field on JSON outputs. */
 declare const FollowUpActionSchema: z.ZodType<FollowUpAction>;
 //#endregion
-//#region src/user-config.d.ts
-declare const githubAppConfigSchema: z.ZodObject<{
-  appId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
-  installationId: z.ZodOptional<z.ZodNumber>;
-  privateKeyPath: z.ZodString;
-}, z.core.$strip>;
-type GithubAppConfig = z.infer<typeof githubAppConfigSchema>;
-declare const factoryUserConfigSchema: z.ZodObject<{
-  githubApp: z.ZodOptional<z.ZodObject<{
-    appId: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
-    installationId: z.ZodOptional<z.ZodNumber>;
-    privateKeyPath: z.ZodString;
-  }, z.core.$strip>>;
-  hqAllowedOrigins: z.ZodOptional<z.ZodArray<z.ZodString>>;
-  hqIngestCredentials: z.ZodOptional<z.ZodObject<{
-    clientIdRef: z.ZodString;
-    clientSecretRef: z.ZodString;
-  }, z.core.$strip>>;
-  schemaVersion: z.ZodLiteral<2>;
-}, z.core.$strip>;
-type FactoryUserConfig = z.infer<typeof factoryUserConfigSchema>;
-interface LoadUserConfigResult {
-  path: string;
-  config: FactoryUserConfig;
-  ignoredKeys?: string[];
-}
-//#endregion
-//#region src/github-app-access.d.ts
-interface FactoryAppAccessDependencies {
-  env?: NodeJS.ProcessEnv;
-  existsSync?: (path: string) => boolean;
-  exchangeBroker?: (input: {
-    fetch?: typeof fetch;
-    oidc: string;
-    owner: string;
-    repo: string;
-    timeoutMs?: number;
-    url?: string;
-  }) => Promise<string>;
-  fetch?: typeof fetch;
-  githubApp?: GithubAppConfig;
-  mintCursorOidc?: (input: {
-    audience?: string;
-    socketPath?: string;
-    timeoutMs?: number;
-  }) => Promise<string>;
-  now?: () => number;
-  timeoutMs?: number;
-  token?: string;
-  transportAttempts?: number;
-}
-//#endregion
 //#region src/pr-verify-mode.d.ts
 /**
  * The verification mode `pr:verify` resolved for a run.
@@ -1539,6 +1638,7 @@ type PostCommitStatus = (input: PostCommitStatusInput) => void;
 //#region src/github-check-runs.d.ts
 declare const FACTORY_CHECK_NAMES: {
   readonly "pr-ready": "patronage-factory/pr-ready";
+  readonly "pr-review": "patronage-factory/pr-review";
   readonly "pr-verify": "patronage-factory/pr-verify";
 };
 type FactoryCheckGate = keyof typeof FACTORY_CHECK_NAMES;
@@ -1562,11 +1662,12 @@ interface PublishFactoryCheckInput {
 }
 interface CheckRunDependencies extends FactoryAppAccessDependencies {
   postCommitStatus?: PostCommitStatus;
-  resolveDetailsUrl?: (input: PublishFactoryCheckInput) => Promise<string> | string;
+  resolveDetailsUrl?: (input: PublishFactoryCheckInput, signal?: AbortSignal) => Promise<string> | string;
   /**
    * Bounded retry for the check-run POST. GitHub answers 422 for a head SHA it
    * has not seen yet, which is the normal state when `pr:verify` runs before
-   * the branch is pushed, and is also briefly true right after a push.
+   * the branch is pushed, and is also briefly true right after a push. Only
+   * that answer is retried (`isRetryableCheckRunFailure`).
    */
   retry?: {
     attempts: number;
@@ -1651,6 +1752,15 @@ declare function fetchPrVerifyProofBinding({
   sha: string;
   runJson?: GhJsonRunner;
 }): PrVerifyProofBinding | undefined;
+/**
+ * Where rules 2 and 4 read from: the App id to trust and the `gh api` runner.
+ * Both default to production (the user config's App id else the pinned one,
+ * and `runGhJson`); tests state them.
+ */
+interface ExactHeadRunSource {
+  appId?: () => string;
+  runJson?: GhJsonRunner;
+}
 //#endregion
 //#region src/merge-freeze.d.ts
 declare const MERGE_FREEZE_CHECK_NAME = "patronage-factory/merge-freeze";
@@ -1660,8 +1770,8 @@ declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
   generationId: z.ZodNumber;
   headSha: z.ZodString;
   outcome: z.ZodEnum<{
-    stale: "stale";
     active: "active";
+    stale: "stale";
   }>;
   reason: z.ZodString;
   recordedAt: z.ZodISODateTime;
@@ -1950,9 +2060,9 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
         "not-required": "not-required";
+        stale: "stale";
         blocked: "blocked";
         current: "current";
-        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -1962,9 +2072,9 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       reviewedPatchId: z.ZodOptional<z.ZodString>;
       status: z.ZodEnum<{
         "not-required": "not-required";
+        stale: "stale";
         blocked: "blocked";
         current: "current";
-        stale: "stale";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -2491,6 +2601,12 @@ interface ReadFactoryPrStatusSourcesInput {
    * a completed unsuccessful check run when inventory has no registration.
    */
   readonly previewTargets?: readonly string[];
+  /**
+   * Token for the `/pulls/:n` identity read only. Defaults to `token`. On a
+   * Cursor VM `token` is the broker's checks token, which cannot read pulls,
+   * so this is the broker's admission token (#1327).
+   */
+  readonly pullToken?: string;
   readonly repo: string;
   /** Factory App installation token, normally minted by the presentation job. */
   readonly token: string;
@@ -2547,8 +2663,19 @@ interface RefreshFactoryPrStatusHudInput {
   readonly repo: string;
   readonly token?: string;
 }
+/**
+ * Where a local HUD refresh gets its credentials. Defaults to the process
+ * environment, the user config, the real broker, and `fetch`.
+ */
+interface RefreshFactoryPrStatusHudDependencies {
+  /** The broker's admission token on a Cursor VM, for the pull read (#1327). */
+  readonly admission?: AdmissionCredential;
+  /** The checks-scope broker mint on a Cursor VM, unchanged (#949). */
+  readonly factoryApp?: FactoryAppAccessDependencies;
+  readonly fetch?: typeof fetch;
+}
 /** Plan from the checkout and present the App-owned HUD. */
-declare function refreshFactoryPrStatusHud(input: RefreshFactoryPrStatusHudInput): Promise<UpsertFactoryPrStatusCommentResult>;
+declare function refreshFactoryPrStatusHud(input: RefreshFactoryPrStatusHudInput, dependencies?: RefreshFactoryPrStatusHudDependencies): Promise<UpsertFactoryPrStatusCommentResult>;
 /**
  * Presentation must not fail an admission gate. Used after pr:ready publishes
  * its check so the table is not stuck at first-write.
@@ -2611,11 +2738,13 @@ interface PrReadyProof {
   schemaVersion: 3;
   /**
    * What GitHub actually did when this run armed native auto-merge (#477).
-   * Present exactly when a ready wave authorizes machine merge and arming ran;
-   * read back from the PR rather than inferred from the invocation, because `gh pr merge
-   * --auto` arms, merges, or does nothing with the same exit code and the same
-   * empty output. `not-armed` means the candidate is admitted but nothing will
-   * merge it, and `followUp` carries the re-dispatch.
+   * Present exactly when a ready run called the arming module (#1299): not
+   * for an `autoMerge: false` wave, and not when a notice names why the run
+   * did not arm. Read back from the PR rather than inferred from the
+   * invocation, because `gh pr merge --auto` arms, merges, or does nothing
+   * with the same exit code and the same empty output. `not-armed` means the
+   * candidate is admitted but nothing will merge it, and `followUp` carries
+   * the re-dispatch.
    */
   arming?: {
     detail?: string;
@@ -2687,13 +2816,76 @@ interface PrReadyProof {
    */
   waivedDemands?: WaivedDemand[];
 }
+/** An issue's sub-issue parent, as the membership rule reads it (#1299). */
+interface IssueParent {
+  labels: string[];
+  number: number;
+  state: string;
+}
+/** What `pr:ready` reads about one pull request before it arms (#1299). */
+interface PullRequestArmingFacts {
+  /** GitHub's per-repository "Allow auto-merge" setting. */
+  autoMergeAllowed: boolean;
+  /**
+   * GitHub's closing references for the pull request to issues in its own
+   * repository, with their parents.
+   */
+  closingIssues: {
+    number: number;
+    parent: IssueParent | null;
+  }[];
+  /**
+   * GitHub has more closing references than the one page `pr:ready` reads,
+   * so `closingIssues` is not the whole set.
+   */
+  closingIssuesIncomplete: boolean;
+  labels: string[];
+}
+/**
+ * The GitHub reads behind the reasons not to arm an admitted candidate
+ * (#1299). A read throws when GitHub cannot answer; `pr:ready` then does not
+ * arm, and its notice says which read failed.
+ */
+interface ArmingPolicyReads {
+  /**
+   * One issue's sub-issue parent, or `null` when it has none. An issue read,
+   * so on a Cursor VM the real one runs on the admission token (#1327).
+   */
+  readIssueParent: (input: {
+    issue: number;
+    owner: string;
+    repo: string;
+  }) => IssueParent | null | Promise<IssueParent | null>;
+  /**
+   * The repository's auto-merge setting and this pull request's labels and
+   * closing issues. The closing issues are issue data, which the VM's own
+   * `gh` credential reads back as none rather than refusing, so on a Cursor
+   * VM the real one also runs on the admission token (#1327).
+   */
+  readPullRequest: (input: {
+    owner: string;
+    pr: number;
+    repo: string;
+  }) => PullRequestArmingFacts | Promise<PullRequestArmingFacts>;
+}
 interface PrReadyDependencies {
   /**
-   * Arms GitHub native auto-merge only for a passing boundary wave that
-   * authorizes machine merge (#477). Defaults to the real `gh pr merge --auto`
-   * call plus the read-back that says what actually happened.
+   * The broker's admission token on a Cursor VM (#1327), for issue reads the
+   * VM's own `gh` credential cannot make. Defaults to the process-wide
+   * credential, which mints nothing off a Cursor managed runtime.
+   */
+  admission?: AdmissionCredential;
+  /**
+   * Arms GitHub native auto-merge for an admitted candidate (#477, #1299).
+   * Defaults to the real `gh pr merge --auto` call plus the read-back that
+   * says what actually happened.
    */
   armAutoMerge?: (input: ArmAutoMergeInput) => ArmAutoMergeOutcome;
+  /**
+   * The GitHub reads behind the reasons not to arm (#1299). Defaults to the
+   * real GraphQL reads.
+   */
+  armingPolicy?: ArmingPolicyReads;
   /**
    * Reads the authoritative base review policy (#922): the profile committed at
    * the live tip of the PR's own base ref. Defaults to the real GitHub reads,
@@ -2701,6 +2893,16 @@ interface PrReadyDependencies {
    * policy — unreadable authority is never absent authority.
    */
   basePolicy?: BaseReviewPolicyAuthority;
+  /**
+   * #1323: where the exact-head rules read GitHub's App runs for `pr-verify`
+   * and `pr-review` at one head. `pr:ready` refuses when any App run of
+   * either gate at the PR head is not a completed pass (rule 4); `pr:publish`,
+   * which inherits this, posts a gate's proof only when its head has no run
+   * for that gate (rule 2). Defaults to the user config's App id, else the
+   * pinned factory App id, and the real `gh api` read, since readiness is a
+   * control and an absent dependency must not mean an unread veto.
+   */
+  exactHeadRuns?: ExactHeadRunSource;
   github?: {
     fetchClosingPullRequests?: (input: {
       issue: number;
@@ -2935,9 +3137,9 @@ declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
 declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
 declare const reviewStatusSchema: z.ZodEnum<{
   "not-required": "not-required";
+  stale: "stale";
   blocked: "blocked";
   current: "current";
-  stale: "stale";
   missing: "missing";
 }>;
 type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -3130,6 +3332,11 @@ interface BoundaryCheckArgs {
   repo?: string;
 }
 interface BoundaryCheckDependencies {
+  /**
+   * The broker's admission token on a Cursor VM (#1327), for the issue reads.
+   * Read by {@link runBoundaryCheckWithAdmission} only.
+   */
+  admission?: AdmissionCredential;
   github?: BoundaryCheckGithub;
   hq?: HqIngestDependencies;
   readWaivers?: (cwd: string) => DemandWaiver[];
@@ -3297,6 +3504,12 @@ interface PrReviewIssueBodyInput {
   repo: string;
 }
 interface PrReviewDependencies {
+  /**
+   * The broker's admission token on a Cursor VM (#1327), for the issue reads
+   * `--assemble` makes. Defaults to the process-wide credential, which mints
+   * nothing off a Cursor managed runtime.
+   */
+  admission?: AdmissionCredential;
   /**
    * Test-only seam (#1131): runs after the recording has read the proof
    * state it is applied to and immediately before the compare-and-swap write,
@@ -3345,6 +3558,11 @@ interface PrReviewDependencies {
    * measured against (#1131). Defaults to the GitHub lookup.
    */
   lookupPullRequestBase?: (cwd: string) => LivePullRequestBaseLookup;
+  /**
+   * #1323: the detached `patronage-factory/pr-review` publisher, the same one
+   * `pr:verify` uses. Injected by the CLI; absent, no check run is posted.
+   */
+  publishCheckRun?: (input: PublishFactoryCheckInput) => void;
 }
 declare function runPrReview(args: PrReviewArgs, dependencies?: PrReviewDependencies): Promise<PrReviewProof>;
 //#endregion
@@ -3445,11 +3663,12 @@ interface PrPublishHandoff {
   routeOwnedRepairs: ReadinessRepair[];
   /**
    * Whether the merge is actually on GitHub's schedule (#477, #515 review).
-   * An admitted candidate is not a handed-off one: `pr:ready` arms only when a
-   * boundary wave authorized it, and the arming can fail to take effect. A
+   * An admitted candidate is not a handed-off one: `pr:ready` does not arm
+   * when the repository does not allow auto-merge, the pull request carries
+   * `factory:hold`, a boundary wave keeps it attended, or it is an epic member
+   * run without `--epic` (#1299), and the arming can fail to take effect. A
    * readiness status of `ready` says the candidate passed, never that anything
-   * will merge it — only an auto-merge-authorized boundary wave can schedule
-   * one — so publish reads this before claiming nothing is owed.
+   * will merge it, so publish reads this before claiming nothing is owed.
    */
   scheduled: boolean;
   status: PrReadyProof["status"];
@@ -3495,6 +3714,12 @@ interface PrPublishResult {
    * it stays an additive change to the published result contract.
    */
   verificationReuse?: VerificationReuse;
+  /**
+   * Whether the conclusion-only pr:review check run landed for this head
+   * (#1323). Optional so adding it stays an additive change to the published
+   * result contract.
+   */
+  reviewProofBinding?: ReviewProofBindingOutcome;
   /**
    * Whether the durable pr:verify check-run binding landed for this head (#247).
    * Always populated from this version on; optional so adding it stays an
@@ -3509,8 +3734,17 @@ declare class PrPublishFollowUpError extends Error {
 interface PrPublishDependencies extends PrReadyDependencies {
   currentBranch?: (cwd: string) => string | undefined;
   /**
-   * Awaited republish of the `pr:verify` check run once the head SHA is on
-   * GitHub (#247). Returns whether the App-owned check run landed.
+   * Awaited publication of the conclusion-only `pr:review` check run for the
+   * publish head (#1323). Returns whether the App-owned check run landed.
+   * Injected by the CLI like the verify sink. A review cycle publish records
+   * from `--findings` posts through it too, accepted or blocked.
+   */
+  ensureReviewCheckRun?: typeof ensureFactoryCheckRunPublished;
+  /**
+   * Awaited post of the `pr:verify` check run once the head SHA is on GitHub
+   * (#247), when the head has no run for it yet (#1323). Returns whether the
+   * App-owned check run landed. A `pr:verify` publish runs fresh posts through
+   * it too, pass or failure (#1323).
    */
   ensureVerifyCheckRun?: typeof ensureFactoryCheckRunPublished;
   factoryCliInvocation?: FactoryCliInvocation;
@@ -3525,7 +3759,11 @@ interface PrPublishDependencies extends PrReadyDependencies {
   };
   runFollowUp?: FollowUpRunner;
   runPrReady?: typeof runPrReady;
-  runPrReview?: (args: PrReviewArgs) => Promise<PrReviewProof>;
+  /**
+   * The review producer publish runs for `--findings`. Its second argument
+   * carries the publisher for the verdict it records (#1323).
+   */
+  runPrReview?: (args: PrReviewArgs, dependencies?: ProducerPublisher) => Promise<PrReviewProof>;
   /** Settles asynchronously scheduled sink work before the handoff drain. */
   awaitPendingIngest?: () => Promise<void>;
   /**
@@ -3535,7 +3773,11 @@ interface PrPublishDependencies extends PrReadyDependencies {
   flushHqSpool?: (args: {
     cwd: string;
   }) => Promise<HqFlushResult>;
-  runPrVerify?: (args: PrVerifyArgs) => Promise<PrVerifyProof>;
+  /**
+   * The verify producer publish runs when no proof applies. Its second
+   * argument carries the publisher for the verdict it produces (#1323).
+   */
+  runPrVerify?: (args: PrVerifyArgs, dependencies?: ProducerPublisher) => Promise<PrVerifyProof>;
   /**
    * Injectable clock for the promotion instant the hosted-run await measures
    * `verify` staleness against (#1045; tests only — production reads the real
@@ -3553,13 +3795,19 @@ interface PrPublishDependencies extends PrReadyDependencies {
  * the publish summary: a binding that silently failed to land is
  * indistinguishable from verification that never happened, and the operator is
  * the only one who can fix the cause (usually an unpushed head).
+ *
+ * #1323 (rule 2): `skipped-existing-run` means the head already has an App run
+ * for the gate, so publish posted nothing; `skipped-unreadable` means GitHub's
+ * runs at the head could not be read whole, so publish posted nothing either.
  */
 type VerifyProofBindingOutcome = {
   status: "not-attempted";
 } | {
   headSha: string;
-  status: "failed" | "published" | "skipped-relabelled-head";
+  status: ExactHeadBindingStatus | "skipped-relabelled-head";
 };
+/** What a gate's post at the publish head came to, once rule 2 has read. */
+type ExactHeadBindingStatus = "failed" | "published" | "skipped-existing-run" | "skipped-unreadable";
 /**
  * Whether publish reused the on-disk `pr:verify` proof, and the one-line reason
  * (#291). Publish decides reuse silently today, which is what made the
@@ -3570,6 +3818,21 @@ interface VerificationReuse {
   reason: string;
   reused: boolean;
 }
+/** The publisher a producer takes: `pr:verify`'s and `pr:review`'s own seam. */
+interface ProducerPublisher {
+  publishCheckRun?: (input: PublishFactoryCheckInput) => void;
+}
+/**
+ * What became of the conclusion-only `pr:review` check run for this publish
+ * (#1323). A proof that records no review (`not-required`) has no verdict to
+ * post.
+ */
+type ReviewProofBindingOutcome = {
+  status: "not-attempted";
+} | {
+  headSha: string;
+  status: ExactHeadBindingStatus | "skipped-no-review" | "skipped-relabelled-head";
+};
 /**
  * Whether publish runs the follow-up `pr:ready` recommended, plus the one-line
  * reason either way (#291).
@@ -4669,6 +4932,26 @@ interface HqSpoolCheckDependencies {
   countSpool?: typeof countHqSpoolWork;
   sweepOrphans?: typeof sweepHqSpoolOrphans;
 }
+/** Test seams. Production never sets these. */
+interface HqReadinessCheckDependencies {
+  fetch?: typeof fetch;
+  resolveSecret?: SecretReferenceResolver;
+  timeoutMs?: number;
+}
+//#endregion
+//#region src/doctor-machine-checks.d.ts
+/** Test seams. Production never sets these. */
+interface MachineCheckDependencies {
+  cpuCount?: () => number;
+  /** Whether an executable file with this name is on the PATH in `env`. */
+  isOnPath?: (name: string, env: NodeJS.ProcessEnv) => boolean;
+  nodeVersion?: string;
+  platform?: NodeJS.Platform;
+  /** A small text file's contents, or undefined when it cannot be read. */
+  readText?: (filePath: string) => string | undefined;
+  /** What `/bin/sh` resolves to, or undefined when it cannot be resolved. */
+  resolveShell?: () => string | undefined;
+}
 //#endregion
 //#region src/doctor.d.ts
 interface DoctorReport {
@@ -4686,8 +4969,12 @@ interface DoctorProjectProfileInput extends LoadProjectProfileInput {
   /** Diff base for the admission preflight; ignored unless `preflight`. */
   base?: string;
   env?: NodeJS.ProcessEnv;
+  /** Test seam for the HQ readiness rows (#1315); production never sets this. */
+  hqReadinessDependencies?: HqReadinessCheckDependencies;
   /** Test seam for the local HQ spool check (#394); production never sets this. */
   hqSpoolDependencies?: HqSpoolCheckDependencies;
+  /** Test seam for the machine readiness rows (#1315); production never sets this. */
+  machineDependencies?: MachineCheckDependencies;
   /**
    * Append the read-only admission checklist (#292): every requirement this
    * candidate must satisfy before merge, named in one pass. Preflight checks
@@ -4821,14 +5108,132 @@ interface EvaluationInput {
     blockingReasons: string[];
     notices: string[];
   };
+  exactHeadRunRefusals?: {
+    prReview: string[];
+    prVerify: string[];
+  };
   waivers?: DemandWaiver[];
 }
 declare const evaluateReadiness: (input: EvaluationInput) => {
+  humanBlockingReasons: string[];
+  ledger: {
+    baseSha: string;
+    blockingReasons: string[];
+    classification: "docs/process-only" | "trivial" | "non-trivial";
+    github: {
+      draft: boolean;
+      mergeStateStatus: string;
+      mergeable: string;
+      requiredChecks: "unknown" | "pending" | "passed" | "failed" | "none";
+      unresolvedReviewThreads: number;
+      reviewDecision?: string | null | undefined;
+    };
+    headSha: string;
+    patchId: string;
+    pr: number;
+    repairs: {
+      action: string;
+      code: "undraft-pr" | "await-post-undraft-checks";
+      command: string;
+    }[];
+    reviews: {
+      correctness: {
+        required: boolean;
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
+        reviewedHeadSha?: string | undefined;
+        reviewedPatchId?: string | undefined;
+      };
+      security?: {
+        required: boolean;
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
+        reviewedHeadSha?: string | undefined;
+        reviewedPatchId?: string | undefined;
+      } | undefined;
+    };
+    schemaVersion: 2;
+    verification: {
+      command: "patronage-factory pr:verify";
+      prVerify: "missing";
+    } | {
+      command: "patronage-factory pr:verify";
+      prVerify: "stale";
+      verifiedHeadSha: string;
+    } | {
+      command: "patronage-factory pr:verify";
+      prVerify: "passed-via-head";
+      verifiedHeadSha: string;
+    } | {
+      command: "patronage-factory pr:verify";
+      docsOnlyVerifiedHeadSha: string;
+      prVerify: "docs-only-delta";
+      verifiedHeadSha?: string | undefined;
+    } | {
+      command: "patronage-factory pr:verify";
+      prVerify: "trivial-delta";
+      trivialVerifiedHeadSha: string;
+      verifiedHeadSha?: string | undefined;
+    };
+    externalChecks?: {
+      checkType: "review" | "verify";
+      name: string;
+      scopeReason: string;
+      status: "satisfied" | "unmet" | "out-of-scope";
+      reason?: string | undefined;
+      scope?: {
+        classifications: ("docs/process-only" | "trivial" | "non-trivial")[];
+      } | undefined;
+    }[] | undefined;
+    mergeBaseSha?: string | undefined;
+    reviewCycleState?: {
+      autoBlockingFindings: number;
+      countsBySeverity: {
+        critical: number;
+        high: number;
+        low: number;
+        medium: number;
+        unknown: number;
+      };
+      nonBlockingFindings: number;
+      openFindings: number;
+      windowExhausted: boolean;
+      highestBlockingSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
+      highestOpenSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
+      maxReviewCycles?: number | undefined;
+      reviewCycle?: number | undefined;
+      staleRepeatFindings?: number | undefined;
+    } | undefined;
+    reviewLadder?: {
+      cycleCounts: {
+        gate: number;
+        interior: number;
+      };
+      nextAction: "run-interior-cycle" | "advance-to-gate" | "run-gate-cycle" | "accept-nonblocking-findings" | "escalate-to-triage" | "ready-for-human";
+      stage: "interior" | "gate" | "interior-complete";
+      forcedTransition?: "gate-cap-exhausted" | "interior-cap-reached" | undefined;
+    } | undefined;
+    reviewRuns?: PrReviewResult[] | undefined;
+    reviewTerminalState?: "blocked" | "accepted-with-findings" | "clean" | undefined;
+  };
+  /**
+   * Facts a reader needs that are not refusals (#477): the settle-window
+   * arming notice, and every waived demand rendered so it can never read as
+   * a met one.
+   */
+  notices: string[];
+  repairs: {
+    action: string;
+    code: "undraft-pr" | "await-post-undraft-checks";
+    command: string;
+  }[];
+  status: ReadinessStatus; /** Demands that were in force, were NOT met, and the operator waived. */
+  waivedDemands: WaivedDemand[];
+  catchUpRecognition: CatchUpRecognition;
   blockedReasons: {
     code: string;
     detail: string;
   }[];
   blockingReasons: string[];
+} | {
   humanBlockingReasons: string[];
   ledger: {
     baseSha: string;
@@ -4853,13 +5258,13 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "not-required" | "blocked" | "current" | "stale" | "missing";
+        status: "not-required" | "stale" | "blocked" | "current" | "missing";
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       } | undefined;
@@ -4941,6 +5346,12 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
   }[];
   status: ReadinessStatus; /** Demands that were in force, were NOT met, and the operator waived. */
   waivedDemands: WaivedDemand[];
+  catchUpRecognition?: undefined;
+  blockedReasons: {
+    code: string;
+    detail: string;
+  }[];
+  blockingReasons: string[];
 };
 //#endregion
 //#region src/evidence-emit.d.ts
@@ -5623,6 +6034,12 @@ declare function createProgram(options?: CreateProgramOptions): Command;
  * 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).
+ *
+ * On the way out it waits for the command's own check-run publications
+ * (bounded, #1322) and HQ emissions, then drains
+ * the checkout's HQ spool once (#1313). This is the one place that drains on
+ * exit. `pr:ready` then prints one line if events are still spooled (#1317).
+ * None of these steps can throw or change the command's exit code.
  */
 declare function run(argv?: string[], cliEntry?: string): Promise<void>;
 //#endregion