jackherd 1.15.1 → 1.15.2

package/src/secrets/listing.ts

@@ -0,0 +1,63 @@
+import { terminalSafe } from '../plan-format/terminal-text'
+import { SOURCE_ORIGIN, type SourceSettings } from '../watch/sources'
+import type { Environment } from './environment'
+import { SECRET_LOOKUP, type SecretLookup } from './store'
+
+/**
+ * A secret name and the sources that need it, in their order; `keychain` when a personal source needs it, the only
+ * kind the watcher looks up in the keychain for.
+ */
+export type RequiredSecret = { name: string; sources: string[]; keychain: boolean }
+
+/** Where a needed secret stands, as `jh secret list` prints it: never its value. */
+export const SECRET_STATUS = {
+  set: 'set',
+  environment: 'set (environment)',
+  missing: 'missing',
+  environmentOnly: 'missing (environment only)',
+  unavailable: 'secret store unavailable',
+} as const
+
+export type SecretStatus = (typeof SECRET_STATUS)[keyof typeof SECRET_STATUS]
+
+export type SecretRow = RequiredSecret & { status: SecretStatus }
+
+/** Every name the sources list under `secrets`, sorted, each with the sources that need it and whether a personal one does. */
+export const requiredSecrets = (
+  sources: readonly Pick<SourceSettings, 'name' | 'secrets' | 'origin'>[],
+): RequiredSecret[] => {
+  const needs = new Map<string, RequiredSecret>()
+  for (const source of sources) {
+    for (const name of source.secrets ?? []) {
+      const known = needs.get(name) ?? { name, sources: [], keychain: false }
+      const personal = source.origin === SOURCE_ORIGIN.personal
+      needs.set(name, { name, sources: [...known.sources, source.name], keychain: known.keychain || personal })
+    }
+  }
+  return [...needs.values()].sort((left, right) => left.name.localeCompare(right.name))
+}
+
+/** The status of a name only repository sources need: the watcher hands them the environment, never the keychain. */
+export const environmentOnlyStatusOf = (name: string, environment: Environment): SecretStatus =>
+  environment[name] ? SECRET_STATUS.environment : SECRET_STATUS.environmentOnly
+
+/**
+ * The status the watcher would meet: in the keychain, else in the environment (this shell's, which a watcher started
+ * elsewhere may not share), else missing; a keychain without an answer and no variable is `unavailable`. Takes the
+ * lookup and keeps nothing of its value.
+ */
+export const secretStatusOf = (name: string, lookup: SecretLookup, environment: Environment): SecretStatus => {
+  if (lookup.kind === SECRET_LOOKUP.found) return SECRET_STATUS.set
+  if (environment[name]) return SECRET_STATUS.environment
+  return lookup.kind === SECRET_LOOKUP.unavailable ? SECRET_STATUS.unavailable : SECRET_STATUS.missing
+}
+
+/** The lines of `jh secret list`: name, status and the sources that need it, in columns; a note when no source names one. */
+export const secretListing = (rows: readonly Pick<SecretRow, 'name' | 'status' | 'sources'>[]): string[] => {
+  if (rows.length === 0) return ['no source names a secret']
+  const nameWidth = Math.max(...rows.map(({ name }) => name.length))
+  const statusWidth = Math.max(...rows.map(({ status }) => status.length))
+  return rows.map(({ name, status, sources }) =>
+    terminalSafe(`${name.padEnd(nameWidth)}  ${status.padEnd(statusWidth)}  ${sources.join(', ')}`),
+  )
+}

package/src/secrets/options.ts

@@ -0,0 +1,45 @@
+import { CLI_NAME } from '../version/release'
+
+/** A secret's name, which becomes the name of an environment variable; the same rule as `secrets` in a source. */
+export const SECRET_NAME = /^[A-Z][A-Z0-9_]*$/
+
+export const SECRET_ACTION = { set: 'set', list: 'list', delete: 'delete' } as const
+
+export const SECRET_USAGE = `Usage: ${CLI_NAME} secret set <NAME>     store a value in the keychain, typed hidden in a terminal
+       ${CLI_NAME} secret list           the names the sources need, set or missing, never a value
+       ${CLI_NAME} secret delete <NAME>  remove the value from the keychain`
+
+export type SecretRequest =
+  | { kind: typeof SECRET_ACTION.set; name: string }
+  | { kind: typeof SECRET_ACTION.list }
+  | { kind: typeof SECRET_ACTION.delete; name: string }
+  | { kind: 'help' }
+  | { kind: 'error'; message: string }
+
+const HELP_FLAGS = new Set(['--help', '-h'])
+
+const named = (
+  kind: typeof SECRET_ACTION.set | typeof SECRET_ACTION.delete,
+  rest: readonly string[],
+): SecretRequest => {
+  const [name, ...extra] = rest
+  if (!name || extra.length > 0) return { kind: 'error', message: `${CLI_NAME} secret ${kind} takes one name` }
+  if (!SECRET_NAME.test(name)) {
+    return { kind: 'error', message: 'a secret name is capital letters, digits and `_`, starting with a letter' }
+  }
+  return { kind, name }
+}
+
+/**
+ * The command line of `jh secret`. A value is never an argument: `set` takes the name only and asks for the value in
+ * the terminal, so it shows up in no shell history and no process list.
+ */
+export const parseSecretArgs = (args: readonly string[]): SecretRequest => {
+  const [action, ...rest] = args
+  if (action === undefined || HELP_FLAGS.has(action)) return { kind: 'help' }
+  if (action === SECRET_ACTION.list) {
+    return rest.length === 0 ? { kind: SECRET_ACTION.list } : { kind: 'error', message: 'list takes no arguments' }
+  }
+  if (action === SECRET_ACTION.set || action === SECRET_ACTION.delete) return named(action, rest)
+  return { kind: 'error', message: `unknown action: ${action}` }
+}

package/src/secrets/store.ts

@@ -0,0 +1,74 @@
+/** The keychain service every jackherd secret is stored under; the entry's name is the environment variable's name. */
+export const SECRET_SERVICE = 'jackherd'
+
+/** How long one keychain call may take before the store counts as unavailable (a locked keychain, a missing D-Bus). */
+export const SECRET_TIMEOUT_MS = 10_000
+
+/** What a keychain lookup found: the value, no entry, or no answer from the keychain service at all. */
+export const SECRET_LOOKUP = { found: 'found', absent: 'absent', unavailable: 'unavailable' } as const
+
+export type SecretLookup =
+  | { kind: typeof SECRET_LOOKUP.found; value: string }
+  | { kind: typeof SECRET_LOOKUP.absent }
+  | { kind: typeof SECRET_LOOKUP.unavailable }
+
+/** What a write or a delete did: done, nothing there to delete, or no answer from the keychain service. */
+export const SECRET_WRITE = { done: 'done', absent: 'absent', unavailable: 'unavailable' } as const
+
+export type SecretWrite = (typeof SECRET_WRITE)[keyof typeof SECRET_WRITE]
+
+/** Looks up one secret by its name. */
+export type SecretLookupFn = (name: string) => Promise<SecretLookup>
+
+export type SecretStore = {
+  get: SecretLookupFn
+  set: (name: string, value: string) => Promise<SecretWrite>
+  delete: (name: string) => Promise<SecretWrite>
+}
+
+/** The part of `Bun.secrets` the store uses, so a test hands in a stub and never reaches the real keychain. */
+export type KeychainApi = Pick<typeof Bun.secrets, 'get' | 'set' | 'delete'>
+
+const TIMED_OUT = Symbol('timed out')
+
+const UNAVAILABLE: SecretLookup = { kind: SECRET_LOOKUP.unavailable }
+const ABSENT: SecretLookup = { kind: SECRET_LOOKUP.absent }
+
+/** `call`'s result, or `TIMED_OUT` once `timeoutMs` passed or it threw: the error text is dropped, it may name the entry's value. */
+const bounded = async <T>(call: () => Promise<T>, timeoutMs: number): Promise<T | typeof TIMED_OUT> => {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const deadline = new Promise<typeof TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(TIMED_OUT), timeoutMs)
+  })
+  try {
+    return await Promise.race([call(), deadline])
+  } catch {
+    return TIMED_OUT
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+/** An empty value counts as no entry: `Bun.secrets` treats storing one as a delete. */
+const lookupOf = (value: string | null | typeof TIMED_OUT): SecretLookup => {
+  if (value === TIMED_OUT) return UNAVAILABLE
+  return value ? { kind: SECRET_LOOKUP.found, value } : ABSENT
+}
+
+/**
+ * The system keychain behind `get`, `set` and `delete`, every entry under the service `jackherd`. Each call is bounded
+ * by `timeoutMs`; a keychain that throws or does not answer in time is `unavailable`, never a rejection, so a locked
+ * keychain cannot stop the watcher. Nothing here logs or prints.
+ */
+export const secretStore = (api: KeychainApi = Bun.secrets, timeoutMs: number = SECRET_TIMEOUT_MS): SecretStore => ({
+  get: async (name) => lookupOf(await bounded(() => api.get({ service: SECRET_SERVICE, name }), timeoutMs)),
+  set: async (name, value) => {
+    const done = await bounded(() => api.set({ service: SECRET_SERVICE, name, value }), timeoutMs)
+    return done === TIMED_OUT ? SECRET_WRITE.unavailable : SECRET_WRITE.done
+  },
+  delete: async (name) => {
+    const deleted = await bounded(() => api.delete({ service: SECRET_SERVICE, name }), timeoutMs)
+    if (deleted === TIMED_OUT) return SECRET_WRITE.unavailable
+    return deleted ? SECRET_WRITE.done : SECRET_WRITE.absent
+  },
+})

package/src/shared/process-info.ts

@@ -0,0 +1,89 @@
+import { readFileSync, readlinkSync } from 'node:fs'
+
+/** Longest a `ps` or `tty` call may take; a call past it counts as no answer. */
+const SPAWN_TIMEOUT_MS = 2000
+
+export type ProcessInfoSystem = {
+  platform: NodeJS.Platform
+  readText: (path: string) => string | null
+  readLink: (path: string) => string | null
+  /** Runs a program and answers its stdout, null when it failed, timed out or is missing. */
+  run: (command: string[], stdin: 'inherit' | 'ignore') => string | null
+}
+
+export type ProcessInfo = {
+  /** The terminal device of stdin (`/dev/…`); null without one. */
+  terminalOfStdin: () => string | null
+  /** Environment entries and arguments of a process, blank-separated words; null where they cannot be read. */
+  wordsOf: (pid: number) => string[] | null
+  /** True when the process does not exist or is a zombie. */
+  isGone: (pid: number) => boolean
+}
+
+const orNull = <T>(read: () => T): T | null => {
+  try {
+    return read()
+  } catch {
+    return null
+  }
+}
+
+/** `/dev/…` as `tty` or `/proc/self/fd/0` names it, null for anything else (`not a tty`). */
+export const deviceOf = (text: string | null): string | null => {
+  const line = text?.trim() ?? ''
+  return line.startsWith('/dev/') ? line : null
+}
+
+/** The words of `ps -E -ww -o command=` (macOS appends the environment to the command line). */
+export const wordsOfPsOutput = (output: string | null): string[] | null => {
+  const words = output?.trim().split(/\s+/).filter(Boolean) ?? []
+  return words.length === 0 ? null : words
+}
+
+/** The `\0`-separated entries of `/proc/<pid>/environ` and `/proc/<pid>/cmdline` as one list; null unless both read. */
+export const wordsOfProcFiles = (environment: string | null, command: string | null): string[] | null =>
+  environment === null || command === null ? null : [...environment.split('\0'), ...command.split('\0')].filter(Boolean)
+
+/** True for a state column of `ps -o stat=` or `/proc/<pid>/stat` that means the process is a zombie. */
+const isZombieState = (state: string): boolean => state.startsWith('Z')
+
+/** The state letter after the parenthesised name in a line of `/proc/<pid>/stat`. */
+export const stateOfProcStat = (stat: string): string => stat.charAt(stat.lastIndexOf(')') + 2)
+
+export const goneFromProcStat = (stat: string | null): boolean => stat === null || isZombieState(stateOfProcStat(stat))
+
+/** Gone when `ps` found nothing (empty output) or the state is a zombie. */
+export const goneFromPsState = (output: string | null): boolean => {
+  const state = output?.trim() ?? ''
+  return state === '' || isZombieState(state)
+}
+
+const linuxInfo = (system: ProcessInfoSystem): ProcessInfo => ({
+  terminalOfStdin: () => deviceOf(system.readLink('/proc/self/fd/0')),
+  wordsOf: (pid) => wordsOfProcFiles(system.readText(`/proc/${pid}/environ`), system.readText(`/proc/${pid}/cmdline`)),
+  isGone: (pid) => goneFromProcStat(system.readText(`/proc/${pid}/stat`)),
+})
+
+const psInfo = (system: ProcessInfoSystem): ProcessInfo => ({
+  terminalOfStdin: () => deviceOf(system.run(['tty'], 'inherit')),
+  wordsOf: (pid) => wordsOfPsOutput(system.run(['ps', '-E', '-ww', '-o', 'command=', '-p', String(pid)], 'ignore')),
+  isGone: (pid) => goneFromPsState(system.run(['ps', '-o', 'stat=', '-p', String(pid)], 'ignore')),
+})
+
+/** Process inspection through `/proc` on Linux and through `ps` and `tty` elsewhere (macOS has no `/proc`). */
+export const processInfoFor = (system: ProcessInfoSystem): ProcessInfo =>
+  system.platform === 'linux' ? linuxInfo(system) : psInfo(system)
+
+export const systemProcessInfoSystem = (): ProcessInfoSystem => ({
+  platform: process.platform,
+  readText: (path) => orNull(() => readFileSync(path, 'utf8')),
+  readLink: (path) => orNull(() => readlinkSync(path)),
+  run: (command, stdin) => {
+    const result = orNull(() =>
+      Bun.spawnSync(command, { stdin, stdout: 'pipe', stderr: 'ignore', timeout: SPAWN_TIMEOUT_MS }),
+    )
+    return result !== null && result.exitCode === 0 ? result.stdout.toString() : null
+  },
+})
+
+export const systemProcessInfo = (): ProcessInfo => processInfoFor(systemProcessInfoSystem())

package/src/sync/command-context.ts

@@ -40,16 +40,38 @@ const YES = /^y(es)?$/i
 
 const hasTerminal = (): boolean => Boolean(process.stdin.isTTY && process.stdout.isTTY)
 
-/** One question on the terminal, the trimmed answer. */
-const questionOnTerminal = async (text: string): Promise<string> => {
-  const terminal = createInterface({ input: process.stdin, output: process.stdout })
+const UNREADABLE_NOTE = 'jackherd: the terminal could not be read, using the default answer'
+
+/**
+ * One question on a stream, the trimmed answer. A read error (macOS kqueue refusing the device with EINVAL, say)
+ * reaches readline as an `error` event while the pending question never settles; it is answered with the empty
+ * string, so the caller takes its default, and one note goes to `warn`.
+ */
+export const questionOnStream = async (
+  text: string,
+  input: NodeJS.ReadableStream,
+  output: NodeJS.WritableStream,
+  warn: (line: string) => void,
+): Promise<string> => {
+  const terminal = createInterface({ input, output })
+  const unreadable = new Promise<null>((resolve) => terminal.once('error', () => resolve(null)))
+  const asked = terminal.question(text)
+  asked.catch(() => undefined)
   try {
-    return (await terminal.question(text)).trim()
+    const answer = await Promise.race([asked, unreadable])
+    if (answer !== null) return answer.trim()
+  } catch {
+    // a rejected question is the same unreadable terminal
   } finally {
     terminal.close()
   }
+  warn(UNREADABLE_NOTE)
+  return ''
 }
 
+const questionOnTerminal = (text: string): Promise<string> =>
+  questionOnStream(text, process.stdin, process.stdout, (line) => console.error(line))
+
 /** Asks on the terminal; without one on both stdin and stdout nobody would see or answer the question. */
 const askOnTerminal = async (question: string): Promise<boolean | null> =>
   hasTerminal() ? YES.test(await questionOnTerminal(`${question} [y/N] `)) : null

package/src/sync/render.ts

@@ -11,14 +11,19 @@ import {
 
 const PLACEHOLDER = /\{\{\s*(kit\.[A-Za-z0-9_.-]*)\s*\}\}/g
 
-const WORKTREE_INCLUDE_COPY =
-  'cd <main-checkout> && git ls-files -z --others --ignored --exclude-from=.worktreeinclude | grep -zv node_modules | xargs -0 -I{} cp -p --parents {} <worktree>/'
+/** Reads the tar archive from stdin into the worktree, keeping file modes; the same flags work on GNU tar and bsdtar. */
+const UNPACK = 'tar -xpf - -C <worktree>'
 
-/** The command that copies a lane's untracked files; the schema keeps quotes out of every path. */
+const WORKTREE_INCLUDE_COPY = `cd <main-checkout> && git ls-files -z --others --ignored --exclude-from=.worktreeinclude -- ':(exclude)*node_modules*' | tar -cf - --null -T - | ${UNPACK}`
+
+/**
+ * The command that copies a lane's untracked files, relative paths and modes kept; it uses only what GNU and BSD
+ * (macOS) userlands share, no `cp --parents` and no `grep -z`. The schema keeps quotes out of every path.
+ */
 const laneCopyCommand = (copy: readonly string[]): string =>
   copy.length === 0
     ? WORKTREE_INCLUDE_COPY
-    : `cd <main-checkout> && cp -p --parents -- ${copy.map((path) => `'${path}'`).join(' ')} <worktree>/`
+    : `cd <main-checkout> && tar -cf - -- ${copy.map((path) => `'${path}'`).join(' ')} | ${UNPACK}`
 
 /** The patterns a pull request may match to be merged without checks, as prose for a skill; `none` for an empty list. */
 const checkFreeList = (patterns: readonly string[]): string =>

package/src/watch/command.ts

@@ -32,6 +32,7 @@ import { existsSync, readFileSync } from 'node:fs'
 import { homedir } from 'node:os'
 import { basename, dirname, join, relative } from 'node:path'
 import { writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import { sourcesWithPersonal } from '../config/personal-sources'
 import { readConfig, readResolvedConfig } from '../config/read-config'
 import type { JackherdConfig } from '../config/schema'
 import { resolveCoordinatorName } from '../context/coordinator-name'
@@ -182,9 +183,16 @@ import { withSingleReportNotice } from './single-report'
 import { readOrchestrateSnapshot, skillLineFor } from './skill-change'
 import { runsFromSource, sourceChangeSettled, watchSourceChanges } from './source-change'
 import { sourceDryRun } from './source-dry-run-command'
+import {
+  type LoadedSources,
+  nextLoadedSources,
+  readFileStamps,
+  readWatchedSources,
+  sourceFilePaths,
+} from './source-reload'
 import { runSource, SOURCE_LIMITS } from './source-run'
-import { recordWatchedSources } from './source-tickets'
-import { isSourceDue, type SourceRun, type SourceSettings, type SourceState, sourceEvents } from './sources'
+import { recordedSourceState } from './source-tickets'
+import { isSourceDue, type SourceRun, type SourceState, sourceEvents } from './sources'
 import { heartbeatStateOf, isHeartbeatNews, streamHeartbeatLine } from './stream-output'
 import {
   formatTaskParallelLine,
@@ -257,7 +265,10 @@ type Watch = {
   /** The switch `watch.parallelTasks.auto` and the paths that always ask, both from the main checkout's config. */
   parallelAuto: AutoSettings
   previews: PreviewsConfig
-  sources: SourceSettings[]
+  /** The sources as read at the start; the loop takes up later changes of their files (`Watching.sources`). */
+  sources: LoadedSources
+  /** The checkouts whose config the sources are read from, as `readResolvedConfig` takes them. */
+  configRoots: string[]
   texts: WatchTexts
   /** Where the orchestrate skill is installed, the project's copy first; the events name a reference inside the one found. */
   skillCopies: SkillCopy[]
@@ -305,6 +316,8 @@ type Watching = {
   failureReadings: FailureReading[]
   /** The last preview read that answered; recorded with every state like the feedback read. */
   previewRead: PreviewRead | null
+  /** The sources run now, read again whenever one of their files changes (`nextLoadedSources`). */
+  sources: LoadedSources
   /** The runs of the sources due at the last GitHub poll; recorded with every state like the feedback read. */
   sourceRuns: SourceRun[]
   /** The lanes' fills of the last read; a lane without an entry or with null has no value. */
@@ -381,7 +394,7 @@ const recordedOf = (watch: Watch, watching: Watching): WatchState => {
     unlinkedArtifacts: watching.unlinkedArtifacts,
     planMissing: watching.planMissing,
     approvals: watching.approvalRequests ? recordApprovals(watching.approvalRequests) : withReads.approvals,
-    sources: recordWatchedSources(withReads.sources, watching.sourceRuns, watch.sources, watching.githubReadAt),
+    ...recordedSourceState(withReads.sources, watching.sourceRuns, watching.sources.sources, watching.githubReadAt),
     appointments: watching.appointments
       ? recordAppointments(withReads.appointments, watching.appointments.table, watching.appointments.readAt)
       : withReads.appointments,
@@ -887,15 +900,26 @@ const recordPreviewRead = (watching: Watching, read: PreviewRead | null): WatchE
  * source stops the watcher. The run's start is recorded with the GitHub read's time, which is `now`.
  */
 const runDueSources = (watch: Watch, watching: Watching, now: number): Promise<SourceRun[]> => {
-  const due = watch.sources.filter((source) =>
+  const due = watching.sources.sources.filter((source) =>
     isSourceDue(watching.state.sources[source.name]?.ranAt, source.every, now),
   )
   return Promise.all(due.map((source) => runSource(source, watch.root, SOURCE_LIMITS)))
 }
 
-const recordSourceRuns = (watch: Watch, watching: Watching, runs: SourceRun[]): WatchEvent[] => {
+/**
+ * Takes up a change of the files the sources come from before the due ones run (`nextLoadedSources`): a source read
+ * anew has no `ranAt` and runs at once, its first run a baseline; an invalid file keeps the list and is said once.
+ */
+const reloadSources = (watch: Watch, watching: Watching) => {
+  const stamps = readFileStamps(Object.keys(watching.sources.stamps))
+  const next = nextLoadedSources(watching.sources, stamps, () => readWatchedSources(watch.configRoots, homedir()))
+  watching.sources = next.loaded
+  for (const line of next.lines) console.log(line)
+}
+
+const recordSourceRuns = (watching: Watching, runs: SourceRun[]): WatchEvent[] => {
   watching.sourceRuns = runs
-  return sourceEvents(watching.state.sources, runs, watch.sources)
+  return sourceEvents(watching.state.sources, runs, watching.sources.sources)
 }
 
 /** Starts a fetch of the base branch in the background when none runs; the loop does not wait for it. */
@@ -917,7 +941,8 @@ const syncPlanHeads = (watch: Watch, watching: Watching, pullRequests: readonly
 
 /**
  * Reads the coordinator's fill, GitHub, the feedback, the previews and the due sources, and stores them only once every read is complete: a SIGTERM
- * while a read is pending saves the state as it was, so no event is taken as reported.
+ * while a read is pending saves the state as it was, so no event is taken as reported. Before the sources run, a
+ * change of the files they come from is taken up (`reloadSources`), which prints its notes.
  */
 const pollGithubAndCoordinator = async (watch: Watch, watching: Watching, now: number): Promise<WatchEvent[]> => {
   syncBase(watch, watching)
@@ -925,6 +950,7 @@ const pollGithubAndCoordinator = async (watch: Watch, watching: Watching, now: n
   const fills = fillReadFor(watch, name, watching.agents, watching.lanes)
   const laneBranches = laneBranchesOf(watch, watching.lanes)
   const searched = Object.values({ ...watching.state.laneBranches, ...laneBranches })
+  reloadSources(watch, watching)
   const [github, sourceRuns] = await Promise.all([
     readGithub(watch.root, watch.deploy, watch.settings.baseBranch, searched),
     runDueSources(watch, watching, now),
@@ -940,7 +966,7 @@ const pollGithubAndCoordinator = async (watch: Watch, watching: Watching, now: n
     ...recordGithub(watching, github, laneBranches, now, failureReadings),
     ...recordFeedbackRead(watching, feedback?.read ?? null),
     ...recordPreviewRead(watching, previews),
-    ...recordSourceRuns(watch, watching, sourceRuns),
+    ...recordSourceRuns(watching, sourceRuns),
     ...recordCoordinator(watching, { name, read: fills.coordinator }),
     ...recordLaneFills(watching, fills.lanes),
     ...recordLaneModelReads(watching, laneModelReadingsOf(watch, watching, fills.models)),
@@ -1355,6 +1381,7 @@ const initialWatching = (
   feedbackRead: null,
   failureReadings: [],
   previewRead: null,
+  sources: watch.sources,
   sourceRuns: [],
   laneReadings: {},
   laneModelReadings: {},
@@ -1458,8 +1485,12 @@ const autoSettingsOf = (root: string, checkoutRoot: string, config: JackherdConf
 const watchOf = (options: WatchOptions): Watch => {
   const root = mainCheckout(process.cwd())
   const checkoutRoot = worktreeRoot(process.cwd())
-  const { config, notes } = readResolvedConfig([checkoutRoot, root])
-  for (const note of notes) console.log(note)
+  const configRoots = [checkoutRoot, root]
+  // Stamped before the read: a change in between is read again at the first poll, never missed.
+  const stamps = readFileStamps(sourceFilePaths(configRoots, homedir()))
+  const { config, notes } = readResolvedConfig(configRoots)
+  const merged = sourcesWithPersonal(config.watch.sources)
+  for (const note of [...notes, ...merged.notes]) console.log(note)
   const settings = plansSettingsOf(config)
   const picked = boardFor(options.boardPath, [root, worktreeRoot(process.cwd())], settings, () =>
     foundLanesOf(root, settings, () => agentNamesOf(listAgents())),
@@ -1478,7 +1509,8 @@ const watchOf = (options: WatchOptions): Watch => {
     taskSignalMinutes: config.watch.taskSignalMinutes,
     parallelAuto: autoSettingsOf(root, checkoutRoot, config),
     previews: config.watch.previews,
-    sources: config.watch.sources,
+    sources: { sources: merged.sources, stamps },
+    configRoots,
     texts: watchTexts(settings.responseLanguage),
     skillCopies: skillCopiesFor(root, homedir(), config.skillPrefix, DEFAULT_SKILL_PREFIX),
     herdr: insideHerdr(settings.adapter, process.env),

package/src/watch/plan-badges-read.ts

@@ -1,9 +1,10 @@
 import { dirname, join } from 'node:path'
+import { type HerdSourceSettings, herdSourceSettingsOf } from '../plans/settings'
 import { isPrivateLevels, type LocationSystem, readPrivateText, systemLocation } from '../shared/private-location'
 import {
   sourceTicketsOf,
-  type TicketSource,
   WATCH_HEALTH,
+  type WatchHealth,
   type WatchReading,
   watchBadgesOf,
   watchHealthOf,
@@ -22,21 +23,35 @@ const readState = (file: string): WatchState | null => {
   }
 }
 
+/** A reading with the sources it was drawn for: those the watcher wrote into its state, else the herd's own. */
+export type SourcedWatchReading = WatchReading & { sourceSettings: HerdSourceSettings }
+
+/**
+ * The sources a live watcher keeps in its state (`watchedSources`); `fallback`, the herd's config, for a watcher that
+ * stopped (its state may predate a config change) or a state written before it kept them.
+ */
+export const sourceSettingsOf = (
+  state: WatchState | null,
+  health: WatchHealth,
+  fallback: HerdSourceSettings,
+): HerdSourceSettings =>
+  health.kind === WATCH_HEALTH.live && state?.watchedSources ? herdSourceSettingsOf(state.watchedSources) : fallback
+
 /**
  * What the watcher of the repository at `root` gives the herd, read from its state file without a GitHub call:
- * its badges, the tickets of `ticketSources`, the status of the sources in `statusNames`, and its health, so the view can say why there are none. A missing or
- * damaged file shows no badges; the view goes on without them. Nothing is read unless both levels of the watcher
- * directory are private (`isPrivateLevels`), and only regular files, so a directory, a file or a FIFO someone else
- * planted neither feeds the view nor blocks it.
+ * its badges, the tickets of the ticket sources, the status of the other sources, and its health, so the view can say
+ * why there are none. The sources are those the state names, so one the watcher took up since the herd started shows
+ * too; `fallback` stands in for a state without them. A missing or damaged file shows no badges; the view goes on
+ * without them. Nothing is read unless both levels of the watcher directory are private (`isPrivateLevels`), and
+ * only regular files, so a directory, a file or a FIFO someone else planted neither feeds the view nor blocks it.
  */
 export const readWatchReading = (
   root: string,
   now: number,
-  ticketSources: readonly TicketSource[],
+  fallback: HerdSourceSettings,
   lookUp?: CommandLineOf,
   system: LocationSystem = systemLocation(),
-  statusNames: readonly string[] = [],
-): WatchReading => {
+): SourcedWatchReading => {
   const directory = watcherDirectoryOf(root, system)
   const isPrivate = isPrivateLevels(dirname(directory), directory, system)
   const state = isPrivate ? readState(join(directory, WATCHER_FILES.state)) : null
@@ -45,11 +60,14 @@ export const readWatchReading = (
     isPrivate && isWatcherRunning(join(directory, WATCHER_FILES.lock), lookUp),
     now,
   )
-  if (!state || health.kind !== WATCH_HEALTH.live) return { badges: {}, tickets: [], health }
+  const sourceSettings = sourceSettingsOf(state, health, fallback)
+  if (!state || health.kind !== WATCH_HEALTH.live) return { badges: {}, tickets: [], health, sourceSettings }
+  const statusNames = sourceSettings.herdSources.map(({ name }) => name)
   return {
     badges: watchBadgesOf(state, now),
-    tickets: sourceTicketsOf(state, ticketSources, now),
+    tickets: sourceTicketsOf(state, sourceSettings.ticketSources, now),
     health,
     ...(statusNames.length > 0 ? { sources: sourceStatusesOf(state, statusNames, now) } : {}),
+    sourceSettings,
   }
 }

package/src/watch/source-dry-run-command.ts

@@ -1,15 +1,17 @@
-import { readResolvedConfig } from '../config/read-config'
-import { type JackherdConfig, parseSourceDraft } from '../config/schema'
+import { homedir } from 'node:os'
+import { personalSourcesPath } from '../config/location'
+import { configuredSources, isNoteAbout } from '../config/personal-sources'
+import { parseSourceDraft } from '../config/schema'
 import { mainCheckout, worktreeRoot } from '../plans/git'
 import type { SourceDryRun } from './options'
 import { type DryRunTarget, dryRunExitCode, dryRunLines, dryRunTarget, emptyMapFields } from './source-dry-run'
-import { runSourceCommand, SOURCE_LIMITS, sourceRunOf } from './source-run'
+import { SOURCE_LIMITS, sourceAnswer, sourceRunOf } from './source-run'
 import type { SourceSettings } from './sources'
 
-const settingsOf = async (target: DryRunTarget, config: JackherdConfig): Promise<SourceSettings> => {
+const settingsOf = async (target: DryRunTarget, sources: readonly SourceSettings[]): Promise<SourceSettings> => {
   if (target.kind === 'name') {
-    const found = config.watch.sources.find(({ name }) => name === target.name)
-    if (!found) throw new Error(`no source ${target.name} in watch.sources`)
+    const found = sources.find(({ name }) => name === target.name)
+    if (!found) throw new Error(`no source ${target.name} in watch.sources or the personal sources file`)
     return found
   }
   const text = target.kind === 'stdin' ? await Bun.stdin.text() : await Bun.file(target.path).text()
@@ -17,19 +19,28 @@ const settingsOf = async (target: DryRunTarget, config: JackherdConfig): Promise
 }
 
 /**
- * `jh watch source <name|draft.json|-> --dry-run [--raw]`: runs one source once in the main checkout, as the
- * watcher would, and prints what it found and would report; `--raw` adds the command's output. Takes no lock and
+ * `jh watch source <name|draft.json|-> --dry-run [--raw]`: runs one source once in the main checkout (a personal one in `~/.jackherd`), as the
+ * watcher would, its `secrets` handed to the command alike, and prints what it found and would report; `--raw` adds
+ * the command's stdout, which by the recipe rules carries no secret value. Takes no lock and
  * neither reads nor writes the watcher's state, so a running watcher is not disturbed. Exits 1 when the run failed or a
  * `map` field is empty in every entry.
  */
 export const sourceDryRun = async ({ target, raw }: SourceDryRun): Promise<number> => {
   const root = mainCheckout(process.cwd())
-  const { config } = readResolvedConfig([worktreeRoot(process.cwd()), root])
-  const settings = await settingsOf(dryRunTarget(target), config)
-  const answer = await runSourceCommand(settings.command, root, SOURCE_LIMITS)
+  const home = homedir()
+  const merged = configuredSources([worktreeRoot(process.cwd()), root], home)
+  const settings = await settingsOf(dryRunTarget(target), merged.sources)
+  const answer = await sourceAnswer(settings, root, SOURCE_LIMITS, home)
   const run = sourceRunOf(settings, answer)
   const mapCheck = answer.ok ? emptyMapFields(answer.stdout, settings) : null
   const stdout = raw && answer.ok ? answer.stdout : undefined
-  console.log(dryRunLines(settings, run, { mapCheck, stdout }).join('\n'))
+  console.log(
+    dryRunLines(settings, run, {
+      mapCheck,
+      stdout,
+      personalPath: personalSourcesPath(home),
+      notes: merged.notes.filter((note) => isNoteAbout(note, settings.name)),
+    }).join('\n'),
+  )
   return dryRunExitCode(run, mapCheck)
 }