jackherd 1.9.0 → 1.11.0

package/src/watch/running-subagents.ts

@@ -0,0 +1,43 @@
+import type { RunningSubagent } from '../plans/subagents'
+import { laneDirectoryOf } from '../plans/unlisted-lanes'
+import { type LaneNotes, type PhaseCount, progressNotes } from './heartbeat-progress'
+
+/** The running subagents of each worktree below `worktreeDirectory`, by lane name; one that works elsewhere is left out. */
+export const runningSubagentCountsOf = (
+  running: readonly Pick<RunningSubagent, 'cwd'>[],
+  worktreeDirectory: string,
+): Record<string, number> => {
+  const counts: Record<string, number> = {}
+  for (const { cwd } of running) {
+    const lane = cwd === null ? null : laneDirectoryOf(cwd, worktreeDirectory)
+    if (lane !== null) counts[lane] = (counts[lane] ?? 0) + 1
+  }
+  return counts
+}
+
+/** What a heartbeat says about running subagents: `3 subagents`; null for none. */
+export const subagentsNote = (count: number): string | null =>
+  count <= 0 ? null : `${count} ${count === 1 ? 'subagent' : 'subagents'}`
+
+/**
+ * The heartbeat notes with the running subagents of each working lane appended (`P12 7/12, 3 subagents`); a lane that
+ * has no count note yet gets the subagents alone. Resting lanes and lanes without running subagents keep their note.
+ */
+export const withSubagentNotes = (
+  notes: LaneNotes,
+  working: readonly string[],
+  counts: Readonly<Record<string, number>>,
+): LaneNotes => {
+  const extra = working.flatMap((lane) => {
+    const note = subagentsNote(counts[lane] ?? 0)
+    return note === null ? [] : [[lane, [notes[lane], note].filter(Boolean).join(', ')]]
+  })
+  return { ...notes, ...Object.fromEntries(extra) }
+}
+
+/** The notes of a heartbeat: each working lane's phase count and its running subagents; resting lanes have neither. */
+export const heartbeatNotesOf = (
+  working: readonly string[],
+  phaseCounts: Readonly<Record<string, PhaseCount>>,
+  subagentCounts: Readonly<Record<string, number>>,
+): LaneNotes => withSubagentNotes(progressNotes(working, phaseCounts), working, subagentCounts)

package/src/watch/skill-change.ts

@@ -1,13 +1,40 @@
-import { mkdirSync, readFileSync } from 'node:fs'
+import { readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
 import { errorText } from '../plans/error-text'
-import { changedSections, SKILL_CHANGE, type SkillChange, skillChangeLine } from '../version/skill-diff'
+import {
+  changedSections,
+  orchestrateChangeLines,
+  REFERENCE_CHANGE,
+  type ReferenceChange,
+  type ReferenceDelta,
+  referenceChanges,
+  SKILL_CHANGE,
+  type SkillChange,
+} from '../version/skill-diff'
 import type { StartedKit } from '../version/started-kit'
-import { writePrivate } from './watcher-lock'
+import { ORCHESTRATE_SKILL_NAME } from './reference-paths'
+
+/** The orchestrate skill as the kit ships it: its text and its reference files by name. */
+export type OrchestrateSnapshot = { skill: string; references: Record<string, string> }
+
+/** The change since a snapshot: the skill itself, and each reference that changed, is new or is gone. */
+export type OrchestrateChange = { skill: SkillChange; references: ReferenceChange[] }
+
+type WrittenDiff = { text: string; path: string }
+
+/** A reference name that stays a plain Markdown file name, since it goes into the name of a diff file. */
+const REFERENCE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.md$/
+
+const skillDirectory = (packageRoot: string): string =>
+  join(packageRoot, 'kit', 'workflow', 'skills', ORCHESTRATE_SKILL_NAME)
 
 /** The kit's own text of the orchestrate skill, with its placeholders, inside the package. */
-export const orchestrateSkillPath = (packageRoot: string): string =>
-  join(packageRoot, 'kit', 'workflow', 'skills', 'orchestrate', 'SKILL.md')
+export const orchestrateSkillPath = (packageRoot: string): string => join(skillDirectory(packageRoot), 'SKILL.md')
+
+/** The directory of the skill's reference files in the kit at `packageRoot`. */
+export const orchestrateReferencesPath = (packageRoot: string): string =>
+  join(skillDirectory(packageRoot), 'references')
 
 /** The orchestrate skill's text in the kit at `packageRoot`; null when it cannot be read. */
 export const readOrchestrateSkill = (packageRoot: string): string | null => {
@@ -18,10 +45,45 @@ export const readOrchestrateSkill = (packageRoot: string): string | null => {
   }
 }
 
+/** The skill's reference files by name (every `*.md` file below `references/`); none when the directory is missing. */
+export const readOrchestrateReferences = (packageRoot: string): Record<string, string> => {
+  const directory = orchestrateReferencesPath(packageRoot)
+  try {
+    const names = readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && REFERENCE_FILE.test(entry.name))
+      .map((entry) => entry.name)
+    return Object.fromEntries(names.map((name) => [name, readFileSync(join(directory, name), 'utf8')]))
+  } catch {
+    return {}
+  }
+}
+
+/** The skill and its references in the kit at `packageRoot`; null when the skill cannot be read. */
+export const readOrchestrateSnapshot = (packageRoot: string): OrchestrateSnapshot | null => {
+  const skill = readOrchestrateSkill(packageRoot)
+  return skill === null ? null : { skill, references: readOrchestrateReferences(packageRoot) }
+}
+
+/**
+ * The unified diff (`git diff --no-index`) between `before` and the file at `currentPath`, written to `directory` as
+ * `<name>.diff`; null when git has none to give.
+ */
+const writeDiff = (before: string, currentPath: string, directory: string, name: string): WrittenDiff | null => {
+  ensurePrivateDirectory(directory)
+  const beforePath = join(directory, `${name}.before.md`)
+  writePrivateFile(beforePath, before)
+  const diff = Bun.spawnSync(['git', 'diff', '--no-index', '--unified=3', '--', beforePath, currentPath])
+  const text = diff.stdout.toString()
+  if (diff.exitCode !== 1 || text === '') return null
+  const path = join(directory, `${name}.diff`)
+  writePrivateFile(path, text)
+  return { text, path }
+}
+
 /**
  * The change of the orchestrate skill between `snapshot` and the kit at `packageRoot` now: the unified diff
- * (`git diff --no-index`) written to `directory` and the sections it touches, so the coordinator reads the change
- * instead of the whole skill. Unavailable without a snapshot, a readable skill or a diff.
+ * written to `directory` and the sections it touches, so the coordinator reads the change instead of the whole
+ * skill. Unavailable without a snapshot, a readable skill or a diff.
  */
 export const skillChangeSince = (snapshot: string | null, packageRoot: string, directory: string): SkillChange => {
   if (snapshot === null) return { kind: SKILL_CHANGE.unavailable, reason: 'no snapshot at start' }
@@ -29,33 +91,63 @@ export const skillChangeSince = (snapshot: string | null, packageRoot: string, d
   if (current === null) return { kind: SKILL_CHANGE.unavailable, reason: 'skill not readable' }
   if (current === snapshot) return { kind: SKILL_CHANGE.unchanged }
   try {
-    mkdirSync(directory, { recursive: true, mode: 0o700 })
-    const before = join(directory, 'orchestrate-skill.before.md')
-    writePrivate(before, snapshot)
-    const diff = Bun.spawnSync([
-      'git',
-      'diff',
-      '--no-index',
-      '--unified=3',
-      '--',
-      before,
-      orchestrateSkillPath(packageRoot),
-    ])
-    const text = diff.stdout.toString()
-    if (diff.exitCode !== 1 || text === '')
-      return { kind: SKILL_CHANGE.unavailable, reason: `git diff exit ${diff.exitCode}` }
-    const diffPath = join(directory, 'orchestrate-skill.diff')
-    writePrivate(diffPath, text)
-    return { kind: SKILL_CHANGE.changed, sections: changedSections(current, text), diffPath }
+    const diff = writeDiff(snapshot, orchestrateSkillPath(packageRoot), directory, `${ORCHESTRATE_SKILL_NAME}-skill`)
+    if (diff === null) return { kind: SKILL_CHANGE.unavailable, reason: 'git diff gave none' }
+    return { kind: SKILL_CHANGE.changed, sections: changedSections(current, diff.text), diffPath: diff.path }
   } catch (error) {
     return { kind: SKILL_CHANGE.unavailable, reason: errorText(error) }
   }
 }
 
-/** The line about the orchestrate skill after a kit update, for the kit the watcher started with. */
-export const skillLineFor = (kit: StartedKit | null, snapshot: string | null, directory: string): string =>
-  skillChangeLine(
-    kit
-      ? skillChangeSince(snapshot, kit.packageRoot, directory)
-      : { kind: SKILL_CHANGE.unavailable, reason: 'kit not located' },
-  )
+const referenceChangeOf = (
+  delta: ReferenceDelta,
+  snapshot: OrchestrateSnapshot,
+  packageRoot: string,
+  directory: string,
+): ReferenceChange => {
+  const path = join(orchestrateReferencesPath(packageRoot), delta.name)
+  if (delta.kind === REFERENCE_CHANGE.deleted) return { name: delta.name, kind: REFERENCE_CHANGE.deleted }
+  if (delta.kind === REFERENCE_CHANGE.added) return { name: delta.name, kind: REFERENCE_CHANGE.added, path }
+  try {
+    const diff = writeDiff(
+      snapshot.references[delta.name] ?? '',
+      path,
+      directory,
+      `${ORCHESTRATE_SKILL_NAME}-reference-${delta.name}`,
+    )
+    return { name: delta.name, kind: REFERENCE_CHANGE.changed, diffPath: diff?.path ?? null }
+  } catch {
+    return { name: delta.name, kind: REFERENCE_CHANGE.changed, diffPath: null }
+  }
+}
+
+/**
+ * The change of the skill and of its references since `snapshot`. The references are judged only while the skill
+ * can be read, so a package being replaced does not make every reference look deleted.
+ */
+export const orchestrateChangeSince = (
+  snapshot: OrchestrateSnapshot | null,
+  packageRoot: string,
+  directory: string,
+): OrchestrateChange => {
+  const skill = skillChangeSince(snapshot?.skill ?? null, packageRoot, directory)
+  if (snapshot === null || skill.kind === SKILL_CHANGE.unavailable) return { skill, references: [] }
+  const deltas = referenceChanges(snapshot.references, readOrchestrateReferences(packageRoot))
+  return { skill, references: deltas.map((delta) => referenceChangeOf(delta, snapshot, packageRoot, directory)) }
+}
+
+/**
+ * The lines about the orchestrate skill after a kit update, for the kit the watcher started with: the skill's, then one
+ * per changed, new or deleted reference, joined by line breaks.
+ */
+export const skillLineFor = (
+  kit: StartedKit | null,
+  snapshot: OrchestrateSnapshot | null,
+  directory: string,
+): string => {
+  if (kit === null) {
+    return orchestrateChangeLines({ kind: SKILL_CHANGE.unavailable, reason: 'kit not located' }, []).join('\n')
+  }
+  const { skill, references } = orchestrateChangeSince(snapshot, kit.packageRoot, directory)
+  return orchestrateChangeLines(skill, references).join('\n')
+}

package/src/watch/source-change.ts

@@ -0,0 +1,48 @@
+import { existsSync, type FSWatcher, watch } from 'node:fs'
+import { join } from 'node:path'
+import { isRestartTrigger, RESTART_DEBOUNCE_MS } from '../plans/restart-decision'
+
+/** The changes to a package's `src/` seen so far: when the last one came (null before any), and the watch to close. */
+export type SourceChanges = { lastChangeAt: () => number | null; close: () => void }
+
+/**
+ * Whether the package at `packageRoot` is a checkout's own source rather than an installed copy, which lies under a
+ * `node_modules` directory. Only the source changes under a running process (a pull or a fast-forward of the
+ * checkout); an installed copy changes by a reinstall, which its version shows.
+ */
+export const runsFromSource = (packageRoot: string): boolean => !packageRoot.split(/[\\/]/).includes('node_modules')
+
+/** Whether a change seen at `lastChangeAt` is over: no further change for the window in which the herd collapses a burst into one restart. */
+export const sourceChangeSettled = (lastChangeAt: number | null, now: number): boolean =>
+  lastChangeAt !== null && now - lastChangeAt >= RESTART_DEBOUNCE_MS
+
+const NO_CHANGES: SourceChanges = { lastChangeAt: () => null, close: () => {} }
+
+/** The watch of `directory`, closed on a later error (`EMFILE` while dev servers run), which would else end the process. */
+const watcherOf = (directory: string, onChange: () => void): FSWatcher | null => {
+  try {
+    const watcher = watch(directory, { recursive: true }, (_event, name) => {
+      if (name && isRestartTrigger(name.toString())) onChange()
+    })
+    watcher.on('error', () => watcher.close())
+    return watcher
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Follows the source files below `<packageRoot>/src` with the trigger the herd restarts on (`isRestartTrigger`: a
+ * `.ts` file, tests and declarations left out), stamping each change with `clock`. A package without `src/`, or one
+ * the platform cannot watch, is followed for nothing.
+ */
+export const watchSourceChanges = (packageRoot: string, clock: () => number = Date.now): SourceChanges => {
+  const directory = join(packageRoot, 'src')
+  if (!existsSync(directory)) return NO_CHANGES
+  let lastChangeAt: number | null = null
+  const watcher = watcherOf(directory, () => {
+    lastChangeAt = clock()
+  })
+  if (!watcher) return NO_CHANGES
+  return { lastChangeAt: () => lastChangeAt, close: () => watcher.close() }
+}

package/src/watch/source-entries.ts

@@ -0,0 +1,55 @@
+import {
+  lineText,
+  reportsItem,
+  type SeenEntry,
+  type SourceEntry,
+  type SourceItem,
+  type SourceRecord,
+  type SourceRun,
+  type SourceSettings,
+  seenMapOf,
+  storedValue,
+} from './sources'
+
+/** The most entries a source keeps for the herd. */
+export const ENTRY_LIMIT = 20
+
+const shownAt = ({ changedAt, seenAt }: SourceEntry): number => changedAt ?? seenAt
+
+const entryOf = (
+  item: SourceItem,
+  known: SourceEntry | undefined,
+  seen: ReadonlyMap<string, SeenEntry> | null,
+  settings: SourceSettings,
+  now: number,
+): SourceEntry => ({
+  id: item.id,
+  title: storedValue(lineText(item.title)),
+  url: item.url,
+  count: item.count,
+  seenAt: known?.seenAt ?? now,
+  changedAt: seen && reportsItem(seen, item, settings) ? now : (known?.changedAt ?? null),
+})
+
+/**
+ * The entries a source that is no ticket keeps after `run`: those of a successful run, at most `ENTRY_LIMIT`, newest
+ * change first, each with the time the watcher first saw it and the time it last reported a change of it (none for the
+ * baseline run). A failed run keeps what the source had; a ticket source keeps none (its tickets are the list).
+ */
+export const entriesAfter = (
+  previous: SourceRecord | undefined,
+  run: SourceRun | undefined,
+  settings: SourceSettings | undefined,
+  now: number,
+): SourceEntry[] | undefined => {
+  if (!settings || settings.ticket) return undefined
+  if (!run?.result.ok) return previous?.entries
+  const seen = seenMapOf(previous)
+  const known = new Map((previous?.entries ?? []).map((entry) => [entry.id, entry]))
+  return run.result.items
+    .map((item) => entryOf(item, known.get(item.id), seen, settings, now))
+    .map((entry, index) => ({ entry, index }))
+    .sort((a, b) => shownAt(b.entry) - shownAt(a.entry) || a.index - b.index)
+    .map(({ entry }) => entry)
+    .slice(0, ENTRY_LIMIT)
+}

package/src/watch/source-fields.ts

@@ -7,6 +7,7 @@ export const SOURCE_FIELD = {
   body: 'body',
   author: 'author',
   status: 'status',
+  count: 'count',
 } as const
 
 /** The fields a reader sees of an entry: a change of one of them is a change of the entry (`contentFingerprint`). */

package/src/watch/source-statuses.ts

@@ -0,0 +1,60 @@
+import { isFresh, NEW_FOR_MS } from './plan-badges'
+import { previewUrlOf } from './previews'
+import { lineText, type SourceEntry, type SourceRecord } from './sources'
+import type { WatchState } from './watch-events'
+
+/** The newest entry a source reported, as the herd draws it; `isNew` while it is younger than `NEW_FOR_MS`. */
+export type LatestStatus = { title: string; url: string | null; isNew: boolean }
+
+/** An entry as the herd lists it under its source: `at` is when it last changed, else when the watcher first saw it; `isNew` only for a reported change younger than `NEW_FOR_MS`. */
+export type EntryStatus = {
+  id: string
+  title: string
+  url: string | null
+  count: string | null
+  at: number
+  isNew: boolean
+}
+
+/** What the herd shows of a source: when it ran last, since when it fails, its newest report and its entries, newest change first. */
+export type SourceStatus = {
+  name: string
+  ranAt: number | null
+  failingSince: number | null
+  latest: LatestStatus | null
+  entries: EntryStatus[]
+}
+
+const entryStatusOf = (entry: SourceEntry, now: number): EntryStatus => ({
+  id: entry.id,
+  title: lineText(entry.title),
+  url: entry.url === null ? null : previewUrlOf(entry.url, undefined),
+  count: entry.count,
+  at: entry.changedAt ?? entry.seenAt,
+  isNew: entry.changedAt !== null && now - entry.changedAt < NEW_FOR_MS,
+})
+
+const latestOf = (latest: SourceRecord['latest'], now: number): LatestStatus | null =>
+  latest
+    ? {
+        title: lineText(latest.title),
+        url: latest.url === null ? null : previewUrlOf(latest.url, undefined),
+        isNew: now - latest.at < NEW_FOR_MS,
+      }
+    : null
+
+const statusOf = (name: string, record: SourceRecord | undefined, now: number): SourceStatus => ({
+  name,
+  ranAt: record?.ranAt ?? null,
+  failingSince: record?.failingSince ?? null,
+  latest: latestOf(record?.latest, now),
+  entries: (record?.entries ?? []).map((entry) => entryStatusOf(entry, now)),
+})
+
+/**
+ * The status of each source in `names`, in their order, from the watcher's saved state alone. A name the watcher has
+ * not run yet shows without a run; a title is drawn as one line and the URL is checked again, as for the tickets, and a
+ * state older than `STALE_AFTER_MS` shows none.
+ */
+export const sourceStatusesOf = (state: WatchState, names: readonly string[], now: number): SourceStatus[] =>
+  isFresh(state.savedAt, now) ? names.map((name) => statusOf(name, state.sources[name], now)) : []

package/src/watch/source-tickets.ts

@@ -1,4 +1,7 @@
+import { entriesAfter } from './source-entries'
 import {
+  type LatestReport,
+  lineText,
   recordSources,
   reportsItem,
   SEEN_LIMIT,
@@ -9,6 +12,7 @@ import {
   type SourceSettings,
   type SourceState,
   seenMapOf,
+  storedValue,
   type TicketRecord,
 } from './sources'
 
@@ -39,6 +43,19 @@ const ticketsAfter = (
   )
 }
 
+/** The newest entry this run reported (the last of them), else what was recorded; failures and baselines record nothing. */
+const latestAfter = (
+  previous: SourceRecord | undefined,
+  run: SourceRun | undefined,
+  settings: SourceSettings | undefined,
+  now: number,
+): LatestReport | undefined => {
+  const seen = seenMapOf(previous)
+  if (!seen || !settings || !run?.result.ok) return previous?.latest
+  const reported = run.result.items.filter((item) => reportsItem(seen, item, settings)).at(-1)
+  return reported ? { title: storedValue(lineText(reported.title)), url: reported.url, at: now } : previous?.latest
+}
+
 const withoutTickets = ({ tickets: _tickets, ...record }: SourceRecord): SourceRecord => record
 
 /** The tickets a source keeps: those of a successful run, else the ones it had; none for a source not marked. */
@@ -71,7 +88,10 @@ const recordTickets = (
       const source = settings.find((candidate) => candidate.name === name)
       const run = runs.find((candidate) => candidate.name === name)
       const tickets = ticketsOf(previous[name], run, source, now)
-      return [name, tickets ? { ...withoutTickets(record), tickets } : withoutTickets(record)]
+      const latest = latestAfter(previous[name], run, source, now)
+      const entries = entriesAfter(previous[name], run, source, now)
+      const base = { ...withoutTickets(record), ...(latest ? { latest } : {}), ...(entries ? { entries } : {}) }
+      return [name, tickets ? { ...base, tickets } : base]
     }),
   )
 

package/src/watch/sources.ts

@@ -67,6 +67,8 @@ export type SourceItem = {
   author: string | null
   /** `map.status` as the state keeps it (`storedValue`), null when not mapped or empty. */
   status: string | null
+  /** `map.count` as one line (how often an error happened); null when not mapped or empty. */
+  count: string | null
   fingerprint: string
   /** The `reportOn` fields as the state keeps them (`storedValue`); empty without `reportOn`. */
   values: Record<string, string>
@@ -86,6 +88,22 @@ export type SeenEntry = [string, string] | [string, string, Record<string, strin
  */
 export type TicketRecord = { url: string | null; status: string | null; changedAt: number | null }
 
+/** The newest entry a source reported: its title as one line, its checked URL or null, and the epoch milliseconds of the run that reported it. */
+export type LatestReport = { title: string; url: string | null; at: number }
+
+/**
+ * An entry of a source as the herd lists it: its title as one line, its checked URL, its count, when the watcher first
+ * saw it (`seenAt`) and when it last reported a change of it (`changedAt`, null while only the baseline knows it).
+ */
+export type SourceEntry = {
+  id: string
+  title: string
+  url: string | null
+  count: string | null
+  seenAt: number
+  changedAt: number | null
+}
+
 /**
  * What the watcher keeps per source: `seen` holds a `SeenEntry` per id, the entries seen most recently last, or null
  * before the first successful run (which is a baseline); `failingSince` is the epoch milliseconds of the first failed
@@ -94,8 +112,14 @@ export type TicketRecord = { url: string | null; status: string | null; changedA
 export type SourceRecord = {
   seen: SeenEntry[] | null
   failingSince: number | null
+  /** When its last run started, failed or not (`isSourceDue`); absent in a state written before it was kept: never. */
+  ranAt?: number
   /** Of a ticket source only: the entries of its last successful run by id. */
   tickets?: Record<string, TicketRecord>
+  /** The newest entry the source reported, kept for the herd's row of the source; absent until one was reported. */
+  latest?: LatestReport
+  /** Of a source that is no ticket: the entries of its last successful run for the herd's expanded row, newest change first. */
+  entries?: SourceEntry[]
 }
 
 export type SourceState = Record<string, SourceRecord>
@@ -143,7 +167,7 @@ const scalarText = (value: unknown): string | null => {
 export const textAt = (entry: unknown, path: SourcePath | undefined): string | null =>
   path === undefined ? null : scalarText(selectPath(entry, path))
 
-type MappedFields = Omit<SourceItem, 'fingerprint' | 'values' | 'status'>
+type MappedFields = Omit<SourceItem, 'fingerprint' | 'values' | 'status' | 'count'>
 
 const hashOf = (text: string, length: number): string =>
   createHash('sha256').update(text).digest('hex').slice(0, length)
@@ -189,6 +213,9 @@ const valuesOf = (
 const statusOf = (entry: unknown, map: SourceMap): string | null =>
   storedValue(lineText(textAt(entry, map.status) ?? '')) || null
 
+const countOf = (entry: unknown, map: SourceMap): string | null =>
+  storedValue(lineText(textAt(entry, map.count) ?? '')) || null
+
 /** One entry after `map`, or null when its id, or a mapped updatedAt, is missing or no text; unmapped it is `''`. */
 const sourceItemOf = (entry: unknown, settings: Pick<SourceSettings, 'map' | 'reportOn'>): SourceItem | null => {
   const { map } = settings
@@ -207,6 +234,7 @@ const sourceItemOf = (entry: unknown, settings: Pick<SourceSettings, 'map' | 're
   return {
     ...fields,
     status: statusOf(entry, map),
+    count: countOf(entry, map),
     fingerprint: contentFingerprint(fields, map),
     values: valuesOf(entry, fields, settings),
   }
@@ -248,7 +276,7 @@ export const parseSourceOutput = (
   return { ok: true, items: uniqueById(items as SourceItem[]) }
 }
 
-/** Whether a source last started at `lastRunAt` (undefined: never in this process) is due again at `now`. */
+/** Whether a source last started at `lastRunAt` (`SourceRecord.ranAt`; undefined: never) is due again at `now`. */
 export const isSourceDue = (lastRunAt: number | undefined, everyMinutes: number, now: number): boolean =>
   lastRunAt === undefined || now - lastRunAt >= everyMinutes * MINUTE_MS
 
@@ -342,8 +370,8 @@ const seenAfter = (seen: readonly SeenEntry[], items: readonly SourceItem[]): Se
 
 const recordOf = (record: SourceRecord | undefined, result: SourceResult, now: number): SourceRecord =>
   result.ok
-    ? { seen: seenAfter(record?.seen ?? [], result.items), failingSince: null }
-    : { seen: record?.seen ?? null, failingSince: record?.failingSince ?? now }
+    ? { seen: seenAfter(record?.seen ?? [], result.items), failingSince: null, ranAt: now }
+    : { seen: record?.seen ?? null, failingSince: record?.failingSince ?? now, ranAt: now }
 
 /**
  * The state after `runs` for the sources configured as `names`: a run records its outcome, a source without a run keeps
@@ -381,10 +409,25 @@ const isTicketRecord = (value: unknown): boolean =>
   isTextOrNull(value.status) &&
   (value.changedAt === null || typeof value.changedAt === 'number')
 
+const isLatestReport = (value: unknown): boolean =>
+  isRecord(value) && typeof value.title === 'string' && isTextOrNull(value.url) && typeof value.at === 'number'
+
+const isSourceEntry = (value: unknown): boolean =>
+  isRecord(value) &&
+  typeof value.id === 'string' &&
+  typeof value.title === 'string' &&
+  isTextOrNull(value.url) &&
+  isTextOrNull(value.count) &&
+  typeof value.seenAt === 'number' &&
+  (value.changedAt === null || typeof value.changedAt === 'number')
+
 const isSourceRecord = (value: unknown): boolean =>
   isRecord(value) &&
+  (value.entries === undefined || (Array.isArray(value.entries) && value.entries.every(isSourceEntry))) &&
+  (value.latest === undefined || isLatestReport(value.latest)) &&
   (value.seen === null || (Array.isArray(value.seen) && value.seen.every(isSeenEntry))) &&
   (value.failingSince === null || typeof value.failingSince === 'number') &&
+  (value.ranAt === undefined || typeof value.ranAt === 'number') &&
   (value.tickets === undefined || (isRecord(value.tickets) && Object.values(value.tickets).every(isTicketRecord)))
 
 export const isSourceState = (value: unknown): value is SourceState =>

package/src/watch/stream-output.ts

@@ -17,7 +17,8 @@ const laneState = (lane: string, current: LaneSnapshot, notes: LaneNotes, rests:
 
 /**
  * The heartbeat of a stream, as one line, since every line of a stream reaches the coordinator as a
- * message of its own: `=== heartbeat <time> · <lane> <status> · …`.
+ * message of its own: `=== heartbeat <time> · <lane> <status> · …`. `standing` are the lines that stay until
+ * their cause is gone (what waits on the user, the main checkout behind its base), each one entry at the end.
  */
 export const streamHeartbeatLine = (
   time: string,
@@ -25,12 +26,12 @@ export const streamHeartbeatLine = (
   current: LaneSnapshot,
   notes: LaneNotes,
   rests: LaneNotes = {},
-  waiting: string | null = null,
+  standing: readonly string[] = [],
 ): string => {
   const states = lanes.map((lane) => laneState(lane, current, notes, rests))
   return [
     `=== ${WATCH_EVENT.heartbeat} ${terminalSafe(time)}`,
     ...(states.length > 0 ? states : ['no lanes']),
-    ...(waiting === null ? [] : [terminalSafe(waiting).replaceAll(SEPARATOR, ' / ')]),
+    ...standing.map((line) => terminalSafe(line).replaceAll(SEPARATOR, ' / ')),
   ].join(SEPARATOR)
 }