jackherd 1.9.0 → 1.10.0

package/src/watch/heartbeat-progress.ts

@@ -1,6 +1,4 @@
 import { currentPhase, type LaneProgress, PHASE_ID_PREFIX, type PhaseProgress } from '../plan-format'
-import { AGENT_STATUS } from '../terminal/types'
-import type { LaneSnapshot } from './lane-watch'
 
 /** The current phase of a lane and how many of its checkboxes are ticked, as the herd counts them. */
 export type PhaseCount = Pick<PhaseProgress, 'id' | 'done' | 'total'>
@@ -23,25 +21,15 @@ export const currentPhaseCountsOf = (progress: Readonly<Record<string, LaneProgr
     }),
   )
 
-const sameCount = (left: PhaseCount | undefined, right: PhaseCount): boolean =>
-  left?.id === right.id && left.done === right.done && left.total === right.total
-
 /**
- * The note of each working lane whose count differs from the one at the last heartbeat (or has none before): a lane
- * that has not moved says nothing, so a stretch on one number tells the coordinator to look for itself.
+ * The note of each working lane that has a count, at every heartbeat: a stretch of reviews or subagents without a new
+ * tick still shows where the lane stands, and an unchanged number tells the coordinator the lane is not stuck on
+ * silence.
  */
-export const progressNotes = (
-  lanes: readonly string[],
-  current: LaneSnapshot,
-  counts: Readonly<Record<string, PhaseCount>>,
-  previous: Readonly<Record<string, PhaseCount>>,
-): LaneNotes =>
+export const progressNotes = (working: readonly string[], counts: Readonly<Record<string, PhaseCount>>): LaneNotes =>
   Object.fromEntries(
-    lanes.flatMap((lane) => {
+    working.flatMap((lane) => {
       const count = counts[lane]
-      const moved = count !== undefined && !sameCount(previous[lane], count)
-      return moved && current[lane]?.status === AGENT_STATUS.working
-        ? [[lane, `${PHASE_ID_PREFIX}${count.id} ${count.done}/${count.total}`]]
-        : []
+      return count !== undefined ? [[lane, `${PHASE_ID_PREFIX}${count.id} ${count.done}/${count.total}`]] : []
     }),
   )

package/src/watch/kit-update.ts

@@ -1,18 +1,37 @@
-import { kitUpdatedLine, pendingKitUpdate } from '../version/installed-version'
+import { type KitUpdate, kitUpdatedLine, pendingKitUpdate } from '../version/installed-version'
 import type { StartedKit } from '../version/started-kit'
 
-type Effects = { saveState: () => void; log: (line: string) => void; skillLine: () => string }
+type Effects = {
+  saveState: () => void
+  log: (line: string) => void
+  skillLine: () => string
+  /** Whether the source the watcher runs from changed and the change settled; always false for an installed copy. */
+  sourceChanged: () => boolean
+}
+
+/**
+ * The line that ends the watcher: a new version on disk, else a settled change to the source it runs from, which
+ * keeps the version (`=== kit updated 1.9.0 → 1.9.0 (source changed)`); null while neither.
+ */
+export const kitEndLine = (update: KitUpdate | null, version: string, sourceChanged: boolean): string | null => {
+  if (update) return kitUpdatedLine(update)
+  return sourceChanged ? `${kitUpdatedLine({ from: version, to: version })} (source changed)` : null
+}
 
 /**
- * Ends the watcher when the kit on disk is another version than the one it started with: saves the state
- * as any stop does, then prints the line that wakes the coordinator and the line about the orchestrate
- * skill. True when the watcher should end.
+ * Ends the watcher when the kit on disk is another version than the one it started with, or when the source it runs
+ * from changed: saves the state as any stop does, then prints the line that wakes the coordinator and the line about
+ * the orchestrate skill. True when the watcher should end.
  */
-export const endedByKitUpdate = (kit: StartedKit | null, { saveState, log, skillLine }: Effects): boolean => {
-  const update = pendingKitUpdate(kit)
-  if (!update) return false
+export const endedByKitUpdate = (
+  kit: StartedKit | null,
+  { saveState, log, skillLine, sourceChanged }: Effects,
+): boolean => {
+  if (!kit) return false
+  const line = kitEndLine(pendingKitUpdate(kit), kit.version, sourceChanged())
+  if (line === null) return false
   saveState()
-  log(kitUpdatedLine(update))
+  log(line)
   log(skillLine())
   return true
 }

package/src/watch/lane-name.ts

@@ -0,0 +1,6 @@
+/**
+ * A lane name that stays a single file name: no separator, no `..`. The prompt, report and hand-over files are named
+ * after the lane, and the watcher puts it on a suggested command line, so every reader of a lane name checks it
+ * against this.
+ */
+export const SAFE_LANE_NAME = /^(?!\.\.?$)[A-Za-z0-9._-]+$/

package/src/watch/lane-progress.ts

@@ -2,35 +2,57 @@ import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { type LaneProgress, parallelGroupsOfPlan, resolvePlanPath, type SprintLane } from '../plan-format'
 import { boardRowsOf } from '../plans/board-rows'
-import { baseReaderOf, gitStatusOf } from '../plans/git'
+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 { parallelBatchOf } from './lane-parallel'
+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. */
+export const watchedPlanPullRequests = (
+  pullRequests: readonly WatchedPullRequest[],
+  settings: PlansSettings,
+): WatchedPullRequest[] =>
+  planPullRequests(
+    pullRequests.filter(({ state }) => state === PULL_REQUEST_STATE.open),
+    settings.planDirectory,
+  )
 
 /**
- * The progress the watcher reports for a lane, from the same reading as the herd: the base ref's plans, the
- * phases the lane works on from its worktree (also without a board row), so both name the same open phase.
+ * The progress the watcher reports for a lane, from the same reading as the herd: the base ref's plans, raised by
+ * the fetched heads of `openPlanPullRequests` (`watchedPlanPullRequests`), the phases the lane works on from its
+ * worktree (also without a board row), so both name the same open phase.
  */
 export const watchedLaneProgress = async (
   root: string,
   settings: PlansSettings,
   boardFile: string,
   lane: SprintLane,
+  openPlanPullRequests: readonly PlanPullRequest[],
+  headReaderOf: (ref: string) => BaseReader = (ref) => baseReaderOf(root, ref),
 ): Promise<LaneProgress> => {
   const baseRef = baseRefOf(settings)
   const worktree = worktreeOf(root, settings, lane.name)
+  const status = await gitStatusOf(worktree, baseRef)
   const sources = {
     root,
     settings,
     base: baseReaderOf(root, baseRef),
     sprintDirectory: dirname(boardRepoPathOf(root, settings, boardFile)),
+    heads: laneHeads(openPlanPullRequests, status.branch, headReaderOf),
   }
-  const work = laneWorkOf(worktree, await gitStatusOf(worktree, baseRef))
-  const { plans } = await readPlans(lane, sources, work, [])
+  const { plans } = await readPlans(lane, sources, laneWorkOf(worktree, status), [])
   return workedLaneProgress(lane, plans)
 }
 
+/** The repository path of the plan of a lane's newest row that links one; null without such a row. */
+const lanePlanPath = (root: string, settings: PlansSettings, boardFile: string, lane: SprintLane): string | null => {
+  const href = lane.steps.filter((step) => step.planHref !== null).at(-1)?.planHref
+  return href ? resolvePlanPath(dirname(boardRepoPathOf(root, settings, boardFile)), href) : null
+}
+
 /**
  * The text of a lane's plan, the plan of its newest row, as the lane's worktree has it, else as the base ref has it;
  * null without a row that links a plan or when neither has the file.
@@ -41,15 +63,25 @@ export const watchedLanePlanText = (
   boardFile: string,
   lane: SprintLane,
 ): string | null => {
-  const href = lane.steps.filter((step) => step.planHref !== null).at(-1)?.planHref
-  if (!href) return null
-  const path = resolvePlanPath(dirname(boardRepoPathOf(root, settings, boardFile)), href)
+  const path = lanePlanPath(root, settings, boardFile, lane)
+  if (path === null) return null
   const worktreeFile = join(worktreeOf(root, settings, lane.name), path)
   return existsSync(worktreeFile)
     ? readFileSync(worktreeFile, 'utf8')
     : textAtBase(baseReaderOf(root, baseRefOf(settings)), path)
 }
 
+/** The text of the same plan as the base ref has it, which the lane cannot change; null without a plan or the file. */
+export const baseLanePlanText = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  lane: SprintLane,
+): string | null => {
+  const path = lanePlanPath(root, settings, boardFile, lane)
+  return path === null ? null : textAtBase(baseReaderOf(root, baseRefOf(settings)), path)
+}
+
 /**
  * The phases of a lane's plan that can run together, by the plan's dependency table and ticks; empty without a plan,
  * without a table or without two such phases.

package/src/watch/lane-report-file.ts

@@ -2,18 +2,27 @@ import { closeSync, lstatSync, openSync, readSync } from 'node:fs'
 import { join } from 'node:path'
 import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
 import type { LaneReportFile } from './lane-message'
+import { SAFE_LANE_NAME } from './lane-name'
 
-/** A lane name that stays a single file name: no separator, no `..`. */
-const SAFE_LANE_NAME = /^(?!\.\.?$)[A-Za-z0-9._-]+$/
 /** The head of a report the watcher reads; it prints far less, and a huge file must not stall it. */
 const READ_LIMIT_BYTES = 8192
 
+/** Where a lane writes its report, relative to its worktree: `.claude/handover/<lane>-report.md`. */
+export const laneReportFile = (lane: string): string => claudePath(HANDOVER_DIRECTORY, `${lane}-report.md`)
+
 /**
- * Where a lane writes its report, inside its worktree: `.claude/handover/<lane>-report.md`. Null for a lane name
- * that could leave that directory: names come from board rows and herdr agents.
+ * Where a lane writes its report, inside its worktree (`laneReportFile`). Null for a lane name that could leave that
+ * directory: names come from board rows and herdr agents.
  */
 export const laneReportPath = (worktree: string, lane: string): string | null =>
-  SAFE_LANE_NAME.test(lane) ? join(worktree, claudePath(HANDOVER_DIRECTORY), `${lane}-report.md`) : null
+  SAFE_LANE_NAME.test(lane) ? join(worktree, laneReportFile(lane)) : null
+
+/**
+ * Where a lane's hand-over lies, inside its worktree: `.claude/handover/<lane>.md`, which the coordinator opens a
+ * fresh chat on. Null for a lane name that could leave that directory.
+ */
+export const laneHandoverPath = (worktree: string, lane: string): string | null =>
+  SAFE_LANE_NAME.test(lane) ? join(worktree, claudePath(HANDOVER_DIRECTORY), `${lane}.md`) : null
 
 /** The change time of a regular file at `path`, not followed through a symlink; null for anything else. */
 const regularFileMtime = (path: string): number | null => {
@@ -35,6 +44,12 @@ const readHead = (path: string): string => {
   }
 }
 
+/** Whether the lane left its hand-over file in the worktree: a regular file, not a link. */
+export const hasLaneHandover = (worktree: string, lane: string): boolean => {
+  const path = laneHandoverPath(worktree, lane)
+  return path !== null && regularFileMtime(path) !== null
+}
+
 /** The change time of the report file; null when there is none or it is no regular file. */
 export const reportMtime = (path: string | null): number | null => (path === null ? null : regularFileMtime(path))
 

package/src/watch/lane-report.ts

@@ -1,4 +1,5 @@
 import { CONTEXT_LEVEL, type ContextLevel, contextLabel } from '../context'
+import { closeDryRunOf } from '../lane/close-command-line'
 import { currentPhase, isTickedUnmerged, type LaneProgress, phasesText } from '../plan-format'
 import { terminalSafe } from '../plan-format/terminal-text'
 import { CHECK_NAME_LENGTH, type ChecksState } from '../plans/pull-requests'
@@ -14,6 +15,7 @@ import { AGENT_STATUS, type LaneSnapshot, NO_AGENT } from './lane-watch'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 import { SOURCE_FIELD } from './source-fields'
 import { type FieldChange, lineText, type SourceEvent } from './sources'
+import { NO_TASK_SIGNAL_EVENT, type NoTaskSignalEvent, noTaskSignalLine } from './task-signal-missing'
 import type { WatchTexts } from './texts'
 import {
   type DeployEvent,
@@ -40,6 +42,7 @@ export type LaneReport = {
 /** The board as the coordinator line reminds of it: its term and the rows only the checkout's board file has. */
 export type BoardReminder = { term: string; checkoutRows: number }
 
+const RESTING_STATUSES: ReadonlySet<string> = new Set([AGENT_STATUS.done, AGENT_STATUS.idle])
 const UNKNOWN = 'unknown'
 const REPORT_TEXT_LENGTH = 160
 const FIELD_VALUE_LENGTH = 60
@@ -78,17 +81,33 @@ const contextSegment = (level: ContextLevel | null): string[] =>
 
 /**
  * One line per lane, in the words of `texts`: `<lane> <status> [· context warn|alert] [· waits on: <question>, <n> open questions] · <branch>|no branch ·
- * PR #<n> <checks>|no PR · open phase …|phase … ticked, not merged|plan finished|no plan`.
+ * PR #<n> <checks>|no PR · open phase …|phase … ticked, not merged|plan finished|no plan`. A resting lane whose plan is
+ * finished is followed by the dry run of `jh lane close` for it and `closeLaneHint`, the path of the reference on
+ * closing a lane.
  */
-export const laneReportLine = (report: LaneReport, texts: WatchTexts): string =>
-  [
+export const laneReportLine = (report: LaneReport, texts: WatchTexts, closeLaneHint = ''): string => {
+  const phase = phaseSegment(report.progress, texts)
+  const waitsForClosing = phase === texts.planFinished && RESTING_STATUSES.has(report.status)
+  const dryRun = closeDryRunOf(report.lane)
+  const closing = `${phase}${dryRun === null ? '' : ` · close: ${dryRun}`}${closeLaneHint}`
+  return [
     `${terminalSafe(report.lane)} ${terminalSafe(report.status)}`,
     ...contextSegment(report.context),
     ...(report.rest ? [terminalSafe(report.rest)] : []),
     report.branch ? terminalSafe(report.branch) : texts.noBranch,
     pullRequestSegment(report.pullRequest, texts),
-    phaseSegment(report.progress, texts),
+    waitsForClosing ? closing : phase,
   ].join(' · ')
+}
+
+/**
+ * The header of a stopped lane's section: `=== <lane>: <status>`. A lane that stopped `done` or `idle` with a hand-over
+ * file in its worktree (`handoverHint`, null without one) names the file and the reference on it.
+ */
+export const laneStopHeader = (lane: string, status: string, handoverHint: string | null): string => {
+  const header = `=== ${terminalSafe(lane)}: ${terminalSafe(status)}`
+  return handoverHint !== null && RESTING_STATUSES.has(status) ? `${header} · hand-over file${handoverHint}` : header
+}
 
 /** The lane, or `branch <name>` for an own pull request without a lane, its name cut like other third-party text. */
 const pullRequestOwner = (event: PullRequestEvent): string =>
@@ -154,6 +173,7 @@ export const watchEventLine = (event: WatchEvent, target: string | null): string
   if (event.kind === WATCH_EVENT.laneParallel)
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${phasesText(event.phases)}`
   if (event.kind === WATCH_EVENT.taskParallel) return `=== ${terminalSafe(event.line)}`
+  if (event.kind === WATCH_EVENT.noTaskSignal) return `=== ${terminalSafe(noTaskSignalLine(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)}`
@@ -300,6 +320,14 @@ export const parallelDutyLines = (events: readonly WatchEvent[], texts: WatchTex
     .filter(isLaneParallel)
     .map(({ lane, phases }) => `${terminalSafe(lane)} parallel: ${texts.parallelDuty(phasesText(phases))}`)
 
+const isNoTaskSignal = (event: WatchEvent): event is NoTaskSignalEvent => event.kind === WATCH_EVENT.noTaskSignal
+
+/** What a lane that works without a task signal asks of the coordinator (`references/events.md`): one line per such lane. */
+export const noTaskSignalDutyLines = (events: readonly WatchEvent[], texts: WatchTexts): string[] =>
+  events
+    .filter(isNoTaskSignal)
+    .map(({ lane }) => `${terminalSafe(lane)} ${NO_TASK_SIGNAL_EVENT}: ${texts.noTaskSignalDuty}`)
+
 const isApproval = (event: WatchEvent): event is ApprovalEvent => event.kind === WATCH_EVENT.approval
 
 /**

package/src/watch/lane-sources.ts

@@ -1,7 +1,10 @@
 import { existsSync } from 'node:fs'
-import { fetchBase } from '../plans/fetch'
-import { BASE_REMOTE } from '../plans/settings'
-import { baseFetchNeeded, remoteTipOf } from './base-tip'
+import { fetchBase, fetchPlanHeads } from '../plans/fetch'
+import { commitOf } from '../plans/git'
+import { BASE_REMOTE, baseRefOf } from '../plans/settings'
+import { baseFetchNeeded, movedHeads, remoteTipOf } from './base-tip'
+import { behindCountOf, type MainCheckoutRead } from './main-checkout'
+import type { WatchedPullRequest } from './pull-requests'
 
 const GIT_ASYNC_TIMEOUT_MS = 30_000
 
@@ -31,6 +34,20 @@ const git = (cwd: string, args: string[]): string | null => {
 export const branchOf = (worktree: string): string | null =>
   existsSync(worktree) ? git(worktree, ['branch', '--show-current']) || null : null
 
+/**
+ * The main checkout's branch and the commits of `origin/<base>` it lacks, as far as git can tell; read from local refs
+ * only. Null when git cannot resolve HEAD, so an unreadable checkout never reads as a detached head.
+ */
+export const readMainCheckout = (root: string, baseBranch: string): MainCheckoutRead | null => {
+  if (git(root, ['rev-parse', '--verify', '--quiet', 'HEAD']) === null) return null
+  const remoteBase = baseRefOf({ baseBranch })
+  return {
+    branch: branchOf(root),
+    behind: behindCountOf(git(root, ['rev-list', '--count', `HEAD..${remoteBase}`])),
+    remoteBase,
+  }
+}
+
 /**
  * Fetches the base branch when the remote moved past `origin/<branch>`, so every reader of that ref
  * (the herd watches `FETCH_HEAD`) sees a merge as soon as the watcher does. Asks the remote
@@ -44,3 +61,14 @@ export const fetchBaseWhenMoved = async (root: string, branch: string): Promise<
   if (!baseFetchNeeded(remote === null ? null : remoteTipOf(remote, branch), local?.trim() || null)) return
   await fetchBase(root, BASE_REMOTE, branch)
 }
+
+/**
+ * Fetches the heads of the plan pull requests whose head commit moved past the herd's ref of it, in one call, so the
+ * watcher and the herd read the same ticks; an unchanged head costs no fetch, a failure leaves the refs as they are.
+ */
+export const fetchPlanHeadsWhenMoved = (root: string, pullRequests: readonly WatchedPullRequest[]): Promise<void> =>
+  fetchPlanHeads(
+    root,
+    BASE_REMOTE,
+    movedHeads(pullRequests, (ref) => commitOf(root, ref)),
+  )

package/src/watch/main-checkout.ts

@@ -0,0 +1,34 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import type { WatchTexts } from './texts'
+
+/**
+ * What git says about the main checkout: the branch it has checked out (null for a detached head) and the commits of
+ * `remoteBase` (`origin/<base>`) it lacks.
+ */
+export type MainCheckoutRead = { branch: string | null; behind: number | null; remoteBase: string }
+
+const COUNT = /^\d+$/
+
+/** The count `git rev-list --count` printed; null when git failed or printed something else. */
+export const behindCountOf = (revList: string | null): number | null => {
+  const count = revList?.trim() ?? ''
+  return COUNT.test(count) ? Number(count) : null
+}
+
+/**
+ * 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
+ * on the base and a fast-forward would land on the wrong branch. With the base checked out and behind the merges on
+ * the remote: `main checkout behind origin/<base> by <n> (git merge --ff-only origin/<base>)`. Null when caught up or
+ * unreadable; a `read` of null (git could not resolve the main checkout's HEAD) is unreadable, not a detached head.
+ */
+export const mainCheckoutDutyLine = (
+  read: MainCheckoutRead | null,
+  baseBranch: string,
+  texts: WatchTexts,
+): 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
+  return terminalSafe(texts.mainCheckoutBehind(read.remoteBase, read.behind))
+}

package/src/watch/plan-badges-read.ts

@@ -1,5 +1,5 @@
-import { readFileSync } from 'node:fs'
-import { join } from 'node:path'
+import { dirname, join } from 'node:path'
+import { isPrivateLevels, type LocationSystem, readPrivateText, systemLocation } from '../shared/private-location'
 import {
   sourceTicketsOf,
   type TicketSource,
@@ -12,8 +12,10 @@ import { parseWatchState, type WatchState } from './watch-events'
 import { type CommandLineOf, isWatcherRunning, WATCHER_FILES, watcherDirectoryOf } from './watcher-lock'
 
 const readState = (file: string): WatchState | null => {
+  const text = readPrivateText(file)
+  if (text === null) return null
   try {
-    return parseWatchState(readFileSync(file, 'utf8'))
+    return parseWatchState(text)
   } catch {
     return null
   }
@@ -22,19 +24,23 @@ const readState = (file: string): WatchState | null => {
 /**
  * What the watcher of the repository at `root` gives the herd, read from its state file without a GitHub call:
  * its badges, the tickets of `ticketSources`, and its health, so the view can say why there are none. A missing or
- * damaged file shows no badges; the view goes on without them.
+ * damaged file shows no badges; the view goes on without them. Nothing is read unless both levels of the watcher
+ * directory are private (`isPrivateLevels`), and only regular files, so a directory, a file or a FIFO someone else
+ * planted neither feeds the view nor blocks it.
  */
 export const readWatchReading = (
   root: string,
   now: number,
   ticketSources: readonly TicketSource[],
   lookUp?: CommandLineOf,
+  system: LocationSystem = systemLocation(),
 ): WatchReading => {
-  const directory = watcherDirectoryOf(root)
-  const state = readState(join(directory, WATCHER_FILES.state))
+  const directory = watcherDirectoryOf(root, system)
+  const isPrivate = isPrivateLevels(dirname(directory), directory, system)
+  const state = isPrivate ? readState(join(directory, WATCHER_FILES.state)) : null
   const health = watchHealthOf(
     state?.savedAt ?? null,
-    isWatcherRunning(join(directory, WATCHER_FILES.lock), lookUp),
+    isPrivate && isWatcherRunning(join(directory, WATCHER_FILES.lock), lookUp),
     now,
   )
   if (!state || health.kind !== WATCH_HEALTH.live) return { badges: {}, tickets: [], health }

package/src/watch/pull-requests.ts

@@ -4,6 +4,7 @@ import {
   checksOf,
   type FailedCheck,
   failedChecksOf,
+  filePathsOf,
   type GhPullRequest,
   isGhPullRequest,
 } from '../plans/pull-requests'
@@ -25,6 +26,8 @@ export type WatchedPullRequest = {
   failedRuns: FailedCheck[]
   headCommit: string
   mergeCommit: string | null
+  /** The paths it changes (at most 100), from the open list only; a plan among them makes its head a plan head. */
+  files?: string[]
 }
 
 /** The rollup is optional: the light list has none. */
@@ -41,8 +44,8 @@ type GhWatchedPullRequest = Omit<GhPullRequest, 'statusCheckRollup'> & {
  */
 export const WATCHED_PULL_REQUEST_FIELDS = 'number,title,url,headRefName,isDraft,state,headRefOid,mergeCommit'
 
-/** The fields of the list of open pull requests, which is the only one that asks for their checks. */
-export const OPEN_PULL_REQUEST_FIELDS = `${WATCHED_PULL_REQUEST_FIELDS},statusCheckRollup`
+/** The fields of the list of open pull requests, which is the only one that asks for their checks and their files. */
+export const OPEN_PULL_REQUEST_FIELDS = `${WATCHED_PULL_REQUEST_FIELDS},statusCheckRollup,files`
 
 const GH_PR_LIST = 'gh pr list'
 
@@ -79,6 +82,7 @@ const watchedPullRequestsOf = (
     failedRuns: failedChecksOf(pullRequest.statusCheckRollup ?? [], pullRequest.url),
     headCommit: pullRequest.headRefOid,
     mergeCommit: pullRequest.mergeCommit?.oid ?? null,
+    ...filePathsOf(pullRequest),
   }))
 
 const asIs = (entry: unknown): unknown => entry

package/src/watch/reference-paths.ts

@@ -0,0 +1,87 @@
+import { join } from 'node:path'
+import { claudePath, SKILLS_DIRECTORY } from '../claude/paths'
+import { CONTEXT_LEVEL } from '../context'
+import { APPOINTMENT_EVENT } from './appointments'
+import { UPDATE_AVAILABLE_EVENT, WATCH_EVENT } from './watch-events'
+
+/** The skill the watcher points the coordinator to, by its name without a prefix. */
+export const ORCHESTRATE_SKILL_NAME = 'orchestrate'
+
+/** The reference files of the orchestrate skill, relative to its directory. */
+export const REFERENCE = {
+  events: 'references/events.md',
+  laneSession: 'references/lane-session.md',
+  coordinatorHandover: 'references/coordinator-handover.md',
+  closeLane: 'references/close-lane.md',
+  laneHandover: 'references/lane-handover.md',
+} as const
+
+export type Reference = (typeof REFERENCE)[keyof typeof REFERENCE]
+
+/** A copy of the orchestrate skill: the directory as the session reads it, and where that is on disk. */
+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.
+ */
+const EVENT_REFERENCES: Readonly<Record<string, Reference>> = {
+  [WATCH_EVENT.feedback]: REFERENCE.events,
+  [WATCH_EVENT.preview]: REFERENCE.events,
+  [WATCH_EVENT.source]: REFERENCE.events,
+  [APPOINTMENT_EVENT.unreadable]: REFERENCE.events,
+  [WATCH_EVENT.laneParallel]: REFERENCE.events,
+  [WATCH_EVENT.taskParallel]: REFERENCE.events,
+  [WATCH_EVENT.noTaskSignal]: REFERENCE.events,
+  [UPDATE_AVAILABLE_EVENT]: REFERENCE.events,
+  [WATCH_EVENT.laneModel]: REFERENCE.laneSession,
+}
+
+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 => {
+  if (event.kind === WATCH_EVENT.coordinator)
+    return isCoordinatorHandoverLevel(event.level) ? REFERENCE.coordinatorHandover : null
+  return EVENT_REFERENCES[event.kind] ?? null
+}
+
+/**
+ * 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
+ * project shows its path relative to the root the session runs in, the global one with `~`.
+ */
+export const skillCopiesFor = (
+  root: string,
+  home: string,
+  projectPrefix: string,
+  globalPrefix: string,
+): SkillCopy[] => {
+  const project = claudePath(SKILLS_DIRECTORY, `${projectPrefix}${ORCHESTRATE_SKILL_NAME}`)
+  const global = claudePath(SKILLS_DIRECTORY, `${globalPrefix}${ORCHESTRATE_SKILL_NAME}`)
+  return [
+    { shown: project, path: join(root, project) },
+    { shown: `~/${global}`, path: join(home, global) },
+  ]
+}
+
+/**
+ * The directory of the first copy that holds the skill: the project's installation, else the global one. `exists`
+ * answers for a path on disk, so the choice stays a pure function.
+ */
+export const skillDirectoryFor = (copies: readonly SkillCopy[], exists: (path: string) => boolean): string | null =>
+  copies.find(({ path }) => exists(join(path, SKILL_ENTRY)))?.shown ?? null
+
+/** ` · read <skill directory>/<reference>`, naming the skill when no copy of it was found. */
+export const referenceHint = (reference: Reference, skillDirectory: string | null): string =>
+  skillDirectory === null
+    ? ` · read ${ORCHESTRATE_SKILL_NAME} skill ${reference}`
+    : ` · read ${skillDirectory}/${reference}`
+
+/** `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))

package/src/watch/running-subagents.ts

@@ -0,0 +1,43 @@
+import type { RunningSubagent } from '../plans/subagents'
+import { laneDirectoryOf } from '../plans/unlisted-lanes'
+import { type LaneNotes, type PhaseCount, progressNotes } from './heartbeat-progress'
+
+/** The running subagents of each worktree below `worktreeDirectory`, by lane name; one that works elsewhere is left out. */
+export const runningSubagentCountsOf = (
+  running: readonly Pick<RunningSubagent, 'cwd'>[],
+  worktreeDirectory: string,
+): Record<string, number> => {
+  const counts: Record<string, number> = {}
+  for (const { cwd } of running) {
+    const lane = cwd === null ? null : laneDirectoryOf(cwd, worktreeDirectory)
+    if (lane !== null) counts[lane] = (counts[lane] ?? 0) + 1
+  }
+  return counts
+}
+
+/** What a heartbeat says about running subagents: `3 subagents`; null for none. */
+export const subagentsNote = (count: number): string | null =>
+  count <= 0 ? null : `${count} ${count === 1 ? 'subagent' : 'subagents'}`
+
+/**
+ * The heartbeat notes with the running subagents of each working lane appended (`P12 7/12, 3 subagents`); a lane that
+ * has no count note yet gets the subagents alone. Resting lanes and lanes without running subagents keep their note.
+ */
+export const withSubagentNotes = (
+  notes: LaneNotes,
+  working: readonly string[],
+  counts: Readonly<Record<string, number>>,
+): LaneNotes => {
+  const extra = working.flatMap((lane) => {
+    const note = subagentsNote(counts[lane] ?? 0)
+    return note === null ? [] : [[lane, [notes[lane], note].filter(Boolean).join(', ')]]
+  })
+  return { ...notes, ...Object.fromEntries(extra) }
+}
+
+/** The notes of a heartbeat: each working lane's phase count and its running subagents; resting lanes have neither. */
+export const heartbeatNotesOf = (
+  working: readonly string[],
+  phaseCounts: Readonly<Record<string, PhaseCount>>,
+  subagentCounts: Readonly<Record<string, number>>,
+): LaneNotes => withSubagentNotes(progressNotes(working, phaseCounts), working, subagentCounts)