jackherd 0.0.1 → 1.0.0

package/src/watch/coordinator-fill.ts

@@ -0,0 +1,76 @@
+import { CONTEXT_LEVEL, type ContextLevel, type ContextReading } from '../context'
+import type { ContextReport } from '../context/report'
+import type { HerdrAgent } from './lane-watch'
+import type { WatchTexts } from './texts'
+
+export type CoordinatorLevel = ContextLevel
+
+/** The coordinator's fill as `jh context <name> --coordinator` reports it. */
+export type CoordinatorReading = ContextReading
+
+/** One read of the coordinator's fill: the reading, or why there is no value. */
+export type CoordinatorRead = { reading: CoordinatorReading; note?: string } | { reason: string }
+
+/** Whether a reading fires the `coordinator` or `lane` event, and the level the state file keeps afterwards. */
+export type LevelStep = { fire: boolean; level: ContextLevel | null }
+
+/** The reason a read gives when the coordinator's log has no value, as `jh context` prints it. */
+const NO_VALUE_REASON = 'null'
+
+const RANK: Record<ContextLevel, number> = { ok: 0, warn: 1, alert: 2 }
+
+export const isContextLevel = (value: unknown): value is ContextLevel =>
+  typeof value === 'string' && (Object.values(CONTEXT_LEVEL) as string[]).includes(value)
+
+/**
+ * Fires when the level rises above the stored one (a missing entry counts as `ok`). A drop is stored
+ * without firing, so a later rise reports again; no value (`current` null) keeps what was stored.
+ */
+export const levelStep = (previous: ContextLevel | null | undefined, current: ContextLevel | null): LevelStep => {
+  if (current === null) return { fire: false, level: previous ?? null }
+  return { fire: RANK[current] > RANK[previous ?? CONTEXT_LEVEL.ok], level: current }
+}
+
+/** The name of the agent in the watcher's own pane; null when the pane is unknown or its agent has no name. */
+export const coordinatorNameOf = (agents: readonly HerdrAgent[], pane: string | undefined): string | null =>
+  (pane && agents.find((agent) => agent.pane_id === pane)?.name) || null
+
+/** How the coordinator is found: an agent of its name, the unnamed agent of the watcher's own pane, or not at all. */
+export type CoordinatorTarget = { kind: 'named' } | { kind: 'unnamedPane'; pane: string } | { kind: 'absent' }
+
+/** Where to read the coordinator `name` from: by name when an agent carries it, else by the watcher's own pane if that agent has no name. */
+export const coordinatorTargetOf = (
+  agents: readonly HerdrAgent[],
+  name: string,
+  pane: string | undefined,
+): CoordinatorTarget => {
+  if (agents.some((agent) => agent.name === name)) return { kind: 'named' }
+  const own = pane ? agents.find((agent) => agent.pane_id === pane && !agent.name) : undefined
+  return own ? { kind: 'unnamedPane', pane: own.pane_id } : { kind: 'absent' }
+}
+
+/** A read with its target's explanation: the rename command for an unnamed pane, `no agent named` instead of `null`. */
+export const explainedRead = (
+  read: CoordinatorRead,
+  target: CoordinatorTarget,
+  name: string,
+  texts: WatchTexts,
+): CoordinatorRead => {
+  if (target.kind === 'named') return read
+  if (target.kind === 'absent') return { reason: texts.noAgentNamed(name) }
+  return 'reading' in read ? { ...read, note: texts.unnamedPane(name) } : { reason: texts.unnamedPane(name) }
+}
+
+/** The share and level of a context report, null without one. */
+export const contextReadingOf = (report: ContextReport | null): ContextReading | null =>
+  report && { share: report.share, level: report.level }
+
+/** The read of a context report with the coordinator's thresholds; no report is no value. */
+export const coordinatorReadOf = (report: ContextReport | null): CoordinatorRead => {
+  const reading = contextReadingOf(report)
+  return reading ? { reading } : { reason: NO_VALUE_REASON }
+}
+
+/** The reading of a read, null when it gave a reason instead. */
+export const readingOf = (read: CoordinatorRead | null): CoordinatorReading | null =>
+  read && 'reading' in read ? read.reading : null

package/src/watch/feedback-read.ts

@@ -0,0 +1,73 @@
+import { errorText } from '../plans/error-text'
+import { FEEDBACK_FORM, type FeedbackItem, type FeedbackTarget, parseFeedbackLines } from './feedback'
+import { type GhAnswer, runGh } from './gh'
+
+export type FeedbackItemsRead = { ok: true; items: FeedbackItem[] } | { ok: false; error: string }
+
+const PAGE = 'per_page=100'
+const AUTHOR = 'author: (.user.login // "ghost")'
+const TEXT = 'body: (.body // "")'
+const NUMBER_FROM = (url: string) => `number: (.${url} | split("/") | last | tonumber)`
+
+/** One object per line, the fields `parseFeedbackLines` reads. */
+const COMMENT_FIELDS = `.[] | {id, ${NUMBER_FROM('issue_url')}, ${AUTHOR}, createdAt: .created_at, updatedAt: .updated_at, ${TEXT}}`
+const INLINE_FIELDS = `.[] | {id, ${NUMBER_FROM('pull_request_url')}, ${AUTHOR}, createdAt: .created_at, updatedAt: .updated_at, path, line: (.line // .original_line), ${TEXT}}`
+/** A pending review has no `submitted_at` yet and is nobody's feedback. */
+const REVIEW_FIELDS = `.[] | select(.submitted_at != null) | {id, ${AUTHOR}, state, createdAt: .submitted_at, updatedAt: .submitted_at, ${TEXT}}`
+
+const api = (root: string, path: string, fields: string): Promise<GhAnswer> =>
+  runGh(['api', '--paginate', `repos/{owner}/{repo}/${path}`, '--jq', fields], root)
+
+/** The repository's pull request comments updated since `since`, the one list a preview author's comment is read from. */
+export const readCommentItems = async (root: string, since: string): Promise<FeedbackItemsRead> => {
+  const answer = await api(root, `issues/comments?since=${since}&${PAGE}`, COMMENT_FIELDS)
+  if (!answer.ok) return answer
+  try {
+    return { ok: true, items: parseFeedbackLines(answer.stdout, FEEDBACK_FORM.comment) }
+  } catch (error) {
+    return { ok: false, error: errorText(error) }
+  }
+}
+
+/**
+ * The feedback on the targets over REST, which kept answering where GitHub's GraphQL list ran into 504s: the
+ * repository's pull request comments and inline comments updated since `since` (new and edited ones alike), and the
+ * reviews of each target, which have no list across the repository. No target, no call.
+ */
+export const readFeedbackItems = async (
+  root: string,
+  targets: readonly FeedbackTarget[],
+  since: string,
+): Promise<FeedbackItemsRead> => {
+  if (targets.length === 0) return { ok: true, items: [] }
+  const [comments, inline, ...reviews] = await Promise.all([
+    readCommentItems(root, since),
+    api(root, `pulls/comments?since=${since}&${PAGE}`, INLINE_FIELDS),
+    ...targets.map(({ number }) => api(root, `pulls/${number}/reviews?${PAGE}`, REVIEW_FIELDS)),
+  ])
+  if (!comments.ok) return comments
+  const failed = [inline, ...reviews].find((answer) => !answer.ok)
+  if (failed && !failed.ok) return { ok: false, error: failed.error }
+  try {
+    const text = (answer: GhAnswer) => (answer.ok ? answer.stdout : '')
+    return {
+      ok: true,
+      items: [
+        ...comments.items,
+        ...parseFeedbackLines(text(inline), FEEDBACK_FORM.inline),
+        ...reviews.flatMap((answer, index) =>
+          parseFeedbackLines(text(answer), FEEDBACK_FORM.review, targets[index].number),
+        ),
+      ],
+    }
+  } catch (error) {
+    return { ok: false, error: errorText(error) }
+  }
+}
+
+/** The login of the account `gh` runs as, whose comments are the lanes' own answers; null when it cannot be read. */
+export const readOwnLogin = async (root: string): Promise<string | null> => {
+  const answer = await runGh(['api', 'user', '--jq', '.login'], root)
+  const login = answer.ok ? answer.stdout.trim() : ''
+  return login === '' ? null : login
+}

package/src/watch/feedback.ts

@@ -0,0 +1,308 @@
+import { isRecord } from './json-guards'
+import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
+
+/** The three forms feedback takes on a pull request: a review, an inline review comment, a pull request comment. */
+export const FEEDBACK_FORM = { review: 'review', inline: 'inline', comment: 'comment' } as const
+
+export type FeedbackForm = (typeof FEEDBACK_FORM)[keyof typeof FEEDBACK_FORM]
+
+export const FEEDBACK_EVENT = 'feedback'
+
+/**
+ * One piece of feedback as the watcher reads it; `state` is a review's (`APPROVED`, …), null for a comment. A review's
+ * `updatedAt` is when it was submitted: GitHub reports no later edit of a review, so an edited review is not new.
+ */
+export type FeedbackItem = {
+  form: FeedbackForm
+  id: number
+  pullRequest: number
+  author: string
+  createdAt: string
+  updatedAt: string
+  state: string | null
+  path: string | null
+  line: number | null
+  body: string
+}
+
+/** An open pull request of a lane whose feedback is read. */
+export type FeedbackTarget = { number: number; lane: string; headCommit: string }
+
+/**
+ * What the watcher remembers of one pull request's feedback: `seen` maps `<form>:<id>` to the `updatedAt` last seen,
+ * `count` the feedback reported since `headCommit`, which a push resets. `changesRequested` is true while a reviewer's
+ * latest decisive review requests changes; a push keeps it, and a state from before it was stored lacks it.
+ */
+export type FeedbackRecord = FeedbackTarget & {
+  seen: Record<string, string>
+  count: number
+  changesRequested?: boolean
+}
+
+/** `since` is the epoch milliseconds of the last read, null before the first. */
+export type FeedbackState = { since: number | null; pullRequests: Record<string, FeedbackRecord> }
+
+/**
+ * One read of the feedback, already cut to the targets and to the authors that count. `changesRequested` names the
+ * targets whose reviews request changes, from every author, ignored ones too: their review blocks the merge all the same.
+ */
+export type FeedbackRead = {
+  readAt: number
+  targets: FeedbackTarget[]
+  items: FeedbackItem[]
+  changesRequested: number[]
+}
+
+/** Whose feedback does not count: `own` is the account the lanes push with, `ignore` the project's list. */
+export type FeedbackFilter = { own: string; ignore: readonly string[] }
+
+/** `place` is `<path>:<line>` for an inline comment, else null; `text` the first line of the body. */
+export type FeedbackEntry = { place: string | null; text: string }
+
+export type FeedbackEvent = {
+  kind: typeof FEEDBACK_EVENT
+  lane: string
+  number: number
+  author: string
+  /** `review <state>`, `inline`, `comment`, or either of the last two with ` edited`. */
+  label: string
+  entries: FeedbackEntry[]
+}
+
+/** How far a read reaches back before the last one: room for a clock that differs from GitHub's. */
+const SINCE_MARGIN_MS = 5 * 60_000
+/** The latest time a JavaScript date holds; a stored `since` past it cannot come from a read. */
+const LATEST_TIME_MS = 8.64e15
+/** GitHub's review states as the REST API spells them. */
+const REVIEW_STATE = {
+  approved: 'APPROVED',
+  changesRequested: 'CHANGES_REQUESTED',
+  commented: 'COMMENTED',
+  dismissed: 'DISMISSED',
+} as const
+/** The review states that decide a reviewer's verdict, as GitHub's own review decision counts them. */
+const DECISIVE_REVIEW_STATES: readonly string[] = [
+  REVIEW_STATE.approved,
+  REVIEW_STATE.changesRequested,
+  REVIEW_STATE.dismissed,
+]
+const EDITED = 'edited'
+const MARKDOWN_HEADING = /^#{1,6}\s/
+
+export const emptyFeedbackState = (): FeedbackState => ({ since: null, pullRequests: {} })
+
+const isNullableString = (value: unknown): boolean => value === null || value === undefined || typeof value === 'string'
+
+const isNullableNumber = (value: unknown): boolean => value === null || value === undefined || typeof value === 'number'
+
+const isFeedbackLine = (value: unknown): value is Record<string, unknown> =>
+  isRecord(value) &&
+  typeof value.id === 'number' &&
+  typeof value.author === 'string' &&
+  typeof value.createdAt === 'string' &&
+  typeof value.updatedAt === 'string' &&
+  typeof value.body === 'string' &&
+  isNullableNumber(value.number) &&
+  isNullableString(value.state) &&
+  isNullableString(value.path) &&
+  isNullableNumber(value.line)
+
+const itemOf = (line: Record<string, unknown>, form: FeedbackForm, pullRequest: number): FeedbackItem => ({
+  form,
+  id: line.id as number,
+  pullRequest,
+  author: line.author as string,
+  createdAt: line.createdAt as string,
+  updatedAt: line.updatedAt as string,
+  state: (line.state as string | undefined) ?? null,
+  path: (line.path as string | undefined) ?? null,
+  line: (line.line as number | undefined) ?? null,
+  body: line.body as string,
+})
+
+/**
+ * Reads the output of `gh api --paginate --jq '.[] | {…}'`, one JSON object per line. A comment names its pull
+ * request in `number`; reviews are read per pull request, which `pullRequest` names. Throws on any other shape.
+ */
+export const parseFeedbackLines = (text: string, form: FeedbackForm, pullRequest?: number): FeedbackItem[] =>
+  text
+    .split('\n')
+    .filter((line) => line.trim() !== '')
+    .map((line) => {
+      const value: unknown = JSON.parse(line)
+      const number = isRecord(value) ? (value.number ?? pullRequest) : undefined
+      if (!isFeedbackLine(value) || typeof number !== 'number') throw new Error(`gh api ${form}: unexpected answer`)
+      return itemOf(value, form, number)
+    })
+
+/** A review without text that only carries inline comments; those are reported on their own. */
+const isReviewShell = (item: FeedbackItem): boolean =>
+  item.form === FEEDBACK_FORM.review && item.state === REVIEW_STATE.commented && item.body.trim() === ''
+
+/** GitHub logins ignore case. */
+const isFiltered = (author: string, filter: FeedbackFilter): boolean =>
+  [filter.own, ...filter.ignore].some((name) => name.toLowerCase() === author.toLowerCase())
+
+/**
+ * True when the latest decisive review of any author requests changes. `items` hold every review of the pull request,
+ * since reviews are read whole on every read.
+ */
+const requestsChanges = (items: readonly FeedbackItem[]): boolean => {
+  const verdicts = new Map<string, string>()
+  const reviews = items.filter((item) => item.form === FEEDBACK_FORM.review)
+  for (const { author, state } of reviews.sort((a, b) => a.updatedAt.localeCompare(b.updatedAt))) {
+    if (DECISIVE_REVIEW_STATES.includes(state ?? '')) verdicts.set(author.toLowerCase(), state ?? '')
+  }
+  return [...verdicts.values()].includes(REVIEW_STATE.changesRequested)
+}
+
+/** The read with only the targets' feedback that counts: no own answers, no ignored authors, no empty review shells. */
+export const feedbackReadOf = (
+  readAt: number,
+  targets: FeedbackTarget[],
+  items: readonly FeedbackItem[],
+  filter: FeedbackFilter,
+): FeedbackRead => {
+  const numbers = new Set(targets.map(({ number }) => number))
+  const counted = items.filter(
+    (item) => numbers.has(item.pullRequest) && !isFiltered(item.author, filter) && !isReviewShell(item),
+  )
+  const changesRequested = targets
+    .map(({ number }) => number)
+    .filter((number) => requestsChanges(items.filter((item) => item.pullRequest === number)))
+  return { readAt, targets, items: counted, changesRequested }
+}
+
+const keyOf = (item: FeedbackItem): string => `${item.form}:${item.id}`
+
+const itemsOf = (read: FeedbackRead, number: number): FeedbackItem[] =>
+  read.items.filter((item) => item.pullRequest === number).sort((a, b) => a.updatedAt.localeCompare(b.updatedAt))
+
+const isNew = (record: FeedbackRecord, item: FeedbackItem): boolean => record.seen[keyOf(item)] !== item.updatedAt
+
+const labelOf = (record: FeedbackRecord, item: FeedbackItem): string => {
+  if (item.form === FEEDBACK_FORM.review) return `review ${(item.state ?? '').toLowerCase().replaceAll('_', ' ')}`
+  const edited = keyOf(item) in record.seen || item.createdAt !== item.updatedAt
+  return edited ? `${item.form} ${EDITED}` : item.form
+}
+
+/** The first line with text that is no Markdown heading; the first heading when the body has nothing else. */
+export const firstLine = (body: string): string => {
+  const lines = body
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line !== '')
+  return lines.find((line) => !MARKDOWN_HEADING.test(line)) ?? lines[0] ?? ''
+}
+
+const entryOf = (item: FeedbackItem): FeedbackEntry => ({
+  place: item.path === null ? null : `${item.path}${item.line === null ? '' : `:${item.line}`}`,
+  text: firstLine(item.body),
+})
+
+/** The new and edited feedback of one pull request, one event per author and label, in the order first seen. */
+const eventsOfRecord = (record: FeedbackRecord, items: readonly FeedbackItem[]): FeedbackEvent[] => {
+  const groups = new Map<string, FeedbackEvent>()
+  for (const item of items.filter((candidate) => isNew(record, candidate))) {
+    const label = labelOf(record, item)
+    const key = `${item.author}\n${label}`
+    const event = groups.get(key) ?? {
+      kind: FEEDBACK_EVENT,
+      lane: record.lane,
+      number: record.number,
+      author: item.author,
+      label,
+      entries: [],
+    }
+    event.entries.push(entryOf(item))
+    groups.set(key, event)
+  }
+  return [...groups.values()]
+}
+
+/**
+ * The feedback that is new or edited since `previous`. A pull request without a record is a baseline: what it
+ * carries at its first read fires nothing, as with checks.
+ */
+export const feedbackEvents = (previous: FeedbackState, read: FeedbackRead): FeedbackEvent[] =>
+  read.targets.flatMap((target) => {
+    const record = previous.pullRequests[String(target.number)]
+    return record ? eventsOfRecord({ ...record, lane: target.lane }, itemsOf(read, target.number)) : []
+  })
+
+const recordOf = (
+  record: FeedbackRecord | undefined,
+  target: FeedbackTarget,
+  items: FeedbackItem[],
+  changesRequested: boolean,
+) => {
+  const reported = record ? items.filter((item) => isNew(record, item)).length : 0
+  const kept = record && record.headCommit === target.headCommit ? record.count : 0
+  const seen = Object.fromEntries(items.map((item) => [keyOf(item), item.updatedAt]))
+  return {
+    ...target,
+    seen: { ...record?.seen, ...seen },
+    count: kept + reported,
+    changesRequested,
+  }
+}
+
+/** The state after `read`: every target's feedback marked seen, its count, and the targets only. */
+export const recordFeedback = (previous: FeedbackState, read: FeedbackRead): FeedbackState => ({
+  since: read.readAt,
+  pullRequests: Object.fromEntries(
+    read.targets.map((target) => [
+      String(target.number),
+      recordOf(
+        previous.pullRequests[String(target.number)],
+        target,
+        itemsOf(read, target.number),
+        read.changesRequested.includes(target.number),
+      ),
+    ]),
+  ),
+})
+
+/** The `since` of the next read as GitHub takes it: the last read minus a margin, now minus it on the first. */
+export const feedbackSince = (state: Pick<FeedbackState, 'since'>, now: number): string =>
+  new Date((state.since ?? now) - SINCE_MARGIN_MS).toISOString()
+
+/**
+ * The pull requests whose feedback is read: the open ones of lane branches when GitHub's list answered, else the
+ * ones the state follows, so a failing list does not stop the feedback.
+ */
+export const feedbackTargets = (
+  pullRequests: readonly WatchedPullRequest[] | null,
+  laneBranches: Readonly<Record<string, string>>,
+  state: FeedbackState,
+): FeedbackTarget[] => {
+  if (!pullRequests)
+    return Object.values(state.pullRequests).map(({ number, lane, headCommit }) => ({ number, lane, headCommit }))
+  return pullRequests.flatMap(({ number, branch, state: lifecycle, headCommit }) => {
+    const lane = Object.keys(laneBranches).find((name) => laneBranches[name] === branch)
+    return lane && lifecycle === PULL_REQUEST_STATE.open ? [{ number, lane, headCommit }] : []
+  })
+}
+
+const isPullRequestNumber = (value: unknown): boolean =>
+  typeof value === 'number' && Number.isSafeInteger(value) && value > 0
+
+/** An epoch time a read can have stamped, or null before the first read. */
+export const isReadTime = (value: unknown): boolean =>
+  value === null || (typeof value === 'number' && Number.isSafeInteger(value) && value >= 0 && value <= LATEST_TIME_MS)
+
+const isFeedbackRecord = (value: unknown): boolean =>
+  isRecord(value) &&
+  isPullRequestNumber(value.number) &&
+  typeof value.lane === 'string' &&
+  typeof value.headCommit === 'string' &&
+  typeof value.count === 'number' &&
+  (value.changesRequested === undefined || typeof value.changesRequested === 'boolean') &&
+  isRecord(value.seen) &&
+  Object.values(value.seen).every((entry) => typeof entry === 'string')
+
+export const isFeedbackState = (value: unknown): value is FeedbackState =>
+  isRecord(value) &&
+  isReadTime(value.since) &&
+  isRecord(value.pullRequests) &&
+  Object.values(value.pullRequests).every(isFeedbackRecord)

package/src/watch/gh.ts

@@ -0,0 +1,22 @@
+import { errorText } from '../plans/error-text'
+
+/** The answer of one `gh` call: its output, or the reason it failed (exit code, stderr, gh not installed). */
+export type GhAnswer = { ok: true; stdout: string } | { ok: false; error: string }
+
+/** Runs `gh` in `cwd`; never rejects, so a caller decides what a failed call means. */
+export const runGh = async (args: string[], cwd: string): Promise<GhAnswer> => {
+  const command = `gh ${args.slice(0, 2).join(' ')}`
+  try {
+    const child = Bun.spawn(['gh', ...args], { cwd, stdout: 'pipe', stderr: 'pipe' })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+    if (exitCode === 0) return { ok: true, stdout }
+    const reason = stderr.trim().replace(/\s*\n\s*/g, ' ') || `exit ${exitCode}`
+    return { ok: false, error: `${command}: ${reason}` }
+  } catch (error) {
+    return { ok: false, error: `${command}: ${errorText(error)}` }
+  }
+}

package/src/watch/github-read.ts

@@ -0,0 +1,175 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { errorText } from '../plans/error-text'
+import { GITHUB_HOST } from '../plans/github'
+import { type GhAnswer, runGh } from './gh'
+import { branchBatches, onBranches, searchableBranches, searchTextOf } from './lane-search'
+import {
+  mergeCheckedPullRequests,
+  OPEN_PULL_REQUEST_FIELDS,
+  parseOpenPullRequests,
+  parseWatchedPullRequests,
+  WATCHED_PULL_REQUEST_FIELDS,
+  type WatchedPullRequest,
+} from './pull-requests'
+import {
+  type DeployConfig,
+  isDeployTarget,
+  parseDeployments,
+  parseWorkflowRuns,
+  runIdOfLogUrl,
+  runListArgs,
+  type WorkflowRun,
+} from './workflow-runs'
+
+export type GithubAnswer = {
+  ok: true
+  pullRequests: WatchedPullRequest[]
+  runs: WorkflowRun[]
+  /** The open pull requests of the signed-in user on a branch no lane has, by number. */
+  own: number[]
+}
+
+/** One read of GitHub: the pull requests and deploy runs, or why `gh` failed. */
+export type GithubRead = GithubAnswer | { ok: false; error: string }
+
+/** A deploy run's environment, or why it could not be read. */
+export type DeployTarget = { target: string } | { reason: string }
+
+const PULL_REQUEST_LIMIT = '100'
+const SEARCH_RESULT_LIMIT = '100'
+const DEPLOYMENT_LIMIT = 30
+
+export const answered = (github: GithubRead | null): GithubAnswer | null => (github?.ok ? github : null)
+
+export const targetText = (deploy: DeployTarget): string =>
+  'target' in deploy ? deploy.target : `unknown (${deploy.reason})`
+
+/** The deploy workflow's runs on the base branch; none, without asking `gh`, when the project reports no deploys. */
+const readRuns = async (root: string, deploy: DeployConfig | undefined, baseBranch: string) => {
+  const args = runListArgs(deploy, baseBranch)
+  return args ? runGh(args, root) : { ok: true as const, stdout: '[]' }
+}
+
+/** One search for the open pull requests of a batch of branches, with their checks. */
+const searchOpen = (root: string, branches: readonly string[]) =>
+  runGh(
+    [
+      'pr',
+      'list',
+      '--state',
+      'open',
+      '--limit',
+      SEARCH_RESULT_LIMIT,
+      '--search',
+      searchTextOf(branches),
+      '--json',
+      OPEN_PULL_REQUEST_FIELDS,
+    ],
+    root,
+  )
+
+/** The open pull requests of the account `gh` runs as, with their checks. */
+const searchOwn = (root: string) =>
+  runGh(
+    [
+      'pr',
+      'list',
+      '--state',
+      'open',
+      '--author',
+      '@me',
+      '--limit',
+      SEARCH_RESULT_LIMIT,
+      '--json',
+      OPEN_PULL_REQUEST_FIELDS,
+    ],
+    root,
+  )
+
+/** The own pull requests on a branch that is no lane's; a lane branch the search could not take counts as a lane's too. */
+const ownWithoutLane = (text: string, laneBranches: readonly string[]) => {
+  const lanes = new Set(laneBranches)
+  return parseOpenPullRequests(text, GITHUB_HOST).filter(({ branch }) => !lanes.has(branch))
+}
+
+/** The open pull requests of the lane branches with their checks: the answers of one search per batch, in parallel. */
+const searchLanes = (root: string, batches: readonly (readonly string[])[]): Promise<GhAnswer[]> =>
+  Promise.all(batches.map((batch) => searchOpen(root, batch)))
+
+/** The open pull requests the searches found, each answer cut to the branches of its own batch. */
+const lanePullRequestsOf = (texts: readonly string[], batches: readonly (readonly string[])[]) =>
+  texts.flatMap((text, index) => onBranches(parseOpenPullRequests(text, GITHUB_HOST), batches[index]))
+
+/** The first failure among the answers, else all their outputs in the same order. */
+const outputsOf = (answers: readonly GhAnswer[]): { outputs: string[] } | { error: string } => {
+  const failed = answers.find((answer): answer is Extract<GhAnswer, { ok: false }> => !answer.ok)
+  return failed ? { error: failed.error } : { outputs: answers.flatMap((answer) => (answer.ok ? [answer.stdout] : [])) }
+}
+
+/**
+ * The repository's pull requests in every state and, with `deploy`, the deploy runs on the base branch. The checks
+ * come from a search for the open pull requests of `laneBranches` (none without a branch, no call either) and from
+ * one search for the open pull requests of the signed-in user, whose ones on a branch without a lane are named in
+ * `own`: one call for 100 pull requests of every state with their `statusCheckRollup` ran into GitHub's GraphQL
+ * timeout (a 504 after ~10 s), and a list of all open pull requests grows with the team's. If several reads fail,
+ * the first in the order light list, own search, lane searches, deploy runs is the one reported.
+ */
+export const readGithub = async (
+  root: string,
+  deploy: DeployConfig | undefined,
+  baseBranch: string,
+  laneBranches: readonly string[],
+): Promise<GithubRead> => {
+  const batches = branchBatches(searchableBranches(laneBranches, baseBranch))
+  const [listed, ownAnswer, searches, runs] = await Promise.all([
+    runGh(['pr', 'list', '--state', 'all', '--limit', PULL_REQUEST_LIMIT, '--json', WATCHED_PULL_REQUEST_FIELDS], root),
+    searchOwn(root),
+    searchLanes(root, batches),
+    readRuns(root, deploy, baseBranch),
+  ])
+  const read = outputsOf([listed, ownAnswer, ...searches, runs])
+  if ('error' in read) return { ok: false, error: read.error }
+  const [listedText, ownText, ...rest] = read.outputs
+  const runsText = rest.pop() ?? '[]'
+  try {
+    const own = ownWithoutLane(ownText, laneBranches)
+    const pullRequests = mergeCheckedPullRequests(parseWatchedPullRequests(listedText, GITHUB_HOST), [
+      ...own,
+      ...lanePullRequestsOf(rest, batches),
+    ])
+    return { ok: true, pullRequests, runs: parseWorkflowRuns(runsText), own: own.map(({ number }) => number) }
+  } catch (error) {
+    return { ok: false, error: errorText(error) }
+  }
+}
+
+/** The target an environment names: one of the configured environments, or the reason it is none. */
+export const targetOfEnvironment = (environment: string, deploy: DeployConfig): DeployTarget =>
+  isDeployTarget(environment, deploy.environments)
+    ? { target: environment }
+    : { reason: `environment ${terminalSafe(environment)}` }
+
+/** The environment of the run's own deployment among those of its commit; the reason when there is none. */
+export const deployTargetOf = async (
+  root: string,
+  deploy: DeployConfig,
+  runId: number,
+  headSha: string,
+): Promise<DeployTarget> => {
+  const deploymentsPath = `repos/{owner}/{repo}/deployments?sha=${headSha}&per_page=${DEPLOYMENT_LIMIT}`
+  const listed = await runGh(['api', deploymentsPath, '--jq', '[.[] | {id, environment}]'], root)
+  if (!listed.ok) return { reason: listed.error }
+  let deployments: ReturnType<typeof parseDeployments>
+  try {
+    deployments = parseDeployments(listed.stdout)
+  } catch (error) {
+    return { reason: errorText(error) }
+  }
+  for (const { id, environment } of deployments) {
+    const statusPath = `repos/{owner}/{repo}/deployments/${id}/statuses?per_page=1`
+    const status = await runGh(['api', statusPath, '--jq', '.[0].log_url // ""'], root)
+    if (!status.ok) return { reason: status.error }
+    if (runIdOfLogUrl(status.stdout.trim()) === runId) return targetOfEnvironment(environment, deploy)
+  }
+  return { reason: 'no deployment of this run' }
+}

package/src/watch/herdr.ts

@@ -0,0 +1,11 @@
+import { runHerdr } from '../terminal/herdr'
+import { agentsOf, type HerdrAgent } from './lane-watch'
+
+const SCREEN_READ_LINES = '50'
+
+/** The agents herdr lists, with the `state_change_seq` the terminal adapter's `LaneAgent` does not carry. */
+export const listAgents = (): HerdrAgent[] => agentsOf(runHerdr(['agent', 'list']))
+
+/** The last lines of a lane agent's screen, as herdr's detection reads them; throws when herdr cannot. */
+export const agentScreen = (lane: string): string =>
+  runHerdr(['agent', 'read', lane, '--source', 'detection', '--lines', SCREEN_READ_LINES])

package/src/watch/json-guards.ts

@@ -0,0 +1,9 @@
+export const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/** The entries of a JSON array when every one passes `isValid`; throws `<source>: unexpected answer` otherwise. */
+export const parseArray = <T>(json: string, isValid: (entry: unknown) => entry is T, source: string): T[] => {
+  const answer: unknown = JSON.parse(json)
+  if (!Array.isArray(answer) || !answer.every(isValid)) throw new Error(`${source}: unexpected answer`)
+  return answer
+}