@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.6 → 0.1.8

package/packages/azdo/src/lib/graph-identity.ts

@@ -6,14 +6,52 @@
 // APIs use everywhere else (`createdBy.id`, `reviewers[].id`, the
 // `autoCompleteSetBy.id` this package already sends in azdo-pr.ts).
 //
+// MODULE CONTRACT (Tarun, 2026-09-30, "we should have one standard —
+// whatever is the working form should become standard"): this is the ONE
+// place in this repository that builds, translates, or compares an Azure
+// DevOps identity descriptor. An identity has several DIFFERENT string
+// forms, and — verified live, the hard way, across several rounds of the
+// same bug — each Azure DevOps API accepts exactly ONE of them, never the
+// others:
+//   - GRAPH descriptor (`aadsp.*` service principal, `aadid.*` user,
+//     `vssgp.*`/`aadgp.*` group, `svc.*` a Graph-side service principal
+//     alias) — what Graph Subject Query / Graph Memberships / `az devops
+//     security permission` accept and return. The Access Control Lists
+//     Query API (`accesscontrollists`) CANNOT evaluate this form at all —
+//     verified live: querying it with agent-tarun's `aadsp.*` descriptor
+//     returns a hollow, empty ACE, not "no permission".
+//   - LEGACY descriptor (`Microsoft.VisualStudio.Services.Claims.
+//     AadServicePrincipal;<tenant>\<objectId>` for a service principal,
+//     `Microsoft.TeamFoundation.ServiceIdentity;<sid>;<projectId>` for a
+//     build service, `Microsoft.TeamFoundation.Identity;<sid>` for a
+//     legacy-native group) — what the Access Control Lists Query API's
+//     `descriptors` filter and its `acesDictionary` keys actually use.
+//     `resolveLegacyDescriptor()`/`resolveAgentLegacyDescriptor()` below are
+//     the only way this module produces one.
+//   - STORAGE KEY (a legacy GUID) — what the Git PR REST APIs want in
+//     `reviewers/{reviewerId}` and read back as `createdBy.id`/
+//     `autoCompleteSetBy.id`. `resolveAgentIdentityId()` below is the only
+//     way this module produces one (Graph descriptor -> Storage Keys — Get).
+// Every caller in this repository asks for the SPECIFIC form its own API
+// needs by calling the matching function below — never constructs, parses,
+// or compares a descriptor string itself (audited 2026-09-30: `rg` across
+// apps/, packages/, bin/, workflows/ found no other descriptor construction
+// anywhere in this repository outside this file, azdo-repo-doctor.ts's
+// consumption of these functions, and the two test files that stub these
+// exact APIs). See docs/architecture/cli-design.md's "Identity descriptor
+// forms" section for the same rule stated as a table.
+//
 // Two REST calls, both against the org-scoped Graph host (a different host
 // from `dev.azure.com/{org}/{project}`, same as azdo-repo-doctor.ts already
 // established for the same reason):
 //
 //   1. Graph — Subject Query (display name -> Graph descriptor)
 //      POST https://vssps.dev.azure.com/{org}/_apis/graph/subjectquery?api-version=7.1-preview.1
-//      body: { query: <displayName>, subjectKind: ['User'] }
+//      body: { query: <displayName>, subjectKind: ['User', 'ServicePrincipal'] }
 //      https://learn.microsoft.com/en-us/rest/api/azure/devops/graph/subject-query/query
+//      (agent-tarun/agent-vivek/agent-reviewer are 'aadsp' service-principal
+//      subjects, not 'User' subjects — verified live 2026-09-30, see
+//      resolveAgentDescriptor()'s own doc comment below for the real shape)
 //
 //   2. Graph — Storage Keys — Get (descriptor -> legacy GUID identity id)
 //      GET https://vssps.dev.azure.com/{org}/_apis/graph/storagekeys/{subjectDescriptor}?api-version=7.1
@@ -72,11 +110,28 @@ export interface GraphSubjectQueryResponse {
   value?: Array<{ displayName?: string; descriptor?: string }>;
 }
 
-/** Resolve `displayName` to its Graph descriptor, or undefined when the Subject Query finds no exact match. */
+/**
+ * Resolve `displayName` to its Graph descriptor, or undefined when the
+ * Subject Query finds no exact match.
+ *
+ * Probed live 2026-09-30 against amsterdamdatalabs/vssps (read-only, as the
+ * calling agent): agent-tarun / agent-vivek / agent-reviewer are Azure AD
+ * SERVICE PRINCIPAL ("aadsp") subjects, not Graph 'User' subjects —
+ * `subjectKind: ['User']` alone returns `{"count":0,"value":null}` for all
+ * three, which is exactly the `permissions.<agent>.not-found` drift
+ * `azdo-repo-doctor.ts` reported live against agent-identities and
+ * adl-agent-control before this fix. Adding `'ServicePrincipal'` to
+ * `subjectKind` returns an exact `displayName` match, e.g. for agent-tarun
+ * (shape shown; the tenant/object ids below are fake, same shape as real):
+ * `{"subjectKind":"servicePrincipal","displayName":"agent-tarun",
+ * "descriptor":"aadsp.ZmFrZS1hZ2VudC10YXJ1bi1kZXNjcmlwdG9y",...}`.
+ * `'User'` stays in the list too — a future named agent could be a real
+ * Graph user, and Subject Query already excludes non-exact-name matches.
+ */
 export async function resolveAgentDescriptor(displayName: string): Promise<string | undefined> {
   const result = await postJson<GraphSubjectQueryResponse>(
     `${vsspsBaseUrl()}/_apis/graph/subjectquery?api-version=7.1-preview.1`,
-    { query: displayName, subjectKind: ['User'] },
+    { query: displayName, subjectKind: ['User', 'ServicePrincipal'] },
     'Graph subject query',
   );
   return (result.value ?? []).find((subject) => subject.displayName === displayName)?.descriptor;
@@ -130,6 +185,138 @@ export async function resolveIdentityByDisplayName(displayName: string): Promise
   )?.descriptor;
 }
 
+/** Identities - Read Identities' `subjectDescriptors` response shape — only the single field resolveLegacyDescriptor() below reads (no `memberOf`; see that function's doc comment for why). */
+interface IdentityBySubjectDescriptorResponse {
+  count?: number;
+  value?: Array<{ descriptor?: string }>;
+}
+
+/** subjectDescriptor (a Graph descriptor, e.g. `aadsp.*`) -> its resolved legacy descriptor, or `null` for "resolved to nothing" (cached distinctly from "not yet looked up"). Cached across all three agents for the life of this process — see resetLegacyDescriptorCacheForTests(). */
+const legacyDescriptorCache = new Map<string, string | null>();
+
+/** Test seam: forget every cached legacy-descriptor resolution. */
+export function resetLegacyDescriptorCacheForTests(): void {
+  legacyDescriptorCache.clear();
+}
+
+/**
+ * Resolve a Graph `subjectDescriptor` (e.g. an `aadsp.*` service principal)
+ * to its own LEGACY descriptor, via Identities - Read Identities'
+ * `subjectDescriptors` + `queryMembership=ExpandedUp` mode:
+ *   GET https://vssps.dev.azure.com/{org}/_apis/identities?subjectDescriptors=<descriptor>&queryMembership=ExpandedUp&api-version=7.1
+ *   https://learn.microsoft.com/en-us/rest/api/azure/devops/ims/identities/read-identities
+ * (`ExpandedUp` also returns a `memberOf` array of every group the identity
+ * transitively belongs to, already in legacy form — deliberately UNUSED
+ * here, see the "second review" note below; `queryMembership` still has to
+ * be a value the API accepts, and `ExpandedUp` is the one already verified
+ * live to work for an `aadsp.*` subject, so it stays rather than
+ * re-verifying a different mode for no behavioural gain.)
+ *
+ * WHY this replaces the Graph-Memberships-walk this file used before
+ * (independent review, 2026-09-30): the Access Control Lists Query API
+ * cannot evaluate a raw GRAPH descriptor at all. Verified live: querying it
+ * with agent-tarun's `aadsp.*` descriptor returns a hollow, empty ACE
+ * (`allow:0, deny:0, extendedInfo:{}`) — not "no permission", but "this
+ * identity form is unrecognized by the legacy security-evaluation
+ * pipeline". Querying the SAME token with agent-tarun's LEGACY descriptor
+ * from THIS function instead (`Microsoft.VisualStudio.Services.Claims.
+ * AadServicePrincipal;<tenant>\<objectId>`) returned `effectiveAllow: 82038`
+ * — the security service itself expanding group membership AND token-level
+ * inheritance once given a descriptor form it recognizes. A full,
+ * unfiltered ACL dump confirmed agent-tarun still holds NO direct ACE
+ * anywhere (no key matching its legacy descriptor or object id exists in
+ * the raw stored ACEs) — that `82038` is server-computed from its group
+ * membership, not a direct grant.
+ *
+ * SECOND REVIEW, 2026-09-30 (design correction): an earlier version of this
+ * fix ALSO queried every one of `memberOf`'s group descriptors separately
+ * and unioned their allow/deny bits client-side. That is WRONG in general:
+ * the server's own per-descriptor evaluation already combines group
+ * membership with TOKEN-level inheritance using real precedence (e.g. an
+ * explicit Allow at the repo-scope token can override an inherited Deny
+ * that came down from the project-scope token) — a client-side union of
+ * separately-queried group ACEs has no way to know which token level a bit
+ * came from, and can therefore disagree with the server: a false
+ * `missing-*`, or worse, silently hiding a real forbidden bit the server
+ * would report. The server is authoritative and already does this
+ * correctly for a SINGLE descriptor queried at a SINGLE token — so the
+ * fix is to ask it exactly that question (this function, plus
+ * `checkAgentPermissions()`'s single ACL read on the returned descriptor),
+ * never to reconstruct the answer from parts ourselves. `memberOf` is
+ * therefore not read by any caller any more; ExpandedUp is kept only
+ * because it is the already-verified-live way to obtain the legacy
+ * descriptor for an `aadsp.*` subject.
+ *
+ * Live-verified for an `aadsp.*` (AAD service principal) subject; NOT
+ * usable for an already-legacy descriptor (a build service's
+ * `Microsoft.TeamFoundation.ServiceIdentity;...`) — probed live the same
+ * way: `subjectDescriptors=<that descriptor>` 400s with "descriptors
+ * element.IdentityType" must have at least one character, i.e. this API
+ * mode expects a GRAPH-space descriptor as input, not a legacy one.
+ * `checkBuildServicePermissions()`/`checkOneBuildServiceCanRelease()` do not
+ * call this — the build service already resolves straight to its legacy
+ * descriptor, which live evidence shows already carries direct ACEs.
+ *
+ * Returns undefined when the identity itself cannot be resolved this way at
+ * all (`count: 0`) — the caller reports that as its own distinct, loud
+ * drift, never silently treated as "no permission".
+ */
+export async function resolveLegacyDescriptor(subjectDescriptor: string): Promise<string | undefined> {
+  const cached = legacyDescriptorCache.get(subjectDescriptor);
+  if (cached !== undefined) return cached ?? undefined;
+  const url = `${vsspsBaseUrl()}/_apis/identities?subjectDescriptors=${encodeURIComponent(subjectDescriptor)}&queryMembership=ExpandedUp&api-version=7.1`;
+  const result = await fetchJson<IdentityBySubjectDescriptorResponse>(
+    url,
+    'Read identities (subjectDescriptors, ExpandedUp)',
+  );
+  const resolved = (result.value ?? [])[0]?.descriptor ?? null;
+  legacyDescriptorCache.set(subjectDescriptor, resolved);
+  return resolved ?? undefined;
+}
+
+/**
+ * `displayName` (one of the three agents) -> its own LEGACY descriptor —
+ * the ONE descriptor `checkAgentPermissions()` queries the ACL with, and
+ * trusts the server's `effectiveAllow`/`effectiveDeny` on directly (see
+ * `resolveLegacyDescriptor()`'s doc comment for why this is the correct,
+ * authoritative unit — never a client-side union across several
+ * descriptors).
+ *
+ * Returns undefined when `displayName` cannot be resolved to a Graph
+ * subject at all (`not-found`) OR when that subject resolves in Graph but
+ * the Identities — ExpandedUp hop itself fails to resolve a legacy
+ * descriptor for it (`expansion-failed`) — a distinct condition the caller
+ * must tell apart rather than reporting both as one generic failure.
+ */
+export async function resolveAgentLegacyDescriptor(
+  displayName: string,
+): Promise<{ descriptor: string } | { error: 'not-found' | 'expansion-failed' }> {
+  const own = await resolveAgentDescriptor(displayName);
+  if (!own) return { error: 'not-found' };
+  const legacy = await resolveLegacyDescriptor(own);
+  if (!legacy) return { error: 'expansion-failed' };
+  return { descriptor: legacy };
+}
+
+/**
+ * True when `descriptor` is a specific project's OWN build-service identity
+ * — a LEGACY `Microsoft.TeamFoundation.ServiceIdentity;<sid>;<projectId>`
+ * descriptor, discovered by scanning a project-level Access Control Lists
+ * dump for the one entry whose descriptor both starts with that prefix and
+ * embeds `projectId` (there is no by-display-name lookup for it — the
+ * project's own build service has no stable friendly name to search by,
+ * unlike `resolveIdentityByDisplayName()` above, which resolves the
+ * RELEASE-pipeline build service — project-scoped OR collection-scoped —
+ * by its exact Security-tab display name instead; the two are looked up
+ * differently because they answer genuinely different questions, not
+ * because of an ad-hoc form mismatch). The single comparison every caller
+ * that needs this discovery uses — see azdo-repo-doctor.ts's
+ * `resolveBuildServiceDescriptor()`, its only caller.
+ */
+export function isProjectBuildServiceDescriptor(descriptor: string, projectId: string): boolean {
+  return descriptor.startsWith('Microsoft.TeamFoundation.ServiceIdentity') && descriptor.includes(projectId);
+}
+
 /**
  * `agent` (one of "agent-tarun" / "agent-vivek" / "agent-reviewer") -> the
  * GUID identity id a Git PR API call accepts as `reviewers/{reviewerId}` or

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

@@ -24,17 +24,65 @@
  *   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
+ * 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.
+ * ~/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 compiles this file into the dedicated, ad-hoc-signed binary
- * /usr/local/libexec/adl/git-maintain (see
+ * 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.
+ * 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'
@@ -501,26 +549,202 @@ function refreshRepo(repo: string, dry: boolean): boolean {
   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,
+/**
+ * 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}`)
     }
-  } 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
+  }
+  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 { root, glob } = scope
   const keepRaw = env.GIT_MAINTAIN_KEEP || '3'
   const dryRaw = env.GIT_MAINTAIN_DRY || '0'
   const keep = Number(keepRaw)
@@ -539,37 +763,73 @@ export function main(env: NodeJS.ProcessEnv, executable: string, manifestPath =
   // "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
-  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
+  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',
+      )
     }
-    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 }
   }
-  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 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
@@ -584,5 +844,5 @@ export function main(env: NodeJS.ProcessEnv, executable: string, manifestPath =
 }
 
 if (import.meta.main) {
-  process.exitCode = main(process.env, process.execPath)
+  process.exitCode = main(process.env, process.execPath, INSTALLED_MANIFEST, process.argv.slice(2))
 }