jackherd 1.6.1 → 1.7.0

package/herdr-plugin/herdr-plugin.toml

@@ -1,20 +1,20 @@
 id = "crossdelta.jackherd"
 name = "jackherd"
-version = "1.6.1"
+version = "1.7.0"
 min_herdr_version = "0.8.2"
-description = "Show the plans of a board's lanes in a herdr pane"
+description = "Show the herd, the state of a board's lanes, in a herdr pane"
 platforms = ["linux", "macos"]
 
 [[panes]]
 id = "plans"
-title = "jackherd plans"
+title = "herd"
 placement = "split"
-command = ["bunx", "jackherd", "plans"]
+command = ["bunx", "jackherd", "herd"]
 
 [[actions]]
 id = "open-plans"
-title = "Open the plans view"
-description = "Split the focused pane to the right and run jh plans there, in the focused pane's directory"
+title = "Open the herd"
+description = "Split the focused pane to the right and run jh herd there, in the focused pane's directory"
 contexts = ["workspace"]
 command = ["bun", "open-plans.ts"]
 

package/herdr-plugin/open-plans.ts

@@ -14,7 +14,7 @@ export const paneDirectoryOf = (json: string): string | null => {
   }
 }
 
-/** Arguments of `herdr plugin pane open` for the plans pane: to the right of the pane, in its directory when known. */
+/** Arguments of `herdr plugin pane open` for the herd pane: to the right of the pane, in its directory when known. */
 export const openPlansArguments = (pane: string | null, directory: string | null): string[] => [
   'plugin',
   'pane',

package/herdr-plugin/restore-plans.ts

@@ -6,7 +6,7 @@ type Limits = { attempts: number; intervalMs: number }
 /**
  * Measured on herdr 0.9.0: the hook starts ~85 ms after the server, `pane process-info` answers
  * `pane_not_found` until the terminals spawn at ~0.9 s, and the agents are back at ~3 s. The panes get 10 s, ten
- * times what they took; `plans --ensure` gets four tries 2 s apart, past the ~3 s of the agents, for a pane that
+ * times what they took; `herd --ensure` gets four tries 2 s apart, past the ~3 s of the agents, for a pane that
  * goes away between the two reads.
  */
 export const RESTORE_LIMITS = {
@@ -43,10 +43,10 @@ export const agentDirectoriesOf = (json: string, agentPanes: readonly string[]):
   }
 }
 
-/** The arguments for `bun` that run `plans --ensure` with the CLI of the package this plugin ships in. */
+/** The arguments for `bun` that run `herd --ensure` with the CLI of the package this plugin ships in. */
 export const ensureArguments = (pluginRoot: string): string[] => [
   join(dirname(pluginRoot), 'src', 'cli.ts'),
-  'plans',
+  'herd',
   '--ensure',
 ]
 
@@ -81,11 +81,11 @@ const ensureIn = (root: string, pluginRoot: string): boolean =>
   spawnSync('bun', ensureArguments(pluginRoot), { cwd: root, stdio: 'inherit' }).status === 0
 
 /**
- * herdr's `[[startup]]` hook: after a server start or a live handoff, brings back the plans views of every
+ * herdr's `[[startup]]` hook: after a server start or a live handoff, brings back the herd panes of every
  * repository an agent runs in. It parses herdr's answers itself and never throws, unlike the strict parsers of
- * `src/plans/plan-panes.ts`: a hook that fails leaves nothing behind but a log line, and `plans --ensure`, which it
+ * `src/plans/plan-panes.ts`: a hook that fails leaves nothing behind but a log line, and `herd --ensure`, which it
  * calls, reads the panes again strictly. It reads the panes at once, while herdr still names their agents, then waits until
- * herdr answers for every pane and retries `plans --ensure` within `RESTORE_LIMITS`. A repository without a board
+ * herdr answers for every pane and retries `herd --ensure` within `RESTORE_LIMITS`. A repository without a board
  * or config only prints why and is skipped.
  */
 const main = (): number => {
@@ -100,7 +100,7 @@ const main = (): number => {
     console.error('restore-plans: herdr did not answer for every pane in time, trying anyway')
   for (const root of roots)
     if (!retried(() => ensureIn(root, import.meta.dir), RESTORE_LIMITS.ensure, sleep))
-      console.error(`restore-plans: plans --ensure failed in ${root}`)
+      console.error(`restore-plans: herd --ensure failed in ${root}`)
   return 0
 }
 

package/install.sh

@@ -9,7 +9,7 @@ set -eu
 
 # The default is the version this file ships with. The release bump changes it together with
 # package.json; install.test.ts fails while the two differ. Overridable, but only by a plain release.
-JACKHERD_VERSION="${JACKHERD_VERSION:-1.6.1}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.7.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

package/kit/hooks/hooks/approval-gate/decision.ts

@@ -0,0 +1,61 @@
+import type { DialogAnswer } from '../shared/dialog-answer'
+import { isFresh } from '../shared/fresh'
+import { type ApprovalRequest, namedRequest } from './request'
+
+export type GateLabels = { allow: string; deny: string }
+
+export type GateDecision = { kind: 'allow'; id: string } | { kind: 'deny'; id: string } | { kind: 'pending' }
+
+export type GateQuery = {
+  requests: readonly ApprovalRequest[]
+  /** The hash of the call waiting now; it covers lane and directory, so no other lane's request matches. */
+  hash: string
+  answers: readonly DialogAnswer[]
+  labels: GateLabels
+  now: number
+  /** How long an answer holds, from the moment it was given. */
+  validMinutes: number
+}
+
+const PENDING: GateDecision = { kind: 'pending' }
+
+/**
+ * The open request of this call an answer names by id and hash, if the answer is one of the offered labels and was
+ * given after it. The hash in the question is the one the coordinator showed; a request rewritten meanwhile has another.
+ */
+const answeredRequest = (
+  answer: DialogAnswer,
+  open: ReadonlyMap<string, ApprovalRequest>,
+  labels: GateLabels,
+): ApprovalRequest | undefined => {
+  const named = namedRequest(answer.question)
+  const candidate = named === null ? undefined : open.get(named.id)
+  const request = candidate?.hash === named?.hash ? candidate : undefined
+  const isLabel = answer.answer === labels.allow || answer.answer === labels.deny
+  return request && isLabel && answer.offered.includes(answer.answer) && answer.answeredAt >= request.createdAt
+    ? request
+    : undefined
+}
+
+/**
+ * What the user decided about this call: the newest fresh answer, given in the dialog with one of the two labels, to a
+ * request of the same call that no answer was spent on yet. An earlier request of the same call counts, so a retry
+ * after the approval passes at once. Anything else leaves the call pending.
+ */
+export const gateDecision = ({ requests, hash, answers, labels, now, validMinutes }: GateQuery): GateDecision => {
+  const open = new Map(
+    requests.filter((request) => request.hash === hash && request.usedAt === null).map((request) => [request.id, request]),
+  )
+  const decided = answers
+    .filter((answer) => isFresh(answer.answeredAt, now, validMinutes))
+    .sort((first, second) => second.answeredAt - first.answeredAt)
+    .flatMap((answer) => {
+      const request = answeredRequest(answer, open, labels)
+      return request ? [{ answer, request }] : []
+    })
+  const [newest] = decided
+  if (!newest) return PENDING
+  return newest.answer.answer === labels.allow
+    ? { kind: 'allow', id: newest.request.id }
+    : { kind: 'deny', id: newest.request.id }
+}

package/kit/hooks/hooks/approval-gate/herdr-panes.ts

@@ -0,0 +1,24 @@
+import { resolve } from 'node:path'
+import { isRecord, type JsonObject } from '../shared/json'
+
+/** 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
+
+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
+}
+
+/**
+ * The sessions of the agents that run in the main checkout, from the `result` of `herdr pane list`: the coordinator
+ * runs there, every lane in a worktree of its own. Its herdr name is no help, since it differs per repository.
+ */
+export const coordinatorSessions = (listing: unknown, main: string): string[] => {
+  const panes = isRecord(listing) && Array.isArray(listing.panes) ? listing.panes.filter(isRecord) : []
+  return panes.flatMap((pane) =>
+    typeof pane.cwd === 'string' && resolve(pane.cwd) === resolve(main) ? (sessionOf(pane) ?? []) : [],
+  )
+}
+

package/kit/hooks/hooks/approval-gate/index.ts

@@ -0,0 +1,69 @@
+// PermissionRequest hook of Claude Code, shipped by jackherd: the client adapter of the approval gate. In a lane it
+// holds a call that would open a permission dialog, records it for the coordinator and answers with the user's decision
+// from the coordinator's dialog; elsewhere, and on any failure, it answers nothing and the dialog stays. argv[2..5]: the
+// allow label, the deny label, the text for a call still pending after the wait, the text for a denied call, rendered
+// into the hook entry by `sync`.
+import { homedir } from 'node:os'
+import { mainCheckoutOf } from '../shared/checkout'
+import { commandOutput } from '../shared/command'
+import { readConfig } from '../shared/config'
+import { isRecord } from '../shared/json'
+import { coordinatorSessions } from './herdr-panes'
+import { type ClientCall, type GateDependencies, type GateOutcome, runGate } from './run'
+import { approvalsDirectory, claimRequest, pruneRequests, readRequests, writeRequest } from './store'
+import { coordinatorAnswers } from './transcripts'
+
+type ClaudeDecision = { behavior: 'allow' } | { behavior: 'deny'; message: string }
+
+/** herdr's pane listing; throws when herdr cannot be asked, so the gate gives up and the dialog stays. */
+const herdrPanes = (): unknown => {
+  const answer: unknown = JSON.parse(commandOutput(['herdr', 'pane', 'list']))
+  if (!isRecord(answer) || !('result' in answer)) throw new Error('herdr answered no pane list')
+  return answer.result
+}
+
+/** Claude Code's hook input: `cwd`, `tool_name`, `tool_input`. */
+const clientCallOf = (text: string): ClientCall | null => {
+  const input: unknown = JSON.parse(text)
+  if (!isRecord(input) || typeof input.cwd !== 'string' || typeof input.tool_name !== 'string') return null
+  return { cwd: input.cwd, tool: input.tool_name, input: input.tool_input ?? null }
+}
+
+const dependencies: GateDependencies = {
+  inLaneSession: process.env.HERDR_ENV === '1',
+  mainCheckoutOf,
+  config: (main) => readConfig([main, homedir()]),
+  readRequests: (main) => readRequests(approvalsDirectory(main)),
+  writeRequest: (main, request) => writeRequest(approvalsDirectory(main), request),
+  claimRequest: (main, id, now) => claimRequest(approvalsDirectory(main), id, now),
+  pruneRequests: (main, now, minutes) => pruneRequests(approvalsDirectory(main), now, minutes),
+  answers: (main) => coordinatorAnswers(coordinatorSessions(herdrPanes(), main)),
+  now: () => Date.now(),
+  sleep: (ms) => Bun.sleep(ms),
+  randomBytes: () => crypto.getRandomValues(new Uint8Array(6)),
+}
+
+const [allow = '', deny = '', pending = '', denied = ''] = process.argv.slice(2)
+
+const decide = async (): Promise<GateOutcome> => {
+  if (!allow || !deny) return null
+  try {
+    const call = clientCallOf(await Bun.stdin.text())
+    return call ? await runGate(call, { allow, deny }, dependencies) : null
+  } catch {
+    return null
+  }
+}
+
+const claudeDecision = (outcome: NonNullable<GateOutcome>): ClaudeDecision => {
+  if (outcome.kind === 'allow') return { behavior: 'allow' }
+  return { behavior: 'deny', message: outcome.kind === 'denied' ? denied : pending }
+}
+
+const outcome = await decide()
+if (outcome) {
+  console.log(
+    JSON.stringify({ hookSpecificOutput: { hookEventName: 'PermissionRequest', decision: claudeDecision(outcome) } }),
+  )
+}
+process.exit(0)

package/kit/hooks/hooks/approval-gate/lane.ts

@@ -0,0 +1,14 @@
+import { isAbsolute, relative, resolve, sep } from 'node:path'
+
+/** 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 }
+
+/** 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
+}

package/kit/hooks/hooks/approval-gate/request.ts

@@ -0,0 +1,111 @@
+import { createHash } from 'node:crypto'
+import { isRecord } from '../shared/json'
+
+/** One call a lane wants to make: where it runs, and the tool with its whole input. */
+export type GateCall = { lane: string; cwd: string; tool: string; input: unknown }
+
+/**
+ * A call a lane wants to make and that waits for the coordinator. Written by the hook, read by the watcher; whatever
+ * it says, it never approves anything: the approval is the user's dialog answer in the coordinator's transcript.
+ */
+export type ApprovalRequest = GateCall & {
+  id: string
+  /** Over lane, directory, tool and input: an approval covers exactly this call. */
+  hash: string
+  /** One line of the call for the coordinator's question; the whole call is `input`. */
+  summary: string
+  createdAt: number
+  /** When an answer to it was spent; a request is answered once. */
+  usedAt: number | null
+}
+
+const ID = /^[0-9a-f]{12}$/
+const MARK = /`approval ([0-9a-f]{12}) ([0-9a-f]{16})`/g
+const SUMMARY_LENGTH = 160
+const MAX_INPUT_LENGTH = 64_000
+const CONTROL = /[\u0000-\u0008\u000e-\u001f\u007f-\u009f]/g
+const WHITESPACE = /\s+/g
+const BACKTICK = /`/g
+
+/** JSON with the keys of every object sorted, so the same input always gives the same text. */
+const canonicalJson = (value: unknown): string => {
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`
+  if (isRecord(value))
+    return `{${Object.keys(value)
+      .sort()
+      .map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`)
+      .join(',')}}`
+  return JSON.stringify(value) ?? 'null'
+}
+
+export const callHash = ({ lane, cwd, tool, input }: GateCall): string =>
+  createHash('sha256').update(canonicalJson({ lane, cwd, tool, input })).digest('hex').slice(0, 16)
+
+/** Whether the input is small enough to be stored whole; a larger call keeps the client's own dialog. */
+export const isStorableInput = (input: unknown): boolean => canonicalJson(input).length <= MAX_INPUT_LENGTH
+
+/** The id from random bytes the caller draws, so the drawing stays out of this function. */
+export const requestId = (bytes: Uint8Array): string =>
+  [...bytes]
+    .slice(0, 6)
+    .map((byte) => byte.toString(16).padStart(2, '0'))
+    .join('')
+
+/** One line: control characters out, every run of whitespace one space, backticks plain quotes (no mark rides along). */
+const oneLine = (text: string): string =>
+  text.replace(CONTROL, '').replace(WHITESPACE, ' ').replace(BACKTICK, "'").trim()
+
+const cut = (line: string): string => {
+  if (line.length <= SUMMARY_LENGTH) return line
+  const kept = SUMMARY_LENGTH - ` … (+${line.length} more characters)`.length
+  return `${line.slice(0, kept)}… (+${line.length - kept} more characters)`
+}
+
+/** A shell call by its command, any other by its input as JSON; one line of at most 160 characters that says what it cut. */
+export const callSummary = (tool: string, input: unknown): string =>
+  cut(oneLine(isRecord(input) && typeof input.command === 'string' ? input.command : (JSON.stringify(input) ?? '')))
+
+/** How a question names the request it asks about: its id, and the hash of the call the coordinator showed. */
+export type RequestMark = { id: string; hash: string }
+
+/**
+ * The mark a question carries, as the watcher's duty line writes it (contract test): an answer approves the shown
+ * content, not whatever the request file says later.
+ */
+export const requestMark = ({ id, hash }: RequestMark): string => `\`approval ${id} ${hash}\``
+
+/** The one mark a question carries; none when it carries none, or marks that differ in id or hash. */
+export const namedRequest = (question: string): RequestMark | null => {
+  const marks = [...question.matchAll(MARK)].map(([, id, hash]) => ({ id, hash }))
+  const [first] = marks
+  return first && marks.every(({ id, hash }) => id === first.id && hash === first.hash) ? first : null
+}
+
+export const newRequest = ({ id, now, ...call }: GateCall & { id: string; now: number }): ApprovalRequest => ({
+  id,
+  hash: callHash(call),
+  lane: call.lane,
+  cwd: call.cwd,
+  tool: call.tool,
+  input: call.input,
+  summary: callSummary(call.tool, call.input),
+  createdAt: now,
+  usedAt: null,
+})
+
+const hasShape = (value: unknown): value is ApprovalRequest =>
+  isRecord(value) &&
+  typeof value.id === 'string' &&
+  ID.test(value.id) &&
+  typeof value.hash === 'string' &&
+  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')
+
+/** A request whose hash and summary are those of its own call; a file altered by hand is no request. */
+export const isApprovalRequest = (value: unknown): value is ApprovalRequest =>
+  hasShape(value) && value.hash === callHash(value) && value.summary === callSummary(value.tool, value.input)

package/kit/hooks/hooks/approval-gate/run.ts

@@ -0,0 +1,94 @@
+import type { DialogAnswer } from '../shared/dialog-answer'
+import { isFresh } from '../shared/fresh'
+import { gateDecision, type GateLabels } from './decision'
+import { laneOf } from './lane'
+import { type ApprovalRequest, callHash, type GateCall, isStorableInput, newRequest, requestId } from './request'
+import { gateSettingsOf } from './settings'
+
+/** A call as the client's hook hands it over, before it is known to be a lane's. */
+export type ClientCall = { cwd: string; tool: string; input: unknown }
+
+/** What the gate decided; null decides nothing, so the client's own dialog stays. */
+export type GateOutcome = { kind: 'allow' } | { kind: 'denied' } | { kind: 'pending' } | null
+
+/** Everything with a side effect, passed in so a test reaches the flow without a multiplexer, git or files. */
+export type GateDependencies = {
+  /** Whether this session runs in a pane of the terminal multiplexer. */
+  inLaneSession: boolean
+  mainCheckoutOf: (cwd: string) => string
+  config: (main: string) => Record<string, unknown>
+  readRequests: (main: string) => ApprovalRequest[]
+  writeRequest: (main: string, request: ApprovalRequest) => void
+  /** Creates the request's claim exclusively; true for the one caller that may act on its answer. */
+  claimRequest: (main: string, id: string, now: number) => boolean
+  pruneRequests: (main: string, now: number, minutes: number) => void
+  answers: (main: string) => DialogAnswer[]
+  now: () => number
+  sleep: (ms: number) => Promise<void>
+  randomBytes: () => Uint8Array
+}
+
+const POLL_MS = 2000
+const MS_PER_MINUTE = 60_000
+/** An answer holds this long from the moment it was given (User decision, plan P18). */
+const VALID_MINUTES = 30
+/** A request is kept for its wait and the validity of an answer to it, then removed. */
+const KEEP_MINUTES = 60
+
+/** The open request of this call, or a new one written for it, so a retry asks the coordinator only once. */
+const openRequest = (main: string, call: GateCall, dependencies: GateDependencies): ApprovalRequest => {
+  const hash = callHash(call)
+  const now = dependencies.now()
+  dependencies.pruneRequests(main, now, KEEP_MINUTES)
+  const open = dependencies
+    .readRequests(main)
+    .find((request) => request.hash === hash && request.usedAt === null && isFresh(request.createdAt, now, VALID_MINUTES))
+  if (open) return open
+  const request = newRequest({ id: requestId(dependencies.randomBytes()), ...call, now })
+  dependencies.writeRequest(main, request)
+  return request
+}
+
+/** Polls the coordinator's answers until the user decided, the answer was claimed elsewhere, or the wait is over. */
+const awaitDecision = async (
+  main: string,
+  hash: string,
+  labels: GateLabels,
+  waitMinutes: number,
+  dependencies: GateDependencies,
+): Promise<GateOutcome> => {
+  const deadline = dependencies.now() + waitMinutes * MS_PER_MINUTE
+  for (;;) {
+    const now = dependencies.now()
+    const requests = dependencies.readRequests(main)
+    const answers = dependencies.answers(main)
+    const decision = gateDecision({ requests, hash, answers, labels, now, validMinutes: VALID_MINUTES })
+    if (decision.kind !== 'pending' && dependencies.claimRequest(main, decision.id, now))
+      return decision.kind === 'allow' ? { kind: 'allow' } : { kind: 'denied' }
+    if (now >= deadline) return { kind: 'pending' }
+    await dependencies.sleep(POLL_MS)
+  }
+}
+
+/**
+ * The gate for a call that would open a permission dialog in a lane: it records the call as a request the watcher
+ * reports, waits for the user's answer to the coordinator's dialog, and allows or denies. Outside a lane, for a call too
+ * large to store, and on any failure (the multiplexer or git cannot be asked), it decides nothing, so the dialog stays.
+ */
+export const runGate = async (
+  clientCall: ClientCall,
+  labels: GateLabels,
+  dependencies: GateDependencies,
+): Promise<GateOutcome> => {
+  if (!dependencies.inLaneSession || !isStorableInput(clientCall.input)) return null
+  try {
+    const main = dependencies.mainCheckoutOf(clientCall.cwd)
+    const settings = gateSettingsOf(dependencies.config(main))
+    const lane = laneOf({ cwd: clientCall.cwd, main, worktreeDirectory: settings.worktreeDirectory })
+    if (!lane) return null
+    const request = openRequest(main, { lane, ...clientCall }, dependencies)
+    return await awaitDecision(main, request.hash, labels, settings.waitMinutes, dependencies)
+  } catch {
+    return null
+  }
+}

package/kit/hooks/hooks/approval-gate/settings.ts

@@ -0,0 +1,26 @@
+import { sectionOf } from '../shared/config'
+import { isRepositoryDirectory } from '../shared/repository-directory'
+
+export type GateSettings = {
+  /** How long the hook holds a call for the coordinator; below the 10 minutes of the hook entry. */
+  waitMinutes: number
+  worktreeDirectory: string
+}
+
+export const DEFAULT_GATE_SETTINGS: GateSettings = { waitMinutes: 8, worktreeDirectory: '.claude/worktrees' }
+
+/** The same bounds as `guard.approvals.waitMinutes` in the config schema, which the hook cannot import. */
+const isWaitMinutes = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isInteger(value) && value >= 1 && value <= 9
+
+/** The gate's settings from a parsed config; whatever is missing or malformed keeps its default. */
+export const gateSettingsOf = (config: Record<string, unknown>): GateSettings => {
+  const approvals = sectionOf(sectionOf(config, 'guard'), 'approvals')
+  const { worktreeDirectory } = config
+  return {
+    waitMinutes: isWaitMinutes(approvals.waitMinutes) ? approvals.waitMinutes : DEFAULT_GATE_SETTINGS.waitMinutes,
+    worktreeDirectory: isRepositoryDirectory(worktreeDirectory)
+      ? worktreeDirectory
+      : DEFAULT_GATE_SETTINGS.worktreeDirectory,
+  }
+}

package/kit/hooks/hooks/approval-gate/store.ts

@@ -0,0 +1,70 @@
+import { chmodSync, existsSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { isFresh } from '../shared/fresh'
+import { ensurePrivateDirectory, PRIVATE_FILE } from '../shared/private-directory'
+import { type ApprovalRequest, isApprovalRequest } from './request'
+
+const REQUEST_FILE = /^([0-9a-f]{12})\.json$/
+
+/** Where the requests of all lanes lie: in the main checkout, which the watcher reads. Ignored by git. */
+export const approvalsDirectory = (main: string): string => join(main, '.jackherd', 'approvals')
+
+const requestPath = (directory: string, id: string): string => join(directory, `${id}.json`)
+const claimPath = (directory: string, id: string): string => join(directory, `${id}.used`)
+
+/** When the request was claimed, from its claim file; null while it is open. */
+const claimedAt = (directory: string, id: string): number | null => {
+  try {
+    const at = Number(readFileSync(claimPath(directory, id), 'utf8'))
+    return Number.isFinite(at) ? at : null
+  } catch {
+    return null
+  }
+}
+
+const readRequest = (directory: string, id: string): ApprovalRequest[] => {
+  try {
+    const request: unknown = JSON.parse(readFileSync(requestPath(directory, id), 'utf8'))
+    return isApprovalRequest(request) && request.id === id ? [{ ...request, usedAt: claimedAt(directory, id) }] : []
+  } catch {
+    return []
+  }
+}
+
+/** Every request file that parses as one, each with the time of its claim; any other file is skipped. */
+export const readRequests = (directory: string): ApprovalRequest[] =>
+  existsSync(directory)
+    ? readdirSync(directory).flatMap((name) => {
+        const id = REQUEST_FILE.exec(name)?.[1]
+        return id ? readRequest(directory, id) : []
+      })
+    : []
+
+export const writeRequest = (directory: string, request: ApprovalRequest): void => {
+  ensurePrivateDirectory(directory)
+  const path = requestPath(directory, request.id)
+  writeFileSync(path, `${JSON.stringify({ ...request, usedAt: null })}\n`, { mode: PRIVATE_FILE })
+  chmodSync(path, PRIVATE_FILE)
+}
+
+/**
+ * Spends the answer to a request: creates its claim file exclusively, so of two hooks that read the same answer only
+ * one gets `true` and acts on it.
+ */
+export const claimRequest = (directory: string, id: string, now: number): boolean => {
+  try {
+    writeFileSync(claimPath(directory, id), String(now), { flag: 'wx', mode: PRIVATE_FILE })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/** Removes the requests created more than `minutes` ago, with their claims, so the directory does not grow. */
+export const pruneRequests = (directory: string, now: number, minutes: number): void => {
+  for (const request of readRequests(directory)) {
+    if (isFresh(request.createdAt, now, minutes)) continue
+    rmSync(claimPath(directory, request.id), { force: true })
+    rmSync(requestPath(directory, request.id), { force: true })
+  }
+}

package/kit/hooks/hooks/approval-gate/transcripts.ts

@@ -0,0 +1,40 @@
+import { closeSync, existsSync, fstatSync, openSync, readdirSync, readSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { type DialogAnswer, dialogAnswers, parseTranscript } from '../shared/dialog-answers'
+
+/** Claude Code's transcripts: `~/.claude/projects/<project>/<session>.jsonl`; this file is the client adapter. */
+const PROJECTS_DIRECTORY = join(homedir(), '.claude', 'projects')
+/** A transcript grows to hundreds of megabytes; answers of the last 30 minutes lie at its end. */
+const TAIL_BYTES = 4 * 1024 * 1024
+
+const transcriptPath = (session: string, projectsDirectory: string): string | undefined =>
+  existsSync(projectsDirectory)
+    ? readdirSync(projectsDirectory)
+        .map((directory) => join(projectsDirectory, directory, `${session}.jsonl`))
+        .find((path) => existsSync(path))
+    : undefined
+
+/** The last `TAIL_BYTES` of a file; the first line may be cut, and the transcript parser skips it. */
+const readTail = (path: string): string => {
+  const descriptor = openSync(path, 'r')
+  try {
+    const size = fstatSync(descriptor).size
+    const length = Math.min(size, TAIL_BYTES)
+    const buffer = Buffer.alloc(length)
+    readSync(descriptor, buffer, 0, length, size - length)
+    return buffer.toString('utf8')
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
+/** The dialog answers in the transcripts of these sessions; a session without a transcript gives none. */
+export const coordinatorAnswers = (
+  sessions: readonly string[],
+  projectsDirectory: string = PROJECTS_DIRECTORY,
+): DialogAnswer[] =>
+  sessions.flatMap((session) => {
+    const path = transcriptPath(session, projectsDirectory)
+    return path ? dialogAnswers(parseTranscript(readTail(path))) : []
+  })