jackherd 1.9.0 → 1.10.0

package/src/check/skill-budgets.ts

@@ -0,0 +1,185 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { CLAUDE_DIRECTORY, claudePath, SKILLS_DIRECTORY } from '../claude/paths'
+import { projectLockCandidates } from '../config/legacy-names'
+import { parseManifest } from '../sync/manifest'
+import { matchesGlob } from './glob'
+import { CHECK_STATUS, type CheckResult, type CheckStatus } from './result'
+import type { SkillBudgets } from './schema'
+import {
+  KIT_FILE_FALLBACK_BUDGET,
+  KIT_SKILL_BUDGETS,
+  OWN_SKILL_BUDGET,
+  SUPPLEMENT_BUDGET,
+} from './skill-budget-defaults'
+
+/** Words per path or glob from the project root; a key joining paths with ` + ` budgets them together. */
+export type BudgetTable = Readonly<SkillBudgets>
+
+/** A file with the budget it falls back on when neither the project nor the kit names one. */
+export type FileWords = { path: string; words: number; fallback: number }
+
+export type Measurement = { label: string; words: number; budget: number }
+
+type Overrun = typeof CHECK_STATUS.warn | typeof CHECK_STATUS.fail
+
+type MeasuredOverrun = { entry: Measurement; overrun: Overrun }
+
+const SUPPLEMENTS_DIRECTORY = 'project'
+const KIT_DOCUMENT = /^(skills\/.+\.md|agents\/[^/]+\.md|rules\/kit\/[^/]+\.md)$/
+const KIT_RULE = /^rules\//
+const PATHS_IN_FRONTMATTER = /^---\r?\n(?:(?!---)[^\n]*\n)*?paths:/
+const SUM_SEPARATOR = ' + '
+const FAIL_FACTOR = 1.1
+
+const OVERRUN_LABEL: Record<Overrun, string> = { warn: 'warning', fail: 'error' }
+
+const isGlob = (key: string): boolean => /[*?]/.test(key)
+
+/**
+ * The words of a file as `wc -w` counts them: runs of non-whitespace, over the whole file. The frontmatter counts,
+ * because an agent reads it with the rest, and the skill's description in it is loaded before the body is.
+ */
+export const countWords = (text: string): number => text.split(/\s+/).filter(Boolean).length
+
+/** The paths a budget key names: one, or several joined with ` + ` for what loads together. */
+export const budgetKeyPaths = (key: string): string[] => key.split(SUM_SEPARATOR)
+
+/**
+ * Whether a kit file, by its path in the kit (`skills/…`, `agents/…`, `rules/kit/…`), is text an agent loads as it
+ * is and so counts against a budget: a skill file, an agent, or a kit rule without a `paths:` glob in its
+ * frontmatter; a rule with one loads only on demand. The one choice `jh check` and the kit's own test share.
+ */
+export const isBudgetedKitDocument = (kitPath: string, text: string): boolean =>
+  KIT_DOCUMENT.test(kitPath) && !(KIT_RULE.test(kitPath) && PATHS_IN_FRONTMATTER.test(text))
+
+/** A file warns above its budget and fails above the budget plus 10 %. */
+export const overrunOf = (words: number, budget: number): Overrun | null => {
+  if (words > budget * FAIL_FACTOR) return CHECK_STATUS.fail
+  return words > budget ? CHECK_STATUS.warn : null
+}
+
+/** The project's entry for the exact path, else its first glob that matches, else the kit's default, else `fallback`. */
+export const budgetOf = (path: string, project: BudgetTable, defaults: BudgetTable, fallback: number): number => {
+  const glob = Object.keys(project).find((key) => isGlob(key) && matchesGlob(path, key))
+  return project[path] ?? (glob === undefined ? undefined : project[glob]) ?? defaults[path] ?? fallback
+}
+
+const sumEntry = (key: string, files: readonly FileWords[]): number | null => {
+  const parts = budgetKeyPaths(key).map((part) => files.find((file) => file.path === part))
+  return parts.every((part) => part !== undefined) ? parts.reduce((total, part) => total + part.words, 0) : null
+}
+
+/** Every file against its budget, then every sum entry of the project and the kit whose files all exist. */
+export const measureFiles = (
+  files: readonly FileWords[],
+  project: BudgetTable,
+  defaults: BudgetTable,
+): Measurement[] => {
+  const single = files.map(({ path, words, fallback }) => ({
+    label: path,
+    words,
+    budget: budgetOf(path, project, defaults, fallback),
+  }))
+  const sums = [...new Set([...Object.keys(project), ...Object.keys(defaults)])]
+    .filter((key) => key.includes(SUM_SEPARATOR))
+    .flatMap((key) => {
+      const words = sumEntry(key, files)
+      return words === null ? [] : [{ label: key, words, budget: budgetOf(key, project, defaults, 0) }]
+    })
+  return [...single, ...sums]
+}
+
+const overrunLine = ({ entry: { label, words, budget }, overrun }: MeasuredOverrun): string =>
+  `${OVERRUN_LABEL[overrun]}: ${label} has ${words} words, budget ${budget}`
+
+const withinLine = (count: number): string =>
+  count === 1 ? '1 file within its word budget' : `${count} files within their word budget`
+
+const statusOf = (overruns: readonly MeasuredOverrun[]): CheckStatus => {
+  if (overruns.some(({ overrun }) => overrun === CHECK_STATUS.fail)) return CHECK_STATUS.fail
+  return overruns.length > 0 ? CHECK_STATUS.warn : CHECK_STATUS.pass
+}
+
+/** One line per overrun; one line in total when none is over. Warns above a budget, fails above the budget plus 10 %. */
+export const budgetResult = (measured: readonly Measurement[], durationMs: number): CheckResult => {
+  const overruns = measured.flatMap((entry) => {
+    const overrun = overrunOf(entry.words, entry.budget)
+    return overrun === null ? [] : [{ entry, overrun }]
+  })
+  return {
+    name: 'Skill budgets',
+    command: `${measured.length} measured, words per budget`,
+    status: statusOf(overruns),
+    detail: overruns.map(overrunLine).join('\n') || withinLine(measured.length),
+    durationMs,
+  }
+}
+
+const readText = (path: string): string | null => {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return null
+  }
+}
+
+const parseJson = (text: string): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch {
+    return null
+  }
+}
+
+/** The kit documents the first valid lock file lists, the lock under its old name counting while sync has not moved it. */
+const kitPathsOf = (root: string): string[] => {
+  for (const candidate of projectLockCandidates(root)) {
+    const text = readText(candidate)
+    const parsed = text === null ? null : parseManifest(parseJson(text))
+    if (parsed?.ok) return Object.keys(parsed.manifest.files).filter((key) => KIT_DOCUMENT.test(key))
+  }
+  return []
+}
+
+const listDirectory = (path: string): string[] => (existsSync(path) ? readdirSync(path) : [])
+
+const fileWordsOf = (root: string, path: string, fallback: number): FileWords[] => {
+  const text = readText(join(root, path))
+  return text === null ? [] : [{ path, words: countWords(text), fallback }]
+}
+
+const kitFileWordsOf = (root: string, kitPath: string): FileWords[] => {
+  const path = claudePath(kitPath)
+  const text = readText(join(root, path))
+  return text === null || !isBudgetedKitDocument(kitPath, text)
+    ? []
+    : [{ path, words: countWords(text), fallback: KIT_FILE_FALLBACK_BUDGET }]
+}
+
+const ownSkillPaths = (root: string, kit: ReadonlySet<string>): string[] =>
+  listDirectory(join(root, CLAUDE_DIRECTORY, SKILLS_DIRECTORY))
+    .map((name) => claudePath(SKILLS_DIRECTORY, name, 'SKILL.md'))
+    .filter((path) => !kit.has(path))
+
+const supplementPaths = (root: string): string[] =>
+  listDirectory(join(root, CLAUDE_DIRECTORY, SUPPLEMENTS_DIRECTORY))
+    .filter((name) => name.endsWith('.md'))
+    .map((name) => claudePath(SUPPLEMENTS_DIRECTORY, name))
+
+/**
+ * The installed kit skills with their references, kit agents and kit rules that load every session (the lock file
+ * says which files the kit installed), the project's supplements and its own skills, measured against the budgets.
+ * Null when there is nothing to measure.
+ */
+export const skillBudgetCheck = (root: string, project: BudgetTable = {}): CheckResult | null => {
+  const started = Date.now()
+  const kitPaths = kitPathsOf(root)
+  const kit = new Set(kitPaths.map((key) => claudePath(key)))
+  const files = [
+    ...kitPaths.flatMap((key) => kitFileWordsOf(root, key)),
+    ...supplementPaths(root).flatMap((path) => fileWordsOf(root, path, SUPPLEMENT_BUDGET)),
+    ...ownSkillPaths(root, kit).flatMap((path) => fileWordsOf(root, path, OWN_SKILL_BUDGET)),
+  ]
+  return files.length === 0 ? null : budgetResult(measureFiles(files, project, KIT_SKILL_BUDGETS), Date.now() - started)
+}

package/src/cli.ts

@@ -24,6 +24,7 @@ export const COMMANDS: CommandTable = {
   [HERD_COMMAND.name]: () => import('./plans/command'),
   init: () => import('./sync/init-command'),
   [HERD_COMMAND.alias]: () => import('./plans/command'),
+  lane: () => import('./lane/command'),
   preview: () => import('./preview/command'),
   settled: () => import('./settled/command'),
   sync: () => import('./sync/command'),

package/src/config/auto-window.ts

@@ -0,0 +1,8 @@
+import { DAY_MS } from '../plan-format/clock'
+
+/** The longest window `watch.parallelTasks.auto` may span: a forgotten switch ends within a week. */
+export const MAX_AUTO_WINDOW_DAYS = 7
+
+/** The days from `since` to `until`, two `YYYY-MM-DD` dates; read as UTC midnights, so no clock change shifts them. */
+export const windowDays = (since: string, until: string): number =>
+  Math.round((Date.parse(`${until}T00:00:00Z`) - Date.parse(`${since}T00:00:00Z`)) / DAY_MS)

package/src/config/link-kinds.ts

@@ -8,11 +8,17 @@ export type LinkKind = {
   icon: string
 }
 
+export const ARTIFACT_LINK_KIND: LinkKind = {
+  pattern: '^https://claude\\.ai/(code/)?artifact/',
+  label: 'Artifact',
+  icon: '✦',
+}
+
 /** The kinds known without configuration: plain URL patterns, no service is called. */
 export const DEFAULT_LINK_KINDS: readonly LinkKind[] = [
   { pattern: '^https://github\\.com/[^/]+/[^/]+/(pull|issues)/\\d+', label: 'GitHub', icon: '⑂' },
   { pattern: '^https://(www\\.)?figma\\.com/', label: 'Figma', icon: '◈' },
-  { pattern: '^https://claude\\.ai/(code/)?artifact/', label: 'Artifact', icon: '✦' },
+  ARTIFACT_LINK_KIND,
 ]
 
 export const isRegularExpression = (source: string): boolean => {

package/src/config/schema.ts

@@ -5,6 +5,7 @@ import { PLAN_LANGUAGE, RESPONSE_ADDRESS } from '../vocabulary'
 import { CONTENT_FIELDS, SOURCE_FIELD } from '../watch/source-fields'
 import { isSourcePath } from '../watch/source-path'
 import { BUN_FAILED_TEST_PATTERN, CLEAN_REVIEW_TEXT } from '../watch/watch-defaults'
+import { MAX_AUTO_WINDOW_DAYS, windowDays } from './auto-window'
 import { BUN_COMMANDS, DEFAULT_BASE_BRANCH } from './detect'
 import { DEFAULT_LINK_KINDS, isRegularExpression } from './link-kinds'
 import { hasNestedQuantifier } from './nested-quantifier'
@@ -127,6 +128,20 @@ const parallelTasksSchema = z.strictObject({
    * the first answer of a lane's session carried.
    */
   maxTokens: z.number().int().positive().default(DEFAULT_PARALLEL_TASKS_MAX_TOKENS),
+  /**
+   * The days, both included, on which a proposal that keeps every limit is marked `auto` and the coordinator starts it
+   * without asking: subagents beside running work in a lane, at most two extra agents, no path that always asks.
+   * `since` is the day it was switched on, `until` at most seven days later; outside the window it is off. Unset by
+   * default, so every proposal asks.
+   */
+  auto: z
+    .strictObject({ since: z.iso.date(), until: z.iso.date() })
+    .refine(({ since, until }) => until >= since, 'until must not be before since')
+    .refine(
+      ({ since, until }) => windowDays(since, until) <= MAX_AUTO_WINDOW_DAYS,
+      `until must be at most ${MAX_AUTO_WINDOW_DAYS} days after since`,
+    )
+    .optional(),
 })
 
 const checksSchema = z.strictObject({
@@ -269,7 +284,7 @@ const checkFreePattern = z
   )
 
 /**
- * A path pattern that always asks before a merge under a plan approval: plain path words with wildcards, relative, no
+ * A path pattern that always asks (`guard.alwaysAsk`): plain path words with wildcards, relative, no
  * empty, `.` or `..` segment (GitHub lists no file with one, so such a pattern would never ask). Broad on purpose (`.github/**`, `**`), since a pattern here only ever adds a question; braces,
  * classes and negation stay out, so the hook, which has no schema library, reads exactly what this accepts.
  */
@@ -304,13 +319,13 @@ const mergeSchema = z.strictObject({
   withoutChecks: z.array(checkFreePattern).default([]),
 })
 
-const guardSchema = z.strictObject({
+const guardFields = z.strictObject({
   /**
-   * The commands the merge guard hook asks the user about before they run, also behind options before the verb, a chain,
-   * a wrapper or `sh -c`. `gh api` asks only for a write to a merge, a file, a dispatch, a rerun or a ref. An empty list switches the
-   * guard off.
+   * The commands the merge guard hook asks the user about before they run, where they stand at a program position, also
+   * behind options before the verb, a chain, a wrapper or `sh -c`. `gh api`, when listed, asks only for a write to a
+   * merge, a file, a dispatch, a rerun or a ref. An empty list switches the guard off.
    */
-  commands: z.array(guardedCommand).default(['gh pr merge', 'gh workflow run', 'gh run rerun', 'gh api']),
+  commands: z.array(guardedCommand).default(['gh pr merge', 'gh workflow run']),
   selfMerge: z
     .strictObject({
       /** Whether `/orchestrate` offers "merge it yourself after green checks" in the pull request question; off also stops the hook honouring such an answer. */
@@ -325,32 +340,49 @@ const guardSchema = z.strictObject({
       waitMinutes: z.number().int().min(1).max(9).default(8),
     })
     .prefault({}),
+  /**
+   * Paths that always ask, on top of the ones jackherd brings (`.github/**`, `**\/migrations/**`, `**\/.env*`,
+   * `.claude/**`, `.jackherd/**`, `bunfig.toml`, `**\/CLAUDE.md`, `**\/AGENTS.md`, `.agents/**`, `.mcp.json`,
+   * `.husky/**`, `lefthook.yml`, the lockfiles of bun, npm, pnpm and yarn, `**\/.npmrc`, `**\/CODEOWNERS`): a
+   * `merge.withoutChecks` pattern never opens them, and the watcher never starts parallel work on them by itself. They
+   * add to that list, never replace it. A standing approval covers them; only workflows, migrations and env files ask.
+   */
+  alwaysAsk: z.array(alwaysAskPattern).default([]),
+  /**
+   * Checks that must be among the head commit's and green before a standing approval lets a merge pass, by their names
+   * on GitHub. Unset, the merge needs at least one check and every one green; set, also each of these. Either way
+   * GitHub must be able to merge it.
+   */
+  requiredChecks: z.array(checkName).optional(),
+  /** Read until 2.0.0 as `alwaysAsk` (`exceptPaths`) and `requiredChecks`; the plan approval it was for is gone. */
   planApproval: z
-    .strictObject({
-      /**
-       * Paths that always ask, on top of the ones jackherd brings (`.github/**`, `**\/migrations/**`, `**\/.env*`,
-       * `.claude/**`, `.jackherd/**`, `bunfig.toml`, `**\/CLAUDE.md`, `**\/AGENTS.md`, `.agents/**`, `.mcp.json`,
-       * `.husky/**`, `lefthook.yml`, the lockfiles of bun, npm, pnpm and yarn, `**\/.npmrc`, `**\/CODEOWNERS`, every
-       * package.json, and the CHANGELOG.md of every package without `"private": true`):
-       * a pull request that changes one is never merged on a plan approval alone. They add to that list, never replace
-       * it; an invalid entry turns plan approval off, so every merge asks.
-       */
-      exceptPaths: z.array(alwaysAskPattern).default([]),
-      /**
-       * Checks that must be among the head commit's and green before a plan approval lets a merge pass, by their names
-       * on GitHub. Unset, the merge needs at least one check and every one green; set, also each of these. Either way
-       * GitHub must be able to merge it and the head must contain the base branch.
-       */
-      requiredChecks: z.array(checkName).optional(),
-    })
-    .prefault({}),
+    .strictObject({ exceptPaths: z.array(alwaysAskPattern).optional(), requiredChecks: z.array(checkName).optional() })
+    .optional()
+    .meta({ deprecated: true }),
 })
 
+/** A config from before 1.10.0 kept the paths that always ask and the required checks under `planApproval`. */
+const guardWithoutPlanApproval = ({ planApproval, ...guard }: z.output<typeof guardFields>) => {
+  const requiredChecks = guard.requiredChecks ?? planApproval?.requiredChecks
+  return {
+    ...guard,
+    alwaysAsk: [...guard.alwaysAsk, ...(planApproval?.exceptPaths ?? [])],
+    ...(requiredChecks === undefined ? {} : { requiredChecks }),
+  }
+}
+
+const guardSchema = guardFields.transform(guardWithoutPlanApproval)
+
 const hintsSchema = z.strictObject({
   /** Whether the `ask-hint` hook points out a last message that ends in a question while the turn used no `AskUserQuestion`; a lane session is never hinted. */
   askUserQuestion: z.boolean().default(true),
+  /** Whether the `task-hint` hook points a lane that edits a file without an open task signal to `jh task start`, once per task. */
+  taskSignal: z.boolean().default(true),
 })
 
+/** Minutes a lane works without a task signal before the watcher reports `no task signal`. */
+const DEFAULT_TASK_SIGNAL_MINUTES = 10
+
 const contextSchema = z
   .strictObject({
     /** Tokens in a lane's context from which its fill shows yellow and `/implement` offers a new chat. */
@@ -449,6 +481,7 @@ export const jackherdConfigSchema = z.strictObject({
    * Read by `jh watch`; without `deploy` it reports no deploy runs. `feedback` is on unless set to `false`:
    * it reports new feedback on the lanes' pull requests except from the account the watcher runs as and `ignore`.
    * `parallelTasks.maxTokens` caps the cost of the extra agents in a proposal of parallel tasks at the heartbeat.
+   * `taskSignalMinutes` is how long a lane works without a task signal before it reports `no task signal`, once per phase.
    * `checks` reads the failed tests of a red lane pull request (`failedTestPattern`), also with `feedback` off.
    * Without `previews` it reads no deploy preview; with it, one `preview` per new head commit. Each of `sources` is a
    * command whose JSON output reports `source` for a new or changed entry.
@@ -459,6 +492,7 @@ export const jackherdConfigSchema = z.strictObject({
       feedback: z.union([z.literal(false), feedbackSchema]).prefault({}),
       checks: checksSchema.prefault({}),
       parallelTasks: parallelTasksSchema.prefault({}),
+      taskSignalMinutes: z.number().int().positive().default(DEFAULT_TASK_SIGNAL_MINUTES),
       previews: previewsSchema.optional(),
       sources: z.array(sourceSchema).refine(hasUniqueNames, 'source names must be unique').default([]),
     })

package/src/lane/close-board.ts

@@ -0,0 +1,106 @@
+import { twoDigits } from '../plan-format/clock'
+import { laneNameOf, parseSprintLanes } from '../plan-format/lanes'
+import { firstTableRows, sectionLines, sectionStart } from '../plan-format/markdown'
+import { terminalSafe } from '../plan-format/terminal-text'
+import { PLAN_LANGUAGE, PLAN_VOCABULARY, type PlanLanguage } from '../vocabulary'
+import { BOARD_LANE, type BoardLane } from './close-check'
+
+const CONTINUATION = '↳'
+const FIRST_CELL = /^\|((?:[^|\\]|\\.)*)\|/
+
+const HISTORY_HEADER: Record<PlanLanguage, readonly [string, string]> = {
+  [PLAN_LANGUAGE.de]: ['Datum', 'Ereignis'],
+  [PLAN_LANGUAGE.en]: ['Date', 'Event'],
+}
+
+const isoDate = (time: Date): string =>
+  `${time.getFullYear()}-${twoDigits(time.getMonth() + 1)}-${twoDigits(time.getDate())}`
+
+/** The word for a cleaned-up lane and the day, as a name cell carries it: `abgeräumt DD.MM.`, `cleaned up YYYY-MM-DD`. */
+export const closedMark = (time: Date, language: PlanLanguage): string => {
+  const day =
+    language === PLAN_LANGUAGE.de ? `${twoDigits(time.getDate())}.${twoDigits(time.getMonth() + 1)}.` : isoDate(time)
+  return `${PLAN_VOCABULARY[language].laneClosed} ${day}`
+}
+
+/** The date cell of a history row, `YYYY-MM-DD` in every plan language. */
+export const historyDate = (time: Date): string => isoDate(time)
+
+/** How the lanes table names `lane`, read as the herd reads it. */
+export const boardLaneOf = (board: string, lane: string, language: PlanLanguage): BoardLane => {
+  const found = parseSprintLanes(board, language).find(({ name }) => name === lane)
+  if (found === undefined) return BOARD_LANE.missing
+  return found.closed ? BOARD_LANE.closed : BOARD_LANE.open
+}
+
+/**
+ * The line indexes of the lane's current rows: the rows since it was last cleaned up, as `parseSprintLanes` keeps them,
+ * a row that names the lane again without the mark starting it anew. Empty when the lane is closed or missing.
+ */
+const currentRowIndexes = (board: string, lane: string, language: PlanLanguage): number[] => {
+  const { sections, laneClosed } = PLAN_VOCABULARY[language]
+  const start = sectionStart(board, sections.lanes)
+  if (start === -1) return []
+  let previous: string | null = null
+  let closed = false
+  let indexes: number[] = []
+  for (const { index, cells } of firstTableRows(sectionLines(board, sections.lanes))) {
+    const first = cells[0] ?? ''
+    const name = laneNameOf(first, previous)
+    previous = name ?? previous
+    if (name !== lane) continue
+    const marked = first.includes(laneClosed)
+    if (closed && !marked && !first.startsWith(CONTINUATION)) {
+      closed = false
+      indexes = []
+    }
+    closed ||= marked
+    indexes.push(start + index)
+  }
+  return closed ? [] : indexes
+}
+
+const withMarkedNameCell = (line: string, mark: string): string =>
+  line.replace(FIRST_CELL, (_cell, name: string) => `| ${name.trim()}, ${mark} |`)
+
+/** The board with `, <mark>` appended to the name cell of each current row of the lane; unchanged without one. */
+export const withLaneClosed = (board: string, lane: string, mark: string, language: PlanLanguage): string => {
+  const marked = new Set(currentRowIndexes(board, lane, language))
+  return board
+    .split('\n')
+    .map((line, index) => (marked.has(index) ? withMarkedNameCell(line, mark) : line))
+    .join('\n')
+}
+
+/** Text that stays inside one table cell: on one line, with its pipes escaped. */
+const cell = (text: string): string => terminalSafe(text.replace(/\s+/g, ' ')).trim().replaceAll('|', '\\|')
+
+const historyTableHead = (language: PlanLanguage): string[] => {
+  const header = HISTORY_HEADER[language]
+  return [`| ${header.join(' | ')} |`, `|${header.map((name) => '-'.repeat(name.length + 2)).join('|')}|`]
+}
+
+const withoutTrailingBlanks = (lines: readonly string[]): string[] => {
+  let end = lines.length
+  while (end > 0 && lines[end - 1].trim() === '') end -= 1
+  return lines.slice(0, end)
+}
+
+/**
+ * The board with a row on top of its history table, newest first as the coordinator writes them. A history section
+ * without a table gets one right under its heading; a board without the section gets it at its end.
+ */
+export const withHistoryRow = (board: string, date: string, text: string, language: PlanLanguage): string => {
+  const heading = PLAN_VOCABULARY[language].sections.history
+  const row = `| ${date} | ${cell(text)} |`
+  const lines = board.split('\n')
+  const start = sectionStart(board, heading)
+  if (start === -1)
+    return [...withoutTrailingBlanks(lines), '', `## ${heading}`, '', ...historyTableHead(language), row, ''].join('\n')
+  const tableAt = sectionLines(board, heading).findIndex((line) => line.startsWith('|'))
+  const firstRow = start + tableAt + 2
+  if (tableAt !== -1) return [...lines.slice(0, firstRow), row, ...lines.slice(firstRow)].join('\n')
+  const at = lines[start]?.trim() === '' ? start + 1 : start
+  const table = [...historyTableHead(language), row, ...(lines[start]?.trim() === '' ? [''] : [])]
+  return [...lines.slice(0, at), ...table, ...lines.slice(at)].join('\n')
+}

package/src/lane/close-check.ts

@@ -0,0 +1,183 @@
+/** The lane's merged pull request: the newest one on its branch, with the commit the merge left on the base. */
+export type MergedPullRequest = { number: number; headCommit: string; mergeCommit: string }
+
+import { claudePath, HANDOVER_DIRECTORY } from '../claude/paths'
+import { AGENT_STATUS } from '../terminal/types'
+
+/** How the board's lanes table names the lane: with open rows, only with rows marked cleaned up, or not at all. */
+export const BOARD_LANE = { open: 'open', closed: 'closed', missing: 'missing' } as const
+
+export type BoardLane = (typeof BOARD_LANE)[keyof typeof BOARD_LANE]
+
+/** The lane's branch, the head the check compared, and its merged pull request once nothing stands against closing it. */
+export type ClosableLane = { branch: string; head: string; pullRequest: MergedPullRequest }
+
+/** Every reason against closing, or the lane ready to close; the second only when the first is empty. */
+export type CloseVerdict = { kind: 'refused'; refusals: string[] } | ({ kind: 'closable' } & ClosableLane)
+
+/** One entry of `git status --porcelain`: its two status letters (`!!` ignored, `??` untracked) and its path. */
+export type StatusEntry = { code: string; path: string }
+
+/**
+ * What git, GitHub and the terminal answered about one lane, gathered before anything is removed. `treeDiff` lists the
+ * paths in which the branch head differs from the merge commit; `status` holds the worktree's status with ignored
+ * files (`statusEntriesOf`); `setupFiles` the patterns of the lane setup's copy list; `handoverEntries` every
+ * entry of the worktree's handover directory, which git shows only as the directory.
+ */
+export type CloseFacts = {
+  lane: string
+  boardLane: BoardLane
+  worktreeExists: boolean
+  branch: string | null
+  /** The commit the worktree's branch points to, as `git worktree list` reports it; null without a worktree. */
+  head: string | null
+  pullRequest: MergedPullRequest | null
+  treeDiff: readonly string[]
+  status: readonly StatusEntry[]
+  setupFiles: readonly string[]
+  handoverEntries: readonly string[]
+  /** The agent named after the lane whose directory lies in the worktree, with its pane. */
+  agent: { pane: string; status: string } | null
+  /** The panes of other agents whose directory lies in the worktree: a helper, or a session without the lane's name. */
+  otherAgents: readonly string[]
+  /** Whether the command itself runs in the worktree it would remove. */
+  runsInside: boolean
+  /** The reason `git worktree lock` recorded, empty for a lock without one; null when the worktree is not locked. */
+  locked: string | null
+}
+
+const RESTING_AGENT = new Set<string>([AGENT_STATUS.idle, AGENT_STATUS.done])
+const IGNORED_CODE = '!!'
+const RENAME_OR_COPY = new Set(['R', 'C'])
+/** A status field is two letters, a space, then the path. */
+const STATUS_PATH_START = 3
+const DEPENDENCY_DIRECTORY = 'node_modules'
+const BUILD_OUTPUT_DIRECTORIES = ['dist', '.turbo', 'test-results', '__pycache__']
+const BUILD_OUTPUT = [
+  ...BUILD_OUTPUT_DIRECTORIES.flatMap((directory) => [`**/${directory}`, `**/${directory}/**`]),
+  '**/*.tsbuildinfo',
+  'packages/*/bin/*.{js,mjs,cjs}',
+  '.husky/_',
+  '.husky/_/**',
+].map((glob) => new Bun.Glob(glob))
+/** Build output only as a directory entry: a package's `bin/` that an ignore rule hides as a whole. */
+const BUILD_OUTPUT_DIRECTORY_ENTRIES = [new Bun.Glob('packages/*/bin')]
+const HANDOVER = claudePath(HANDOVER_DIRECTORY)
+
+const withoutSlashes = (path: string): string => path.replace(/^\/+|\/+$/g, '')
+
+const isHandoverDirectory = (path: string): boolean => withoutSlashes(path) === HANDOVER
+
+/** The patterns of a `.gitignore`-style list that name files; comments, blanks and negations name none. */
+const patternsOf = (lines: readonly string[]): string[] =>
+  lines.map((line) => line.trim()).filter((line) => line !== '' && !line.startsWith('#') && !line.startsWith('!'))
+
+/**
+ * Whether `path` (relative to the worktree, a directory with its trailing slash) is one the lane setup copies in: a
+ * pattern with an inner slash is anchored at the root, one without matches the name at any depth, as in `.gitignore`.
+ */
+export const isSetupFile = (path: string, setupFiles: readonly string[]): boolean => {
+  const target = withoutSlashes(path)
+  return patternsOf(setupFiles).some((pattern) => {
+    const bare = withoutSlashes(pattern)
+    const glob = bare.includes('/') ? bare : `**/${bare}`
+    return new Bun.Glob(glob).match(target) || new Bun.Glob(bare).match(target)
+  })
+}
+
+const isDependencyPath = (path: string): boolean => withoutSlashes(path).split('/').includes(DEPENDENCY_DIRECTORY)
+
+/**
+ * The entries of `git status --porcelain=v1 -z --ignored=matching`: NUL-separated, never quoted, a rename or copy followed by
+ * its source as a field of its own, which is skipped. Names are read as git wrote them, so no file name can pose as
+ * another path.
+ */
+export const statusEntriesOf = (output: string): StatusEntry[] => {
+  const fields = output.split('\0')
+  const entries: StatusEntry[] = []
+  for (let i = 0; i < fields.length; i += 1) {
+    const field = fields[i]
+    if (field.length < STATUS_PATH_START) continue
+    const code = field.slice(0, 2)
+    entries.push({ code, path: field.slice(STATUS_PATH_START) })
+    if (RENAME_OR_COPY.has(code[0])) i += 1
+  }
+  return entries
+}
+
+/**
+ * Whether `path` (relative to the worktree, a directory with its trailing slash) is output a build makes again, from a
+ * fixed list: `dist`, `.turbo`, `test-results` and `__pycache__` at any depth, a `*.tsbuildinfo`, a
+ * `packages/*\/bin/*.{js,mjs,cjs}` or a whole `packages/*\/bin/`, and husky's helpers in `.husky/_`. Everything else an
+ * ignore rule hides may hold work and is not.
+ */
+export const isBuildOutput = (path: string): boolean => {
+  const target = withoutSlashes(path)
+  const directory = path.endsWith('/') && BUILD_OUTPUT_DIRECTORY_ENTRIES.some((glob) => glob.match(target))
+  return directory || BUILD_OUTPUT.some((glob) => glob.match(target))
+}
+
+/**
+ * The paths removing the worktree would delete for good: every tracked change and untracked file, and every ignored
+ * path except dependencies (`node_modules` at any depth), the setup files, build output and the handover directory.
+ */
+export const lostPathsOf = (status: readonly StatusEntry[], setupFiles: readonly string[]): string[] => {
+  const kept = (path: string) =>
+    isDependencyPath(path) || isSetupFile(path, setupFiles) || isBuildOutput(path) || isHandoverDirectory(path)
+  return status.filter(({ code, path }) => code !== IGNORED_CODE || !kept(path)).map(({ path }) => path)
+}
+
+/** The lost paths and the entries of the handover directory, each once: the directory stands for all of them. */
+const deletedPathsOf = ({ status, setupFiles, handoverEntries }: CloseFacts): string[] => [
+  ...new Set([...lostPathsOf(status, setupFiles), ...handoverEntries]),
+]
+
+/** A lane the board marks cleaned up already may still have its worktree left over; only a lane it never named is refused. */
+const boardRefusals = ({ lane, boardLane }: CloseFacts): string[] =>
+  boardLane === BOARD_LANE.missing ? [`the board has no row for lane ${lane}`] : []
+
+const mergeRefusals = ({ lane, branch, pullRequest, treeDiff }: CloseFacts): string[] => {
+  if (branch === null) return [`the worktree of ${lane} is on no branch`]
+  if (pullRequest === null) return [`branch ${branch} has no merged pull request`]
+  return treeDiff.map(
+    (path) => `branch ${branch} differs from the merge of #${pullRequest.number} (${pullRequest.mergeCommit}): ${path}`,
+  )
+}
+
+const agentRefusals = ({ lane, agent, otherAgents }: CloseFacts): string[] => [
+  ...(agent === null || RESTING_AGENT.has(agent.status) ? [] : [`the agent of ${lane} is ${agent.status}`]),
+  ...otherAgents.map((pane) => `pane ${pane} runs another agent in the worktree of ${lane}`),
+]
+
+const lockRefusals = ({ lane, locked }: CloseFacts): string[] =>
+  locked === null
+    ? []
+    : [`the worktree of ${lane} is locked${locked ? ` (${locked})` : ''}; unlock it once its session has ended`]
+
+/**
+ * Every reason not to close the lane, all at once; empty when nothing would be lost. Closing needs an open board row,
+ * the worktree on a branch whose newest merged pull request left the same tree on the base (a squash merge leaves the
+ * branch unmerged in git's eyes, so the trees are compared), nothing in the worktree beyond dependencies, the setup
+ * files and build output (`isBuildOutput`), an empty handover directory, an agent that is gone or rests, and no lock
+ * on the worktree (a Claude Code session may still hold it).
+ */
+export const closeRefusals = (facts: CloseFacts): string[] => {
+  if (!facts.worktreeExists) return [...boardRefusals(facts), `lane ${facts.lane} has no worktree`]
+  if (facts.runsInside) return [`run it outside the worktree of ${facts.lane}, which it would remove`]
+  return [
+    ...boardRefusals(facts),
+    ...mergeRefusals(facts),
+    ...deletedPathsOf(facts).map((path) => `removing the worktree deletes ${path}`),
+    ...agentRefusals(facts),
+    ...lockRefusals(facts),
+  ]
+}
+
+/** `closeRefusals` as a verdict that carries the branch and pull request it proved, so a caller needs no second check. */
+export const closeVerdict = (facts: CloseFacts): CloseVerdict => {
+  const refusals = closeRefusals(facts)
+  const { branch, head, pullRequest } = facts
+  if (refusals.length > 0 || branch === null || head === null || pullRequest === null)
+    return { kind: 'refused', refusals }
+  return { kind: 'closable', branch, head, pullRequest }
+}

package/src/lane/close-command-line.ts

@@ -0,0 +1,11 @@
+import { CLI_NAME } from '../version/release'
+import { SAFE_LANE_NAME } from '../watch/lane-name'
+
+/** The command as the usage, the board's history and the watcher's status line name it. */
+export const LANE_CLOSE_COMMAND = `${CLI_NAME} lane close`
+
+export const DRY_RUN_OPTION = '--dry-run'
+
+/** The dry run the watcher suggests for a lane; null for a name no command line should carry. */
+export const closeDryRunOf = (lane: string): string | null =>
+  SAFE_LANE_NAME.test(lane) ? `${LANE_CLOSE_COMMAND} ${lane} ${DRY_RUN_OPTION}` : null