jackherd 0.0.1 → 1.0.1

package/src/watch/lane-watch.ts

@@ -0,0 +1,121 @@
+export type HerdrAgent = { name?: string; pane_id: string; agent_status: string; state_change_seq?: number }
+
+/** The herdr agent states; herdr's JSON delivers them as plain strings. */
+export const AGENT_STATUS = { working: 'working', blocked: 'blocked', done: 'done', idle: 'idle' } as const
+
+/** The state a report gives a lane whose agent left the herdr listing. */
+export const LANE_GONE = 'no longer listed'
+
+/** The state a report gives a lane that has no agent in herdr. */
+export const NO_AGENT = 'no agent'
+
+export type AgentStatus = (typeof AGENT_STATUS)[keyof typeof AGENT_STATUS]
+
+export type LaneState = { status: string; seq: number | null }
+
+export type LaneSnapshot = Record<string, LaneState>
+
+/** The last `state_change_seq` the watcher saw per lane, kept across runs; no entry means never seen. */
+export type SeenSeqs = Record<string, number | null>
+
+const STOP_STATUSES = new Set<string>([AGENT_STATUS.blocked, AGENT_STATUS.done, AGENT_STATUS.idle])
+
+export const isAgentStatus = (value: string): value is AgentStatus =>
+  (Object.values(AGENT_STATUS) as string[]).includes(value)
+
+/** The state of each named lane in a `herdr agent list` answer; unnamed and other agents are left out. */
+export const toSnapshot = (agents: readonly HerdrAgent[], lanes: readonly string[]): LaneSnapshot =>
+  Object.fromEntries(
+    agents
+      .filter((agent) => agent.name && lanes.includes(agent.name))
+      .map((agent) => [agent.name, { status: agent.agent_status, seq: agent.state_change_seq ?? null }]),
+  )
+
+const isHerdrAgent = (value: unknown): value is HerdrAgent => {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as Record<string, unknown>
+  return (
+    typeof candidate.pane_id === 'string' &&
+    typeof candidate.agent_status === 'string' &&
+    (candidate.name === undefined || typeof candidate.name === 'string') &&
+    (candidate.state_change_seq === undefined || typeof candidate.state_change_seq === 'number')
+  )
+}
+
+/** Reads the JSON of `herdr agent list`; throws on anything else, so a changed format is seen, not guessed. */
+export const agentsOf = (json: string): HerdrAgent[] => {
+  const agents = (JSON.parse(json) as { result?: { agents?: unknown } }).result?.agents
+  if (!Array.isArray(agents) || !agents.every(isHerdrAgent)) throw new Error('herdr agent list: unexpected answer')
+  return agents
+}
+
+/** The sidebar titles that differ from the ones last reported, in the order of `titles`; null clears one. */
+export const changedTitles = (
+  titles: ReadonlyMap<string, string | null>,
+  reported: ReadonlyMap<string, string | null>,
+): [string, string | null][] => [...titles].filter(([pane, title]) => reported.get(pane) !== title)
+
+const isWaiting = (state: LaneState): boolean => STOP_STATUSES.has(state.status)
+
+const hasSeen = (seen: SeenSeqs, lane: string): boolean => Object.hasOwn(seen, lane)
+
+/**
+ * The baseline a new run starts from. A lane never seen before takes its current state, so a freshly
+ * started lane does not wake the coordinator. A waiting lane seen earlier with another sequence is
+ * set back to that sequence, so a stop between the last return and the re-arm fires on the first
+ * poll instead of being swallowed. Lanes that are working start from their current state. A lane
+ * seen earlier that is missing now stays in the baseline, so its exit fires.
+ */
+export const armBaseline = (current: LaneSnapshot, seen: SeenSeqs): LaneSnapshot => {
+  const gone = Object.keys(seen)
+    .filter((lane) => !(lane in current))
+    .map((lane) => [lane, { status: LANE_GONE, seq: seen[lane] ?? null }])
+  const listed = Object.entries(current).map(([lane, state]) => [
+    lane,
+    isWaiting(state) && hasSeen(seen, lane) && seen[lane] !== state.seq ? { ...state, seq: seen[lane] ?? null } : state,
+  ])
+  return Object.fromEntries([...gone, ...listed])
+}
+
+/**
+ * The lanes that need the coordinator: a lane fires when it sits in `blocked`, `done` or `idle` with
+ * a `state_change_seq` other than the one in the baseline. A lane the last run already reported keeps
+ * its sequence and does not fire again, so re-arming right after handling a lane never returns at
+ * once. A lane that left the listing (its agent exited) fires as well; one never listed does not.
+ */
+export const firedLanes = (baseline: LaneSnapshot, current: LaneSnapshot, lanes: readonly string[]): string[] =>
+  lanes.filter((lane) => {
+    const now = current[lane]
+    if (!now) return baseline[lane] !== undefined
+    return isWaiting(now) && baseline[lane]?.seq !== now.seq
+  })
+
+/** The sequence of every observed lane; saved on each return so "no entry" means "never seen". */
+export const seenSeqsOf = (current: LaneSnapshot): SeenSeqs =>
+  Object.fromEntries(Object.entries(current).map(([lane, state]) => [lane, state.seq]))
+
+/** Moves the baseline along for lanes that are working, so their next stop counts as a change. */
+export const advanceBaseline = (baseline: LaneSnapshot, current: LaneSnapshot): LaneSnapshot =>
+  Object.fromEntries(
+    Object.entries(current).map(([lane, state]) => [
+      lane,
+      state.status === AGENT_STATUS.working ? state : (baseline[lane] ?? state),
+    ]),
+  )
+
+/**
+ * The baseline once agents showed up: a lane whose agent is listed but has no baseline entry takes
+ * its current state, as on a fresh start, so an agent that starts out idle does not wake the
+ * coordinator. Entries already there stay, including those of lanes whose agent left.
+ */
+export const baselineWithNewAgents = (baseline: LaneSnapshot, current: LaneSnapshot): LaneSnapshot => ({
+  ...current,
+  ...baseline,
+})
+
+/**
+ * The lanes that left the watched set together with their agent: they were seen, and nothing is
+ * listed for them now. They fire as gone once, although they are no longer watched.
+ */
+export const departedLanes = (removed: readonly string[], baseline: LaneSnapshot, current: LaneSnapshot): string[] =>
+  removed.filter((lane) => lane in baseline && !(lane in current))

package/src/watch/monitor-tool.ts

@@ -0,0 +1,19 @@
+type Environment = Readonly<Record<string, string | undefined>>
+
+const PROVIDER_SWITCHES = ['CLAUDE_CODE_USE_BEDROCK', 'CLAUDE_CODE_USE_VERTEX', 'CLAUDE_CODE_USE_FOUNDRY']
+
+/** Read only for being set at all: any non-empty value, `0` included, switches the behaviour on. */
+const PRESENCE_SWITCHES = ['DISABLE_TELEMETRY', 'CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC']
+
+const ON_VALUES = ['1', 'true', 'yes', 'on']
+
+/**
+ * Whether a Claude Code session started in this environment has the Monitor tool. Source: Claude Code docs,
+ * tools reference, "Monitor tool" (code.claude.com/docs/en/tools-reference#monitor-tool): not available on
+ * Amazon Bedrock, Google Cloud's Agent Platform (Vertex) or Microsoft Foundry, nor when `DISABLE_TELEMETRY` or
+ * `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` is set. The provider switches take `1`/`true`/`yes`/`on` in any
+ * casing (env-vars reference); the two others count when set to anything non-empty.
+ */
+export const monitorToolAvailable = (env: Environment): boolean =>
+  !PROVIDER_SWITCHES.some((name) => ON_VALUES.includes((env[name] ?? '').toLowerCase())) &&
+  !PRESENCE_SWITCHES.some((name) => (env[name] ?? '') !== '')

package/src/watch/options.ts

@@ -0,0 +1,79 @@
+import { CLI_NAME } from '../version/release'
+
+/**
+ * `lanes` null finds the lanes instead of taking them from the command line. `coordinator` names the
+ * coordinator's agent; null leaves it to the agent in the watcher's own pane. `stream` keeps the
+ * watcher running after a report instead of returning.
+ */
+export type WatchOptions = {
+  lanes: string[] | null
+  heartbeatMinutes: number
+  boardPath: string | null
+  coordinator: string | null
+  stream: boolean
+  /** `watch source <target> --dry-run [--raw]`: run one source once instead of watching (`SourceDryRun`). */
+  sourceDryRun: SourceDryRun | null
+}
+
+/** `target` is a configured name, a draft file or `-` for stdin; `raw` also prints the command's output. */
+export type SourceDryRun = { target: string; raw: boolean }
+
+export const DEFAULT_HEARTBEAT_MINUTES = 15
+
+const VALUE_OPTIONS = ['--heartbeat', '--board', '--coordinator']
+const SOURCE_SUBCOMMAND = 'source'
+const DRY_RUN_FLAG = '--dry-run'
+const RAW_FLAG = '--raw'
+const STREAM_FLAG = '--stream'
+
+const USAGE = `usage: ${CLI_NAME} watch [--stream] [--heartbeat <minutes>] [--board <board.md>] [--coordinator <name>] [<lane> ...]\n       ${CLI_NAME} watch source <name|draft.json|-> --dry-run [--raw]`
+
+const optionValue = (args: readonly string[], option: string): string | null => {
+  const index = args.indexOf(option)
+  if (index === -1) return null
+  const value = args[index + 1]
+  if (value === undefined || value.startsWith('--')) throw new Error(`${option} needs a value\n${USAGE}`)
+  return value
+}
+
+const heartbeatOf = (value: string | null): number => {
+  if (value === null) return DEFAULT_HEARTBEAT_MINUTES
+  const minutes = Number(value)
+  if (!Number.isFinite(minutes) || minutes <= 0)
+    throw new Error(`--heartbeat needs a positive number of minutes\n${USAGE}`)
+  return minutes
+}
+
+/** `source <name|draft.json|-> --dry-run [--raw]` and nothing else; a source is never watched from the command line. */
+const sourceDryRunOf = (args: readonly string[]): SourceDryRun => {
+  const [, target, flag, ...rest] = args
+  const raw = rest.length === 1 && rest[0] === RAW_FLAG
+  if (target === undefined || target.startsWith('--') || flag !== DRY_RUN_FLAG || (rest.length > 0 && !raw))
+    throw new Error(`watch source runs one source once: source <name|draft.json|-> --dry-run [--raw]\n${USAGE}`)
+  return { target, raw }
+}
+
+/** Reads the watcher's command line; throws with the usage on an unknown option or a missing value. */
+export const parseWatchOptions = (args: readonly string[]): WatchOptions => {
+  if (args[0] === SOURCE_SUBCOMMAND)
+    return {
+      lanes: null,
+      heartbeatMinutes: DEFAULT_HEARTBEAT_MINUTES,
+      boardPath: null,
+      coordinator: null,
+      stream: false,
+      sourceDryRun: sourceDryRunOf(args),
+    }
+  const unknown = args.find((arg) => arg.startsWith('--') && !VALUE_OPTIONS.includes(arg) && arg !== STREAM_FLAG)
+  if (unknown) throw new Error(`unknown option ${unknown}\n${USAGE}`)
+  const valueIndexes = new Set(VALUE_OPTIONS.map((option) => args.indexOf(option) + 1).filter((index) => index > 0))
+  const lanes = args.filter((arg, index) => !arg.startsWith('--') && !valueIndexes.has(index))
+  return {
+    lanes: lanes.length > 0 ? lanes : null,
+    heartbeatMinutes: heartbeatOf(optionValue(args, '--heartbeat')),
+    boardPath: optionValue(args, '--board'),
+    coordinator: optionValue(args, '--coordinator'),
+    stream: args.includes(STREAM_FLAG),
+    sourceDryRun: null,
+  }
+}

package/src/watch/plan-badges-read.ts

@@ -0,0 +1,30 @@
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { WATCH_HEALTH, type WatchReading, watchBadgesOf, watchHealthOf } from './plan-badges'
+import { parseWatchState, type WatchState } from './watch-events'
+import { type CommandLineOf, isWatcherRunning, WATCHER_FILES, watcherDirectoryOf } from './watcher-lock'
+
+const readState = (file: string): WatchState | null => {
+  try {
+    return parseWatchState(readFileSync(file, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * What the watcher of the repository at `root` gives the plans view, read from its state file without a GitHub call:
+ * its badges, and its health, so the view can say why there are none. A missing or damaged file shows no badges; the
+ * view goes on without them.
+ */
+export const readWatchReading = (root: string, now: number, lookUp?: CommandLineOf): WatchReading => {
+  const directory = watcherDirectoryOf(root)
+  const state = readState(join(directory, WATCHER_FILES.state))
+  const health = watchHealthOf(
+    state?.savedAt ?? null,
+    isWatcherRunning(join(directory, WATCHER_FILES.lock), lookUp),
+    now,
+  )
+  const badges = state && health.kind === WATCH_HEALTH.live ? watchBadgesOf(state, now) : {}
+  return { badges, health }
+}

package/src/watch/plan-badges.ts

@@ -0,0 +1,66 @@
+import { PULL_REQUEST_STATE } from './pull-requests'
+import type { WatchState } from './watch-events'
+
+/**
+ * What the plans view shows beside a pull request: the checked URL of its preview, the feedback since its last push,
+ * and whether a reviewer requests changes.
+ */
+export type PullRequestBadges = { preview: string | null; feedback: number; changesRequested: boolean }
+
+/** The badges of a pull request the watcher shows nothing for. */
+export const NO_BADGES: PullRequestBadges = { preview: null, feedback: 0, changesRequested: false }
+
+/** Pull request number → its badges; a pull request without an entry has none. */
+export type WatchBadges = Record<string, PullRequestBadges>
+
+/** Whether the watcher's state can be shown: no watcher runs, its state is too old, or it is live. */
+export const WATCH_HEALTH = { live: 'live', off: 'off', stale: 'stale' } as const
+
+/** `minutes` is the whole minutes since the stale state was saved. */
+export type WatchHealth =
+  | { kind: typeof WATCH_HEALTH.live }
+  | { kind: typeof WATCH_HEALTH.off }
+  | { kind: typeof WATCH_HEALTH.stale; minutes: number }
+
+/** The badges the view draws and why there may be none. */
+export type WatchReading = { badges: WatchBadges; health: WatchHealth }
+
+/** Three missed GitHub reads of the watcher (one a minute): an older state is not shown (D96). */
+export const STALE_AFTER_MS = 180_000
+
+const MINUTE_MS = 60_000
+
+const isFresh = (savedAt: number | null, now: number): boolean => savedAt !== null && now - savedAt <= STALE_AFTER_MS
+
+/**
+ * The health of a watcher from whether it runs and when it last saved its state. A watcher that runs but has not
+ * saved after a GitHub read yet is live: it only just started.
+ */
+export const watchHealthOf = (savedAt: number | null, running: boolean, now: number): WatchHealth => {
+  if (!running) return { kind: WATCH_HEALTH.off }
+  if (savedAt === null || isFresh(savedAt, now)) return { kind: WATCH_HEALTH.live }
+  return { kind: WATCH_HEALTH.stale, minutes: Math.floor((now - savedAt) / MINUTE_MS) }
+}
+
+/**
+ * The badges of the open pull requests the watcher follows, from its saved state alone: the preview reported for the
+ * head the watcher knows, the feedback counted since that head, and the requested changes, which a push keeps. A value
+ * of an older head, a preview recorded without its URL, and a state older than `STALE_AFTER_MS` show nothing.
+ */
+export const watchBadgesOf = (state: WatchState, now: number): WatchBadges => {
+  if (!isFresh(state.savedAt, now)) return {}
+  return Object.fromEntries(
+    Object.entries(state.pullRequests).flatMap(([number, { state: prState, headCommit }]) => {
+      if (prState !== PULL_REQUEST_STATE.open) return []
+      const preview = state.previews.pullRequests[number]
+      const feedback = state.feedback.pullRequests[number]
+      const badges = {
+        preview: preview?.reportedHead === headCommit ? (preview.url ?? null) : null,
+        feedback: feedback?.headCommit === headCommit ? feedback.count : 0,
+        changesRequested: feedback?.changesRequested === true,
+      }
+      const shown = badges.preview !== null || badges.feedback > 0 || badges.changesRequested
+      return shown ? [[number, badges]] : []
+    }),
+  )
+}

package/src/watch/plan-views.ts

@@ -0,0 +1,59 @@
+import { TERMINAL_ADAPTER } from '../config/schema'
+import { errorText } from '../plans/error-text'
+import type { PlansSettings } from '../plans/settings'
+import type { LaneSnapshot } from './lane-watch'
+
+export const ENSURE_TRIGGER = { start: 'start', poll: 'poll' } as const
+
+/**
+ * Why the watcher may bring back plans views: its own start, or a poll that found lanes added to the watched set
+ * or watched lanes whose agent appeared (a lane gets its view only once its agent runs).
+ */
+export type EnsureTrigger =
+  | { kind: typeof ENSURE_TRIGGER.start }
+  | { kind: typeof ENSURE_TRIGGER.poll; added: string[]; withNewAgent: string[] }
+
+/** Whether the last failure of `plans --ensure` was already printed; a run that works clears it. */
+export type PlanViews = { failureReported: boolean }
+
+type Ensured = { ok: true; lines: string[] } | { ok: false; error: string }
+
+type Effects = { ensure: () => string[]; log: (line: string) => void }
+
+export const insideHerdr = (adapter: PlansSettings['adapter'], env: Record<string, string | undefined>): boolean =>
+  adapter === TERMINAL_ADAPTER.herdr && env.HERDR_ENV === '1'
+
+/** The watched lanes that had no agent at the last poll and have one now. */
+export const lanesWithNewAgent = (previous: LaneSnapshot, next: LaneSnapshot, lanes: readonly string[]): string[] =>
+  lanes.filter((lane) => !previous[lane] && next[lane])
+
+/** At the start, and after a poll that added a lane or saw a lane's agent appear; a lane that only left needs no view. */
+export const ensureDue = (trigger: EnsureTrigger): boolean =>
+  trigger.kind === ENSURE_TRIGGER.start || trigger.added.length > 0 || trigger.withNewAgent.length > 0
+
+/** The lines one run leaves in the watcher's output: what it brought back, or a failure once per streak. */
+export const ensuredLines = (ensured: Ensured, views: PlanViews): { lines: string[]; views: PlanViews } => {
+  if (ensured.ok)
+    return { lines: ensured.lines.map((line) => `plans --ensure: ${line}`), views: { failureReported: false } }
+  if (views.failureReported) return { lines: [], views }
+  return { lines: [`plans --ensure failed, still watching: ${ensured.error}`], views: { failureReported: true } }
+}
+
+const ensuredOf = (ensure: () => string[]): Ensured => {
+  try {
+    return { ok: true, lines: ensure() }
+  } catch (error) {
+    return { ok: false, error: errorText(error) }
+  }
+}
+
+/**
+ * Brings back missing plans views when `trigger` calls for it, as `jh plans --ensure` does. A failure
+ * never ends the watch; it is printed once until a run works again.
+ */
+export const keepPlanViews = (trigger: EnsureTrigger, views: PlanViews, effects: Effects): PlanViews => {
+  if (!ensureDue(trigger)) return views
+  const { lines, views: next } = ensuredLines(ensuredOf(effects.ensure), views)
+  for (const line of lines) effects.log(line)
+  return next
+}

package/src/watch/preview-read.ts

@@ -0,0 +1,60 @@
+import { errorText } from '../plans/error-text'
+import type { FeedbackTarget } from './feedback'
+import { runGh } from './gh'
+import {
+  deploymentCandidate,
+  type PreviewCandidate,
+  parseDeploymentLines,
+  parseDeploymentStatus,
+  previewDeployments,
+} from './previews'
+
+export type PreviewCandidatesRead = { ok: true; candidates: PreviewCandidate[] } | { ok: false; error: string }
+
+type HeadRead = { ok: true; candidate: PreviewCandidate | null } | { ok: false; error: string }
+
+const DEPLOYMENT_LIMIT = 30
+const DEPLOYMENT_FIELDS = '.[] | {id, environment, production: (.production_environment // false)}'
+/** A deployment without a status yet answers `null`, read as an empty state. */
+const STATUS_FIELDS = '.[0] | {state: (.state // ""), url: (.environment_url // "")}'
+
+/**
+ * The newest preview deployment of the target's head as a candidate once its latest status succeeded with a URL, else
+ * none: a head costs one list and at most one status call per read. An older deployment of the same head that
+ * succeeded is not asked, the newest one stands for the head.
+ */
+const readHeadPreview = async (
+  root: string,
+  target: FeedbackTarget,
+  deployEnvironments: readonly string[],
+): Promise<HeadRead> => {
+  const listPath = `repos/{owner}/{repo}/deployments?sha=${target.headCommit}&per_page=${DEPLOYMENT_LIMIT}`
+  const listed = await runGh(['api', listPath, '--jq', DEPLOYMENT_FIELDS], root)
+  if (!listed.ok) return listed
+  try {
+    const [newest] = previewDeployments(parseDeploymentLines(listed.stdout), deployEnvironments)
+    if (!newest) return { ok: true, candidate: null }
+    const statusPath = `repos/{owner}/{repo}/deployments/${newest.id}/statuses?per_page=1`
+    const status = await runGh(['api', statusPath, '--jq', STATUS_FIELDS], root)
+    if (!status.ok) return status
+    return { ok: true, candidate: deploymentCandidate(target, newest.id, parseDeploymentStatus(status.stdout)) }
+  } catch (error) {
+    return { ok: false, error: errorText(error) }
+  }
+}
+
+/**
+ * The preview deployments of the targets' head commits over REST, one list per target and the status of its newest
+ * preview deployment. The deployments of `deployEnvironments` are the project's own deploys, never a
+ * preview. No target, no call; the first failure is the reason.
+ */
+export const readDeploymentCandidates = async (
+  root: string,
+  targets: readonly FeedbackTarget[],
+  deployEnvironments: readonly string[],
+): Promise<PreviewCandidatesRead> => {
+  const reads = await Promise.all(targets.map((target) => readHeadPreview(root, target, deployEnvironments)))
+  const failed = reads.find((read) => !read.ok)
+  if (failed && !failed.ok) return { ok: false, error: failed.error }
+  return { ok: true, candidates: reads.flatMap((read) => (read.ok && read.candidate ? [read.candidate] : [])) }
+}

package/src/watch/previews.ts

@@ -0,0 +1,234 @@
+import { FEEDBACK_FORM, type FeedbackFilter, type FeedbackItem, type FeedbackTarget, isReadTime } from './feedback'
+import { isRecord } from './json-guards'
+
+export const PREVIEW_EVENT = 'preview'
+
+/** Where a preview is read: a deployment of the head commit, or a comment of a configured author. */
+export const PREVIEW_SOURCE = { deployment: 'deployment', comment: FEEDBACK_FORM.comment } as const
+
+export type PreviewSource = (typeof PREVIEW_SOURCE)[keyof typeof PREVIEW_SOURCE]
+
+/**
+ * A preview as one source shows it, with what changes when it is updated: `key` names the comment or deployment
+ * (`<source>:<id>`), `stamp` its version (a comment's `updated_at`, a deployment's `success`). `url` is null when the
+ * source names no usable link yet; `headCommit` is the head a deployment was read for, null for a comment, which
+ * names no commit.
+ */
+export type PreviewCandidate = {
+  pullRequest: number
+  source: PreviewSource
+  key: string
+  stamp: string
+  url: string | null
+  headCommit: string | null
+}
+
+/**
+ * `reportedHead` is the head a preview was last reported (or, at the first sighting, found) for, `url` that preview's
+ * checked URL (missing in a state written before the plans view showed it); `stamps` maps `key` to `stamp`.
+ */
+export type PreviewRecord = { reportedHead: string | null; stamps: Record<string, string>; url?: string | null }
+
+/** `since` is the epoch milliseconds of the last read, null before the first. */
+export type PreviewState = { since: number | null; pullRequests: Record<string, PreviewRecord> }
+
+export type PreviewRead = { readAt: number; targets: FeedbackTarget[]; candidates: PreviewCandidate[] }
+
+/** Which comments name a preview: their authors' logins, and optionally a pattern whose first group is the URL. */
+export type PreviewSettings = { authors: readonly string[]; urlPattern?: string }
+
+export type PreviewEvent = { kind: typeof PREVIEW_EVENT; lane: string; number: number; url: string; headCommit: string }
+
+/** A deployment of a commit as `gh api --jq` lists it, newest first. */
+export type Deployment = { id: number; environment: string; production: boolean }
+
+/** A deployment's latest status; both empty when it has none. */
+export type DeploymentStatus = { state: string; url: string }
+
+const DEPLOYMENT_SUCCESS = 'success'
+/** A plain https link up to the first space, control character or Markdown and table delimiter. */
+const FIRST_HTTPS_LINK = /https:\/\/[^\s<>()[\]{}"'`|\p{Cc}]+/u
+const TRAILING_PUNCTUATION = /[.,;:!?]+$/
+const URL_MAX_LENGTH = 200
+
+export const emptyPreviewState = (): PreviewState => ({ since: null, pullRequests: {} })
+
+/** The URL a text names, as a checked https URL: the first group of `pattern` (or its match), else the first https link. */
+export const previewUrlOf = (text: string, pattern: string | undefined): string | null => {
+  const match = pattern === undefined ? FIRST_HTTPS_LINK.exec(text) : new RegExp(pattern).exec(text)
+  const raw = (match?.[1] ?? match?.[0] ?? '').replace(TRAILING_PUNCTUATION, '')
+  const linked = FIRST_HTTPS_LINK.exec(raw)?.[0]
+  if (linked === undefined || linked !== raw || raw.length > URL_MAX_LENGTH) return null
+  try {
+    const url = new URL(raw)
+    const withCredentials = url.username !== '' || url.password !== ''
+    return url.protocol === 'https:' && !withCredentials ? url.href : null
+  } catch {
+    return null
+  }
+}
+
+/** GitHub logins ignore case. */
+export const isPreviewAuthor = (author: string, authors: readonly string[]): boolean =>
+  authors.some((name) => name.toLowerCase() === author.toLowerCase())
+
+/** Whose comments are no feedback: the account the watcher runs as, the ignored logins and the preview authors. */
+export const feedbackFilterOf = (
+  own: string,
+  ignore: readonly string[],
+  previews: Pick<PreviewSettings, 'authors'> | undefined,
+): FeedbackFilter => ({ own, ignore: [...ignore, ...(previews?.authors ?? [])] })
+
+/**
+ * Whether the feedback read, which reached back from its own last read, also covers everything since the previews'
+ * last read; a first preview read is a baseline and needs no history.
+ */
+export const feedbackReadCovers = (feedbackSince: number | null, previewsSince: number | null): boolean =>
+  previewsSince === null || (feedbackSince !== null && feedbackSince <= previewsSince)
+
+/** The pull request comments of the configured authors as candidates; a comment's text gives nothing but its URL. */
+export const commentCandidates = (items: readonly FeedbackItem[], settings: PreviewSettings): PreviewCandidate[] =>
+  items
+    .filter((item) => item.form === FEEDBACK_FORM.comment && isPreviewAuthor(item.author, settings.authors))
+    .map((item) => ({
+      pullRequest: item.pullRequest,
+      source: PREVIEW_SOURCE.comment,
+      key: `${PREVIEW_SOURCE.comment}:${item.id}`,
+      stamp: item.updatedAt,
+      url: previewUrlOf(item.body, settings.urlPattern),
+      headCommit: null,
+    }))
+
+const isDeployment = (value: unknown): value is Deployment =>
+  isRecord(value) &&
+  Number.isSafeInteger(value.id) &&
+  (value.id as number) > 0 &&
+  typeof value.environment === 'string' &&
+  typeof value.production === 'boolean'
+
+/** Reads the lines of `gh api --jq '.[] | {id, environment, production}'`; throws on any other shape. */
+export const parseDeploymentLines = (text: string): Deployment[] =>
+  text
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => {
+      const value: unknown = JSON.parse(line)
+      if (!isDeployment(value)) throw new Error('gh api deployments: unexpected answer')
+      return { id: value.id, environment: value.environment, production: value.production }
+    })
+
+/** Reads `{state, url}` of a deployment's latest status; throws on any other shape. */
+export const parseDeploymentStatus = (text: string): DeploymentStatus => {
+  const value: unknown = JSON.parse(text)
+  if (!isRecord(value) || typeof value.state !== 'string' || typeof value.url !== 'string')
+    throw new Error('gh api deployment status: unexpected answer')
+  return { state: value.state, url: value.url }
+}
+
+/** The deployments that may hold a preview: no production one and none of the project's deploy environments. */
+export const previewDeployments = (deployments: readonly Deployment[], deployEnvironments: readonly string[]) =>
+  deployments.filter(({ production, environment }) => !production && !deployEnvironments.includes(environment))
+
+/** A deployment of `target`'s head as a candidate once its latest status succeeded with an https URL. */
+export const deploymentCandidate = (
+  target: FeedbackTarget,
+  id: number,
+  status: DeploymentStatus,
+): PreviewCandidate | null => {
+  const url = status.state === DEPLOYMENT_SUCCESS ? previewUrlOf(status.url, undefined) : null
+  return url === null
+    ? null
+    : {
+        pullRequest: target.number,
+        source: PREVIEW_SOURCE.deployment,
+        key: `${PREVIEW_SOURCE.deployment}:${id}`,
+        stamp: DEPLOYMENT_SUCCESS,
+        url,
+        headCommit: target.headCommit,
+      }
+}
+
+export const previewReadOf = (
+  readAt: number,
+  targets: FeedbackTarget[],
+  candidates: readonly PreviewCandidate[],
+): PreviewRead => {
+  const numbers = new Set(targets.map(({ number }) => number))
+  return { readAt, targets, candidates: candidates.filter(({ pullRequest }) => numbers.has(pullRequest)) }
+}
+
+/** A candidate with a URL that may stand for the target's current head: a comment, or a deployment of that head. */
+const isUsable = (candidate: PreviewCandidate, target: FeedbackTarget): boolean =>
+  candidate.url !== null && (candidate.headCommit === null || candidate.headCommit === target.headCommit)
+
+/** Deployments before comments: a deployment names its commit, a comment does not. */
+const byDeploymentFirst = (a: PreviewCandidate, b: PreviewCandidate): number =>
+  Number(a.source !== PREVIEW_SOURCE.deployment) - Number(b.source !== PREVIEW_SOURCE.deployment)
+
+const candidatesOf = (read: PreviewRead, target: FeedbackTarget): PreviewCandidate[] =>
+  read.candidates.filter(({ pullRequest }) => pullRequest === target.number).sort(byDeploymentFirst)
+
+/** The usable candidate that changed since `record`, when the head has had no preview reported yet. */
+const freshPreview = (record: PreviewRecord, target: FeedbackTarget, candidates: readonly PreviewCandidate[]) =>
+  target.headCommit === record.reportedHead
+    ? undefined
+    : candidates.find((candidate) => record.stamps[candidate.key] !== candidate.stamp && isUsable(candidate, target))
+
+/**
+ * One event per pull request whose head is new since its last reported preview and whose preview source changed
+ * since. A pull request without a record is a baseline: what it shows at its first read fires nothing.
+ */
+export const previewEvents = (previous: PreviewState, read: PreviewRead): PreviewEvent[] =>
+  read.targets.flatMap((target) => {
+    const record = previous.pullRequests[String(target.number)]
+    const fresh = record ? freshPreview(record, target, candidatesOf(read, target)) : undefined
+    return fresh?.url
+      ? [
+          {
+            kind: PREVIEW_EVENT,
+            lane: target.lane,
+            number: target.number,
+            url: fresh.url,
+            headCommit: target.headCommit,
+          },
+        ]
+      : []
+  })
+
+const recordOf = (record: PreviewRecord | undefined, target: FeedbackTarget, candidates: PreviewCandidate[]) => {
+  const stamps = Object.fromEntries(candidates.map(({ key, stamp }) => [key, stamp]))
+  const shown = record
+    ? freshPreview(record, target, candidates)
+    : candidates.find((candidate) => isUsable(candidate, target))
+  const reportedHead = shown ? target.headCommit : (record?.reportedHead ?? null)
+  const url = shown ? shown.url : (record?.url ?? null)
+  return { reportedHead, stamps: { ...record?.stamps, ...stamps }, url }
+}
+
+/** The state after `read`: each target's head marked as reported when it fired (or showed a preview at its first read). */
+export const recordPreviews = (previous: PreviewState, read: PreviewRead): PreviewState => ({
+  since: read.readAt,
+  pullRequests: Object.fromEntries(
+    read.targets.map((target) => [
+      String(target.number),
+      recordOf(previous.pullRequests[String(target.number)], target, candidatesOf(read, target)),
+    ]),
+  ),
+})
+
+/** The targets whose current head has no preview reported yet; only they need their deployments read. */
+export const unreportedTargets = (state: PreviewState, targets: readonly FeedbackTarget[]): FeedbackTarget[] =>
+  targets.filter(({ number, headCommit }) => state.pullRequests[String(number)]?.reportedHead !== headCommit)
+
+const isPreviewRecord = (value: unknown): boolean =>
+  isRecord(value) &&
+  (value.reportedHead === null || typeof value.reportedHead === 'string') &&
+  isRecord(value.stamps) &&
+  Object.values(value.stamps).every((stamp) => typeof stamp === 'string') &&
+  (value.url === undefined || value.url === null || typeof value.url === 'string')
+
+export const isPreviewState = (value: unknown): value is PreviewState =>
+  isRecord(value) &&
+  isReadTime(value.since) &&
+  isRecord(value.pullRequests) &&
+  Object.values(value.pullRequests).every(isPreviewRecord)