@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.46 → 0.1.47

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

@@ -1,649 +0,0 @@
-/**
- * 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
-  }
-}

package/packages/repo-controls/assets/GLOBAL-INVARIANTS.md

@@ -1,21 +0,0 @@
-# Invariants
-
-The things this repository must never regress. These apply to every repository
-adl manages; add this repository's own below, one bullet each, stating the rule
-and how it is verified.
-
-- The compliance gates enabled in `adl-config.toml` pass before every commit
-  (verified by `adl repo controls` pre-commit and CI). A gate is switched off by
-  removing it from `[controls.compliance] enabled`, which is the owner's decision.
-- Protected paths (`adl-config.toml`, `.workflows/`, the agent surface folders,
-  `workflows/` and the declared compliance register folder) are landed only by the
-  owner. An agent leaves them uncommitted and asks (verified by the pre-commit
-  integrity gate).
-- Ratchets only shrink. A register names the specific files granted, and a grant
-  is removed once its file is clean, never added to (verified by the gate that reads
-  the register).
-- No multi-line comments in code. The explanation lives in `docs/`, and the code
-  keeps at most a one-line pointer (verified by `repository.no-multiline-comments`).
-- The standard trees `docs`, `plans`, `workflows` and `compliance` are declared in
-  `[controls.compliance.trees]`, and layout rules follow those declarations
-  (verified by the layout and docs gates).