jackherd 1.7.0 → 1.8.0

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

@@ -0,0 +1,194 @@
+/**
+ * A plan approval outlives the session it was given in: the `PostToolUse` hook on `AskUserQuestion` leaves a pointer
+ * (plan, transcript file, `tool_use_id`) under `.jackherd/approvals/plans/`, and the merge guard follows it back into
+ * that transcript at every merge. The pointer only says where to look; what counts is the dialog it finds there, the
+ * question naming the plan and the label the user picked, so a pointer an agent writes itself gains nothing.
+ *
+ * The limit, as for the branch approval: an agent that runs as the user could still write a transcript file. This
+ * guards against a mistake, not against an agent that sets out to get around it.
+ */
+import { readdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { ASK_USER_QUESTION_TOOL, dialogAnswers } from '../shared/dialog-answers'
+import { realPathOrNull } from '../shared/files'
+import { isRecord } from '../shared/json'
+import { ensurePrivateDirectory, PRIVATE_FILE } from '../shared/private-directory'
+import type { PlanAnswer } from './plan-approval'
+
+/**
+ * `answers`: per plan, the answer the hook input reported, null where it reported none. An approval still needs its
+ * dialog in the transcript; any other answer ends the approval at `recordedAt` without one, since it only adds a question.
+ */
+export type PlanPointer = {
+  toolUseId: string
+  transcript: string
+  plans: string[]
+  answers: Record<string, string | null>
+  recordedAt: number
+}
+
+export type PlanAnswerQuery = {
+  /** The pointer directory, `.jackherd/approvals/plans` of the main checkout. */
+  directory: string
+  /** The transcript of the session that merges: only transcripts beside it, of the same project, are read. */
+  currentTranscript: string | undefined
+  plan: string
+  /** The label that approves a plan; a pointer with any other answer is a revocation. */
+  label: string
+}
+
+const PLAN_MENTION = /\bPlan `([^`]*)`/g
+const PLAN_PATH = /^[A-Za-z0-9_./-]+\.md$/
+const TOOL_USE_ID = /^[A-Za-z0-9_-]{1,128}$/
+const POINTER_FILE = /^([A-Za-z0-9_-]{1,128})\.json$/
+const TRANSCRIPT_FILE = /\.jsonl$/
+
+/** A plan path as a board links it: a relative markdown file, no empty, `.` or `..` segment. */
+const isPlanPath = (path: string): boolean =>
+  PLAN_PATH.test(path) && path.split('/').every((segment) => segment !== '' && segment !== '.' && segment !== '..')
+
+const isTranscriptPath = (value: unknown): value is string =>
+  typeof value === 'string' && isAbsolute(value) && TRANSCRIPT_FILE.test(value)
+
+const isToolUseId = (value: unknown): value is string => typeof value === 'string' && TOOL_USE_ID.test(value)
+
+/** The one plan a question names as ``Plan `path` ``; a question that names none or several names none. */
+export const namedPlan = (question: string): string | undefined => {
+  const plans = new Set([...question.matchAll(PLAN_MENTION)].map(([, path]) => path))
+  const [only] = plans
+  return plans.size === 1 && isPlanPath(only) ? only : undefined
+}
+
+type PlanAsked = { plan: string; question: string }
+
+/** The plans of the single-choice questions that name one and offer one of the plan labels, with the question text. */
+const plansAsked = (input: unknown, labels: readonly string[]): PlanAsked[] => {
+  const questions = isRecord(input) && Array.isArray(input.questions) ? input.questions.filter(isRecord) : []
+  return questions.flatMap((question) => {
+    const options = question.multiSelect !== true && Array.isArray(question.options) ? question.options : []
+    const offersLabel = options.some((option) => isRecord(option) && labels.includes(String(option.label)))
+    const text = typeof question.question === 'string' ? question.question : ''
+    const plan = namedPlan(text)
+    return offersLabel && plan !== undefined ? [{ plan, question: text }] : []
+  })
+}
+
+/** The answer the hook input reports for a question, keyed by its text; null when it reports none. */
+const reportedAnswer = (response: unknown, question: string): string | null => {
+  const answers = isRecord(response) && isRecord(response.answers) ? response.answers : {}
+  const answer = answers[question]
+  return typeof answer === 'string' ? answer : null
+}
+
+/** The pointer for a `PostToolUse` input of an `AskUserQuestion` call that asked about a plan; undefined for any other. */
+export const pointerOf = (input: unknown, labels: readonly string[], now: number): PlanPointer | undefined => {
+  if (!isRecord(input) || input.tool_name !== ASK_USER_QUESTION_TOOL) return undefined
+  const { tool_use_id: toolUseId, transcript_path: transcript } = input
+  if (!isToolUseId(toolUseId) || !isTranscriptPath(transcript)) return undefined
+  const asked = plansAsked(input.tool_input, labels.filter(Boolean))
+  if (asked.length === 0) return undefined
+  const answers = Object.fromEntries(asked.map(({ plan, question }) => [plan, reportedAnswer(input.tool_response, question)]))
+  return { toolUseId, transcript, plans: [...new Set(asked.map(({ plan }) => plan))], answers, recordedAt: now }
+}
+
+/** The lines of the file that contain `needle`: a transcript runs to hundreds of megabytes, and only these get parsed. */
+const linesContaining = (text: Buffer, needle: string): string[] => {
+  const lines: string[] = []
+  for (let at = text.indexOf(needle); at !== -1; ) {
+    const start = text.lastIndexOf('\n', at) + 1
+    const newline = text.indexOf('\n', at)
+    const end = newline === -1 ? text.length : newline
+    lines.push(text.subarray(start, end).toString('utf8'))
+    at = newline === -1 ? -1 : text.indexOf(needle, end)
+  }
+  return lines
+}
+
+const parsedLines = (lines: string[]): unknown[] =>
+  lines.flatMap((line) => {
+    try {
+      return [JSON.parse(line)]
+    } catch {
+      return []
+    }
+  })
+
+/** The answers of the dialog `toolUseId` in the transcript to questions naming `plan`, free text included. */
+const answersInTranscript = (text: Buffer, toolUseId: string, plan: string): PlanAnswer[] =>
+  dialogAnswers(parsedLines(linesContaining(text, JSON.stringify(toolUseId))))
+    .filter(({ question }) => namedPlan(question) === plan)
+    .map(({ answer, answeredAt }) => ({ answer, answeredAt }))
+
+/** A pointer whose reported answer is not the label ends the approval when it was recorded; no transcript needed. */
+const revocationOf = (pointer: PlanPointer, plan: string): PlanAnswer => ({
+  answer: pointer.answers[plan] ?? '',
+  answeredAt: pointer.recordedAt,
+})
+
+/** The pointer directory of a main checkout, beside the approval gate's requests. */
+export const planPointersDirectory = (main: string): string => join(main, '.jackherd', 'approvals', 'plans')
+
+export const writePointer = (directory: string, pointer: PlanPointer): void => {
+  ensurePrivateDirectory(directory)
+  writeFileSync(join(directory, `${pointer.toolUseId}.json`), `${JSON.stringify(pointer)}\n`, { mode: PRIVATE_FILE })
+}
+
+const pointerIn = (directory: string, name: string): PlanPointer[] => {
+  const id = POINTER_FILE.exec(name)?.[1]
+  if (id === undefined) return []
+  try {
+    const value: unknown = JSON.parse(readFileSync(join(directory, name), 'utf8'))
+    if (!isRecord(value) || value.toolUseId !== id || !isTranscriptPath(value.transcript)) return []
+    const plans = Array.isArray(value.plans) ? value.plans : []
+    const valid = plans.length > 0 && plans.every((plan) => typeof plan === 'string' && isPlanPath(plan))
+    if (!valid || typeof value.recordedAt !== 'number') return []
+    const answers = isRecord(value.answers) ? value.answers : {}
+    const reported = (plan: string) => (typeof answers[plan] === 'string' ? answers[plan] : null)
+    return [{ ...(value as PlanPointer), answers: Object.fromEntries(plans.map((plan) => [plan, reported(plan)])) }]
+  } catch {
+    return []
+  }
+}
+
+/** Every file of the directory that parses as a pointer named after its own id; none for a missing directory. */
+export const readPointers = (directory: string): PlanPointer[] => {
+  try {
+    return readdirSync(directory).flatMap((name) => pointerIn(directory, name))
+  } catch {
+    return []
+  }
+}
+
+const readOrNull = (path: string): Buffer | null => {
+  try {
+    return readFileSync(path)
+  } catch {
+    return null
+  }
+}
+
+/** The answers a pointer's transcript holds for `plan`, when that transcript lies beside the current one. */
+const backedAnswers = (pointer: PlanPointer, plan: string, project: string, texts: Map<string, Buffer | null>) => {
+  const path = realPathOrNull(pointer.transcript)
+  if (path === null || dirname(path) !== project) return []
+  if (!texts.has(path)) texts.set(path, readOrNull(path))
+  const text = texts.get(path)
+  return text ? answersInTranscript(text, pointer.toolUseId, plan) : []
+}
+
+/**
+ * The answers to the plan questions naming `plan`. A pointer that reported the approval label counts only with its
+ * dialog in a transcript beside the current one (Claude Code keeps a project's sessions side by side); a pointer that
+ * reported anything else, free text or nothing included, is a revocation and counts as it stands.
+ */
+export const planAnswers = ({ directory, currentTranscript, plan, label }: PlanAnswerQuery): PlanAnswer[] => {
+  const pointers = readPointers(directory).filter((pointer) => pointer.plans.includes(plan))
+  const revocations = pointers.filter((pointer) => pointer.answers[plan] !== label).map((pointer) => revocationOf(pointer, plan))
+  const project = currentTranscript === undefined ? null : realPathOrNull(dirname(currentTranscript))
+  if (project === null) return revocations
+  const texts = new Map<string, Buffer | null>()
+  const approvals = pointers
+    .filter((pointer) => pointer.answers[plan] === label)
+    .flatMap((pointer) => backedAnswers(pointer, plan, project, texts))
+  return [...approvals, ...revocations]
+}

package/kit/hooks/hooks/merge-guard/pull-request.ts

@@ -4,28 +4,80 @@
  * says which branch pull request <number> carries.
  */
 
+import { FULL_COMMIT } from '../shared/commit'
+import { parseJsonObject } from '../shared/json'
 import { runGh } from './gh'
 
-type PullRequestView = { headRefName?: unknown; isCrossRepository?: unknown; state?: unknown }
+type PullRequestView = {
+  headRefName?: unknown
+  headRefOid?: unknown
+  baseRefName?: unknown
+  isCrossRepository?: unknown
+  state?: unknown
+  statusCheckRollup?: unknown
+  mergeable?: unknown
+  url?: unknown
+  changedFiles?: unknown
+}
 
 /** Where a pull request lives and how many files it changes, as GitHub's `pr view` says. */
 export type RepositoryFacts = { repository: string; changedFiles: number }
 
-const VIEW_FIELDS = 'headRefName,isCrossRepository,state,url,changedFiles'
+const VIEW_FIELDS = 'headRefName,headRefOid,baseRefName,isCrossRepository,state,url,changedFiles,statusCheckRollup,mergeable'
 const PULL_REQUEST_URL = /^https:\/\/github\.com\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)\/pull\/[1-9]\d*$/
+/** The conclusions of a finished check run that do not stand in a merge's way. */
+const GREEN_CONCLUSIONS = new Set(['SUCCESS', 'NEUTRAL', 'SKIPPED'])
+
+const viewOf = (json: string): PullRequestView | undefined => parseJsonObject(json)
 
+/**
+ * A check of the rollup by its name, whether it is green, and whether it is a check run: a run comes from a workflow
+ * or an app, while a status anyone with push access can set through the API.
+ */
+const checkOf = (entry: unknown): { name: string; green: boolean; run: boolean } | undefined => {
+  if (typeof entry !== 'object' || entry === null) return undefined
+  const { __typename, name, status, conclusion, context, state } = entry as Record<string, unknown>
+  if (__typename === 'CheckRun' && typeof name === 'string') {
+    const green = status === 'COMPLETED' && typeof conclusion === 'string' && GREEN_CONCLUSIONS.has(conclusion)
+    return { name, green, run: true }
+  }
+  if (__typename === 'StatusContext' && typeof context === 'string') return { name: context, green: state === 'SUCCESS', run: false }
+  return undefined
+}
 
 /** The head branch of an open pull request from this repository; a fork's branch name proves nothing. */
 export const parseHeadBranch = (json: string): string | undefined => {
-  try {
-    const view: unknown = JSON.parse(json)
-    if (typeof view !== 'object' || view === null) return undefined
-    const { headRefName, isCrossRepository, state } = view as PullRequestView
-    const ours = state === 'OPEN' && isCrossRepository === false
-    return ours && typeof headRefName === 'string' ? headRefName : undefined
-  } catch {
-    return undefined
-  }
+  const { headRefName, isCrossRepository, state } = viewOf(json) ?? {}
+  const ours = state === 'OPEN' && isCrossRepository === false
+  return ours && typeof headRefName === 'string' ? headRefName : undefined
+}
+
+/** The branch the pull request merges into, as GitHub says. */
+export const parseBaseBranch = (json: string): string | undefined => {
+  const base = viewOf(json)?.baseRefName
+  return typeof base === 'string' ? base : undefined
+}
+
+/**
+ * Whether the head commit's checks let a merge pass without a question: GitHub can merge it, it has at least one check
+ * run, every check is green (a run finished as success, neutral or skipped, a status succeeded), and every required
+ * check is among the runs. An empty list is what a pull request shows right after a push, before any workflow started,
+ * so it does not pass; neither does a list of statuses alone, which an agent could set itself in that moment.
+ */
+export const checksPassed = (json: string, requiredChecks: readonly string[] | undefined): boolean => {
+  const view = viewOf(json)
+  const rollup = view?.statusCheckRollup
+  if (view?.mergeable !== 'MERGEABLE' || !Array.isArray(rollup)) return false
+  const checks = rollup.map(checkOf)
+  if (!checks.every((check) => check?.green === true)) return false
+  const runs = new Set(checks.flatMap((check) => (check?.run ? [check.name] : [])))
+  return runs.size > 0 && (requiredChecks ?? []).every((name) => runs.has(name))
+}
+
+/** The commit the pull request's head points at, as GitHub says now; what a `--match-head-commit` must name. */
+export const parseHeadCommit = (json: string): string | undefined => {
+  const commit = viewOf(json)?.headRefOid
+  return typeof commit === 'string' && FULL_COMMIT.test(commit) ? commit : undefined
 }
 
 /**
@@ -33,16 +85,10 @@ export const parseHeadBranch = (json: string): string | undefined => {
  * file list is then asked of that repository by name, so it cannot come from another one than `gh pr merge` merges in.
  */
 export const parseRepositoryFacts = (json: string): RepositoryFacts | undefined => {
-  try {
-    const view: unknown = JSON.parse(json)
-    if (typeof view !== 'object' || view === null) return undefined
-    const { url, changedFiles } = view as { url?: unknown; changedFiles?: unknown }
-    const repository = typeof url === 'string' ? url.match(PULL_REQUEST_URL)?.[1] : undefined
-    const counted = typeof changedFiles === 'number' && Number.isInteger(changedFiles) && changedFiles >= 0
-    return repository !== undefined && counted ? { repository, changedFiles } : undefined
-  } catch {
-    return undefined
-  }
+  const { url, changedFiles } = viewOf(json) ?? {}
+  const repository = typeof url === 'string' ? url.match(PULL_REQUEST_URL)?.[1] : undefined
+  const counted = typeof changedFiles === 'number' && Number.isInteger(changedFiles) && changedFiles >= 0
+  return repository !== undefined && counted ? { repository, changedFiles } : undefined
 }
 
 /** Runs `gh pr view <number>` in `directory`, the directory the command itself runs in; any failure answers nothing. */

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

@@ -1,13 +1,46 @@
 import { readFileSync } from 'node:fs'
 import { isAbsolute, relative } from 'node:path'
+import { mainCheckoutOf } from '../shared/checkout'
 import { parseTranscript } from '../shared/dialog-answers'
+import { isCoordinatorAgent } from '../shared/lane'
+import { once } from '../shared/once'
+import { ownPaneAgent } from '../shared/own-pane'
+import { readShellDefinitions } from '../shared/shell-snapshots'
 import { approvedBranches } from './approval'
 import { allFilesMatch, changedFilesOf } from './check-free'
-import { decideBashCommand, type GuardPolicy, type MergeGuardDecision } from './decision'
-import { parseHeadBranch, parseRepositoryFacts, type RepositoryFacts, viewPullRequest } from './pull-request'
+import { decideBashCommand, type GuardPolicy, type MergeGuardDecision, type MergeNote, type PlainMerge } from './decision'
+import { isPlanApproved, type PlanVerdict } from './plan-approval'
+import { isLaneIn, planApprovalSources, planBaseOf } from './plan-approval-sources'
+import { planPointersDirectory, readPointers } from './plan-pointers'
+import {
+  checksPassed,
+  parseBaseBranch,
+  parseHeadBranch,
+  parseHeadCommit,
+  parseRepositoryFacts,
+  viewPullRequest,
+} from './pull-request'
 import { type GuardSettings, readGuardSettings } from './settings'
 
-type HookInput = { tool_input?: { command?: unknown }; transcript_path?: unknown; cwd?: unknown }
+type HookInput = { tool_input?: { command?: unknown }; transcript_path?: unknown; cwd?: unknown; session_id?: unknown }
+
+/** The exact option labels that approve a merge: the one of the pull request question and the one of a plan question. */
+export type ApprovalLabels = { selfMerge: string; plan: string }
+
+/** What GitHub says about the pull request a merge names; `files` is asked only when a rule needs it. */
+type MergeFacts = {
+  branch: string
+  baseBranch: string | undefined
+  headCommit: string | undefined
+  /** The `gh pr view` answer, which carries the checks and whether GitHub can merge. */
+  view: string
+  files: () => readonly string[] | undefined
+}
+
+type PlanApproval = (facts: MergeFacts & { headCommit: string }) => PlanVerdict
+
+/** The ways a merge may pass without a question. */
+type MergeApprovals = { branches: ReadonlySet<string>; withoutChecks: readonly string[]; plan: PlanApproval | undefined }
 
 const PASS: MergeGuardDecision = { kind: 'pass' }
 
@@ -27,46 +60,102 @@ const isInside = (directory: string, project: string): boolean => {
   return path === '' || (!path.startsWith('..') && !isAbsolute(path))
 }
 
-/** Every file of the pull request, as GitHub lists them, matches `merge.withoutChecks`. */
-const isCheckFree = (
-  pullRequest: number,
-  facts: RepositoryFacts | undefined,
-  withoutChecks: readonly string[],
-  directory: string,
-): boolean => facts !== undefined && allFilesMatch(changedFilesOf(pullRequest, directory, facts) ?? [], withoutChecks)
+/**
+ * The user approved the branch and its checks passed, every file needs no checks, or the user approved the plan of the
+ * branch's lane; each only for a merge bound to the head commit GitHub reports, so a push after the check is not
+ * merged unchecked. A plan approval that no longer covers the plan answers with a note for the question.
+ */
+const approvesMerge = (
+  { branches, withoutChecks, plan }: MergeApprovals,
+  merge: PlainMerge,
+  facts: MergeFacts,
+): boolean | MergeNote => {
+  const { headCommit } = facts
+  if (headCommit === undefined || merge.headCommit !== headCommit) return false
+  if (branches.has(facts.branch) && checksPassed(facts.view, undefined)) return true
+  if (withoutChecks.length > 0 && allFilesMatch(facts.files() ?? [], withoutChecks)) return true
+  return plan === undefined ? false : plan({ ...facts, headCommit })
+}
 
-const policyFor = (input: HookInput, label: string, projectDirectory: string): GuardPolicy => {
+/**
+ * The files of the pull request, while its head is still the commit `gh pr view` named: a push between the two
+ * calls would list the files of a commit the merge does not name.
+ */
+const filesAtHead = (pullRequest: number, view: string, directory: string): (() => readonly string[] | undefined) => {
+  const facts = parseRepositoryFacts(view)
+  const headCommit = parseHeadCommit(view)
+  return once(() => {
+    if (facts === undefined || headCommit === undefined) return undefined
+    const files = changedFilesOf(pullRequest, directory, facts)
+    const again = files === undefined ? undefined : parseHeadCommit(viewPullRequest(pullRequest, directory) ?? '')
+    return again === headCommit ? files : undefined
+  })
+}
+
+/** The facts of the pull request from its `gh pr view`; undefined unless it is open and from this repository. */
+const mergeFactsOf = (pullRequest: number, view: string, directory: string): MergeFacts | undefined => {
+  const branch = parseHeadBranch(view)
+  if (branch === undefined) return undefined
+  return {
+    branch,
+    baseBranch: parseBaseBranch(view),
+    headCommit: parseHeadCommit(view),
+    view,
+    files: filesAtHead(pullRequest, view, directory),
+  }
+}
+
+/**
+ * How to tell whether the user approved the plan of the branch's lane, read in the main checkout; undefined when no
+ * plan approval can hold (no label, no transcript, no repository, plan approval off, no pointer, a session that is not
+ * the coordinator's), so GitHub is not asked.
+ */
+const planApprovalFor = (input: HookInput, label: string, projectDirectory: string): PlanApproval | undefined => {
+  const transcript = input.transcript_path
+  if (label === '' || typeof transcript !== 'string') return undefined
+  try {
+    const main = mainCheckoutOf(projectDirectory)
+    if (readPointers(planPointersDirectory(main)).length === 0) return undefined
+    const base = planBaseOf(main)
+    if (base === undefined) return undefined
+    const isLane = isLaneIn(main, base.settings.worktreeDirectory)
+    if (!isCoordinatorAgent({ agent: ownPaneAgent(), session: input.session_id, main, isLane })) return undefined
+    return ({ branch, baseBranch, headCommit, view, files }) =>
+      baseBranch !== undefined &&
+      isPlanApproved(
+        { pullRequest: { branch, baseBranch, headCommit }, label, now: Date.now(), settings: base.settings },
+        planApprovalSources({ main, base, transcript, label, files, view }),
+      )
+  } catch {
+    return undefined
+  }
+}
+
+const policyFor = (input: HookInput, labels: ApprovalLabels, projectDirectory: string): GuardPolicy => {
   const settings = readGuardSettings(projectDirectory)
   const directory = typeof input.cwd === 'string' && input.cwd !== '' ? input.cwd : projectDirectory
-  const views = new Map<number, string | undefined>()
-  const viewOf = (pullRequest: number): string => {
-    if (!views.has(pullRequest)) views.set(pullRequest, viewPullRequest(pullRequest, directory))
-    return views.get(pullRequest) ?? ''
-  }
-  let approved: Set<string> | undefined
+  const branches = once(() => approvedBranchesFrom(input.transcript_path, settings, labels.selfMerge))
+  const plan = once(() => planApprovalFor(input, labels.plan, projectDirectory))
   return {
     commands: settings.commands,
-    isMergeApproved: (pullRequest) => {
+    shellDefinitions: once(() => readShellDefinitions()),
+    isMergeApproved: (merge) => {
       if (!isInside(directory, projectDirectory)) return false
-      const branches = (approved ??= approvedBranchesFrom(input.transcript_path, settings, label))
-      if (branches.size === 0 && settings.withoutChecks.length === 0) return false
-      // The branch lookup also proves the pull request is open and from this repository; both paths need that.
-      const view = viewOf(pullRequest)
-      const branch = parseHeadBranch(view)
-      if (branch === undefined) return false
-      return (
-        branches.has(branch) || isCheckFree(pullRequest, parseRepositoryFacts(view), settings.withoutChecks, directory)
-      )
+      const approvals = { branches: branches(), withoutChecks: settings.withoutChecks, plan: plan() }
+      if (approvals.branches.size === 0 && approvals.withoutChecks.length === 0 && approvals.plan === undefined) return false
+      // The branch lookup also proves the pull request is open and from this repository; every path needs that.
+      const facts = mergeFactsOf(merge.pullRequest, viewPullRequest(merge.pullRequest, directory) ?? '', directory)
+      return facts !== undefined && approvesMerge(approvals, merge, facts)
     },
   }
 }
 
 /** Reads the hook input and decides; throws on input it cannot read. */
-export const decideInput = (text: string, label: string, projectDirectory: string): MergeGuardDecision => {
+export const decideInput = (text: string, labels: ApprovalLabels, projectDirectory: string): MergeGuardDecision => {
   const input = JSON.parse(text) as HookInput
   const command = input.tool_input?.command
   if (typeof command !== 'string') return PASS
-  return decideBashCommand(command, policyFor(input, label, projectDirectory))
+  return decideBashCommand(command, policyFor(input, labels, projectDirectory))
 }
 
 export const failureDecision = (error: unknown): MergeGuardDecision => ({

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

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import { isRecord } from '../shared/json'
 
 export type GuardSettings = {
   commands: string[]
@@ -10,7 +11,7 @@ export type GuardSettings = {
 }
 
 export const DEFAULT_SETTINGS: GuardSettings = {
-  commands: ['gh pr merge', 'gh workflow run'],
+  commands: ['gh pr merge', 'gh workflow run', 'gh run rerun', 'gh api'],
   selfMerge: { offer: true, approvalMinutes: 180 },
   withoutChecks: [],
 }
@@ -29,27 +30,26 @@ const isCheckFreePattern = (value: unknown): value is string =>
 
 const isPatternList = (value: unknown): value is string[] => Array.isArray(value) && value.every(isCheckFreePattern)
 
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-  typeof value === 'object' && value !== null && !Array.isArray(value)
-
 const isCommandList = (value: unknown): value is string[] =>
   Array.isArray(value) && value.every((entry) => typeof entry === 'string' && GUARDED_COMMAND.test(entry))
 
 const isMinutes = (value: unknown): value is number =>
   typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= MAX_MINUTES
 
-/** The first config that exists; the hook has no schema library, `jh` validates the file. */
-const readConfig = (directories: string[]): Record<string, unknown> => {
+/** The first config that exists, `{}` for none, `null` for one that is no JSON object; the hook has no schema library, `jh` validates the file. */
+export const readConfigOrNull = (directories: string[]): Record<string, unknown> | null => {
   const path = directories.map((directory) => join(directory, CONFIG_PATH)).find((candidate) => existsSync(candidate))
   if (!path) return {}
   try {
     const config: unknown = JSON.parse(readFileSync(path, 'utf8'))
-    return isRecord(config) ? config : {}
+    return isRecord(config) ? config : null
   } catch {
-    return {}
+    return null
   }
 }
 
+const readConfig = (directories: string[]): Record<string, unknown> => readConfigOrNull(directories) ?? {}
+
 /**
  * The guard settings of the project's `.jackherd/config.json`, else of the home one. Whatever is missing or
  * malformed keeps its default, so a broken config guards more, never less; only an empty list switches the guard off.

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

@@ -1,13 +1,13 @@
 // Runs the decision off the main thread, so index.ts can end it when it takes too long.
-import { decideInput, failureDecision } from './run'
+import { type ApprovalLabels, decideInput, failureDecision } from './run'
 
-type Job = { text: string; label: string; projectDirectory: string }
+type Job = { text: string; labels: ApprovalLabels; projectDirectory: string }
 
 declare const self: Worker
 
 self.onmessage = ({ data }: MessageEvent<Job>) => {
   try {
-    self.postMessage(decideInput(data.text, data.label, data.projectDirectory))
+    self.postMessage(decideInput(data.text, data.labels, data.projectDirectory))
   } catch (error) {
     self.postMessage(failureDecision(error))
   }

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
+}