@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

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

@@ -0,0 +1,588 @@
+/**
+ * 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)
+ *
+ * Logs go to stdout; the LaunchAgent (packages/fleet/manifest.json
+ * mac.common.launch_agents.git-maintain) captures stdout+stderr in
+ * ~/Library/Logs/adl/git-maintain.log.
+ *
+ * Reconcile compiles this file into the dedicated, ad-hoc-signed binary
+ * /usr/local/libexec/adl/git-maintain (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.
+ */
+
+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
+}
+
+export function main(env: NodeJS.ProcessEnv, executable: string, manifestPath = INSTALLED_MANIFEST): number {
+  adoIdentityEnv = {}
+  let scope: RepositoryScope
+  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 { root, glob } = scope
+  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").
+  let agentForAdo: string | undefined
+  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 }
+
+  log(`=== git-maintain start (root=${root} glob=${glob} keep=${keepRaw} dry=${dryRaw}) ===`)
+
+  if (!isDirectory(root)) {
+    log(`${root}: missing (not a directory)`)
+    return 1
+  }
+  let discoveryFailed = false
+  const candidates = discoverGitRepositories(root, scope, (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)
+    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)
+}