jackherd 1.14.0 → 1.15.1

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,
@@ -114,6 +121,8 @@ import {
   otherPullRequestsLine,
   parallelDutyLines,
   planMissingDutyLines,
+  type ReadyPhase,
+  readyPhaseDutyLines,
   sourceEventLines,
   sourceFailingStatusLine,
   watchEventLine,
@@ -556,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) {
@@ -577,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(
@@ -648,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
@@ -663,8 +687,11 @@ 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),
@@ -674,7 +701,7 @@ const reportOf = async (
     ...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 {
@@ -1350,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()
@@ -1389,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?.()
@@ -1456,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 {
@@ -1480,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,6 +48,10 @@ 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. */
 export const lanePlanPath = (
   root: string,
@@ -54,7 +59,7 @@ export const lanePlanPath = (
   boardFile: string,
   lane: SprintLane,
 ): string | null => {
-  const href = lane.steps.filter((step) => step.planHref !== null).at(-1)?.planHref
+  const href = newestPlanHref(lane)
   return href ? resolvePlanPath(dirname(boardRepoPathOf(root, settings, boardFile)), href) : null
 }
 
@@ -102,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,7 @@ 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'
@@ -370,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/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

@@ -32,6 +32,8 @@ export type WatchTexts = {
   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). */
@@ -76,6 +78,8 @@ export const watchTexts = (dialogLanguage: PlanLanguage): WatchTexts => ({
     "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}`,