jackherd 1.15.1 → 1.16.0

package/src/plans/source-rows.ts

@@ -2,6 +2,7 @@ import { TONE, type ToneName } from '../config/tones'
 import { padVisible } from '../terminal/text'
 import { textWidth } from '../terminal/width'
 import type { EntryStatus, SourceStatus } from '../watch/source-statuses'
+import { SOURCE_SHOW, type SourceShow } from '../watch/sources'
 import { ASK_KIND } from './ask-target'
 import type { AskedCheck } from './source-asked'
 import { chevronOf } from './symbols'
@@ -9,9 +10,10 @@ import type { BlockItem } from './waiting-click'
 
 /**
  * A source's status with the tone its config names for the mark while its report is new (null where it names none) and
- * the label its config gives it, absent where it gives none.
+ * the label its config gives it, absent where it gives none, and `show` where it asks for its entries in a block of
+ * their own.
  */
-export type HerdSource = SourceStatus & { tone?: ToneName | null; label?: string }
+export type HerdSource = SourceStatus & { tone?: ToneName | null; label?: string; show?: SourceShow }
 
 /** One source in the line of the folded sources block: what it says and the tone it wears, none for dim. */
 export type SourceSummary = { text: string; tone?: ToneName }
@@ -179,6 +181,37 @@ const entryItems = (source: HerdSource, view: SourceView, now: number, newTone:
   ]
 }
 
+/** Whether the source asks for its entries in a block of their own. */
+export const showsEntries = (source: HerdSource): boolean => source.show === SOURCE_SHOW.entries
+
+/** The sources that have a block of their own: those that ask for it and have entries; an empty run draws none. */
+export const entryBlockSources = (sources: readonly HerdSource[]): HerdSource[] =>
+  sources.filter((source) => showsEntries(source) && source.entries.length > 0)
+
+/** The source as the `Sources` block draws it: a source with a block of its own keeps its status, not its entries. */
+export const statusOnly = (source: HerdSource): HerdSource =>
+  showsEntries(source) ? { ...source, entries: [], latest: null } : source
+
+/**
+ * The rows of the block of a source that shows its entries: count, time and title as in the opened source, in the
+ * order the state holds them, in the tone of the source, none of them asking or expanding; a row with an address
+ * is linked. Only the first `limit` entries become rows, the columns measured over those.
+ */
+export const entryBlockItems = (source: HerdSource, now: number, limit: number): BlockItem[] => {
+  const shown = source.entries.slice(0, limit)
+  const columns = columnsOf(shown, now)
+  return shown.map((entry) => ({
+    key: entryKey(source.name, entry),
+    mark: ENTRY_MARK,
+    lead: entryLeadOf(entry, now, columns),
+    text: entry.title,
+    url: entry.url,
+    ask: null,
+    expands: false,
+    ...(source.tone && { tone: source.tone }),
+  }))
+}
+
 const DEFAULT_VIEW: SourceView = { expanded: new Set(), asked: () => false }
 
 /**

package/src/secrets/command.ts

@@ -0,0 +1,163 @@
+import { configuredSources } from '../config/personal-sources'
+import { errorText } from '../plans/error-text'
+import { mainCheckout, worktreeRoot } from '../plans/git'
+import { CLI_NAME } from '../version/release'
+import type { SourceSettings } from '../watch/sources'
+import type { Environment } from './environment'
+import { hiddenInputStep } from './hidden-input'
+import { environmentOnlyStatusOf, requiredSecrets, secretListing, secretStatusOf } from './listing'
+import { parseSecretArgs, SECRET_ACTION, SECRET_USAGE } from './options'
+import { SECRET_LOOKUP, SECRET_SERVICE, SECRET_WRITE, type SecretStore, secretStore } from './store'
+
+/** What `jh secret` reaches outside itself, so a test runs it against stubs and never against the real keychain. */
+export type SecretPorts = {
+  store: SecretStore
+  /** Whether stdin is a terminal: `set` reads from one only. */
+  isTerminal: () => boolean
+  /** 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[] }
+  environment: Environment
+  out: (line: string) => void
+  err: (line: string) => void
+}
+
+/** Exit code of `set` without a terminal, apart from 1 for a wrong command line or a failed write. */
+export const NO_TERMINAL_EXIT = 2
+
+const ENDING_SIGNALS = ['SIGTERM', 'SIGHUP'] as const
+
+/** Exit code after a signal ended the hidden input: 128 + SIGINT, as a cancel. */
+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`
+
+/**
+ * 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.
+ */
+const readHiddenFromTerminal = (prompt: string): Promise<string | null> =>
+  new Promise((resolve) => {
+    const stdin = process.stdin
+    let typed = ''
+    const restore = () => {
+      stdin.off('data', onData)
+      stdin.off('error', onError)
+      process.off('exit', restore)
+      for (const signal of ENDING_SIGNALS) process.off(signal, onSignal)
+      if (stdin.isTTY) stdin.setRawMode(false)
+      stdin.pause()
+    }
+    // A closed pane or a kill ends the process without `exit`: give the terminal back first.
+    const onSignal = () => {
+      restore()
+      process.exit(SIGNAL_EXIT)
+    }
+    // A terminal that goes away (EIO) ends the input as cancelled instead of leaving it open.
+    const onError = () => {
+      restore()
+      resolve(null)
+    }
+    const onData = (chunk: Buffer | string) => {
+      const step = hiddenInputStep(typed, chunk.toString())
+      if (step.kind === 'typing') {
+        typed = step.value
+        return
+      }
+      restore()
+      process.stderr.write('\n')
+      resolve(step.kind === 'done' ? step.value : null)
+    }
+    process.stderr.write(prompt)
+    process.on('exit', restore)
+    for (const signal of ENDING_SIGNALS) process.once(signal, onSignal)
+    stdin.setRawMode(true)
+    stdin.resume()
+    stdin.on('data', onData)
+    stdin.on('error', onError)
+  })
+
+const terminalPorts = (): SecretPorts => ({
+  store: secretStore(),
+  isTerminal: () => process.stdin.isTTY === true,
+  readHidden: readHiddenFromTerminal,
+  sources: () => configuredSources([worktreeRoot(process.cwd()), mainCheckout(process.cwd())]),
+  environment: process.env,
+  out: (line) => console.log(line),
+  err: (line) => console.error(line),
+})
+
+const setSecret = async (name: string, ports: SecretPorts): Promise<number> => {
+  if (!ports.isTerminal()) {
+    ports.err(NO_TERMINAL)
+    return NO_TERMINAL_EXIT
+  }
+  const value = await ports.readHidden(`${name} (hidden, Enter stores, Ctrl-C cancels): `)
+  if (value === null || value === '') {
+    ports.err(value === null ? 'cancelled, nothing stored' : 'empty value, nothing stored')
+    return 1
+  }
+  if ((await ports.store.set(name, value)) === SECRET_WRITE.unavailable) {
+    ports.err('secret store unavailable, nothing stored')
+    return 1
+  }
+  ports.out(`stored ${name} in the keychain (service ${SECRET_SERVICE})`)
+  return 0
+}
+
+const listSecrets = async (ports: SecretPorts): Promise<number> => {
+  const { sources, notes } = ports.sources()
+  for (const note of notes) ports.err(note)
+  const required = requiredSecrets(sources)
+  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 }
+    const status = secret.keychain
+      ? secretStatusOf(secret.name, lookup, ports.environment)
+      : environmentOnlyStatusOf(secret.name, ports.environment)
+    return { ...secret, status }
+  })
+  for (const line of secretListing(rows)) ports.out(line)
+  return 0
+}
+
+const deleteSecret = async (name: string, ports: SecretPorts): Promise<number> => {
+  const deleted = await ports.store.delete(name)
+  if (deleted === SECRET_WRITE.unavailable) {
+    ports.err('secret store unavailable, nothing deleted')
+    return 1
+  }
+  ports.out(deleted === SECRET_WRITE.done ? `deleted ${name}` : `${name} was not set`)
+  return 0
+}
+
+/**
+ * `jh secret set <NAME> | list | delete <NAME>`: the keychain entries (service `jackherd`) the sources' `secrets`
+ * name. `set` asks for the value hidden in a terminal and exits 2 without one, never reading a pipe; `list` prints
+ * the names the sources need with their status and never a value. Exit 0, 1 on a wrong command line or a keychain
+ * without an answer.
+ */
+export const run = async (args: string[], ports: SecretPorts = terminalPorts()): Promise<number> => {
+  const request = parseSecretArgs(args)
+  if (request.kind === 'help') {
+    if (args.length === 0) {
+      ports.err(SECRET_USAGE)
+      return 1
+    }
+    ports.out(SECRET_USAGE)
+    return 0
+  }
+  if (request.kind === 'error') {
+    ports.err(`${request.message}\n${SECRET_USAGE}`)
+    return 1
+  }
+  try {
+    if (request.kind === SECRET_ACTION.set) return await setSecret(request.name, ports)
+    if (request.kind === SECRET_ACTION.delete) return await deleteSecret(request.name, ports)
+    return await listSecrets(ports)
+  } catch (error) {
+    ports.err(errorText(error))
+    return 1
+  }
+}

package/src/secrets/environment.ts

@@ -0,0 +1,45 @@
+import { SECRET_LOOKUP, type SecretLookup, type SecretLookupFn } from './store'
+
+/** Environment variables as a process sees them; `process.env` fits. */
+export type Environment = Record<string, string | undefined>
+
+/** The environment a source's command starts with, or the class of reason it cannot start: never a value. */
+export type SourceEnvironment = { ok: true; environment: Environment } | { ok: false; reason: string }
+
+/** Why a source's secrets could not be resolved; `secret missing: <NAME>` comes from `secretMissing`. */
+export const SECRET_FAILURE = { unavailable: 'secret store unavailable' } as const
+
+export const secretMissing = (name: string): string => `secret missing: ${name}`
+
+type Resolved = { value: string } | { reason: string }
+
+/** Keychain first, then the environment; without either the reason names the keychain when it gave no answer. */
+const resolved = (name: string, lookup: SecretLookup, environment: Environment): Resolved => {
+  if (lookup.kind === SECRET_LOOKUP.found) return { value: lookup.value }
+  const fromEnvironment = environment[name]
+  if (fromEnvironment) return { value: fromEnvironment }
+  return { reason: lookup.kind === SECRET_LOOKUP.unavailable ? SECRET_FAILURE.unavailable : secretMissing(name) }
+}
+
+/**
+ * The environment of a source's command: `environment` with each of `names` set, looked up in the keychain first,
+ * then taken from `environment` itself. A name in neither fails the run with `secret missing: <NAME>`, or with
+ * `secret store unavailable` when the keychain gave no answer; the first such name in `names` decides. The lookups
+ * run side by side, so a keychain that hangs costs one lookup's time limit, not one per name. `environment` is not
+ * changed, and the answer is kept by no one: the caller hands it to the command and drops it.
+ */
+export const sourceEnvironment = async (
+  names: readonly string[],
+  lookup: SecretLookupFn,
+  environment: Environment,
+): Promise<SourceEnvironment> => {
+  if (names.length === 0) return { ok: true, environment: { ...environment } }
+  const lookups = await Promise.all(names.map((name) => lookup(name)))
+  const values: Record<string, string> = {}
+  for (const [index, name] of names.entries()) {
+    const entry = resolved(name, lookups[index] ?? { kind: SECRET_LOOKUP.absent }, environment)
+    if ('reason' in entry) return { ok: false, reason: entry.reason }
+    values[name] = entry.value
+  }
+  return { ok: true, environment: { ...environment, ...values } }
+}

package/src/secrets/hidden-input.ts

@@ -0,0 +1,51 @@
+/** Where typing a hidden value stands: still typing, ended with Enter, or cancelled (nothing is written then). */
+export type HiddenInput = { kind: 'typing'; value: string } | { kind: 'done'; value: string } | { kind: 'cancelled' }
+
+const ENTER = new Set(['\r', '\n'])
+const CANCEL = new Set(['\x03', '\x04'])
+const BACKSPACE = new Set(['\x7f', '\b'])
+const CLEAR_LINE = '\x15'
+const ESCAPE = '\x1b'
+const CSI_START = '['
+const SS3_START = 'O'
+
+const isControl = (character: string): boolean => (character.codePointAt(0) ?? 0) < 0x20
+
+/** The index after an escape sequence starting at `start` (the escape character): a CSI up to its final byte, SS3 and others one character. */
+const afterEscape = (characters: readonly string[], start: number): number => {
+  const introducer = characters[start + 1]
+  if (introducer === SS3_START) return start + 3
+  if (introducer !== CSI_START) return start + 2
+  let index = start + 2
+  while (index < characters.length) {
+    const code = characters[index]?.codePointAt(0) ?? 0
+    index += 1
+    if (code >= 0x40 && code <= 0x7e) return index
+  }
+  return index
+}
+
+/**
+ * One chunk of raw terminal input applied to the hidden value typed so far. Enter ends it, Ctrl-C or Ctrl-D cancel
+ * it, Backspace removes the last character and Ctrl-U the whole line; arrow keys and other escape sequences and
+ * further control characters are dropped. Whatever follows Enter in the same chunk is ignored.
+ */
+export const hiddenInputStep = (typed: string, chunk: string): HiddenInput => {
+  const characters = Array.from(chunk)
+  let value = Array.from(typed)
+  let index = 0
+  while (index < characters.length) {
+    const character = characters[index] ?? ''
+    if (ENTER.has(character)) return { kind: 'done', value: value.join('') }
+    if (CANCEL.has(character)) return { kind: 'cancelled' }
+    if (character === ESCAPE) {
+      index = afterEscape(characters, index)
+      continue
+    }
+    if (BACKSPACE.has(character)) value = value.slice(0, -1)
+    else if (character === CLEAR_LINE) value = []
+    else if (!isControl(character)) value.push(character)
+    index += 1
+  }
+  return { kind: 'typing', value: value.join('') }
+}

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 =>