jackherd 1.8.1 → 1.10.0

package/kit/hooks/hooks/merge-guard/decision.ts

@@ -1,13 +1,5 @@
-import { commandTextRunnerIndex, searchableText } from '../shared/command-text-runners'
 import { FULL_COMMIT } from '../shared/commit'
-import {
-  inlineScript,
-  isOption,
-  isProgramPosition,
-  isShell,
-  programName,
-  runsInterpreterProgram,
-} from '../shared/program-position'
+import { inlineScript, isOption, isProgramPosition, programName } from '../shared/program-position'
 import {
   expandingHereDocumentAdvice,
   isExpanded,
@@ -18,15 +10,13 @@ import {
   type Word,
 } from '../shared/shell'
 import {
-  definesShellAlias,
-  mayRunDefinedFunction,
   NO_DEFINITIONS,
   type ShellDefinitionHit,
   type ShellDefinitions,
   shellDefinitionAt,
   shellDefinitionHint,
 } from '../shared/shell-aliases'
-import { resolvePlainXargs } from './xargs-program'
+import { GLOB, resolvePlainXargs, XARGS } from '../shared/xargs-program'
 
 export type MergeGuardDecision = { kind: 'pass' } | { kind: 'ask'; reason: string }
 
@@ -43,8 +33,8 @@ export type GuardPolicy = {
   /** The guarded commands as words: a program and the plain words after it, such as `gh pr merge`. */
   commands: readonly string[]
   /**
-   * Whether the merge of this pull request may pass without a question: the user approved its branch or the plan of
-   * its lane, or every file of it matches `merge.withoutChecks`. Asked only for a plain `gh pr merge <number>`.
+   * Whether the merge of this pull request may pass without a question: the user approved its branch, a standing
+   * approval covers the plan of its lane, or every file of it matches `merge.withoutChecks`. Asked only for a plain `gh pr merge <number>`.
    * A throw counts as not approved; a note is not approved either, and the question carries it.
    */
   isMergeApproved: (merge: PlainMerge) => boolean | MergeNote
@@ -54,10 +44,9 @@ export type GuardPolicy = {
 
 /**
  * A guarded command the script runs or could run, and the pull request a merge names, when it names one plainly; or
- * the shell alias or function that may run one (`definition`, whose name is then the `command`), or a program whose
- * name is unknown (`note` says why it may run one).
+ * the shell alias or function that may run one (`definition`, whose name is then the `command`).
  */
-type Finding = { command: string; merge: PlainMerge | undefined; definition?: ShellDefinitionHit; note?: string }
+type Finding = { command: string; merge: PlainMerge | undefined; definition?: ShellDefinitionHit }
 
 /** What the search looks for: the guarded commands, and the shell definitions that may stand for one of them. */
 type Search = { commands: readonly string[]; definitions: () => ShellDefinitions }
@@ -78,11 +67,21 @@ const OPTIONS_WITH_VALUE = new Set(['-R', '--repo', '--hostname'])
 const APPROVABLE_FLAGS = new Set(['--squash', '-s', '--merge', '-m', '--rebase', '-r', '--delete-branch', '-d'])
 const PULL_REQUEST_NUMBER = /^[1-9]\d*$/
 const HEAD_COMMIT_FLAG = '--match-head-commit'
-const GLOB = /[*?[]/
-
-const SOURCING = new Set(['source', '.'])
 
-const INPUT_PATH = /^(\/dev\/stdin|\/dev\/fd\/|\/proc\/self\/fd\/)/
+/** The option that prints a command's help and runs nothing; gh also takes `-h`, another tool may read it as a host. */
+const HELP_OPTION = '--help'
+const GH_SHORT_HELP = '-h'
+/** The gh verbs that only read: `gh <noun> view`, `gh <noun> list`. */
+const READING_VERBS = new Set(['view', 'list'])
+const GH = 'gh'
+/** What `xargs` appends to the program it runs: words from its input, which the guard cannot know. */
+const XARGS_INPUT: Word = { value: '$xargs-input', literal: false }
+/**
+ * Where a command may start in text the parse could not read: an operator, a bracket, a quote, a backtick, a line
+ * break. Cut there, a word at a program position of a piece may be one.
+ */
+const COMMAND_BOUNDARY = /[;&|()`'"{}\n]/
+const BLANKS = /\s+/
 
 /** `gh api` is guarded only for a write that merges, writes a file, starts or reruns a workflow or moves a ref (D43); every other call passes. */
 const API_COMMAND = 'gh api'
@@ -126,9 +125,6 @@ const DANGEROUS_ENDINGS = [
   /(^|\/)(rerun|rerun-failed-jobs)\/?$/,
   /(^|\/)refs(\/|$)/,
 ]
-const DANGEROUS_MENTION = /\b(merges?|contents|dispatches|rerun|refs)\b/
-const EXPANDED_FUNCTION_NOTE =
-  'The program is expanded from a variable or a substitution and may name a shell function that runs one of guard.commands in .jackherd/config.json, so the user confirms it.'
 
 const PASS: MergeGuardDecision = { kind: 'pass' }
 
@@ -272,23 +268,59 @@ const apiArguments = (words: SimpleCommand, index: number): Word[] => {
   return at === -1 ? after : after.slice(at + 1)
 }
 
-/** Every guarded command counts wherever it is found, except a `gh api` call that does not write dangerously. */
+/** Every guarded command at a program position counts, except a `gh api` call that does not write dangerously. */
 const isGuardedUse = (command: string, words: SimpleCommand, programIndex: number): boolean =>
   command !== API_COMMAND || writesDangerously(apiArguments(words, programIndex))
 
-/** In text the parse cannot see, `api` followed by the end of a dangerous endpoint is the sign; the method is unknown. */
-const mentionsDangerousApiCall = (script: string): boolean => {
-  const at = findWord(script, API_WORD, 0)
-  return at !== -1 && DANGEROUS_MENTION.test(script.slice(at))
+const commandWords = (command: string): string[] => command.split(' ').slice(1)
+
+/** `gh <noun> view` or `gh <noun> list`, written plainly: it only reads. */
+const isGhRead = (words: SimpleCommand, index: number): boolean => {
+  const [noun, verb] = words.slice(index + 1, index + 3)
+  const plainNoun = noun?.literal === true && !isOption(noun)
+  return programName(words[index]) === GH && plainNoun && verb?.literal === true && READING_VERBS.has(verb.value)
+}
+
+const isHelpOption = (program: Word, { value }: Word): boolean =>
+  value === HELP_OPTION || (value === GH_SHORT_HELP && programName(program) === GH)
+
+/** The command's own words, written plainly, then `--help` (or gh's `-h`): it prints the help and runs nothing. */
+const isHelpOf = (words: SimpleCommand, index: number, command: string): boolean => {
+  const expected = commandWords(command)
+  const after = words.slice(index + 1, index + 2 + expected.length)
+  const help = after[expected.length]
+  return (
+    after.every((word) => word.literal) &&
+    expected.every((value, at) => after[at]?.value === value) &&
+    help !== undefined &&
+    isHelpOption(words[index], help)
+  )
+}
+
+/** A call of the program at `index` that only reads: a help text or a gh view or list (D108). */
+const isReading = (words: SimpleCommand, index: number, command: string): boolean =>
+  isGhRead(words, index) || isHelpOf(words, index, command)
+
+/** An `xargs` before the program hands it words from its input: they may be any of the command words. */
+const isFedByXargs = (words: SimpleCommand, index: number): boolean =>
+  words.slice(0, index).some((word, at) => programName(word) === XARGS && isProgramPosition(words, at))
+
+/** The words after the program at `index`, with a stand-in for what `xargs` appends. */
+const argumentsOf = (words: SimpleCommand, index: number): Word[] => {
+  const after = words.slice(index + 1)
+  return isFedByXargs(words, index) ? [...after, XARGS_INPUT] : after
 }
 
+/** Whether the words after the program at `index` can be the command's own words. */
+const namesCommandWords = (words: SimpleCommand, index: number, command: string): boolean =>
+  operandLists(argumentsOf(words, index)).some((operands) => matchesFrom(operands, commandWords(command)))
+
 /** `sole`: the script is this one simple command, written plainly, the only shape an approval can lift. */
 const findingOf = (command: string, words: SimpleCommand, index: number, sole: boolean): Finding | undefined => {
-  const expected = command.split(' ').slice(1)
-  if (!operandLists(words.slice(index + 1)).some((operands) => matchesFrom(operands, expected))) return undefined
+  if (!namesCommandWords(words, index, command) || isReading(words, index, command)) return undefined
   if (!isGuardedUse(command, words, index)) return undefined
-  const plain = sole && words[index].literal && words[index].value === 'gh'
-  return { command, merge: plain ? plainMerge(words.slice(index), expected) : undefined }
+  const plain = sole && words[index].literal && words[index].value === GH
+  return { command, merge: plain ? plainMerge(words.slice(index), commandWords(command)) : undefined }
 }
 
 const programsOf = (commands: readonly string[]): string[] => [
@@ -301,90 +333,37 @@ const definitionFinding = (words: SimpleCommand, index: number, { commands, defi
   return definition ? [{ command: definition.name, merge: undefined, definition }] : []
 }
 
-const expandedFunctionFinding = (words: SimpleCommand, { commands, definitions }: Search, text: string): Finding[] =>
-  mayRunDefinedFunction(words, definitions, programsOf(commands), text)
-    ? [{ command: '', merge: undefined, note: EXPANDED_FUNCTION_NOTE }]
-    : []
+/**
+ * A program from a variable, a substitution or a glob may be a guarded one: it counts when the parsed words after it
+ * can be that command's words (`"$tool" pr merge 5`). A variable that holds the whole command (`$X`) is not searched.
+ */
+const expandedProgramFindings = (words: SimpleCommand, index: number, { commands }: Search): Finding[] =>
+  commands
+    .filter((command) => namesCommandWords(words, index, command) && isGuardedUse(command, words, index))
+    .map((command) => ({ command, merge: undefined }))
+
+/** A program word from an expansion or a glob; a quoted word (`'gh pr merge'`, a script text) is the name it spells. */
+const isExpandedProgram = ({ value, literal }: Word): boolean => isExpanded(value) || (literal && GLOB.test(value))
 
 const callsOfWord = (words: SimpleCommand, index: number, search: Search, sole: boolean): Finding[] => {
   if (!isProgramPosition(words, index)) return []
+  if (isExpandedProgram(words[index])) return expandedProgramFindings(words, index, search)
   const program = programName(words[index])
   const guarded = search.commands.filter((command) => command.split(' ')[0] === program)
   if (guarded.length === 0) return definitionFinding(words, index, search)
   return guarded.flatMap((command) => findingOf(command, words, index, sole && index === 0) ?? [])
 }
 
-const isWordCharacter = (character: string | undefined): boolean => character !== undefined && /\w/.test(character)
-
-const findWord = (script: string, word: string, from: number): number => {
-  for (let at = script.indexOf(word, from); at !== -1; at = script.indexOf(word, at + 1)) {
-    if (!isWordCharacter(script[at - 1]) && !isWordCharacter(script[at + word.length])) return at
-  }
-  return -1
-}
-
-/** Whether the script names the words as whole words in this order; a linear search, so a long script cannot stall it. */
-const namesInOrder = (script: string, words: string[]): boolean => {
-  let from = 0
-  for (const word of words) {
-    const at = findWord(script, word, from)
-    if (at === -1) return false
-    from = at + word.length
-  }
-  return true
-}
-
-/** Where the program is hidden or the words are handed over as text, the command words after the program are the sign. */
-const mentionedCommandWords = (script: string, commands: readonly string[]): Finding[] =>
-  commands
-    .filter((command) =>
-      command === API_COMMAND ? mentionsDangerousApiCall(script) : namesInOrder(script, command.split(' ').slice(1)),
-    )
-    .map((command) => ({ command, merge: undefined }))
-
-/** A program expanded from a variable or a substitution could be the guarded one. */
-const runsExpandedProgram = (words: SimpleCommand): boolean =>
-  words.some((word, index) => !word.literal && isProgramPosition(words, index))
-
-const runsOpaquely = (words: SimpleCommand): boolean => commandTextRunnerIndex(words) !== -1
-
-/**
- * A shell, anywhere a program can stand, that reads its script from stdin (no operand, or `-s`), from a process
- * substitution or from a file descriptor; or `source` of such a thing: the text comes from somewhere else.
- */
-const readsScriptFromElsewhere = (words: SimpleCommand): boolean =>
-  words.some((word, index) => {
-    if (!isProgramPosition(words, index)) return false
-    const shell = isShell(word)
-    if (!shell && !SOURCING.has(programName(word))) return false
-    const rest = words.slice(index + 1)
-    const operands = rest.filter((each) => !isOption(each))
-    const fromInput = shell && (operands.length === 0 || rest.some(({ value }) => value === '-s'))
-    return fromInput || operands.some((each) => !each.literal || INPUT_PATH.test(each.value))
-  })
-
-/** Git handed an alias (`git -c alias.m=!…`) runs text the parse cannot see. */
-const definesGitAlias = (words: SimpleCommand): boolean =>
-  words.some(
-    (word, index) =>
-      isProgramPosition(words, index) &&
-      programName(word) === 'git' &&
-      words.slice(index + 1).some(({ value }) => value.startsWith('alias.')),
-  )
-
-/** An inline script that is itself an expansion (`eval "$X"`) hides its text from the parse of the call. */
-const runsInlineExpansion = (words: SimpleCommand): boolean =>
-  words.some((_word, index) => inlineScript(words, index)?.includes('$') === true)
-
 /**
  * Whether the command's words contain the guarded command's words in this order, anything between them: the
  * fallback for a wrapper nobody listed (`mise exec -- gh pr merge 5`), which hides the program from the position test.
+ * It reads the parsed words of the command, never text inside them.
  */
 const containsInOrder = (words: SimpleCommand, command: string): boolean => {
   const [program, ...rest] = command.split(' ')
   const at = words.findIndex((word) => programName(word) === program)
   let from = at + 1
-  if (at === -1) return false
+  if (at === -1 || isReading(words, at, command)) return false
   for (const expected of rest) {
     const next = words.findIndex((word, index) => index >= from && word.literal && word.value === expected)
     if (next === -1) return false
@@ -393,45 +372,28 @@ const containsInOrder = (words: SimpleCommand, command: string): boolean => {
   return isGuardedUse(command, words, at)
 }
 
-/** `text` is the searchable text of the script around the command: a variable there may hold a function's name. */
-const callsInCommand = (words: SimpleCommand, search: Search, sole: boolean, whole: string, text: string): Finding[] => {
+const callsInCommand = (words: SimpleCommand, search: Search, sole: boolean): Finding[] => {
   const direct = words.flatMap((_word, index) => {
     const script = inlineScript(words, index)
-    return script === undefined ? callsOfWord(words, index, search, sole) : callsIn(script, search, false, whole)
+    return script === undefined ? callsOfWord(words, index, search, sole) : callsIn(script, search, false)
   })
   const found = new Set(direct.map(({ command }) => command))
   const byWords = search.commands
     .filter((command) => !found.has(command) && containsInOrder(words, command))
     .map((command) => ({ command, merge: undefined }))
-  return [...direct, ...byWords, ...expandedFunctionFinding(words, search, text)]
+  return [...direct, ...byWords]
 }
 
 /**
- * Each check reads the whole script: a shell that reads stdin, an expanded program, an opaque runner or an interpreter
- * handed program text hides what runs.
+ * The guarded commands in the parsed script: in a program position, in the script of `sh -c`, `eval` or `trap`, in a
+ * substitution. Text the script hands to an interpreter, a shell's input, a here-document's data and the words
+ * `xargs` reads are not searched (D108).
  */
-const hidesWhatRuns = (words: SimpleCommand): boolean =>
-  runsExpandedProgram(words) ||
-  runsOpaquely(words) ||
-  readsScriptFromElsewhere(words) ||
-  runsInlineExpansion(words) ||
-  runsInterpreterProgram(words) ||
-  definesGitAlias(words) ||
-  definesShellAlias(words)
-
-const callsInScriptWide = (whole: string, parsed: SimpleCommand[], commands: readonly string[]): Finding[] =>
-  parsed.some(hidesWhatRuns) ? mentionedCommandWords(searchableText(whole, parsed), commands) : []
-
-/** `whole` is the text of the outermost script: a nested script's input comes from there, so the words are searched in it. */
-const callsIn = (script: string, search: Search, top: boolean, whole: string): Finding[] => {
+const callsIn = (script: string, search: Search, top: boolean): Finding[] => {
   const guardedPrograms = programsOf(search.commands)
   const parsed = parseShell(script).map((words) => resolvePlainXargs(words, guardedPrograms))
   const sole = top && parsed.length === 1 && !script.trimStart().startsWith('(')
-  const text = searchableText(whole, parsed)
-  return [
-    ...parsed.flatMap((words) => callsInCommand(words, search, sole, whole, text)),
-    ...callsInScriptWide(whole, parsed, search.commands),
-  ]
+  return parsed.flatMap((words) => callsInCommand(words, search, sole))
 }
 
 const approvalOf = ({ command, merge }: Finding, policy: GuardPolicy): boolean | MergeNote => {
@@ -451,9 +413,7 @@ const guardedListSentence = (commands: string[]): string[] =>
       ]
 
 const askBecause = (findings: Finding[], notes: string[], script: string): MergeGuardDecision => {
-  const guarded = findings
-    .filter(({ definition, note }) => definition === undefined && note === undefined)
-    .map(({ command }) => command)
+  const guarded = findings.filter(({ definition }) => definition === undefined).map(({ command }) => command)
   const definitions = [
     ...new Map(
       findings.flatMap(({ definition }) => (definition ? [[definition.name, definition] as const] : [])),
@@ -467,7 +427,6 @@ const askBecause = (findings: Finding[], notes: string[], script: string): Merge
         (definition) =>
           `${shellDefinitionHint(definition)} It may run a command of guard.commands in .jackherd/config.json, so the user confirms it.`,
       ),
-      ...new Set(findings.flatMap(({ note }) => note ?? [])),
       ...notes,
       expandingHereDocumentAdvice(script),
     ]
@@ -476,9 +435,34 @@ const askBecause = (findings: Finding[], notes: string[], script: string): Merge
   }
 }
 
+/** A word of text the parse could not read: one with an expansion or a backslash may stand for any word. */
+const roughWord = (value: string): Word => ({ value, literal: !/[$\\]/.test(value) })
+
+/**
+ * Whether text the parse could not read has a guarded program at a program position: the text is cut where a command
+ * may start (an operator, a bracket, a quote, a backtick, a line break), and a piece whose word at a program position
+ * is a guarded program counts, unless that call only reads. A split program word (`g''h`) is not found, accepted
+ * (D108): the guard catches mistakes, not a hidden intent.
+ */
+const namesGuardedProgram = (script: string, commands: readonly string[]): boolean => {
+  const programs = programsOf(commands)
+  return script.split(COMMAND_BOUNDARY).some((piece) => {
+    const words = piece
+      .split(BLANKS)
+      .filter((value) => value !== '')
+      .map(roughWord)
+    return words.some(
+      (word, index) =>
+        isProgramPosition(words, index) &&
+        programs.includes(programName(word)) &&
+        !commands.some((command) => isReading(words, index, command)),
+    )
+  })
+}
+
 /**
- * Quotes split a word (`g''h`), a variable builds it, an expansion hides a command: in text the parse cannot follow,
- * no word search can tell whether a guarded command runs, so every unreadable script asks (fail closed).
+ * Quotes split a word, an expansion hides a command: in text the parse cannot follow, a guarded program at a program
+ * position may run with any words, so the script asks.
  */
 const askUnreadable = ({ message }: ShellParseError, script: string): MergeGuardDecision => ({
   kind: 'ask',
@@ -493,7 +477,7 @@ const askUnreadable = ({ message }: ShellParseError, script: string): MergeGuard
 
 const findingsOrUnreadable = (command: string, search: Search): Finding[] | ShellParseError => {
   try {
-    return callsIn(command, search, true, command)
+    return callsIn(command, search, true)
   } catch (error) {
     if (error instanceof ShellParseError) return error
     throw error
@@ -501,20 +485,23 @@ const findingsOrUnreadable = (command: string, search: Search): Finding[] | Shel
 }
 
 /**
- * Decides on a Bash command before it runs: `ask` when it runs, or could run, a guarded command (`gh pr merge`,
- * `gh workflow run`, `gh run rerun` and a `gh api` write to a merge, a file, a dispatch, a rerun or a ref by default), also behind options before the
- * verb, a chain, a wrapper, `sh -c`, `eval`, a script piped into a shell, an interpreter's program text, a shell alias
- * or function, or a program held in a variable. A script that is exactly `gh pr merge <number>` with merge-method and
+ * Decides on a Bash command before it runs: `ask` when a guarded command (`gh pr merge` and `gh workflow run` by
+ * default) stands at a program position of the parsed script, also behind options before the verb, a chain, a wrapper,
+ * `env`, `sh -c`, `eval`, a substitution or a shell alias or function, or behind a program from a variable whose
+ * parsed words are the command's words. Only the parsed script counts (D108): text handed to an interpreter or a
+ * shell's input, a here-document's data and what `xargs` reads are not searched, and a call that only reads (`--help`,
+ * `-h`, `gh … view`, `gh … list`) passes. A script that is exactly `gh pr merge <number>` with merge-method and
  * delete-branch flags and at most one `--match-head-commit <sha>` passes when the user approved it
- * (`isMergeApproved`); any other shape of the merge, and every other guarded command, asks. A command that merely
- * names the words (an argument, a commit message) is none. A script the parse cannot read asks whatever it names,
- * unless the list is empty.
+ * (`isMergeApproved`); any other shape of the merge, and every other guarded command, asks. A script the parse cannot
+ * read asks only when a guarded program stands where a command starts.
  */
 export const decideBashCommand = (command: string, policy: GuardPolicy): MergeGuardDecision => {
   if (policy.commands.length === 0) return PASS
   const search = { commands: policy.commands, definitions: policy.shellDefinitions ?? (() => NO_DEFINITIONS) }
   const findings = findingsOrUnreadable(command, search)
-  if (findings instanceof ShellParseError) return askUnreadable(findings, command)
+  if (findings instanceof ShellParseError) {
+    return namesGuardedProgram(command, policy.commands) ? askUnreadable(findings, command) : PASS
+  }
   if (findings.length === 0) return PASS
   const unapproved = findings
     .map((finding) => ({ finding, approval: approvalOf(finding, policy) }))

package/kit/hooks/hooks/merge-guard/index.ts

@@ -2,8 +2,8 @@
 // decision on stdout when the command runs a guarded one, or with nothing to leave the call to the
 // permission rules. Any failure asks: a guard that crashes, or takes too long, must not wave the command through.
 // The decision runs in a worker that is ended after DEADLINE_MS, because Claude Code lets a call through when a hook
-// runs into its own timeout. argv[2] and argv[3] are the exact option labels that approve a merge: the one of the pull request
-// question and the one of a plan question, rendered into the hook entry by `sync`.
+// runs into its own timeout. argv[2] is the exact option label of the pull request question that approves a merge, argv[3]
+// the one of the standing approval and argv[4] the word before its end, all rendered into the hook entry by `sync`.
 import type { MergeGuardDecision } from './decision'
 import { type ApprovalLabels, failureDecision } from './run'
 
@@ -35,7 +35,10 @@ const decide = async (): Promise<MergeGuardDecision> => {
   try {
     const text = await Bun.stdin.text()
     const projectDirectory = process.env.CLAUDE_PROJECT_DIR ?? process.cwd()
-    const labels = { selfMerge: process.argv[2] ?? '', plan: process.argv[3] ?? '' }
+    const labels = {
+      selfMerge: process.argv[2] ?? '',
+      standing: { approve: process.argv[3] ?? '', until: process.argv[4] ?? '' },
+    }
     return await decideWithin({ text, labels, projectDirectory }, DEADLINE_MS)
   } catch (error) {
     return failureDecision(error)

package/kit/hooks/hooks/merge-guard/lane-plan.ts

@@ -0,0 +1,79 @@
+/**
+ * The plan a branch belongs to: the lane whose worktree has the branch checked out, and the one plan that lane's rows
+ * link on the boards, as the main checkout holds them (the coordinator keeps its board there, committed or not). The
+ * git call runs without a shell and with a timeout; any failure answers nothing, so the guard asks.
+ */
+import { readdirSync, readFileSync } from 'node:fs'
+import { join, posix, relative, resolve } from 'node:path'
+import { type BoardLanguage, lanePlansOf } from '../shared/board-lanes'
+import { laneOf } from '../shared/lane'
+import type { BoardSettings } from './board-settings'
+
+/** A board's directory relative to the repository, and its text. */
+export type Board = { directory: string; text: string }
+
+const GIT_TIMEOUT_MS = 3000
+
+/** The lane whose worktree, directly below the worktree directory, has `branch` checked out. */
+export const laneInWorktreeList = (
+  worktreeList: string,
+  main: string,
+  worktreeDirectory: string,
+  branch: string,
+): string | undefined => {
+  const blocks = worktreeList.split('\n\n').map((block) => block.split('\n'))
+  const block = blocks.find((lines) => lines.includes(`branch refs/heads/${branch}`))
+  const path = block?.find((line) => line.startsWith('worktree '))?.slice('worktree '.length)
+  if (path === undefined) return undefined
+  const lane = laneOf({ cwd: path, main, worktreeDirectory })
+  return lane !== null && relative(resolve(main, worktreeDirectory), resolve(path)) === lane ? lane : undefined
+}
+
+/** The one plan the lane's open rows link across the boards; none for a cleaned-up lane, no plan or several. */
+export const onlyPlanOf = (boards: readonly Board[], lane: string, language: BoardLanguage): string | undefined => {
+  const rows = boards.flatMap(({ directory, text }) => lanePlansOf(text, directory, lane, language) ?? [])
+  const plans = new Set(rows.filter(({ closed }) => !closed).flatMap(({ plans }) => plans))
+  const [only] = plans
+  return plans.size === 1 ? only : undefined
+}
+
+const worktreeListOf = (main: string): string | undefined => {
+  const result = Bun.spawnSync(['git', '-C', main, 'worktree', 'list', '--porcelain'], {
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'ignore',
+    timeout: GIT_TIMEOUT_MS,
+  })
+  return result.exitCode === 0 ? result.stdout.toString() : undefined
+}
+
+const readTextOrUndefined = (path: string): string | undefined => {
+  try {
+    return readFileSync(path, 'utf8')
+  } catch {
+    return undefined
+  }
+}
+
+/** The boards under the plan directory of the main checkout whose directory name matches the board pattern. */
+const boardsIn = (main: string, settings: BoardSettings): Board[] => {
+  const pattern = new Bun.Glob(settings.board.pattern)
+  try {
+    return readdirSync(join(main, settings.planDirectory), { withFileTypes: true })
+      .filter((entry) => entry.isDirectory() && pattern.match(entry.name))
+      .flatMap((entry) => {
+        const directory = posix.join(settings.planDirectory, entry.name)
+        const text = readTextOrUndefined(join(main, directory, settings.board.file))
+        return text === undefined ? [] : [{ directory, text }]
+      })
+  } catch {
+    return []
+  }
+}
+
+/** The one plan the lane of `branch` links on the boards of the main checkout; undefined when it cannot tell. */
+export const planOfBranch = (main: string, settings: BoardSettings, branch: string): string | undefined => {
+  const list = worktreeListOf(main)
+  const lane = list === undefined ? undefined : laneInWorktreeList(list, main, settings.worktreeDirectory, branch)
+  return lane === undefined ? undefined : onlyPlanOf(boardsIn(main, settings), lane, settings.planLanguage)
+}