jackherd 1.16.0 → 1.17.0

package/src/watch/config-reload.ts

@@ -0,0 +1,119 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import { locateConfigFile, PROJECT_CONFIG_PATH } from '../config/location'
+import { type ResolvedConfig, readResolvedConfig } from '../config/read-config'
+import { readRepositoryIdentity } from '../config/repository-identity'
+import type { JackherdConfig } from '../config/schema'
+import {
+  type FileStamps,
+  type LoadedSources,
+  nextLoadedSources,
+  type ReadFailure,
+  readWatchedSources,
+  reasonOf,
+} from './source-reload'
+import type { SourceSettings } from './sources'
+import type { WorkflowRun } from './workflow-runs'
+
+/** What a line starts with when a changed config left the values as they were. */
+export const CONFIG_NOT_RELOADED = 'config not reloaded:'
+
+/** The parts of `watch` the loop takes up while it runs, in the order a reload names them. */
+const LIVE_PARTS = ['deploy', 'feedback', 'previews', 'checks'] as const
+
+export type LivePart = (typeof LIVE_PARTS)[number]
+
+/** The values of `watch` that change while the watcher runs: what it reports and how it reads it. */
+export type LiveValues = Pick<JackherdConfig['watch'], LivePart>
+
+/** The sources and the live values the watcher runs; the change times of their files travel with `sources`. */
+export type LoadedConfig = { sources: LoadedSources; live: LiveValues }
+
+/** One read of the repository config and the personal file: the live values and merged sources with the notes, or the line naming the file that failed. */
+export type ConfigRead = { ok: true; live: LiveValues; sources: SourceSettings[]; notes: string[] } | ReadFailure
+
+/** What a reload starts counting from: runs and heads that existed before it are the baseline, not news. */
+export type Baselines = { deploy: boolean; previews: boolean }
+
+export const liveValuesOf = (config: JackherdConfig): LiveValues => ({
+  deploy: config.watch.deploy,
+  feedback: config.watch.feedback,
+  previews: config.watch.previews,
+  checks: config.watch.checks,
+})
+
+/** The parts of `next` that differ from `previous` by value. */
+export const changedParts = (previous: LiveValues, next: LiveValues): LivePart[] =>
+  LIVE_PARTS.filter((part) => !isDeepStrictEqual(previous[part], next[part]))
+
+/**
+ * Whether the reload starts a baseline: a deploy workflow that is new or another one (a removed `deploy` reports
+ * nothing anyway), and previews that were off before. A change of the environments or of the preview authors keeps
+ * what the watcher has recorded.
+ */
+export const baselinesOf = (previous: LiveValues, next: LiveValues): Baselines => ({
+  deploy: next.deploy !== undefined && next.deploy.workflow !== previous.deploy?.workflow,
+  previews: next.previews !== undefined && previous.previews === undefined,
+})
+
+/** The runs created at or after `since`, all of them while there is no baseline (null). */
+export const withoutRunsBefore = (runs: WorkflowRun[], since: number | null): WorkflowRun[] =>
+  since === null ? runs : runs.filter((run) => Date.parse(run.createdAt) >= since)
+
+const configPathOf = (roots: string[], home: string): string =>
+  locateConfigFile(roots, home, existsSync) ?? join(roots[0] ?? home, PROJECT_CONFIG_PATH)
+
+const readRepositoryConfig = (
+  roots: string[],
+  home: string,
+  path: string,
+): { ok: true; resolved: ResolvedConfig } | ReadFailure => {
+  try {
+    return { ok: true, resolved: readResolvedConfig(roots, home) }
+  } catch (error) {
+    return { ok: false, line: `${CONFIG_NOT_RELOADED} ${path}: ${reasonOf(path, error)}` }
+  }
+}
+
+/**
+ * Reads the repository config once (`readResolvedConfig` finds it in `roots`) and the personal sources of `home`:
+ * the live values and the merged sources, for the repository `origin` of the last of `roots` (the main checkout)
+ * names (`readRepositoryIdentity`). An invalid or missing config is the line `config not reloaded:` with its
+ * file and reason; an invalid personal file keeps the whole reading back (`readWatchedSources`).
+ */
+export const readWatchedConfig = (roots: string[], home: string): ConfigRead => {
+  const path = configPathOf(roots, home)
+  const repository = readRepositoryConfig(roots, home, path)
+  if (!repository.ok) return repository
+  const { config, notes } = repository.resolved
+  const mainRoot = roots.at(-1)
+  const identity = mainRoot === undefined ? null : readRepositoryIdentity(mainRoot)
+  const sources = readWatchedSources({ path, read: () => config.watch.sources }, home, identity)
+  return sources.ok
+    ? { ok: true, live: liveValuesOf(config), sources: sources.sources, notes: [...notes, ...sources.notes] }
+    : sources
+}
+
+/**
+ * The config after one cycle: with the stamps as they were, as it was and without a read; after a change, what `read`
+ * gives, with `config reloaded: <parts>` when live values differ; when a changed file is invalid, everything as it was
+ * and the line naming the file. The new stamps are taken either way, so one change reports once.
+ */
+export const nextLoadedConfig = (
+  previous: LoadedConfig,
+  stamps: FileStamps,
+  read: () => ConfigRead,
+): { loaded: LoadedConfig; lines: string[] } => {
+  const taken: { live?: LiveValues } = {}
+  const sources = nextLoadedSources(previous.sources, stamps, () => {
+    const result = read()
+    if (!result.ok) return result
+    taken.live = result.live
+    return { ok: true, sources: result.sources, notes: result.notes }
+  })
+  const live = taken.live ?? previous.live
+  const changed = changedParts(previous.live, live)
+  const lines = changed.length > 0 ? [...sources.lines, `config reloaded: ${changed.join(', ')}`] : sources.lines
+  return { loaded: { sources: sources.loaded, live }, lines }
+}

package/src/watch/lane-model.ts

@@ -1,4 +1,4 @@
-import { differsFromColumn } from '../plan-format'
+import { differsFromColumn, type LaneProgress, type SprintLane } from '../plan-format'
 import { isRecord } from '../shared/is-record'
 
 export const LANE_MODEL_EVENT = 'model'
@@ -14,6 +14,16 @@ export type LaneModelReading = { model: string | null; idle: boolean; column: st
 
 export type LaneModelEvent = { kind: typeof LANE_MODEL_EVENT; lane: string; model: string; column: string }
 
+/**
+ * The model column a lane's agent is measured against: the row of the phase it works on (`progress.current`), else
+ * the lane's newest row, which also stands in when the current step has no board row of its own. Undefined for a
+ * lane without rows.
+ */
+export const modelColumnOf = (lane: SprintLane, progress: LaneProgress | undefined): string | undefined => {
+  const current = progress?.current ? progress.steps[progress.current.stepIndex]?.step : undefined
+  return (current && !current.withoutRow ? current : lane.steps.at(-1))?.model
+}
+
 const differs = (reading: LaneModelReading): reading is LaneModelReading & { model: string } =>
   reading.model !== null && differsFromColumn(reading.column, reading.model)
 

package/src/watch/lane-progress.ts

@@ -1,14 +1,26 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { currentPhase, type LaneProgress, parallelGroupsOfPlan, resolvePlanPath, type SprintLane } from '../plan-format'
+import { laneBuild } from '../check/plan-structure-check'
+import { isObjectId } from '../lane/close-survey'
+import {
+  currentPhase,
+  type LaneProgress,
+  mergedPhasesWithOpenBoxes,
+  type PlanStep,
+  parallelGroupsOfPlan,
+  phaseIdsOfCell,
+  resolvePlanPath,
+  type SprintLane,
+} from '../plan-format'
 import { boardRowsOf } from '../plans/board-rows'
 import { type BaseReader, baseReaderOf, gitStatusOf } from '../plans/git'
 import { laneWorkOf, readPlans, textAtBase } from '../plans/lane-plans'
 import { laneHeads, type PlanPullRequest, planPullRequests } from '../plans/plan-heads'
 import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from '../plans/settings'
 import { workedLaneProgress } from '../plans/worked-phases'
+import type { PlanLanguage } from '../vocabulary'
 import { parallelBatchOf } from './lane-parallel'
-import { type ReadyPhase, readyPhasesOf } from './lane-report'
+import { type OpenBoxesOf, type ReadyPhase, readyPhasesOf } from './lane-report'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 
 /** The open pull requests of the watcher's list that change a plan, as the herd chooses them. */
@@ -107,6 +119,29 @@ export const watchedLaneParallel = (
   return groups === null ? [] : parallelBatchOf(groups)
 }
 
+/**
+ * Reads the open boxes of the phase a merged lane built from the lane's worktree, which still holds the pull request's
+ * plan and board row, against the merge commit's parent (what the pull request ticked): the check's `laneBuild`. Null for a lane without a worktree or a phase without open boxes, and
+ * when anything on the way throws, so the merge line stays the plain duty.
+ */
+export const worktreeOpenBoxes =
+  (root: string, settings: PlansSettings): OpenBoxesOf =>
+  (lane, mergeCommit) => {
+    try {
+      const build = laneBuild({
+        root: worktreeOf(root, settings, lane),
+        lane,
+        planDirectory: settings.planDirectory,
+        board: settings.board,
+        language: settings.planLanguage,
+        baseOf: mergeCommit !== null && isObjectId(mergeCommit) ? baseReaderOf(root, `${mergeCommit}^`) : () => null,
+      })
+      return build?.open ? { phaseId: build.open.id, lines: build.open.openLines } : null
+    } catch {
+      return null
+    }
+  }
+
 /** A phase the lanes work on, keyed by its plan link as the board spells it, since two plans may share an id. */
 const workedPhaseKey = (planHref: string, id: string): string => `${planHref}#${id}`
 
@@ -126,6 +161,30 @@ export const workedPhaseKeys = (progress: Readonly<Record<string, LaneProgress>>
     }),
   )
 
+/** A clause of a board row that reports a merged pull request: `gemergt (#<number>)`, `merged (#<number>)`. */
+const MERGED_CLAUSE = /(?:gemergt|merged)\s*\(#\d+/i
+
+/**
+ * The phases of `planHref` that are merged: those a clause (`;`-separated) of a board row's phases cell marks `gemergt
+ * (#…)`, and those the base branch carries while the plan still has open boxes (`mergedPhasesWithOpenBoxes`, what a
+ * merged pull request leaves behind, so no extra GitHub call). Without a base plan, the board rows alone count.
+ */
+const mergedPhaseIdsOf = (
+  steps: readonly PlanStep[],
+  planHref: string,
+  text: string,
+  base: string | null,
+  language: PlanLanguage,
+): Set<string> => {
+  const fromRows = steps
+    .filter((step) => step.planHref === planHref)
+    .flatMap((step) => step.label.split(';'))
+    .filter((clause) => MERGED_CLAUSE.test(clause))
+    .flatMap((clause) => phaseIdsOfCell(clause, language))
+  const fromBase = base === null ? [] : mergedPhasesWithOpenBoxes(text, base, language).map(({ id }) => id)
+  return new Set([...fromRows, ...fromBase])
+}
+
 /**
  * Per lane, the open phases of its plan whose dependencies are all ticked off and that no lane works on (`worked`, from
  * `workedPhaseKeys`), by the plan's dependency table and ticks, as the lane's worktree has them; empty for a lane
@@ -142,12 +201,15 @@ export const watchedReadyPhases = (
     lanes.map((lane) => {
       const planHref = newestPlanHref(lane)
       const text = watchedLanePlanText(root, settings, boardFile, lane)
-      return [
-        lane.name,
-        text === null || planHref === null
-          ? []
-          : readyPhasesOf(text, settings.planLanguage, phaseIdsWorkedIn(worked, planHref)),
-      ]
+      if (text === null || planHref === null) return [lane.name, []]
+      const merged = mergedPhaseIdsOf(
+        lane.steps,
+        planHref,
+        text,
+        baseLanePlanText(root, settings, boardFile, lane),
+        settings.planLanguage,
+      )
+      return [lane.name, readyPhasesOf(text, settings.planLanguage, phaseIdsWorkedIn(worked, planHref), merged)]
     }),
   )
 

package/src/watch/lane-report.ts

@@ -26,6 +26,7 @@ import type { LaneModelEvent } from './lane-model'
 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 { PLAN_MISSING_EVENT, type PlanMissingEvent, planMissingLine } from './plan-missing'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 import { SOURCE_FIELD } from './source-fields'
@@ -308,18 +309,62 @@ type MergeEvent = PullRequestEvent & { kind: typeof WATCH_EVENT.merged }
 
 const isMerge = (event: WatchEvent): event is MergeEvent => event.kind === WATCH_EVENT.merged
 
-const mergeDuty = (merged: MergeEvent, lane: string, texts: WatchTexts): string => {
-  const duty = lane === merged.lane ? texts.mergedLaneDuty : texts.otherLaneDuty
-  return `${texts.afterMerge(merged.number)}: ${terminalSafe(lane)} ${duty}`
+/** Which checks a merge asks of a lane that rebases; null where the overlap could not be told: in doubt, all of them run. */
+export type OverlapOf = (lane: string, mergeCommit: string | null) => MergeOverlap | null
+
+const checksText = (overlap: MergeOverlap, texts: WatchTexts): string => {
+  if (overlap.kind === MERGE_OVERLAP.all) return texts.mergeChecksAll
+  if (overlap.kind === MERGE_OVERLAP.none) return texts.mergeChecksNone
+  return texts.mergeChecksRoots(overlap.roots.map(terminalSafe).join(', '))
+}
+
+const mergeDuty = (merged: MergeEvent, lane: string, texts: WatchTexts, overlapOf: OverlapOf | undefined): string => {
+  const prefix = `${texts.afterMerge(merged.number)}: ${terminalSafe(lane)}`
+  if (lane === merged.lane) return `${prefix} ${texts.mergedLaneDuty}`
+  if (overlapOf === undefined) return `${prefix} ${texts.otherLaneDuty}`
+  const overlap = overlapOf(lane, merged.mergeCommit) ?? { kind: MERGE_OVERLAP.all }
+  return `${prefix} ${texts.otherLaneDuty} · ${checksText(overlap, texts)}`
 }
 
 /**
  * What a merge asks of every watched lane (`orchestrate` § 6), one line per lane and merge: the
- * merged lane goes on or closes, every other lane rebases and goes on or waits with a reason. The
- * watcher only names the duty; the coordinator decides and prompts the lanes.
+ * merged lane goes on or closes, every other lane rebases and goes on or waits with a reason, and
+ * `overlapOf` adds which checks that rebase needs where the files the merge changed reach the lane.
+ * The watcher only names the duty; the coordinator decides and prompts the lanes.
+ */
+export const mergeDutyLines = (
+  events: readonly WatchEvent[],
+  lanes: readonly string[],
+  texts: WatchTexts,
+  overlapOf?: OverlapOf,
+): string[] =>
+  events.filter(isMerge).flatMap((merged) => lanes.map((lane) => mergeDuty(merged, lane, texts, overlapOf)))
+
+/** The phase a merged lane built with the lines of its open boxes in the plan. */
+export type OpenBoxesFound = { phaseId: string; lines: readonly number[] }
+
+/**
+ * Reads the open boxes of the phase a merged lane built, the plan of the pull request against its parent
+ * (`mergeCommit`, null where unknown); null where there is none or the lane cannot be read.
+ */
+export type OpenBoxesOf = (lane: string, mergeCommit: string | null) => OpenBoxesFound | null
+
+/**
+ * What a merged phase with open boxes asks of the coordinator (`orchestrate` § 6): one line per merge whose lane
+ * (`openBoxesOf`) leaves boxes open, `<lane> P<n> merged with <k> open boxes at <lines>`. A merged pull request without
+ * a lane has no phase to read.
  */
-export const mergeDutyLines = (events: readonly WatchEvent[], lanes: readonly string[], texts: WatchTexts): string[] =>
-  events.filter(isMerge).flatMap((merged) => lanes.map((lane) => mergeDuty(merged, lane, texts)))
+export const openBoxesDutyLines = (
+  events: readonly WatchEvent[],
+  openBoxesOf: OpenBoxesOf,
+  texts: WatchTexts,
+): string[] =>
+  events.filter(isMerge).flatMap(({ lane, mergeCommit }) => {
+    const found = lane === null ? null : openBoxesOf(lane, mergeCommit)
+    return lane === null || found === null
+      ? []
+      : [`${terminalSafe(lane)} ${texts.mergedWithOpenBoxes(phaseLabel(found.phaseId), found.lines)}`]
+  })
 
 const isLaneAlert = (event: WatchEvent): event is LaneFillEvent =>
   event.kind === WATCH_EVENT.laneFill && event.level === CONTEXT_LEVEL.alert
@@ -388,10 +433,16 @@ export type ReadyPhase = { id: string; after: string[] }
 
 /**
  * The phases of a plan that can start now, in table order: open, not worked on (`worked`, the ids of the phases the
- * lanes work on), every phase of the `Depends on` cell finished and no external gate in it. Empty for a plan without
- * a dependency table or a row without a phase in the plan.
+ * lanes work on), not merged (`merged`: a merged phase may keep an open box, e.g. its acceptance), every phase of the
+ * `Depends on` cell finished and no external gate in it. Empty for a plan without a dependency table or a row without
+ * a phase in the plan.
  */
-export const readyPhasesOf = (markdown: string, language: PlanLanguage, worked: ReadonlySet<string>): ReadyPhase[] => {
+export const readyPhasesOf = (
+  markdown: string,
+  language: PlanLanguage,
+  worked: ReadonlySet<string>,
+  merged: ReadonlySet<string> = new Set(),
+): ReadyPhase[] => {
   const table = parseDependencyTable(markdown, language) ?? []
   const phases = parsePlanPhases(markdown, language)
   const finished = new Set(phases.filter(isPhaseFinished).map(({ id }) => id))
@@ -399,7 +450,11 @@ export const readyPhasesOf = (markdown: string, language: PlanLanguage, worked:
   return table
     .filter(
       ({ id, after, external }) =>
-        open.has(id) && !worked.has(id) && external.length === 0 && after.every((each) => finished.has(each)),
+        open.has(id) &&
+        !worked.has(id) &&
+        !merged.has(id) &&
+        external.length === 0 &&
+        after.every((each) => finished.has(each)),
     )
     .map(({ id, after }) => ({ id, after }))
 }

package/src/watch/main-checkout.ts

@@ -15,6 +15,10 @@ export const behindCountOf = (revList: string | null): number | null => {
   return COUNT.test(count) ? Number(count) : null
 }
 
+/** True when the main checkout has the base checked out and lacks commits of the remote base. */
+export const isBehindOnBase = (read: MainCheckoutRead | null, baseBranch: string): boolean =>
+  read !== null && read.branch === baseBranch && (read.behind ?? 0) > 0
+
 /**
  * The duty line of the main checkout, in every report and heartbeat until it is resolved. With another branch or a
  * detached head checked out: `main checkout on <branch>, not <base>`, since the main checkout is the coordinator's seat
@@ -29,6 +33,6 @@ export const mainCheckoutDutyLine = (
 ): string | null => {
   if (read === null) return null
   if (read.branch !== baseBranch) return terminalSafe(texts.mainCheckoutOffBase(read.branch, baseBranch))
-  if (read.behind === null || read.behind === 0) return null
+  if (!isBehindOnBase(read, baseBranch) || read.behind === null) return null
   return terminalSafe(texts.mainCheckoutBehind(read.remoteBase, read.behind))
 }

package/src/watch/merge-duties.ts

@@ -0,0 +1,33 @@
+/** What a lane writes: the paths of its phases' writes cells (`''` is the whole repository) and the plan it links. */
+export type LaneScope = { writes: readonly string[]; plan: string | null }
+
+export const MERGE_OVERLAP = { all: 'all', roots: 'roots', none: 'none' } as const
+
+/** What a merge asks of a lane's checks: all of them, those of the named roots (or plans), or none. */
+export type MergeOverlap =
+  | { kind: typeof MERGE_OVERLAP.all }
+  | { kind: typeof MERGE_OVERLAP.roots; roots: string[] }
+  | { kind: typeof MERGE_OVERLAP.none }
+
+const withoutTrailingSlash = (path: string): string => path.replace(/\/+$/, '')
+
+const isUnder = (file: string, path: string): boolean => file === path || file.startsWith(`${path}/`)
+
+/**
+ * Whether the files a merge changed reach a lane (`orchestrate` § 6): a change to the lock file or the root manifest
+ * (`sharedFiles`), a lane that writes the whole repository, or one whose writes are unknown run every check; a change
+ * under a path the lane writes, or to its plan, runs the checks of that path; anything else needs a rebase and no run.
+ */
+export const overlapOf = (
+  changed: readonly string[],
+  { writes, plan }: LaneScope,
+  sharedFiles: readonly string[],
+): MergeOverlap => {
+  if (changed.length === 0) return { kind: MERGE_OVERLAP.none }
+  if (changed.some((file) => sharedFiles.includes(file))) return { kind: MERGE_OVERLAP.all }
+  if (writes.length === 0 || writes.includes('')) return { kind: MERGE_OVERLAP.all }
+  const hits = [...writes.map(withoutTrailingSlash), ...(plan === null ? [] : [plan])].filter((path) =>
+    changed.some((file) => isUnder(file, path)),
+  )
+  return hits.length === 0 ? { kind: MERGE_OVERLAP.none } : { kind: MERGE_OVERLAP.roots, roots: [...new Set(hits)] }
+}

package/src/watch/merge-overlap-read.ts

@@ -0,0 +1,69 @@
+import { STACKS } from '../config/detect'
+import { isObjectId } from '../lane/close-survey'
+import { parseSprintLanes } from '../plan-format'
+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'
+import { planTaskViewOf } from './task-parallel-input'
+
+/** The files at the repository root that every package depends on: the lock files and manifests of the known stacks. */
+const SHARED_FILES: readonly string[] = [
+  ...new Set(Object.values(STACKS).flatMap((stack) => [...stack.lockFiles, stack.rootMarker])),
+]
+
+/** The files the merge commit changed, null when git cannot say (no such commit, a root commit). */
+const changedFilesOf = (root: string, mergeCommit: string): string[] | null => {
+  if (!isObjectId(mergeCommit)) return null
+  const result = Bun.spawnSync(
+    ['git', '-C', root, 'diff', '--name-only', '--end-of-options', `${mergeCommit}^`, mergeCommit],
+    { stdout: 'pipe', stderr: 'ignore' },
+  )
+  return result.exitCode === 0 ? result.stdout.toString().split('\n').filter(Boolean) : null
+}
+
+/** The overlap of one lane; null when anything on the way throws (git, the plan file), so the line stays safe. */
+const overlapFor = (read: () => MergeOverlap | null): MergeOverlap | null => {
+  try {
+    return read()
+  } catch {
+    return null
+  }
+}
+
+/** What a lane writes, from the writes cells of its plan and the plan itself; null without a readable plan. */
+const scopeOf = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  boardText: string,
+  name: string,
+): LaneScope | null => {
+  const lane = parseSprintLanes(boardText, settings.planLanguage).find((candidate) => candidate.name === name)
+  if (lane === undefined) return null
+  const text = watchedLanePlanText(root, settings, boardFile, lane)
+  if (text === null) return null
+  const writes = Object.values(planTaskViewOf(text, settings.planLanguage).phaseWrites).flat()
+  return { writes, plan: lanePlanPath(root, settings, boardFile, lane) }
+}
+
+/**
+ * Which checks each merge asks of each rebasing lane: the files the merge commit changed against what the lane
+ * writes (`overlapOf`). Null for a lane or a commit it cannot tell for, so the line stays the plain duty.
+ */
+export const mergeOverlapReader = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  boardText: string,
+): OverlapOf => {
+  const changed = new Map<string, string[] | null>()
+  return (lane, mergeCommit) =>
+    overlapFor(() => {
+      if (mergeCommit === null) return null
+      if (!changed.has(mergeCommit)) changed.set(mergeCommit, changedFilesOf(root, mergeCommit))
+      const files = changed.get(mergeCommit) ?? null
+      const scope = scopeOf(root, settings, boardFile, boardText, lane)
+      return files === null || scope === null ? null : overlapOf(files, scope, SHARED_FILES)
+    })
+}

package/src/watch/plan-views.ts

@@ -18,7 +18,12 @@ export type PlanViews = { failureReported: boolean }
 
 type Ensured = { ok: true; lines: string[] } | { ok: false; error: string }
 
-type Effects = { ensure: () => string[]; log: (line: string) => void }
+type Effects = {
+  ensure: () => string[]
+  log: (line: string) => void
+  /** ` · read <path>` of the reference that holds the handling of a failure; none when omitted. */
+  failureHint?: () => string
+}
 
 export const insideHerdr = (adapter: PlansSettings['adapter'], env: Record<string, string | undefined>): boolean =>
   adapter === TERMINAL_ADAPTER.herdr && env.HERDR_ENV === '1'
@@ -32,11 +37,18 @@ export const ensureDue = (trigger: EnsureTrigger): boolean =>
   trigger.kind === ENSURE_TRIGGER.start || trigger.added.length > 0 || trigger.withNewAgent.length > 0
 
 /** The lines one run leaves in the watcher's output: what it brought back, or a failure once per streak. */
-export const ensuredLines = (ensured: Ensured, views: PlanViews): { lines: string[]; views: PlanViews } => {
+export const ensuredLines = (
+  ensured: Ensured,
+  views: PlanViews,
+  failureHint = '',
+): { lines: string[]; views: PlanViews } => {
   if (ensured.ok)
     return { lines: ensured.lines.map((line) => `herd --ensure: ${line}`), views: { failureReported: false } }
   if (views.failureReported) return { lines: [], views }
-  return { lines: [`herd --ensure failed, still watching: ${ensured.error}`], views: { failureReported: true } }
+  return {
+    lines: [`herd --ensure failed, still watching: ${ensured.error}${failureHint}`],
+    views: { failureReported: true },
+  }
 }
 
 const ensuredOf = (ensure: () => string[]): Ensured => {
@@ -53,7 +65,7 @@ const ensuredOf = (ensure: () => string[]): Ensured => {
  */
 export const keepPlanViews = (trigger: EnsureTrigger, views: PlanViews, effects: Effects): PlanViews => {
   if (!ensureDue(trigger)) return views
-  const { lines, views: next } = ensuredLines(ensuredOf(effects.ensure), views)
+  const { lines, views: next } = ensuredLines(ensuredOf(effects.ensure), views, effects.failureHint?.())
   for (const line of lines) effects.log(line)
   return next
 }

package/src/watch/reference-paths.ts

@@ -1,6 +1,7 @@
 import { join } from 'node:path'
 import { claudePath, SKILLS_DIRECTORY } from '../claude/paths'
 import { CONTEXT_LEVEL } from '../context'
+import { type LaneSetChange, laneSetLines } from '../plans/lane-discovery'
 import { APPOINTMENT_EVENT } from './appointments'
 import { UPDATE_AVAILABLE_EVENT, WATCH_EVENT } from './watch-events'
 
@@ -14,6 +15,14 @@ export const REFERENCE = {
   coordinatorHandover: 'references/coordinator-handover.md',
   closeLane: 'references/close-lane.md',
   laneHandover: 'references/lane-handover.md',
+  startLane: 'references/start-lane.md',
+  appointments: 'references/appointments.md',
+  stageApproval: 'references/stage-approval.md',
+  planCommit: 'references/plan-commit.md',
+  herdAsk: 'references/herd-ask.md',
+  watchWithoutMonitor: 'references/watch-without-monitor.md',
+  adoptPlan: 'references/adopt-plan.md',
+  waiting: 'references/waiting.md',
 } as const
 
 export type Reference = (typeof REFERENCE)[keyof typeof REFERENCE]
@@ -24,9 +33,9 @@ export type SkillCopy = { shown: string; path: string }
 const SKILL_ENTRY = 'SKILL.md'
 
 /**
- * The rare events and the reference that holds their handling. The frequent ones (`blocked`, `done`/`idle`, `merged`,
- * the checks, `heartbeat`, `approval`, the lanes' fill, the watcher's end, `kit updated`) stay in the skill and have
- * no path, so their lines do not grow.
+ * The events that need a reference and the file that holds their handling. The frequent ones (`blocked`, `done`/`idle`,
+ * `merged`, the checks, `heartbeat`, an `approval` of a tool that is no standing stage tool) have no path, so their
+ * lines do not grow. A lane's fill and an approval depend on more than the kind: see `eventReference`.
  */
 const EVENT_REFERENCES: Readonly<Record<string, Reference>> = {
   [WATCH_EVENT.feedback]: REFERENCE.events,
@@ -38,6 +47,9 @@ const EVENT_REFERENCES: Readonly<Record<string, Reference>> = {
   [WATCH_EVENT.noTaskSignal]: REFERENCE.events,
   [WATCH_EVENT.unlinkedArtifact]: REFERENCE.events,
   [WATCH_EVENT.planMissing]: REFERENCE.events,
+  [WATCH_EVENT.deploy]: REFERENCE.events,
+  [WATCH_EVENT.laneStalled]: REFERENCE.events,
+  [WATCH_EVENT.due]: REFERENCE.appointments,
   [UPDATE_AVAILABLE_EVENT]: REFERENCE.events,
   [WATCH_EVENT.laneModel]: REFERENCE.laneSession,
 }
@@ -45,13 +57,30 @@ const EVENT_REFERENCES: Readonly<Record<string, Reference>> = {
 const isCoordinatorHandoverLevel = (level: unknown): boolean =>
   level === CONTEXT_LEVEL.warn || level === CONTEXT_LEVEL.alert
 
-/** The reference to read for `event`; null for a frequent event, and for a coordinator still at `ok`. */
-export const eventReference = (event: { kind: string; level?: unknown }): Reference | null => {
+/** The reference of a lane whose context rose: its hand-over at `alert`, the events at `warn`. */
+const laneFillReference = (level: unknown): Reference =>
+  level === CONTEXT_LEVEL.alert ? REFERENCE.laneHandover : REFERENCE.events
+
+/**
+ * The reference to read for `event`; null for a frequent event, for a coordinator still at `ok` and for an approval
+ * whose tool is no standing stage tool (`isStageTool`, which only the config can tell).
+ */
+export const eventReference = (
+  event: { kind: string; level?: unknown; tool?: string },
+  isStageTool: (tool: string) => boolean = () => false,
+): Reference | null => {
   if (event.kind === WATCH_EVENT.coordinator)
     return isCoordinatorHandoverLevel(event.level) ? REFERENCE.coordinatorHandover : null
+  if (event.kind === WATCH_EVENT.laneFill) return laneFillReference(event.level)
+  if (event.kind === WATCH_EVENT.approval)
+    return event.tool !== undefined && isStageTool(event.tool) ? REFERENCE.stageApproval : null
   return EVENT_REFERENCES[event.kind] ?? null
 }
 
+/** The tools of `guard.approvals.standing`, the calls a standing approval may let through; none without one. */
+export const stageToolsOf = (standing: { tools: Readonly<Record<string, string>> } | undefined): string[] =>
+  Object.keys(standing?.tools ?? {})
+
 /**
  * The places the orchestrate skill is installed, the project's first: `<root>/.claude/skills/<prefix>orchestrate`, and
  * the global copy `~/.claude/skills/<globalPrefix>orchestrate` that `jh sync --global` writes (`toGlobalKit`). The
@@ -84,6 +113,18 @@ export const referenceHint = (reference: Reference, skillDirectory: string | nul
     ? ` · read ${ORCHESTRATE_SKILL_NAME} skill ${reference}`
     : ` · read ${skillDirectory}/${reference}`
 
+/** A hint as a line of its own, without its leading separator; no line for an empty hint. */
+export const referenceLine = (hint: string): string[] => (hint === '' ? [] : [hint.trimStart()])
+
 /** `lines` with `hint` on the first one, the header of a multi-line event. */
 export const annotateFirstLine = (lines: readonly string[], hint: string): string[] =>
   lines.map((line, index) => (index === 0 ? `${line}${hint}` : line))
+
+/** `lines` with `hint` on each of them, the duty lines that all name the same reference. */
+export const annotateEach = (lines: readonly string[], hint: string): string[] => lines.map((line) => `${line}${hint}`)
+
+/** `lane added` and `lane removed` lines, the hint on the removed ones only: an added lane is handled in the core. */
+export const laneSetEventLines = ({ added, removed }: LaneSetChange, hint: string): string[] => [
+  ...laneSetLines({ added, removed: [] }),
+  ...annotateEach(laneSetLines({ added: [], removed }), hint),
+]

package/src/watch/report-questions.ts

@@ -8,9 +8,12 @@ const CODE_FENCE = /^\s*(```|~~~)/
 const LIST_ITEM = /^(?:\d+[.)]|[-*])\s/
 const CONTINUATION_LINE = /^\s/
 const LIST_MARKER = /^(?:\d+[.)]|[-*])\s*/
-/** What a section writes when it has nothing to ask: "Keine.", "None.", "Keine offenen Fragen.", "Keine offenen.", a dash. */
+/**
+ * What a section writes when it has nothing to ask: a sentence that opens with "Keine"/"None" and asks nothing
+ * ("Keine Rückfragen.", "None, all decided."), the short forms "No questions." / "Nein.", "n/a", a dash.
+ */
 const NO_QUESTIONS =
-  /^(?:(?:keine|none|no|nein)(?:\s+(?:(?:offen(?:en?)?|open)(?:\s+ones?)?|(?:offenen\s+)?(?:fragen?|questions?)))?\.?|n\/a|[—–])$/i
+  /^(?:(?:keine|none)\b[^?]*|(?:no|nein)(?:\s+(?:(?:offen(?:en?)?|open)(?:\s+ones?)?|(?:offenen\s+)?(?:fragen?|questions?)))?\.?|n\/a|[—–])$/i
 
 /** What the questions part of a message may take: whole up to these limits, else cut question by question. */
 const QUESTION_LINES = 20