@patronage/software-factory 0.20.0

package/dist/index.d.ts

@@ -0,0 +1,4338 @@
+import { existsSync, readFileSync, rmSync } from "node:fs";
+import { Command } from "commander";
+import { z } from "zod";
+
+//#region src/github-issue-comments.d.ts
+interface GithubIssueCommentApi {
+  author_association?: string;
+  body: string;
+  created_at: string;
+  html_url: string;
+  node_id: string;
+  updated_at: string;
+  user?: {
+    login?: string;
+  };
+}
+interface GithubIssueComment {
+  author: {
+    login?: string;
+  };
+  authorAssociation?: string;
+  body: string;
+  createdAt: string;
+  id: string;
+  updatedAt: string;
+  url: string;
+}
+declare const normalizeIssueComments: (value: GithubIssueCommentApi[] | GithubIssueCommentApi[][]) => GithubIssueComment[];
+declare namespace boundary_review_proof_d_exports {
+  export { BOUNDARY_REVIEW_PROOF_KIND, BoundaryReviewProof, BoundaryReviewProofComment, boundaryReviewProofSchema, selectBoundaryReviewProof, undispositionedBlockingFindings };
+}
+declare const BOUNDARY_REVIEW_PROOF_KIND = "boundary-review-proof";
+declare const boundaryReviewProofBaseSchema: z.ZodObject<{
+  boundary: z.ZodString;
+  coveredSet: z.ZodArray<z.ZodObject<{
+    headSha: z.ZodOptional<z.ZodString>;
+    issue: z.ZodOptional<z.ZodNumber>;
+    mergedSha: z.ZodOptional<z.ZodString>;
+    pr: z.ZodNumber;
+    state: z.ZodEnum<{
+      open: "open";
+      merged: "merged";
+    }>;
+    wave: z.ZodOptional<z.ZodString>;
+  }, z.core.$loose>>;
+  dispositions: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+  findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    blockingAfterCap: z.ZodOptional<z.ZodBoolean>;
+    category: z.ZodOptional<z.ZodString>;
+    disposition: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+  }, z.core.$loose>>>;
+  kind: z.ZodLiteral<"boundary-review-proof">;
+  manifestHash: z.ZodObject<{
+    algo: z.ZodLiteral<"sha256">;
+    scope: z.ZodOptional<z.ZodString>;
+    value: z.ZodString;
+  }, z.core.$loose>;
+  outcome: z.ZodEnum<{
+    pass: "pass";
+    fail: "fail";
+  }>;
+  producer: z.ZodString;
+  rung: z.ZodEnum<{
+    oracle: "oracle";
+    "independent-model": "independent-model";
+    human: "human";
+  }>;
+  schemaVersion: z.ZodLiteral<1>;
+  sessionId: z.ZodOptional<z.ZodString>;
+  specHash: z.ZodOptional<z.ZodObject<{
+    algo: z.ZodLiteral<"sha256">;
+    scope: z.ZodOptional<z.ZodString>;
+    value: z.ZodString;
+  }, z.core.$loose>>;
+}, z.core.$loose>;
+declare const boundaryReviewProofSchema: z.ZodObject<{
+  boundary: z.ZodString;
+  coveredSet: z.ZodArray<z.ZodObject<{
+    headSha: z.ZodOptional<z.ZodString>;
+    issue: z.ZodOptional<z.ZodNumber>;
+    mergedSha: z.ZodOptional<z.ZodString>;
+    pr: z.ZodNumber;
+    state: z.ZodEnum<{
+      open: "open";
+      merged: "merged";
+    }>;
+    wave: z.ZodOptional<z.ZodString>;
+  }, z.core.$loose>>;
+  dispositions: z.ZodOptional<z.ZodArray<z.ZodUnknown>>;
+  findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    blockingAfterCap: z.ZodOptional<z.ZodBoolean>;
+    category: z.ZodOptional<z.ZodString>;
+    disposition: z.ZodOptional<z.ZodString>;
+    title: z.ZodString;
+  }, z.core.$loose>>>;
+  kind: z.ZodLiteral<"boundary-review-proof">;
+  manifestHash: z.ZodObject<{
+    algo: z.ZodLiteral<"sha256">;
+    scope: z.ZodOptional<z.ZodString>;
+    value: z.ZodString;
+  }, z.core.$loose>;
+  outcome: z.ZodEnum<{
+    pass: "pass";
+    fail: "fail";
+  }>;
+  producer: z.ZodString;
+  rung: z.ZodEnum<{
+    oracle: "oracle";
+    "independent-model": "independent-model";
+    human: "human";
+  }>;
+  schemaVersion: z.ZodLiteral<1>;
+  sessionId: z.ZodOptional<z.ZodString>;
+  specHash: z.ZodOptional<z.ZodObject<{
+    algo: z.ZodLiteral<"sha256">;
+    scope: z.ZodOptional<z.ZodString>;
+    value: z.ZodString;
+  }, z.core.$loose>>;
+}, z.core.$loose>;
+type BoundaryReviewProof = z.infer<typeof boundaryReviewProofBaseSchema>;
+interface BoundaryReviewProofComment {
+  proof: BoundaryReviewProof;
+  commentId?: string | number;
+  commentUrl?: string;
+}
+declare const selectBoundaryReviewProof: (comments: GithubIssueComment[], boundary: string, declaredBy: string) => BoundaryReviewProofComment | undefined;
+declare const undispositionedBlockingFindings: (proof: BoundaryReviewProof) => string[];
+//#endregion
+//#region src/hq-ingest-sink.d.ts
+interface HqIngestDependencies {
+  /**
+   * @deprecated Custom persistence seam. It receives an immutable spool-file
+   * target and one complete JSON event; production never appends legacy JSONL.
+   */
+  appendJournal?: (target: string, row: string) => Promise<void> | void;
+  diagnostic?: (line: string) => Promise<void> | void;
+  env?: NodeJS.ProcessEnv;
+  fetch?: typeof fetch;
+  now?: () => Date;
+  randomUUID?: () => string;
+  /**
+   * Ceiling for persisting a failure after the transport leg (default
+   * `HQ_JOURNAL_FLUSH_BUDGET_MS`). Injectable for the same reason as
+   * `timeoutMs`: see the note there.
+   */
+  journalFlushBudgetMs?: number;
+  /** @deprecated Legacy sidecars are now streamed directly; retained for API compatibility. */
+  sidecarReclaimMs?: number;
+  /**
+   * Setup budget for callers that own the process lifetime — honored AS GIVEN,
+   * above the `DEFAULT_HQ_INGEST_TIMEOUT_MS` ceiling that clamps `timeoutMs`.
+   *
+   * Exists because the budgets are wall-clock while the work they bound is real
+   * `fsync`. On a loaded CI runner the 750ms setup budget expires, the event is
+   * discarded as `held`, and assertions expecting `deferred` fail. `timeoutMs`
+   * is deliberately clamped DOWNWARD, so it offered no lever to widen — which
+   * left skipping the tests in CI (`itCiSensitive`) as the only available fix,
+   * buying green runs at the cost of running LESS coverage in CI than locally
+   * (#225).
+   *
+   * This is separate from `timeoutMs` rather than a relaxation of it: the
+   * clamp is a real invariant (a gate command must not be made to hang by a
+   * large requested timeout) and is preserved. Use this only where the caller
+   * controls process exit — tests, and tooling that is not a gate.
+   */
+  setupBudgetMs?: number;
+  timeoutMs?: number;
+  transportTimeoutMs?: number;
+}
+//#endregion
+//#region src/checkout-repository.d.ts
+interface CheckoutRepository {
+  name: string;
+  owner: string;
+}
+//#endregion
+//#region src/follow-up.d.ts
+interface FactoryCliInvocation {
+  /** Runtime arguments ending with the factory CLI entry module. */
+  argvPrefix: string[];
+  executable: string;
+}
+declare const FactoryCliInvocationSchema: z.ZodType<FactoryCliInvocation>;
+interface FollowUpAction {
+  /**
+   * Machine-safe argv-style array for the obvious next action, e.g.
+   * ["gh","pr","merge","513","--squash"]. Same shape and field name that
+   * `factory:delegate --print` emits, so an orchestrating agent can spawn the
+   * next command without reconstructing a shell string. argv[0] is the
+   * executable; the rest are literal, already-split arguments.
+   */
+  argv: string[];
+  /**
+   * Human-readable rendering of {@link argv} for logs and operators. Additive
+   * to argv, never a substitute for it — argv is the source of truth.
+   */
+  command: string;
+}
+/**
+ * Build a {@link FollowUpAction} from a literal argv array. The `command`
+ * string is derived from argv so the two never drift.
+ */
+declare const followUpFromArgv: (argv: string[]) => FollowUpAction;
+/** Canonical zod schema for the optional follow-up field on JSON outputs. */
+declare const FollowUpActionSchema: z.ZodType<FollowUpAction>;
+//#endregion
+//#region src/github-client.d.ts
+interface GithubPullRequestReview {
+  author: {
+    login?: string;
+  };
+  body: string;
+  /** GraphQL `PullRequestReview.lastEditedAt` — REST's `/pulls/reviews` has no equivalent (#843). */
+  lastEditedAt?: string;
+  state: string;
+  submittedAt?: string;
+  url: string;
+}
+//#endregion
+//#region src/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;
+}
+/**
+ * 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/merge-freeze.d.ts
+interface MergeFreezeGeneration {
+  headSha: string;
+  id: number;
+  startedAt: string;
+}
+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 };
+}
+/**
+ * Detects when a PR head branch is checked out in a local git worktree.
+ *
+ * `gh pr merge --delete-branch` fails when the local branch is held by a
+ * worktree (git refuses to delete a checked-out branch), which previously
+ * broke the auto-merge lane mid-merge (patronage/internal#284). The merge
+ * preflight surfaces this as an actionable notice — not a hard fail — so the
+ * operator merges without `--delete-branch` (or prunes the worktree first)
+ * and defers local branch cleanup to closeout.
+ */
+interface WorktreeHeldBranch {
+  branch: string;
+  worktreePath: string;
+}
+interface WorktreeListEntry {
+  branch?: string;
+  path: string;
+}
+/**
+ * Parses `git worktree list --porcelain` output. Entries are separated by
+ * blank lines; each starts with `worktree <path>` and carries an optional
+ * `branch refs/heads/<name>` attribute (detached worktrees have none).
+ */
+declare function parseGitWorktreeList(porcelain: string): WorktreeListEntry[];
+/**
+ * Returns the worktree holding `branch`, or undefined when no local worktree
+ * has it checked out (or the porcelain listing was unavailable).
+ */
+declare function findWorktreeHeldBranch({
+  branch,
+  worktreeListPorcelain
+}: {
+  branch: string;
+  worktreeListPorcelain: string | undefined;
+}): undefined | WorktreeHeldBranch;
+declare function worktreeHeldBranchNotice(held: WorktreeHeldBranch): string;
+interface MergeOperationalNotices {
+  notices: string[];
+  worktreeHeldBranch?: WorktreeHeldBranch;
+  worktreeHeldBranches?: WorktreeHeldBranch[];
+}
+/**
+ * Single entry point for non-blocking merge preflight notices, mirroring
+ * `resolveMergeGuardIdentity`/`mergeGuardBlockingReasons` in
+ * merge-identity.ts: adding a notice kind never requires coordinated edits
+ * in the command runner, and persisted notice strings cannot drift from the
+ * structured detection result.
+ */
+declare function resolveMergeOperationalNotices({
+  headRefName,
+  worktreeListPorcelain
+}: {
+  headRefName: string | undefined;
+  worktreeListPorcelain: string | undefined;
+}): MergeOperationalNotices;
+/**
+ * Shared `git worktree list --porcelain` reader for merge preflight and
+ * closeout. Returns undefined when the directory is missing, not a git
+ * repository, or git is unavailable — detection is best-effort and callers
+ * report "skipped" rather than fabricating a result.
+ */
+declare function listWorktreesPorcelain(cwd: string): string | undefined;
+interface WorktreeHeldBranchCheck {
+  held?: WorktreeHeldBranch;
+  /** "skipped" means no branch was recorded or worktrees were unlistable. */
+  status: "clean" | "held" | "skipped";
+}
+/**
+ * Closeout-side counterpart to the merge-preflight notice: the merge step
+ * defers local branch cleanup to closeout, so closeout planning checks
+ * whether the worker branch is still held by a worktree (#284).
+ */
+declare function checkWorktreeHeldBranch({
+  branch,
+  worktreeListPorcelain
+}: {
+  branch: string | undefined;
+  worktreeListPorcelain: string | undefined;
+}): WorktreeHeldBranchCheck;
+/** One-line closeout summary, owned beside the detection logic. */
+declare function formatHeldBranchCloseoutSummary(check: WorktreeHeldBranchCheck): string;
+declare namespace merge_identity_d_exports {
+  export { LiveHeadInput, MergeGuardIdentity, MergeIdentityResult, PostProofCommit, ReadyProofForMergeIdentity, evaluateMergeIdentity, mergeGuardBlockingReasons, mergeGuardIdentitySchema, resolveMergeGuardIdentity };
+}
+interface PostProofCommit {
+  sha: string;
+  subject: string;
+}
+/**
+ * The slice of the pr:ready proof the merge guard actually consumes, so this
+ * module does not depend on the parent proof envelope. `PrReadyProof` is
+ * structurally assignable to this type.
+ */
+interface ReadyProofForMergeIdentity {
+  blockingReasons: string[];
+  ledger: {
+    /**
+     * The evaluated head SHA recorded by pr:ready: `pr.headRefOid` captured
+     * at evaluation time. The merge guard compares it to the live pushed
+     * HEAD with exact equality.
+     */
+    headSha: string;
+    pr: number;
+  };
+  status: string;
+}
+type MergeIdentityResult = {
+  kind: "match";
+  headSha: string;
+} | {
+  kind: "diverged";
+  liveHeadSha: string;
+  postProofCommits?: PostProofCommit[];
+  proofHeadSha: string;
+};
+type MergeGuardIdentity = MergeIdentityResult | {
+  kind: "live-head-invalid";
+  pr: number;
+  received: string;
+} | {
+  kind: "ready-proof-missing";
+  errorDetail?: string;
+  readyProofPath: string;
+} | {
+  kind: "ready-proof-pr-mismatch";
+  proofPr: number;
+  requestedPr: number;
+} | {
+  kind: "ready-proof-not-ready";
+  blockingReasons: string[];
+  status: string;
+};
+declare const evaluateMergeIdentity: ({
+  liveHeadSha,
+  postProofCommits,
+  proofHeadSha
+}: {
+  liveHeadSha: string;
+  postProofCommits?: PostProofCommit[];
+  proofHeadSha: string;
+}) => MergeIdentityResult;
+/**
+ * The live PR head as fetched from GitHub: either a validated 40-hex SHA or
+ * the raw (stringified) response that failed validation.
+ */
+type LiveHeadInput = {
+  headSha: string;
+} | {
+  invalidResponse: string;
+};
+/**
+ * Single entry point that owns construction of every MergeGuardIdentity
+ * kind, so adding or changing a kind never requires coordinated edits in the
+ * command runner.
+ */
+declare const resolveMergeGuardIdentity: ({
+  commitsBetween,
+  liveHead,
+  pr,
+  readyProof,
+  readyProofError,
+  readyProofPath
+}: {
+  commitsBetween?: (fromSha: string, toSha: string) => PostProofCommit[] | undefined;
+  liveHead: LiveHeadInput;
+  pr: number;
+  readyProof: ReadyProofForMergeIdentity | undefined;
+  readyProofError?: unknown;
+  readyProofPath: string;
+}) => MergeGuardIdentity;
+declare const mergeGuardIdentitySchema: z.ZodType<MergeGuardIdentity>;
+declare const mergeGuardBlockingReasons: (identity: MergeGuardIdentity) => string[];
+//#endregion
+//#region src/review-rungs.d.ts
+declare const EVIDENCE_REVIEW_RUNGS: readonly ["independent-model", "oracle", "human"];
+type EvidenceReviewRung = (typeof EVIDENCE_REVIEW_RUNGS)[number];
+//#endregion
+//#region src/pr-merge-check.d.ts
+interface PrMergeCheckArgs extends LoadProjectProfileInput {
+  epic?: number;
+  json?: boolean;
+  output?: string;
+  pr: number;
+  readyProof?: string;
+}
+interface PrMergeCheckProof {
+  schemaVersion: 1;
+  blockingReasons: string[];
+  boundary?: {
+    autoMerge: boolean;
+    epic: number;
+    review: EvidenceReviewRung;
+    wave: string;
+  };
+  command: "patronage-factory pr:merge-check";
+  /**
+   * Machine-safe arg array for the obvious next action (#523): on `pass`, the
+   * remote-only GitHub merge API invocation for this PR; on `fail`, the re-run that clears the
+   * block (`pr:ready`, or `pr:verify` then `pr:ready` after a head
+   * divergence). Same `argv` shape `factory:delegate --print` emits. Optional
+   * and purely additive — existing consumers ignore it.
+   */
+  followUp?: FollowUpAction;
+  identity: MergeGuardIdentity;
+  /**
+   * The pushed PR head SHA fetched from GitHub at check time. Absent only
+   * when GitHub returned no usable 40-hex head (identity kind
+   * "live-head-invalid"), which is itself a fail-closed blocking state.
+   */
+  liveHeadSha?: string;
+  /**
+   * Actionable operational notices that do not block the merge, e.g. a PR
+   * head branch held by a local worktree, which makes
+   * `gh pr merge --delete-branch` fail (patronage/internal#284).
+   */
+  notices?: string[];
+  pr: number;
+  status: "pass" | "fail";
+  /** 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;
+  showFileAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
+  objectIdAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
+}
+interface PrMergeCheckDependencies {
+  git?: Partial<PrMergeCheckGitDependencies>;
+  github?: {
+    fetchClosingPullRequests?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => {
+      number: number;
+    }[];
+    fetchIssueBody?: (input: {
+      issue: number;
+      owner: string;
+      repo: string;
+    }) => string;
+    fetchPullRequestHead: (input: {
+      cwd: string;
+      owner: string;
+      pr: number;
+      repo: string;
+    }) => {
+      headRefName?: string;
+      headRefOid: string;
+      baseRefName?: string;
+      baseRefOid?: string;
+      mergedAt?: string | null;
+      remoteHeadRefExists?: boolean;
+      labels?: {
+        name: string;
+      }[];
+    };
+    fetchPullRequestReviews?: (input: {
+      owner: string;
+      pr: number;
+      repo: string;
+    }) => GithubPullRequestReview[];
+  };
+  mergeFreeze?: MergeFreezeStore;
+}
+declare function validatePrMergeCheckProof(value: unknown): PrMergeCheckProof;
+declare function readPrMergeCheckProof(filePath: string): PrMergeCheckProof;
+declare function runPrMergeCheck(args: PrMergeCheckArgs, dependencies?: PrMergeCheckDependencies): PrMergeCheckProof;
+//#endregion
+//#region src/pr-proof-io.d.ts
+interface ProofDescriptor<T> {
+  label: string;
+  defaultPath: string;
+  schemaVersion: number;
+  parse: (raw: unknown) => T;
+}
+//#endregion
+//#region src/packages/review-prompt-sections/schema.d.ts
+declare const reviewPromptSectionSchema: z.ZodObject<{
+  provenance: z.ZodEnum<{
+    "prior-review-ledger": "prior-review-ledger";
+    "profile-standing-checklist": "profile-standing-checklist";
+    "issue-review-focus": "issue-review-focus";
+  }>;
+  source: z.ZodString;
+  text: z.ZodString;
+}, z.core.$strict>;
+type ReviewPromptSection = z.infer<typeof reviewPromptSectionSchema>;
+type ReviewPromptSectionProvenance = ReviewPromptSection["provenance"];
+declare const reviewPromptSectionsSchema: z.ZodArray<z.ZodObject<{
+  provenance: z.ZodEnum<{
+    "prior-review-ledger": "prior-review-ledger";
+    "profile-standing-checklist": "profile-standing-checklist";
+    "issue-review-focus": "issue-review-focus";
+  }>;
+  source: z.ZodString;
+  text: z.ZodString;
+}, z.core.$strict>>;
+//#endregion
+//#region src/review-ladder-policy.d.ts
+type ReviewFindingSeverity = "critical" | "high" | "medium" | "low" | "unknown";
+type ReviewFindingCategory = "correctness" | "safety" | "coordination" | "maintainability" | "unknown";
+declare const REVIEW_SEVERITIES: readonly ["critical", "high", "medium", "low", "unknown"];
+declare const resolveReviewFindingSeverity: (priority?: string) => ReviewFindingSeverity;
+declare const resolveReviewFindingCategory: (category?: string) => ReviewFindingCategory;
+declare const FINDING_DISPOSITIONS: readonly ["open", "fixed-in-thread", "follow-up-filed", "waived", "stale-repeat", "rerun-noise"];
+type FindingDisposition = (typeof FINDING_DISPOSITIONS)[number];
+interface ReviewFindingAttributes {
+  blockingAfterCap?: boolean;
+  category?: string;
+  citedSpan?: string;
+  file?: string;
+  prescribedAction?: string;
+  priority?: string;
+  supersedes?: {
+    file?: string;
+    title: string;
+  };
+  title: string;
+}
+type BlockingResolvableFinding = Pick<ReviewFindingAttributes, "blockingAfterCap" | "category" | "priority">;
+declare const resolveFindingBlocking: (finding: BlockingResolvableFinding, disposition?: FindingDisposition) => boolean;
+interface ReviewLadderPolicy {
+  gate: {
+    cap: number;
+  };
+  interior: {
+    cap: number;
+  };
+}
+declare const resolveReviewLadderPolicy: (profile: Pick<FactoryProjectProfile, "review">) => ReviewLadderPolicy;
+//#endregion
+//#region src/review-ladder-ledger.d.ts
+type LadderCycleStage = "interior" | "gate";
+interface LadderCycleRef {
+  cycle: number;
+  stage: LadderCycleStage;
+}
+type LadderFindingReport = ReviewFindingAttributes;
+type DeclarableFindingDisposition = Exclude<FindingDisposition, "open" | "stale-repeat" | "rerun-noise">;
+interface LadderDispositionDeclaration {
+  disposition: DeclarableFindingDisposition;
+  finding: {
+    file?: string;
+    title: string;
+  };
+  findingReport?: LadderFindingReport;
+  reference?: string;
+}
+interface FindingLedgerEntry extends ReviewFindingAttributes {
+  disposition: FindingDisposition;
+  firstFlagged: LadderCycleRef;
+  flagCount: number;
+  key: string;
+  lastFlagged: LadderCycleRef;
+  priorDisposition?: FindingDisposition;
+  reference?: string;
+  reopenedCount: number;
+  staleRepeatCount: number;
+}
+declare const findingKey: (finding: {
+  citedSpan?: string;
+  file?: string;
+  prescribedAction?: string;
+  title?: string;
+}) => string;
+declare const openLadderFindings: (ledger: FindingLedgerEntry[]) => FindingLedgerEntry[];
+declare const blockingLadderFindings: (ledger: FindingLedgerEntry[]) => FindingLedgerEntry[];
+declare const staleRepeatLadderFindings: (ledger: FindingLedgerEntry[]) => FindingLedgerEntry[];
+declare const inferFixedInThreadDispositions: (ledger: FindingLedgerEntry[], findings: readonly LadderFindingReport[], options?: {
+  sameHeadAsPriorCycle?: boolean;
+}) => LadderDispositionDeclaration[];
+//#endregion
+//#region src/review-ladder.d.ts
+type ReviewLadderExecutedStage = "interior" | "gate";
+interface LadderSessionAttribution {
+  orchestrationMode?: "autonomous" | "manual";
+  resumedSession?: boolean;
+  runtime?: string;
+  sessionId?: string;
+}
+interface LadderUsageReport {
+  estimatedCostUsd?: number;
+  source?: string;
+  totalTokens?: number;
+}
+interface ReviewLadderCycle {
+  dispositions?: LadderDispositionDeclaration[];
+  engine?: string;
+  findings: LadderFindingReport[];
+  identity?: {
+    headSha: string;
+    patchId: string;
+  };
+  model?: string;
+  correlatedRerun?: boolean;
+  session?: LadderSessionAttribution;
+  stage: LadderCycleStage;
+  usage?: LadderUsageReport;
+}
+interface LadderInteriorCapTransition {
+  cap: number;
+  kind: "interior-cap-reached";
+}
+interface LadderGateCapTransition {
+  blockingFindings: string[];
+  cap: number;
+  kind: "gate-cap-exhausted";
+}
+type LadderForcedTransition = LadderGateCapTransition | LadderInteriorCapTransition;
+interface LadderRunInteriorCycleAction {
+  cycle: number;
+  kind: "run-interior-cycle";
+}
+type LadderGateNextAction = {
+  cycle: number;
+  kind: "run-gate-cycle";
+} | {
+  kind: "accept-nonblocking-findings";
+} | {
+  kind: "escalate-to-triage";
+} | {
+  kind: "ready-for-human";
+};
+type LadderPosition = {
+  forcedTransition?: LadderGateCapTransition;
+  nextAction: LadderGateNextAction;
+  stage: "gate";
+} | {
+  forcedTransition?: LadderInteriorCapTransition;
+  nextAction: {
+    kind: "advance-to-gate";
+  };
+  stage: "interior-complete";
+} | {
+  forcedTransition?: never;
+  nextAction: LadderRunInteriorCycleAction;
+  stage: "interior";
+};
+type LadderNextAction = LadderPosition["nextAction"];
+type ReviewLadderStage = LadderPosition["stage"];
+interface ReviewLadderStageEvent {
+  cycle: number;
+  cyclesToClean?: number;
+  engine?: string;
+  findingsSummary: {
+    blocking: number;
+    bySeverity: Record<ReviewFindingSeverity, number>;
+    flagged: number;
+    open: number;
+    staleRepeats: number;
+  };
+  forcedTransition?: LadderForcedTransition["kind"];
+  model?: string;
+  payloadVersion: 1;
+  session?: LadderSessionAttribution;
+  stage: ReviewLadderExecutedStage;
+  type: "review-ladder-stage";
+  usage?: LadderUsageReport;
+}
+interface LadderDiagnostic {
+  code: "interior-cycles-unrecorded";
+  message: string;
+}
+type ReviewLadderEvaluation = LadderPosition & {
+  cycleCounts: {
+    gate: number;
+    interior: number;
+  };
+  diagnostics: LadderDiagnostic[];
+  event?: ReviewLadderStageEvent;
+  ledger: FindingLedgerEntry[];
+  unmatchedDispositions: LadderDispositionDeclaration[];
+};
+interface EvaluateReviewLadderInput {
+  cycles: ReviewLadderCycle[];
+  policy: ReviewLadderPolicy;
+}
+declare const evaluateReviewLadder: ({
+  cycles,
+  policy
+}: EvaluateReviewLadderInput) => ReviewLadderEvaluation;
+//#endregion
+//#region src/pr-readiness/ladder-proof-state.d.ts
+interface PrReviewLadderState {
+  cycles: ReviewLadderCycle[];
+}
+interface OpenCycleState {
+  autoBlockingFindings: number;
+  blockingEntries: ReviewFindingAttributes[];
+  openEntries: ReviewFindingAttributes[];
+  staleRepeatFindings?: number;
+}
+interface ReviewLadderSummaryState {
+  cycleCounts: {
+    gate: number;
+    interior: number;
+  };
+  forcedTransition?: LadderForcedTransition["kind"];
+  nextAction: LadderNextAction["kind"];
+  stage: ReviewLadderStage;
+}
+interface ReviewLadderSnapshot {
+  cycleState: OpenCycleState;
+  evaluation: ReviewLadderEvaluation;
+  ledger: FindingLedgerEntry[];
+  policyGateCap: number;
+  summary: ReviewLadderSummaryState;
+}
+type ReviewEpochMode = {
+  kind: "ladder";
+  ladder: PrReviewLadderState;
+  snapshot?: ReviewLadderSnapshot;
+} | {
+  kind: "declared-window";
+};
+//#endregion
+//#region src/pr-readiness/review-proof-types.d.ts
+type PrReviewKind = "correctness" | "security";
+type PrReviewMode = PrReviewKind | "all";
+type PrReviewOutcome = "passed" | "failed" | "error";
+interface PrReviewStageResolution {
+  model: string;
+  sessionId: string;
+}
+//#endregion
+//#region src/pr-readiness/review-proof-shape.d.ts
+interface PrReviewFinding extends ReviewFindingAttributes {
+  body: string;
+  category?: ReviewFindingCategory;
+  line?: number;
+  protocolFinding?: true;
+}
+interface PrReviewResult {
+  kind: PrReviewKind;
+  startedAt: string;
+  endedAt: string;
+  durationMs: number;
+  model?: string;
+  producer?: string;
+  rung?: EvidenceReviewRung;
+  sessionId?: string;
+  outcome: PrReviewOutcome;
+  issuesFlagged: number;
+  summary: string;
+  findings: PrReviewFinding[];
+  typedVerdict?: boolean;
+  verdictSource?: "footer" | "recovered";
+  promptSections?: ReviewPromptSection[];
+}
+interface PrReviewProof {
+  schemaVersion: 2;
+  findingProvenanceVersion: 1;
+  base: string;
+  headSha: string;
+  patchId: string;
+  reviewCycle?: number;
+  maxReviewCycles?: number;
+  changedFiles: string[];
+  cleanedPaths: string[];
+  ladder?: PrReviewLadderState;
+  reviewRequirement?: {
+    reason: "docs-only-profile-bypass";
+    status: "not-required";
+  };
+  reviews: PrReviewResult[];
+}
+//#endregion
+//#region src/pr-readiness/readiness-ledger.d.ts
+declare const SCHEMA_VERSION = 1;
+declare const previewDeploySchema: z.ZodObject<{
+  adminUrl: z.ZodOptional<z.ZodString>;
+  apiHealthUrl: z.ZodOptional<z.ZodString>;
+  headSha: z.ZodOptional<z.ZodString>;
+  localPreviewProof: z.ZodOptional<z.ZodUnknown>;
+  localProofPath: z.ZodOptional<z.ZodString>;
+  proofSource: z.ZodOptional<z.ZodEnum<{
+    "github-actions": "github-actions";
+    "local-self-certified": "local-self-certified";
+  }>>;
+  publicUrl: z.ZodOptional<z.ZodString>;
+  seedStatus: z.ZodEnum<{
+    unknown: "unknown";
+    skipped: "skipped";
+    passed: "passed";
+    failed: "failed";
+  }>;
+  stage: z.ZodOptional<z.ZodString>;
+  timingsMs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodNumber>>>;
+  workflowRunUrl: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const READINESS_REPAIR_CODES: readonly ["undraft-pr", "render-pr-body-sections", "await-post-undraft-checks"];
+declare const readinessRepairSchema: z.ZodObject<{
+  action: z.ZodString;
+  code: z.ZodEnum<{
+    "undraft-pr": "undraft-pr";
+    "render-pr-body-sections": "render-pr-body-sections";
+    "await-post-undraft-checks": "await-post-undraft-checks";
+  }>;
+  command: z.ZodString;
+}, z.core.$strip>;
+declare const managedReadinessLedgerSchema: z.ZodObject<{
+  baseSha: z.ZodString;
+  blockingReasons: z.ZodArray<z.ZodString>;
+  classification: z.ZodEnum<{
+    trivial: "trivial";
+    "docs/process-only": "docs/process-only";
+    "non-trivial": "non-trivial";
+  }>;
+  externalChecks: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    checkType: z.ZodEnum<{
+      review: "review";
+      verify: "verify";
+    }>;
+    inScope: z.ZodBoolean;
+    name: z.ZodString;
+    reason: z.ZodOptional<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>>;
+    scopeReason: z.ZodString;
+    status: z.ZodEnum<{
+      satisfied: "satisfied";
+      unmet: "unmet";
+      "out-of-scope": "out-of-scope";
+    }>;
+  }, z.core.$strip>>>;
+  finalReviewPoint: z.ZodBoolean;
+  github: z.ZodObject<{
+    currentWithBase: z.ZodBoolean;
+    draft: z.ZodBoolean;
+    mergeStateStatus: z.ZodString;
+    mergeable: z.ZodString;
+    requiredChecks: z.ZodEnum<{
+      unknown: "unknown";
+      pending: "pending";
+      passed: "passed";
+      failed: "failed";
+      none: "none";
+    }>;
+    unresolvedReviewThreads: z.ZodNumber;
+  }, z.core.$strip>;
+  handledCommentsProducer: z.ZodOptional<z.ZodObject<{
+    identity: z.ZodString;
+    mode: z.ZodEnum<{
+      app: "app";
+      "commit-status": "commit-status";
+    }>;
+  }, z.core.$strip>>;
+  handledHumanComments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    clearedAt: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    source: z.ZodEnum<{
+      "check-run": "check-run";
+      cli: "cli";
+    }>;
+    url: z.ZodString;
+  }, z.core.$strip>>>;
+  headSha: z.ZodString;
+  mergeBaseSha: z.ZodOptional<z.ZodString>;
+  patchId: z.ZodString;
+  postReadinessHumanComments: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    author: z.ZodString;
+    createdAt: z.ZodString;
+    summary: z.ZodString;
+    url: z.ZodString;
+  }, z.core.$strip>>>;
+  postReadinessHumanReviews: z.ZodOptional<z.ZodArray<z.ZodObject<{
+    author: z.ZodString;
+    createdAt: z.ZodString;
+    summary: z.ZodString;
+    url: z.ZodString;
+  }, z.core.$strip>>>;
+  pr: z.ZodNumber;
+  previewDeploy: z.ZodOptional<z.ZodObject<{
+    adminUrl: z.ZodOptional<z.ZodString>;
+    apiHealthUrl: z.ZodOptional<z.ZodString>;
+    headSha: z.ZodOptional<z.ZodString>;
+    localPreviewProof: z.ZodOptional<z.ZodUnknown>;
+    localProofPath: z.ZodOptional<z.ZodString>;
+    proofSource: z.ZodOptional<z.ZodEnum<{
+      "github-actions": "github-actions";
+      "local-self-certified": "local-self-certified";
+    }>>;
+    publicUrl: z.ZodOptional<z.ZodString>;
+    seedStatus: z.ZodEnum<{
+      unknown: "unknown";
+      skipped: "skipped";
+      passed: "passed";
+      failed: "failed";
+    }>;
+    stage: z.ZodOptional<z.ZodString>;
+    timingsMs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodOptional<z.ZodNumber>>>;
+    workflowRunUrl: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>>;
+  previewDeployRequired: z.ZodBoolean;
+  repairs: z.ZodDefault<z.ZodArray<z.ZodObject<{
+    action: z.ZodString;
+    code: z.ZodEnum<{
+      "undraft-pr": "undraft-pr";
+      "render-pr-body-sections": "render-pr-body-sections";
+      "await-post-undraft-checks": "await-post-undraft-checks";
+    }>;
+    command: z.ZodString;
+  }, z.core.$strip>>>;
+  reviewCycleState: z.ZodOptional<z.ZodObject<{
+    autoBlockingFindings: z.ZodNumber;
+    countsBySeverity: z.ZodObject<{
+      critical: z.ZodNumber;
+      high: z.ZodNumber;
+      low: z.ZodNumber;
+      medium: z.ZodNumber;
+      unknown: z.ZodNumber;
+    }, z.core.$strip>;
+    highestBlockingSeverity: z.ZodOptional<z.ZodEnum<{
+      unknown: "unknown";
+      critical: "critical";
+      high: "high";
+      low: "low";
+      medium: "medium";
+    }>>;
+    highestOpenSeverity: z.ZodOptional<z.ZodEnum<{
+      unknown: "unknown";
+      critical: "critical";
+      high: "high";
+      low: "low";
+      medium: "medium";
+    }>>;
+    maxReviewCycles: z.ZodOptional<z.ZodNumber>;
+    nonBlockingFindings: z.ZodNumber;
+    openFindings: z.ZodNumber;
+    reviewCycle: z.ZodOptional<z.ZodNumber>;
+    staleRepeatFindings: z.ZodOptional<z.ZodNumber>;
+    windowExhausted: z.ZodBoolean;
+  }, z.core.$strip>>;
+  reviewLadder: z.ZodOptional<z.ZodObject<{
+    cycleCounts: z.ZodObject<{
+      gate: z.ZodNumber;
+      interior: z.ZodNumber;
+    }, z.core.$strip>;
+    forcedTransition: z.ZodOptional<z.ZodEnum<{
+      "gate-cap-exhausted": "gate-cap-exhausted";
+      "interior-cap-reached": "interior-cap-reached";
+    }>>;
+    nextAction: z.ZodEnum<{
+      "run-gate-cycle": "run-gate-cycle";
+      "accept-nonblocking-findings": "accept-nonblocking-findings";
+      "escalate-to-triage": "escalate-to-triage";
+      "ready-for-human": "ready-for-human";
+      "advance-to-gate": "advance-to-gate";
+      "run-interior-cycle": "run-interior-cycle";
+    }>;
+    stage: z.ZodEnum<{
+      gate: "gate";
+      interior: "interior";
+      "interior-complete": "interior-complete";
+    }>;
+  }, z.core.$strip>>;
+  reviewRuns: z.ZodOptional<z.ZodArray<z.ZodType<PrReviewResult, unknown, z.core.$ZodTypeInternals<PrReviewResult, unknown>>>>;
+  reviewTerminalState: z.ZodOptional<z.ZodEnum<{
+    blocked: "blocked";
+    "accepted-with-findings": "accepted-with-findings";
+    clean: "clean";
+  }>>;
+  reviews: z.ZodObject<{
+    correctness: z.ZodObject<{
+      docsOnlyDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
+      required: z.ZodBoolean;
+      reviewedHeadSha: z.ZodOptional<z.ZodString>;
+      reviewedPatchId: z.ZodOptional<z.ZodString>;
+      status: z.ZodEnum<{
+        blocked: "blocked";
+        "not-required": "not-required";
+        current: "current";
+        stale: "stale";
+        missing: "missing";
+      }>;
+    }, z.core.$strip>;
+    security: z.ZodOptional<z.ZodObject<{
+      docsOnlyDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
+      required: z.ZodBoolean;
+      reviewedHeadSha: z.ZodOptional<z.ZodString>;
+      reviewedPatchId: z.ZodOptional<z.ZodString>;
+      status: z.ZodEnum<{
+        blocked: "blocked";
+        "not-required": "not-required";
+        current: "current";
+        stale: "stale";
+        missing: "missing";
+      }>;
+    }, z.core.$strip>>;
+  }, z.core.$strip>;
+  schemaVersion: z.ZodLiteral<1>;
+  stackRole: z.ZodEnum<{
+    slice: "slice";
+    single: "single";
+    rollup: "rollup";
+    "merge-gate prerequisite": "merge-gate prerequisite";
+  }>;
+  verification: z.ZodObject<{
+    command: z.ZodLiteral<"patronage-factory pr:verify">;
+    docsOnlyDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
+    docsOnlyVerifiedHeadSha: z.ZodOptional<z.ZodString>;
+    prVerify: z.ZodEnum<{
+      passed: "passed";
+      stale: "stale";
+      missing: "missing";
+    }>;
+    trivialDeltaAccepted: z.ZodOptional<z.ZodBoolean>;
+    trivialVerifiedHeadSha: z.ZodOptional<z.ZodString>;
+    verifiedHeadSha: z.ZodOptional<z.ZodString>;
+  }, z.core.$strip>;
+}, z.core.$strip>;
+type PreviewDeployProof = z.infer<typeof previewDeploySchema>;
+type PreviewSeedStatus = PreviewDeployProof["seedStatus"];
+type ReadinessRepair = z.infer<typeof readinessRepairSchema>;
+type ReadinessStatus = "ready" | "blocked" | "slice-ready/not-final";
+type ManagedReadinessLedger = z.infer<typeof managedReadinessLedgerSchema>;
+declare function validateManagedReadinessLedger(value: unknown): ManagedReadinessLedger;
+declare namespace status_check_rollup_d_exports {
+  export { CheckState, StatusCheckRollup, isFactoryReadyCheck, statusCheckState };
+}
+type CheckState = "passed" | "failed" | "pending" | "none" | "unknown";
+interface StatusCheckRollup {
+  __typename?: string;
+  completedAt?: string;
+  conclusion?: string;
+  context?: string;
+  name?: string;
+  startedAt?: string;
+  state?: string;
+  status?: string;
+  workflowName?: string;
+}
+declare const isFactoryReadyCheck: (check: StatusCheckRollup) => boolean;
+declare const statusCheckState: (rollup: StatusCheckRollup[] | undefined, exclude?: (check: StatusCheckRollup) => boolean) => CheckState;
+//#endregion
+//#region src/pr-ready.d.ts
+interface PrReadyArgs extends LoadProjectProfileInput {
+  authoringSessionIds?: string[];
+  base: string;
+  bodyForEvaluation?: string;
+  handledCommentUrls?: string[];
+  json?: boolean;
+  output?: string;
+  report?: boolean;
+  pr: number;
+  reviewProof?: string;
+  throwWhenBlocked?: boolean;
+  verifyProof?: string;
+}
+interface GitHubPullRequest {
+  baseRefName: string;
+  baseRefOid: string;
+  body: string;
+  comments: {
+    author?: {
+      login?: string;
+    };
+    body: string;
+    createdAt?: string;
+    id?: string | number;
+    updatedAt?: string;
+    url?: string;
+  }[];
+  headRefOid: string;
+  isDraft: boolean;
+  labels?: {
+    name: string;
+  }[];
+  mergeStateStatus: string;
+  mergeable: string;
+  number: number;
+  reviews?: {
+    author?: {
+      login?: string;
+    };
+    body?: string;
+    lastEditedAt?: string;
+    state: string;
+    submittedAt?: string;
+    url?: string;
+  }[];
+  statusCheckRollup?: StatusCheckRollup[];
+  title: string;
+  unresolvedReviewThreads: number;
+  url: string;
+}
+interface PrReadyProof {
+  schemaVersion: 1;
+  blockingReasons: string[];
+  humanBlockingReasons: string[];
+  command: "patronage-factory pr:ready";
+  /**
+   * Machine-safe arg array for the obvious next action (#523): when `ready`,
+   * the `pr:merge-check` that must precede a merge; otherwise the `pr:verify`
+   * re-run that the blocking reasons name (re-verify the head, then re-run
+   * pr:ready). Same `argv` shape `factory:delegate --print` emits. Optional
+   * and purely additive.
+   */
+  followUp?: FollowUpAction;
+  /**
+   * `ledger.headSha` is the evaluated head SHA: the GitHub `pr.headRefOid`
+   * captured at evaluation time (not a local git read), recorded explicitly
+   * so merge-time identity checks are a pure comparison against the live
+   * pushed HEAD, not a re-derivation. See the ledger schema.
+   */
+  ledger: ManagedReadinessLedger;
+  /** Committed profile blob evaluated by readiness. Required for merge. */
+  profileBlobSha?: string;
+  /** Checkout-relative committed profile path evaluated by readiness. */
+  profilePath?: string;
+  repairs: ReadinessRepair[];
+  /** Trusted checkout repository used for all GitHub reads and writes. */
+  repository?: string;
+  status: ReadinessStatus;
+}
+type PublishHandledCommentsResult = HandledCommentsProducer | Promise<HandledCommentsProducer | undefined> | undefined;
+interface PrReadyDependencies {
+  github?: {
+    fetchHandledComments?: (input: {
+      owner: string;
+      pr: number;
+      repo: string;
+    }) => {
+      producer?: HandledCommentsProducer;
+      urls: string[];
+    }; /** @deprecated Prefer fetchHandledComments (includes producer identity). */
+    fetchHandledCommentUrls?: (input: {
+      owner: string;
+      pr: number;
+      repo: string;
+    }) => string[];
+    fetchPullRequest: (input: {
+      owner: string;
+      repo: string;
+      pr: number;
+    }) => GitHubPullRequest;
+    publishHandledCommentsCheck?: (input: PublishHandledCommentsCheckInput) => PublishHandledCommentsResult;
+  };
+  git?: PrReadyGitDependencies;
+  hq?: HqIngestDependencies;
+  publishCheckRun?: (input: PublishFactoryCheckInput) => void;
+  /** Injectable delay for the UNKNOWN-mergeable brief poll (tests). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Injectable clock for CLI handled-comment provenance (tests). */
+  now?: () => Date;
+}
+interface PrReadyGitDependencies {
+  canResolveCommit: (cwd: string, sha: string) => boolean;
+  changedFiles: (cwd: string, base: string, headSha?: string) => string[];
+  checkoutRepository: (cwd: string) => CheckoutRepository;
+  currentHeadSha: (cwd: string) => string;
+  mergeBaseSha: (cwd: string, base: string) => string;
+  objectIdAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
+  resolveCommitSha: (cwd: string, ref: string) => string | undefined;
+  showFileAtRef: (cwd: string, ref: string, absolutePath: string) => string | undefined;
+  stablePatchId: (cwd: string, base: string) => string;
+}
+declare function validatePrReadyProof(value: unknown): PrReadyProof;
+declare function readPrReadyProof(filePath: string): PrReadyProof;
+declare function runPrReady(args: PrReadyArgs, dependencies?: PrReadyDependencies): Promise<PrReadyProof>;
+//#endregion
+//#region src/required-check-policy.d.ts
+declare const EVIDENCE_CHECK_TYPES: readonly ["review", "verify"];
+type EvidenceCheckType = (typeof EVIDENCE_CHECK_TYPES)[number];
+declare const requiredCheckScopeSchema: z.ZodObject<{
+  classifications: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+    trivial: "trivial";
+    "docs/process-only": "docs/process-only";
+    "non-trivial": "non-trivial";
+  }>>>;
+  labels: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+type RequiredCheckScope = z.infer<typeof requiredCheckScopeSchema>;
+interface RequiredCheckScopeContext {
+  labels: string[] | undefined;
+  classification: DiffClassification;
+}
+interface ScopeDecision {
+  inScope: boolean;
+  reason: string;
+}
+declare const requiredCheckInScope: ({
+  context,
+  scope
+}: {
+  context: RequiredCheckScopeContext;
+  scope?: RequiredCheckScope;
+}) => ScopeDecision;
+interface RequiredCheck {
+  name: string;
+  checkType: EvidenceCheckType;
+  scope?: RequiredCheckScope;
+}
+//#endregion
+//#region src/factory-session.d.ts
+declare const resolveAuthoringSessionIds: ({
+  override,
+  recorded
+}: {
+  override?: string[];
+  recorded?: string;
+}) => string[];
+declare namespace external_evidence_d_exports {
+  export { EVIDENCE_CHECK_TYPES, EVIDENCE_DIR, EVIDENCE_ENVELOPE_SCHEMA_VERSION, EVIDENCE_REVIEW_RUNGS, EvidenceCandidateIdentity, EvidenceCheckType, EvidenceEnvelope, EvidenceEnvelopeParse, EvidenceReviewRung, IndependenceResult, LoadedEvidenceEnvelope, RequiredCheck, RequiredCheckEvaluation, RequiredCheckEvaluationInput, RequiredCheckOutcome, RequiredCheckScope, RequiredCheckScopeContext, ScopeDecision, evaluateRequiredChecks, evidenceBindingFresh, evidenceEnvelopeSchema, evidenceReviewIndependence, loadEvidenceEnvelopes, parseEvidenceEnvelope, requiredCheckInScope, requiredCheckScopeSchema, resolveAuthoringSessionIds };
+}
+declare const EVIDENCE_ENVELOPE_SCHEMA_VERSION = 1;
+declare const evidenceEnvelopeBaseSchema: z.ZodObject<{
+  check: z.ZodString;
+  checkType: z.ZodEnum<{
+    review: "review";
+    verify: "verify";
+  }>;
+  findingsPointer: z.ZodOptional<z.ZodString>;
+  headSha: z.ZodString;
+  mergeBaseSha: z.ZodString;
+  model: z.ZodOptional<z.ZodString>;
+  outcome: z.ZodEnum<{
+    pass: "pass";
+    fail: "fail";
+  }>;
+  patchId: z.ZodString;
+  policyVersion: z.ZodOptional<z.ZodString>;
+  producer: z.ZodString;
+  requestId: z.ZodOptional<z.ZodString>;
+  rung: z.ZodOptional<z.ZodEnum<{
+    oracle: "oracle";
+    "independent-model": "independent-model";
+    human: "human";
+  }>>;
+  schemaVersion: z.ZodLiteral<1>;
+  sessionId: z.ZodOptional<z.ZodString>;
+  timestamp: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$loose>;
+declare const evidenceEnvelopeSchema: z.ZodObject<{
+  check: z.ZodString;
+  checkType: z.ZodEnum<{
+    review: "review";
+    verify: "verify";
+  }>;
+  findingsPointer: z.ZodOptional<z.ZodString>;
+  headSha: z.ZodString;
+  mergeBaseSha: z.ZodString;
+  model: z.ZodOptional<z.ZodString>;
+  outcome: z.ZodEnum<{
+    pass: "pass";
+    fail: "fail";
+  }>;
+  patchId: z.ZodString;
+  policyVersion: z.ZodOptional<z.ZodString>;
+  producer: z.ZodString;
+  requestId: z.ZodOptional<z.ZodString>;
+  rung: z.ZodOptional<z.ZodEnum<{
+    oracle: "oracle";
+    "independent-model": "independent-model";
+    human: "human";
+  }>>;
+  schemaVersion: z.ZodLiteral<1>;
+  sessionId: z.ZodOptional<z.ZodString>;
+  timestamp: z.ZodOptional<z.ZodISODateTime>;
+}, z.core.$loose>;
+type EvidenceEnvelope = z.infer<typeof evidenceEnvelopeBaseSchema>;
+type EvidenceEnvelopeParse = {
+  ok: true;
+  envelope: EvidenceEnvelope;
+} | {
+  ok: false;
+  error: string;
+};
+declare const parseEvidenceEnvelope: (raw: unknown) => EvidenceEnvelopeParse;
+interface EvidenceCandidateIdentity {
+  headSha: string;
+  patchId: string;
+  mergeBaseSha: string;
+}
+declare const evidenceBindingFresh: ({
+  candidate,
+  envelope
+}: {
+  candidate: EvidenceCandidateIdentity;
+  envelope: EvidenceEnvelope;
+}) => boolean;
+interface IndependenceResult {
+  independent: boolean;
+  reason?: "no-session" | "unknown-authoring-identity" | "same-session";
+}
+declare const evidenceReviewIndependence: ({
+  authoringSessionIds,
+  envelope
+}: {
+  authoringSessionIds: string[];
+  envelope: EvidenceEnvelope;
+}) => IndependenceResult;
+type LoadedEvidenceEnvelope = {
+  ok: true;
+  envelope: EvidenceEnvelope;
+  path: string;
+} | {
+  check?: string;
+  error: string;
+  ok: false;
+  path: string;
+};
+interface RequiredCheckEvaluationInput {
+  authoringSessionIds: string[];
+  candidate: EvidenceCandidateIdentity;
+  envelopes: LoadedEvidenceEnvelope[];
+  requiredChecks: RequiredCheck[];
+  scopeContext: RequiredCheckScopeContext;
+}
+interface RequiredCheckOutcome {
+  name: string;
+  checkType: EvidenceCheckType;
+  status: "satisfied" | "unmet" | "out-of-scope";
+  inScope: boolean;
+  scopeReason: string;
+  scope?: RequiredCheckScope;
+  reason?: string;
+  matchedPath?: string;
+}
+interface RequiredCheckEvaluation {
+  outcomes: RequiredCheckOutcome[];
+  blockingReasons: string[];
+}
+declare const evaluateRequiredChecks: ({
+  authoringSessionIds,
+  candidate,
+  envelopes,
+  requiredChecks,
+  scopeContext
+}: RequiredCheckEvaluationInput) => RequiredCheckEvaluation;
+declare const EVIDENCE_DIR = ".factory-memory/evidence";
+declare const loadEvidenceEnvelopes: (cwd: string) => LoadedEvidenceEnvelope[];
+//#endregion
+//#region src/review-proof-applicability.d.ts
+declare const REVIEW_STATUS_VALUES: readonly ["not-required", "current", "stale", "missing", "blocked"];
+declare const reviewStatusSchema: z.ZodEnum<{
+  blocked: "blocked";
+  "not-required": "not-required";
+  current: "current";
+  stale: "stale";
+  missing: "missing";
+}>;
+type ReviewStatus = z.infer<typeof reviewStatusSchema>;
+interface CurrentReviewIdentity {
+  headSha: string;
+  patchId: string;
+}
+declare const reviewStatus: ({
+  blocked,
+  required,
+  reviewedHeadSha,
+  reviewedPatchId,
+  headSha,
+  patchId
+}: CurrentReviewIdentity & {
+  blocked?: boolean;
+  required: boolean;
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+}) => ReviewStatus;
+declare namespace proof_identity_d_exports {
+  export { CurrentReviewIdentity, REVIEW_STATUS_VALUES, ReviewProofClaim, ReviewStatus, explicitFailureIdentity, isExplicitReviewFailure, isUntypedReviewProof, reviewStatus, reviewStatusSchema, selectReviewProof };
+}
+type ReviewProofClaim = {
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+  untypedVerdict?: boolean;
+} | {
+  explicitFailure: true;
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+  untypedVerdict?: boolean;
+};
+declare const isExplicitReviewFailure: (proof: ReviewProofClaim) => proof is {
+  explicitFailure: true;
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+  untypedVerdict?: boolean;
+};
+declare const isUntypedReviewProof: (proof: ReviewProofClaim) => proof is {
+  untypedVerdict: true;
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+};
+declare const explicitFailureIdentity: (proof: ReviewProofClaim) => {
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+};
+declare const selectReviewProof: ({
+  reviewProof
+}: {
+  reviewProof: ReviewProofClaim;
+}) => {
+  reviewedHeadSha?: string;
+  reviewedPatchId?: string;
+  untypedVerdict?: boolean;
+};
+//#endregion
+//#region src/pr-readiness/review-epoch.d.ts
+interface ReviewCycleState {
+  autoBlockingFindings: number;
+  countsBySeverity: Record<ReviewFindingSeverity, number>;
+  highestBlockingSeverity?: ReviewFindingSeverity;
+  highestOpenSeverity?: ReviewFindingSeverity;
+  maxReviewCycles?: number;
+  nonBlockingFindings: number;
+  openFindings: number;
+  reviewCycle?: number;
+  staleRepeatFindings?: number;
+  windowExhausted: boolean;
+}
+declare const reviewCycleStateFor: (proof: Pick<PrReviewProof, "ladder" | "reviewCycle" | "maxReviewCycles" | "reviews">, policy?: ReviewLadderPolicy, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewCycleState;
+type ReviewAcceptance = "accepted-after-cap" | "accepted-clean" | "accepted-through-ladder" | "blocked";
+declare const resolveReviewAcceptance: (proof: PrReviewProof, review: PrReviewResult, policy: ReviewLadderPolicy | undefined) => ReviewAcceptance;
+type ReviewTerminalState = "accepted-with-findings" | "blocked" | "clean";
+declare const resolveReviewTerminalStateForEpoch: (proof: PrReviewProof, review: PrReviewResult, epoch: ReviewEpochMode, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewTerminalState;
+declare const resolveReviewTerminalState: (proof: PrReviewProof, review: PrReviewResult, policy: ReviewLadderPolicy | undefined) => ReviewTerminalState;
+declare const resolveReviewTerminalStateAcrossReviews: (proof: PrReviewProof, epoch: ReviewEpochMode, adjudicatedLedger?: FindingLedgerEntry[]) => ReviewTerminalState | undefined;
+declare const resolveReviewTerminalStateAcrossReviewsForPolicy: (proof: PrReviewProof, policy: ReviewLadderPolicy) => ReviewTerminalState | undefined;
+declare const reviewProofFor: (proof: PrReviewProof | undefined, kind: PrReviewKind, policy: ReviewLadderPolicy | undefined, current?: {
+  patchId: string;
+}) => ReviewProofClaim;
+declare namespace review_proof_d_exports {
+  export { DEFAULT_PR_REVIEW_MAX_CYCLES, DEFAULT_PR_REVIEW_PROOF_PATH, PR_REVIEW_FINAL_READINESS_NOTICE, PR_REVIEW_FINDING_PROVENANCE_VERSION, PR_REVIEW_PROOF_DESCRIPTOR, PR_REVIEW_SCHEMA_VERSION, PrReviewFinding, PrReviewKind, PrReviewLadderState, PrReviewMode, PrReviewOutcome, PrReviewProof, PrReviewResult, PrReviewStageResolution, REVIEW_SEVERITIES, ReviewAcceptance, ReviewCycleState, ReviewFindingCategory, ReviewFindingSeverity, ReviewTerminalState, prReviewFindingSchema, prReviewProofSchema, prReviewResultSchema, readPrReviewProof, resolveReviewAcceptance, resolveReviewTerminalState, resolveReviewTerminalStateAcrossReviews, resolveReviewTerminalStateAcrossReviewsForPolicy, resolveReviewTerminalStateForEpoch, reviewCycleStateFor, reviewProofFor, validatePrReviewProof, validatePrReviewResult };
+}
+declare const PR_REVIEW_SCHEMA_VERSION = 2;
+declare const PR_REVIEW_FINDING_PROVENANCE_VERSION = 1;
+declare const DEFAULT_PR_REVIEW_PROOF_PATH = ".factory-memory/pr-review.json";
+declare const DEFAULT_PR_REVIEW_MAX_CYCLES = 5;
+declare const PR_REVIEW_FINAL_READINESS_NOTICE = "pr:review is a final readiness proof gate. Run it after local verification and avoid repeated full runs unless the review proof records actionable findings. Default review window: 5 cycles.";
+declare const prReviewFindingSchema: z.ZodType<PrReviewFinding>;
+declare const prReviewResultSchema: z.ZodType<PrReviewResult>;
+declare const prReviewProofSchema: z.ZodType<PrReviewProof>;
+declare const validatePrReviewResult: (value: unknown) => PrReviewResult;
+declare const validatePrReviewProof: (value: unknown) => PrReviewProof;
+declare const readPrReviewProof: (filePath: string) => PrReviewProof;
+declare const PR_REVIEW_PROOF_DESCRIPTOR: ProofDescriptor<PrReviewProof>;
+declare namespace verification_proof_d_exports {
+  export { PrVerifyBaselineFullProof, PrVerifyCommandResult, PrVerifyExecutedCommand, PrVerifyProof, PrVerifySchemaVersion, ResolvedPrVerifyMode, SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS, VerificationHeadShas, VerificationProofState, VerifiedHeadShas, prVerifyFullHeadShasForDiff, prVerifyProofHeadShas, readPrVerifyProof, resolveVerifyProofApplicability, validatePrVerifyProof, verificationProofApplicabilityFor, verificationProofBlockingReason, verificationProofForReadiness, verificationProofStateFor, verifyProofIdentityMatches, verifyProofPassed };
+}
+interface VerifiedHeadShas {
+  docsOnlyVerifiedHeadShas: string[];
+  trivialVerifiedHeadShas: string[];
+  verifiedHeadShas: string[];
+}
+type VerificationHeadShas = {
+  explicitFailure: true;
+} | VerifiedHeadShas;
+declare const SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS: readonly [1, 2, 3, 4];
+type PrVerifySchemaVersion = (typeof SUPPORTED_PR_VERIFY_SCHEMA_VERSIONS)[number];
+interface PrVerifyCommandResult {
+  command: string;
+  description: string;
+  name: string;
+  scope: "always" | "docs-only" | "trivial" | "full";
+}
+interface PrVerifyExecutedCommand {
+  command: string;
+  counts?: {
+    testFiles?: number;
+    tests?: number;
+  };
+  durationMs: number;
+  exitCode: number;
+  name: string;
+  scope: "always" | "docs-only" | "trivial" | "full";
+}
+interface PrVerifyProof {
+  schemaVersion: PrVerifySchemaVersion;
+  authoringSession?: string;
+  base: string;
+  baselineFullProofs?: {
+    base: string;
+    changedFiles: string[];
+    headSha: string;
+    profilePath: string;
+    projectKey: string;
+    repository: string;
+  }[];
+  changedFiles: string[];
+  classification: DiffClassification;
+  classificationReasons: string[];
+  command: "patronage-factory pr:verify";
+  durationMs: number;
+  endedAt: string;
+  executedCommands?: PrVerifyExecutedCommand[];
+  headSha: string;
+  mode: ResolvedPrVerifyMode;
+  mergeBaseSha?: string;
+  outcome?: "aborted" | "passed";
+  patchId?: string;
+  profilePath: string;
+  projectKey: string;
+  repository: string;
+  startedAt: string;
+  verificationCommands: PrVerifyCommandResult[];
+}
+type PrVerifyBaselineFullProof = NonNullable<PrVerifyProof["baselineFullProofs"]>[number];
+declare function validatePrVerifyProof(value: unknown): PrVerifyProof;
+declare function readPrVerifyProof(filePath: string): PrVerifyProof;
+declare const verifyProofPassed: (proof: PrVerifyProof) => boolean;
+declare const prVerifyProofHeadShas: (proof: PrVerifyProof | undefined, creditedHeadSha?: string) => VerifiedHeadShas;
+declare const verifyProofIdentityMatches: ({
+  currentIdentity,
+  proof
+}: {
+  currentIdentity?: {
+    patchId: string;
+    mergeBaseSha?: string;
+  };
+  proof?: PrVerifyProof;
+}) => boolean;
+declare const prVerifyFullHeadShasForDiff: ({
+  docsOnlyDeltaAcceptedSince,
+  files,
+  proof
+}: {
+  docsOnlyDeltaAcceptedSince?: (baselineHeadSha: string) => boolean;
+  files: string[];
+  proof: PrVerifyProof;
+}) => string[];
+type VerificationProofState = {
+  kind: "typed-aborted";
+  proof: PrVerifyProof;
+} | {
+  kind: "typed-missing";
+  path: string;
+  reason: "enoent" | "invalid";
+  message?: string;
+} | {
+  kind: "typed";
+  headShas: VerifiedHeadShas;
+  proof: PrVerifyProof;
+} | {
+  kind: "typed-diff-mismatch";
+  mode: ResolvedPrVerifyMode;
+};
+declare const verificationProofStateFor: ({
+  proof,
+  proofMatchesCurrentDiff,
+  proofPath
+}: {
+  proof?: PrVerifyProof;
+  proofMatchesCurrentDiff?: boolean;
+  proofPath?: string;
+}) => VerificationProofState;
+declare const verificationProofApplicabilityFor: ({
+  docsOnlyDeltaAcceptedSince,
+  explicitProof,
+  files,
+  headSha,
+  currentIdentity,
+  proof,
+  proofPath,
+  proofReadError
+}: {
+  docsOnlyDeltaAcceptedSince?: (baselineHeadSha: string) => boolean;
+  explicitProof: boolean;
+  files: string[];
+  headSha: string;
+  currentIdentity?: {
+    patchId: string;
+    mergeBaseSha?: string;
+  };
+  proof?: PrVerifyProof;
+  proofPath?: string;
+  proofReadError?: unknown;
+}) => {
+  fullVerifiedHeadShas: never[];
+  verificationProof: VerificationProofState;
+} | {
+  fullVerifiedHeadShas: string[];
+  verificationProof: {
+    headShas: VerifiedHeadShas;
+    kind: "typed";
+    proof: PrVerifyProof;
+  };
+};
+declare const resolveVerifyProofApplicability: ({
+  proofPath,
+  explicitProof,
+  docsOnlyDeltaAcceptedSince,
+  files,
+  headSha,
+  currentVerifyIdentityForBase,
+  preread
+}: {
+  proofPath: string;
+  explicitProof: boolean;
+  docsOnlyDeltaAcceptedSince?: (baselineHeadSha: string) => boolean;
+  files: string[];
+  headSha: string;
+  currentVerifyIdentityForBase?: (base: string) => {
+    patchId: string;
+    mergeBaseSha?: string;
+  };
+  preread?: {
+    proof?: PrVerifyProof;
+    error?: unknown;
+  };
+}) => {
+  fullVerifiedHeadShas: never[];
+  verificationProof: VerificationProofState;
+} | {
+  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/schemas.d.ts
+declare const boundaryCheckProofSchema: z.ZodObject<{
+  blockingReasons: z.ZodArray<z.ZodString>;
+  boundary: z.ZodOptional<z.ZodString>;
+  command: z.ZodLiteral<"patronage-factory boundary:check">;
+  coveredSet: z.ZodArray<z.ZodObject<{
+    issue: z.ZodOptional<z.ZodNumber>;
+    pr: z.ZodNumber;
+    sha: z.ZodString;
+    state: z.ZodEnum<{
+      open: "open";
+      merged: "merged";
+    }>;
+    wave: z.ZodString;
+  }, z.core.$strip>>;
+  demandedRung: z.ZodOptional<z.ZodEnum<{
+    oracle: "oracle";
+    "independent-model": "independent-model";
+    human: "human";
+  }>>;
+  epicIssue: z.ZodNumber;
+  manifestHash: z.ZodOptional<z.ZodObject<{
+    algo: z.ZodLiteral<"sha256">;
+    value: z.ZodString;
+  }, z.core.$strip>>;
+  notices: z.ZodArray<z.ZodString>;
+  repo: z.ZodString;
+  reviewProof: z.ZodOptional<z.ZodObject<{
+    commentId: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+    commentUrl: z.ZodOptional<z.ZodString>;
+    producer: z.ZodString;
+    rung: z.ZodEnum<{
+      oracle: "oracle";
+      "independent-model": "independent-model";
+      human: "human";
+    }>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    specHash: z.ZodOptional<z.ZodObject<{
+      algo: z.ZodLiteral<"sha256">;
+      scope: z.ZodOptional<z.ZodString>;
+      value: z.ZodString;
+    }, z.core.$loose>>;
+  }, z.core.$strip>>;
+  schemaVersion: z.ZodLiteral<1>;
+  specHash: z.ZodOptional<z.ZodObject<{
+    algo: z.ZodLiteral<"sha256">;
+    value: z.ZodString;
+  }, z.core.$strip>>;
+  status: z.ZodEnum<{
+    blocked: "blocked";
+    ready: "ready";
+  }>;
+}, z.core.$strip>;
+type BoundaryCheckProofRecord = z.infer<typeof boundaryCheckProofSchema>;
+//#endregion
+//#region src/boundary-check.d.ts
+interface BoundaryPullRequestRef {
+  headRefOid?: string;
+  mergeCommitOid?: string;
+  number: number;
+  state: "OPEN" | "CLOSED" | "MERGED";
+}
+interface BoundaryCheckGithub {
+  fetchIssueBody: (repo: string, issue: number) => string;
+  fetchIssueComments: (repo: string, issue: number) => GithubIssueComment[];
+  fetchClosingPullRequests: (repo: string, issue: number) => BoundaryPullRequestRef[];
+  fetchPullRequest: (repo: string, pr: number) => BoundaryPullRequestRef;
+}
+interface BoundaryCheckArgs {
+  cwd?: string;
+  epic: number;
+  json?: boolean;
+  output?: string;
+  repo?: string;
+}
+interface BoundaryCheckDependencies {
+  github?: BoundaryCheckGithub;
+  hq?: HqIngestDependencies;
+  resolveRepo?: (cwd: string) => string;
+}
+declare function runBoundaryCheck(args: BoundaryCheckArgs, dependencies?: BoundaryCheckDependencies): BoundaryCheckProofRecord;
+declare function validateBoundaryCheckProof(value: unknown): BoundaryCheckProofRecord;
+//#endregion
+//#region src/commands/doctor.d.ts
+interface CliOutput {
+  stderr: Pick<NodeJS.WriteStream, "write">;
+  stdout: Pick<NodeJS.WriteStream, "write">;
+}
+//#endregion
+//#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;
+}
+//#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;
+}
+interface PrVerifyArgs extends LoadProjectProfileInput {
+  authoringSession?: string;
+  base: string;
+  mode: PrVerifyMode;
+  output?: string;
+  requireKnownAuthoringSession?: boolean;
+}
+interface PrVerifyGitDependencies {
+  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;
+  stablePatchId: (cwd: string, base: string) => string;
+}
+interface PrVerifyDependencies {
+  cleanInstall?: CleanInstallResolutionDependencies | false;
+  env?: NodeJS.ProcessEnv;
+  git?: PrVerifyGitDependencies;
+  hq?: HqIngestDependencies;
+  postCommitStatus?: PostCommitStatus;
+  publishCheckRun?: (input: PublishFactoryCheckInput) => void;
+}
+declare function runPrVerify(args: PrVerifyArgs, dependencies?: PrVerifyDependencies): PrVerifyProof;
+//#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;
+}
+//#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 {
+  base: string;
+  cycle: number;
+  dispositions?: string;
+  findings?: string;
+  issue?: number;
+  maxCycles?: number;
+  mode: PrReviewMode;
+  output?: string;
+  verifyProof?: string;
+}
+interface PrReviewGitDependencies {
+  changedFiles: (cwd: string, base: string) => string[];
+  currentHeadSha: (cwd: string) => string;
+  isAncestor: (cwd: string, ancestor: string, descendant: string) => boolean;
+  stablePatchId: (cwd: string, base: string) => string;
+  statusPorcelain: (cwd: string) => string;
+}
+interface PrReviewDependencies {
+  git?: PrReviewGitDependencies;
+  hq?: HqIngestDependencies;
+  publishCheckRun?: (input: PublishFactoryCheckInput) => void;
+}
+declare function runPrReview(args: PrReviewArgs, dependencies?: PrReviewDependencies): Promise<PrReviewProof>;
+//#endregion
+//#region src/pr-publish.d.ts
+type PrPublishArgs = Omit<PrReadyArgs, "pr" | "throwWhenBlocked"> & {
+  /** A clean-session findings file to validate into the review proof. */findings?: string;
+  pr?: number;
+};
+type GhRunner = (args: string[], cwd: string) => string;
+type FollowUpRunner = (followUp: FollowUpAction, cwd: string) => Promise<void> | void;
+interface PrPublishHandoff {
+  humanActions: string[];
+  routeOwnedRepairs: ReadinessRepair[];
+  status: PrReadyProof["status"];
+}
+type PrPublishFollowUpOutcome = {
+  status: "not-requested";
+} | {
+  action: FollowUpAction;
+  reason: string;
+  status: "succeeded";
+} | {
+  action: FollowUpAction;
+  error: string;
+  status: "failed";
+}
+/**
+ * The planner declined to run the follow-up because it cannot change the
+ * condition that produced it (#291). `reason` is the one-line causal
+ * statement; a skip is a decision, never a silent omission.
+ */
+| {
+  action: FollowUpAction;
+  reason: string;
+  status: "skipped";
+};
+interface PrPublishResult {
+  bodyPatched: boolean;
+  followUp: PrPublishFollowUpOutcome;
+  handoff: PrPublishHandoff;
+  proof: PrReadyProof;
+  /**
+   * Whether publish reused the on-disk `pr:verify` proof or ran verification,
+   * and why (#291). Always populated from this version on; optional so adding
+   * it stays an additive change to the published result contract.
+   */
+  verificationReuse?: VerificationReuse;
+  /**
+   * Whether the durable pr:verify check-run binding landed for this head (#247).
+   * Always populated from this version on; optional so adding it stays an
+   * additive change to the published result contract.
+   */
+  verifyProofBinding?: VerifyProofBindingOutcome;
+}
+declare class PrPublishFollowUpError extends Error {
+  readonly result: PrPublishResult;
+  constructor(result: PrPublishResult, cause: unknown);
+}
+interface PrPublishDependencies extends PrReadyDependencies {
+  currentBranch?: (cwd: string) => string | undefined;
+  /**
+   * Awaited republish of the `pr:verify` check run once the head SHA is on
+   * GitHub (#247). Returns whether the App-owned check run landed.
+   */
+  ensureVerifyCheckRun?: typeof ensureFactoryCheckRunPublished;
+  factoryCliInvocation?: FactoryCliInvocation;
+  gh?: GhRunner;
+  github?: PrReadyDependencies["github"] & {
+    editPullRequestBody?: (input: {
+      body: string;
+      owner: string;
+      repo: string;
+      pr: number;
+    }) => void;
+  };
+  runFollowUp?: FollowUpRunner;
+  runPrReady?: typeof runPrReady;
+  runPrReview?: (args: PrReviewArgs) => Promise<PrReviewProof>;
+  runPrVerify?: (args: PrVerifyArgs) => Promise<PrVerifyProof>;
+}
+/**
+ * What became of the durable `pr:verify` binding for this publish. Reported in
+ * the publish summary: a binding that silently failed to land is
+ * indistinguishable from verification that never happened, and the operator is
+ * the only one who can fix the cause (usually an unpushed head).
+ */
+type VerifyProofBindingOutcome = {
+  status: "not-attempted";
+} | {
+  headSha: string;
+  status: "failed" | "published" | "skipped-relabelled-head";
+};
+/**
+ * Whether publish reused the on-disk `pr:verify` proof, and the one-line reason
+ * (#291). Publish decides reuse silently today, which is what made the
+ * redundant follow-up rerun in paitronage#1043 impossible to attribute without
+ * a second investigation pass. Every publish states this decision.
+ */
+interface VerificationReuse {
+  reason: string;
+  reused: boolean;
+}
+/**
+ * Whether publish runs the follow-up `pr:ready` recommended, plus the one-line
+ * reason either way (#291).
+ */
+type PublishFollowUpPlan = {
+  kind: "run";
+  reason: string;
+} | {
+  kind: "skip";
+  reason: string;
+};
+/**
+ * Decide whether a `pr:ready` follow-up is worth running (#291).
+ *
+ * `pr:ready` recommends a verification rerun as its generic answer to a blocked
+ * candidate, including when the blocker is red hosted required checks. That
+ * rerun is unusable by construction when (a) verify-once applicability already
+ * accepted an exact-head passing proof for this candidate — so the rerun would
+ * repeat work the proof covers — and (b) the durable check-run binding did not
+ * land, most commonly because no factory GitHub App is configured, so the
+ * rerun's result has nowhere to go and cannot move the hosted check state that
+ * triggered the follow-up. That was ~100 seconds of unusable work on
+ * paitronage#1043 while the real blocker went untouched.
+ *
+ * Applicability is not re-decided here: `proofHeadSha`/`verifiedHeadSha` come
+ * from {@link ensureVerifyProof}, which routes through the single shared
+ * verify-once entry point (#692 / ADR 0016). Equal SHAs mean the proof was
+ * accepted for this exact head rather than relabelled onto it.
+ */
+declare const planPublishFollowUp: ({
+  binding,
+  followUp,
+  proofHeadSha,
+  verifiedHeadSha
+}: {
+  binding: VerifyProofBindingOutcome;
+  followUp: FollowUpAction;
+  proofHeadSha: string;
+  verifiedHeadSha: string;
+}) => PublishFollowUpPlan;
+declare function runPrPublish(args: PrPublishArgs, dependencies?: PrPublishDependencies): Promise<PrPublishResult>;
+//#endregion
+//#region src/commands/pr-publish.d.ts
+type PrPublishAction = (args: PrPublishArgs) => Promise<unknown>;
+//#endregion
+//#region src/commands/pr-ready.d.ts
+type PrReadyAction = (args: PrReadyArgs) => Promise<unknown>;
+//#endregion
+//#region src/commands/pr-review.d.ts
+type PrReviewAction = (args: PrReviewArgs) => Promise<unknown>;
+//#endregion
+//#region src/packages/trace/implementation/core.d.ts
+declare const FactoryTraceEnvelopeCoreSchema: z.ZodObject<{
+  createdAt: z.ZodString;
+  envelope: z.ZodLiteral<1>;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  payload: z.ZodUnknown;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  thread: z.ZodOptional<z.ZodString>;
+  type: z.ZodString;
+  typeVersion: z.ZodNumber;
+  worker: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const UnknownFactoryTraceEventSchema: z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  eventType: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  typeVersion: z.ZodNumber;
+  payload: z.ZodUnknown;
+  unknownTraceEvent: z.ZodLiteral<true>;
+}, z.core.$strict>;
+//#endregion
+//#region src/packages/trace/implementation/worker-closeout-lessons.d.ts
+declare const WorkerCloseoutLessonsTraceEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  lessonStatus: z.ZodLiteral<"captured">;
+  lessons: z.ZodString;
+  prompt: z.ZodOptional<z.ZodString>;
+  typeVersion: z.ZodLiteral<1>;
+}, z.core.$strict>, z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  lessonStatus: z.ZodLiteral<"unavailable">;
+  prompt: z.ZodOptional<z.ZodString>;
+  typeVersion: z.ZodLiteral<1>;
+  unavailableReason: z.ZodString;
+}, z.core.$strict>], "lessonStatus">;
+declare const LegacyWorkerCloseoutStatusTraceEventSchema: z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  archiveStatus: z.ZodOptional<z.ZodEnum<{
+    unavailable: "unavailable";
+    archived: "archived";
+    skipped: "skipped";
+    "not-applicable": "not-applicable";
+    pending: "pending";
+  }>>;
+  closeoutReason: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  lessonStatus: z.ZodOptional<z.ZodEnum<{
+    captured: "captured";
+    unavailable: "unavailable";
+    skipped: "skipped";
+  }>>;
+  lessonSummary: z.ZodOptional<z.ZodString>;
+  typeVersion: z.ZodLiteral<2>;
+}, z.core.$strict>;
+declare const LegacyWorkerCloseoutLessonsTraceEventSchema: z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  typeVersion: z.ZodLiteral<3>;
+}, z.core.$strict>;
+//#endregion
+//#region src/packages/trace/implementation/definitions.d.ts
+type InferSchema<TSchema> = TSchema extends z.ZodType ? z.infer<TSchema> : never;
+type ReadEventSchemasOf<TDefinition> = TDefinition extends {
+  readEventSchemas: readonly (infer TSchema)[];
+} ? TSchema extends z.ZodType ? InferSchema<TSchema> : never : never;
+type FactoryTraceEventFromDefinitions<TDefinitions extends readonly TraceEventDefinition[]> = ReadEventSchemasOf<TDefinitions[number]>;
+interface TraceEventDefinition {
+  appendEventSchema: z.ZodType;
+  emit: (event: never) => unknown;
+  kind: string;
+  payloadVersions: Record<number, z.ZodType>;
+  readEventSchemas: readonly z.ZodType[];
+}
+interface DefinedTraceEvent<TKind extends string = string, TAppendSchema extends z.ZodType = z.ZodType, TReadSchemas extends readonly z.ZodType[] = readonly z.ZodType[], TPayloadVersions extends Record<number, z.ZodType> = Record<number, z.ZodType>, TEmitEvent = z.infer<TAppendSchema>> {
+  appendEventSchema: TAppendSchema;
+  emit: (event: TEmitEvent) => unknown;
+  kind: TKind;
+  payloadVersions: TPayloadVersions;
+  readEventSchemas: TReadSchemas;
+}
+type WorkerCloseoutTraceEvent = z.infer<typeof WorkerCloseoutLessonsTraceEventSchema> | z.infer<typeof LegacyWorkerCloseoutStatusTraceEventSchema> | z.infer<typeof LegacyWorkerCloseoutLessonsTraceEventSchema>;
+declare const FACTORY_TRACE_EVENT_DEFINITIONS: readonly [DefinedTraceEvent<"review-gate", z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"review-gate">;
+  typeVersion: z.ZodLiteral<1>;
+  base: z.ZodString;
+  changedFiles: z.ZodArray<z.ZodString>;
+  headSha: z.ZodString;
+  maxReviewCycles: z.ZodNumber;
+  observedAt: z.ZodString;
+  outcome: z.ZodLiteral<"not-required">;
+  patchId: z.ZodString;
+  reason: z.ZodLiteral<"docs-only-profile-bypass">;
+  reviewCycle: z.ZodNumber;
+}, z.core.$strict>, readonly [z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"review-gate">;
+  typeVersion: z.ZodLiteral<1>;
+  base: z.ZodString;
+  changedFiles: z.ZodArray<z.ZodString>;
+  headSha: z.ZodString;
+  maxReviewCycles: z.ZodNumber;
+  observedAt: z.ZodString;
+  outcome: z.ZodLiteral<"not-required">;
+  patchId: z.ZodString;
+  reason: z.ZodLiteral<"docs-only-profile-bypass">;
+  reviewCycle: z.ZodNumber;
+}, z.core.$strict>], {
+  readonly 1: z.ZodObject<{
+    base: z.ZodString;
+    changedFiles: z.ZodArray<z.ZodString>;
+    headSha: z.ZodString;
+    maxReviewCycles: z.ZodNumber;
+    observedAt: z.ZodString;
+    outcome: z.ZodLiteral<"not-required">;
+    patchId: z.ZodString;
+    reason: z.ZodLiteral<"docs-only-profile-bypass">;
+    reviewCycle: z.ZodNumber;
+  }, z.core.$strict>;
+}, {
+  createdAt: string;
+  eventId: string;
+  repo: string;
+  schemaVersion: 1;
+  eventType: "review-gate";
+  typeVersion: 1;
+  base: string;
+  changedFiles: string[];
+  headSha: string;
+  maxReviewCycles: number;
+  observedAt: string;
+  outcome: "not-required";
+  patchId: string;
+  reason: "docs-only-profile-bypass";
+  reviewCycle: number;
+  issue?: number | undefined;
+  pr?: number | undefined;
+  threadId?: string | undefined;
+  workerId?: string | undefined;
+}>, DefinedTraceEvent<"review-ladder-stage", z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"review-ladder-stage">;
+  typeVersion: z.ZodLiteral<1>;
+  cycle: z.ZodNumber;
+  cyclesToClean: z.ZodOptional<z.ZodNumber>;
+  engine: z.ZodOptional<z.ZodString>;
+  findingsSummary: z.ZodObject<{
+    blocking: z.ZodNumber;
+    bySeverity: z.ZodObject<{
+      critical: z.ZodNumber;
+      high: z.ZodNumber;
+      low: z.ZodNumber;
+      medium: z.ZodNumber;
+      unknown: z.ZodNumber;
+    }, z.core.$strict>;
+    flagged: z.ZodNumber;
+    open: z.ZodNumber;
+    staleRepeats: z.ZodNumber;
+  }, z.core.$strict>;
+  forcedTransition: z.ZodOptional<z.ZodEnum<{
+    "gate-cap-exhausted": "gate-cap-exhausted";
+    "interior-cap-reached": "interior-cap-reached";
+  }>>;
+  headSha: z.ZodOptional<z.ZodString>;
+  model: z.ZodOptional<z.ZodString>;
+  observedAt: z.ZodString;
+  patchId: z.ZodOptional<z.ZodString>;
+  session: z.ZodOptional<z.ZodObject<{
+    orchestrationMode: z.ZodOptional<z.ZodEnum<{
+      autonomous: "autonomous";
+      manual: "manual";
+    }>>;
+    resumedSession: z.ZodOptional<z.ZodBoolean>;
+    runtime: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  stage: z.ZodEnum<{
+    gate: "gate";
+    interior: "interior";
+  }>;
+  usage: z.ZodOptional<z.ZodObject<{
+    estimatedCostUsd: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodOptional<z.ZodString>;
+    totalTokens: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>;
+}, z.core.$strict>, readonly [z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"review-ladder-stage">;
+  typeVersion: z.ZodLiteral<1>;
+  cycle: z.ZodNumber;
+  cyclesToClean: z.ZodOptional<z.ZodNumber>;
+  engine: z.ZodOptional<z.ZodString>;
+  findingsSummary: z.ZodObject<{
+    blocking: z.ZodNumber;
+    bySeverity: z.ZodObject<{
+      critical: z.ZodNumber;
+      high: z.ZodNumber;
+      low: z.ZodNumber;
+      medium: z.ZodNumber;
+      unknown: z.ZodNumber;
+    }, z.core.$strict>;
+    flagged: z.ZodNumber;
+    open: z.ZodNumber;
+    staleRepeats: z.ZodNumber;
+  }, z.core.$strict>;
+  forcedTransition: z.ZodOptional<z.ZodEnum<{
+    "gate-cap-exhausted": "gate-cap-exhausted";
+    "interior-cap-reached": "interior-cap-reached";
+  }>>;
+  headSha: z.ZodOptional<z.ZodString>;
+  model: z.ZodOptional<z.ZodString>;
+  observedAt: z.ZodString;
+  patchId: z.ZodOptional<z.ZodString>;
+  session: z.ZodOptional<z.ZodObject<{
+    orchestrationMode: z.ZodOptional<z.ZodEnum<{
+      autonomous: "autonomous";
+      manual: "manual";
+    }>>;
+    resumedSession: z.ZodOptional<z.ZodBoolean>;
+    runtime: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  stage: z.ZodEnum<{
+    gate: "gate";
+    interior: "interior";
+  }>;
+  usage: z.ZodOptional<z.ZodObject<{
+    estimatedCostUsd: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodOptional<z.ZodString>;
+    totalTokens: z.ZodOptional<z.ZodNumber>;
+  }, z.core.$strict>>;
+}, z.core.$strict>], {
+  readonly 1: z.ZodObject<{
+    cycle: z.ZodNumber;
+    cyclesToClean: z.ZodOptional<z.ZodNumber>;
+    engine: z.ZodOptional<z.ZodString>;
+    findingsSummary: z.ZodObject<{
+      blocking: z.ZodNumber;
+      bySeverity: z.ZodObject<{
+        critical: z.ZodNumber;
+        high: z.ZodNumber;
+        low: z.ZodNumber;
+        medium: z.ZodNumber;
+        unknown: z.ZodNumber;
+      }, z.core.$strict>;
+      flagged: z.ZodNumber;
+      open: z.ZodNumber;
+      staleRepeats: z.ZodNumber;
+    }, z.core.$strict>;
+    forcedTransition: z.ZodOptional<z.ZodEnum<{
+      "gate-cap-exhausted": "gate-cap-exhausted";
+      "interior-cap-reached": "interior-cap-reached";
+    }>>;
+    headSha: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    observedAt: z.ZodString;
+    patchId: z.ZodOptional<z.ZodString>;
+    session: z.ZodOptional<z.ZodObject<{
+      orchestrationMode: z.ZodOptional<z.ZodEnum<{
+        autonomous: "autonomous";
+        manual: "manual";
+      }>>;
+      resumedSession: z.ZodOptional<z.ZodBoolean>;
+      runtime: z.ZodOptional<z.ZodString>;
+      sessionId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    stage: z.ZodEnum<{
+      gate: "gate";
+      interior: "interior";
+    }>;
+    usage: z.ZodOptional<z.ZodObject<{
+      estimatedCostUsd: z.ZodOptional<z.ZodNumber>;
+      source: z.ZodOptional<z.ZodString>;
+      totalTokens: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>;
+}, {
+  createdAt: string;
+  eventId: string;
+  repo: string;
+  schemaVersion: 1;
+  eventType: "review-ladder-stage";
+  typeVersion: 1;
+  cycle: number;
+  findingsSummary: {
+    blocking: number;
+    bySeverity: {
+      critical: number;
+      high: number;
+      low: number;
+      medium: number;
+      unknown: number;
+    };
+    flagged: number;
+    open: number;
+    staleRepeats: number;
+  };
+  observedAt: string;
+  stage: "gate" | "interior";
+  issue?: number | undefined;
+  pr?: number | undefined;
+  threadId?: string | undefined;
+  workerId?: string | undefined;
+  cyclesToClean?: number | undefined;
+  engine?: string | undefined;
+  forcedTransition?: "gate-cap-exhausted" | "interior-cap-reached" | undefined;
+  headSha?: string | undefined;
+  model?: string | undefined;
+  patchId?: string | undefined;
+  session?: {
+    orchestrationMode?: "autonomous" | "manual" | undefined;
+    resumedSession?: boolean | undefined;
+    runtime?: string | undefined;
+    sessionId?: string | undefined;
+  } | undefined;
+  usage?: {
+    estimatedCostUsd?: number | undefined;
+    source?: string | undefined;
+    totalTokens?: number | undefined;
+  } | undefined;
+}>, DefinedTraceEvent<"worker-closeout-lessons", z.ZodDiscriminatedUnion<[z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  lessonStatus: z.ZodLiteral<"captured">;
+  lessons: z.ZodString;
+  prompt: z.ZodOptional<z.ZodString>;
+  typeVersion: z.ZodLiteral<1>;
+}, z.core.$strict>, z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  lessonStatus: z.ZodLiteral<"unavailable">;
+  prompt: z.ZodOptional<z.ZodString>;
+  typeVersion: z.ZodLiteral<1>;
+  unavailableReason: z.ZodString;
+}, z.core.$strict>], "lessonStatus">, readonly [z.ZodDiscriminatedUnion<[z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  lessonStatus: z.ZodLiteral<"captured">;
+  lessons: z.ZodString;
+  prompt: z.ZodOptional<z.ZodString>;
+  typeVersion: z.ZodLiteral<1>;
+}, z.core.$strict>, z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  lessonStatus: z.ZodLiteral<"unavailable">;
+  prompt: z.ZodOptional<z.ZodString>;
+  typeVersion: z.ZodLiteral<1>;
+  unavailableReason: z.ZodString;
+}, z.core.$strict>], "lessonStatus">, z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  archiveStatus: z.ZodOptional<z.ZodEnum<{
+    unavailable: "unavailable";
+    archived: "archived";
+    skipped: "skipped";
+    "not-applicable": "not-applicable";
+    pending: "pending";
+  }>>;
+  closeoutReason: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  lessonStatus: z.ZodOptional<z.ZodEnum<{
+    captured: "captured";
+    unavailable: "unavailable";
+    skipped: "skipped";
+  }>>;
+  lessonSummary: z.ZodOptional<z.ZodString>;
+  typeVersion: z.ZodLiteral<2>;
+}, z.core.$strict>, z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"worker-closeout-lessons">;
+  typeVersion: z.ZodLiteral<3>;
+}, z.core.$strict>], {
+  readonly 1: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    observedAt: z.ZodString;
+    prompt: z.ZodOptional<z.ZodString>;
+    lessonStatus: z.ZodLiteral<"captured">;
+    lessons: z.ZodString;
+  }, z.core.$strict>, z.ZodObject<{
+    observedAt: z.ZodString;
+    prompt: z.ZodOptional<z.ZodString>;
+    lessonStatus: z.ZodLiteral<"unavailable">;
+    unavailableReason: z.ZodString;
+  }, z.core.$strict>], "lessonStatus">;
+  readonly 2: z.ZodObject<{
+    archiveStatus: z.ZodOptional<z.ZodEnum<{
+      unavailable: "unavailable";
+      archived: "archived";
+      skipped: "skipped";
+      "not-applicable": "not-applicable";
+      pending: "pending";
+    }>>;
+    closeoutReason: z.ZodOptional<z.ZodString>;
+    lessonStatus: z.ZodOptional<z.ZodEnum<{
+      captured: "captured";
+      unavailable: "unavailable";
+      skipped: "skipped";
+    }>>;
+    lessonSummary: z.ZodOptional<z.ZodString>;
+    observedAt: z.ZodString;
+  }, z.core.$strict>;
+  readonly 3: z.ZodObject<{
+    observedAt: z.ZodString;
+  }, z.core.$strict>;
+}, WorkerCloseoutTraceEvent>, DefinedTraceEvent<"orchestrator-session", z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"orchestrator-session">;
+  typeVersion: z.ZodLiteral<1>;
+  avgContextTokens: z.ZodNumber;
+  cacheReadTokens: z.ZodNumber;
+  cacheWriteTokens: z.ZodNumber;
+  inputTokens: z.ZodNumber;
+  observedAt: z.ZodString;
+  outputTokens: z.ZodNumber;
+  sessionId: z.ZodString;
+  totalTokens: z.ZodNumber;
+  turnCount: z.ZodNumber;
+  usageSource: z.ZodEnum<{
+    "claude-code-jsonl": "claude-code-jsonl";
+  }>;
+}, z.core.$strict>, readonly [z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"orchestrator-session">;
+  typeVersion: z.ZodLiteral<1>;
+  avgContextTokens: z.ZodNumber;
+  cacheReadTokens: z.ZodNumber;
+  cacheWriteTokens: z.ZodNumber;
+  inputTokens: z.ZodNumber;
+  observedAt: z.ZodString;
+  outputTokens: z.ZodNumber;
+  sessionId: z.ZodString;
+  totalTokens: z.ZodNumber;
+  turnCount: z.ZodNumber;
+  usageSource: z.ZodEnum<{
+    "claude-code-jsonl": "claude-code-jsonl";
+  }>;
+}, z.core.$strict>], {
+  readonly 1: z.ZodObject<{
+    avgContextTokens: z.ZodNumber;
+    cacheReadTokens: z.ZodNumber;
+    cacheWriteTokens: z.ZodNumber;
+    inputTokens: z.ZodNumber;
+    observedAt: z.ZodString;
+    outputTokens: z.ZodNumber;
+    sessionId: z.ZodString;
+    totalTokens: z.ZodNumber;
+    turnCount: z.ZodNumber;
+    usageSource: z.ZodEnum<{
+      "claude-code-jsonl": "claude-code-jsonl";
+    }>;
+  }, z.core.$strict>;
+}, {
+  createdAt: string;
+  eventId: string;
+  repo: string;
+  schemaVersion: 1;
+  eventType: "orchestrator-session";
+  typeVersion: 1;
+  avgContextTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  inputTokens: number;
+  observedAt: string;
+  outputTokens: number;
+  sessionId: string;
+  totalTokens: number;
+  turnCount: number;
+  usageSource: "claude-code-jsonl";
+  issue?: number | undefined;
+  pr?: number | undefined;
+  threadId?: string | undefined;
+  workerId?: string | undefined;
+}>, DefinedTraceEvent<"delegate-exec", z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"delegate-exec">;
+  typeVersion: z.ZodLiteral<1>;
+  changedFiles: z.ZodArray<z.ZodString>;
+  command: z.ZodString;
+  diff: z.ZodString;
+  durationMs: z.ZodNumber;
+  endedAt: z.ZodString;
+  engineSessionId: z.ZodOptional<z.ZodString>;
+  exitCode: z.ZodNullable<z.ZodNumber>;
+  harness: z.ZodString;
+  interiorCycle: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  purpose: z.ZodEnum<{
+    review: "review";
+    code: "code";
+  }>;
+  slotResolution: z.ZodObject<{
+    effort: z.ZodEnum<{
+      high: "high";
+      low: "low";
+      medium: "medium";
+      xhigh: "xhigh";
+    }>;
+    engine: z.ZodString;
+    fallbackTier: z.ZodOptional<z.ZodLiteral<"delegate">>;
+    layerSource: z.ZodEnum<{
+      committedDefault: "committedDefault";
+      operatorSession: "operatorSession";
+      userConfig: "userConfig";
+    }>;
+    model: z.ZodString;
+    tier: z.ZodEnum<{
+      review: "review";
+      delegate: "delegate";
+      oracle: "oracle";
+      workhorse: "workhorse";
+      scout: "scout";
+    }>;
+  }, z.core.$strict>;
+  startedAt: z.ZodString;
+  tier: z.ZodEnum<{
+    review: "review";
+    delegate: "delegate";
+    oracle: "oracle";
+    workhorse: "workhorse";
+    scout: "scout";
+  }>;
+  tokenUsage: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningOutputTokens: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodEnum<{
+      "cursor-csv": "cursor-csv";
+      "codex-json": "codex-json";
+      "cursor-json": "cursor-json";
+      "claude-json": "claude-json";
+    }>;
+    status: z.ZodLiteral<"available">;
+    totalTokens: z.ZodNumber;
+  }, z.core.$strict>, z.ZodObject<{
+    missingReason: z.ZodString;
+    status: z.ZodLiteral<"unavailable">;
+  }, z.core.$strict>], "status">;
+  usageSource: z.ZodEnum<{
+    "cursor-agent-json": "cursor-agent-json";
+    "codex-exec-json": "codex-exec-json";
+    "grok-exec-json": "grok-exec-json";
+    "in-harness": "in-harness";
+  }>;
+}, z.core.$strict>, readonly [z.ZodObject<{
+  createdAt: z.ZodString;
+  eventId: z.ZodString;
+  issue: z.ZodOptional<z.ZodNumber>;
+  pr: z.ZodOptional<z.ZodNumber>;
+  repo: z.ZodString;
+  schemaVersion: z.ZodLiteral<1>;
+  threadId: z.ZodOptional<z.ZodString>;
+  workerId: z.ZodOptional<z.ZodString>;
+  eventType: z.ZodLiteral<"delegate-exec">;
+  typeVersion: z.ZodLiteral<1>;
+  changedFiles: z.ZodArray<z.ZodString>;
+  command: z.ZodString;
+  diff: z.ZodString;
+  durationMs: z.ZodNumber;
+  endedAt: z.ZodString;
+  engineSessionId: z.ZodOptional<z.ZodString>;
+  exitCode: z.ZodNullable<z.ZodNumber>;
+  harness: z.ZodString;
+  interiorCycle: z.ZodOptional<z.ZodNumber>;
+  observedAt: z.ZodString;
+  purpose: z.ZodEnum<{
+    review: "review";
+    code: "code";
+  }>;
+  slotResolution: z.ZodObject<{
+    effort: z.ZodEnum<{
+      high: "high";
+      low: "low";
+      medium: "medium";
+      xhigh: "xhigh";
+    }>;
+    engine: z.ZodString;
+    fallbackTier: z.ZodOptional<z.ZodLiteral<"delegate">>;
+    layerSource: z.ZodEnum<{
+      committedDefault: "committedDefault";
+      operatorSession: "operatorSession";
+      userConfig: "userConfig";
+    }>;
+    model: z.ZodString;
+    tier: z.ZodEnum<{
+      review: "review";
+      delegate: "delegate";
+      oracle: "oracle";
+      workhorse: "workhorse";
+      scout: "scout";
+    }>;
+  }, z.core.$strict>;
+  startedAt: z.ZodString;
+  tier: z.ZodEnum<{
+    review: "review";
+    delegate: "delegate";
+    oracle: "oracle";
+    workhorse: "workhorse";
+    scout: "scout";
+  }>;
+  tokenUsage: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+    inputTokens: z.ZodOptional<z.ZodNumber>;
+    outputTokens: z.ZodOptional<z.ZodNumber>;
+    reasoningOutputTokens: z.ZodOptional<z.ZodNumber>;
+    source: z.ZodEnum<{
+      "cursor-csv": "cursor-csv";
+      "codex-json": "codex-json";
+      "cursor-json": "cursor-json";
+      "claude-json": "claude-json";
+    }>;
+    status: z.ZodLiteral<"available">;
+    totalTokens: z.ZodNumber;
+  }, z.core.$strict>, z.ZodObject<{
+    missingReason: z.ZodString;
+    status: z.ZodLiteral<"unavailable">;
+  }, z.core.$strict>], "status">;
+  usageSource: z.ZodEnum<{
+    "cursor-agent-json": "cursor-agent-json";
+    "codex-exec-json": "codex-exec-json";
+    "grok-exec-json": "grok-exec-json";
+    "in-harness": "in-harness";
+  }>;
+}, z.core.$strict>], {
+  readonly 1: z.ZodObject<{
+    changedFiles: z.ZodArray<z.ZodString>;
+    command: z.ZodString;
+    diff: z.ZodString;
+    durationMs: z.ZodNumber;
+    endedAt: z.ZodString;
+    engineSessionId: z.ZodOptional<z.ZodString>;
+    exitCode: z.ZodNullable<z.ZodNumber>;
+    harness: z.ZodString;
+    interiorCycle: z.ZodOptional<z.ZodNumber>;
+    observedAt: z.ZodString;
+    purpose: z.ZodEnum<{
+      review: "review";
+      code: "code";
+    }>;
+    slotResolution: z.ZodObject<{
+      effort: z.ZodEnum<{
+        high: "high";
+        low: "low";
+        medium: "medium";
+        xhigh: "xhigh";
+      }>;
+      engine: z.ZodString;
+      fallbackTier: z.ZodOptional<z.ZodLiteral<"delegate">>;
+      layerSource: z.ZodEnum<{
+        committedDefault: "committedDefault";
+        operatorSession: "operatorSession";
+        userConfig: "userConfig";
+      }>;
+      model: z.ZodString;
+      tier: z.ZodEnum<{
+        review: "review";
+        delegate: "delegate";
+        oracle: "oracle";
+        workhorse: "workhorse";
+        scout: "scout";
+      }>;
+    }, z.core.$strict>;
+    startedAt: z.ZodString;
+    tier: z.ZodEnum<{
+      review: "review";
+      delegate: "delegate";
+      oracle: "oracle";
+      workhorse: "workhorse";
+      scout: "scout";
+    }>;
+    tokenUsage: z.ZodDiscriminatedUnion<[z.ZodObject<{
+      cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+      inputTokens: z.ZodOptional<z.ZodNumber>;
+      outputTokens: z.ZodOptional<z.ZodNumber>;
+      reasoningOutputTokens: z.ZodOptional<z.ZodNumber>;
+      source: z.ZodEnum<{
+        "cursor-csv": "cursor-csv";
+        "codex-json": "codex-json";
+        "cursor-json": "cursor-json";
+        "claude-json": "claude-json";
+      }>;
+      status: z.ZodLiteral<"available">;
+      totalTokens: z.ZodNumber;
+    }, z.core.$strict>, z.ZodObject<{
+      missingReason: z.ZodString;
+      status: z.ZodLiteral<"unavailable">;
+    }, z.core.$strict>], "status">;
+    usageSource: z.ZodEnum<{
+      "cursor-agent-json": "cursor-agent-json";
+      "codex-exec-json": "codex-exec-json";
+      "grok-exec-json": "grok-exec-json";
+      "in-harness": "in-harness";
+    }>;
+  }, z.core.$strict>;
+}, {
+  createdAt: string;
+  eventId: string;
+  repo: string;
+  schemaVersion: 1;
+  eventType: "delegate-exec";
+  typeVersion: 1;
+  changedFiles: string[];
+  command: string;
+  diff: string;
+  durationMs: number;
+  endedAt: string;
+  exitCode: number | null;
+  harness: string;
+  observedAt: string;
+  purpose: "review" | "code";
+  slotResolution: {
+    effort: "high" | "low" | "medium" | "xhigh";
+    engine: string;
+    layerSource: "committedDefault" | "operatorSession" | "userConfig";
+    model: string;
+    tier: "review" | "delegate" | "oracle" | "workhorse" | "scout";
+    fallbackTier?: "delegate" | undefined;
+  };
+  startedAt: string;
+  tier: "review" | "delegate" | "oracle" | "workhorse" | "scout";
+  tokenUsage: {
+    source: "cursor-csv" | "codex-json" | "cursor-json" | "claude-json";
+    status: "available";
+    totalTokens: number;
+    cachedInputTokens?: number | undefined;
+    inputTokens?: number | undefined;
+    outputTokens?: number | undefined;
+    reasoningOutputTokens?: number | undefined;
+  } | {
+    missingReason: string;
+    status: "unavailable";
+  };
+  usageSource: "cursor-agent-json" | "codex-exec-json" | "grok-exec-json" | "in-harness";
+  issue?: number | undefined;
+  pr?: number | undefined;
+  threadId?: string | undefined;
+  workerId?: string | undefined;
+  engineSessionId?: string | undefined;
+  interiorCycle?: number | undefined;
+}>];
+type FactoryTraceEvent = FactoryTraceEventFromDefinitions<typeof FACTORY_TRACE_EVENT_DEFINITIONS>;
+//#endregion
+//#region src/packages/trace/implementation/trace-shard.d.ts
+type FactoryTraceEnvelope = z.infer<typeof FactoryTraceEnvelopeCoreSchema>;
+//#endregion
+//#region src/packages/trace/implementation/trace-sinks.d.ts
+interface TraceSink {
+  append: (envelope: FactoryTraceEnvelope) => void;
+}
+interface TraceMirrorDiagnostic {
+  code: "mirror-append-failed";
+  eventId: string;
+  message: string;
+}
+interface TraceWriteSinks {
+  canonical: TraceSink;
+  mirror?: TraceSink;
+}
+interface TraceWriteResult {
+  mirrorDiagnostics: TraceMirrorDiagnostic[];
+}
+interface ResolveTraceWriteSinksOptions {
+  mirror?: TraceSink;
+}
+declare const createLocalJsonlTraceSink: (repoRoot: string) => TraceSink;
+declare const appendWithTraceSinks: (envelope: FactoryTraceEnvelope, sinks: TraceWriteSinks) => TraceWriteResult;
+declare const resolveTraceWriteSinks: (repoRoot: string, options?: ResolveTraceWriteSinksOptions) => TraceWriteSinks;
+//#endregion
+//#region src/packages/trace/implementation/facade.d.ts
+type ReadableFactoryTraceEvent = FactoryTraceEvent | z.infer<typeof UnknownFactoryTraceEventSchema>;
+type WorkerCloseoutLessonsTraceEvent = z.infer<typeof WorkerCloseoutLessonsTraceEventSchema>;
+interface FactoryTraceFilters {
+  eventType?: string | readonly string[];
+  issue?: number | readonly number[];
+  pr?: number | readonly number[];
+  repo?: string | readonly string[];
+  threadId?: string | readonly string[];
+  workerId?: string | readonly string[];
+}
+interface FactoryTraceDiagnostic {
+  code: "malformed-json" | "invalid-event" | "unknown-event-type" | "unknown-event-version";
+  event?: {
+    eventId: string;
+    eventType: string;
+    issue?: number;
+    pr?: number;
+    repo: string;
+    threadId?: string;
+    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;
+};
+/**
+ * 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/interior-telemetry/gate-timing.d.ts
+declare const GATE_TIMING_SCHEMA_VERSION = 1;
+type FactoryGateName = "boundary:check" | "factory:closeout" | "pr:merge-check" | "pr:ready" | "pr:review" | "pr:verify";
+type GateTimingOutcome = "fail" | "pass";
+interface GateTimingRecord {
+  agentRunId: string;
+  cycle: number;
+  durationMs: number;
+  gate: FactoryGateName;
+  outcome: GateTimingOutcome;
+  schemaVersion: typeof GATE_TIMING_SCHEMA_VERSION;
+  startedAt: string;
+  startOffsetMs: number;
+}
+//#endregion
+//#region src/retro-envelope-builder.d.ts
+/**
+ * Folds a lane's gate-timing ledger (`.factory-memory/gate-timing/<id>.jsonl`,
+ * wave-1 PR #33) into a versioned retro envelope at `factory:closeout`.
+ *
+ * STRUCTURAL INVARIANT (#677 repeat-class rule; PR #35 review cycles 1-2):
+ * telemetry CONTENT can never fail the closeout build gate. Every value that
+ * reaches the envelope passes through one sanitization seam that makes the
+ * output valid BY CONSTRUCTION:
+ *
+ * - strings are clamped to their wire bounds (truncated, with a data gap when
+ *   truncation lost information);
+ * - numbers must be finite and within plausibility bounds BEFORE any derived
+ *   arithmetic; an absurd value (1e16 ms duration, year-9999 timestamp) SKIPS
+ *   its record with a data gap rather than clamping, because clamping would
+ *   assert a measurement that never happened;
+ * - arrays are bounded to their schema maxima (gates[] keeps the most recent);
+ * - derived computations (wall clock, cycles) consume only sanitized inputs,
+ *   so no ledger content can push them outside Date/Number safe ranges.
+ *
+ * Terminal backstop: the assembled candidate goes through a final schema
+ * parse; if that still fails, a minimal-valid envelope (clamped identity,
+ * empty gates, a data gap naming the failure) is built and returned instead.
+ * `buildRetroEnvelope` therefore never throws for content — the closeout gate
+ * can only fail on filesystem errors when persisting.
+ */
+interface BuildRetroEnvelopeInput {
+  agentRunId: string;
+  /** Optional pointer (key/URL) to #8's durable proof archive — never payload. */
+  archiveRef?: string;
+  dataGaps?: string[];
+  generatedAt: Date;
+  interventions?: number;
+  /** Per-family session identities the lane already records. */
+  joinKeys?: {
+    claudeSessionIds?: string[];
+    codexThreadIds?: string[];
+  };
+  /** The lane's gate-timing ledger records, in append order. */
+  ledger: GateTimingRecord[];
+  outcome?: RetroEnvelope["outcome"];
+  phases?: RetroEnvelope["phases"];
+  refs: RetroEnvelope["refs"];
+  repo: RetroEnvelope["repo"];
+  /**
+   * Token families. They may be absent when native session data is unavailable
+   * (valid does not imply available telemetry). When present they satisfy the
+   * family invariants.
+   */
+  tokenFamilies?: RetroEnvelope["tokenFamilies"];
+}
+declare const buildRetroEnvelope: (input: BuildRetroEnvelopeInput) => RetroEnvelope;
+declare namespace comment_provenance_d_exports {
+  export { SHA_MATCH_MIN_LENGTH, isBotLogin, sameHeadSha };
+}
+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
+type DoctorCheckStatus = "error" | "ok" | "warning";
+interface DoctorCheck {
+  message: string;
+  name: string;
+  status: DoctorCheckStatus;
+}
+interface DoctorReport {
+  checks: DoctorCheck[];
+  ok: boolean;
+  profilePath: string;
+  projectKey: string;
+  repository: {
+    defaultBranch: string;
+    name: string;
+    owner: string;
+  };
+  schemaVersion: typeof PROFILE_SCHEMA_VERSION;
+}
+interface DoctorProjectProfileInput extends LoadProjectProfileInput {
+  /** Diff base for the admission preflight; ignored unless `preflight`. */
+  base?: string;
+  env?: NodeJS.ProcessEnv;
+  /**
+   * Append the read-only admission checklist (#292): every requirement this
+   * candidate must satisfy before merge, named in one pass. Preflight checks
+   * never report `error`, so they cannot change the doctor exit code.
+   */
+  preflight?: boolean;
+  userConfig?: LoadUserConfigResult;
+}
+declare function doctorProjectProfile(input?: DoctorProjectProfileInput): DoctorReport;
+//#endregion
+//#region src/pr-review-gate-trace.d.ts
+interface ReviewGateTraceIdentity {
+  issue?: number;
+  repo: string;
+}
+type ReviewGateNotRequiredProof = Pick<PrReviewProof, "base" | "changedFiles" | "headSha" | "patchId"> & Required<Pick<PrReviewProof, "maxReviewCycles" | "reviewCycle" | "reviewRequirement">>;
+declare const buildReviewGateNotRequiredTraceEvent: ({
+  createdAt,
+  identity,
+  proof
+}: {
+  createdAt?: string;
+  identity: ReviewGateTraceIdentity;
+  proof: ReviewGateNotRequiredProof;
+}) => FactoryTraceEvent;
+declare const tryAppendReviewGateNotRequiredTraceEvent: ({
+  identity,
+  proof,
+  repoRoot
+}: {
+  identity: ReviewGateTraceIdentity;
+  proof: ReviewGateNotRequiredProof;
+  repoRoot: string;
+}) => {
+  readonly filePath: string;
+  readonly ok: true;
+  readonly errorMessage?: undefined;
+} | {
+  readonly errorMessage: string;
+  readonly ok: false;
+  readonly filePath?: undefined;
+};
+declare namespace worktree_scratch_files_d_exports {
+  export { WorktreeRootLister, WorktreeScratchFileCheck, checkWorktreeScratchFiles, formatScratchFileCheckSummary, isWorktreeScratchFile };
+}
+declare function isWorktreeScratchFile(fileName: string): boolean;
+interface WorktreeScratchFileCheck {
+  /** Stray scratch file names found at the worktree root. */
+  files: string[];
+  /**
+   * "skipped" means no worktree path was recorded or the path was not
+   * readable from the planning machine, so nothing was checked.
+   */
+  status: "clean" | "flagged" | "skipped";
+  worktreePath?: string;
+}
+type WorktreeRootLister = (worktreePath: string) => string[] | undefined;
+declare function checkWorktreeScratchFiles(worktreePath?: string, listRootEntries?: WorktreeRootLister): WorktreeScratchFileCheck;
+/**
+ * Human-readable one-line summary of a scratch-file check, owned beside the
+ * detection logic (mirroring worktreeHeldBranchNotice) so planner output,
+ * docs, and future surfaces cannot drift apart.
+ */
+declare function formatScratchFileCheckSummary(check: WorktreeScratchFileCheck): string;
+declare namespace pr_body_metadata_d_exports {
+  export { PrBodyMetadata, StackRole, readPrBodyMetadata };
+}
+type StackRole = "single" | "slice" | "rollup" | "merge-gate prerequisite";
+interface PrBodyMetadata {
+  requiredSectionsPresent: boolean;
+  stackRole: StackRole;
+  finalReviewPoint: boolean;
+  trivialWaiverAccepted: boolean;
+}
+declare const readPrBodyMetadata: (body: string) => PrBodyMetadata;
+declare namespace post_readiness_comments_d_exports {
+  export { BLOCKING_REVIEW_STATE, HandledCommentEntry, PostReadinessHumanComment, PrReadinessComment, PrReadinessReview, activePostReadinessHumanComments, activePostReadinessHumanReviews, isBotLogin, postReadinessHumanCommentReason, postReadinessHumanReviewReason, selectPostReadinessHumanComments };
+}
+interface PrReadinessComment {
+  author?: {
+    login?: string;
+  };
+  body: string;
+  createdAt?: string;
+  id?: string | number;
+  updatedAt?: string;
+  url?: string;
+}
+interface PrReadinessReview {
+  author?: {
+    login?: string;
+  };
+  body?: string;
+  /** GraphQL `PullRequestReview.lastEditedAt` — the body-edit signal used to re-arm a cleared review (#843). */
+  lastEditedAt?: string;
+  state: string;
+  submittedAt?: string;
+  url?: string;
+}
+interface PostReadinessHumanComment {
+  author: string;
+  createdAt: string;
+  summary: string;
+  url: string;
+}
+declare const BLOCKING_REVIEW_STATE = "CHANGES_REQUESTED";
+interface HandledCommentEntry {
+  clearedAt?: string;
+  url: string;
+}
+/**
+ * Active human blocking comments: all non-bot human PR comments minus the
+ * explicitly-handled URL set. No review-timestamp recency gate — an unhandled
+ * blocker blocks regardless of later review runs (#819 cycle 3). A handled
+ * comment that is EDITED after it was cleared re-arms (#825a).
+ */
+declare const selectPostReadinessHumanComments: ({
+  comments,
+  handledComments
+}: {
+  comments: PrReadinessComment[];
+  handledComments?: HandledCommentEntry[];
+}) => PostReadinessHumanComment[];
+/**
+ * Active human blockers are recomputed from live GitHub comments each run
+ * (#819). The prior local readiness proof is not a carry source —
+ * `.factory-memory/` is gitignored and vanishes on clean checkout. Clearing
+ * persists only via the durable handled set (factory check-run
+ * `patronage-factory/handled-comments`) plus explicit `--handled-comment`.
+ */
+declare const activePostReadinessHumanComments: ({
+  comments,
+  handledComments
+}: {
+  comments: PrReadinessComment[];
+  handledComments?: HandledCommentEntry[];
+}) => PostReadinessHumanComment[];
+/**
+ * Active CHANGES_REQUESTED PR review submissions (#825b): a top-level review
+ * body carries no inline thread, so without this scan it is the only human
+ * channel auto-merge would sail over — unwatched by both the issue-comment
+ * scan and the unresolved-review-thread count. Shares the handled-set /
+ * re-arm rules with comments so an operator can clear a stale request the
+ * same way (`--handled-comment <review-url>`). The clear-comparison uses
+ * `lastEditedAt` when present so a body edit after a clear re-arms the
+ * blocker the same way an edited comment does — resubmission is not the
+ * only edit signal GitHub exposes (#843).
+ */
+declare const activePostReadinessHumanReviews: ({
+  handledComments,
+  reviews
+}: {
+  handledComments?: HandledCommentEntry[];
+  reviews: PrReadinessReview[];
+}) => PostReadinessHumanComment[];
+declare const postReadinessHumanCommentReason: ({
+  comment,
+  pr,
+  prTitle
+}: {
+  comment: PostReadinessHumanComment;
+  pr: number;
+  prTitle?: string;
+}) => string;
+declare const postReadinessHumanReviewReason: ({
+  pr,
+  prTitle,
+  review
+}: {
+  pr: number;
+  prTitle?: string;
+  review: PostReadinessHumanComment;
+}) => string;
+//#endregion
+//#region src/pr-readiness/pr-body-sections.d.ts
+declare const MANAGED_SECTION_NAMES: readonly ["Verification", "Review proof", "How to review"];
+declare namespace pr_body_renderer_d_exports {
+  export { MANAGED_SECTION_NAMES as PR_BODY_MANAGED_SECTIONS, renderPrBodySectionParts, renderPrBodySections };
+}
+declare const renderPrBodySectionParts: ({
+  reviewProof,
+  verifyProof
+}: {
+  reviewProof?: PrReviewProof;
+  verifyProof?: PrVerifyProof;
+}) => {
+  heading: string;
+  content: string;
+}[];
+declare const renderPrBodySections: ({
+  reviewProof,
+  verifyProof
+}: {
+  reviewProof?: PrReviewProof;
+  verifyProof?: PrVerifyProof;
+}) => string;
+//#endregion
+//#region src/pr-readiness/review-requiredness.d.ts
+interface DocsOnlyReviewBypassState {
+  applies: boolean;
+}
+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 };
+}
+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.";
+declare const DRAFT_BLOCKER_REASON = "PR is still marked draft.";
+declare const RENDER_PR_BODY_SECTIONS_BLOCKER_REASON = "PR body must include Verification, Review proof, and How to review sections.";
+declare const PENDING_CHECKS_BLOCKER_REASON_PREFIX = "Required/current checks are";
+declare const readinessExitCode: (status: ReadinessStatus) => 1 | 0;
+interface EvaluationInput {
+  pr: number;
+  prTitle?: string;
+  body: string;
+  headSha: string;
+  localHeadSha?: string;
+  baseSha: string;
+  patchId: string;
+  classification: DiffClassification;
+  comments?: PrReadinessComment[];
+  reviews?: PrReadinessReview[];
+  unresolvedReviewThreads: number;
+  requiredChecks: CheckState;
+  draft: boolean;
+  currentWithBase: boolean;
+  mergeable: string;
+  mergeStateStatus: string;
+  ladderPolicy?: ReviewLadderPolicy;
+  reviewModes?: PrReviewKind[];
+  reviewProof?: PrReviewProof;
+  verificationProof?: VerificationProofState;
+  docsOnlyVerifyBaselineHeadShas?: string[];
+  docsOnlySinceReviewProof?: boolean;
+  docsOnlyReviewBypass?: boolean;
+  externalRequiredChecks?: RequiredCheck[];
+  evidenceEnvelopes?: LoadedEvidenceEnvelope[];
+  mergeBaseSha?: string;
+  authoringSessionIds?: string[];
+  prLabels?: string[];
+  priorLedger?: Pick<ManagedReadinessLedger, "reviewRuns">;
+  handledCommentUrls?: string[];
+  checkRunHandledCommentUrls?: string[];
+  handledCommentsProducer?: {
+    identity: string;
+    mode: "app" | "commit-status";
+  };
+  handledCommentSessionId?: string;
+  handledCommentClearedAt?: string;
+}
+declare const evaluateReadiness: (input: EvaluationInput) => {
+  blockingReasons: string[];
+  humanBlockingReasons: string[];
+  ledger: {
+    baseSha: string;
+    blockingReasons: string[];
+    classification: "trivial" | "docs/process-only" | "non-trivial";
+    finalReviewPoint: boolean;
+    github: {
+      currentWithBase: boolean;
+      draft: boolean;
+      mergeStateStatus: string;
+      mergeable: string;
+      requiredChecks: "unknown" | "pending" | "passed" | "failed" | "none";
+      unresolvedReviewThreads: number;
+    };
+    headSha: string;
+    patchId: string;
+    pr: number;
+    previewDeployRequired: boolean;
+    repairs: {
+      action: string;
+      code: "undraft-pr" | "render-pr-body-sections" | "await-post-undraft-checks";
+      command: string;
+    }[];
+    reviews: {
+      correctness: {
+        required: boolean;
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
+        docsOnlyDeltaAccepted?: boolean | undefined;
+        reviewedHeadSha?: string | undefined;
+        reviewedPatchId?: string | undefined;
+      };
+      security?: {
+        required: boolean;
+        status: "blocked" | "not-required" | "current" | "stale" | "missing";
+        docsOnlyDeltaAccepted?: boolean | undefined;
+        reviewedHeadSha?: string | undefined;
+        reviewedPatchId?: string | undefined;
+      } | undefined;
+    };
+    schemaVersion: 1;
+    stackRole: "slice" | "single" | "rollup" | "merge-gate prerequisite";
+    verification: {
+      command: "patronage-factory pr:verify";
+      prVerify: "passed" | "stale" | "missing";
+      docsOnlyDeltaAccepted?: boolean | undefined;
+      docsOnlyVerifiedHeadSha?: string | undefined;
+      trivialDeltaAccepted?: boolean | undefined;
+      trivialVerifiedHeadSha?: string | undefined;
+      verifiedHeadSha?: string | undefined;
+    };
+    externalChecks?: {
+      checkType: "review" | "verify";
+      inScope: boolean;
+      name: string;
+      scopeReason: string;
+      status: "satisfied" | "unmet" | "out-of-scope";
+      reason?: string | undefined;
+      scope?: {
+        classifications?: ("trivial" | "docs/process-only" | "non-trivial")[] | undefined;
+        labels?: string[] | undefined;
+      } | undefined;
+    }[] | undefined;
+    handledCommentsProducer?: {
+      identity: string;
+      mode: "app" | "commit-status";
+    } | undefined;
+    handledHumanComments?: {
+      source: "check-run" | "cli";
+      url: string;
+      clearedAt?: string | undefined;
+      sessionId?: string | undefined;
+    }[] | undefined;
+    mergeBaseSha?: string | undefined;
+    postReadinessHumanComments?: {
+      author: string;
+      createdAt: string;
+      summary: string;
+      url: string;
+    }[] | undefined;
+    postReadinessHumanReviews?: {
+      author: string;
+      createdAt: string;
+      summary: string;
+      url: string;
+    }[] | undefined;
+    previewDeploy?: {
+      seedStatus: "unknown" | "skipped" | "passed" | "failed";
+      adminUrl?: string | undefined;
+      apiHealthUrl?: string | undefined;
+      headSha?: string | undefined;
+      localPreviewProof?: unknown;
+      localProofPath?: string | undefined;
+      proofSource?: "github-actions" | "local-self-certified" | undefined;
+      publicUrl?: string | undefined;
+      stage?: string | undefined;
+      timingsMs?: Record<string, number | undefined> | undefined;
+      workflowRunUrl?: string | undefined;
+    } | undefined;
+    reviewCycleState?: {
+      autoBlockingFindings: number;
+      countsBySeverity: {
+        critical: number;
+        high: number;
+        low: number;
+        medium: number;
+        unknown: number;
+      };
+      nonBlockingFindings: number;
+      openFindings: number;
+      windowExhausted: boolean;
+      highestBlockingSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
+      highestOpenSeverity?: "unknown" | "critical" | "high" | "low" | "medium" | undefined;
+      maxReviewCycles?: number | undefined;
+      reviewCycle?: number | undefined;
+      staleRepeatFindings?: number | undefined;
+    } | undefined;
+    reviewLadder?: {
+      cycleCounts: {
+        gate: number;
+        interior: number;
+      };
+      nextAction: "run-gate-cycle" | "accept-nonblocking-findings" | "escalate-to-triage" | "ready-for-human" | "advance-to-gate" | "run-interior-cycle";
+      stage: "gate" | "interior" | "interior-complete";
+      forcedTransition?: "gate-cap-exhausted" | "interior-cap-reached" | undefined;
+    } | undefined;
+    reviewRuns?: PrReviewResult[] | undefined;
+    reviewTerminalState?: "blocked" | "accepted-with-findings" | "clean" | undefined;
+  };
+  repairs: {
+    action: string;
+    code: "undraft-pr" | "render-pr-body-sections" | "await-post-undraft-checks";
+    command: string;
+  }[];
+  status: ReadinessStatus;
+};
+//#endregion
+//#region src/evidence-emit.d.ts
+interface EvidenceEmitArgs {
+  base: string;
+  check: string;
+  checkType: EvidenceCheckType;
+  cwd: string;
+  findingsPointer?: string;
+  json?: boolean;
+  model?: string;
+  outcome: "pass" | "fail";
+  output?: string;
+  policyVersion?: string;
+  profilePath?: string;
+  producer: string;
+  requestId?: string;
+  rung?: EvidenceReviewRung;
+  sessionId?: string;
+}
+interface EvidenceEmitDependencies {
+  env?: NodeJS.ProcessEnv;
+  git?: {
+    currentHeadSha: (cwd: string) => string;
+    mergeBaseSha: (cwd: string, base: string) => string;
+    stablePatchId: (cwd: string, base: string) => string;
+  };
+  hq?: HqIngestDependencies;
+  now?: () => Date;
+}
+interface EvidenceEmitResult {
+  envelope: EvidenceEnvelope;
+  path: string;
+}
+declare const evidenceEnvelopeFilename: (check: string, headSha: string) => string;
+declare function buildEvidenceEnvelope(args: EvidenceEmitArgs, dependencies?: EvidenceEmitDependencies): EvidenceEnvelope;
+declare function runEvidenceEmit(args: EvidenceEmitArgs, dependencies?: EvidenceEmitDependencies): EvidenceEmitResult;
+//#endregion
+//#region src/hq-access.d.ts
+/** Cloudflare Access service-token credentials for production HQ ingest. */
+interface CloudflareAccessServiceToken {
+  clientId: string;
+  clientSecret: string;
+}
+//#endregion
+//#region src/epic-structure.d.ts
+/**
+ * Producer-side `epic-structure` v1 emitter (epic #132, lane #135).
+ *
+ * `psf epic:publish-structure` reads a planner's ephemeral `dag.yml` (never
+ * committed — see epic #132 / ADR 0018), validates the graph fail-closed, and
+ * POSTs an `epic-structure` v1 event to HQ's `/api/ingest` boundary. This
+ * module is the pure core: parse-to-IR validation, the wire mapping, and the
+ * deterministic content-addressed eventId. All I/O (stdin/file read, fetch)
+ * lives in the command wrapper.
+ *
+ * WIRE PARITY (do not fork the schema): the emitted payload is the exact shape
+ * HQ's `EpicGraphSchema` accepts (`software-factory-hq/src/contracts/
+ * epic-schemas.ts`) and is built by hand the same way `seed-dev.ts` builds it
+ * — no re-declared zod twin. HQ's `epic-structure-parity.test.ts` imports
+ * {@link buildEpicStructureEvent} and runs its output through the real
+ * `EpicGraphSchema`, so any drift (field, enum, bound, strictness) fails CI.
+ *
+ * The `dag.yml` schema itself is documented with the epic skill (lane #137);
+ * this module is the executable contract, not a second source of truth.
+ */
+declare const EPIC_STRUCTURE_SCHEMA_VERSION = 1;
+/**
+ * DAG-node PLANNING statuses — the planning-plane vocabulary a planner authors
+ * on a `dag.yml` node. Carried forward by ADR 0018 §4 and defined by the epic
+ * skill (`reference/epic-artifacts.md`) and both `CONTEXT.md` glossaries.
+ *
+ * A DAG node is a unit of *plan*; an HQ lane is a unit of *runtime execution*.
+ * These are two planes with two vocabularies and must not be conflated — the
+ * producer validates and emits ONLY planning statuses:
+ *
+ *   - `open`              authored, not yet done
+ *   - `closed`            done (a PR merged, or otherwise resolved)
+ *   - `satisfied-on-main` already true on main without a dedicated PR
+ *   - `parked`            real node, scope still moving — relabeled off
+ *                         `ready-for-agent`, never closed
+ *
+ * HQ's `DagNodeSchema` (`software-factory-hq/src/contracts/epic-schemas.ts`)
+ * accepts this planning vocabulary on ingest AND overlays a runtime LANE status
+ * onto a node once a lane is linked (`syncNodesWithLanes` /
+ * `projectEpicMembership`) — the overlay is HQ-internal; the producer never
+ * emits a lane status. HQ's `epic-structure-parity.test.ts` fails CI if the
+ * producer emits any status HQ won't accept.
+ */
+declare const EPIC_STRUCTURE_NODE_STATUSES: readonly ["open", "closed", "satisfied-on-main", "parked"];
+type EpicStructureNodeStatus = (typeof EPIC_STRUCTURE_NODE_STATUSES)[number];
+interface DagDocument {
+  epic?: unknown;
+  boundary?: unknown;
+  name?: unknown;
+  repo?: unknown;
+  nodes?: unknown;
+  edges?: unknown;
+}
+interface EpicStructureGraphNode {
+  epicId: string;
+  laneId?: string;
+  slug: string;
+  status: EpicStructureNodeStatus;
+  title: string;
+}
+interface EpicStructureGraphEdge {
+  epicId: string;
+  from: string;
+  to: string;
+  type: "depends-on";
+}
+interface EpicStructureGraphPayload {
+  edges: EpicStructureGraphEdge[];
+  epics: {
+    id: string;
+    name: string;
+    repo: string;
+  }[];
+  nodes: EpicStructureGraphNode[];
+}
+interface EpicStructureEvent {
+  eventId: string;
+  kind: "epic-structure";
+  observedAt: string;
+  payload: EpicStructureGraphPayload;
+  schemaVersion: number;
+}
+interface BuildEpicStructureEventInput {
+  /** Parsed dag.yml (or JSON) document. */
+  document: DagDocument;
+  /** Boundary slug override (else `dag.boundary`, else `epic-<id>`). */
+  boundary?: string;
+  /** Epic display name override (else `dag.name`, else `Epic <id>`). */
+  name?: string;
+  /** Repo name override (else `dag.repo`). Required by one of the two. */
+  repo?: string;
+  /** Event observedAt; NOT part of the eventId hash. Defaults to now. */
+  observedAt?: string;
+}
+/**
+ * Fail-closed validation error carrying every offending node/edge diagnostic.
+ */
+declare class EpicStructureValidationError extends Error {
+  readonly diagnostics: string[];
+  constructor(diagnostics: string[]);
+}
+interface ValidatedNode {
+  slug: string;
+  title: string;
+  status: EpicStructureNodeStatus;
+  issue?: number;
+  laneId?: string;
+  external: boolean;
+}
+interface ValidatedDag {
+  epicId: string;
+  boundary: string;
+  name: string;
+  repo: string;
+  nodes: ValidatedNode[];
+  edges: {
+    from: string;
+    to: string;
+  }[];
+}
+/**
+ * Validates a dag document fail-closed. Throws {@link
+ * EpicStructureValidationError} with a diagnostic per offending node/edge.
+ */
+declare const validateDagDocument: (input: BuildEpicStructureEventInput) => ValidatedDag;
+/**
+ * Builds the wire payload with deterministic ordering (nodes by slug, edges by
+ * from then to) so re-emission of the same graph is byte-stable regardless of
+ * the planner's source ordering — the basis for the content-addressed eventId.
+ */
+declare const buildEpicStructurePayload: (dag: ValidatedDag) => EpicStructureGraphPayload;
+/**
+ * Deterministic eventId = `epic-structure-<boundary>-<sha256(payload)[0:16]>`.
+ * Re-emitting identical graph content yields the same eventId (HQ dedups →
+ * 200/duplicate); an amendment changes the content hash → a new eventId that
+ * supersedes the prior structure wholesale (HQ keeps the latest). This mirrors
+ * seed-dev's fixed-eventId idempotency, content-addressed instead of literal.
+ */
+declare const epicStructureEventId: (boundary: string, payload: EpicStructureGraphPayload) => string;
+/**
+ * Validates and builds the full `epic-structure` v1 ingest event, ready to POST
+ * to `/api/ingest`. Throws {@link EpicStructureValidationError} fail-closed.
+ */
+declare const buildEpicStructureEvent: (input: BuildEpicStructureEventInput) => EpicStructureEvent;
+type FetchLike = (input: string, init?: {
+  body?: string;
+  headers?: Record<string, string>;
+  method?: string;
+  redirect?: "error";
+}) => Promise<{
+  json: () => Promise<unknown>;
+  status: number;
+  text: () => Promise<string>;
+}>;
+interface PublishEpicStructureArgs {
+  /**
+   * Cloudflare Access credentials for production HQ ingest. Since v0.16.0,
+   * this replaces the removed application bearer-token `token` member.
+   */
+  accessServiceToken?: CloudflareAccessServiceToken;
+  event: EpicStructureEvent;
+  url: string;
+  fetchImpl?: FetchLike;
+}
+interface PublishEpicStructureResult {
+  duplicate: boolean;
+  eventId: string;
+  status: number;
+}
+/** The prod HQ worker is reachable at `hq.patronage.com` and its frozen
+ * `-v1.*.workers.dev` alias. Emitting there without an Access service token is
+ * fail-closed. */
+declare const isProductionHqUrl: (url: string) => boolean;
+/**
+ * POSTs the event to HQ ingest. Fail-closed: a production URL without a
+ * Cloudflare Access service token is refused before any request; a 401/403 is
+ * 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";
+interface IssueReviewFocus {
+  issueNumber: number;
+  text: string;
+}
+declare const reviewFocusFromIssueBody: (body: string) => string | undefined;
+//#endregion
+//#region src/review-prompt.d.ts
+interface AssembleReviewPromptInput {
+  base: string;
+  changedFiles: string[];
+  headSha: string;
+  issueFocus?: IssueReviewFocus;
+  kind: PrReviewKind;
+  patchId: string;
+  priorLedgerEntries?: FindingLedgerEntry[];
+  profile: FactoryProjectProfile;
+  standingChecklist?: readonly string[];
+}
+interface AssembledReviewPrompt {
+  prompt: string;
+  sections: ReviewPromptSection[];
+}
+declare const assembleReviewPrompt: ({
+  base,
+  changedFiles,
+  headSha,
+  issueFocus,
+  kind,
+  patchId,
+  priorLedgerEntries,
+  profile,
+  standingChecklist
+}: AssembleReviewPromptInput) => AssembledReviewPrompt;
+//#endregion
+//#region src/review-ladder-trace.d.ts
+interface ReviewLadderTraceIdentity {
+  issue?: number;
+  pr?: number;
+  repo: string;
+  threadId?: string;
+  workerId?: string;
+}
+interface ReviewLadderStageTraceWriteResult {
+  errorMessage?: string;
+  filePath?: string;
+  mirrorDiagnostics: TraceMirrorDiagnostic[];
+  ok: boolean;
+}
+declare const buildReviewLadderStageTraceEvent: ({
+  createdAt,
+  event,
+  headSha,
+  identity,
+  patchId
+}: {
+  createdAt?: string;
+  event: ReviewLadderStageEvent;
+  headSha?: string;
+  identity: ReviewLadderTraceIdentity;
+  patchId?: string;
+}) => FactoryTraceEvent;
+declare const appendReviewLadderStageTraceEvent: ({
+  createdAt,
+  event,
+  headSha,
+  identity,
+  mirror,
+  patchId,
+  repoRoot
+}: {
+  createdAt?: string;
+  event: ReviewLadderStageEvent;
+  headSha?: string;
+  identity: ReviewLadderTraceIdentity;
+  mirror?: TraceSink;
+  patchId?: string;
+  repoRoot: string;
+}) => AppendFactoryTraceEventResult;
+declare const tryAppendReviewLadderStageTraceEvent: (input: Parameters<typeof appendReviewLadderStageTraceEvent>[0]) => ReviewLadderStageTraceWriteResult;
+//#endregion
+//#region src/worker-checkout-guard.d.ts
+type CheckoutDirsProbe = (cwd: string) => {
+  gitCommonDir: string;
+  gitDir: string;
+};
+declare class WorkerCheckoutGuardError extends Error {
+  constructor(message: string);
+}
+declare function assertWorkerCheckoutAllowed({
+  cwd,
+  operation,
+  probe
+}: {
+  cwd: string;
+  operation: string;
+  probe?: CheckoutDirsProbe;
+}): void;
+//#endregion
+//#region src/index.d.ts
+interface CreateProgramOptions {
+  actions?: {
+    boundaryCheck?: BoundaryCheckAction;
+    canaryVerify?: CanaryVerifyAction;
+    prMergeCheck?: PrMergeCheckAction;
+    prPublish?: PrPublishAction;
+    prReady?: PrReadyAction;
+    prReview?: PrReviewAction;
+  };
+  factoryCliInvocation?: FactoryCliInvocation;
+  output?: CliOutput;
+}
+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 };