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

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

@@ -2,15 +2,58 @@
  * `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;
+    }>;
+    /**
+     * 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;
     readonly platformUrl: string;
@@ -18,10 +61,47 @@ 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;
+    /**
+     * 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;
     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.