buildhive-agent 1.0.0-beta.10 → 1.0.0-beta.11

package/dist/auth/joinCommand.d.ts

@@ -2,15 +2,43 @@
  * `buildhive-agent join <token>` implementation.
  *
  * Row 17c — zero-GH developer onboarding (Wave A).
+ * Group B / S-1 — `join` now auto-installs the macOS LaunchAgent so the
+ * dev never has to think about persistence (two-commands install promise).
  * Design: docs/ops/zero-github-dev-onboarding-design-2026-05-17.md §3.1
+ *         docs/ops/buildhive-reinit-fix-plan-2026-05-28.html §Group B (S-1)
  *
  * Exit-code contract (consumed by row 17b's `start` subcommand):
  *   0 — success, JWT stored in OS keyring
  *   1 — token rejected by backend (invalid / expired / consumed / revoked)
  *   2 — network error (cannot reach BuildHive)
  *   3 — keyring write failed
+ *
+ * Note: a LaunchAgent install failure does NOT change the exit code. The
+ * agent is fully enrolled at that point; the developer can re-run
+ * `buildhive-agent service:install` themselves and still pick up jobs
+ * from the foreground (`buildhive-agent start`) in the meantime.
  */
 import { AgentEnrollmentKeyringStore } from './agentEnrollmentKeyringStore.js';
+import type { ServicePaths } from '../service/paths.js';
+/**
+ * Service-install dependency surface — exposed for test injection so we
+ * don't reach into the real launchctl binary from unit tests.
+ *
+ * Mirrors the public shape of {@link installService} from
+ * `../service/serviceInstaller.ts`. When `serviceInstaller` is omitted,
+ * the production import is used.
+ */
+export interface ServiceInstallerInjection {
+    readonly installService: (opts: {
+        mode: 'user' | 'system';
+        cliEntryPath: string;
+        label?: string;
+        homeDir?: string;
+    }) => Promise<{
+        paths: ServicePaths;
+        bootstrapStdout: string;
+    }>;
+}
 export interface JoinOptions {
     readonly token: string;
     readonly platformUrl: string;
@@ -18,10 +46,39 @@ export interface JoinOptions {
     readonly store?: ConstructorParameters<typeof AgentEnrollmentKeyringStore>[0];
     /** Override fetch for tests. */
     readonly fetchFn?: typeof fetch;
+    /**
+     * S-1: opt-out of the post-enroll LaunchAgent install (e.g. when the
+     * caller is running the agent in a container or build-farm context that
+     * manages its own supervision). Default: false → install runs.
+     */
+    readonly skipServiceInstall?: boolean;
+    /**
+     * Dependency injection for tests (avoids real launchctl bootstrap).
+     * When omitted, the real `service/serviceInstaller.installService` is
+     * used via dynamic import.
+     */
+    readonly serviceInstaller?: ServiceInstallerInjection;
+    /**
+     * Override platform detection — tests set this to `'darwin'` regardless
+     * of the host OS so the LaunchAgent install path runs deterministically.
+     */
+    readonly platformOverride?: NodeJS.Platform;
+    /**
+     * Override the resolved CLI entry path. Tests set this so the service
+     * installer doesn't try to realpath `process.argv[1]` (which points at
+     * the test runner, not at dist/cli.js).
+     */
+    readonly cliEntryPathOverride?: string;
 }
 export interface JoinResult {
     readonly exitCode: 0 | 1 | 2 | 3;
     readonly message?: string;
+    /**
+     * S-1: whether the post-enroll LaunchAgent install was attempted and
+     * succeeded. Surfaced in the return for test assertions; the exit code
+     * is unchanged on install failure (the agent is still enrolled).
+     */
+    readonly serviceInstalled?: boolean;
 }
 /**
  * The main join logic. Exported for unit testing.

package/dist/auth/joinCommand.js

@@ -2,16 +2,24 @@
  * `buildhive-agent join <token>` implementation.
  *
  * Row 17c — zero-GH developer onboarding (Wave A).
+ * Group B / S-1 — `join` now auto-installs the macOS LaunchAgent so the
+ * dev never has to think about persistence (two-commands install promise).
  * Design: docs/ops/zero-github-dev-onboarding-design-2026-05-17.md §3.1
+ *         docs/ops/buildhive-reinit-fix-plan-2026-05-28.html §Group B (S-1)
  *
  * Exit-code contract (consumed by row 17b's `start` subcommand):
  *   0 — success, JWT stored in OS keyring
  *   1 — token rejected by backend (invalid / expired / consumed / revoked)
  *   2 — network error (cannot reach BuildHive)
  *   3 — keyring write failed
+ *
+ * Note: a LaunchAgent install failure does NOT change the exit code. The
+ * agent is fully enrolled at that point; the developer can re-run
+ * `buildhive-agent service:install` themselves and still pick up jobs
+ * from the foreground (`buildhive-agent start`) in the meantime.
  */
 import os from 'os';
-import { readFileSync } from 'fs';
+import { readFileSync, realpathSync } from 'fs';
 import { join, dirname } from 'path';
 import { fileURLToPath } from 'node:url';
 import { AgentEnrollmentKeyringStore } from './agentEnrollmentKeyringStore.js';
@@ -185,12 +193,90 @@ export async function runJoin(opts) {
         }
         return { exitCode: 3, message: `Could not store agent credentials in OS keyring: ${err instanceof Error ? err.message : err}` };
     }
-    // 8. Print success message.
+    // 8. Print enrollment success.
     const agentIdShort = agentId.slice(0, 8);
     console.log(`✓ Agent enrolled in team "${teamName}" as agent ${agentIdShort}…`);
     console.log(`✓ JWT stored in OS keyring (expires ${expiresDate}).`);
-    console.log('Run `buildhive-agent start` to begin picking up workflow jobs.');
-    return { exitCode: 0 };
+    // 9. S-1: Auto-install LaunchAgent so the dev never thinks about persistence.
+    //    Idempotent — re-running `join` cleanly upgrades the plist (the underlying
+    //    installer uses an atomic tmp-file → rename).
+    const serviceInstalled = await maybeInstallLaunchAgent(opts);
+    if (serviceInstalled) {
+        console.log('✓ Agent installed and will auto-start on every login. ' +
+            'Inspect logs with `buildhive-agent logs`.');
+    }
+    else {
+        // Either non-macOS, opt-out, or install failed. Fall back to the
+        // foreground-start guidance the user can still execute.
+        console.log('Run `buildhive-agent start` to begin picking up workflow jobs.');
+    }
+    return { exitCode: 0, serviceInstalled };
+}
+/**
+ * S-1 helper: install the macOS LaunchAgent after a successful enrollment.
+ *
+ * Returns true if the service was installed (and is loaded into launchd),
+ * false otherwise. Never throws — a service-install failure is non-fatal
+ * for the join itself (the user can still run `buildhive-agent start`
+ * in the foreground while diagnosing).
+ */
+async function maybeInstallLaunchAgent(opts) {
+    if (opts.skipServiceInstall === true) {
+        return false;
+    }
+    const platform = opts.platformOverride ?? process.platform;
+    if (platform !== 'darwin') {
+        // LaunchAgent is macOS-only. Linux/Windows fall through to the
+        // foreground-start path without an error.
+        return false;
+    }
+    // Resolve the CLI entry path so launchd's ProgramArguments points at
+    // an absolute path that survives PATH changes (e.g. nvm version switch).
+    let cliEntryPath;
+    try {
+        cliEntryPath = opts.cliEntryPathOverride ?? realpathSync(process.argv[1] ?? '');
+    }
+    catch {
+        console.error('[join] Could not resolve the CLI entry path for service install. ' +
+            'Run `buildhive-agent service:install --cli-entry <abs-path>` manually.');
+        return false;
+    }
+    if (!cliEntryPath || !cliEntryPath.startsWith('/')) {
+        console.error('[join] Resolved CLI entry path is not absolute; skipping service install. ' +
+            'Run `buildhive-agent service:install --cli-entry <abs-path>` manually.');
+        return false;
+    }
+    // Dynamic import so test environments without the service files (or
+    // running on platforms where launchctl isn't available) don't pay the
+    // load cost. Tests inject a fake via opts.serviceInstaller.
+    let installFn;
+    if (opts.serviceInstaller) {
+        installFn = opts.serviceInstaller.installService;
+    }
+    else {
+        try {
+            const mod = await import('../service/serviceInstaller.js');
+            installFn = mod.installService;
+        }
+        catch (err) {
+            console.error('[join] Could not load service installer:', err instanceof Error ? err.message : err);
+            return false;
+        }
+    }
+    try {
+        await installFn({ mode: 'user', cliEntryPath });
+        return true;
+    }
+    catch (err) {
+        // Already-loaded-service is a benign case — installService's atomic
+        // tmp-file-rename + launchctl bootstrap is idempotent, but a launchctl
+        // bootstrap on an already-loaded service may emit a non-zero exit. Surface
+        // the error to the user but do not change the enrollment exit code.
+        console.error('[join] LaunchAgent install failed (agent is still enrolled — JWT is in the keyring):', err instanceof Error ? err.message : err);
+        console.error('[join] You can finish setup manually with `buildhive-agent service:install` ' +
+            'or run the agent in the foreground via `buildhive-agent start`.');
+        return false;
+    }
 }
 /** Pull tenant_id from JWT payload without signature verification. */
 function extractTenantId(jwtToken) {

package/dist/cli.js

@@ -160,8 +160,10 @@ program
     .command('start')
     .description('Start the BuildHive agent (registers as a self-hosted GitHub Actions runner)')
     .option('-c, --config <path>', 'Configuration file path')
-    .option('--owner <owner>', 'GitHub org or user that owns the repo (overrides config / env)')
-    .option('--repo <repo>', 'GitHub repo name to register the runner for (overrides config / env)')
+    // Group B / RI-08: --owner + --repo retained as power-user overrides only;
+    // the canonical zero-GH path resolves them server-side via /api/runners/my-repos.
+    .option('--owner <owner>', 'Power-user override: GitHub org/user (default: resolved from BuildHive enrollment)')
+    .option('--repo <repo>', 'Power-user override: GitHub repo (default: resolved from BuildHive enrollment)')
     .option('-j, --jobs <n>', 'Number of concurrent ephemeral runner slots (default: 1, or maxConcurrentJobs from config; max 64)', (v) => {
     const n = parseInt(v, 10);
     if (isNaN(n) || n < 1)

package/dist/doctor/index.d.ts

@@ -1,22 +1,40 @@
 /**
- * doctor/index.ts — Sprint B B4 (worker-B4)
+ * doctor/index.ts — Sprint B B4 (worker-B4).
  *
- * Sequential orchestrator + ANSI formatter for the 12 diagnostic checks.
+ * Sequential orchestrator + ANSI formatter for the diagnostic checks.
  * Sequential by design — output ordering matters more than wall-clock speed.
  * No `chalk` dep; ANSI escape codes inline (NO_COLOR / non-TTY disables).
+ *
+ * Group B / RI-04 (expanded) — 2026-05-28: dropped the 5 stale pre-pivot
+ * checks (#5 config file, #6 config JSON valid, #7 apiKey format,
+ * #8 server URL reachable from config, #9 server-health-from-config,
+ * #10 api key valid via heartbeat) and replaced them with 4 runner-era
+ * checks that match the post-pivot model (join → keyring → my-repos).
+ * All "Fix" strings reference `buildhive-agent join` / `/admin/github`;
+ * never `init`, `register`, or `--api-key`.
  */
 import { CheckResult, CheckDeps } from './runChecks.js';
 import { CacheCheckDeps } from './cacheCheck.js';
+import { RunnerCheckDeps } from './runnerChecks.js';
 /**
- * Run all 17 checks. Returns results (in fixed order) + exit code:
+ * Run all 15 checks. Returns results (in fixed order) + exit code:
  * 0 if every check passed (warnings are non-fatal advisories), 1 if any failed.
  *
- * @param cacheDeps - Optional cache-check deps. When omitted, check 17 uses a
- *   default disabled-state dep so the check is a no-op advisory rather than
- *   requiring a fully initialised CacheManager at doctor startup time. Callers
- *   that have a loaded AgentConfig should pass `defaultCacheCheckDeps(config)`.
+ * Check ordering (Group B / RI-04):
+ *   1-4  Node + Docker (host prerequisites)
+ *   5-8  Runner-era identity: keyring JWT, identity claims, platformUrl
+ *        reachable, /api/runners/my-repos returns ≥1 repo
+ *   9-10 Disk + workspace
+ *   11-14 launchd service state (post-join)
+ *   15   Optional cache opt-in
+ *
+ * @param cacheDeps - Optional cache-check deps. When omitted, the cache check
+ *   uses a default disabled-state dep so it's a no-op advisory rather than
+ *   requiring a fully initialised CacheManager at doctor startup time.
+ * @param runnerDeps - Optional runner-era check deps. Tests inject fakes to
+ *   avoid touching the real OS keyring + outbound HTTP.
  */
-export declare function runDoctor(deps?: CheckDeps, out?: (line: string) => void, cacheDeps?: CacheCheckDeps): Promise<{
+export declare function runDoctor(deps?: CheckDeps, out?: (line: string) => void, cacheDeps?: CacheCheckDeps, runnerDeps?: RunnerCheckDeps): Promise<{
     results: CheckResult[];
     exitCode: number;
 }>;

package/dist/doctor/index.js

@@ -1,13 +1,22 @@
 /**
- * doctor/index.ts — Sprint B B4 (worker-B4)
+ * doctor/index.ts — Sprint B B4 (worker-B4).
  *
- * Sequential orchestrator + ANSI formatter for the 12 diagnostic checks.
+ * Sequential orchestrator + ANSI formatter for the diagnostic checks.
  * Sequential by design — output ordering matters more than wall-clock speed.
  * No `chalk` dep; ANSI escape codes inline (NO_COLOR / non-TTY disables).
+ *
+ * Group B / RI-04 (expanded) — 2026-05-28: dropped the 5 stale pre-pivot
+ * checks (#5 config file, #6 config JSON valid, #7 apiKey format,
+ * #8 server URL reachable from config, #9 server-health-from-config,
+ * #10 api key valid via heartbeat) and replaced them with 4 runner-era
+ * checks that match the post-pivot model (join → keyring → my-repos).
+ * All "Fix" strings reference `buildhive-agent join` / `/admin/github`;
+ * never `init`, `register`, or `--api-key`.
  */
-import { checkNodeVersion, checkDockerInstalled, checkDockerDaemon, checkDockerSocketAccess, checkConfigFile, checkConfigValid, checkApiKeyFormat, checkServerReachable, checkServerHealthShape, checkApiKeyValid, checkDiskSpace, checkWorkspaceWritable, checkServicePlistInstalled, checkServicePlistValid, checkServiceLoaded, checkServiceRunning, defaultDeps, } from './runChecks.js';
+import { checkNodeVersion, checkDockerInstalled, checkDockerDaemon, checkDockerSocketAccess, checkDiskSpace, checkWorkspaceWritable, checkServicePlistInstalled, checkServicePlistValid, checkServiceLoaded, checkServiceRunning, defaultDeps, } from './runChecks.js';
 import { checkCacheEnabled } from './cacheCheck.js';
-const TOTAL = 17;
+import { checkKeyringPresent, checkKeyringClaims, checkPlatformUrlReachable, checkEnrolledRepos, defaultRunnerCheckDeps, } from './runnerChecks.js';
+const TOTAL = 15;
 const useColor = () => !process.env.NO_COLOR && Boolean(process.stdout.isTTY);
 const wrap = (code, s) => useColor() ? `\x1b[${code}m${s}\x1b[0m` : s;
 const green = (s) => wrap('32', s);
@@ -38,7 +47,7 @@ const safeAsync = async (fn) => {
 };
 /** Like `safe` but for the launchd-loaded check, which returns
  * `{result, printOutput}`. On unexpected throw we synthesize a fail row +
- * `loaded:false` so check 16 chains correctly. */
+ * `loaded:false` so the running-state check chains correctly. */
 const safeLoaded = (fn) => {
     try {
         return fn();
@@ -51,48 +60,62 @@ const safeLoaded = (fn) => {
     }
 };
 /**
- * Run all 17 checks. Returns results (in fixed order) + exit code:
+ * Run all 15 checks. Returns results (in fixed order) + exit code:
  * 0 if every check passed (warnings are non-fatal advisories), 1 if any failed.
  *
- * @param cacheDeps - Optional cache-check deps. When omitted, check 17 uses a
- *   default disabled-state dep so the check is a no-op advisory rather than
- *   requiring a fully initialised CacheManager at doctor startup time. Callers
- *   that have a loaded AgentConfig should pass `defaultCacheCheckDeps(config)`.
+ * Check ordering (Group B / RI-04):
+ *   1-4  Node + Docker (host prerequisites)
+ *   5-8  Runner-era identity: keyring JWT, identity claims, platformUrl
+ *        reachable, /api/runners/my-repos returns ≥1 repo
+ *   9-10 Disk + workspace
+ *   11-14 launchd service state (post-join)
+ *   15   Optional cache opt-in
+ *
+ * @param cacheDeps - Optional cache-check deps. When omitted, the cache check
+ *   uses a default disabled-state dep so it's a no-op advisory rather than
+ *   requiring a fully initialised CacheManager at doctor startup time.
+ * @param runnerDeps - Optional runner-era check deps. Tests inject fakes to
+ *   avoid touching the real OS keyring + outbound HTTP.
  */
-export async function runDoctor(deps = defaultDeps(), out = (line) => process.stdout.write(line + '\n'), cacheDeps) {
+export async function runDoctor(deps = defaultDeps(), out = (line) => process.stdout.write(line + '\n'), cacheDeps, runnerDeps) {
     out(bold('Running BuildHive agent diagnostics...\n'));
     const results = [];
+    // 1-4 host prerequisites
     results.push(safe(() => checkNodeVersion(deps)));
     results.push(safe(() => checkDockerInstalled(deps)));
     results.push(safe(() => checkDockerDaemon(deps)));
     results.push(safe(() => checkDockerSocketAccess(deps)));
-    results.push(await safeAsync(() => checkConfigFile(deps)));
-    // Check 6 returns parsed payload — thread it into deps.config so checks
-    // 7-10 see it without re-reading the file.
-    let v;
+    // 5-8 runner-era identity (Group B / RI-04)
+    // Check 5 returns the keyring state — thread it into checks 6-8 so we
+    // don't re-read the keyring per check (matches the orchestrator's
+    // 6→7-10 config-threading pattern from before the rewrite).
+    const effectiveRunnerDeps = runnerDeps ?? defaultRunnerCheckDeps();
+    let keyring;
     try {
-        v = await checkConfigValid(deps);
+        keyring = await checkKeyringPresent(effectiveRunnerDeps);
     }
     catch (err) {
-        v = { result: errResult('Config valid JSON', err) };
+        keyring = {
+            result: errResult('Agent enrollment JWT (keyring)', err),
+            state: { jwt: null, platformUrl: null, agentId: null, tenantId: null },
+        };
     }
-    results.push(v.result);
-    if (v.parsed)
-        deps.config = v.parsed;
-    results.push(safe(() => checkApiKeyFormat(deps.config)));
-    results.push(await safeAsync(() => checkServerReachable(deps)));
-    results.push(await safeAsync(() => checkServerHealthShape(deps)));
-    results.push(await safeAsync(() => checkApiKeyValid(deps)));
+    results.push(keyring.result);
+    results.push(safe(() => checkKeyringClaims(keyring.state)));
+    results.push(await safeAsync(() => checkPlatformUrlReachable(keyring.state, effectiveRunnerDeps)));
+    results.push(await safeAsync(() => checkEnrolledRepos(keyring.state, effectiveRunnerDeps)));
+    // 9-10 disk + workspace
     results.push(await safeAsync(() => checkDiskSpace(deps)));
     results.push(await safeAsync(() => checkWorkspaceWritable(deps)));
-    // 13-16: launchd service state. Check 15 emits the `launchctl print` stdout
-    // which check 16 parses — same threading pattern as 6→7-10 for config.
+    // 11-14 launchd service state (post-join — `join` auto-installs the
+    // service per S-1, so a green run-state row is the expected steady
+    // state on macOS).
     results.push(await safeAsync(() => checkServicePlistInstalled(deps)));
     results.push(await safeAsync(() => checkServicePlistValid(deps)));
     const loaded = safeLoaded(() => checkServiceLoaded(deps));
     results.push(loaded.result);
     results.push(safe(() => checkServiceRunning(deps, loaded.printOutput)));
-    // 17: on-device build cache opt-in state (Q7 touchpoint #2 — doctor banner)
+    // 15 on-device build cache opt-in state (Q7 touchpoint #2 — doctor banner)
     const effectiveCacheDeps = cacheDeps ?? {
         enabled: false,
         getStats: async () => ({ totalEntries: 0, totalSizeBytes: 0, maxSizeBytes: 0, hitRate: 0, totalHits: 0, totalMisses: 0 }),
@@ -100,7 +123,7 @@ export async function runDoctor(deps = defaultDeps(), out = (line) => process.st
     };
     results.push(await safeAsync(() => checkCacheEnabled(effectiveCacheDeps)));
     results.forEach((r, i) => {
-        out(`[${i + 1}/${TOTAL}] ${r.name.padEnd(30, ' ')} ${symbol(r.status)} ${r.message}`);
+        out(`[${i + 1}/${TOTAL}] ${r.name.padEnd(38, ' ')} ${symbol(r.status)} ${r.message}`);
         if (r.fix && r.status !== 'pass')
             out(`       ${dim('Fix: ' + r.fix)}`);
     });

package/dist/doctor/runChecks.d.ts

@@ -35,29 +35,13 @@ export interface CheckDeps {
     platform: NodeJS.Platform;
     groupsCmd: () => string;
     homedir: string;
-    /** Parsed payload from check 6 — threaded into checks 7-10 by the orchestrator. */
-    config?: {
-        apiKey?: unknown;
-        serverUrl?: unknown;
-        platformUrl?: unknown;
-    };
 }
-export declare const DEFAULT_CONFIG_PATH: (homedir: string) => string;
 export declare const DEFAULT_WORKSPACE_PATH: (homedir: string) => string;
 export declare function defaultDeps(): CheckDeps;
 export declare function checkNodeVersion(deps: Pick<CheckDeps, 'nodeVersion'>): CheckResult;
 export declare function checkDockerInstalled(deps: Pick<CheckDeps, 'exec'>): CheckResult;
 export declare function checkDockerDaemon(deps: Pick<CheckDeps, 'exec'>): CheckResult;
 export declare function checkDockerSocketAccess(deps: Pick<CheckDeps, 'platform' | 'groupsCmd'>): CheckResult;
-export declare function checkConfigFile(deps: Pick<CheckDeps, 'fileExists' | 'homedir'>): Promise<CheckResult>;
-export declare function checkConfigValid(deps: Pick<CheckDeps, 'readFile' | 'fileExists' | 'homedir'>): Promise<{
-    result: CheckResult;
-    parsed?: Record<string, unknown>;
-}>;
-export declare function checkApiKeyFormat(config: CheckDeps['config']): CheckResult;
-export declare function checkServerReachable(deps: Pick<CheckDeps, 'fetcher' | 'config'>): Promise<CheckResult>;
-export declare function checkServerHealthShape(deps: Pick<CheckDeps, 'fetcher' | 'config'>): Promise<CheckResult>;
-export declare function checkApiKeyValid(deps: Pick<CheckDeps, 'fetcher' | 'config'>): Promise<CheckResult>;
 export declare function checkDiskSpace(deps: Pick<CheckDeps, 'diskFreeBytes' | 'homedir'>): Promise<CheckResult>;
 export declare function checkWorkspaceWritable(deps: Pick<CheckDeps, 'mkdir' | 'writeFile' | 'unlink' | 'homedir'>): Promise<CheckResult>;
 export declare function checkServicePlistInstalled(deps: Pick<CheckDeps, 'fileExists' | 'platform' | 'homedir'>): Promise<CheckResult>;

package/dist/doctor/runChecks.js

@@ -14,7 +14,9 @@ import { execSync } from 'child_process';
 import { join } from 'path';
 import os from 'os';
 import { AGENT_LABEL, getServicePaths } from '../service/paths.js';
-export const DEFAULT_CONFIG_PATH = (homedir) => join(homedir, '.buildhive', 'buildhive-agent.json');
+// Group B / RI-04: DEFAULT_CONFIG_PATH was the home of the legacy
+// `~/.buildhive/buildhive-agent.json` file. The runner-era stores
+// credentials in the OS keyring instead — keep only WORKSPACE_PATH.
 export const DEFAULT_WORKSPACE_PATH = (homedir) => join(homedir, '.buildhive', 'workspaces');
 export function defaultDeps() {
     return {
@@ -109,167 +111,14 @@ export function checkDockerSocketAccess(deps) {
         };
     }
 }
-// 5: config file exists
-export async function checkConfigFile(deps) {
-    const path = DEFAULT_CONFIG_PATH(deps.homedir);
-    if (await deps.fileExists(path)) {
-        return { name: 'Config file', status: 'pass', message: `Found at ${path}` };
-    }
-    return {
-        name: 'Config file', status: 'fail',
-        message: `Not found at ${path}`,
-        fix: 'Run `buildhive-agent init` first',
-    };
-}
-// 6: parseable JSON. Returns parsed payload — orchestrator threads it into
-// CheckDeps.config so checks 7-10 don't re-read the file.
-export async function checkConfigValid(deps) {
-    const path = DEFAULT_CONFIG_PATH(deps.homedir);
-    if (!(await deps.fileExists(path))) {
-        return { result: {
-                name: 'Config valid JSON', status: 'fail',
-                message: 'Config file missing (see previous check)',
-                fix: 'Run `buildhive-agent init` first',
-            } };
-    }
-    try {
-        const parsed = JSON.parse(await deps.readFile(path));
-        return { result: { name: 'Config valid JSON', status: 'pass', message: 'Parses cleanly' }, parsed };
-    }
-    catch (err) {
-        return { result: {
-                name: 'Config valid JSON', status: 'fail',
-                message: `Invalid JSON: ${errMsg(err).slice(0, 80)}`,
-                fix: 'Re-run `buildhive-agent init --force`',
-            } };
-    }
-}
-// 7: API key shape — bh_api_<hex>. Loose so server-side prefix tweaks don't
-// make the doctor cry wolf.
-export function checkApiKeyFormat(config) {
-    const key = typeof config?.apiKey === 'string' ? config.apiKey : '';
-    const keyFix = 'Recreate API key in dashboard /admin/keys, then `buildhive-agent init --force --api-key <new>`';
-    if (!key) {
-        return { name: 'API key format', status: 'fail', message: 'apiKey field missing or empty', fix: keyFix };
-    }
-    if (!/^bh_api_[a-f0-9]{16,}$/i.test(key)) {
-        return {
-            name: 'API key format', status: 'fail',
-            message: `apiKey doesn't match bh_api_<hex> (got ${key.slice(0, 12)}…)`,
-            fix: keyFix,
-        };
-    }
-    return { name: 'API key format', status: 'pass', message: `bh_api_…${key.slice(-4)}` };
-}
-function getServerUrl(config) {
-    for (const c of [config?.platformUrl, config?.serverUrl]) {
-        if (typeof c === 'string' && c.trim())
-            return c.trim().replace(/\/+$/, '');
-    }
-    return null;
-}
-const URL_FIX = 'Check the URL is correct (default: https://api.buildhive.app) and your network allows outbound HTTPS';
-const HEALTH_FIX = 'Server may be deploying or down — check status.buildhive.app or wait 60s';
-// 8: server reachable — GET /health within 5s
-export async function checkServerReachable(deps) {
-    const base = getServerUrl(deps.config);
-    if (!base) {
-        return {
-            name: 'Server URL reachable', status: 'fail',
-            message: 'No platformUrl in config', fix: 'Re-run `buildhive-agent init --force`',
-        };
-    }
-    try {
-        // AbortSignal.timeout is the cleanest fetch timeout. We require Node ≥ 18
-        // (check 1) so it's always present.
-        const r = await deps.fetcher(`${base}/health`, { signal: AbortSignal.timeout(5000) });
-        if (r.ok)
-            return { name: 'Server URL reachable', status: 'pass', message: `${base} → ${r.status}` };
-        return {
-            name: 'Server URL reachable', status: 'fail',
-            message: `${base}/health returned HTTP ${r.status}`, fix: URL_FIX,
-        };
-    }
-    catch (err) {
-        return {
-            name: 'Server URL reachable', status: 'fail',
-            message: `Cannot reach ${base}: ${errMsg(err).slice(0, 80)}`, fix: URL_FIX,
-        };
-    }
-}
-// 9: /health body shape — {"status":"healthy"}
-export async function checkServerHealthShape(deps) {
-    const base = getServerUrl(deps.config);
-    if (!base)
-        return { name: 'Server health response', status: 'fail', message: 'No platformUrl in config' };
-    try {
-        const body = await (await deps.fetcher(`${base}/health`, { signal: AbortSignal.timeout(5000) })).text();
-        let parsed;
-        try {
-            parsed = JSON.parse(body);
-        }
-        catch {
-            return {
-                name: 'Server health response', status: 'warn',
-                message: `Health endpoint returned non-JSON (${body.slice(0, 40)}…)`,
-            };
-        }
-        if (parsed.status === 'healthy') {
-            return { name: 'Server health response', status: 'pass', message: '{"status":"healthy"}' };
-        }
-        return {
-            name: 'Server health response', status: 'warn',
-            message: `Server reports status=${String(parsed.status ?? 'unknown')}`, fix: HEALTH_FIX,
-        };
-    }
-    catch (err) {
-        return {
-            name: 'Server health response', status: 'fail',
-            message: `Health check failed: ${errMsg(err).slice(0, 80)}`, fix: HEALTH_FIX,
-        };
-    }
-}
-// 10: API key valid — heartbeat returns anything except 401/403. We pass an
-// obviously-fake agentId; server should reject with 4xx based on payload, NOT
-// auth, when the key itself is good.
-export async function checkApiKeyValid(deps) {
-    const base = getServerUrl(deps.config);
-    const key = typeof deps.config?.apiKey === 'string' ? deps.config.apiKey : '';
-    if (!base || !key) {
-        return {
-            name: 'API key valid against server', status: 'fail',
-            message: 'Missing platformUrl or apiKey in config',
-        };
-    }
-    try {
-        const r = await deps.fetcher(`${base}/api/agents/heartbeat`, {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
-            body: JSON.stringify({
-                agentId: '00000000-0000-0000-0000-000000000000',
-                status: 'ONLINE', currentLoad: 0, activeJobs: 0,
-            }),
-            signal: AbortSignal.timeout(5000),
-        });
-        if (r.status === 401 || r.status === 403) {
-            return {
-                name: 'API key valid against server', status: 'fail',
-                message: `Server rejected key with HTTP ${r.status}`,
-                fix: 'API key revoked or wrong tenant — recreate in /admin/keys',
-            };
-        }
-        return {
-            name: 'API key valid against server', status: 'pass',
-            message: `Server accepted key (HTTP ${r.status})`,
-        };
-    }
-    catch (err) {
-        return {
-            name: 'API key valid against server', status: 'warn',
-            message: `Could not verify key (network error: ${errMsg(err).slice(0, 60)})`,
-        };
-    }
-}
+// Checks 5-10 from the pre-pivot era (config file → JSON parse →
+// apiKey format → server reachable → /health body shape → apiKey valid)
+// have been DELETED in Group B / RI-04 (2026-05-28). They tested for
+// `~/.buildhive/buildhive-agent.json` and the `bh_api_*` key model that
+// the runner-era no longer uses. The replacement checks live in
+// `./runnerChecks.ts` (keyring JWT, identity, platformUrl reachable,
+// my-repos returns ≥1 repo) and use `buildhive-agent join` /
+// `/admin/github` in their Fix strings.
 const ONE_GB = 1024 * 1024 * 1024;
 // 11: ≥ 1 GB free at workspaces root (or closest existing ancestor — statfs
 // needs an extant path).
@@ -339,7 +188,12 @@ export async function checkWorkspaceWritable(deps) {
 // resilience-diagnostic AGT-G1 follow-up. macOS-only for the user-mode
 // LaunchAgent path; Linux + Windows return a non-applicable pass row so the
 // orchestrator never short-circuits on platform.
-const SERVICE_INSTALL_FIX = 'Run `buildhive-agent service:install` (or `service:migrate` if upgrading from a legacy install)';
+// Group B / RI-04 — `join` now auto-installs the LaunchAgent (S-1), so the
+// canonical remediation for a missing/unloaded service is to re-run `join`.
+// `service:install` remains as the manual fallback for advanced users (e.g.
+// when the keyring JWT is intact but the plist was hand-deleted).
+const SERVICE_INSTALL_FIX = 'Re-run `buildhive-agent join <token>` (auto-installs the service). ' +
+    'Or, if the keyring is fine, run `buildhive-agent service:install` to reinstall the plist only.';
 // 13: plist file present at the expected user-scope path
 export async function checkServicePlistInstalled(deps) {
     if (deps.platform !== 'darwin') {

package/dist/doctor/runnerChecks.d.ts

@@ -0,0 +1,54 @@
+/**
+ * doctor/runnerChecks.ts — Group B / RI-04 (expanded).
+ *
+ * Replaces the stale pre-pivot diagnostic checks (#5 config file,
+ * #7 apiKey format, #8 platformUrl in config, #9-#10 cascades) with
+ * checks that match the runner-era model:
+ *
+ *   - Keyring entry `agent-enrollment.jwt` present
+ *   - agent_id + tenant_id resolvable from the keyring payload
+ *   - platformUrl reachable (HTTP GET /health)
+ *   - GET /api/runners/my-repos returns ≥1 repo for the agent's tenant
+ *
+ * Fix strings ALWAYS reference `buildhive-agent join` and `/admin/github`;
+ * never `init`, `register`, or `--api-key`.
+ *
+ * Design refs: docs/ops/buildhive-reinit-fix-plan-2026-05-28.html §Group B (RI-04).
+ */
+import type { CheckResult } from './runChecks.js';
+/**
+ * Keyring-credential payload threaded from check 1 → checks 2-4.
+ * Mirrors the orchestrator's `config` plumbing pattern.
+ */
+export interface RunnerCheckState {
+    readonly jwt: string | null;
+    readonly platformUrl: string | null;
+    readonly agentId: string | null;
+    readonly tenantId: string | null;
+}
+/**
+ * DI surface — production callers pass `defaultRunnerCheckDeps()`; tests
+ * supply fakes so no real keyring / network access is required.
+ */
+export interface RunnerCheckDeps {
+    /** Build / read the agent-enrollment keyring store. */
+    readonly readKeyring: () => Promise<RunnerCheckState>;
+    /** HTTP client (defaults to global fetch). */
+    readonly fetcher: (url: string, init?: RequestInit) => Promise<{
+        ok: boolean;
+        status: number;
+        json: () => Promise<unknown>;
+        text: () => Promise<string>;
+    }>;
+}
+export declare function defaultRunnerCheckDeps(): RunnerCheckDeps;
+/**
+ * Returns the read state so subsequent checks can reuse it (no re-read).
+ */
+export declare function checkKeyringPresent(deps: Pick<RunnerCheckDeps, 'readKeyring'>): Promise<{
+    result: CheckResult;
+    state: RunnerCheckState;
+}>;
+export declare function checkKeyringClaims(state: RunnerCheckState): CheckResult;
+export declare function checkPlatformUrlReachable(state: RunnerCheckState, deps: Pick<RunnerCheckDeps, 'fetcher'>): Promise<CheckResult>;
+export declare function checkEnrolledRepos(state: RunnerCheckState, deps: Pick<RunnerCheckDeps, 'fetcher'>): Promise<CheckResult>;

package/dist/doctor/runnerChecks.js

@@ -0,0 +1,212 @@
+/**
+ * doctor/runnerChecks.ts — Group B / RI-04 (expanded).
+ *
+ * Replaces the stale pre-pivot diagnostic checks (#5 config file,
+ * #7 apiKey format, #8 platformUrl in config, #9-#10 cascades) with
+ * checks that match the runner-era model:
+ *
+ *   - Keyring entry `agent-enrollment.jwt` present
+ *   - agent_id + tenant_id resolvable from the keyring payload
+ *   - platformUrl reachable (HTTP GET /health)
+ *   - GET /api/runners/my-repos returns ≥1 repo for the agent's tenant
+ *
+ * Fix strings ALWAYS reference `buildhive-agent join` and `/admin/github`;
+ * never `init`, `register`, or `--api-key`.
+ *
+ * Design refs: docs/ops/buildhive-reinit-fix-plan-2026-05-28.html §Group B (RI-04).
+ */
+import { AgentEnrollmentKeyringStore } from '../auth/agentEnrollmentKeyringStore.js';
+const JOIN_FIX = 'Run `buildhive-agent join <token>`. Get the token from /admin/github in your BuildHive dashboard.';
+const ENROLL_FIX = 'Open /admin/github in your BuildHive dashboard, enroll at least one repo, then re-run `buildhive-agent join <token>`.';
+const NETWORK_FIX = 'Check the platform URL is correct (default: https://api.buildhive.app) and your network allows outbound HTTPS.';
+const HEALTH_FIX = 'BuildHive server may be deploying or down — wait 60s and retry, or check status.buildhive.app.';
+export function defaultRunnerCheckDeps() {
+    return {
+        readKeyring: async () => {
+            try {
+                const store = new AgentEnrollmentKeyringStore();
+                const creds = await store.readAll();
+                return {
+                    jwt: creds.jwt ?? null,
+                    platformUrl: creds.platformUrl ?? null,
+                    agentId: creds.agentId ?? null,
+                    tenantId: creds.tenantId ?? null,
+                };
+            }
+            catch {
+                return { jwt: null, platformUrl: null, agentId: null, tenantId: null };
+            }
+        },
+        fetcher: (url, init) => globalThis.fetch(url, init).then((r) => r),
+    };
+}
+// ─── Check 1: keyring entry present ───────────────────────────────────────
+/**
+ * Returns the read state so subsequent checks can reuse it (no re-read).
+ */
+export async function checkKeyringPresent(deps) {
+    let state;
+    try {
+        state = await deps.readKeyring();
+    }
+    catch {
+        state = { jwt: null, platformUrl: null, agentId: null, tenantId: null };
+    }
+    if (state.jwt && state.jwt.length > 0) {
+        return {
+            result: {
+                name: 'Agent enrollment JWT (keyring)',
+                status: 'pass',
+                message: 'Found in OS keyring under agent-enrollment.jwt',
+            },
+            state,
+        };
+    }
+    return {
+        result: {
+            name: 'Agent enrollment JWT (keyring)',
+            status: 'fail',
+            message: 'No agent-enrollment JWT in the OS keyring',
+            fix: JOIN_FIX,
+        },
+        state,
+    };
+}
+// ─── Check 2: agent_id + tenant_id resolvable ─────────────────────────────
+export function checkKeyringClaims(state) {
+    if (!state.jwt) {
+        return {
+            name: 'Agent identity (agent_id + tenant_id)',
+            status: 'fail',
+            message: 'Cannot resolve identity — no JWT in keyring',
+            fix: JOIN_FIX,
+        };
+    }
+    if (!state.agentId || !state.tenantId) {
+        return {
+            name: 'Agent identity (agent_id + tenant_id)',
+            status: 'fail',
+            message: 'JWT present but agent_id or tenant_id missing from keyring payload',
+            fix: 'Keyring payload is incomplete — re-enroll with `buildhive-agent join <token>`.',
+        };
+    }
+    return {
+        name: 'Agent identity (agent_id + tenant_id)',
+        status: 'pass',
+        message: `agent_id=${state.agentId.slice(0, 8)}… tenant_id=${state.tenantId.slice(0, 8)}…`,
+    };
+}
+// ─── Check 3: platformUrl reachable ────────────────────────────────────────
+export async function checkPlatformUrlReachable(state, deps) {
+    const base = state.platformUrl?.trim().replace(/\/+$/, '');
+    if (!base) {
+        return {
+            name: 'Platform URL reachable',
+            status: 'fail',
+            message: 'No platformUrl in the keyring (agent not enrolled)',
+            fix: JOIN_FIX,
+        };
+    }
+    try {
+        const r = await deps.fetcher(`${base}/health`, { signal: AbortSignal.timeout(5000) });
+        if (r.ok) {
+            return {
+                name: 'Platform URL reachable',
+                status: 'pass',
+                message: `${base} → ${r.status}`,
+            };
+        }
+        return {
+            name: 'Platform URL reachable',
+            status: 'fail',
+            message: `${base}/health returned HTTP ${r.status}`,
+            fix: HEALTH_FIX,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            name: 'Platform URL reachable',
+            status: 'fail',
+            message: `Cannot reach ${base}: ${msg.slice(0, 80)}`,
+            fix: NETWORK_FIX,
+        };
+    }
+}
+// ─── Check 4: /api/runners/my-repos returns ≥1 repo ────────────────────────
+export async function checkEnrolledRepos(state, deps) {
+    const base = state.platformUrl?.trim().replace(/\/+$/, '');
+    if (!base || !state.jwt) {
+        return {
+            name: 'Tenant has ≥1 enrolled repo',
+            status: 'fail',
+            message: 'Cannot query — no JWT or platformUrl available',
+            fix: JOIN_FIX,
+        };
+    }
+    let response;
+    try {
+        response = await deps.fetcher(`${base}/api/runners/my-repos`, {
+            method: 'GET',
+            headers: { Accept: 'application/json', Authorization: `Bearer ${state.jwt}` },
+            signal: AbortSignal.timeout(5000),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            name: 'Tenant has ≥1 enrolled repo',
+            status: 'fail',
+            message: `Network error querying /api/runners/my-repos: ${msg.slice(0, 80)}`,
+            fix: NETWORK_FIX,
+        };
+    }
+    if (response.status === 401) {
+        return {
+            name: 'Tenant has ≥1 enrolled repo',
+            status: 'fail',
+            message: 'Server rejected the agent JWT (401) — token revoked or expired',
+            fix: JOIN_FIX,
+        };
+    }
+    if (!response.ok) {
+        return {
+            name: 'Tenant has ≥1 enrolled repo',
+            status: 'fail',
+            message: `/api/runners/my-repos returned HTTP ${response.status}`,
+            fix: HEALTH_FIX,
+        };
+    }
+    let body;
+    try {
+        body = await response.json();
+    }
+    catch (err) {
+        return {
+            name: 'Tenant has ≥1 enrolled repo',
+            status: 'warn',
+            message: `Could not parse my-repos response body: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    if (!body || typeof body !== 'object' || !Array.isArray(body.repos)) {
+        return {
+            name: 'Tenant has ≥1 enrolled repo',
+            status: 'warn',
+            message: 'Malformed my-repos response (missing repos array)',
+        };
+    }
+    const repos = body.repos;
+    if (repos.length === 0) {
+        return {
+            name: 'Tenant has ≥1 enrolled repo',
+            status: 'fail',
+            message: 'Your tenant has no enrolled repos',
+            fix: ENROLL_FIX,
+        };
+    }
+    return {
+        name: 'Tenant has ≥1 enrolled repo',
+        status: 'pass',
+        message: `${repos.length} enrolled repo(s)`,
+    };
+}

package/dist/runner/binaryFetcher.d.ts

@@ -32,11 +32,22 @@
  */
 export declare function validateRunnerVersion(version: string): void;
 /**
- * Wave 1 pinned runner version.
- * Matches the latest stable actions/runner release at the time this was written.
- * Operators can override via BUILDHIVE_RUNNER_VERSION env var for testing.
+ * Pinned actions/runner version.
+ *
+ * GitHub deprecates older runner versions roughly every 2-3 months and refuses
+ * connections from them ("Runner version vX.Y.Z is deprecated and cannot
+ * receive messages") — when that happens, no job can run on a BuildHive
+ * agent until this constant is bumped + a new buildhive-agent beta published.
+ *
+ * Operators can override via BUILDHIVE_RUNNER_VERSION env var for testing
+ * (used during the 2026-05-31 walk to confirm v2.334.0 unblocks the flow).
+ *
+ * Bump policy: keep within ~1 minor release of the latest stable tag at
+ * https://github.com/actions/runner/releases. The
+ * `.github/workflows/check-actions-runner-version.yml` cron opens a
+ * tracking issue weekly when this constant falls behind upstream.
  */
-export declare const DEFAULT_RUNNER_VERSION = "2.325.0";
+export declare const DEFAULT_RUNNER_VERSION = "2.334.0";
 /**
  * Platform-not-supported error message.
  * Exact string required by task spec so tests can assert on it.

package/dist/runner/binaryFetcher.js

@@ -61,11 +61,22 @@ const MAX_TARBALL_BYTES = 500 * 1024 * 1024;
 const MAX_RELEASE_BODY_BYTES = 1 * 1024 * 1024;
 const logger = createLogger('runner.binaryFetcher');
 /**
- * Wave 1 pinned runner version.
- * Matches the latest stable actions/runner release at the time this was written.
- * Operators can override via BUILDHIVE_RUNNER_VERSION env var for testing.
+ * Pinned actions/runner version.
+ *
+ * GitHub deprecates older runner versions roughly every 2-3 months and refuses
+ * connections from them ("Runner version vX.Y.Z is deprecated and cannot
+ * receive messages") — when that happens, no job can run on a BuildHive
+ * agent until this constant is bumped + a new buildhive-agent beta published.
+ *
+ * Operators can override via BUILDHIVE_RUNNER_VERSION env var for testing
+ * (used during the 2026-05-31 walk to confirm v2.334.0 unblocks the flow).
+ *
+ * Bump policy: keep within ~1 minor release of the latest stable tag at
+ * https://github.com/actions/runner/releases. The
+ * `.github/workflows/check-actions-runner-version.yml` cron opens a
+ * tracking issue weekly when this constant falls behind upstream.
  */
-export const DEFAULT_RUNNER_VERSION = '2.325.0';
+export const DEFAULT_RUNNER_VERSION = '2.334.0';
 /**
  * Platform-not-supported error message.
  * Exact string required by task spec so tests can assert on it.
@@ -221,6 +232,12 @@ export function parseSha256FromReleaseBody(body, platform) {
  *
  * Security considerations:
  * - User-Agent header is required for unauthenticated GitHub API requests (403 otherwise).
+ * - Optional Authorization header from GITHUB_TOKEN/GH_TOKEN env raises the
+ *   per-IP anonymous limit (60/hr) to the authenticated per-repo limit
+ *   (5000/hr). Used by CI (runner-version-validate workflow injects
+ *   `${{ github.token }}`) so shared-IP rate-limit exhaustion can't block a
+ *   runner-version bump PR. On user machines the env vars are absent; the
+ *   call stays anonymous (one call per cold install).
  * - Response body is capped at MAX_RELEASE_BODY_BYTES to prevent OOM on adversarial responses.
  * - Fail-closed: throws on 4xx/5xx, missing platform marker, or malformed hash.
  * - HTTPS enforced (api.github.com URL is always HTTPS).
@@ -233,17 +250,26 @@ export function parseSha256FromReleaseBody(body, platform) {
  */
 async function fetchRunnerSha256(version, platform, fetchFn) {
     const apiUrl = `https://api.github.com/repos/actions/runner/releases/tags/v${version}`;
-    logger.info('Fetching runner checksum from GitHub Releases API', { apiUrl, platform });
+    const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+    const headers = {
+        'Accept': 'application/vnd.github+json',
+        'User-Agent': `BuildHive-Agent/${AGENT_VERSION}`,
+    };
+    if (token) {
+        headers['Authorization'] = `Bearer ${token}`;
+    }
+    logger.info('Fetching runner checksum from GitHub Releases API', {
+        apiUrl,
+        platform,
+        authenticated: Boolean(token),
+    });
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), 30_000);
     let body;
     try {
         const resp = await fetchFn(apiUrl, {
             signal: controller.signal,
-            headers: {
-                'Accept': 'application/vnd.github+json',
-                'User-Agent': `BuildHive-Agent/${AGENT_VERSION}`,
-            },
+            headers,
         });
         if (resp.status === 403) {
             throw new Error(`GitHub API responded with 403 when fetching release v${version} — ` +

package/dist/runner/myReposClient.d.ts

@@ -0,0 +1,29 @@
+/**
+ * myReposClient — fetches the agent's enrolled repos from the BuildHive
+ * backend's GET /api/runners/my-repos endpoint.
+ *
+ * Group B / RI-08. Replaces the BUILDHIVE_OWNER / BUILDHIVE_REPO env-var
+ * read path in startCommand.ts with a server-side resolution call — the
+ * developer no longer needs to know which GitHub org/repo to point at.
+ *
+ * Wire contract: server returns
+ *   { repos: [{ owner: string, repo: string, installationId: string }] }
+ */
+export interface EnrolledRepoInfo {
+    readonly owner: string;
+    readonly repo: string;
+    readonly installationId: string;
+}
+export interface FetchMyReposOptions {
+    /** BuildHive backend URL (e.g. https://api.buildhive.app) */
+    readonly platformUrl: string;
+    /** Agent enrollment JWT to use as Bearer token */
+    readonly jwt: string;
+    /** Override fetch for tests */
+    readonly fetchFn?: typeof fetch;
+}
+/**
+ * GET /api/runners/my-repos and return the parsed list.
+ * Throws a descriptive Error on any non-200 response or network failure.
+ */
+export declare function fetchMyRepos(opts: FetchMyReposOptions): Promise<ReadonlyArray<EnrolledRepoInfo>>;

package/dist/runner/myReposClient.js

@@ -0,0 +1,92 @@
+/**
+ * myReposClient — fetches the agent's enrolled repos from the BuildHive
+ * backend's GET /api/runners/my-repos endpoint.
+ *
+ * Group B / RI-08. Replaces the BUILDHIVE_OWNER / BUILDHIVE_REPO env-var
+ * read path in startCommand.ts with a server-side resolution call — the
+ * developer no longer needs to know which GitHub org/repo to point at.
+ *
+ * Wire contract: server returns
+ *   { repos: [{ owner: string, repo: string, installationId: string }] }
+ */
+import { createLogger } from '../utils/logger.js';
+import { redactSecrets } from '../security/logRedactor.js';
+const logger = createLogger('runner.myReposClient');
+const FETCH_TIMEOUT_MS = 30_000;
+/**
+ * GET /api/runners/my-repos and return the parsed list.
+ * Throws a descriptive Error on any non-200 response or network failure.
+ */
+export async function fetchMyRepos(opts) {
+    const { platformUrl, jwt } = opts;
+    const fetchFn = opts.fetchFn ?? fetch;
+    const url = `${platformUrl.replace(/\/$/, '')}/api/runners/my-repos`;
+    logger.info('Fetching enrolled repos', { url });
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+    let response;
+    try {
+        response = await fetchFn(url, {
+            method: 'GET',
+            headers: {
+                Accept: 'application/json',
+                Authorization: `Bearer ${jwt}`,
+            },
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error && err.name === 'AbortError'
+            ? `Timed out after ${FETCH_TIMEOUT_MS}ms fetching enrolled repos`
+            : `Network error fetching enrolled repos: ${err instanceof Error ? err.message : String(err)}`;
+        logger.error(msg);
+        throw new Error(msg);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (!response.ok) {
+        let body = '';
+        try {
+            body = await response.text();
+        }
+        catch {
+            // ignore
+        }
+        const msg = `Enrolled-repos request failed: HTTP ${response.status} — ${redactSecrets(body.slice(0, 200))}`;
+        logger.error(msg, { status: response.status });
+        throw new Error(msg);
+    }
+    let parsed;
+    try {
+        parsed = (await response.json());
+    }
+    catch (err) {
+        const msg = `Failed to parse my-repos response body: ${err instanceof Error ? err.message : String(err)}`;
+        logger.error(msg);
+        throw new Error(msg);
+    }
+    const repos = parsed['repos'];
+    if (!Array.isArray(repos)) {
+        const msg = 'Malformed my-repos response: missing repos array';
+        logger.error(msg, { parsedKeys: Object.keys(parsed) });
+        throw new Error(msg);
+    }
+    const validated = [];
+    for (const r of repos) {
+        if (!r || typeof r !== 'object')
+            continue;
+        const row = r;
+        if (typeof row.owner === 'string' &&
+            typeof row.repo === 'string' &&
+            typeof row.installationId === 'string') {
+            validated.push({
+                owner: row.owner,
+                repo: row.repo,
+                installationId: row.installationId,
+            });
+        }
+    }
+    logger.info('Enrolled repos fetched', { count: validated.length });
+    return validated;
+}

package/dist/runner/startCommand.d.ts

@@ -21,6 +21,7 @@
  *   2 — platform not supported
  */
 import { AgentEnrollmentKeyringStore } from '../auth/agentEnrollmentKeyringStore.js';
+import { fetchMyRepos } from './myReposClient.js';
 import { ensureRunner } from './binaryFetcher.js';
 import { type PoolDeps } from './pool.js';
 import type { EnsureRunnerOptions } from './binaryFetcher.js';
@@ -36,6 +37,8 @@ export interface StartOptions {
     readonly keyringStore?: AgentEnrollmentKeyringStore;
     /** Dependency injection for tests — avoids real network calls */
     readonly fetchFn?: typeof fetch;
+    /** Dependency injection for tests — avoids hitting the my-repos endpoint */
+    readonly fetchMyReposFn?: typeof fetchMyRepos;
     /** Dependency injection for tests — avoids real binary download */
     readonly ensureRunnerFn?: (opts?: EnsureRunnerOptions) => ReturnType<typeof ensureRunner>;
     /** Skip the LaunchAgent startup guard in tests */

package/dist/runner/startCommand.js

@@ -24,6 +24,7 @@ import os from 'os';
 import { createLogger } from '../utils/logger.js';
 import { AgentEnrollmentKeyringStore } from '../auth/agentEnrollmentKeyringStore.js';
 import { fetchRunnerToken } from './tokenClient.js';
+import { fetchMyRepos } from './myReposClient.js';
 import { ensureRunner, PLATFORM_NOT_SUPPORTED_MSG } from './binaryFetcher.js';
 import { configureRunner, runRunner, generateRunnerName, applyLaunchAgentStartupGuard, } from './supervisor.js';
 import { prepareCache, stopCache } from './cacheEnv.js';
@@ -71,46 +72,51 @@ async function resolveJwt(store) {
     return null;
 }
 /**
- * Read owner and repo from config. These are used to scope the runner-token
- * request. For v1.1 the agent is configured once per repo; the operator passes
- * these values in the agent config file or as CLI options.
+ * Resolve owner + repo for the current `start` invocation.
  *
- * Reads from:
- *   1. CLI opts (highest priority)
- *   2. BUILDHIVE_OWNER / BUILDHIVE_REPO env vars
- *   3. config file (if present)
+ * Group B / RI-08: zero-GH agent runtime. The developer never has to type
+ * BUILDHIVE_OWNER / BUILDHIVE_REPO. Resolution order:
  *
- * Returns null if neither owner nor repo can be resolved — caller surfaces error.
+ *   1. CLI overrides (`--owner` + `--repo`) — power-user / build-farm path.
+ *   2. BUILDHIVE_OWNER + BUILDHIVE_REPO env vars — retained as an override
+ *      but NEVER advertised in docs / help / doctor output.
+ *   3. Server-side resolution via GET /api/runners/my-repos — the
+ *      canonical zero-GH path. Picks the first enrolled repo in the
+ *      server's deterministic alphabetical order.
+ *
+ * Returns null only when (a) the server returns zero enrolled repos AND
+ * (b) no CLI/env override is set — caller surfaces an actionable error
+ * pointing at `/admin/github`.
  */
-async function resolveOwnerRepo(opts) {
-    // 1. CLI overrides
+async function resolveOwnerRepo(opts, serverCtx) {
+    // 1. CLI overrides (highest priority; power-user / build-farm)
     if (opts.owner && opts.repo) {
-        return { owner: opts.owner, repo: opts.repo };
+        return { owner: opts.owner, repo: opts.repo, extraRepos: [], source: 'cli' };
     }
-    // 2. Environment variables
+    // 2. Environment variables (retained as override — never advertised)
     const ownerEnv = process.env.BUILDHIVE_OWNER?.trim();
     const repoEnv = process.env.BUILDHIVE_REPO?.trim();
     if (ownerEnv && repoEnv) {
-        return { owner: ownerEnv, repo: repoEnv };
+        return { owner: ownerEnv, repo: repoEnv, extraRepos: [], source: 'env' };
     }
-    // 3. Config file
+    // 3. Server-side resolution — the canonical zero-GH path.
+    let repos;
     try {
-        const { loadConfig } = await import('../config/index.js');
-        const cfg = await loadConfig();
-        // AgentConfig may have these fields under a different name; the canonical
-        // place for them in the config file is `githubOwner` + `githubRepo`.
-        const cfgAny = cfg;
-        const cfgOwner = typeof cfgAny.githubOwner === 'string' ? cfgAny.githubOwner : (opts.owner ?? '');
-        const cfgRepo = typeof cfgAny.githubRepo === 'string' ? cfgAny.githubRepo : (opts.repo ?? '');
-        if (cfgOwner && cfgRepo) {
-            return { owner: cfgOwner, repo: cfgRepo };
-        }
+        const fetchFn = opts.fetchMyReposFn ?? fetchMyRepos;
+        repos = await fetchFn({ platformUrl: serverCtx.platformUrl, jwt: serverCtx.jwt });
     }
-    catch {
-        // Config load failure is non-fatal at this step — fall through
+    catch (err) {
+        logger.error('Failed to fetch enrolled repos from /api/runners/my-repos', {
+            err: err instanceof Error ? err.message : String(err),
+        });
+        return null;
     }
-    // 4. Not resolvable
-    return null;
+    if (repos.length === 0) {
+        logger.error('Your tenant has no enrolled repos. Open /admin/github and enroll at least one repo, then run `buildhive-agent start` again.');
+        return null;
+    }
+    const [chosen, ...extras] = repos;
+    return { owner: chosen.owner, repo: chosen.repo, extraRepos: extras, source: 'server' };
 }
 /**
  * Main orchestrator. Called by cli.ts's `start` action.
@@ -144,14 +150,30 @@ export async function runStart(opts = {}) {
     const platformUrl = opts.platformUrl ?? jwtCreds.platformUrl;
     const { jwt } = jwtCreds;
     // ── Step 2: Resolve owner + repo ────────────────────────────────────────────
-    const ownerRepo = await resolveOwnerRepo({ owner: opts.owner, repo: opts.repo });
+    // Group B / RI-08: the developer no longer needs to type
+    // BUILDHIVE_OWNER / BUILDHIVE_REPO. Resolution prefers (in order):
+    //   1. CLI overrides — power-user / build-farm
+    //   2. Env vars — retained as override but never advertised
+    //   3. /api/runners/my-repos — the canonical zero-GH path
+    const ownerRepo = await resolveOwnerRepo({ owner: opts.owner, repo: opts.repo, fetchMyReposFn: opts.fetchMyReposFn }, { platformUrl, jwt });
     if (!ownerRepo) {
-        const msg = 'GitHub owner and repo are required. Set BUILDHIVE_OWNER and BUILDHIVE_REPO ' +
-            'or add githubOwner/githubRepo to your agent config file.';
+        const msg = 'No enrolled repos found for this agent. Open /admin/github in the BuildHive ' +
+            'dashboard, enroll at least one repository, then run `buildhive-agent start` again.';
         logger.error(msg);
         return { exitCode: 1, message: msg };
     }
     const { owner, repo } = ownerRepo;
+    if (ownerRepo.source === 'server') {
+        logger.info('Resolved repo from /api/runners/my-repos', { owner, repo });
+        if (ownerRepo.extraRepos.length > 0) {
+            const more = ownerRepo.extraRepos.map((r) => `${r.owner}/${r.repo}`).join(', ');
+            logger.info(`Tenant has ${ownerRepo.extraRepos.length} additional enrolled repo(s): ${more}. ` +
+                `Ephemeral runner lifecycle will rotate through them on subsequent launches.`);
+        }
+    }
+    else {
+        logger.info(`Using ${ownerRepo.source} override for owner/repo`, { owner, repo });
+    }
     // ── Step 3: LaunchAgent startup guard (FB16131937) ──────────────────────────
     if (!opts.skipStartupGuard) {
         await applyLaunchAgentStartupGuard();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "buildhive-agent",
-  "version": "1.0.0-beta.10",
+  "version": "1.0.0-beta.11",
   "description": "BuildHive CI Agent - Distributed build execution agent",
   "type": "module",
   "main": "dist/index.js",