jackherd 1.12.7 → 1.14.0

package/src/watch/lane-report.ts

@@ -13,6 +13,7 @@ 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 { 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 +162,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 +341,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
 
 /**

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/texts.ts

@@ -28,6 +28,8 @@ 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
   /** The standing duty while the main checkout is behind its base branch on the remote (`origin/main`), with the count of commits. */
@@ -70,6 +72,8 @@ 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)',
   mainCheckoutBehind: (remoteBase, count) =>

package/src/watch/watch-events.ts

@@ -16,6 +16,7 @@ import { isLaneModels, LANE_MODEL_EVENT, type LaneModelEvent, type LaneModels }
 import { isLaneParallels, LANE_PARALLEL_EVENT, type LaneParallelEvent, type LaneParallels } from './lane-parallel'
 import { isStallState, LANE_STALLED_EVENT, type LaneStalledEvent, type StallState } from './lane-stalled'
 import { type LaneSnapshot, type SeenSeqs, seenSeqsOf } from './lane-watch'
+import { isPlanMissingState, PLAN_MISSING_EVENT, type PlanMissingEvent, type PlanMissingState } from './plan-missing'
 import { emptyPreviewState, isPreviewState, PREVIEW_EVENT, type PreviewEvent, type PreviewState } from './previews'
 import { PULL_REQUEST_STATE, type WatchedPullRequest } from './pull-requests'
 import { emptySourceState, isSourceState, SOURCE_EVENT, type SourceEvent, type SourceState } from './sources'
@@ -60,6 +61,7 @@ export const WATCH_EVENT = {
   noTaskSignal: NO_TASK_SIGNAL_EVENT,
   laneStalled: LANE_STALLED_EVENT,
   unlinkedArtifact: UNLINKED_ARTIFACT_EVENT,
+  planMissing: PLAN_MISSING_EVENT,
   approval: APPROVAL_EVENT,
   source: SOURCE_EVENT,
   due: APPOINTMENT_EVENT.due,
@@ -122,6 +124,8 @@ export type WatchState = {
   laneStalls: StallState
   /** Per open artifact send no plan or board links: in its grace or already reported as `unlinked artifact`. */
   unlinkedArtifacts: UnlinkedState
+  /** Per working lane whose board row links a plan the base ref lacks: the plan last reported as `plan missing on base`. */
+  planMissing: PlanMissingState
   /** The ids of the approval requests on disk when they were last read, each reported once while it is open. */
   approvals: string[]
   /** Per configured source of `watch.sources`: the entries seen (`[id, fingerprint]`) and the start of a failure streak. */
@@ -185,6 +189,7 @@ export type WatchEvent =
   | NoTaskSignalEvent
   | LaneStalledEvent
   | UnlinkedArtifactEvent
+  | PlanMissingEvent
   | ApprovalEvent
   | SourceEvent
   | AppointmentEvent
@@ -224,6 +229,7 @@ export const emptyWatchState = (): WatchState => ({
   noTaskSignals: {},
   laneStalls: {},
   unlinkedArtifacts: {},
+  planMissing: {},
   approvals: [],
   sources: emptySourceState(),
   reportMtimes: {},
@@ -277,6 +283,7 @@ const isWatchState = (value: Record<string, unknown>): value is WatchState =>
   isNoSignalState(value.noTaskSignals) &&
   isStallState(value.laneStalls) &&
   isUnlinkedState(value.unlinkedArtifacts) &&
+  isPlanMissingState(value.planMissing) &&
   Array.isArray(value.approvals) &&
   value.approvals.every((id) => typeof id === 'string') &&
   isSourceState(value.sources) &&