@patronage/software-factory 0.23.0 → 0.30.0-alpha.1

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync, rmSync } from "node:fs";
 import { Command } from "commander";
 import { z } from "zod";
+import { readFile } from "node:fs/promises";
 
 //#region src/github-issue-comments.d.ts
 interface GithubIssueCommentApi {
@@ -25,7 +26,7 @@ interface GithubIssueComment {
 }
 declare const normalizeIssueComments: (value: GithubIssueCommentApi[] | GithubIssueCommentApi[][]) => GithubIssueComment[];
 declare namespace boundary_review_proof_d_exports {
-  export { BOUNDARY_REVIEW_PROOF_KIND, BoundaryReviewProof, BoundaryReviewProofComment, boundaryReviewProofSchema, selectBoundaryReviewProof, undispositionedBlockingFindings };
+  export { BOUNDARY_REVIEW_PROOF_KIND, BoundaryReviewProof, BoundaryReviewProofComment, boundaryReviewProofAuthorsSeen, boundaryReviewProofSchema, selectBoundaryReviewProof, undispositionedBlockingFindings };
 }
 declare const BOUNDARY_REVIEW_PROOF_KIND = "boundary-review-proof";
 declare const boundaryReviewProofBaseSchema: z.ZodObject<{
@@ -123,6 +124,7 @@ interface BoundaryReviewProofComment {
   commentUrl?: string;
 }
 declare const selectBoundaryReviewProof: (comments: GithubIssueComment[], boundary: string, declaredBy: string) => BoundaryReviewProofComment | undefined;
+declare const boundaryReviewProofAuthorsSeen: (comments: GithubIssueComment[], boundary: string) => string[];
 declare const undispositionedBlockingFindings: (proof: BoundaryReviewProof) => string[];
 //#endregion
 //#region src/hq-ingest-sink.d.ts
@@ -166,6 +168,195 @@ interface HqIngestDependencies {
   timeoutMs?: number;
   transportTimeoutMs?: number;
 }
+/** The repository whose undelivered evidence a spool holds. */
+interface HqSpoolRepository {
+  owner: string;
+  repo: string;
+}
+/**
+ * What became of one spooled event. `delivered` and `duplicate` both mean HQ
+ * holds it (dedup is by content-addressed eventId), so the entry is removed;
+ * `rejected` and `unreachable` leave it spooled.
+ */
+interface HqSpoolEntryOutcome {
+  detail?: string;
+  eventId: string;
+  kind: string;
+  spool: string;
+  /**
+   * `migrated` belongs to the legacy JSONL journal only: the row was moved
+   * into the current spool without being delivered. The spool pass that runs
+   * after it in the same drain supersedes that line with a real outcome when
+   * it gets to the row; a `migrated` line that survives the run means the row
+   * is still waiting.
+   *
+   * `undeliverable` is the one terminal verdict (#445). Every other status
+   * describes a moment: HQ was unreachable, HQ refused this content today, the
+   * row moved. Retrying is meaningful for all of them. A wrong-origin entry is
+   * different in kind — it is refused here, from the entry's own bytes, with no
+   * request made, and the same bytes produce the same verdict on every future
+   * run. Leaving it spooled asks the operator to retry something that provably
+   * cannot succeed, and the count it inflates is the one doctor goes red on.
+   */
+  status: "delivered" | "duplicate" | "migrated" | "rejected" | "undeliverable" | "unreachable";
+}
+interface HqSpoolFlushInput {
+  clientId: string;
+  clientSecret: string;
+  /** Repository root whose legacy `.factory-memory` spool is also drained. */
+  cwd: string;
+  /** The profile's HQ origin; entries recorded against another are refused. */
+  endpoint: string;
+  /** Operator-named spool directories; replaces the default two locations. */
+  explicitDirectories?: string[];
+  repository: HqSpoolRepository;
+}
+interface HqSpoolFlushSummary {
+  delivered: number;
+  duplicate: number;
+  /**
+   * The drain did not finish: the budget elapsed, or events beyond the
+   * rejected ones are still spooled. Never report an incomplete pass as a
+   * clean drain — a recovery run reads this to know whether to run again.
+   */
+  incomplete: boolean;
+  outcomes: HqSpoolEntryOutcome[];
+  rejected: number;
+  /** Events still in the drained spools when the pass ended. */
+  remaining: number;
+  /** Locations that were read; a missing one is simply absent from the list. */
+  spools: string[];
+  /**
+   * Events dispositioned as permanently undeliverable this pass (#445). They
+   * are gone from `remaining` — that is the point — so this is the only place
+   * the run says they existed.
+   */
+  undeliverable: number;
+  unreachable: number;
+  /** Files retained by a transport failure, counted per file. */
+  unreachableFiles: number;
+}
+interface HqSpoolWorkCount {
+  /**
+   * The earliest moment learned across pending spool files (their own write
+   * time) and legacy journal rows (their own `failedAt`). Absent only when
+   * `pending` is `0`, or when every timestamp source was unreadable within
+   * budget — an estimate for doctor's remediation message (#394), never a
+   * precise audit trail.
+   */
+  oldestQueuedAt?: string;
+  /** Spooled events and replayable journals waiting in the locations below. */
+  pending: number;
+  /** Locations that exist and hold spooled work. */
+  spools: string[];
+  /**
+   * A location existed but could not be listed. The count above saw nothing
+   * there, so a caller deciding whether the drain is worth doing must treat a
+   * non-zero value as "work may be waiting" — never as an empty spool.
+   */
+  unlistable: number;
+}
+/**
+ * Counts spooled work for a repository without draining it or touching a
+ * credential (#414).
+ *
+ * `hq:flush` used to resolve the HQ Access token before it ever looked at the
+ * spool, so a lane with nothing to send still paid a secret-manager round trip
+ * — and still failed, opaquely, in a sandbox that has no keychain access. The
+ * 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, "cwd" | "explicitDirectories" | "repository">, dependencies?: {
+  budgetMs?: number;
+  env?: NodeJS.ProcessEnv;
+}): Promise<HqSpoolWorkCount>;
+/** A spool under an earlier key for this repository, not the current one. */
+interface HqSpoolOrphan {
+  /** The `hq-retry-spool` directory itself, ready to pass to `--dir`. */
+  directory: string;
+  oldestQueuedAt?: string;
+  /** Spooled events and journal rows waiting there. */
+  pending: number;
+  /**
+   * The location exists but could not be listed. As everywhere else in this
+   * inspection, unknown counts as work: a swept location nobody could read is
+   * reported, never quietly dropped as empty.
+   */
+  unlistable: number;
+}
+interface HqSpoolOrphanSweep {
+  /** Only locations holding work; an empty orphan spool is not a finding. */
+  orphans: HqSpoolOrphan[];
+  root: string;
+}
+/**
+ * Reports spooled evidence sitting under an earlier key for *this* repository
+ * (#420).
+ *
+ * The spool is keyed by owner and repo, so a change to the segment encoding
+ * itself — which happened during #390's own development — moves the address
+ * without moving the evidence. Both readers of the spool resolve exactly one
+ * key, so the events under the old one become invisible: the drain reports
+ * success, doctor reports empty, and three real proofs sat unread until an
+ * attended recovery enumerated the tree by hand.
+ *
+ * This sweep only reports. Draining another key's events is a decision this
+ * does not make — the operator gets the location and the count, and
+ * `hq:flush --dir` remains the recovery path.
+ *
+ * **Why candidate keys and not a walk of the root (#446).** The root is shared
+ * by every factory repository on the machine, so enumerating it and calling
+ * everything that is not the current key an orphan describes another
+ * repository's ordinary, current, correct spool exactly as well as it describes
+ * this repository's obsolete one. That made doctor red in one checkout because
+ * a different repository had pending work, and told the operator to drain it —
+ * confidently prescribing the wrong action. Nothing on disk distinguishes the
+ * two cases: an unrecognised key carries no statement about who wrote it.
+ *
+ * So discovery is scoped to the keys *this* repository could plausibly have
+ * produced — the current scheme plus the earlier ones listed in
+ * `hqSpoolCandidateKeys` — and a key outside that set is never this
+ * repository's business. The #420 incident is inside it: the joined
+ * single-segment key is one of the candidates.
+ *
+ * **And a marked walk beside them (#447).** Derivation's other blind spot is a
+ * key whose *encoding* this checkout no longer produces but whose owner and
+ * repo are unchanged — the retired non-injective era being the live example.
+ * That era cannot be derived safely, because a candidate built from it can
+ * equal a different repository's current key, so #446 dropped it rather than
+ * risk the cross-repository claim again.
+ *
+ * `SPOOL_REPOSITORY_MARKER` supplies the proof that derivation could not. Every
+ * enqueue stamps its spool with the repository writing it, so the root can be
+ * walked again: a directory whose marker names *this* repository is this
+ * repository's, whatever key encoding it sits under, and a directory whose
+ * marker names another repository is never reported here. That is the
+ * discriminator #446 correctly said did not exist — it exists now because
+ * something writes it down.
+ *
+ * The two discoveries are complements, not alternatives. The walk sees only
+ * what was stamped; directories written before this shipped have no marker, and
+ * candidate keys still find those. An unmarked directory is still never
+ * reported, because it still carries no statement about who wrote it.
+ *
+ * **What this does NOT close, despite being the marker's obvious use: renames
+ * and owner changes.** A marker records the identity that was current when the
+ * directory was written, so after `patronage/old` becomes `patronage/new` the
+ * stranded directory is stamped `patronage/old` — and matching is equality
+ * against the checkout's *present* identity, which rejects it. Making that work
+ * needs an identifier that survives a rename, which neither the profile nor the
+ * marker carries today; accepting a non-matching marker instead would be
+ * guessing, which is the #446 defect wearing a new hat. #447 stays open for it.
+ *
+ * Also outside the sweep, by construction: evidence under a *different state
+ * root*, if `XDG_STATE_HOME` moves. No walk of this root can reach another one.
+ */
+declare function sweepHqSpoolOrphans(input: {
+  repository: HqSpoolRepository;
+}, dependencies?: {
+  budgetMs?: number;
+  env?: NodeJS.ProcessEnv;
+}): Promise<HqSpoolOrphanSweep>;
 //#endregion
 //#region src/demand-waiver.d.ts
 declare const DEFAULT_DEMAND_WAIVER_PATH = ".factory-memory/demand-waivers.json";
@@ -264,6 +455,34 @@ declare const authorizeDemandWaiver: ({
   session: string | undefined;
 }) => AuthorizeDemandWaiverResult;
 //#endregion
+//#region src/blocked-reasons.d.ts
+declare const blockedReasonSchema: z.ZodObject<{
+  code: z.ZodString;
+  detail: z.ZodString;
+}, z.core.$strip>;
+type BlockedReason = z.infer<typeof blockedReasonSchema>;
+//#endregion
+//#region src/arm-auto-merge.d.ts
+interface ArmAutoMergeInput {
+  cwd: string;
+  /** The validated PR head this arming is a compare-and-set against. */
+  headSha: string;
+  owner: string;
+  pr: number;
+  repo: string;
+}
+/**
+ * What the PR actually did, read back after the call — never inferred from the
+ * exit code. `not-armed` is a failure: the candidate is admitted but nothing
+ * will merge it, so it carries the detail and `pr:ready` emits a re-dispatch.
+ */
+interface ArmAutoMergeOutcome {
+  /** Why the arming did not take effect, or what the invocation reported. */
+  detail?: string;
+  headSha: string;
+  outcome: "armed" | "merged" | "not-armed";
+}
+//#endregion
 //#region src/checkout-repository.d.ts
 interface CheckoutRepository {
   name: string;
@@ -300,235 +519,30 @@ 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/github-client.d.ts
-interface GithubPullRequestReview {
-  author: {
-    login?: string;
-  };
-  body: string;
-  /** GraphQL `PullRequestReview.lastEditedAt` — REST's `/pulls/reviews` has no equivalent (#843). */
-  lastEditedAt?: string;
-  state: string;
-  submittedAt?: string;
-  url: string;
-}
-//#endregion
-//#region src/merge-freeze.d.ts
-declare const MERGE_FREEZE_CHECK_NAME = "patronage-factory/merge-freeze";
-declare const MERGE_FREEZE_APP_SLUG = "patronage-factory";
-declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-  active: z.ZodLiteral<true>;
-  generationId: z.ZodNumber;
-  headSha: z.ZodString;
-  outcome: z.ZodEnum<{
-    stale: "stale";
-    active: "active";
-  }>;
-  reason: z.ZodString;
-  recordedAt: z.ZodISODateTime;
-  schemaVersion: z.ZodLiteral<1>;
-}, z.core.$strip>, z.ZodObject<{
-  active: z.ZodLiteral<false>;
-  clearRationale: z.ZodOptional<z.ZodString>;
-  generationId: z.ZodNumber;
-  headSha: z.ZodString;
-  outcome: z.ZodLiteral<"inactive">;
-  reason: z.ZodString;
-  recordedAt: z.ZodISODateTime;
-  schemaVersion: z.ZodLiteral<1>;
-}, z.core.$strip>], "active">;
-type MergeFreezeState = z.infer<typeof mergeFreezeStateSchema>;
-/**
- * The write side of this contract lives in the generated main-push verify
- * workflow (#356, ADR 0016 as amended): it is the ONLY producer of
- * `patronage-factory/merge-freeze` generations. Its emitted `output.text`
- * payload must parse under this exact reader schema, which is what the
- * workflow's own tests assert through this export.
- */
-declare function validateMergeFreezeState(value: unknown): MergeFreezeState;
-interface MergeFreezeStoreInput {
-  cwd: string;
-  headSha: string;
-  repository: CheckoutRepository;
-}
-interface MergeFreezeStore {
-  read: (input: MergeFreezeStoreInput) => unknown;
-}
-declare namespace worktree_held_branch_d_exports {
-  export { MergeOperationalNotices, WorktreeHeldBranch, WorktreeHeldBranchCheck, WorktreeListEntry, checkWorktreeHeldBranch, findWorktreeHeldBranch, formatHeldBranchCloseoutSummary, listWorktreesPorcelain, parseGitWorktreeList, resolveMergeOperationalNotices, worktreeHeldBranchNotice };
-}
-/**
- * Detects when a PR head branch is checked out in a local git worktree.
- *
- * `gh pr merge --delete-branch` fails when the local branch is held by a
- * worktree (git refuses to delete a checked-out branch), which previously
- * broke the auto-merge lane mid-merge (patronage/internal#284). The merge
- * preflight surfaces this as an actionable notice — not a hard fail — so the
- * operator merges without `--delete-branch` (or prunes the worktree first)
- * and defers local branch cleanup to closeout.
- */
-interface WorktreeHeldBranch {
-  branch: string;
-  worktreePath: string;
-}
-interface WorktreeListEntry {
-  branch?: string;
-  path: string;
-}
-/**
- * Parses `git worktree list --porcelain` output. Entries are separated by
- * blank lines; each starts with `worktree <path>` and carries an optional
- * `branch refs/heads/<name>` attribute (detached worktrees have none).
- */
-declare function parseGitWorktreeList(porcelain: string): WorktreeListEntry[];
-/**
- * Returns the worktree holding `branch`, or undefined when no local worktree
- * has it checked out (or the porcelain listing was unavailable).
- */
-declare function findWorktreeHeldBranch({
-  branch,
-  worktreeListPorcelain
-}: {
-  branch: string;
-  worktreeListPorcelain: string | undefined;
-}): undefined | WorktreeHeldBranch;
-declare function worktreeHeldBranchNotice(held: WorktreeHeldBranch): string;
-interface MergeOperationalNotices {
-  notices: string[];
-  worktreeHeldBranch?: WorktreeHeldBranch;
-  worktreeHeldBranches?: WorktreeHeldBranch[];
-}
-/**
- * Single entry point for non-blocking merge preflight notices, mirroring
- * `resolveMergeGuardIdentity`/`mergeGuardBlockingReasons` in
- * merge-identity.ts: adding a notice kind never requires coordinated edits
- * in the command runner, and persisted notice strings cannot drift from the
- * structured detection result.
- */
-declare function resolveMergeOperationalNotices({
-  headRefName,
-  worktreeListPorcelain
-}: {
-  headRefName: string | undefined;
-  worktreeListPorcelain: string | undefined;
-}): MergeOperationalNotices;
-/**
- * Shared `git worktree list --porcelain` reader for merge preflight and
- * closeout. Returns undefined when the directory is missing, not a git
- * repository, or git is unavailable — detection is best-effort and callers
- * report "skipped" rather than fabricating a result.
- */
-declare function listWorktreesPorcelain(cwd: string): string | undefined;
-interface WorktreeHeldBranchCheck {
-  held?: WorktreeHeldBranch;
-  /** "skipped" means no branch was recorded or worktrees were unlistable. */
-  status: "clean" | "held" | "skipped";
-}
-/**
- * Closeout-side counterpart to the merge-preflight notice: the merge step
- * defers local branch cleanup to closeout, so closeout planning checks
- * whether the worker branch is still held by a worktree (#284).
- */
-declare function checkWorktreeHeldBranch({
-  branch,
-  worktreeListPorcelain
-}: {
-  branch: string | undefined;
-  worktreeListPorcelain: string | undefined;
-}): WorktreeHeldBranchCheck;
-/** One-line closeout summary, owned beside the detection logic. */
-declare function formatHeldBranchCloseoutSummary(check: WorktreeHeldBranchCheck): string;
-declare namespace merge_identity_d_exports {
-  export { LiveHeadInput, MergeGuardIdentity, MergeIdentityResult, PostProofCommit, ReadyProofForMergeIdentity, evaluateMergeIdentity, mergeGuardBlockingReasons, mergeGuardIdentitySchema, resolveMergeGuardIdentity };
-}
-interface PostProofCommit {
-  sha: string;
-  subject: string;
-}
+//#region src/pr-readiness/handled-human-comments.d.ts
+declare const HANDLED_COMMENTS_PAYLOAD_KIND: "handled-human-comments";
 /**
- * The slice of the pr:ready proof the merge guard actually consumes, so this
- * module does not depend on the parent proof envelope. `PrReadyProof` is
- * structurally assignable to this type.
+ * Authenticated producer of the durable handled set. Recorded on the readiness
+ * ledger; unverifiable producers are ignored on read (fail closed).
  */
-interface ReadyProofForMergeIdentity {
-  blockingReasons: string[];
-  ledger: {
-    /**
-     * The evaluated head SHA recorded by pr:ready: `pr.headRefOid` captured
-     * at evaluation time. The merge guard compares it to the live pushed
-     * HEAD with exact equality.
-     */
-    headSha: string;
-    pr: number;
-  };
-  status: string;
+type HandledCommentsProducerMode = "app" | "commit-status";
+interface HandledCommentsProducer {
+  /** App id (stringified) or GitHub login, depending on mode. */
+  identity: string;
+  mode: HandledCommentsProducerMode;
 }
-type MergeIdentityResult = {
-  kind: "match";
-  headSha: string;
-} | {
-  kind: "diverged";
-  liveHeadSha: string;
-  postProofCommits?: PostProofCommit[];
-  proofHeadSha: string;
-};
-type MergeGuardIdentity = MergeIdentityResult | {
-  kind: "live-head-invalid";
-  pr: number;
-  received: string;
-} | {
-  kind: "ready-proof-missing";
-  errorDetail?: string;
-  readyProofPath: string;
-} | {
-  kind: "ready-proof-pr-mismatch";
-  proofPr: number;
-  requestedPr: number;
-} | {
-  kind: "ready-proof-not-ready";
-  blockingReasons: string[];
-  status: string;
-};
-declare const evaluateMergeIdentity: ({
-  liveHeadSha,
-  postProofCommits,
-  proofHeadSha
-}: {
-  liveHeadSha: string;
-  postProofCommits?: PostProofCommit[];
-  proofHeadSha: string;
-}) => MergeIdentityResult;
-/**
- * The live PR head as fetched from GitHub: either a validated 40-hex SHA or
- * the raw (stringified) response that failed validation.
- */
-type LiveHeadInput = {
-  headSha: string;
-} | {
-  invalidResponse: string;
-};
-/**
- * Single entry point that owns construction of every MergeGuardIdentity
- * kind, so adding or changing a kind never requires coordinated edits in the
- * command runner.
- */
-declare const resolveMergeGuardIdentity: ({
-  commitsBetween,
-  liveHead,
-  pr,
-  readyProof,
-  readyProofError,
-  readyProofPath
-}: {
-  commitsBetween?: (fromSha: string, toSha: string) => PostProofCommit[] | undefined;
-  liveHead: LiveHeadInput;
+interface HandledCommentsCheckPayload {
+  clearedAt?: string;
+  handledCommentUrls: string[];
+  kind: typeof HANDLED_COMMENTS_PAYLOAD_KIND;
   pr: number;
-  readyProof: ReadyProofForMergeIdentity | undefined;
-  readyProofError?: unknown;
-  readyProofPath: string;
-}) => MergeGuardIdentity;
-declare const mergeGuardIdentitySchema: z.ZodType<MergeGuardIdentity>;
-declare const mergeGuardBlockingReasons: (identity: MergeGuardIdentity) => string[];
+  schemaVersion: 1;
+  sessionId?: string;
+}
+//#endregion
+//#region src/diff-classification.d.ts
+declare const DIFF_CLASSIFICATIONS: readonly ["docs/process-only", "trivial", "non-trivial"];
+type DiffClassification = (typeof DIFF_CLASSIFICATIONS)[number];
 //#endregion
 //#region src/profile.d.ts
 declare const DEFAULT_FACTORY_REPOSITORY = "unknown/unknown";
@@ -565,12 +579,11 @@ declare const factoryProjectProfileSchema: z.ZodObject<{
     }>;
     name: z.ZodString;
     scope: z.ZodOptional<z.ZodObject<{
-      classifications: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+      classifications: z.ZodArray<z.ZodEnum<{
         trivial: "trivial";
         "docs/process-only": "docs/process-only";
         "non-trivial": "non-trivial";
-      }>>>;
-      labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      }>>;
     }, z.core.$strict>>;
   }, z.core.$strict>>>;
   review: z.ZodObject<{
@@ -620,138 +633,6 @@ interface LoadProjectProfileResult {
 }
 declare function loadProjectProfile(input?: LoadProjectProfileInput): LoadProjectProfileResult;
 //#endregion
-//#region src/review-rungs.d.ts
-declare const EVIDENCE_REVIEW_RUNGS: readonly ["independent-model", "oracle", "human"];
-type EvidenceReviewRung = (typeof EVIDENCE_REVIEW_RUNGS)[number];
-//#endregion
-//#region src/pr-merge-check.d.ts
-interface PrMergeCheckArgs extends LoadProjectProfileInput {
-  epic?: number;
-  json?: boolean;
-  output?: string;
-  pr: number;
-  readyProof?: string;
-}
-interface PrMergeCheckProof {
-  schemaVersion: 1;
-  blockingReasons: string[];
-  boundary?: {
-    autoMerge: boolean;
-    epic: number;
-    review: EvidenceReviewRung;
-    wave: string;
-  };
-  command: "patronage-factory pr:merge-check";
-  /**
-   * Machine-safe arg array for the obvious next action (#523): on `pass`, the
-   * remote-only GitHub merge API invocation for this PR; on `fail`, the re-run that clears the
-   * block (`pr:ready`, or `pr:verify` then `pr:ready` after a head
-   * divergence). Same `argv` shape `factory:delegate --print` emits. Optional
-   * and purely additive — existing consumers ignore it.
-   */
-  followUp?: FollowUpAction;
-  identity: MergeGuardIdentity;
-  /**
-   * The pushed PR head SHA fetched from GitHub at check time. Absent only
-   * when GitHub returned no usable 40-hex head (identity kind
-   * "live-head-invalid"), which is itself a fail-closed blocking state.
-   */
-  liveHeadSha?: string;
-  /**
-   * Actionable operational notices that do not block the merge, e.g. a PR
-   * head branch held by a local worktree, which makes
-   * `gh pr merge --delete-branch` fail (patronage/internal#284).
-   */
-  notices?: string[];
-  pr: number;
-  status: "pass" | "fail";
-  /**
-   * Demands that were in force, were NOT met, and were waived by the operator
-   * (#354). Each entry carries the demand's refusals verbatim, so a waived
-   * demand can never read as a met one; the merge proceeds on the recorded
-   * operator act, not on evidence.
-   */
-  waivedDemands?: WaivedDemand[];
-  /** Present when the PR head branch is checked out in a local worktree. */
-  worktreeHeldBranch?: WorktreeHeldBranch;
-  /** All merge-relevant branches held by local worktrees (head and default). */
-  worktreeHeldBranches?: WorktreeHeldBranch[];
-}
-interface PrMergeCheckGitDependencies {
-  checkoutRepository: (cwd: string) => CheckoutRepository;
-  commitsBetween: (cwd: string, fromSha: string, toSha: string) => PostProofCommit[] | undefined;
-  worktreeListPorcelain: (cwd: string) => string | undefined;
-  showFileAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
-  objectIdAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
-}
-interface PrMergeCheckDependencies {
-  git?: Partial<PrMergeCheckGitDependencies>;
-  github?: {
-    fetchClosingPullRequests?: (input: {
-      issue: number;
-      owner: string;
-      repo: string;
-    }) => {
-      number: number;
-    }[];
-    fetchIssueBody?: (input: {
-      issue: number;
-      owner: string;
-      repo: string;
-    }) => string;
-    fetchPullRequestHead: (input: {
-      cwd: string;
-      owner: string;
-      pr: number;
-      repo: string;
-    }) => {
-      headRefName?: string;
-      headRefOid: string;
-      baseRefName?: string;
-      baseRefOid?: string;
-      mergedAt?: string | null;
-      remoteHeadRefExists?: boolean;
-      labels?: {
-        name: string;
-      }[];
-    };
-    fetchPullRequestReviews?: (input: {
-      owner: string;
-      pr: number;
-      repo: string;
-    }) => GithubPullRequestReview[];
-  };
-  mergeFreeze?: MergeFreezeStore;
-}
-declare function validatePrMergeCheckProof(value: unknown): PrMergeCheckProof;
-declare function readPrMergeCheckProof(filePath: string): PrMergeCheckProof;
-declare function runPrMergeCheck(args: PrMergeCheckArgs, dependencies?: PrMergeCheckDependencies): PrMergeCheckProof;
-//#endregion
-//#region src/pr-readiness/handled-human-comments.d.ts
-declare const HANDLED_COMMENTS_PAYLOAD_KIND: "handled-human-comments";
-/**
- * Authenticated producer of the durable handled set. Recorded on the readiness
- * ledger; unverifiable producers are ignored on read (fail closed).
- */
-type HandledCommentsProducerMode = "app" | "commit-status";
-interface HandledCommentsProducer {
-  /** App id (stringified) or GitHub login, depending on mode. */
-  identity: string;
-  mode: HandledCommentsProducerMode;
-}
-interface HandledCommentsCheckPayload {
-  clearedAt?: string;
-  handledCommentUrls: string[];
-  kind: typeof HANDLED_COMMENTS_PAYLOAD_KIND;
-  pr: number;
-  schemaVersion: 1;
-  sessionId?: string;
-}
-//#endregion
-//#region src/diff-classification.d.ts
-declare const DIFF_CLASSIFICATIONS: readonly ["docs/process-only", "trivial", "non-trivial"];
-type DiffClassification = (typeof DIFF_CLASSIFICATIONS)[number];
-//#endregion
 //#region src/pr-verify-mode.d.ts
 /**
  * The verification mode `pr:verify` resolved for a run.
@@ -877,6 +758,28 @@ interface CheckRunDependencies {
  * 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.
+ *
+ * "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
+ * source-pinned required check read `in_progress` across three runs — so GitHub
+ * never scheduled the merge and emitted no rollup row saying why. Arming
+ * already refuses to infer its outcome from the invocation and reads the pull
+ * request back (`arm-auto-merge.ts`); publication now does the same.
+ *
+ * "Landed" is judged against every run of the name from the pinned App, not
+ * against the one GitHub collapses to (#524): the newest must be *this* run, in
+ * the status and conclusion that were published, and no run of the name may
+ * still be unfinished. A surviving `in_progress` run blocks the required check
+ * on its own, so confirming past it would report success on a pull request
+ * GitHub will never merge. One read, no polling: an unconfirmed publication
+ * returns `false`, which `pr:ready` already turns into a notice and an
+ * idempotent re-dispatch.
+ *
+ * Confirmation is a point-in-time read, deliberately: a later publication for
+ * the same name changes the answer — a completed one by becoming the newest, an
+ * unfinished one by holding the check open beside this verdict rather than
+ * replacing it — and every remaining writer publishes once, as the last thing
+ * its invocation does. No retry, no poll, no re-confirm.
  */
 declare function ensureFactoryCheckRunPublished(input: PublishFactoryCheckInput, dependencies?: CheckRunDependencies & {
   onDiagnostic?: (message: string) => void;
@@ -890,6 +793,79 @@ interface PublishHandledCommentsCheckInput {
   sha: string;
 }
 //#endregion
+//#region src/merge-freeze.d.ts
+declare const MERGE_FREEZE_CHECK_NAME = "patronage-factory/merge-freeze";
+declare const MERGE_FREEZE_APP_SLUG = "patronage-factory";
+declare const mergeFreezeStateSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  active: z.ZodLiteral<true>;
+  generationId: z.ZodNumber;
+  headSha: z.ZodString;
+  outcome: z.ZodEnum<{
+    active: "active";
+    stale: "stale";
+  }>;
+  reason: z.ZodString;
+  recordedAt: z.ZodISODateTime;
+  schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strip>, z.ZodObject<{
+  active: z.ZodLiteral<false>;
+  clearRationale: z.ZodOptional<z.ZodString>;
+  generationId: z.ZodNumber;
+  headSha: z.ZodString;
+  outcome: z.ZodLiteral<"inactive">;
+  reason: z.ZodString;
+  recordedAt: z.ZodISODateTime;
+  schemaVersion: z.ZodLiteral<1>;
+}, z.core.$strip>], "active">;
+type MergeFreezeState = z.infer<typeof mergeFreezeStateSchema>;
+/**
+ * The write side of this contract lives in the generated main-push verify
+ * workflow (#356, ADR 0016 as amended): it is the ONLY producer of
+ * `patronage-factory/merge-freeze` generations. Its emitted `output.text`
+ * payload must parse under this exact reader schema, which is what the
+ * workflow's own tests assert through this export.
+ */
+declare function validateMergeFreezeState(value: unknown): MergeFreezeState;
+interface MergeFreezeStoreInput {
+  cwd: string;
+  headSha: string;
+  repository: CheckoutRepository;
+}
+interface MergeFreezeStore {
+  read: (input: MergeFreezeStoreInput) => unknown;
+}
+/**
+ * The freeze generation as an arming decision needs to see it (#477).
+ *
+ * `read` above collapses three different situations into one refusal, because
+ * merge time treated all of them as "do not merge". Arming time distinguishes
+ * them: a settled generation is the writer's verdict, a **settling** one is the
+ * window between a merge landing and its main-push verify completing (a
+ * running generation, or a missing generation proven by the immediately prior
+ * settled tip plus a current source-pinned verify run), and an **unreadable**
+ * one is ambiguous, malformed, foreign-App, or unavailable state. Same
+ * selection, same pinned App, same `started_at` ordering — only the reporting
+ * is finer.
+ */
+type MergeFreezeGeneration = {
+  kind: "settled";
+  state: MergeFreezeState;
+} | {
+  kind: "settling";
+  reason: string;
+  running?: {
+    headSha: string;
+    id: number;
+  };
+} | {
+  kind: "unreadable";
+  reason: string;
+};
+/** A merge-freeze reader that can also report the settle window (#477). */
+interface MergeFreezeAuthority extends MergeFreezeStore {
+  readGeneration: (input: MergeFreezeStoreInput) => MergeFreezeGeneration;
+}
+//#endregion
 //#region src/pr-proof-io.d.ts
 interface ProofDescriptor<T> {
   label: string;
@@ -953,6 +929,10 @@ interface ReviewLadderPolicy {
 }
 declare const resolveReviewLadderPolicy: (profile: Pick<FactoryProjectProfile, "review">) => ReviewLadderPolicy;
 //#endregion
+//#region src/review-rungs.d.ts
+declare const EVIDENCE_REVIEW_RUNGS: readonly ["independent-model", "oracle", "human"];
+type EvidenceReviewRung = (typeof EVIDENCE_REVIEW_RUNGS)[number];
+//#endregion
 //#region src/review-ladder-ledger.d.ts
 type LadderCycleStage = "interior" | "gate";
 interface LadderCycleRef {
@@ -1239,12 +1219,11 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
     name: z.ZodString;
     reason: z.ZodOptional<z.ZodString>;
     scope: z.ZodOptional<z.ZodObject<{
-      classifications: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+      classifications: z.ZodArray<z.ZodEnum<{
         trivial: "trivial";
         "docs/process-only": "docs/process-only";
         "non-trivial": "non-trivial";
-      }>>>;
-      labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+      }>>;
     }, z.core.$strict>>;
     scopeReason: z.ZodString;
     status: z.ZodEnum<{
@@ -1399,8 +1378,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       status: z.ZodEnum<{
         blocked: "blocked";
         "not-required": "not-required";
-        current: "current";
         stale: "stale";
+        current: "current";
         missing: "missing";
       }>;
     }, z.core.$strip>;
@@ -1412,8 +1391,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
       status: z.ZodEnum<{
         blocked: "blocked";
         "not-required": "not-required";
-        current: "current";
         stale: "stale";
+        current: "current";
         missing: "missing";
       }>;
     }, z.core.$strip>>;
@@ -1430,8 +1409,8 @@ declare const managedReadinessLedgerSchema: z.ZodObject<{
     docsOnlyDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
     docsOnlyVerifiedHeadSha: z.ZodOptional<z.ZodString>;
     prVerify: z.ZodEnum<{
-      passed: "passed";
       stale: "stale";
+      passed: "passed";
       missing: "missing";
     }>;
     trivialDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
@@ -1446,7 +1425,7 @@ type ReadinessStatus = "ready" | "blocked" | "slice-ready/not-final";
 type ManagedReadinessLedger = z.infer<typeof managedReadinessLedgerSchema>;
 declare function validateManagedReadinessLedger(value: unknown): ManagedReadinessLedger;
 declare namespace status_check_rollup_d_exports {
-  export { CheckState, StatusCheckRollup, isFactoryReadyCheck, statusCheckState };
+  export { CheckState, HOSTED_VERIFY_CHECK_NAME, StatusCheckRollup, hostedVerifyCheckState, isFactoryReadyCheck, isHostedVerifyCheck, statusCheckState };
 }
 type CheckState = "passed" | "failed" | "pending" | "none" | "unknown";
 interface StatusCheckRollup {
@@ -1461,6 +1440,38 @@ interface StatusCheckRollup {
   workflowName?: string;
 }
 declare const isFactoryReadyCheck: (check: StatusCheckRollup) => boolean;
+/**
+ * The hosted verification gate's context name — the branch ruleset's other
+ * source-pinned required check, alongside `patronage-factory/pr-ready`. One
+ * name across the fleet because one generator emits the workflow that posts
+ * it (ADR 0016, 2026-07-31 amendment).
+ */
+declare const HOSTED_VERIFY_CHECK_NAME = "verify";
+/**
+ * Is this rollup entry the hosted `verify` gate, from the producer the
+ * ruleset pins it to?
+ *
+ * `workflowName` is the producer signal the rollup actually carries: GitHub
+ * Actions check runs name their workflow, App-posted check runs come back with
+ * an empty one, and a user-token commit status arrives as a `context` with no
+ * `name` at all. Epic #473 wave 2 measured that a same-named check from the
+ * wrong writer is as inert as no check at all, so matching the name alone
+ * would accept exactly the thing the pin rejects.
+ */
+declare const isHostedVerifyCheck: (check: StatusCheckRollup) => boolean;
+/**
+ * The hosted `verify` gate's state on this head, read by presence (#477).
+ *
+ * This is the one rollup question the rollup can answer honestly. Wave 2
+ * measured that GitHub omits an *unsatisfied pinned requirement* from
+ * `statusCheckRollup` entirely — there is no "expected" or "missing" row — so
+ * a green rollup is not evidence of mergeability. What the rollup does report
+ * faithfully is the checks that ran. Asking whether this specific check ran,
+ * and passed, on this head turns the rollup's silence from a false green into
+ * a named refusal: `"none"` means the pinned requirement is unsatisfied and
+ * nothing else in the rollup would have said so.
+ */
+declare const hostedVerifyCheckState: (rollup: StatusCheckRollup[] | undefined) => CheckState;
 declare const statusCheckState: (rollup: StatusCheckRollup[] | undefined, exclude?: (check: StatusCheckRollup) => boolean) => CheckState;
 //#endregion
 //#region src/pr-ready.d.ts
@@ -1479,6 +1490,21 @@ interface PrReadyArgs extends LoadProjectProfileInput {
   verifyProof?: string;
 }
 interface GitHubPullRequest {
+  /**
+   * GitHub's live auto-merge enablement, or `null` when nothing is scheduled.
+   *
+   * Required, not optional (#515 review). `gh pr view --json autoMergeRequest`
+   * always returns the key — explicitly `null` when nothing is scheduled — and
+   * errors loudly on a field name it does not know, so there is no shape where
+   * the real CLI omits it. But `fetchPullRequest` is injectable, and an
+   * implementation that left the field out would silently disable the
+   * `boundary-wave` refusal that stops an epicless run from greening a
+   * candidate GitHub is already scheduled to merge. Requiring it makes the
+   * compiler enforce what `gh` already promises.
+   */
+  autoMergeRequest: {
+    enabledAt?: string;
+  } | null;
   baseRefName: string;
   baseRefOid: string;
   body: string;
@@ -1494,9 +1520,6 @@ interface GitHubPullRequest {
   }[];
   headRefOid: string;
   isDraft: boolean;
-  labels?: {
-    name: string;
-  }[];
   mergeStateStatus: string;
   mergeable: string;
   number: number;
@@ -1516,16 +1539,38 @@ interface GitHubPullRequest {
   url: string;
 }
 interface PrReadyProof {
-  schemaVersion: 1;
+  schemaVersion: 3;
+  /**
+   * What GitHub actually did when this run armed native auto-merge (#477).
+   * Present exactly when readiness passed and the 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.
+   */
+  arming?: {
+    detail?: string;
+    headSha: string;
+    outcome: "armed" | "merged" | "not-armed";
+  };
+  /**
+   * Why this run blocked, one entry per refusing demand (#391): `code` is the
+   * demand key from the resolver's vocabulary, `detail` the one-sentence
+   * refusal. Same refusals as `blockingReasons`, in the same order — the
+   * analyzable projection of a flat string list, so a wall of blocked proofs
+   * on one PR can be counted by cause. Absent when nothing blocked.
+   */
+  blockedReasons?: BlockedReason[];
   blockingReasons: string[];
   humanBlockingReasons: string[];
   command: "patronage-factory pr:ready";
   /**
-   * Machine-safe arg array for the obvious next action (#523): when `ready`,
-   * the `pr:merge-check` that must precede a merge; otherwise the `pr:verify`
-   * re-run that the blocking reasons name (re-verify the head, then re-run
-   * pr:ready). Same `argv` shape `factory:delegate --print` emits. Optional
-   * and purely additive.
+   * Machine-safe arg array for the obvious next action (#523): when `ready`
+   * but arming did not take effect, a `pr:ready` re-dispatch (idempotent on
+   * an unchanged head); otherwise the `gh pr ready` undraft repair or the
+   * `pr:verify` re-run that the blocking reasons name (re-verify the head,
+   * then re-run pr:ready). Same `argv` shape `factory:delegate --print`
+   * emits. Optional and purely additive.
    */
   followUp?: FollowUpAction;
   /**
@@ -1535,6 +1580,12 @@ interface PrReadyProof {
    * pushed HEAD, not a re-derivation. See the ledger schema.
    */
   ledger: ManagedReadinessLedger;
+  /**
+   * Actionable facts that did not block (#477): a settling merge-freeze
+   * generation that armed with a notice, and how each waived demand reads to a
+   * human. Absent when there are none.
+   */
+  notices?: string[];
   /** Committed profile blob evaluated by readiness. Required for merge. */
   profileBlobSha?: string;
   /** Checkout-relative committed profile path evaluated by readiness. */
@@ -1543,9 +1594,22 @@ interface PrReadyProof {
   /** Trusted checkout repository used for all GitHub reads and writes. */
   repository?: string;
   status: ReadinessStatus;
+  /**
+   * Demands that were in force, were NOT met, and were waived by the operator
+   * (#354, moved here from the merge-time proof by #477). Each entry carries
+   * the demand's refusals verbatim, so a waived demand can never read as a met
+   * one; the arming proceeds on the recorded operator act, not on evidence.
+   */
+  waivedDemands?: WaivedDemand[];
 }
 type PublishHandledCommentsResult = HandledCommentsProducer | Promise<HandledCommentsProducer | undefined> | undefined;
 interface PrReadyDependencies {
+  /**
+   * Arms GitHub native auto-merge for a passing candidate (#477). Defaults to
+   * the real `gh pr merge --auto` call plus the read-back that says what
+   * actually happened.
+   */
+  armAutoMerge?: (input: ArmAutoMergeInput) => ArmAutoMergeOutcome;
   github?: {
     fetchClosingPullRequests?: (input: {
       issue: number;
@@ -1581,7 +1645,26 @@ interface PrReadyDependencies {
   };
   git?: PrReadyGitDependencies;
   hq?: HqIngestDependencies;
-  publishCheckRun?: (input: PublishFactoryCheckInput) => void;
+  /**
+   * The authoritative merge-freeze reader (#477). Defaults to the pinned-App
+   * GitHub check-run authority — readiness is a control, so an absent
+   * dependency must not mean an unread freeze.
+   */
+  mergeFreeze?: Pick<MergeFreezeAuthority, "readGeneration">;
+  /**
+   * Awaited publication of the branded check, which is a source-pinned
+   * required check rather than a mirror (#477). Returns true only when the
+   * App-owned run landed. Defaults to `ensureFactoryCheckRunPublished`.
+   *
+   * `pr:ready` has no other publication seam, and this one cannot express a
+   * non-terminal run (#526): `status` is omitted from the input, so every run
+   * readiness creates is completed with a conclusion. A `pr:ready` invocation
+   * therefore cannot leave a run holding the source-pinned required check
+   * open, which is a permanent block on the pull request (#524).
+   */
+  publishFinalCheckRun?: (input: Omit<PublishFactoryCheckInput, "status"> & {
+    conclusion: "failure" | "success";
+  }) => Promise<boolean> | boolean;
   /** Injectable delay for the UNKNOWN-mergeable brief poll (tests). */
   sleep?: (ms: number) => Promise<void>;
   /** Injectable clock for CLI handled-comment provenance (tests). */
@@ -1606,16 +1689,14 @@ declare function runPrReady(args: PrReadyArgs, dependencies?: PrReadyDependencie
 declare const EVIDENCE_CHECK_TYPES: readonly ["review", "verify"];
 type EvidenceCheckType = (typeof EVIDENCE_CHECK_TYPES)[number];
 declare const requiredCheckScopeSchema: z.ZodObject<{
-  classifications: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+  classifications: z.ZodArray<z.ZodEnum<{
     trivial: "trivial";
     "docs/process-only": "docs/process-only";
     "non-trivial": "non-trivial";
-  }>>>;
-  labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }>>;
 }, z.core.$strict>;
 type RequiredCheckScope = z.infer<typeof requiredCheckScopeSchema>;
 interface RequiredCheckScopeContext {
-  labels: string[] | undefined;
   classification: DiffClassification | undefined;
 }
 interface ScopeDecision {
@@ -1779,8 +1860,8 @@ declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale"
 declare const reviewStatusSchema: z.ZodEnum<{
   blocked: "blocked";
   "not-required": "not-required";
-  current: "current";
   stale: "stale";
+  current: "current";
   missing: "missing";
 }>;
 type ReviewStatus = z.infer<typeof reviewStatusSchema>;
@@ -2366,8 +2447,54 @@ declare const runDemandWaive: (args: DemandWaiveArgs, dependencies?: DemandWaive
 //#region src/commands/demand-waive.d.ts
 type DemandWaiveAction = (args: DemandWaiveArgs) => DemandWaiver;
 //#endregion
-//#region src/commands/pr-merge-check.d.ts
-type PrMergeCheckAction = (args: PrMergeCheckArgs) => PrMergeCheckProof;
+//#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-flush.d.ts
+/**
+ * Spool locations this run did not drain because they sit under an earlier
+ * key for this repository. Reported, never drained: draining an older key's
+ * events is an operator decision, made with `--dir`.
+ */
+interface HqFlushOrphans {
+  orphans: HqSpoolOrphan[];
+}
+type HqFlushResult = (HqFlushOrphans & {
+  reason: string;
+  /**
+   * Events still spooled when the command gave up. Non-zero means the
+   * skip retained work: the exit status says so, and no caller may read
+   * the skip as "there was nothing to do".
+   */
+  retained: number;
+  status: "skipped";
+}) | (HqFlushOrphans & HqSpoolFlushSummary & {
+  endpoint: string;
+  status: "flushed";
+});
 //#endregion
 //#region src/pr-review.d.ts
 interface PrReviewArgs extends LoadProjectProfileInput {
@@ -2449,6 +2576,14 @@ type FollowUpRunner = (followUp: FollowUpAction, cwd: string) => Promise<void> |
 interface PrPublishHandoff {
   humanActions: string[];
   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
+   * readiness status of `ready` says the candidate passed, never that anything
+   * will merge it — so publish reads this before claiming nothing is owed.
+   */
+  scheduled: boolean;
   status: PrReadyProof["status"];
 }
 type PrPublishFollowUpOutcome = {
@@ -2514,6 +2649,15 @@ interface PrPublishDependencies extends PrReadyDependencies {
   runFollowUp?: FollowUpRunner;
   runPrReady?: typeof runPrReady;
   runPrReview?: (args: PrReviewArgs) => Promise<PrReviewProof>;
+  /** Settles asynchronously scheduled sink work before the handoff drain. */
+  awaitPendingIngest?: () => Promise<void>;
+  /**
+   * The handoff drain (#390). Advisory everywhere: publish reports what it
+   * found and never changes its verdict or exit status on the result.
+   */
+  flushHqSpool?: (args: {
+    cwd: string;
+  }) => Promise<HqFlushResult>;
   runPrVerify?: (args: PrVerifyArgs) => Promise<PrVerifyProof>;
   /**
    * Injectable delay for the bounded hosted-run await (#348; tests only —
@@ -3225,8 +3369,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    code: "code";
     review: "review";
+    code: "code";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3304,8 +3448,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   interiorCycle: z.ZodOptional<z.ZodNumber>;
   observedAt: z.ZodString;
   purpose: z.ZodEnum<{
-    code: "code";
     review: "review";
+    code: "code";
   }>;
   slotResolution: z.ZodObject<{
     effort: z.ZodEnum<{
@@ -3374,8 +3518,8 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     interiorCycle: z.ZodOptional<z.ZodNumber>;
     observedAt: z.ZodString;
     purpose: z.ZodEnum<{
-      code: "code";
       review: "review";
+      code: "code";
     }>;
     slotResolution: z.ZodObject<{
       effort: z.ZodEnum<{
@@ -3447,7 +3591,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   exitCode: number | null;
   harness: string;
   observedAt: string;
-  purpose: "code" | "review";
+  purpose: "review" | "code";
   slotResolution: {
     effort: "high" | "low" | "medium" | "xhigh";
     engine: string;
@@ -3594,7 +3738,7 @@ declare const scanFactoryTraceDiagnostics: ({
 //#endregion
 //#region src/interior-telemetry/gate-timing.d.ts
 declare const GATE_TIMING_SCHEMA_VERSION = 1;
-type FactoryGateName = "boundary:check" | "factory:closeout" | "pr:merge-check" | "pr:ready" | "pr:review" | "pr:verify";
+type FactoryGateName = "boundary:check" | "factory:closeout" | "pr:ready" | "pr:review" | "pr:verify";
 type GateTimingOutcome = "fail" | "pass";
 interface GateTimingRecord {
   agentRunId: string;
@@ -3666,13 +3810,39 @@ declare const isBotLogin: (login?: string | undefined) => boolean;
 declare const SHA_MATCH_MIN_LENGTH = 7;
 declare const sameHeadSha: (left: string, right: string) => boolean;
 //#endregion
-//#region src/doctor.d.ts
+//#region src/doctor-hq-checks.d.ts
+/**
+ * Two `doctor` checks that make silent HQ delivery failure loud (#394,
+ * epic #389 wave 2).
+ *
+ * Both consume #414's structured credential resolution rather than inventing
+ * a second classification: a sandboxed session that cannot reach the
+ * keychain is reported as "cannot resolve credentials here", never as
+ * "credentials are wrong" or a silent pass. Both name `psf hq:flush` and
+ * `psf pr:publish` as the commands that need a trusted local session.
+ *
+ * Advisory stays advisory: neither check can block anything but doctor's own
+ * exit status (epic #389 design decision 4). Absent credentials make the
+ * remote check a skip with a printed reason, never a silent pass.
+ */
 type DoctorCheckStatus = "error" | "ok" | "warning";
 interface DoctorCheck {
   message: string;
   name: string;
   status: DoctorCheckStatus;
 }
+interface HqSpoolCheckDependencies {
+  countSpool?: typeof countHqSpoolWork;
+  sweepOrphans?: typeof sweepHqSpoolOrphans;
+}
+interface HqRetroReadbackCheckDependencies {
+  fetch?: typeof fetch;
+  readFile?: typeof readFile;
+  resolve?: SecretReferenceResolver;
+  timeoutMs?: number;
+}
+//#endregion
+//#region src/doctor.d.ts
 interface DoctorReport {
   checks: DoctorCheck[];
   ok: boolean;
@@ -3689,6 +3859,10 @@ interface DoctorProjectProfileInput extends LoadProjectProfileInput {
   /** Diff base for the admission preflight; ignored unless `preflight`. */
   base?: string;
   env?: NodeJS.ProcessEnv;
+  /** Test seam for the local HQ spool check (#394); production never sets this. */
+  hqRetroReadbackDependencies?: HqRetroReadbackCheckDependencies;
+  /** Test seam for the remote HQ retro-envelope read-back check (#394). */
+  hqSpoolDependencies?: HqSpoolCheckDependencies;
   /**
    * Append the read-only admission checklist (#292): every requirement this
    * candidate must satisfy before merge, named in one pass. Preflight checks
@@ -3697,7 +3871,7 @@ interface DoctorProjectProfileInput extends LoadProjectProfileInput {
   preflight?: boolean;
   userConfig?: LoadUserConfigResult;
 }
-declare function doctorProjectProfile(input?: DoctorProjectProfileInput): DoctorReport;
+declare function doctorProjectProfile(input?: DoctorProjectProfileInput): Promise<DoctorReport>;
 //#endregion
 //#region src/pr-review-gate-trace.d.ts
 interface ReviewGateTraceIdentity {
@@ -3749,8 +3923,8 @@ type WorktreeRootLister = (worktreePath: string) => string[] | undefined;
 declare function checkWorktreeScratchFiles(worktreePath?: string, listRootEntries?: WorktreeRootLister): WorktreeScratchFileCheck;
 /**
  * Human-readable one-line summary of a scratch-file check, owned beside the
- * detection logic (mirroring worktreeHeldBranchNotice) so planner output,
- * docs, and future surfaces cannot drift apart.
+ * detection logic so planner output, docs, and future surfaces cannot drift
+ * apart.
  */
 declare function formatScratchFileCheckSummary(check: WorktreeScratchFileCheck): string;
 declare namespace pr_body_metadata_d_exports {
@@ -3999,6 +4173,8 @@ interface EvaluationInput {
   reviews?: PrReadinessReview[];
   unresolvedReviewThreads: number;
   requiredChecks: CheckState;
+  hostedVerifyCheck?: CheckState;
+  autoMergeEnabled?: boolean;
   draft: boolean;
   currentWithBase: boolean;
   mergeable: string;
@@ -4013,7 +4189,6 @@ interface EvaluationInput {
   evidenceEnvelopes?: LoadedEvidenceEnvelope[];
   mergeBaseSha?: string;
   authoringSessionIds?: string[];
-  prLabels?: string[];
   priorLedger?: Pick<ManagedReadinessLedger, "reviewRuns">;
   handledCommentUrls?: string[];
   checkRunHandledCommentUrls?: string[];
@@ -4023,9 +4198,18 @@ interface EvaluationInput {
   };
   handledCommentSessionId?: string;
   handledCommentClearedAt?: string;
-  waveReviewDemand?: Pick<WaveReviewDemand, "review" | "wave">;
+  waveReviewDemand?: Pick<WaveReviewDemand, "autoMerge" | "review" | "wave">;
+  mergeFreeze?: {
+    blockingReasons: string[];
+    notices: string[];
+  };
+  waivers?: DemandWaiver[];
 }
 declare const evaluateReadiness: (input: EvaluationInput) => {
+  blockedReasons: {
+    code: string;
+    detail: string;
+  }[];
   blockingReasons: string[];
   humanBlockingReasons: string[];
   ledger: {
@@ -4053,14 +4237,14 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     reviews: {
       correctness: {
         required: boolean;
-        status: "blocked" | "not-required" | "current" | "stale" | "missing";
+        status: "blocked" | "not-required" | "stale" | "current" | "missing";
         docsOnlyDeltaAccepted?: boolean | undefined;
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
       };
       security?: {
         required: boolean;
-        status: "blocked" | "not-required" | "current" | "stale" | "missing";
+        status: "blocked" | "not-required" | "stale" | "current" | "missing";
         docsOnlyDeltaAccepted?: boolean | undefined;
         reviewedHeadSha?: string | undefined;
         reviewedPatchId?: string | undefined;
@@ -4070,7 +4254,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     stackRole: "slice" | "single" | "rollup" | "merge-gate prerequisite";
     verification: {
       command: "patronage-factory pr:verify";
-      prVerify: "passed" | "stale" | "missing";
+      prVerify: "stale" | "passed" | "missing";
       docsOnlyDeltaAccepted?: boolean | undefined;
       docsOnlyVerifiedHeadSha?: string | undefined;
       trivialDeltaAccepted?: boolean | undefined;
@@ -4085,8 +4269,7 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
       status: "satisfied" | "unmet" | "out-of-scope";
       reason?: string | undefined;
       scope?: {
-        classifications?: ("trivial" | "docs/process-only" | "non-trivial")[] | undefined;
-        labels?: string[] | undefined;
+        classifications: ("trivial" | "docs/process-only" | "non-trivial")[];
       } | undefined;
     }[] | undefined;
     handledCommentsProducer?: {
@@ -4155,12 +4338,19 @@ declare const evaluateReadiness: (input: EvaluationInput) => {
     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" | "render-pr-body-sections" | "await-post-undraft-checks";
     command: string;
   }[];
-  status: ReadinessStatus;
+  status: ReadinessStatus; /** Demands that were in force, were NOT met, and the operator waived. */
+  waivedDemands: WaivedDemand[];
 };
 //#endregion
 //#region src/evidence-emit.d.ts
@@ -4356,6 +4546,7 @@ type FetchLike = (input: string, init?: {
   headers?: Record<string, string>;
   method?: string;
   redirect?: "error";
+  signal?: AbortSignal;
 }) => Promise<{
   json: () => Promise<unknown>;
   status: number;
@@ -4370,6 +4561,14 @@ interface PublishEpicStructureArgs {
   event: EpicStructureEvent;
   url: string;
   fetchImpl?: FetchLike;
+  /**
+   * Optional caller-owned abort signal. A caller that bounds this call with
+   * its own deadline (e.g. `factory:closeout`'s advisory re-emission, #392)
+   * can abort the in-flight request itself instead of merely abandoning the
+   * `await` — leaving the outbound socket alive past the caller's own
+   * declared timeout.
+   */
+  signal?: AbortSignal;
 }
 interface PublishEpicStructureResult {
   duplicate: boolean;
@@ -4492,7 +4691,6 @@ interface CreateProgramOptions {
   actions?: {
     boundaryCheck?: BoundaryCheckAction;
     demandWaive?: DemandWaiveAction;
-    prMergeCheck?: PrMergeCheckAction;
     prPublish?: PrPublishAction;
     prReady?: PrReadyAction;
     prReview?: PrReviewAction;
@@ -4503,4 +4701,4 @@ interface CreateProgramOptions {
 declare function createProgram(options?: CreateProgramOptions): Command;
 declare function run(argv?: string[]): Promise<void>;
 //#endregion
-export { type AppendFactoryTraceEventResult, type AssembledReviewPrompt, type BoundaryCheckArgs, type BoundaryCheckDependencies, type BoundaryCheckProofRecord, type BuildEpicStructureEventInput, type BuildRetroEnvelopeInput, type CloudflareAccessServiceToken, CreateProgramOptions, DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, type DagDocument, type DemandWaiveArgs, type DemandWaiveDependencies, DemandWaiveRefusalError, type DemandWaiver, type DemandWaiverStore, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, type EpicStructureEvent, type EpicStructureGraphPayload, type EpicStructureNodeStatus, EpicStructureValidationError, type EvidenceEmitArgs, type EvidenceEmitDependencies, type EvidenceEmitResult, type FactoryCliInvocation, FactoryCliInvocationSchema, type FactoryProjectProfile, type FactoryTraceDiagnostic, type FactoryTraceEnvelope, type FactoryTraceEvent, type FindingDisposition, type FindingLedgerEntry, type FollowUpAction, FollowUpActionSchema, type IssueReviewFocus, type LadderDispositionDeclaration, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, type MergeFreezeState, type ParsedRetroEnvelope, type PrPublishArgs, type PrPublishDependencies, PrPublishFollowUpError, type PrPublishFollowUpOutcome, type PrPublishHandoff, type PrPublishResult, type PrReadyArgs, type PrReadyProof, type PublishEpicStructureArgs, type PublishEpicStructureResult, type PublishFollowUpPlan, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, REVIEW_FOCUS_SECTION, type RetroEnvelope, type ReviewGateNotRequiredProof, type ReviewGateTraceIdentity, type ReviewLadderCycle, type ReviewLadderEvaluation, type ReviewLadderPolicy, type ReviewLadderStageEvent, type ReviewLadderTraceIdentity, type ReviewPromptSection, type ReviewPromptSectionProvenance, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, type ScanFactoryTraceDiagnosticsOptions, type ScanFactoryTraceOptions, type ScanFactoryTraceResult, type TraceMirrorDiagnostic, type TraceSink, type TraceWriteResult, type TraceWriteSinks, type VerificationReuse, type WaivedDemand, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendReviewLadderStageTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertWorkerCheckoutAllowed, authorizeDemandWaiver, blockingLadderFindings, boundary_manifest_d_exports as boundaryManifest, boundary_review_proof_d_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildRetroEnvelope, buildReviewGateNotRequiredTraceEvent, buildReviewLadderStageTraceEvent, comment_provenance_d_exports as commentProvenance, createLocalJsonlTraceSink, createProgram, doctorProjectProfile, epicStructureEventId, evaluateReviewLadder, evidenceEnvelopeFilename, findingKey, followUpFromArgv, inferFixedInThreadDispositions, isProductionHqUrl, isRetroEnvelopeWireComplete, loadProjectProfile, normalizeIssueComments, openLadderFindings, parseRetroEnvelope, planPublishFollowUp, worktree_held_branch_d_exports as prMergePreflight, pr_body_metadata_d_exports as prReadinessBodyMetadata, readiness_evaluation_d_exports as prReadinessEvaluation, external_evidence_d_exports as prReadinessExternalEvidence, merge_identity_d_exports as prReadinessMergeIdentity, post_readiness_comments_d_exports as prReadinessPostComments, pr_body_renderer_d_exports as prReadinessPrBodyRenderer, proof_identity_d_exports as prReadinessProofIdentity, review_proof_d_exports as prReadinessReviewProof, status_check_rollup_d_exports as prReadinessStatusChecks, verification_proof_d_exports as prReadinessVerificationProof, publishEpicStructure, readDemandWaivers, readPrMergeCheckProof, readPrReadyProof, readPrReviewProof, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, retroEnvelopeSchemaVersionOf, retroEnvelopeV1Schema, retroEpicReference, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runDemandWaive, runEvidenceEmit, runPrMergeCheck, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, selectWaiversForCandidate, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateDemandWaiverStore, validateFactoryTraceEvent, validateMergeFreezeState, validatePrMergeCheckProof, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_d_exports as worktreeScratchFiles };
+export { type AppendFactoryTraceEventResult, type AssembledReviewPrompt, type BoundaryCheckArgs, type BoundaryCheckDependencies, type BoundaryCheckProofRecord, type BuildEpicStructureEventInput, type BuildRetroEnvelopeInput, type CloudflareAccessServiceToken, CreateProgramOptions, DEFAULT_DEMAND_WAIVER_PATH, DEFAULT_FACTORY_REPOSITORY, type DagDocument, type DemandWaiveArgs, type DemandWaiveDependencies, DemandWaiveRefusalError, type DemandWaiver, type DemandWaiverStore, EPIC_STRUCTURE_NODE_STATUSES, EPIC_STRUCTURE_SCHEMA_VERSION, type EpicStructureEvent, type EpicStructureGraphPayload, type EpicStructureNodeStatus, EpicStructureValidationError, type EvidenceEmitArgs, type EvidenceEmitDependencies, type EvidenceEmitResult, type FactoryCliInvocation, FactoryCliInvocationSchema, type FactoryProjectProfile, type FactoryTraceDiagnostic, type FactoryTraceEnvelope, type FactoryTraceEvent, type FindingDisposition, type FindingLedgerEntry, type FollowUpAction, FollowUpActionSchema, type IssueReviewFocus, type LadderDispositionDeclaration, MERGE_FREEZE_APP_SLUG, MERGE_FREEZE_CHECK_NAME, type MergeFreezeState, type ParsedRetroEnvelope, type PrPublishArgs, type PrPublishDependencies, PrPublishFollowUpError, type PrPublishFollowUpOutcome, type PrPublishHandoff, type PrPublishResult, type PrReadyArgs, type PrReadyProof, type PublishEpicStructureArgs, type PublishEpicStructureResult, type PublishFollowUpPlan, RETRO_ENVELOPE_SCHEMA_VERSION, RETRO_ENVELOPE_VALIDATORS, REVIEW_FOCUS_SECTION, type RetroEnvelope, type ReviewGateNotRequiredProof, type ReviewGateTraceIdentity, type ReviewLadderCycle, type ReviewLadderEvaluation, type ReviewLadderPolicy, type ReviewLadderStageEvent, type ReviewLadderTraceIdentity, type ReviewPromptSection, type ReviewPromptSectionProvenance, SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS, type ScanFactoryTraceDiagnosticsOptions, type ScanFactoryTraceOptions, type ScanFactoryTraceResult, type TraceMirrorDiagnostic, type TraceSink, type TraceWriteResult, type TraceWriteSinks, type VerificationReuse, type WaivedDemand, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendReviewLadderStageTraceEvent, appendWithTraceSinks, applyDemandWaiver, assembleReviewPrompt, assertWorkerCheckoutAllowed, authorizeDemandWaiver, blockingLadderFindings, boundary_manifest_d_exports as boundaryManifest, boundary_review_proof_d_exports as boundaryReviewProof, buildEpicStructureEvent, buildEpicStructurePayload, buildEvidenceEnvelope, buildRetroEnvelope, buildReviewGateNotRequiredTraceEvent, buildReviewLadderStageTraceEvent, comment_provenance_d_exports as commentProvenance, createLocalJsonlTraceSink, createProgram, doctorProjectProfile, epicStructureEventId, evaluateReviewLadder, evidenceEnvelopeFilename, findingKey, followUpFromArgv, inferFixedInThreadDispositions, isProductionHqUrl, isRetroEnvelopeWireComplete, loadProjectProfile, normalizeIssueComments, openLadderFindings, parseRetroEnvelope, planPublishFollowUp, pr_body_metadata_d_exports as prReadinessBodyMetadata, readiness_evaluation_d_exports as prReadinessEvaluation, external_evidence_d_exports as prReadinessExternalEvidence, post_readiness_comments_d_exports as prReadinessPostComments, pr_body_renderer_d_exports as prReadinessPrBodyRenderer, proof_identity_d_exports as prReadinessProofIdentity, review_proof_d_exports as prReadinessReviewProof, status_check_rollup_d_exports as prReadinessStatusChecks, verification_proof_d_exports as prReadinessVerificationProof, publishEpicStructure, readDemandWaivers, readPrReadyProof, readPrReviewProof, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, retroEnvelopeSchemaVersionOf, retroEnvelopeV1Schema, retroEpicReference, 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, waivedDemandNotice, waivedDemandSchema, worktree_scratch_files_d_exports as worktreeScratchFiles };