@erclx/canon 5.41.0 → 5.43.0

package/src/markdown/scope.ts

@@ -42,41 +42,113 @@ export const GATED_PATHS: readonly string[] = [
   'canon/context/context-model.md',
   'canon/context/index.md',
   'claude/skills/api-design/SKILL.md',
+  'claude/skills/api-design/references/adopted.md',
   'claude/skills/auto-ship/SKILL.md',
+  'claude/skills/auto-ship/references/draft-mark.md',
+  'claude/skills/auto-ship/references/failure-recovery.md',
+  'claude/skills/auto-ship/references/fan-in.md',
+  'claude/skills/auto-ship/references/tier-failures.md',
+  'claude/skills/auto-ship/references/ui-checklist.md',
+  'claude/skills/auto-ship/references/verb-absent.md',
+  'claude/skills/auto-ship/references/worktree-name.md',
   'claude/skills/backlog-triage/SKILL.md',
   'claude/skills/backlog-triage/references/apply.md',
   'claude/skills/build-in-slices/SKILL.md',
+  'claude/skills/build-in-slices/references/adopted.md',
   'claude/skills/canon-cli/SKILL.md',
   'claude/skills/canon-feedback-triage/SKILL.md',
   'claude/skills/canon-feedback/SKILL.md',
+  'claude/skills/canon-feedback/references/template.md',
   'claude/skills/canvas-board/SKILL.md',
+  'claude/skills/canvas-board/references/canvas.md',
+  'claude/skills/canvas-board/references/design.md',
   'claude/skills/ci-workflow/SKILL.md',
+  'claude/skills/ci-workflow/references/workflows.md',
   'claude/skills/code-craft/SKILL.md',
+  'claude/skills/code-craft/references/adopted.md',
   'claude/skills/codebase-layout/SKILL.md',
+  'claude/skills/codebase-layout/references/adopted.md',
+  'claude/skills/codebase-layout/references/frontend.md',
+  'claude/skills/codebase-layout/references/tests.md',
   'claude/skills/context-fold/SKILL.md',
+  'claude/skills/context-fold/references/classify.md',
+  'claude/skills/context-fold/references/completion-report.md',
+  'claude/skills/context-fold/references/context-refresh.md',
+  'claude/skills/context-fold/references/context.md',
+  'claude/skills/context-fold/references/unusable-baseline.md',
   'claude/skills/create-rule/SKILL.md',
+  'claude/skills/create-rule/references/rule.md',
   'claude/skills/create-skill/SKILL.md',
+  'claude/skills/create-skill/references/skill-disclosure.md',
+  'claude/skills/create-skill/references/skill-frontmatter.md',
+  'claude/skills/create-skill/references/skill-paths.md',
+  'claude/skills/create-skill/references/skill-practice.md',
+  'claude/skills/create-skill/references/skill-reference.md',
+  'claude/skills/create-skill/references/skill-requirement.md',
+  'claude/skills/create-skill/references/skill.md',
   'claude/skills/decision-escalate/SKILL.md',
   'claude/skills/deploy-app/SKILL.md',
+  'claude/skills/deploy-app/references/cloudflare.md',
+  'claude/skills/deploy-app/references/vercel.md',
   'claude/skills/deprecation-migration/SKILL.md',
+  'claude/skills/deprecation-migration/references/adopted.md',
   'claude/skills/design-taste/SKILL.md',
+  'claude/skills/design-taste/references/adopted.md',
+  'claude/skills/design-taste/references/craft.md',
+  'claude/skills/design-taste/references/kinds.md',
+  'claude/skills/design-taste/references/preflight.md',
+  'claude/skills/design-taste/references/systems.md',
+  'claude/skills/design-taste/references/tells.md',
+  'claude/skills/design-taste/references/vocabulary.md',
   'claude/skills/docs-sync/SKILL.md',
+  'claude/skills/docs-sync/references/docs.md',
+  'claude/skills/docs-sync/references/readme.md',
   'claude/skills/document-health/SKILL.md',
+  'claude/skills/document-health/references/axes.md',
   'claude/skills/draft-and-pick/SKILL.md',
+  'claude/skills/draft-and-pick/references/live-arms.md',
   'claude/skills/draft-doc/SKILL.md',
+  'claude/skills/draft-doc/references/context.md',
+  'claude/skills/draft-doc/references/docs.md',
+  'claude/skills/draft-doc/references/readme.md',
+  'claude/skills/draft-doc/references/readme/agent-facing.md',
+  'claude/skills/draft-doc/references/readme/application.md',
+  'claude/skills/draft-doc/references/readme/cli.md',
+  'claude/skills/draft-doc/references/readme/library.md',
+  'claude/skills/draft-doc/references/readme/plugin.md',
+  'claude/skills/draft-doc/references/requirements.md',
+  'claude/skills/draft-doc/references/wiki-kind.md',
+  'claude/skills/draft-doc/references/wiki.md',
   'claude/skills/draft-figure/SKILL.md',
+  'claude/skills/draft-figure/references/architecture-set.md',
+  'claude/skills/draft-figure/references/figures.md',
+  'claude/skills/draft-figure/references/hand-drawn.md',
+  'claude/skills/draft-figure/references/mermaid-path.md',
+  'claude/skills/draft-figure/references/mermaid.md',
   'claude/skills/draft-identity/SKILL.md',
   'claude/skills/draft-identity/references/card-route.md',
   'claude/skills/draft-ready/SKILL.md',
+  'claude/skills/draft-ready/references/assembly.md',
+  'claude/skills/draft-ready/references/ready.md',
   'claude/skills/draft-screencast/SKILL.md',
   'claude/skills/draft-screencast/references/beats-template.md',
   'claude/skills/draft-slides/SKILL.md',
   'claude/skills/draft-slides/references/deck.md',
   'claude/skills/git-branch/SKILL.md',
+  'claude/skills/git-branch/references/branch.md',
+  'claude/skills/git-branch/references/slug.md',
   'claude/skills/git-commit/SKILL.md',
+  'claude/skills/git-commit/references/commit.md',
+  'claude/skills/git-commit/references/versioning.md',
   'claude/skills/git-followup/SKILL.md',
   'claude/skills/git-issue/SKILL.md',
+  'claude/skills/git-issue/references/issue.md',
   'claude/skills/git-pr/SKILL.md',
+  'claude/skills/git-pr/references/final-command.md',
+  'claude/skills/git-pr/references/labels.md',
+  'claude/skills/git-pr/references/pr.md',
+  'claude/skills/git-pr/references/publish.md',
+  'claude/skills/git-pr/references/task-number.md',
   'claude/skills/git-ship/SKILL.md',
   'claude/skills/git-ship/references/ci-watch.md',
   'claude/skills/git-split/SKILL.md',
@@ -86,45 +158,117 @@ export const GATED_PATHS: readonly string[] = [
   'claude/skills/git-worktree/SKILL.md',
   'claude/skills/git-worktree/references/cleanup.md',
   'claude/skills/markdown-craft/SKILL.md',
+  'claude/skills/markdown-craft/references/markdown.md',
   'claude/skills/plan-feature/SKILL.md',
   'claude/skills/plan-feature/references/batches.md',
+  'claude/skills/plan-feature/references/plan-lifecycle.md',
+  'claude/skills/plan-feature/references/plan.md',
   'claude/skills/plan-groundwork/SKILL.md',
+  'claude/skills/plan-groundwork/references/groundwork-spikes.md',
+  'claude/skills/plan-groundwork/references/groundwork.md',
   'claude/skills/plan-groundwork/references/output.md',
   'claude/skills/plan-intake-answer/SKILL.md',
   'claude/skills/plan-intake/SKILL.md',
+  'claude/skills/plan-intake/references/intake.md',
+  'claude/skills/pr-evidence/SKILL.md',
+  'claude/skills/pr-evidence/references/evidence.md',
   'claude/skills/read-frames/SKILL.md',
   'claude/skills/record-screencast/SKILL.md',
   'claude/skills/review-address/SKILL.md',
+  'claude/skills/review-address/references/post-review-findings.md',
+  'claude/skills/review-address/references/rebase-conflicts.md',
   'claude/skills/review-address/references/rebase-only.md',
+  'claude/skills/review-address/references/rest-reads.md',
   'claude/skills/review-craft/SKILL.md',
+  'claude/skills/review-craft/references/adopted.md',
+  'claude/skills/review-craft/references/security.md',
+  'claude/skills/review-craft/references/ui.md',
   'claude/skills/review-pr/SKILL.md',
+  'claude/skills/review-pr/references/body-variants.md',
+  'claude/skills/review-pr/references/close-out.md',
+  'claude/skills/review-pr/references/key-changes.md',
+  'claude/skills/review-pr/references/post.md',
+  'claude/skills/review-pr/references/scope.md',
   'claude/skills/review-ui/SKILL.md',
+  'claude/skills/review-ui/references/close-out.md',
+  'claude/skills/review-ui/references/driving.md',
   'claude/skills/review-ui/references/hosted-preview.md',
+  'claude/skills/review-ui/references/post.md',
+  'claude/skills/review-ui/references/tick.md',
   'claude/skills/role-orchestrator/SKILL.md',
+  'claude/skills/role-orchestrator/references/orchestrator-cloud-launch.md',
+  'claude/skills/role-orchestrator/references/orchestrator-dispatch.md',
   'claude/skills/role-orchestrator/references/orchestrator-filing.md',
+  'claude/skills/role-orchestrator/references/orchestrator-handback.md',
+  'claude/skills/role-orchestrator/references/orchestrator-handoff.md',
+  'claude/skills/role-orchestrator/references/orchestrator-inbound.md',
+  'claude/skills/role-orchestrator/references/orchestrator-launch.md',
+  'claude/skills/role-orchestrator/references/orchestrator-output.md',
+  'claude/skills/role-orchestrator/references/orchestrator-parked.md',
+  'claude/skills/role-orchestrator/references/orchestrator-poll.md',
+  'claude/skills/role-orchestrator/references/orchestrator-refill.md',
+  'claude/skills/role-orchestrator/references/orchestrator-resume.md',
+  'claude/skills/role-orchestrator/references/orchestrator-review-dispatch.md',
+  'claude/skills/role-orchestrator/references/orchestrator-reviewer-launch.md',
+  'claude/skills/role-orchestrator/references/orchestrator-sweep.md',
+  'claude/skills/role-orchestrator/references/orchestrator-watch.md',
   'claude/skills/role-planner/SKILL.md',
   'claude/skills/role-reviewer/SKILL.md',
   'claude/skills/role-worker/SKILL.md',
   'claude/skills/search-craft/SKILL.md',
+  'claude/skills/search-craft/references/adopted.md',
   'claude/skills/session-compact/SKILL.md',
+  'claude/skills/session-compact/references/handoff-note.md',
   'claude/skills/session-map/SKILL.md',
+  'claude/skills/session-map/references/session.md',
   'claude/skills/session-relay/SKILL.md',
   'claude/skills/session-resume/SKILL.md',
   'claude/skills/session-worktree/SKILL.md',
+  'claude/skills/session-worktree/references/install-command.md',
+  'claude/skills/session-worktree/references/main-root-writes.md',
   'claude/skills/systematic-debugging/SKILL.md',
+  'claude/skills/systematic-debugging/references/adopted.md',
   'claude/skills/target-check/SKILL.md',
+  'claude/skills/target-check/references/domains.md',
   'claude/skills/target-setup/SKILL.md',
+  'claude/skills/target-setup/references/detect.md',
+  'claude/skills/target-setup/references/indexes.md',
+  'claude/skills/target-setup/references/verify.md',
   'claude/skills/task-board/SKILL.md',
+  'claude/skills/task-board/references/board.md',
   'claude/skills/task-board/references/create-report.md',
+  'claude/skills/task-board/references/decline.md',
+  'claude/skills/task-board/references/tasks-decline.md',
+  'claude/skills/task-board/references/tasks.md',
   'claude/skills/task-complete/SKILL.md',
+  'claude/skills/task-complete/references/archive.md',
+  'claude/skills/task-complete/references/receipt-sweep.md',
+  'claude/skills/task-complete/references/unusable-baseline.md',
   'claude/skills/teach-workspace/SKILL.md',
+  'claude/skills/teach-workspace/references/glossary.md',
+  'claude/skills/teach-workspace/references/lesson-build.md',
+  'claude/skills/teach-workspace/references/lesson-craft.md',
+  'claude/skills/teach-workspace/references/pedagogy.md',
+  'claude/skills/teach-workspace/references/promotion-fold.md',
+  'claude/skills/teach-workspace/references/promotion.md',
+  'claude/skills/teach-workspace/references/revisit.md',
+  'claude/skills/teach-workspace/references/teach.md',
   'claude/skills/test-craft/SKILL.md',
+  'claude/skills/test-craft/references/adopted.md',
+  'claude/skills/test-craft/references/component.md',
+  'claude/skills/test-craft/references/e2e.md',
+  'claude/skills/test-craft/references/unit.md',
   'claude/skills/test-first/SKILL.md',
+  'claude/skills/test-first/references/adopted.md',
   'claude/skills/ui-checklist/SKILL.md',
   'claude/skills/ux-audit/SKILL.md',
   'claude/skills/ux-measure/SKILL.md',
   'claude/skills/video-craft/SKILL.md',
+  'claude/skills/video-craft/references/adopted.md',
   'claude/skills/write-human/SKILL.md',
+  'claude/skills/write-human/references/adopted.md',
+  'claude/skills/write-human/references/density.md',
+  'claude/skills/write-human/references/machine-tells.md',
   'claude/skills/youtube-transcripts/SKILL.md',
   '.claude/skills/internal-',
   'docs/',

package/src/migrate/session-defaults.ts

@@ -0,0 +1,138 @@
+/**
+ * Adds the session defaults the seeded `.claude/settings.json` carries to a
+ * target that was seeded before them.
+ *
+ * `canon claude init` copies a seed only when the file is absent, so a target
+ * holding its own settings never sees a later seed change. This verb adds each
+ * default only where the key is absent: a deny entry is never removed, and a
+ * person's `autoMemoryEnabled: true` is never overwritten.
+ */
+
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import {
+  readSettings,
+  type SettingsKey,
+  type SettingsRecord,
+  serializeSettings,
+  writeSettings,
+} from '@/claude/settings'
+
+/** Both names, since `Task` is the tool's name before Claude Code renamed it. */
+export const DENIED_TOOLS: readonly string[] = ['Agent', 'Task']
+
+export interface SessionDefaultsPlan {
+  readonly keys: readonly SettingsKey[]
+  readonly next: SettingsRecord
+  readonly changed: boolean
+  /**
+   * True when the file holds no default at all. A file holding either one has
+   * been through the seed or this verb, so a missing deny there was removed
+   * on purpose, which is how an operator opts back into subagents.
+   */
+  readonly predates: boolean
+}
+
+export type SessionDefaultsRead =
+  | { readonly kind: 'refused'; readonly reason: string }
+  | { readonly kind: 'absent'; readonly path: string }
+  | {
+      readonly kind: 'planned'
+      readonly path: string
+      readonly indent: string
+      readonly plan: SessionDefaultsPlan
+    }
+
+export function settingsPath(root: string): string {
+  return join(root, '.claude', 'settings.json')
+}
+
+function isRecord(value: unknown): value is SettingsRecord {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Appends the denied tools a list lacks, keeping the list's own order, so the
+ * diff a person reads is the added entries alone.
+ */
+export function planSessionDefaults(
+  current: SettingsRecord,
+): SessionDefaultsPlan {
+  const next: SettingsRecord = { ...current }
+  const permissions = isRecord(current.permissions) ? current.permissions : {}
+  const deny = Array.isArray(permissions.deny) ? permissions.deny : []
+
+  const missing = DENIED_TOOLS.filter((tool) => !deny.includes(tool))
+  if (missing.length > 0) {
+    next.permissions = { ...permissions, deny: [...deny, ...missing] }
+  }
+
+  const memoryAbsent = !('autoMemoryEnabled' in current)
+  if (memoryAbsent) next.autoMemoryEnabled = false
+
+  const keys: SettingsKey[] = [
+    { label: 'permissions.deny', changed: missing.length > 0 },
+    { label: 'autoMemoryEnabled', changed: memoryAbsent },
+  ]
+  return {
+    keys,
+    next,
+    changed: keys.some((key) => key.changed),
+    predates: memoryAbsent && missing.length === DENIED_TOOLS.length,
+  }
+}
+
+/**
+ * Refuses rather than plans whenever a write could replace something the
+ * person owns: the toolkit's own settings, a file `JSON.parse` cannot read,
+ * or a `permissions` or `deny` value of an unexpected shape.
+ */
+export async function readSessionDefaults(
+  root: string,
+  protectedRoot: string,
+): Promise<SessionDefaultsRead> {
+  if (root === protectedRoot) {
+    return {
+      kind: 'refused',
+      reason:
+        'Cannot run against toolkit root. Files here are the source of truth.',
+    }
+  }
+
+  const path = settingsPath(root)
+  if (!existsSync(path)) return { kind: 'absent', path }
+
+  let read: Awaited<ReturnType<typeof readSettings>>
+  try {
+    read = await readSettings(path)
+  } catch (error) {
+    return {
+      kind: 'refused',
+      reason: error instanceof Error ? error.message : String(error),
+    }
+  }
+
+  const { permissions } = read.value
+  if (permissions !== undefined && !isRecord(permissions)) {
+    return { kind: 'refused', reason: `${path}: permissions is not an object` }
+  }
+  if (permissions?.deny !== undefined && !Array.isArray(permissions.deny)) {
+    return {
+      kind: 'refused',
+      reason: `${path}: permissions.deny is not a list`,
+    }
+  }
+
+  return {
+    kind: 'planned',
+    path,
+    indent: read.indent,
+    plan: planSessionDefaults(read.value),
+  }
+}
+
+export async function applySessionDefaults(
+  read: Extract<SessionDefaultsRead, { kind: 'planned' }>,
+): Promise<void> {
+  await writeSettings(read.path, serializeSettings(read.plan.next, read.indent))
+}

package/src/pr/lift.ts

@@ -144,7 +144,10 @@ function fail(gate: GateName, reason: LiftRefusal): GateResult {
  * since the commit it covers is a stamp GitHub wrote at submission, which the
  * marker exists to replace.
  */
-function reviewGate(reviews: readonly ReviewRow[], head: string): GateResult {
+export function reviewGate(
+  reviews: readonly ReviewRow[],
+  head: string,
+): GateResult {
   const scope = resolveReviewScope({ reviews })
   if (scope.state === 'none') return fail('review', 'review-missing')
   if (scope.state === 'open') return fail('review', 'review-open')
@@ -175,8 +178,8 @@ function carried(gates: readonly GateResult[]): {
  * checklist the reviewer drove as true as it was. A close that is not an
  * ancestor, which a force-push or a rebase leaves, never carries.
  */
-async function uiGate(
-  api: LiftApi,
+export async function uiGate(
+  api: Pick<LiftApi, 'readChanged'>,
   painted: PaintedPatterns,
   reviews: readonly ReviewRow[],
   head: string,

package/src/pr/local.ts

@@ -1,26 +1,11 @@
+import { belongsTo } from '@/listeners/belongs'
+import type { ListenerReader } from '@/listeners/machine'
 import { readAddresses } from '@/pr/evidence'
 
-/**
- * The folder linked worktrees sit under. A listener there belongs to another
- * branch even though its cwd sits inside the main checkout's toplevel.
- */
-const LINKED_WORKTREES = '.claude/worktrees'
-
-/** The state `/proc/net/tcp` writes for a socket in LISTEN. */
-const PROC_LISTEN_STATE = '0A'
-
 export type LocalRefusal = 'no-server' | 'no-listener-reader'
 
-export interface Listener {
-  readonly port: number
-  readonly pid: number
-}
-
-/** The machine reads a detection makes, injected so it can be driven without binding a socket. */
-export interface LocalRunner {
-  /** Every TCP socket in LISTEN with its owning pid, or undefined when this machine offers no way to read them. */
-  listListeners(): Promise<readonly Listener[] | undefined>
-  cwdOf(pid: number): Promise<string | undefined>
+/** The listener reads a detection makes plus an HTML probe, injected so it can be driven without binding a socket. */
+export interface LocalRunner extends ListenerReader {
   /** Whether the port serves an HTML page at its root inside the runner's timeout. */
   probe(port: number): Promise<boolean>
 }
@@ -29,22 +14,6 @@ export type LocalResult =
   | { readonly kind: 'found'; readonly port: number; readonly url: string }
   | { readonly kind: 'refused'; readonly reason: LocalRefusal }
 
-function isInside(path: string, root: string): boolean {
-  return path === root || path.startsWith(`${root}/`)
-}
-
-/**
- * Whether a process running in `cwd` serves this worktree. A tool that
- * changes into a subfolder before listening still counts, while a sibling
- * worktree nested under the main checkout's `.claude/worktrees/` does not.
- */
-function belongsTo(cwd: string, worktreeRoot: string): boolean {
-  return (
-    isInside(cwd, worktreeRoot) &&
-    !isInside(cwd, `${worktreeRoot}/${LINKED_WORKTREES}`)
-  )
-}
-
 /**
  * Finds the server this worktree is running: the lowest port whose listening
  * process runs inside the worktree and answers an HTTP probe. A port rather
@@ -76,40 +45,6 @@ export async function findLocalServer(
   return { kind: 'refused', reason: 'no-server' }
 }
 
-/** Reads `lsof -nP -iTCP -sTCP:LISTEN -Fpn` output, where a `p` line opens a process and each `n` line names one of its sockets. */
-export function parseLsofListeners(text: string): Listener[] {
-  const listeners: Listener[] = []
-  let pid: number | undefined
-  for (const line of text.split('\n')) {
-    if (line.startsWith('p')) pid = Number(line.slice(1))
-    if (!line.startsWith('n') || pid === undefined) continue
-    const port = Number(line.slice(line.lastIndexOf(':') + 1))
-    if (Number.isInteger(port) && port > 0) listeners.push({ pid, port })
-  }
-  return listeners
-}
-
-export interface ProcSocket {
-  readonly port: number
-  readonly inode: string
-}
-
-/** Reads `/proc/net/tcp` or `tcp6`, keeping each listening socket's port and inode for matching against `/proc/<pid>/fd`. */
-export function parseProcNetTcp(text: string): ProcSocket[] {
-  const sockets: ProcSocket[] = []
-  for (const line of text.split('\n').slice(1)) {
-    const fields = line.trim().split(/\s+/)
-    const local = fields[1]
-    const state = fields[3]
-    const inode = fields[9]
-    if (local === undefined || inode === undefined) continue
-    if (state !== PROC_LISTEN_STATE) continue
-    const port = Number.parseInt(local.slice(local.lastIndexOf(':') + 1), 16)
-    if (Number.isInteger(port) && port > 0) sockets.push({ port, inode })
-  }
-  return sockets
-}
-
 /**
  * Drops the address line of a marked body, hosted and local segments alike,
  * since the close that runs this also deletes the branch's preview

package/src/pr/review-state.ts

@@ -0,0 +1,182 @@
+import {
+  CHECKS_POLL_MS,
+  type GateResult,
+  type LiftApi,
+  type LiftRefusal,
+  reviewGate,
+  uiGate,
+} from '@/pr/lift'
+import { DEFAULT_PAINTED, type PaintedPatterns } from '@/pr/painted'
+import {
+  coversHead,
+  type ReviewRow,
+  type ReviewScope,
+  resolveReviewScope,
+  resolveUiScope,
+  type UiScope,
+} from '@/pr/review-scope'
+
+/**
+ * The reads the verb makes, a subset of the lift's so a worker waiting here and
+ * a reviewer lifting read one answer. A read that failed returns undefined, and
+ * the verb refuses `gh-failed` rather than reading absence as no pass.
+ */
+export type ReviewStateApi = Pick<
+  LiftApi,
+  'readReviews' | 'readEvidence' | 'readChanged' | 'sleep' | 'now'
+> & {
+  /** The branch tip from the remote, which is what a pass has to cover. */
+  readTip(): Promise<string | undefined>
+}
+
+/** One family's standing at the tip. */
+export interface FamilyState {
+  /** The lift's refusal for this family, absent when its gate passes. */
+  readonly reason?: LiftRefusal
+  /**
+   * Whether a pass covers the tip, which is what a waiting worker reads. True
+   * when the gate passes, or when the newest pass, open or unmarked, names the
+   * tip. The reason alone cannot answer it, since the lift reads an open pass
+   * before it reads currency.
+   */
+  readonly isCovered: boolean
+}
+
+export interface UiState extends UiScope, FamilyState {
+  /** Whether the evidence comment carries a checklist, which binds the family. */
+  readonly isBound: boolean
+  readonly carriedFrom?: string
+  readonly paintedPaths?: readonly string[]
+}
+
+export interface ReviewStateRecord {
+  readonly head: string
+  readonly scope: ReviewScope
+  readonly review: FamilyState
+  readonly ui: UiState
+}
+
+export type ReviewStateRead =
+  | { readonly kind: 'read'; readonly record: ReviewStateRecord }
+  | { readonly kind: 'refused'; readonly reason: 'gh-failed' }
+
+export type ReviewWait =
+  | {
+      readonly kind: 'read'
+      readonly reason: 'covered' | 'timeout'
+      readonly record: ReviewStateRecord
+      readonly waitedSeconds: number
+    }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'gh-failed'
+      readonly waitedSeconds: number
+    }
+
+export interface WaitOptions {
+  readonly waitSeconds: number
+  readonly pollMs?: number
+  readonly painted?: PaintedPatterns
+}
+
+function familyOf(gate: GateResult, commit: string | undefined, tip: string) {
+  return {
+    ...(gate.reason !== undefined && { reason: gate.reason }),
+    isCovered: gate.isOk || (commit !== undefined && coversHead(commit, tip)),
+  }
+}
+
+/**
+ * Both families at the tip through the lift's own gates, so a worker and the
+ * lift never disagree on a reason. The evidence is read by the caller, since a
+ * wait reads it once rather than once per poll.
+ */
+async function readAt(
+  api: ReviewStateApi,
+  hasChecklist: boolean,
+  painted: PaintedPatterns,
+): Promise<ReviewStateRead> {
+  const [tip, reviews] = await Promise.all([api.readTip(), api.readReviews()])
+  if (tip === undefined || reviews === undefined) {
+    return { kind: 'refused', reason: 'gh-failed' }
+  }
+
+  const listing: { reviews: readonly ReviewRow[] } = { reviews }
+  const scope = resolveReviewScope(listing)
+  const uiScope = resolveUiScope(listing)
+  const ui = await uiGate(api, painted, reviews, tip, hasChecklist)
+  if (ui.reason === 'gh-failed') return { kind: 'refused', reason: 'gh-failed' }
+
+  return {
+    kind: 'read',
+    record: {
+      head: tip,
+      scope,
+      review: familyOf(reviewGate(reviews, tip), scope.commit, tip),
+      ui: {
+        ...uiScope,
+        ...familyOf(ui, uiScope.commit, tip),
+        isBound: hasChecklist,
+        ...(ui.carriedFrom !== undefined && { carriedFrom: ui.carriedFrom }),
+        ...(ui.paintedPaths !== undefined && { paintedPaths: ui.paintedPaths }),
+      },
+    },
+  }
+}
+
+export async function readReviewState(
+  api: ReviewStateApi,
+  painted: PaintedPatterns = DEFAULT_PAINTED,
+): Promise<ReviewStateRead> {
+  const evidence = await api.readEvidence()
+  if (evidence === undefined) return { kind: 'refused', reason: 'gh-failed' }
+  return readAt(api, evidence.hasChecklist, painted)
+}
+
+/**
+ * Holds until every bound family has a pass covering the tip, or the deadline
+ * passes. The tip is read again every poll, so a push during the wait moves
+ * what a pass has to cover. The evidence is read once, since a checklist
+ * appearing mid-wait is a ship-chain write the waiting worker made before it
+ * started.
+ */
+export async function waitForReviews(
+  api: ReviewStateApi,
+  opts: WaitOptions,
+): Promise<ReviewWait> {
+  const pollMs = opts.pollMs ?? CHECKS_POLL_MS
+  const painted = opts.painted ?? DEFAULT_PAINTED
+  const started = api.now()
+  const deadline = started + opts.waitSeconds * 1000
+  const waited = () => Math.round((api.now() - started) / 1000)
+
+  const evidence = await api.readEvidence()
+  if (evidence === undefined) {
+    return { kind: 'refused', reason: 'gh-failed', waitedSeconds: waited() }
+  }
+
+  for (;;) {
+    const read = await readAt(api, evidence.hasChecklist, painted)
+    if (read.kind === 'refused') {
+      return { ...read, waitedSeconds: waited() }
+    }
+    const { record } = read
+    if (record.review.isCovered && record.ui.isCovered) {
+      return {
+        kind: 'read',
+        reason: 'covered',
+        record,
+        waitedSeconds: waited(),
+      }
+    }
+    if (api.now() + pollMs > deadline) {
+      return {
+        kind: 'read',
+        reason: 'timeout',
+        record,
+        waitedSeconds: waited(),
+      }
+    }
+    await api.sleep(pollMs)
+  }
+}