jackherd 1.6.1 → 1.7.1

package/src/plans/texts.ts

@@ -1,9 +1,10 @@
 import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
-import { CHECKS, type ChecksState } from './pull-requests'
-import { NO_AGENT_WORD, PHASE_COUNT } from './symbols'
+import { CHECK_NAME_LENGTH, CHECKS, type ChecksState, type PullRequest } from './pull-requests'
+import { shownWithMore } from './shown-with-more'
+import { MODEL_MARK, NO_AGENT_WORD, PHASE_COUNT } from './symbols'
 
 /**
- * Everything the plans view says in words but the watcher's badges. The view is English whatever language the
+ * Everything the herd says in words but the watcher's badges. The herd is English whatever language the
  * project answers in; plan and phase titles come from the plans as written, and the status words are herdr's own terms.
  */
 export type PlanTexts = {
@@ -15,11 +16,10 @@ export type PlanTexts = {
   noRow: string
   notInPlan: string
   noCheckboxes: string
-  ticked: string
+  /** In place of the count of a phase whose only open box is the documentation box of its review gate. */
+  allButDocs: string
   tickedUnmerged: string
   tickedSummary: (count: number) => string
-  notesHidden: (count: number) => string
-  notesShown: (count: number) => string
   draft: string
   privateLink: string
   planned: (phases: number, plans: number) => string
@@ -59,7 +59,7 @@ export const BADGE_TEXTS: Record<PlanLanguage, BadgeTexts> = {
   },
 }
 
-/** What the view says about a board, in the word the project calls it (`board.term`). */
+/** What the herd says about a board, in the word the project calls it (`board.term`). */
 export const boardTexts = (term: string) => ({
   missing: (glob: string) => `no ${term} under ${glob}`,
   laneNotListed: (lane: string) => `lane "${lane}" is not in the ${term}`,
@@ -70,6 +70,8 @@ export const boardTexts = (term: string) => ({
   notReadable: (reason: string) => `${term} not readable: ${reason}`,
 })
 
+const ALL_BUT_DOCS = 'docs open'
+
 export const TEXTS: PlanTexts = {
   noAgent: NO_AGENT_WORD,
   waiting: (lanes) => `waiting (${lanes})`,
@@ -79,11 +81,9 @@ export const TEXTS: PlanTexts = {
   noRow: 'no row in lanes',
   notInPlan: 'not in the plan',
   noCheckboxes: 'no checkboxes',
-  ticked: 'ticked',
+  allButDocs: ALL_BUT_DOCS,
   tickedUnmerged: 'ticked, not merged',
   tickedSummary: (count) => `${count} ticked · click or a lists them`,
-  notesHidden: (count) => `${count} ${count === 1 ? 'note' : 'notes'} hidden · click or n shows them`,
-  notesShown: (count) => `${count} ${count === 1 ? 'note' : 'notes'} shown · click or n hides them`,
   draft: 'draft · ',
   privateLink: 'private',
   following: (groups) => `also open · ${groups}`,
@@ -95,13 +95,30 @@ export const TEXTS: PlanTexts = {
     [CHECKS.pending]: '… checks',
     [CHECKS.none]: 'no checks',
   },
-  hint: '↑↓ select  →← open  a all  n notes  s html  q quit  ? help',
+  hint: '↑↓ select  →← open  a show ticked  s html  q quit  ? help',
   legend: [
     'enter/space or click toggles a lane or a phase, click or enter on a task opens its whole text, and opens a ↗ pull request · wheel PgUp PgDn scroll · j k h l like the arrows · click or ctrl+click on a 📎 chip opens its link · ✦ artifact · ⑂ pull request or issue · ◈ Figma · private = the plan says so',
-    '⚡ working · ❓ blocked, waits for you · 📨 done = the agent finished its answer, not the lane · ⏸ idle · · no agent = a worktree nobody works in · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · working and blocked lanes open by themselves, → ← overrule until the status changes',
-    `n/m = m checkboxes of the phase, n ticked (the phase being worked on is yellow; ticked, not merged = all ticked in the worktree, not on the base branch yet) · ${PHASE_COUNT.allTicked} n/n all ticked · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · n shows or hides the notes of a lane · s opens every lane and plan as one HTML page · ⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main`,
+    '● working · ◆ blocked, waits for you · ◉ done = the agent finished its answer, not the lane · ○ idle · (·) no agent = a worktree nobody works in · waiting = not started: no worktree yet, something left to do, and what it starts after; finished lanes (cleaned up, or every named phase ticked) are not shown · working and blocked lanes open by themselves, → ← overrule until the status changes',
+    `▸ ▾ open and close · ▶ next open task · ✓ finished phase · ${ALL_BUT_DOCS} = only the documentation box is open · ticked, not merged = all ticked in the worktree, not on the base branch yet · the herd follows the phase whose boxes moved last, in yellow · ${PHASE_COUNT.empty} no checkboxes · ${PHASE_COUNT.missing} not in the plan · a lists the ticked checkboxes one by one · s opens every lane and plan as one HTML page`,
+    `◐ lane progress · n/m = m checkboxes of the phase, n ticked · n/n in green = all ticked · 🥣 share of the context window used · Opus ${MODEL_MARK.fits} = the phase's subagent ran on the plan's model, Sonnet ${MODEL_MARK.differs} Opus in amber = on another`,
+    '↗ pull request · 💬 new feedback · ✋ changes requested · 🌐 preview · 📡 ticket: chip 📡 T-1 · status under 📎, 📡 <n> in amber on a folded lane when tickets are new',
+    '⎇ branch · ↑ commits ahead · ± uncommitted · no worktree: plan read from main',
   ],
 }
 
 /** The mark of a running lane the board has no row for; null for a lane it lists. */
 export const laneMarkText = (lane: { unlisted?: boolean }): string | null => (lane.unlisted ? TEXTS.noRow : null)
+
+/** The most red checks the checks column names; the rest is counted. */
+export const NAMED_CHECKS = 3
+
+/**
+ * The words of a pull request's check state: `✗ test, lint` names the red checks (at most `NAMED_CHECKS`, then
+ * `+<n>`), every other state and a red one without names is the fixed word of `PLAN_TEXTS.checks`.
+ */
+export const checksText = ({ checks, failedChecks }: Pick<PullRequest, 'checks' | 'failedChecks'>): string => {
+  if (checks !== CHECKS.failed || failedChecks.length === 0) return TEXTS.checks[checks]
+  const { shown, more } = shownWithMore(failedChecks, NAMED_CHECKS)
+  const names = shown.map((name) => name.slice(0, CHECK_NAME_LENGTH)).join(', ')
+  return `✗ ${names}${more > 0 ? ` +${more}` : ''}`
+}

package/src/plans/view.ts

@@ -36,6 +36,7 @@ export const renderSnapshot = (
       lanes: snapshot.views,
       planned: snapshot.planned,
       watch: snapshot.watch,
+      watchesTickets: snapshot.watchesTickets,
       language: snapshot.language,
     },
     selection,

package/src/sync/command.ts

@@ -1,4 +1,7 @@
-import { CLI_NAME } from '../version/release'
+import { existsSync } from 'node:fs'
+import { hasProjectInstall } from '../config/legacy-names'
+import { configCandidates } from '../config/location'
+import { CLI_NAME, PACKAGE_NAME } from '../version/release'
 import {
   type CommandContext,
   defaultContext,
@@ -62,6 +65,16 @@ export const parseSyncArgs = (args: string[]): SyncArgs => {
   return { ok: true, accept, global, ifChanged, check }
 }
 
+/**
+ * True when `root` has a project config but no project install: the config holds settings for the global install,
+ * and only `jh init` may turn it into a project install.
+ */
+const isConfigWithoutInstall = (root: string, exists: (path: string) => boolean): boolean =>
+  configCandidates(root).some(exists) && !hasProjectInstall(root, exists)
+
+const notInstalledLine = (root: string): string =>
+  `${CLI_NAME} sync: ${root} has a ${PACKAGE_NAME} config but no project install, so nothing was synced. \`${CLI_NAME} init\` installs the kit here; \`${CLI_NAME} sync ${GLOBAL_FLAG}\` updates the global kit.`
+
 const syncGlobal = (context: CommandContext, accept: string[]): Promise<number> =>
   runWithKit(context, 'sync', async (kit) => {
     const result = await runGlobalSync({ home: context.home, kit, accept, configHome: context.configHome })
@@ -98,6 +111,8 @@ export const runSyncCommand = async (
   const { accept, global, ifChanged, check: dryRun } = parsed
   if (ifChanged) return syncGlobalIfChanged(context, accept, check)
   if (global) return syncGlobal(context, accept)
+  if (isConfigWithoutInstall(context.projectRoot, existsSync))
+    return usageError(context, notInstalledLine(context.projectRoot))
   return runWithKit(
     context,
     'sync',

package/src/sync/herdr-plugin.ts

@@ -142,7 +142,7 @@ export const linkHerdrPlugin = ({
     return `Could not link the herdr plugin, herdr said: ${result.output || `exit ${result.exitCode}`}`
   const linkedLine = linked
     ? `Relinked the herdr plugin from ${linked.root} to ${directory} (${reasonText(reason, linked)}).`
-    : 'Linked the herdr plugin (the pane and the action for the plans view).'
+    : 'Linked the herdr plugin (the pane and the action for the herd).'
   return joinLines(linkedLine, unlink())
 }
 

package/src/sync/next-steps.ts

@@ -36,7 +36,7 @@ export const nextSteps = ({ skillPrefix, adapter, tools, version, cli }: NextSte
     `${orchestrate}: run a board's phases in parallel lanes.`,
     herdrLine(orchestrate, adapter, tools),
     ghLine(orchestrate, tools),
-    `${cli} plans: see every plan and lane in one view.`,
+    `${cli} herd: the whole herd at a glance, the state of every lane.`,
     `Docs: https://www.npmjs.com/package/${PACKAGE_NAME}/v/${version}#documentation`,
   ]
 }

package/src/sync/render.ts

@@ -1,6 +1,6 @@
 import type { JackherdConfig } from '../config'
 import { frozenInstallCommand } from '../config/detect'
-import { ADDRESS_FORM, LANGUAGE_NAME, PLAN_VOCABULARY, SELF_MERGE_LABEL } from '../vocabulary'
+import { ADDRESS_FORM, APPROVAL_TEXTS, LANGUAGE_NAME, PLAN_VOCABULARY, SELF_MERGE_LABEL } from '../vocabulary'
 
 const PLACEHOLDER = /\{\{\s*(kit\.[A-Za-z0-9_.-]*)\s*\}\}/g
 
@@ -39,6 +39,7 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ...prefixed('board', config.board),
     ['kit.guard.selfMergeLabel', SELF_MERGE_LABEL[config.responseLanguage]],
     ['kit.guard.selfMerge', config.guard.selfMerge.offer ? 'offered' : 'not offered'],
+    ...prefixed('approval', APPROVAL_TEXTS[config.responseLanguage]),
     ['kit.merge.withoutChecks', checkFreeList(config.merge.withoutChecks)],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
   ])

package/src/sync/setup-questions.ts

@@ -11,7 +11,7 @@ const LANGUAGE_CHOICES: readonly Choice<PlanLanguage>[] = [PLAN_LANGUAGE.en, PLA
 }))
 
 const ADAPTER_CHOICES: readonly Choice<TerminalAdapter>[] = [
-  { value: TERMINAL_ADAPTER.herdr, label: 'Yes, use herdr (agent states and context fill in the plans view)' },
+  { value: TERMINAL_ADAPTER.herdr, label: 'Yes, use herdr (agent states and context fill in the herd)' },
   { value: TERMINAL_ADAPTER.none, label: 'No, not now' },
 ]
 
@@ -20,7 +20,7 @@ const RESPONSE_QUESTION = 'Which language should the skills answer you in?'
 const PLAN_QUESTION = 'Which language should plans and boards be written in? It sets their headings.'
 
 const ADAPTER_QUESTION =
-  'Use herdr? It runs parallel lanes for /orchestrate and shows each agent in the plans view; /plan and /implement work without it.'
+  'Use herdr? It runs parallel lanes for /orchestrate and shows each agent in the herd; /plan and /implement work without it.'
 
 const INSTALL_QUESTION = `herdr is not installed. It is only needed for parallel lanes. Install it now with its official installer, \`${INSTALLERS.herdr}\`?`
 

package/src/terminal/text.ts

@@ -41,6 +41,7 @@ export const paint = {
   green: style('32'),
   yellow: style('33'),
   magenta: style('35'),
+  teal: style('38;5;37'),
   cyan: style('36'),
   inverse: style('7'),
 }
@@ -67,6 +68,9 @@ export const link = (url: string, text: string): string =>
 export const badge = (url: string, text: string, hint = '', tone: BadgeTone = BADGE_TONE.grey): string =>
   `${ESC}[${tone}m ${link(url, text)}${hint ? `${FAINT_ON} ${hint}${FAINT_OFF}` : ''} ${RESET}`
 
+/** `text` as a badge without a link, for what no click opens: the background of `tone`, a cell of padding either side. */
+export const box = (text: string, tone: BadgeTone = BADGE_TONE.grey): string => `${ESC}[${tone}m ${text} ${RESET}`
+
 /** A line for output that is not a terminal: styling dropped, each link written out as `text (url)`. */
 export const plainText = (text: string): string =>
   stripAnsi(text.replace(LINK, (_, url, inner) => `${stripAnsi(inner)} (${url})`))

package/src/terminal/types.ts

@@ -16,7 +16,7 @@ export type AdoptedName = { pane: string; name: string }
 export type LaneAgent = { name: string; pane: string; status: string; session: string | null; cwd: string | null }
 
 /**
- * Where lane agents run. The plans view reads agent status and sets a short title per lane through
+ * Where lane agents run. The herd reads agent status and sets a short title per lane through
  * this; the adapter `none` stands for a setup without a terminal multiplexer.
  */
 export type LaneStatusSource = {

package/src/update/command.ts

@@ -1,13 +1,14 @@
 /**
  * `jh update`: installs the newest release with the package manager that holds the kit globally,
- * then syncs `~/.claude` (and the project, when the working directory is inside one) with the new code. It
- * runs only when the user or a session that asked the user starts it; no hook runs it.
+ * then syncs `~/.claude` (and the project, when the working directory is inside one with its own install) with
+ * the new code. It runs only when the user or a session that asked the user starts it; no hook runs it.
  *
  *   jh update
  */
 import { existsSync, realpathSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
+import { hasProjectInstall } from '../config/legacy-names'
 import { findProjectRoot } from '../config/location'
 import { defaultUpdateCheck, lockedVersion } from '../sync/if-changed'
 import { locateKit } from '../sync/kit-source'
@@ -50,6 +51,7 @@ const adaptersFor = async (): Promise<UpdateAdapters> => {
     jhOnPath: () => Bun.which(CLI_NAME) !== null,
     home,
     projectRoot: findProjectRoot(process.cwd(), home, existsSync),
+    hasProjectKit: (root) => hasProjectInstall(root, existsSync),
     log: (line) => console.log(line),
   }
 }

package/src/update/update.ts

@@ -1,4 +1,4 @@
-import { CLI_NAME, isNewerVersion, isRelease } from '../version/release'
+import { CLI_NAME, isNewerVersion, isRelease, PACKAGE_NAME } from '../version/release'
 import { installCommand, LEGACY_PACKAGE_NAME, type PackageManager, removeCommand } from './package-manager'
 
 export const UPDATE_EXIT = { ok: 0, error: 1 } as const
@@ -21,8 +21,13 @@ export type UpdateAdapters = {
   /** Whether a `jh` command is on the path; false when only the `@crossdelta/agent-kit` shell carries this jackherd. Asked before and after the install. */
   jhOnPath: () => boolean
   home: string
-  /** The project the working directory belongs to, or null. */
+  /** The project the working directory belongs to (the nearest directory with a project config), or null. */
   projectRoot: string | null
+  /**
+   * True when `root` holds a project install (a lock of its own); a config alone is settings for the global kit.
+   * The lock's existence counts, not its validity: a broken lock is synced, and the sync names the error.
+   */
+  hasProjectKit: (root: string) => boolean
   log: (line: string) => void
 }
 
@@ -34,10 +39,20 @@ const failed = (log: UpdateAdapters['log'], step: string, command: string): numb
   return UPDATE_EXIT.error
 }
 
+const notInstalledLine = (projectRoot: string): string =>
+  `${projectRoot} has a ${PACKAGE_NAME} config but no project install, so it was not synced; \`${CLI_NAME} init\` installs the kit there.`
+
+/** The project `jh update` syncs: only one with an install of its own, since only `jh init` may create one. */
+const installedProject = (adapters: UpdateAdapters): string | null =>
+  adapters.projectRoot && adapters.hasProjectKit(adapters.projectRoot) ? adapters.projectRoot : null
+
 /** The syncs that bring `~/.claude` and the project to the new files, in the order they run. */
-const syncSteps = async (adapters: UpdateAdapters): Promise<{ argv: string[]; cwd: string }[]> => [
+const syncSteps = async (
+  adapters: UpdateAdapters,
+  project: string | null,
+): Promise<{ argv: string[]; cwd: string }[]> => [
   ...((await adapters.hasGlobalKit()) ? [{ argv: [...adapters.kitCli, 'sync', '--global'], cwd: adapters.home }] : []),
-  ...(adapters.projectRoot ? [{ argv: [...adapters.kitCli, 'sync'], cwd: adapters.projectRoot }] : []),
+  ...(project ? [{ argv: [...adapters.kitCli, 'sync'], cwd: project }] : []),
 ]
 
 /**
@@ -59,6 +74,14 @@ const installAndVerify = async (
   return UPDATE_EXIT.error
 }
 
+/** Runs the syncs with the freshly installed code; the first that fails stops the rest and names its command. */
+const syncAfterInstall = async (adapters: UpdateAdapters, project: string | null): Promise<number> => {
+  for (const { argv, cwd } of await syncSteps(adapters, project)) {
+    if ((await adapters.run(argv, cwd)) !== 0) return failed(adapters.log, 'the sync', argv.join(' '))
+  }
+  return UPDATE_EXIT.ok
+}
+
 const doneLine = (adapters: UpdateAdapters, manager: PackageManager, latest: string, jhWasOnPath: boolean): string => {
   if (jhWasOnPath) return `${CLI_NAME} updated ${adapters.installedVersion} → ${latest}.`
   if (adapters.jhOnPath()) return `${CLI_NAME} ${latest} installed globally.`
@@ -88,10 +111,11 @@ const updateToLatest = async (adapters: UpdateAdapters, manager: PackageManager)
   }
   const installed = await installAndVerify(adapters, manager, latest)
   if (installed !== UPDATE_EXIT.ok) return installed
-  for (const { argv, cwd } of await syncSteps(adapters)) {
-    if ((await adapters.run(argv, cwd)) !== 0) return failed(log, 'the sync', argv.join(' '))
-  }
+  const project = installedProject(adapters)
+  const synced = await syncAfterInstall(adapters, project)
+  if (synced !== UPDATE_EXIT.ok) return synced
   log(doneLine(adapters, manager, latest, jhWasOnPath))
+  if (adapters.projectRoot && !project) log(notInstalledLine(adapters.projectRoot))
   return UPDATE_EXIT.ok
 }
 
@@ -99,8 +123,8 @@ const legacyPackageLine = (manager: PackageManager): string =>
   `${LEGACY_PACKAGE_NAME} is still installed globally; ${CLI_NAME} replaces it. Remove it with: ${removeCommand(manager, LEGACY_PACKAGE_NAME).join(' ')}`
 
 /**
- * Installs the newest release with the manager that holds the kit globally, then syncs `~/.claude` and the
- * project with the freshly installed code; a global package from before the rename is named, not removed.
+ * Installs the newest release with the manager that holds the kit globally, then syncs `~/.claude` and an
+ * installed project with the freshly installed code; a global package from before the rename is named, not removed.
  */
 export const runUpdate = async (adapters: UpdateAdapters): Promise<number> => {
   const { manager, log } = adapters

package/src/vocabulary/index.ts

@@ -38,6 +38,25 @@ export const SELF_MERGE_LABEL: Record<PlanLanguage, string> = {
   [PLAN_LANGUAGE.de]: 'Freigeben, und nach grünen Checks selbst mergen',
 }
 
+/**
+ * The words of an approval: the two option labels of the coordinator's question about a lane's call, which the
+ * approval gate hook matches exactly, and what the hook tells the lane when it denies. Fixed per language, not config.
+ */
+export const APPROVAL_TEXTS: Record<PlanLanguage, { allow: string; deny: string; pending: string; denied: string }> = {
+  [PLAN_LANGUAGE.en]: {
+    allow: 'Allow this call',
+    deny: 'Deny this call',
+    pending: 'Approval pending with the coordinator; retry the same call once it is approved.',
+    denied: 'The user denied this call through the coordinator; do not retry it.',
+  },
+  [PLAN_LANGUAGE.de]: {
+    allow: 'Aufruf erlauben',
+    deny: 'Aufruf ablehnen',
+    pending: 'Freigabe steht aus beim Koordinator; denselben Aufruf nach der Freigabe erneut versuchen.',
+    denied: 'Der User hat diesen Aufruf über den Koordinator abgelehnt; nicht erneut versuchen.',
+  },
+}
+
 export const isPlanLanguage = (value: string): value is PlanLanguage =>
   (Object.values(PLAN_LANGUAGE) as string[]).includes(value)
 
@@ -81,8 +100,18 @@ export type PlanVocabulary = {
   laneClosed: string
   /** Words a starts-after cell begins with when the lane may start at once. */
   startsNow: readonly string[]
+  /** Opens the parenthesis by which a board row's phases cell records a user's side order in prose. */
+  sideOrderMarker: string
   /** Words that may stand between two phases of one entry (`P1 Rule und P2 Monitor`). */
   phaseConnectors: readonly string[]
+  /** Words that open a writes cell naming another phase's set instead of listing it (`wie 15`). */
+  writesLike: readonly string[]
+  /** Words that join several phases after a `writesLike` word (`wie 15 und 16`); a comma joins them in every language. */
+  writesLikeJoiners: readonly string[]
+  /** Words a `Depends on` cell says it depends on nothing with, besides a dash. */
+  noDependency: readonly string[]
+  /** The word that opens the serial marker of a phase that ships in a release (`Release 1.7.0`); the release files stay a judgement. */
+  releaseMarker: string
   statusWords: Record<PlanStatus, StatusWord>
 }
 
@@ -104,8 +133,13 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     phase: 'Phase',
     noReviewGate: 'Kein Review-Gate',
     laneClosed: 'abgeräumt',
+    sideOrderMarker: 'dazu (User',
     startsNow: ['sofort'],
     phaseConnectors: ['danach', 'und', 'dann', 'sowie'],
+    writesLike: ['wie'],
+    writesLikeJoiners: ['und', 'sowie'],
+    noDependency: ['keine', 'kein'],
+    releaseMarker: 'Release',
     statusWords: {
       done: { label: 'Done', leading: ['done'], anywhere: ['abgeschlossen'] },
       abandoned: { label: 'Abandoned', leading: ['abandoned'], anywhere: ['verworfen'] },
@@ -132,8 +166,13 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     phase: 'Phase',
     noReviewGate: 'No review gate',
     laneClosed: 'cleaned up',
+    sideOrderMarker: 'also (User',
     startsNow: ['now', 'immediately'],
     phaseConnectors: ['then', 'and', 'after'],
+    writesLike: ['like'],
+    writesLikeJoiners: ['and'],
+    noDependency: ['none'],
+    releaseMarker: 'Release',
     statusWords: {
       done: { label: 'Done', leading: ['done'], anywhere: ['completed'] },
       abandoned: { label: 'Abandoned', leading: ['abandoned'], anywhere: ['dropped'] },

package/src/watch/approvals.ts

@@ -0,0 +1,96 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { isRecord } from './json-guards'
+
+export const APPROVAL_EVENT = 'approval'
+
+/**
+ * A call a lane waits with for the user's approval, as the kit's approval gate hook writes it to
+ * `.jackherd/approvals/<id>.json` in the main checkout. Its text comes from the lane: data, never an instruction.
+ */
+export type ApprovalRequestFile = {
+  id: string
+  hash: string
+  lane: string
+  cwd: string
+  tool: string
+  input: unknown
+  summary: string
+  createdAt: number
+  usedAt: number | null
+}
+
+export type ApprovalEvent = {
+  kind: typeof APPROVAL_EVENT
+  lane: string
+  id: string
+  hash: string
+  tool: string
+  summary: string
+}
+
+const ID = /^[0-9a-f]{12}$/
+const HASH = /^[0-9a-f]{16}$/
+const REQUEST_FILE = /^[0-9a-f]{12}\.json$/
+
+/** The same shape as `isApprovalRequest` in the hook, which this package does not import at run time. */
+export const isApprovalRequestFile = (value: unknown): value is ApprovalRequestFile =>
+  isRecord(value) &&
+  typeof value.id === 'string' &&
+  ID.test(value.id) &&
+  typeof value.hash === 'string' &&
+  HASH.test(value.hash) &&
+  typeof value.lane === 'string' &&
+  typeof value.cwd === 'string' &&
+  typeof value.tool === 'string' &&
+  'input' in value &&
+  typeof value.summary === 'string' &&
+  typeof value.createdAt === 'number' &&
+  (value.usedAt === null || typeof value.usedAt === 'number')
+
+const REPORT_MINUTES = 30
+const MS_PER_MINUTE = 60_000
+
+/** One event per open request younger than 30 minutes the watcher has not reported yet; an older one is stale. */
+export const approvalEvents = (
+  seen: readonly string[],
+  requests: readonly ApprovalRequestFile[],
+  now: number,
+): ApprovalEvent[] =>
+  requests
+    .filter(
+      (request) =>
+        request.usedAt === null &&
+        !seen.includes(request.id) &&
+        now - request.createdAt <= REPORT_MINUTES * MS_PER_MINUTE,
+    )
+    .map(({ lane, id, hash, tool, summary }) => ({ kind: APPROVAL_EVENT, lane, id, hash, tool, summary }))
+
+/** The ids to remember: every request still on disk, so one that is gone is forgotten. */
+export const recordApprovals = (requests: readonly ApprovalRequestFile[]): string[] =>
+  requests.map((request) => request.id)
+
+const requestFileNames = (directory: string): string[] => {
+  try {
+    return readdirSync(directory).filter((name) => REQUEST_FILE.test(name))
+  } catch {
+    return []
+  }
+}
+
+/**
+ * The requests in the main checkout's `.jackherd/approvals/`, a claimed one as used; a file that does not parse is
+ * skipped, and a directory that cannot be listed reads as none, so the watch goes on.
+ */
+export const readApprovalRequests = (root: string): ApprovalRequestFile[] => {
+  const directory = join(root, '.jackherd', 'approvals')
+  return requestFileNames(directory).flatMap((name) => {
+    try {
+      const request: unknown = JSON.parse(readFileSync(join(directory, name), 'utf8'))
+      if (!isApprovalRequestFile(request) || `${request.id}.json` !== name) return []
+      return [existsSync(join(directory, `${request.id}.used`)) ? { ...request, usedAt: request.createdAt } : request]
+    } catch {
+      return []
+    }
+  })
+}