@patronage/software-factory 0.20.0 → 0.25.0

package/dist/index.d.ts

@@ -1,10 +1,10 @@
 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 {
-  author_association?: string;
   body: string;
   created_at: string;
   html_url: string;
@@ -18,7 +18,6 @@ interface GithubIssueComment {
   author: {
     login?: string;
   };
-  authorAssociation?: string;
   body: string;
   createdAt: string;
   id: string;
@@ -168,6 +167,299 @@ 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";
+/** One recorded operator act: this demand, on this candidate, waived. */
+interface DemandWaiver {
+  candidate: {
+    headSha: string;
+    pr: number;
+  };
+  demand: string;
+  /** The authenticated GitHub account that recorded the waiver. */
+  operator: string;
+  rationale: string;
+  recordedAt: string;
+  /** The operator session the waiver was recorded in. */
+  session: string;
+}
+interface DemandWaiverStore {
+  command: "patronage-factory demand:waive";
+  schemaVersion: 1;
+  waivers: DemandWaiver[];
+}
+declare const validateDemandWaiverStore: (value: unknown) => DemandWaiverStore;
+/**
+ * A demand that was in force, was NOT met, and was waived by the operator.
+ *
+ * `unmetReasons` is required and non-empty: every reason the demand refused is
+ * carried through verbatim. There is no field on this record that could say
+ * "satisfied", and no code path constructs one without a refusal to carry.
+ */
+interface WaivedDemand {
+  demand: string;
+  operator: string;
+  rationale: string;
+  recordedAt: string;
+  session: string;
+  /** The demand's refusals at evaluation time, preserved verbatim. */
+  unmetReasons: string[];
+}
+declare const waivedDemandSchema: z.ZodType<WaivedDemand>;
+/** The waivers that bind one candidate: same PR, same head. */
+declare const selectWaiversForCandidate: ({
+  headSha,
+  pr,
+  waivers
+}: {
+  headSha: string | undefined;
+  pr: number;
+  waivers: readonly DemandWaiver[];
+}) => DemandWaiver[];
+interface DemandOutcome {
+  blockingReasons: string[];
+  waived?: WaivedDemand;
+}
+/**
+ * Fold one resolved demand's refusals through the operator's waivers.
+ *
+ * A satisfied demand (no refusals) stays satisfied and the waiver stays inert
+ * — a waiver can only ever move a demand from *unmet-and-blocking* to
+ * *unmet-and-waived*, never to met.
+ */
+declare const applyDemandWaiver: ({
+  demand,
+  reasons,
+  waivers
+}: {
+  demand: string;
+  reasons: readonly string[];
+  waivers: readonly DemandWaiver[];
+}) => DemandOutcome;
+/** How a waived demand reads to a human. Never the word "satisfied". */
+declare const waivedDemandNotice: (waived: WaivedDemand) => string;
+interface DemandWaiverAuthorization {
+  operator: string;
+  session: string;
+}
+type AuthorizeDemandWaiverResult = {
+  authorization: DemandWaiverAuthorization;
+  refusals?: undefined;
+} | {
+  authorization?: undefined;
+  refusals: string[];
+};
+/**
+ * Operator identity, `declaredBy`-style: a named human account, recorded on
+ * the waiver and enforced here — plus session distinctness from the candidate
+ * the waiver applies to. Every refusal is named; nothing falls open.
+ */
+declare const authorizeDemandWaiver: ({
+  authenticatedLogin,
+  authoringSession,
+  session
+}: {
+  authenticatedLogin: string | undefined;
+  authoringSession: string | undefined;
+  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/checkout-repository.d.ts
 interface CheckoutRepository {
@@ -218,281 +510,46 @@ interface GithubPullRequestReview {
   url: string;
 }
 //#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/profile.d.ts
-declare const DEFAULT_FACTORY_REPOSITORY = "unknown/unknown";
-/** The one profile shape this build accepts (ADR 0023, #318). */
-declare const PROFILE_SCHEMA_VERSION = 3;
-declare const factoryProjectProfileSchema: z.ZodObject<{
-  $schema: z.ZodOptional<z.ZodString>;
-  env: z.ZodOptional<z.ZodObject<{
-    required: z.ZodArray<z.ZodString>;
-  }, z.core.$strict>>;
-  extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-  hq: z.ZodOptional<z.ZodObject<{
-    enabled: z.ZodBoolean;
-    endpoint: z.ZodIntersection<z.ZodString, z.ZodString>;
-  }, z.core.$strict>>;
-  project: z.ZodObject<{
-    key: z.ZodString;
-  }, z.core.$strict>;
-  proof: z.ZodObject<{
-    classificationPolicy: z.ZodObject<{
-      docsOnly: z.ZodDefault<z.ZodArray<z.ZodString>>;
-      trivial: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    }, z.core.$strict>;
-  }, z.core.$strict>;
-  repository: z.ZodObject<{
-    defaultBranch: z.ZodString;
-    name: z.ZodString;
-    owner: z.ZodString;
-  }, z.core.$strict>;
-  requiredChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
-    checkType: z.ZodEnum<{
-      review: "review";
-      verify: "verify";
-    }>;
-    name: z.ZodString;
-    scope: z.ZodOptional<z.ZodObject<{
-      classifications: z.ZodOptional<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<{
-    conditional: z.ZodOptional<z.ZodArray<z.ZodObject<{
-      modes: z.ZodArray<z.ZodEnum<{
-        correctness: "correctness";
-        security: "security";
-      }>>;
-      paths: z.ZodArray<z.ZodString>;
-    }, z.core.$strict>>>;
-    defaultMaxCycles: z.ZodNumber;
-    docsOnlyBypass: z.ZodOptional<z.ZodBoolean>;
-    ladder: z.ZodOptional<z.ZodObject<{
-      gate: z.ZodOptional<z.ZodObject<{
-        cap: z.ZodNumber;
-      }, z.core.$strict>>;
-    }, z.core.$strict>>;
-    modes: z.ZodArray<z.ZodEnum<{
-      correctness: "correctness";
-      security: "security";
-    }>>;
-    standingChecklist: z.ZodOptional<z.ZodArray<z.ZodString>>;
-  }, z.core.$strict>;
-  schemaVersion: z.ZodLiteral<3>;
-  verification: z.ZodObject<{
-    commands: z.ZodArray<z.ZodObject<{
-      command: z.ZodString;
-      description: z.ZodString;
-      name: z.ZodString;
-      requiredCheck: z.ZodOptional<z.ZodString>;
-      scope: z.ZodDefault<z.ZodEnum<{
-        trivial: "trivial";
-        "docs-only": "docs-only";
-        full: "full";
-      }>>;
-    }, z.core.$strip>>;
-  }, z.core.$strip>;
-}, z.core.$strict>;
-type FactoryProjectProfile = z.infer<typeof factoryProjectProfileSchema>;
-declare const resolveFactoryRepository: (profile?: Pick<FactoryProjectProfile, "repository"> | undefined) => string;
-/**
- * Whether a pure docs/process diff may skip independent review. Opt-in: absent
- * config means review is required (#318, ADR 0023).
- */
-declare const resolveDocsOnlyReviewBypass: (profile: Pick<FactoryProjectProfile, "review">) => boolean;
-interface LoadProjectProfileInput {
-  cwd?: string;
-  profilePath?: string;
-}
-interface LoadProjectProfileResult {
-  path: string;
-  profile: FactoryProjectProfile;
-}
-declare function loadProjectProfile(input?: LoadProjectProfileInput): LoadProjectProfileResult;
-//#endregion
-//#region src/pr-verify-mode.d.ts
-/**
- * The verification mode `pr:verify` resolved for a run.
- *
- * Canonically declared here rather than inside `pr-readiness/` so that modules
- * on either side of that boundary — the readiness proof shape and the durable
- * check-run payload — can name the same union without importing each other.
- */
-type ResolvedPrVerifyMode = "docs-only" | "trivial" | "full";
-//#endregion
-//#region src/pr-verify-status.d.ts
-type CommitStatusState = "failure" | "pending" | "success";
-interface PostCommitStatusInput {
-  context?: string;
-  cwd: string;
-  description: string;
-  owner: string;
-  repo: string;
-  sha: string;
-  state: CommitStatusState;
-  /**
-   * Drop this mirror's own failure diagnostic because the caller has already
-   * reported the same cause. Set only on the pre-push path, where the status
-   * POST 422s for exactly the reason the pre-push notice gives and a trailing
-   * "unable to post ... status" line would put back the false-defect reading
-   * that notice exists to remove (#316).
-   *
-   * Deliberately a field on the request rather than a second, quieter poster:
-   * an injected `PostCommitStatus` double sees the flag, so the branch is
-   * assertable instead of collapsing to the same closure under test.
-   */
-  suppressFailureDiagnostic?: boolean;
-  targetUrl: string;
-}
-type PostCommitStatus = (input: PostCommitStatusInput) => void;
-//#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>>;
-  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-check-runs.d.ts
-declare const FACTORY_CHECK_NAMES: {
-  readonly boundary: "patronage-factory/boundary";
-  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;
-interface PublishFactoryCheckInput {
-  conclusion?: "failure" | "success";
-  cwd: string;
-  gate: FactoryCheckGate;
-  /**
-   * HQ lane-permalink base (`<origin>/lanes/by-ref`). When present, the check
-   * run's Details link deep-links to the HQ lane page instead of the PR-ledger
-   * fallback. Derive it from the repository profile via
-   * `hqLaneRefBaseUrlFromProfile` — the same source as the HQ gate sink.
-   */
-  hqLaneBaseUrl?: string;
-  /**
-   * Explicit issue/PR number for the HQ lane ref, used when the check run is not
-   * PR-scoped (e.g. an epic boundary check keyed by its epic issue). Falls back
-   * to `pr`, then to the checkout's PR, when omitted.
-   */
-  laneRefNumber?: number;
-  owner: string;
-  pr?: number;
-  proof: unknown;
-  repo: string;
-  sha: string;
-  status?: "completed" | "in_progress";
-}
-interface CheckRunDependencies {
-  fetch?: typeof fetch;
-  githubApp?: GithubAppConfig;
-  now?: () => number;
-  postCommitStatus?: PostCommitStatus;
-  resolveDetailsUrl?: (input: PublishFactoryCheckInput) => 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.
-   */
-  retry?: {
-    attempts: number;
-    budgetMs?: number;
-    delayMs: number;
-  };
-  /** Injectable delay for the bounded retry (tests only). */
-  sleep?: (ms: number) => Promise<void>;
-  /** Overrides GITHUB_PUBLISH_TIMEOUT_MS for the App fetch calls (tests only). */
-  timeoutMs?: number;
-}
+//#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>;
 /**
- * Publish a factory check run and *wait* for it, so a caller that has just made
- * the head SHA visible on GitHub (pushed the branch, created the PR) can make
- * the proof reliably present for that SHA before it returns (#247).
- *
- * Never throws and never posts a commit-status fallback: the commit status is a
- * human-readable mirror, not a proof surface, so a caller that needs an
- * App-verified check run must be told plainly whether it got one. Returns
- * `true` only when the App-owned check run landed.
+ * 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 ensureFactoryCheckRunPublished(input: PublishFactoryCheckInput, dependencies?: CheckRunDependencies & {
-  onDiagnostic?: (message: string) => void;
-}): Promise<boolean>;
-interface PublishHandledCommentsCheckInput {
-  cwd: string;
-  owner: string;
-  payload: HandledCommentsCheckPayload;
-  pr: number;
-  repo: string;
-  sha: string;
-}
-//#endregion
-//#region src/merge-freeze.d.ts
-interface MergeFreezeGeneration {
-  headSha: string;
-  id: number;
-  startedAt: string;
-}
+declare function validateMergeFreezeState(value: unknown): MergeFreezeState;
 interface MergeFreezeStoreInput {
   cwd: string;
   headSha: string;
   repository: CheckoutRepository;
 }
 interface MergeFreezeStore {
-  complete: (input: MergeFreezeStoreInput & {
-    clearRationale?: string;
-    generation: MergeFreezeGeneration;
-    outcome: "active" | "inactive" | "stale";
-    reason: string;
-  }) => Promise<void>;
   read: (input: MergeFreezeStoreInput) => unknown;
-  start: (input: MergeFreezeStoreInput) => Promise<MergeFreezeGeneration>;
 }
 declare namespace worktree_held_branch_d_exports {
   export { MergeOperationalNotices, WorktreeHeldBranch, WorktreeHeldBranchCheck, WorktreeListEntry, checkWorktreeHeldBranch, findWorktreeHeldBranch, formatHeldBranchCloseoutSummary, listWorktreesPorcelain, parseGitWorktreeList, resolveMergeOperationalNotices, worktreeHeldBranchNotice };
@@ -670,6 +727,96 @@ declare const resolveMergeGuardIdentity: ({
 declare const mergeGuardIdentitySchema: z.ZodType<MergeGuardIdentity>;
 declare const mergeGuardBlockingReasons: (identity: MergeGuardIdentity) => string[];
 //#endregion
+//#region src/profile.d.ts
+declare const DEFAULT_FACTORY_REPOSITORY = "unknown/unknown";
+/** The one profile shape this build accepts (ADR 0023, #318, #351). */
+declare const PROFILE_SCHEMA_VERSION = 4;
+declare const factoryProjectProfileSchema: z.ZodObject<{
+  $schema: z.ZodOptional<z.ZodString>;
+  env: z.ZodOptional<z.ZodObject<{
+    required: z.ZodArray<z.ZodString>;
+  }, z.core.$strict>>;
+  extensions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+  hq: z.ZodOptional<z.ZodObject<{
+    enabled: z.ZodBoolean;
+    endpoint: z.ZodIntersection<z.ZodString, z.ZodString>;
+  }, z.core.$strict>>;
+  project: z.ZodObject<{
+    key: z.ZodString;
+  }, z.core.$strict>;
+  proof: z.ZodObject<{
+    classificationPolicy: z.ZodObject<{
+      docsOnly: z.ZodDefault<z.ZodArray<z.ZodString>>;
+      trivial: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>;
+  }, z.core.$strict>;
+  repository: z.ZodObject<{
+    defaultBranch: z.ZodString;
+    name: z.ZodString;
+    owner: z.ZodString;
+  }, z.core.$strict>;
+  requiredChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    checkType: z.ZodEnum<{
+      review: "review";
+      verify: "verify";
+    }>;
+    name: z.ZodString;
+    scope: z.ZodOptional<z.ZodObject<{
+      classifications: z.ZodOptional<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<{
+    conditional: z.ZodOptional<z.ZodArray<z.ZodObject<{
+      modes: z.ZodArray<z.ZodEnum<{
+        correctness: "correctness";
+        security: "security";
+      }>>;
+      paths: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>>;
+    defaultMaxCycles: z.ZodNumber;
+    ladder: z.ZodOptional<z.ZodObject<{
+      gate: z.ZodOptional<z.ZodObject<{
+        cap: z.ZodNumber;
+      }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    modes: z.ZodArray<z.ZodEnum<{
+      correctness: "correctness";
+      security: "security";
+    }>>;
+    standingChecklist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>;
+  schemaVersion: z.ZodLiteral<4>;
+  verification: z.ZodObject<{
+    commands: z.ZodArray<z.ZodObject<{
+      command: z.ZodString;
+      description: z.ZodString;
+      name: z.ZodString;
+      requiredCheck: z.ZodOptional<z.ZodString>;
+      scope: z.ZodDefault<z.ZodEnum<{
+        trivial: "trivial";
+        "docs-only": "docs-only";
+        full: "full";
+      }>>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>;
+}, z.core.$strict>;
+type FactoryProjectProfile = z.infer<typeof factoryProjectProfileSchema>;
+declare const resolveFactoryRepository: (profile?: Pick<FactoryProjectProfile, "repository"> | undefined) => string;
+interface LoadProjectProfileInput {
+  cwd?: string;
+  profilePath?: string;
+}
+interface LoadProjectProfileResult {
+  path: string;
+  profile: FactoryProjectProfile;
+}
+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];
@@ -715,13 +862,19 @@ interface PrMergeCheckProof {
   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 {
-  changedFilesBetween: (cwd: string, baseSha: string, headSha: string) => string[] | undefined;
   checkoutRepository: (cwd: string) => CheckoutRepository;
   commitsBetween: (cwd: string, fromSha: string, toSha: string) => PostProofCommit[] | undefined;
   worktreeListPorcelain: (cwd: string) => string | undefined;
@@ -771,6 +924,169 @@ 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.
+ *
+ * Canonically declared here rather than inside `pr-readiness/` so that modules
+ * on either side of that boundary — the readiness proof shape and the durable
+ * check-run payload — can name the same union without importing each other.
+ */
+type ResolvedPrVerifyMode = "docs-only" | "trivial" | "full";
+//#endregion
+//#region src/pr-verify-status.d.ts
+type CommitStatusState = "failure" | "pending" | "success";
+interface PostCommitStatusInput {
+  context?: string;
+  cwd: string;
+  description: string;
+  owner: string;
+  repo: string;
+  sha: string;
+  state: CommitStatusState;
+  /**
+   * Drop this mirror's own failure diagnostic because the caller has already
+   * reported the same cause. Set only on the pre-push path, where the status
+   * POST 422s for exactly the reason the pre-push notice gives and a trailing
+   * "unable to post ... status" line would put back the false-defect reading
+   * that notice exists to remove (#316).
+   *
+   * Deliberately a field on the request rather than a second, quieter poster:
+   * an injected `PostCommitStatus` double sees the flag, so the branch is
+   * assertable instead of collapsing to the same closure under test.
+   */
+  suppressFailureDiagnostic?: boolean;
+  targetUrl: string;
+}
+type PostCommitStatus = (input: PostCommitStatusInput) => void;
+//#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-check-runs.d.ts
+declare const FACTORY_CHECK_NAMES: {
+  readonly boundary: "patronage-factory/boundary";
+  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;
+interface PublishFactoryCheckInput {
+  conclusion?: "failure" | "success";
+  cwd: string;
+  gate: FactoryCheckGate;
+  /**
+   * HQ lane-permalink base (`<origin>/lanes/by-ref`). When present, the check
+   * run's Details link deep-links to the HQ lane page instead of the PR-ledger
+   * fallback. Derive it from the repository profile via
+   * `hqLaneRefBaseUrlFromProfile` — the same source as the HQ gate sink.
+   */
+  hqLaneBaseUrl?: string;
+  /**
+   * Explicit issue/PR number for the HQ lane ref, used when the check run is not
+   * PR-scoped (e.g. an epic boundary check keyed by its epic issue). Falls back
+   * to `pr`, then to the checkout's PR, when omitted.
+   */
+  laneRefNumber?: number;
+  owner: string;
+  pr?: number;
+  proof: unknown;
+  repo: string;
+  sha: string;
+  status?: "completed" | "in_progress";
+}
+interface CheckRunDependencies {
+  fetch?: typeof fetch;
+  githubApp?: GithubAppConfig;
+  now?: () => number;
+  postCommitStatus?: PostCommitStatus;
+  resolveDetailsUrl?: (input: PublishFactoryCheckInput) => 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.
+   */
+  retry?: {
+    attempts: number;
+    budgetMs?: number;
+    delayMs: number;
+  };
+  /** Injectable delay for the bounded retry (tests only). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Overrides GITHUB_PUBLISH_TIMEOUT_MS for the App fetch calls (tests only). */
+  timeoutMs?: number;
+}
+/**
+ * Publish a factory check run and *wait* for it, so a caller that has just made
+ * the head SHA visible on GitHub (pushed the branch, created the PR) can make
+ * the proof reliably present for that SHA before it returns (#247).
+ *
+ * Never throws and never posts a commit-status fallback: the commit status is a
+ * human-readable mirror, not a proof surface, so a caller that needs an
+ * App-verified check run must be told plainly whether it got one. Returns
+ * `true` only when the App-owned check run landed.
+ */
+declare function ensureFactoryCheckRunPublished(input: PublishFactoryCheckInput, dependencies?: CheckRunDependencies & {
+  onDiagnostic?: (message: string) => void;
+}): Promise<boolean>;
+interface PublishHandledCommentsCheckInput {
+  cwd: string;
+  owner: string;
+  payload: HandledCommentsCheckPayload;
+  pr: number;
+  repo: string;
+  sha: string;
+}
+//#endregion
 //#region src/pr-proof-io.d.ts
 interface ProofDescriptor<T> {
   label: string;
@@ -1064,7 +1380,7 @@ interface PrReviewProof {
   cleanedPaths: string[];
   ladder?: PrReviewLadderState;
   reviewRequirement?: {
-    reason: "docs-only-profile-bypass";
+    reason: "no-applicable-mode";
     status: "not-required";
   };
   reviews: PrReviewResult[];
@@ -1280,8 +1596,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>;
@@ -1293,8 +1609,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>>;
@@ -1311,8 +1627,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>;
@@ -1349,6 +1665,7 @@ interface PrReadyArgs extends LoadProjectProfileInput {
   authoringSessionIds?: string[];
   base: string;
   bodyForEvaluation?: string;
+  epic?: number;
   handledCommentUrls?: string[];
   json?: boolean;
   output?: string;
@@ -1396,7 +1713,15 @@ interface GitHubPullRequest {
   url: string;
 }
 interface PrReadyProof {
-  schemaVersion: 1;
+  schemaVersion: 2;
+  /**
+   * 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";
@@ -1427,6 +1752,18 @@ interface PrReadyProof {
 type PublishHandledCommentsResult = HandledCommentsProducer | Promise<HandledCommentsProducer | undefined> | undefined;
 interface PrReadyDependencies {
   github?: {
+    fetchClosingPullRequests?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => {
+      number: number;
+    }[];
+    fetchIssueBody?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => string;
     fetchHandledComments?: (input: {
       owner: string;
       pr: number;
@@ -1484,7 +1821,7 @@ declare const requiredCheckScopeSchema: z.ZodObject<{
 type RequiredCheckScope = z.infer<typeof requiredCheckScopeSchema>;
 interface RequiredCheckScopeContext {
   labels: string[] | undefined;
-  classification: DiffClassification;
+  classification: DiffClassification | undefined;
 }
 interface ScopeDecision {
   inScope: boolean;
@@ -1647,8 +1984,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>;
@@ -1913,15 +2250,195 @@ declare const resolveVerifyProofApplicability: ({
   fullVerifiedHeadShas: never[];
   verificationProof: VerificationProofState;
 } | {
-  fullVerifiedHeadShas: string[];
-  verificationProof: {
-    headShas: VerifiedHeadShas;
-    kind: "typed";
-    proof: PrVerifyProof;
-  };
+  fullVerifiedHeadShas: string[];
+  verificationProof: {
+    headShas: VerifiedHeadShas;
+    kind: "typed";
+    proof: PrVerifyProof;
+  };
+};
+declare const verificationProofForReadiness: (state: VerificationProofState) => VerificationHeadShas;
+declare const verificationProofBlockingReason: (state: VerificationProofState) => string | undefined;
+//#endregion
+//#region src/retro-envelope.d.ts
+/**
+ * Versioned retro envelope schema (epic #27 wave 2, issue #34).
+ *
+ * One envelope per lane, built at `factory:closeout` and delivered through the
+ * typed gate-sink as the `retro-envelope` ingest kind. Re-derived in TypeScript
+ * from the `spike/telemetry-layer2` S5 scratch schema (reference-only, never
+ * merged). This module is the single source of truth for the v1 wire shape
+ * and its bounds ({@link RETRO_ENVELOPE_WIRE_BOUNDS}) — producer and consumer
+ * alike. HQ imports these exports directly from the Worker-safe
+ * `@patronage/software-factory/schemas` subpath
+ * (`software-factory-hq/src/contracts/retro-schemas.ts`) instead of
+ * maintaining a parallel hand-written copy, so there is exactly one wire
+ * contract and no drift-detection machinery is needed (issue #350; formerly
+ * a hand-written twin plus a 767-line parity test, #46).
+ *
+ * DESIGN INVARIANT: cross-family token sums must be UNREPRESENTABLE.
+ *
+ * The two model families use different tokenizers, prices, and accounting
+ * conventions, so any token total that spans Claude and GPT is a lie:
+ *
+ * 1. There is no combined/total token field anywhere in the envelope.
+ * 2. `tokenFamilies` is strict — its only keys are `claude` and `gpt`; data
+ *    cannot smuggle in a third "all"/"combined" slot.
+ * 3. The family BLOCKS are structurally different shapes with DIFFERENT keys
+ *    (claude is a single flat block keyed on freshInput/cacheReadInput/
+ *    cacheCreationInput; gpt is `{ roles: [...] }`). The exclusive input-tier
+ *    COUNTS share no key name across families. The residual names shared
+ *    between the claude block and a gpt ROLE entry are pinned to exactly
+ *    {costUsd, model, output} (PR #32 advisory): `costUsd` is deliberate —
+ *    USD is the one cross-family summable unit (rule 4); `model` is an
+ *    unsummable label; `output` is the same name at DIFFERENT depths (lane
+ *    block vs per-role entry), frozen by a tripwire test in
+ *    `retro-envelope.test.ts` so the overlap cannot grow. Renaming `output`
+ *    is a schemaVersion-2 wire change, deliberately not spent in v1.
+ * 4. Cost is per-family USD and nullable. Combined totals are allowed in USD
+ *    only, and only as a projection-time sum of per-family USD.
+ *
+ * Field names also encode the S2/S3 reader lessons: Claude `freshInput` alone
+ * is not prompt size (true input context = freshInput + cacheReadInput +
+ * cacheCreationInput, requestId-deduped), and codex `inputInclusiveOfCache`
+ * already includes `cachedInput`, so `freshInputDerived` (inclusive − cached)
+ * is the only value safe to feed a per-token pricer.
+ *
+ * COMPLETENESS POSTURE: harvest may have no usable native log for a lane, so
+ * `tokenFamilies` may legitimately be absent. The closeout build gate demands
+ * a valid envelope, not available telemetry. A families-absent envelope keeps
+ * its operator-visible data gaps and is a replayable advisory HQ event, so it
+ * never substitutes unavailable usage with zero. The wire shape (field names,
+ * types, structure) stays byte-parity with HQ v1.
+ */
+declare const RETRO_ENVELOPE_SCHEMA_VERSION = 1;
+declare const retroEnvelopeV1Schema: z.ZodObject<{
+  agentRunId: z.ZodString;
+  archiveRef: z.ZodOptional<z.ZodString>;
+  cycles: z.ZodObject<{
+    gateRunsToFirstGreen: z.ZodNumber;
+    reviewerFixRounds: z.ZodNumber;
+    thermoFixRounds: z.ZodNumber;
+  }, z.core.$strict>;
+  dataGaps: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  gates: z.ZodArray<z.ZodObject<{
+    cycle: z.ZodNumber;
+    duration: z.ZodNumber;
+    gate: z.ZodString;
+    outcome: z.ZodEnum<{
+      pass: "pass";
+      fail: "fail";
+      skip: "skip";
+    }>;
+    startedAt: z.ZodISODateTime;
+  }, z.core.$strict>>;
+  generatedAt: z.ZodISODateTime;
+  interventions: z.ZodObject<{
+    count: z.ZodNumber;
+  }, z.core.$strict>;
+  joinKeys: z.ZodObject<{
+    claudeSessionIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    codexThreadIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
+  }, z.core.$strict>;
+  kind: z.ZodLiteral<"retro-envelope">;
+  outcome: z.ZodOptional<z.ZodObject<{
+    mergeCheck: z.ZodOptional<z.ZodEnum<{
+      pass: "pass";
+      fail: "fail";
+      "not-run": "not-run";
+    }>>;
+    status: z.ZodEnum<{
+      success: "success";
+      fail: "fail";
+      blocked: "blocked";
+      "ship-with-followups": "ship-with-followups";
+    }>;
+    verdict: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  phases: z.ZodArray<z.ZodObject<{
+    at: z.ZodISODateTime;
+    deltaSec: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodString;
+  }, z.core.$strict>>;
+  refs: z.ZodObject<{
+    branch: z.ZodOptional<z.ZodString>;
+    epic: z.ZodOptional<z.ZodString>;
+    headSha: z.ZodOptional<z.ZodString>;
+    issue: z.ZodOptional<z.ZodString>;
+    prNumber: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>;
+  repo: z.ZodObject<{
+    name: z.ZodString;
+    owner: z.ZodString;
+  }, z.core.$strict>;
+  schemaVersion: z.ZodLiteral<1>;
+  tokenFamilies: z.ZodObject<{
+    claude: z.ZodOptional<z.ZodObject<{
+      cacheCreationInput: z.ZodNumber;
+      cacheReadInput: z.ZodNumber;
+      costUsd: z.ZodNullable<z.ZodNumber>;
+      family: z.ZodLiteral<"claude">;
+      freshInput: z.ZodNumber;
+      model: z.ZodString;
+      output: z.ZodNumber;
+      requests: z.ZodNumber;
+    }, z.core.$strict>>;
+    gpt: z.ZodOptional<z.ZodObject<{
+      family: z.ZodLiteral<"gpt">;
+      roles: z.ZodArray<z.ZodObject<{
+        cachedInput: z.ZodNumber;
+        costUsd: z.ZodNullable<z.ZodNumber>;
+        freshInputDerived: z.ZodNumber;
+        inputInclusiveOfCache: z.ZodNumber;
+        model: z.ZodString;
+        output: z.ZodNumber;
+        reasoningOutput: z.ZodNumber;
+        role: z.ZodString;
+        threadId: z.ZodOptional<z.ZodString>;
+      }, z.core.$strict>>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>;
+  wallClock: z.ZodObject<{
+    endTs: z.ZodISODateTime;
+    startTs: z.ZodISODateTime;
+    totalSec: z.ZodNumber;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+type RetroEnvelope = z.infer<typeof retroEnvelopeV1Schema>;
+/**
+ * Versioned payload validators, keyed by schema major. Unknown majors never
+ * reach these — {@link parseRetroEnvelope} returns them raw and marked
+ * degraded, mirroring HQ's ingest skew posture (stored raw, never dropped).
+ */
+declare const RETRO_ENVELOPE_VALIDATORS: Record<number, z.ZodType<RetroEnvelope, unknown>>;
+declare const SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS: readonly number[];
+/** The `schemaVersion` a candidate declares, or undefined when unreadable. */
+declare const retroEnvelopeSchemaVersionOf: (candidate: unknown) => number | undefined;
+type ParsedRetroEnvelope = {
+  disposition: "trusted";
+  envelope: RetroEnvelope;
+  schemaVersion: number;
+} | {
+  disposition: "degraded";
+  raw: unknown;
+  schemaVersion: number | undefined;
 };
-declare const verificationProofForReadiness: (state: VerificationProofState) => VerificationHeadShas;
-declare const verificationProofBlockingReason: (state: VerificationProofState) => string | undefined;
+/**
+ * Parses a candidate against the versioned validators. A recognized major is
+ * validated typed-only (throws on an invalid known-version payload); an unknown
+ * major is round-tripped RAW and marked degraded — the retained payload is the
+ * exact input object, never a coerced projection. Mirrors the HQ ingest seam so
+ * the two sides agree on the skew posture.
+ */
+declare const parseRetroEnvelope: (candidate: unknown) => ParsedRetroEnvelope;
+/**
+ * Whether harvest recorded at least one token family. This is an operator
+ * summary predicate, not a delivery gate: a families-absent envelope remains
+ * valid and replayable when its data gaps explain why telemetry is unavailable.
+ */
+declare const isRetroEnvelopeWireComplete: (envelope: Pick<RetroEnvelope, "tokenFamilies">) => boolean;
+/** Epic anchor for an envelope: refs.epic, else refs.issue, else the PR. */
+declare const retroEpicReference: (refs: RetroEnvelope["refs"]) => string | undefined;
 //#endregion
 //#region src/schemas.d.ts
 declare const boundaryCheckProofSchema: z.ZodObject<{
@@ -2015,90 +2532,166 @@ interface CliOutput {
 //#region src/commands/boundary-check.d.ts
 type BoundaryCheckAction = (args: BoundaryCheckArgs) => BoundaryCheckProofRecord;
 //#endregion
-//#region src/workspace-install-resolution.d.ts
-interface CleanInstallResolutionDependencies {
-  existsSync?: typeof existsSync;
-  readFileSync?: typeof readFileSync;
-  rmSync?: typeof rmSync;
-  runInstall?: (repoRoot: string) => void;
+//#region src/demand-waive.d.ts
+/** Every waiver recorded in this checkout; an absent or unreadable store is
+ * no waivers, so a damaged file can only ever block, never permit. */
+declare const readDemandWaivers: (cwd: string, filePath?: string) => DemandWaiver[];
+interface DemandWaiveArgs {
+  cwd?: string;
+  demand: string;
+  json?: boolean;
+  output?: string;
+  pr: number;
+  rationale: string;
+}
+interface DemandWaiveDependencies {
+  checkoutRepository?: (cwd: string) => CheckoutRepository;
+  env?: NodeJS.ProcessEnv;
+  fetchAuthenticatedLogin?: (cwd: string) => string | undefined;
+  fetchPullRequestHeadSha?: (input: {
+    cwd: string;
+    owner: string;
+    pr: number;
+    repo: string;
+  }) => string | undefined;
+  now?: () => Date;
+}
+declare class DemandWaiveRefusalError extends Error {
+  readonly refusals: string[];
+  constructor(refusals: string[]);
 }
+/**
+ * Record one waiver. One step: the operator names the demand, the candidate,
+ * and why. No confirmation, no second approval, no cooldown — the trust model
+ * puts the bar at operator identity, not at ceremony aimed at the operator
+ * (ADR 0025).
+ */
+declare const runDemandWaive: (args: DemandWaiveArgs, dependencies?: DemandWaiveDependencies) => DemandWaiver;
 //#endregion
-//#region src/pr-verify.d.ts
-type PrVerifyMode = "auto" | "docs-only" | "trivial" | "full";
-interface VerificationCommandOutcome {
-  counts?: {
-    testFiles?: number;
-    tests?: number;
-  };
-  durationMs: number;
-  exitCode: number;
+//#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;
+//#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-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[];
 }
-interface PrVerifyArgs extends LoadProjectProfileInput {
-  authoringSession?: string;
+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 {
   base: string;
-  mode: PrVerifyMode;
+  cycle: number;
+  dispositions?: string;
+  findings?: string;
+  issue?: number;
+  maxCycles?: number;
+  mode: PrReviewMode;
   output?: string;
-  requireKnownAuthoringSession?: boolean;
+  verifyProof?: string;
 }
-interface PrVerifyGitDependencies {
+interface PrReviewGitDependencies {
   changedFiles: (cwd: string, base: string) => string[];
   currentHeadSha: (cwd: string) => string;
-  emptyTreeHash: (cwd: string) => string;
-  mergeBaseSha: (cwd: string, base: string) => string;
-  runVerificationCommand: (command: string, cwd: string, env: Record<string, string>) => VerificationCommandOutcome;
-  statusPorcelain: (cwd: string) => string;
+  isAncestor: (cwd: string, ancestor: string, descendant: string) => boolean;
   stablePatchId: (cwd: string, base: string) => string;
+  statusPorcelain: (cwd: string) => string;
 }
-interface PrVerifyDependencies {
-  cleanInstall?: CleanInstallResolutionDependencies | false;
-  env?: NodeJS.ProcessEnv;
-  git?: PrVerifyGitDependencies;
+interface PrReviewDependencies {
+  git?: PrReviewGitDependencies;
   hq?: HqIngestDependencies;
-  postCommitStatus?: PostCommitStatus;
   publishCheckRun?: (input: PublishFactoryCheckInput) => void;
 }
-declare function runPrVerify(args: PrVerifyArgs, dependencies?: PrVerifyDependencies): PrVerifyProof;
+declare function runPrReview(args: PrReviewArgs, dependencies?: PrReviewDependencies): Promise<PrReviewProof>;
 //#endregion
-//#region src/canary-verify.d.ts
-interface CanaryVerifyArgs extends LoadProjectProfileInput {
-  /** Lift an active merge freeze without running verification. */
-  clear?: boolean;
-  output?: string;
-  /** Required with --clear; recorded on the canary proof. */
-  rationale?: string;
+//#region src/workspace-install-resolution.d.ts
+interface CleanInstallResolutionDependencies {
+  existsSync?: typeof existsSync;
+  readFileSync?: typeof readFileSync;
+  rmSync?: typeof rmSync;
+  runInstall?: (repoRoot: string) => void;
 }
 //#endregion
-//#region src/commands/canary-verify.d.ts
-type CanaryVerifyAction = (args: CanaryVerifyArgs) => Promise<unknown> | unknown;
-//#endregion
-//#region src/commands/pr-merge-check.d.ts
-type PrMergeCheckAction = (args: PrMergeCheckArgs) => PrMergeCheckProof;
-//#endregion
-//#region src/pr-review.d.ts
-interface PrReviewArgs extends LoadProjectProfileInput {
+//#region src/pr-verify.d.ts
+type PrVerifyMode = "auto" | "docs-only" | "trivial" | "full";
+interface VerificationCommandOutcome {
+  counts?: {
+    testFiles?: number;
+    tests?: number;
+  };
+  durationMs: number;
+  exitCode: number;
+}
+interface PrVerifyArgs extends LoadProjectProfileInput {
+  authoringSession?: string;
   base: string;
-  cycle: number;
-  dispositions?: string;
-  findings?: string;
-  issue?: number;
-  maxCycles?: number;
-  mode: PrReviewMode;
+  mode: PrVerifyMode;
   output?: string;
-  verifyProof?: string;
+  requireKnownAuthoringSession?: boolean;
 }
-interface PrReviewGitDependencies {
+interface PrVerifyGitDependencies {
   changedFiles: (cwd: string, base: string) => string[];
   currentHeadSha: (cwd: string) => string;
-  isAncestor: (cwd: string, ancestor: string, descendant: string) => boolean;
-  stablePatchId: (cwd: string, base: string) => string;
+  emptyTreeHash: (cwd: string) => string;
+  mergeBaseSha: (cwd: string, base: string) => string;
+  runVerificationCommand: (command: string, cwd: string, env: Record<string, string>) => VerificationCommandOutcome;
   statusPorcelain: (cwd: string) => string;
+  stablePatchId: (cwd: string, base: string) => string;
 }
-interface PrReviewDependencies {
-  git?: PrReviewGitDependencies;
+interface PrVerifyDependencies {
+  cleanInstall?: CleanInstallResolutionDependencies | false;
+  env?: NodeJS.ProcessEnv;
+  git?: PrVerifyGitDependencies;
   hq?: HqIngestDependencies;
+  postCommitStatus?: PostCommitStatus;
   publishCheckRun?: (input: PublishFactoryCheckInput) => void;
 }
-declare function runPrReview(args: PrReviewArgs, dependencies?: PrReviewDependencies): Promise<PrReviewProof>;
+declare function runPrVerify(args: PrVerifyArgs, dependencies?: PrVerifyDependencies): PrVerifyProof;
 //#endregion
 //#region src/pr-publish.d.ts
 type PrPublishArgs = Omit<PrReadyArgs, "pr" | "throwWhenBlocked"> & {
@@ -2175,7 +2768,21 @@ 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 —
+   * production always waits the real interval).
+   */
+  sleep?: (ms: number) => Promise<void>;
 }
 /**
  * What became of the durable `pr:verify` binding for this publish. Reported in
@@ -2392,7 +2999,9 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   observedAt: z.ZodString;
   outcome: z.ZodLiteral<"not-required">;
   patchId: z.ZodString;
-  reason: z.ZodLiteral<"docs-only-profile-bypass">;
+  reason: z.ZodEnum<{
+    "no-applicable-mode": "no-applicable-mode";
+  }>;
   reviewCycle: z.ZodNumber;
 }, z.core.$strict>, readonly [z.ZodObject<{
   createdAt: z.ZodString;
@@ -2412,7 +3021,9 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   observedAt: z.ZodString;
   outcome: z.ZodLiteral<"not-required">;
   patchId: z.ZodString;
-  reason: z.ZodLiteral<"docs-only-profile-bypass">;
+  reason: z.ZodEnum<{
+    "no-applicable-mode": "no-applicable-mode";
+  }>;
   reviewCycle: z.ZodNumber;
 }, z.core.$strict>], {
   readonly 1: z.ZodObject<{
@@ -2423,7 +3034,9 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
     observedAt: z.ZodString;
     outcome: z.ZodLiteral<"not-required">;
     patchId: z.ZodString;
-    reason: z.ZodLiteral<"docs-only-profile-bypass">;
+    reason: z.ZodEnum<{
+      "no-applicable-mode": "no-applicable-mode";
+    }>;
     reviewCycle: z.ZodNumber;
   }, z.core.$strict>;
 }, {
@@ -2440,7 +3053,7 @@ declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"revi
   observedAt: string;
   outcome: "not-required";
   patchId: string;
-  reason: "docs-only-profile-bypass";
+  reason: "no-applicable-mode";
   reviewCycle: number;
   issue?: number | undefined;
   pr?: number | undefined;
@@ -3179,249 +3792,68 @@ interface FactoryTraceDiagnostic {
     workerId?: string;
   };
   file: string;
-  line: number;
-  message: string;
-}
-interface ScanFactoryTraceOptions {
-  diagnosticsOnly?: boolean;
-  filters?: FactoryTraceFilters;
-  from: string;
-  malformed?: "diagnostic" | "throw";
-  repoRoot: string;
-  to: string;
-}
-interface ScanFactoryTraceResult {
-  diagnostics: FactoryTraceDiagnostic[];
-  events: ReadableFactoryTraceEvent[];
-}
-interface ScanFactoryTraceDiagnosticsOptions {
-  filters?: FactoryTraceFilters;
-  from: string;
-  repoRoot: string;
-  to: string;
-}
-declare const validateFactoryTraceEvent: (event: unknown) => FactoryTraceEvent;
-declare const toFactoryTraceEnvelope: (event: FactoryTraceEvent) => {
-  createdAt: string;
-  envelope: 1;
-  eventId: string;
-  payload: unknown;
-  repo: string;
-  type: string;
-  typeVersion: number;
-  issue?: number | undefined;
-  pr?: number | undefined;
-  thread?: string | undefined;
-  worker?: string | undefined;
-};
-interface AppendFactoryTraceEventResult {
-  event: FactoryTraceEvent;
-  filePath: string;
-  mirrorDiagnostics: TraceMirrorDiagnostic[];
-}
-declare const scanFactoryTraceEvents: ({
-  diagnosticsOnly,
-  filters,
-  from,
-  malformed,
-  repoRoot,
-  to
-}: ScanFactoryTraceOptions) => ScanFactoryTraceResult;
-/**
- * Diagnostics-only trace read (#707). Scans the shard window purely to surface
- * malformed / unknown-record diagnostics, without materializing (and then
- * discarding) every well-formed event. Malformed shards are always collected as
- * diagnostics, never thrown. Use when a consumer wants shard-corruption signal
- * but no event payloads — e.g. epic closeout after the orchestrator-metrics
- * removal.
- */
-declare const scanFactoryTraceDiagnostics: ({
-  filters,
-  from,
-  repoRoot,
-  to
-}: ScanFactoryTraceDiagnosticsOptions) => FactoryTraceDiagnostic[];
-//#endregion
-//#region src/retro-envelope.d.ts
-/**
- * Versioned retro envelope schema (epic #27 wave 2, issue #34).
- *
- * One envelope per lane, built at `factory:closeout` and delivered through the
- * typed gate-sink as the `retro-envelope` ingest kind. Re-derived in TypeScript
- * from the `spike/telemetry-layer2` S5 scratch schema (reference-only, never
- * merged) and kept structurally parity-compatible with HQ's v1 wire validator
- * (`software-factory-hq/src/contracts/retro-schemas.ts`, PR #32): a complete
- * envelope emitted by this package validates verbatim against HQ's payload
- * validator. This module is the producer-side single source of truth for the
- * v1 wire shape and its bounds ({@link RETRO_ENVELOPE_WIRE_BOUNDS}); the
- * exhaustive per-field/bound parity test in
- * `software-factory-hq/src/retro-envelope-parity.test.ts` (#46) walks this
- * schema against HQ's actual validator so ANY drift — field, type, bound,
- * enum, strictness — fails CI, not just drift a fixture happens to exercise.
- *
- * DESIGN INVARIANT: cross-family token sums must be UNREPRESENTABLE.
- *
- * The two model families use different tokenizers, prices, and accounting
- * conventions, so any token total that spans Claude and GPT is a lie:
- *
- * 1. There is no combined/total token field anywhere in the envelope.
- * 2. `tokenFamilies` is strict — its only keys are `claude` and `gpt`; data
- *    cannot smuggle in a third "all"/"combined" slot.
- * 3. The family BLOCKS are structurally different shapes with DIFFERENT keys
- *    (claude is a single flat block keyed on freshInput/cacheReadInput/
- *    cacheCreationInput; gpt is `{ roles: [...] }`). The exclusive input-tier
- *    COUNTS share no key name across families. The residual names shared
- *    between the claude block and a gpt ROLE entry are pinned to exactly
- *    {costUsd, model, output} (PR #32 advisory): `costUsd` is deliberate —
- *    USD is the one cross-family summable unit (rule 4); `model` is an
- *    unsummable label; `output` is the same name at DIFFERENT depths (lane
- *    block vs per-role entry), frozen by a tripwire test in
- *    `retro-envelope.test.ts` so the overlap cannot grow. Renaming `output`
- *    is a schemaVersion-2 wire change, deliberately not spent in v1.
- * 4. Cost is per-family USD and nullable. Combined totals are allowed in USD
- *    only, and only as a projection-time sum of per-family USD.
- *
- * Field names also encode the S2/S3 reader lessons: Claude `freshInput` alone
- * is not prompt size (true input context = freshInput + cacheReadInput +
- * cacheCreationInput, requestId-deduped), and codex `inputInclusiveOfCache`
- * already includes `cachedInput`, so `freshInputDerived` (inclusive − cached)
- * is the only value safe to feed a per-token pricer.
- *
- * COMPLETENESS POSTURE: harvest may have no usable native log for a lane, so
- * `tokenFamilies` may legitimately be absent. The closeout build gate demands
- * a valid envelope, not available telemetry. A families-absent envelope keeps
- * its operator-visible data gaps and is a replayable advisory HQ event, so it
- * never substitutes unavailable usage with zero. The wire shape (field names,
- * types, structure) stays byte-parity with HQ v1.
- */
-declare const RETRO_ENVELOPE_SCHEMA_VERSION = 1;
-declare const retroEnvelopeV1Schema: z.ZodObject<{
-  agentRunId: z.ZodString;
-  archiveRef: z.ZodOptional<z.ZodString>;
-  cycles: z.ZodObject<{
-    gateRunsToFirstGreen: z.ZodNumber;
-    reviewerFixRounds: z.ZodNumber;
-    thermoFixRounds: z.ZodNumber;
-  }, z.core.$strict>;
-  dataGaps: z.ZodDefault<z.ZodArray<z.ZodString>>;
-  gates: z.ZodArray<z.ZodObject<{
-    cycle: z.ZodNumber;
-    duration: z.ZodNumber;
-    gate: z.ZodString;
-    outcome: z.ZodEnum<{
-      pass: "pass";
-      fail: "fail";
-      skip: "skip";
-    }>;
-    startedAt: z.ZodISODateTime;
-  }, z.core.$strict>>;
-  generatedAt: z.ZodISODateTime;
-  interventions: z.ZodObject<{
-    count: z.ZodNumber;
-  }, z.core.$strict>;
-  joinKeys: z.ZodObject<{
-    claudeSessionIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
-    codexThreadIds: z.ZodDefault<z.ZodArray<z.ZodString>>;
-  }, z.core.$strict>;
-  kind: z.ZodLiteral<"retro-envelope">;
-  outcome: z.ZodOptional<z.ZodObject<{
-    mergeCheck: z.ZodOptional<z.ZodEnum<{
-      pass: "pass";
-      fail: "fail";
-      "not-run": "not-run";
-    }>>;
-    status: z.ZodEnum<{
-      success: "success";
-      fail: "fail";
-      blocked: "blocked";
-      "ship-with-followups": "ship-with-followups";
-    }>;
-    verdict: z.ZodOptional<z.ZodString>;
-  }, z.core.$strict>>;
-  phases: z.ZodArray<z.ZodObject<{
-    at: z.ZodISODateTime;
-    deltaSec: z.ZodOptional<z.ZodNumber>;
-    name: z.ZodString;
-  }, z.core.$strict>>;
-  refs: z.ZodObject<{
-    branch: z.ZodOptional<z.ZodString>;
-    epic: z.ZodOptional<z.ZodString>;
-    headSha: z.ZodOptional<z.ZodString>;
-    issue: z.ZodOptional<z.ZodString>;
-    prNumber: z.ZodOptional<z.ZodNumber>;
-  }, z.core.$strict>;
-  repo: z.ZodObject<{
-    name: z.ZodString;
-    owner: z.ZodString;
-  }, z.core.$strict>;
-  schemaVersion: z.ZodLiteral<1>;
-  tokenFamilies: z.ZodObject<{
-    claude: z.ZodOptional<z.ZodObject<{
-      cacheCreationInput: z.ZodNumber;
-      cacheReadInput: z.ZodNumber;
-      costUsd: z.ZodNullable<z.ZodNumber>;
-      family: z.ZodLiteral<"claude">;
-      freshInput: z.ZodNumber;
-      model: z.ZodString;
-      output: z.ZodNumber;
-      requests: z.ZodNumber;
-    }, z.core.$strict>>;
-    gpt: z.ZodOptional<z.ZodObject<{
-      family: z.ZodLiteral<"gpt">;
-      roles: z.ZodArray<z.ZodObject<{
-        cachedInput: z.ZodNumber;
-        costUsd: z.ZodNullable<z.ZodNumber>;
-        freshInputDerived: z.ZodNumber;
-        inputInclusiveOfCache: z.ZodNumber;
-        model: z.ZodString;
-        output: z.ZodNumber;
-        reasoningOutput: z.ZodNumber;
-        role: z.ZodString;
-        threadId: z.ZodOptional<z.ZodString>;
-      }, z.core.$strict>>;
-    }, z.core.$strict>>;
-  }, z.core.$strict>;
-  wallClock: z.ZodObject<{
-    endTs: z.ZodISODateTime;
-    startTs: z.ZodISODateTime;
-    totalSec: z.ZodNumber;
-  }, z.core.$strict>;
-}, z.core.$strict>;
-type RetroEnvelope = z.infer<typeof retroEnvelopeV1Schema>;
-/**
- * Versioned payload validators, keyed by schema major. Unknown majors never
- * reach these — {@link parseRetroEnvelope} returns them raw and marked
- * degraded, mirroring HQ's ingest skew posture (stored raw, never dropped).
- */
-declare const RETRO_ENVELOPE_VALIDATORS: Record<number, z.ZodType<RetroEnvelope, unknown>>;
-declare const SUPPORTED_RETRO_ENVELOPE_SCHEMA_VERSIONS: readonly number[];
-/** The `schemaVersion` a candidate declares, or undefined when unreadable. */
-declare const retroEnvelopeSchemaVersionOf: (candidate: unknown) => number | undefined;
-type ParsedRetroEnvelope = {
-  disposition: "trusted";
-  envelope: RetroEnvelope;
-  schemaVersion: number;
-} | {
-  disposition: "degraded";
-  raw: unknown;
-  schemaVersion: number | undefined;
+  line: number;
+  message: string;
+}
+interface ScanFactoryTraceOptions {
+  diagnosticsOnly?: boolean;
+  filters?: FactoryTraceFilters;
+  from: string;
+  malformed?: "diagnostic" | "throw";
+  repoRoot: string;
+  to: string;
+}
+interface ScanFactoryTraceResult {
+  diagnostics: FactoryTraceDiagnostic[];
+  events: ReadableFactoryTraceEvent[];
+}
+interface ScanFactoryTraceDiagnosticsOptions {
+  filters?: FactoryTraceFilters;
+  from: string;
+  repoRoot: string;
+  to: string;
+}
+declare const validateFactoryTraceEvent: (event: unknown) => FactoryTraceEvent;
+declare const toFactoryTraceEnvelope: (event: FactoryTraceEvent) => {
+  createdAt: string;
+  envelope: 1;
+  eventId: string;
+  payload: unknown;
+  repo: string;
+  type: string;
+  typeVersion: number;
+  issue?: number | undefined;
+  pr?: number | undefined;
+  thread?: string | undefined;
+  worker?: string | undefined;
 };
+interface AppendFactoryTraceEventResult {
+  event: FactoryTraceEvent;
+  filePath: string;
+  mirrorDiagnostics: TraceMirrorDiagnostic[];
+}
+declare const scanFactoryTraceEvents: ({
+  diagnosticsOnly,
+  filters,
+  from,
+  malformed,
+  repoRoot,
+  to
+}: ScanFactoryTraceOptions) => ScanFactoryTraceResult;
 /**
- * Parses a candidate against the versioned validators. A recognized major is
- * validated typed-only (throws on an invalid known-version payload); an unknown
- * major is round-tripped RAW and marked degraded — the retained payload is the
- * exact input object, never a coerced projection. Mirrors the HQ ingest seam so
- * the two sides agree on the skew posture.
- */
-declare const parseRetroEnvelope: (candidate: unknown) => ParsedRetroEnvelope;
-/**
- * Whether harvest recorded at least one token family. This is an operator
- * summary predicate, not a delivery gate: a families-absent envelope remains
- * valid and replayable when its data gaps explain why telemetry is unavailable.
+ * Diagnostics-only trace read (#707). Scans the shard window purely to surface
+ * malformed / unknown-record diagnostics, without materializing (and then
+ * discarding) every well-formed event. Malformed shards are always collected as
+ * diagnostics, never thrown. Use when a consumer wants shard-corruption signal
+ * but no event payloads — e.g. epic closeout after the orchestrator-metrics
+ * removal.
  */
-declare const isRetroEnvelopeWireComplete: (envelope: Pick<RetroEnvelope, "tokenFamilies">) => boolean;
-/** Epic anchor for an envelope: refs.epic, else refs.issue, else the PR. */
-declare const retroEpicReference: (refs: RetroEnvelope["refs"]) => string | undefined;
+declare const scanFactoryTraceDiagnostics: ({
+  filters,
+  from,
+  repoRoot,
+  to
+}: ScanFactoryTraceDiagnosticsOptions) => FactoryTraceDiagnostic[];
 //#endregion
 //#region src/interior-telemetry/gate-timing.d.ts
 declare const GATE_TIMING_SCHEMA_VERSION = 1;
@@ -3497,13 +3929,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;
@@ -3520,6 +3978,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
@@ -3528,7 +3990,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 {
@@ -3716,17 +4178,100 @@ declare const renderPrBodySections: ({
   reviewProof?: PrReviewProof;
   verifyProof?: PrVerifyProof;
 }) => string;
+declare namespace boundary_manifest_d_exports {
+  export { BOUNDARY_CLOSEOUT_DEFAULT_RUNG, BOUNDARY_MANIFEST_SCHEMA_VERSION, BoundaryManifest, BoundaryManifestExtraction, BoundaryManifestParse, FACTORY_BOUNDARY_FENCE_LANG, boundaryManifestSchema, closeoutRungFor, extractBoundaryManifestBlock, manifestContentHash, parseBoundaryManifest, rungMeetsMinimum, specContentHash };
+}
+declare const FACTORY_BOUNDARY_FENCE_LANG = "factory-boundary";
+declare const BOUNDARY_MANIFEST_SCHEMA_VERSION = 1;
+declare const BOUNDARY_CLOSEOUT_DEFAULT_RUNG: EvidenceReviewRung;
+declare const rungMeetsMinimum: (rung: EvidenceReviewRung, minimum: EvidenceReviewRung) => boolean;
+declare const boundaryManifestBaseSchema: z.ZodObject<{
+  boundary: z.ZodString;
+  closeout: z.ZodOptional<z.ZodObject<{
+    review: z.ZodEnum<{
+      oracle: "oracle";
+      "independent-model": "independent-model";
+      human: "human";
+    }>;
+  }, z.core.$loose>>;
+  declaredBy: z.ZodString;
+  prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  schemaVersion: z.ZodLiteral<1>;
+  topology: z.ZodEnum<{
+    flagged: "flagged";
+    "each-to-main": "each-to-main";
+    stacked: "stacked";
+  }>;
+  waves: z.ZodArray<z.ZodObject<{
+    autoMerge: z.ZodOptional<z.ZodBoolean>;
+    issues: z.ZodArray<z.ZodNumber>;
+    name: z.ZodString;
+    review: z.ZodEnum<{
+      oracle: "oracle";
+      "independent-model": "independent-model";
+      human: "human";
+    }>;
+  }, z.core.$loose>>;
+}, z.core.$loose>;
+declare const boundaryManifestSchema: z.ZodObject<{
+  boundary: z.ZodString;
+  closeout: z.ZodOptional<z.ZodObject<{
+    review: z.ZodEnum<{
+      oracle: "oracle";
+      "independent-model": "independent-model";
+      human: "human";
+    }>;
+  }, z.core.$loose>>;
+  declaredBy: z.ZodString;
+  prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  schemaVersion: z.ZodLiteral<1>;
+  topology: z.ZodEnum<{
+    flagged: "flagged";
+    "each-to-main": "each-to-main";
+    stacked: "stacked";
+  }>;
+  waves: z.ZodArray<z.ZodObject<{
+    autoMerge: z.ZodOptional<z.ZodBoolean>;
+    issues: z.ZodArray<z.ZodNumber>;
+    name: z.ZodString;
+    review: z.ZodEnum<{
+      oracle: "oracle";
+      "independent-model": "independent-model";
+      human: "human";
+    }>;
+  }, z.core.$loose>>;
+}, z.core.$loose>;
+type BoundaryManifest = z.infer<typeof boundaryManifestBaseSchema>;
+type BoundaryManifestExtraction = {
+  ok: true;
+  blockText: string;
+} | {
+  ok: false;
+  error: string;
+};
+declare const extractBoundaryManifestBlock: (issueBody: string) => BoundaryManifestExtraction;
+declare const manifestContentHash: (blockText: string) => string;
+declare const specContentHash: (issueBody: string) => string;
+type BoundaryManifestParse = {
+  ok: true;
+  manifest: BoundaryManifest;
+  manifestHash: string;
+} | {
+  ok: false;
+  error: string;
+};
+declare const parseBoundaryManifest: (issueBody: string) => BoundaryManifestParse;
+declare const closeoutRungFor: (manifest: BoundaryManifest) => EvidenceReviewRung;
 //#endregion
-//#region src/pr-readiness/review-requiredness.d.ts
-interface DocsOnlyReviewBypassState {
-  applies: boolean;
+//#region src/demand-resolution.d.ts
+/** The boundary-manifest wave demand that applies to one pull request. */
+interface WaveReviewDemand {
+  autoMerge: boolean;
+  review: EvidenceReviewRung;
+  wave: string;
 }
-declare const resolveDocsOnlyReviewBypassState: (input: {
-  classification: DiffClassification;
-  docsOnlyReviewBypass?: boolean;
-}) => DocsOnlyReviewBypassState;
 declare namespace readiness_evaluation_d_exports {
-  export { CORRECTNESS_UNTYPED_REVIEW_BLOCKER_REASON, DRAFT_BLOCKER_REASON, DocsOnlyReviewBypassState, EvaluationInput, ManagedReadinessLedger, PENDING_CHECKS_BLOCKER_REASON_PREFIX, PreviewDeployProof, PreviewSeedStatus, READINESS_REPAIR_CODES, RENDER_PR_BODY_SECTIONS_BLOCKER_REASON, ReadinessRepair, ReadinessStatus, SCHEMA_VERSION, SECURITY_UNTYPED_REVIEW_BLOCKER_REASON, evaluateReadiness, managedReadinessLedgerSchema, readinessExitCode, readinessRepairSchema, resolveDocsOnlyReviewBypassState, validateManagedReadinessLedger };
+  export { CORRECTNESS_UNTYPED_REVIEW_BLOCKER_REASON, DRAFT_BLOCKER_REASON, EvaluationInput, ManagedReadinessLedger, PENDING_CHECKS_BLOCKER_REASON_PREFIX, PreviewDeployProof, PreviewSeedStatus, READINESS_REPAIR_CODES, RENDER_PR_BODY_SECTIONS_BLOCKER_REASON, ReadinessRepair, ReadinessStatus, SCHEMA_VERSION, SECURITY_UNTYPED_REVIEW_BLOCKER_REASON, evaluateReadiness, managedReadinessLedgerSchema, readinessExitCode, readinessRepairSchema, validateManagedReadinessLedger };
 }
 declare const CORRECTNESS_UNTYPED_REVIEW_BLOCKER_REASON = "Correctness review proof is not a head-bound typed findings verdict; re-run pr:review with a valid findings file.";
 declare const SECURITY_UNTYPED_REVIEW_BLOCKER_REASON = "Security review proof is not a head-bound typed findings verdict; re-run pr:review with a valid findings file.";
@@ -3757,7 +4302,6 @@ interface EvaluationInput {
   verificationProof?: VerificationProofState;
   docsOnlyVerifyBaselineHeadShas?: string[];
   docsOnlySinceReviewProof?: boolean;
-  docsOnlyReviewBypass?: boolean;
   externalRequiredChecks?: RequiredCheck[];
   evidenceEnvelopes?: LoadedEvidenceEnvelope[];
   mergeBaseSha?: string;
@@ -3772,8 +4316,13 @@ interface EvaluationInput {
   };
   handledCommentSessionId?: string;
   handledCommentClearedAt?: string;
+  waveReviewDemand?: Pick<WaveReviewDemand, "review" | "wave">;
 }
 declare const evaluateReadiness: (input: EvaluationInput) => {
+  blockedReasons: {
+    code: string;
+    detail: string;
+  }[];
   blockingReasons: string[];
   humanBlockingReasons: string[];
   ledger: {
@@ -3801,14 +4350,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;
@@ -3818,7 +4367,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;
@@ -4104,6 +4653,7 @@ type FetchLike = (input: string, init?: {
   headers?: Record<string, string>;
   method?: string;
   redirect?: "error";
+  signal?: AbortSignal;
 }) => Promise<{
   json: () => Promise<unknown>;
   status: number;
@@ -4118,6 +4668,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;
@@ -4134,90 +4692,6 @@ declare const isProductionHqUrl: (url: string) => boolean;
  * surfaced with actionable guidance; any non-2xx throws.
  */
 declare const publishEpicStructure: (args: PublishEpicStructureArgs) => Promise<PublishEpicStructureResult>;
-declare namespace boundary_manifest_d_exports {
-  export { BOUNDARY_CLOSEOUT_DEFAULT_RUNG, BOUNDARY_MANIFEST_SCHEMA_VERSION, BoundaryManifest, BoundaryManifestExtraction, BoundaryManifestParse, FACTORY_BOUNDARY_FENCE_LANG, boundaryManifestSchema, closeoutRungFor, extractBoundaryManifestBlock, manifestContentHash, parseBoundaryManifest, rungMeetsMinimum, specContentHash };
-}
-declare const FACTORY_BOUNDARY_FENCE_LANG = "factory-boundary";
-declare const BOUNDARY_MANIFEST_SCHEMA_VERSION = 1;
-declare const BOUNDARY_CLOSEOUT_DEFAULT_RUNG: EvidenceReviewRung;
-declare const rungMeetsMinimum: (rung: EvidenceReviewRung, minimum: EvidenceReviewRung) => boolean;
-declare const boundaryManifestBaseSchema: z.ZodObject<{
-  boundary: z.ZodString;
-  closeout: z.ZodOptional<z.ZodObject<{
-    review: z.ZodEnum<{
-      oracle: "oracle";
-      "independent-model": "independent-model";
-      human: "human";
-    }>;
-  }, z.core.$loose>>;
-  declaredBy: z.ZodString;
-  prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  schemaVersion: z.ZodLiteral<1>;
-  topology: z.ZodEnum<{
-    flagged: "flagged";
-    "each-to-main": "each-to-main";
-    stacked: "stacked";
-  }>;
-  waves: z.ZodArray<z.ZodObject<{
-    autoMerge: z.ZodOptional<z.ZodBoolean>;
-    issues: z.ZodArray<z.ZodNumber>;
-    name: z.ZodString;
-    review: z.ZodEnum<{
-      oracle: "oracle";
-      "independent-model": "independent-model";
-      human: "human";
-    }>;
-  }, z.core.$loose>>;
-}, z.core.$loose>;
-declare const boundaryManifestSchema: z.ZodObject<{
-  boundary: z.ZodString;
-  closeout: z.ZodOptional<z.ZodObject<{
-    review: z.ZodEnum<{
-      oracle: "oracle";
-      "independent-model": "independent-model";
-      human: "human";
-    }>;
-  }, z.core.$loose>>;
-  declaredBy: z.ZodString;
-  prs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
-  schemaVersion: z.ZodLiteral<1>;
-  topology: z.ZodEnum<{
-    flagged: "flagged";
-    "each-to-main": "each-to-main";
-    stacked: "stacked";
-  }>;
-  waves: z.ZodArray<z.ZodObject<{
-    autoMerge: z.ZodOptional<z.ZodBoolean>;
-    issues: z.ZodArray<z.ZodNumber>;
-    name: z.ZodString;
-    review: z.ZodEnum<{
-      oracle: "oracle";
-      "independent-model": "independent-model";
-      human: "human";
-    }>;
-  }, z.core.$loose>>;
-}, z.core.$loose>;
-type BoundaryManifest = z.infer<typeof boundaryManifestBaseSchema>;
-type BoundaryManifestExtraction = {
-  ok: true;
-  blockText: string;
-} | {
-  ok: false;
-  error: string;
-};
-declare const extractBoundaryManifestBlock: (issueBody: string) => BoundaryManifestExtraction;
-declare const manifestContentHash: (blockText: string) => string;
-declare const specContentHash: (issueBody: string) => string;
-type BoundaryManifestParse = {
-  ok: true;
-  manifest: BoundaryManifest;
-  manifestHash: string;
-} | {
-  ok: false;
-  error: string;
-};
-declare const parseBoundaryManifest: (issueBody: string) => BoundaryManifestParse;
-declare const closeoutRungFor: (manifest: BoundaryManifest) => EvidenceReviewRung;
 //#endregion
 //#region src/review-focus.d.ts
 declare const REVIEW_FOCUS_SECTION = "Review focus";
@@ -4323,7 +4797,7 @@ declare function assertWorkerCheckoutAllowed({
 interface CreateProgramOptions {
   actions?: {
     boundaryCheck?: BoundaryCheckAction;
-    canaryVerify?: CanaryVerifyAction;
+    demandWaive?: DemandWaiveAction;
     prMergeCheck?: PrMergeCheckAction;
     prPublish?: PrPublishAction;
     prReady?: PrReadyAction;
@@ -4335,4 +4809,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_FACTORY_REPOSITORY, type DagDocument, 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, 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, WorkerCheckoutGuardError, type WorkerCloseoutLessonsTraceEvent, appendReviewLadderStageTraceEvent, appendWithTraceSinks, assembleReviewPrompt, assertWorkerCheckoutAllowed, 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, readPrMergeCheckProof, readPrReadyProof, readPrReviewProof, resolveDocsOnlyReviewBypass, resolveFactoryRepository, resolveFindingBlocking, resolveReviewFindingCategory, resolveReviewFindingSeverity, resolveReviewLadderPolicy, resolveTraceWriteSinks, retroEnvelopeSchemaVersionOf, retroEnvelopeV1Schema, retroEpicReference, reviewCycleStateFor, reviewFocusFromIssueBody, reviewPromptSectionSchema, reviewPromptSectionsSchema, run, runBoundaryCheck, runEvidenceEmit, runPrMergeCheck, runPrPublish, runPrReady, runPrReview, runPrVerify, scanFactoryTraceDiagnostics, scanFactoryTraceEvents, staleRepeatLadderFindings, toFactoryTraceEnvelope, tryAppendReviewGateNotRequiredTraceEvent, tryAppendReviewLadderStageTraceEvent, validateBoundaryCheckProof, validateDagDocument, validateFactoryTraceEvent, validatePrMergeCheckProof, validatePrReadyProof, validatePrReviewProof, validatePrVerifyProof, 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, 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 };