@erclx/canon 5.64.0 → 5.66.0

package/src/commands/sandbox.ts

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { basename, dirname, join, relative, resolve } from 'node:path'
 import type { Command } from 'commander'
 import { checkoutMismatchWarning, PROJECT_ROOT } from '@/roots/project'
 import {
@@ -27,8 +27,24 @@ import {
 } from '@/sandbox/expect'
 import { runHeadless } from '@/sandbox/headless/run'
 import { runSandbox } from '@/sandbox/provision'
+import {
+  EXPECTED_FILE,
+  expectationOf,
+  judgeDrift,
+  readExpectation,
+  writeExpectation,
+  type ReplayExpectation,
+} from '@/sandbox/replay/expected'
+import {
+  checkoutRefusal,
+  hasFormatter,
+  listSnapshots,
+  replaySource,
+  type ReplayResult,
+  type ReplaySource,
+} from '@/sandbox/replay/run'
 import { listCategories, listScenarioFiles } from '@/sandbox/scenario'
-import { sandboxTree } from '@/sandbox/tree'
+import { assertSandboxDirSafe, sandboxRoots, sandboxTree } from '@/sandbox/tree'
 import {
   frameError,
   intro,
@@ -434,6 +450,194 @@ async function runEquivalence(
   process.exitCode = equivalenceExitCode(record)
 }
 
+interface ReplayOptions {
+  readonly json?: boolean
+  readonly record?: boolean
+}
+
+const REPLAY_FINDINGS_SHOWN = 5
+
+function refuseReplay(reason: string, message: string, json: boolean): void {
+  logError(message)
+  if (json)
+    process.stdout.write(`${JSON.stringify({ ok: false, reason, message })}\n`)
+  outro()
+  process.exitCode = 1
+}
+
+/**
+ * Replays each consumer through a sync with this checkout's CLI and judges
+ * the reads that follow. Bare, it replays the frozen snapshots, which is what
+ * the gate runs. Given paths, it copies each real checkout, the operator's
+ * step before a release. Every source is checked before any replay starts, so
+ * a refusal never arrives after half the runs. A snapshot is judged against
+ * the answer recorded beside it, since a frozen tree answers the same on every
+ * push, and `--record` rewrites that answer from a run that broke nothing.
+ */
+function runReplay(paths: string[], options: ReplayOptions): void {
+  if (reportAbsentScenarioTree()) return
+
+  intro('canon sandbox replay')
+  const json = options.json === true
+  const record = options.record === true
+
+  if (record && paths.length > 0) {
+    refuseReplay(
+      'record-checkout',
+      'A named checkout moves between runs, so --record pins snapshots only. Drop the paths.',
+      json,
+    )
+    return
+  }
+
+  if (!hasFormatter(PROJECT_ROOT)) {
+    refuseReplay(
+      'no-formatter',
+      'No oxfmt under node_modules, so the format step cannot run. Run bun install in this checkout.',
+      json,
+    )
+    return
+  }
+
+  let sources: ReplaySource[]
+  if (paths.length === 0) {
+    sources = listSnapshots(join(SANDBOX_DIR, 'fixtures', 'replay'))
+    if (sources.length === 0) {
+      refuseReplay(
+        'no-snapshots',
+        'No snapshot under sandbox/fixtures/replay/',
+        json,
+      )
+      return
+    }
+  } else {
+    sources = []
+    for (const raw of paths) {
+      const path = resolve(process.cwd(), raw)
+      const refusal = checkoutRefusal(path)
+      if (refusal !== undefined) {
+        refuseReplay(refusal.reason, refusal.message, json)
+        return
+      }
+      sources.push({ name: basename(path), path, kind: 'checkout' })
+    }
+  }
+
+  // Beside the provisioned tree rather than inside it, since `canon sandbox
+  // clean` wipes that one and a concurrent replay would lose its tree.
+  const tempRoot = join(dirname(sandboxTree()), 'replay')
+  const unsafe = assertSandboxDirSafe(
+    join(tempRoot, 'tree'),
+    sandboxRoots(PROJECT_ROOT),
+  )
+  if (unsafe !== undefined) {
+    refuseReplay('unsafe-root', unsafe, json)
+    return
+  }
+
+  const expectations = new Map<string, ReplayExpectation | undefined>()
+  if (!record)
+    for (const source of sources) {
+      if (source.kind !== 'snapshot') continue
+      try {
+        expectations.set(source.name, readExpectation(source.path))
+      } catch (error) {
+        refuseReplay('bad-expectation', (error as Error).message, json)
+        return
+      }
+    }
+
+  const replays: ReplayResult[] = []
+  for (const source of sources) {
+    const run = replaySource(source, {
+      checkoutRoot: PROJECT_ROOT,
+      tempRoot,
+    })
+    const result: ReplayResult =
+      source.kind === 'snapshot' && !record
+        ? {
+            ...run,
+            steps: judgeDrift(run.steps, expectations.get(source.name)),
+          }
+        : run
+    replays.push(result)
+
+    logStep(`${result.name} (${result.kind})`)
+    for (const step of result.steps) {
+      if (step.verdict === 'ok') logInfo(`${step.step}, exit ${step.exit}`)
+      else
+        logError(`${result.name}: ${step.step} ${step.verdict}: ${step.detail}`)
+      // A sync over an old layout prints a line per rule it moves, so the
+      // frame shows the first few and the record carries every one.
+      if (json) continue
+      for (const finding of step.findings.slice(0, REPLAY_FINDINGS_SHOWN))
+        logWarn(`${step.step}: ${finding}`)
+      const hidden = step.findings.length - REPLAY_FINDINGS_SHOWN
+      if (hidden > 0)
+        logWarn(`${step.step}: ${hidden} more, listed under --json`)
+    }
+  }
+
+  const failed = replays
+    .flatMap((r) => r.steps)
+    .filter((s) => s.verdict !== 'ok')
+
+  if (record) {
+    recordReplays(sources, replays, failed.length, json)
+    return
+  }
+
+  logStep('Replay')
+  const summary = `${replays.length} replayed, ${failed.length} failed steps`
+  if (failed.length === 0) logInfo(summary)
+  else logWarn(summary)
+
+  if (json)
+    process.stdout.write(
+      `${JSON.stringify({ ok: true, failed: failed.length, replays })}\n`,
+    )
+
+  outro()
+  process.exitCode = failed.length === 0 ? 0 : 2
+}
+
+/**
+ * Writes each snapshot's expectation from its run, or refuses and writes none
+ * when any step broke, since pinning a crash would make it the expected answer.
+ */
+function recordReplays(
+  sources: readonly ReplaySource[],
+  replays: readonly ReplayResult[],
+  broken: number,
+  json: boolean,
+): void {
+  if (broken > 0) {
+    refuseReplay(
+      'broken-run',
+      `${broken} steps broke, so nothing was recorded. Fix the run, then record it.`,
+      json,
+    )
+    return
+  }
+
+  logStep('Record')
+  const recorded: string[] = []
+  for (const [i, source] of sources.entries()) {
+    const replay = replays[i]
+    if (replay === undefined) continue
+    writeExpectation(source.path, expectationOf(replay.steps))
+    const path = relative(PROJECT_ROOT, join(source.path, EXPECTED_FILE))
+    recorded.push(path)
+    logInfo(path)
+  }
+
+  if (json)
+    process.stdout.write(`${JSON.stringify({ ok: true, recorded, replays })}\n`)
+
+  outro()
+  process.exitCode = 0
+}
+
 function runCheck(
   target: string,
   arm: string | undefined,
@@ -683,4 +887,45 @@ export function register(program: Command): void {
     .action((targets: string[], options: EquivalenceOptions) =>
       runEquivalence(targets, options),
     )
+
+  sandbox
+    .command('replay')
+    .description(
+      'Sync a copy of each consumer with this checkout and judge the reads that follow',
+    )
+    .argument(
+      '[paths...]',
+      'Consumer checkouts to copy, defaulting to every snapshot under sandbox/fixtures/replay/',
+    )
+    .helpOption('-h, --help', 'Show this help message')
+    .option('--json', 'Emit the record as JSON on stdout')
+    .option(
+      '--record',
+      `Write each snapshot's ${EXPECTED_FILE} from this run instead of judging against it`,
+    )
+    .addHelpText(
+      'after',
+      [
+        '',
+        'Examples:',
+        '  canon sandbox replay',
+        '  canon sandbox replay --record',
+        '  canon sandbox replay ../frameboard ../jobtriage --json',
+        '',
+        'Each replay copies the source to a temp tree outside the repository,',
+        'runs sync, then sync --check, context audit, markdown audit, and',
+        'migrate status, and checks what sync wrote with oxfmt. A finding or a',
+        'refusal from a read is the verb working. Only a crash, stdout a --json',
+        'caller cannot parse, or an unformatted write fails the run.',
+        'A snapshot also fails a step whose exit or finding count drifted from',
+        `the ${EXPECTED_FILE} beside it, and fails every step when it has none.`,
+        '--record rewrites those files, refusing named paths and a broken run.',
+        'A named checkout with uncommitted changes is refused, never synced over.',
+        '',
+        'Exit codes: 0 clean or recorded, 1 refused, 2 when any step failed.',
+      ].join('\n'),
+    )
+    .action((paths: string[], options: ReplayOptions) => {
+      runReplay(paths, options)
+    })
 }

package/src/gate/measures.ts

@@ -519,9 +519,12 @@ export const documentCeiling: Measure = async (ctx) => {
  *
  * `canon/context/context-model.md` is exempt, since "context model" is the
  * domain's own name and the entry reads as nothing else without the prefix.
+ * So is a replay snapshot, which copies a consumer's paths verbatim, such as
+ * `canon/config/config.json`, and a renamed copy would sync as another file.
  */
 export function isFolderEchoedName(path: string): boolean {
   if (path === 'canon/context/context-model.md') return false
+  if (path.startsWith('sandbox/fixtures/replay/')) return false
   const segments = path.split('/')
   if (segments.length < 2) return false
   const folder = segments[segments.length - 2] ?? ''

package/src/gate/stages.ts

@@ -304,6 +304,31 @@ export const STAGES: readonly Stage[] = [
     label: 'Unreferenced rules',
     checks: [{ kind: 'measure', measure: unreferencedRules }],
   },
+  {
+    // A defect that only shows after a sync, such as a read crashing on a
+    // rule layout the sync just renamed, passes every unit test and every
+    // stage that reads this repository. Replaying the frozen consumer
+    // snapshots through this checkout's sync is what reaches it before a
+    // consumer does. Scoped to what a sync ships or reads, since a replay
+    // costs seconds a docs-only push should not pay. Governance is whole
+    // but for the ledger, since sync resolves stacks and renames as well as
+    // rules, and a rename is the class the stage was built against.
+    id: 'consumer-replay',
+    label: 'Consumer replay',
+    scope:
+      /^src\/|^governance\/(?!ledger\/)|^tooling\/|^sandbox\/fixtures\/replay\//,
+    skipped:
+      'No synced surface or snapshot changed, so no consumer was replayed',
+    checks: [
+      {
+        kind: 'cli',
+        argv: ['sandbox', 'replay'],
+        failure:
+          'A consumer replay crashed, printed unparsable JSON, left an unformatted write, or drifted from its recorded answer. Run bun src/cli.ts sandbox replay, and when a drift is one the change meant, such as a governance rename moving a sync count, run it with --record and commit the expectations.',
+      },
+    ],
+    success: 'Consumer replays clean',
+  },
   {
     // The facts the audit can answer from the files gate: a cited path that
     // does not resolve, a required section an entry does not declare, an H2

package/src/labels/apply.ts

@@ -20,20 +20,25 @@ export interface LabelDiff {
  * A label the remote lacks is separated from the addable set rather than
  * dropped, because the REST add endpoint creates any label it is handed and
  * that write to the repository settings is not the map's call.
+ *
+ * Names match regardless of case, as GitHub holds them, so this agrees with
+ * `missingLabels` on which labels the remote carries.
  */
 export function diffLabels(
   earned: readonly string[],
   present: readonly string[],
   remote: readonly string[],
 ): LabelDiff {
-  const has = new Set(present)
-  const carried = new Set(remote)
+  const fold = (labels: readonly string[]): Set<string> =>
+    new Set(labels.map((label) => label.toLowerCase()))
+  const has = fold(present)
+  const carried = fold(remote)
 
-  const owed = earned.filter((label) => !has.has(label))
+  const owed = earned.filter((label) => !has.has(label.toLowerCase()))
 
   return {
     owed,
-    toAdd: owed.filter((label) => carried.has(label)),
-    missingOnRemote: owed.filter((label) => !carried.has(label)),
+    toAdd: owed.filter((label) => carried.has(label.toLowerCase())),
+    missingOnRemote: owed.filter((label) => !carried.has(label.toLowerCase())),
   }
 }

package/src/labels/sync.ts

@@ -0,0 +1,17 @@
+/**
+ * The labels a map names that the remote does not carry yet, in map order.
+ *
+ * Only ever a subset of the map, so a label a person made by hand never
+ * appears and nothing here can become an edit or a deletion on the remote.
+ *
+ * GitHub holds label names unique regardless of case, so a remote `Docs`
+ * counts as carrying `docs`. Creating it would be refused, and every later
+ * run would report the same failure.
+ */
+export function missingLabels(
+  mapLabels: readonly string[],
+  remote: readonly string[],
+): string[] {
+  const carried = new Set(remote.map((label) => label.toLowerCase()))
+  return mapLabels.filter((label) => !carried.has(label.toLowerCase()))
+}

package/src/migrate/records.ts

@@ -103,6 +103,11 @@ function escape(value: string): string {
  * never match. The guard then stops firing in a project the move has not
  * reached, which is silent: the index goes stale while every save succeeds.
  *
+ * A replay snapshot is a frozen copy of a consumer, its hooks included, and
+ * the replay tests the upgrade from exactly that state. Sweeping one rewrites
+ * the consumer's own old-root citations, so the snapshot stops matching the
+ * release it was cut at.
+ *
  * A file outside this list can still couple to one inside it, naming an
  * excluded path as plain text while it also carries a live citation of its
  * own, which `referencesExcluded` reports separately below. Widening this list
@@ -115,6 +120,7 @@ const EXCLUDED_PREFIXES: readonly string[] = [
   'scripts/eval/result-',
   '.claude/hooks/',
   'tooling/claude/seeds/.claude/hooks/',
+  'sandbox/fixtures/replay/',
 ]
 
 const EXCLUDED_PATHS: readonly string[] = [

package/src/pr/close.ts

@@ -0,0 +1,152 @@
+import { scanPhaseLabels } from '@/labels/phase'
+import { BAN_SETS } from '@/markdown/bans'
+import { type DensityFinding, densityFindings } from '@/markdown/density'
+import { bodyLines, scanBans } from '@/markdown/scan'
+
+/** Why the verb did not close, in the order the refusals are read. */
+export type CloseRefusal =
+  | 'no-reason'
+  | 'reason-unpublishable'
+  | 'gh-failed'
+  | 'pull-closed'
+  | 'head-mismatch'
+  | 'comment-failed'
+  | 'close-failed'
+
+export interface ClosePull {
+  readonly isOpen: boolean
+  /** The head branch name, which the caller's expected head is checked against. */
+  readonly branch: string
+  /** Whether the head lives in another repository, whose branch this one cannot delete. */
+  readonly isFork: boolean
+}
+
+/**
+ * Everything the verb reads or writes, injected so every refusal runs without
+ * a network. A read or write that failed returns undefined or false, never a
+ * guess.
+ */
+export interface CloseApi {
+  readPull(): Promise<ClosePull | undefined>
+  /** Posts the reason and answers the comment's URL. */
+  postComment(body: string): Promise<string | undefined>
+  patchClosed(): Promise<boolean>
+  deleteBranch(branch: string): Promise<boolean>
+}
+
+export interface CloseOptions {
+  readonly number: number
+  readonly reason: string
+  /** The head branch the caller means, so a mistyped number closes nothing. */
+  readonly head: string
+  readonly isKeepBranch: boolean
+}
+
+/** What the reason carries that a reader on the remote cannot use. */
+export interface ReasonFindings {
+  readonly isClean: boolean
+  readonly bannedCharacters: readonly string[]
+  readonly phaseLabels: readonly string[]
+  readonly boardReferences: readonly string[]
+  readonly sessionLinks: readonly string[]
+  readonly density: readonly DensityFinding[]
+}
+
+/** What happened to the head branch once the pull request closed. */
+export type BranchOutcome = 'deleted' | 'kept' | 'fork' | 'delete-failed'
+
+export interface CloseRecord {
+  readonly reason: 'closed' | CloseRefusal
+  readonly isOk: boolean
+  readonly number: number
+  readonly commentUrl?: string
+  readonly branch?: BranchOutcome
+  readonly findings?: ReasonFindings
+}
+
+/**
+ * Runs the checks `canon labels scan` runs on a pull request body, plus
+ * density measured on the reason itself.
+ *
+ * The scan's own post density reads a body only when it opens on a known
+ * post heading, and a closing comment carries none, so an overloaded reason
+ * would pass it unmeasured.
+ */
+export function checkReason(reason: string): ReasonFindings {
+  const lines = bodyLines(reason)
+  const bannedCharacters = scanBans(lines, BAN_SETS).map(
+    (finding) => finding.term,
+  )
+  const { phaseLabels, boardReferences, sessionLinks } = scanPhaseLabels({
+    title: '',
+    body: reason,
+    headRefName: '',
+  })
+  const density = densityFindings(lines)
+
+  return {
+    isClean:
+      bannedCharacters.length === 0 &&
+      phaseLabels.length === 0 &&
+      boardReferences.length === 0 &&
+      sessionLinks.length === 0 &&
+      density.length === 0,
+    bannedCharacters,
+    phaseLabels,
+    boardReferences,
+    sessionLinks,
+    density,
+  }
+}
+
+function refused(
+  reason: CloseRefusal,
+  number: number,
+  extra: Partial<CloseRecord> = {},
+): CloseRecord {
+  return { reason, isOk: false, number, ...extra }
+}
+
+/**
+ * Closes one pull request unmerged with its reason posted first.
+ *
+ * The comment lands before the close, so a failure between the two leaves a
+ * comment on an open pull request rather than a closed one carrying no
+ * reason, which is the defect this verb exists to remove. The branch delete
+ * runs last and never fails the close, since the pull request is already
+ * closed with its reason by then.
+ */
+export async function close(
+  api: CloseApi,
+  opts: CloseOptions,
+): Promise<CloseRecord> {
+  const { number } = opts
+  const reason = opts.reason.trim()
+
+  if (reason === '') return refused('no-reason', number)
+  const findings = checkReason(reason)
+  if (!findings.isClean) {
+    return refused('reason-unpublishable', number, { findings })
+  }
+
+  const pull = await api.readPull()
+  if (pull === undefined) return refused('gh-failed', number)
+  if (!pull.isOpen) return refused('pull-closed', number)
+  if (pull.branch !== opts.head) return refused('head-mismatch', number)
+
+  const commentUrl = await api.postComment(reason)
+  if (commentUrl === undefined) return refused('comment-failed', number)
+
+  if (!(await api.patchClosed())) {
+    return refused('close-failed', number, { commentUrl })
+  }
+
+  let branch: BranchOutcome
+  if (opts.isKeepBranch) branch = 'kept'
+  else if (pull.isFork) branch = 'fork'
+  else {
+    branch = (await api.deleteBranch(pull.branch)) ? 'deleted' : 'delete-failed'
+  }
+
+  return { reason: 'closed', isOk: true, number, commentUrl, branch }
+}

package/src/pr/health.ts

@@ -0,0 +1,56 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Where a project declares what `canon pr local` checks beyond the page. */
+export const LOCAL_CONFIG_REL = join('canon', 'config', 'local.toml')
+
+/**
+ * The health paths a project declared. `none` is an absent file or an empty
+ * `health = []`. `invalid` is a declaration that exists and cannot be used,
+ * which refuses rather than falling back to the page-only probe, since that
+ * fallback is the failure the declaration exists to catch.
+ */
+export type HealthDeclaration =
+  | { readonly kind: 'paths'; readonly paths: readonly string[] }
+  | { readonly kind: 'none' }
+  | { readonly kind: 'invalid'; readonly reason: string }
+
+/**
+ * A path on the page's own host. A second leading slash would read as a
+ * protocol-relative host, so it is refused to keep the probe on localhost.
+ */
+function isLocalPath(entry: unknown): entry is string {
+  return (
+    typeof entry === 'string' &&
+    entry.startsWith('/') &&
+    !entry.startsWith('//') &&
+    !entry.startsWith('/\\')
+  )
+}
+
+export function readHealthPaths(root: string): HealthDeclaration {
+  const path = join(root, LOCAL_CONFIG_REL)
+  if (!existsSync(path)) return { kind: 'none' }
+
+  let parsed: Record<string, unknown>
+  try {
+    parsed = Bun.TOML.parse(readFileSync(path, 'utf8')) as Record<
+      string,
+      unknown
+    >
+  } catch {
+    return { kind: 'invalid', reason: `${LOCAL_CONFIG_REL} is not valid TOML` }
+  }
+
+  const declared = parsed.health
+  if (!Array.isArray(declared) || !declared.every(isLocalPath)) {
+    return {
+      kind: 'invalid',
+      reason: `${LOCAL_CONFIG_REL} needs health as a list of paths, each starting with a single /`,
+    }
+  }
+
+  return declared.length === 0
+    ? { kind: 'none' }
+    : { kind: 'paths', paths: declared }
+}

package/src/pr/local.ts

@@ -2,27 +2,62 @@ import { belongsTo } from '@/listeners/belongs'
 import type { ListenerReader } from '@/listeners/machine'
 import { readAddresses } from '@/pr/evidence'
 
-export type LocalRefusal = 'no-server' | 'no-listener-reader'
+export type LocalRefusal = 'no-server' | 'no-listener-reader' | 'unhealthy'
 
-/** The listener reads a detection makes plus an HTML probe, injected so it can be driven without binding a socket. */
+/** The listener reads a detection makes plus two HTTP probes, 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>
+  /** The final status a path on the port answers after redirects, or null when nothing answers inside the timeout. */
+  check(port: number, path: string): Promise<number | null>
 }
 
 export type LocalResult =
   | { readonly kind: 'found'; readonly port: number; readonly url: string }
-  | { readonly kind: 'refused'; readonly reason: LocalRefusal }
+  | {
+      readonly kind: 'refused'
+      readonly reason: Exclude<LocalRefusal, 'unhealthy'>
+    }
+  | {
+      readonly kind: 'refused'
+      readonly reason: 'unhealthy'
+      readonly port: number
+      readonly path: string
+      readonly status: number | null
+    }
+
+interface HealthFailure {
+  readonly path: string
+  readonly status: number | null
+}
+
+async function firstFailingPath(
+  port: number,
+  healthPaths: readonly string[],
+  runner: LocalRunner,
+): Promise<HealthFailure | undefined> {
+  for (const path of healthPaths) {
+    const status = await runner.check(port, path)
+    if (status === null || status < 200 || status >= 300) {
+      return { path, status }
+    }
+  }
+  return undefined
+}
 
 /**
  * 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
- * than a process is the unit, since one dev server often holds a second
- * socket for its reload channel, and the lower one is the page by convention.
+ * process runs inside the worktree, answers an HTTP probe, and passes every
+ * declared health path. A port rather than a process is the unit, since one
+ * dev server often holds a second socket for its reload channel, and the
+ * lower one is the page by convention. Health is read on the page's own port,
+ * since that is the address a reviewer drives, and a page whose backend fails
+ * refuses as `unhealthy` naming the lowest page port's first failing path.
  */
 export async function findLocalServer(
   worktreeRoot: string,
   runner: LocalRunner,
+  healthPaths: readonly string[] = [],
 ): Promise<LocalResult> {
   const listeners = await runner.listListeners()
   if (listeners === undefined) {
@@ -37,12 +72,18 @@ export async function findLocalServer(
     if (cwd !== undefined && belongsTo(cwd, worktreeRoot)) ports.add(port)
   }
 
+  let unhealthy: (HealthFailure & { readonly port: number }) | undefined
   for (const port of [...ports].sort((a, b) => a - b)) {
-    if (await runner.probe(port)) {
+    if (!(await runner.probe(port))) continue
+    const failure = await firstFailingPath(port, healthPaths, runner)
+    if (failure === undefined) {
       return { kind: 'found', port, url: `http://localhost:${port}` }
     }
+    unhealthy ??= { port, ...failure }
   }
-  return { kind: 'refused', reason: 'no-server' }
+  return unhealthy === undefined
+    ? { kind: 'refused', reason: 'no-server' }
+    : { kind: 'refused', reason: 'unhealthy', ...unhealthy }
 }
 
 /**