jackherd 1.13.0 → 1.15.0

package/src/watch/command.ts

@@ -95,7 +95,14 @@ import { type LaneReadings, laneFillEvents, recordLaneLevels } from './lane-fill
 import { laneMessage, rememberedStatusLines, statusBlock } from './lane-message'
 import { type LaneModelReading, laneModelEvents, recordLaneModels } from './lane-model'
 import { laneParallelEvents, recordLaneParallels } from './lane-parallel'
-import { boardCheckoutRows, watchedLaneParallel, watchedLaneProgress, watchedPlanPullRequests } from './lane-progress'
+import {
+  boardCheckoutRows,
+  watchedLaneParallel,
+  watchedLaneProgress,
+  watchedPlanPullRequests,
+  watchedReadyPhases,
+  workedPhaseKeys,
+} from './lane-progress'
 import {
   appointmentEventLine,
   approvalDutyLines,
@@ -113,6 +120,9 @@ import {
   noTaskSignalDutyLines,
   otherPullRequestsLine,
   parallelDutyLines,
+  planMissingDutyLines,
+  type ReadyPhase,
+  readyPhaseDutyLines,
   sourceEventLines,
   sourceFailingStatusLine,
   watchEventLine,
@@ -136,6 +146,8 @@ import {
 import { mainCheckoutDutyLine } from './main-checkout'
 import { monitorToolAvailable } from './monitor-tool'
 import { parseWatchOptions, type WatchOptions } from './options'
+import type { PlanMissingEvent, PlanMissingState } from './plan-missing'
+import { readPlanMissingEvents } from './plan-missing-read'
 import {
   ENSURE_TRIGGER,
   type EnsureTrigger,
@@ -311,6 +323,8 @@ type Watching = {
   laneStalls: StallState
   /** The open artifact sends in their grace or already reported as `unlinked artifact`; persisted like the fingerprints. */
   unlinkedArtifacts: UnlinkedState
+  /** Per working lane, the plan last reported as `plan missing on base`; persisted like the fingerprints. */
+  planMissing: PlanMissingState
   /** The approval requests of the last poll; null before the first read, so the stored ids stay. */
   approvalRequests: ApprovalRequestFile[] | null
   /** The board's appointment table at the last poll and the time it was read at; null before the first read and while the board cannot be read. */
@@ -365,6 +379,7 @@ const recordedOf = (watch: Watch, watching: Watching): WatchState => {
     noTaskSignals: watching.noTaskSignals,
     laneStalls: watching.laneStalls,
     unlinkedArtifacts: watching.unlinkedArtifacts,
+    planMissing: watching.planMissing,
     approvals: watching.approvalRequests ? recordApprovals(watching.approvalRequests) : withReads.approvals,
     sources: recordWatchedSources(withReads.sources, watching.sourceRuns, watch.sources, watching.githubReadAt),
     appointments: watching.appointments
@@ -550,12 +565,14 @@ const laneReportOf = (
   }
 }
 
+type BoardReadOrNote = { progress: Record<string, LaneProgress>; checkoutRows: number; notes: string[] }
+
 /** `boardReadOf`, or when the board cannot be read, nothing of it and a note that says why. */
 const boardReadOrNote = async (
   watch: Watch,
   lanes: readonly string[],
   pullRequests: readonly WatchedPullRequest[],
-): Promise<{ progress: Record<string, LaneProgress>; checkoutRows: number; notes: string[] }> => {
+): Promise<BoardReadOrNote> => {
   try {
     return { ...(await boardReadOf(watch, lanes, pullRequests)), notes: [] }
   } catch (error) {
@@ -571,15 +588,15 @@ const boardReadOrNote = async (
  * The lane lines of the status block, the coordinator's line, the line of the own pull requests without a lane that
  * follows it (`others`), and the lines after the block (notes, a gh outage).
  */
-const statusLinesOf = async (
+const statusLinesOf = (
   watch: Watch,
   watching: Watching,
   state: WatchState,
-): Promise<{ laneLines: string[]; coordinator: string; others: string[]; rest: string[] }> => {
+  { progress, checkoutRows, notes }: BoardReadOrNote,
+): { laneLines: string[]; coordinator: string; others: string[]; rest: string[] } => {
   const github = answered(watching.github)
   const pullRequests = github?.pullRequests ?? []
   const others = otherPullRequestsLine(pullRequests, github?.own ?? [], watch.texts)
-  const { progress, checkoutRows, notes } = await boardReadOrNote(watch, watching.lanes, pullRequests)
   const closeLaneHint = hintFor(watch, REFERENCE.closeLane)
   const laneLines = watching.lanes.map((lane) =>
     laneReportLine(
@@ -642,6 +659,19 @@ const mainCheckoutLineAfter = async (
   return mainCheckoutLineOf(watch)
 }
 
+/** The ready phases of the stopped lanes that rest (`done`, `idle`); only their plans are read. */
+const readyPhasesOfResting = (
+  watch: Watch,
+  watching: Watching,
+  stopped: readonly string[],
+  progress: Readonly<Record<string, LaneProgress>>,
+): Record<string, ReadyPhase[]> => {
+  const resting = stopped.filter((lane) => IDLE_STATUSES.has(watching.current[lane]?.status ?? ''))
+  if (resting.length === 0) return {}
+  const lanes = (readSprintLanes(watch) ?? []).filter((lane) => resting.includes(lane.name))
+  return watchedReadyPhases(watch.root, watch.settings, watch.sprintFile, lanes, workedPhaseKeys(progress))
+}
+
 /**
  * Every line of one return, gathered before any is printed, so the output is never cut halfway by a slow lookup, and
  * the state with what it showed: the report times of the stopped lanes and the status lines. A state without status
@@ -657,17 +687,21 @@ const reportOf = async (
   const stops = stoppedLaneSections(watch, watching, stopped, next)
   const eventLines = await eventLinesOf(watch, events, watching.github)
   const mainCheckout = await mainCheckoutLineAfter(watch, watching, events)
+  const board = await boardReadOrNote(watch, watching.lanes, answered(watching.github)?.pullRequests ?? [])
+  const ready = readyPhasesOfResting(watch, watching, stopped, board.progress)
   const dutyLines = [
     ...blockedDutyLines(stopped, watching.current, watch.texts),
+    ...readyPhaseDutyLines(stopped, watching.current, ready, watch.texts),
     ...mergeDutyLines(events, watching.lanes, watch.texts),
     ...(mainCheckout === null ? [] : [mainCheckout]),
     ...laneFillDutyLines(events, watch.texts),
     ...laneModelDutyLines(events, watch.texts),
     ...parallelDutyLines(events, watch.texts),
     ...noTaskSignalDutyLines(events, watch.texts),
+    ...planMissingDutyLines(events, watch.texts),
     ...approvalDutyLines(events, watch.texts),
   ]
-  const status = await statusLinesOf(watch, watching, next)
+  const status = statusLinesOf(watch, watching, next, board)
   const block = statusBlock(status.laneLines, status.coordinator, next.statusLines, status.others)
   const shownReports = stopped.filter((lane) => stops.reportMtimes[lane] !== next.reportMtimes[lane])
   return {
@@ -1129,6 +1163,27 @@ const unlinkedArtifactEventsOf = (watch: Watch, watching: Watching): UnlinkedArt
   }
 }
 
+/**
+ * This heartbeat's `plan missing on base` events: the working lanes whose board row, as their worktree has it, links a
+ * plan the base ref lacks, each once; records the state in `watching`. Nothing when the boards or git cannot be read:
+ * the next heartbeat reads again.
+ */
+const planMissingEventsOf = (watch: Watch, watching: Watching): PlanMissingEvent[] => {
+  try {
+    const { events, state } = readPlanMissingEvents(
+      watch.root,
+      watch.settings,
+      watch.sprintFile,
+      workingLanes(watching),
+      watching.planMissing,
+    )
+    watching.planMissing = state
+    return events
+  } catch {
+    return []
+  }
+}
+
 /** The progress of the working lanes, with the pull requests of the last GitHub read; nothing while no lane works. */
 const workingProgressOf = async (watch: Watch, watching: Watching): Promise<Record<string, LaneProgress>> => {
   const working = workingLanes(watching)
@@ -1137,13 +1192,14 @@ const workingProgressOf = async (watch: Watch, watching: Watching): Promise<Reco
   return progress
 }
 
-/** The events a heartbeat of a report brings: the parallel-task proposals, the lanes without a task signal, the unlinked artifacts. */
+/** The events a heartbeat of a report brings: the parallel-task proposals, the lanes without a task signal, the unlinked artifacts, the plans missing on the base. */
 const heartbeatEventsOf = async (watch: Watch, watching: Watching, now: number): Promise<WatchEvent[]> => {
   const progress = await workingProgressOf(watch, watching)
   return [
     ...taskParallelEventsOf(watch, watching, now),
     ...noTaskSignalEventsOf(watch, watching, progress, now),
     ...unlinkedArtifactEventsOf(watch, watching),
+    ...planMissingEventsOf(watch, watching),
   ]
 }
 
@@ -1206,6 +1262,7 @@ const printStreamHeartbeat = async (watch: Watch, watching: Watching, now: numbe
     ...taskParallelEventsOf(watch, watching, now),
     ...noTaskSignalEventsOf(watch, watching, progress, now),
     ...unlinkedArtifactEventsOf(watch, watching),
+    ...planMissingEventsOf(watch, watching),
   ]
   for (const event of events) console.log(`${watchEventLine(event, null)}${hintFor(watch, eventReference(event))}`)
   return sent
@@ -1307,6 +1364,7 @@ const initialWatching = (
   noTaskSignals: start.state.noTaskSignals,
   laneStalls: start.state.laneStalls,
   unlinkedArtifacts: start.state.unlinkedArtifacts,
+  planMissing: start.state.planMissing,
   approvalRequests: null,
   appointments: null,
   reportQuestions: null,
@@ -1319,7 +1377,8 @@ const saveState = (watch: Watch, watching: Watching) => {
   writePrivateFile(watch.files.state, JSON.stringify(unread ? watching.state : recordedOf(watch, watching)))
 }
 
-const watchLanes = async (watch: Watch) => {
+/** Watches until the lanes end or the kit changes on disk; true when a kit update ended it. */
+const watchLanes = async (watch: Watch): Promise<boolean> => {
   const takeOver = await takeOverLock(watch.files.lock)
   const state = await readState(watch.files)
   const agents = listAgents()
@@ -1358,8 +1417,9 @@ const watchLanes = async (watch: Watch) => {
       await Bun.sleep(POLL_MS)
       pollLanes(watch, watching)
       await announceUpdate?.()
-      if (endedByKitUpdate(kit, effects)) return
+      if (endedByKitUpdate(kit, effects)) return true
     }
+    return false
   } finally {
     sourceChanges?.close()
     stopPublisher?.()
@@ -1425,6 +1485,20 @@ const watchOf = (options: WatchOptions): Watch => {
   }
 }
 
+/** How a watch ended: the kit's source changed under it, or the loop stopped with an exit code. */
+type WatchEnd = { kind: 'kitUpdated' } | { kind: 'stopped'; code: number }
+
+const watchToEnd = async (watch: Watch): Promise<WatchEnd> => {
+  try {
+    return (await watchLanes(watch)) ? { kind: 'kitUpdated' } : { kind: 'stopped', code: 0 }
+  } catch (error) {
+    console.log(`watcher stopped: ${errorText(error)}`)
+    return { kind: 'stopped', code: 1 }
+  } finally {
+    releaseLock(watch.files.lock)
+  }
+}
+
 export const run = async (args: string[]): Promise<number> => {
   let options: WatchOptions
   try {
@@ -1449,13 +1523,9 @@ export const run = async (args: string[]): Promise<number> => {
     console.error(errorText(error))
     return 1
   }
-  try {
-    await watchLanes(watch)
-    return 0
-  } catch (error) {
-    console.log(`watcher stopped: ${errorText(error)}`)
-    return 1
-  } finally {
-    releaseLock(watch.files.lock)
-  }
+  const end = await watchToEnd(watch)
+  // The loop's timers and child handles outlive it, so the process would stay beside the watcher that replaces it;
+  // the state is saved and the lock released, as on SIGTERM.
+  if (end.kind === 'kitUpdated') process.exit(0)
+  return end.code
 }

package/src/watch/lane-message.ts

@@ -1,5 +1,5 @@
 import { terminalSafe } from '../plan-format/terminal-text'
-import { AGENT_STATUS } from './lane-watch'
+import { AGENT_STATUS } from '../terminal/types'
 import { budgetQuestions, questionCount, questionSections } from './report-questions'
 
 /** A lane's report file as the watcher found it: its path, when it was last written, its text. */

package/src/watch/lane-progress.ts

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { type LaneProgress, parallelGroupsOfPlan, resolvePlanPath, type SprintLane } from '../plan-format'
+import { currentPhase, type LaneProgress, parallelGroupsOfPlan, 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'
@@ -8,6 +8,7 @@ import { laneHeads, type PlanPullRequest, planPullRequests } from '../plans/plan
 import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from '../plans/settings'
 import { workedLaneProgress } from '../plans/worked-phases'
 import { parallelBatchOf } from './lane-parallel'
+import { 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. */
@@ -47,9 +48,18 @@ export const watchedLaneProgress = async (
   return workedLaneProgress(lane, plans)
 }
 
+/** The plan link of a lane's newest row that links one, as the board spells it; null without such a row. */
+const newestPlanHref = (lane: SprintLane): string | null =>
+  lane.steps.filter((step) => step.planHref !== null).at(-1)?.planHref ?? null
+
 /** 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
+export const lanePlanPath = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  lane: SprintLane,
+): string | null => {
+  const href = newestPlanHref(lane)
   return href ? resolvePlanPath(dirname(boardRepoPathOf(root, settings, boardFile)), href) : null
 }
 
@@ -97,6 +107,50 @@ export const watchedLaneParallel = (
   return groups === null ? [] : parallelBatchOf(groups)
 }
 
+/** 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}`
+
+/** The ids of the phases in the plan of `planHref` that a lane works on, out of `workedPhaseKeys`. */
+const phaseIdsWorkedIn = (worked: ReadonlySet<string>, planHref: string): Set<string> => {
+  const prefix = workedPhaseKey(planHref, '')
+  return new Set([...worked].flatMap((key) => (key.startsWith(prefix) ? [key.slice(prefix.length)] : [])))
+}
+
+/** The phases the lanes work on: the current phase of each lane's progress that has one, with its plan link. */
+export const workedPhaseKeys = (progress: Readonly<Record<string, LaneProgress>>): Set<string> =>
+  new Set(
+    Object.values(progress).flatMap((each) => {
+      const phase = currentPhase(each)
+      const planHref = each.current === null ? null : each.steps[each.current.stepIndex]?.step.planHref
+      return phase && planHref ? [workedPhaseKey(planHref, phase.id)] : []
+    }),
+  )
+
+/**
+ * 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
+ * without a readable plan.
+ */
+export const watchedReadyPhases = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  lanes: readonly SprintLane[],
+  worked: ReadonlySet<string>,
+): Record<string, ReadyPhase[]> =>
+  Object.fromEntries(
+    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)),
+      ]
+    }),
+  )
+
 /**
  * The rows the checkout's board file (`checkoutText`) has beyond the board at the base ref, counted as the herd
  * adds them; 0 when the base ref lacks the board, which is then read from the checkout as a whole.

package/src/watch/lane-report.ts

@@ -1,9 +1,22 @@
 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 {
+  currentPhase,
+  isPhaseFinished,
+  isPhaseOpen,
+  isTickedUnmerged,
+  type LaneProgress,
+  parseDependencyTable,
+  parsePlanPhases,
+  phaseLabel,
+  phaseLabels,
+  phasesText,
+} from '../plan-format'
 import { terminalSafe } from '../plan-format/terminal-text'
 import { CHECK_NAME_LENGTH, type ChecksState } from '../plans/pull-requests'
 import { shownWithMore } from '../plans/shown-with-more'
+import { AGENT_STATUS } from '../terminal/types'
+import type { PlanLanguage } from '../vocabulary'
 import type { AppointmentEvent } from './appointments'
 import type { ApprovalEvent } from './approvals'
 import type { CoordinatorRead } from './coordinator-fill'
@@ -12,7 +25,8 @@ import type { LaneFillEvent } from './lane-fill'
 import type { LaneModelEvent } from './lane-model'
 import type { LaneParallelEvent } from './lane-parallel'
 import { laneStalledLine } from './lane-stalled'
-import { AGENT_STATUS, type LaneSnapshot, NO_AGENT } from './lane-watch'
+import { type LaneSnapshot, NO_AGENT } from './lane-watch'
+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'
 import { type FieldChange, lineText, type SourceEvent } from './sources'
@@ -161,6 +175,7 @@ const laneEventLine = (event: WatchEvent): string | null => {
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${phasesText(event.phases)}`
   if (event.kind === WATCH_EVENT.noTaskSignal) return `=== ${terminalSafe(noTaskSignalLine(event))}`
   if (event.kind === WATCH_EVENT.laneStalled) return `=== ${terminalSafe(laneStalledLine(event))}`
+  if (event.kind === WATCH_EVENT.planMissing) return `=== ${planMissingLine(event)}`
   return null
 }
 
@@ -339,6 +354,14 @@ export const noTaskSignalDutyLines = (events: readonly WatchEvent[], texts: Watc
     .filter(isNoTaskSignal)
     .map(({ lane }) => `${terminalSafe(lane)} ${NO_TASK_SIGNAL_EVENT}: ${texts.noTaskSignalDuty}`)
 
+const isPlanMissing = (event: WatchEvent): event is PlanMissingEvent => event.kind === WATCH_EVENT.planMissing
+
+/** What a lane whose plan only its worktree has asks of the coordinator (`orchestrate` § 2 step 0): one line per such lane. */
+export const planMissingDutyLines = (events: readonly WatchEvent[], texts: WatchTexts): string[] =>
+  events
+    .filter(isPlanMissing)
+    .map(({ lane }) => `${terminalSafe(lane)} ${PLAN_MISSING_EVENT}: ${texts.planMissingDuty}`)
+
 const isApproval = (event: WatchEvent): event is ApprovalEvent => event.kind === WATCH_EVENT.approval
 
 /**
@@ -360,6 +383,48 @@ export const blockedDutyLines = (stopped: readonly string[], current: LaneSnapsh
     .filter((lane) => current[lane]?.status === AGENT_STATUS.blocked)
     .map((lane) => `${terminalSafe(lane)} ${AGENT_STATUS.blocked}: ${texts.blockedDuty}`)
 
+/** An open phase whose dependencies are all ticked off, with the phases it waited for. */
+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.
+ */
+export const readyPhasesOf = (markdown: string, language: PlanLanguage, worked: ReadonlySet<string>): ReadyPhase[] => {
+  const table = parseDependencyTable(markdown, language) ?? []
+  const phases = parsePlanPhases(markdown, language)
+  const finished = new Set(phases.filter(isPhaseFinished).map(({ id }) => id))
+  const open = new Set(phases.filter(isPhaseOpen).map(({ id }) => id))
+  return table
+    .filter(
+      ({ id, after, external }) =>
+        open.has(id) && !worked.has(id) && external.length === 0 && after.every((each) => finished.has(each)),
+    )
+    .map(({ id, after }) => ({ id, after }))
+}
+
+const readyPhaseText = ({ id, after }: ReadyPhase): string =>
+  `${phaseLabel(id)}${after.length > 0 ? ` (after ${phaseLabels(after, ', ')})` : ''}`
+
+/**
+ * What a resting lane (`done` or `idle`) with ready phases asks of the coordinator (`orchestrate` § 2): one line per such
+ * lane, naming every ready phase, to start it now; a pull request waiting for approval holds only the commit.
+ */
+export const readyPhaseDutyLines = (
+  stopped: readonly string[],
+  current: LaneSnapshot,
+  ready: Readonly<Record<string, readonly ReadyPhase[]>>,
+  texts: WatchTexts,
+): string[] =>
+  stopped.flatMap((lane) => {
+    const phases = ready[lane] ?? []
+    if (phases.length === 0 || !RESTING_STATUSES.has(current[lane]?.status ?? '')) return []
+    return [
+      `${terminalSafe(lane)} ready: ${phases.map(readyPhaseText).join(', ')}: ${texts.readyPhaseDuty(phases.length)}`,
+    ]
+  })
+
 const takeOverNote = ({ replaced, stillRunning }: TakeOver): string => {
   if (stillRunning !== null) return ` (watcher ${stillRunning} did not stop)`
   return replaced === null ? '' : ` (replaced watcher ${replaced})`

package/src/watch/lane-watch.ts

@@ -1,7 +1,6 @@
-export type HerdrAgent = { name?: string; pane_id: string; agent_status: string; state_change_seq?: number }
+import { AGENT_STATUS } from '../terminal/types'
 
-/** The herdr agent states; herdr's JSON delivers them as plain strings. */
-export const AGENT_STATUS = { working: 'working', blocked: 'blocked', done: 'done', idle: 'idle' } as const
+export type HerdrAgent = { name?: string; pane_id: string; agent_status: string; state_change_seq?: number }
 
 /** The state a report gives a lane whose agent left the herdr listing. */
 export const LANE_GONE = 'no longer listed'
@@ -9,8 +8,6 @@ export const LANE_GONE = 'no longer listed'
 /** The state a report gives a lane that has no agent in herdr. */
 export const NO_AGENT = 'no agent'
 
-export type AgentStatus = (typeof AGENT_STATUS)[keyof typeof AGENT_STATUS]
-
 export type LaneState = { status: string; seq: number | null }
 
 export type LaneSnapshot = Record<string, LaneState>
@@ -20,9 +17,6 @@ export type SeenSeqs = Record<string, number | null>
 
 const STOP_STATUSES = new Set<string>([AGENT_STATUS.blocked, AGENT_STATUS.done, AGENT_STATUS.idle])
 
-export const isAgentStatus = (value: string): value is AgentStatus =>
-  (Object.values(AGENT_STATUS) as string[]).includes(value)
-
 /** The state of each named lane in a `herdr agent list` answer; unnamed and other agents are left out. */
 export const toSnapshot = (agents: readonly HerdrAgent[], lanes: readonly string[]): LaneSnapshot =>
   Object.fromEntries(

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

@@ -0,0 +1,47 @@
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { parseSprintLanes } from '../plan-format'
+import { baseReaderAt, commitOf } from '../plans/git'
+import { isOutsideRepository } from '../plans/lane-plans'
+import { baseRefOf, boardRepoPathOf, type PlansSettings, worktreeOf } from '../plans/settings'
+import { lanePlanPath } from './lane-progress'
+import {
+  type PlanMissingEvent,
+  type PlanMissingReadings,
+  type PlanMissingState,
+  planMissingEvents,
+} from './plan-missing'
+
+/**
+ * The plan the lane's newest linking row names in the board as its worktree has it; null without a worktree board or
+ * row, or for a link that leaves the repository, which no base ref can hold.
+ */
+const worktreePlanOf = (root: string, settings: PlansSettings, boardFile: string, laneName: string): string | null => {
+  const file = join(worktreeOf(root, settings, laneName), boardRepoPathOf(root, settings, boardFile))
+  if (!existsSync(file)) return null
+  const lane = parseSprintLanes(readFileSync(file, 'utf8'), settings.planLanguage).find(({ name }) => name === laneName)
+  const path = lane === undefined ? null : lanePlanPath(root, settings, boardFile, lane)
+  return path === null || isOutsideRepository(path) ? null : path
+}
+
+/**
+ * This heartbeat's `plan missing on base` events and the state to keep, for the working lanes: the plan of each lane's
+ * row in its own worktree against the base ref, where a worktree made from the base would not find it. Nothing when
+ * the base ref does not resolve, which would make every plan look missing.
+ */
+export const readPlanMissingEvents = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  workingLanes: readonly string[],
+  previous: PlanMissingState,
+): { events: PlanMissingEvent[]; state: PlanMissingState } => {
+  const baseRef = baseRefOf(settings)
+  const commit = commitOf(root, baseRef)
+  if (commit === null) return { events: [], state: previous }
+  const base = baseReaderAt(root, commit)
+  const readings: PlanMissingReadings = Object.fromEntries(
+    workingLanes.map((lane) => [lane, worktreePlanOf(root, settings, boardFile, lane)]),
+  )
+  return planMissingEvents(previous, readings, (path) => base(path) !== null, baseRef)
+}

package/src/watch/plan-missing.ts

@@ -0,0 +1,43 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { isRecord } from '../shared/is-record'
+
+export const PLAN_MISSING_EVENT = 'plan missing on base'
+
+/** Per working lane: the plan its newest board row links, as its worktree has it; null without one. */
+export type PlanMissingReadings = Readonly<Record<string, string | null>>
+
+/** Per lane: the plan path last reported as missing on the base ref; a lane whose plan is there has no entry. */
+export type PlanMissingState = Record<string, string>
+
+export type PlanMissingEvent = { kind: typeof PLAN_MISSING_EVENT; lane: string; path: string; baseRef: string }
+
+/**
+ * One event per working lane whose board row, as its worktree has it, links a plan the base ref lacks (`existsAtBase`
+ * answers for a repository path). A plan is reported once while it stays missing: the state clears when it reaches the
+ * base or the row links another, and a lane without a reading (not at work) keeps what it had.
+ */
+export const planMissingEvents = (
+  previous: PlanMissingState,
+  readings: PlanMissingReadings,
+  existsAtBase: (path: string) => boolean,
+  baseRef: string,
+): { events: PlanMissingEvent[]; state: PlanMissingState } => {
+  const events: PlanMissingEvent[] = []
+  const state: PlanMissingState = { ...previous }
+  for (const [lane, planPath] of Object.entries(readings)) {
+    if (planPath === null || existsAtBase(planPath)) {
+      delete state[lane]
+      continue
+    }
+    if (previous[lane] !== planPath) events.push({ kind: PLAN_MISSING_EVENT, lane, path: planPath, baseRef })
+    state[lane] = planPath
+  }
+  return { events, state }
+}
+
+/** `lane <name> plan missing on <base ref>: <path>`. */
+export const planMissingLine = ({ lane, path, baseRef }: PlanMissingEvent): string =>
+  `lane ${terminalSafe(lane)} plan missing on ${terminalSafe(baseRef)}: ${terminalSafe(path)}`
+
+export const isPlanMissingState = (value: unknown): value is PlanMissingState =>
+  isRecord(value) && Object.values(value).every((path) => typeof path === 'string')

package/src/watch/reference-paths.ts

@@ -37,6 +37,7 @@ const EVENT_REFERENCES: Readonly<Record<string, Reference>> = {
   [WATCH_EVENT.taskParallel]: REFERENCE.events,
   [WATCH_EVENT.noTaskSignal]: REFERENCE.events,
   [WATCH_EVENT.unlinkedArtifact]: REFERENCE.events,
+  [WATCH_EVENT.planMissing]: REFERENCE.events,
   [UPDATE_AVAILABLE_EVENT]: REFERENCE.events,
   [WATCH_EVENT.laneModel]: REFERENCE.laneSession,
 }

package/src/watch/task-parallel-touched.ts

@@ -1,13 +1,20 @@
 import { isAbsolute, relative } from 'node:path'
+import { CLAUDE_TOOL, CONTENT_BLOCK_TYPE } from '../context/log-vocabulary'
 import { parseLogEntry } from '../context/session-log'
 import { isRecord } from '../shared/is-record'
 
-const WRITING_TOOLS: ReadonlySet<string> = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit'])
+const WRITING_TOOLS: ReadonlySet<string> = new Set([
+  CLAUDE_TOOL.edit,
+  CLAUDE_TOOL.write,
+  CLAUDE_TOOL.multiEdit,
+  CLAUDE_TOOL.notebookEdit,
+])
 
 const writtenPathsOf = (entry: Record<string, unknown>): string[] => {
   const content = isRecord(entry.message) && Array.isArray(entry.message.content) ? entry.message.content : []
   return content.flatMap((block) => {
-    if (!isRecord(block) || block.type !== 'tool_use' || !WRITING_TOOLS.has(String(block.name))) return []
+    if (!isRecord(block) || block.type !== CONTENT_BLOCK_TYPE.toolUse || !WRITING_TOOLS.has(String(block.name)))
+      return []
     const input = isRecord(block.input) ? block.input : {}
     const path = input.file_path ?? input.notebook_path
     return typeof path === 'string' ? [path] : []

package/src/watch/texts.ts

@@ -28,8 +28,12 @@ export type WatchTexts = {
   parallelDuty: (phases: string) => string
   /** What a lane that works without a task signal asks of the coordinator. */
   noTaskSignalDuty: string
+  /** What a lane whose plan the base ref lacks asks of the coordinator. */
+  planMissingDuty: string
   /** What a lane's call waiting for approval asks of the coordinator, with the mark (request id and call hash) the question must carry. */
   approvalDuty: (id: string, hash: string) => string
+  /** What a resting lane with ready phases asks of the coordinator, with how many phases are ready. */
+  readyPhaseDuty: (count: number) => string
   /** The standing duty while the main checkout is behind its base branch on the remote (`origin/main`), with the count of commits. */
   mainCheckoutBehind: (remoteBase: string, count: number) => string
   /** The standing duty while the main checkout has another branch than the base checked out (null for a detached head). */
@@ -70,8 +74,12 @@ export const watchTexts = (dialogLanguage: PlanLanguage): WatchTexts => ({
   parallelDuty: (phases) =>
     `${phases} can run in parallel: propose it to the user, check content and release files yourself (the table covers paths and markers only)`,
   noTaskSignalDuty: 'remind the lane to report its task with jh task start; do not stop it',
+  planMissingDuty:
+    "the herd shows the base ref's plan, not this one: run § 2 step 0 for it, copying from the lane's worktree",
   laneModelDuty:
     'switch it while idle: /exit, then claude --resume <session> --model <id> in the same pane (§ 2 step 6)',
+  readyPhaseDuty: (count) =>
+    `start ${count === 1 ? 'it' : 'them'} now (§ 2); a waiting PR approval holds only the commit`,
   mainCheckoutBehind: (remoteBase, count) =>
     `main checkout behind ${remoteBase} by ${count} (git merge --ff-only ${remoteBase})`,
   mainCheckoutOffBase: (branch, baseBranch) => `main checkout on ${branch ?? 'a detached head'}, not ${baseBranch}`,