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

package/README.md

@@ -76,6 +76,6 @@ npx skills add https://github.com/patronage/software-factory -g --all
 
 They provide procedure and link back to the documentation site; they are not a second command reference.
 
-The package also exports an Oxlint plugin at `@patronage/software-factory/oxlint-jev`. It asks Jev questions that a project writes about its own code, through HQ, from a dedicated Oxlint config. It records by default and sends only with `PATRONAGE_JEV_MODE=live`. `psf jev:calibrate` scores those questions against the project's labeled cases. Both are session diagnostics, never gates. See [Ask Jev about code](https://factory.patronage.com/how-to/ask-jev-about-code).
+The package also exports an Oxlint plugin at `@patronage/software-factory/oxlint-jev`. It asks Jev questions that a project writes about its own code, through HQ, from a dedicated Oxlint config. It records by default and sends only with `PATRONAGE_JEV_MODE=live`. `psf jev:calibrate` scores those questions against the project's labeled cases. Both are session diagnostics, never gates. See [Ask Jev about your code](https://factory.patronage.com/tutorials/ask-jev-about-code).
 
 `assembleReviewPrompt` puts a repository-root `CODING_STANDARDS.md` into the correctness prompt when the file exists and is not blank. It reads the file at the candidate head, not from the working tree, and emits one `coding-standards` section that names the head SHA. A repository without the file gets an unchanged prompt. `pr:review --assemble` writes that factory-owned prompt under `.factory-memory/pr-review-prompt.json`. `pr:review --findings` copies the recorded sections onto the proof when the artifact's patch-id matches.

package/dist/index.d.ts

@@ -4,6 +4,109 @@ 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>;
@@ -1250,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.
@@ -1547,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;
@@ -1570,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;
@@ -1659,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";
@@ -2499,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;
@@ -2555,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.
@@ -2728,19 +2847,34 @@ interface PullRequestArmingFacts {
  * arm, and its notice says which read failed.
  */
 interface ArmingPolicyReads {
-  /** One issue's sub-issue parent, or `null` when it has none. */
+  /**
+   * 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;
+  }) => 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;
+  }) => PullRequestArmingFacts | Promise<PullRequestArmingFacts>;
 }
 interface PrReadyDependencies {
+  /**
+   * 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
@@ -2759,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;
@@ -3188,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[];
@@ -3355,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,
@@ -3403,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
@@ -3554,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
@@ -3568,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;
@@ -3584,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>;
   /**
@@ -3594,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
@@ -3612,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
@@ -3629,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).
@@ -4728,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 {
@@ -4745,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
@@ -4880,6 +5108,10 @@ interface EvaluationInput {
     blockingReasons: string[];
     notices: string[];
   };
+  exactHeadRunRefusals?: {
+    prReview: string[];
+    prVerify: string[];
+  };
   waivers?: DemandWaiver[];
 }
 declare const evaluateReadiness: (input: EvaluationInput) => {
@@ -5802,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