jackherd 1.16.0 → 1.17.0

package/src/lane/send-options.ts

@@ -0,0 +1,23 @@
+import { CLI_NAME } from '../version/release'
+
+/** What `jh lane send` was asked for; `file` is null where `--file` was left out. */
+export type SendOptions = { lane: string; file: string | null }
+
+const FILE = '--file'
+
+export const LANE_SEND_USAGE = `usage: ${CLI_NAME} lane send <lane> [${FILE} <prompt-file>]
+
+Sends the lane's prompt file (default: .claude/handover/<lane>-prompt.md of the main checkout) to its agent and waits
+until it works. On a stall it reads the screen: a lane at work counts as sent, a prompt on the screen gets enter (exit 1 if that does not start the lane), else the
+file is sent once more. A second stall exits 1 with one line for the coordinator.`
+
+/** Reads `<lane> [--file <path>]`; throws with the usage on anything else. */
+export const parseSendOptions = (args: readonly string[]): SendOptions => {
+  const [lane, ...rest] = args
+  if (lane === undefined || lane.startsWith('-')) throw new Error(LANE_SEND_USAGE)
+  if (rest.length === 0) return { lane, file: null }
+  const [option, file, ...extra] = rest
+  if (option !== FILE || file === undefined || file.startsWith('--') || extra.length > 0)
+    throw new Error(LANE_SEND_USAGE)
+  return { lane, file }
+}

package/src/lane/send.ts

@@ -0,0 +1,90 @@
+/** The codes of herdr's answer to `herdr agent prompt --wait` that do not prove the text is lost. */
+export const SEND_CODE = { stalled: 'agent_prompt_stalled', timeout: 'timeout' } as const
+
+/** How long the input line's mark is: whole on any screen width the lane's pane has. */
+const MARK_LENGTH = 40
+
+type Awaitable<T> = T | Promise<T>
+
+/** What one call of herdr answered: `ok`, else the `error.code` of its answer, null when it named none. */
+export type HerdrAnswer = { ok: boolean; code: string | null }
+
+/** The calls the send makes on the lane's agent; the command wires them to `herdr`. */
+export type SendPorts = {
+  /** `herdr agent prompt <lane> <text> --wait --until working`. */
+  prompt: (lane: string, text: string) => Awaitable<HerdrAnswer>
+  /** Whether herdr reports the lane's agent as working. */
+  isWorking: (lane: string) => Awaitable<boolean>
+  /** The visible screen of the lane's agent. */
+  screen: (lane: string) => Awaitable<string>
+  /** `herdr agent send-keys <lane> enter`. */
+  enter: (lane: string) => Awaitable<HerdrAnswer>
+  /** Whether the lane's agent starts working within a few seconds. */
+  awaitWorking: (lane: string) => Awaitable<boolean>
+}
+
+export type SendOutcome = {
+  kind: 'sent' | 'entered' | 'resent' | 'failed'
+  exitCode: 0 | 1
+  /** The one line for Jack. */
+  line: string
+}
+
+const isStall = ({ code }: HerdrAnswer): boolean => code === SEND_CODE.stalled || code === SEND_CODE.timeout
+
+/** The start of the prompt's first line: what the input line shows while the text waits there, unsent. */
+export const inputLineMarkOf = (prompt: string): string =>
+  (prompt.split('\n').find((line) => line.trim() !== '') ?? '').slice(0, MARK_LENGTH)
+
+const outcome = (kind: SendOutcome['kind'], lane: string, text: string): SendOutcome => ({
+  kind,
+  exitCode: kind === 'failed' ? 1 : 0,
+  line: `${lane}: ${text}`,
+})
+
+const refused = (lane: string, answer: HerdrAnswer): SendOutcome =>
+  outcome('failed', lane, `herdr refused the prompt (${answer.code ?? 'unknown'}); ask the user.`)
+
+/** Whether the start of the prompt is on the visible screen: in the input line, or already in the transcript. */
+const screenShowsPrompt = async (ports: SendPorts, lane: string, prompt: string): Promise<boolean> => {
+  const mark = inputLineMarkOf(prompt)
+  return mark !== '' && (await ports.screen(lane)).includes(mark)
+}
+
+/**
+ * After a stall: done when the lane works; `enter` when the prompt is on the screen (an `enter` on an empty input line
+ * does nothing); null when the screen does not show it. `stuck` is a prompt on the screen that `enter` did not start:
+ * sending the file again would append it to the text that waits.
+ */
+const recovered = async (
+  ports: SendPorts,
+  lane: string,
+  prompt: string,
+): Promise<'working' | 'entered' | 'stuck' | null> => {
+  if (await ports.isWorking(lane)) return 'working'
+  if (!(await screenShowsPrompt(ports, lane, prompt))) return null
+  const answer = await ports.enter(lane)
+  return answer.ok && (await ports.awaitWorking(lane)) ? 'entered' : 'stuck'
+}
+
+/**
+ * Sends the prompt text to the lane and makes sure it arrived. A stall or a timeout does not prove the text is lost:
+ * the screen decides. A lane at work is done; a prompt on the screen gets `enter`, and an `enter` the lane does not
+ * answer ends with exit 1, since another send would append to the waiting text; a screen without the prompt sends the
+ * text once more. A second stall, or any other error, ends with exit 1 and a line for Jack.
+ */
+export const sendLanePrompt = async (ports: SendPorts, lane: string, prompt: string): Promise<SendOutcome> => {
+  const first = await ports.prompt(lane, prompt)
+  if (first.ok) return outcome('sent', lane, 'prompt sent.')
+  if (!isStall(first)) return refused(lane, first)
+  const state = await recovered(ports, lane, prompt)
+  if (state === 'working') return outcome('sent', lane, 'prompt sent, the lane works.')
+  if (state === 'entered') return outcome('entered', lane, 'prompt was waiting in the input line, sent with enter.')
+  if (state === 'stuck')
+    return outcome('failed', lane, 'the prompt is on the screen and enter did not start the lane; ask the user.')
+  const second = await ports.prompt(lane, prompt)
+  if (second.ok || (await ports.isWorking(lane))) return outcome('resent', lane, 'prompt sent a second time.')
+  return isStall(second)
+    ? outcome('failed', lane, 'the prompt stalled twice and the lane does not work; ask the user.')
+    : refused(lane, second)
+}

package/src/lane/skill-hint.ts

@@ -0,0 +1,27 @@
+import { existsSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { DEFAULT_SKILL_PREFIX } from '../config/schema'
+import { mainCheckoutOrNull } from '../plans/git'
+import { readSettings } from '../plans/settings'
+import { type Reference, referenceHint, skillCopiesFor, skillDirectoryFor } from '../watch/reference-paths'
+
+/** The directory of the orchestrate skill installed for `root`: the project's copy, else the global one; null without. */
+export const installedSkillDirectory = (root: string, home: string = homedir()): string | null =>
+  skillDirectoryFor(skillCopiesFor(root, home, readSettings([root]).skillPrefix, DEFAULT_SKILL_PREFIX), existsSync)
+
+/**
+ * ` · read <skill directory>/<reference>` for the orchestrate skill installed for `root`; empty without one. A command
+ * that also runs without orchestrate (`jh check`, `jh plan check`, `jh waiting`) stays silent then, so a user who does
+ * not have the skill is not sent to its files; orchestrate's own commands (`jh lane`, the watcher) name the skill
+ * instead (`referenceHint` with no directory).
+ */
+export const installedReferenceHint = (root: string, reference: Reference, home: string = homedir()): string => {
+  const directory = installedSkillDirectory(root, home)
+  return directory === null ? '' : referenceHint(reference, directory)
+}
+
+/** `installedReferenceHint` for the main checkout of the repository `cwd` is in; empty outside a git checkout. */
+export const installedReferenceHintFor = (cwd: string, reference: Reference): string => {
+  const root = mainCheckoutOrNull(cwd)
+  return root === null ? '' : installedReferenceHint(root, reference)
+}

package/src/lane/space-command.ts

@@ -0,0 +1,30 @@
+import { statfsSync } from 'node:fs'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { readSettings } from '../plans/settings'
+import { asksForHelp } from '../preview/options'
+import { freeSpaceLine, LANE_SPACE_USAGE, parseSpaceOptions, spaceVerdict } from './space'
+
+/** The bytes a normal user can still write on the disk that holds `path`. */
+const freeBytesAt = (path: string): number => {
+  const { bavail, bsize } = statfsSync(path)
+  return Number(bavail) * Number(bsize)
+}
+
+/** `jh lane space [--min-gb <n>]`: prints one line; exit 0 with room for a lane, 1 without, or on a wrong line. */
+export const run = (args: string[], cwd: string = process.cwd()): number => {
+  if (asksForHelp(args)) {
+    console.log(LANE_SPACE_USAGE)
+    return 0
+  }
+  try {
+    const root = mainCheckout(cwd)
+    const { minFreeGb } = readSettings([root, worktreeRoot(cwd)])
+    const needed = parseSpaceOptions(args).minFreeGb ?? minFreeGb
+    const verdict = spaceVerdict(freeBytesAt(root), needed)
+    console.log(freeSpaceLine(verdict))
+    return verdict.enough ? 0 : 1
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}

package/src/lane/space.ts

@@ -0,0 +1,49 @@
+import { CLI_NAME } from '../version/release'
+
+/**
+ * Free space a new lane needs before its dependencies are installed, in gigabytes. Measured 24.10.2026: a first
+ * `bun install` of a worktree writes 2.3 GB when the cache holds none of it, and a warm one about 0.1 GB beside the
+ * 0.2 GB checkout (the packages are hardlinks into the cache); the rest is room to build and test.
+ */
+export const DEFAULT_MIN_FREE_GB = 5
+
+const BYTES_PER_GB = 1024 ** 3
+const COLD_INSTALL_GB = 2.3
+
+/** `minFreeGb` is null where `--min-gb` was left out: the configured threshold then stands. */
+export type SpaceOptions = { minFreeGb: number | null }
+
+export type SpaceVerdict = { enough: boolean; freeGb: number; neededGb: number }
+
+const MIN_GB_OPTION = '--min-gb'
+
+export const LANE_SPACE_USAGE = `usage: ${CLI_NAME} lane space [${MIN_GB_OPTION} <gigabytes>]
+
+Checks that the disk holds enough free space for a new lane before its dependencies are installed; exit 1 and one line
+when it does not. The threshold is lanes.minFreeGb of the config (default ${DEFAULT_MIN_FREE_GB} GB) unless ${MIN_GB_OPTION} says otherwise.`
+
+/** Reads `[--min-gb <n>]`; throws with the usage on anything else. */
+export const parseSpaceOptions = (args: readonly string[]): SpaceOptions => {
+  if (args.length === 0) return { minFreeGb: null }
+  const [option, value, ...rest] = args
+  if (option !== MIN_GB_OPTION || rest.length > 0) throw new Error(LANE_SPACE_USAGE)
+  const minFreeGb = Number(value)
+  if (value === undefined || !Number.isFinite(minFreeGb) || minFreeGb <= 0)
+    throw new Error(`${MIN_GB_OPTION} needs a number of gigabytes above 0\n${LANE_SPACE_USAGE}`)
+  return { minFreeGb }
+}
+
+const roundedDown = (value: number): number => Math.floor(value * 10) / 10
+
+/** Whether `freeBytes` reach the threshold; the free value is rounded down to one decimal. */
+export const spaceVerdict = (freeBytes: number, neededGb: number): SpaceVerdict => ({
+  enough: freeBytes >= neededGb * BYTES_PER_GB,
+  freeGb: roundedDown(freeBytes / BYTES_PER_GB),
+  neededGb,
+})
+
+/** The one line the command prints, for the coordinator to pass on. */
+export const freeSpaceLine = ({ enough, freeGb, neededGb }: SpaceVerdict): string =>
+  enough
+    ? `${freeGb} GB free, ${neededGb} GB needed: room for a lane`
+    : `no lane started: ${freeGb} GB free, ${neededGb} GB needed (a fresh install takes about ${COLD_INSTALL_GB} GB, a lane needs room to build); free space first`

package/src/lane/start-lane-hint.ts

@@ -0,0 +1,18 @@
+import { homedir } from 'node:os'
+import { mainCheckoutOrNull, worktreeRoot } from '../plans/git'
+import { REFERENCE, referenceHint } from '../watch/reference-paths'
+import { installedSkillDirectory } from './skill-hint'
+
+/** `· read <skill directory>/references/start-lane.md`, the line after the output of `jh lane base` and `jh lane prompt`. */
+export const startLaneHintLine = (skillDirectory: string | null): string =>
+  referenceHint(REFERENCE.startLane, skillDirectory).trimStart()
+
+/**
+ * The hint line for a call from the main checkout, where a lane is started from; null from a lane's worktree or outside a
+ * checkout, which have no start to guide. The skill copy is the project's, else the global one.
+ */
+export const startLaneHintFor = (cwd: string): string | null => {
+  const root = mainCheckoutOrNull(cwd)
+  if (root === null || worktreeRoot(cwd) !== root) return null
+  return startLaneHintLine(installedSkillDirectory(root, homedir()))
+}

package/src/plan-contract/base-check-git.ts

@@ -0,0 +1,33 @@
+import { readFileSync } from 'node:fs'
+import { basename, resolve } from 'node:path'
+import { commitOf, existsOnRef, mainCheckout, worktreeRoot } from '../plans/git'
+import { baseRefOf, boardGlobOf, boardRepoPathOf, readSettings } from '../plans/settings'
+import { baseGapLines, repoPathOf } from './base-check'
+
+/** The boards of the main checkout that link the plan, by its file name, as paths from the repository root. */
+const boardPathsLinking = (root: string, plan: string): string[] => {
+  const settings = readSettings([root])
+  const name = basename(plan)
+  return [...new Bun.Glob(boardGlobOf(settings)).scanSync({ cwd: root })]
+    .map((file) => resolve(root, file))
+    .filter((file) => readFileSync(file, 'utf8').includes(name))
+    .map((file) => boardRepoPathOf(root, settings, file))
+}
+
+/**
+ * The lines that say the plan or a board that links it is not on the base branch (orchestrate § 0), each with its path
+ * from the repository root. None where git cannot judge: outside a repository, without the base ref, or for a file
+ * outside the repository.
+ */
+export const baseGapLinesFor = (file: string, cwd: string): string[] => {
+  try {
+    const root = mainCheckout(cwd)
+    const baseRef = baseRefOf(readSettings([root]))
+    if (commitOf(root, baseRef) === null) return []
+    const plan = repoPathOf(worktreeRoot(cwd), resolve(cwd, file))
+    if (plan === null) return []
+    return baseGapLines(baseRef, [plan, ...boardPathsLinking(root, plan)], (path) => existsOnRef(root, baseRef, path))
+  } catch {
+    return []
+  }
+}

package/src/plan-contract/base-check.ts

@@ -0,0 +1,17 @@
+import { isAbsolute, relative, resolve } from 'node:path'
+
+/** The path of `file` from the repository root, without `..`; null for the root itself or a file outside it. */
+export const repoPathOf = (root: string, file: string): string | null => {
+  const path = relative(resolve(root), resolve(file))
+  return path === '' || path.startsWith('..') || isAbsolute(path) ? null : path
+}
+
+/** One line per file of `paths` that `isOnBase` does not find on `baseRef`: git does not resolve `..` in a tree path. */
+export const baseGapLines = (
+  baseRef: string,
+  paths: readonly string[],
+  isOnBase: (path: string) => boolean,
+): string[] =>
+  paths
+    .filter((path) => !isOnBase(path))
+    .map((path) => `base: ${path} is not on ${baseRef}: ask for its documentation commit (orchestrate § 2 step 0).`)

package/src/plan-contract/command.ts

@@ -3,22 +3,29 @@ import { homedir } from 'node:os'
 import { resolve } from 'node:path'
 import { findProjectRoot } from '../config/location'
 import { readConfig } from '../config/read-config'
+import { installedReferenceHint } from '../lane/skill-hint'
 import { asksForHelp } from '../preview/options'
 import { CLI_NAME } from '../version/release'
 import type { PlanLanguage } from '../vocabulary'
+import { REFERENCE, type Reference, referenceLine } from '../watch/reference-paths'
+import { baseGapLinesFor } from './base-check-git'
 import { contractOf, type PartFinding, type PlanContract } from './contract'
 
 const CHECK_SUBCOMMAND = 'check'
 
-/** Exit codes of `jh plan check`: the contract is met, a part has a gap, the command line or the file is wrong. */
-export const PLAN_CHECK_EXIT = { met: 0, gaps: 1, error: 2 } as const
+/**
+ * Exit codes of `jh plan check`: the contract is met, a part has a gap, the command line or the file is wrong, the
+ * contract is met but the plan or a board that links it is not on the base branch.
+ */
+export const PLAN_CHECK_EXIT = { met: 0, gaps: 1, error: 2, notOnBase: 3 } as const
 
 export const USAGE = `usage: ${CLI_NAME} plan ${CHECK_SUBCOMMAND} <plan.md>
 
 Checks one plan against the plan contract: phases, tasks in every phase, a model for every phase, a dependency
 row for every phase (from two phases on). One line per part, \`file:line\` where a part is incomplete.
+Where git has the base branch, a plan, or a board that links it, that the base branch lacks gets a \`base:\` line with its path.
 The plan language comes from .jackherd/config.json.
-Exit 0 met, 1 with gaps, 2 for a wrong command line or an unreadable file.`
+Exit 0 met, 1 with gaps, 2 for a wrong command line or an unreadable file, 3 met but not on the base branch.`
 
 const where = (file: string, line: number | null): string => (line === null ? '' : ` ${file}:${line}`)
 
@@ -45,6 +52,12 @@ const readPlan = (file: string): string | null => {
   }
 }
 
+/** The line after the findings that names the reference to read for the gap, for exit 1 and exit 3; none without the skill. */
+const printReference = (reference: Reference, home: string): void => {
+  const root = findProjectRoot(process.cwd(), home, existsSync) ?? process.cwd()
+  for (const line of referenceLine(installedReferenceHint(root, reference, home))) console.log(line)
+}
+
 const fail = (message: string): number => {
   console.error(message)
   return PLAN_CHECK_EXIT.error
@@ -65,5 +78,13 @@ export const run = (args: string[], home: string = homedir()): number => {
   if ('error' in result) return fail(result.error)
   const contract = contractOf(markdown, result.language)
   for (const line of contractLines(file, contract)) console.log(line)
-  return contract.met ? PLAN_CHECK_EXIT.met : PLAN_CHECK_EXIT.gaps
+  if (!contract.met) {
+    printReference(REFERENCE.adoptPlan, home)
+    return PLAN_CHECK_EXIT.gaps
+  }
+  const gapLines = baseGapLinesFor(file, process.cwd())
+  for (const line of gapLines) console.log(line)
+  if (gapLines.length === 0) return PLAN_CHECK_EXIT.met
+  printReference(REFERENCE.planCommit, home)
+  return PLAN_CHECK_EXIT.notOnBase
 }

package/src/plan-format/plan-structure.ts

@@ -20,11 +20,11 @@ export type PhaseWithoutGate = PhaseHeading
 /** A row of the lanes table (1-based line) whose phases cell names no phase id. */
 export type RowWithoutPhase = OpenLaneRow
 
-/**
- * A `### Phase` heading (1-based line) whose tasks are all ticked on the base branch while its own section still
- * has open checkboxes not moved on with `→ P<n>` (`openLines`, 1-based).
- */
-export type MergedPhaseWithOpenBoxes = PhaseWithoutGate & { openLines: number[] }
+/** A `### Phase` heading (1-based line) whose own section has open checkboxes not moved on with `→ P<n>` (`openLines`, 1-based). */
+export type PhaseWithOpenBoxes = PhaseWithoutGate & { openLines: number[] }
+
+/** A `PhaseWithOpenBoxes` whose tasks are all ticked on the base branch. */
+export type MergedPhaseWithOpenBoxes = PhaseWithOpenBoxes
 
 type PhaseSection = PhaseWithoutGate & { tasks: boolean; gate: boolean; openLines: number[] }
 
@@ -118,6 +118,18 @@ export const mergedPhasesWithOpenBoxes = (
     .map(({ line, id, title, openLines }) => ({ line, id, title, openLines }))
 }
 
+/**
+ * The phase `id` of `markdown` when its own section still has open checkboxes, gate boxes included, that no `→ P<n>`
+ * at their end moves on; null when it has none or the plan lacks the phase. Unlike `mergedPhasesWithOpenBoxes` it
+ * does not ask whether the phase counts as merged: the caller knows which phase a branch builds.
+ */
+export const openBoxesOfPhase = (markdown: string, language: PlanLanguage, id: string): PhaseWithOpenBoxes | null => {
+  const section = phaseSections(markdown, language).find((candidate) => candidate.id === id)
+  return section && section.openLines.length > 0
+    ? { line: section.line, id: section.id, title: section.title, openLines: section.openLines }
+    : null
+}
+
 /**
  * The changed rows of open lanes whose phases cell names no phase id (`P10c`), so neither the view nor the watcher
  * can tie that step to a phase.

package/src/plans/ask-coordinator.ts

@@ -1,8 +1,10 @@
 import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
 import { resolveCoordinatorName } from '../context/coordinator-name'
+import { installedReferenceHintFor } from '../lane/skill-hint'
 import { laneSenderForAsync } from '../settled/send'
 import { type HerdrAsyncRunner, parseAgentList } from '../terminal/herdr'
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import { REFERENCE } from '../watch/reference-paths'
 import { ASK_KIND, type AskTarget, boardRowKey } from './ask-target'
 import { errorText } from './error-text'
 import { isQuestionId } from './question-records'
@@ -18,29 +20,32 @@ export type AskDependencies = {
   /** The repository's directory name, from which the coordinator's herdr name follows. */
   repository: string
   run: HerdrAsyncRunner
+  /** Where the repository is looked up for the skill's reference; the working directory when omitted. */
+  cwd?: string
 }
 
 /** A sentence takes the subject's key and, for an entry of a source, the source it belongs to (else `''`). */
-type AskSentences = Record<AskTarget['kind'], (subject: string, scope: string) => string>
+type AskSentences = Record<AskTarget['kind'], (subject: string, scope: string, hint: string) => string>
 
 const ASK_LINES: Record<PlanLanguage, AskSentences> = {
   [PLAN_LANGUAGE.de]: {
-    [ASK_KIND.question]: (id) => `Stell mir die offene Frage ${id} jetzt (jh waiting).`,
-    [ASK_KIND.boardRow]: (key) => `Stell mir die offene Board-Zeile \`${key}\` jetzt (jh waiting).`,
+    [ASK_KIND.question]: (id, _scope, hint) => `Stell mir die offene Frage ${id} jetzt (jh waiting).${hint}`,
+    [ASK_KIND.boardRow]: (key, _scope, hint) =>
+      `Stell mir die offene Board-Zeile \`${key}\` jetzt (jh waiting).${hint}`,
     [ASK_KIND.appointmentRun]: (key) => `Führe den Termin \`${key}\` jetzt aus, unter den Freigaben, die er braucht.`,
     [ASK_KIND.appointmentMove]: (key) =>
       `Frag den User per Dialog nach der neuen Zeit für den Termin \`${key}\` und trag sie ins Board ein (verschobene Zeile = neuer Termin).`,
-    [ASK_KIND.sourceEntry]: (title, source) =>
-      `Sieh dir die Meldung \`${title}\` der Quelle \`${source}\` an und stell mir, falls nötig, die Frage dazu (jh waiting).`,
+    [ASK_KIND.sourceEntry]: (title, source, hint) =>
+      `Sieh dir die Meldung \`${title}\` der Quelle \`${source}\` an und stell mir, falls nötig, die Frage dazu (jh waiting).${hint}`,
   },
   [PLAN_LANGUAGE.en]: {
-    [ASK_KIND.question]: (id) => `Ask me the open question ${id} now (jh waiting).`,
-    [ASK_KIND.boardRow]: (key) => `Ask me the open board row \`${key}\` now (jh waiting).`,
+    [ASK_KIND.question]: (id, _scope, hint) => `Ask me the open question ${id} now (jh waiting).${hint}`,
+    [ASK_KIND.boardRow]: (key, _scope, hint) => `Ask me the open board row \`${key}\` now (jh waiting).${hint}`,
     [ASK_KIND.appointmentRun]: (key) => `Run the appointment \`${key}\` now, under the approvals it needs.`,
     [ASK_KIND.appointmentMove]: (key) =>
       `Ask the user in a dialog for the new time of the appointment \`${key}\` and write it into the board (a moved row is a new appointment).`,
-    [ASK_KIND.sourceEntry]: (title, source) =>
-      `Look at the report \`${title}\` of the source \`${source}\` and, if it needs it, put the question about it to me (jh waiting).`,
+    [ASK_KIND.sourceEntry]: (title, source, hint) =>
+      `Look at the report \`${title}\` of the source \`${source}\` and, if it needs it, put the question about it to me (jh waiting).${hint}`,
   },
 }
 
@@ -60,10 +65,11 @@ const scopeOf = (target: AskTarget): string =>
 /**
  * The line sent to the coordinator: a fixed sentence that carries the id of a question, or the sanitised key of a
  * row (`boardRowKey`), and nothing else from the board or the question, so a prompt line cannot be steered by
- * the file it reads. The caller checks the id with `isQuestionId`.
+ * the file it reads. The caller checks the id with `isQuestionId`. The sentences that send the coordinator to `jh waiting` end
+ * with `hint`, the reference that says how to put the question (none without the orchestrate skill).
  */
-export const askLine = (target: AskTarget, language: PlanLanguage): string =>
-  ASK_LINES[language][target.kind](subjectKeyOf(target), scopeOf(target))
+export const askLine = (target: AskTarget, language: PlanLanguage, hint = ''): string =>
+  ASK_LINES[language][target.kind](subjectKeyOf(target), scopeOf(target), hint)
 
 const isAskable = (target: AskTarget): boolean =>
   target.kind === ASK_KIND.question
@@ -114,7 +120,11 @@ export const askCoordinator = async (target: AskTarget, dependencies: AskDepende
   if ('reason' in coordinator) return TEXTS.notAsked(coordinator.reason)
   const failure = await laneSenderForAsync(dependencies.adapter, dependencies.run)(
     coordinator.name,
-    askLine(target, dependencies.language),
+    askLine(
+      target,
+      dependencies.language,
+      installedReferenceHintFor(dependencies.cwd ?? process.cwd(), REFERENCE.herdAsk),
+    ),
   )
   return failure === null ? TEXTS.asked(coordinator.name, subjectOf(target)) : TEXTS.notAsked(failure)
 }

package/src/plans/board-rows.ts

@@ -26,18 +26,23 @@ const newPartOf = (lane: SprintLane, step: PlanStep): PlanStep | null => {
   return rest.phaseIds.length > 0 ? rest : null
 }
 
-/** The lane with the checkout's steps it does not have yet; the same object when nothing is new. */
+/** Whether the lane is closed: the base says so, or the checkout marks it cleaned up before the mark is merged. */
+const closedBy = (known: SprintLane, checkout: SprintLane | undefined): boolean =>
+  known.closed || checkout?.closed === true
+
+/** The lane with the checkout's steps it does not have yet and its closed mark; the same object when nothing is new. */
 const grownBy = (known: SprintLane, checkout: SprintLane | undefined): SprintLane => {
-  const grown: SprintLane = { ...known, steps: [...known.steps] }
+  const grown: SprintLane = { ...known, steps: [...known.steps], closed: closedBy(known, checkout) }
   for (const step of checkout?.steps ?? []) {
     const part = newPartOf(grown, step)
     if (part !== null) grown.steps.push(part)
   }
-  return grown.steps.length > known.steps.length ? grown : known
+  return grown.steps.length > known.steps.length || grown.closed !== known.closed ? grown : known
 }
 
 /**
- * The board at the base ref with the rows only the checkout has. Base lanes keep their order and their rows;
+ * The board at the base ref with the rows only the checkout has. Base lanes keep their order and their rows, and are
+ * closed when the checkout marks them cleaned up, so the herd drops a lane before the mark reaches the base;
  * a lane only the checkout names is appended; a step of a known lane is added when the base does not name its
  * phases for that plan yet (identity: plan link and phase id), a row without a plan link when its label is new.
  * Both sides come parsed, this function reads no text.

package/src/plans/click-hint.ts

@@ -3,8 +3,10 @@ import { pullRequestNumberOfKey } from './pull-requests'
 import { LINKS_KEY_PREFIX } from './row-focus'
 import {
   BACKLOG_KEY,
+  entryBlockOfKey,
   finishedKey,
   isBlockFolded,
+  isEntryBlockFolded,
   isLaneOpen,
   isLanesOpen,
   isTaskRestKey,
@@ -55,6 +57,8 @@ const foldingHint = (key: string, state: Selection, agentOf: AgentOf): string |
   const lane = laneOfKey(key)
   if (lane !== null) return foldHint(isLaneOpen(state, lane, agentOf(lane)), lane)
   if (key === LANES_KEY) return foldHint(isLanesOpen(state), TEXTS.lanesHeading)
+  const entrySource = entryBlockOfKey(key)
+  if (entrySource !== null) return foldHint(!isEntryBlockFolded(state, entrySource), entrySource)
   const top = topBlockOfKey(key)
   if (top !== null) return foldHint(!isBlockFolded(state, top), TOP_BLOCK_NAMES[top])
   const open = state.expanded.has(key)

package/src/plans/command.ts

@@ -4,7 +4,7 @@ import { laneStatusSourceFor } from '../terminal'
 import { listHerdrAgents } from '../terminal/herdr'
 import { startedKit } from '../version/started-kit'
 import { boardFor, foundLanesOf } from './board-pick'
-import { ensurePlanPanes } from './ensure-panes'
+import { ensurePlanPaneRun } from './ensure-panes'
 import { mainCheckout, worktreeRoot } from './git'
 import { fetchPullRequests } from './github'
 import { claimOwnTerminal, startExclusive } from './herd-claim'
@@ -12,6 +12,7 @@ import { recallLanes, rememberLanes } from './herd-memory'
 import { publishedKey } from './herd-state'
 import { runLive } from './live'
 import { parseOptions } from './options'
+import { ENSURE_EXIT } from './plan-panes'
 import { isSupervisedChild } from './restart-decision'
 import { type PlansSettings, readSettings } from './settings'
 import { loadSnapshot, type Source } from './snapshot'
@@ -55,12 +56,12 @@ export const run = async (args: string[], home: string = homedir()): Promise<num
       foundLanesOf(root, settings, () => terminal.listAgents().map((agent) => agent.name)),
     )
     if (options.ensure) {
-      const lines =
+      const { lines, exitCode } =
         settings.adapter === TERMINAL_ADAPTER.herdr
-          ? ensurePlanPanes(root, settings, picked.file)
-          : ['the terminal adapter is not herdr: no panes to bring back']
+          ? ensurePlanPaneRun(root, settings, picked.file)
+          : { lines: ['the terminal adapter is not herdr: no panes to bring back'], exitCode: ENSURE_EXIT.done }
       for (const line of lines.length > 0 ? lines : ['every herd pane is running']) console.log(line)
-      return 0
+      return exitCode
     }
     const source: Source = { root, sprintFile: picked.file, options, settings, terminal, ...agentListOf(settings) }
     if (options.once || !process.stdout.isTTY) await printOnceWithNotice(source, picked.notice)

package/src/plans/ensure-panes.ts

@@ -8,6 +8,8 @@ import {
   agentPanesOf,
   coordinatorLabelOf,
   coordinatorPaneOf,
+  type EnsureExit,
+  ensureExitOf,
   foregroundOf,
   missingCoordinatorNote,
   type PaneAction,
@@ -60,9 +62,14 @@ const labelCoordinator = (label: { pane: string; label: string } | null) => {
 /**
  * `herd --ensure`: brings back every missing herd pane beside the coordinator and each lane of the board, and
  * leaves running ones alone, so it can run after every start. A lane gets its view once its agent runs. One line per
- * action or skipped target, none when every view runs. The coordinator's pane is labelled `🐾 Jack` on the way.
+ * action or skipped target, none when every view runs, and the exit code (`ENSURE_EXIT`) that says whether the
+ * coordinator's pane was found. The coordinator's pane is labelled `🐾 Jack` on the way.
  */
-export const ensurePlanPanes = (root: string, settings: PlansSettings, boardFile: string): string[] => {
+export const ensurePlanPaneRun = (
+  root: string,
+  settings: PlansSettings,
+  boardFile: string,
+): { lines: string[]; exitCode: EnsureExit } => {
   const agents = runHerdr(['agent', 'list'])
   const listed = parseAgentList(agents)
   const panes = panesWithForeground(agentPanesOf(agents))
@@ -84,5 +91,9 @@ export const ensurePlanPanes = (root: string, settings: PlansSettings, boardFile
     command: (lane) => viewCommandOf(process.argv, lane),
     missingCoordinator: missingCoordinatorNote(panes, root, coordinatorName),
   })
-  return [...actions.map(apply), ...notes]
+  return { lines: [...actions.map(apply), ...notes], exitCode: ensureExitOf(panes, coordinator) }
 }
+
+/** The lines of `ensurePlanPaneRun`, for a caller that brings the panes back without an exit code (the watcher). */
+export const ensurePlanPanes = (root: string, settings: PlansSettings, boardFile: string): string[] =>
+  ensurePlanPaneRun(root, settings, boardFile).lines

package/src/plans/git.ts

@@ -39,6 +39,11 @@ export const showAtRef = (root: string, ref: string, path: string): string | nul
   return result.exitCode === 0 ? result.stdout.toString() : null
 }
 
+/** Whether `path` (from the repository root, without `..`) exists at `ref`. */
+export const existsOnRef = (root: string, ref: string, path: string): boolean =>
+  Bun.spawnSync(['git', '-C', root, 'cat-file', '-e', `${ref}:${path}`], { stdout: 'ignore', stderr: 'ignore' })
+    .exitCode === 0
+
 /** The commit `ref` points at, null when it does not exist. */
 export const commitOf = (root: string, ref: string): string | null =>
   git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])
@@ -151,6 +156,15 @@ export const mainCheckout = (cwd: string): string => {
   return dirname(commonDirectory)
 }
 
+/** `mainCheckout`, null outside a git checkout instead of git's error. */
+export const mainCheckoutOrNull = (cwd: string): string | null => {
+  try {
+    return mainCheckout(cwd)
+  } catch {
+    return null
+  }
+}
+
 /** The top of the checkout `cwd` is in: the worktree itself, not the main checkout. */
 export const worktreeRoot = (cwd: string): string => {
   const top = git(cwd, ['rev-parse', '--show-toplevel'])