@app-vitals/agent-runtime 0.0.1 → 0.1.0

package/github-auth-deps.ts

@@ -0,0 +1,128 @@
+/**
+ * agent/src/runtime/github-auth-deps.ts
+ *
+ * Builds the production GitHubAuthDeps for setupGitHubAuth() — shared by
+ * entrypoint-main.ts (one-shot boot call, Step 5) and index.ts
+ * (retry-on-tick via github-auth-startup.ts's startGitHubAuthIfPossible())
+ * so the two separate processes wire identical spawnSync/writeToken/
+ * tokenPath/credentialHelperPath behavior instead of duplicating it.
+ *
+ * Only index.ts enables installation discovery (`withInstallations`): it owns
+ * repo scope (agentReposRef) and the per-owner `gh-token.d/` files. The
+ * entrypoint process keeps the single pinned-installation path, whose
+ * refresh rewrites `gh-token` only so it never clobbers index.ts's per-owner
+ * files.
+ */
+
+import { join } from "node:path";
+import { createAppAuth } from "@octokit/auth-app";
+import { agentReposRef } from "./agent-repos-ref.ts";
+import { writeFileAtomic, writeTokenFiles } from "./gh-token-files.ts";
+import {
+  createGitHubTokenManager,
+  type GitHubTokenManager,
+  getBotIdentity,
+} from "./github-app-auth.ts";
+import {
+  githubInstallationsManagerRef,
+  scopeOwnersOf,
+} from "./github-auth-startup.ts";
+import { GitHubInstallationsManager } from "./github-installations.ts";
+import {
+  type GitHubInstallationsReporter,
+  NoopGitHubInstallationsReporter,
+  startInstallationsHeartbeat,
+} from "./github-installations-reporter.ts";
+import type {
+  GitHubAuthDeps,
+  GitHubInstallationsDeps,
+} from "./setup-github-auth.ts";
+
+type InstallationAuthFn = ConstructorParameters<
+  typeof GitHubTokenManager
+>[0]["auth"];
+
+/** Production installations manager built from live GH_APP_* env vars. */
+function createInstallationsManager(
+  onTokensChanged: () => void,
+  reporter: GitHubInstallationsReporter,
+): GitHubInstallationsManager {
+  const env = process.env;
+  const appAuth = createAppAuth({
+    appId: env.GH_APP_ID ?? "",
+    privateKey: (env.GH_APP_PRIVATE_KEY ?? "").replace(/\\n/g, "\n"),
+  });
+  const auth: InstallationAuthFn = async (params) =>
+    appAuth(
+      params as Parameters<typeof appAuth>[0],
+    ) as ReturnType<InstallationAuthFn>;
+  const pin = Number(env.GH_APP_INSTALLATION_ID);
+  const manager: GitHubInstallationsManager = new GitHubInstallationsManager({
+    auth,
+    pinnedId: Number.isInteger(pin) && pin > 0 ? pin : null,
+    onEvent: (event) => {
+      if (event.type === "minted") onTokensChanged();
+    },
+    onChange: (state) => {
+      onTokensChanged();
+      void reporter.report(state);
+    },
+  });
+  startInstallationsHeartbeat(reporter, () => manager.getState());
+  return manager;
+}
+
+/**
+ * @param agentHome persistent agent home dir — the token file lives at `${agentHome}/gh-token`.
+ * @param scriptsBin directory containing `git-credential-shipwright.sh`.
+ * @param opts.withInstallations enable installation discovery (index.ts only).
+ */
+export function buildGitHubAuthDeps(
+  agentHome: string,
+  scriptsBin: string,
+  opts: {
+    withInstallations?: boolean;
+    installationsReporter?: GitHubInstallationsReporter;
+  } = {},
+): GitHubAuthDeps {
+  const tokenPath = join(agentHome, "gh-token");
+
+  const installations: GitHubInstallationsDeps | undefined =
+    opts.withInstallations
+      ? {
+          createManager: (onTokensChanged) =>
+            createInstallationsManager(
+              onTokensChanged,
+              opts.installationsReporter ??
+                new NoopGitHubInstallationsReporter(),
+            ),
+          getScopeOwners: () => scopeOwnersOf(agentReposRef),
+          writeTokenFiles: (input) => writeTokenFiles(agentHome, input),
+          onActivated: (manager) => githubInstallationsManagerRef.set(manager),
+        }
+      : undefined;
+
+  return {
+    env: process.env as Record<string, string | undefined>,
+    createTokenManager: createGitHubTokenManager,
+    getBotIdentity,
+    spawnSync: (cmd, args, opts) => {
+      const proc = Bun.spawnSync([cmd, ...args], {
+        stdio:
+          opts.stdio === "inherit"
+            ? ["inherit", "inherit", "inherit"]
+            : ["pipe", "pipe", "pipe"],
+        env: opts.env as Record<string, string>,
+      });
+      return { status: proc.exitCode };
+    },
+    // Single-installation path: `gh-token` only — `gh-token.d/` belongs to
+    // the installations manager (see module docstring).
+    writeToken: (token: string) => {
+      writeFileAtomic(tokenPath, token);
+    },
+    tokenPath,
+    credentialHelperPath: join(scriptsBin, "git-credential-shipwright.sh"),
+    installations,
+  };
+}

package/github-auth-startup.ts

@@ -0,0 +1,231 @@
+/**
+ * agent/src/runtime/github-auth-startup.ts
+ *
+ * Decision logic + live "already active" flag for (re)starting GitHub App
+ * auth once credentials are available — whether that happens at boot
+ * (entrypoint-main.ts's one-shot setupGitHubAuth() call, Step 5) or later,
+ * when index.ts's syncConfig() picks up GH_APP_ID / GH_APP_PRIVATE_KEY
+ * (plus the optional GH_APP_INSTALLATION_ID pin) saved to the admin DB after
+ * this agent-server process already started, or when an App installation
+ * appears later.
+ *
+ * Why this exists: entrypoint-main.ts spawns index.ts as a SEPARATE child
+ * process (spawnAgentServer) and just waits for it to exit — index.ts does
+ * not share in-memory state (e.g. a GitHubTokenManager instance) with
+ * entrypoint-main.ts's process. If a GitHub App is installed after the pod
+ * boots, entrypoint-main.ts's one-shot setupGitHubAuth() call already ran
+ * and found no credentials; index.ts's syncConfig() re-applies process.env
+ * every tick but had no hook to retry GitHub App auth setup in its own
+ * process — the agent stayed unable to authenticate as the App until a full
+ * pod restart. This module gives syncConfig() a single, shared, testable
+ * decision: "are credentials live now, and has GitHub App auth not already
+ * been set up successfully in this process? If so, set it up — exactly
+ * once."
+ *
+ * setupGitHubAuth() (setup-github-auth.ts) itself is NOT safely
+ * re-invokable: each call creates a brand-new GitHubTokenManager and calls
+ * startBackgroundRefresh() on it. A manager's startBackgroundRefresh() only
+ * stops ITS OWN prior interval — a second, independent manager from a
+ * second setupGitHubAuth() call has its own separate interval that the
+ * first manager's stopBackgroundRefresh() never touches, leaking a
+ * duplicate background refresh. The isActive() guard below is what must
+ * prevent a second call after a successful setup — setupGitHubAuth() itself
+ * does not protect against repeated invocation.
+ *
+ * Kept dependency-injected and I/O-free itself (matches the project's
+ * no-`mock.module()` isolation rule) — the real setupGitHubAuth() call is
+ * injected by the caller (index.ts), so this module's own tests use
+ * fakes/spies instead of a real GitHub App. Mirrors slack-startup.ts's
+ * ref/guard style for the "already active" flag and the start-in-flight
+ * guard so no module-scope mutable state leaks across test cases (each test
+ * constructs its own via createGitHubAuthActiveRef()/
+ * createGitHubAuthStartGuard()).
+ */
+
+import type { AgentReposRef } from "./agent-repos-ref.ts";
+import type { InstallationsSnapshot } from "./github-installations.ts";
+
+/**
+ * True iff the GitHub App id and private key are present. The installation
+ * id (GH_APP_INSTALLATION_ID) is an optional pin — without it, installations
+ * are discovered at setup time, so credentials alone don't guarantee setup
+ * activates (see setupGitHubAuth's boolean result).
+ */
+export function hasGitHubAppCredentials(
+  env: Record<string, string | undefined>,
+): boolean {
+  return Boolean(env.GH_APP_ID && env.GH_APP_PRIVATE_KEY);
+}
+
+/** The slice of GitHubInstallationsManager the config-sync tick needs. */
+interface ReconcilableInstallations {
+  reconcile(scopeOwners: string[] | null): Promise<void>;
+  /** Current installations (the real manager has it); used for the default owner. */
+  getState?(): InstallationsSnapshot;
+}
+
+interface GitHubInstallationsManagerRef {
+  /** The installations manager App auth activated with, or null if none. */
+  get(): ReconcilableInstallations | null;
+  set(manager: ReconcilableInstallations | null): void;
+}
+
+export function createGitHubInstallationsManagerRef(): GitHubInstallationsManagerRef {
+  let manager: ReconcilableInstallations | null = null;
+  return {
+    get: () => manager,
+    set: (next) => {
+      manager = next;
+    },
+  };
+}
+
+/**
+ * Process-wide installations manager ref — set by setupGitHubAuth() once App
+ * auth activates via the manager, read by index.ts's syncConfig() tick.
+ */
+export const githubInstallationsManagerRef: GitHubInstallationsManagerRef =
+  createGitHubInstallationsManagerRef();
+
+/**
+ * Unique lowercase repo owners the agent is scoped to, or null while scope
+ * has never synced — the installations manager treats null as pinned-only.
+ */
+export function scopeOwnersOf(
+  reposRef: Pick<AgentReposRef, "get" | "hasSynced">,
+): string[] | null {
+  if (!reposRef.hasSynced()) return null;
+  const owners = reposRef
+    .get()
+    .map((repo) => repo.split("/")[0]?.toLowerCase())
+    .filter((owner): owner is string => Boolean(owner));
+  return [...new Set(owners)];
+}
+
+/**
+ * Re-runs installation discovery/selection against the current repo scope.
+ * Returns false (no-op) when App auth hasn't activated via the manager.
+ */
+export async function reconcileGitHubInstallations(
+  managerRef: GitHubInstallationsManagerRef,
+  reposRef: Pick<AgentReposRef, "get" | "hasSynced">,
+): Promise<boolean> {
+  const manager = managerRef.get();
+  if (!manager) return false;
+  await manager.reconcile(scopeOwnersOf(reposRef));
+  return true;
+}
+
+export interface GitHubAuthActiveRef {
+  /** True once GitHub App auth has been set up successfully in this process. */
+  isActive(): boolean;
+  setActive(active: boolean): void;
+}
+
+/** Creates a new, independent "already active" ref defaulting to false. */
+export function createGitHubAuthActiveRef(): GitHubAuthActiveRef {
+  let active = false;
+  return {
+    isActive: (): boolean => active,
+    setActive: (next: boolean): void => {
+      active = next;
+    },
+  };
+}
+
+/**
+ * The process-wide "already active" ref used by index.ts's syncConfig()
+ * call site.
+ */
+export const githubAuthActiveRef: GitHubAuthActiveRef =
+  createGitHubAuthActiveRef();
+
+/**
+ * Guards startGitHubAuthIfPossible() against overlapping callers — e.g. two
+ * syncConfig() ticks racing because syncConfig() is dispatched via an
+ * unawaited setInterval. Kept as its own tiny ref (rather than a
+ * module-scope `let`) so tests can construct an independent, disposable
+ * guard instead of mutating shared state that would otherwise leak between
+ * test cases.
+ */
+interface GitHubAuthStartGuard {
+  isInFlight(): boolean;
+  set(inFlight: boolean): void;
+}
+
+export function createGitHubAuthStartGuard(): GitHubAuthStartGuard {
+  let inFlight = false;
+  return {
+    isInFlight: (): boolean => inFlight,
+    set: (next: boolean): void => {
+      inFlight = next;
+    },
+  };
+}
+
+/**
+ * The process-wide start-in-flight guard used by index.ts's syncConfig()
+ * call site. A single shared instance is required in production so
+ * overlapping ticks can't race each other; tests should construct their own
+ * via createGitHubAuthStartGuard() instead of reusing this singleton.
+ */
+const githubAuthStartGuard: GitHubAuthStartGuard = createGitHubAuthStartGuard();
+
+export interface StartGitHubAuthDeps {
+  /** Live process env, read at call time (not a static snapshot). */
+  env: Record<string, string | undefined>;
+  /** True once GitHub App auth has already been set up successfully (by any prior call in this process). */
+  isActive: () => boolean;
+  /** Records that setup succeeded so isActive() reflects it on the next call. */
+  markActive: () => void;
+  /**
+   * Performs the actual setup — real prod wiring or a test fake. Resolves
+   * true iff GitHub App auth activated; false (e.g. zero usable
+   * installations, PAT path) leaves it inactive so the next tick retries.
+   * Errors propagate.
+   */
+  setupGitHubAuth: () => Promise<boolean>;
+  /** Start-in-flight guard — defaults to the process-wide singleton; tests inject their own. */
+  guard?: GitHubAuthStartGuard;
+}
+
+/**
+ * Attempts to set up GitHub App auth if — and only if — credentials are
+ * complete right now AND setup hasn't already succeeded in this process.
+ * Safe to call on every syncConfig() tick: a no-op when credentials are
+ * still incomplete, and a no-op once a prior call already succeeded.
+ *
+ * Returns true iff this call ran setup AND App auth activated; false for
+ * every no-op path (incomplete credentials, already active, a racing call
+ * that lost the in-flight guard) and for a setup that did not activate (no
+ * pin and no usable installation yet) — that case is retried next tick.
+ *
+ * Errors from `setupGitHubAuth()` propagate to the caller (not swallowed
+ * here) so index.ts's call site can log a start failure distinctly from a
+ * config-bundle fetch/env-sync failure — see the call site in index.ts.
+ */
+export async function startGitHubAuthIfPossible(
+  deps: StartGitHubAuthDeps,
+): Promise<boolean> {
+  const guard = deps.guard ?? githubAuthStartGuard;
+
+  if (guard.isInFlight()) return false;
+  if (deps.isActive()) return false;
+  if (!hasGitHubAppCredentials(deps.env)) return false;
+
+  guard.set(true);
+  try {
+    // Re-check after acquiring the guard in case another call already
+    // succeeded between the check above and here — defense in depth on top
+    // of the guard itself (JS has no preemption between the isActive check
+    // and the set(true) above, so this branch is unreachable today, but
+    // keeps the invariant obvious even if that ordering ever changes).
+    if (deps.isActive()) return false;
+
+    if (!(await deps.setupGitHubAuth())) return false;
+    deps.markActive();
+    return true;
+  } finally {
+    guard.set(false);
+  }
+}

package/github-auth-startup.unit.test.ts

@@ -0,0 +1,325 @@
+/**
+ * agent/src/runtime/github-auth-startup.unit.test.ts
+ *
+ * Unit tests for startGitHubAuthIfPossible() and the "already active" ref —
+ * pure logic, no I/O. The real setupGitHubAuth() call is a fake/spy injected
+ * via StartGitHubAuthDeps; no real network, git, or `mock.module()` usage.
+ */
+
+import { describe, expect, it } from "bun:test";
+import { createAgentReposRef } from "./agent-repos-ref.ts";
+import {
+  createGitHubAuthActiveRef,
+  createGitHubAuthStartGuard,
+  createGitHubInstallationsManagerRef,
+  githubAuthActiveRef,
+  hasGitHubAppCredentials,
+  reconcileGitHubInstallations,
+  type StartGitHubAuthDeps,
+  scopeOwnersOf,
+  startGitHubAuthIfPossible,
+} from "./github-auth-startup.ts";
+
+const COMPLETE_ENV: Record<string, string | undefined> = {
+  GH_APP_ID: "12345",
+  GH_APP_INSTALLATION_ID: "67890",
+  GH_APP_PRIVATE_KEY:
+    "-----BEGIN PRIVATE KEY-----\nfake\n-----END PRIVATE KEY-----",
+};
+
+/**
+ * Builds a fresh, fully-independent set of fakes for one test case —
+ * mirrors production semantics (isActive flips true only after markActive)
+ * but with no real GitHub App I/O, and returns spy call counters for
+ * assertions.
+ */
+function buildFakeDeps(envOverrides?: Record<string, string | undefined>) {
+  const activeRef = createGitHubAuthActiveRef();
+  const guard = createGitHubAuthStartGuard();
+  const calls = { setupGitHubAuth: 0 };
+
+  const deps: StartGitHubAuthDeps = {
+    env: { ...COMPLETE_ENV, ...envOverrides },
+    isActive: activeRef.isActive,
+    markActive: () => activeRef.setActive(true),
+    setupGitHubAuth: async () => {
+      calls.setupGitHubAuth++;
+      return true;
+    },
+    guard,
+  };
+
+  return { deps, calls, activeRef, guard };
+}
+
+describe("hasGitHubAppCredentials", () => {
+  it("is true when all three GitHub App env vars are present", () => {
+    expect(hasGitHubAppCredentials(COMPLETE_ENV)).toBe(true);
+  });
+
+  it("is false when GH_APP_ID is missing", () => {
+    expect(
+      hasGitHubAppCredentials({ ...COMPLETE_ENV, GH_APP_ID: undefined }),
+    ).toBe(false);
+  });
+
+  it("is true when GH_APP_INSTALLATION_ID is missing (the installation id is an optional pin)", () => {
+    expect(
+      hasGitHubAppCredentials({
+        ...COMPLETE_ENV,
+        GH_APP_INSTALLATION_ID: undefined,
+      }),
+    ).toBe(true);
+  });
+
+  it("is false when GH_APP_PRIVATE_KEY is missing", () => {
+    expect(
+      hasGitHubAppCredentials({
+        ...COMPLETE_ENV,
+        GH_APP_PRIVATE_KEY: undefined,
+      }),
+    ).toBe(false);
+  });
+
+  it("is false when all three are missing", () => {
+    expect(
+      hasGitHubAppCredentials({
+        GH_APP_ID: undefined,
+        GH_APP_INSTALLATION_ID: undefined,
+        GH_APP_PRIVATE_KEY: undefined,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe("startGitHubAuthIfPossible", () => {
+  it("credentials complete on a later tick (not boot) triggers exactly one GitHub auth setup", async () => {
+    const { deps, calls, activeRef } = buildFakeDeps();
+
+    const started = await startGitHubAuthIfPossible(deps);
+
+    expect(started).toBe(true);
+    expect(calls.setupGitHubAuth).toBe(1);
+    expect(activeRef.isActive()).toBe(true);
+  });
+
+  it("a later tick with GitHub auth already active does not re-trigger setup (regression: no duplicate refresh interval)", async () => {
+    const { deps, calls } = buildFakeDeps();
+
+    const first = await startGitHubAuthIfPossible(deps);
+    const second = await startGitHubAuthIfPossible(deps);
+
+    expect(first).toBe(true);
+    expect(second).toBe(false);
+    // Critical: setupGitHubAuth must be called exactly once across both
+    // ticks — a second call would create a second GitHubTokenManager with
+    // its own independent background-refresh interval that the first
+    // manager's stopBackgroundRefresh() never touches (see module docstring).
+    expect(calls.setupGitHubAuth).toBe(1);
+  });
+
+  it("a tick with incomplete credentials (missing GH_APP_ID) does not attempt setup", async () => {
+    const { deps, calls } = buildFakeDeps({ GH_APP_ID: undefined });
+
+    const started = await startGitHubAuthIfPossible(deps);
+
+    expect(started).toBe(false);
+    expect(calls.setupGitHubAuth).toBe(0);
+  });
+
+  it("a tick with App id + key but no GH_APP_INSTALLATION_ID pin attempts setup (discovery may find installations)", async () => {
+    const { deps, calls } = buildFakeDeps({
+      GH_APP_INSTALLATION_ID: undefined,
+    });
+
+    const started = await startGitHubAuthIfPossible(deps);
+
+    expect(started).toBe(true);
+    expect(calls.setupGitHubAuth).toBe(1);
+  });
+
+  it("setup that does not activate App auth (e.g. zero installations) is not marked active and is retried next tick", async () => {
+    const { deps, calls, activeRef, guard } = buildFakeDeps({
+      GH_APP_INSTALLATION_ID: undefined,
+    });
+    deps.setupGitHubAuth = async () => {
+      calls.setupGitHubAuth++;
+      return false;
+    };
+
+    expect(await startGitHubAuthIfPossible(deps)).toBe(false);
+    expect(activeRef.isActive()).toBe(false);
+    expect(guard.isInFlight()).toBe(false);
+
+    expect(await startGitHubAuthIfPossible(deps)).toBe(false);
+    expect(calls.setupGitHubAuth).toBe(2);
+
+    // Installations appear later: setup activates exactly once, then stops.
+    deps.setupGitHubAuth = async () => {
+      calls.setupGitHubAuth++;
+      return true;
+    };
+    expect(await startGitHubAuthIfPossible(deps)).toBe(true);
+    expect(await startGitHubAuthIfPossible(deps)).toBe(false);
+    expect(calls.setupGitHubAuth).toBe(3);
+    expect(activeRef.isActive()).toBe(true);
+  });
+
+  it("a tick with incomplete credentials (missing GH_APP_PRIVATE_KEY) does not attempt setup", async () => {
+    const { deps, calls } = buildFakeDeps({ GH_APP_PRIVATE_KEY: undefined });
+
+    const started = await startGitHubAuthIfPossible(deps);
+
+    expect(started).toBe(false);
+    expect(calls.setupGitHubAuth).toBe(0);
+  });
+
+  it("a tick with all credentials missing does not attempt setup", async () => {
+    const { deps, calls } = buildFakeDeps({
+      GH_APP_ID: undefined,
+      GH_APP_INSTALLATION_ID: undefined,
+      GH_APP_PRIVATE_KEY: undefined,
+    });
+
+    const started = await startGitHubAuthIfPossible(deps);
+
+    expect(started).toBe(false);
+    expect(calls.setupGitHubAuth).toBe(0);
+  });
+
+  it("overlapping/concurrent calls (two ticks racing before the first setup resolves) do not double-setup", async () => {
+    const { deps, calls } = buildFakeDeps();
+
+    let releaseSetup: () => void = () => {};
+    const setupGate = new Promise<void>((resolve) => {
+      releaseSetup = resolve;
+    });
+    deps.setupGitHubAuth = async () => {
+      await setupGate;
+      calls.setupGitHubAuth++;
+      return true;
+    };
+
+    const firstCall = startGitHubAuthIfPossible(deps);
+    const secondCall = startGitHubAuthIfPossible(deps);
+
+    releaseSetup();
+    const [first, second] = await Promise.all([firstCall, secondCall]);
+
+    expect([first, second].filter(Boolean)).toHaveLength(1);
+    expect(calls.setupGitHubAuth).toBe(1);
+  });
+
+  it("errors from setupGitHubAuth propagate to the caller rather than being swallowed", async () => {
+    const { deps } = buildFakeDeps();
+    deps.setupGitHubAuth = async () => {
+      throw new Error("boom");
+    };
+
+    await expect(startGitHubAuthIfPossible(deps)).rejects.toThrow("boom");
+  });
+
+  it("errors from setupGitHubAuth do not mark GitHub auth active, so a subsequent retry can proceed", async () => {
+    const { deps, calls, activeRef, guard } = buildFakeDeps();
+    deps.setupGitHubAuth = async () => {
+      throw new Error("boom");
+    };
+
+    await expect(startGitHubAuthIfPossible(deps)).rejects.toThrow("boom");
+    expect(activeRef.isActive()).toBe(false);
+    expect(guard.isInFlight()).toBe(false);
+
+    // Retry with working deps — should succeed since setup never actually completed.
+    deps.setupGitHubAuth = async () => {
+      calls.setupGitHubAuth++;
+      return true;
+    };
+    const started = await startGitHubAuthIfPossible(deps);
+    expect(started).toBe(true);
+    expect(activeRef.isActive()).toBe(true);
+  });
+});
+
+describe("GitHubAuthActiveRef", () => {
+  it("createGitHubAuthActiveRef() defaults to inactive", () => {
+    const ref = createGitHubAuthActiveRef();
+    expect(ref.isActive()).toBe(false);
+  });
+
+  it("setActive(true) is reflected by the next isActive()", () => {
+    const ref = createGitHubAuthActiveRef();
+    ref.setActive(true);
+    expect(ref.isActive()).toBe(true);
+  });
+
+  it("multiple independent ref instances don't share state", () => {
+    const refA = createGitHubAuthActiveRef();
+    const refB = createGitHubAuthActiveRef();
+
+    refA.setActive(true);
+
+    expect(refA.isActive()).toBe(true);
+    expect(refB.isActive()).toBe(false);
+  });
+});
+
+describe("githubAuthActiveRef (process-wide singleton)", () => {
+  it("is a working ref, independent of createGitHubAuthActiveRef() instances", () => {
+    const independent = createGitHubAuthActiveRef();
+    independent.setActive(true);
+
+    expect(githubAuthActiveRef.isActive()).toBe(false);
+    githubAuthActiveRef.setActive(true);
+    expect(githubAuthActiveRef.isActive()).toBe(true);
+    expect(independent.isActive()).toBe(true);
+
+    // Reset the process-wide singleton so this test doesn't leak state into siblings.
+    githubAuthActiveRef.setActive(false);
+  });
+});
+
+describe("scopeOwnersOf", () => {
+  it("is null while scope has never synced (pinned-only)", () => {
+    expect(scopeOwnersOf(createAgentReposRef())).toBeNull();
+  });
+
+  it("returns the unique, lowercased owners of the synced repos", () => {
+    const ref = createAgentReposRef();
+    ref.set(["Acme/api", "acme/web", "Other/tool"]);
+    expect(scopeOwnersOf(ref)).toEqual(["acme", "other"]);
+  });
+
+  it("is an empty list (not null) when synced to an empty scope", () => {
+    const ref = createAgentReposRef();
+    ref.set([]);
+    expect(scopeOwnersOf(ref)).toEqual([]);
+  });
+});
+
+describe("reconcileGitHubInstallations", () => {
+  it("is a no-op when no installations manager is active", async () => {
+    const managerRef = createGitHubInstallationsManagerRef();
+    const reposRef = createAgentReposRef();
+    reposRef.set(["acme/api"]);
+    await expect(
+      reconcileGitHubInstallations(managerRef, reposRef),
+    ).resolves.toBe(false);
+  });
+
+  it("reconciles the active manager against the current scope owners", async () => {
+    const managerRef = createGitHubInstallationsManagerRef();
+    const reposRef = createAgentReposRef();
+    const seen: (string[] | null)[] = [];
+    managerRef.set({
+      reconcile: async (owners) => {
+        seen.push(owners);
+      },
+    });
+
+    expect(await reconcileGitHubInstallations(managerRef, reposRef)).toBe(true);
+    reposRef.set(["Acme/api"]);
+    expect(await reconcileGitHubInstallations(managerRef, reposRef)).toBe(true);
+
+    expect(seen).toEqual([null, ["acme"]]);
+  });
+});