@amsterdamdatalabs/adl-agent-control-darwin-arm64 0.1.4

package/packages/fleet/src/launch-agents.ts

@@ -0,0 +1,649 @@
+/**
+ * User LaunchAgents owned by adl.
+ *
+ * `packages/fleet/manifest.json` declares them under `mac.common.launch_agents`
+ * (and optionally `mac.devices.<device>.launch_agents`; validate-manifest
+ * rejects them on linux). For each declared job, reconcile (as root, apply):
+ *
+ *   1. compiles the job's TypeScript entry (`source`/`entry`) with
+ *      `bun build --compile` into the dedicated binary
+ *      `/usr/local/libexec/adl/<job id>` (root-owned, 0755 --
+ *      never user-writable, since launchd runs it on a schedule), ad-hoc
+ *      signed with the stable identifier `<label>` and the explicit designated
+ *      requirement `identifier "<label>"`. It rebuilds only when a content
+ *      hash of the source directory changes (or the binary is missing).
+ *
+ *      Why a dedicated binary: under launchd the program in ProgramArguments
+ *      is the responsible process for macOS privacy protection (TCC), and the
+ *      `git` children it spawns are attributed to it. A job run by /bin/bash
+ *      would need Full Disk Access granted to every bash script; a dedicated
+ *      binary lets the owner grant exactly that one path. TCC matches a grant
+ *      against the code's designated requirement; plain ad-hoc signing pins it
+ *      to the cdhash (TN3127), so every rebuild would silently void the grant.
+ *      The explicit identifier requirement keeps rebuilds satisfying it; the
+ *      grant itself is still keyed to this root-owned path;
+ *   2. renders `~/Library/LaunchAgents/<label>.plist` for the device's
+ *      administrator, expanding a leading `$HOME` in environment values and the
+ *      home-relative `log` path (launchd itself expands nothing);
+ *   3. replaces any differing declared plist from source and removes every
+ *      retired `replaces` path outright;
+ *   4. (re)loads the job in `gui/<uid>` when anything changed or it is not
+ *      loaded. Without a GUI session for that user the job is left installed
+ *      and launchd loads it at the next login (RunAtLoad applies then).
+ *
+ * A job present in the previously applied manifest but absent now is booted
+ * out, its plist and binary and source hash removed. The libexec dir itself
+ * is shared with other managers (e.g. `repo-dir` targets such as
+ * `agent-skills`/`repo-controls`/`agent-hooks`), so it is never swept
+ * wholesale: only an entry whose id this component currently declares, or
+ * once built and recorded a `<id>.source-hash` marker for under `stateDir`,
+ * is eligible for stale removal. Anything else in the dir -- another
+ * manager's target, a hand-placed file -- is left untouched.
+ *
+ * When a job's last log line is a TCC denial (git-maintain's
+ * `TCC_DENIED_MARKER`), plan and apply surface it verbatim, remedy included.
+ *
+ * `global-surface-sweep` derives LaunchAgent protection from the same
+ * declarations (`declaredLaunchAgentPlists`), so a shipped job is never a
+ * sweep candidate.
+ */
+
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import {
+  chmodSync,
+  chownSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path'
+import { TCC_DENIED_MARKER } from '../jobs/git-maintain/src/main.ts'
+
+export const DEFAULT_LIBEXEC_DIR = '/usr/local/libexec/adl'
+const LAUNCH_AGENTS_DIR = 'Library/LaunchAgents'
+
+export interface RepositoryScope {
+  readonly root: string
+  readonly glob: string
+  readonly recursive: true
+}
+
+export interface LaunchAgentSpec {
+  readonly label: string
+  /** Checkout-relative job directory; its content hash decides rebuilds. */
+  readonly source: string
+  /** Entry file relative to `source`. */
+  readonly entry: string
+  readonly start_interval_seconds: number
+  readonly run_at_load: boolean
+  readonly repo_scope?: RepositoryScope
+  readonly environment: Readonly<Record<string, string>>
+  readonly log: string
+  readonly replaces: readonly string[]
+}
+
+export type Platform = 'mac' | 'linux'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function decodeRepoScope(id: string, raw: unknown): RepositoryScope {
+  if (
+    !isRecord(raw) ||
+    typeof raw.root !== 'string' ||
+    raw.root.length === 0 ||
+    typeof raw.glob !== 'string' ||
+    raw.glob.length === 0 ||
+    raw.recursive !== true
+  ) {
+    throw new Error(`invalid launch agent repo_scope: ${id} (need root: string, glob: string, recursive: true)`)
+  }
+  return { root: raw.root, glob: raw.glob, recursive: true }
+}
+
+function decodeSpec(id: string, raw: unknown): LaunchAgentSpec {
+  if (
+    !isRecord(raw) ||
+    typeof raw.label !== 'string' ||
+    typeof raw.source !== 'string' ||
+    typeof raw.entry !== 'string' ||
+    raw.script !== undefined ||
+    typeof raw.start_interval_seconds !== 'number' ||
+    typeof raw.run_at_load !== 'boolean' ||
+    !isRecord(raw.environment) ||
+    typeof raw.log !== 'string' ||
+    (raw.replaces !== undefined && !Array.isArray(raw.replaces))
+  ) {
+    throw new Error(`invalid launch agent declaration: ${id}`)
+  }
+  const environment: Record<string, string> = {}
+  for (const [key, value] of Object.entries(raw.environment)) {
+    if (typeof value !== 'string') throw new Error(`invalid launch agent environment value: ${id}.${key}`)
+    environment[key] = value
+  }
+  const replaces = ((raw.replaces ?? []) as unknown[]).map((entry) => {
+    if (typeof entry !== 'string') throw new Error(`invalid launch agent replaces entry: ${id}`)
+    return entry
+  })
+  const repo_scope = raw.repo_scope === undefined ? undefined : decodeRepoScope(id, raw.repo_scope)
+  return {
+    label: raw.label,
+    source: raw.source,
+    entry: raw.entry,
+    start_interval_seconds: raw.start_interval_seconds,
+    run_at_load: raw.run_at_load,
+    ...(repo_scope === undefined ? {} : { repo_scope }),
+    environment,
+    log: raw.log,
+    replaces,
+  }
+}
+
+function agentsAt(value: unknown, id: string): Record<string, LaunchAgentSpec> {
+  if (value === undefined) return {}
+  if (!isRecord(value)) throw new Error(`launch_agents must be an object: ${id}`)
+  const result: Record<string, LaunchAgentSpec> = {}
+  for (const [key, raw] of Object.entries(value)) result[key] = decodeSpec(key, raw)
+  return result
+}
+
+/** `<platform>.common.launch_agents` merged with `<platform>.devices.<device>.launch_agents` (device wins). */
+export function resolveLaunchAgents(manifest: unknown, platform: Platform, device: string): Record<string, LaunchAgentSpec> {
+  if (!isRecord(manifest)) throw new Error('manifest must be an object')
+  const section = manifest[platform]
+  if (!isRecord(section) || !isRecord(section.common) || !isRecord(section.devices)) {
+    throw new Error(`manifest has no ${platform} section`)
+  }
+  const deviceEntry = section.devices[device]
+  if (!isRecord(deviceEntry)) throw new Error(`device ${device} is not declared under ${platform}`)
+  return {
+    ...agentsAt(section.common.launch_agents, `${platform}.common`),
+    ...agentsAt(deviceEntry.launch_agents, `${platform}.devices.${device}`),
+  }
+}
+
+/**
+ * Every LaunchAgent plist (home-relative) any mac device in the manifest
+ * declares, with its declaration path. Protection needs only each label, so a
+ * job's build fields never gate it; an entry without a valid label fails loud.
+ */
+export function declaredLaunchAgentPlists(manifest: unknown): readonly { readonly path: string; readonly declaredAt: string }[] {
+  if (!isRecord(manifest) || !isRecord(manifest.mac)) return []
+  const mac = manifest.mac
+  const found = new Map<string, string>()
+  const collect = (value: unknown, where: string): void => {
+    if (value === undefined) return
+    if (!isRecord(value)) throw new Error(`launch_agents must be an object: ${where}`)
+    for (const [id, raw] of Object.entries(value)) {
+      if (!isRecord(raw) || typeof raw.label !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(raw.label)) {
+        throw new Error(`invalid launch agent label: mac.${where}.launch_agents.${id}`)
+      }
+      const path = `${LAUNCH_AGENTS_DIR}/${raw.label}.plist`
+      if (!found.has(path)) found.set(path, `mac.${where}.launch_agents.${id}`)
+    }
+  }
+  if (isRecord(mac.common)) collect(mac.common.launch_agents, 'common')
+  if (isRecord(mac.devices)) {
+    for (const [device, entry] of Object.entries(mac.devices)) {
+      if (isRecord(entry)) collect(entry.launch_agents, `devices.${device}`)
+    }
+  }
+  return [...found.entries()].map(([path, declaredAt]) => ({ path, declaredAt })).sort((a, b) => a.path.localeCompare(b.path))
+}
+
+function xml(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('<', '&lt;').replaceAll('>', '&gt;').replaceAll('"', '&quot;')
+}
+
+function expandHome(value: string, home: string): string {
+  if (value === '$HOME') return home
+  if (value.startsWith('$HOME/')) return `${home}${value.slice('$HOME'.length)}`
+  return value
+}
+
+/** `<platform>` launch agent labels by job id, tolerating older declaration shapes (removal needs only the label). */
+function resolveLabels(manifest: unknown, platform: Platform, device: string): Record<string, string> {
+  const labels: Record<string, string> = {}
+  if (!isRecord(manifest) || !isRecord(manifest[platform])) return labels
+  const section = manifest[platform] as Record<string, unknown>
+  const collect = (value: unknown): void => {
+    if (!isRecord(value)) return
+    for (const [id, raw] of Object.entries(value)) {
+      if (isRecord(raw) && typeof raw.label === 'string') labels[id] = raw.label
+    }
+  }
+  if (isRecord(section.common)) collect(section.common.launch_agents)
+  if (isRecord(section.devices) && isRecord(section.devices[device])) collect(section.devices[device].launch_agents)
+  return labels
+}
+
+export function installedProgramPath(id: string, libexecDir: string): string {
+  return join(libexecDir, id)
+}
+
+function sourceHashPath(stateDir: string, id: string): string {
+  return join(stateDir, 'launch-agents', `${id}.source-hash`)
+}
+
+const SOURCE_HASH_SUFFIX = '.source-hash'
+
+/**
+ * ids this component may treat as its own in `libexecDir`: every currently
+ * declared job, plus any id it previously built and still holds a
+ * `<id>.source-hash` marker for in `stateDir`. An id with neither is not
+ * ours to remove, however stale-looking it is -- it belongs to whatever
+ * other manager (or hand-placed file) put it there.
+ */
+function ownedProgramIds(stateDir: string, currentIds: ReadonlySet<string>): Set<string> {
+  const owned = new Set(currentIds)
+  let markers: string[]
+  try {
+    markers = readdirSync(join(stateDir, 'launch-agents'))
+  } catch {
+    markers = []
+  }
+  for (const name of markers) {
+    if (name.endsWith(SOURCE_HASH_SUFFIX)) owned.add(name.slice(0, -SOURCE_HASH_SUFFIX.length))
+  }
+  return owned
+}
+
+function listFiles(dir: string): string[] {
+  const out: string[] = []
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === 'node_modules' || entry.name.endsWith('.bun-build')) continue
+    const path = join(dir, entry.name)
+    if (entry.isDirectory()) out.push(...listFiles(path))
+    else if (entry.isFile()) out.push(path)
+  }
+  return out
+}
+
+/** sha256 over every file (relative path + content) in the job's source directory. */
+export function sourceHash(sourceDir: string): string {
+  const hash = createHash('sha256')
+  for (const file of listFiles(sourceDir).sort()) {
+    hash.update(`${relative(sourceDir, file)}\0`)
+    hash.update(readFileSync(file))
+    hash.update('\0')
+  }
+  return hash.digest('hex')
+}
+
+export interface ProgramBuilder {
+  /** Compile `entryPath` to `outputPath` (a fresh file) signed with `identifier`; throw on failure. */
+  build(entryPath: string, outputPath: string, identifier: string): void
+}
+
+/**
+ * `bun build --compile` through the shared bun-compile-build.sh (throwaway
+ * CWD, so no `*.bun-build` leaks), then an ad-hoc re-sign with the stable
+ * identifier as an explicit designated requirement.
+ */
+export function systemProgramBuilder(bunBin: string, buildLibPath: string): ProgramBuilder {
+  return {
+    build: (entryPath, outputPath, identifier) => {
+      if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(identifier)) throw new Error(`unsafe signing identifier: ${identifier}`)
+      const compiled = spawnSync(
+        '/bin/bash',
+        ['-c', 'set -euo pipefail; source "$1"; bun_compile_build "$2" "$3" "$4"', 'bun-compile', buildLibPath, bunBin, entryPath, outputPath],
+        { encoding: 'utf8' },
+      )
+      if (compiled.status !== 0) {
+        throw new Error(`bun build --compile ${entryPath} failed: ${`${compiled.stdout}${compiled.stderr}`.trim()}`)
+      }
+      const signed = spawnSync(
+        'codesign',
+        ['--force', '--sign', '-', '--identifier', identifier, `-r=designated => identifier "${identifier}"`, outputPath],
+        { encoding: 'utf8' },
+      )
+      if (signed.status !== 0) throw new Error(`codesign ${outputPath} failed: ${`${signed.stdout}${signed.stderr}`.trim()}`)
+    },
+  }
+}
+
+/** The job's last log line when it is a TCC denial, so reconcile output carries the remedy. */
+function lastRunDenial(spec: LaunchAgentSpec, home: string): string | null {
+  const content = readIfFile(join(home, spec.log))
+  if (content === null) return null
+  const last = content.split('\n').filter((line) => line.length > 0).at(-1)
+  return last !== undefined && last.includes(TCC_DENIED_MARKER) ? `launch-agent: ${spec.label} last run: ${last}` : null
+}
+
+export function renderLaunchAgentPlist(
+  spec: LaunchAgentSpec,
+  options: { readonly home: string; readonly programPath: string },
+): string {
+  const logPath = join(options.home, spec.log)
+  const environment = Object.keys(spec.environment)
+    .sort()
+    .flatMap((key) => [
+      `    <key>${xml(key)}</key>`,
+      `    <string>${xml(expandHome(spec.environment[key]!, options.home))}</string>`,
+    ])
+  return [
+    '<?xml version="1.0" encoding="UTF-8"?>',
+    '<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">',
+    '<!-- Generated by adl global-tools (manifest launch_agents) -- do not edit; reconcile overwrites it. -->',
+    '<plist version="1.0">',
+    '<dict>',
+    '  <key>Label</key>',
+    `  <string>${xml(spec.label)}</string>`,
+    '  <key>ProgramArguments</key>',
+    '  <array>',
+    `    <string>${xml(options.programPath)}</string>`,
+    '  </array>',
+    '  <key>EnvironmentVariables</key>',
+    '  <dict>',
+    ...environment,
+    '  </dict>',
+    '  <key>RunAtLoad</key>',
+    spec.run_at_load ? '  <true/>' : '  <false/>',
+    '  <key>StartInterval</key>',
+    `  <integer>${spec.start_interval_seconds}</integer>`,
+    '  <key>StandardOutPath</key>',
+    `  <string>${xml(logPath)}</string>`,
+    '  <key>StandardErrorPath</key>',
+    `  <string>${xml(logPath)}</string>`,
+    '  <key>ProcessType</key>',
+    '  <string>Background</string>',
+    '  <key>LowPriorityIO</key>',
+    '  <true/>',
+    '  <key>Nice</key>',
+    '  <integer>10</integer>',
+    '</dict>',
+    '</plist>',
+    '',
+  ].join('\n')
+}
+
+export interface Launchctl {
+  hasGuiDomain(uid: number): boolean
+  isLoaded(uid: number, label: string): boolean
+  /** Unload; a job that is not loaded is the harmless common case. */
+  bootout(uid: number, label: string): void
+  bootstrap(uid: number, plistPath: string): { readonly ok: boolean; readonly detail: string }
+}
+
+export const systemLaunchctl: Launchctl = {
+  hasGuiDomain: (uid) => spawnSync('launchctl', ['print', `gui/${uid}`], { encoding: 'utf8' }).status === 0,
+  isLoaded: (uid, label) => spawnSync('launchctl', ['print', `gui/${uid}/${label}`], { encoding: 'utf8' }).status === 0,
+  bootout: (uid, label) => {
+    spawnSync('launchctl', ['bootout', `gui/${uid}/${label}`], { encoding: 'utf8' })
+  },
+  bootstrap: (uid, plistPath) => {
+    const result = spawnSync('launchctl', ['bootstrap', `gui/${uid}`, plistPath], { encoding: 'utf8' })
+    return { ok: result.status === 0, detail: `${result.stdout}${result.stderr}`.trim() }
+  },
+}
+
+export interface ApplyOptions {
+  readonly manifest: unknown
+  readonly previousManifest: unknown | null
+  readonly platform: Platform
+  readonly device: string
+  readonly home: string
+  readonly repoRoot: string
+  readonly libexecDir: string
+  readonly stateDir: string
+  readonly launchctl: Launchctl
+  readonly builder: ProgramBuilder
+}
+
+export interface ApplyResult {
+  readonly lines: readonly string[]
+}
+
+function readIfFile(path: string): string | null {
+  try {
+    if (!lstatSync(path).isFile()) return null
+  } catch {
+    return null
+  }
+  return readFileSync(path, 'utf8')
+}
+
+function atomicWrite(path: string, content: string, mode: number, owner: { uid: number; gid: number } | null): void {
+  mkdirSync(dirname(path), { recursive: true })
+  const temporary = `${path}.adl-new`
+  writeFileSync(temporary, content, { mode })
+  chmodSync(temporary, mode)
+  if (owner !== null) chownSync(temporary, owner.uid, owner.gid)
+  renameSync(temporary, path)
+}
+
+function ensureOwnedDir(path: string, owner: { uid: number; gid: number } | null): void {
+  mkdirSync(path, { recursive: true })
+  if (owner !== null) chownSync(path, owner.uid, owner.gid)
+}
+
+function needsBuild(id: string, spec: LaunchAgentSpec, options: { repoRoot: string; libexecDir: string; stateDir: string }): string | null {
+  const hash = sourceHash(join(options.repoRoot, spec.source))
+  const programPath = installedProgramPath(id, options.libexecDir)
+  const recorded = readIfFile(sourceHashPath(options.stateDir, id))?.trim()
+  return recorded === hash && existsSync(programPath) ? null : hash
+}
+
+export function planLaunchAgents(options: Omit<ApplyOptions, 'launchctl' | 'builder'>): readonly string[] {
+  const lines: string[] = []
+  const agents = resolveLaunchAgents(options.manifest, options.platform, options.device)
+  for (const [id, spec] of Object.entries(agents)) {
+    const plistPath = join(options.home, LAUNCH_AGENTS_DIR, `${spec.label}.plist`)
+    const programPath = installedProgramPath(id, options.libexecDir)
+    lines.push(`would install launch agent: ${spec.label} -> ${plistPath} (program ${programPath})`)
+    if (readIfFile(join(options.repoRoot, spec.source, spec.entry)) === null) {
+      lines.push(`launch agent job entry missing from checkout: ${join(spec.source, spec.entry)}`)
+    } else {
+      const hash = needsBuild(id, spec, options)
+      if (hash !== null) lines.push(`would build ${programPath} (source ${hash})`)
+    }
+    for (const legacy of spec.replaces) {
+      if (existsSync(join(options.home, legacy))) lines.push(`would remove retired ${join(options.home, legacy)}`)
+    }
+    const denial = lastRunDenial(spec, options.home)
+    if (denial !== null) lines.push(denial)
+  }
+  if (options.previousManifest !== null) {
+    const current = new Set(Object.values(agents).map((spec) => spec.label))
+    for (const label of Object.values(resolveLabels(options.previousManifest, options.platform, options.device))) {
+      if (!current.has(label)) lines.push(`would remove launch agent: ${label}`)
+    }
+  }
+  return lines
+}
+
+export function applyLaunchAgents(options: ApplyOptions): ApplyResult {
+  for (const [label, value] of [
+    ['home', options.home],
+    ['repo root', options.repoRoot],
+    ['libexec dir', options.libexecDir],
+    ['state dir', options.stateDir],
+  ] as const) {
+    if (!isAbsolute(value)) throw new Error(`${label} must be absolute: ${value}`)
+  }
+  const home = resolve(options.home)
+  const agents = resolveLaunchAgents(options.manifest, options.platform, options.device)
+  const previous =
+    options.previousManifest === null ? {} : resolveLabels(options.previousManifest, options.platform, options.device)
+
+  // Fail before the first mutation if any declared job entry is missing.
+  for (const spec of Object.values(agents)) {
+    if (readIfFile(join(options.repoRoot, spec.source, spec.entry)) === null) {
+      throw new Error(`launch agent job entry missing from checkout: ${join(spec.source, spec.entry)}`)
+    }
+  }
+
+  const homeStat = statSync(home)
+  const uid = homeStat.uid
+  const owner = typeof process.getuid === 'function' && process.getuid() === 0 ? { uid, gid: homeStat.gid } : null
+  const lines: string[] = []
+
+  const currentLabels = new Set(Object.values(agents).map((spec) => spec.label))
+  for (const [id, label] of Object.entries(previous)) {
+    if (currentLabels.has(label)) continue
+    const relativePlist = `${LAUNCH_AGENTS_DIR}/${label}.plist`
+    options.launchctl.bootout(uid, label)
+    if (options.launchctl.isLoaded(uid, label)) {
+      throw new Error(`launch agent ${label} is still loaded after bootout; refusing to remove it`)
+    }
+    rmSync(join(home, relativePlist), { force: true })
+    if (!(id in agents)) {
+      rmSync(installedProgramPath(id, options.libexecDir), { force: true })
+      rmSync(sourceHashPath(options.stateDir, id), { force: true })
+    }
+    lines.push(`launch-agent: removed ${label} (deleted from manifest)`)
+  }
+
+  // Only remove entries this component owns: currently declared ids, or ids
+  // it previously built (a `.source-hash` marker under stateDir). The dir is
+  // shared with other managers (e.g. repo-dir targets), so an entry with
+  // neither is left alone even if it looks stale.
+  if (existsSync(options.libexecDir)) {
+    const expected = new Set(Object.keys(agents))
+    const owned = ownedProgramIds(options.stateDir, expected)
+    for (const name of readdirSync(options.libexecDir)) {
+      if (expected.has(name) || !owned.has(name)) continue
+      rmSync(join(options.libexecDir, name), { recursive: true, force: true })
+      lines.push(`launch-agent: removed stale ${join(options.libexecDir, name)}`)
+    }
+  }
+
+  for (const [id, spec] of Object.entries(agents)) {
+    const relativePlist = `${LAUNCH_AGENTS_DIR}/${spec.label}.plist`
+    const plistPath = join(home, relativePlist)
+    const programPath = installedProgramPath(id, options.libexecDir)
+    const plistContent = renderLaunchAgentPlist(spec, { home, programPath })
+
+    let changed = false
+    const hash = needsBuild(id, spec, options)
+    if (hash !== null) {
+      // Build to a staged path so a failed build never clobbers a working binary.
+      const staged = `${programPath}.staged`
+      mkdirSync(options.libexecDir, { recursive: true, mode: 0o755 })
+      rmSync(staged, { force: true })
+      try {
+        options.builder.build(join(options.repoRoot, spec.source, spec.entry), staged, spec.label)
+        chmodSync(staged, 0o755)
+      } catch (cause) {
+        rmSync(staged, { force: true })
+        throw cause
+      }
+      renameSync(staged, programPath)
+      atomicWrite(sourceHashPath(options.stateDir, id), `${hash}\n`, 0o644, null)
+      changed = true
+      lines.push(`launch-agent: built ${programPath} (identifier ${spec.label})`)
+    }
+    const existingPlist = readIfFile(plistPath)
+    if (existingPlist !== plistContent) {
+      ensureOwnedDir(join(home, 'Library'), owner)
+      ensureOwnedDir(join(home, LAUNCH_AGENTS_DIR), owner)
+      atomicWrite(plistPath, plistContent, 0o644, owner)
+      changed = true
+      lines.push(`launch-agent: wrote ${plistPath}`)
+    }
+    for (const legacy of spec.replaces) {
+      if (existsSync(join(home, legacy))) {
+        rmSync(join(home, legacy), { recursive: true, force: true })
+        lines.push(`launch-agent: removed retired ${join(home, legacy)}`)
+        changed = true
+      }
+    }
+    const denial = lastRunDenial(spec, home)
+    if (denial !== null) lines.push(denial)
+    let logDir = home
+    for (const part of dirname(spec.log).split('/')) {
+      logDir = join(logDir, part)
+      ensureOwnedDir(logDir, owner)
+    }
+
+    if (!options.launchctl.hasGuiDomain(uid)) {
+      lines.push(`launch-agent: ${spec.label} installed; no GUI session for uid ${uid}, launchd loads it at next login`)
+      continue
+    }
+    if (!changed && options.launchctl.isLoaded(uid, spec.label)) {
+      lines.push(`launch-agent: already up to date: ${spec.label}`)
+      continue
+    }
+    options.launchctl.bootout(uid, spec.label)
+    const loaded = options.launchctl.bootstrap(uid, plistPath)
+    if (!loaded.ok) throw new Error(`launchctl bootstrap gui/${uid} ${plistPath} failed: ${loaded.detail}`)
+    lines.push(`launch-agent: loaded gui/${uid}/${spec.label}`)
+  }
+
+  return { lines }
+}
+
+function usage(): never {
+  throw new Error(
+    'usage: launch-agents.ts --mode plan|apply --manifest FILE [--previous-manifest FILE] --platform mac|linux ' +
+      '--device NAME --home ABSOLUTE_PATH --state-dir ABSOLUTE_PATH [--libexec-dir ABSOLUTE_PATH]',
+  )
+}
+
+export function main(argv: readonly string[]): void {
+  const args = new Map<string, string>()
+  for (let index = 0; index < argv.length; index += 2) {
+    const key = argv[index]
+    const value = argv[index + 1]
+    if (key === undefined || !key.startsWith('--') || value === undefined) usage()
+    args.set(key.slice(2), value)
+  }
+  const mode = args.get('mode')
+  const manifestPath = args.get('manifest')
+  const platform = args.get('platform')
+  const device = args.get('device')
+  const home = args.get('home')
+  const stateDir = args.get('state-dir')
+  if (
+    (mode !== 'plan' && mode !== 'apply') ||
+    manifestPath === undefined ||
+    (platform !== 'mac' && platform !== 'linux') ||
+    device === undefined ||
+    home === undefined ||
+    stateDir === undefined
+  ) {
+    usage()
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'))
+  const previousPath = args.get('previous-manifest')
+  const previousManifest = previousPath === undefined ? null : JSON.parse(readFileSync(previousPath, 'utf8'))
+  const libexecDir = args.get('libexec-dir') ?? DEFAULT_LIBEXEC_DIR
+  const repoRoot = resolve(import.meta.dir, '..', '..', '..')
+
+  if (mode === 'plan') {
+    for (const line of planLaunchAgents({ manifest, previousManifest, platform, device, home, repoRoot, libexecDir, stateDir })) {
+      console.log(line)
+    }
+    return
+  }
+  const result = applyLaunchAgents({
+    manifest,
+    previousManifest,
+    platform,
+    device,
+    home,
+    repoRoot,
+    libexecDir,
+    stateDir,
+    launchctl: systemLaunchctl,
+    builder: systemProgramBuilder(process.execPath, join(repoRoot, 'bin/lib/bun-compile-build.sh')),
+  })
+  for (const line of result.lines) console.log(line)
+}
+
+if (import.meta.main) {
+  try {
+    main(process.argv.slice(2))
+  } catch (cause) {
+    console.error(`launch-agents: ${cause instanceof Error ? cause.message : String(cause)}`)
+    process.exitCode = 1
+  }
+}