jackherd 1.8.1 → 1.10.0

package/src/watch/failed-tests.ts

@@ -1,4 +1,5 @@
 import { terminalSafe } from '../plan-format/terminal-text'
+import { stripAnsi } from '../terminal/text'
 
 /** The most failed tests kept for one head commit. */
 export const FAILED_TEST_LIMIT = 50
@@ -29,24 +30,69 @@ const compiled = (pattern: string): RegExp | null => {
   }
 }
 
+/** `places` holds, by test name, the package or test file the log printed before the test; a test before any has none. */
+export type FailedTestScan = { tests: string[]; places: Record<string, string> }
+
+/** `##[group]`, which GitHub Actions folds a section behind, in front of a header line. */
+const GROUP_MARK = /^##\[group\]/
+
+/** The task header a monorepo runner (turbo) prints before a package's run: `@scope/name:test`, the package first. */
+const TASK_HEADER = /^(@[\w.-]+\/[\w.-]+|[\w.-]+):[\w:-]*test[\w:-]*$/
+
+/** The header Bun prints before the results of one test file: its path and a colon. */
+const FILE_HEADER = /^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/
+
+/** Where the scan stands in the log: the package of the current task and the test file of the current run. */
+type ScanPlace = { task: string | null; file: string | null }
+
+/** The place after `line`: a task header starts a new package, a file header a new file. */
+const placeAfter = (place: ScanPlace, line: string): ScanPlace => {
+  const header = stripAnsi(line).replace(GROUP_MARK, '')
+  const task = TASK_HEADER.exec(header)?.[1]
+  if (task) return { task: nameOf(task), file: null }
+  const file = FILE_HEADER.exec(header)?.[1]
+  return file ? { ...place, file: nameOf(file) } : place
+}
+
+const cleanLine = (raw: string): string => raw.replace(/\r$/, '').replace(LOG_PREFIX, '')
+
 /**
- * The names of the failed tests in the log `gh run view <id> --log-failed` printed, in the order first seen. Each line
- * loses its job, step and timestamp prefix, then `pattern` (a regular expression) is matched against it: the first
- * group is the name, else the whole match. A test the log names twice (Bun lists it in the run and in the summary) is
- * listed once. Names are made terminal-safe and cut; at most `FAILED_TEST_LIMIT` are kept. A pattern that is no
- * regular expression finds nothing.
+ * The failed tests in the log `gh run view <id> --log-failed` printed, in the order first seen, with the place each
+ * was first seen in. Each line loses its job, step and timestamp prefix, then `pattern` (a regular expression) is
+ * matched against it: the first group is the name, else the whole match. The place is the package of the task header
+ * before it (`@scope/name:test`), else the test file Bun printed before it. A test the log names twice (Bun lists it
+ * in the run and in the summary) is listed once, at its first place. Names and places are made terminal-safe and cut;
+ * at most `FAILED_TEST_LIMIT` are kept. A pattern that is no regular expression finds nothing.
  */
-export const extractFailedTests = (log: string, pattern: string): string[] => {
+export const scanFailedTests = (log: string, pattern: string): FailedTestScan => {
   const expression = compiled(pattern)
-  if (!expression) return []
+  const places: Record<string, string> = {}
+  if (!expression) return { tests: [], places }
   const names = new Set<string>()
+  let place: ScanPlace = { task: null, file: null }
   for (const raw of log.split('\n')) {
     if (names.size >= FAILED_TEST_LIMIT) break
-    const line = raw.replace(/\r$/, '').replace(LOG_PREFIX, '')
+    const line = cleanLine(raw)
     if (line.length > MAX_LINE_LENGTH) continue
+    place = placeAfter(place, line)
     const match = expression.exec(line)
     const name = nameOf(match?.[1] ?? match?.[0] ?? '')
-    if (name !== '') names.add(name)
+    if (name === '' || names.has(name)) continue
+    names.add(name)
+    const where = place.task ?? place.file
+    if (where) places[name] = where
   }
-  return [...names]
+  return { tests: [...names], places }
 }
+
+/** `places` read back from the state file, for the names in `names` only, made terminal-safe and cut like the names. */
+export const sanitisedFailedTestPlaces = (
+  places: Readonly<Record<string, string>>,
+  names: readonly string[],
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(places).flatMap(([name, place]) => {
+      const shown = nameOf(name)
+      return names.includes(shown) && nameOf(place) !== '' ? [[shown, nameOf(place)]] : []
+    }),
+  )

package/src/watch/failure-read.ts

@@ -1,6 +1,6 @@
-import { extractFailedTests, FAILED_TEST_LIMIT } from './failed-tests'
+import { isRecord } from '../shared/is-record'
+import { FAILED_TEST_LIMIT, scanFailedTests } from './failed-tests'
 import { type GhAnswer, runGh } from './gh'
-import { isRecord } from './json-guards'
 
 /** How long `gh run view --log-failed` may take before the call is given up; a read that timed out is tried again. */
 export const LOG_TIMEOUT_MS = 30_000
@@ -8,8 +8,13 @@ export const LOG_TIMEOUT_MS = 30_000
 /** Of a longer log only this many characters from the end are kept; Bun repeats its failures in the summary there. */
 export const LOG_TAIL_CHARS = 2_000_000
 
-/** `running` is true when a run was still going, which is no failure of the read and is not counted as an attempt. */
-export type FailedTestsRead = { ok: true; tests: string[] } | { ok: false; running: boolean }
+/**
+ * `running` is true when a run was still going, which is no failure of the read and is not counted as an attempt.
+ * `places` names, by test, the package or test file the logs printed before it; absent when they named none.
+ */
+export type FailedTestsRead =
+  | { ok: true; tests: string[]; places?: Record<string, string> }
+  | { ok: false; running: boolean }
 
 type RunGh = (args: string[]) => Promise<GhAnswer>
 
@@ -51,6 +56,13 @@ export const readFailedTests = async (
   const answers = await Promise.all(runIds.map((runId) => run(logArgs(runId))))
   const logs = answers.flatMap((answer) => (answer.ok ? [answer.stdout] : []))
   if (logs.length < answers.length) return { ok: false, running: false }
-  const tests = new Set(logs.flatMap((text) => extractFailedTests(text, pattern)))
-  return { ok: true, tests: [...tests].slice(0, FAILED_TEST_LIMIT) }
+  const scans = logs.map((text) => scanFailedTests(text, pattern))
+  const tests = [...new Set(scans.flatMap((scan) => scan.tests))].slice(0, FAILED_TEST_LIMIT)
+  const places = Object.fromEntries(
+    tests.flatMap((name) => {
+      const place = scans.find((scan) => scan.places[name] !== undefined)?.places[name]
+      return place === undefined ? [] : [[name, place]]
+    }),
+  )
+  return { ok: true, tests, ...(Object.keys(places).length > 0 && { places }) }
 }

package/src/watch/failures.ts

@@ -1,14 +1,21 @@
 import { CHECKS } from '../plans/pull-requests'
+import { isRecord } from '../shared/is-record'
 import type { FailedTestsRead } from './failure-read'
-import { isRecord } from './json-guards'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 
 /**
  * What the watcher read of a red pull request's logs: the tests that failed on `headCommit`. `read` is true once the
  * logs answered (with no test among them, too), `attempts` counts the reads tried, so a run that was still going when
- * it was asked is asked again, a few times, and no head commit is read more than once it has answered.
+ * it was asked is asked again, a few times, and no head commit is read more than once it has answered. `places` names,
+ * by test, the package or test file the log printed before it; absent in a state written before it was read.
  */
-export type FailureRecord = { headCommit: string; tests: string[]; read: boolean; attempts: number }
+export type FailureRecord = {
+  headCommit: string
+  tests: string[]
+  read: boolean
+  attempts: number
+  places?: Record<string, string>
+}
 
 /** Pull request number → what was read for it; kept for the open pull requests only. */
 export type FailureState = Record<string, FailureRecord>
@@ -27,13 +34,17 @@ export const FAILURE_RUN_LIMIT = 3
 
 export const emptyFailureState = (): FailureState => ({})
 
+const isPlaces = (value: unknown): boolean =>
+  value === undefined || (isRecord(value) && Object.values(value).every((place) => typeof place === 'string'))
+
 const isFailureRecord = (value: unknown): boolean =>
   isRecord(value) &&
   typeof value.headCommit === 'string' &&
   Array.isArray(value.tests) &&
   value.tests.every((test) => typeof test === 'string') &&
   typeof value.read === 'boolean' &&
-  typeof value.attempts === 'number'
+  typeof value.attempts === 'number' &&
+  isPlaces(value.places)
 
 export const isFailureState = (value: unknown): value is FailureState =>
   isRecord(value) && Object.values(value).every(isFailureRecord)
@@ -78,7 +89,14 @@ export const failureReadingOf = (
   result: FailedTestsRead,
 ): FailureReading =>
   result.ok
-    ? { number, headCommit, tests: result.tests, read: true, attempts: attempts + 1 }
+    ? {
+        number,
+        headCommit,
+        tests: result.tests,
+        read: true,
+        attempts: attempts + 1,
+        ...(result.places && { places: result.places }),
+      }
     : { number, headCommit, tests: [], read: false, attempts: result.running ? attempts : attempts + 1 }
 
 /**
@@ -105,3 +123,9 @@ export const failedTestsOf = (state: FailureState, number: number, headCommit: s
   const record = state[String(number)]
   return record?.headCommit === headCommit ? record.tests : []
 }
+
+/** The places of the failed tests read for `headCommit` of the pull request; none for any other head commit. */
+export const failedTestPlacesOf = (state: FailureState, number: number, headCommit: string): Record<string, string> => {
+  const record = state[String(number)]
+  return record?.headCommit === headCommit ? (record.places ?? {}) : {}
+}

package/src/watch/feedback.ts

@@ -1,5 +1,5 @@
+import { isRecord } from '../shared/is-record'
 import { FEEDBACK_FORM, type FeedbackForm, type FeedbackItem } from './feedback-item'
-import { isRecord } from './json-guards'
 import { isNoFindingComment, ROUND_WINDOW_MS } from './no-finding'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 

package/src/watch/gh-process.ts

@@ -7,9 +7,10 @@ export type GhAnswer = { ok: true; stdout: string } | { ok: false; error: string
  * `timeoutMs` ends a call that has not finished by then; without it the call waits as long as `gh` does.
  * `tailChars` keeps only that many characters from the end of the output: stdout is read as a stream and never held
  * whole, so memory stays near twice `tailChars` however much `gh` prints. `executable` replaces the `gh` that is run,
- * for a test that stands in for it.
+ * for a test that stands in for it. `stdin` is written to the process's standard input, for a request body too large for
+ * the command line.
  */
-export type GhOptions = { timeoutMs?: number; tailChars?: number; executable?: string }
+export type GhOptions = { timeoutMs?: number; tailChars?: number; executable?: string; stdin?: string }
 
 const readTail = async (stream: ReadableStream<Uint8Array>, tailChars: number): Promise<string> => {
   const decoder = new TextDecoder()
@@ -30,7 +31,12 @@ export const runGh = async (args: string[], cwd: string, options: GhOptions = {}
   let timedOut = false
   let timer: ReturnType<typeof setTimeout> | undefined
   try {
-    const child = Bun.spawn([options.executable ?? 'gh', ...args], { cwd, stdout: 'pipe', stderr: 'pipe' })
+    const child = Bun.spawn([options.executable ?? 'gh', ...args], {
+      cwd,
+      stdin: options.stdin === undefined ? 'ignore' : new Blob([options.stdin]),
+      stdout: 'pipe',
+      stderr: 'pipe',
+    })
     if (options.timeoutMs !== undefined)
       timer = setTimeout(() => {
         timedOut = true

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/json-guards.ts

@@ -1,6 +1,3 @@
-export const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
 /** The entries of a JSON array when every one passes `isValid`; throws `<source>: unexpected answer` otherwise. */
 export const parseArray = <T>(json: string, isValid: (entry: unknown) => entry is T, source: string): T[] => {
   const answer: unknown = JSON.parse(json)

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-fill.ts

@@ -1,6 +1,6 @@
 import type { ContextLevel, ContextReading } from '../context'
+import { isRecord } from '../shared/is-record'
 import { isContextLevel, levelStep } from './coordinator-fill'
-import { isRecord } from './json-guards'
 
 export const LANE_FILL_EVENT = 'lane'
 

package/src/watch/lane-model.ts

@@ -1,5 +1,5 @@
 import { differsFromColumn } from '../plan-format'
-import { isRecord } from './json-guards'
+import { isRecord } from '../shared/is-record'
 
 export const LANE_MODEL_EVENT = 'model'
 

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-parallel.ts

@@ -1,4 +1,4 @@
-import { isRecord } from './json-guards'
+import { isRecord } from '../shared/is-record'
 
 export const LANE_PARALLEL_EVENT = 'parallel'
 

package/src/watch/lane-progress.ts

@@ -2,53 +2,97 @@ 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 phases 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) that can run together, by the plan's dependency table and ticks; empty without a plan, without a table or
- * without two such phases.
+ * 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.
  */
-export const watchedLaneParallel = (
+export const watchedLanePlanText = (
   root: string,
   settings: PlansSettings,
   boardFile: string,
   lane: SprintLane,
-): string[] => {
-  const href = lane.steps.filter((step) => step.planHref !== null).at(-1)?.planHref
-  if (!href) return []
-  const path = resolvePlanPath(dirname(boardRepoPathOf(root, settings, boardFile)), href)
+): string | null => {
+  const path = lanePlanPath(root, settings, boardFile, lane)
+  if (path === null) return null
   const worktreeFile = join(worktreeOf(root, settings, lane.name), path)
-  const text = existsSync(worktreeFile)
+  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.
+ */
+export const watchedLaneParallel = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+  lane: SprintLane,
+): string[] => {
+  const text = watchedLanePlanText(root, settings, boardFile, lane)
   const groups = text === null ? null : parallelGroupsOfPlan(text, settings.planLanguage)
   return groups === null ? [] : parallelBatchOf(groups)
 }

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,
@@ -33,11 +35,14 @@ export type LaneReport = {
   progress: LaneProgress | null
   /** The context level last read for the lane's agent; null without a value. */
   context: ContextLevel | null
+  /** What a resting lane waits on, from its report (`restNote`); absent or null while it works or asks nothing. */
+  rest?: string | null
 }
 
 /** 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
@@ -75,17 +80,34 @@ const contextSegment = (level: ContextLevel | null): string[] =>
   level === null || level === CONTEXT_LEVEL.ok ? [] : [`context ${level}`]
 
 /**
- * One line per lane, in the words of `texts`: `<lane> <status> [· context warn|alert] · <branch>|no branch ·
- * PR #<n> <checks>|no PR · open phase …|phase … ticked, not merged|plan finished|no plan`.
+ * 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`. 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 =>
@@ -150,6 +172,8 @@ export const watchEventLine = (event: WatchEvent, target: string | null): string
     return `=== ${event.kind} ${terminalSafe(event.lane)} ${terminalSafe(event.model)} · board ${terminalSafe(event.column)}`
   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)}`
@@ -296,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-rest.ts

@@ -0,0 +1,28 @@
+import { ellipsize, terminalSafe } from '../plan-format/terminal-text'
+import { questionCount, questionSections } from './report-questions'
+
+const LIST_MARKER = /^(?:\d+[.)]|[-*])\s*/
+const QUESTION_LENGTH = 60
+
+/** The first question as one line: list marker and bold out, made safe, cut. */
+const firstQuestion = (lines: readonly string[], start: number, end: number): string => {
+  const body = lines
+    .slice(start + 1, end)
+    .map((line) => line.trim().replace(LIST_MARKER, '').replaceAll('**', '').trim())
+    .find((line) => line !== '')
+  return ellipsize(terminalSafe(body ?? ''), QUESTION_LENGTH)
+}
+
+/**
+ * What a resting lane (idle or done) is waiting for, from its report: `waits on: <first question>, <n> open
+ * questions`; null without a report or without an open question, so a lane that has nothing to ask stays `idle`.
+ */
+export const restNote = (reportText: string | null): string | null => {
+  if (reportText === null) return null
+  const lines = reportText.split('\n')
+  const sections = questionSections(lines)
+  const [first] = sections
+  if (!first) return null
+  const count = questionCount(lines, sections)
+  return `waits on: ${firstQuestion(lines, first.start, first.end)}, ${count} open ${count === 1 ? 'question' : 'questions'}`
+}