@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.10 → 0.1.12

package/packages/fleet/jobs/git-maintain/src/main.ts

@@ -1,848 +0,0 @@
-/**
- * git-maintain — keep local repos fresh and tidy.
- *
- * For each repo under $GIT_MAINTAIN_ROOT whose directory name matches
- * $GIT_MAINTAIN_GLOB (and Git recognizes it as a worktree):
- *   1. fetch origin --prune (drop stale remote-tracking refs)
- *   2. fast-forward the local baseline branch (integration, else main/master)
- *      WITHOUT disturbing the working tree or current checkout; a checked-out
- *      baseline is fast-forwarded only when clean (`merge --ff-only`)
- *   3. prune old local branches, keeping:
- *        - protected:  integration / main / master / develop
- *        - current HEAD (never deleted)
- *        - the $KEEP most-recently-committed non-protected branches
- *      Deletion is SAFE-ONLY:
- *        - upstream "[gone]" (remote branch deleted after merge) -> git branch -D
- *        - true ancestor of baseline (--merged)                  -> git branch -d
- *        - anything else                                          -> kept + logged
- *      It NEVER force-deletes a branch that cannot be confirmed merged.
- *
- * Env:
- *   GIT_MAINTAIN_ROOT   (default: $HOME/Documents/Repos)
- *   GIT_MAINTAIN_GLOB   (default: adl-*)
- *   GIT_MAINTAIN_KEEP   (default: 3)
- *   GIT_MAINTAIN_DRY    (1 = report only: fetches, but never moves a local
- *                        ref, fast-forwards a checkout, or deletes a branch)
- *
- * CLI:
- *   --repo <path>       (repeatable) an explicit, closed list of repos, as
- *                        an alternative to the GIT_MAINTAIN_ROOT/GLOB
- *                        recursive scan above -- see `parseArgv`'s own
- *                        header comment for why this exists (the fleet's
- *                        Linux VPS checkouts live at a fixed, root-owned
- *                        path with no home-relative root to scan). When any
- *                        `--repo` is given, the scan is skipped entirely.
- *   --arm-only          used together with --repo. Runs ONLY `armHooks` for
- *                        the declared repos -- no fetch, no fast-forward,
- *                        no branch prune, no bundle-refresh installer, no
- *                        network at all.
- *
- * ARM-ONLY, why it exists (coordinator decision, 2026-09-30): the Linux
- * VPSes' `git_maintain_repos` names their OWN fleet checkout
- * (`/opt/adl-azdo`), and running the FULL job there -- fetch, fast-forward,
- * prune, bundle-refresh -- turned out to be new, unapproved, and risky
- * behaviour once actually reasoned through, not merely a self-checkout
- * ordering hazard (see `main`'s own placement comment in bin/reconcile for
- * that separate, narrower ordering concern):
- *   - the fast-forward step (2 above) would silently auto-deploy whatever
- *     `origin/integration` (or main) has advanced to, as root, onto a
- *     production checkout -- `bin/sync-and-reconcile` never pulls in
- *     checkout source mode today, so this would have been genuinely NEW
- *     auto-deploy behaviour, not a restoration of an existing one;
- *   - `fleet-cutover.sh` re-reads `fleet-retire-list.json` from that same
- *     checkout AFTER reconcile runs (fleet-cutover.sh:1129-1135, :254) --
- *     mutating the checkout mid-cutover is exactly the class of hazard this
- *     job's own "run last" placement in bin/reconcile was trying to avoid,
- *     generalized to a tool this job doesn't control;
- *   - branches get deleted (`git branch -D`) as root on a checkout other
- *     tooling depends on being stable;
- *   - the fetch step still runs in dry/plan/audit mode (see GIT_MAINTAIN_DRY
- *     above) even though nothing else does, and its own failure path exits
- *     0, not 1 -- a network hiccup would be silently absorbed rather than
- *     reported, for a step this use case has no reason to run at all.
- * The actual goal was only ever arming `core.hooksPath` -- the ONE thing
- * `.git/config` never getting the repo's own committed value is impossible
- * to route around any other way (unlike the fetch/prune/refresh above, all
- * of which land safely through this job's macOS LaunchAgent path or
- * through the ordinary bundle-refresh `refreshRepo` already runs
- * elsewhere). `--arm-only` narrows the Linux invocation to exactly that.
- *
- * Logs go to stdout; on macOS the LaunchAgent (packages/fleet/manifest.json
- * mac.common.launch_agents.git-maintain) captures stdout+stderr in
- * ~/Library/Logs/adl/git-maintain.log. On Linux there is no LaunchAgent
- * equivalent -- see `parseArgv` -- `bin/reconcile` instead runs this file
- * directly (via `bun`, not a compiled binary) on its own schedule, in
- * `--arm-only` mode, whenever a device declares `git_maintain_repos` in the
- * manifest.
- *
- * Reconcile ALSO compiles this file into the dedicated, ad-hoc-signed binary
- * /usr/local/libexec/adl/git-maintain for the macOS LaunchAgent path (see
- * packages/fleet/src/launch-agents.ts). Under launchd that binary is the
- * responsible process for macOS privacy protection (TCC), so the owner grants
- * Full Disk Access to exactly that binary; the `git` processes it spawns are
- * attributed to it. A denied listing is logged as `TCC denied` with the exact
- * remedy, and reconcile surfaces that last log line. None of that TCC
- * machinery applies to the Linux `--repo` path above, which runs as `root`.
- */
-
-import { spawnSync } from 'node:child_process'
-import { lstatSync, readFileSync, readdirSync, realpathSync, statSync, type Dirent } from 'node:fs'
-import { homedir } from 'node:os'
-import { basename, isAbsolute, join, relative, resolve } from 'node:path'
-// F6 (independent review, 2026-09-29): this job's `git fetch` runs from a
-// LaunchAgent with no TTY and no ADL_AGENT_ID_AGENT, so once bin/git-ado's
-// fail-closed rule (STATUS.md 12p decision 1) is deployed, every Azure
-// DevOps fetch was refused. The one shared resolver every other Azure
-// DevOps surface in this repo uses, never re-implemented here.
-import { NO_AGENT_IDENTITY_MESSAGE, resolveAgentIdentity } from '../../../../azdo/src/lib/agent-identity.ts'
-
-export const TCC_DENIED_MARKER = 'TCC denied'
-
-/**
- * Matches packages/fleet/src/launch-agents.ts's DEFAULT_LIBEXEC_DIR -- a
- * literal duplicate rather than an import, deliberately: launch-agents.ts
- * already imports TCC_DENIED_MARKER FROM this file, so importing the
- * constant back from there would make the two files circular.
- */
-const LIBEXEC_DIR = '/usr/local/libexec/adl'
-
-/**
- * The file whose presence marks a repo adl hook-managed. It carries several
- * owners' tables (`version`/`hooks`/`rules`/`repo` = adl hook, `extensions` =
- * agent-skills, `controls` = repo-controls) plus hand-written
- * blocks, so an installer that rewrites it wholesale silently deletes another
- * owner's section.
- *
- * The invariant is ADDITIVE-ONLY, not byte-identical. Measured 2026-09-15
- * against the real binaries (then named `adl-repo-controls install --repo X
- * --force`; see the adl-m3-finish item-1/2/3 rename below): the run
- * appends `[controls]`, `[controls.compliance]` and
- * `[controls.compliance.trees]` while leaving a pre-existing `[extensions]` table
- * and comments intact. Writing its own table IS an installer's job, so a
- * byte-identical assertion would fail on every legitimate run. What must never
- * happen is LOSING a table or comment that was there before — that is the
- * shredder case, and it is what this job refuses to continue past.
- */
-export const MARKER = 'adl-config.toml'
-
-/**
- * Installers that own repo-local surfaces, with the argv each actually takes.
- *
- * adl-m3-finish items 1-3 (2026-09-27): neither installer is a standalone
- * global command any more. `adl repo controls` folds repo-controls into the
- * one `adl` binary (docs/architecture/cli-design.md §6, STATUS.md item 10) -- `adl` is
- * itself fleet-installed by the `bun-compile` manager, so it is guaranteed
- * on PATH by the time this job runs. agent-skills has no `adl` fold-in yet
- * (a separate, not-yet-done item), so it is invoked directly from its
- * `repo-dir`-deployed copy (packages/fleet/manifest.json's "agent-skills"
- * tool, `bin/reconcile`'s `write_one_repo_dir`) via `bun`, the same way
- * every other bundled `.mjs`/`.ts` entry point in this job already is.
- *
- * The bundle NAME must come before `--repo`
- * (`install <name> --repo <path> --host claude,codex,cursor,kimi`); called without it, it exits 1 with
- * "install --repo requires a plugin name". `adl-repo` is the baseline bundle
- * its own `list --json` advertises. OpenCode is deliberately absent: its hook
- * carrier is a VPS-owned global artifact, not a direct repo-local host.
- *
- * Each installer's `repoArgs` carries only the flags that installer's own
- * `parse()` actually accepts (checked against the real CLIs, not stubs):
- * agent-skills' `adl-extensions.mjs install` accepts `--force` (a no-op kept
- * for compatibility — its own lock-owned content is always repaired on a
- * plain install); repo-controls' `install` (packages/repo-controls/src/
- * cli.ts) recognizes only `--dry-run` and exits 1 on an unknown flag, so it
- * gets none. `--force` used to be appended to every installer's argv
- * unconditionally, which made every real (non-stubbed) run of the
- * repo-controls installer fail with "unknown option for install: --force" --
- * install is already idempotent there, so nothing is lost by not forcing it.
- */
-export const INSTALLERS: readonly {
-  readonly bin: string
-  readonly args: readonly string[]
-  readonly repoArgs?: readonly string[]
-}[] = [
-  {
-    bin: 'bun',
-    args: [join(LIBEXEC_DIR, 'agent-skills', 'scripts', 'adl-extensions.mjs'), 'install', 'adl-repo'],
-    repoArgs: ['--host', 'claude,codex,cursor,kimi', '--force'],
-  },
-  { bin: 'adl', args: ['repo', 'controls', 'install'] },
-]
-
-/** Table headers and comment lines — the structure a refresh must never remove. */
-export function markerEntries(text: string): string[] {
-  return text
-    .split('\n')
-    .map((line) => line.trim())
-    .filter((line) => line.startsWith('[') || line.startsWith('#'))
-}
-
-const PROTECTED = new Set(['integration', 'main', 'master', 'develop'])
-
-function timestamp(date = new Date()): string {
-  const pad = (value: number) => String(value).padStart(2, '0')
-  const offset = -date.getTimezoneOffset()
-  const sign = offset >= 0 ? '+' : '-'
-  const abs = Math.abs(offset)
-  return (
-    `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
-    `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
-    `${sign}${pad(Math.floor(abs / 60))}${pad(abs % 60)}`
-  )
-}
-
-function log(message: string): void {
-  process.stdout.write(`[${timestamp()}] ${message}\n`)
-}
-
-/**
- * Lines explaining why ROOT could not be listed. EPERM from readdir is what
- * macOS privacy protection returns (plain permission bits give EACCES), so it
- * names the exact binary the owner must grant Full Disk Access.
- *
- * ENOTDIR is a misconfiguration -- the path is the right name but the wrong
- * kind (e.g. a file where a directory was expected). The message is the
- * scanner's own ("not a directory"), not a readdir-failure wrapper.
- */
-export function listFailureLines(root: string, error: unknown, executable: string): readonly string[] {
-  const message = error instanceof Error ? error.message : String(error)
-  const code = (error as { code?: unknown } | null)?.code
-  if (code === 'ENOTDIR') return [`${root}: ${message}`]
-  const lines = [`${root}: cannot list: ${message}`]
-  if (code === 'EPERM') {
-    lines.push(
-      `${root}: ${TCC_DENIED_MARKER}: macOS privacy protection blocked ${executable}; ` +
-        `one-time fix: System Settings › Privacy & Security › Full Disk Access › + › add ${executable}`,
-    )
-  }
-  return lines
-}
-
-export interface RepositoryScope {
-  readonly root: string
-  readonly glob: string
-  readonly recursive: true
-}
-
-const INSTALLED_MANIFEST = '/var/lib/adl/applied-manifest.json'
-
-/** Read the installed LaunchAgent scope; its root is always relative to the user's home. */
-export function readRepositoryScope(manifestPath: string, home: string, platform: 'mac' | 'linux'): RepositoryScope {
-  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as Record<string, unknown>
-  const section = manifest[platform] as Record<string, unknown> | undefined
-  const common = section?.common as Record<string, unknown> | undefined
-  const agents = common?.launch_agents as Record<string, unknown> | undefined
-  const job = agents?.['git-maintain'] as Record<string, unknown> | undefined
-  const scope = job?.repo_scope as Record<string, unknown> | undefined
-  if (
-    typeof scope?.root !== 'string' ||
-    scope.root.length === 0 ||
-    isAbsolute(scope.root) ||
-    scope.root.split(/[\\/]/).includes('..') ||
-    typeof scope.glob !== 'string' ||
-    scope.glob.length === 0 ||
-    scope.recursive !== true
-  ) {
-    throw new Error(`${manifestPath}: mac.common.launch_agents.git-maintain.repo_scope must declare a home-relative root, glob, and recursive: true`)
-  }
-  const root = resolve(home, scope.root)
-  const fromHome = relative(resolve(home), root)
-  if (fromHome === '..' || fromHome.startsWith(`..${process.platform === 'win32' ? '\\\\' : '/'}`) || isAbsolute(fromHome)) {
-    throw new Error(`${manifestPath}: git-maintain repo_scope.root escapes the user's home`)
-  }
-  return { root, glob: scope.glob, recursive: true }
-}
-
-/**
- * The fleet root is `~/Documents`; managed checkouts also live one level down
- * in `~/Documents/Repos`. Both are in scope. A non-directory entry with this
- * name at the top of the root is a misconfiguration -- silent skip would mask
- * it (status 0, no maintenance performed).
- */
-const TOP_LEVEL_COLLECTION = 'Repos'
-
-/** Recursively locate real Git roots, including worktrees, without following symlinks. */
-export function discoverGitRepositories(
-  root: string,
-  scope: Pick<RepositoryScope, 'glob' | 'recursive'>,
-  onError: (path: string, error: unknown) => void = () => {},
-): string[] {
-  const matcher = globToRegExp(scope.glob)
-  const repositories: string[] = []
-  const visit = (directory: string): void => {
-    let entries: Dirent[]
-    try {
-      entries = readdirSync(directory, { withFileTypes: true })
-    } catch (error) {
-      onError(directory, error)
-      return
-    }
-    if (directory === root) {
-      const collection = entries.find((entry) => entry.name === TOP_LEVEL_COLLECTION)
-      if (collection !== undefined && !collection.isDirectory()) {
-        onError(
-          join(directory, TOP_LEVEL_COLLECTION),
-          Object.assign(new Error('not a directory'), { code: 'ENOTDIR' }),
-        )
-        return
-      }
-    }
-    try {
-      lstatSync(join(directory, '.git'))
-      const topLevel = spawnSync('git', ['-C', directory, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' })
-      if (topLevel.error !== undefined) throw topLevel.error
-      if (topLevel.status === 0 && realpathSync(topLevel.stdout.trim()) === realpathSync(directory) && matcher.test(basename(directory))) {
-        repositories.push(directory)
-      }
-    } catch (error) {
-      if ((error as { code?: unknown } | null)?.code !== 'ENOENT') onError(join(directory, '.git'), error)
-    }
-    if (scope.recursive) {
-      for (const entry of entries) {
-        if (entry.isDirectory() && entry.name !== '.git') visit(join(directory, entry.name))
-      }
-    }
-  }
-  visit(root)
-  return repositories.sort()
-}
-
-interface GitResult {
-  readonly ok: boolean
-  readonly stdout: string
-  /**
-   * Captured so a failure can report what git SAID.
-   *
-   * This was discarded, which is why the fetch failure below could only guess
-   * at a cause -- the information never reached the call site. `.donor` then
-   * failed every run for hours under a logged `(offline?)` that nobody had
-   * checked, while the real message on an https Azure DevOps remote is
-   * `could not read Username`: an authentication problem, not a network one.
-   */
-  readonly stderr: string
-}
-
-/**
- * F6: the resolved agent identity's env overlay for every `git` child this
- * job spawns, set once in `main()` before the repo loop and merged into
- * EVERY call (not only `fetch`) -- harmless for local-only commands, and
- * simpler than threading it through every one of this file's ~30 call
- * sites. Empty until `main()` resolves an identity; a repo with no
- * Azure DevOps remote is unaffected either way.
- */
-let adoIdentityEnv: NodeJS.ProcessEnv = {}
-
-function git(repo: string, ...args: string[]): GitResult {
-  const result = spawnSync('git', ['-C', repo, ...args], { encoding: 'utf8', env: { ...process.env, ...adoIdentityEnv } })
-  if (result.error !== undefined) throw result.error
-  return { ok: result.status === 0, stdout: result.stdout, stderr: result.stderr ?? '' }
-}
-
-/** Matches bin/git's own Azure DevOps HTTPS remote check (F6/F2). */
-const ADO_REMOTE_PATTERN = /^https:\/\/[^/]*dev\.azure\.com\//
-
-/** Cheap, local-only (no network): reads the configured `origin` URL. */
-function originIsAzureDevOps(repo: string): boolean {
-  const url = git(repo, 'remote', 'get-url', 'origin')
-  return url.ok && ADO_REMOTE_PATTERN.test(url.stdout.trim())
-}
-
-function lines(output: string): string[] {
-  return output.split('\n').filter((line) => line.length > 0)
-}
-
-/** find -name semantics for the simple glob characters `*`, `?` and `[...]`. */
-function globToRegExp(glob: string): RegExp {
-  let pattern = ''
-  for (let index = 0; index < glob.length; index++) {
-    const char = glob[index]!
-    if (char === '*') pattern += '.*'
-    else if (char === '?') pattern += '.'
-    else if (char === '[') {
-      const close = glob.indexOf(']', index + 1)
-      if (close === -1) pattern += '\\['
-      else {
-        const body = glob.slice(index + 1, close).replace(/^!/, '^').replaceAll('\\', '\\\\')
-        pattern += `[${body}]`
-        index = close
-      }
-    } else pattern += char.replace(/[.+^${}()|\\/\]]/g, '\\$&')
-  }
-  return new RegExp(`^${pattern}$`, 's')
-}
-
-function isDirectory(path: string): boolean {
-  try {
-    return statSync(path).isDirectory()
-  } catch {
-    return false
-  }
-}
-
-function baselineFor(repo: string): string {
-  for (const branch of ['integration', 'main', 'master']) {
-    if (git(repo, 'show-ref', '--verify', '--quiet', `refs/remotes/origin/${branch}`).ok) return branch
-  }
-  return ''
-}
-
-function maintainRepo(repo: string, keep: number, dry: boolean): void {
-  const name = basename(repo)
-  if (!git(repo, 'rev-parse', '--git-dir').ok) return
-
-  const head = git(repo, 'symbolic-ref', '--short', '-q', 'HEAD')
-  const current = head.ok ? head.stdout.trim() : '(detached)'
-
-  // 1. fetch + prune
-  //
-  // Report what git SAID, never a guess at what it meant. This logged
-  // `fetch failed (offline?)` and discarded the stderr, so `.donor` failed
-  // every run for hours while the log asserted a cause nobody had checked --
-  // and on an https Azure DevOps remote the real message is
-  // `could not read Username`, which is an authentication problem and not a
-  // network one. A wrong cause in a log is worse than no cause: it stops the
-  // next person looking.
-  const fetched = git(repo, 'fetch', 'origin', '--prune', '--quiet')
-  if (!fetched.ok) {
-    const reason = fetched.stderr.trim().split('\n').pop() ?? 'no stderr from git'
-    log(`${name}: fetch failed, skipping repo: ${reason}`)
-    return
-  }
-
-  const base = baselineFor(repo)
-
-  // 2. fast-forward baseline without touching the working tree
-  if (base !== '') {
-    const local = `refs/heads/${base}`
-    const remote = `refs/remotes/origin/${base}`
-    const behind =
-      git(repo, 'show-ref', '--verify', '--quiet', local).ok &&
-      git(repo, 'rev-parse', local).stdout.trim() !== git(repo, 'rev-parse', remote).stdout.trim() &&
-      git(repo, 'merge-base', '--is-ancestor', local, remote).ok
-    if (current === base) {
-      if (git(repo, 'status', '--porcelain').stdout.trim() !== '') {
-        log(`${name}: ${base} checked out but dirty — skip FF`)
-      } else if (behind && dry) {
-        log(`${name}: [dry] would fast-forward ${base} (checked out)`)
-      } else if (behind) {
-        if (git(repo, 'merge', '--ff-only', `origin/${base}`, '--quiet').ok) {
-          log(`${name}: ${base} fast-forwarded (checked out)`)
-        }
-      }
-    } else if (behind) {
-      // update the local ref directly; FF-safe, no working-tree change
-      if (dry) log(`${name}: [dry] would fast-forward ${base} (background)`)
-      else if (git(repo, 'fetch', 'origin', `${base}:${base}`, '--quiet').ok) {
-        log(`${name}: ${base} ref fast-forwarded (background)`)
-      }
-    }
-  }
-
-  // 3. guarded prune
-  // Keep-set: top-KEEP most-recent non-protected, non-current branches.
-  const keptRecent = new Set(
-    lines(git(repo, 'for-each-ref', '--sort=-committerdate', 'refs/heads/', '--format=%(refname:short)').stdout)
-      .filter((branch) => !PROTECTED.has(branch) && branch !== current)
-      .slice(0, keep),
-  )
-  const merged =
-    base === ''
-      ? new Set<string>()
-      : new Set(lines(git(repo, 'branch', '--merged', `origin/${base}`, '--format=%(refname:short)').stdout))
-
-  for (const line of lines(git(repo, 'for-each-ref', 'refs/heads/', '--format=%(refname:short)|%(upstream:track)').stdout)) {
-    const separator = line.indexOf('|')
-    const branch = line.slice(0, separator)
-    const track = line.slice(separator + 1)
-    if (PROTECTED.has(branch) || branch === current || keptRecent.has(branch)) continue
-
-    if (track.includes('[gone]')) {
-      // remote branch deleted after merge -> proven safe
-      if (dry) log(`${name}: [dry] would delete (upstream gone) ${branch}`)
-      else if (git(repo, 'branch', '-D', branch).ok) log(`${name}: deleted (upstream gone) ${branch}`)
-      else log(`${name}: FAILED delete ${branch}`)
-    } else if (base !== '' && merged.has(branch)) {
-      if (dry) log(`${name}: [dry] would delete (merged into ${base}) ${branch}`)
-      else if (git(repo, 'branch', '-d', branch).ok) log(`${name}: deleted (merged into ${base}) ${branch}`)
-      else log(`${name}: kept (${branch}: -d refused)`)
-    } else {
-      log(`${name}: kept (unconfirmed merged) ${branch}`)
-    }
-  }
-}
-
-function isFile(path: string): boolean {
-  try {
-    return statSync(path).isFile()
-  } catch {
-    return false
-  }
-}
-
-/**
- * Re-install the repo-local surfaces into `repo`, if it carries the marker.
- * Returns false if anything went wrong — a missing installer, a failing one,
- * or a disturbed marker. A missing installer is a LOUD failure, never a quiet
- * skip: "marker found, installer absent, nothing happened, no error" is
- * exactly the presence-is-not-armedness shape this refresh exists to remove.
- *
- * Never commits and never stages: it runs the installers and nothing else.
- */
-function refreshRepo(repo: string, dry: boolean): boolean {
-  const name = basename(repo)
-  const marker = join(repo, MARKER)
-  if (!isFile(marker)) return true
-
-  const argvFor = (installer: (typeof INSTALLERS)[number]) => [
-    ...installer.args,
-    '--repo',
-    repo,
-    ...(installer.repoArgs ?? []),
-  ]
-
-  if (dry) {
-    for (const installer of INSTALLERS) {
-      log(`${name}: [dry] would refresh via ${installer.bin} ${argvFor(installer).join(' ')}`)
-    }
-    return true
-  }
-
-  const beforeText = readFileSync(marker, 'utf8')
-  const mtimeBefore = statSync(marker).mtimeMs
-  const before = markerEntries(beforeText)
-  let ok = true
-
-  for (const installer of INSTALLERS) {
-    const argv = argvFor(installer)
-    const result = spawnSync(installer.bin, argv, { encoding: 'utf8' })
-    const code = (result.error as { code?: unknown } | undefined)?.code
-    if (code === 'ENOENT') {
-      log(`${name}: ${installer.bin} not found on PATH — refresh incomplete, repo left stale`)
-      ok = false
-    } else if (result.error !== undefined) {
-      log(`${name}: ${installer.bin} failed to run: ${result.error.message}`)
-      ok = false
-    } else if (result.status !== 0) {
-      log(`${name}: ${installer.bin} ${argv.join(' ')} exited ${result.status}: ${result.stderr.trim()}`)
-      ok = false
-    } else {
-      log(`${name}: refreshed via ${installer.bin}`)
-    }
-  }
-
-  const afterText = readFileSync(marker, 'utf8')
-  const after = markerEntries(afterText)
-  const lost = before.filter((entry) => !after.includes(entry))
-
-  if (lost.length > 0) {
-    log(`${name}: ${MARKER} LOST ${lost.join(', ')} at ${repo} — another owner's section was destroyed; refusing to call this a clean refresh`)
-    ok = false
-  } else if (afterText === beforeText && statSync(marker).mtimeMs === mtimeBefore) {
-    // The steady state, and what every run after a repo's first must look like.
-    log(`${name}: ${MARKER} untouched`)
-  } else {
-    // An installer creating its own missing table: legitimate exactly once per
-    // repo. Seen on a repo that already had every table, it means an installer
-    // stopped being idempotent — so it is logged, loudly, rather than ignored.
-    log(`${name}: ${MARKER} gained ${after.filter((entry) => !before.includes(entry)).join(', ') || '(no new table)'} at ${repo} — expected only on a repo's first install`)
-  }
-
-  return ok
-}
-
-/**
- * The repository-relative hooks directory repo-controls installs into every
- * enrolled repo (packages/repo-controls/src/constants.ts's own HOOKS_PATH) --
- * a literal duplicate here, deliberately, the same as LIBEXEC_DIR above:
- * this job needs only the one string, and it never changes independent of
- * the layout `adl repo controls install` itself writes.
- */
-const HOOKS_DIR = '.workflows/hooks'
-
-/**
- * Arms `core.hooksPath` for a repo carrying the MARKER, if the repo also
- * carries a committed `.workflows/hooks` directory.
- *
- * `core.hooksPath` lives in `.git/config`, which never travels with a clone
- * -- a repo cloned onto a fresh machine keeps its committed hook stubs but
- * stays unarmed (every commit silently skips every gate) until someone runs
- * `adl repo controls install` there by hand. `refreshRepo` above already
- * runs that installer on this job's own schedule, but only on a repo that
- * ALREADY has the marker's tables in place; this closes the narrower gap of
- * the git-local setting itself, directly, on the same schedule, without
- * depending on that installer being present or succeeding.
- *
- * Scope is exactly the marker AND a committed hooks directory -- never a
- * repo missing either. Correction (coordinator, 2026-09-30): a repo in that
- * scope is ENROLLED, and an enrolled repo has no valid reason for
- * `core.hooksPath` to point anywhere else -- it means the repo has NO gates
- * (every commit silently skips every one of them), not a deliberate owner
- * choice worth preserving. So a wrong value is restored, exactly like
- * `packages/repo-controls/src/install.ts`'s own unconditional restore
- * (which `refreshRepo` above already runs as part of this job's bundle
- * refresh) -- this aligns with that standard instead of deviating from it.
- *
- * Returns false only when arming was attempted and the write itself failed
- * -- a repo skipped by scope or already armed returns true; none of those
- * is a fleet failure.
- */
-function armHooks(repo: string, dry: boolean): boolean {
-  const name = basename(repo)
-  if (!isFile(join(repo, MARKER))) return true
-  if (!isDirectory(join(repo, HOOKS_DIR))) return true
-
-  const current = git(repo, 'config', '--local', '--get', 'core.hooksPath')
-  const value = current.ok ? current.stdout.trim() : ''
-
-  if (value === HOOKS_DIR) {
-    log(`${name}: hooksPath already armed (${HOOKS_DIR})`)
-    return true
-  }
-  const wasUnset = value === ''
-  const suffix = wasUnset ? '' : ` (was ${value})`
-  if (dry) {
-    log(`${name}: [dry] would ${wasUnset ? 'arm' : 're-arm'} core.hooksPath=${HOOKS_DIR}${suffix}`)
-    return true
-  }
-  if (git(repo, 'config', '--local', 'core.hooksPath', HOOKS_DIR).ok) {
-    log(`${name}: ${wasUnset ? 'armed' : 're-armed'} core.hooksPath=${HOOKS_DIR}${suffix}`)
-    return true
-  }
-  log(`${name}: FAILED to arm core.hooksPath`)
-  return false
-}
-
-export interface ParsedArgv {
-  readonly repos: string[]
-  readonly armOnly: boolean
-}
-
-/**
- * Strict argv parser. Recognizes exactly two tokens:
- *
- *   --repo <path>  (repeatable) -- an explicit, closed list of
- *                  repositories, as an alternative to the recursive
- *                  root+glob scan `discoverGitRepositories` performs. This
- *                  is how `bin/reconcile` reaches the fleet's own Linux VPS
- *                  checkouts (see `main`'s header comment for why): those
- *                  live at a fixed path outside any device's home (e.g.
- *                  `/opt/adl-azdo`, root-owned), so there is no
- *                  home-relative root to recursively scan in the first
- *                  place -- and a recursive scan from a shared parent like
- *                  `/opt` would also walk into unrelated, explicitly
- *                  off-limits directories (Azure Pipelines agent installs).
- *                  An explicit path list structurally cannot do that: it
- *                  only ever touches exactly what it is given.
- *
- *   --arm-only     REQUIRES at least one --repo (enforced here, not just
- *                  documented: --arm-only alone is a usage error) -- see
- *                  `main`'s ARM-ONLY comment for the full decision. Runs
- *                  ONLY `armHooks` for the declared repos -- no fetch, no
- *                  fast-forward, no branch prune, no bundle-refresh
- *                  installer, no network at all.
- *
- * Both are CLI flags, not environment variables: `bin/reconcile` computes
- * this data from the manifest itself and passes it as argv, the same
- * convention already used for every other bun-invoked step in that script
- * (`--platform <p> --mode <m>`, never a bespoke env var for data reconcile
- * already has).
- *
- * ANY other token -- an unrecognized flag, `--repo` with no following
- * value, `--repo=/path` (the `=` form is not supported; write `--repo
- * /path`), or a near-miss like `--rep` -- is a loud, fatal usage error.
- * This must never happen: silently ignoring or misreading an argument here
- * and falling through to the recursive scope-resolution path below would
- * silently WIDEN what this run touches, far past whatever was actually
- * declared.
- */
-export function parseArgv(argv: readonly string[]): ParsedArgv {
-  const repos: string[] = []
-  let armOnly = false
-  for (let index = 0; index < argv.length; index++) {
-    const token = argv[index]!
-    if (token === '--repo') {
-      const value = argv[index + 1]
-      if (value === undefined) throw new Error('--repo requires a path argument')
-      repos.push(value)
-      index++
-    } else if (token === '--arm-only') {
-      armOnly = true
-    } else {
-      throw new Error(`unknown argument: ${token}`)
-    }
-  }
-  if (armOnly && repos.length === 0) throw new Error('--arm-only requires at least one --repo')
-  return { repos, armOnly }
-}
-
-/**
- * Path names, or resolves to (via realpath, so a symlink cannot launder
- * it), something naming an Azure Pipelines agent install -- case
- * insensitive, matching bin/validate-manifest's own schema-layer guard on
- * `git_maintain_repos` (independent review, 2026-09-30: that guard alone
- * only ever sees the manifest's literal string; this is the same check
- * enforced again at the point of actual use, so a hand-typed `--repo`
- * argument or a symlinked path bypassing the manifest entirely is refused
- * too). This estate's own agent directories/services are never named here,
- * on purpose: this function exists so this job can refuse them, not so it
- * can reference them as a path it might otherwise touch.
- */
-const FORBIDDEN_PATH_PATTERN = /azagent|vsts\.agent/i
-
-function isForbiddenAzurePipelinesPath(path: string): boolean {
-  if (FORBIDDEN_PATH_PATTERN.test(path)) return true
-  try {
-    return FORBIDDEN_PATH_PATTERN.test(realpathSync(path))
-  } catch {
-    return false
-  }
-}
-
-/** Same top-level-repo check `discoverGitRepositories` applies while walking -- standalone, for a caller that already has an exact candidate path and skips the walk entirely. */
-function isGitToplevel(directory: string): boolean {
-  try {
-    lstatSync(join(directory, '.git'))
-  } catch {
-    return false
-  }
-  const topLevel = spawnSync('git', ['-C', directory, 'rev-parse', '--show-toplevel'], { encoding: 'utf8' })
-  if (topLevel.error !== undefined || topLevel.status !== 0) return false
-  try {
-    return realpathSync(topLevel.stdout.trim()) === realpathSync(directory)
-  } catch {
-    return false
-  }
-}
-
-export function main(env: NodeJS.ProcessEnv, executable: string, manifestPath = INSTALLED_MANIFEST, argv: readonly string[] = []): number {
-  adoIdentityEnv = {}
-  let parsedArgv: ParsedArgv
-  try {
-    parsedArgv = parseArgv(argv)
-  } catch (error) {
-    // Exit 2 (usage error), never 1 (runtime failure) -- and returned here,
-    // before any scope is resolved, so a bad argument can never fall
-    // through to the recursive scan below by accident.
-    log(`usage error: ${error instanceof Error ? error.message : String(error)}`)
-    return 2
-  }
-  const { repos: explicitRepos, armOnly } = parsedArgv
-  let scope: RepositoryScope | undefined
-  if (explicitRepos.length === 0) {
-    if (env.GIT_MAINTAIN_ROOT !== undefined || env.GIT_MAINTAIN_GLOB !== undefined) {
-      // Optional test overrides keep fixtures out of the installed host scope.
-      scope = {
-        root: env.GIT_MAINTAIN_ROOT ?? join(homedir(), 'Documents'),
-        glob: env.GIT_MAINTAIN_GLOB ?? '*',
-        recursive: true,
-      }
-    } else {
-      try {
-        const platform = process.platform === 'darwin' ? 'mac' : 'linux'
-        scope = readRepositoryScope(manifestPath, homedir(), platform)
-      } catch (error) {
-        log(`cannot read installed git-maintain scope from ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`)
-        return 1
-      }
-    }
-  }
-  const keepRaw = env.GIT_MAINTAIN_KEEP || '3'
-  const dryRaw = env.GIT_MAINTAIN_DRY || '0'
-  const keep = Number(keepRaw)
-  if (!Number.isInteger(keep) || keep < 0) {
-    log(`GIT_MAINTAIN_KEEP must be a non-negative integer: ${keepRaw}`)
-    return 1
-  }
-  const dry = dryRaw === '1'
-
-  // F6: resolve the Azure DevOps agent identity ONCE, before touching any
-  // repo, the same way every other Azure DevOps surface does
-  // (`resolveAgentIdentity`: env, else the machine default-agent file,
-  // never a human fallback). A real resolution error (e.g. an invalid name
-  // in the default-agent file) is fatal, not a per-repo skip -- it means
-  // the machine's own identity configuration is broken. Resolving to
-  // "nothing configured" is not fatal by itself: only Azure DevOps-remoted
-  // repos need it, and those are skipped loudly below, never silently
-  // fetched with no identity (AGENTS.md: "no silent fallback or degrade").
-  //
-  // ARM-ONLY (coordinator decision, 2026-09-30): skipped entirely in
-  // --arm-only mode, which never fetches and so never needs an Azure
-  // DevOps identity for anything -- resolving one anyway would make this
-  // mode's success depend on machine identity configuration it has no use
-  // for at all.
-  let agentForAdo: string | undefined
-  if (!armOnly) {
-    try {
-      agentForAdo = resolveAgentIdentity(env).agent
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error)
-      if (message !== NO_AGENT_IDENTITY_MESSAGE) {
-        log(`cannot resolve an Azure DevOps agent identity: ${message}`)
-        return 1
-      }
-      log(
-        'no Azure DevOps agent identity resolved (no ADL_AGENT_ID_AGENT, no default-agent file): ' +
-          'Azure DevOps-remoted repos will be skipped this run, not silently fetched with no identity',
-      )
-    }
-    if (agentForAdo !== undefined) adoIdentityEnv = { ADL_AGENT_ID_AGENT: agentForAdo }
-  }
-
-  let discoveryFailed = false
-  let candidates: string[]
-  if (explicitRepos.length > 0) {
-    log(`=== git-maintain start (repos=${explicitRepos.length} declared${armOnly ? ', arm-only' : ''} keep=${keepRaw} dry=${dryRaw}) ===`)
-    candidates = []
-    for (const repo of explicitRepos.slice().sort()) {
-      if (isForbiddenAzurePipelinesPath(repo)) {
-        log(`${repo}: refusing an Azure Pipelines agent path (declared via --repo)`)
-        discoveryFailed = true
-      } else if (isGitToplevel(repo)) {
-        candidates.push(repo)
-      } else {
-        log(`${repo}: not a git repository (declared via --repo)`)
-        discoveryFailed = true
-      }
-    }
-  } else {
-    const { root, glob } = scope as RepositoryScope
-    log(`=== git-maintain start (root=${root} glob=${glob} keep=${keepRaw} dry=${dryRaw}) ===`)
-    if (!isDirectory(root)) {
-      log(`${root}: missing (not a directory)`)
-      return 1
-    }
-    candidates = discoverGitRepositories(root, scope as RepositoryScope, (path, error) => {
-      for (const line of listFailureLines(path, error, executable)) log(line)
-      discoveryFailed = true
-    })
-  }
-
-  let refreshed = !discoveryFailed
-  for (const repo of candidates) {
-    const name = basename(repo)
-    // Local-only (no fetch, no Azure DevOps identity needed), so it runs for
-    // every candidate before the identity gate below -- a repo skipped for
-    // having no resolvable ADO identity must not also stay unarmed for a
-    // reason that has nothing to do with that.
-    if (!armHooks(repo, dry)) refreshed = false
-    // ARM-ONLY: nothing below this line ever runs. No fetch, no
-    // fast-forward, no branch prune (maintainRepo), no bundle-refresh
-    // installer (refreshRepo) -- and therefore no Azure DevOps identity
-    // check either, since that check exists only to gate the fetch
-    // maintainRepo is about to skip anyway.
-    if (armOnly) continue
-    if (agentForAdo === undefined && originIsAzureDevOps(repo)) {
-      log(`${name}: skipping — Azure DevOps remote but no agent identity resolved (see the start-of-run message above)`)
-      refreshed = false
-      continue
-    }
-    maintainRepo(repo, keep, dry)
-    if (!refreshRepo(repo, dry)) refreshed = false
-  }
-
-  log('=== git-maintain done ===')
-  return refreshed ? 0 : 1
-}
-
-if (import.meta.main) {
-  process.exitCode = main(process.env, process.execPath, INSTALLED_MANIFEST, process.argv.slice(2))
-}