jackherd 1.23.3 → 1.24.0

package/src/backend/lock.ts

@@ -0,0 +1,84 @@
+import { closeSync, openSync, readFileSync, rmSync, statSync, writeSync } from 'node:fs'
+import { lockedPid } from '../watch/watcher-lock'
+
+const PRIVATE_FILE = 0o600
+const RETRY_MS = 200
+const UNFILLED_LOCK_MS = 10_000
+/** Longer than any call holds the lock: a `jh backend` call waits at most 90 s for it and 30 s for a stop. */
+const HELD_LOCK_MS = 5 * 60_000
+
+/** Whether a process with this id exists; a process of another user still counts as alive. */
+const isAlive = (pid: number): boolean => {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'EPERM'
+  }
+}
+
+const readHolder = (path: string): number | null => {
+  try {
+    return lockedPid(readFileSync(path, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+const modifiedAt = (path: string): number | null => {
+  try {
+    return statSync(path).mtimeMs
+  } catch {
+    return null
+  }
+}
+
+/**
+ * A lock whose holder has ended, one older than `HELD_LOCK_MS` (no call holds it that long, so its process id was
+ * reused by another process), or one without a holder (a writer between creating and filling it) that is older than
+ * `UNFILLED_LOCK_MS`.
+ */
+const isStale = (path: string): boolean => {
+  const modified = modifiedAt(path)
+  const age = modified === null ? 0 : Date.now() - modified
+  const holder = readHolder(path)
+  if (holder !== null) return !isAlive(holder) || age > HELD_LOCK_MS
+  return age > UNFILLED_LOCK_MS
+}
+
+/** Creates the lock file with this process's id; false when another holds it. A lock of a process that ended is taken over. */
+const tryLock = (path: string): boolean => {
+  try {
+    const descriptor = openSync(path, 'wx', PRIVATE_FILE)
+    writeSync(descriptor, String(process.pid))
+    closeSync(descriptor)
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error
+    if (!isStale(path)) return false
+    rmSync(path, { force: true })
+    return tryLock(path)
+  }
+}
+
+/**
+ * Runs `work` while this process holds the lock at `path`, so the watcher and `jh backend` never write `backend.json`
+ * over each other. Waits up to `waitMs` for another holder; null when the lock stayed taken (the watcher passes 0 and
+ * tries again at its next check).
+ *
+ * Accepted risk: two callers that find the same stale lock at the same moment can both remove it, and the second
+ * removes the lock the first just created; both then run. It needs a holder that died and two callers within
+ * milliseconds, and both are the same user's watcher and `jh backend`.
+ */
+export const withBackendLock = async <T>(path: string, waitMs: number, work: () => Promise<T>): Promise<T | null> => {
+  const deadline = Date.now() + waitMs
+  while (!tryLock(path)) {
+    if (Date.now() >= deadline) return null
+    await Bun.sleep(RETRY_MS)
+  }
+  try {
+    return await work()
+  } finally {
+    if (readHolder(path) === process.pid) rmSync(path, { force: true })
+  }
+}

package/src/backend/process-cwd.ts

@@ -0,0 +1,32 @@
+import { readlinkSync } from 'node:fs'
+
+/** Longest an `lsof` call may take; a call past it counts as no answer. */
+const LSOF_TIMEOUT_MS = 2000
+
+/** The directory of an `lsof -Fn` answer for one process's `cwd`: the line that starts with `n`. */
+export const cwdOfLsofOutput = (output: string): string | null => {
+  const line = output.split('\n').find((each) => each.startsWith('n'))
+  return line ? line.slice(1) : null
+}
+
+const linuxCwdOf = (pid: number): string | null => {
+  try {
+    return readlinkSync(`/proc/${pid}/cwd`)
+  } catch {
+    return null
+  }
+}
+
+const lsofCwdOf = (pid: number): string | null => {
+  const result = Bun.spawnSync(['lsof', '-a', '-p', String(pid), '-d', 'cwd', '-Fn'], {
+    stdin: 'ignore',
+    stdout: 'pipe',
+    stderr: 'ignore',
+    timeout: LSOF_TIMEOUT_MS,
+  })
+  return result.exitCode === 0 ? cwdOfLsofOutput(result.stdout.toString()) : null
+}
+
+/** The working directory of a process: `/proc/<pid>/cwd` on Linux, `lsof` elsewhere (macOS); null when unreadable. */
+export const processCwdOf = (pid: number, platform: NodeJS.Platform = process.platform): string | null =>
+  platform === 'linux' ? linuxCwdOf(pid) : lsofCwdOf(pid)

package/src/backend/schema.ts

@@ -0,0 +1,47 @@
+import { z } from 'zod'
+import { MAX_PORT } from '../lane/port'
+import { SHELL_WORD } from '../shared/shell-word'
+
+/** Where the names of the services not handed to a lane go in `lanes.backend.command`. */
+export const SERVICES_PLACEHOLDER = '{services}'
+
+/** The pane label of the backend when the config names none. */
+export const DEFAULT_BACKEND_LABEL = 'backend'
+
+/** One herdr argument that cannot read as an option. */
+const BACKEND_LABEL = /^(?!-)[\w.-]+$/
+
+const duplicateIn = (values: readonly (string | number)[]): boolean => new Set(values).size !== values.length
+
+const serviceSchema = z.strictObject({
+  /** The name the command's tool takes, e.g. a package name. */
+  name: z.string().regex(SHELL_WORD, 'must be one shell word of letters, digits and @ . / : _ -, not starting with -'),
+  /** The port the service listens on; checked before a start and named when the service is handed to a lane. */
+  port: z.number().int().min(1).max(MAX_PORT),
+})
+
+export const backendSchema = z
+  .strictObject({
+    /** The command that runs the services in the main checkout; `{services}` becomes the names of the services not handed to a lane. */
+    command: z
+      .string()
+      .min(1)
+      .refine((command) => command.includes(SERVICES_PLACEHOLDER), `must contain ${SERVICES_PLACEHOLDER}`),
+    services: z.array(serviceSchema).min(1),
+    /** The label of the backend pane; `backend` when left out. */
+    label: z
+      .string()
+      .regex(BACKEND_LABEL, 'letters, digits and . _ -, not starting with -')
+      .default(DEFAULT_BACKEND_LABEL),
+  })
+  .refine(({ services }) => !duplicateIn(services.map(({ name }) => name)), {
+    message: 'service names must be unique',
+    path: ['services'],
+  })
+  .refine(({ services }) => !duplicateIn(services.map(({ port }) => port)), {
+    message: 'service ports must be unique',
+    path: ['services'],
+  })
+
+/** The shared backend of the lanes: its command, the services it runs and the pane label. */
+export type BackendConfig = z.infer<typeof backendSchema>

package/src/backend/state.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod'
+
+/** What the watcher sees of the backend pane. */
+export const BACKEND_PANE = { missing: 'missing', running: 'running', exited: 'exited' } as const
+
+export type BackendPane = (typeof BACKEND_PANE)[keyof typeof BACKEND_PANE]
+
+export const isBackendPane = (value: string): value is BackendPane =>
+  (Object.values(BACKEND_PANE) as string[]).includes(value)
+
+/** The version `backend.json` is written with; a file of another version is read as empty. */
+export const BACKEND_STATE_VERSION = 1
+
+const backendStateSchema = z.strictObject({
+  version: z.literal(BACKEND_STATE_VERSION),
+  /** The command line last started, null before the first start. */
+  command: z.string().nullable(),
+  /** The services a lane works on, by service name and lane name. */
+  released: z.array(z.strictObject({ service: z.string(), lane: z.string() })),
+  /** When the automatic starts happened, in milliseconds since the epoch. */
+  starts: z.array(z.number()),
+  /** Whether the start limit was reached; only `jh backend restart` clears it. */
+  gaveUp: z.boolean(),
+  /** The last line the watcher reported for a standing condition, so the same line is not repeated; null when none stands. */
+  notice: z.string().nullable(),
+})
+
+/** The content of `backend.json` in the watcher's state directory. */
+export type BackendState = z.infer<typeof backendStateSchema>
+
+export const EMPTY_BACKEND_STATE: BackendState = {
+  version: BACKEND_STATE_VERSION,
+  command: null,
+  released: [],
+  starts: [],
+  gaveUp: false,
+  notice: null,
+}
+
+/** The state in the text of `backend.json`; a missing, old or damaged file reads as the empty state. */
+export const parseBackendState = (text: string | null): BackendState => {
+  if (text === null) return EMPTY_BACKEND_STATE
+  try {
+    const parsed = backendStateSchema.safeParse(JSON.parse(text))
+    return parsed.success ? parsed.data : EMPTY_BACKEND_STATE
+  } catch {
+    return EMPTY_BACKEND_STATE
+  }
+}
+
+/** The state after `jh backend restart`: the start history and "gave up" are forgotten, the handovers stay. */
+export const restarted = (state: BackendState): BackendState => ({
+  ...state,
+  starts: [],
+  gaveUp: false,
+  notice: null,
+})

package/src/backend/step.ts

@@ -0,0 +1,93 @@
+import { MS_PER_MINUTE } from '../plan-format/clock'
+import { BACKEND_PANE, type BackendPane, type BackendState } from './state'
+
+/** At most this many automatic starts within `BACKEND_START_WINDOW_MS`. */
+export const BACKEND_START_LIMIT = 3
+export const BACKEND_START_WINDOW_MS = 10 * MS_PER_MINUTE
+
+export const BACKEND_STEP_ACTION = { none: 'none', start: 'start', split: 'split' } as const
+
+export type BackendStepAction = (typeof BACKEND_STEP_ACTION)[keyof typeof BACKEND_STEP_ACTION]
+
+export const BACKEND_GIVE_UP_LINE = `backend: gave up after ${BACKEND_START_LIMIT} starts in ${BACKEND_START_WINDOW_MS / MS_PER_MINUTE} minutes; jh backend restart`
+export const BACKEND_DIFFERS_LINE = 'backend: running command differs from lanes.backend; jh backend restart'
+
+/** What the watcher found: the pane, where it sits, the busy service ports of the current list, the wanted command. */
+export type BackendObservation = {
+  pane: BackendPane
+  /** The pane's id, or the tab label when the pane is still to be created; named in the start line. */
+  place: string
+  busyPorts: readonly number[]
+  /** The command line `backendCommandOf` gives; null when every service is released. */
+  desired: string | null
+}
+
+export type BackendStep = { action: BackendStepAction; state: BackendState; line: string | null }
+
+const stay = (state: BackendState): BackendStep => ({ action: BACKEND_STEP_ACTION.none, state, line: null })
+
+/** Reports `line` only when it differs from the one already standing. */
+export const noticed = (state: BackendState, line: string): BackendStep => ({
+  action: BACKEND_STEP_ACTION.none,
+  state: { ...state, notice: line },
+  line: state.notice === line ? null : line,
+})
+
+const settled = (state: BackendState): BackendState => (state.notice === null ? state : { ...state, notice: null })
+
+const runningStep = (state: BackendState, desired: string | null): BackendStep =>
+  desired === null || state.command === desired ? stay(settled(state)) : noticed(state, BACKEND_DIFFERS_LINE)
+
+const portLine = (port: number): string => `backend: port ${port} in use, not started`
+
+const started = (
+  state: BackendState,
+  observation: BackendObservation,
+  desired: string,
+  starts: number[],
+): BackendStep => ({
+  action: observation.pane === BACKEND_PANE.missing ? BACKEND_STEP_ACTION.split : BACKEND_STEP_ACTION.start,
+  state: { ...state, command: desired, starts, notice: null },
+  line: `backend: started in ${observation.place}`,
+})
+
+const startStep = (state: BackendState, observation: BackendObservation, desired: string, now: number): BackendStep => {
+  const recent = state.starts.filter((start) => now - start < BACKEND_START_WINDOW_MS)
+  if (recent.length >= BACKEND_START_LIMIT)
+    return noticed({ ...state, starts: recent, gaveUp: true }, BACKEND_GIVE_UP_LINE)
+  return started(state, observation, desired, [...recent, now])
+}
+
+const refusedByHand = (state: BackendState, line: string): BackendStep => ({
+  action: BACKEND_STEP_ACTION.none,
+  state,
+  line,
+})
+
+/**
+ * The start `jh backend` makes after it stopped the pane (`restart`, `release`, `return`): no start limit, no start
+ * counted, every refusal said each time, since a person asked for it. A busy port prevents it as at every check.
+ */
+export const startedByHand = (state: BackendState, observation: BackendObservation): BackendStep => {
+  const { pane, desired, busyPorts, place } = observation
+  if (pane === BACKEND_PANE.running) return refusedByHand(state, `backend: still running in ${place}, not started`)
+  if (desired === null)
+    return refusedByHand({ ...state, command: null }, 'backend: every service is handed to a lane, nothing started')
+  const [busy] = busyPorts
+  if (busy !== undefined) return refusedByHand(state, portLine(busy))
+  return started(state, observation, desired, state.starts)
+}
+
+/**
+ * The decision of one check: what to do with the pane, the state to keep and the line to report, if any. A standing
+ * condition (a busy port, a differing command, the given-up state) is reported once, not at every check. Nothing here
+ * stops a process or frees a port: a busy port only prevents the start.
+ */
+export const backendStep = (state: BackendState, observation: BackendObservation, now: number): BackendStep => {
+  const { pane, desired, busyPorts } = observation
+  if (pane === BACKEND_PANE.running) return runningStep(state, desired)
+  if (desired === null || state.gaveUp) return stay(state)
+  const [busy] = busyPorts
+  if (busy !== undefined) return noticed(state, portLine(busy))
+  return startStep(state, observation, desired, now)
+}

package/src/backend/system.ts

@@ -0,0 +1,150 @@
+import { realpathSync } from 'node:fs'
+import { join } from 'node:path'
+import { writePrivateFile } from '../../kit/hooks/hooks/shared/private-directory'
+import { worktreeNames } from '../plans/git'
+import { paneListOf } from '../plans/plan-panes'
+import { listeningPorts } from '../plans/port-listening'
+import { readPrivateText } from '../shared/private-location'
+import { type HerdrRunner, renameArguments, runHerdr } from '../terminal/herdr'
+import { ensureWatcherDirectory } from '../watch/watcher-lock'
+import type { BackendSystem } from './control'
+import {
+  type BackendSight,
+  backendSightOf,
+  createdPaneOf,
+  mainWorkspaceOf,
+  type PaneProcesses,
+  paneProcessesOf,
+  stopTargetOf,
+  tabIdsOf,
+} from './herdr'
+import { processCwdOf } from './process-cwd'
+import type { BackendConfig } from './schema'
+import { BACKEND_PANE, parseBackendState } from './state'
+
+/** The backend's files in the watcher's directory of the repository, beside `watch-state.json`. */
+export const BACKEND_FILES = { state: 'backend.json', lock: 'backend.lock' } as const
+
+export type BackendFiles = Record<keyof typeof BACKEND_FILES, string>
+
+type Context = { root: string; label: string; run: HerdrRunner }
+
+type StopResult = { ok: true } | { ok: false; line: string }
+
+/** How long `jh backend` waits for a stopped backend to free its pane and ports. */
+const STOP_WAIT_MS = 30_000
+const STOP_POLL_MS = 500
+
+/** The paths of the backend's state and lock for the main checkout `root`; creates the private directory. */
+export const backendFilesOf = (root: string): BackendFiles => {
+  const directory = ensureWatcherDirectory(root)
+  return { state: join(directory, BACKEND_FILES.state), lock: join(directory, BACKEND_FILES.lock) }
+}
+
+const workspaceOf = ({ root, run }: Context): string => mainWorkspaceOf(run(['workspace', 'list']), root)
+
+const processesOf = (context: Context, pane: string): PaneProcesses =>
+  paneProcessesOf(context.run(['pane', 'process-info', '--pane', pane]))
+
+const lookWith = (context: Context): BackendSight =>
+  backendSightOf({
+    panes: paneListOf(context.run(['pane', 'list'])),
+    tabs: tabIdsOf(context.run(['tab', 'list', '--workspace', workspaceOf(context)])),
+    label: context.label,
+    root: context.root,
+    foregroundOf: (pane) => processesOf(context, pane).processes.map(({ argv }) => argv),
+  })
+
+const busyPortsOf = async (ports: readonly number[]): Promise<number[]> => {
+  const listening = await listeningPorts(ports)
+  return ports.filter((port) => listening.has(port))
+}
+
+/** A new tab in the main checkout's workspace, without focus, working in `root`; its pane labelled and running `command`. */
+const createWith = (context: Context, command: string): string => {
+  const { root, label, run } = context
+  const created = run([
+    'tab',
+    'create',
+    '--workspace',
+    workspaceOf(context),
+    '--cwd',
+    root,
+    '--label',
+    label,
+    '--no-focus',
+  ])
+  const pane = createdPaneOf(created)
+  run(renameArguments(pane, label))
+  run(['pane', 'run', pane, command])
+  return pane
+}
+
+const isStopped = async (context: Context, ports: readonly number[]): Promise<boolean> => {
+  const sight = lookWith(context)
+  return sight.kind === 'found' && sight.pane !== BACKEND_PANE.running && (await busyPortsOf(ports)).length === 0
+}
+
+/** SIGTERM to `pid`; a process that ended since it was read is what the stop wanted, any other failure propagates. */
+const terminate = (pid: number) => {
+  try {
+    process.kill(pid, 'SIGTERM')
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error
+  }
+}
+
+const waitUntilStopped = async (context: Context, pane: string, pid: number, ports: readonly number[]) => {
+  const deadline = Date.now() + STOP_WAIT_MS
+  while (Date.now() < deadline) {
+    if (await isStopped(context, ports)) return { ok: true } as const
+    await Bun.sleep(STOP_POLL_MS)
+  }
+  return {
+    ok: false,
+    line: `backend: still running ${STOP_WAIT_MS / 1000} s after SIGTERM to ${pid}; stop it in pane ${pane}`,
+  } as const
+}
+
+/**
+ * SIGTERM to the leader of the pane's foreground group once `stopTargetOf` accepted it (never the shell, only a
+ * process in the main checkout), then a wait until the pane is a shell again and the ports are free. The pane is read
+ * a second time after the directory check, and the signal goes out only when the same group still leads it, so a
+ * process id reused in between is not hit. Never a port kill.
+ */
+const stopWith = async (context: Context, pane: string, ports: readonly number[]): Promise<StopResult> => {
+  const target = stopTargetOf(processesOf(context, pane), context.root, (pid) => processCwdOf(pid), pane)
+  if (!target.ok) return target
+  if (processesOf(context, pane).groupId !== target.pid)
+    return { ok: false, line: `backend: the process in pane ${pane} changed while it was checked; try again` }
+  terminate(target.pid)
+  return waitUntilStopped(context, pane, target.pid, ports)
+}
+
+/**
+ * The backend's calls for the main checkout `root`: herdr through `run`, the state in `files`, the ports probed on
+ * this machine, the lanes' worktrees under `worktreeDirectory`.
+ */
+export const backendSystemOf = (input: {
+  root: string
+  worktreeDirectory: string
+  backend: BackendConfig
+  files: BackendFiles
+  run?: HerdrRunner
+}): BackendSystem => {
+  const root = realpathSync(input.root)
+  const context: Context = { root, label: input.backend.label, run: input.run ?? runHerdr }
+  return {
+    readState: () => parseBackendState(readPrivateText(input.files.state)),
+    writeState: (state) => writePrivateFile(input.files.state, `${JSON.stringify(state)}\n`),
+    look: () => lookWith(context),
+    busyPorts: busyPortsOf,
+    create: (command) => createWith(context, command),
+    run: (pane, command) => {
+      context.run(['pane', 'run', pane, command])
+    },
+    stop: (pane, ports) => stopWith(context, pane, ports),
+    worktrees: () => worktreeNames(join(root, input.worktreeDirectory)),
+    now: Date.now,
+  }
+}

package/src/backend/watch.ts

@@ -0,0 +1,75 @@
+import { readConfig } from '../config/read-config'
+import type { JackherdConfig } from '../config/schema'
+import { errorText } from '../plans/error-text'
+import { checkBackend } from './control'
+import { withBackendLock } from './lock'
+import type { BackendConfig } from './schema'
+import { backendFilesOf, backendSystemOf } from './system'
+
+/** The watcher's memory of the backend between polls: the last check and whether a failure was already said. */
+export type BackendWatch = { checkedAt: number | null; failureReported: boolean }
+
+export type BackendWatchEffects = {
+  /** One check; null when `jh backend` holds the lock, so the next check tries again. */
+  check: () => Promise<string[] | null>
+  log: (line: string) => void
+  /** Put behind every line: where the coordinator reads what to do. */
+  hint: string
+}
+
+/** The backend and the lanes' worktree directory, both from the main checkout's config. */
+export type MainCheckoutBackend = { backend: BackendConfig; worktreeDirectory: string }
+
+/** The watcher checks the backend pane at its start and then once a minute, not at every poll. */
+export const BACKEND_CHECK_MS = 60_000
+
+export const INITIAL_BACKEND_WATCH: BackendWatch = { checkedAt: null, failureReported: false }
+
+export const backendCheckDue = ({ checkedAt }: BackendWatch, now: number): boolean =>
+  checkedAt === null || now - checkedAt >= BACKEND_CHECK_MS
+
+/**
+ * Checks the backend when one is due and prints its lines. A failure never ends the watch; it is printed once until
+ * a check works again, as `keepPlanViews` does for the herd panes.
+ */
+export const keepBackend = async (
+  watch: BackendWatch,
+  now: number,
+  effects: BackendWatchEffects,
+): Promise<BackendWatch> => {
+  if (!backendCheckDue(watch, now)) return watch
+  try {
+    for (const line of (await effects.check()) ?? []) effects.log(`${line}${effects.hint}`)
+    return { checkedAt: now, failureReported: false }
+  } catch (error) {
+    if (!watch.failureReported) effects.log(`backend check failed, still watching: ${errorText(error)}${effects.hint}`)
+    return { checkedAt: now, failureReported: true }
+  }
+}
+
+/**
+ * `lanes.backend` and `worktreeDirectory` of the main checkout's config only: a lane's worktree must change neither
+ * what the watcher runs in the main checkout nor which lanes count as gone. `config` is reused when the watcher
+ * already read the main checkout; undefined without a backend or when that config cannot be read.
+ */
+export const mainCheckoutBackendOf = (
+  root: string,
+  checkoutRoot: string,
+  config: JackherdConfig,
+): MainCheckoutBackend | undefined => {
+  try {
+    const main = checkoutRoot === root ? config : readConfig([root])
+    return main.lanes.backend ? { backend: main.lanes.backend, worktreeDirectory: main.worktreeDirectory } : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/** One check of the main checkout's backend under the lock, without waiting for it. */
+export const backendCheckOf =
+  (root: string, { backend, worktreeDirectory }: MainCheckoutBackend) =>
+  (): Promise<string[] | null> => {
+    const files = backendFilesOf(root)
+    const system = backendSystemOf({ root, worktreeDirectory, backend, files })
+    return withBackendLock(files.lock, 0, () => checkBackend(backend, system))
+  }

package/src/cli.ts

@@ -19,6 +19,7 @@ const ALIASES = new Set<string>([HERD_COMMAND.alias])
 /** One line per command; each entry lazily imports the module that exports its `run`. */
 export const COMMANDS: CommandTable = {
   approval: () => import('./approval/command'),
+  backend: () => import('./backend/command-line'),
   brief: () => import('./brief/command'),
   check: () => import('./check/command'),
   config: () => import('./config/command'),

package/src/config/schema.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { backendSchema } from '../backend/schema'
 import { checkConfigSchema } from '../check/schema'
 import { claudePath, WORKTREES_DIRECTORY } from '../claude/paths'
 import { SECRET_NAME } from '../secrets/options'
@@ -607,6 +608,8 @@ export const jackherdConfigSchema = z.strictObject({
       basePort: z.number().int().min(1).max(65535).optional(),
       /** The command `jh lane dev` runs as `PORT=<port> <command>` in a pane beside the lane's agent; `{port}` and `{filter}` (`--filter <package>`) are filled in. Without it `jh lane dev` refuses. */
       devCommand: z.string().min(1).optional(),
+      /** The services every lane's app talks to, run in one pane of the main checkout that the watcher starts and keeps; without it `jh backend` has nothing to run. */
+      backend: backendSchema.optional(),
     })
     .prefault({}),
   models: z.record(z.enum(Object.values(MODEL_ROLE)), modelId).default(DEFAULT_MODELS),

package/src/lane/dev.ts

@@ -1,4 +1,5 @@
 import { isRecord } from '../shared/is-record'
+import { SHELL_WORD } from '../shared/shell-word'
 import { CLI_NAME } from '../version/release'
 import { MAX_PORT } from './port'
 
@@ -36,7 +37,6 @@ board, the command is lanes.devCommand of the config ({port} and {filter} stand
 PORT=<port> <command> in a pane labelled "<lane> dev :<port>". A port something listens on is refused; a pane with
 that label in the lane's tab is reported and left alone.`
 
-const FILTER_VALUE = /^[\w@./:-]+$/
 const PORT_PLACEHOLDER = '{port}'
 const FILTER_PLACEHOLDER = '{filter}'
 
@@ -83,7 +83,7 @@ export const devLabelOf = (lane: string, port: number): string => `${lane} dev :
  */
 export const devCommandOf = (template: string | null | undefined, port: number, filter: string | null): string => {
   if (!template) throw new Error('no dev command: set lanes.devCommand in .jackherd/config.json')
-  if (filter !== null && !FILTER_VALUE.test(filter)) throw new Error(`${FILTER} ${filter} is no package name`)
+  if (filter !== null && !SHELL_WORD.test(filter)) throw new Error(`${FILTER} ${filter} is no package name`)
   if (filter === null && template.includes(FILTER_PLACEHOLDER))
     throw new Error(`lanes.devCommand names {filter}: pass ${FILTER} <package>`)
   const command = template.replaceAll(PORT_PLACEHOLDER, String(port)).replaceAll(FILTER_PLACEHOLDER, filter ?? '')

package/src/plans/plan-panes.ts

@@ -151,7 +151,7 @@ export const isIdleShell = ({ agent, foreground }: PaneState): boolean =>
  * A restored pane whose shell is still starting: nothing in the foreground yet, or a shell first (its prompt may run
  * `git` beside it). Another program there, an editor or a pager, would take the command as its input.
  */
-const isStartingShell = ({ agent, foreground }: PaneState): boolean =>
+export const isStartingShell = ({ agent, foreground }: PaneState): boolean =>
   !agent && (foreground.length === 0 || SHELLS.has(programOf(foreground[0])))
 
 const hasHerdBeside = (panes: readonly PaneState[], agent: PaneState): boolean =>

package/src/plans/settings.ts

@@ -23,6 +23,8 @@ export type PlansSettings = Pick<
   basePort: number
   /** The command `jh lane dev` starts a lane's dev server with (`lanes.devCommand`); undefined when none is set. */
   devCommand: string | undefined
+  /** The shared backend of the lanes (`lanes.backend`); undefined when none is set. */
+  backend: JackherdConfig['lanes']['backend']
   fetchIntervalMinutes: number
   /** Whether the running task of a folded lane shimmers; `NO_COLOR` keeps it still whatever this says. */
   shimmer: boolean
@@ -69,6 +71,7 @@ export const plansSettingsOf = (config: JackherdConfig): PlansSettings => ({
   minFreeGb: config.lanes.minFreeGb ?? DEFAULT_MIN_FREE_GB,
   basePort: config.lanes.basePort ?? DEFAULT_BASE_PORT,
   devCommand: config.lanes.devCommand,
+  backend: config.lanes.backend,
   fetchIntervalMinutes: config.plans.fetchIntervalMinutes,
   shimmer: config.plans.shimmer,
   linkKinds: config.plans.linkKinds,

package/src/shared/shell-word.ts

@@ -0,0 +1,2 @@
+/** One shell word that cannot start an option: a name that goes into a command line unquoted. */
+export const SHELL_WORD = /^(?!-)[\w@./:-]+$/