jackherd 1.24.0 → 1.26.0

package/src/watch/lane-progress.ts

@@ -224,5 +224,5 @@ export const boardCheckoutRows = (
   checkoutText: string,
 ): number => {
   const atBase = textAtBase(baseReaderOf(root, baseRefOf(settings)), boardRepoPathOf(root, settings, boardFile))
-  return atBase === null ? 0 : boardRowsOf(atBase, checkoutText, settings.planLanguage).rowsFromCheckout
+  return atBase === null ? 0 : boardRowsOf(atBase, checkoutText, settings.boardLanguage).rowsFromCheckout
 }

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/merge-overlap-read.ts

@@ -1,7 +1,7 @@
 import { STACKS } from '../config/detect'
 import { isObjectId } from '../lane/close-survey'
 import { parseSprintLanes } from '../plan-format'
-import type { PlansSettings } from '../plans/settings'
+import { type PlansSettings } from '../plans/settings'
 import { lanePlanPath, watchedLanePlanText } from './lane-progress'
 import type { OverlapOf } from './lane-report'
 import { type LaneScope, type MergeOverlap, overlapOf } from './merge-duties'
@@ -39,7 +39,7 @@ const scopeOf = (
   boardText: string,
   name: string,
 ): LaneScope | null => {
-  const lane = parseSprintLanes(boardText, settings.planLanguage).find((candidate) => candidate.name === name)
+  const lane = parseSprintLanes(boardText, settings.boardLanguage).find((candidate) => candidate.name === name)
   if (lane === undefined) return null
   const text = watchedLanePlanText(root, settings, boardFile, lane)
   if (text === null) return null

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/plan-missing-read.ts

@@ -19,7 +19,9 @@ import {
 const worktreePlanOf = (root: string, settings: PlansSettings, boardFile: string, laneName: string): string | null => {
   const file = join(worktreeOf(root, settings, laneName), boardRepoPathOf(root, settings, boardFile))
   if (!existsSync(file)) return null
-  const lane = parseSprintLanes(readFileSync(file, 'utf8'), settings.planLanguage).find(({ name }) => name === laneName)
+  const lane = parseSprintLanes(readFileSync(file, 'utf8'), settings.boardLanguage).find(
+    ({ name }) => name === laneName,
+  )
   const path = lane === undefined ? null : lanePlanPath(root, settings, boardFile, lane)
   return path === null || isOutsideRepository(path) ? null : path
 }

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,

package/src/watch/watch-events.ts

@@ -23,6 +23,13 @@ import { isLaneModels, LANE_MODEL_EVENT, type LaneModelEvent, type LaneModels }
 import { isLaneParallels, LANE_PARALLEL_EVENT, type LaneParallelEvent, type LaneParallels } from './lane-parallel'
 import { isStallState, LANE_STALLED_EVENT, type LaneStalledEvent, type StallState } from './lane-stalled'
 import { type LaneSnapshot, type SeenSeqs, seenSeqsOf } from './lane-watch'
+import {
+  isProposalState,
+  type ProposalState,
+  WAITING_OBSOLETE_EVENT,
+  type WaitingObsoleteEvent,
+} from './obsolete-proposals'
+import { WAITING_CLOSED_EVENT, type WaitingClosedEvent } from './obsolete-records'
 import { isPlanMissingState, PLAN_MISSING_EVENT, type PlanMissingEvent, type PlanMissingState } from './plan-missing'
 import { emptyPreviewState, isPreviewState, PREVIEW_EVENT, type PreviewEvent, type PreviewState } from './previews'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
@@ -71,6 +78,8 @@ export const WATCH_EVENT = {
   laneStalled: LANE_STALLED_EVENT,
   unlinkedArtifact: UNLINKED_ARTIFACT_EVENT,
   planMissing: PLAN_MISSING_EVENT,
+  waitingClosed: WAITING_CLOSED_EVENT,
+  waitingObsolete: WAITING_OBSOLETE_EVENT,
   approval: APPROVAL_EVENT,
   source: SOURCE_EVENT,
   due: APPOINTMENT_EVENT.due,
@@ -137,6 +146,10 @@ export type WatchState = {
   unlinkedArtifacts: UnlinkedState
   /** Per working lane whose board row links a plan the base ref lacks: the plan last reported as `plan missing on base`. */
   planMissing: PlanMissingState
+  /** The lanes of open waiting points whose directory was missing at the last heartbeat; missing twice in a row, a lane is gone. */
+  waitingMissingLanes: string[]
+  /** Per open waiting point (record id or board row key): the reasons already proposed as `waiting obsolete?`. */
+  waitingProposals: ProposalState
   /** The ids of the approval requests on disk when they were last read, each reported once while it is open. */
   approvals: string[]
   /** Per configured source of `watch.sources`: the entries seen (`[id, fingerprint]`) and the start of a failure streak. */
@@ -207,6 +220,8 @@ export type WatchEvent =
   | LaneStalledEvent
   | UnlinkedArtifactEvent
   | PlanMissingEvent
+  | WaitingClosedEvent
+  | WaitingObsoleteEvent
   | ApprovalEvent
   | SourceEvent
   | AppointmentEvent
@@ -248,6 +263,8 @@ export const emptyWatchState = (): WatchState => ({
   laneStalls: {},
   unlinkedArtifacts: {},
   planMissing: {},
+  waitingMissingLanes: [],
+  waitingProposals: {},
   approvals: [],
   sources: emptySourceState(),
   watchedSources: null,
@@ -304,6 +321,9 @@ const isWatchState = (value: Record<string, unknown>): value is WatchState =>
   isStallState(value.laneStalls) &&
   isUnlinkedState(value.unlinkedArtifacts) &&
   isPlanMissingState(value.planMissing) &&
+  Array.isArray(value.waitingMissingLanes) &&
+  value.waitingMissingLanes.every((lane) => typeof lane === 'string') &&
+  isProposalState(value.waitingProposals) &&
   Array.isArray(value.approvals) &&
   value.approvals.every((id) => typeof id === 'string') &&
   isSourceState(value.sources) &&