jackherd 1.8.1 → 1.10.0

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

@@ -1,6 +1,6 @@
 import { CHECKS } from '../plans/pull-requests'
-import { sanitisedFailedTests } from './failed-tests'
-import { failedTestsOf } from './failures'
+import { sanitisedFailedTestPlaces, sanitisedFailedTests } from './failed-tests'
+import { failedTestPlacesOf, failedTestsOf } from './failures'
 import { previewUrlOf } from './previews'
 import { PULL_REQUEST_STATE } from './pull-requests'
 import { lineText, type TicketRecord } from './sources'
@@ -16,6 +16,8 @@ export type PullRequestBadges = {
   changesRequested: boolean
   /** The tests a red run failed on this head commit, as the watcher read them from the run's log; absent reads as none. */
   failedTests?: string[]
+  /** By failed test, the package or test file the log printed before it; a test without an entry has no known place. */
+  failedTestPlaces?: Record<string, string>
 }
 
 /** The badges of a pull request the watcher shows nothing for. */
@@ -82,11 +84,16 @@ export const watchBadgesOf = (state: WatchState, now: number): WatchBadges => {
       const preview = state.previews.pullRequests[number]
       const feedback = state.feedback.pullRequests[number]
       const failedTests = checks === CHECKS.failed ? shownFailedTestsOf(state, number, headCommit) : []
+      const places = sanitisedFailedTestPlaces(
+        failedTestPlacesOf(state.failures, Number(number), headCommit),
+        failedTests,
+      )
       const badges = {
         preview: preview?.reportedHead === headCommit ? (preview.url ?? null) : null,
         feedback: feedback?.headCommit === headCommit ? feedback.count : 0,
         changesRequested: feedback?.changesRequested === true,
         ...(failedTests.length > 0 && { failedTests }),
+        ...(Object.keys(places).length > 0 && { failedTestPlaces: places }),
       }
       const shown = badges.preview !== null || badges.feedback > 0 || badges.changesRequested || failedTests.length > 0
       return shown ? [[number, badges]] : []

package/src/watch/previews.ts

@@ -1,6 +1,6 @@
+import { isRecord } from '../shared/is-record'
 import { type FeedbackTarget, isReadTime } from './feedback'
 import { FEEDBACK_FORM, type FeedbackItem } from './feedback-item'
-import { isRecord } from './json-guards'
 
 export const PREVIEW_EVENT = 'preview'
 

package/src/watch/pull-requests.ts

@@ -4,10 +4,12 @@ import {
   checksOf,
   type FailedCheck,
   failedChecksOf,
+  filePathsOf,
   type GhPullRequest,
   isGhPullRequest,
 } from '../plans/pull-requests'
-import { isRecord, parseArray } from './json-guards'
+import { isRecord } from '../shared/is-record'
+import { parseArray } from './json-guards'
 
 /** The states of a pull request in `gh pr list --json state`. */
 export const PULL_REQUEST_STATE = { open: 'OPEN', merged: 'MERGED', closed: 'CLOSED' } as const
@@ -24,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. */
@@ -40,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'
 
@@ -78,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)

package/src/watch/skill-change.ts

@@ -1,13 +1,40 @@
-import { mkdirSync, readFileSync } from 'node:fs'
+import { readdirSync, readFileSync } from 'node:fs'
 import { join } from 'node:path'
+import { ensurePrivateDirectory, writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
 import { errorText } from '../plans/error-text'
-import { changedSections, SKILL_CHANGE, type SkillChange, skillChangeLine } from '../version/skill-diff'
+import {
+  changedSections,
+  orchestrateChangeLines,
+  REFERENCE_CHANGE,
+  type ReferenceChange,
+  type ReferenceDelta,
+  referenceChanges,
+  SKILL_CHANGE,
+  type SkillChange,
+} from '../version/skill-diff'
 import type { StartedKit } from '../version/started-kit'
-import { writePrivate } from './watcher-lock'
+import { ORCHESTRATE_SKILL_NAME } from './reference-paths'
+
+/** The orchestrate skill as the kit ships it: its text and its reference files by name. */
+export type OrchestrateSnapshot = { skill: string; references: Record<string, string> }
+
+/** The change since a snapshot: the skill itself, and each reference that changed, is new or is gone. */
+export type OrchestrateChange = { skill: SkillChange; references: ReferenceChange[] }
+
+type WrittenDiff = { text: string; path: string }
+
+/** A reference name that stays a plain Markdown file name, since it goes into the name of a diff file. */
+const REFERENCE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*\.md$/
+
+const skillDirectory = (packageRoot: string): string =>
+  join(packageRoot, 'kit', 'workflow', 'skills', ORCHESTRATE_SKILL_NAME)
 
 /** The kit's own text of the orchestrate skill, with its placeholders, inside the package. */
-export const orchestrateSkillPath = (packageRoot: string): string =>
-  join(packageRoot, 'kit', 'workflow', 'skills', 'orchestrate', 'SKILL.md')
+export const orchestrateSkillPath = (packageRoot: string): string => join(skillDirectory(packageRoot), 'SKILL.md')
+
+/** The directory of the skill's reference files in the kit at `packageRoot`. */
+export const orchestrateReferencesPath = (packageRoot: string): string =>
+  join(skillDirectory(packageRoot), 'references')
 
 /** The orchestrate skill's text in the kit at `packageRoot`; null when it cannot be read. */
 export const readOrchestrateSkill = (packageRoot: string): string | null => {
@@ -18,10 +45,45 @@ export const readOrchestrateSkill = (packageRoot: string): string | null => {
   }
 }
 
+/** The skill's reference files by name (every `*.md` file below `references/`); none when the directory is missing. */
+export const readOrchestrateReferences = (packageRoot: string): Record<string, string> => {
+  const directory = orchestrateReferencesPath(packageRoot)
+  try {
+    const names = readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile() && REFERENCE_FILE.test(entry.name))
+      .map((entry) => entry.name)
+    return Object.fromEntries(names.map((name) => [name, readFileSync(join(directory, name), 'utf8')]))
+  } catch {
+    return {}
+  }
+}
+
+/** The skill and its references in the kit at `packageRoot`; null when the skill cannot be read. */
+export const readOrchestrateSnapshot = (packageRoot: string): OrchestrateSnapshot | null => {
+  const skill = readOrchestrateSkill(packageRoot)
+  return skill === null ? null : { skill, references: readOrchestrateReferences(packageRoot) }
+}
+
+/**
+ * The unified diff (`git diff --no-index`) between `before` and the file at `currentPath`, written to `directory` as
+ * `<name>.diff`; null when git has none to give.
+ */
+const writeDiff = (before: string, currentPath: string, directory: string, name: string): WrittenDiff | null => {
+  ensurePrivateDirectory(directory)
+  const beforePath = join(directory, `${name}.before.md`)
+  writePrivateFile(beforePath, before)
+  const diff = Bun.spawnSync(['git', 'diff', '--no-index', '--unified=3', '--', beforePath, currentPath])
+  const text = diff.stdout.toString()
+  if (diff.exitCode !== 1 || text === '') return null
+  const path = join(directory, `${name}.diff`)
+  writePrivateFile(path, text)
+  return { text, path }
+}
+
 /**
  * The change of the orchestrate skill between `snapshot` and the kit at `packageRoot` now: the unified diff
- * (`git diff --no-index`) written to `directory` and the sections it touches, so the coordinator reads the change
- * instead of the whole skill. Unavailable without a snapshot, a readable skill or a diff.
+ * written to `directory` and the sections it touches, so the coordinator reads the change instead of the whole
+ * skill. Unavailable without a snapshot, a readable skill or a diff.
  */
 export const skillChangeSince = (snapshot: string | null, packageRoot: string, directory: string): SkillChange => {
   if (snapshot === null) return { kind: SKILL_CHANGE.unavailable, reason: 'no snapshot at start' }
@@ -29,33 +91,63 @@ export const skillChangeSince = (snapshot: string | null, packageRoot: string, d
   if (current === null) return { kind: SKILL_CHANGE.unavailable, reason: 'skill not readable' }
   if (current === snapshot) return { kind: SKILL_CHANGE.unchanged }
   try {
-    mkdirSync(directory, { recursive: true, mode: 0o700 })
-    const before = join(directory, 'orchestrate-skill.before.md')
-    writePrivate(before, snapshot)
-    const diff = Bun.spawnSync([
-      'git',
-      'diff',
-      '--no-index',
-      '--unified=3',
-      '--',
-      before,
-      orchestrateSkillPath(packageRoot),
-    ])
-    const text = diff.stdout.toString()
-    if (diff.exitCode !== 1 || text === '')
-      return { kind: SKILL_CHANGE.unavailable, reason: `git diff exit ${diff.exitCode}` }
-    const diffPath = join(directory, 'orchestrate-skill.diff')
-    writePrivate(diffPath, text)
-    return { kind: SKILL_CHANGE.changed, sections: changedSections(current, text), diffPath }
+    const diff = writeDiff(snapshot, orchestrateSkillPath(packageRoot), directory, `${ORCHESTRATE_SKILL_NAME}-skill`)
+    if (diff === null) return { kind: SKILL_CHANGE.unavailable, reason: 'git diff gave none' }
+    return { kind: SKILL_CHANGE.changed, sections: changedSections(current, diff.text), diffPath: diff.path }
   } catch (error) {
     return { kind: SKILL_CHANGE.unavailable, reason: errorText(error) }
   }
 }
 
-/** The line about the orchestrate skill after a kit update, for the kit the watcher started with. */
-export const skillLineFor = (kit: StartedKit | null, snapshot: string | null, directory: string): string =>
-  skillChangeLine(
-    kit
-      ? skillChangeSince(snapshot, kit.packageRoot, directory)
-      : { kind: SKILL_CHANGE.unavailable, reason: 'kit not located' },
-  )
+const referenceChangeOf = (
+  delta: ReferenceDelta,
+  snapshot: OrchestrateSnapshot,
+  packageRoot: string,
+  directory: string,
+): ReferenceChange => {
+  const path = join(orchestrateReferencesPath(packageRoot), delta.name)
+  if (delta.kind === REFERENCE_CHANGE.deleted) return { name: delta.name, kind: REFERENCE_CHANGE.deleted }
+  if (delta.kind === REFERENCE_CHANGE.added) return { name: delta.name, kind: REFERENCE_CHANGE.added, path }
+  try {
+    const diff = writeDiff(
+      snapshot.references[delta.name] ?? '',
+      path,
+      directory,
+      `${ORCHESTRATE_SKILL_NAME}-reference-${delta.name}`,
+    )
+    return { name: delta.name, kind: REFERENCE_CHANGE.changed, diffPath: diff?.path ?? null }
+  } catch {
+    return { name: delta.name, kind: REFERENCE_CHANGE.changed, diffPath: null }
+  }
+}
+
+/**
+ * The change of the skill and of its references since `snapshot`. The references are judged only while the skill
+ * can be read, so a package being replaced does not make every reference look deleted.
+ */
+export const orchestrateChangeSince = (
+  snapshot: OrchestrateSnapshot | null,
+  packageRoot: string,
+  directory: string,
+): OrchestrateChange => {
+  const skill = skillChangeSince(snapshot?.skill ?? null, packageRoot, directory)
+  if (snapshot === null || skill.kind === SKILL_CHANGE.unavailable) return { skill, references: [] }
+  const deltas = referenceChanges(snapshot.references, readOrchestrateReferences(packageRoot))
+  return { skill, references: deltas.map((delta) => referenceChangeOf(delta, snapshot, packageRoot, directory)) }
+}
+
+/**
+ * The lines about the orchestrate skill after a kit update, for the kit the watcher started with: the skill's, then one
+ * per changed, new or deleted reference, joined by line breaks.
+ */
+export const skillLineFor = (
+  kit: StartedKit | null,
+  snapshot: OrchestrateSnapshot | null,
+  directory: string,
+): string => {
+  if (kit === null) {
+    return orchestrateChangeLines({ kind: SKILL_CHANGE.unavailable, reason: 'kit not located' }, []).join('\n')
+  }
+  const { skill, references } = orchestrateChangeSince(snapshot, kit.packageRoot, directory)
+  return orchestrateChangeLines(skill, references).join('\n')
+}

package/src/watch/source-change.ts

@@ -0,0 +1,48 @@
+import { existsSync, type FSWatcher, watch } from 'node:fs'
+import { join } from 'node:path'
+import { isRestartTrigger, RESTART_DEBOUNCE_MS } from '../plans/restart-decision'
+
+/** The changes to a package's `src/` seen so far: when the last one came (null before any), and the watch to close. */
+export type SourceChanges = { lastChangeAt: () => number | null; close: () => void }
+
+/**
+ * Whether the package at `packageRoot` is a checkout's own source rather than an installed copy, which lies under a
+ * `node_modules` directory. Only the source changes under a running process (a pull or a fast-forward of the
+ * checkout); an installed copy changes by a reinstall, which its version shows.
+ */
+export const runsFromSource = (packageRoot: string): boolean => !packageRoot.split(/[\\/]/).includes('node_modules')
+
+/** Whether a change seen at `lastChangeAt` is over: no further change for the window in which the herd collapses a burst into one restart. */
+export const sourceChangeSettled = (lastChangeAt: number | null, now: number): boolean =>
+  lastChangeAt !== null && now - lastChangeAt >= RESTART_DEBOUNCE_MS
+
+const NO_CHANGES: SourceChanges = { lastChangeAt: () => null, close: () => {} }
+
+/** The watch of `directory`, closed on a later error (`EMFILE` while dev servers run), which would else end the process. */
+const watcherOf = (directory: string, onChange: () => void): FSWatcher | null => {
+  try {
+    const watcher = watch(directory, { recursive: true }, (_event, name) => {
+      if (name && isRestartTrigger(name.toString())) onChange()
+    })
+    watcher.on('error', () => watcher.close())
+    return watcher
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Follows the source files below `<packageRoot>/src` with the trigger the herd restarts on (`isRestartTrigger`: a
+ * `.ts` file, tests and declarations left out), stamping each change with `clock`. A package without `src/`, or one
+ * the platform cannot watch, is followed for nothing.
+ */
+export const watchSourceChanges = (packageRoot: string, clock: () => number = Date.now): SourceChanges => {
+  const directory = join(packageRoot, 'src')
+  if (!existsSync(directory)) return NO_CHANGES
+  let lastChangeAt: number | null = null
+  const watcher = watcherOf(directory, () => {
+    lastChangeAt = clock()
+  })
+  if (!watcher) return NO_CHANGES
+  return { lastChangeAt: () => lastChangeAt, close: () => watcher.close() }
+}

package/src/watch/source-path.ts

@@ -1,4 +1,4 @@
-import { isRecord } from './json-guards'
+import { isRecord } from '../shared/is-record'
 
 /**
  * Where a field sits in a source's JSON output: `.` is the whole output, else a chain of `.key`, `[n]` and `[-n]`

package/src/watch/sources.ts

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto'
 import { terminalSafe } from '../plan-format/terminal-text'
-import { isRecord } from './json-guards'
+import { isRecord } from '../shared/is-record'
 import { previewUrlOf } from './previews'
 import { CONTENT_FIELDS, SOURCE_FIELD } from './source-fields'
 import { ROOT_PATH, type SourcePath, selectPath } from './source-path'
@@ -94,6 +94,8 @@ export type TicketRecord = { url: string | null; status: string | null; changedA
 export type SourceRecord = {
   seen: SeenEntry[] | null
   failingSince: number | null
+  /** When its last run started, failed or not (`isSourceDue`); absent in a state written before it was kept: never. */
+  ranAt?: number
   /** Of a ticket source only: the entries of its last successful run by id. */
   tickets?: Record<string, TicketRecord>
 }
@@ -248,7 +250,7 @@ export const parseSourceOutput = (
   return { ok: true, items: uniqueById(items as SourceItem[]) }
 }
 
-/** Whether a source last started at `lastRunAt` (undefined: never in this process) is due again at `now`. */
+/** Whether a source last started at `lastRunAt` (`SourceRecord.ranAt`; undefined: never) is due again at `now`. */
 export const isSourceDue = (lastRunAt: number | undefined, everyMinutes: number, now: number): boolean =>
   lastRunAt === undefined || now - lastRunAt >= everyMinutes * MINUTE_MS
 
@@ -342,8 +344,8 @@ const seenAfter = (seen: readonly SeenEntry[], items: readonly SourceItem[]): Se
 
 const recordOf = (record: SourceRecord | undefined, result: SourceResult, now: number): SourceRecord =>
   result.ok
-    ? { seen: seenAfter(record?.seen ?? [], result.items), failingSince: null }
-    : { seen: record?.seen ?? null, failingSince: record?.failingSince ?? now }
+    ? { seen: seenAfter(record?.seen ?? [], result.items), failingSince: null, ranAt: now }
+    : { seen: record?.seen ?? null, failingSince: record?.failingSince ?? now, ranAt: now }
 
 /**
  * The state after `runs` for the sources configured as `names`: a run records its outcome, a source without a run keeps
@@ -385,6 +387,7 @@ const isSourceRecord = (value: unknown): boolean =>
   isRecord(value) &&
   (value.seen === null || (Array.isArray(value.seen) && value.seen.every(isSeenEntry))) &&
   (value.failingSince === null || typeof value.failingSince === 'number') &&
+  (value.ranAt === undefined || typeof value.ranAt === 'number') &&
   (value.tickets === undefined || (isRecord(value.tickets) && Object.values(value.tickets).every(isTicketRecord)))
 
 export const isSourceState = (value: unknown): value is SourceState =>