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

package/dist/auth/agentEnrollmentKeyringStore.d.ts

@@ -14,6 +14,7 @@
  *   agent-enrollment.platform_url     — bound at enroll; refuses cross-instance reuse
  */
 import type { SecretStore } from '../security/secretStore.js';
+import { CredentialFileStore } from './credentialFileStore.js';
 import { PlatformUrlMismatchError } from './types.js';
 export declare const AGENT_ENROLLMENT_KEY_PREFIX = "agent-enrollment.";
 export declare const KEY_JWT = "agent-enrollment.jwt";
@@ -31,6 +32,12 @@ export interface AgentEnrollmentCredentials {
 export interface AgentEnrollmentKeyringStoreOptions {
     /** Override the SecretStore (tests + environments without OS keyring). */
     readonly store?: SecretStore;
+    /**
+     * Override the 0600 credential-file mirror (row 21b / F2 daemon fallback).
+     * Tests inject a fake; production uses the real `~/.buildhive/` file.
+     * Pass `null` to disable the file mirror entirely (keyring-only).
+     */
+    readonly fileStore?: CredentialFileStore | null;
 }
 /**
  * Custom error thrown when the stored platform_url doesn't match the current
@@ -42,6 +49,8 @@ export declare class AgentPlatformUrlMismatchError extends PlatformUrlMismatchEr
 }
 export declare class AgentEnrollmentKeyringStore {
     private readonly store;
+    /** 0600 file mirror for the launchd daemon; null when explicitly disabled. */
+    private readonly fileStore;
     constructor(opts?: AgentEnrollmentKeyringStoreOptions);
     /** Throws KeyringUnavailableError if the OS keyring is unreachable. */
     static assertAvailable(): Promise<void>;
@@ -63,16 +72,21 @@ export declare class AgentEnrollmentKeyringStore {
      * Throws NotLoggedInError if any required key is missing.
      */
     readAll(): Promise<AgentEnrollmentCredentials>;
+    /**
+     * Read the 0600 file mirror, swallowing any error to null. Centralised so
+     * every read path (readJwt / readAll / hasEnrollment) shares one fallback.
+     */
+    private readFromFileMirror;
     /**
      * Cross-platform-url check. Refuses to use credentials minted against a
      * different BuildHive instance.
      */
     assertPlatformUrlMatches(currentPlatformUrl: string): Promise<void>;
-    /** Returns true if any enrollment key exists in the keyring. */
+    /** Returns true if an enrollment JWT exists in the keyring OR the file mirror. */
     hasEnrollment(): Promise<boolean>;
     /**
-     * Delete all 5 `agent-enrollment.*` keys. Idempotent.
-     * Called by a hypothetical `buildhive-agent leave` command (out of scope for v1).
+     * Delete all 5 `agent-enrollment.*` keys AND the 0600 file mirror. Idempotent.
+     * Called by `buildhive-agent logout` (row 21b / F4) to fully de-enroll.
      */
     clear(): Promise<void>;
 }

package/dist/auth/agentEnrollmentKeyringStore.js

@@ -14,7 +14,10 @@
  *   agent-enrollment.platform_url     — bound at enroll; refuses cross-instance reuse
  */
 import { KeyringSecretStore } from '../security/keyringSecretStore.js';
+import { CredentialFileStore } from './credentialFileStore.js';
+import { createLogger } from '../utils/logger.js';
 import { KeyringUnavailableError, NotLoggedInError, PlatformUrlMismatchError, } from './types.js';
+const logger = createLogger('auth.agentEnrollmentKeyringStore');
 export const AGENT_ENROLLMENT_KEY_PREFIX = 'agent-enrollment.';
 export const KEY_JWT = `${AGENT_ENROLLMENT_KEY_PREFIX}jwt`;
 export const KEY_JWT_EXP = `${AGENT_ENROLLMENT_KEY_PREFIX}jwt_exp`;
@@ -44,8 +47,29 @@ export class AgentPlatformUrlMismatchError extends PlatformUrlMismatchError {
 }
 export class AgentEnrollmentKeyringStore {
     store;
+    /** 0600 file mirror for the launchd daemon; null when explicitly disabled. */
+    fileStore;
     constructor(opts = {}) {
         this.store = opts.store ?? new KeyringSecretStore();
+        // File-mirror resolution (row 21b / F2):
+        //   - explicit `null`        → disabled (keyring-only)
+        //   - explicit CredentialFileStore → use it
+        //   - omitted + real keyring → real `~/.buildhive/` mirror (production)
+        //   - omitted + INJECTED keyring (tests) → disabled, so unit tests never
+        //     read/write the real user home. A test exercising the mirror must
+        //     inject its own `fileStore` explicitly.
+        if (opts.fileStore === null) {
+            this.fileStore = null;
+        }
+        else if (opts.fileStore) {
+            this.fileStore = opts.fileStore;
+        }
+        else if (opts.store) {
+            this.fileStore = null;
+        }
+        else {
+            this.fileStore = new CredentialFileStore();
+        }
     }
     /** Throws KeyringUnavailableError if the OS keyring is unreachable. */
     static async assertAvailable() {
@@ -75,6 +99,21 @@ export class AgentEnrollmentKeyringStore {
             await this.clear().catch(() => undefined);
             throw err;
         }
+        // Row 21b / F2: mirror to the 0600 file so the launchd daemon (which
+        // cannot read the interactive login keychain) can resolve the JWT.
+        // The keychain write above is the source of truth; a file-mirror failure
+        // is non-fatal here (the agent is enrolled for foreground use) but it
+        // leaves the daemon unable to start — `join`'s post-bootstrap self-check
+        // (Fix D) and the doctor will surface that loudly rather than silently.
+        if (this.fileStore) {
+            try {
+                await this.fileStore.write(creds);
+            }
+            catch (err) {
+                logger.warn('Could not write the 0600 credential mirror — the background daemon may ' +
+                    'not be able to read the JWT. Foreground `buildhive-agent start` is unaffected.', { err: err instanceof Error ? err.message : String(err) });
+            }
+        }
     }
     /**
      * Read the stored JWT + its cached exp. Throws NotLoggedInError if absent
@@ -85,13 +124,17 @@ export class AgentEnrollmentKeyringStore {
             this.store.getSecret(KEY_JWT),
             this.store.getSecret(KEY_JWT_EXP),
         ]);
-        if (!token || !expStr)
-            throw new NotLoggedInError();
-        const exp = Number(expStr);
-        return {
-            jwt: token,
-            expiresAtUnix: Number.isFinite(exp) ? exp : 0,
-        };
+        if (token && expStr) {
+            const exp = Number(expStr);
+            return { jwt: token, expiresAtUnix: Number.isFinite(exp) ? exp : 0 };
+        }
+        // Row 21b / F2: keychain returned nothing (the daemon case) — fall back
+        // to the 0600 file mirror before declaring "not enrolled".
+        const fromFile = await this.readFromFileMirror();
+        if (fromFile) {
+            return { jwt: fromFile.jwt, expiresAtUnix: fromFile.jwtExpiresAtUnix };
+        }
+        throw new NotLoggedInError();
     }
     /**
      * Read the full stored credentials (for display or row-17b supervisor).
@@ -105,43 +148,79 @@ export class AgentEnrollmentKeyringStore {
             this.store.getSecret(KEY_TENANT_ID),
             this.store.getSecret(KEY_PLATFORM_URL),
         ]);
-        if (!jwt || !expStr || !agentId || !tenantId || !platformUrl) {
-            throw new NotLoggedInError();
-        }
-        const exp = Number(expStr);
-        return {
-            jwt,
-            jwtExpiresAtUnix: Number.isFinite(exp) ? exp : 0,
-            agentId,
-            tenantId,
-            platformUrl,
-        };
+        if (jwt && expStr && agentId && tenantId && platformUrl) {
+            const exp = Number(expStr);
+            return {
+                jwt,
+                jwtExpiresAtUnix: Number.isFinite(exp) ? exp : 0,
+                agentId,
+                tenantId,
+                platformUrl,
+            };
+        }
+        // Row 21b / F2: the launchd daemon's keychain read comes back empty.
+        // Fall back to the 0600 file mirror written by `join` before throwing.
+        const fromFile = await this.readFromFileMirror();
+        if (fromFile)
+            return fromFile;
+        throw new NotLoggedInError();
+    }
+    /**
+     * Read the 0600 file mirror, swallowing any error to null. Centralised so
+     * every read path (readJwt / readAll / hasEnrollment) shares one fallback.
+     */
+    async readFromFileMirror() {
+        if (!this.fileStore)
+            return null;
+        try {
+            const creds = await this.fileStore.read();
+            if (creds) {
+                logger.info('Resolved agent credentials from the 0600 file mirror (keychain unavailable in this session)');
+            }
+            return creds;
+        }
+        catch {
+            return null;
+        }
     }
     /**
      * Cross-platform-url check. Refuses to use credentials minted against a
      * different BuildHive instance.
      */
     async assertPlatformUrlMatches(currentPlatformUrl) {
-        const stored = await this.store.getSecret(KEY_PLATFORM_URL);
-        if (!stored)
-            throw new NotLoggedInError();
+        let stored = await this.store.getSecret(KEY_PLATFORM_URL);
+        if (!stored) {
+            // Row 21b / F2: keep the cross-instance guard working in the daemon
+            // session, where the keychain read comes back empty — fall back to the
+            // 0600 file mirror before declaring "not enrolled".
+            const fromFile = await this.readFromFileMirror();
+            if (!fromFile)
+                throw new NotLoggedInError();
+            stored = fromFile.platformUrl;
+        }
         if (normalizeUrl(stored) !== normalizeUrl(currentPlatformUrl)) {
             throw new AgentPlatformUrlMismatchError(stored, currentPlatformUrl);
         }
     }
-    /** Returns true if any enrollment key exists in the keyring. */
+    /** Returns true if an enrollment JWT exists in the keyring OR the file mirror. */
     async hasEnrollment() {
         const jwt = await this.store.getSecret(KEY_JWT);
-        return jwt !== null && jwt.length > 0;
+        if (jwt !== null && jwt.length > 0)
+            return true;
+        const fromFile = await this.readFromFileMirror();
+        return fromFile !== null;
     }
     /**
-     * Delete all 5 `agent-enrollment.*` keys. Idempotent.
-     * Called by a hypothetical `buildhive-agent leave` command (out of scope for v1).
+     * Delete all 5 `agent-enrollment.*` keys AND the 0600 file mirror. Idempotent.
+     * Called by `buildhive-agent logout` (row 21b / F4) to fully de-enroll.
      */
     async clear() {
         for (const k of ALL_KEYS) {
             await this.store.deleteSecret(k).catch(() => false);
         }
+        if (this.fileStore) {
+            await this.fileStore.delete().catch(() => undefined);
+        }
     }
 }
 function normalizeUrl(u) {

package/dist/auth/credentialFileStore.d.ts

@@ -0,0 +1,79 @@
+/**
+ * credentialFileStore — 0600 on-disk fallback for the agent-enrollment
+ * credentials, so the **launchd-managed daemon** can read its JWT.
+ *
+ * ── Why this exists (row 21b / F2, 2026-06-02) ───────────────────────────────
+ * The 2026-06-01 verification walk found the LaunchAgent daemon crashlooping
+ * with `last exit code = 1` and empty logs. Root cause (proven in
+ * docs/ops/diagnosis-f3-agent-daemon-2026-06-02.html): the macOS Keychain item
+ * holding the JWT is created by the *foreground* `join` process (Terminal
+ * security session). The launchd-spawned daemon runs in a different security
+ * session (`SessionCreate=true`), so `@napi-rs/keyring`'s `getPassword()`
+ * returns `null` for it (silent access-deny). The daemon then reads "no JWT" →
+ * "Not enrolled" → exits 1 → launchd respawns → silent crashloop.
+ *
+ * GitHub's own `actions/runner` `svc.sh` stores its `.credentials` as files in
+ * the runner directory for exactly this reason — a launchd/systemd service
+ * cannot rely on the interactive login keychain.
+ *
+ * ── Design ───────────────────────────────────────────────────────────────────
+ * The OS keyring stays the PRIMARY store (used by foreground `start`, where it
+ * works and is the more-secure option). This file is a daemon-readable MIRROR:
+ * `join` writes both; the resolver falls back to the file only when the keyring
+ * returns nothing (the daemon case).
+ *
+ * Security:
+ *   - File mode 0600 (owner read/write only), parent dir 0700.
+ *   - Lives under the user's own `~/.buildhive/` — same trust boundary as the
+ *     actions/runner `.credentials` file and the workspaces dir.
+ *   - Never packaged (runtime state in $HOME, not in the npm tarball).
+ *
+ * This module is pure-where-possible: fs + homedir are injectable for tests.
+ */
+import type { AgentEnrollmentCredentials } from './agentEnrollmentKeyringStore.js';
+/** Basename of the credential mirror file under `~/.buildhive/`. */
+export declare const CREDENTIAL_FILE_NAME = "agent-enrollment.cred";
+/** Injectable fs surface (subset of node:fs/promises we use). */
+export interface CredentialFileFs {
+    readonly mkdir: (path: string, opts: {
+        recursive: boolean;
+        mode?: number;
+    }) => Promise<string | undefined>;
+    readonly writeFile: (path: string, data: string, opts: {
+        encoding: 'utf8';
+        mode?: number;
+    }) => Promise<void>;
+    readonly chmod: (path: string, mode: number) => Promise<void>;
+    readonly rename: (from: string, to: string) => Promise<void>;
+    readonly readFile: (path: string, encoding: 'utf8') => Promise<string>;
+    readonly unlink: (path: string) => Promise<void>;
+}
+export interface CredentialFileStoreOptions {
+    /** Override the home directory (tests + multi-user). */
+    readonly homeDir?: string;
+    /** Override the fs surface (tests). */
+    readonly fs?: CredentialFileFs;
+}
+/**
+ * Reads/writes the agent-enrollment credentials as a single 0600 JSON file.
+ */
+export declare class CredentialFileStore {
+    private readonly fs;
+    private readonly dir;
+    private readonly filePath;
+    constructor(opts?: CredentialFileStoreOptions);
+    /** Absolute path to the credential file (for diagnostics + doctor). */
+    get path(): string;
+    /**
+     * Atomically write the credential mirror with 0600 perms.
+     * tmp-file → chmod 0600 → rename avoids a torn read by the daemon.
+     */
+    write(creds: AgentEnrollmentCredentials): Promise<void>;
+    /**
+     * Read the credential mirror. Returns null when absent or malformed — never
+     * throws, so the resolver can cleanly fall through to "not enrolled".
+     */
+    read(): Promise<AgentEnrollmentCredentials | null>;
+    /** Delete the credential mirror. Idempotent (ENOENT is not an error). */
+    delete(): Promise<void>;
+}

package/dist/auth/credentialFileStore.js

@@ -0,0 +1,140 @@
+/**
+ * credentialFileStore — 0600 on-disk fallback for the agent-enrollment
+ * credentials, so the **launchd-managed daemon** can read its JWT.
+ *
+ * ── Why this exists (row 21b / F2, 2026-06-02) ───────────────────────────────
+ * The 2026-06-01 verification walk found the LaunchAgent daemon crashlooping
+ * with `last exit code = 1` and empty logs. Root cause (proven in
+ * docs/ops/diagnosis-f3-agent-daemon-2026-06-02.html): the macOS Keychain item
+ * holding the JWT is created by the *foreground* `join` process (Terminal
+ * security session). The launchd-spawned daemon runs in a different security
+ * session (`SessionCreate=true`), so `@napi-rs/keyring`'s `getPassword()`
+ * returns `null` for it (silent access-deny). The daemon then reads "no JWT" →
+ * "Not enrolled" → exits 1 → launchd respawns → silent crashloop.
+ *
+ * GitHub's own `actions/runner` `svc.sh` stores its `.credentials` as files in
+ * the runner directory for exactly this reason — a launchd/systemd service
+ * cannot rely on the interactive login keychain.
+ *
+ * ── Design ───────────────────────────────────────────────────────────────────
+ * The OS keyring stays the PRIMARY store (used by foreground `start`, where it
+ * works and is the more-secure option). This file is a daemon-readable MIRROR:
+ * `join` writes both; the resolver falls back to the file only when the keyring
+ * returns nothing (the daemon case).
+ *
+ * Security:
+ *   - File mode 0600 (owner read/write only), parent dir 0700.
+ *   - Lives under the user's own `~/.buildhive/` — same trust boundary as the
+ *     actions/runner `.credentials` file and the workspaces dir.
+ *   - Never packaged (runtime state in $HOME, not in the npm tarball).
+ *
+ * This module is pure-where-possible: fs + homedir are injectable for tests.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promises as defaultFsPromises } from 'node:fs';
+/** Basename of the credential mirror file under `~/.buildhive/`. */
+export const CREDENTIAL_FILE_NAME = 'agent-enrollment.cred';
+const defaultFs = {
+    mkdir: (p, o) => defaultFsPromises.mkdir(p, o),
+    writeFile: (p, d, o) => defaultFsPromises.writeFile(p, d, o),
+    chmod: (p, m) => defaultFsPromises.chmod(p, m),
+    rename: (a, b) => defaultFsPromises.rename(a, b),
+    readFile: (p, e) => defaultFsPromises.readFile(p, e),
+    unlink: (p) => defaultFsPromises.unlink(p),
+};
+/**
+ * Reads/writes the agent-enrollment credentials as a single 0600 JSON file.
+ */
+export class CredentialFileStore {
+    fs;
+    dir;
+    filePath;
+    constructor(opts = {}) {
+        this.fs = opts.fs ?? defaultFs;
+        const home = opts.homeDir ?? homedir();
+        this.dir = join(home, '.buildhive');
+        this.filePath = join(this.dir, CREDENTIAL_FILE_NAME);
+    }
+    /** Absolute path to the credential file (for diagnostics + doctor). */
+    get path() {
+        return this.filePath;
+    }
+    /**
+     * Atomically write the credential mirror with 0600 perms.
+     * tmp-file → chmod 0600 → rename avoids a torn read by the daemon.
+     */
+    async write(creds) {
+        await this.fs.mkdir(this.dir, { recursive: true, mode: 0o700 });
+        const tmpPath = `${this.filePath}.tmp.${process.pid}`;
+        const payload = JSON.stringify({
+            jwt: creds.jwt,
+            jwtExpiresAtUnix: creds.jwtExpiresAtUnix,
+            agentId: creds.agentId,
+            tenantId: creds.tenantId,
+            platformUrl: creds.platformUrl,
+        });
+        await this.fs.writeFile(tmpPath, payload, { encoding: 'utf8', mode: 0o600 });
+        try {
+            // Belt-and-suspenders over the writeFile mode (umask can clear bits).
+            await this.fs.chmod(tmpPath, 0o600);
+            await this.fs.rename(tmpPath, this.filePath);
+        }
+        catch (err) {
+            // Don't leave a tmp file holding the JWT on a chmod/rename failure
+            // (ENOSPC, cross-device, mid-op crash). Best-effort cleanup, re-throw.
+            await this.fs.unlink(tmpPath).catch(() => undefined);
+            throw err;
+        }
+    }
+    /**
+     * Read the credential mirror. Returns null when absent or malformed — never
+     * throws, so the resolver can cleanly fall through to "not enrolled".
+     */
+    async read() {
+        let raw;
+        try {
+            raw = await this.fs.readFile(this.filePath, 'utf8');
+        }
+        catch {
+            return null; // ENOENT or unreadable
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        if (!parsed || typeof parsed !== 'object')
+            return null;
+        const o = parsed;
+        if (typeof o.jwt !== 'string' ||
+            typeof o.agentId !== 'string' ||
+            typeof o.tenantId !== 'string' ||
+            typeof o.platformUrl !== 'string' ||
+            o.jwt.length === 0 ||
+            o.agentId.length === 0 ||
+            o.tenantId.length === 0 ||
+            o.platformUrl.length === 0) {
+            return null;
+        }
+        const exp = typeof o.jwtExpiresAtUnix === 'number' ? o.jwtExpiresAtUnix : 0;
+        return {
+            jwt: o.jwt,
+            jwtExpiresAtUnix: Number.isFinite(exp) ? exp : 0,
+            agentId: o.agentId,
+            tenantId: o.tenantId,
+            platformUrl: o.platformUrl,
+        };
+    }
+    /** Delete the credential mirror. Idempotent (ENOENT is not an error). */
+    async delete() {
+        try {
+            await this.fs.unlink(this.filePath);
+        }
+        catch {
+            // best-effort — file may already be gone
+        }
+    }
+}

package/dist/auth/joinCommand.d.ts

@@ -38,6 +38,21 @@ export interface ServiceInstallerInjection {
         paths: ServicePaths;
         bootstrapStdout: string;
     }>;
+    /**
+     * Row 21b / Fix D — read the launchd service health after bootstrap so
+     * `join` can self-verify the daemon actually started (instead of silently
+     * installing a crashlooping daemon). Optional: when omitted, the real
+     * `getServiceStatus` is used via dynamic import.
+     */
+    readonly getServiceStatus?: (opts: {
+        mode: 'user' | 'system';
+        label?: string;
+        homeDir?: string;
+    }) => Promise<{
+        loaded: boolean;
+        state: 'running' | 'waiting' | 'unknown' | null;
+        lastExitCode: number | null;
+    }>;
 }
 export interface JoinOptions {
     readonly token: string;
@@ -69,6 +84,14 @@ export interface JoinOptions {
      * the test runner, not at dist/cli.js).
      */
     readonly cliEntryPathOverride?: string;
+    /**
+     * Row 21b / Fix D — how long to wait after bootstrap before reading the
+     * daemon's launchd health (gives RunAtLoad + the FB16131937 startup guard
+     * time to fire). Default 3000ms; tests pass 0.
+     */
+    readonly verifyDelayMs?: number;
+    /** Sleep injection for the Fix-D verify delay (tests pass a no-op). */
+    readonly sleepFn?: (ms: number) => Promise<void>;
 }
 export interface JoinResult {
     readonly exitCode: 0 | 1 | 2 | 3;

package/dist/auth/joinCommand.js

@@ -195,19 +195,24 @@ export async function runJoin(opts) {
     }
     // 8. Print enrollment success.
     const agentIdShort = agentId.slice(0, 8);
-    console.log(`✓ Agent enrolled in team "${teamName}" as agent ${agentIdShort}…`);
+    // teamName is cosmetic; guard against an older/forward backend that omits it.
+    console.log(`✓ Agent enrolled in team "${teamName ?? '(unknown)'}" as agent ${agentIdShort}…`);
     console.log(`✓ JWT stored in OS keyring (expires ${expiresDate}).`);
     // 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).
+    //    Row 21b / Fix D: maybeInstallLaunchAgent ALSO self-verifies the daemon
+    //    actually came up; it returns false (with a loud message) when the daemon
+    //    installed but crashed, so we never claim "set and forget" falsely.
     const serviceInstalled = await maybeInstallLaunchAgent(opts);
     if (serviceInstalled) {
-        console.log('✓ Agent installed and will auto-start on every login. ' +
+        console.log('✓ Agent installed and running — it 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.
+        // Either non-macOS, opt-out, install failed, OR the daemon did not start
+        // cleanly (Fix D). maybeInstallLaunchAgent already printed the specific
+        // reason; give the foreground fallback the user can always run.
         console.log('Run `buildhive-agent start` to begin picking up workflow jobs.');
     }
     return { exitCode: 0, serviceInstalled };
@@ -265,7 +270,6 @@ async function maybeInstallLaunchAgent(opts) {
     }
     try {
         await installFn({ mode: 'user', cliEntryPath });
-        return true;
     }
     catch (err) {
         // Already-loaded-service is a benign case — installService's atomic
@@ -277,6 +281,56 @@ async function maybeInstallLaunchAgent(opts) {
             'or run the agent in the foreground via `buildhive-agent start`.');
         return false;
     }
+    // Row 21b / Fix D — self-verify the daemon actually started. The 2026-06-01
+    // walk installed a daemon that crashlooped silently (last exit code = 1) yet
+    // join reported success. Now we wait, read launchd health, and fail LOUD.
+    return verifyDaemonStarted(opts);
+}
+/**
+ * Fix D: after bootstrap, give launchd's RunAtLoad + the FB16131937 startup
+ * guard a moment to fire, then read the daemon's health. Returns true only when
+ * the daemon is genuinely up (loaded, not crashed). On a crash it prints an
+ * actionable message and returns false so `join` recommends the foreground
+ * fallback instead of claiming "set and forget".
+ */
+async function verifyDaemonStarted(opts) {
+    const sleep = opts.sleepFn ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const delay = opts.verifyDelayMs ?? 3000;
+    // Resolve the status reader (injected for tests, real one otherwise).
+    let statusFn;
+    if (opts.serviceInstaller?.getServiceStatus) {
+        statusFn = opts.serviceInstaller.getServiceStatus;
+    }
+    else {
+        try {
+            const mod = await import('../service/serviceInstaller.js');
+            statusFn = mod.getServiceStatus;
+        }
+        catch {
+            // Can't verify — assume installed (don't block enrollment), but say so.
+            console.error('[join] Service installed; could not verify daemon health automatically.');
+            return true;
+        }
+    }
+    await sleep(delay);
+    let status;
+    try {
+        status = await statusFn({ mode: 'user' });
+    }
+    catch {
+        console.error('[join] Service installed; could not read daemon health (launchctl print failed).');
+        return true;
+    }
+    const crashed = status.lastExitCode !== null && status.lastExitCode !== 0;
+    if (!status.loaded || crashed) {
+        console.error('[join] ⚠ The background service was installed but did NOT start cleanly' +
+            (crashed ? ` (last exit code = ${status.lastExitCode}).` : ' (not loaded).'));
+        console.error('[join]   Diagnose with `buildhive-agent doctor`, read the log with ' +
+            '`buildhive-agent logs` (~/.buildhive/logs/buildhive-agent.log), ' +
+            'or run `buildhive-agent start` in the foreground for now.');
+        return false;
+    }
+    return true;
 }
 /** Pull tenant_id from JWT payload without signature verification. */
 function extractTenantId(jwtToken) {

package/dist/cacheServer/index.d.ts

@@ -33,7 +33,7 @@ export interface CacheServerOptions {
 }
 /**
  * Hit/miss/bytes snapshot of the cache server's runtime counters.
- * Row 18b Wave 3 / S6 — consumed by the agent's cacheStatsReporter.
+ * Row 18b Wave 3 / S6 — exposed via the cache server's getStats().
  */
 export interface CacheServerStats {
     /** Number of GET /cache requests that returned 200 (cache hit). */