jackherd 1.7.1 → 1.8.1

package/kit/hooks/hooks/merge-guard/xargs-program.ts

@@ -0,0 +1,182 @@
+import { programName, ruleStart } from '../shared/program-position'
+import { expandsBraces, isExpanded, type SimpleCommand, type Word } from '../shared/shell'
+
+/**
+ * What an `xargs` call is told to run: the program word (absent when it runs `echo`) and where it stands among the
+ * words after `xargs`, and the strings `-I`, `-i`, `--replace` or BSD's `-J` replace with the input, which may stand
+ * anywhere, the program included.
+ */
+type XargsCall = { program: Word | undefined; at: number; replaceStrings: string[] }
+
+/** One option word read: the words it used up, and the replace string it set, if any. */
+type OptionRead = { width: number; replaceString?: string }
+
+const XARGS = 'xargs'
+const END_OF_OPTIONS = '--'
+const DEFAULT_REPLACE_STRING = '{}'
+const GLOB = /[*?[]/
+const ECHO: Word = { value: 'echo', literal: true }
+
+/** GNU and BSD short options: with a value (attached or the next word), with a value only when attached, without one. */
+const SHORT_WITH_VALUE = new Set(['a', 'd', 'E', 'I', 'J', 'L', 'n', 'P', 'R', 's', 'S'])
+const SHORT_WITH_ATTACHED_VALUE = new Set(['e', 'i', 'l'])
+const SHORT_FLAGS = new Set(['0', 'o', 'p', 'r', 't', 'x'])
+const SHORT_REPLACE = new Set(['I', 'J'])
+const SHORT_OLD_REPLACE = 'i'
+
+const LONG_WITH_VALUE = new Set([
+  '--arg-file',
+  '--delimiter',
+  '--max-args',
+  '--max-chars',
+  '--max-procs',
+  '--process-slot-var',
+])
+const LONG_WITH_ATTACHED_VALUE = new Set(['--eof', '--max-lines', '--replace'])
+const LONG_FLAGS = new Set([
+  '--exit',
+  '--help',
+  '--interactive',
+  '--no-run-if-empty',
+  '--null',
+  '--open-tty',
+  '--show-limits',
+  '--verbose',
+  '--version',
+])
+const LONG_REPLACE = '--replace'
+
+/**
+ * Programs that read or write the files their arguments name and start nothing, whatever the arguments say: input
+ * handed to them by `xargs` stays arguments. A program that runs text or a program its arguments name stays out (`git`
+ * with `-c alias.…`, `sed` with `e`, `awk` with `system()`, `rg --pre`, `sort --compress-program`), as does every
+ * program not listed: the list is closed, so an unknown program keeps the search of the whole text.
+ */
+const PLAIN_PROGRAMS = new Set([
+  'basename',
+  'cat',
+  'chmod',
+  'dirname',
+  'du',
+  'echo',
+  'egrep',
+  'fgrep',
+  'file',
+  'grep',
+  'head',
+  'jq',
+  'ls',
+  'md5sum',
+  'mkdir',
+  'printf',
+  'readlink',
+  'realpath',
+  'rm',
+  'rmdir',
+  'sha1sum',
+  'sha256sum',
+  'shasum',
+  'stat',
+  'tail',
+  'touch',
+  'tr',
+  'uniq',
+  'wc',
+])
+
+/**
+ * A word the shell hands over as written, quotes and escapes aside: an expansion, a glob or braces could become
+ * several words, or none, and shift which word is the program.
+ */
+const isFixed = ({ value }: Word): boolean => !isExpanded(value) && !GLOB.test(value) && !expandsBraces(value)
+
+/** A value in the next word must be there and fixed. */
+const nextValue = (words: Word[], index: number): Word | undefined => {
+  const next = words[index + 1]
+  return next !== undefined && isFixed(next) ? next : undefined
+}
+
+const readLongOption = (words: Word[], index: number): OptionRead | undefined => {
+  const { value } = words[index]
+  const at = value.indexOf('=')
+  const name = at === -1 ? value : value.slice(0, at)
+  const attached = at === -1 ? undefined : value.slice(at + 1)
+  if (LONG_WITH_VALUE.has(name)) {
+    if (attached !== undefined) return { width: 1 }
+    return nextValue(words, index) ? { width: 2 } : undefined
+  }
+  if (LONG_WITH_ATTACHED_VALUE.has(name)) {
+    const replaceString = name === LONG_REPLACE ? (attached ?? DEFAULT_REPLACE_STRING) : undefined
+    return { width: 1, replaceString }
+  }
+  return LONG_FLAGS.has(name) && attached === undefined ? { width: 1 } : undefined
+}
+
+/** A short option that takes a value: the rest of its word, or the next word when nothing is attached. */
+const readShortValue = (words: Word[], index: number, letter: string, attached: string): OptionRead | undefined => {
+  if (attached !== '') return { width: 1, replaceString: SHORT_REPLACE.has(letter) ? attached : undefined }
+  const separate = nextValue(words, index)
+  if (separate === undefined) return undefined
+  return { width: 2, replaceString: SHORT_REPLACE.has(letter) ? separate.value : undefined }
+}
+
+/** A cluster of short options (`-0rn1`, `-tI{}`): flags, then at most one option that takes the rest as its value. */
+const readShortOptions = (words: Word[], index: number): OptionRead | undefined => {
+  const { value } = words[index]
+  for (let at = 1; at < value.length; at++) {
+    const letter = value[at]
+    if (SHORT_FLAGS.has(letter)) continue
+    const attached = value.slice(at + 1)
+    if (SHORT_WITH_VALUE.has(letter)) return readShortValue(words, index, letter, attached)
+    if (!SHORT_WITH_ATTACHED_VALUE.has(letter)) return undefined
+    const replaceString = letter === SHORT_OLD_REPLACE ? attached || DEFAULT_REPLACE_STRING : undefined
+    return { width: 1, replaceString }
+  }
+  return { width: 1 }
+}
+
+const readOption = (words: Word[], index: number): OptionRead | undefined =>
+  words[index].value.startsWith('--') ? readLongOption(words, index) : readShortOptions(words, index)
+
+/**
+ * Reads the words after `xargs` up to its program. An option this guard does not know, or a word before the program
+ * that is not fixed, makes the call unreadable: undefined.
+ */
+const readXargsCall = (args: Word[]): XargsCall | undefined => {
+  const replaceStrings: string[] = []
+  for (let index = 0; index < args.length; ) {
+    const word = args[index]
+    if (!isFixed(word)) return undefined
+    if (word.value === END_OF_OPTIONS) return { program: args[index + 1], at: index + 1, replaceStrings }
+    if (!word.value.startsWith('-') || word.value === '-') return { program: word, at: index, replaceStrings }
+    const option = readOption(args, index)
+    if (option === undefined) return undefined
+    if (option.replaceString !== undefined) replaceStrings.push(option.replaceString)
+    index += option.width
+  }
+  return { program: undefined, at: args.length, replaceStrings }
+}
+
+const isPlainProgram = (program: Word, replaceStrings: string[], guardedPrograms: readonly string[]): boolean =>
+  isFixed(program) &&
+  !replaceStrings.some((replaceString) => program.value.includes(replaceString)) &&
+  PLAIN_PROGRAMS.has(program.value) &&
+  !guardedPrograms.includes(program.value)
+
+/**
+ * An `xargs` at the start of the command that runs a fixed program starting nothing (D77) becomes that program's
+ * call, the words before `xargs` kept: its input then only adds arguments, so the program counts like any other call
+ * and the text around it is no sign. Without a program it becomes `echo`, which `xargs` then runs. Every other
+ * command comes back as it is, so `xargs` stays opaque for a program from an expansion or a replace string, a glob,
+ * a guarded program, a starter (a shell, `env`, `xargs`, `timeout`, an interpreter) and any program not on the list.
+ */
+export const resolvePlainXargs = (words: SimpleCommand, guardedPrograms: readonly string[]): SimpleCommand => {
+  const start = ruleStart(words)
+  if (words[start] === undefined || programName(words[start]) !== XARGS) return words
+  const call = readXargsCall(words.slice(start + 1))
+  if (call === undefined) return words
+  const prefix = words.slice(0, start)
+  if (call.program === undefined) return [...prefix, ECHO]
+  if (!isPlainProgram(call.program, call.replaceStrings, guardedPrograms)) return words
+  return [...prefix, ...words.slice(start + 1 + call.at)]
+}

package/kit/hooks/hooks/shared/base-branch.ts

@@ -0,0 +1,23 @@
+export const DEFAULT_BASE_BRANCH = 'main'
+
+/**
+ * A branch name both guards accept as the base branch: no option (`-x`), no `HEAD`, none of the forms git refuses
+ * (`..`, `//`, `@{`, a `.lock` component, a trailing `.` or `/`), only characters a project plausibly names one with.
+ */
+const BRANCH =/^(?!HEAD$)(?![-/.])(?!.*(?:\.\.|\/\/|@\{|\.lock(?:\/|$)))[A-Za-z0-9._/-]+(?<![./])$/
+
+const BRANCH_REF = /^refs\/heads\//
+
+const isBranchName = (value: unknown): value is string => typeof value === 'string' && BRANCH.test(value)
+
+/**
+ * The base branch a project config names, `refs/heads/<name>` read as `<name>`: `main` when it names none, undefined
+ * when the config could not be read (`null`) or the value is no branch name.
+ */
+export const baseBranchOf = (config: Record<string, unknown> | null): string | undefined => {
+  if (config === null) return undefined
+  if (!('baseBranch' in config)) return DEFAULT_BASE_BRANCH
+  const value = config.baseBranch
+  const name = typeof value === 'string' ? value.replace(BRANCH_REF, '') : value
+  return isBranchName(name) ? name : undefined
+}

package/kit/hooks/hooks/shared/board-lanes.ts

@@ -0,0 +1,93 @@
+/**
+ * The lanes table of a board, read the way the herd reads it (`parseSprintLanes` in the package), which a hook cannot
+ * import: the first table under `## <lanes>`, a row naming its lane in backticks or continuing the one above with `↳`,
+ * the plan as the link in the third cell. A test compares both on the repository's real boards.
+ */
+import { posix } from 'node:path'
+
+export type BoardLanguage = 'de' | 'en'
+
+/** The plan vocabulary's words for the lanes section and a closed lane, per plan language. */
+export const BOARD_WORDS: Record<BoardLanguage, { lanes: string; laneClosed: string }> = {
+  de: { lanes: 'Spuren', laneClosed: 'abgeräumt' },
+  en: { lanes: 'Lanes', laneClosed: 'cleaned up' },
+}
+
+/** A lane's rows: whether any says the lane was cleaned up, and the plans they link, relative to the repository. */
+export type LanePlans = { closed: boolean; plans: string[] }
+
+type Row = { lane: string; cells: string[] }
+
+const LANE_NAME = /`([^`]+)`/
+const CONTINUATION = '↳'
+const PLAN_LINK = /\[([^\]]+)\]\(([^)]+)\)/
+const SECTION_END = /^##\s/
+const TABLE_SEPARATOR = /^\|[\s|:-]+\|$/
+const PLAN_COLUMN = 2
+
+const escapeRegExp = (text: string): string => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+
+const sectionLines = (markdown: string, heading: string): string[] => {
+  const lines = markdown.split('\n')
+  const pattern = new RegExp(`^##\\s+${escapeRegExp(heading)}\\s*$`)
+  const start = lines.findIndex((line) => pattern.test(line))
+  if (start === -1) return []
+  const rest = lines.slice(start + 1)
+  const end = rest.findIndex((line) => SECTION_END.test(line))
+  return end === -1 ? rest : rest.slice(0, end)
+}
+
+const cellsOf = (line: string): string[] =>
+  line
+    .slice(1, line.endsWith('|') ? -1 : undefined)
+    .split('|')
+    .map((cell) => cell.trim())
+
+/** The body rows of the first table, header and separator rows dropped. */
+const firstTableLines = (lines: string[]): string[] => {
+  const start = lines.findIndex((line) => line.startsWith('|'))
+  if (start === -1) return []
+  const rest = lines.slice(start)
+  const end = rest.findIndex((line) => !line.startsWith('|'))
+  return (end === -1 ? rest : rest.slice(0, end)).slice(1).filter((line) => !TABLE_SEPARATOR.test(line))
+}
+
+const laneRows = (markdown: string, language: BoardLanguage): Row[] => {
+  const rows: Row[] = []
+  let previous: string | null = null
+  for (const line of firstTableLines(sectionLines(markdown, BOARD_WORDS[language].lanes))) {
+    const cells = cellsOf(line)
+    const first = cells[0] ?? ''
+    const lane: string | null = first.match(LANE_NAME)?.[1] ?? (first.startsWith(CONTINUATION) ? previous : null)
+    if (lane === null) continue
+    rows.push({ lane, cells })
+    previous = lane
+  }
+  return rows
+}
+
+/** The repository path of a plan link, relative to the board's directory. */
+const planPathOf = (boardDirectory: string, cell: string): string[] => {
+  const href = cell.match(PLAN_LINK)?.[2]
+  return href === undefined ? [] : [posix.normalize(posix.join(boardDirectory, href.split('#')[0]))]
+}
+
+/** Every lane the lanes table names, in table order. */
+export const laneNamesOf = (markdown: string, language: BoardLanguage): string[] => [
+  ...new Set(laneRows(markdown, language).map(({ lane }) => lane)),
+]
+
+/** The rows of `lane` in the board's lanes table; undefined when the table has no row for it. */
+export const lanePlansOf = (
+  markdown: string,
+  boardDirectory: string,
+  lane: string,
+  language: BoardLanguage,
+): LanePlans | undefined => {
+  const rows = laneRows(markdown, language).filter((row) => row.lane === lane)
+  if (rows.length === 0) return undefined
+  return {
+    closed: rows.some(({ cells }) => (cells[0] ?? '').includes(BOARD_WORDS[language].laneClosed)),
+    plans: [...new Set(rows.flatMap(({ cells }) => planPathOf(boardDirectory, cells[PLAN_COLUMN] ?? '')))],
+  }
+}

package/kit/hooks/hooks/shared/command-text-runners.ts

@@ -0,0 +1,71 @@
+import { isProgramPosition, programName } from './program-position'
+import type { SimpleCommand, Word } from './shell'
+
+/** Programs that run text they are given or read from elsewhere, so no parse of the shell sees what runs. */
+const OPAQUE_RUNNERS = new Set([
+  'xargs',
+  'find',
+  'trap',
+  'coproc',
+  'repeat',
+  'script',
+  'su',
+  'flock',
+  'ssh',
+  'parallel',
+  'ionice',
+  'chrt',
+  'taskset',
+  'strace',
+  'unbuffer',
+  'chroot',
+  'runuser',
+  'systemd-run',
+  'nsenter',
+  'unshare',
+  'firejail',
+  'pkexec',
+  'entr',
+  'watchexec',
+  'busybox',
+  'watch',
+  'osascript',
+])
+
+/** Package runners whose `-c`/`--call` hands a command string to a shell: `npx -c`, `npm exec -c`, `pnpm dlx -c`. */
+const PACKAGE_RUNNERS = new Set(['npx', 'npm', 'pnpm', 'yarn'])
+const CALL_OPTION = /^(-c|--call)(=|$)/
+const AWK_PROGRAMS = new Set(['awk', 'gawk', 'mawk', 'nawk'])
+/** An awk program that starts a command: `system(…)`, a pipe into or out of `getline`, `print … | "cmd"`. */
+const AWK_RUNS_COMMAND = /\bsystem\s*\(|\|\s*getline|\|&|print[^;}]*\|/
+/** sed's `e` command, alone or after an address: `1e cmd`, `/x/e cmd`, `;e`. */
+const SED_EXECUTE_COMMAND = /(^|[\s;{}!=\d$/])e(\s|;|$)/
+/** sed's `s///e` flag, which runs the pattern space as a command. */
+const SED_EXECUTE_FLAG = /^\s*s(.)(?:\\.|(?!\1).)*\1(?:\\.|(?!\1).)*\1[^;\s}]*e/
+
+const sedRunsCommand = (rest: Word[]): boolean =>
+  rest.some(
+    ({ value }) => SED_EXECUTE_COMMAND.test(value) || value.split(/[;\n]/).some((piece) => SED_EXECUTE_FLAG.test(piece)),
+  )
+
+const runsCommandText = (name: string, rest: Word[]): boolean =>
+  OPAQUE_RUNNERS.has(name) ||
+  (PACKAGE_RUNNERS.has(name) && rest.some(({ value }) => CALL_OPTION.test(value))) ||
+  (name === 'sed' && sedRunsCommand(rest)) ||
+  (AWK_PROGRAMS.has(name) && rest.some(({ value }) => AWK_RUNS_COMMAND.test(value)))
+
+/**
+ * The index of a program that runs command text it is given (`watch '…'`, `script -qc '…'`, `npx -c '…'`, sed's `e`,
+ * awk's `system()`), anywhere a program can stand; -1 when there is none.
+ */
+export const commandTextRunnerIndex = (words: SimpleCommand): number =>
+  words.findIndex(
+    (word, index) => isProgramPosition(words, index) && runsCommandText(programName(word), words.slice(index + 1)),
+  )
+
+/**
+ * The text a mention search reads: the script as written and, beside it, every word as the shell decodes it, so a word
+ * split by quotes (`pu""sh`) or written in `$'…'` escapes (`pu\x73h`) is found too.
+ */
+export const searchableText = (script: string, commands: SimpleCommand[]): string =>
+  [script, ...commands.map((words) => words.map(({ value }) => value).join(' '))].join('\n')

package/kit/hooks/hooks/shared/command.ts

@@ -1,6 +1,18 @@
-/** The trimmed stdout of a command run without a shell; throws when it fails, so the caller gives up. */
+/** Long enough for a local `git` or `herdr` answer, well below the deadline of the hook that waits for it. */
+export const COMMAND_TIMEOUT_MS = 3000
+
+/**
+ * The trimmed stdout of a command run without a shell; throws when it fails or outlives `COMMAND_TIMEOUT_MS`, so the
+ * caller gives up. A command past the limit is killed with SIGKILL, which it cannot ignore.
+ */
 export const commandOutput = (command: string[], cwd?: string): string => {
-  const result = Bun.spawnSync(command, { cwd, stdout: 'pipe', stderr: 'ignore' })
+  const result = Bun.spawnSync(command, {
+    cwd,
+    stdout: 'pipe',
+    stderr: 'ignore',
+    timeout: COMMAND_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+  })
   if (result.exitCode !== 0) throw new Error(`${command[0]} failed`)
   return result.stdout.toString().trim()
 }

package/kit/hooks/hooks/shared/commit.ts

@@ -0,0 +1,2 @@
+/** A full commit id as git and GitHub write it: 40 hex digits for SHA-1, 64 for SHA-256. */
+export const FULL_COMMIT = /^[0-9a-f]{40}$|^[0-9a-f]{64}$/

package/kit/hooks/hooks/shared/dialog-answers.ts

@@ -3,6 +3,9 @@ import { isRecord, type JsonObject } from './json'
 
 export type { DialogAnswer } from './dialog-answer'
 
+/** The tool name of the dialog, as hook inputs and transcripts carry it. */
+export const ASK_USER_QUESTION_TOOL = 'AskUserQuestion'
+
 /**
  * The answers of the user's dialogs, read from a session transcript. The transcript is written by the agent's own
  * client, not by the agent: a dialog answer sits in it as the result of an `AskUserQuestion` call, with the question the
@@ -49,7 +52,7 @@ const askedQuestions = (entries: JsonObject[]): Map<string, AskedQuestion[]> =>
     entries
       .filter(isMainThread)
       .flatMap(contentOf)
-      .filter((block) => block.type === 'tool_use' && block.name === 'AskUserQuestion' && typeof block.id === 'string')
+      .filter((block) => block.type === 'tool_use' && block.name === ASK_USER_QUESTION_TOOL && typeof block.id === 'string')
       .map((block): [string, AskedQuestion[]] => [block.id as string, questionsOf(block.input)]),
   )
 

package/kit/hooks/hooks/shared/json.ts

@@ -2,3 +2,13 @@ export type JsonObject = Record<string, unknown>
 
 export const isRecord = (value: unknown): value is JsonObject =>
   typeof value === 'object' && value !== null && !Array.isArray(value)
+
+/** The JSON text as an object; undefined for text that is no JSON or no object (an array included). */
+export const parseJsonObject = (text: string): JsonObject | undefined => {
+  try {
+    const value: unknown = JSON.parse(text)
+    return isRecord(value) ? value : undefined
+  } catch {
+    return undefined
+  }
+}

package/kit/hooks/hooks/shared/lane.ts

@@ -0,0 +1,57 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+import type { PaneAgent } from './pane-agent'
+
+/** herdr's agent names; a worktree whose directory has another name cannot be a lane. */
+const LANE_NAME = /^[a-z][a-z0-9_-]{0,31}$/
+
+export type LaneLocation = { cwd: string; main: string; worktreeDirectory: string }
+
+export type AgentLocation = {
+  /** The agent herdr runs in the pane the hook was called from. */
+  agent: PaneAgent
+  /** The session the hook was called for. */
+  session: string
+  main: string
+  worktreeDirectory: string
+}
+
+/** The session that merges, against the agent herdr runs in its pane. */
+export type MergingSession = {
+  /** The agent of the pane the hook runs in; null outside herdr. */
+  agent: PaneAgent | null
+  /** The `session_id` of the hook input. */
+  session: unknown
+  main: string
+  /** Whether a herdr name is a lane's, whose worktree exists. */
+  isLane: (name: string) => boolean
+}
+
+/** The lane whose worktree holds `cwd`: the first directory below the main checkout's worktree directory, else null. */
+export const laneOf = ({ cwd, main, worktreeDirectory }: LaneLocation): string | null => {
+  const path = relative(resolve(main, worktreeDirectory), resolve(cwd))
+  if (path === '' || path.startsWith('..') || isAbsolute(path)) return null
+  const [lane] = path.split(sep)
+  return LANE_NAME.test(lane) ? lane : null
+}
+
+/**
+ * The lane the agent of this pane is: an agent named after a worktree that it runs in, in the session the hook was
+ * called for. The shell's directory has no say: the coordinator's shell may stand in a lane's worktree.
+ */
+export const laneOfAgent = ({ agent, session, main, worktreeDirectory }: AgentLocation): string | null => {
+  if (agent.name === null || agent.cwd === null || agent.session === null || agent.session !== session) return null
+  return laneOf({ cwd: agent.cwd, main, worktreeDirectory }) === agent.name ? agent.name : null
+}
+
+/**
+ * Whether the session that merges is the coordinator: the agent of its pane, in this very session, started in the main
+ * checkout and not under a lane's name. A lane's transcript may lie beside the coordinator's when it was started in the
+ * main checkout; its name still tells it apart, so the plan approval never covers a lane's own merge.
+ */
+export const isCoordinatorAgent = ({ agent, session, main, isLane }: MergingSession): boolean =>
+  agent !== null &&
+  agent.session !== null &&
+  agent.session === session &&
+  agent.cwd !== null &&
+  resolve(agent.cwd) === resolve(main) &&
+  (agent.name === null || !isLane(agent.name))

package/kit/hooks/hooks/shared/once.ts

@@ -0,0 +1,8 @@
+/** The value of `compute`, computed at the first call and kept for every later one, undefined and throws aside. */
+export const once = <T>(compute: () => T): (() => T) => {
+  let kept: { value: T } | undefined
+  return () => {
+    kept ??= { value: compute() }
+    return kept.value
+  }
+}

package/kit/hooks/hooks/shared/own-pane.ts

@@ -0,0 +1,31 @@
+import { type PaneAgent, paneAgentOf } from './pane-agent'
+
+/** herdr's pane ids (`w2V:p1`); anything else never reaches the command line. */
+const PANE_ID = /^[A-Za-z0-9][A-Za-z0-9:_-]{0,63}$/
+/** Well below the deadlines of the hooks that ask, which still have work to do after it. */
+const HERDR_TIMEOUT_MS = 2000
+
+/**
+ * The agent herdr runs in the pane this process was started in; null outside herdr and whenever herdr cannot be asked.
+ *
+ * Only the pane is fixed: herdr sets `HERDR_PANE_ID` in the client's environment, and no command the agent runs can
+ * change it there. herdr's answer about that pane is not: the agent's name and session are reported to herdr, and any
+ * process may report them. Only `cwd` herdr reads from the process itself. A caller trusts a name or a session only
+ * where a second fact binds it, such as the session of the hook input or a worktree of that name.
+ */
+export const ownPaneAgent = (env: Record<string, string | undefined> = process.env): PaneAgent | null => {
+  const paneId = env.HERDR_PANE_ID
+  if (paneId === undefined || !PANE_ID.test(paneId)) return null
+  try {
+    const result = Bun.spawnSync(['herdr', 'agent', 'get', paneId], {
+      stdin: 'ignore',
+      stdout: 'pipe',
+      stderr: 'ignore',
+      timeout: HERDR_TIMEOUT_MS,
+      env,
+    })
+    return result.exitCode === 0 ? paneAgentOf(JSON.parse(result.stdout.toString())) : null
+  } catch {
+    return null
+  }
+}

package/kit/hooks/hooks/shared/pane-agent.ts

@@ -0,0 +1,24 @@
+import { isRecord, type JsonObject } from './json'
+
+/** The agent herdr runs in a pane: its herdr name, the directory it started in and its client session, each null when unknown. */
+export type PaneAgent = { name: string | null; cwd: string | null; session: string | null }
+
+/** A client's session id as a UUID; nothing else may reach a path. */
+const SESSION_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i
+
+/** The client session of an agent or a pane herdr reports; null for a shell, or a session id of another shape. */
+export const sessionOf = (pane: JsonObject): string | null => {
+  const session = isRecord(pane.agent_session) ? pane.agent_session.value : undefined
+  return typeof pane.agent === 'string' && pane.agent !== '' && typeof session === 'string' && SESSION_ID.test(session)
+    ? session
+    : null
+}
+
+const textOrNull = (value: unknown): string | null => (typeof value === 'string' && value !== '' ? value : null)
+
+/** The agent of the answer of `herdr agent get <pane>`; null for an error or an answer of another shape. */
+export const paneAgentOf = (answer: unknown): PaneAgent | null => {
+  const agent = isRecord(answer) && isRecord(answer.result) ? answer.result.agent : undefined
+  if (!isRecord(agent)) return null
+  return { name: textOrNull(agent.name), cwd: textOrNull(agent.cwd), session: sessionOf(agent) }
+}

package/kit/hooks/hooks/shared/plan-open-phases.ts

@@ -0,0 +1,114 @@
+/**
+ * Whether a plan still has an open phase, read the way the herd reads phases (`parsePlanPhases` in the package),
+ * which a hook cannot import. A test compares both on the repository's real plans.
+ */
+
+/** A task of a phase, a checkbox or a row with a ⬜/✅ cell: whether it is open, and its text without the state. */
+export type PlanTask = { open: boolean; text: string }
+
+type Phase = { id: string; items: boolean[]; deferredOpen: boolean; pointer?: string }
+
+/** A phase's id, its heading without the leading hashes, and its lines up to the next heading that ends it. */
+export type PhaseBlock = { id: string; heading: string; lines: string[] }
+
+const PHASE_HEADING = /^###\s+Phase\s+(\d+[a-z]?)\b/i
+/** `## 10 — title`, and `## P15 — title` as a board names the phase. */
+const NUMBERED_SECTION = /^##\s+P?(\d+[a-z]?)\s*[—–:-]\s*(.*)$/
+const PHASE_END = /^#{1,3}\s/
+const SECTION_HEADING = /^##\s+(.+?)\s*$/
+const TOP_HEADING = /^#\s/
+const CHECKBOX = /^\s*[-*]\s+\[([ xX])\]\s+(.*)$/
+const DEFERRED_TO = /\s→\s*P(\d+[a-z]?)\s*$/i
+const SECTION_POINTER = /`##\s+([^`]+?)\s*`/
+const STATUS = { done: '✅', open: '⬜' } as const
+
+const collapsed = (text: string): string => text.trim().replace(/\s+/g, ' ')
+
+/** The task a line holds, null for a line that is none. */
+export const taskOf = (line: string): PlanTask | null => {
+  const checkbox = line.match(CHECKBOX)
+  if (checkbox) return { open: checkbox[1] === ' ', text: collapsed(checkbox[2]) }
+  const trimmed = line.trim()
+  if (!trimmed.startsWith('|')) return null
+  const cells = trimmed.replace(/^\|/, '').replace(/\|$/, '').split('|').map((cell) => cell.trim())
+  const status = cells.find((cell) => cell === STATUS.done || cell === STATUS.open)
+  if (status === undefined) return null
+  const text = cells.filter((cell) => cell !== STATUS.done && cell !== STATUS.open).join(' | ')
+  return { open: status === STATUS.open, text: collapsed(text) }
+}
+
+/** An item of a phase: `true` while open, `false` when done, null for a line that is none. */
+const itemOf = (line: string): boolean | null => taskOf(line)?.open ?? null
+
+/** An open checkbox moved on to another phase with `→ P<n>` at its end; it stays open, in that phase. */
+const isDeferred = (line: string, phaseId: string): boolean => {
+  const checkbox = line.match(CHECKBOX)
+  const target = checkbox?.[1] === ' ' ? checkbox[2].match(DEFERRED_TO)?.[1]?.toLowerCase() : undefined
+  return target !== undefined && target !== phaseId
+}
+
+const phaseIdOf = (line: string): string | undefined =>
+  (line.match(PHASE_HEADING) ?? line.match(NUMBERED_SECTION))?.[1]?.toLowerCase()
+
+const fileLine = (phase: Phase, line: string): void => {
+  phase.pointer ??= line.match(SECTION_POINTER)?.[1]
+  if (isDeferred(line, phase.id)) {
+    phase.deferredOpen = true
+    return
+  }
+  const item = itemOf(line)
+  if (item !== null) phase.items.push(item)
+}
+
+/** The phases of a plan as they stand, `### Phase <id>` and `## <id> — title` alike. */
+export const phaseBlocksOf = (markdown: string): PhaseBlock[] => {
+  const blocks: PhaseBlock[] = []
+  let open: PhaseBlock | null = null
+  for (const line of markdown.split('\n')) {
+    const id = phaseIdOf(line)
+    if (id !== undefined) {
+      open = { id, heading: collapsed(line.replace(/^#+/, '')), lines: [] }
+      blocks.push(open)
+    } else if (PHASE_END.test(line)) open = null
+    else open?.lines.push(line)
+  }
+  return blocks
+}
+
+const phasesOf = (markdown: string): Phase[] =>
+  phaseBlocksOf(markdown).map(({ id, lines }) => {
+    const phase: Phase = { id, items: [], deferredOpen: false }
+    for (const line of lines) fileLine(phase, line)
+    return phase
+  })
+
+/** The items of every `## ` section by heading, sub-headings included; the last of equal headings wins. */
+const sectionItems = (markdown: string): Map<string, boolean[]> => {
+  const sections = new Map<string, boolean[]>()
+  let open: boolean[] | null = null
+  for (const line of markdown.split('\n')) {
+    const heading = line.match(SECTION_HEADING)
+    if (heading) {
+      open = []
+      sections.set(heading[1], open)
+    } else if (TOP_HEADING.test(line)) open = null
+    else {
+      const item = itemOf(line)
+      if (item !== null) open?.push(item)
+    }
+  }
+  return sections
+}
+
+/**
+ * True when a phase (`### Phase <id>` or `## <id> — title`) holds an open checkbox or ⬜ row, a deferred one included;
+ * a phase without items of its own counts the section it points at (``Siehe `## Dokumentation` ``).
+ */
+export const hasOpenPhase = (markdown: string): boolean => {
+  const phases = phasesOf(markdown)
+  if (phases.some((phase) => phase.deferredOpen || phase.items.includes(true))) return true
+  const pointed = phases.filter((phase) => phase.items.length === 0 && phase.pointer !== undefined)
+  if (pointed.length === 0) return false
+  const sections = sectionItems(markdown)
+  return pointed.some((phase) => (sections.get(phase.pointer ?? '') ?? []).includes(true))
+}