jackherd 1.7.1 → 1.8.1

package/src/sync/sync.ts

@@ -2,6 +2,7 @@ import { homedir } from 'node:os'
 import { basename, dirname, join } from 'node:path'
 import { CLAUDE_DIRECTORY, SETTINGS_FILE } from '../claude/paths'
 import type { JackherdConfig } from '../config'
+import { contextSharesTextInTokens } from '../config/context-shares'
 import type { RepositoryFacts } from '../config/detect'
 import { CONFIG_FILE, MANIFEST_FILE, TOOL_DIRECTORY } from '../config/location'
 import { readRepositoryFacts } from '../config/repository-facts'
@@ -41,6 +42,9 @@ import {
 } from './sync-plan'
 import type { SyncResult } from './sync-result'
 
+/** The config with the notes of reading it, and its text in the new form when reading it changed the file's. */
+type ReadConfig = { config: JackherdConfig; notes: string[]; rewrite: string | null }
+
 /** A sync's result with the config it was read from, so a caller can name what the config decided. */
 export type ConfiguredSync = { result: SyncResult; config: JackherdConfig }
 
@@ -97,10 +101,22 @@ const readConfig = async (
   location: string,
   initCommand: string,
   facts?: RepositoryFacts,
-): Promise<{ config: JackherdConfig; notes: string[] }> => {
+): Promise<ReadConfig> => {
   const text = await readRegularFile(toolDirectory, CONFIG_FILE)
   if (text === undefined) throw new Error(`No ${location}/${CONFIG_FILE} found. Run \`${initCommand}\` first.`)
-  return parseConfig(text, location, facts)
+  parseJson(text, CONFIG_FILE, location)
+  const converted = contextSharesTextInTokens(text)
+  const parsed = parseConfig(converted.text, location, facts)
+  return {
+    ...parsed,
+    notes: [...converted.notes, ...parsed.notes],
+    rewrite: converted.text === text ? null : converted.text,
+  }
+}
+
+/** A config file rewritten in the new form is written with the rest of the plan, never before it is validated. */
+const writeConfigRewrite = async (toolDirectory: string, { rewrite }: ReadConfig): Promise<void> => {
+  if (rewrite !== null) await writeFileSafely(toolDirectory, CONFIG_FILE, rewrite, FILE_MODE.regular)
 }
 
 const readManifest = async (toolDirectory: string): Promise<{ manifest: Manifest; text: string | undefined }> => {
@@ -277,7 +293,8 @@ export const syncProjectWithConfig = async (request: SyncRequest): Promise<Confi
   const toolDirectory = join(request.projectRoot, TOOL_DIRECTORY)
   const moved = request.check ? [] : await moveProjectLegacyFiles(request.projectRoot)
   const facts = request.facts ?? readRepositoryFacts(request.projectRoot)
-  const { config, notes } = await readConfig(toolDirectory, TOOL_DIRECTORY, `${CLI_NAME} init`, facts)
+  const read = await readConfig(toolDirectory, TOOL_DIRECTORY, `${CLI_NAME} init`, facts)
+  const { config, notes } = read
   const directories = { claudeDirectory, toolDirectory, locate: inClaudeDirectory(claudeDirectory) }
   const plan = await buildPlan({
     ...directories,
@@ -287,6 +304,7 @@ export const syncProjectWithConfig = async (request: SyncRequest): Promise<Confi
     readHooks: projectHooks(claudeDirectory, request.kit, config),
   })
   const keptDirectoryNotes = request.check ? [] : await applyPlan(directories, plan)
+  if (!request.check) await writeConfigRewrite(toolDirectory, read)
   if (!request.check) await ensureGitignoreLines(request.projectRoot)
   return { result: { ...syncResultOf(plan), notes: [...moved, ...notes, ...keptDirectoryNotes] }, config }
 }
@@ -305,7 +323,8 @@ export const syncGlobalWithConfig = async (request: GlobalSyncRequest): Promise<
   const claudeDirectory = join(request.home, CLAUDE_DIRECTORY)
   const toolDirectory = join(request.home, TOOL_DIRECTORY)
   const moved = await moveGlobalLegacyFiles(request.home, request.configHome)
-  const { config } = await readConfig(toolDirectory, GLOBAL_TOOL_LOCATION, `${CLI_NAME} init --global`)
+  const read = await readConfig(toolDirectory, GLOBAL_TOOL_LOCATION, `${CLI_NAME} init --global`)
+  const { config } = read
   if (config.skillPrefix === '') {
     throw new Error(
       `${GLOBAL_TOOL_LOCATION}/${CONFIG_FILE} has no skillPrefix; a global install needs one (e.g. "kit-") so it cannot shadow project skills`,
@@ -321,8 +340,9 @@ export const syncGlobalWithConfig = async (request: GlobalSyncRequest): Promise<
     overrides: REPOSITORY_TOKENS,
   })
   const keptDirectoryNotes = await applyPlan(directories, plan)
+  await writeConfigRewrite(toolDirectory, read)
   await removeEmptyLegacyDirectories(claudeDirectory)
-  return { result: { ...syncResultOf(plan), notes: [...moved, ...keptDirectoryNotes] }, config }
+  return { result: { ...syncResultOf(plan), notes: [...moved, ...read.notes, ...keptDirectoryNotes] }, config }
 }
 
 export const runGlobalSync = async (request: GlobalSyncRequest): Promise<SyncResult> =>

package/src/terminal/herdr.ts

@@ -1,9 +1,18 @@
 import { herdrBinary } from '../sync/tools'
 import type { AdoptedName, LaneAgent, LaneStatusSource } from './types'
 
-type HerdrAgent = { name?: string; pane_id: string; agent_status: string; agent_session?: unknown; cwd?: unknown }
+type HerdrAgent = {
+  name?: string
+  pane_id: string
+  agent_status: string
+  agent_session?: unknown
+  cwd?: unknown
+  terminal_title_stripped?: unknown
+}
 
 const METADATA_SOURCE = 'pf-plans'
+/** The title Claude Code shows until a session has one of its own. */
+const UNTITLED_SESSION = 'Claude Code'
 
 const isHerdrAgent = (value: unknown): value is HerdrAgent => {
   if (typeof value !== 'object' || value === null) return false
@@ -21,13 +30,23 @@ const sessionOf = ({ agent_session }: HerdrAgent): string | null => {
   return typeof value === 'string' && value !== '' ? value : null
 }
 
-const laneAgentOf = (agent: HerdrAgent, name: string): LaneAgent => ({
-  name,
-  pane: agent.pane_id,
-  status: agent.agent_status,
-  session: sessionOf(agent),
-  cwd: typeof agent.cwd === 'string' ? agent.cwd : null,
-})
+/** The session's own title from the terminal title without its status glyph; null for none or the default one. */
+const titleOf = ({ terminal_title_stripped }: HerdrAgent): string | null => {
+  const title = typeof terminal_title_stripped === 'string' ? terminal_title_stripped.trim() : ''
+  return title === '' || title === UNTITLED_SESSION ? null : title
+}
+
+const laneAgentOf = (agent: HerdrAgent, name: string): LaneAgent => {
+  const title = titleOf(agent)
+  return {
+    name,
+    pane: agent.pane_id,
+    status: agent.agent_status,
+    session: sessionOf(agent),
+    cwd: typeof agent.cwd === 'string' ? agent.cwd : null,
+    ...(title ? { title } : {}),
+  }
+}
 
 /**
  * Reads the JSON of `herdr agent list`; throws on anything else, so a changed format is seen, not guessed.
@@ -55,6 +74,14 @@ export const titleArguments = (pane: string, title: string | null): string[] =>
   ...(title ? ['--title', title] : ['--clear-title']),
 ]
 
+/** Sets the label of a pane, or with null clears it; the pane id goes before the option, as in `titleArguments`. */
+export const renameArguments = (pane: string, label: string | null): string[] => [
+  'pane',
+  'rename',
+  pane,
+  label ?? '--clear',
+]
+
 /** Runs the herdr CLI with these arguments and returns its stdout; throws when it fails. */
 export type HerdrRunner = (args: string[]) => string
 
@@ -76,7 +103,8 @@ export const herdrRunner =
 
 export const runHerdr: HerdrRunner = herdrRunner(process.env)
 
-export const createHerdrLaneStatusSource = (run: HerdrRunner): LaneStatusSource => ({
+/** `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),
   setTitle: (pane, title) => {
     try {
@@ -86,6 +114,14 @@ export const createHerdrLaneStatusSource = (run: HerdrRunner): LaneStatusSource
       return `${pane}: ${error instanceof Error ? error.message : String(error)}`
     }
   },
+  labelOwnPane: (label) => {
+    if (!ownPane) return
+    try {
+      run(renameArguments(ownPane, label))
+    } catch {
+      // The label is decoration: a herdr that cannot be asked must not stop the caller.
+    }
+  },
 })
 
-export const herdrLaneStatusSource = createHerdrLaneStatusSource(runHerdr)
+export const herdrLaneStatusSource = createHerdrLaneStatusSource(runHerdr, process.env.HERDR_PANE_ID)

package/src/terminal/none.ts

@@ -4,4 +4,5 @@ import type { LaneStatusSource } from './types'
 export const noneLaneStatusSource: LaneStatusSource = {
   listAgents: () => [],
   setTitle: () => null,
+  labelOwnPane: () => {},
 }

package/src/terminal/types.ts

@@ -11,9 +11,17 @@ export type AdoptedName = { pane: string; name: string }
 
 /**
  * One agent as a terminal adapter reports it; `pane` identifies where its sidebar title is set, `session` is the
- * id of its Claude Code session (the name of its log), null when the terminal does not say. `cwd` is the directory the agent runs in.
+ * id of its Claude Code session (the name of its log), null when the terminal does not say. `cwd` is the directory the
+ * agent runs in, `title` the title of its session as the terminal shows it, absent when the session has none of its own.
  */
-export type LaneAgent = { name: string; pane: string; status: string; session: string | null; cwd: string | null }
+export type LaneAgent = {
+  name: string
+  pane: string
+  status: string
+  session: string | null
+  cwd: string | null
+  title?: string
+}
 
 /**
  * Where lane agents run. The herd reads agent status and sets a short title per lane through
@@ -27,4 +35,9 @@ export type LaneStatusSource = {
   listAgents: (adopt?: AdoptedName) => LaneAgent[]
   /** Sets, or with null clears, the title of a pane. Returns the error text, or null on success. */
   setTitle: (pane: string, title: string | null) => string | null
+  /**
+   * Labels, or with null unlabels, the pane this process runs in; does nothing where the terminal cannot tell
+   * which pane that is. Never throws: the label is decoration, a failure is dropped.
+   */
+  labelOwnPane: (label: string | null) => void
 }

package/src/update/command.ts

@@ -14,6 +14,7 @@ import { defaultUpdateCheck, lockedVersion } from '../sync/if-changed'
 import { locateKit } from '../sync/kit-source'
 import { readInstalledVersion } from '../version/installed-version'
 import { CLI_NAME } from '../version/release'
+import { rewriteConfigShares } from './config-shares'
 import { detectPackageManager, legacyPackageRoot, shellHostedGlobalRoot } from './package-manager'
 import { runUpdate, UPDATE_EXIT, type UpdateAdapters } from './update'
 
@@ -52,6 +53,7 @@ const adaptersFor = async (): Promise<UpdateAdapters> => {
     home,
     projectRoot: findProjectRoot(process.cwd(), home, existsSync),
     hasProjectKit: (root) => hasProjectInstall(root, existsSync),
+    rewriteConfigShares,
     log: (line) => console.log(line),
   }
 }

package/src/update/config-shares.ts

@@ -0,0 +1,30 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { contextSharesTextInTokens } from '../config/context-shares'
+import { PROJECT_CONFIG_PATH } from '../config/location'
+
+type Converted = { text: string; notes: string[] }
+
+/** The file's text with its shares in tokens; null when it is missing or not JSON, which reading the config names. */
+const converted = (path: string): Converted | null => {
+  if (!existsSync(path)) return null
+  try {
+    return contextSharesTextInTokens(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Writes the context thresholds of `root`'s `.jackherd/config.json` as tokens when the file still gives them as a
+ * share, and returns a line for each block that changed. A project without an install of its own has no sync that
+ * would do it. A missing or unreadable file is left alone: reading the config names that error. A failed write
+ * throws, so `jh update` reports it.
+ */
+export const rewriteConfigShares = (root: string): string[] => {
+  const path = join(root, PROJECT_CONFIG_PATH)
+  const result = converted(path)
+  if (result === null || result.notes.length === 0) return []
+  writeFileSync(path, result.text)
+  return result.notes.map((note) => `${PROJECT_CONFIG_PATH}: ${note}`)
+}

package/src/update/update.ts

@@ -28,6 +28,8 @@ export type UpdateAdapters = {
    * The lock's existence counts, not its validity: a broken lock is synced, and the sync names the error.
    */
   hasProjectKit: (root: string) => boolean
+  /** Writes the context thresholds in the project's config as tokens when they are still a share; returns a line for each change. */
+  rewriteConfigShares: (root: string) => string[]
   log: (line: string) => void
 }
 
@@ -46,6 +48,11 @@ const notInstalledLine = (projectRoot: string): string =>
 const installedProject = (adapters: UpdateAdapters): string | null =>
   adapters.projectRoot && adapters.hasProjectKit(adapters.projectRoot) ? adapters.projectRoot : null
 
+/** Rewrites the context thresholds of a project without an install, which no sync does, and says what changed. */
+const logConfigShares = (adapters: UpdateAdapters, root: string): void => {
+  for (const line of adapters.rewriteConfigShares(root)) adapters.log(line)
+}
+
 /** The syncs that bring `~/.claude` and the project to the new files, in the order they run. */
 const syncSteps = async (
   adapters: UpdateAdapters,
@@ -107,6 +114,7 @@ const updateToLatest = async (adapters: UpdateAdapters, manager: PackageManager)
   const jhWasOnPath = adapters.jhOnPath()
   if (jhWasOnPath && !isNewerVersion(latest, installedVersion)) {
     log(`${CLI_NAME} ${installedVersion} is the latest release.`)
+    if (adapters.projectRoot && !installedProject(adapters)) logConfigShares(adapters, adapters.projectRoot)
     return UPDATE_EXIT.ok
   }
   const installed = await installAndVerify(adapters, manager, latest)
@@ -115,7 +123,10 @@ const updateToLatest = async (adapters: UpdateAdapters, manager: PackageManager)
   const synced = await syncAfterInstall(adapters, project)
   if (synced !== UPDATE_EXIT.ok) return synced
   log(doneLine(adapters, manager, latest, jhWasOnPath))
-  if (adapters.projectRoot && !project) log(notInstalledLine(adapters.projectRoot))
+  if (adapters.projectRoot && !project) {
+    logConfigShares(adapters, adapters.projectRoot)
+    log(notInstalledLine(adapters.projectRoot))
+  }
   return UPDATE_EXIT.ok
 }
 

package/src/vocabulary/index.ts

@@ -38,22 +38,58 @@ export const SELF_MERGE_LABEL: Record<PlanLanguage, string> = {
   [PLAN_LANGUAGE.de]: 'Freigeben, und nach grünen Checks selbst mergen',
 }
 
+/**
+ * The options of the question that approves a plan for all its lanes (``Plan `<path>` ``) and of the one that revokes
+ * that approval. The merge guard hook lifts its question for a plain merge of such a lane only when the newest answer
+ * to a question naming the plan is exactly `approve`, so the labels are fixed per language and not a config value.
+ */
+export const PLAN_APPROVAL_LABELS: Record<PlanLanguage, { approve: string; revoke: string }> = {
+  [PLAN_LANGUAGE.en]: { approve: 'Approve the plan', revoke: 'Revoke the plan approval' },
+  [PLAN_LANGUAGE.de]: { approve: 'Plan freigeben', revoke: 'Plan-Freigabe widerrufen' },
+}
+
+/** What the approval gate hook tells the lane when it denies: jackherd's own words, English in every language. */
+const APPROVAL_REASONS = {
+  pending: 'Approval pending with the coordinator; retry the same call once it is approved.',
+  denied: 'The user denied this call through the coordinator; do not retry it.',
+}
+
 /**
  * The words of an approval: the two option labels of the coordinator's question about a lane's call, which the
- * approval gate hook matches exactly, and what the hook tells the lane when it denies. Fixed per language, not config.
+ * approval gate hook matches exactly and which follow the response language, and what the hook tells the lane when it
+ * denies, which is English. Fixed per language, not config.
  */
 export const APPROVAL_TEXTS: Record<PlanLanguage, { allow: string; deny: string; pending: string; denied: string }> = {
-  [PLAN_LANGUAGE.en]: {
-    allow: 'Allow this call',
-    deny: 'Deny this call',
-    pending: 'Approval pending with the coordinator; retry the same call once it is approved.',
-    denied: 'The user denied this call through the coordinator; do not retry it.',
-  },
+  [PLAN_LANGUAGE.en]: { allow: 'Allow this call', deny: 'Deny this call', ...APPROVAL_REASONS },
+  [PLAN_LANGUAGE.de]: { allow: 'Aufruf erlauben', deny: 'Aufruf ablehnen', ...APPROVAL_REASONS },
+}
+
+/**
+ * The board section of agreed times, which the watcher reads: its heading, the header names of its columns (when,
+ * action, 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
+ * appointment starts with.
+ */
+export const APPOINTMENT_VOCABULARY: Record<
+  PlanLanguage,
+  {
+    heading: string
+    columns: { when: string; action: string; origin: string; status: string }
+    /** Further header names that count as the status column. */
+    statusAlso: readonly string[]
+    open: readonly string[]
+  }
+> = {
   [PLAN_LANGUAGE.de]: {
-    allow: 'Aufruf erlauben',
-    deny: 'Aufruf ablehnen',
-    pending: 'Freigabe steht aus beim Koordinator; denselben Aufruf nach der Freigabe erneut versuchen.',
-    denied: 'Der User hat diesen Aufruf über den Koordinator abgelehnt; nicht erneut versuchen.',
+    heading: 'Termine',
+    columns: { when: 'Wann', action: 'Aktion', origin: 'Herkunft', status: 'Stand' },
+    statusAlso: ['Status'],
+    open: ['offen'],
+  },
+  [PLAN_LANGUAGE.en]: {
+    heading: 'Appointments',
+    columns: { when: 'When', action: 'Action', origin: 'Origin', status: 'Status' },
+    statusAlso: [],
+    open: ['open'],
   },
 }
 
@@ -98,6 +134,8 @@ export type PlanVocabulary = {
   noReviewGate: string
   /** Marks a lane as closed when its name cell contains it. */
   laneClosed: string
+  /** Opens the line a lane's hand-over file must hold as `<word>: 0`, so the coordinator hands over only after a wave. */
+  openSubagents: string
   /** Words a starts-after cell begins with when the lane may start at once. */
   startsNow: readonly string[]
   /** Opens the parenthesis by which a board row's phases cell records a user's side order in prose. */
@@ -133,6 +171,7 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     phase: 'Phase',
     noReviewGate: 'Kein Review-Gate',
     laneClosed: 'abgeräumt',
+    openSubagents: 'offene Sub-Agenten',
     sideOrderMarker: 'dazu (User',
     startsNow: ['sofort'],
     phaseConnectors: ['danach', 'und', 'dann', 'sowie'],
@@ -166,6 +205,7 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     phase: 'Phase',
     noReviewGate: 'No review gate',
     laneClosed: 'cleaned up',
+    openSubagents: 'open subagents',
     sideOrderMarker: 'also (User',
     startsNow: ['now', 'immediately'],
     phaseConnectors: ['then', 'and', 'after'],

package/src/watch/appointments.ts

@@ -0,0 +1,206 @@
+import { firstTableWithHeader, sectionLines } from '../plan-format/markdown'
+import { APPOINTMENT_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { isRecord } from './json-guards'
+
+export const APPOINTMENT_EVENT = { due: 'due', unreadable: 'appointment unreadable' } as const
+
+/** One row of the board's appointment table whose time could be read; `key` is what the watcher remembers it by. */
+export type Appointment = { when: Date; whenText: string; action: string; open: boolean; key: string }
+
+/**
+ * An open row whose time cell could not be read, as written; or a table that lacks a column the watcher reads, with
+ * its header as `whenText` and the missing names as `action`.
+ */
+export type UnreadableAppointment = { whenText: string; action: string }
+
+export type AppointmentTable = { appointments: Appointment[]; unreadable: UnreadableAppointment[] }
+
+/** `when` is the time cell as the board wrote it. */
+export type AppointmentEvent = {
+  kind: (typeof APPOINTMENT_EVENT)[keyof typeof APPOINTMENT_EVENT]
+  when: string
+  action: string
+}
+
+/** The keys of the appointments reported as due and of the unreadable rows reported, each once. */
+export type AppointmentState = { reported: string[]; unreadable: string[] }
+
+type DateParts = { year: number | null; month: number; day: number; hours: number; minutes: number }
+
+const DAY_FIRST = /^(?:\p{L}{2,3}\.?,?\s+)?(\d{1,2})\.(\d{1,2})\.(\d{4})?\s+(\d{1,2}):(\d{2})$/u
+const ISO = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{1,2}):(\d{2})$/
+const KEY_TIME_LENGTH = 'YYYY-MM-DDThh:mm'.length
+const DAY_MS = 86_400_000
+const KEEP_GONE_MS = 7 * DAY_MS
+
+const APPOINTMENT_KINDS: readonly string[] = Object.values(APPOINTMENT_EVENT)
+
+export const isAppointmentEvent = (event: { kind: string }): event is AppointmentEvent =>
+  APPOINTMENT_KINDS.includes(event.kind)
+
+export const emptyAppointmentState = (): AppointmentState => ({ reported: [], unreadable: [] })
+
+const isStringList = (value: unknown): boolean =>
+  Array.isArray(value) && value.every((entry) => typeof entry === 'string')
+
+export const isAppointmentState = (value: unknown): value is AppointmentState =>
+  isRecord(value) && isStringList(value.reported) && isStringList(value.unreadable)
+
+const datePartsOf = (text: string): DateParts | null => {
+  const iso = ISO.exec(text)
+  if (iso) {
+    const [year, month, day, hours, minutes] = iso.slice(1).map(Number)
+    return { year, month, day, hours, minutes }
+  }
+  const dayFirst = DAY_FIRST.exec(text)
+  if (!dayFirst) return null
+  const [day, month, year, hours, minutes] = dayFirst.slice(1).map((part) => (part === undefined ? null : Number(part)))
+  return { year, month: month ?? 0, day: day ?? 0, hours: hours ?? 0, minutes: minutes ?? 0 }
+}
+
+/** The local time of the parts in `year`, or null when the parts name no such time (a 31st of February, hour 24). */
+const localTime = ({ month, day, hours, minutes }: DateParts, year: number): Date | null => {
+  const date = new Date(year, month - 1, day, hours, minutes)
+  const exact =
+    date.getFullYear() === year &&
+    date.getMonth() === month - 1 &&
+    date.getDate() === day &&
+    date.getHours() === hours &&
+    date.getMinutes() === minutes
+  return exact ? date : null
+}
+
+/** Of the previous, the clock's and the next year, the one that puts the date nearest to `now`. */
+const nearestToClock = (parts: DateParts, now: Date): Date | null => {
+  const year = now.getFullYear()
+  const candidates = [year - 1, year, year + 1].flatMap((candidate) => localTime(parts, candidate) ?? [])
+  const distance = (date: Date) => Math.abs(date.getTime() - now.getTime())
+  return candidates.reduce<Date | null>((best, date) => (best && distance(best) <= distance(date) ? best : date), null)
+}
+
+/**
+ * The local time of a board's time cell: `<day name> DD.MM. hh:mm` (the day name is ignored), `DD.MM. hh:mm`,
+ * `DD.MM.YYYY hh:mm`, `YYYY-MM-DD hh:mm`. A year written in the cell wins; without one, the year that puts the date
+ * nearest to `now`, so a January appointment written in December lands in the next year. Null for anything else,
+ * a time of day included: an appointment has a minute.
+ */
+export const parseAppointmentTime = (text: string, now: Date): Date | null => {
+  const parts = datePartsOf(text.trim())
+  if (!parts) return null
+  return parts.year === null ? nearestToClock(parts, now) : localTime(parts, parts.year)
+}
+
+const twoDigits = (value: number): string => String(value).padStart(2, '0')
+
+/** The local time to the minute and the action: a moved appointment gets a new key, a reworded day name does not. */
+export const appointmentKey = (when: Date, action: string): string =>
+  `${when.getFullYear()}-${twoDigits(when.getMonth() + 1)}-${twoDigits(when.getDate())}T${twoDigits(when.getHours())}:${twoDigits(when.getMinutes())} ${action}`
+
+const unreadableKey = ({ whenText, action }: UnreadableAppointment): string => `${whenText} ${action}`
+
+const oneLine = (text: string): string => text.replace(/\s+/g, ' ').trim()
+
+/** An empty status counts as open: a row nobody closed is not dropped in silence. */
+const isOpen = (status: string, language: PlanLanguage): boolean => {
+  const lower = status.toLowerCase()
+  return lower === '' || APPOINTMENT_VOCABULARY[language].open.some((word) => lower.startsWith(word))
+}
+
+/** The row as an appointment, as an unreadable row when it is open and its time cannot be read, else as nothing. */
+const tableOfRow = (
+  cells: string[],
+  [when, action, status]: number[],
+  language: PlanLanguage,
+  now: Date,
+): AppointmentTable => {
+  const whenText = cells[when] ?? ''
+  const actionText = oneLine(cells[action] ?? '')
+  const open = isOpen(cells[status] ?? '', language)
+  const time = parseAppointmentTime(whenText, now)
+  if (time)
+    return {
+      appointments: [{ when: time, whenText, action: actionText, open, key: appointmentKey(time, actionText) }],
+      unreadable: [],
+    }
+  return { appointments: [], unreadable: open ? [{ whenText, action: actionText }] : [] }
+}
+
+/**
+ * The rows of the board's appointment section in `language` (`## Termine`, `## Appointments`), its columns found by
+ * their header names in any order; the origin column is not read. A row whose time cannot be read is not an
+ * appointment; while it is open it is listed as unreadable. A table without the when, action or status column is
+ * listed as unreadable as a whole, with its header and the missing names; a section without a table has no rows.
+ */
+export const readAppointmentTable = (board: string, language: PlanLanguage, now: Date): AppointmentTable => {
+  const { heading, columns, statusAlso } = APPOINTMENT_VOCABULARY[language]
+  const { header, rows } = firstTableWithHeader(sectionLines(board, heading))
+  if (header.length === 0) return { appointments: [], unreadable: [] }
+  const statusName = [columns.status, ...statusAlso].find((name) => header.includes(name)) ?? columns.status
+  const needed = [columns.when, columns.action, statusName]
+  const missing = needed.filter((name) => !header.includes(name))
+  if (missing.length > 0)
+    return {
+      appointments: [],
+      unreadable: [{ whenText: header.join(' | '), action: `missing columns: ${missing.join(', ')}` }],
+    }
+  const positions = needed.map((name) => header.indexOf(name))
+  const tables = rows.map((cells) => tableOfRow(cells, positions, language, now))
+  return {
+    appointments: tables.flatMap(({ appointments }) => appointments),
+    unreadable: tables.flatMap(({ unreadable }) => unreadable),
+  }
+}
+
+const dueAppointments = (state: AppointmentState, table: AppointmentTable, now: number): Appointment[] =>
+  table.appointments
+    .filter(({ open, when, key }) => open && when.getTime() <= now && !state.reported.includes(key))
+    .sort((left, right) => left.when.getTime() - right.when.getTime())
+
+/**
+ * The open appointments due at `now` that were not reported yet, by time, then the open rows whose time could not be
+ * read and were not reported yet. Due means from its time on, however long ago: one that fell due while the watcher
+ * was down fires at the next run. No table read, no event.
+ */
+export const appointmentEvents = (
+  state: AppointmentState,
+  table: AppointmentTable | null,
+  now: number,
+): AppointmentEvent[] => {
+  if (!table) return []
+  const due = dueAppointments(state, table, now).map(({ whenText, action }) => ({
+    kind: APPOINTMENT_EVENT.due,
+    when: whenText,
+    action,
+  }))
+  const unreadable = table.unreadable
+    .filter((row) => !state.unreadable.includes(unreadableKey(row)))
+    .map(({ whenText, action }) => ({ kind: APPOINTMENT_EVENT.unreadable, when: whenText, action }))
+  return [...due, ...unreadable]
+}
+
+/** Whether a key's time lies within the last week; a key that does not start with a time does not. */
+const isRecent = (key: string, now: number): boolean => {
+  const when = parseAppointmentTime(key.slice(0, KEY_TIME_LENGTH), new Date(now))
+  return when !== null && now - when.getTime() <= KEEP_GONE_MS
+}
+
+/**
+ * The state after `appointmentEvents` were reported: the due keys added. A reported key stays while its row is in
+ * the table, open or done, and for a week after its time once the row is gone, so a board read halfway through an
+ * edit does not report it twice. Unreadable rows are remembered while they stay unreadable. No table read keeps the
+ * state as it was.
+ */
+export const recordAppointments = (
+  state: AppointmentState,
+  table: AppointmentTable | null,
+  now: number,
+): AppointmentState => {
+  if (!table) return state
+  const present = new Set(table.appointments.map(({ key }) => key))
+  const kept = state.reported.filter((key) => present.has(key) || isRecent(key, now))
+  const due = dueAppointments(state, table, now).map(({ key }) => key)
+  return {
+    reported: [...new Set([...kept, ...due])],
+    unreadable: table.unreadable.map(unreadableKey),
+  }
+}