jackherd 1.16.0 → 1.17.0

package/src/resume/targets.ts

@@ -0,0 +1,84 @@
+import { isRecord } from '../shared/is-record'
+import { parseJsonOrNull } from '../shared/parse-json'
+
+/** One pane an agent runs in, from herdr's lists; `name` is null while herdr names none. */
+export type AgentPane = { pane: string; name: string | null; cwd: string | null }
+
+export const TARGET_MISS = { missing: 'missing', ambiguous: 'ambiguous', elsewhere: 'elsewhere' } as const
+
+export type TargetMiss = (typeof TARGET_MISS)[keyof typeof TARGET_MISS]
+
+/** No agent to send to, with the panes that made it ambiguous or carry the name in another directory. */
+export type TargetMissed = { kind: 'none'; reason: TargetMiss; panes: string[] }
+
+/** Where a message goes: the agent's name or its pane id, `byName` when herdr named it. */
+export type Target = { kind: 'found'; target: string; byName: boolean } | TargetMissed
+
+/** The one unnamed pane found in the directory so far, and in how many polls in a row. */
+export type Streak = { pane: string; polls: number } | null
+
+/**
+ * How many polls in a row the one unnamed agent pane of a directory must stay the only one before it gets the message:
+ * herdr brings the sessions back one after the other within seconds, and a pane that is alone at first may be the
+ * user's other session, with the named one still to come. Five polls of two seconds are past the ~8 s the
+ * coordinator's session took after a crash (`RESTORE_LIMITS`).
+ */
+export const STEADY_POLLS = 5
+
+const entriesOf = (json: string, key: 'agents' | 'panes'): Record<string, unknown>[] => {
+  const answer = parseJsonOrNull(json)
+  const result = isRecord(answer) ? answer.result : undefined
+  const entries = isRecord(result) ? result[key] : undefined
+  return Array.isArray(entries) ? entries.filter(isRecord) : []
+}
+
+const stringOrNull = (value: unknown): string | null => (typeof value === 'string' ? value : null)
+
+/**
+ * The agent panes of `herdr agent list` and `herdr pane list`, each once; none from an answer that cannot be read.
+ * Right after a restart the pane list names no agent for a few seconds while the agent list already does, and the
+ * other way round, so a pane counts when either list names its agent. Tolerant, unlike `agentPanesOf` of
+ * `src/plans/plan-panes.ts`: a hook never throws over herdr's answer.
+ */
+export const resumablePanesOf = (agentList: string, paneList: string): AgentPane[] => {
+  const found = new Map<string, AgentPane>()
+  for (const { pane_id, name, cwd } of entriesOf(agentList, 'agents'))
+    if (typeof pane_id === 'string')
+      found.set(pane_id, { pane: pane_id, name: stringOrNull(name), cwd: stringOrNull(cwd) })
+  for (const { pane_id, agent, cwd } of entriesOf(paneList, 'panes')) {
+    if (typeof pane_id !== 'string' || (typeof agent !== 'string' && !found.has(pane_id))) continue
+    const known = found.get(pane_id)
+    found.set(pane_id, { pane: pane_id, name: known?.name ?? null, cwd: known?.cwd ?? stringOrNull(cwd) })
+  }
+  return [...found.values()]
+}
+
+const missed = (reason: TargetMiss, panes: string[]): TargetMissed => ({ kind: 'none', reason, panes })
+
+/**
+ * The agent to send to: the one named `name` when it runs in `directory` (the main checkout for the coordinator, the
+ * worktree for a lane) or herdr names no directory; the name in another directory belongs to another repository's
+ * agent. Without the name, the one unnamed agent pane in `directory`: an agent with another name there is another
+ * agent, a helper of the lane for one, and two unnamed panes are never guessed between.
+ */
+export const targetFor = (panes: readonly AgentPane[], name: string, directory: string): Target => {
+  const named = panes.find((pane) => pane.name === name)
+  if (named)
+    return named.cwd === null || named.cwd === directory
+      ? { kind: 'found', target: name, byName: true }
+      : missed(TARGET_MISS.elsewhere, [named.pane])
+  const candidates = panes.filter((pane) => pane.name === null && pane.cwd === directory).map(({ pane }) => pane)
+  if (candidates.length === 1) return { kind: 'found', target: candidates[0] as string, byName: false }
+  return missed(candidates.length === 0 ? TARGET_MISS.missing : TARGET_MISS.ambiguous, candidates)
+}
+
+/**
+ * The target of one poll once it can be trusted: a named agent at once, the one unnamed pane only after it stayed
+ * alone for `STEADY_POLLS` polls in a row; until then it counts as missing. Returns the streak for the next poll.
+ */
+export const steadyTarget = (target: Target, streak: Streak): { target: Target; streak: Streak } => {
+  if (target.kind === 'none' || target.byName) return { target, streak: null }
+  const polls = streak?.pane === target.target ? streak.polls + 1 : 1
+  const next = { pane: target.target, polls }
+  return { target: polls >= STEADY_POLLS ? target : missed(TARGET_MISS.missing, []), streak: next }
+}

package/src/resume/texts.ts

@@ -0,0 +1,27 @@
+import { PLAN_LANGUAGE, type PlanLanguage } from '../vocabulary'
+
+/** The fixed words `jh resume` sends; nothing else from outside reaches a session but checked lane names and the board. */
+export type ResumeTexts = {
+  /** One line, no break: herdr would send a break as an enter and split the command. */
+  coordinatorLine: (board: string, interrupted: readonly string[], blocked: readonly string[]) => string
+  laneText: string
+}
+
+const listed = (lanes: readonly string[], none: string): string => (lanes.length > 0 ? lanes.join(', ') : none)
+
+const TEXTS: Record<PlanLanguage, ResumeTexts> = {
+  [PLAN_LANGUAGE.de]: {
+    coordinatorLine: (board, interrupted, blocked) =>
+      `/orchestrate ${board} Neustart nach Absturz: Watcher starten (§ 4), Wecker mit den Terminen abgleichen; fortgesetzt: ${listed(interrupted, 'keine')}; vor dem Absturz blockiert: ${listed(blocked, 'keine')}.`,
+    laneText:
+      'Der Rechner ist abgestürzt und herdr wurde neu gestartet. Dein letzter Befehl wurde unterbrochen: prüfe, wie weit er kam, und setze ihn fort.',
+  },
+  [PLAN_LANGUAGE.en]: {
+    coordinatorLine: (board, interrupted, blocked) =>
+      `/orchestrate ${board} Restart after a crash: start the watcher (§ 4), match the timers against the appointments; resumed: ${listed(interrupted, 'none')}; blocked before the crash: ${listed(blocked, 'none')}.`,
+    laneText:
+      'The computer crashed and herdr was restarted. Your last command was interrupted: check how far it got, and carry on with it.',
+  },
+}
+
+export const resumeTexts = (language: PlanLanguage): ResumeTexts => TEXTS[language]

package/src/secrets/command.ts

@@ -1,4 +1,5 @@
-import { configuredSources } from '../config/personal-sources'
+import { configuredSources, type ExcludedSource, type MergedSources } from '../config/personal-sources'
+import { readRepositoryIdentity } from '../config/repository-identity'
 import { errorText } from '../plans/error-text'
 import { mainCheckout, worktreeRoot } from '../plans/git'
 import { CLI_NAME } from '../version/release'
@@ -17,7 +18,7 @@ export type SecretPorts = {
   /** The value typed after `prompt`, hidden; null when cancelled. */
   readHidden: (prompt: string) => Promise<string | null>
   /** The sources of the repository and the personal file, with the notes of their merge. */
-  sources: () => { sources: SourceSettings[]; notes: string[] }
+  sources: () => MergedSources
   environment: Environment
   out: (line: string) => void
   err: (line: string) => void
@@ -33,6 +34,12 @@ const SIGNAL_EXIT = 130
 
 const NO_TERMINAL = `${CLI_NAME} secret set reads the value from a terminal only, never from a pipe: run it in a terminal of your own`
 
+/** A source left out for its `repos`, named in the listing with the reason, so its secrets show where they are needed. */
+const excludedAsListed = ({ source, reason }: ExcludedSource): SourceSettings => ({
+  ...source,
+  name: `${source.name} (${reason})`,
+})
+
 /**
  * Reads one hidden value from the terminal: raw mode, nothing echoed, each chunk applied by `hiddenInputStep`. The
  * terminal is given back on every end, the process's `exit` included.
@@ -82,7 +89,10 @@ const terminalPorts = (): SecretPorts => ({
   store: secretStore(),
   isTerminal: () => process.stdin.isTTY === true,
   readHidden: readHiddenFromTerminal,
-  sources: () => configuredSources([worktreeRoot(process.cwd()), mainCheckout(process.cwd())]),
+  sources: () => {
+    const root = mainCheckout(process.cwd())
+    return configuredSources([worktreeRoot(process.cwd()), root], readRepositoryIdentity(root))
+  },
   environment: process.env,
   out: (line) => console.log(line),
   err: (line) => console.error(line),
@@ -107,9 +117,9 @@ const setSecret = async (name: string, ports: SecretPorts): Promise<number> => {
 }
 
 const listSecrets = async (ports: SecretPorts): Promise<number> => {
-  const { sources, notes } = ports.sources()
+  const { sources, notes, excluded } = ports.sources()
   for (const note of notes) ports.err(note)
-  const required = requiredSecrets(sources)
+  const required = requiredSecrets([...sources, ...excluded.map(excludedAsListed)])
   const lookups = await Promise.all(required.map(({ name, keychain }) => (keychain ? ports.store.get(name) : null)))
   const rows = required.map((secret, index) => {
     const lookup = lookups[index] ?? { kind: SECRET_LOOKUP.absent }

package/src/sync/herdr-plugin.ts

@@ -1,6 +1,6 @@
 import { realpathSync } from 'node:fs'
 import { join, resolve } from 'node:path'
-import { isLinkedWorktree, mainCheckout } from '../plans/git'
+import { isLinkedWorktree, mainCheckoutOrNull } from '../plans/git'
 import { herdrBinary, spawnTool, type ToolRun } from './tools'
 
 export const HERDR_PLUGIN_ID = 'crossdelta.jackherd'
@@ -161,15 +161,6 @@ const realPathOf = (path: string): string => {
   }
 }
 
-/** The repository a path belongs to (its main checkout, also from a linked worktree); null outside git. */
-const repositoryOf = (path: string): string | null => {
-  try {
-    return mainCheckout(path)
-  } catch {
-    return null
-  }
-}
-
 /**
  * A checkout takes over only at home: when the project lies in the checkout's own repository. For another repository
  * (or a project outside git) it acts like an installed package, so `init` there does not move the link.
@@ -181,7 +172,7 @@ export const checkoutCopyFor = (projectRepository: string | null, packageReposit
 const packageCopyOf = (packageRoot: string, projectRoot: string): PackageCopy => {
   if (isLinkedWorktree(packageRoot)) return PACKAGE_COPY.laneWorktree
   if (isInstalledCopy(realPathOf(packageRoot))) return PACKAGE_COPY.installed
-  return checkoutCopyFor(repositoryOf(projectRoot), repositoryOf(packageRoot))
+  return checkoutCopyFor(mainCheckoutOrNull(projectRoot), mainCheckoutOrNull(packageRoot))
 }
 
 export const linkHerdrPluginFrom = ({

package/src/sync/plan-ask-rules.ts

@@ -32,6 +32,17 @@ export const SHIPPED_ASK_RULES: readonly string[] = [
   'Bash(gh api *dispatches*)',
   'Bash(gh api *rerun*)',
   'Bash(gh api *git/refs*)',
+  'Bash(gh api *mergePullRequest*)',
+  'Bash(gh api *mergeBranch*)',
+  'Bash(gh api *enablePullRequestAutoMerge*)',
+  'Bash(gh api *enqueuePullRequest*)',
+  'Bash(gh api *createCommitOnBranch*)',
+  'Bash(gh api *createRef*)',
+  'Bash(gh api *updateRef*)',
+  'Bash(gh api *deleteRef*)',
+  'Bash(gh api *rerequestCheckSuite*)',
+  'Bash(gh api *graphql*query=@*)',
+  'Bash(gh api *graphql*--input*)',
   'Bash(jh lane close*)',
   'Bash(jackherd lane close*)',
   'Bash(bunx jackherd* lane close*)',

package/src/sync/render.ts

@@ -5,6 +5,7 @@ import {
   APPROVAL_TEXTS,
   LANGUAGE_NAME,
   PLAN_VOCABULARY,
+  RECOMMENDED_MARK,
   SELF_MERGE_LABEL,
   STANDING_APPROVAL_TEXTS,
 } from '../vocabulary'
@@ -51,6 +52,7 @@ const placeholderValues = (config: JackherdConfig): Map<string, string> => {
     ['kit.guard.selfMerge', config.guard.selfMerge.offer ? 'offered' : 'not offered'],
     ...prefixed('guard.standingApproval', STANDING_APPROVAL_TEXTS[config.responseLanguage]),
     ...prefixed('approval', APPROVAL_TEXTS[config.responseLanguage]),
+    ['kit.question.recommended', RECOMMENDED_MARK[config.responseLanguage]],
     ['kit.merge.withoutChecks', checkFreeList(config.merge.withoutChecks)],
     ['kit.merge.openAsDraft', config.merge.openAsDraft ? 'on' : 'off'],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
@@ -64,7 +66,7 @@ export const listPlaceholders = (template: string): string[] =>
 /**
  * Fills the kit placeholders from the project config: `{{kit.model.<role>}}`,
  * `{{kit.command.<test|typecheck|lint|format|install|dev>}}`, `{{kit.lanes.<copyCommand|lockFile|verifyInstall>}}`, `{{kit.word.<laneClosed|openSubagents>}}`,
- * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.merge.<withoutChecks|openAsDraft>}}`, `{{kit.heading.<key>}}` from the plan
+ * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.question.recommended}}`, `{{kit.merge.<withoutChecks|openAsDraft>}}`, `{{kit.heading.<key>}}` from the plan
  * vocabulary, the two languages, `{{kit.responseAddress}}`, the plan and worktree directory and the base branch. A
  * command or lock file the config leaves unset renders as `unsetValueText`, never as a guessed default. Other
  * `{{…}}` text is left alone; an unknown `kit.` placeholder throws rather than reaching a project

package/src/vocabulary/index.ts

@@ -49,6 +49,15 @@ export const STANDING_APPROVAL_TEXTS: Record<PlanLanguage, { approve: string; un
   [PLAN_LANGUAGE.de]: { approve: 'Stehend freigeben', until: 'bis' },
 }
 
+/**
+ * The mark at the end of the first option's label that says it is the recommendation. The plain question hook sends
+ * a dialog back whose first option lacks it, so it is fixed per language and not a config value.
+ */
+export const RECOMMENDED_MARK: Record<PlanLanguage, string> = {
+  [PLAN_LANGUAGE.en]: '(recommended)',
+  [PLAN_LANGUAGE.de]: '(Empfohlen)',
+}
+
 /**
  * The words a lane prompt opens with, followed by the lane's name. The ask hint hook and the project's lane exception
  * recognise a lane by them, so they are fixed per language and not a config value.
@@ -183,6 +192,8 @@ export type PlanVocabulary = {
   noReviewGate: string
   /** Marks a lane as closed when its name cell contains it. */
   laneClosed: string
+  /** Stands in a board row's phases cell when that pull request builds only part of the phase. */
+  partialPhase: string
   /** Opens the line a lane's hand-over file must hold as `<word>: 0`, so the coordinator hands over only after a wave. */
   openSubagents: string
   /** Words a starts-after cell begins with when the lane may start at once. */
@@ -220,6 +231,7 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     phase: 'Phase',
     noReviewGate: 'Kein Review-Gate',
     laneClosed: 'abgeräumt',
+    partialPhase: '(Teil)',
     openSubagents: 'offene Sub-Agenten',
     sideOrderMarker: 'dazu (User',
     startsNow: ['sofort'],
@@ -254,6 +266,7 @@ export const PLAN_VOCABULARY: Record<PlanLanguage, PlanVocabulary> = {
     phase: 'Phase',
     noReviewGate: 'No review gate',
     laneClosed: 'cleaned up',
+    partialPhase: '(part)',
     openSubagents: 'open subagents',
     sideOrderMarker: 'also (User',
     startsNow: ['now', 'immediately'],

package/src/waiting/command.ts

@@ -1,3 +1,4 @@
+import { installedReferenceHint } from '../lane/skill-hint'
 import { terminalSafe } from '../plan-format/terminal-text'
 import type { WaitingItem } from '../plan-format/waiting'
 import { mainCheckout } from '../plans/git'
@@ -5,14 +6,18 @@ import { closeAllQuestionRecords, closeQuestionRecords } from '../plans/question
 import { closeAllSentRecords, closeSentRecords } from '../plans/sent-files-read'
 import { recordWaitingItems } from '../plans/waiting-records'
 import { CLI_NAME } from '../version/release'
+import { REFERENCE, referenceLine } from '../watch/reference-paths'
 
 const USAGE = `usage: ${CLI_NAME} waiting [close <id> ... | close --all]`
 
-/** The lines `jh waiting` prints: id, time and text of each item, made safe for the terminal; a note when none waits. */
-export const waitingListing = (items: readonly WaitingItem[]): string[] =>
+/**
+ * The lines `jh waiting` prints: id, time and text of each item, made safe for the terminal, then the reference that
+ * holds how to put them to the user (`hint`, none without the skill); a note when none waits.
+ */
+export const waitingListing = (items: readonly WaitingItem[], hint = ''): string[] =>
   items.length === 0
     ? ['nothing waits on you']
-    : items.map(({ since, item, id }) => terminalSafe(`${id} · ${since} · ${item}`))
+    : [...items.map(({ since, item, id }) => terminalSafe(`${id} · ${since} · ${item}`)), ...referenceLine(hint)]
 
 const CLOSE_ALL = '--all'
 
@@ -32,7 +37,11 @@ export const closeAllWaiting = (root: string, now: number): number =>
 export const run = async (args: string[]): Promise<number> => {
   const root = mainCheckout(process.cwd())
   if (args.length === 0) {
-    for (const line of waitingListing(recordWaitingItems(root, Date.now()))) console.log(line)
+    for (const line of waitingListing(
+      recordWaitingItems(root, Date.now()),
+      installedReferenceHint(root, REFERENCE.waiting),
+    ))
+      console.log(line)
     return 0
   }
   const [command, ...rest] = args