jackherd 1.9.0 → 1.10.0

package/src/lane/close-command.ts

@@ -0,0 +1,217 @@
+import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
+import { TERMINAL_ADAPTER } from '../config'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { boardFor } from '../plans/board-pick'
+import { commitOf, mainCheckout, worktreeRoot } from '../plans/git'
+import { type PlansSettings, readSettings, worktreeOf } from '../plans/settings'
+import { asksForHelp } from '../preview/options'
+import { laneStatusSourceFor } from '../terminal'
+import { runHerdr } from '../terminal/herdr'
+import { runGh } from '../watch/gh'
+import { parseWatchedPullRequests, WATCHED_PULL_REQUEST_FIELDS } from '../watch/pull-requests'
+import { type ClosePorts, type CloseRequest, type CloseSurvey, closeLane } from './close'
+import { boardLaneOf } from './close-board'
+import { type CloseFacts, type MergedPullRequest, statusEntriesOf } from './close-check'
+import { type CloseOptions, LANE_CLOSE_USAGE, parseCloseOptions } from './close-options'
+import { agentFactsOf, mergedPullRequestOf, openWorkspaceOf, type WorktreeEntry, worktreeEntryOf } from './close-survey'
+
+/** Where the command runs and what it acts on, located once. */
+type CloseContext = { root: string; cwd: string; settings: PlansSettings; worktree: string; boardFile: string }
+
+/** The facts that only a worktree git lists has. */
+type WorktreeFacts = Pick<
+  CloseFacts,
+  'worktreeExists' | 'branch' | 'head' | 'pullRequest' | 'treeDiff' | 'status' | 'handoverEntries' | 'locked'
+>
+
+/** The file the lane setup copies into every new worktree, in `.gitignore` syntax. */
+const SETUP_FILES = '.worktreeinclude'
+const GH_TIMEOUT_MS = 30_000
+const PULL_REQUEST_LIMIT = 20
+const EXIT_WAIT_MS = 60_000
+const EXIT_POLL_MS = 1_000
+const EXIT_COMMAND = '/exit'
+const BRANCH_REF = 'refs/heads/'
+/**
+ * Ignored paths as an ignore pattern names them: a directory whose files are all ignored by a file pattern
+ * (`packages/*\/bin/*.js`) shows as those files, not folded into a directory no pattern names, so the build output
+ * list can judge each one.
+ */
+const IGNORED_MATCHING = '--ignored=matching'
+/** Untracked files are listed whatever `status.showUntrackedFiles` says, so a project setting cannot hide one. */
+const ALL_UNTRACKED = '--untracked-files=all'
+
+const ABSENT_WORKTREE: WorktreeFacts = {
+  worktreeExists: false,
+  branch: null,
+  head: null,
+  pullRequest: null,
+  treeDiff: [],
+  status: [],
+  handoverEntries: [],
+  locked: null,
+}
+
+/** Runs git and returns its stdout; throws with git's own error text. */
+const runGit = (cwd: string, args: string[]): string => {
+  const result = Bun.spawnSync(['git', '-C', cwd, ...args], { stdout: 'pipe', stderr: 'pipe' })
+  if (result.exitCode !== 0)
+    throw new Error(`git ${args[0]}: ${result.stderr.toString().trim() || `exit ${result.exitCode}`}`)
+  return result.stdout.toString()
+}
+
+const realPath = (path: string): string => (existsSync(path) ? realpathSync(path) : path)
+
+const linesOf = (text: string): string[] => text.split('\n').filter((line) => line.trim() !== '')
+
+const setupFilesOf = (root: string): string[] => {
+  const file = join(root, SETUP_FILES)
+  return existsSync(file) ? readFileSync(file, 'utf8').split('\n') : []
+}
+
+/** The paths in which the branch head differs from the merge commit; fetches the base once when the commit is missing. */
+const treeDiffOf = (context: CloseContext, head: string, mergeCommit: string): string[] => {
+  if (commitOf(context.root, mergeCommit) === null)
+    runGit(context.root, ['fetch', '--quiet', 'origin', context.settings.baseBranch])
+  return linesOf(runGit(context.root, ['diff', '--name-only', '--end-of-options', head, mergeCommit]))
+}
+
+/** Every entry of the worktree's handover directory, a folder with its trailing slash, as git names paths. */
+const handoverEntriesOf = (worktree: string): string[] => {
+  const directory = claudePath(HANDOVER_DIRECTORY)
+  const absolute = join(worktree, directory)
+  if (!existsSync(absolute)) return []
+  return readdirSync(absolute, { withFileTypes: true })
+    .map((entry) => `${directory}/${entry.name}${entry.isDirectory() ? '/' : ''}`)
+    .sort()
+}
+
+const mergedPullRequestOn = async (context: CloseContext, branch: string): Promise<MergedPullRequest | null> => {
+  const fields = ['--json', WATCHED_PULL_REQUEST_FIELDS, '--limit', String(PULL_REQUEST_LIMIT)]
+  const answer = await runGh(['pr', 'list', '--head', branch, '--state', 'merged', ...fields], context.root, {
+    timeoutMs: GH_TIMEOUT_MS,
+  })
+  if (!answer.ok) throw new Error(answer.error)
+  return mergedPullRequestOf(parseWatchedPullRequests(answer.stdout), branch)
+}
+
+/** Branch, merged pull request, tree difference, status, handover files and lock of the worktree git lists for the lane. */
+const worktreeFactsOf = async (context: CloseContext, entry: WorktreeEntry): Promise<WorktreeFacts> => {
+  const pullRequest = entry.branch === null ? null : await mergedPullRequestOn(context, entry.branch)
+  return {
+    worktreeExists: true,
+    branch: entry.branch,
+    head: entry.head,
+    pullRequest,
+    treeDiff: pullRequest === null ? [] : treeDiffOf(context, entry.head, pullRequest.mergeCommit),
+    status: statusEntriesOf(
+      runGit(context.worktree, ['status', '--porcelain=v1', '-z', IGNORED_MATCHING, ALL_UNTRACKED]),
+    ),
+    handoverEntries: handoverEntriesOf(context.worktree),
+    locked: entry.locked,
+  }
+}
+
+const workspaceOf = (context: CloseContext): string | null =>
+  context.settings.adapter === TERMINAL_ADAPTER.herdr
+    ? openWorkspaceOf(runHerdr(['worktree', 'list', '--cwd', context.root]), context.worktree)
+    : null
+
+/** What git, GitHub and the terminal say about the lane now; throws when one of them cannot be asked. */
+const surveyOf = async (lane: string, context: CloseContext): Promise<CloseSurvey> => {
+  const entry = worktreeEntryOf(runGit(context.root, ['worktree', 'list', '--porcelain']), context.worktree)
+  const present = entry !== null && existsSync(context.worktree)
+  const facts: CloseFacts = {
+    lane,
+    boardLane: boardLaneOf(readFileSync(context.boardFile, 'utf8'), lane, context.settings.planLanguage),
+    setupFiles: setupFilesOf(context.root),
+    ...agentFactsOf(laneStatusSourceFor(context.settings.adapter).listAgents(), lane, context.worktree),
+    runsInside: realPath(worktreeRoot(context.cwd)) === realPath(context.worktree),
+    ...(present ? await worktreeFactsOf(context, entry) : ABSENT_WORKTREE),
+  }
+  return { facts, workspace: present ? workspaceOf(context) : null }
+}
+
+const sleep = (ms: number): Promise<void> => new Promise((done) => setTimeout(done, ms))
+
+/** Sends `/exit` to the agent in `pane` and waits until the terminal lists no session in that pane. */
+const exitAgentIn =
+  (context: CloseContext) =>
+  async (pane: string): Promise<void> => {
+    if (context.settings.adapter !== TERMINAL_ADAPTER.herdr) throw new Error('only herdr can end an agent')
+    runHerdr(['agent', 'prompt', pane, EXIT_COMMAND])
+    const source = laneStatusSourceFor(context.settings.adapter)
+    for (let waited = 0; waited < EXIT_WAIT_MS; waited += EXIT_POLL_MS) {
+      await sleep(EXIT_POLL_MS)
+      const agent = source.listAgents().find((listed) => listed.pane === pane)
+      if (agent === undefined || agent.session === null) return
+    }
+    throw new Error(`the agent in pane ${pane} still runs after ${EXIT_WAIT_MS / 1000} s`)
+  }
+
+/** Git removes the worktree and refuses on any change itself; herdr then only closes the emptied workspace. */
+const removeWorktreeIn =
+  (context: CloseContext) =>
+  (worktree: string, workspace: string | null): void => {
+    runGit(context.root, ['worktree', 'remove', worktree])
+    if (workspace !== null) runHerdr(['workspace', 'close', workspace])
+  }
+
+/** Deletes the branch only while it points to `head`; git refuses when it moved since the check. */
+const deleteBranchIn =
+  (context: CloseContext) =>
+  (branch: string, head: string): void => {
+    runGit(context.root, ['update-ref', '-d', `${BRANCH_REF}${branch}`, head])
+  }
+
+const portsFor = (lane: string, context: CloseContext): ClosePorts => ({
+  survey: () => surveyOf(lane, context),
+  exitAgent: exitAgentIn(context),
+  removeWorktree: removeWorktreeIn(context),
+  deleteBranch: deleteBranchIn(context),
+  readBoard: () => readFileSync(context.boardFile, 'utf8'),
+  writeBoard: (text) => writeFileSync(context.boardFile, text),
+  print: (line) => console.log(terminalSafe(line)),
+  printError: (line) => console.error(terminalSafe(line)),
+})
+
+/** The main checkout, its settings, the lane's worktree from those settings, and the board, with the pick's notice. */
+const contextOf = (options: CloseOptions, cwd: string): { context: CloseContext; notice: string | null } => {
+  const root = mainCheckout(cwd)
+  const settings = readSettings([root, worktreeRoot(cwd)])
+  const boardPath = options.boardPath === null ? null : resolve(cwd, options.boardPath)
+  const board = boardFor(boardPath, [root], settings, () => [options.lane])
+  const worktree = worktreeOf(root, settings, options.lane)
+  return { context: { root, cwd, settings, worktree, boardFile: board.file }, notice: board.notice }
+}
+
+/**
+ * `jh lane close <lane> [--dry-run] [--board <board.md>]`: closes a lane in one run once nothing would be lost, see
+ * `closeLane`. The worktree's path comes from the settings and the lane's name, never from a reply. Exit 0 closed or
+ * dry run, 1 refused or failed.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(LANE_CLOSE_USAGE)
+    return 0
+  }
+  try {
+    const options = parseCloseOptions(args)
+    const { context, notice } = contextOf(options, cwd)
+    if (notice) console.error(terminalSafe(notice))
+    const request: CloseRequest = {
+      lane: options.lane,
+      worktree: context.worktree,
+      boardPath: relative(context.root, context.boardFile),
+      dryRun: options.dryRun,
+      now: new Date(),
+      language: context.settings.planLanguage,
+    }
+    return await closeLane(request, portsFor(options.lane, context))
+  } catch (error) {
+    console.error(terminalSafe(error instanceof Error ? error.message : String(error)))
+    return 1
+  }
+}

package/src/lane/close-options.ts

@@ -0,0 +1,43 @@
+import { CLI_NAME } from '../version/release'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+import { DRY_RUN_OPTION, LANE_CLOSE_COMMAND } from './close-command-line'
+
+/** What `jh lane close` was asked for; `boardPath` is null where `--board` was left out. */
+export type CloseOptions = { lane: string; dryRun: boolean; boardPath: string | null }
+
+const BOARD = '--board'
+
+export const LANE_CLOSE_USAGE = `usage: ${LANE_CLOSE_COMMAND} <lane> [${DRY_RUN_OPTION}] [--board <board.md>]
+
+Closes a lane whose pull request is merged, once nothing in it would be lost: exits its agent, removes its workspace,
+worktree and local branch, and marks its rows in the board with a history row. Refuses with every reason otherwise.
+  --dry-run            check and print the steps, change nothing
+  --board <board.md>   the board to mark; without it the board is picked as for ${CLI_NAME} herd`
+
+const usageError = (message: string): Error => new Error(`${message}\n${LANE_CLOSE_USAGE}`)
+
+const laneOf = (words: readonly string[]): string => {
+  if (words.length === 0) throw usageError('the lane is required')
+  if (words.length > 1) throw usageError(`one lane at most, got ${words.join(' ')}`)
+  if (!SAFE_LANE_NAME.test(words[0])) throw usageError(`${words[0]} is no lane name (letters, digits, . _ -)`)
+  return words[0]
+}
+
+/** Reads `<lane> [--dry-run] [--board <file>]` in any order, the arguments after `close`; throws on a wrong line. */
+export const parseCloseOptions = (args: readonly string[]): CloseOptions => {
+  const words: string[] = []
+  let dryRun = false
+  let boardPath: string | null = null
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i]
+    if (arg === DRY_RUN_OPTION) dryRun = true
+    else if (arg === BOARD) {
+      const value = args[i + 1]
+      if (value === undefined || value.startsWith('--')) throw usageError(`${BOARD} needs a value`)
+      boardPath = value
+      i += 1
+    } else if (arg.startsWith('--')) throw usageError(`unknown option ${arg}`)
+    else words.push(arg)
+  }
+  return { lane: laneOf(words), dryRun, boardPath }
+}

package/src/lane/close-survey.ts

@@ -0,0 +1,83 @@
+import { sep } from 'node:path'
+import { isRecord } from '../shared/is-record'
+import type { LaneAgent } from '../terminal'
+import { PULL_REQUEST_STATE, type WatchedPullRequest } from '../watch/pull-requests'
+import type { CloseFacts, MergedPullRequest } from './close-check'
+
+/** A worktree as `git worktree list --porcelain` lists it; `branch` null when detached, `locked` as in `CloseFacts`. */
+export type WorktreeEntry = { head: string; branch: string | null; locked: string | null }
+
+const BRANCH_REF = 'refs/heads/'
+const OBJECT_ID = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/
+
+const fieldOf = (lines: readonly string[], key: string): string | null => {
+  const line = lines.find((entry) => entry === key || entry.startsWith(`${key} `))
+  return line === undefined ? null : line.slice(key.length + 1)
+}
+
+/** The entry of the worktree at `path` in `git worktree list --porcelain`; null when git lists none there. */
+export const worktreeEntryOf = (porcelain: string, path: string): WorktreeEntry | null => {
+  const entry = porcelain
+    .split('\n\n')
+    .map((block) => block.split('\n').filter(Boolean))
+    .find((lines) => fieldOf(lines, 'worktree') === path)
+  if (entry === undefined) return null
+  const branch = fieldOf(entry, 'branch')
+  return {
+    head: fieldOf(entry, 'HEAD') ?? '',
+    branch: branch?.startsWith(BRANCH_REF) ? branch.slice(BRANCH_REF.length) : null,
+    locked: fieldOf(entry, 'locked'),
+  }
+}
+
+type HerdrWorktree = { path: string; open_workspace_id?: string }
+
+const isHerdrWorktree = (value: unknown): value is HerdrWorktree =>
+  isRecord(value) &&
+  typeof value.path === 'string' &&
+  (value.open_workspace_id === undefined || typeof value.open_workspace_id === 'string')
+
+/** The herdr workspace the worktree at `path` is open in, from `herdr worktree list`; null when it is in none. */
+export const openWorkspaceOf = (json: string, path: string): string | null => {
+  const result = (JSON.parse(json) as { result?: { worktrees?: unknown } }).result
+  const worktrees = result?.worktrees
+  if (!Array.isArray(worktrees) || !worktrees.every(isHerdrWorktree))
+    throw new Error('herdr worktree list: unexpected answer')
+  return worktrees.find((worktree) => worktree.path === path)?.open_workspace_id ?? null
+}
+
+/** A full git object id, SHA-1 or SHA-256; anything else from GitHub never reaches a git command line. */
+export const isObjectId = (value: string): boolean => OBJECT_ID.test(value)
+
+/** The newest merged pull request on `branch`, by number; null when none was merged with a well-formed merge commit. */
+export const mergedPullRequestOf = (
+  pullRequests: readonly WatchedPullRequest[],
+  branch: string,
+): MergedPullRequest | null => {
+  const merged = pullRequests
+    .filter((pullRequest) => pullRequest.branch === branch && pullRequest.state === PULL_REQUEST_STATE.merged)
+    .flatMap(({ number, headCommit, mergeCommit }) =>
+      mergeCommit === null || !isObjectId(mergeCommit) ? [] : [{ number, headCommit, mergeCommit }],
+    )
+  return merged.sort((left, right) => right.number - left.number)[0] ?? null
+}
+
+const isInside = (cwd: string | null, worktree: string): boolean =>
+  cwd !== null && (cwd === worktree || cwd.startsWith(`${worktree}${sep}`))
+
+/**
+ * The lane's agent, by its name and a directory in the worktree, so an agent of that name elsewhere is never ended;
+ * and the panes of every other agent in the worktree.
+ */
+export const agentFactsOf = (
+  agents: readonly LaneAgent[],
+  lane: string,
+  worktree: string,
+): Pick<CloseFacts, 'agent' | 'otherAgents'> => {
+  const inWorktree = agents.filter(({ cwd }) => isInside(cwd, worktree))
+  const own = inWorktree.find(({ name }) => name === lane)
+  return {
+    agent: own === undefined ? null : { pane: own.pane, status: own.status },
+    otherAgents: inWorktree.filter((agent) => agent !== own).map(({ pane }) => pane),
+  }
+}

package/src/lane/close.ts

@@ -0,0 +1,141 @@
+import { twoDigits } from '../plan-format/clock'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { errorText } from '../plans/error-text'
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+import { closedMark, historyDate, withHistoryRow, withLaneClosed } from './close-board'
+import { BOARD_LANE, type ClosableLane, type CloseFacts, closeVerdict } from './close-check'
+import { LANE_CLOSE_COMMAND } from './close-command-line'
+
+/** The facts the check reads, and the herdr workspace the worktree is open in, null when none is. */
+export type CloseSurvey = { facts: CloseFacts; workspace: string | null }
+
+/** What `jh lane close` was asked for; `worktree` comes from the settings and the lane's name, never from a reply. */
+export type CloseRequest = {
+  lane: string
+  worktree: string
+  /** The board as the output names it, relative to the main checkout. */
+  boardPath: string
+  dryRun: boolean
+  now: Date
+  language: PlanLanguage
+}
+
+/** The I/O `closeLane` drives; every port but `survey` and the printers throws when it fails. */
+export type ClosePorts = {
+  survey: () => Promise<CloseSurvey>
+  /** Ends the agent in this pane and returns once the terminal no longer lists its session. */
+  exitAgent: (pane: string) => Promise<void>
+  /** Removes the worktree without force, then closes the terminal workspace `workspace` names, if any. */
+  removeWorktree: (worktree: string, workspace: string | null) => void
+  /** Deletes the branch only while it still points to `head`, the commit the check compared. */
+  deleteBranch: (branch: string, head: string) => void
+  readBoard: () => string
+  writeBoard: (text: string) => void
+  print: (line: string) => void
+  printError: (line: string) => void
+}
+
+type ClosedLane = { lane: string } & ClosableLane
+
+type Step = { label: string; run: () => Promise<void> | void }
+
+/** A merge commit as the history row cites it. */
+const SHORT_COMMIT_LENGTH = 7
+
+const HISTORY_TEXT: Record<PlanLanguage, (closed: ClosedLane, mergeCommit: string) => string> = {
+  [PLAN_LANGUAGE.de]: ({ lane, branch, pullRequest }, mergeCommit) =>
+    `Spur \`${lane}\` abgeräumt mit \`${LANE_CLOSE_COMMAND}\`: PR #${pullRequest.number} gemergt (\`${mergeCommit}\`), Baum gleich Merge, Worktree entfernt, lokaler Branch \`${branch}\` gelöscht`,
+  [PLAN_LANGUAGE.en]: ({ lane, branch, pullRequest }, mergeCommit) =>
+    `Lane \`${lane}\` cleaned up with \`${LANE_CLOSE_COMMAND}\`: PR #${pullRequest.number} merged (\`${mergeCommit}\`), tree equal to the merge, worktree removed, local branch \`${branch}\` deleted`,
+}
+
+const clockOf = (time: Date): string => `${twoDigits(time.getHours())}:${twoDigits(time.getMinutes())}`
+
+/** The history row's text: the time, then what was closed and proven, in the board's language. */
+export const historyText = (closed: ClosedLane, request: Pick<CloseRequest, 'now' | 'language'>): string =>
+  `${clockOf(request.now)}: ${HISTORY_TEXT[request.language](closed, closed.pullRequest.mergeCommit.slice(0, SHORT_COMMIT_LENGTH))}`
+
+/** The board with the lane's rows marked and the history row on top. */
+const closedBoard = (board: string, closed: ClosedLane, request: CloseRequest): string =>
+  withHistoryRow(
+    withLaneClosed(board, closed.lane, closedMark(request.now, request.language), request.language),
+    historyDate(request.now),
+    historyText(closed, request),
+    request.language,
+  )
+
+const boardLabel = (facts: CloseFacts, request: CloseRequest): string =>
+  facts.boardLane === BOARD_LANE.closed
+    ? `add a history row in ${request.boardPath}, whose rows mark ${request.lane} already`
+    : `mark the rows of ${request.lane} "${closedMark(request.now, request.language)}" and add a history row in ${request.boardPath}`
+
+/** The removal steps after the agent is gone, in the order that never leaves the board claiming more than was done. */
+const removalSteps = (closed: ClosedLane, survey: CloseSurvey, request: CloseRequest, ports: ClosePorts): Step[] => {
+  const { workspace, facts } = survey
+  const place = workspace === null ? '' : ` and close workspace ${workspace}`
+  return [
+    {
+      label: `remove worktree ${request.worktree}${place}`,
+      run: () => ports.removeWorktree(request.worktree, workspace),
+    },
+    { label: `delete branch ${closed.branch}`, run: () => ports.deleteBranch(closed.branch, closed.head) },
+    { label: boardLabel(facts, request), run: () => ports.writeBoard(closedBoard(ports.readBoard(), closed, request)) },
+  ]
+}
+
+const exitSteps = ({ facts }: CloseSurvey, request: CloseRequest, ports: ClosePorts): Step[] => {
+  const { agent } = facts
+  if (agent === null) return []
+  return [
+    { label: `exit the agent of ${request.lane} and wait until it is gone`, run: () => ports.exitAgent(agent.pane) },
+  ]
+}
+
+/** The lane closable from `survey`, or null after printing every reason against it under `heading`. */
+const checked = (survey: CloseSurvey, heading: string, request: CloseRequest, ports: ClosePorts): ClosedLane | null => {
+  const verdict = closeVerdict(survey.facts)
+  if (verdict.kind === 'closable') return { lane: request.lane, ...verdict }
+  ports.printError(heading)
+  for (const refusal of verdict.refusals) ports.printError(`  ${terminalSafe(refusal)}`)
+  return null
+}
+
+/** Runs the steps in order, one line each; at the first failure, names it and every step left undone. */
+const runSteps = async (steps: readonly Step[], ports: ClosePorts): Promise<boolean> => {
+  for (const [index, step] of steps.entries()) {
+    try {
+      await step.run()
+      ports.print(`done: ${step.label}`)
+    } catch (error) {
+      ports.printError(`failed: ${step.label}: ${terminalSafe(errorText(error))}`)
+      for (const left of steps.slice(index + 1)) ports.printError(`not done: ${left.label}`)
+      return false
+    }
+  }
+  return true
+}
+
+/**
+ * Closes a lane in one run, or refuses with every reason and changes nothing. Checks first (`closeVerdict`); a dry run
+ * stops there and prints the steps. Otherwise it ends the lane's agent, checks again, since the agent may have written
+ * until it exited, then removes the worktree and its workspace, deletes the local branch, and marks the board last, so
+ * the board never records a removal that failed. Exit 0 closed or dry run, 1 refused or failed.
+ */
+export const closeLane = async (request: CloseRequest, ports: ClosePorts): Promise<number> => {
+  const first = await ports.survey()
+  const closed = checked(first, `not closing ${request.lane}:`, request, ports)
+  if (closed === null) return 1
+  const exit = exitSteps(first, request, ports)
+  if (request.dryRun) {
+    ports.print(`dry run, nothing changed; closing ${request.lane} would:`)
+    for (const step of [...exit, ...removalSteps(closed, first, request, ports)]) ports.print(`  ${step.label}`)
+    return 0
+  }
+  if (!(await runSteps(exit, ports))) return 1
+  const settled = exit.length === 0 ? first : await ports.survey()
+  const late = checked(settled, `not closing ${request.lane} after its agent exited:`, request, ports)
+  if (late === null) return 1
+  if (!(await runSteps(removalSteps(late, settled, request, ports), ports))) return 1
+  ports.print(`closed ${request.lane}`)
+  return 0
+}

package/src/lane/command.ts

@@ -0,0 +1,13 @@
+import { run as runPrompt } from '../lane-prompt/command'
+
+const CLOSE = 'close'
+
+/**
+ * `jh lane close …` closes a lane, everything else is `jh lane prompt …`. `close` must come first, so the ask rule
+ * `jh lane close` always sees it; `jh lane --board b.md close x` reaches the prompt parser and is refused there.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (args[0] !== CLOSE) return runPrompt(args, cwd)
+  const { run: runClose } = await import('./close-command')
+  return runClose(args.slice(1), cwd)
+}

package/src/lane-prompt/build.ts

@@ -0,0 +1,74 @@
+import { phaseLabel } from '../plan-format/lanes'
+import { LANE_PROMPT_OPENING, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { laneReportFile } from '../watch/lane-report-file'
+import { LANE_PROMPT_TEXTS, type LanePromptTexts } from './texts'
+
+/** A phase of the lane with the paths its row of the dependency table writes (`''` is the whole repository); null without a row. */
+export type LanePhase = { id: string; writes: string[] | null }
+
+/** A plan the lane works on, by its path from the repository root, with the lane's phases in it. */
+export type LanePlan = { path: string; phases: LanePhase[] }
+
+/**
+ * Everything a lane prompt is made of. `port` is null when the board gives the lane none; `handover` names the
+ * hand-over file a restarted lane reads first (`/orchestrate` § 8), null for a fresh start.
+ */
+export type LanePromptInput = {
+  language: PlanLanguage
+  lane: string
+  plans: LanePlan[]
+  port: number | null
+  handover: string | null
+}
+
+const writesText = (language: PlanLanguage, texts: LanePromptTexts, writes: string[] | null): string => {
+  if (writes === null) return texts.noWrites
+  const paths = writes.map((path) => (path === '' ? texts.wholeRepository : `\`${path}\``)).join(', ')
+  return `${PLAN_VOCABULARY[language].columns.writes}: ${paths}`
+}
+
+const phaseText = (language: PlanLanguage, texts: LanePromptTexts, phase: LanePhase): string =>
+  `\`${PLAN_VOCABULARY[language].phase} ${phaseLabel(phase.id)}\` (${writesText(language, texts, phase.writes)})`
+
+const planLines = (language: PlanLanguage, texts: LanePromptTexts, plan: LanePlan): string[] => [
+  `- \`${plan.path}\``,
+  ...plan.phases.map((phase) => `  - ${phaseText(language, texts, phase)}`),
+]
+
+const ruleLines = (input: LanePromptInput, texts: LanePromptTexts): string[] => [
+  input.port === null ? texts.noPort : texts.port(input.port),
+  texts.blocking,
+  texts.mustNot,
+  texts.commit,
+  texts.report(laneReportFile(input.lane)),
+  texts.textBlock,
+  texts.secret,
+  texts.askRule,
+  texts.approvalGate,
+  texts.helper(`${input.lane}-${texts.helperPurpose}`),
+]
+
+/**
+ * The prompt that starts a lane, in the plan language: a first line that names the lane (the words the ask hint hook
+ * and the project's lane exception recognise), the plans with their phases as `Phase P<n>` and each phase's write
+ * set, the rules of `/orchestrate` § 1 that `/implement` does not carry already, and the start: `/implement`, or the
+ * hand-over file after a restart.
+ */
+export const buildLanePrompt = (input: LanePromptInput): string => {
+  const texts = LANE_PROMPT_TEXTS[input.language]
+  return [
+    `${LANE_PROMPT_OPENING[input.language]} ${input.lane}. ${texts.answersTo}`,
+    '',
+    texts.phasesIntro,
+    '',
+    ...input.plans.flatMap((plan) => planLines(input.language, texts, plan)),
+    '',
+    texts.editInside,
+    texts.writeTools,
+    '',
+    ...ruleLines(input, texts).map((line) => `- ${line}`),
+    '',
+    input.handover === null ? texts.start : texts.restart(input.handover),
+    '',
+  ].join('\n')
+}

package/src/lane-prompt/command.ts

@@ -0,0 +1,87 @@
+import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
+import { boardFor } from '../plans/board-pick'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { boardRepoPathOf, readSettings, worktreeOf } from '../plans/settings'
+import { asksForHelp } from '../preview/options'
+import { buildLanePrompt } from './build'
+import { type BoardSource, type LanePromptRequest, lanePromptInputOf, type ReadPlan } from './input'
+import { LANE_PROMPT_USAGE, type LanePromptOptions, parseLanePromptOptions } from './options'
+
+/**
+ * What `lanePromptInputOf` reads, located from the command line, and the main checkout the default file goes to;
+ * `readLanePlan` reads from the lane's worktree, null for every plan while it has none.
+ */
+type PromptSources = {
+  request: LanePromptRequest
+  board: BoardSource
+  readPlan: ReadPlan
+  readLanePlan: ReadPlan
+  root: string
+}
+
+/** Where the prompt goes without `--out`: the hand-over directory of the main checkout, which git ignores. */
+export const defaultPromptFile = (root: string, lane: string): string =>
+  join(root, claudePath(HANDOVER_DIRECTORY), `${lane}-prompt.md`)
+
+/** The first of `roots` that holds `path` as a regular file, read; null when none does. */
+const readFirstIn =
+  (roots: readonly string[]) =>
+  (path: string): string | null => {
+    const file = roots
+      .map((root) => join(root, path))
+      .find((candidate) => existsSync(candidate) && statSync(candidate).isFile())
+    return file === undefined ? null : readFileSync(file, 'utf8')
+  }
+
+/** The lane's request, its board and the plan reader, from the checkouts of `cwd`; prints the board pick's notice. */
+const promptSourcesOf = (options: LanePromptOptions, cwd: string): PromptSources => {
+  const checkout = worktreeRoot(cwd)
+  const root = mainCheckout(cwd)
+  const settings = readSettings([checkout, root])
+  const boardPath = options.boardPath === null ? null : resolve(cwd, options.boardPath)
+  const board = boardFor(boardPath, [root, checkout], settings, () => [options.lane])
+  if (board.notice) console.error(board.notice)
+  const directory = dirname(boardRepoPathOf(root, settings, board.file))
+  return {
+    request: { lane: options.lane, handover: options.handover, language: settings.planLanguage },
+    board: { text: readFileSync(board.file, 'utf8'), directory, path: relative(cwd, board.file) },
+    readPlan: readFirstIn([root, checkout]),
+    readLanePlan: readFirstIn([worktreeOf(root, settings, options.lane)]),
+    root,
+  }
+}
+
+const writePrompt = (out: string, prompt: string): void => {
+  mkdirSync(dirname(out), { recursive: true })
+  writeFileSync(out, prompt)
+}
+
+/**
+ * `jh lane prompt <lane> [--board <board.md>] [--out <file>] [--handover <file>]`: writes the lane's prompt, built
+ * from its board row and its plan in the plan language, and prints the file's path, so the coordinator sends it with
+ * `herdr agent prompt <lane> "$(cat <file>)"`. `--help` prints the usage. Exit 0 written, 1 refused or failed.
+ */
+export const run = async (args: string[], cwd: string = process.cwd()): Promise<number> => {
+  if (asksForHelp(args)) {
+    console.log(LANE_PROMPT_USAGE)
+    return 0
+  }
+  try {
+    const options = parseLanePromptOptions(args)
+    const { request, board, readPlan, readLanePlan, root } = promptSourcesOf(options, cwd)
+    const result = lanePromptInputOf(request, board, readPlan, readLanePlan)
+    if (result.kind === 'refused') {
+      console.error(result.reason)
+      return 1
+    }
+    const out = options.out === null ? defaultPromptFile(root, options.lane) : resolve(cwd, options.out)
+    writePrompt(out, buildLanePrompt(result.input))
+    console.log(out)
+    return 0
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error))
+    return 1
+  }
+}