jackherd 1.14.0 → 1.15.0

package/herdr-plugin/restore-plans.ts

@@ -7,11 +7,13 @@ 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; `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.
+ * goes away between the two reads. The coordinator gets a minute: after a crash its session was still not back after
+ * ~8 s, and the herd beside it stayed missing.
  */
 export const RESTORE_LIMITS = {
   panes: { attempts: 20, intervalMs: 500 },
   ensure: { attempts: 4, intervalMs: 2_000 },
+  coordinator: { attempts: 30, intervalMs: 2_000 },
 } as const satisfies Record<string, Limits>
 
 /** Runs `attempt` until it works or the attempts are used up, waiting the interval between two of them. */
@@ -23,6 +25,31 @@ export const retried = (attempt: () => boolean, limits: Limits, sleep: (ms: numb
   }
 }
 
+/**
+ * Waits for every item in one shared window of `limits`, calls `onReady` for each as soon as `isReady` holds, and
+ * returns the items that never got ready.
+ */
+export const awaitEach = <T>(
+  items: readonly T[],
+  isReady: (item: T) => boolean,
+  onReady: (item: T) => void,
+  limits: Limits,
+  sleep: (ms: number) => void,
+): T[] => {
+  let pending = [...items]
+  retried(
+    () => {
+      const ready = pending.filter(isReady)
+      for (const item of ready) onReady(item)
+      pending = pending.filter((item) => !ready.includes(item))
+      return pending.length === 0
+    },
+    limits,
+    sleep,
+  )
+  return pending
+}
+
 /**
  * The directories of the panes an agent runs in, each once, from a `herdr pane list` answer; none when unreadable.
  * `agentPanes` are the panes of `herdr agent list`: right after a restart the pane list names no agent there for a
@@ -43,6 +70,10 @@ export const agentDirectoriesOf = (json: string, agentPanes: readonly string[]):
   }
 }
 
+/** Whether an agent runs in `root` itself, where the coordinator works, rather than only in its lanes' worktrees. */
+export const hasAgentIn = (root: string, paneList: string, agentPanes: readonly string[]): boolean =>
+  agentDirectoriesOf(paneList, agentPanes).includes(root)
+
 /** 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'),
@@ -80,13 +111,33 @@ const panesAnswer = (panes: readonly string[]): boolean =>
 const ensureIn = (root: string, pluginRoot: string): boolean =>
   spawnSync('bun', ensureArguments(pluginRoot), { cwd: root, stdio: 'inherit' }).status === 0
 
+const coordinatorBackIn = (root: string): boolean =>
+  hasAgentIn(root, herdrRun(['pane', 'list']).stdout ?? '', idsOf(herdrRun(['agent', 'list']).stdout ?? '', 'agents'))
+
+const ensureWithRetries = (root: string, sleep: (ms: number) => void) => {
+  if (!retried(() => ensureIn(root, import.meta.dir), RESTORE_LIMITS.ensure, sleep))
+    console.error(`restore-plans: herd --ensure failed in ${root}`)
+}
+
+/**
+ * The herd beside each coordinator once its session is back, which can take longer than the lanes'. A coordinator
+ * already back had its herd from the first `--ensure`; the others share one waiting window.
+ */
+const ensureCoordinators = (roots: readonly string[], sleep: (ms: number) => void) => {
+  const missing = roots.filter((root) => !coordinatorBackIn(root))
+  const ensure = (root: string) => ensureWithRetries(root, sleep)
+  for (const root of awaitEach(missing, coordinatorBackIn, ensure, RESTORE_LIMITS.coordinator, sleep))
+    console.error(`restore-plans: no coordinator came back in ${root}`)
+}
+
 /**
  * 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 `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 `herd --ensure` within `RESTORE_LIMITS`. A repository without a board
- * or config only prints why and is skipped.
+ * herdr answers for every pane and retries `herd --ensure` within `RESTORE_LIMITS`. A repository whose coordinator
+ * is not back yet gets one more `herd --ensure` once an agent runs in its main checkout. A repository without a
+ * board or config only prints why and is skipped.
  */
 const main = (): number => {
   const list = herdrRun(['pane', 'list'])
@@ -98,9 +149,8 @@ const main = (): number => {
   const sleep = (ms: number) => Bun.sleepSync(ms)
   if (!retried(() => panesAnswer(idsOf(listing, 'panes')), RESTORE_LIMITS.panes, sleep))
     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: herd --ensure failed in ${root}`)
+  for (const root of roots) ensureWithRetries(root, sleep)
+  ensureCoordinators([...roots], sleep)
   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.14.0}"
+JACKHERD_VERSION="${JACKHERD_VERSION:-1.15.0}"
 
 JACKHERD_PACKAGE='jackherd'
 # Test seam: the terminal the wizard asks its questions on.

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

@@ -39,8 +39,11 @@ const sectionsAreObjects = (config: Record<string, unknown>): boolean =>
   isSectionOrAbsent(sectionAt(config, 'guard'), 'planApproval') &&
   isSectionOrAbsent(config, 'board')
 
-/** `guard.requiredChecks`, else where configs before 1.10.0 kept it, `guard.planApproval.requiredChecks`. */
-const requiredChecksOf = (guard: Record<string, unknown>) =>
+/**
+ * `guard.requiredChecks`, else where configs before 1.10.0 kept it, `guard.planApproval.requiredChecks`: `{ value }`,
+ * with `value` undefined when neither is set, and `undefined` for a list that does not read.
+ */
+export const requiredChecksOf = (guard: Record<string, unknown>): { value: readonly string[] | undefined } | undefined =>
   'requiredChecks' in guard
     ? optionalValue(guard, 'requiredChecks', isCheckList)
     : optionalValue(sectionAt(guard, 'planApproval'), 'requiredChecks', isCheckList)

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

@@ -13,6 +13,7 @@ type PullRequestView = {
   headRefOid?: unknown
   baseRefName?: unknown
   isCrossRepository?: unknown
+  isDraft?: unknown
   state?: unknown
   statusCheckRollup?: unknown
   mergeable?: unknown
@@ -20,10 +21,17 @@ type PullRequestView = {
   changedFiles?: unknown
 }
 
+/**
+ * A check of the rollup: `green` when it does not stand in a merge's way, `succeeded` only for a check run that
+ * concluded success; a status never succeeds here.
+ */
+type RollupCheck = { name: string; green: boolean; succeeded: boolean }
+
 /** 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,headRefOid,baseRefName,isCrossRepository,state,url,changedFiles,statusCheckRollup,mergeable'
+const VIEW_FIELDS =
+  'headRefName,headRefOid,baseRefName,isCrossRepository,isDraft,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'])
@@ -31,24 +39,27 @@ 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.
+ * A check of the rollup by its name, whether it is green, and whether it succeeded as 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 => {
+const checkOf = (entry: unknown): RollupCheck | 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 }
+    const finished = status === 'COMPLETED' && typeof conclusion === 'string'
+    return { name, green: finished && GREEN_CONCLUSIONS.has(conclusion), succeeded: finished && conclusion === 'SUCCESS' }
   }
-  if (__typename === 'StatusContext' && typeof context === 'string') return { name: context, green: state === 'SUCCESS', run: false }
+  if (__typename === 'StatusContext' && typeof context === 'string') return { name: context, green: state === 'SUCCESS', succeeded: false }
   return undefined
 }
 
-/** The head branch of an open pull request from this repository; a fork's branch name proves nothing. */
+/**
+ * The head branch of an open, ready pull request from this repository; a fork's branch name proves nothing, and a
+ * draft is never merged, nor one whose draft flag GitHub did not answer.
+ */
 export const parseHeadBranch = (json: string): string | undefined => {
-  const { headRefName, isCrossRepository, state } = viewOf(json) ?? {}
-  const ours = state === 'OPEN' && isCrossRepository === false
+  const { headRefName, isCrossRepository, isDraft, state } = viewOf(json) ?? {}
+  const ours = state === 'OPEN' && isCrossRepository === false && isDraft === false
   return ours && typeof headRefName === 'string' ? headRefName : undefined
 }
 
@@ -60,9 +71,11 @@ export const parseBaseBranch = (json: string): string | 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.
+ * run that succeeded, every check is green (a run finished as success, neutral or skipped, a status succeeded), and
+ * every required check has a run that succeeded. 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, nor skipped runs alone or a required check that was only skipped, as a draft's runs stand right after
+ * `gh pr ready`.
  */
 export const checksPassed = (json: string, requiredChecks: readonly string[] | undefined): boolean => {
   const view = viewOf(json)
@@ -70,8 +83,8 @@ export const checksPassed = (json: string, requiredChecks: readonly string[] | u
   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))
+  const succeeded = new Set(checks.flatMap((check) => (check?.succeeded ? [check.name] : [])))
+  return succeeded.size > 0 && (requiredChecks ?? []).every((name) => succeeded.has(name))
 }
 
 /** The commit the pull request's head points at, as GitHub says now; what a `--match-head-commit` must name. */

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

@@ -41,6 +41,8 @@ type StandingApproval = (facts: MergeFacts) => boolean | MergeNote
 /** The ways a merge may pass without a question. */
 type MergeApprovals = {
   branches: ReadonlySet<string>
+  /** The checks a self-merge of an approved branch waits for a successful run of. */
+  requiredChecks: readonly string[] | undefined
   withoutChecks: readonly string[]
   /** The paths that always ask, which a `withoutChecks` pattern never opens. */
   alwaysAsk: readonly string[]
@@ -64,13 +66,13 @@ const approvedBranchesFrom = (entries: unknown[], settings: GuardSettings, label
  * is not merged unchecked. A standing approval that does not cover a file answers with a note for the question.
  */
 const approvesMerge = (
-  { branches, withoutChecks, alwaysAsk, standing }: MergeApprovals,
+  { branches, requiredChecks, withoutChecks, alwaysAsk, standing }: 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 (branches.has(facts.branch) && checksPassed(facts.view, requiredChecks)) return true
   if (withoutChecks.length > 0 && isCheckFree(facts.files() ?? [], withoutChecks, alwaysAsk)) return true
   return standing === undefined ? false : standing(facts)
 }
@@ -143,12 +145,13 @@ const policyFor = (input: HookInput, labels: ApprovalLabels, projectDirectory: s
       if (!isWithinDirectory(directory, projectDirectory)) return false
       const approvals = {
         branches: branches(),
+        requiredChecks: settings.requiredChecks,
         withoutChecks: settings.withoutChecks,
         alwaysAsk: [...ALWAYS_ASK_PATHS, ...settings.alwaysAsk],
         standing: standing(),
       }
       if (approvals.branches.size === 0 && approvals.withoutChecks.length === 0 && approvals.standing === undefined) return false
-      // The branch lookup also proves the pull request is open and from this repository; every path needs that.
+      // The branch lookup also proves the pull request is open, no draft 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)
     },

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

@@ -2,6 +2,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { join } from 'node:path'
 import { isRecord } from '../shared/json'
+import { requiredChecksOf } from './board-settings'
 
 export type GuardSettings = {
   commands: string[]
@@ -13,6 +14,11 @@ export type GuardSettings = {
    * before 1.10.0); they only ever add a question.
    */
   alwaysAsk: string[]
+  /**
+   * `guard.requiredChecks`: the checks a self-merge waits for a successful run of; undefined: none named, or a list
+   * that does not read, which turns `selfMerge.offer` off.
+   */
+  requiredChecks: readonly string[] | undefined
 }
 
 export const DEFAULT_SETTINGS: GuardSettings = {
@@ -20,6 +26,7 @@ export const DEFAULT_SETTINGS: GuardSettings = {
   selfMerge: { offer: true, approvalMinutes: 180 },
   withoutChecks: [],
   alwaysAsk: [],
+  requiredChecks: undefined,
 }
 
 const CONFIG_PATH = join('.jackherd', 'config.json')
@@ -63,6 +70,7 @@ const pathsOf = (value: unknown): string[] =>
 /**
  * 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.
+ * A `requiredChecks` list that does not read has no default that guards more, so it turns the self-merge answer off.
  */
 export const readGuardSettings = (projectDirectory: string, home: string = homedir()): GuardSettings => {
   const config = readConfig([projectDirectory, home])
@@ -70,15 +78,18 @@ export const readGuardSettings = (projectDirectory: string, home: string = homed
   const merge = isRecord(config.merge) ? config.merge : {}
   const selfMerge = isRecord(section.selfMerge) ? section.selfMerge : {}
   const legacy = isRecord(section.planApproval) ? section.planApproval : {}
+  const readableRequiredChecks = requiredChecksOf(section)
+  const offer = typeof selfMerge.offer === 'boolean' ? selfMerge.offer : DEFAULT_SETTINGS.selfMerge.offer
   return {
     commands: isCommandList(section.commands) ? section.commands : DEFAULT_SETTINGS.commands,
     selfMerge: {
-      offer: typeof selfMerge.offer === 'boolean' ? selfMerge.offer : DEFAULT_SETTINGS.selfMerge.offer,
+      offer: offer && readableRequiredChecks !== undefined,
       approvalMinutes: isMinutes(selfMerge.approvalMinutes)
         ? selfMerge.approvalMinutes
         : DEFAULT_SETTINGS.selfMerge.approvalMinutes,
     },
     withoutChecks: isPatternList(merge.withoutChecks) ? merge.withoutChecks : DEFAULT_SETTINGS.withoutChecks,
     alwaysAsk: [...pathsOf(section.alwaysAsk), ...pathsOf(legacy.exceptPaths)],
+    requiredChecks: readableRequiredChecks?.value,
   }
 }

package/kit/hooks/hooks/model-log/transcript.ts

@@ -1,11 +1,8 @@
 import { parseTranscript } from '../shared/dialog-answers'
 import { isRecord, type JsonObject } from '../shared/json'
+import { CONTENT_BLOCK_TYPE, LOG_ENTRY_TYPE } from '../shared/log-vocabulary'
 import { familyOf, type ModelFamily } from '../shared/model-family'
 
-const USER_ENTRY = 'user'
-const ASSISTANT_ENTRY = 'assistant'
-const TEXT_BLOCK = 'text'
-
 const messageOf = (entry: unknown): JsonObject | null =>
   isRecord(entry) && isRecord(entry.message) ? entry.message : null
 
@@ -13,14 +10,14 @@ const textOf = (content: unknown): string | null => {
   if (typeof content === 'string') return content
   if (!Array.isArray(content)) return null
   const texts = content.flatMap((block) =>
-    isRecord(block) && block.type === TEXT_BLOCK && typeof block.text === 'string' ? [block.text] : [],
+    isRecord(block) && block.type === CONTENT_BLOCK_TYPE.text && typeof block.text === 'string' ? [block.text] : [],
   )
   return texts.length > 0 ? texts.join('\n') : null
 }
 
 /** The subagent's prompt: the text of the first user entry of its transcript; null without one. */
 export const promptOf = (head: string): string | null => {
-  const first = parseTranscript(head).find((entry) => isRecord(entry) && entry.type === USER_ENTRY)
+  const first = parseTranscript(head).find((entry) => isRecord(entry) && entry.type === LOG_ENTRY_TYPE.user)
   return textOf(messageOf(first)?.content)
 }
 
@@ -28,7 +25,7 @@ export const promptOf = (head: string): string | null => {
 export type AnsweredModel = { model: string; family: ModelFamily }
 
 const answeredModel = (entry: unknown): AnsweredModel[] => {
-  const model = isRecord(entry) && entry.type === ASSISTANT_ENTRY ? messageOf(entry)?.model : undefined
+  const model = isRecord(entry) && entry.type === LOG_ENTRY_TYPE.assistant ? messageOf(entry)?.model : undefined
   const family = typeof model === 'string' ? familyOf(model) : null
   return typeof model === 'string' && family ? [{ model, family }] : []
 }

package/kit/hooks/hooks/open-question/record.ts

@@ -1,5 +1,6 @@
 import { ASK_USER_QUESTION_TOOL, contentOf, dialogAnswers, questionsOf } from '../shared/dialog-answers'
 import { isRecord, type JsonObject } from '../shared/json'
+import { CONTENT_BLOCK_TYPE, LOG_ENTRY_TYPE } from '../shared/log-vocabulary'
 
 /**
  * A question of a dialog that ended without an answer, as the hook records it: what was asked, when, from where and
@@ -50,7 +51,7 @@ const asksOf = (entries: readonly JsonObject[]): Ask[] =>
     const askedAt = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
     if (Number.isNaN(askedAt)) return []
     return contentOf(entry)
-      .filter((block) => block.type === 'tool_use' && block.name === ASK_USER_QUESTION_TOOL)
+      .filter((block) => block.type === CONTENT_BLOCK_TYPE.toolUse && block.name === ASK_USER_QUESTION_TOOL)
       .flatMap((block) =>
         typeof block.id === 'string'
           ? questionsOf(block.input).map(({ question }) => ({
@@ -70,7 +71,7 @@ const resultsOf = (entries: readonly JsonObject[]): Map<string, JsonObject | nul
   for (const entry of entries) {
     const answers = isRecord(entry.toolUseResult) && isRecord(entry.toolUseResult.answers) ? entry.toolUseResult.answers : null
     for (const block of contentOf(entry))
-      if (block.type === 'tool_result' && typeof block.tool_use_id === 'string') results.set(block.tool_use_id, answers)
+      if (block.type === CONTENT_BLOCK_TYPE.toolResult &&typeof block.tool_use_id === 'string') results.set(block.tool_use_id, answers)
   }
   return results
 }
@@ -79,7 +80,7 @@ const resultsOf = (entries: readonly JsonObject[]): Map<string, JsonObject | nul
 const wentOnAfter = (ask: Ask, entries: readonly JsonObject[]): boolean =>
   entries
     .slice(ask.position + 1)
-    .some((entry) => (entry.type === 'user' || entry.type === 'assistant') && messageIdOf(entry) !== ask.messageId)
+    .some((entry) => (entry.type === LOG_ENTRY_TYPE.user || entry.type === LOG_ENTRY_TYPE.assistant) && messageIdOf(entry) !== ask.messageId)
 
 /** No answer came back, the answer is not a text for this question, or it only puts the question off. */
 const endedUnanswered = (ask: Ask, results: ReadonlyMap<string, JsonObject | null>, entries: readonly JsonObject[]) => {

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

@@ -5,11 +5,12 @@
  */
 import type { DialogAnswer } from './dialog-answer'
 import { isRecord, type JsonObject } from './json'
+import { CLAUDE_TOOL, CONTENT_BLOCK_TYPE } from './log-vocabulary'
 
 export type { DialogAnswer } from './dialog-answer'
 
 /** The tool name of the dialog, as hook inputs and transcripts carry it. */
-export const ASK_USER_QUESTION_TOOL = 'AskUserQuestion'
+export const ASK_USER_QUESTION_TOOL = CLAUDE_TOOL.askUserQuestion
 
 /** The content blocks of a transcript entry's message; none when it has no list of blocks. */
 export const contentOf = (entry: JsonObject): JsonObject[] => {
@@ -52,7 +53,10 @@ const askedQuestions = (entries: JsonObject[]): Map<string, AskedQuestion[]> =>
     entries
       .filter(isMainThread)
       .flatMap(contentOf)
-      .filter((block) => block.type === 'tool_use' && block.name === ASK_USER_QUESTION_TOOL && typeof block.id === 'string')
+      .filter(
+        (block) =>
+          block.type === CONTENT_BLOCK_TYPE.toolUse && block.name === ASK_USER_QUESTION_TOOL && typeof block.id === 'string',
+      )
       .map((block): [string, AskedQuestion[]] => [block.id as string, questionsOf(block.input)]),
   )
 
@@ -61,7 +65,7 @@ const answersIn = (entry: JsonObject, asked: Map<string, AskedQuestion[]>): Dial
   const answeredAt = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : Number.NaN
   if (!isRecord(answers) || Number.isNaN(answeredAt)) return []
   return contentOf(entry)
-    .filter((block) => block.type === 'tool_result')
+    .filter((block) => block.type === CONTENT_BLOCK_TYPE.toolResult)
     .flatMap((block) => asked.get(String(block.tool_use_id)) ?? [])
     .flatMap(({ question, offered }) => {
       const answer = answers[question]

package/kit/hooks/hooks/shared/log-vocabulary.ts

@@ -0,0 +1,13 @@
+/** The entry types of a Claude Code transcript line that a hook tells apart; the transcript delivers them as strings. */
+export const LOG_ENTRY_TYPE = { user: 'user', assistant: 'assistant' } as const
+
+/** The block types inside an entry's `message.content`. */
+export const CONTENT_BLOCK_TYPE = { text: 'text', toolUse: 'tool_use', toolResult: 'tool_result' } as const
+
+/** The names of Claude Code's tools a hook looks for, in a `tool_use` block or a hook input's `tool_name`. */
+export const CLAUDE_TOOL = {
+  askUserQuestion: 'AskUserQuestion',
+  agent: 'Agent',
+  taskUpdate: 'TaskUpdate',
+  todoWrite: 'TodoWrite',
+} as const

package/kit/hooks/hooks/shared/transcript.ts

@@ -1,4 +1,5 @@
 import { isRecord } from './json'
+import { CONTENT_BLOCK_TYPE, LOG_ENTRY_TYPE } from './log-vocabulary'
 
 export type Turn = { firstPrompt: string; tools: string[] }
 
@@ -37,17 +38,19 @@ const blocks = (entry: Entry): Block[] => {
 
 /** The text a person typed: a string, or text parts. A tool result and the harness's own skill text are no prompt. */
 const promptText = (entry: Entry): string | undefined => {
-  if (entry.type !== 'user' || entry.isMeta === true) return undefined
+  if (entry.type !== LOG_ENTRY_TYPE.user || entry.isMeta === true) return undefined
   const content = entry.message?.content
   if (typeof content === 'string') return content
-  const texts = blocks(entry).flatMap((block) => (block.type === 'text' && typeof block.text === 'string' ? [block.text] : []))
+  const texts = blocks(entry).flatMap((block) =>
+    block.type === CONTENT_BLOCK_TYPE.text && typeof block.text === 'string' ? [block.text] : [],
+  )
   return texts.length > 0 ? texts.join('\n') : undefined
 }
 
 const toolUses = (entry: Entry): ToolUse[] =>
-  entry.type === 'assistant'
+  entry.type === LOG_ENTRY_TYPE.assistant
     ? blocks(entry).flatMap((block) =>
-        block.type === 'tool_use' && typeof block.name === 'string'
+        block.type === CONTENT_BLOCK_TYPE.toolUse && typeof block.name === 'string'
           ? [{ name: block.name, input: isRecord(block.input) ? block.input : {} }]
           : [],
       )

package/kit/hooks/hooks/task-hint/decision.ts

@@ -1,4 +1,5 @@
 import { isRecord } from '../shared/json'
+import { CLAUDE_TOOL } from '../shared/log-vocabulary'
 import { toolUsesOf } from '../shared/transcript'
 
 /**
@@ -41,8 +42,8 @@ export const hasTaskInProgress = (lines: readonly string[]): boolean => {
   let todos = false
   const tasks = new Map<string, boolean>()
   for (const { name, input } of toolUsesOf(lines.join('\n'))) {
-    if (name === 'TodoWrite') todos = todosInProgress(input)
-    if (name === 'TaskUpdate' && input.taskId !== undefined && input.status !== undefined)
+    if (name === CLAUDE_TOOL.todoWrite) todos = todosInProgress(input)
+    if (name === CLAUDE_TOOL.taskUpdate &&input.taskId !== undefined && input.status !== undefined)
       tasks.set(String(input.taskId), input.status === IN_PROGRESS)
   }
   return todos || [...tasks.values()].some(Boolean)

package/kit/hooks/hooks/task-hint/run.ts

@@ -1,14 +1,12 @@
 import { isHintOn } from '../shared/config'
 import { isWithinDirectory } from '../shared/files'
+import { CLAUDE_TOOL } from '../shared/log-vocabulary'
 import { firstPromptOf, isLanePrompt } from '../shared/transcript'
 import { decideTaskHint, hasTaskInProgress, TASK_HINT_SUBAGENT_TEXT, TASK_HINT_TEXT } from './decision'
 
 /** An Edit, Write or Agent call as the hook receives it: the session, its directory, its transcript and the tool. */
 export type TaskHintCall = { session: string; cwd: string; transcriptPath: string; tool: string }
 
-/** The tool that starts a subagent. */
-const SUBAGENT_TOOL = 'Agent'
-
 /** Everything with a side effect, passed in so a test reaches the flow without git, files or a home directory. */
 export type TaskHintDependencies = {
   mainCheckoutOf: (cwd: string) => string
@@ -34,7 +32,7 @@ const hintFor = (call: TaskHintCall, dependencies: TaskHintDependencies): string
   const main = dependencies.mainCheckoutOf(call.cwd)
   const worktree = dependencies.repositoryRootOf(call.cwd)
   const hinted = dependencies.readMark(main, call.session)
-  const subagent = call.tool === SUBAGENT_TOOL
+  const subagent = call.tool === CLAUDE_TOOL.agent
   const decision = decideTaskHint({
     enabled: isHintOn(dependencies.configs(main), 'taskSignal'),
     lane: isLanePrompt(firstPromptOf(dependencies.readHead(call.transcriptPath).join('\n'))),

package/kit/rules/rules/kit/pull-requests.md

@@ -8,6 +8,7 @@ How an agent opens a pull request so every PR reads consistently and is review-
 - **Base = `{{kit.baseBranch}}`** unless the user names another.
 - **Work on a branch.** If the working branch is `{{kit.baseBranch}}`, branch first.
 - **Push before creating, with the user's go-ahead for the push.** The head branch must be on the remote so `gh pr create` has a target.
+- **Drafts:** Opening as a draft is **{{kit.merge.openAsDraft}}** (`merge.openAsDraft`); `on` opens every PR with `gh pr create --draft`; you turn it ready (`gh pr ready <n>`) once it goes to merge.
 - **Check for an existing PR first** (`gh pr view <branch>`). If a prior PR for the same branch is already **merged**, the new one is a continuation — mark it in the title.
 
 ## Title

package/kit/workflow/skills/orchestrate/SKILL.md

@@ -60,6 +60,9 @@ Each file under `references/` is read when its trigger fires: the step or the ev
       `origin/{{kit.baseBranch}}` would not have it: § 2 step 0. New rows of a board that is on the base
       branch need nothing; the herd shows them. Check a plan that joins the board later the same way; one
       only a working lane's worktree has, the watcher reports as `plan missing`.
+- [ ] **Every plan meets the contract.** `jh plan check <plan>` for each plan a starting lane links. Exit 1,
+      or a row that links an issue or a `.scratch/` folder instead of a plan file: [`references/adopt-plan.md`](references/adopt-plan.md),
+      before § 2 step 0. Exit 2 goes to the user. Done when each check exits 0.
 - [ ] Tell the user which lanes start now and which wait, before starting any, and whether § 2 step 0
       is needed.
 
@@ -84,7 +87,8 @@ stay approval-bound (§ 5, § 6).
 When the user wants a plan's lanes merged without a question for a while: § 5, **Standing approval**.
 
 0. **Plan commit as the base**, when § 0 found the board or a plan missing on
-   `origin/{{kit.baseBranch}}`. Ask through `AskUserQuestion`: commit the missing files on a
+   `origin/{{kit.baseBranch}}`, or adopted a plan (then the diff round of
+   [`references/adopt-plan.md`](references/adopt-plan.md) is this question; ask nothing more). Ask through `AskUserQuestion`: commit the missing files on a
    documentation branch and open a documentation PR, so the lanes start from that commit? The answer
    is the approval of that commit, its push and the PR (§ 5). `<topic>` is the plan's file name
    without date and extension, or the board's directory name when several files are missing. On yes,
@@ -99,7 +103,7 @@ When the user wants a plan's lanes merged without a question for a while: § 5,
    your judgement.
 2. **Worktree workspace** from `<base>`: `origin/{{kit.baseBranch}}` when, after
    `git fetch origin {{kit.baseBranch}}`, `git cat-file -e origin/{{kit.baseBranch}}:<plan>` succeeds
-   for the lane's plan, else `origin/docs/plan-<topic>` of step 0. The file decides, not the state of
+   for the lane's plan and `git diff --quiet origin/{{kit.baseBranch}} -- <plan>` exits 0, else `origin/docs/plan-<topic>` of step 0. The file decides, not the state of
    the PR, so a later lane gets the right base:
    ```bash
    herdr worktree create --cwd <main-checkout> --branch <branch> --base <base> \
@@ -133,12 +137,16 @@ When the user wants a plan's lanes merged without a question for a while: § 5,
    within a poll or two: `bunx jackherd herd --ensure`.
 8. **Prompt** from the file of § 1:
    ```bash
-   herdr agent prompt <lane> "$(cat <prompt-file>)"
+   herdr agent prompt <lane> "$(cat <prompt-file>)" --wait --until working --timeout 30000
    ```
    The prompt quotes commands in backticks (`git reset`, `/pre-commit`); typed into the command
    line inside double quotes, your own shell would run them before the lane sees the text. Text
    read through `$(cat …)` is not expanded again. Every `herdr agent prompt` in this skill goes
-   this way, from a file you wrote with the `Write` tool or `jh lane prompt` wrote.
+   this way, from a file you wrote with the `Write` tool or `jh lane prompt` wrote, with the same
+   `--wait` options, so the lane confirms it started. `agent_prompt_stalled` or `timeout` does not prove the
+   text is lost: read the screen (`herdr agent read <lane> --source visible --lines 12`). Text still in the input
+   line: `herdr agent send-keys <lane> enter`; a lane already at work: done; neither: send the file once more,
+   same command. A second stall goes to the user.
 
 ## 3. Dev server
 
@@ -242,7 +250,7 @@ On wake-up:
 | `blocked` | Read the screen (`--source detection`, or zoom the pane when cut off). A question is vetted (below, **Settled questions stay in the lane**): one the plan or a rule settles you answer in the lane, an open decision goes to the user via `AskUserQuestion`. You never hand the lane's pane to the user. A question dialog in a lane (not a permission dialog) is a gap in the lane prompt (§ 1): send it the text-block rule and the answer by prompt. A permission dialog for a step on the list in § 5 you confirm, after checking the cursor sits on the one-time option; anything else goes to the user. Dim text in the input line is a suggestion, not input (`--format ansi` shows `\e[2m`); in a multi-select dialog `space` toggles an option, `enter` moves on. The watcher prints a duty line for each blocked lane; it is done when the lane has its answer or the user has the question |
 | `working` with `questions: <n>` | The lane changed the questions of its report while its subagents run. Read `report <path>` and close each new question as the `done` / `idle` row does (`jh settled`, or `AskUserQuestion` with the answer sent on by `herdr agent prompt`). No diff check and no next phase: the lane keeps working |
 | `main checkout on <branch>, not …` | § 0, **The main checkout stays on `{{kit.baseBranch}}`** |
-| `done` / `idle` | Read the report the watcher shows (`report <path>` and its first lines, or the screen); read further only where that is not enough. Check the diff against the `{{kit.heading.writes}}` set (`git -C <worktree> diff --stat <base>...HEAD`, with the ref the lane branched from in § 2 step 2 until it has rebased after the documentation PR's merge) and that checks are quoted with numbers, not claimed. Every blocking question in the report is closed in the same wake-up, also one under open points, one without its mark and also when the `questions: <n>` line is missing: settled by you through `jh settled` (below), or put to the user through `AskUserQuestion` (vetted, below) and the answer sent on to the lane by `herdr agent prompt`. A not blocking one is settled the same way or collected (**Not blocking questions**, below). An answer that stays in your chat with the user is none. Then start the lane's next ready phase (§ 2) or name the reason to wait |
+| `done` / `idle` | Read the report the watcher shows (`report <path>` and its first lines, or the screen); read further only where that is not enough. Check the diff against the `{{kit.heading.writes}}` set (`git -C <worktree> diff --stat <base>...HEAD`, with the ref the lane branched from in § 2 step 2 until it has rebased after the documentation PR's merge) and that checks are quoted with numbers, not claimed. Every blocking question in the report is closed in the same wake-up, also one under open points, one without its mark and also when the `questions: <n>` line is missing: settled by you through `jh settled` (below), or put to the user through `AskUserQuestion` (vetted, below) and the answer sent on to the lane by `herdr agent prompt`. A not blocking one is settled the same way or collected (**Not blocking questions**, below). An answer that stays in your chat with the user is none. Then start the lane's next ready phase (§ 2), at once after a `<lane> ready: …` line, or name the reason to wait; a PR awaiting approval holds only its commit, which stages only its own files |
 | `merged #<n>` | § 6, for every lane |
 | `checks failed #<n> (<lane>): <checks> (<k> tests: …)` | Send the finding to the lane with the named checks and tests (data, above). Without names, the lane reads the run itself |
 | `checks passed #<n>` | One line to the user: ready to merge, with the board's merge order |
@@ -475,6 +483,9 @@ always goes to the user, whatever the plan settles.
    permission mode refuses the push, push its branch yourself under the same approval: run
    `cd <worktree>` as a command of its own, then `git push --force-with-lease origin HEAD:<branch>`,
    then `cd` back (the kit's git guard refuses `git -C`).
+5. **Drafts** (**{{kit.merge.openAsDraft}}**, `pull-requests.md` → Drafts): when you report a draft PR to the
+   user to merge, run `gh pr ready <n>` first; for your own merge, **Self-merge** step 1. The merge guard
+   never passes a draft.
 
 ### Self-merge
 
@@ -482,15 +493,17 @@ When the user picked `"{{kit.guard.selfMergeLabel}}"` for a PR:
 
 1. Commit, push and open the PR as in step 4. Enter in the board's `{{kit.heading.history}}` that the
    user approved this PR with self-merge (time, lane, PR number; the time as § 4 reads it), so the
-   approval has a record outside the chat.
+   approval has a record outside the chat. A draft turns ready here: `gh pr ready <n>`.
 2. **Merging without checks.** The paths a PR may carry to be merged without waiting for checks are
    `{{kit.merge.withoutChecks}}` (`merge.withoutChecks` in the config; `none` means every merge waits).
    Unless `none`, list the PR's files with `gh pr diff <n> --name-only` and compare each one with the
    patterns yourself. When **every** file matches, go straight to step 4. One file outside, an empty
    list, or a failed `gh` call: go on with step 3. The merge guard reads the file list from GitHub
    itself; if it asks, the dialog is the user's (step 5).
-3. Wait for the checks in the background, never in the foreground: a Bash call
-   `gh pr checks <n> --watch` with `run_in_background: true`, then work on until it reports.
+3. Wait for the checks in the background, never in the foreground. After a ready (step 1), start only
+   once every check that counts (each of `guard.requiredChecks`, else each check the draft skipped) has
+   a run that started after the ready, as a watch would end on the draft's skipped runs at once. Then a Bash call
+   `gh pr checks <n> --watch` with `run_in_background: true`, and work on until it reports.
 4. Green (or a PR that qualified in step 2): `gh pr merge <n> --squash --delete-branch --match-head-commit <sha>`,
    with the plain PR number, the full `headRefOid` from `gh pr view <n> --json headRefOid` read right before, and
    without `-R`, `--repo` or `--admin`. The merge guard lets exactly this command through for the approved branch
@@ -531,7 +544,7 @@ For a PR the user approved (step 2) whose lane works on a plan under a standing
 
 1. A PR behind the base branch is rebased first (§ 6, under the PR's approval), so its checks run
    against the current base.
-2. Wait for the checks as in **Self-merge** step 3.
+2. Turn a draft ready as in **Self-merge** step 1, then wait for the checks as in its step 3.
 3. Green: the same command as **Self-merge** step 4, with the `<sha>` read right before. The merge
    guard lets it through only before the approval's end, with every check green, GitHub able to merge
    it and no workflow, migration, env file or file of the guards in it; otherwise it asks, and that dialog is the user's