@phigon/observer 8.1.0 → 8.3.0

package/dist/src/cli.js

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
 import { create, toJsonString } from "@bufbuild/protobuf";
 import { timestampDate, timestampFromDate } from "@bufbuild/protobuf/wkt";
-import { constants, realpathSync } from "node:fs";
+import { constants, readFileSync, realpathSync } from "node:fs";
 import { access, readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { FileActionPolicyStore, managedActionNames, } from "./action-policy.js";
@@ -10,7 +11,7 @@ import { GuardianDecisionUnavailableError, HTTPGuardianDecisionClient, readGuard
 import { AgentActionExecutor } from "./agent-action-executor.js";
 import { ActivityCollector, historySyncQueueHeadroom, mergeInventoryWithSourceIdentities, registeredAgentActivitySources, } from "./activity/collector.js";
 import { ingestActivityJSONL } from "./activity/ingest.js";
-import { loadConfig, DEFAULT_CONTROL_PLANE_ORIGIN, } from "./config.js";
+import { consentedCollectionPolicy, contentOutsideProfileMessage, dataDirectoryFrom, loadConfig, DEFAULT_CONTROL_PLANE_ORIGIN, } from "./config.js";
 import { FileCredentialStore } from "./credential-store.js";
 import { CustomAgentRegistry, customAgentRegistration, } from "./custom-agent-registry.js";
 import { DiscoveryEngine, runDiscoveryLoop, } from "./discovery/index.js";
@@ -18,9 +19,16 @@ import { AgentState } from "./generated/phigon/v1/common_pb.js";
 import { AgentInventorySchema } from "./generated/phigon/v1/identity_pb.js";
 import { HistorySyncResultSchema, HistorySyncResultState, } from "./generated/phigon/v1/history_sync_pb.js";
 import { HistoricalIdentityStore, mergeInventoryWithHistoricalIdentities, } from "./historical-identity-store.js";
-import { createHealthSnapshot, } from "./health.js";
+import { consentHealth, createHealthSnapshot, describeConsent, } from "./health.js";
 import { OBSERVER_CONSENT_POLICY_VERSION, pairMachine, } from "./pair.js";
+import { EnrollmentError, checkedEnrollmentCode, enrollMachine, enrollmentCodeVariable, } from "./enroll.js";
 import { removeMachine } from "./remove-machine.js";
+import { forgetServerAuthority, parseAuthorityFingerprint, pinServerAuthority, trustAuthority } from "./server-authority.js";
+import { readServiceSettings, startService, stopService, uninstallService } from "./service.js";
+import { runServiceCommand, serviceContext } from "./service-command.js";
+import { purgeDataDirectory, removeEmptyDataDirectory } from "./purge.js";
+import { hasByteHeadroom } from "./event-queue.js";
+import { InstanceLock, ObserverAlreadyRunningError, processIsAlive } from "./instance-lock.js";
 import { clearEventSpool } from "./event-spool.js";
 import { GuardianDecisionJournal } from "./guardian-decision-journal.js";
 import { GuardianContainmentExecutor, } from "./guardian-containment.js";
@@ -34,15 +42,29 @@ import { semanticDecision } from "./agentic-guardian.js";
 import { guardianRunnerPath } from "./guardian-native.js";
 import { GuardianProcessMonitor } from "./guardian-process-monitor.js";
 import { setTimeout as delay } from "node:timers/promises";
+import { ServerClock, describeClockSkew } from "./server-clock.js";
 import { StreamStateStore } from "./stream-state.js";
 import { connectionEnvironment } from "./connection-config.js";
 import { latestObserverVersion, newerVersion, offerObserverUpdate } from "./update.js";
+import { UserNotices } from "./user-notices.js";
+import { announceCompanyCollection } from "./collection-notice.js";
+import { defaultMaxDeliveryAgeMinutes, formatDoctorCheck, runDoctorCheck, } from "./doctor-check.js";
+import { proxyForUrl, proxySettings, useProxyFromEnvironment, } from "./proxy.js";
+import { RotatingLogFile, levelledOutput, logLevelFrom, } from "./observer-log.js";
 const defaultOutput = {
     stdout: (value) => process.stdout.write(value),
     stderr: (value) => process.stderr.write(value),
 };
-export async function run(argv, environment = process.env, output = defaultOutput, input = process.stdin) {
+export async function run(argv, environment = process.env, output = defaultOutput, input = process.stdin, dependencies = {}) {
     const [command, ...flags] = argv;
+    let logged;
+    // A background service runs `run --service-settings <file>`; the file
+    // sits in the data directory and holds the settings it was installed with.
+    const serviceSettingsFile = command === "run" ? flagValue(flags, "--service-settings") : undefined;
+    const ownEnvironment = environment === process.env;
+    if (serviceSettingsFile !== undefined) {
+        environment = { ...environment, PHIGON_DATA_DIR: dirname(resolve(serviceSettingsFile)) };
+    }
     if (command === "--version" || command === "-v" || command === "version") {
         output.stdout(`${await readVersion()}\n`);
         return 0;
@@ -61,17 +83,51 @@ export async function run(argv, environment = process.env, output = defaultOutpu
         command !== "pair" &&
         command !== "remove-machine" &&
         command !== "unpair" &&
+        command !== "service" &&
         command !== "run") {
         output.stderr(`Unknown command: ${command}\n\n${helpText()}`);
         return 2;
     }
+    if (command === "run") {
+        // A background service throws away what it prints, so `run` also keeps
+        // a log file in the data directory, at PHIGON_LOG_LEVEL.
+        const log = new RotatingLogFile(dataDirectoryFrom(environment), {
+            onFailure: (message) => output.stderr(message),
+        });
+        logged = levelledOutput(output, logLevelFrom(environment["PHIGON_LOG_LEVEL"]), log);
+        output = logged;
+    }
+    let callerEnvironment = environment;
+    let proxy;
     try {
+        if (serviceSettingsFile !== undefined) {
+            const settings = await readServiceSettings(serviceSettingsFile);
+            environment = { ...environment, ...settings, PHIGON_DATA_DIR: dirname(resolve(serviceSettingsFile)) };
+            if (ownEnvironment) {
+                // PATH (to find agents) and the proxy variables (for grpc-js) are
+                // read from the process itself.
+                Object.assign(process.env, settings);
+            }
+            callerEnvironment = environment;
+            trustExtraCertificates(settings["NODE_EXTRA_CA_CERTS"], output);
+        }
         environment = command === "update" ? { PHIGON_DATA_DIR: environment["PHIGON_DATA_DIR"] } : await connectionEnvironment(environment, command === "pair" || command === "run" || command === "doctor" ? flags : []);
         const config = loadConfig(observabilityEnvironment(command, flags, environment));
+        // Every HTTPS call and the telemetry stream go through the proxy that
+        // HTTPS_PROXY, HTTP_PROXY and NO_PROXY name, when there is one.
+        proxy = useProxyFromEnvironment(callerEnvironment, { streamUrl: config.grpcUrl });
+        if (proxy.notice !== undefined)
+            output.stderr(`${proxy.notice}\n`);
         const version = await readVersion();
         const json = flags.includes("--json");
-        const interactive = input === process.stdin && process.stdin.isTTY === true && process.stdout.isTTY === true && !json;
-        if (command === "update" || (interactive && (command === "pair" || command === "run") && environment["PHIGON_UPDATE_CHECK"] !== "false")) {
+        // The company's code a device management script enrolls with. It never
+        // prompts, so it is never offered an update either.
+        const enrollmentCode = command === "pair" ? enrollmentCodeFrom(flags, callerEnvironment) : undefined;
+        // A background service has a console under conhost on Windows, but nobody
+        // reads it: it never prompts.
+        const interactive = input === process.stdin && process.stdin.isTTY === true && process.stdout.isTTY === true && !json &&
+            serviceSettingsFile === undefined;
+        if (command === "update" || (interactive && ((command === "pair" && enrollmentCode === undefined) || command === "run") && environment["PHIGON_UPDATE_CHECK"] !== "false")) {
             const latest = await latestObserverVersion(config.dataDirectory, { force: command === "update" });
             if (command === "update" && (json || flags.includes("--check"))) {
                 output.stdout(`${JSON.stringify({ current: version, latest, updateAvailable: latest !== null && newerVersion(version, latest), status: latest === null ? "unavailable" : "checked" })}\n`);
@@ -88,6 +144,9 @@ export async function run(argv, environment = process.env, output = defaultOutpu
             }
         }
         const customAgentRegistry = new CustomAgentRegistry(config.dataDirectory);
+        if (command === "service") {
+            return await runServiceCommand(flags, config, callerEnvironment, output, json, dependencies);
+        }
         if (command === "guardian") {
             const subcommand = flags[0] ?? "status";
             if (subcommand === "exec") {
@@ -118,6 +177,8 @@ export async function run(argv, environment = process.env, output = defaultOutpu
             const action = parseManagedAction(flagValue(flags, "--action"));
             const resource = flagValue(flags, "--resource");
             const agentID = flagValue(flags, "--agent") ?? "";
+            if (agentID !== "")
+                validatedAgentID(agentID);
             const processID = parseOptionalProcessID(flagValue(flags, "--process-id"));
             const processStartedAt = flagValue(flags, "--process-started-at");
             if ((processID === undefined) !== (processStartedAt === undefined)) {
@@ -343,6 +404,9 @@ export async function run(argv, environment = process.env, output = defaultOutpu
             return result.records > 0 ? 0 : 1;
         }
         if (command === "remove-machine" || command === "unpair") {
+            if (flags.includes("--purge")) {
+                return await removeMachineAndPurge(config, callerEnvironment, flags, json, output, input, dependencies);
+            }
             const credentialStore = new FileCredentialStore(config.dataDirectory);
             const credential = await credentialStore.load();
             if (credential === null) {
@@ -351,21 +415,42 @@ export async function run(argv, environment = process.env, output = defaultOutpu
             if (json && !flags.includes("--yes")) {
                 throw new Error("JSON machine removal requires --yes after reviewing the removal scope.");
             }
-            if (!flags.includes("--yes")) {
-                output.stdout(removeMachinePrompt(credential.machineId));
-                const confirmed = await readConfirmation(input);
-                if (confirmed !== "remove") {
-                    throw new Error("Machine removal was not confirmed. No request was sent.");
+            // A running observer would keep writing the queue this removes, then
+            // stop as unpaired and be restarted by its service over and over.
+            let removalLock;
+            try {
+                removalLock = await InstanceLock.acquire(config.dataDirectory);
+            }
+            catch (error) {
+                if (!(error instanceof ObserverAlreadyRunningError))
+                    throw error;
+                throw new Error("A Phigon observer is running with this data directory. Stop it, " +
+                    "or stop its service (phigon-observer service uninstall), and then " +
+                    "run remove-machine again; remove-machine --purge stops the service " +
+                    "itself. No request was sent.");
+            }
+            let result;
+            try {
+                if (!flags.includes("--yes")) {
+                    output.stdout(removeMachinePrompt(credential.machineId));
+                    const confirmed = await readConfirmation(input);
+                    if (confirmed !== "remove") {
+                        throw new Error("Machine removal was not confirmed. No request was sent.");
+                    }
                 }
+                result = await removeMachine({
+                    config,
+                    credential,
+                    clearCredential: async () => {
+                        clearEventSpool(config.dataDirectory);
+                        await forgetServerAuthority(config.dataDirectory);
+                        return await credentialStore.clear();
+                    },
+                });
+            }
+            finally {
+                await removalLock.release();
             }
-            const result = await removeMachine({
-                config,
-                credential,
-                clearCredential: async () => {
-                    clearEventSpool(config.dataDirectory);
-                    return await credentialStore.clear();
-                },
-            });
             output.stdout(json
                 ? `${JSON.stringify(result, null, 2)}\n`
                 : formatRemoveMachineResult(result));
@@ -386,6 +471,22 @@ export async function run(argv, environment = process.env, output = defaultOutpu
             const stop = () => controller.abort();
             process.once("SIGINT", stop);
             process.once("SIGTERM", stop);
+            // On Windows the service runs the observer under conhost, and ending
+            // the scheduled task ends only conhost; stop with it.
+            // A service's console can disappear before the observer has stopped;
+            // writing to it must not end the process, the log keeps the message.
+            const ignoreConsoleError = () => undefined;
+            if (serviceSettingsFile !== undefined) {
+                process.stdout.on("error", ignoreConsoleError);
+                process.stderr.on("error", ignoreConsoleError);
+            }
+            const stopWatchingParent = serviceSettingsFile !== undefined && process.platform === "win32"
+                ? watchParentProcess(process.ppid, () => {
+                    output.stdout("The background service stopped, so the observer stops too.\n");
+                    controller.abort();
+                })
+                : undefined;
+            let instanceLock;
             try {
                 const credential = await new FileCredentialStore(config.dataDirectory).load();
                 if (credential === null) {
@@ -404,7 +505,15 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                     credential.consentProfile !== "full") {
                     throw new Error("Full-content collection is outside the consented metadata profile.");
                 }
-                let effectivePolicy = intersectCollectionPolicy(config.policy);
+                if (config.contentSettingsOutsideProfile.length > 0) {
+                    throw new Error(contentOutsideProfileMessage(config.contentSettingsOutsideProfile));
+                }
+                // Before any queued activity, cursor or saved state is read. A
+                // signal only aborts the tasks, so `finally` releases the lock.
+                instanceLock = await InstanceLock.acquire(config.dataDirectory);
+                logged?.debug(`Observer ${version} started for machine ${credential.machineId} ` +
+                    `with the ${config.observabilityProfile} profile, using ${config.dataDirectory}.\n`);
+                let effectivePolicy = intersectCollectionPolicy(config.policy, credential.consentProfile);
                 let collector;
                 let resolveCollector;
                 const collectorReady = new Promise((resolve) => {
@@ -414,16 +523,24 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                 const discoveryEngine = new DiscoveryEngine({
                     customAgentRegistry,
                 });
+                const userNotices = new UserNotices({ enabled: config.userNotices });
+                const serverClock = new ServerClock({
+                    onLargeSkew: (offsetMs) => output.stdout(`${describeClockSkew(offsetMs)}\n`),
+                });
                 const actionExecutor = new AgentActionExecutor({
+                    notices: userNotices,
                     enabled: config.remoteActionsEnabled,
                     commandsEnabled: config.remoteCommandsEnabled,
                     machineID: credential.machineId,
                     dataDirectory: config.dataDirectory,
                     inventory: async () => (await discoveryEngine.discover(credential.machineId)).inventory,
+                    serverNow: () => serverClock.now(),
                 });
                 const client = new ObserverStreamClient({
                     config,
                     actionExecutor,
+                    serverClock,
+                    observerVersion: version,
                     onHistorySync: async (syncCommand) => {
                         const rejected = (detail) => create(HistorySyncResultSchema, {
                             jobId: syncCommand.jobId,
@@ -445,7 +562,7 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                             return rejected("Workspace collection policy does not allow readable prompts, replies, and tool activity.");
                         }
                         const expiresAt = timestampDate(syncCommand.expiresAt).getTime();
-                        const remainingMs = expiresAt - Date.now();
+                        const remainingMs = expiresAt - serverClock.now();
                         if (!Number.isFinite(remainingMs) || remainingMs <= 0) {
                             return rejected("History sync command expired before execution.");
                         }
@@ -468,7 +585,7 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                     },
                     onStatus: (message) => output.stdout(`${message}\n`),
                     onPolicy: (policy) => {
-                        effectivePolicy = intersectCollectionPolicy(config.policy, policy);
+                        effectivePolicy = intersectCollectionPolicy(config.policy, credential.consentProfile, policy);
                         collector?.updatePolicy(effectivePolicy);
                     },
                     onCursorReset: (acknowledgedSequence, allocationSequence) => {
@@ -491,11 +608,16 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                 const historicalStore = new HistoricalIdentityStore(config.dataDirectory, {
                     tenantId: credential.tenantId,
                     machineId: credential.machineId,
+                }, {
+                    onSaveError: (error) => output.stderr(`Saved agent identities could not be written (${(error instanceof Error ? error.message : String(error))
+                        .replace(/\s+/gu, " ")
+                        .slice(0, 200)}); retrying on the next pass.\n`),
                 });
                 let historicalIdentities = await historicalStore.load();
                 const initialDiscovery = await discoveryEngine.discover(credential.machineId);
                 historicalIdentities = await historicalStore.remember(initialDiscovery.inventory.agents);
                 let latestDiscoveryInventory = initialDiscovery.inventory;
+                actionExecutor.observeInventory(latestDiscoveryInventory);
                 const publishInventory = () => {
                     const withHistory = mergeInventoryWithHistoricalIdentities(latestDiscoveryInventory, historicalIdentities);
                     client.updateInventory(mergeInventoryWithSourceIdentities(withHistory, collector?.sourceIdentities() ?? []));
@@ -505,10 +627,13 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                 const streaming = client.run(controller.signal);
                 const discovering = runDiscoveryLoop(discoveryEngine, credential.machineId, config.discoveryIntervalMs, controller.signal, async (inventory) => {
                     latestDiscoveryInventory = inventory;
+                    actionExecutor.observeInventory(inventory);
                     collector?.updateInventory(inventory);
                     historicalIdentities = await historicalStore.remember(inventory.agents);
                     publishInventory();
-                });
+                }, (error) => output.stderr(`Agent discovery failed and will retry on the next pass: ${(error instanceof Error ? error.message : String(error))
+                    .replace(/\s+/gu, " ")
+                    .slice(0, 200)}\n`));
                 const processMonitor = new GuardianProcessMonitor({
                     coverageClient: new GuardianHostedClient({ controlPlaneURL: config.controlPlaneUrl, credential: credential.credential }),
                     machineId: credential.machineId,
@@ -523,10 +648,23 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                         inventory: async () => (await discoveryEngine.discover(credential.machineId)).inventory,
                     }),
                     journal: new GuardianDecisionJournal(config.dataDirectory),
+                    notices: userNotices,
                     onStatus: (message) => output.stdout(`${message}\n`),
                 });
+                // Being stopped before the stream first connects is a normal stop.
+                const streamReady = async () => {
+                    try {
+                        return await client.waitUntilReady(controller.signal);
+                    }
+                    catch (error) {
+                        if (controller.signal.aborted)
+                            return undefined;
+                        throw error;
+                    }
+                };
                 const monitoring = (async () => {
-                    await client.waitUntilReady(controller.signal);
+                    if (await streamReady() === undefined)
+                        return;
                     while (!controller.signal.aborted) {
                         try {
                             await processMonitor.review(latestDiscoveryInventory, controller.signal);
@@ -543,24 +681,47 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                     }
                 })();
                 const collecting = (async () => {
-                    const allocationSequence = await client.waitUntilReady(controller.signal);
+                    const allocationSequence = await streamReady();
+                    if (allocationSequence === undefined)
+                        return;
+                    // Collection starts now. Where the company consented, tell the
+                    // person at the computer; a notice never holds collection up.
+                    void announceCompanyCollection({
+                        dataDirectory: config.dataDirectory,
+                        credential,
+                        profile: config.observabilityProfile,
+                        notices: userNotices,
+                    }).then((outcome) => {
+                        if (outcome === "shown")
+                            output.stdout("Told the person at this computer that Phigon is recording AI agent activity.\n");
+                    }, () => output.stderr("The start-of-collection notice could not be remembered; it is shown again on the next start.\n"));
                     collector = new ActivityCollector({
                         config,
                         credential,
                         initialSequence: allocationSequence,
                         initialAcknowledgedSequence: client.metrics().lastAcknowledgedSequence,
                         durableDelivery: true,
+                        flushDelivery: () => client.flush(),
                         policy: effectivePolicy,
                         emit: (event) => client.enqueue(event),
+                        // The spool also has a byte budget; reaching it fails delivery
+                        // instead of waiting, so both stop well before it.
                         canCollect: () => {
                             const queue = client.metrics().queue;
-                            return (queue.capacity - queue.depth >=
-                                Math.max(32, config.activityRateLimitPerMinute));
+                            return (hasByteHeadroom(queue) &&
+                                queue.capacity - queue.depth >=
+                                    Math.max(32, config.activityRateLimitPerMinute));
                         },
                         canSyncHistory: () => {
                             const queue = client.metrics().queue;
-                            return queue.capacity - queue.depth >= Math.min(queue.capacity, historySyncQueueHeadroom);
+                            return hasByteHeadroom(queue) &&
+                                queue.capacity - queue.depth >= Math.min(queue.capacity, historySyncQueueHeadroom);
                         },
+                        onDeliveryRefused: (error) => output.stderr(`Telemetry delivery is paused (${(error instanceof Error ? error.message : String(error))
+                            .replace(/\s+/gu, " ")
+                            .slice(0, 200)}). Collection resumes from the same records once queued events are acknowledged.\n`),
+                        onSourceFailure: (failure) => output.stderr(`Activity source ${failure.adapterId} could not be read (${failure.message}). ` +
+                            "It is retried shortly; other sources keep collecting.\n"),
                         additionalSources: async () => registeredAgentActivitySources(await customAgentRegistry.list()),
                         onSourceIdentity: async (identity) => {
                             // Make the source target addressable immediately, then durably
@@ -623,15 +784,36 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                         }
                     }
                 })();
-                await settleObserverTasks([streaming, discovering, collecting, monitoring, maintaining], controller, () => fatalPersistenceError);
+                try {
+                    await settleObserverTasks([streaming, discovering, collecting, monitoring, maintaining], controller, () => fatalPersistenceError);
+                }
+                finally {
+                    // Write what the spool still buffers. Nothing depends on it:
+                    // checkpoints only moved past written events, and a lost
+                    // acknowledgement only sends an event again.
+                    try {
+                        client.flush();
+                    }
+                    catch { /* Read again on the next start. */ }
+                }
                 output.stdout("Observer stopped.\n");
             }
             finally {
                 process.removeListener("SIGINT", stop);
                 process.removeListener("SIGTERM", stop);
+                stopWatchingParent?.();
+                process.stdout.removeListener("error", ignoreConsoleError);
+                process.stderr.removeListener("error", ignoreConsoleError);
+                await instanceLock?.release();
             }
             return 0;
         }
+        if (command === "pair" && enrollmentCode !== undefined) {
+            if (config.controlPlaneUrl.origin !== DEFAULT_CONTROL_PLANE_ORIGIN && !config.grpcEndpointConfigured) {
+                throw new Error("Custom workspaces require --grpc-url alongside --control-plane-url (or PHIGON_GRPC_URL). Copy both endpoints from your workspace's Connect machine dialog.");
+            }
+            return await enrollWithCode(enrollmentCode, flags, config, callerEnvironment, json, version, output);
+        }
         if (command === "pair") {
             if (config.controlPlaneUrl.origin !== DEFAULT_CONTROL_PLANE_ORIGIN && !config.grpcEndpointConfigured) {
                 throw new Error("Custom workspaces require --grpc-url alongside --control-plane-url (or PHIGON_GRPC_URL). Copy both endpoints from your workspace's Connect machine dialog.");
@@ -642,6 +824,8 @@ export async function run(argv, environment = process.env, output = defaultOutpu
             }
             const displayName = flagValue(flags, "--name");
             const consentProfile = parseConsentProfile(flagValue(flags, "--consent-profile"));
+            const authorityFlag = flagValue(flags, "--server-ca-sha256");
+            const authority = authorityFlag === undefined ? undefined : parseAuthorityFingerprint(authorityFlag);
             if (json && !flags.includes("--accept-consent")) {
                 throw new Error("JSON pairing requires --accept-consent after reviewing the selected profile.");
             }
@@ -652,17 +836,41 @@ export async function run(argv, environment = process.env, output = defaultOutpu
                     throw new Error("Consent was not granted. No pairing request was sent.");
                 }
             }
-            const result = await pairMachine({
-                config,
-                code,
-                consentProfile,
-                ...(displayName === undefined ? {} : { displayName }),
-            });
+            if (authority !== undefined) {
+                await pinServerAuthority(config.controlPlaneUrl, authority, config.dataDirectory, undefined, {
+                    proxy: proxyForUrl(config.controlPlaneUrl, proxySettings(callerEnvironment)),
+                });
+            }
+            let result;
+            try {
+                result = await pairMachine({
+                    config,
+                    code,
+                    consentProfile,
+                    ...(displayName === undefined ? {} : { displayName }),
+                });
+            }
+            catch (error) {
+                // An authority pinned for a pairing that failed is not kept.
+                if (authority !== undefined && await new FileCredentialStore(config.dataDirectory).load() === null) {
+                    await forgetServerAuthority(config.dataDirectory);
+                }
+                throw error;
+            }
             output.stdout(json
                 ? `${JSON.stringify(result, null, 2)}\n`
                 : formatPairResult(result));
             return 0;
         }
+        if (flags.includes("--check")) {
+            const report = await runDoctorCheck({
+                config,
+                observerVersion: version,
+                maxDeliveryAgeMinutes: parseMaxDeliveryAge(flagValue(flags, "--max-delivery-age")),
+            });
+            output.stdout(json ? `${JSON.stringify(report, null, 2)}\n` : formatDoctorCheck(report));
+            return report.exitCode;
+        }
         const storedCredential = await new FileCredentialStore(config.dataDirectory).load();
         let streamCursor;
         let streamCursorIssue;
@@ -682,15 +890,107 @@ export async function run(argv, environment = process.env, output = defaultOutpu
         const health = createHealthSnapshot({
             ...config,
             machineTokenConfigured: config.machineTokenConfigured || storedCredential !== null,
-        }, version, new Date(), streamCursor, streamCursorIssue);
+        }, version, new Date(), streamCursor, streamCursorIssue, storedCredential === null ? undefined : consentHealth(storedCredential));
         output.stdout(json ? `${JSON.stringify(health, null, 2)}\n` : formatHealth(health));
         return 0;
     }
     catch (error) {
         const message = error instanceof Error ? error.message : "Unknown error.";
-        output.stderr(`Observer command failed: ${message}\n`);
+        (logged?.error ?? output.stderr)(`Observer command failed: ${message}\n`);
+        if (error instanceof EnrollmentError) {
+            if (flags.includes("--json")) {
+                output.stdout(`${JSON.stringify({
+                    enrolled: false,
+                    error: { code: error.code, message: error.message },
+                    exitCode: error.exitCode,
+                }, null, 2)}\n`);
+            }
+            return error.exitCode;
+        }
         return 1;
     }
+    finally {
+        proxy?.restore();
+    }
+}
+/**
+ * The enrollment code from --enrollment-code or PHIGON_ENROLLMENT_CODE, or
+ * undefined for an owner's pairing. The value is never repeated in errors.
+ */
+function enrollmentCodeFrom(flags, environment) {
+    const flagGiven = flags.some((flag) => flag === "--enrollment-code" || flag.startsWith("--enrollment-code="));
+    const fromFlag = flagValue(flags, "--enrollment-code");
+    if (flagGiven && (fromFlag === undefined || fromFlag.trim() === "")) {
+        throw new Error(`--enrollment-code needs the code. Device management scripts should set ${enrollmentCodeVariable} instead, which keeps it out of process lists.`);
+    }
+    const fromEnvironment = environment[enrollmentCodeVariable]?.trim() || undefined;
+    const code = fromFlag ?? fromEnvironment;
+    if (code === undefined)
+        return undefined;
+    if (flags.some((flag) => flag === "--code" || flag.startsWith("--code="))) {
+        throw new Error(`Use either --code with a one-time pairing code, or an enrollment code (--enrollment-code or ${enrollmentCodeVariable}), not both.`);
+    }
+    if (flags.some((flag) => flag === "--accept-consent" || flag === "--consent-profile" || flag.startsWith("--consent-profile="))) {
+        throw new Error("With an enrollment code your company has chosen the collection profile and given consent. Remove --consent-profile and --accept-consent.");
+    }
+    return code;
+}
+/**
+ * `pair` with an enrollment code: no prompt, the company's consent, and a
+ * distinct exit code for each failure a device management script can act on.
+ */
+async function enrollWithCode(code, flags, config, environment, json, version, output) {
+    // Checked before anything is pinned or sent.
+    const enrollmentCode = checkedEnrollmentCode(code);
+    const displayName = flagValue(flags, "--name");
+    const authorityFlag = flagValue(flags, "--server-ca-sha256");
+    const authority = authorityFlag === undefined ? undefined : parseAuthorityFingerprint(authorityFlag);
+    if (authority !== undefined) {
+        await pinServerAuthority(config.controlPlaneUrl, authority, config.dataDirectory, undefined, {
+            proxy: proxyForUrl(config.controlPlaneUrl, proxySettings(environment)),
+        });
+    }
+    let result;
+    try {
+        result = await enrollMachine({
+            config,
+            code: enrollmentCode,
+            observerVersion: version,
+            ...(displayName === undefined ? {} : { displayName }),
+            onRetry: (waitMs) => output.stderr(`The Phigon server is busy. Trying again in ${Math.ceil(waitMs / 1_000)} seconds.\n`),
+        });
+    }
+    catch (error) {
+        // An authority pinned for an enrollment that failed is not kept.
+        if (authority !== undefined && await new FileCredentialStore(config.dataDirectory).load() === null) {
+            await forgetServerAuthority(config.dataDirectory);
+        }
+        throw error;
+    }
+    const warning = config.observabilityProfile === "full" && result.consent.profile !== "full"
+        ? "Your company's code covers the metadata profile only, so the observer does not start with PHIGON_OBSERVABILITY_PROFILE=full. Set it to metadata, or ask for a full-activity code."
+        : undefined;
+    if (warning !== undefined)
+        output.stderr(`${warning}\n`);
+    output.stdout(json ? `${JSON.stringify({ enrolled: true, ...result }, null, 2)}\n` : formatEnrollResult(result));
+    return 0;
+}
+function formatEnrollResult(result) {
+    return [
+        "Computer enrolled.",
+        `Machine: ${result.displayName} (${result.machineId})`,
+        `Control plane: ${result.controlPlaneOrigin}`,
+        `Consent: given by your company${result.consent.enrollmentCodeLabel === undefined ? "" : ` with the enrollment code "${result.consent.enrollmentCodeLabel}"`}, ${result.consent.profile} profile`,
+        "Machine credential: stored securely",
+        ...(result.replacedMachineId === undefined
+            ? []
+            : [
+                `Earlier machine: ${result.replacedMachineId} (the workspace no longer accepted its key)`,
+                "This computer was enrolled as a new machine. Activity the earlier machine had not delivered was moved to the retired-pairings folder in the data directory.",
+            ]),
+        "Next step: phigon-observer service install",
+        "",
+    ].join("\n");
 }
 function guardianAgentMessage(action, allowed, approvalRequired, reason, adminContract, approvalState) {
     const operation = action.replace(".", " ");
@@ -745,6 +1045,7 @@ async function runGuardianLaunch(flags, environment, output, input, dataDirector
     if (agentID === undefined) {
         throw new Error("guardian launch requires --agent <agent-id>.");
     }
+    validatedAgentID(agentID);
     const model = validatedModelResource(flagValue(gatewayFlags, "--model"));
     const executable = flags[separator + 1];
     const commandArguments = flags.slice(separator + 2);
@@ -754,6 +1055,14 @@ async function runGuardianLaunch(flags, environment, output, input, dataDirector
     }
     return await runGuardedCommand(executable, commandArguments, gatewayFlags, model, environment, output, dataDirectory);
 }
+// The control plane refuses any other agent ID with a generic manifest error,
+// so check here and say what is wrong.
+function validatedAgentID(value) {
+    if (!/^[A-Za-z0-9._:-]{1,128}$/u.test(value)) {
+        throw new Error("--agent must be 1-128 letters, numbers, dots, underscores, colons or hyphens.");
+    }
+    return value;
+}
 function validateGuardianExecFlags(flags) {
     const valued = new Set([
         "--agent",
@@ -806,7 +1115,7 @@ async function runGuardedCommand(executable, arguments_, flags, model, environme
         output.stdout("Phigon Guardian blocked execution: administrator policy is unavailable.\n");
         return 77;
     }
-    const agentId = flagValue(flags, "--agent") ?? "managed-agent";
+    const agentId = validatedAgentID(flagValue(flags, "--agent") ?? "managed-agent");
     const context = await readGuardianActionContext(flagValue(flags, "--context-file"));
     const hosted = new GuardianHostedClient({ controlPlaneURL: config.controlPlaneUrl, credential: credential.credential });
     const childEnvironment = executionEnvironment({ ...process.env, ...environment });
@@ -910,6 +1219,37 @@ async function runGuardedCommand(executable, arguments_, flags, model, environme
         await bridge?.close();
     }
 }
+/**
+ * Calls `onGone` once the process `pid` has exited, checking every few
+ * seconds. Returns a function that stops watching.
+ */
+export function watchParentProcess(pid, onGone, intervalMs = 5_000, isAlive = processIsAlive) {
+    const timer = setInterval(() => {
+        if (pid > 0 && isAlive(pid))
+            return;
+        clearInterval(timer);
+        onGone();
+    }, intervalMs);
+    timer.unref();
+    return () => clearInterval(timer);
+}
+/**
+ * NODE_EXTRA_CA_CERTS from the service settings. Node.js reads the variable
+ * only when it starts, so the service adds those authorities itself.
+ */
+function trustExtraCertificates(file, output) {
+    if (file === undefined || file === "")
+        return;
+    try {
+        const certificates = readFileSync(file, "utf8")
+            .match(/-----BEGIN CERTIFICATE-----[\s\S]+?-----END CERTIFICATE-----/gu) ?? [];
+        for (const certificate of certificates)
+            trustAuthority(`${certificate}\n`);
+    }
+    catch {
+        output.stderr(`The certificates in NODE_EXTRA_CA_CERTS (${file}) could not be read; HTTPS uses the system's authorities only.\n`);
+    }
+}
 export async function settleObserverTasks(tasks, controller, fatalError) {
     try {
         await Promise.all(tasks);
@@ -922,7 +1262,8 @@ export async function settleObserverTasks(tasks, controller, fatalError) {
         await Promise.allSettled(tasks);
     }
 }
-function intersectCollectionPolicy(local, server) {
+function intersectCollectionPolicy(configured, consentProfile, server) {
+    const local = consentedCollectionPolicy(configured, consentProfile);
     return Object.freeze({
         promptContent: local.promptContent &&
             server?.promptContent === true,
@@ -989,16 +1330,22 @@ function helpText() {
         "  phigon-observer agent list [--json]",
         "  phigon-observer agent remove --id <id> [--yes] [--json]",
         "  phigon-observer doctor [--profile <metadata|full>] [--json]",
+        "  phigon-observer doctor --check [--max-delivery-age <minutes>] [--json]",
         "  phigon-observer update [--check] [--yes] [--json]",
         "  phigon-observer --version",
         "  phigon-observer discover [--json]",
         "  phigon-observer ingest --agent <agent-id|custom> [--name <agent-name>] [--quiet] [--json]",
-        "  phigon-observer pair --code <one-time-code> --consent-profile <metadata|full> [--control-plane-url <url> --grpc-url <url>] [--name <machine-name>] [--accept-consent] [--json]",
-        "  phigon-observer remove-machine [--yes] [--json]",
+        "  phigon-observer pair --code <one-time-code> --consent-profile <metadata|full> [--control-plane-url <url> --grpc-url <url> [--server-ca-sha256 <fingerprint>]] [--name <machine-name>] [--accept-consent] [--json]",
+        "  PHIGON_ENROLLMENT_CODE=<code> phigon-observer pair [--control-plane-url <url> --grpc-url <url> [--server-ca-sha256 <fingerprint>]] [--name <machine-name>] [--json]",
+        "  phigon-observer pair --enrollment-code <code> [same options]",
+        "  phigon-observer remove-machine [--purge] [--yes] [--json]",
         "  phigon-observer run [--profile <metadata|full>]",
+        "  phigon-observer service install [--profile <metadata|full>] [--json]",
+        "  phigon-observer service uninstall [--json]",
+        "  phigon-observer service status [--json]",
         "  phigon-observer help",
         "",
-        "The doctor command validates local configuration without transmitting data.",
+        "The doctor command validates local configuration without transmitting data. With --check it also probes the control plane and exits non-zero when something needs attention: 3 not paired, 4 consent missing or outdated, 5 observer not running, 6 nothing delivered within --max-delivery-age minutes (default 15), 7 control plane unreachable.",
         "The agent commands manage dynamic local monitoring definitions for custom agents without changing observer code.",
         "The authorize-action command is a fail-closed decision point for managed gateways; it does not intercept actions performed outside that boundary. Stop/force-stop requires an administrator policy and exact process identity.",
         "The optional Guardian context file supplies bounded task_id, user_prompt, agent_plan, justification, and recent_activity fields for semantic review.",
@@ -1008,8 +1355,10 @@ function helpText() {
         "The discover command reports a sanitized one-time local inventory.",
         "The ingest command accepts NDJSON on stdin for every supported bridge; use --agent custom --name <agent-name> for any other agent.",
         "The pair command shows the selected collection scope, requires machine-owner acceptance, and stores that evidence with the mode-0600 credential.",
-        "The remove-machine command unregisters only this paired machine, revokes its credential, and requires local confirmation.",
+        "With a company's enrollment code (phe_...), pair asks nothing: the company has given consent and chosen the profile, which the observer stores and keeps collection within. Prefer PHIGON_ENROLLMENT_CODE to --enrollment-code, which shows in process lists. The code is never printed or stored. A busy server is retried a few times. Exit codes: 20 try again later, 21 the code expired, was revoked, is used up or outdated, 22 not a valid code, 23 this computer already used this code, 24 already connected to this workspace. Then run phigon-observer service install.",
+        "The remove-machine command stops collection on this paired machine and revokes its credential; activity already collected stays until an administrator deletes the machine or it expires. It requires local confirmation. With --purge it also removes the background service and every file the observer keeps in the data directory.",
         "The run command maintains an authenticated, resumable telemetry stream; --profile applies the same portable local collection profile on Windows, macOS, and Linux.",
+        "The service commands run the observer in the background for the signed-in user (a Task Scheduler task, a LaunchAgent or a systemd user unit) with this data directory and these settings, starting it at sign-in and again if it stops. Install needs a paired computer with the owner's consent.",
         "",
     ].join("\n");
 }
@@ -1059,25 +1408,149 @@ function formatPairResult(result) {
         `Machine: ${result.displayName} (${result.machineId})`,
         `Control plane: ${result.controlPlaneOrigin}`,
         "Machine credential: stored securely",
+        ...(result.replacedMachineId === undefined
+            ? []
+            : [
+                `Earlier machine: ${result.replacedMachineId} (the workspace no longer accepted its key)`,
+                "This computer was paired as a new machine. Activity the earlier machine had not delivered was moved to the retired-pairings folder in the data directory.",
+            ]),
         "",
     ].join("\n");
 }
+/**
+ * `remove-machine --purge`: the usual removal, then the background service
+ * and every file the observer keeps on this computer. The company's copy of
+ * the activity is not touched; only an administrator or retention removes it.
+ */
+async function removeMachineAndPurge(config, environment, flags, json, output, input, dependencies) {
+    const credentialStore = new FileCredentialStore(config.dataDirectory);
+    const credential = await credentialStore.load();
+    if (json && !flags.includes("--yes")) {
+        throw new Error("JSON machine removal requires --yes after reviewing the removal scope.");
+    }
+    if (!flags.includes("--yes")) {
+        output.stdout(purgePrompt(credential?.machineId, config.dataDirectory));
+        if (await readConfirmation(input) !== "remove") {
+            throw new Error("Machine removal was not confirmed. Nothing was changed.");
+        }
+    }
+    // The service would restart the observer this removes, so stop it first,
+    // and start it again if the removal fails.
+    let service;
+    try {
+        service = serviceContext(config, environment, dependencies);
+    }
+    catch {
+        // No background service on this system; there is nothing to stop.
+    }
+    const serviceStopped = service !== undefined && await stopService(service);
+    const restartService = async () => {
+        if (serviceStopped && service !== undefined)
+            await startService(service).catch(() => undefined);
+    };
+    if (serviceStopped)
+        await waitForObserverToStop(config.dataDirectory, dependencies.stopTimeoutMs ?? 15_000);
+    let removalLock;
+    try {
+        removalLock = await InstanceLock.acquire(config.dataDirectory);
+    }
+    catch (error) {
+        await restartService();
+        if (!(error instanceof ObserverAlreadyRunningError))
+            throw error;
+        throw new Error("A Phigon observer is running with this data directory. Stop it, or stop its service, " +
+            "and then run remove-machine again. No request was sent.");
+    }
+    let result;
+    let purged;
+    try {
+        if (credential !== null) {
+            try {
+                result = await removeMachine({
+                    config,
+                    credential,
+                    clearCredential: async () => {
+                        clearEventSpool(config.dataDirectory);
+                        await forgetServerAuthority(config.dataDirectory);
+                        return await credentialStore.clear();
+                    },
+                });
+            }
+            catch (error) {
+                await removalLock.release();
+                await restartService();
+                throw error;
+            }
+        }
+        if (service !== undefined)
+            await uninstallService(service);
+        purged = await purgeDataDirectory(config.dataDirectory, ["observer.lock"]);
+    }
+    finally {
+        await removalLock.release();
+    }
+    const directoryRemoved = purged.leftBehind.length === 0 &&
+        await removeEmptyDataDirectory(config.dataDirectory);
+    const local = {
+        serviceRemoved: serviceStopped,
+        filesRemoved: purged.removed,
+        dataDirectory: config.dataDirectory,
+        dataDirectoryRemoved: directoryRemoved,
+        leftBehind: purged.leftBehind,
+    };
+    output.stdout(json
+        ? `${JSON.stringify({ ...(result ?? { status: "not_paired" }), purged: local }, null, 2)}\n`
+        : [
+            ...(result === undefined
+                ? ["This computer was not paired, so nothing was sent to a workspace."]
+                : [formatRemoveMachineResult(result).trimEnd()]),
+            `Background service: ${serviceStopped ? "removed" : "was not installed"}`,
+            directoryRemoved
+                ? `Local data: removed, with ${config.dataDirectory}`
+                : `Local data: removed from ${config.dataDirectory}${purged.leftBehind.length === 0 ? "" : `; ${purged.leftBehind.length} file(s) the observer did not create were left there`}`,
+            "To remove the program too, run: npm uninstall --global @phigon/observer",
+            "",
+        ].join("\n"));
+    return 0;
+}
+async function waitForObserverToStop(dataDirectory, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline && (await InstanceLock.inspect(dataDirectory)).running) {
+        await delay(250);
+    }
+}
+function purgePrompt(machineId, dataDirectory) {
+    return [
+        "Remove this computer from Phigon and delete its local data?",
+        ...(machineId === undefined ? ["This computer is not paired."] : [
+            `Machine: ${machineId}`,
+            "Collection stops at once and this computer's observer key is revoked.",
+            "Activity already collected stays with your company until an administrator deletes this computer or it expires under the retention policy.",
+        ]),
+        "The background service is removed, and every file the observer keeps in",
+        `${dataDirectory} is deleted, including activity not yet delivered.`,
+        'Type "remove" to continue: ',
+    ].join("\n");
+}
 function removeMachinePrompt(machineId) {
     return [
         "Remove this machine from Phigon?",
         `Machine: ${machineId}`,
-        "This unregisters the machine and immediately revokes its observer credential.",
-        "Its stored telemetry and machine-scoped data will be durably purged; a minimal deletion tombstone plus consent and audit evidence remain according to retention policy.",
+        "Collection stops at once and this computer's observer key is revoked.",
+        "Activity already collected stays with your company until an administrator deletes this computer or it expires under the retention policy.",
         'Type "remove" to continue: ',
     ].join("\n");
 }
 function formatRemoveMachineResult(result) {
     return [
-        "Machine removed successfully.",
+        result.status === "already_removed"
+            ? "This machine was already removed from the workspace, or its key was revoked. The local copy is now cleaned up."
+            : "Machine removed successfully.",
         `Machine: ${result.machineId}`,
         `Control plane: ${result.controlPlaneOrigin}`,
+        "Collection: stopped; the observer key is revoked",
         "Machine credential: removed from this device",
-        "Stored machine telemetry: deletion scheduled",
+        "Collected activity: kept until an administrator deletes this computer or it expires",
         "Next step: pair again to reconnect this observer.",
         "",
     ].join("\n");
@@ -1175,7 +1648,8 @@ function flagValue(flags, name) {
     for (let index = 0; index < flags.length; index++) {
         const flag = flags[index];
         if (flag === name) {
-            return flags[index + 1];
+            const value = flags[index + 1];
+            return value === undefined || value.startsWith("--") ? undefined : value;
         }
         if (flag?.startsWith(equalsPrefix)) {
             return flag.slice(equalsPrefix.length);
@@ -1204,8 +1678,8 @@ function observabilityEnvironment(command, flags, environment) {
     const profile = flagValue(flags, "--profile");
     if (profile === undefined)
         return environment;
-    if (command !== "doctor" && command !== "run") {
-        throw new Error("--profile is supported only by doctor and run.");
+    if (command !== "doctor" && command !== "run" && !(command === "service" && flags[0] === "install")) {
+        throw new Error("--profile is supported only by doctor, run and service install.");
     }
     if (profile !== "metadata" && profile !== "full") {
         throw new Error("--profile must be metadata or full.");
@@ -1215,6 +1689,15 @@ function observabilityEnvironment(command, flags, environment) {
         PHIGON_OBSERVABILITY_PROFILE: profile,
     };
 }
+function parseMaxDeliveryAge(value) {
+    if (value === undefined)
+        return defaultMaxDeliveryAgeMinutes;
+    const minutes = Number(value);
+    if (!/^\d{1,5}$/u.test(value) || minutes < 1 || minutes > 10_080) {
+        throw new Error("--max-delivery-age must be a number of minutes from 1 to 10080.");
+    }
+    return minutes;
+}
 function parseConsentProfile(value) {
     if (value === "metadata" || value === "full")
         return value;
@@ -1257,6 +1740,7 @@ function formatHealth(health) {
             : [
                 `Stream cursor: ${health.streamCursor.acknowledgedSequence} for ${health.streamCursor.machineId}`,
             ]),
+        ...(health.consent === undefined ? [] : [`Consent: ${describeConsent(health.consent)}`]),
         `Content collection: ${health.safeCollectionDefaults ? "metadata only" : "explicit categories enabled"}`,
         "",
     ].join("\n");