jackherd 1.25.0 → 1.26.0

package/src/plans/sent-files.ts

@@ -16,6 +16,8 @@ export type SentFileRecord = {
   session: string
   agentId: string | null
   closedAt: number | null
+  /** Who closed the record and why (`closeReasonOf`); absent or null on a record that predates the field or is open. */
+  closedReason?: string | null
 }
 
 /** A badge for a sent file: a `file:` address and the file's name. */
@@ -55,7 +57,8 @@ export const isSentFileRecord = (value: unknown): value is SentFileRecord => {
     typeof record.cwd === 'string' &&
     typeof record.session === 'string' &&
     (record.agentId === null || typeof record.agentId === 'string') &&
-    (record.closedAt === null || typeof record.closedAt === 'number')
+    (record.closedAt === null || typeof record.closedAt === 'number') &&
+    (record.closedReason == null || typeof record.closedReason === 'string')
   )
 }
 
@@ -69,7 +72,7 @@ export const sentLaneOf = ({ files, cwd }: SentFileRecord, worktreeDirectory: st
     .find((lane) => lane !== null) ?? laneDirectoryOf(cwd, worktreeDirectory)
 
 /** The records without an earlier send of the same first file: an artifact updated each round is one send, the newest. */
-const latestPerFile = (records: readonly SentFileRecord[]): SentFileRecord[] =>
+export const latestPerFile = (records: readonly SentFileRecord[]): SentFileRecord[] =>
   records.filter((record, index) => !records.slice(index + 1).some((later) => later.files[0] === record.files[0]))
 
 /**
@@ -94,12 +97,17 @@ export const sentChipsByLane = (
   return lanes
 }
 
+/** What a row of "Your turn" shows of a send: the first file's label and how many more follow. */
+export const sentTextOf = (record: SentFileRecord): string => {
+  const more = record.files.length > 1 ? ` +${record.files.length - 1}` : ''
+  return `${labelOf(record.files[0], record.caption)}${more}`
+}
+
 const itemOf = (record: SentFileRecord): WaitingItem => {
   const [first] = record.files
-  const more = record.files.length > 1 ? ` +${record.files.length - 1}` : ''
   return {
     since: clockText(record.sentAt),
-    item: `${labelOf(first, record.caption)}${more}`,
+    item: sentTextOf(record),
     kind: WAITING_KIND.file,
     id: record.id,
     open: true,

package/src/waiting/command.ts

@@ -1,14 +1,64 @@
 import { installedReferenceHint } from '../lane/skill-hint'
+import { clockText, DAY_MS } from '../plan-format/clock'
 import { terminalSafe } from '../plan-format/terminal-text'
 import type { WaitingItem } from '../plan-format/waiting'
+import { CLOSE_REASON, closeReasonOf } from '../plans/close-reason'
 import { mainCheckout } from '../plans/git'
+import { type QuestionRecord, questionTextOf } from '../plans/question-records'
 import { closeAllQuestionRecords, closeQuestionRecords } from '../plans/questions-read'
+import { type SentFileRecord, sentTextOf } from '../plans/sent-files'
 import { closeAllSentRecords, closeSentRecords } from '../plans/sent-files-read'
-import { recordWaitingItems } from '../plans/waiting-records'
+import { readWaitingRecords, recordWaitingItems } from '../plans/waiting-records'
 import { CLI_NAME } from '../version/release'
 import { REFERENCE, referenceLine } from '../watch/reference-paths'
 
-const USAGE = `usage: ${CLI_NAME} waiting [close <id> ... | close --all]`
+const USAGE = `usage: ${CLI_NAME} waiting [--closed | close <id> ... [--reason "<text>"] | close --all [--reason "<text>"]]`
+
+const CLOSE_ALL = '--all'
+const CLOSED = '--closed'
+const REASON = '--reason'
+
+/** A closed record as `jh waiting --closed` lists it. */
+type ClosedRecord = { id: string; closedAt: number; closedReason?: string | null; text: string }
+
+const closedRecordsOf = (sent: readonly SentFileRecord[], questions: readonly QuestionRecord[]): ClosedRecord[] =>
+  [
+    ...sent.map((record) => ({ ...record, text: sentTextOf(record) })),
+    ...questions.map((record) => ({ ...record, text: questionTextOf(record) })),
+  ].flatMap(({ id, closedAt, closedReason, text }) => (closedAt === null ? [] : [{ id, closedAt, closedReason, text }]))
+
+/**
+ * The lines `jh waiting --closed` prints: the records closed within the last 24 hours, newest first, each as
+ * `id · time of closing · reason · text` (a dash for a record closed without a reason: one that predates the field, or one the hook closed itself); a note when none.
+ */
+export const closedListing = (
+  sent: readonly SentFileRecord[],
+  questions: readonly QuestionRecord[],
+  now: number,
+): string[] => {
+  const recent = closedRecordsOf(sent, questions)
+    .filter(({ closedAt }) => now - closedAt <= DAY_MS)
+    .sort((left, right) => right.closedAt - left.closedAt)
+  return recent.length === 0
+    ? ['nothing was closed in the last 24 hours']
+    : recent.map(({ id, closedAt, closedReason, text }) =>
+        terminalSafe(`${id} · ${clockText(closedAt)} · ${closedReason ?? '-'} · ${text}`),
+      )
+}
+
+/** What `jh waiting close` was asked to close and with which reason. */
+export type CloseArguments = { all: true; reason: string } | { all: false; ids: string[]; reason: string }
+
+/** The arguments after `close`: the ids or `--all`, then optionally `--reason "<text>"`; the reason is `coordinator` plus the text. Null when they do not fit. */
+export const closeArgumentsOf = (args: readonly string[]): CloseArguments | null => {
+  const at = args.indexOf(REASON)
+  if (at !== -1 && at !== args.length - 2) return null
+  const ids = at === -1 ? [...args] : args.slice(0, at)
+  const all = ids.includes(CLOSE_ALL)
+  if (ids.length === 0 || (all && ids.length > 1)) return null
+  const reason = closeReasonOf(CLOSE_REASON.coordinator, at === -1 ? '' : args[at + 1])
+  return all ? { all, reason } : { all, ids, reason }
+}
 
 /**
  * The lines `jh waiting` prints: id, time and text of each item, made safe for the terminal, then the reference that
@@ -19,41 +69,47 @@ export const waitingListing = (items: readonly WaitingItem[], hint = ''): string
     ? ['nothing waits on you']
     : [...items.map(({ since, item, id }) => terminalSafe(`${id} · ${since} · ${item}`)), ...referenceLine(hint)]
 
-const CLOSE_ALL = '--all'
-
-/** Closes the records the ids name, files and questions alike; how many it closed. */
-export const closeWaiting = (root: string, ids: readonly string[], now: number): number =>
-  closeSentRecords(root, ids, now) + closeQuestionRecords(root, ids, now)
+/** Closes the records the ids name with `reason`, files and questions alike; how many it closed. */
+export const closeWaiting = (root: string, ids: readonly string[], now: number, reason: string): number =>
+  closeSentRecords(root, ids, now, reason) + closeQuestionRecords(root, ids, now, reason)
 
-/** Closes every open record, files and questions alike; how many it closed. */
-export const closeAllWaiting = (root: string, now: number): number =>
-  closeAllSentRecords(root, now) + closeAllQuestionRecords(root, now)
+/** Closes every open record with `reason`, files and questions alike; how many it closed. */
+export const closeAllWaiting = (root: string, now: number, reason: string): number =>
+  closeAllSentRecords(root, now, reason) + closeAllQuestionRecords(root, now, reason)
 
 /**
  * `jh waiting` lists the files sent to the user and the questions left unanswered that no one closed (their id, time
- * and text); `jh waiting close <id> ...` or `close --all` closes them once the user has answered. Exit 0, 1 on a wrong
- * command line.
+ * and text); `--closed` lists what was closed in the last 24 hours with its reason; `jh waiting close <id> ...` or
+ * `close --all` closes them once the user has answered. Exit 0, 1 on a wrong command line.
  */
 export const run = async (args: string[]): Promise<number> => {
   const root = mainCheckout(process.cwd())
-  if (args.length === 0) {
-    for (const line of waitingListing(
-      recordWaitingItems(root, Date.now()),
-      installedReferenceHint(root, REFERENCE.waiting),
-    ))
-      console.log(line)
-    return 0
-  }
+  if (args.length === 0) return printWaiting(root)
+  if (args.length === 1 && args[0] === CLOSED) return printClosed(root)
   const [command, ...rest] = args
-  if (command !== 'close' || rest.length === 0) {
+  const close = command === 'close' ? closeArgumentsOf(rest) : null
+  if (close === null) {
     console.error(USAGE)
     return 1
   }
-  if (rest.includes(CLOSE_ALL) && rest.length > 1) {
-    console.error(`${CLOSE_ALL} closes everything and takes no ids\n${USAGE}`)
-    return 1
-  }
-  const closed = rest[0] === CLOSE_ALL ? closeAllWaiting(root, Date.now()) : closeWaiting(root, rest, Date.now())
+  const closed = close.all
+    ? closeAllWaiting(root, Date.now(), close.reason)
+    : closeWaiting(root, close.ids, Date.now(), close.reason)
   console.log(`closed ${closed}`)
   return 0
 }
+
+const printWaiting = (root: string): number => {
+  for (const line of waitingListing(
+    recordWaitingItems(root, Date.now()),
+    installedReferenceHint(root, REFERENCE.waiting),
+  ))
+    console.log(line)
+  return 0
+}
+
+const printClosed = (root: string): number => {
+  const { sent, questions } = readWaitingRecords(root)
+  for (const line of closedListing(sent, questions, Date.now())) console.log(line)
+  return 0
+}

package/src/watch/command.ts

@@ -50,12 +50,15 @@ import { contextReport } from '../context/report'
 import { agentLog } from '../context/session-log'
 import { type LaneProgress, parseSprintLanes, type SprintLane } from '../plan-format'
 import { terminalSafe } from '../plan-format/terminal-text'
+import { openWaitingItems } from '../plan-format/waiting'
 import { boardFor, foundLanesOf } from '../plans/board-pick'
 import { ensurePlanPanes } from '../plans/ensure-panes'
 import { errorText } from '../plans/error-text'
 import { baseReaderOf, mainCheckout, worktreeNames, worktreeRoot } from '../plans/git'
 import { discoverLanes, isUnchanged, laneSetChange } from '../plans/lane-discovery'
 import { readerOncePerRef } from '../plans/plan-heads'
+import { readQuestionRecords } from '../plans/questions-read'
+import { closeSentRecords, readSentRecords } from '../plans/sent-files-read'
 import { CLOCK_LOCALE, type PlansSettings, plansSettingsOf, worktreeOf } from '../plans/settings'
 import { readRunningSubagents, subagentSourceOf } from '../plans/subagents-read'
 import { boardTexts } from '../plans/texts'
@@ -182,6 +185,21 @@ import {
 import { isBehindOnBase, mainCheckoutDutyLine } from './main-checkout'
 import { mergeOverlapReader } from './merge-overlap-read'
 import { monitorToolAvailable } from './monitor-tool'
+import {
+  obsoleteProposalEvents,
+  type ProposalInput,
+  type ProposalState,
+  type WaitingObsoleteEvent,
+  waitingLanesOf,
+} from './obsolete-proposals'
+import {
+  type Closing,
+  closingsByReason,
+  laneAbsenceOf,
+  obsoleteSendsOf,
+  WAITING_CLOSED_EVENT,
+  type WaitingClosedEvent,
+} from './obsolete-records'
 import { parseWatchOptions, type WatchOptions } from './options'
 import type { PlanMissingEvent, PlanMissingState } from './plan-missing'
 import { readPlanMissingEvents } from './plan-missing-read'
@@ -306,6 +324,8 @@ type Watch = {
   herdr: boolean
   /** `lanes.backend` and the worktree directory of the main checkout's config; undefined without one, then the backend is never touched. */
   backend: MainCheckoutBackend | undefined
+  /** Runs in the main checkout, not in a lane's worktree: only then does it close records of "Your turn" or propose to. */
+  inMainCheckout: boolean
 }
 
 /** The coordinator's agent name (null when none is found), its last read (null before the first one) and the tokens of that read (null without a value). */
@@ -376,6 +396,10 @@ type Watching = {
   unlinkedArtifacts: UnlinkedState
   /** Per working lane, the plan last reported as `plan missing on base`; persisted like the fingerprints. */
   planMissing: PlanMissingState
+  /** The lanes of open waiting points missing at the last heartbeat; persisted like the fingerprints. */
+  waitingMissingLanes: string[]
+  /** The reasons proposed per open waiting point as `waiting obsolete?`; persisted like the fingerprints. */
+  waitingProposals: ProposalState
   /** 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. */
@@ -443,6 +467,8 @@ const recordedOf = (watch: Watch, watching: Watching): WatchState => {
     laneStalls: watching.laneStalls,
     unlinkedArtifacts: watching.unlinkedArtifacts,
     planMissing: watching.planMissing,
+    waitingMissingLanes: watching.waitingMissingLanes,
+    waitingProposals: watching.waitingProposals,
     approvals: watching.approvalRequests ? recordApprovals(watching.approvalRequests) : withReads.approvals,
     ...recordedSourceState(withReads.sources, watching.sourceRuns, watching.sources.sources, watching.githubReadAt),
     appointments: watching.appointments
@@ -1322,6 +1348,69 @@ const unlinkedArtifactEventsOf = (watch: Watch, watching: Watching): UnlinkedArt
   }
 }
 
+/** Closes the sends through the log, one call per reason; returns the closings that were written, so a failed write is neither reported nor counted. */
+const closeObsoleteSends = (root: string, closings: readonly Closing[], now: number): Closing[] =>
+  [...closingsByReason(closings)].flatMap(([reason, ids]) => {
+    try {
+      closeSentRecords(root, ids, now, reason)
+      return ids.map((id) => ({ id, reason }))
+    } catch {
+      return []
+    }
+  })
+
+/** What the proposals read besides the records: the pull requests of the last GitHub read and the lanes' branches. */
+const proposalContextOf = (watching: Watching): Pick<ProposalInput, 'pullRequests' | 'laneBranches' | 'knownLanes'> => {
+  const laneBranches = { ...watching.state.laneBranches, ...watching.laneBranches }
+  return {
+    pullRequests: answered(watching.github)?.pullRequests ?? null,
+    laneBranches,
+    knownLanes: new Set([...Object.keys(laneBranches), ...watching.lanes]),
+  }
+}
+
+/**
+ * This heartbeat's run over "Your turn", only from the main checkout: closes the sends a safe signal makes obsolete
+ * (`waiting closed`, one event per run that closes something), then proposes what only looks obsolete (`waiting
+ * obsolete?`, each point and reason once); records the missing lanes and the proposals in `watching`. Never writes
+ * into the board. A read error closes nothing and reports nothing: the next heartbeat reads again.
+ */
+const waitingObsoleteEventsOf = (
+  watch: Watch,
+  watching: Watching,
+  now: number,
+): (WaitingClosedEvent | WaitingObsoleteEvent)[] => {
+  if (!watch.inMainCheckout) return []
+  try {
+    const worktreeDirectory = join(watch.root, watch.settings.worktreeDirectory)
+    if (!existsSync(worktreeDirectory)) return []
+    const sends = readSentRecords(watch.root)
+    const questions = readQuestionRecords(watch.root)
+    const boardText = readBoardText(watch)
+    const board = boardText === null ? null : openWaitingItems(boardText, watch.settings.boardLanguage)
+    const { missing, gone } = laneAbsenceOf(
+      waitingLanesOf({ sends, questions, board, worktreeDirectory }),
+      new Set(worktreeNames(worktreeDirectory)),
+      watching.waitingMissingLanes,
+    )
+    const closings = closeObsoleteSends(watch.root, obsoleteSendsOf(sends, worktreeDirectory, gone), now)
+    const closed = new Set(closings.map(({ id }) => id))
+    const { events, state } = obsoleteProposalEvents(watching.waitingProposals, {
+      sends: sends.filter(({ id }) => !closed.has(id)),
+      questions,
+      board,
+      worktreeDirectory,
+      gone,
+      ...proposalContextOf(watching),
+    })
+    watching.waitingMissingLanes = missing
+    watching.waitingProposals = state
+    return closings.length === 0 ? events : [{ kind: WAITING_CLOSED_EVENT, closings }, ...events]
+  } catch {
+    return []
+  }
+}
+
 /**
  * This heartbeat's `plan missing on base` events: the working lanes whose board row, as their worktree has it, links a
  * plan the base ref lacks, each once; records the state in `watching`. Nothing when the boards or git cannot be read:
@@ -1351,13 +1440,14 @@ const workingProgressOf = async (watch: Watch, watching: Watching): Promise<Reco
   return progress
 }
 
-/** The events a heartbeat of a report brings: the parallel-task proposals, the lanes without a task signal, the unlinked artifacts, the plans missing on the base. */
+/** The events a heartbeat of a report brings: the parallel-task proposals, the lanes without a task signal, the unlinked artifacts, the obsolete waiting points, the plans missing on the base. */
 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),
     ...unlinkedArtifactEventsOf(watch, watching),
+    ...waitingObsoleteEventsOf(watch, watching, now),
     ...planMissingEventsOf(watch, watching),
   ]
 }
@@ -1421,6 +1511,7 @@ const printStreamHeartbeat = async (watch: Watch, watching: Watching, now: numbe
     ...taskParallelEventsOf(watch, watching, now),
     ...noTaskSignalEventsOf(watch, watching, progress, now),
     ...unlinkedArtifactEventsOf(watch, watching),
+    ...waitingObsoleteEventsOf(watch, watching, now),
     ...planMissingEventsOf(watch, watching),
   ]
   for (const event of events) console.log(`${watchEventLine(event, null)}${hintFor(watch, eventReference(event))}`)
@@ -1589,6 +1680,8 @@ const initialWatching = (
   laneStalls: start.state.laneStalls,
   unlinkedArtifacts: start.state.unlinkedArtifacts,
   planMissing: start.state.planMissing,
+  waitingMissingLanes: start.state.waitingMissingLanes,
+  waitingProposals: start.state.waitingProposals,
   approvalRequests: null,
   appointments: null,
   reportQuestions: null,
@@ -1737,6 +1830,7 @@ const watchOf = (options: WatchOptions): Watch => {
     selfMergeMinutes: config.guard.selfMerge.approvalMinutes,
     herdr: insideHerdr(settings.adapter, process.env),
     backend: mainCheckoutBackendOf(root, checkoutRoot, config),
+    inMainCheckout: checkoutRoot === root,
   }
 }
 

package/src/watch/lane-report.ts

@@ -27,6 +27,8 @@ import type { LaneParallelEvent } from './lane-parallel'
 import { laneStalledLine } from './lane-stalled'
 import { type LaneSnapshot, NO_AGENT } from './lane-watch'
 import { MERGE_OVERLAP, type MergeOverlap } from './merge-duties'
+import { waitingObsoleteLine } from './obsolete-proposals'
+import { waitingClosedLine } from './obsolete-records'
 import { PLAN_MISSING_EVENT, type PlanMissingEvent, planMissingLine } from './plan-missing'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 import { SOURCE_FIELD } from './source-fields'
@@ -204,6 +206,8 @@ export const watchEventLine = (event: WatchEvent, target: string | null): string
   if (laneLine !== null) return laneLine
   if (event.kind === WATCH_EVENT.taskParallel) return `=== ${terminalSafe(event.line)}`
   if (event.kind === WATCH_EVENT.unlinkedArtifact) return `=== ${unlinkedArtifactLine(event)}`
+  if (event.kind === WATCH_EVENT.waitingClosed) return `=== ${waitingClosedLine(event)}`
+  if (event.kind === WATCH_EVENT.waitingObsolete) return `=== ${waitingObsoleteLine(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/obsolete-proposals.ts

@@ -0,0 +1,175 @@
+import { createHash } from 'node:crypto'
+import { terminalSafe } from '../plan-format/terminal-text'
+import type { WaitingItem } from '../plan-format/waiting'
+import { CLOSE_REASON, closeReasonOf } from '../plans/close-reason'
+import { type QuestionRecord, questionTextOf } from '../plans/question-records'
+import { type SentFileRecord, sentLaneOf, sentTextOf } from '../plans/sent-files'
+import { laneDirectoryOf } from '../plans/unlisted-lanes'
+import { isRecord } from '../shared/is-record'
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import { latestPullRequestOf, PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
+
+export const WAITING_OBSOLETE_EVENT = 'waiting obsolete?'
+
+/** A point of "Your turn" that looks obsolete: a record's id or a board row's key, why, and what it shows. */
+export type Proposal = { key: string; reason: string; text: string }
+
+export type WaitingObsoleteEvent = { kind: typeof WAITING_OBSOLETE_EVENT } & Proposal
+
+/** Per open point, the reasons already proposed for it; a point that closed or left the board has no entry. */
+export type ProposalState = Record<string, string[]>
+
+/** The pull request numbers and lane names a free text names. */
+export type TextReferences = { pullRequests: number[]; lanes: string[] }
+
+/** What a heartbeat read for its proposals; null where the source did not answer, so nothing is said about it. */
+export type ProposalInput = {
+  sends: readonly SentFileRecord[]
+  questions: readonly QuestionRecord[]
+  /** The open rows of the board's waiting section; null when the board cannot be read. */
+  board: readonly WaitingItem[] | null
+  /** The pull requests of the watcher's last GitHub read; null before one answered. */
+  pullRequests: readonly WatchedPullRequest[] | null
+  /** Lane → branch, as the watcher keeps it after a lane was closed. */
+  laneBranches: Readonly<Record<string, string>>
+  worktreeDirectory: string
+  /** The lanes whose directory was missing in two heartbeats in a row (`laneAbsenceOf`). */
+  gone: ReadonlySet<string>
+  /** The lanes known to have existed; a board row naming a lane that never had a worktree proposes nothing. */
+  knownLanes: ReadonlySet<string>
+}
+
+/** The word that names a lane before its name in backticks, per board language (`Spur \`name\``); every one is read. */
+const LANE_WORD: Record<PlanLanguage, string> = { [PLAN_LANGUAGE.de]: 'Spur', [PLAN_LANGUAGE.en]: 'lane' }
+
+/** `#<digits>` standing alone: not `#AB12CD`, not `#12a`, not a part of a word or an address (`a#1`, `/#1`). */
+const PULL_REQUEST_REFERENCE = /(?<![\w#&/])#(\d+)(?!\w)/g
+
+const LANE_REFERENCE = new RegExp(`\\b(?:${Object.values(LANE_WORD).join('|')})\\s+\`([^\`\\s]+)\``, 'gi')
+
+const ROW_KEY_PREFIX = 'row-'
+const ROW_HASH_LENGTH = 8
+const SUPERSEDED = 'superseded'
+/** The reason of a question whose own session has ended (`SessionEnd`, also after `/clear`) with the question still open. */
+const SESSION_ENDED = 'session ended'
+
+/** What of a board row names its pull request or lane: the item and the origin. */
+const rowText = ({ item, origin }: WaitingItem): string => `${item} ${origin ?? ''}`
+
+/** The pull request numbers (`#<n>`) and lane names (`Spur \`name\``, `lane \`name\``) a free text names, each once. */
+export const textReferencesOf = (text: string): TextReferences => ({
+  pullRequests: [...new Set([...text.matchAll(PULL_REQUEST_REFERENCE)].map((match) => Number(match[1])))],
+  lanes: [...new Set([...text.matchAll(LANE_REFERENCE)].map((match) => match[1]))],
+})
+
+/** The lanes the open points name: a send's lane, a question's lane by its directory, a board row's lanes in its text. */
+export const waitingLanesOf = (
+  input: Pick<ProposalInput, 'sends' | 'questions' | 'board' | 'worktreeDirectory'>,
+): string[] => [
+  ...input.sends.flatMap((record) =>
+    record.closedAt === null ? (sentLaneOf(record, input.worktreeDirectory) ?? []) : [],
+  ),
+  ...input.questions.flatMap((record) =>
+    record.closedAt === null ? (laneDirectoryOf(record.cwd, input.worktreeDirectory) ?? []) : [],
+  ),
+  ...(input.board ?? []).flatMap((row) => textReferencesOf(rowText(row)).lanes),
+]
+
+/** A board row's key: `row-` and a short hash of its item, stable while the row's text stays. */
+export const rowKeyOf = (item: string): string =>
+  `${ROW_KEY_PREFIX}${createHash('sha256').update(item).digest('hex').slice(0, ROW_HASH_LENGTH)}`
+
+const hasEnded = ({ state }: WatchedPullRequest): boolean => state !== PULL_REQUEST_STATE.open
+
+const pullRequestReason = ({ number, state }: WatchedPullRequest): string => `pr #${number} ${state.toLowerCase()}`
+
+const laneRemovedReason = (lane: string): string => closeReasonOf(CLOSE_REASON.laneRemoved, lane)
+
+const sendProposals = (input: ProposalInput): Proposal[] =>
+  input.sends.flatMap((record) => {
+    const lane = sentLaneOf(record, input.worktreeDirectory)
+    const branch = lane === null ? undefined : input.laneBranches[lane]
+    const pullRequest = branch === undefined ? null : latestPullRequestOf(input.pullRequests ?? [], branch)
+    return record.closedAt === null && pullRequest !== null && hasEnded(pullRequest)
+      ? [{ key: record.id, reason: pullRequestReason(pullRequest), text: sentTextOf(record) }]
+      : []
+  })
+
+const questionReasons = (record: QuestionRecord, input: ProposalInput): string[] => {
+  const lane = laneDirectoryOf(record.cwd, input.worktreeDirectory)
+  const superseded = record.supersededBy ? [`${SUPERSEDED}: ${record.supersededBy.question}`] : []
+  const ended = typeof record.sessionEndedAt === 'number' ? [SESSION_ENDED] : []
+  return [...superseded, ...ended, ...(lane !== null && input.gone.has(lane) ? [laneRemovedReason(lane)] : [])]
+}
+
+const questionProposals = (input: ProposalInput): Proposal[] =>
+  input.questions
+    .filter(({ closedAt }) => closedAt === null)
+    .flatMap((record) =>
+      questionReasons(record, input).map((reason) => ({ key: record.id, reason, text: questionTextOf(record) })),
+    )
+
+const rowReasons = (row: WaitingItem, input: ProposalInput): string[] => {
+  const { pullRequests, lanes } = textReferencesOf(rowText(row))
+  const ended = (input.pullRequests ?? []).filter((pullRequest) => pullRequests.includes(pullRequest.number))
+  const removed = lanes.filter((lane) => input.gone.has(lane) && input.knownLanes.has(lane))
+  return [...ended.filter(hasEnded).map(pullRequestReason), ...removed.map(laneRemovedReason)]
+}
+
+const boardProposals = (input: ProposalInput): Proposal[] =>
+  (input.board ?? []).flatMap((row) =>
+    rowReasons(row, input).map((reason) => ({ key: rowKeyOf(row.item), reason, text: row.item })),
+  )
+
+/**
+ * What looks obsolete but is not safe to close: an open send whose lane's pull request was merged or closed, an open
+ * board row naming such a pull request (`#<n>`) or a lane whose directory is gone, an open question a later dialog
+ * probably answered (`supersededBy`), whose session has ended (`session ended`) or whose lane is gone. The coordinator decides; nothing here closes anything.
+ */
+export const obsoleteProposalsOf = (input: ProposalInput): Proposal[] => [
+  ...sendProposals(input),
+  ...questionProposals(input),
+  ...boardProposals(input),
+]
+
+/** The keys still open: the open records and board rows; while the board cannot be read, the rows proposed before. */
+const openKeysOf = (previous: ProposalState, input: ProposalInput): Set<string> => {
+  const records = [...input.sends, ...input.questions].filter(({ closedAt }) => closedAt === null).map(({ id }) => id)
+  const rows =
+    input.board === null
+      ? Object.keys(previous).filter((key) => key.startsWith(ROW_KEY_PREFIX))
+      : input.board.map(({ item }) => rowKeyOf(item))
+  return new Set([...records, ...rows])
+}
+
+/**
+ * One event per point and reason, once while the point is open: a reason proposed before is not said again, and a
+ * point that closed leaves the state. A source that did not answer keeps what was proposed from it.
+ */
+export const obsoleteProposalEvents = (
+  previous: ProposalState,
+  input: ProposalInput,
+): { events: WaitingObsoleteEvent[]; state: ProposalState } => {
+  const open = openKeysOf(previous, input)
+  const state: ProposalState = Object.fromEntries(Object.entries(previous).filter(([key]) => open.has(key)))
+  const events: WaitingObsoleteEvent[] = []
+  for (const proposal of obsoleteProposalsOf(input)) {
+    const said = state[proposal.key] ?? []
+    if (said.includes(proposal.reason)) continue
+    events.push({ kind: WAITING_OBSOLETE_EVENT, ...proposal })
+    state[proposal.key] = [...said, proposal.reason]
+  }
+  return { events, state }
+}
+
+const quoted = (text: string): string => terminalSafe(text).replaceAll('"', "'")
+
+/** `waiting obsolete? <key> <reason> "<text>"`; double quotes inside become single ones, so the quotes stay the text's bounds. */
+export const waitingObsoleteLine = ({ key, reason, text }: WaitingObsoleteEvent): string =>
+  `${WAITING_OBSOLETE_EVENT} ${terminalSafe(key)} ${quoted(reason)} "${quoted(text)}"`
+
+export const isProposalState = (value: unknown): value is ProposalState =>
+  isRecord(value) &&
+  Object.values(value).every(
+    (reasons) => Array.isArray(reasons) && reasons.every((reason) => typeof reason === 'string'),
+  )

package/src/watch/obsolete-records.ts

@@ -0,0 +1,77 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { CLOSE_REASON, closeReasonOf } from '../plans/close-reason'
+import { latestPerFile, type SentFileRecord, sentLaneOf } from '../plans/sent-files'
+
+export const WAITING_CLOSED_EVENT = 'waiting closed'
+
+/** A record the watcher closes on a safe signal, and the reason it writes to it (`closeReasonOf`). */
+export type Closing = { id: string; reason: string }
+
+/** What a heartbeat knows of the lanes' directories: the ones missing now, and those missing in two heartbeats in a row. */
+export type LaneAbsence = { missing: string[]; gone: Set<string> }
+
+export type WaitingClosedEvent = { kind: typeof WAITING_CLOSED_EVENT; closings: Closing[] }
+
+/**
+ * Which of the `lanes` have no directory among `existing`, and which of those were missing at the last heartbeat
+ * too (`previousMissing`): only these count as gone, so a worktree renamed or slow to list closes nothing.
+ */
+export const laneAbsenceOf = (
+  lanes: Iterable<string>,
+  existing: ReadonlySet<string>,
+  previousMissing: readonly string[],
+): LaneAbsence => {
+  const missing = [...new Set(lanes)].filter((lane) => !existing.has(lane)).sort()
+  return { missing, gone: new Set(missing.filter((lane) => previousMissing.includes(lane))) }
+}
+
+/** Each older send of a first entry that a newer send has, closed with the newer send's id (`latestPerFile`). */
+const olderVersionsOf = (records: readonly SentFileRecord[]): Closing[] => {
+  const ordered = [...records].sort((left, right) => left.sentAt - right.sentAt)
+  const latest = latestPerFile(ordered)
+  const newestOf = new Map(latest.map((record) => [record.files[0], record.id]))
+  const kept = new Set(latest.map(({ id }) => id))
+  return ordered.flatMap((record) => {
+    const newer = newestOf.get(record.files[0])
+    return kept.has(record.id) || newer === undefined
+      ? []
+      : [{ id: record.id, reason: closeReasonOf(CLOSE_REASON.newerVersion, newer) }]
+  })
+}
+
+/**
+ * The open sends a safe signal makes obsolete: an older send of a first entry that was sent again (`newer version:
+ * <id>`, whoever sent it), and a send whose lane is gone (`lane removed: <name>`); the newer version wins when both hold.
+ * A send without a lane (lane null) is never closed as removed, and a question record is never closed here: the
+ * coordinator decides on those.
+ */
+export const obsoleteSendsOf = (
+  records: readonly SentFileRecord[],
+  worktreeDirectory: string,
+  gone: ReadonlySet<string>,
+): Closing[] => {
+  const open = records.flatMap((record) => {
+    const lane = sentLaneOf(record, worktreeDirectory)
+    return record.closedAt === null ? [{ id: record.id, lane }] : []
+  })
+  const openIds = new Set(open.map(({ id }) => id))
+  const newer = olderVersionsOf(records).filter(({ id }) => openIds.has(id))
+  const closedByNewer = new Set(newer.map(({ id }) => id))
+  const removed = open.flatMap(({ id, lane }) =>
+    lane !== null && gone.has(lane) && !closedByNewer.has(id)
+      ? [{ id, reason: closeReasonOf(CLOSE_REASON.laneRemoved, lane) }]
+      : [],
+  )
+  return [...newer, ...removed]
+}
+
+/** The closings grouped by reason, each group one call of the log's `close`. */
+export const closingsByReason = (closings: readonly Closing[]): Map<string, string[]> => {
+  const groups = new Map<string, string[]>()
+  for (const { id, reason } of closings) groups.set(reason, [...(groups.get(reason) ?? []), id])
+  return groups
+}
+
+/** `waiting closed <n>: <id> <reason>; …`, the reasons without control characters. */
+export const waitingClosedLine = ({ closings }: WaitingClosedEvent): string =>
+  `${WAITING_CLOSED_EVENT} ${closings.length}: ${closings.map(({ id, reason }) => `${terminalSafe(id)} ${terminalSafe(reason)}`).join('; ')}`

package/src/watch/reference-paths.ts

@@ -53,6 +53,8 @@ const EVENT_REFERENCES: Readonly<Record<string, Reference>> = {
   [WATCH_EVENT.noTaskSignal]: REFERENCE.events,
   [WATCH_EVENT.unlinkedArtifact]: REFERENCE.events,
   [WATCH_EVENT.planMissing]: REFERENCE.events,
+  [WATCH_EVENT.waitingClosed]: REFERENCE.waiting,
+  [WATCH_EVENT.waitingObsolete]: REFERENCE.waiting,
   [WATCH_EVENT.deploy]: REFERENCE.events,
   [WATCH_EVENT.laneStalled]: REFERENCE.events,
   [WATCH_EVENT.due]: REFERENCE.appointments,