jackherd 1.9.0 → 1.10.0

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

@@ -0,0 +1,94 @@
+import { HOOK_OUTCOME, type HookOutcome } from './plan-hooks'
+import type { Settings } from './settings-hooks'
+
+export type AskRulesInput = {
+  /** The `permissions.ask` rules the kit ships. */
+  kit: readonly string[]
+  /** The rules sync put into the settings before, from the lock. */
+  recorded: readonly string[]
+  settings: Settings
+  /** `--accept .claude/settings.json`: put back a kit rule the user removed. */
+  accept: boolean
+}
+
+export type AskRulesPlan = {
+  settings: Settings
+  changed: boolean
+  /** What the lock records next: every kit rule, a removed one included, so it is not added again. */
+  recorded: string[]
+  outcomes: { name: string; outcome: HookOutcome }[]
+  accepted: boolean
+}
+
+/**
+ * Every rule a jackherd kit has ever shipped in an `ask-rules.json`. Only these are ever removed: a lock is a file in
+ * the project, and a rule it lists that no kit shipped (a tampered lock) stays where it is. Add, never remove.
+ */
+export const SHIPPED_ASK_RULES: readonly string[] = [
+  'Bash(gh run rerun *)',
+  'Bash(gh api *pulls/*/merge*)',
+  'Bash(gh api *merges*)',
+  'Bash(gh api *contents/*)',
+  'Bash(gh api *dispatches*)',
+  'Bash(gh api *rerun*)',
+  'Bash(gh api *git/refs*)',
+  'Bash(jh lane close*)',
+  'Bash(jackherd lane close*)',
+  'Bash(bunx jackherd* lane close*)',
+  'Bash(bun */cli.ts lane close*)',
+  'Bash(bunx jh lane close*)',
+  'Bash(bun x jackherd* lane close*)',
+]
+
+/** How a rule shows in the sync report, beside the hooks. */
+export const askRuleName = (rule: string): string => `permissions.ask ${rule}`
+
+const askOf = (settings: Settings): string[] => {
+  const permissions = settings.permissions
+  const ask =
+    typeof permissions === 'object' && permissions !== null ? (permissions as { ask?: unknown }).ask : undefined
+  return Array.isArray(ask) ? ask.filter((rule): rule is string => typeof rule === 'string') : []
+}
+
+/** The settings with this ask list; an emptied list, and permissions it empties, disappear. Returns a copy. */
+const withAsk = (settings: Settings, ask: string[]): Settings => {
+  const { permissions: _old, ...rest } = settings
+  const { ask: _list, ...otherPermissions } = (settings.permissions ?? {}) as Record<string, unknown>
+  const permissions = ask.length > 0 ? { ...otherPermissions, ask } : otherPermissions
+  return Object.keys(permissions).length > 0 ? { ...rest, permissions } : rest
+}
+
+const outcomeOf = (rule: string, input: AskRulesInput, present: ReadonlySet<string>): HookOutcome => {
+  const shipped = input.kit.includes(rule)
+  if (!shipped)
+    return present.has(rule) && SHIPPED_ASK_RULES.includes(rule) ? HOOK_OUTCOME.removed : HOOK_OUTCOME.dropped
+  if (present.has(rule)) return HOOK_OUTCOME.unchanged
+  if (!input.recorded.includes(rule)) return HOOK_OUTCOME.created
+  return input.accept ? HOOK_OUTCOME.accepted : HOOK_OUTCOME.deselected
+}
+
+const ADDING: readonly HookOutcome[] = [HOOK_OUTCOME.created, HOOK_OUTCOME.accepted]
+
+/**
+ * Merges the kit's ask rules into `permissions.ask`, the way `planHooks` merges hooks. Pure. Only a rule the lock
+ * records and some kit shipped (`SHIPPED_ASK_RULES`) is ever removed, and only once the kit stops shipping it; every other entry stays where it is. A kit rule
+ * the user removed is not put back unless `accept` is set.
+ */
+export const planAskRules = (input: AskRulesInput): AskRulesPlan => {
+  const before = askOf(input.settings)
+  const present = new Set(before)
+  const rules = [...new Set([...input.kit, ...input.recorded])]
+  const decided = rules.map((rule) => ({ rule, outcome: outcomeOf(rule, input, present) }))
+  const removed = new Set(decided.filter(({ outcome }) => outcome === HOOK_OUTCOME.removed).map(({ rule }) => rule))
+  const added = decided.filter(({ outcome }) => ADDING.includes(outcome)).map(({ rule }) => rule)
+  const changed = removed.size > 0 || added.length > 0
+  return {
+    settings: changed
+      ? withAsk(input.settings, [...before.filter((rule) => !removed.has(rule)), ...added])
+      : input.settings,
+    changed,
+    recorded: [...input.kit],
+    outcomes: decided.map(({ rule, outcome }) => ({ name: askRuleName(rule), outcome })),
+    accepted: decided.some(({ outcome }) => outcome === HOOK_OUTCOME.accepted),
+  }
+}

package/src/sync/plan-hooks.ts

@@ -47,6 +47,8 @@ export type HooksPlan = {
   kitNewRecorded: string | undefined
   /** `--accept` was given for the settings but no hook was in conflict or deselected. */
   notAcceptable: boolean
+  /** The kit's `permissions.ask` rules the lock records next (`planAskRules`); none outside a project install. */
+  askRules?: string[]
 }
 
 type HookDecision = {

package/src/sync/render.ts

@@ -4,9 +4,9 @@ import {
   ADDRESS_FORM,
   APPROVAL_TEXTS,
   LANGUAGE_NAME,
-  PLAN_APPROVAL_LABELS,
   PLAN_VOCABULARY,
   SELF_MERGE_LABEL,
+  STANDING_APPROVAL_TEXTS,
 } from '../vocabulary'
 
 const PLACEHOLDER = /\{\{\s*(kit\.[A-Za-z0-9_.-]*)\s*\}\}/g
@@ -47,7 +47,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('guard.planApproval', PLAN_APPROVAL_LABELS[config.responseLanguage]),
+    ...prefixed('guard.standingApproval', STANDING_APPROVAL_TEXTS[config.responseLanguage]),
     ...prefixed('approval', APPROVAL_TEXTS[config.responseLanguage]),
     ['kit.merge.withoutChecks', checkFreeList(config.merge.withoutChecks)],
     ...prefixed('heading', { ...header, ...sections, ...columns, phase }),
@@ -61,7 +61,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.planApproval.<approve|revoke>}}`, `{{kit.merge.withoutChecks}}`, `{{kit.heading.<key>}}` from the plan
+ * `{{kit.board.<pattern|file|term>}}`, `{{kit.guard.<selfMerge|selfMergeLabel>}}`, `{{kit.guard.standingApproval.<approve|until>}}`, `{{kit.merge.withoutChecks}}`, `{{kit.heading.<key>}}` from the plan
  * vocabulary, the two languages, `{{kit.responseAddress}}`, the plan and worktree directory and the base branch. Other
  * `{{…}}` text is left alone; an unknown `kit.` placeholder throws rather than reaching a project
  * file unrendered. `overrides` win over the config: a global kit renders what each repository decides as

package/src/sync/settings-hooks.ts

@@ -25,7 +25,10 @@ const hookGroupSchema = z.looseObject({
   hooks: z.array(z.record(z.string(), z.unknown())),
 })
 
-const settingsSchema = z.looseObject({ hooks: z.record(z.string(), z.array(hookGroupSchema)).optional() })
+const settingsSchema = z.looseObject({
+  hooks: z.record(z.string(), z.array(hookGroupSchema)).optional(),
+  permissions: z.looseObject({ ask: z.array(z.string()).optional() }).optional(),
+})
 
 export const parseSettings = (raw: unknown): SettingsResult => {
   const parsed = settingsSchema.safeParse(raw)

package/src/sync/sync-plan.ts

@@ -115,6 +115,7 @@ export const nextManifest = (kitVersion: string, files: FilePlan[], hooks: Hooks
     kitVersion,
     files: Object.fromEntries(files.flatMap(({ path, entry }) => (entry ? [[path, entry]] : []))),
     hooks: hooks.entries,
+    ...(hooks.askRules !== undefined && hooks.askRules.length > 0 ? { askRules: hooks.askRules } : {}),
   }
   return hooks.kitNewRecorded === undefined ? manifest : { ...manifest, settingsKitNew: hooks.kitNewRecorded }
 }

package/src/sync/sync.ts

@@ -15,6 +15,7 @@ import type { KitSource } from './kit'
 import { kitNewPath, toolRootPath } from './kit-path'
 import { moveGlobalLegacyFiles, moveProjectLegacyFiles, removeEmptyLegacyDirectories } from './legacy-files'
 import { EMPTY_MANIFEST, type Manifest, parseManifest, serializeManifest } from './manifest'
+import { planAskRules } from './plan-ask-rules'
 import { FILE_MODE, FILE_OUTCOME, type FileEffect, type FilePlan, planFile, type RenderedFile } from './plan-file'
 import { type HooksPlan, planHooks } from './plan-hooks'
 import {
@@ -191,11 +192,29 @@ const buildPlan = async ({
   return { files, hooks, manifest: nextManifest(kit.version, files, hooks), manifestText }
 }
 
-/** Merges the kit's hooks into the project's `settings.json`. */
+/** The hooks plan with the kit's ask rules merged into the settings it writes, and their outcomes beside the hooks'. */
+const withAskRules = (hooks: HooksPlan, kit: KitSource, manifest: Manifest, accept: AcceptRequest): HooksPlan => {
+  const rules = planAskRules({
+    kit: kit.askRules ?? [],
+    recorded: manifest.askRules ?? [],
+    settings: hooks.settings,
+    accept: accept.settings,
+  })
+  return {
+    ...hooks,
+    settings: rules.settings,
+    changed: hooks.changed || rules.changed,
+    outcomes: [...hooks.outcomes, ...rules.outcomes],
+    notAcceptable: hooks.notAcceptable && !rules.accepted,
+    askRules: rules.recorded,
+  }
+}
+
+/** Merges the kit's hooks and ask rules into the project's `settings.json`. */
 const projectHooks =
   (claudeDirectory: string, kit: KitSource, config: JackherdConfig) =>
-  async (manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> =>
-    planHooks({
+  async (manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> => {
+    const hooks = planHooks({
       kit: renderKitHooks(kit, (template) => renderTemplate(template, config)),
       entries: manifest.hooks,
       settings: await readSettings(claudeDirectory),
@@ -203,6 +222,8 @@ const projectHooks =
       kitNewRecorded: manifest.settingsKitNew,
       accept: accept.settings,
     })
+    return withAskRules(hooks, kit, manifest, accept)
+  }
 
 /** A global install ships no hooks and never reads the user's `settings.json`. */
 const noHooks = async (_manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> =>

package/src/task-signals/claude-read.ts

@@ -2,6 +2,7 @@ import { readdirSync, readFileSync, statSync } from 'node:fs'
 import { join } from 'node:path'
 import { readTailLines } from '../context/session-log'
 import { isRecord } from '../shared/is-record'
+import { readCached, type StatRound } from '../shared/stat-cache'
 import { claudeSignalsOf } from './claude-signals'
 import { cleanAgentName } from './text'
 import type { TaskSignal } from './types'
@@ -11,7 +12,12 @@ const SUBAGENT_LOG = /^(agent-[A-Za-z0-9]+)\.jsonl$/
 /** How much of the end of a log is read by default: sessions grow to hundreds of megabytes. */
 const SIGNAL_TAIL_BYTES = 8 * 1024 * 1024
 
+/** The signals of each log by path, kept while its modification time and size stay; `used` collects the paths of one round. */
+export type SignalCache = StatRound<TaskSignal[]>
+
 export type ReadOptions = {
+  /** Kept between reads, so a log that did not change is not parsed again. */
+  cache?: SignalCache
   /** How many bytes from the end of each log are read; a task created before that is unknown, so it gives no signal. */
   tailBytes?: number
   /** Subagent logs last written before this (epoch milliseconds) are left out. */
@@ -46,27 +52,38 @@ const isRecent = (path: string, notOlderThan: number): boolean => {
   }
 }
 
-const subagentSignals = (directory: string, tailBytes: number, notOlderThan: number): TaskSignal[] => {
+const named = (signals: TaskSignal[], agent: string): TaskSignal[] => signals.map((signal) => ({ ...signal, agent }))
+
+const subagentSignals = (
+  directory: string,
+  signalsOf: (path: string) => TaskSignal[],
+  notOlderThan: number,
+): TaskSignal[] => {
   try {
     return readdirSync(directory)
       .sort()
       .flatMap((name) => {
         const stem = SUBAGENT_LOG.exec(name)?.[1]
         const path = join(directory, name)
-        return stem && isRecent(path, notOlderThan)
-          ? claudeSignalsOf(linesOf(path, tailBytes), agentNameOf(directory, stem))
-          : []
+        return stem && isRecent(path, notOlderThan) ? named(signalsOf(path), agentNameOf(directory, stem)) : []
       })
   } catch {
     return []
   }
 }
 
-/** The tasks in progress in a Claude Code session log and in every `<session>/subagents/agent-*.jsonl` beside it. */
+/**
+ * The tasks in progress in a Claude Code session log and in every `<session>/subagents/agent-*.jsonl` beside it.
+ * With a `cache`, a log whose modification time and size are as at the last read is not read and parsed again.
+ */
 export const readClaudeSignals = (
   sessionLogPath: string,
-  { tailBytes = SIGNAL_TAIL_BYTES, notOlderThan = 0 }: ReadOptions = {},
-): TaskSignal[] => [
-  ...claudeSignalsOf(linesOf(sessionLogPath, tailBytes), 'session'),
-  ...subagentSignals(join(sessionLogPath.replace(/\.jsonl$/, ''), 'subagents'), tailBytes, notOlderThan),
-]
+  { tailBytes = SIGNAL_TAIL_BYTES, notOlderThan = 0, cache }: ReadOptions = {},
+): TaskSignal[] => {
+  const parsed = (path: string): TaskSignal[] => claudeSignalsOf(linesOf(path, tailBytes), '')
+  const signalsOf = cache ? (path: string) => readCached(cache, path, parsed, `${path}\0${tailBytes}`) : parsed
+  return [
+    ...named(signalsOf(sessionLogPath), 'session'),
+    ...subagentSignals(join(sessionLogPath.replace(/\.jsonl$/, ''), 'subagents'), signalsOf, notOlderThan),
+  ]
+}

package/src/terminal/text.ts

@@ -78,9 +78,14 @@ export const badge = (url: string, text: string, hint = '', tone: BadgeTone = BA
 /** `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})`))
+/**
+ * A line for output that is not a terminal: styling dropped, each link written out as `text (url)`, except the
+ * ones `writesAddress` refuses, which keep the bare text.
+ */
+export const plainText = (text: string, writesAddress: (url: string) => boolean = () => true): string =>
+  stripAnsi(
+    text.replace(LINK, (_, url, inner) => (writesAddress(url) ? `${stripAnsi(inner)} (${url})` : stripAnsi(inner))),
+  )
 
 /** The terminal cells a styled line takes: emoji count two. */
 export const visibleLength = (text: string): number => textWidth(stripAnsi(text))

package/src/version/skill-diff.ts

@@ -6,6 +6,19 @@ export type SkillChange =
   | { kind: typeof SKILL_CHANGE.unchanged }
   | { kind: typeof SKILL_CHANGE.unavailable; reason: string }
 
+/** How a reference file of the orchestrate skill differs between the kit at the start and the kit now. */
+export const REFERENCE_CHANGE = { changed: 'changed', added: 'added', deleted: 'deleted' } as const
+
+type ReferenceChangeKind = (typeof REFERENCE_CHANGE)[keyof typeof REFERENCE_CHANGE]
+
+/** A reference that differs, before the diff is written or the path known. */
+export type ReferenceDelta = { name: string; kind: ReferenceChangeKind }
+
+export type ReferenceChange =
+  | { name: string; kind: typeof REFERENCE_CHANGE.changed; diffPath: string | null }
+  | { name: string; kind: typeof REFERENCE_CHANGE.added; path: string }
+  | { name: string; kind: typeof REFERENCE_CHANGE.deleted }
+
 const HUNK_HEADER = /^@@ -\d+(?:,\d+)? \+(\d+)(?:,\d+)? @@/
 const SECTION_HEADING = /^## (.+)$/
 const NUMBERED_SECTION = /^(\d+)\.\s/
@@ -61,3 +74,36 @@ export const skillChangeLine = (change: SkillChange): string => {
   if (change.kind === SKILL_CHANGE.unchanged) return 'orchestrate skill unchanged'
   return `orchestrate skill diff unavailable (${change.reason}): read the skill again`
 }
+
+const deltaOf = (name: string, before: string | undefined, after: string | undefined): ReferenceDelta[] => {
+  if (before === after) return []
+  if (before === undefined) return [{ name, kind: REFERENCE_CHANGE.added }]
+  return [{ name, kind: after === undefined ? REFERENCE_CHANGE.deleted : REFERENCE_CHANGE.changed }]
+}
+
+/** The references (file name → text) that changed, are new or are gone, by name; unchanged ones are left out. */
+export const referenceChanges = (
+  before: Readonly<Record<string, string>>,
+  after: Readonly<Record<string, string>>,
+): ReferenceDelta[] =>
+  [...new Set([...Object.keys(before), ...Object.keys(after)])]
+    .sort()
+    .flatMap((name) => deltaOf(name, before[name], after[name]))
+
+export const referenceChangeLine = (change: ReferenceChange): string => {
+  const head = `orchestrate reference ${change.name}`
+  if (change.kind === REFERENCE_CHANGE.deleted) return `${head} deleted`
+  if (change.kind === REFERENCE_CHANGE.added) return `${head} new · read ${change.path}`
+  return change.diffPath === null
+    ? `${head} changed · diff unavailable: read it again`
+    : `${head} changed · diff ${change.diffPath}`
+}
+
+/**
+ * The lines about the orchestrate skill after a kit update: the skill's own, then one per reference that changed. An
+ * unchanged skill is named only when no reference changed either, so a quiet update stays one line.
+ */
+export const orchestrateChangeLines = (skill: SkillChange, references: readonly ReferenceChange[]): string[] => {
+  if (skill.kind === SKILL_CHANGE.unchanged && references.length > 0) return references.map(referenceChangeLine)
+  return [skillChangeLine(skill), ...references.map(referenceChangeLine)]
+}

package/src/vocabulary/index.ts

@@ -39,13 +39,23 @@ export const SELF_MERGE_LABEL: Record<PlanLanguage, string> = {
 }
 
 /**
- * The options of the question that approves a plan for all its lanes (``Plan `<path>` ``) and of the one that revokes
- * that approval. The merge guard hook lifts its question for a plain merge of such a lane only when the newest answer
- * to a question naming the plan is exactly `approve`, so the labels are fixed per language and not a config value.
+ * The standing approval: the option that approves (`approve`) and the word between the plan and the end in its
+ * question (``Plan `<path>` <until> <YYYY-MM-DD HH:MM>``). The merge guard hook lifts its question for a plain merge of
+ * that plan's lanes only when the newest answer to such a question is exactly `approve`, so both are fixed per
+ * language and not a config value.
  */
-export const PLAN_APPROVAL_LABELS: Record<PlanLanguage, { approve: string; revoke: string }> = {
-  [PLAN_LANGUAGE.en]: { approve: 'Approve the plan', revoke: 'Revoke the plan approval' },
-  [PLAN_LANGUAGE.de]: { approve: 'Plan freigeben', revoke: 'Plan-Freigabe widerrufen' },
+export const STANDING_APPROVAL_TEXTS: Record<PlanLanguage, { approve: string; until: string }> = {
+  [PLAN_LANGUAGE.en]: { approve: 'Approve standing', until: 'until' },
+  [PLAN_LANGUAGE.de]: { approve: 'Stehend freigeben', until: 'bis' },
+}
+
+/**
+ * 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.
+ */
+export const LANE_PROMPT_OPENING: Record<PlanLanguage, string> = {
+  [PLAN_LANGUAGE.en]: 'You are the lane',
+  [PLAN_LANGUAGE.de]: 'Du bist die Spur',
 }
 
 /** What the approval gate hook tells the lane when it denies: jackherd's own words, English in every language. */

package/src/waiting/command.ts

@@ -1,8 +1,9 @@
 import { terminalSafe } from '../plan-format/terminal-text'
 import type { WaitingItem } from '../plan-format/waiting'
 import { mainCheckout } from '../plans/git'
-import { sentWaitingItems } from '../plans/sent-files'
-import { closeAllSentRecords, closeSentRecords, readSentRecords } from '../plans/sent-files-read'
+import { closeAllQuestionRecords, closeQuestionRecords } from '../plans/questions-read'
+import { closeAllSentRecords, closeSentRecords } from '../plans/sent-files-read'
+import { recordWaitingItems } from '../plans/waiting-records'
 import { CLI_NAME } from '../version/release'
 
 const USAGE = `usage: ${CLI_NAME} waiting [close <id> ... | close --all]`
@@ -13,14 +14,25 @@ export const waitingListing = (items: readonly WaitingItem[]): string[] =>
     ? ['nothing waits on you']
     : items.map(({ since, item, id }) => terminalSafe(`${id} · ${since} · ${item}`))
 
+const CLOSE_ALL = '--all'
+
+/** Closes the records the ids name, files and questions alike; how many it closed. */
+export const closeWaiting = (root: string, ids: readonly string[], now: number): number =>
+  closeSentRecords(root, ids, now) + closeQuestionRecords(root, ids, now)
+
+/** Closes every open record, files and questions alike; how many it closed. */
+export const closeAllWaiting = (root: string, now: number): number =>
+  closeAllSentRecords(root, now) + closeAllQuestionRecords(root, now)
+
 /**
- * `jh waiting` lists the files sent to the user that no one closed (their id, time and caption);
- * `jh waiting close <id> ...` or `close --all` closes them once the user has answered. Exit 0, 1 on a wrong command line.
+ * `jh waiting` lists the files sent to the user and the questions left unanswered that no one closed (their id, time
+ * and text); `jh waiting close <id> ...` or `close --all` closes them once the user has answered. Exit 0, 1 on a wrong
+ * command line.
  */
 export const run = async (args: string[]): Promise<number> => {
   const root = mainCheckout(process.cwd())
   if (args.length === 0) {
-    for (const line of waitingListing(sentWaitingItems(readSentRecords(root), Date.now()))) console.log(line)
+    for (const line of waitingListing(recordWaitingItems(root, Date.now()))) console.log(line)
     return 0
   }
   const [command, ...rest] = args
@@ -28,8 +40,11 @@ export const run = async (args: string[]): Promise<number> => {
     console.error(USAGE)
     return 1
   }
-  const now = Date.now()
-  const closed = rest.includes('--all') ? closeAllSentRecords(root, now) : closeSentRecords(root, rest, now)
+  if (rest.includes(CLOSE_ALL) && rest.length > 1) {
+    console.error(`${CLOSE_ALL} closes everything and takes no ids\n${USAGE}`)
+    return 1
+  }
+  const closed = rest[0] === CLOSE_ALL ? closeAllWaiting(root, Date.now()) : closeWaiting(root, rest, Date.now())
   console.log(`closed ${closed}`)
   return 0
 }

package/src/watch/appointments.ts

@@ -1,4 +1,4 @@
-import { twoDigits } from '../plan-format/clock'
+import { DAY_MS, twoDigits } from '../plan-format/clock'
 import { firstTableWithHeader, sectionLines } from '../plan-format/markdown'
 import { isRecord } from '../shared/is-record'
 import { APPOINTMENT_VOCABULARY, type PlanLanguage } from '../vocabulary'
@@ -31,7 +31,6 @@ type DateParts = { year: number | null; month: number; day: number; hours: numbe
 const DAY_FIRST = /^(?:\p{L}{2,3}\.?,?\s+)?(\d{1,2})\.(\d{1,2})\.(\d{4})?\s+(\d{1,2}):(\d{2})$/u
 const ISO = /^(\d{4})-(\d{2})-(\d{2})[ T](\d{1,2}):(\d{2})$/
 const KEY_TIME_LENGTH = 'YYYY-MM-DDThh:mm'.length
-const DAY_MS = 86_400_000
 const KEEP_GONE_MS = 7 * DAY_MS
 
 const APPOINTMENT_KINDS: readonly string[] = Object.values(APPOINTMENT_EVENT)

package/src/watch/asking-lanes.ts

@@ -0,0 +1,40 @@
+import { questionSections } from './report-questions'
+
+/** The questions sections of a report as one string; empty without a report or without an open question. */
+export const questionsFingerprint = (text: string | null): string => {
+  if (text === null) return ''
+  const lines = text.split('\n')
+  return questionSections(lines)
+    .map(({ start, end }) => lines.slice(start, end).join('\n'))
+    .join('\n')
+}
+
+/**
+ * The working lanes whose report asks something other than what was last remembered for them (`current` and
+ * `remembered` are fingerprints per lane): a lane waiting on its background subagents ends no turn, so its question
+ * would wait for them. A lane without a remembered entry is unseen and asks nothing; its report is the baseline.
+ */
+export const askingLanes = (
+  working: readonly string[],
+  current: Readonly<Record<string, string>>,
+  remembered: Readonly<Record<string, string>>,
+): string[] =>
+  working.filter((lane) => lane in remembered && (current[lane] ?? '') !== '' && current[lane] !== remembered[lane])
+
+/**
+ * The fingerprints to remember for the watched lanes (the keys of `current`): a lane whose report was `shown`, that
+ * asks nothing now or is seen for the first time takes what it has now; any other keeps what it had, so a question
+ * not yet shown still fires. A lane no longer watched is forgotten.
+ */
+export const recordReportQuestions = (
+  remembered: Readonly<Record<string, string>>,
+  current: Readonly<Record<string, string>>,
+  shown: readonly string[],
+): Record<string, string> =>
+  Object.fromEntries(
+    Object.entries(current).map(([lane, questions]) => {
+      const kept = remembered[lane]
+      const takesCurrent = kept === undefined || questions === '' || shown.includes(lane)
+      return [lane, takesCurrent ? questions : kept]
+    }),
+  )

package/src/watch/base-tip.ts

@@ -1,3 +1,5 @@
+import { pullHeadRef } from '../plans/plan-heads'
+
 const COMMIT = /^[0-9a-f]{40}$/
 
 /** The commit of `refs/heads/<branch>` in a `git ls-remote` answer; null when it is not listed. */
@@ -16,3 +18,12 @@ export const remoteTipOf = (lsRemote: string, branch: string): string | null =>
  */
 export const baseFetchNeeded = (remoteTip: string | null, localTip: string | null): boolean =>
   remoteTip !== null && remoteTip !== localTip
+
+/**
+ * The pull requests whose head moved past the herd's ref of it (`pullHeadRef`), or that have none yet: the
+ * watcher's list carries each head commit, so an unchanged head costs no fetch.
+ */
+export const movedHeads = <Head extends { number: number; headCommit: string }>(
+  heads: readonly Head[],
+  localCommitOf: (ref: string) => string | null,
+): Head[] => heads.filter(({ number, headCommit }) => baseFetchNeeded(headCommit, localCommitOf(pullHeadRef(number))))