jackherd 0.0.1 → 1.0.0

package/src/sync/sync-plan.ts

@@ -0,0 +1,120 @@
+import { posix } from 'node:path'
+import { CLAUDE_DIRECTORY, SETTINGS_FILE } from '../claude/paths'
+import { type JackherdConfig, parseConfigFile } from '../config'
+import { type RepositoryFacts, withDetected } from '../config/detect'
+import { CONFIG_FILE, TOOL_DIRECTORY } from '../config/location'
+import { checksum } from './checksum'
+import { errorMessage } from './error-message'
+import type { KitSource } from './kit'
+import { parseKitHooks } from './kit-hooks'
+import { parseKitPath } from './kit-path'
+import type { Manifest } from './manifest'
+import { FILE_MODE, FILE_OUTCOME, type FilePlan, type RenderedFile } from './plan-file'
+import type { HooksPlan } from './plan-hooks'
+import type { HookDefinition } from './settings-hooks'
+
+export type AcceptRequest = { files: Set<string>; settings: boolean }
+
+const SETTINGS_ACCEPT_PATHS: readonly string[] = [SETTINGS_FILE, `${CLAUDE_DIRECTORY}/${SETTINGS_FILE}`]
+
+export const parseJson = (text: string, file: string, location: string = TOOL_DIRECTORY): unknown => {
+  try {
+    return JSON.parse(text)
+  } catch (err) {
+    throw new Error(`${location}/${file} is not valid JSON: ${errorMessage(err)}`)
+  }
+}
+
+/**
+ * `location` names the config's directory in messages: `.jackherd` in a project, `~/.jackherd` for a global install.
+ * With `facts`, the values the file leaves out are detected from that repository (see `withDetected`).
+ */
+export const parseConfig = (
+  text: string,
+  location: string = TOOL_DIRECTORY,
+  facts?: RepositoryFacts,
+): { config: JackherdConfig; notes: string[] } => {
+  const raw = parseJson(text, CONFIG_FILE, location)
+  const detected = facts ? withDetected(raw, facts) : { raw, notes: [] }
+  return { config: parseConfigFile(detected.raw, `${location}/${CONFIG_FILE}`), notes: detected.notes }
+}
+
+export const parseAcceptPaths = (raw: string[]): AcceptRequest => {
+  const files = new Set<string>()
+  let settings = false
+  for (const path of raw) {
+    if (SETTINGS_ACCEPT_PATHS.includes(path)) {
+      settings = true
+      continue
+    }
+    const parsed = parseKitPath(path)
+    if (!parsed.ok) throw new Error(`--accept ${path}: ${parsed.reason}`)
+    files.add(parsed.path)
+  }
+  return { files, settings }
+}
+
+/** Closed whatever the config says, so a tampered `.jackherd/config.json` cannot reopen it. */
+const DEFAULT_WORKTREE_PREFIX = 'worktrees/'
+
+/** Lower-case prefixes relative to `.claude/` that hold worktrees: the default and the configured one. */
+const worktreePrefixes = (config: JackherdConfig): string[] => {
+  const normalized = posix.normalize(config.worktreeDirectory)
+  const parsed = parseKitPath(normalized)
+  const configured = parsed.ok && normalized.startsWith(`${CLAUDE_DIRECTORY}/`) ? [`${parsed.path.toLowerCase()}/`] : []
+  return [DEFAULT_WORKTREE_PREFIX, ...configured]
+}
+
+/**
+ * Worktrees under `.claude/` hold other checkouts; no kit path, manifest entry or `--accept` may
+ * reach into them, whatever checksum a manifest entry claims.
+ */
+export const assertOutsideWorktrees = (paths: Iterable<string>, config: JackherdConfig): void => {
+  const prefixes = worktreePrefixes(config)
+  const inside = [...paths].filter((path) => prefixes.some((prefix) => path.toLowerCase().startsWith(prefix)))
+  if (inside.length > 0) {
+    throw new Error(`Refusing paths inside the worktree directory ${config.worktreeDirectory}: ${inside.join(', ')}`)
+  }
+}
+
+export const renderKitFiles = (kit: KitSource, render: (template: string) => string): Map<string, RenderedFile> => {
+  const rendered = new Map<string, RenderedFile>()
+  for (const file of kit.files) {
+    const parsed = parseKitPath(file.path)
+    if (!parsed.ok) throw new Error(`Kit file ${file.path} ${parsed.reason}`)
+    if (rendered.has(parsed.path)) throw new Error(`Kit file ${parsed.path} appears twice`)
+    const content = render(file.template)
+    const mode = file.executable ? FILE_MODE.executable : FILE_MODE.regular
+    rendered.set(parsed.path, { content, checksum: checksum(content), mode })
+  }
+  return rendered
+}
+
+export const renderKitHooks = (
+  kit: KitSource,
+  render: (template: string) => string,
+): Record<string, HookDefinition> => {
+  if (kit.hooksTemplate === undefined) return {}
+  const parsed = parseKitHooks(render(kit.hooksTemplate))
+  if (!parsed.ok) throw new Error(`Kit hooks are invalid: ${parsed.reason}`)
+  return parsed.hooks
+}
+
+/** Every `--accept` must land on something to accept; otherwise the run stops before any write. */
+export const assertAcceptsApply = (accept: AcceptRequest, files: FilePlan[], hooks: HooksPlan): void => {
+  const accepted = new Set(files.filter(({ outcome }) => outcome === FILE_OUTCOME.accepted).map(({ path }) => path))
+  const refused = [...accept.files].filter((path) => !accepted.has(path))
+  if (accept.settings && hooks.notAcceptable) refused.push(`${CLAUDE_DIRECTORY}/${SETTINGS_FILE}`)
+  if (refused.length > 0) {
+    throw new Error(`Nothing to accept for: ${refused.join(', ')} (no conflict, no deselected kit file or hook there)`)
+  }
+}
+
+export const nextManifest = (kitVersion: string, files: FilePlan[], hooks: HooksPlan): Manifest => {
+  const manifest: Manifest = {
+    kitVersion,
+    files: Object.fromEntries(files.flatMap(({ path, entry }) => (entry ? [[path, entry]] : []))),
+    hooks: hooks.entries,
+  }
+  return hooks.kitNewRecorded === undefined ? manifest : { ...manifest, settingsKitNew: hooks.kitNewRecorded }
+}

package/src/sync/sync-result.ts

@@ -0,0 +1,9 @@
+import type { FileOutcome } from './plan-file'
+import type { HookOutcome } from './plan-hooks'
+
+export type FileReport = { path: string; outcome: FileOutcome }
+
+export type HookReport = { name: string; outcome: HookOutcome }
+
+/** `notes` name the config values the repository did not decide, printed before the summary. */
+export type SyncResult = { files: FileReport[]; hooks: HookReport[]; notes?: string[] }

package/src/sync/sync.ts

@@ -0,0 +1,307 @@
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import { CLAUDE_DIRECTORY, SETTINGS_FILE } from '../claude/paths'
+import type { JackherdConfig } from '../config'
+import type { RepositoryFacts } from '../config/detect'
+import { CONFIG_FILE, MANIFEST_FILE, TOOL_DIRECTORY } from '../config/location'
+import { readRepositoryFacts } from '../config/repository-facts'
+import { REPOSITORY_TOKENS } from '../config/repository-values'
+import { CLI_NAME } from '../version/release'
+import { ensureGitignoreLines } from './gitignore'
+import { toGlobalKit, toProjectKit } from './global-kit'
+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 { FILE_MODE, type FileEffect, type FilePlan, planFile, type RenderedFile } from './plan-file'
+import { type HooksPlan, planHooks } from './plan-hooks'
+import {
+  assertNotHomeDirectory,
+  assertOwnDirectoriesInProject,
+  readLocalState,
+  readRegularFile,
+  removeFileSafely,
+  writeFileSafely,
+} from './project-fs'
+import { renderTemplate } from './render'
+import { parseSettings, type Settings } from './settings-hooks'
+import {
+  type AcceptRequest,
+  assertAcceptsApply,
+  assertOutsideWorktrees,
+  nextManifest,
+  parseAcceptPaths,
+  parseConfig,
+  parseJson,
+  renderKitFiles,
+  renderKitHooks,
+} from './sync-plan'
+import type { SyncResult } from './sync-result'
+
+/** A sync's result with the config it was read from, so a caller can name what the config decided. */
+export type ConfiguredSync = { result: SyncResult; config: JackherdConfig }
+
+export type SyncRequest = {
+  projectRoot: string
+  /** The user's home directory, which is never a project; defaults to the real one. */
+  home?: string
+  kit: KitSource
+  /** Paths from `--accept`, relative to `.claude/` or to the project root. */
+  accept: string[]
+  /** What fills the values the config leaves out; read from the project root when absent. */
+  facts?: RepositoryFacts
+}
+
+export type GlobalSyncRequest = {
+  /** The directory holding the user's `.claude/`, normally the home directory. */
+  home: string
+  kit: KitSource
+  /** Paths from `--accept`, relative to `~/.claude/`. */
+  accept: string[]
+  /** `XDG_CONFIG_HOME` as the command read it, where the old public-content facts lie; undefined for `~/.config`. */
+  configHome?: string
+}
+
+/** Where a lock path lies on disk: the directory to read and write it in, and the path below it. */
+type Location = { directory: string; path: string }
+
+type Locate = (path: string) => Location
+
+/** What the plan is built from once the target decided how to read its config and settings. */
+type PlanInput = {
+  claudeDirectory: string
+  toolDirectory: string
+  locate: Locate
+  kit: KitSource
+  config: JackherdConfig
+  accept: string[]
+  readHooks: (manifest: Manifest, accept: AcceptRequest) => Promise<HooksPlan>
+  /** Placeholders rendered as something other than their config value (see `renderTemplate`). */
+  overrides?: ReadonlyMap<string, string>
+}
+
+type SyncPlan = { files: FilePlan[]; hooks: HooksPlan; manifest: Manifest; manifestText: string | undefined }
+
+const SETTINGS_KIT_NEW = kitNewPath(SETTINGS_FILE)
+
+const GLOBAL_TOOL_LOCATION = `~/${TOOL_DIRECTORY}`
+
+/** `location` names the directory in messages; `initCommand` is what creates the config there. */
+const readConfig = async (
+  toolDirectory: string,
+  location: string,
+  initCommand: string,
+  facts?: RepositoryFacts,
+): Promise<{ config: JackherdConfig; notes: string[] }> => {
+  const text = await readRegularFile(toolDirectory, CONFIG_FILE)
+  if (text === undefined) throw new Error(`No ${location}/${CONFIG_FILE} found. Run \`${initCommand}\` first.`)
+  return parseConfig(text, location, facts)
+}
+
+const readManifest = async (toolDirectory: string): Promise<{ manifest: Manifest; text: string | undefined }> => {
+  const text = await readRegularFile(toolDirectory, MANIFEST_FILE)
+  if (text === undefined) return { manifest: EMPTY_MANIFEST, text }
+  const parsed = parseManifest(parseJson(text, MANIFEST_FILE))
+  if (!parsed.ok) throw new Error(`${TOOL_DIRECTORY}/${MANIFEST_FILE} is invalid:\n${parsed.reason}`)
+  return { manifest: parsed.manifest, text }
+}
+
+const readSettings = async (claudeDirectory: string): Promise<Settings> => {
+  const text = await readRegularFile(claudeDirectory, SETTINGS_FILE)
+  if (text === undefined) return {}
+  const parsed = parseSettings(parseJson(text, SETTINGS_FILE, CLAUDE_DIRECTORY))
+  if (!parsed.ok) throw new Error(`.claude/${SETTINGS_FILE} has hooks sync cannot read:\n${parsed.reason}`)
+  return parsed.settings
+}
+
+/** A project keeps every kit file in `.claude/`. */
+const inClaudeDirectory =
+  (claudeDirectory: string): Locate =>
+  (path) => ({ directory: claudeDirectory, path })
+
+/** A global install keeps the tool root's files in `~/.jackherd/`, everything else in `~/.claude/`. */
+const inGlobalDirectories =
+  (claudeDirectory: string, toolDirectory: string): Locate =>
+  (path) => {
+    const inTool = toolRootPath(path)
+    return inTool === null ? { directory: claudeDirectory, path } : { directory: toolDirectory, path: inTool }
+  }
+
+const localStateAt = ({ directory, path }: Location) => readLocalState(directory, path)
+
+const planFiles = async (
+  locate: Locate,
+  rendered: Map<string, RenderedFile>,
+  manifest: Manifest,
+  accept: AcceptRequest,
+): Promise<FilePlan[]> => {
+  const paths = [...new Set([...rendered.keys(), ...Object.keys(manifest.files)])].sort()
+  return Promise.all(
+    paths.map(async (path) =>
+      planFile({
+        path,
+        rendered: rendered.get(path) ?? null,
+        entry: manifest.files[path],
+        local: await localStateAt(locate(path)),
+        kitNew: await localStateAt(locate(kitNewPath(path))),
+        accept: accept.files.has(path),
+      }),
+    ),
+  )
+}
+
+const buildPlan = async ({
+  toolDirectory,
+  locate,
+  kit,
+  config,
+  accept: acceptPaths,
+  readHooks,
+  overrides,
+}: PlanInput): Promise<SyncPlan> => {
+  const { manifest, text: manifestText } = await readManifest(toolDirectory)
+  const accept = parseAcceptPaths(acceptPaths)
+  const render = (template: string) => renderTemplate(template, config, overrides)
+  const rendered = renderKitFiles(kit, render)
+  assertOutsideWorktrees([...rendered.keys(), ...Object.keys(manifest.files), ...accept.files], config)
+  const files = await planFiles(locate, rendered, manifest, accept)
+  const hooks = await readHooks(manifest, accept)
+  assertAcceptsApply(accept, files, hooks)
+  return { files, hooks, manifest: nextManifest(kit.version, files, hooks), manifestText }
+}
+
+/** Merges the kit's hooks into the project's `settings.json`. */
+const projectHooks =
+  (claudeDirectory: string, kit: KitSource, config: JackherdConfig) =>
+  async (manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> =>
+    planHooks({
+      kit: renderKitHooks(kit, (template) => renderTemplate(template, config)),
+      entries: manifest.hooks,
+      settings: await readSettings(claudeDirectory),
+      kitNew: await readLocalState(claudeDirectory, SETTINGS_KIT_NEW),
+      kitNewRecorded: manifest.settingsKitNew,
+      accept: accept.settings,
+    })
+
+/** A global install ships no hooks and never reads the user's `settings.json`. */
+const noHooks = async (_manifest: Manifest, accept: AcceptRequest): Promise<HooksPlan> =>
+  planHooks({
+    kit: {},
+    entries: {},
+    settings: {},
+    kitNew: { kind: 'missing' },
+    kitNewRecorded: undefined,
+    accept: accept.settings,
+  })
+
+const applyFileEffect = (locate: Locate, path: string, effect: FileEffect): Promise<void> => {
+  const { directory, path: target } = locate(effect.target === 'file' ? path : kitNewPath(path))
+  if (effect.kind === 'remove') return removeFileSafely(directory, target)
+  return writeFileSafely(directory, target, effect.content, effect.mode)
+}
+
+/** Writes before removals, so a file that moved (an old global path to the tool root) is never missing in between. */
+const effectsInOrder = (files: FilePlan[]): { path: string; effect: FileEffect }[] => {
+  const all = files.flatMap(({ path, effects }) => effects.map((effect) => ({ path, effect })))
+  return [
+    ...all.filter(({ effect }) => effect.kind !== 'remove'),
+    ...all.filter(({ effect }) => effect.kind === 'remove'),
+  ]
+}
+
+const applyHooks = async (claudeDirectory: string, hooks: HooksPlan): Promise<void> => {
+  if (hooks.changed) {
+    await writeFileSafely(
+      claudeDirectory,
+      SETTINGS_FILE,
+      `${JSON.stringify(hooks.settings, null, 2)}\n`,
+      FILE_MODE.regular,
+    )
+  }
+  if (hooks.kitNew.kind === 'write')
+    await writeFileSafely(claudeDirectory, SETTINGS_KIT_NEW, hooks.kitNew.content, FILE_MODE.regular)
+  if (hooks.kitNew.kind === 'remove') await removeFileSafely(claudeDirectory, SETTINGS_KIT_NEW)
+}
+
+/**
+ * The manifest is written last: a run that dies halfway leaves files whose content equals the
+ * kit version, which the next run adopts as unchanged instead of mistaking them for local edits.
+ */
+const applyPlan = async (
+  { claudeDirectory, toolDirectory, locate }: Pick<PlanInput, 'claudeDirectory' | 'toolDirectory' | 'locate'>,
+  plan: SyncPlan,
+): Promise<void> => {
+  for (const { path, effect } of effectsInOrder(plan.files)) await applyFileEffect(locate, path, effect)
+  await applyHooks(claudeDirectory, plan.hooks)
+  const manifestText = serializeManifest(plan.manifest)
+  if (manifestText !== plan.manifestText)
+    await writeFileSafely(toolDirectory, MANIFEST_FILE, manifestText, FILE_MODE.regular)
+}
+
+const syncResultOf = (plan: SyncPlan): SyncResult => ({
+  files: plan.files.map(({ path, outcome }) => ({ path, outcome })),
+  hooks: plan.hooks.outcomes,
+})
+
+/**
+ * Brings the project's `.claude/` in line with the kit and records it in `.jackherd/lock.json`. Everything is read, validated and planned
+ * before the first write, so a refusal (invalid config, manifest or settings, a bad path, an
+ * `--accept` with nothing to accept) throws and leaves the project exactly as it was.
+ */
+export const syncProjectWithConfig = async (request: SyncRequest): Promise<ConfiguredSync> => {
+  await assertNotHomeDirectory(request.projectRoot, request.home ?? homedir())
+  await assertOwnDirectoriesInProject(request.projectRoot)
+  const claudeDirectory = join(request.projectRoot, CLAUDE_DIRECTORY)
+  const toolDirectory = join(request.projectRoot, TOOL_DIRECTORY)
+  const moved = await moveProjectLegacyFiles(request.projectRoot)
+  const facts = request.facts ?? readRepositoryFacts(request.projectRoot)
+  const { config, notes } = await readConfig(toolDirectory, TOOL_DIRECTORY, `${CLI_NAME} init`, facts)
+  const directories = { claudeDirectory, toolDirectory, locate: inClaudeDirectory(claudeDirectory) }
+  const plan = await buildPlan({
+    ...directories,
+    kit: toProjectKit(request.kit, config.skillPrefix),
+    config,
+    accept: request.accept,
+    readHooks: projectHooks(claudeDirectory, request.kit, config),
+  })
+  await applyPlan(directories, plan)
+  await ensureGitignoreLines(request.projectRoot)
+  return { result: { ...syncResultOf(plan), notes: [...moved, ...notes] }, config }
+}
+
+export const runSync = async (request: SyncRequest): Promise<SyncResult> =>
+  (await syncProjectWithConfig(request)).result
+
+/**
+ * Installs the kit into the user's `~/.claude/` with every skill and agent renamed by `skillPrefix`
+ * (see `toGlobalKit`). Same plan-then-write and manifest rules as a project sync, against
+ * `~/.jackherd/config.json` and `~/.jackherd/lock.json`; no hooks, no `settings.json`, no
+ * `.gitignore`. Files the kit never wrote stay untouched; one at a kit path becomes a conflict.
+ */
+export const syncGlobalWithConfig = async (request: GlobalSyncRequest): Promise<ConfiguredSync> => {
+  await assertOwnDirectoriesInProject(request.home)
+  const claudeDirectory = join(request.home, CLAUDE_DIRECTORY)
+  const toolDirectory = join(request.home, TOOL_DIRECTORY)
+  const moved = await moveGlobalLegacyFiles(request.home, request.configHome)
+  const { config } = await readConfig(toolDirectory, GLOBAL_TOOL_LOCATION, `${CLI_NAME} init --global`)
+  if (config.skillPrefix === '') {
+    throw new Error(
+      `${GLOBAL_TOOL_LOCATION}/${CONFIG_FILE} has no skillPrefix; a global install needs one (e.g. "kit-") so it cannot shadow project skills`,
+    )
+  }
+  const directories = { claudeDirectory, toolDirectory, locate: inGlobalDirectories(claudeDirectory, toolDirectory) }
+  const plan = await buildPlan({
+    ...directories,
+    kit: toGlobalKit(request.kit, config.skillPrefix),
+    config,
+    accept: request.accept,
+    readHooks: noHooks,
+    overrides: REPOSITORY_TOKENS,
+  })
+  await applyPlan(directories, plan)
+  await removeEmptyLegacyDirectories(claudeDirectory)
+  return { result: { ...syncResultOf(plan), notes: moved }, config }
+}
+
+export const runGlobalSync = async (request: GlobalSyncRequest): Promise<SyncResult> =>
+  (await syncGlobalWithConfig(request)).result

package/src/sync/tools.ts

@@ -0,0 +1,52 @@
+import { spawnSync } from 'node:child_process'
+
+/** What a run of an external program answered; `missing` is true when there is no such program to run at all. */
+export type ToolRun = { exitCode: number; output: string; missing: boolean }
+
+/** Runs one external program with arguments, never through a shell. */
+export type RunTool = (binary: string, args: string[]) => ToolRun
+
+/**
+ * The external programs the kit works with, as far as they are installed; `herdrInstallable` is true where the
+ * official herdr installer applies (Linux and macOS).
+ */
+export type ToolPresence = { herdr: boolean; gh: boolean; herdrInstallable: boolean }
+
+type Environment = Record<string, string | undefined>
+
+/**
+ * The installers the kit may run after a yes: each tool's official script, HTTPS-only on every redirect. The script
+ * is downloaded whole into a temporary file before `sh` runs it, so a download cut off midway runs nothing and a
+ * failed download ends with curl's exit code. Wrapped in `sh -c`, the command is also safe to paste into any
+ * interactive shell: its `exit` ends only the inner shell. herdr's applies to Linux and macOS.
+ */
+export const INSTALLERS = {
+  herdr:
+    'sh -c \'installer=$(mktemp) && curl --proto =https --tlsv1.2 -fsSL https://herdr.dev/install.sh -o "$installer" && sh "$installer"; code=$?; rm -f "$installer"; exit $code\'',
+} as const
+
+export type InstallerName = keyof typeof INSTALLERS
+
+/** The binary herdr names in `HERDR_BIN_PATH`, else `herdr` from the PATH. */
+export const herdrBinary = (env: Environment): string => env.HERDR_BIN_PATH || 'herdr'
+
+const INSTALLABLE_PLATFORMS: readonly NodeJS.Platform[] = ['linux', 'darwin']
+
+const isPresent = (run: RunTool, binary: string): boolean => !run(binary, ['--version']).missing
+
+/** Which tools are installed, asked by running them; a program that runs at all counts, whatever it answers. */
+export const detectTools = (env: Environment, platform: NodeJS.Platform, run: RunTool): ToolPresence => ({
+  herdr: isPresent(run, herdrBinary(env)),
+  gh: isPresent(run, 'gh'),
+  herdrInstallable: INSTALLABLE_PLATFORMS.includes(platform),
+})
+
+/** `env` is passed on because Bun looks the binary up in it. */
+export const spawnTool =
+  (env: Environment): RunTool =>
+  (binary, args) => {
+    const result = spawnSync(binary, args, { encoding: 'utf-8', env })
+    const output = `${result.error?.message ?? ''} ${result.stdout ?? ''}${result.stderr ?? ''}`.trim()
+    const missing = (result.error as NodeJS.ErrnoException | undefined)?.code === 'ENOENT'
+    return { exitCode: result.status ?? 1, output, missing }
+  }

package/src/terminal/herdr.ts

@@ -0,0 +1,91 @@
+import { herdrBinary } from '../sync/tools'
+import type { AdoptedName, LaneAgent, LaneStatusSource } from './types'
+
+type HerdrAgent = { name?: string; pane_id: string; agent_status: string; agent_session?: unknown; cwd?: unknown }
+
+const METADATA_SOURCE = 'pf-plans'
+
+const isHerdrAgent = (value: unknown): value is HerdrAgent => {
+  if (typeof value !== 'object' || value === null) return false
+  const candidate = value as Record<string, unknown>
+  return (
+    typeof candidate.pane_id === 'string' &&
+    typeof candidate.agent_status === 'string' &&
+    (candidate.name === undefined || typeof candidate.name === 'string')
+  )
+}
+
+const sessionOf = ({ agent_session }: HerdrAgent): string | null => {
+  if (typeof agent_session !== 'object' || agent_session === null) return null
+  const { value } = agent_session as Record<string, unknown>
+  return typeof value === 'string' && value !== '' ? value : null
+}
+
+const laneAgentOf = (agent: HerdrAgent, name: string): LaneAgent => ({
+  name,
+  pane: agent.pane_id,
+  status: agent.agent_status,
+  session: sessionOf(agent),
+  cwd: typeof agent.cwd === 'string' ? agent.cwd : null,
+})
+
+/**
+ * Reads the JSON of `herdr agent list`; throws on anything else, so a changed format is seen, not guessed.
+ * Agents without a name are left out, except the one in `adopt.pane`, which takes `adopt.name`.
+ */
+export const parseAgentList = (json: string, adopt?: AdoptedName): LaneAgent[] => {
+  const agents = (JSON.parse(json) as { result?: { agents?: unknown } }).result?.agents
+  if (!Array.isArray(agents) || !agents.every(isHerdrAgent)) throw new Error('herdr agent list: unexpected answer')
+  return agents.flatMap((agent) => {
+    const name = agent.name || (agent.pane_id === adopt?.pane ? adopt.name : '')
+    return name ? [laneAgentOf(agent, name)] : []
+  })
+}
+
+/**
+ * Sets or, with null, clears the sidebar title of a pane. The pane id goes before the options:
+ * herdr 0.9.0 rejects it after them, despite `--help`.
+ */
+export const titleArguments = (pane: string, title: string | null): string[] => [
+  'pane',
+  'report-metadata',
+  pane,
+  '--source',
+  METADATA_SOURCE,
+  ...(title ? ['--title', title] : ['--clear-title']),
+]
+
+/** Runs the herdr CLI with these arguments and returns its stdout; throws when it fails. */
+export type HerdrRunner = (args: string[]) => string
+
+/**
+ * Runs the herdr binary of `herdrBinary` (`HERDR_BIN_PATH`, else `herdr` from the PATH) and returns its stdout;
+ * throws with herdr's own error text when it fails or is not running.
+ */
+export const herdrRunner =
+  (env: Record<string, string | undefined>): HerdrRunner =>
+  (args) => {
+    const result = Bun.spawnSync([herdrBinary(env), ...args], { stdout: 'pipe', stderr: 'pipe', env })
+    if (result.exitCode !== 0) {
+      throw new Error(
+        `herdr ${args.slice(0, 2).join(' ')}: ${result.stderr.toString().trim() || `exit ${result.exitCode}`}`,
+      )
+    }
+    return result.stdout.toString()
+  }
+
+export const runHerdr: HerdrRunner = herdrRunner(process.env)
+
+export const createHerdrLaneStatusSource = (run: HerdrRunner): LaneStatusSource => ({
+  listAgents: (adopt) => parseAgentList(run(['agent', 'list']), adopt),
+  setTitle: (pane, title) => {
+    try {
+      run(titleArguments(pane, title))
+      return null
+    } catch (error) {
+      return `${pane}: ${error instanceof Error ? error.message : String(error)}`
+    }
+  },
+})
+
+export const herdrLaneStatusSource = createHerdrLaneStatusSource(runHerdr)

package/src/terminal/index.ts

@@ -0,0 +1,13 @@
+import { TERMINAL_ADAPTER, type TerminalAdapter } from '../config'
+import { herdrLaneStatusSource } from './herdr'
+import { noneLaneStatusSource } from './none'
+import type { LaneStatusSource } from './types'
+
+export type { AdoptedName, LaneAgent, LaneStatusSource } from './types'
+
+const SOURCES: Record<TerminalAdapter, LaneStatusSource> = {
+  [TERMINAL_ADAPTER.none]: noneLaneStatusSource,
+  [TERMINAL_ADAPTER.herdr]: herdrLaneStatusSource,
+}
+
+export const laneStatusSourceFor = (adapter: TerminalAdapter): LaneStatusSource => SOURCES[adapter]

package/src/terminal/none.ts

@@ -0,0 +1,7 @@
+import type { LaneStatusSource } from './types'
+
+/** No terminal adapter: no agents are known, nothing is titled, and nothing is reported as an error. */
+export const noneLaneStatusSource: LaneStatusSource = {
+  listAgents: () => [],
+  setTitle: () => null,
+}

package/src/terminal/open.ts

@@ -0,0 +1,39 @@
+/** What opening something in the default application needs from the machine; tests pass their own. */
+export type OpenEnvironment = {
+  platform: NodeJS.Platform
+  env: Record<string, string | undefined>
+  start: (command: string, args: string[]) => void
+}
+
+const OPENERS: Partial<Record<NodeJS.Platform, string>> = { darwin: 'open', linux: 'xdg-open' }
+
+/** The command that opens a file or a link in the default application of the platform, null when there is none. */
+export const openerFor = (platform: NodeJS.Platform): string | null => OPENERS[platform] ?? null
+
+/** Linux opens things in a graphical session only; elsewhere the platform's opener is assumed to work. */
+export const hasDisplay = ({ platform, env }: Pick<OpenEnvironment, 'platform' | 'env'>): boolean =>
+  platform !== 'linux' || Boolean(env.DISPLAY || env.WAYLAND_DISPLAY)
+
+const systemEnvironment = (): OpenEnvironment => ({
+  platform: process.platform,
+  env: process.env,
+  start: (command, args) => {
+    Bun.spawn([command, ...args], { stdout: 'ignore', stderr: 'ignore' })
+  },
+})
+
+/**
+ * Opens a file or a link in the default application. Returns the reason when that was not possible (no
+ * opener for the platform, no display, the opener could not be started), null when it was started.
+ */
+export const openInBrowser = (target: string, environment: OpenEnvironment = systemEnvironment()): string | null => {
+  const opener = openerFor(environment.platform)
+  if (!opener) return `no way to open ${target} on ${environment.platform}`
+  if (!hasDisplay(environment)) return 'no display'
+  try {
+    environment.start(opener, [target])
+    return null
+  } catch (error) {
+    return `${opener} ${target}: ${error instanceof Error ? error.message : String(error)}`
+  }
+}