jackherd 1.11.1 → 1.12.0

package/src/plans/your-turn.ts

@@ -0,0 +1,226 @@
+import { DAY_MS, twoDigits } from '../plan-format/clock'
+import type { WaitingItem } from '../plan-format/waiting'
+import type { PlanLanguage } from '../vocabulary'
+import { parseAppointmentTime } from '../watch/appointments'
+import { type AppointmentRow, appointmentRows, TIME_OPEN } from './appointment-rows'
+import { calendarDaysBetween } from './calendar-days'
+import { plain } from './layout-phase'
+import { nextLines } from './next-rows'
+import { shortTitle } from './task-name'
+import { waitingKey } from './waiting-click'
+
+/** `now` for what waits on the user's answer, `planned` for what has (or still needs) a time of its own. */
+export const TURN_KIND = { now: 'now', planned: 'planned' } as const
+
+export type TurnKind = (typeof TURN_KIND)[keyof typeof TURN_KIND]
+
+/**
+ * One topic of "Your turn": its text with the source's prefix, the time column (`since <day>`, `<weekday> <day> <time>`,
+ * `time open`), `at` the time behind it in epoch milliseconds (the since of a now row, the appointment of a planned
+ * one; null where none can be read) and the lanes it frees. `waiting` and `appointment` are the rows it was made of:
+ * they carry what its buttons close, ask and open.
+ */
+export type TurnRow = {
+  key: string
+  kind: TurnKind
+  text: string
+  time: string
+  at: number | null
+  unblocks: readonly string[]
+  waiting?: WaitingItem
+  appointment?: AppointmentRow
+}
+
+/** "Your turn": the now rows, what blocks a lane first, then the oldest; the planned rows, those without a time first. */
+export type YourTurn = { now: TurnRow[]; planned: TurnRow[] }
+
+/** "Your turn" as the herd draws it, with the clock (epoch milliseconds) its ages and the week ahead are counted from. */
+export type YourTurnBlock = { turn: YourTurn; now: number }
+
+/** Where "Your turn" is read from: the open board rows, questions and files, the open appointments, the next lines. */
+export type TurnSources = {
+  waiting: readonly WaitingItem[]
+  appointments: readonly AppointmentRow[]
+  next: readonly string[]
+  now: Date
+}
+
+/**
+ * What the open block shows: the now rows within the cap, the line for the rest and the rest below it once opened,
+ * the planned rows, how many later and those below their line once opened, and which of the two lines is open.
+ */
+export type TurnPage = {
+  now: TurnRow[]
+  nowMore: { count: number; older: number } | null
+  nowRest: TurnRow[]
+  planned: TurnRow[]
+  later: number
+  plannedRest: TurnRow[]
+  opened: TurnOpened
+}
+
+/** The parts of the head's balance; the head paints what blocks a lane in the tone of what waits. */
+export type TurnBalance = { blocking: string | null; oldest: string | null }
+
+/** Whether the more line and the later line are open and show every row. */
+export type TurnOpened = { allNow: boolean; allPlanned: boolean }
+
+/** How many now rows show before `▸ <n> more`. */
+export const SHOWN_NOW_ROWS = 5
+/** How many planned rows show before `▸ <n> later`, and how many days ahead they may lie. */
+export const SHOWN_PLANNED_ROWS = 3
+const PLANNED_DAYS = 7
+/** From how many calendar days back a now row counts as old in the more line. */
+export const OLD_DAYS = 7
+const SINCE = 'since'
+const START_OF_DAY = '00:00'
+
+const topicOf = (text: string): string => shortTitle(plain(text)).trim().toLowerCase()
+
+const sameTopic = (left: string, right: string): boolean =>
+  topicOf(left) === topicOf(right) || left.trim().toLowerCase() === right.trim().toLowerCase()
+
+/** The since of a board row, a question or a file as a time; a day without a time of day counts from its start. */
+const sinceTime = (since: string, now: Date): number | null =>
+  (parseAppointmentTime(since, now) ?? parseAppointmentTime(`${since} ${START_OF_DAY}`, now))?.getTime() ?? null
+
+/** `since 18.10.`: the day of the since; the since as written when it names no day. */
+const sinceText = (since: string, at: number | null): string => {
+  if (at === null) return `${SINCE} ${since}`.trim()
+  const day = new Date(at)
+  return `${SINCE} ${twoDigits(day.getDate())}.${twoDigits(day.getMonth() + 1)}.`
+}
+
+const withPrefix = (prefix: string | undefined, text: string): string => (prefix ? `${prefix}: ${text}` : text)
+
+const nowRowOf = (item: WaitingItem, now: Date): TurnRow => {
+  const at = sinceTime(item.since, now)
+  return {
+    key: waitingKey(item),
+    kind: TURN_KIND.now,
+    text: withPrefix(item.prefix, plain(item.item)),
+    time: sinceText(item.since, at),
+    at,
+    unblocks: item.unblocks ?? [],
+    waiting: item,
+  }
+}
+
+const plannedRowOf = (row: AppointmentRow): TurnRow => ({
+  key: `appointment>${row.key}`,
+  kind: TURN_KIND.planned,
+  text: row.action,
+  time: row.label,
+  at: row.at,
+  unblocks: [],
+  appointment: row,
+})
+
+const nextRowOf = (text: string): TurnRow => ({
+  key: `next>${text}`,
+  kind: TURN_KIND.planned,
+  text,
+  time: TIME_OPEN,
+  at: null,
+  unblocks: [],
+})
+
+const topicText = (row: TurnRow): string => row.waiting?.item ?? row.appointment?.action ?? row.text
+
+const unionOf = (left: readonly string[], right: readonly string[]): string[] => [...new Set([...left, ...right])]
+
+/** The earlier of two now rows of one topic keeps its place; it takes the other's lanes. */
+const mergedNow = (kept: TurnRow, other: TurnRow): TurnRow => ({
+  ...kept,
+  unblocks: unionOf(kept.unblocks, other.unblocks),
+})
+
+/** A now row of the appointment's topic becomes the planned row, and keeps what it frees and the board row it was. */
+const plannedFrom = (row: TurnRow | undefined, appointment: AppointmentRow): TurnRow => {
+  const planned = plannedRowOf(appointment)
+  return row ? { ...planned, unblocks: row.unblocks, ...(row.waiting ? { waiting: row.waiting } : {}) } : planned
+}
+
+const byBlockingThenAge = (left: TurnRow, right: TurnRow): number =>
+  Number(right.unblocks.length > 0) - Number(left.unblocks.length > 0) ||
+  (left.at ?? Number.POSITIVE_INFINITY) - (right.at ?? Number.POSITIVE_INFINITY)
+
+const byTime = (left: TurnRow, right: TurnRow): number =>
+  (left.at ?? Number.NEGATIVE_INFINITY) - (right.at ?? Number.NEGATIVE_INFINITY)
+
+const withNowRow = (rows: TurnRow[], row: TurnRow): TurnRow[] => {
+  const index = rows.findIndex((known) => sameTopic(topicText(known), topicText(row)))
+  return index === -1 ? [...rows, row] : rows.map((known, at) => (at === index ? mergedNow(known, row) : known))
+}
+
+/**
+ * "Your turn" from its sources, one row per topic: a topic is the short title (the text up to its first `: `), in any
+ * case; nothing else is guessed. Board rows, questions and files are now rows, one topic merged into the first; an
+ * appointment takes the now row of its topic along and is planned; a next line of a topic already shown is left out,
+ * one of a new topic is planned without a time.
+ */
+export const yourTurnOf = ({ waiting, appointments, next, now }: TurnSources): YourTurn => {
+  let nowRows = waiting.map((item) => nowRowOf(item, now)).reduce<TurnRow[]>(withNowRow, [])
+  const planned: TurnRow[] = []
+  for (const appointment of appointments) {
+    if (planned.some((row) => sameTopic(topicText(row), appointment.action))) continue
+    const taken = nowRows.find((row) => sameTopic(topicText(row), appointment.action))
+    nowRows = nowRows.filter((row) => row !== taken)
+    planned.push(plannedFrom(taken, appointment))
+  }
+  const shown = [...nowRows, ...planned]
+  const nextRows = next.filter((text) => !shown.some((row) => sameTopic(topicText(row), text))).map(nextRowOf)
+  return { now: [...nowRows].sort(byBlockingThenAge), planned: [...planned, ...nextRows].sort(byTime) }
+}
+
+/** "Your turn" of a board: `waiting` (its open rows, the questions and the files), its open appointments and next lines. */
+export const yourTurnOfBoard = (
+  board: string,
+  language: PlanLanguage,
+  waiting: readonly WaitingItem[],
+  now: number,
+): YourTurnBlock => {
+  const clock = new Date(now)
+  const appointments = appointmentRows(board, language, clock)
+  return { turn: yourTurnOf({ waiting, appointments, next: nextLines(board, language), now: clock }), now }
+}
+
+const isOld = (row: TurnRow, now: Date): boolean =>
+  row.at !== null && calendarDaysBetween(new Date(row.at), now) > OLD_DAYS
+
+/** Within the next seven days, an overdue appointment and one without a time included: those are due now. */
+const isWithinWeek = (row: TurnRow, now: Date): boolean =>
+  row.at === null || row.at - now.getTime() <= PLANNED_DAYS * DAY_MS
+
+/**
+ * The open block's rows: at most five now rows and the rest as one line with how many of them are older than seven
+ * calendar days; the planned rows of the next seven days (and those without a time), at most three, the rest counted
+ * as later. An opened more line or later line shows the rest of its rows below itself (`nowRest`, `plannedRest`),
+ * never above; the counts stay.
+ */
+export const turnPage = ({ now: nowRows, planned }: YourTurn, opened: TurnOpened, now: Date): TurnPage => {
+  const hidden = nowRows.slice(SHOWN_NOW_ROWS)
+  const soon = planned.filter((row) => isWithinWeek(row, now)).slice(0, SHOWN_PLANNED_ROWS)
+  return {
+    now: nowRows.slice(0, SHOWN_NOW_ROWS),
+    nowMore: hidden.length > 0 ? { count: hidden.length, older: hidden.filter((row) => isOld(row, now)).length } : null,
+    nowRest: opened.allNow ? hidden : [],
+    planned: soon,
+    later: planned.length - soon.length,
+    plannedRest: opened.allPlanned ? planned.filter((row) => !soon.includes(row)) : [],
+    opened,
+  }
+}
+
+/**
+ * The balance in the head, shown folded too (`4 block lanes · oldest 12 d`): how many now rows free a lane and the
+ * age of the oldest now row in calendar days; each part null when it has nothing to say.
+ */
+export const turnBalance = ({ now: nowRows }: YourTurn, now: Date): TurnBalance => {
+  const blocking = nowRows.filter(({ unblocks }) => unblocks.length > 0).length
+  const times = nowRows.flatMap(({ at }) => (at === null ? [] : [at]))
+  return {
+    blocking: blocking === 0 ? null : blocking === 1 ? '1 blocks lanes' : `${blocking} block lanes`,
+    oldest: times.length === 0 ? null : `oldest ${calendarDaysBetween(new Date(Math.min(...times)), now)} d`,
+  }
+}

package/src/terminal/herdr.ts

@@ -85,6 +85,12 @@ export const renameArguments = (pane: string, label: string | null): string[] =>
 /** Runs the herdr CLI with these arguments and returns its stdout; throws when it fails. */
 export type HerdrRunner = (args: string[]) => string
 
+/** As `HerdrRunner`, without holding the event loop while herdr answers. */
+export type HerdrAsyncRunner = (args: string[]) => Promise<string>
+
+const failureOf = (args: string[], stderr: string, exitCode: number | null): Error =>
+  new Error(`herdr ${args.slice(0, 2).join(' ')}: ${stderr.trim() || `exit ${exitCode}`}`)
+
 /**
  * Runs the herdr binary of `herdrBinary` (`HERDR_BIN_PATH`, else `herdr` from the PATH) and returns its stdout;
  * throws with herdr's own error text when it fails or is not running.
@@ -93,16 +99,30 @@ export const herdrRunner =
   (env: Record<string, string | undefined>): HerdrRunner =>
   (args) => {
     const result = Bun.spawnSync([herdrBinary(env), ...args], { stdout: 'pipe', stderr: 'pipe', env })
-    if (result.exitCode !== 0) {
-      throw new Error(
-        `herdr ${args.slice(0, 2).join(' ')}: ${result.stderr.toString().trim() || `exit ${result.exitCode}`}`,
-      )
-    }
+    if (result.exitCode !== 0) throw failureOf(args, result.stderr.toString(), result.exitCode)
     return result.stdout.toString()
   }
 
+/** As `herdrRunner`, but the answer arrives as a promise, so a live view keeps drawing while herdr answers. */
+export const herdrRunnerAsync =
+  (env: Record<string, string | undefined>): HerdrAsyncRunner =>
+  async (args) => {
+    const child = Bun.spawn([herdrBinary(env), ...args], { stdout: 'pipe', stderr: 'pipe', env })
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(child.stdout).text(),
+      new Response(child.stderr).text(),
+      child.exited,
+    ])
+    if (exitCode !== 0) throw failureOf(args, stderr, exitCode)
+    return stdout
+  }
+
 export const runHerdr: HerdrRunner = herdrRunner(process.env)
 
+/** The named agents of `herdr agent list`, read without holding the event loop; rejects as `listAgents` throws. */
+export const listHerdrAgents = async (run: HerdrAsyncRunner = herdrRunnerAsync(process.env)): Promise<LaneAgent[]> =>
+  parseAgentList(await run(['agent', 'list']))
+
 /** `ownPane` is herdr's id of the pane this process runs in (`HERDR_PANE_ID`), undefined outside herdr. */
 export const createHerdrLaneStatusSource = (run: HerdrRunner, ownPane?: string): LaneStatusSource => ({
   listAgents: (adopt) => parseAgentList(run(['agent', 'list']), adopt),

package/src/terminal/restore.ts

@@ -0,0 +1,44 @@
+/** How a full-screen view gives the terminal back: the reset sequence it writes and the raw mode it releases. */
+export type TerminalRelease = { write: (text: string) => void; releaseRaw: () => void }
+
+/** How the process ends after an error nobody caught: its exit code and what goes to stderr, null for nothing. */
+export type CrashEnd = { code: number; report: string | null }
+
+const CLOSED_TERMINAL_CODES: ReadonlySet<string> = new Set(['EIO', 'EBADF'])
+
+const attempt = (step: () => void) => {
+  try {
+    step()
+  } catch {
+    // The terminal is gone already; there is nothing left on it to restore.
+  }
+}
+
+/** An error of a terminal that went away under the process: its input reads `EIO` or `EBADF`. */
+export const isClosedTerminal = (error: unknown): boolean =>
+  typeof error === 'object' &&
+  error !== null &&
+  'code' in error &&
+  typeof error.code === 'string' &&
+  CLOSED_TERMINAL_CODES.has(error.code)
+
+/** A closed terminal ends quietly, code 0 and no stack; any other error ends with code 1 and its stack. */
+export const crashEnd = (error: unknown): CrashEnd => {
+  if (isClosedTerminal(error)) return { code: 0, report: null }
+  return { code: 1, report: error instanceof Error ? (error.stack ?? error.message) : String(error) }
+}
+
+/**
+ * The restore of the terminal for every way the process ends: the first call writes `sequence` and releases raw
+ * mode, every later call does nothing. Each step runs even when the one before throws, and none throws: it runs
+ * inside `exit` and crash handlers, where the terminal may already be closed.
+ */
+export const onceRestore = (sequence: string, release: TerminalRelease): (() => void) => {
+  let restored = false
+  return () => {
+    if (restored) return
+    restored = true
+    attempt(() => release.write(sequence))
+    attempt(release.releaseRaw)
+  }
+}

package/src/terminal/text.ts

@@ -29,8 +29,8 @@ export const INVERSE_ON = `${ESC}[7m`
 export const BADGE_TONE = { grey: '48;5;240;38;5;255', amber: '48;5;136;38;5;16', red: '48;5;124;38;5;255' } as const
 
 export type BadgeTone = (typeof BADGE_TONE)[keyof typeof BADGE_TONE]
-const FAINT_ON = `${ESC}[2m`
-const FAINT_OFF = `${ESC}[22m`
+export const FAINT_ON = `${ESC}[2m`
+export const FAINT_OFF = `${ESC}[22m`
 const BAR_WIDTH = 10
 
 const style = (code: string) => (text: string) => `${ESC}[${code}m${text}${RESET}`

package/src/terminal/width.ts

@@ -2,6 +2,13 @@ const VARIATION_SELECTOR = 0xfe0f
 const TEXT_SELECTOR = 0xfe0e
 const ZERO_WIDTH_JOINER = 0x200d
 const COMBINING_MARKS: readonly [number, number][] = [[0x0300, 0x036f]]
+/** Below the first combining mark no code point is wide or takes no cell: each one is one cell. */
+const FIRST_SPECIAL = 0x0300
+/** Whether every code unit of `text` lies below `FIRST_SPECIAL`: then each is one code point of one cell. */
+const isNarrowOnly = (text: string): boolean => {
+  for (let index = 0; index < text.length; index++) if (text.charCodeAt(index) >= FIRST_SPECIAL) return false
+  return true
+}
 
 /** Wide in East Asian Width, or emoji by default presentation: a terminal draws these in two cells. */
 const WIDE: readonly [number, number][] = [
@@ -60,6 +67,7 @@ const within = (ranges: readonly [number, number][], codePoint: number): boolean
  * variation selector (`⏸`) is one cell on its own; `textWidth` counts it as two when the selector follows.
  */
 export const cellWidth = (codePoint: number): number => {
+  if (codePoint < FIRST_SPECIAL) return 1
   if (codePoint === VARIATION_SELECTOR || codePoint === TEXT_SELECTOR || codePoint === ZERO_WIDTH_JOINER) return 0
   if (within(COMBINING_MARKS, codePoint)) return 0
   return within(WIDE, codePoint) ? 2 : 1
@@ -72,6 +80,7 @@ const characterWidth = (character: string, next: string | undefined): number =>
 
 /** The cells a text takes; an emoji followed by a variation selector takes two. */
 export const textWidth = (text: string): number => {
+  if (isNarrowOnly(text)) return text.length
   const characters = [...text]
   return characters.reduce((sum, character, index) => sum + characterWidth(character, characters[index + 1]), 0)
 }

package/src/vocabulary/index.ts

@@ -115,27 +115,28 @@ export const NEXT_VOCABULARY: Record<PlanLanguage, { heading: string }> = {
 
 /**
  * The board section of what waits on the user's answer (a sent preview, an open question, a report to accept): its
- * heading, the header names of its columns (since, item, origin, status, found by name in any order; the status
- * column may also carry a name of `statusAlso`) and the lower-case words a status cell of a still open item starts with.
+ * heading, the header names of its columns (since, item, origin, unblocks, status, found by name in any order; origin
+ * and unblocks are optional, the status column may also carry a name of `statusAlso`) and the lower-case words a status
+ * cell of a still open item starts with.
  */
 export const WAITING_VOCABULARY: Record<
   PlanLanguage,
   {
     heading: string
-    columns: { since: string; item: string; origin: string; status: string }
+    columns: { since: string; item: string; origin: string; unblocks: string; status: string }
     statusAlso: readonly string[]
     open: readonly string[]
   }
 > = {
   [PLAN_LANGUAGE.de]: {
     heading: 'Wartet auf dich',
-    columns: { since: 'Seit', item: 'Punkt', origin: 'Herkunft', status: 'Stand' },
+    columns: { since: 'Seit', item: 'Punkt', origin: 'Herkunft', unblocks: 'Gibt frei', status: 'Stand' },
     statusAlso: ['Status'],
     open: ['offen'],
   },
   [PLAN_LANGUAGE.en]: {
     heading: 'Waiting for you',
-    columns: { since: 'Since', item: 'Item', origin: 'Origin', status: 'Status' },
+    columns: { since: 'Since', item: 'Item', origin: 'Origin', unblocks: 'Unblocks', status: 'Status' },
     statusAlso: [],
     open: ['open'],
   },

package/src/watch/command.ts

@@ -185,6 +185,8 @@ import { readTaskParallelInputs } from './task-parallel-read'
 import { type NoSignalState, type NoTaskSignalEvent, noTaskSignalEvents } from './task-signal-missing'
 import { signalledLanes } from './task-signal-read'
 import { type WatchTexts, watchTexts } from './texts'
+import type { UnlinkedArtifactEvent, UnlinkedState } from './unlinked-artifacts'
+import { readUnlinkedArtifactEvents } from './unlinked-artifacts-read'
 import { updateAnnouncer } from './update-available'
 import { waitingLine } from './waiting-line'
 import {
@@ -303,6 +305,8 @@ type Watching = {
   parallelAutoEnded: string | null
   /** Since when each lane works without a task signal and the phase last reported; persisted like the fingerprints. */
   noTaskSignals: NoSignalState
+  /** The open artifact sends in their grace or already reported as `unlinked artifact`; persisted like the fingerprints. */
+  unlinkedArtifacts: UnlinkedState
   /** The approval requests of the last poll; null before the first read, so the stored ids stay. */
   approvalRequests: ApprovalRequestFile[] | null
   /** The board's appointment table at the last poll and the time it was read at; null before the first read and while the board cannot be read. */
@@ -355,6 +359,7 @@ const recordedOf = (watch: Watch, watching: Watching): WatchState => {
     taskParallels: watching.taskParallels,
     parallelAutoEnded: watching.parallelAutoEnded,
     noTaskSignals: watching.noTaskSignals,
+    unlinkedArtifacts: watching.unlinkedArtifacts,
     approvals: watching.approvalRequests ? recordApprovals(watching.approvalRequests) : withReads.approvals,
     sources: recordWatchedSources(withReads.sources, watching.sourceRuns, watch.sources, watching.githubReadAt),
     appointments: watching.appointments
@@ -1104,6 +1109,21 @@ const noTaskSignalEventsOf = (
   }
 }
 
+/**
+ * This heartbeat's `unlinked artifact` events: the open artifact sends that no plan or board links after a heartbeat's
+ * grace, each once; records the state in `watching`. Nothing when the records or plans cannot be read: the next
+ * heartbeat reads again.
+ */
+const unlinkedArtifactEventsOf = (watch: Watch, watching: Watching): UnlinkedArtifactEvent[] => {
+  try {
+    const { events, state } = readUnlinkedArtifactEvents(watch.root, watch.settings, watching.unlinkedArtifacts)
+    watching.unlinkedArtifacts = state
+    return events
+  } catch {
+    return []
+  }
+}
+
 /** The progress of the working lanes, with the pull requests of the last GitHub read; nothing while no lane works. */
 const workingProgressOf = async (watch: Watch, watching: Watching): Promise<Record<string, LaneProgress>> => {
   const working = workingLanes(watching)
@@ -1112,10 +1132,14 @@ const workingProgressOf = async (watch: Watch, watching: Watching): Promise<Reco
   return progress
 }
 
-/** The events a heartbeat of a report brings: the parallel-task proposals, then the lanes without a task signal. */
+/** The events a heartbeat of a report brings: the parallel-task proposals, the lanes without a task signal, the unlinked artifacts. */
 const heartbeatEventsOf = async (watch: Watch, watching: Watching, now: number): Promise<WatchEvent[]> => {
   const progress = await workingProgressOf(watch, watching)
-  return [...taskParallelEventsOf(watch, watching, now), ...noTaskSignalEventsOf(watch, watching, progress, now)]
+  return [
+    ...taskParallelEventsOf(watch, watching, now),
+    ...noTaskSignalEventsOf(watch, watching, progress, now),
+    ...unlinkedArtifactEventsOf(watch, watching),
+  ]
 }
 
 /**
@@ -1156,6 +1180,7 @@ const printStreamHeartbeat = async (watch: Watch, watching: Watching, now: numbe
   const events = [
     ...taskParallelEventsOf(watch, watching, now),
     ...noTaskSignalEventsOf(watch, watching, progress, now),
+    ...unlinkedArtifactEventsOf(watch, watching),
   ]
   for (const event of events) console.log(`${watchEventLine(event, null)}${hintFor(watch, eventReference(event))}`)
 }
@@ -1254,6 +1279,7 @@ const initialWatching = (
   taskParallels: start.state.taskParallels,
   parallelAutoEnded: start.state.parallelAutoEnded,
   noTaskSignals: start.state.noTaskSignals,
+  unlinkedArtifacts: start.state.unlinkedArtifacts,
   approvalRequests: null,
   appointments: null,
   reportQuestions: null,

package/src/watch/lane-report.ts

@@ -17,6 +17,7 @@ import { SOURCE_FIELD } from './source-fields'
 import { type FieldChange, lineText, type SourceEvent } from './sources'
 import { NO_TASK_SIGNAL_EVENT, type NoTaskSignalEvent, noTaskSignalLine } from './task-signal-missing'
 import type { WatchTexts } from './texts'
+import { unlinkedArtifactLine } from './unlinked-artifacts'
 import {
   type DeployEvent,
   isPullRequestEvent,
@@ -174,6 +175,7 @@ export const watchEventLine = (event: WatchEvent, target: string | null): string
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${phasesText(event.phases)}`
   if (event.kind === WATCH_EVENT.taskParallel) return `=== ${terminalSafe(event.line)}`
   if (event.kind === WATCH_EVENT.noTaskSignal) return `=== ${terminalSafe(noTaskSignalLine(event))}`
+  if (event.kind === WATCH_EVENT.unlinkedArtifact) return `=== ${unlinkedArtifactLine(event)}`
   if (event.kind === WATCH_EVENT.approval)
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${event.id} ${terminalSafe(event.tool)} · ${terminalSafe(event.summary)}`
   if (event.kind === WATCH_EVENT.coordinator) return `=== ${event.kind} ${event.level} ${contextLabel(event.share)}`

package/src/watch/lane-rest.ts

@@ -4,6 +4,12 @@ import { questionCount, questionSections } from './report-questions'
 const LIST_MARKER = /^(?:\d+[.)]|[-*])\s*/
 const QUESTION_LENGTH = 60
 
+/** The label a rest note opens with, and the open-question count it ends with: the herd reads the count (group 1). */
+export const REST_NOTE_LABEL = 'waits on: '
+export const REST_QUESTION_COUNT = /, (\d+) open questions?$/
+
+const openQuestions = (count: number): string => `, ${count} open ${count === 1 ? 'question' : 'questions'}`
+
 /** The first question as one line: list marker and bold out, made safe, cut. */
 const firstQuestion = (lines: readonly string[], start: number, end: number): string => {
   const body = lines
@@ -24,5 +30,5 @@ export const restNote = (reportText: string | null): string | null => {
   const [first] = sections
   if (!first) return null
   const count = questionCount(lines, sections)
-  return `waits on: ${firstQuestion(lines, first.start, first.end)}, ${count} open ${count === 1 ? 'question' : 'questions'}`
+  return `${REST_NOTE_LABEL}${firstQuestion(lines, first.start, first.end)}${openQuestions(count)}`
 }

package/src/watch/reference-paths.ts

@@ -36,6 +36,7 @@ const EVENT_REFERENCES: Readonly<Record<string, Reference>> = {
   [WATCH_EVENT.laneParallel]: REFERENCE.events,
   [WATCH_EVENT.taskParallel]: REFERENCE.events,
   [WATCH_EVENT.noTaskSignal]: REFERENCE.events,
+  [WATCH_EVENT.unlinkedArtifact]: REFERENCE.events,
   [UPDATE_AVAILABLE_EVENT]: REFERENCE.events,
   [WATCH_EVENT.laneModel]: REFERENCE.laneSession,
 }

package/src/watch/unlinked-artifacts-read.ts

@@ -0,0 +1,43 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { sentLaneOf } from '../plans/sent-files'
+import { readSentRecords } from '../plans/sent-files-read'
+import { type PlansSettings, worktreeOf } from '../plans/settings'
+import {
+  linkedUrlsOf,
+  openArtifactsOf,
+  type UnlinkedArtifactEvent,
+  type UnlinkedState,
+  unlinkedArtifactEvents,
+} from './unlinked-artifacts'
+
+/** The texts of every Markdown file below `directory`, boards included; none when it is missing. */
+const markdownTextsUnder = (directory: string): string[] => {
+  if (!existsSync(directory)) return []
+  return readdirSync(directory, { recursive: true, encoding: 'utf8' })
+    .filter((path) => path.endsWith('.md'))
+    .map((path) => readFileSync(join(directory, path), 'utf8'))
+}
+
+/**
+ * This heartbeat's `unlinked artifact` events with the state to keep. The plans and boards are those of the main
+ * checkout, where the coordinator links its own artifacts, and of the worktrees of the lanes that sent one, which link
+ * theirs before the merge. Nothing is read while no artifact send is open.
+ */
+export const readUnlinkedArtifactEvents = (
+  root: string,
+  settings: PlansSettings,
+  previous: UnlinkedState,
+): { events: UnlinkedArtifactEvent[]; state: UnlinkedState } => {
+  const records = readSentRecords(root)
+  const artifacts = openArtifactsOf(records)
+  if (artifacts.length === 0) return { events: [], state: {} }
+  const ids = new Set(artifacts.map(({ id }) => id))
+  const worktrees = join(root, settings.worktreeDirectory)
+  const lanes = new Set(
+    records.filter(({ id }) => ids.has(id)).flatMap((record) => sentLaneOf(record, worktrees) ?? []),
+  )
+  const checkouts = [root, ...[...lanes].map((lane) => worktreeOf(root, settings, lane))]
+  const texts = checkouts.flatMap((checkout) => markdownTextsUnder(join(checkout, settings.planDirectory)))
+  return unlinkedArtifactEvents(previous, artifacts, linkedUrlsOf(texts, settings.linkKinds))
+}

package/src/watch/unlinked-artifacts.ts

@@ -0,0 +1,76 @@
+import type { LinkKind } from '../config/link-kinds'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { readLinkChips } from '../plans/link-chips'
+import type { SentFileRecord } from '../plans/sent-files'
+import { isRecord } from '../shared/is-record'
+
+export const UNLINKED_ARTIFACT_EVENT = 'unlinked artifact'
+
+/** An open send of a published artifact: the record's id, its caption (`artifact` without one) and its address. */
+export type OpenArtifact = { id: string; title: string; url: string }
+
+/** `seen` once a heartbeat found a record's artifact unlinked (the grace), `reported` after its event. */
+export const UNLINKED_STATUS = { seen: 'seen', reported: 'reported' } as const
+
+export type UnlinkedStatus = (typeof UNLINKED_STATUS)[keyof typeof UNLINKED_STATUS]
+
+/** Per record id; a record that was closed, or whose artifact was linked, has no entry. */
+export type UnlinkedState = Record<string, UnlinkedStatus>
+
+export type UnlinkedArtifactEvent = { kind: typeof UNLINKED_ARTIFACT_EVENT } & OpenArtifact
+
+const UNTITLED = 'artifact'
+
+const isArtifactAddress = (file: string): boolean => file.startsWith('https://')
+
+/**
+ * The artifacts of the open sends, one per address: an artifact published again in every round of a review is one
+ * entry, its newest record. Sent files are no artifacts and stay out.
+ */
+export const openArtifactsOf = (records: readonly SentFileRecord[]): OpenArtifact[] => {
+  const newest = new Map<string, SentFileRecord>()
+  for (const record of [...records].sort((left, right) => left.sentAt - right.sentAt)) {
+    const [url] = record.files
+    if (record.closedAt !== null || url === undefined || !isArtifactAddress(url)) continue
+    newest.delete(url)
+    newest.set(url, record)
+  }
+  return [...newest].map(([url, { id, caption }]) => ({ id, title: caption ?? UNTITLED, url }))
+}
+
+/**
+ * The addresses the texts link, read with the herd's own link detection, so what counts as linked shows as a chip.
+ * Read without the herd's cache: a heartbeat reads every plan, more texts than that cache keeps.
+ */
+export const linkedUrlsOf = (texts: readonly string[], kinds: readonly LinkKind[]): Set<string> =>
+  new Set(texts.flatMap((text) => readLinkChips(text, kinds).map(({ url }) => url)))
+
+/**
+ * One event per open artifact that no plan or board links, after the grace of one heartbeat (the link may be on its
+ * way), and once per record: a hint given stays given while the record is open. A linked or closed one leaves the state.
+ */
+export const unlinkedArtifactEvents = (
+  previous: UnlinkedState,
+  artifacts: readonly OpenArtifact[],
+  linked: ReadonlySet<string>,
+): { events: UnlinkedArtifactEvent[]; state: UnlinkedState } => {
+  const events: UnlinkedArtifactEvent[] = []
+  const state: UnlinkedState = {}
+  for (const artifact of artifacts) {
+    if (linked.has(artifact.url)) continue
+    const before = previous[artifact.id]
+    if (before === UNLINKED_STATUS.seen) events.push({ kind: UNLINKED_ARTIFACT_EVENT, ...artifact })
+    state[artifact.id] = before === undefined ? UNLINKED_STATUS.seen : UNLINKED_STATUS.reported
+  }
+  return { events, state }
+}
+
+/** `unlinked artifact <id> "<title>" <url>`; the title's own double quotes become single ones, so the quotes stay its bounds. */
+export const unlinkedArtifactLine = ({ id, title, url }: UnlinkedArtifactEvent): string =>
+  `${UNLINKED_ARTIFACT_EVENT} ${terminalSafe(id)} "${terminalSafe(title).replaceAll('"', "'")}" ${terminalSafe(url)}`
+
+const isUnlinkedStatus = (value: unknown): value is UnlinkedStatus =>
+  (Object.values(UNLINKED_STATUS) as unknown[]).includes(value)
+
+export const isUnlinkedState = (value: unknown): value is UnlinkedState =>
+  isRecord(value) && Object.values(value).every(isUnlinkedStatus)