@phigon/observer 8.1.0 → 8.3.0

package/dist/src/observer-log.d.ts

@@ -0,0 +1,50 @@
+import type { ObserverLogLevel } from "./config.js";
+/** The log folder in the data directory, and the file the observer writes. */
+export declare const logDirectoryName = "logs";
+export declare const logFileName = "observer.log";
+/** About 5 MB per file and three files: the current one and two older ones. */
+export declare const defaultLogFileBytes: number;
+export declare const defaultLogFiles = 3;
+export declare function logFilePath(dataDirectory: string): string;
+/**
+ * `PHIGON_LOG_LEVEL`, read before the rest of the configuration so that a
+ * configuration error is logged too. An invalid value logs at info; the
+ * configuration check then reports it.
+ */
+export declare function logLevelFrom(value: string | undefined): ObserverLogLevel;
+export type RotatingLogFileOptions = Readonly<{
+    maxBytes?: number;
+    files?: number;
+    now?: () => Date;
+    /** Told once when the file cannot be written; logging then stops. */
+    onFailure?: (message: string) => void;
+}>;
+/**
+ * A log file in the data directory that a background service keeps, since
+ * a scheduled task or LaunchAgent throws its output away. It is written
+ * synchronously, one short line at a time, and rotated by size, so it never
+ * holds anything in memory and never grows past `files` × `maxBytes`. It
+ * only ever receives messages that are already safe to print.
+ */
+export declare class RotatingLogFile {
+    #private;
+    constructor(dataDirectory: string, options?: RotatingLogFileOptions);
+    get path(): string;
+    write(level: ObserverLogLevel, message: string): void;
+}
+export type LogOutput = Readonly<{
+    stdout: (value: string) => void;
+    stderr: (value: string) => void;
+}>;
+/** `LogOutput` that also takes errors and debug details. */
+export type LevelledOutput = LogOutput & Readonly<{
+    error: (value: string) => void;
+    debug: (value: string) => void;
+}>;
+/**
+ * Applies `PHIGON_LOG_LEVEL` to what a command prints and copies each
+ * message it keeps to the log file: status lines are info, problems on
+ * stderr are warnings, and the message a command fails with is an error.
+ */
+export declare function levelledOutput(output: LogOutput, level: ObserverLogLevel, log?: RotatingLogFile): LevelledOutput;
+//# sourceMappingURL=observer-log.d.ts.map

package/dist/src/observer-log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-log.d.ts","sourceRoot":"","sources":["../../src/observer-log.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAGpD,8EAA8E;AAC9E,eAAO,MAAM,gBAAgB,SAAS,CAAC;AACvC,eAAO,MAAM,WAAW,iBAAiB,CAAC;AAC1C,+EAA+E;AAC/E,eAAO,MAAM,mBAAmB,QAAkB,CAAC;AACnD,eAAO,MAAM,eAAe,IAAI,CAAC;AAUjC,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,gBAAgB,CAExE;AAED,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IACjB,qEAAqE;IACrE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACvC,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,qBAAa,eAAe;;gBAUd,aAAa,EAAE,MAAM,EAAE,OAAO,GAAE,sBAA2B;IASvE,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,KAAK,CAAC,KAAK,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;CAsDtD;AASD,MAAM,MAAM,SAAS,GAAG,QAAQ,CAAC;IAC/B,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAChC,MAAM,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CACjC,CAAC,CAAC;AAEH,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG,QAAQ,CAAC;IAChD,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC,CAAC,CAAC;AAEH;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,gBAAgB,EACvB,GAAG,CAAC,EAAE,eAAe,GACpB,cAAc,CAchB"}

package/dist/src/observer-log.js

@@ -0,0 +1,141 @@
+import { appendFileSync, existsSync, mkdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { atomicReplaceSync } from "./atomic-replace.js";
+import { makeDirectoryPrivateSync } from "./private-directory.js";
+/** The log folder in the data directory, and the file the observer writes. */
+export const logDirectoryName = "logs";
+export const logFileName = "observer.log";
+/** About 5 MB per file and three files: the current one and two older ones. */
+export const defaultLogFileBytes = 5 * 1024 * 1024;
+export const defaultLogFiles = 3;
+const maxLineBytes = 4 * 1024;
+const severity = Object.freeze({
+    debug: 10,
+    info: 20,
+    warn: 30,
+    error: 40,
+});
+export function logFilePath(dataDirectory) {
+    return join(dataDirectory, logDirectoryName, logFileName);
+}
+/**
+ * `PHIGON_LOG_LEVEL`, read before the rest of the configuration so that a
+ * configuration error is logged too. An invalid value logs at info; the
+ * configuration check then reports it.
+ */
+export function logLevelFrom(value) {
+    return value === "debug" || value === "warn" || value === "error" ? value : "info";
+}
+/**
+ * A log file in the data directory that a background service keeps, since
+ * a scheduled task or LaunchAgent throws its output away. It is written
+ * synchronously, one short line at a time, and rotated by size, so it never
+ * holds anything in memory and never grows past `files` × `maxBytes`. It
+ * only ever receives messages that are already safe to print.
+ */
+export class RotatingLogFile {
+    #dataDirectory;
+    #path;
+    #maxBytes;
+    #files;
+    #now;
+    #onFailure;
+    #size;
+    #failed = false;
+    constructor(dataDirectory, options = {}) {
+        this.#dataDirectory = dataDirectory;
+        this.#path = logFilePath(dataDirectory);
+        this.#maxBytes = options.maxBytes ?? defaultLogFileBytes;
+        this.#files = Math.max(1, options.files ?? defaultLogFiles);
+        this.#now = options.now ?? (() => new Date());
+        this.#onFailure = options.onFailure;
+    }
+    get path() {
+        return this.#path;
+    }
+    write(level, message) {
+        if (this.#failed)
+            return;
+        const stamp = this.#now().toISOString();
+        const label = level.toUpperCase().padEnd(5);
+        const text = message
+            .split(/\r?\n/u)
+            .map(clean)
+            .filter((line) => line.length > 0)
+            .map((line) => `${stamp} ${label} ${line}\n`)
+            .join("");
+        if (text.length === 0)
+            return;
+        try {
+            if (this.#size === undefined)
+                this.#size = this.#open();
+            const bytes = Buffer.byteLength(text, "utf8");
+            if (this.#size > 0 && this.#size + bytes > this.#maxBytes) {
+                this.#rotate();
+                this.#size = 0;
+            }
+            appendFileSync(this.#path, text, { encoding: "utf8", mode: 0o600 });
+            this.#size += bytes;
+        }
+        catch {
+            // The observer keeps running without its log; say so once.
+            this.#failed = true;
+            this.#onFailure?.(`The observer log could not be written to ${this.#path}; messages are no longer logged there.\n`);
+        }
+    }
+    #open() {
+        const directory = join(this.#dataDirectory, logDirectoryName);
+        if (!existsSync(this.#dataDirectory)) {
+            mkdirSync(this.#dataDirectory, { recursive: true, mode: 0o700 });
+        }
+        makeDirectoryPrivateSync(this.#dataDirectory);
+        mkdirSync(directory, { recursive: true, mode: 0o700 });
+        try {
+            return statSync(this.#path).size;
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                return 0;
+            throw error;
+        }
+    }
+    #rotate() {
+        for (let index = this.#files - 1; index >= 1; index--) {
+            const from = index === 1 ? this.#path : `${this.#path}.${index - 1}`;
+            if (existsSync(from))
+                atomicReplaceSync(from, `${this.#path}.${index}`);
+        }
+        // With a single file there is nothing to keep: start it again.
+        if (this.#files === 1 && existsSync(this.#path)) {
+            appendFileSync(this.#path, "", { flag: "w" });
+        }
+    }
+}
+/** Drops control characters, such as terminal colour codes, and caps the length. */
+function clean(line) {
+    const printable = line.replace(/[\u0000-\u0008\u000b-\u001f\u007f\u009b]/gu, "").trimEnd();
+    if (Buffer.byteLength(printable, "utf8") <= maxLineBytes)
+        return printable;
+    return `${Buffer.from(printable, "utf8").subarray(0, maxLineBytes).toString("utf8").replace(/�$/u, "")}…`;
+}
+/**
+ * Applies `PHIGON_LOG_LEVEL` to what a command prints and copies each
+ * message it keeps to the log file: status lines are info, problems on
+ * stderr are warnings, and the message a command fails with is an error.
+ */
+export function levelledOutput(output, level, log) {
+    const emit = (messageLevel, write) => (value) => {
+        if (severity[messageLevel] < severity[level])
+            return;
+        // The log first: a background service's console may already be gone.
+        log?.write(messageLevel, value);
+        write(value);
+    };
+    return Object.freeze({
+        stdout: emit("info", output.stdout),
+        stderr: emit("warn", output.stderr),
+        error: emit("error", output.stderr),
+        debug: emit("debug", output.stdout),
+    });
+}
+//# sourceMappingURL=observer-log.js.map

package/dist/src/observer-log.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observer-log.js","sourceRoot":"","sources":["../../src/observer-log.ts"],"names":[],"mappings":"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"}

package/dist/src/pair.d.ts

@@ -1,14 +1,43 @@
 import type { ObserverConfig } from "./config.js";
-import { type CredentialStore } from "./credential-store.js";
+import { type CredentialStore, type StoredMachineCredential } from "./credential-store.js";
 export declare const OBSERVER_CONSENT_POLICY_VERSION = "observer-policy-v1";
 export type ConsentProfile = "metadata" | "full";
+export type PairingMachine = Readonly<{
+    id: string;
+    tenant_id: string;
+    display_name: string;
+    state: string;
+}>;
+/** What the pairing exchange and an enrollment both answer with. */
+export type ConnectedMachine = Readonly<{
+    machine: PairingMachine;
+    credential: string;
+}>;
 export type PairResult = Readonly<{
     machineId: string;
     displayName: string;
     state: string;
     controlPlaneOrigin: string;
     credentialStored: true;
+    /**
+     * The earlier machine this computer was paired as, when the workspace no
+     * longer accepted its key and the computer was paired as a new machine.
+     */
+    replacedMachineId?: string;
+}>;
+/**
+ * One exchange with the control plane. A failure other than a stored key
+ * the server refused is `credentialRejected: false`, and its error is
+ * thrown as is.
+ */
+export type ExchangeOutcome<T extends ConnectedMachine> = Readonly<{
+    paired: T;
+}> | Readonly<{
+    error: Error;
+    credentialRejected: boolean;
 }>;
+/** The consent evidence a connection stores with the machine credential. */
+export type ConsentEvidence = Pick<StoredMachineCredential, "consentProfile" | "consentPolicyVersion" | "consentedAt" | "consentSource" | "enrollmentCodeId" | "enrollmentCodeLabel">;
 export type PairOptions = Readonly<{
     config: ObserverConfig;
     code: string;
@@ -18,4 +47,42 @@ export type PairOptions = Readonly<{
     fetcher?: typeof fetch;
 }>;
 export declare function pairMachine(options: PairOptions): Promise<PairResult>;
+export type ConnectOptions<T extends ConnectedMachine> = Readonly<{
+    config: ObserverConfig;
+    endpoint: URL;
+    fetcher: typeof fetch;
+    credentialStore?: CredentialStore;
+    /** Exchanges a code for this installation, with the stored key if any. */
+    exchange: (installationID: string, existingCredential?: string) => Promise<ExchangeOutcome<T>>;
+    /** The consent evidence to store with the credential `paired` returned. */
+    evidence: (paired: T, at: string) => ConsentEvidence;
+}>;
+/**
+ * Connects this computer with a code, keeping its machine when the server
+ * still accepts its stored key: pairing again, or enrolling, renews consent
+ * and keeps the same machine, so its queued activity stays deliverable.
+ * When the server no longer accepts the key, the computer connects as a
+ * new machine and its old queue moves aside.
+ */
+export declare function connectMachine<T extends ConnectedMachine>(options: ConnectOptions<T>): Promise<Readonly<{
+    paired: T;
+    result: PairResult;
+}>>;
+/**
+ * Whether a failed exchange refused the stored key. The server answers a
+ * key it no longer accepts with HTTP 400 and "machine credential is
+ * invalid".
+ */
+export declare function credentialRejected(status: number, failure: Readonly<{
+    code?: string;
+    message?: string;
+}>): boolean;
+/** A response with a machine and a machine credential. */
+export declare function isConnectedMachine(value: unknown): value is ConnectedMachine;
+/** The `{ error: { code, message } }` body of a failed control-plane call. */
+export declare function apiError(response: Response): Promise<Readonly<{
+    code?: string;
+    message?: string;
+}>>;
+export declare function normalizedOperatingSystem(): "macos" | "linux" | "windows";
 //# sourceMappingURL=pair.d.ts.map

package/dist/src/pair.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pair.d.ts","sourceRoot":"","sources":["../../src/pair.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAEL,KAAK,eAAe,EACrB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,+BAA+B,uBAAuB,CAAC;AACpE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,CAAC;AAcjD,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,IAAI,CAAC;CACxB,CAAC,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,CAAC,CAAC;AAEH,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA8F3E"}
+{"version":3,"file":"pair.d.ts","sourceRoot":"","sources":["../../src/pair.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAGL,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC7B,MAAM,uBAAuB,CAAC;AAK/B,eAAO,MAAM,+BAA+B,uBAAuB,CAAC;AACpE,MAAM,MAAM,cAAc,GAAG,UAAU,GAAG,MAAM,CAAC;AAEjD,MAAM,MAAM,cAAc,GAAG,QAAQ,CAAC;IACpC,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;CACf,CAAC,CAAC;AAEH,oEAAoE;AACpE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,OAAO,EAAE,cAAc,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,MAAM,UAAU,GAAG,QAAQ,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gBAAgB,EAAE,IAAI,CAAC;IACvB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B,CAAC,CAAC;AAEH;;;;GAIG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,SAAS,gBAAgB,IAClD,QAAQ,CAAC;IAAE,MAAM,EAAE,CAAC,CAAA;CAAE,CAAC,GACvB,QAAQ,CAAC;IAAE,KAAK,EAAE,KAAK,CAAC;IAAC,kBAAkB,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAE5D,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GAAG,IAAI,CAChC,uBAAuB,EACrB,gBAAgB,GAChB,sBAAsB,GACtB,aAAa,GACb,eAAe,GACf,kBAAkB,GAClB,qBAAqB,CACxB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG,QAAQ,CAAC;IACjC,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,cAAc,CAAC;IAC/B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;CACxB,CAAC,CAAC;AAEH,wBAAsB,WAAW,CAAC,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CA6C3E;AAED,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,gBAAgB,IAAI,QAAQ,CAAC;IAChE,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,GAAG,CAAC;IACd,OAAO,EAAE,OAAO,KAAK,CAAC;IACtB,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,0EAA0E;IAC1E,QAAQ,EAAE,CAAC,cAAc,EAAE,MAAM,EAAE,kBAAkB,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/F,2EAA2E;IAC3E,QAAQ,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,EAAE,MAAM,KAAK,eAAe,CAAC;CACtD,CAAC,CAAC;AAEH;;;;;;GAMG;AACH,wBAAsB,cAAc,CAAC,CAAC,SAAS,gBAAgB,EAC7D,OAAO,EAAE,cAAc,CAAC,CAAC,CAAC,GACzB,OAAO,CAAC,QAAQ,CAAC;IAAE,MAAM,EAAE,CAAC,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC,CAAC,CAkFtD;AA6DD;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,QAAQ,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GACrD,OAAO,CAIT;AA4CD,0DAA0D;AAC1D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,gBAAgB,CAiB5E;AAED,8EAA8E;AAC9E,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,QAAQ,GACjB,OAAO,CAAC,QAAQ,CAAC;IAAE,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,CAwBxD;AAED,wBAAgB,yBAAyB,IAAI,OAAO,GAAG,OAAO,GAAG,SAAS,CAKzE"}

package/dist/src/pair.js

@@ -1,25 +1,141 @@
 import { arch, hostname, platform } from "node:os";
-import { FileCredentialStore, } from "./credential-store.js";
-import { loadOrCreateInstallationID } from "./installation.js";
+import { FileCredentialStore, credentialFileName, } from "./credential-store.js";
+import { retirePairingState } from "./event-spool.js";
+import { installationFileName, loadOrCreateInstallationID } from "./installation.js";
+import { InstanceLock } from "./instance-lock.js";
 export const OBSERVER_CONSENT_POLICY_VERSION = "observer-policy-v1";
 export async function pairMachine(options) {
     const code = options.code.trim();
     if (code.length === 0) {
         throw new Error("Pairing code is required.");
     }
-    const installationID = await loadOrCreateInstallationID(options.config.dataDirectory);
     if (options.config.observabilityProfile === "full" &&
         options.consentProfile !== "full") {
         throw new Error("The configured full observability profile requires full-content consent.");
     }
     const endpoint = new URL("/v1/pairing/exchange", options.config.controlPlaneUrl);
     const fetcher = options.fetcher ?? fetch;
+    const connected = await connectMachine({
+        config: options.config,
+        endpoint,
+        fetcher,
+        ...(options.credentialStore === undefined ? {} : { credentialStore: options.credentialStore }),
+        exchange: (installationID, existingCredential) => exchangePairing(fetcher, endpoint, {
+            code,
+            installation_id: installationID,
+            display_name: options.displayName?.trim() || hostname(),
+            hostname: hostname(),
+            operating_system: normalizedOperatingSystem(),
+            architecture: arch(),
+            consent: {
+                granted: true,
+                profile: options.consentProfile,
+                policy_version: OBSERVER_CONSENT_POLICY_VERSION,
+            },
+            ...(existingCredential === undefined ? {} : { existing_credential: existingCredential }),
+        }),
+        evidence: (_paired, at) => ({
+            consentProfile: options.consentProfile,
+            consentPolicyVersion: OBSERVER_CONSENT_POLICY_VERSION,
+            consentedAt: at,
+            consentSource: "owner",
+        }),
+    });
+    return connected.result;
+}
+/**
+ * Connects this computer with a code, keeping its machine when the server
+ * still accepts its stored key: pairing again, or enrolling, renews consent
+ * and keeps the same machine, so its queued activity stays deliverable.
+ * When the server no longer accepts the key, the computer connects as a
+ * new machine and its old queue moves aside.
+ */
+export async function connectMachine(options) {
+    const dataDirectory = options.config.dataDirectory;
+    const installationID = await loadOrCreateInstallationID(dataDirectory);
     const credentialStore = options.credentialStore ??
-        new FileCredentialStore(options.config.dataDirectory);
+        new FileCredentialStore(dataDirectory);
     const previous = await credentialStore.load();
-    if (previous !== null && previous.controlPlaneOrigin !== endpoint.origin) {
+    if (previous !== null && previous.controlPlaneOrigin !== options.endpoint.origin) {
         throw new Error("The stored machine belongs to a different control plane. Use a separate data directory to pair another workspace.");
     }
+    let paired;
+    if (previous !== null) {
+        const renewal = await options.exchange(installationID, previous.credential);
+        if ("paired" in renewal) {
+            paired = renewal.paired;
+        }
+        else if (!renewal.credentialRejected) {
+            throw renewal.error;
+        }
+        else if (await credentialStillAccepted(options.fetcher, options.config.controlPlaneUrl, previous.credential)) {
+            // The exchange also refuses a key that is valid in another workspace.
+            throw new Error("This computer is paired with another workspace on this server. Use a separate data directory to pair another workspace.");
+        }
+    }
+    let lock;
+    try {
+        if (paired === undefined || !sameMachine(previous, paired)) {
+            // A new machine. Its queue, stream cursor and credential start empty;
+            // the observer must not be using the old ones while they move.
+            lock = await InstanceLock.acquire(dataDirectory);
+            // The old credential goes with its queue: it is the only key that can
+            // decrypt it. Once it is gone, a retry after a lost response pairs
+            // without it, and the server answers with the same new machine.
+            //
+            // A key the server no longer accepts also retires its installation ID:
+            // a server can still hold that ID for the deleted machine, and the
+            // built-in SQLite server refuses to pair it again. A new ID pairs
+            // cleanly everywhere.
+            const replacing = paired === undefined && previous !== null;
+            retirePairingState(dataDirectory, previous?.machineId, [
+                credentialFileName,
+                ...(replacing ? [installationFileName] : []),
+            ]);
+            if (paired === undefined) {
+                const freshInstallationID = replacing
+                    ? await loadOrCreateInstallationID(dataDirectory)
+                    : installationID;
+                const fresh = await options.exchange(freshInstallationID);
+                if (!("paired" in fresh))
+                    throw fresh.error;
+                paired = fresh.paired;
+            }
+        }
+        const pairedAt = new Date().toISOString();
+        await credentialStore.save({
+            machineId: paired.machine.id,
+            tenantId: paired.machine.tenant_id,
+            credential: paired.credential,
+            controlPlaneOrigin: options.config.controlPlaneUrl.origin,
+            grpcOrigin: options.config.grpcUrl.origin,
+            createdAt: pairedAt,
+            ...options.evidence(paired, pairedAt),
+        });
+    }
+    finally {
+        await lock?.release();
+    }
+    const replaced = previous !== null && previous.machineId !== paired.machine.id;
+    return Object.freeze({
+        paired,
+        result: Object.freeze({
+            machineId: paired.machine.id,
+            displayName: paired.machine.display_name,
+            state: paired.machine.state,
+            controlPlaneOrigin: options.config.controlPlaneUrl.origin,
+            credentialStored: true,
+            ...(replaced ? { replacedMachineId: previous.machineId } : {}),
+        }),
+    });
+}
+function sameMachine(previous, paired) {
+    return previous !== null &&
+        previous.machineId === paired.machine.id &&
+        previous.tenantId === paired.machine.tenant_id &&
+        previous.credential === paired.credential;
+}
+async function exchangePairing(fetcher, endpoint, body) {
     let response;
     try {
         response = await fetcher(endpoint, {
@@ -28,20 +144,7 @@ export async function pairMachine(options) {
                 "Content-Type": "application/json",
                 Accept: "application/json",
             },
-            body: JSON.stringify({
-                code,
-                ...(previous === null ? {} : { existing_credential: previous.credential }),
-                installation_id: installationID,
-                display_name: options.displayName?.trim() || hostname(),
-                hostname: hostname(),
-                operating_system: normalizedOperatingSystem(),
-                architecture: arch(),
-                consent: {
-                    granted: true,
-                    profile: options.consentProfile,
-                    policy_version: OBSERVER_CONSENT_POLICY_VERSION,
-                },
-            }),
+            body: JSON.stringify(body),
             redirect: "error",
             signal: AbortSignal.timeout(10_000),
         });
@@ -53,7 +156,11 @@ export async function pairMachine(options) {
         throw new Error(`Could not reach ${endpoint.origin}. Check your internet connection and try again.`);
     }
     if (!response.ok) {
-        throw new Error(await pairingFailureMessage(response));
+        const failure = await apiError(response);
+        return {
+            error: new Error(failure.message ?? `Pairing failed with HTTP ${response.status}.`),
+            credentialRejected: credentialRejected(response.status, failure),
+        };
     }
     let value;
     try {
@@ -64,66 +171,98 @@ export async function pairMachine(options) {
         // print fragments. The server supports retries for this installation.
         throw new Error("The pairing response was incomplete or invalid. Retry with the same code before it expires; keep the existing data directory.");
     }
-    const paired = parsePairingResponse(value);
-    await credentialStore.save({
-        machineId: paired.machine.id,
-        tenantId: paired.machine.tenant_id,
-        credential: paired.credential,
-        controlPlaneOrigin: options.config.controlPlaneUrl.origin,
-        grpcOrigin: options.config.grpcUrl.origin,
-        createdAt: new Date().toISOString(),
-        consentProfile: options.consentProfile,
-        consentPolicyVersion: OBSERVER_CONSENT_POLICY_VERSION,
-        consentedAt: new Date().toISOString(),
-    });
-    return Object.freeze({
-        machineId: paired.machine.id,
-        displayName: paired.machine.display_name,
-        state: paired.machine.state,
-        controlPlaneOrigin: options.config.controlPlaneUrl.origin,
-        credentialStored: true,
-    });
-}
-function parsePairingResponse(value) {
-    if (typeof value !== "object" ||
-        value === null ||
-        !("credential" in value) ||
-        typeof value.credential !== "string" ||
-        !value.credential.startsWith("phg_m_") ||
-        !("machine" in value) ||
-        typeof value.machine !== "object" ||
-        value.machine === null ||
-        !("id" in value.machine) ||
-        typeof value.machine.id !== "string" ||
-        !("tenant_id" in value.machine) ||
-        typeof value.machine.tenant_id !== "string" ||
-        !("display_name" in value.machine) ||
-        typeof value.machine.display_name !== "string" ||
-        !("state" in value.machine) ||
-        typeof value.machine.state !== "string") {
+    if (!isConnectedMachine(value)) {
         throw new Error("Control plane returned an invalid pairing response.");
     }
-    return value;
+    return { paired: value };
+}
+/**
+ * Whether a failed exchange refused the stored key. The server answers a
+ * key it no longer accepts with HTTP 400 and "machine credential is
+ * invalid".
+ */
+export function credentialRejected(status, failure) {
+    return failure.code === "invalid_credential" ||
+        (status === 400 &&
+            /^machine credential is (?:invalid|revoked)\b/iu.test(failure.message ?? ""));
+}
+/**
+ * Whether a server still accepts a stored key. Only a key the server
+ * itself calls invalid or revoked, because an administrator removed the
+ * computer or revoked the key, may be set aside for a new pairing.
+ */
+async function credentialStillAccepted(fetcher, controlPlaneUrl, credential) {
+    const endpoint = new URL("/v1/machine/heartbeat", controlPlaneUrl);
+    let response;
+    try {
+        response = await fetcher(endpoint, {
+            method: "POST",
+            headers: {
+                Authorization: `Bearer ${credential}`,
+                Accept: "application/json",
+            },
+            redirect: "error",
+            signal: AbortSignal.timeout(10_000),
+        });
+    }
+    catch {
+        throw new Error(`Could not reach ${endpoint.origin} to check this computer's earlier pairing. Check your internet connection and try again.`);
+    }
+    if (response.ok) {
+        await response.body?.cancel();
+        return true;
+    }
+    if (response.status === 401 &&
+        (await apiError(response)).code === "invalid_credential") {
+        return false;
+    }
+    throw new Error(`Could not check this computer's earlier pairing (HTTP ${response.status}). Try again.`);
+}
+/** A response with a machine and a machine credential. */
+export function isConnectedMachine(value) {
+    return typeof value === "object" &&
+        value !== null &&
+        "credential" in value &&
+        typeof value.credential === "string" &&
+        value.credential.startsWith("phg_m_") &&
+        "machine" in value &&
+        typeof value.machine === "object" &&
+        value.machine !== null &&
+        "id" in value.machine &&
+        typeof value.machine.id === "string" &&
+        "tenant_id" in value.machine &&
+        typeof value.machine.tenant_id === "string" &&
+        "display_name" in value.machine &&
+        typeof value.machine.display_name === "string" &&
+        "state" in value.machine &&
+        typeof value.machine.state === "string";
 }
-async function pairingFailureMessage(response) {
+/** The `{ error: { code, message } }` body of a failed control-plane call. */
+export async function apiError(response) {
     try {
         const value = await response.json();
         if (typeof value === "object" &&
             value !== null &&
             "error" in value &&
             typeof value.error === "object" &&
-            value.error !== null &&
-            "message" in value.error &&
-            typeof value.error.message === "string") {
-            return value.error.message;
+            value.error !== null) {
+            const error = value.error;
+            return {
+                ...("code" in error && typeof error.code === "string"
+                    ? { code: error.code }
+                    : {}),
+                ...("message" in error && typeof error.message === "string"
+                    ? { message: error.message }
+                    : {}),
+            };
         }
     }
     catch {
         // The status code still provides an actionable, non-sensitive failure.
     }
-    return `Pairing failed with HTTP ${response.status}.`;
+    return {};
 }
-function normalizedOperatingSystem() {
+export function normalizedOperatingSystem() {
     const value = platform();
     if (value === "darwin")
         return "macos";