jackherd 1.8.1 → 1.10.0

package/src/task-signals/matcher.ts

@@ -0,0 +1,96 @@
+import { MAX_TASK_TEXT } from './text'
+import type { TaskSignal } from './types'
+
+/** An open task of a plan: where it stands (`phaseId`, index among the phase's items) and its text. */
+export type OpenPlanTask = { phaseId: string; taskIndex: number; text: string }
+
+export type MatchedSignal = { signal: TaskSignal; task: OpenPlanTask | null }
+
+/** Shorter than this, a text names nothing: it would match any task. */
+const MIN_TEXT = 4
+/** A whole plan task found inside a longer signal must be this long, or "Tests" claims every signal about tests. */
+const MIN_TASK_INSIDE_SIGNAL = 12
+/** Shorter words (`PR`, `und`, `die`, numbers) carry no meaning for similar wording. */
+const MIN_WORD = 4
+/** Two forms of one word share at least this many letters from the start. */
+const MIN_STEM = 4
+/** And differ in at most this many letters at the end of the shorter one: German endings, `-en`, `-er`, `-e`. */
+const MAX_ENDING = 2
+/** Similar wording needs this many of the signal's words in the task, so two shared words claim nothing. */
+const MIN_SIMILAR_WORDS = 3
+/** And this share of them. */
+const MIN_SIMILAR_SHARE = 0.75
+
+const normalised = (text: string): string =>
+  text
+    .toLowerCase()
+    .replace(/[^\p{L}\p{N}]+/gu, ' ')
+    .trim()
+
+const headOf = (task: OpenPlanTask): string => task.text.slice(0, MAX_TASK_TEXT)
+
+const isPrefix = (signalText: string, task: OpenPlanTask): boolean =>
+  signalText.length >= MIN_TEXT && headOf(task).startsWith(signalText)
+
+const isContained = (signalText: string, task: OpenPlanTask): boolean => {
+  const signal = normalised(signalText)
+  const head = normalised(headOf(task))
+  if (signal.length < MIN_TEXT) return false
+  return head.includes(signal) || (head.length >= MIN_TASK_INSIDE_SIGNAL && signal.includes(head))
+}
+
+const wordsOf = (text: string): string[] =>
+  normalised(text)
+    .split(' ')
+    .filter((word) => word.length >= MIN_WORD)
+
+const commonPrefix = (first: string, second: string): number => {
+  let length = 0
+  while (length < first.length && first[length] === second[length]) length += 1
+  return length
+}
+
+/** One word, two forms: equal, or the same stem with a short ending of its own (`roter`, `roten`; `kompakter`, `kompaktere`). */
+const sameWord = (first: string, second: string): boolean => {
+  const shared = commonPrefix(first, second)
+  return first === second || (shared >= MIN_STEM && shared >= Math.min(first.length, second.length) - MAX_ENDING)
+}
+
+/** How many of the signal's words the task's head holds, and their share of the signal's words. */
+const similarity = (signalWords: readonly string[], task: OpenPlanTask): { matched: number; share: number } => {
+  const taskWords = wordsOf(headOf(task))
+  const matched = signalWords.filter((word) => taskWords.some((each) => sameWord(word, each))).length
+  return { matched, share: signalWords.length === 0 ? 0 : matched / signalWords.length }
+}
+
+/**
+ * The task whose head holds most of the signal's words, each in any inflected form, when at least `MIN_SIMILAR_WORDS`
+ * and `MIN_SIMILAR_SHARE` of them; null otherwise. For an agent that names a task in its own words.
+ */
+const similarTask = (tasks: readonly OpenPlanTask[], signalText: string): OpenPlanTask | null => {
+  const signalWords = [...new Set(wordsOf(signalText))]
+  const scored = tasks
+    .map((task) => ({ task, ...similarity(signalWords, task) }))
+    .filter(({ matched, share }) => matched >= MIN_SIMILAR_WORDS && share >= MIN_SIMILAR_SHARE)
+  return (
+    scored.reduce<(typeof scored)[number] | null>(
+      (best, each) => (best === null || each.share > best.share ? each : best),
+      null,
+    )?.task ?? null
+  )
+}
+
+/**
+ * The plan task each signal belongs to, else null (an unplanned task). An exact prefix of a task's text wins over text
+ * containment (case, punctuation and spacing ignored, in either direction, on the first 200 characters of the task),
+ * and containment over similar wording (`similarTask`). Several signals may match several tasks of several phases,
+ * and several signals the same task.
+ */
+export const matchSignals = (tasks: readonly OpenPlanTask[], signals: readonly TaskSignal[]): MatchedSignal[] =>
+  signals.map((signal) => ({
+    signal,
+    task:
+      tasks.find((task) => isPrefix(signal.text, task)) ??
+      tasks.find((task) => isContained(signal.text, task)) ??
+      similarTask(tasks, signal.text),
+  }))

package/src/task-signals/record-store.ts

@@ -0,0 +1,40 @@
+import { join } from 'node:path'
+import { readRecords, writeRecordAtomically } from '../shared/private-records'
+import { isTaskRecord, namesTask, openRecord, type TaskRecord } from './record'
+import { cleanAgentName } from './text'
+
+const directoryOf = (root: string): string => join(root, '.jackherd', 'tasks')
+
+/** Every well-formed record in the main checkout's `.jackherd/tasks/`, oldest first; nothing when the directory is missing. */
+export const readTaskRecords = (root: string): TaskRecord[] =>
+  readRecords(directoryOf(root), isTaskRecord, ({ startedAt }) => startedAt)
+
+/** The agent's open record, null when it has none. */
+export const openTaskOf = (root: string, agent: string): TaskRecord | null => {
+  const wanted = cleanAgentName(agent)
+  return readTaskRecords(root).find((record) => record.agent === wanted && record.closedAt === null) ?? null
+}
+
+/** Starts a task for `agent`. The agent's one record is reused (its id kept) and reopened with the new task. */
+export const startTask = (
+  root: string,
+  fields: { agent: string; text: string; cwd: string; newId: () => string },
+  now: number,
+): TaskRecord => {
+  const previous = readTaskRecords(root).find(({ agent }) => agent === cleanAgentName(fields.agent))
+  const record = openRecord({ ...fields, id: previous?.id ?? fields.newId() }, now)
+  writeRecordAtomically(directoryOf(root), record)
+  return record
+}
+
+/**
+ * Closes the agent's open task; with `text`, only when it names that task. Returns the closed record, or null when
+ * the agent has no open task or the text names another.
+ */
+export const finishTask = (root: string, agent: string, text: string, now: number): TaskRecord | null => {
+  const open = openTaskOf(root, agent)
+  if (!open || !namesTask(open, text)) return null
+  const closed = { ...open, closedAt: now }
+  writeRecordAtomically(directoryOf(root), closed)
+  return closed
+}

package/src/task-signals/record.ts

@@ -0,0 +1,68 @@
+import { isRecord } from '../shared/is-record'
+import { cleanAgentName, cleanTaskText, MAX_TASK_TEXT } from './text'
+import type { TaskSignal } from './types'
+
+/** What `jh task start` stores in `.jackherd/tasks/<id>.json`: one record per agent, closed by `jh task done`. */
+export type TaskRecord = {
+  id: string
+  agent: string
+  text: string
+  startedAt: number
+  cwd: string
+  closedAt: number | null
+}
+
+const ID = /^[0-9a-f]{12}$/
+const ID_BYTES = 6
+
+/** The id of a record from random bytes the caller drew, so a test reaches the drawing; 12 hex characters. */
+export const buildTaskId = (randomBytes: Uint8Array): string =>
+  [...randomBytes.slice(0, ID_BYTES)].map((byte) => byte.toString(16).padStart(2, '0')).join('')
+
+export const isTaskRecord = (value: unknown): value is TaskRecord => {
+  if (!isRecord(value)) return false
+  const record = value
+  return (
+    typeof record.id === 'string' &&
+    ID.test(record.id) &&
+    typeof record.agent === 'string' &&
+    typeof record.text === 'string' &&
+    record.text.length <= MAX_TASK_TEXT &&
+    typeof record.startedAt === 'number' &&
+    typeof record.cwd === 'string' &&
+    (record.closedAt === null || typeof record.closedAt === 'number')
+  )
+}
+
+/** A fresh open record; the text and the agent name are cleaned here, whoever wrote them. */
+export const openRecord = (
+  fields: { id: string; agent: string; text: string; cwd: string },
+  now: number,
+): TaskRecord => ({
+  id: fields.id,
+  agent: cleanAgentName(fields.agent),
+  text: cleanTaskText(fields.text),
+  startedAt: now,
+  cwd: fields.cwd,
+  closedAt: null,
+})
+
+/** Whether `text` names the record's task: empty text names any, else it is the start of the record's text. */
+export const namesTask = (record: TaskRecord, text: string): boolean => {
+  const wanted = cleanTaskText(text)
+  return wanted === '' || record.text.startsWith(wanted)
+}
+
+/** The open records as signals; a record cleaned on write is cleaned again on read, as a hand-written file may differ. */
+export const recordSignals = (records: readonly TaskRecord[]): TaskSignal[] =>
+  records
+    .filter(({ closedAt }) => closedAt === null)
+    .map(({ agent, text, startedAt, cwd }) => ({
+      agent: cleanAgentName(agent),
+      source: 'jh' as const,
+      text: cleanTaskText(text),
+      startedAt,
+      cwd,
+    }))
+    .filter(({ text }) => text !== '')
+    .sort((left, right) => left.startedAt - right.startedAt)

package/src/task-signals/text.ts

@@ -0,0 +1,13 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+
+/** The longest task text a signal carries; a plan task is matched on its first 200 characters as well. */
+export const MAX_TASK_TEXT = 200
+const MAX_AGENT_NAME = 100
+
+const capped = (text: string, max: number): string => terminalSafe(text.replace(/\s+/g, ' ')).trim().slice(0, max)
+
+/** Agent-written task text made safe to store and print: no control characters, one line, at most 200 characters. */
+export const cleanTaskText = (text: string): string => capped(text, MAX_TASK_TEXT)
+
+/** The same for the name of an agent. */
+export const cleanAgentName = (name: string): string => capped(name, MAX_AGENT_NAME)

package/src/task-signals/types.ts

@@ -0,0 +1,14 @@
+/** Who reported a task: Claude Code's task list, Codex's plan tool, or `jh task start`. */
+export type TaskSource = 'claude' | 'codex' | 'jh'
+
+/**
+ * One task an agent is working on right now. `agent` names the session or subagent that reported it, `startedAt` is
+ * epoch milliseconds, `cwd` the directory the agent worked in (its worktree tells the lane).
+ */
+export type TaskSignal = {
+  agent: string
+  source: TaskSource
+  text: string
+  startedAt: number
+  cwd: string
+}

package/src/terminal/open.ts

@@ -5,10 +5,16 @@ export type OpenEnvironment = {
   start: (command: string, args: string[]) => void
 }
 
-const OPENERS: Partial<Record<NodeJS.Platform, string>> = { darwin: 'open', linux: 'xdg-open' }
+const OPENERS: Partial<Record<NodeJS.Platform, (target: string) => string[]>> = {
+  darwin: (target) => ['open', target],
+  linux: (target) => ['xdg-open', target],
+  /** Not `cmd /c start`: cmd reads `&`, `|`, `%` and `^` in the target as its own syntax; rundll32 takes it as one argument. */
+  win32: (target) => ['rundll32', 'url.dll,FileProtocolHandler', target],
+}
 
-/** The command that opens a file or a link in the default application of the platform, null when there is none. */
-export const openerFor = (platform: NodeJS.Platform): string | null => OPENERS[platform] ?? null
+/** The command and arguments that open a file or a link in the default application of the platform, null when there is none. */
+export const openCommandFor = (platform: NodeJS.Platform, target: string): string[] | null =>
+  OPENERS[platform]?.(target) ?? null
 
 /** Linux opens things in a graphical session only; elsewhere the platform's opener is assumed to work. */
 export const hasDisplay = ({ platform, env }: Pick<OpenEnvironment, 'platform' | 'env'>): boolean =>
@@ -27,11 +33,12 @@ const systemEnvironment = (): OpenEnvironment => ({
  * opener for the platform, no display, the opener could not be started), null when it was started.
  */
 export const openInBrowser = (target: string, environment: OpenEnvironment = systemEnvironment()): string | null => {
-  const opener = openerFor(environment.platform)
-  if (!opener) return `no way to open ${target} on ${environment.platform}`
+  const command = openCommandFor(environment.platform, target)
+  if (!command) return `no way to open ${target} on ${environment.platform}`
   if (!hasDisplay(environment)) return 'no display'
+  const [opener, ...args] = command
   try {
-    environment.start(opener, [target])
+    environment.start(opener, args)
     return null
   } catch (error) {
     return `${opener} ${target}: ${error instanceof Error ? error.message : String(error)}`

package/src/terminal/text.ts

@@ -34,6 +34,13 @@ const FAINT_OFF = `${ESC}[22m`
 const BAR_WIDTH = 10
 
 const style = (code: string) => (text: string) => `${ESC}[${code}m${text}${RESET}`
+const BRAND_TEAL_TRUE_COLOUR = '38;2;3;181;189'
+const BRAND_TEAL_256 = '38;5;37'
+
+/** The brand teal `#03B5BD` as true colour where `COLORTERM` says `truecolor` or `24bit`, else 256-colour 37. */
+export const tealCodeOf = (env: Record<string, string | undefined>): string =>
+  env.COLORTERM === 'truecolor' || env.COLORTERM === '24bit' ? BRAND_TEAL_TRUE_COLOUR : BRAND_TEAL_256
+
 export const paint = {
   bold: style('1'),
   dim: style('2'),
@@ -41,7 +48,7 @@ export const paint = {
   green: style('32'),
   yellow: style('33'),
   magenta: style('35'),
-  teal: style('38;5;37'),
+  teal: style(tealCodeOf(process.env)),
   cyan: style('36'),
   inverse: style('7'),
 }
@@ -71,9 +78,14 @@ export const badge = (url: string, text: string, hint = '', tone: BadgeTone = BA
 /** `text` as a badge without a link, for what no click opens: the background of `tone`, a cell of padding either side. */
 export const box = (text: string, tone: BadgeTone = BADGE_TONE.grey): string => `${ESC}[${tone}m ${text} ${RESET}`
 
-/** A line for output that is not a terminal: styling dropped, each link written out as `text (url)`. */
-export const plainText = (text: string): string =>
-  stripAnsi(text.replace(LINK, (_, url, inner) => `${stripAnsi(inner)} (${url})`))
+/**
+ * A line for output that is not a terminal: styling dropped, each link written out as `text (url)`, except the
+ * ones `writesAddress` refuses, which keep the bare text.
+ */
+export const plainText = (text: string, writesAddress: (url: string) => boolean = () => true): string =>
+  stripAnsi(
+    text.replace(LINK, (_, url, inner) => (writesAddress(url) ? `${stripAnsi(inner)} (${url})` : stripAnsi(inner))),
+  )
 
 /** The terminal cells a styled line takes: emoji count two. */
 export const visibleLength = (text: string): number => textWidth(stripAnsi(text))

package/src/terminal/width.ts

@@ -1,4 +1,5 @@
 const VARIATION_SELECTOR = 0xfe0f
+const TEXT_SELECTOR = 0xfe0e
 const ZERO_WIDTH_JOINER = 0x200d
 const COMBINING_MARKS: readonly [number, number][] = [[0x0300, 0x036f]]
 
@@ -59,7 +60,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 === VARIATION_SELECTOR || codePoint === ZERO_WIDTH_JOINER) return 0
+  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
 }

package/src/version/skill-diff.ts

@@ -6,6 +6,19 @@ export type SkillChange =
   | { kind: typeof SKILL_CHANGE.unchanged }
   | { kind: typeof SKILL_CHANGE.unavailable; reason: string }
 
+/** How a reference file of the orchestrate skill differs between the kit at the start and the kit now. */
+export const REFERENCE_CHANGE = { changed: 'changed', added: 'added', deleted: 'deleted' } as const
+
+type ReferenceChangeKind = (typeof REFERENCE_CHANGE)[keyof typeof REFERENCE_CHANGE]
+
+/** A reference that differs, before the diff is written or the path known. */
+export type ReferenceDelta = { name: string; kind: ReferenceChangeKind }
+
+export type ReferenceChange =
+  | { name: string; kind: typeof REFERENCE_CHANGE.changed; diffPath: string | null }
+  | { name: string; kind: typeof REFERENCE_CHANGE.added; path: string }
+  | { name: string; kind: typeof REFERENCE_CHANGE.deleted }
+
 const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/
 const SECTION_HEADING = /^## (.+)$/
 const NUMBERED_SECTION = /^(\d+)\.\s/
@@ -61,3 +74,36 @@ export const skillChangeLine = (change: SkillChange): string => {
   if (change.kind === SKILL_CHANGE.unchanged) return 'orchestrate skill unchanged'
   return `orchestrate skill diff unavailable (${change.reason}): read the skill again`
 }
+
+const deltaOf = (name: string, before: string | undefined, after: string | undefined): ReferenceDelta[] => {
+  if (before === after) return []
+  if (before === undefined) return [{ name, kind: REFERENCE_CHANGE.added }]
+  return [{ name, kind: after === undefined ? REFERENCE_CHANGE.deleted : REFERENCE_CHANGE.changed }]
+}
+
+/** The references (file name → text) that changed, are new or are gone, by name; unchanged ones are left out. */
+export const referenceChanges = (
+  before: Readonly<Record<string, string>>,
+  after: Readonly<Record<string, string>>,
+): ReferenceDelta[] =>
+  [...new Set([...Object.keys(before), ...Object.keys(after)])]
+    .sort()
+    .flatMap((name) => deltaOf(name, before[name], after[name]))
+
+export const referenceChangeLine = (change: ReferenceChange): string => {
+  const head = `orchestrate reference ${change.name}`
+  if (change.kind === REFERENCE_CHANGE.deleted) return `${head} deleted`
+  if (change.kind === REFERENCE_CHANGE.added) return `${head} new · read ${change.path}`
+  return change.diffPath === null
+    ? `${head} changed · diff unavailable: read it again`
+    : `${head} changed · diff ${change.diffPath}`
+}
+
+/**
+ * The lines about the orchestrate skill after a kit update: the skill's own, then one per reference that changed. An
+ * unchanged skill is named only when no reference changed either, so a quiet update stays one line.
+ */
+export const orchestrateChangeLines = (skill: SkillChange, references: readonly ReferenceChange[]): string[] => {
+  if (skill.kind === SKILL_CHANGE.unchanged && references.length > 0) return references.map(referenceChangeLine)
+  return [skillChangeLine(skill), ...references.map(referenceChangeLine)]
+}

package/src/vocabulary/index.ts

@@ -39,13 +39,23 @@ export const SELF_MERGE_LABEL: Record<PlanLanguage, string> = {
 }
 
 /**
- * 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.
+ * The standing approval: the option that approves (`approve`) and the word between the plan and the end in its
+ * question (``Plan `<path>` <until> <YYYY-MM-DD HH:MM>``). The merge guard hook lifts its question for a plain merge of
+ * that plan's lanes only when the newest answer to such a question is exactly `approve`, so both 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' },
+export const STANDING_APPROVAL_TEXTS: Record<PlanLanguage, { approve: string; until: string }> = {
+  [PLAN_LANGUAGE.en]: { approve: 'Approve standing', until: 'until' },
+  [PLAN_LANGUAGE.de]: { approve: 'Stehend freigeben', until: 'bis' },
+}
+
+/**
+ * The words a lane prompt opens with, followed by the lane's name. The ask hint hook and the project's lane exception
+ * recognise a lane by them, so they are fixed per language and not a config value.
+ */
+export const LANE_PROMPT_OPENING: Record<PlanLanguage, string> = {
+  [PLAN_LANGUAGE.en]: 'You are the lane',
+  [PLAN_LANGUAGE.de]: 'Du bist die Spur',
 }
 
 /** What the approval gate hook tells the lane when it denies: jackherd's own words, English in every language. */
@@ -93,6 +103,34 @@ export const APPOINTMENT_VOCABULARY: Record<
   },
 }
 
+/**
+ * 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.
+ */
+export const WAITING_VOCABULARY: Record<
+  PlanLanguage,
+  {
+    heading: string
+    columns: { since: string; item: string; origin: 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' },
+    statusAlso: ['Status'],
+    open: ['offen'],
+  },
+  [PLAN_LANGUAGE.en]: {
+    heading: 'Waiting for you',
+    columns: { since: 'Since', item: 'Item', origin: 'Origin', status: 'Status' },
+    statusAlso: [],
+    open: ['open'],
+  },
+}
+
 export const isPlanLanguage = (value: string): value is PlanLanguage =>
   (Object.values(PLAN_LANGUAGE) as string[]).includes(value)
 

package/src/waiting/command.ts

@@ -0,0 +1,50 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import type { WaitingItem } from '../plan-format/waiting'
+import { mainCheckout } from '../plans/git'
+import { closeAllQuestionRecords, closeQuestionRecords } from '../plans/questions-read'
+import { closeAllSentRecords, closeSentRecords } from '../plans/sent-files-read'
+import { recordWaitingItems } from '../plans/waiting-records'
+import { CLI_NAME } from '../version/release'
+
+const USAGE = `usage: ${CLI_NAME} waiting [close <id> ... | close --all]`
+
+/** The lines `jh waiting` prints: id, time and text of each item, made safe for the terminal; a note when none waits. */
+export const waitingListing = (items: readonly WaitingItem[]): string[] =>
+  items.length === 0
+    ? ['nothing waits on you']
+    : items.map(({ since, item, id }) => terminalSafe(`${id} · ${since} · ${item}`))
+
+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 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)
+
+/**
+ * `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.
+ */
+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()))) console.log(line)
+    return 0
+  }
+  const [command, ...rest] = args
+  if (command !== 'close' || rest.length === 0) {
+    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())
+  console.log(`closed ${closed}`)
+  return 0
+}

package/src/watch/appointments.ts

@@ -1,6 +1,7 @@
+import { DAY_MS, twoDigits } from '../plan-format/clock'
 import { firstTableWithHeader, sectionLines } from '../plan-format/markdown'
+import { isRecord } from '../shared/is-record'
 import { APPOINTMENT_VOCABULARY, type PlanLanguage } from '../vocabulary'
-import { isRecord } from './json-guards'
 
 export const APPOINTMENT_EVENT = { due: 'due', unreadable: 'appointment unreadable' } as const
 
@@ -30,7 +31,6 @@ type DateParts = { year: number | null; month: number; day: number; hours: numbe
 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)
@@ -90,8 +90,6 @@ export const parseAppointmentTime = (text: string, now: Date): Date | 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}`

package/src/watch/approvals.ts

@@ -1,6 +1,7 @@
 import { existsSync, readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
-import { isRecord } from './json-guards'
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { isRecord } from '../shared/is-record'
 
 export const APPROVAL_EVENT = 'approval'
 
@@ -49,7 +50,6 @@ export const isApprovalRequestFile = (value: unknown): value is ApprovalRequestF
   (value.usedAt === null || typeof value.usedAt === 'number')
 
 const REPORT_MINUTES = 30
-const MS_PER_MINUTE = 60_000
 
 /** One event per open request younger than 30 minutes the watcher has not reported yet; an older one is stale. */
 export const approvalEvents = (

package/src/watch/asking-lanes.ts

@@ -0,0 +1,40 @@
+import { questionSections } from './report-questions'
+
+/** The questions sections of a report as one string; empty without a report or without an open question. */
+export const questionsFingerprint = (text: string | null): string => {
+  if (text === null) return ''
+  const lines = text.split('\n')
+  return questionSections(lines)
+    .map(({ start, end }) => lines.slice(start, end).join('\n'))
+    .join('\n')
+}
+
+/**
+ * The working lanes whose report asks something other than what was last remembered for them (`current` and
+ * `remembered` are fingerprints per lane): a lane waiting on its background subagents ends no turn, so its question
+ * would wait for them. A lane without a remembered entry is unseen and asks nothing; its report is the baseline.
+ */
+export const askingLanes = (
+  working: readonly string[],
+  current: Readonly<Record<string, string>>,
+  remembered: Readonly<Record<string, string>>,
+): string[] =>
+  working.filter((lane) => lane in remembered && (current[lane] ?? '') !== '' && current[lane] !== remembered[lane])
+
+/**
+ * The fingerprints to remember for the watched lanes (the keys of `current`): a lane whose report was `shown`, that
+ * asks nothing now or is seen for the first time takes what it has now; any other keeps what it had, so a question
+ * not yet shown still fires. A lane no longer watched is forgotten.
+ */
+export const recordReportQuestions = (
+  remembered: Readonly<Record<string, string>>,
+  current: Readonly<Record<string, string>>,
+  shown: readonly string[],
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(current).map(([lane, questions]) => {
+      const kept = remembered[lane]
+      const takesCurrent = kept === undefined || questions === '' || shown.includes(lane)
+      return [lane, takesCurrent ? questions : kept]
+    }),
+  )

package/src/watch/base-tip.ts

@@ -1,3 +1,5 @@
+import { pullHeadRef } from '../plans/plan-heads'
+
 const COMMIT = /^[0-9a-f]{40}$/
 
 /** The commit of `refs/heads/<branch>` in a `git ls-remote` answer; null when it is not listed. */
@@ -16,3 +18,12 @@ export const remoteTipOf = (lsRemote: string, branch: string): string | null =>
  */
 export const baseFetchNeeded = (remoteTip: string | null, localTip: string | null): boolean =>
   remoteTip !== null && remoteTip !== localTip
+
+/**
+ * The pull requests whose head moved past the herd's ref of it (`pullHeadRef`), or that have none yet: the
+ * watcher's list carries each head commit, so an unchanged head costs no fetch.
+ */
+export const movedHeads = <Head extends { number: number; headCommit: string }>(
+  heads: readonly Head[],
+  localCommitOf: (ref: string) => string | null,
+): Head[] => heads.filter(({ number, headCommit }) => baseFetchNeeded(headCommit, localCommitOf(pullHeadRef(number))))