chore: Implement Watchdog process for reliable telemetry (#777)

This PR implements the watchdog process architecture for the telemetry
system. It moves the `ClearcutSender` execution to a dedicated child
process, ensuring that events—especially shutdown events—are reliably
transmitted even if the main server process terminates abruptly.

Added an e2e test that runs the server, checks the log file and confirms
the telemetry logs exist and that the watchdog process is correctly
killed after sending the shutdown event once the main process is killed.

**Implementation Roadmap:**
This is the fourth in a series of PRs designed to implement the
telemetry system:
1. **CLI & Opt-out Mechanism
([Merged](#757
    *   Added `--usage-statistics` flag and transparency logging.
2. **Logger Scaffolding & Integration
([Merged](#758
    *   **`ClearcutLogger`**: Implemented the main logging entry point.
* **One-way Data Flow**: Integrated `logToolInvocation` and
`logServerStart` hooks into `main.ts` to capture events.
    *   **`ClearcutSender`**: Introduced a transport abstraction.
* **Type Definitions**: Added TypeScript definitions for the telemetry
Protocol Buffer messages.
3. **Persistence Layer
([Merged](#766
* **`FilePersistence`**: Implemented a local file-based state manager to
persist the `lastActive` timestamp.
* **Daily Active Logic**: Integrated persistence into `ClearcutLogger`
to automatically detect and log `daily_active` events (with
`days_since_last_active` calculation) via `logDailyActiveIfNeeded`.
4.  **Watchdog Process Architecture (This PR):**
* **`WatchdogClient`**: Added a client-side wrapper to spawn and
communicate with the watchdog process via `stdin`.
* **`watchdog/main.ts`**: Created the entry point for the watchdog
process. It listens for IPC messages and uses `ClearcutSender` to
transmit events.
* **Reliable Shutdown**: The watchdog monitors the parent process and
guarantees a `shutdown` event is sent when the parent exits or crashes
(detecting `stdin` closure).
* **Refactoring**: Moved `ClearcutSender` to the `watchdog` directory
and updated `ClearcutLogger` to delegate event sending to the
`WatchdogClient`.
5.  **Transport, Batching & Retries (Next):**
* Finalize `ClearcutSender` with actual HTTP transport logic, including
event batching and exponential backoff retries.

Author: ergunsh

src/logger.ts

@@ -31,4 +31,17 @@ export function saveLogsToFile(fileName: string): fs.WriteStream {
   return logFile;
 }
 
+export function flushLogs(
+  logFile: fs.WriteStream,
+  timeoutMs = 2000,
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const timeout = setTimeout(reject, timeoutMs);
+    logFile.end(() => {
+      clearTimeout(timeout);
+      resolve();
+    });
+  });
+}
+
 export const logger = debug(mcpDebugNamespace);

src/main.ts

@@ -38,7 +38,10 @@ export const args = parseArguments(VERSION);
 const logFile = args.logFile ? saveLogsToFile(args.logFile) : undefined;
 let clearcutLogger: ClearcutLogger | undefined;
 if (args.usageStatistics) {
-  clearcutLogger = new ClearcutLogger();
+  clearcutLogger = new ClearcutLogger({
+    logFile: args.logFile,
+    appVersion: VERSION,
+  });
 }
 
 process.on('unhandledRejection', (reason, promise) => {

src/telemetry/clearcut-logger.ts

@@ -4,42 +4,75 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+import process from 'node:process';
+
 import {logger} from '../logger.js';
 
-import {ClearcutSender} from './clearcut-sender.js';
 import type {LocalState, Persistence} from './persistence.js';
 import {FilePersistence} from './persistence.js';
-import type {FlagUsage} from './types.js';
+import {type FlagUsage, WatchdogMessageType, OsType} from './types.js';
+import {WatchdogClient} from './watchdog-client.js';
 
 const MS_PER_DAY = 24 * 60 * 60 * 1000;
 
+function detectOsType(): OsType {
+  switch (process.platform) {
+    case 'win32':
+      return OsType.OS_TYPE_WINDOWS;
+    case 'darwin':
+      return OsType.OS_TYPE_MACOS;
+    case 'linux':
+      return OsType.OS_TYPE_LINUX;
+    default:
+      return OsType.OS_TYPE_UNSPECIFIED;
+  }
+}
+
 export class ClearcutLogger {
   #persistence: Persistence;
-  #sender: ClearcutSender;
+  #watchdog: WatchdogClient;
 
-  constructor(options?: {persistence?: Persistence; sender?: ClearcutSender}) {
-    this.#persistence = options?.persistence ?? new FilePersistence();
-    this.#sender = options?.sender ?? new ClearcutSender();
+  constructor(options: {
+    appVersion: string;
+    logFile?: string;
+    persistence?: Persistence;
+    watchdogClient?: WatchdogClient;
+  }) {
+    this.#persistence = options.persistence ?? new FilePersistence();
+    this.#watchdog =
+      options.watchdogClient ??
+      new WatchdogClient({
+        parentPid: process.pid,
+        appVersion: options.appVersion,
+        osType: detectOsType(),
+        logFile: options.logFile,
+      });
   }
 
   async logToolInvocation(args: {
     toolName: string;
     success: boolean;
     latencyMs: number;
   }): Promise<void> {
-    await this.#sender.send({
-      tool_invocation: {
-        tool_name: args.toolName,
-        success: args.success,
-        latency_ms: args.latencyMs,
+    this.#watchdog.send({
+      type: WatchdogMessageType.LOG_EVENT,
+      payload: {
+        tool_invocation: {
+          tool_name: args.toolName,
+          success: args.success,
+          latency_ms: args.latencyMs,
+        },
       },
     });
   }
 
   async logServerStart(flagUsage: FlagUsage): Promise<void> {
-    await this.#sender.send({
-      server_start: {
-        flag_usage: flagUsage,
+    this.#watchdog.send({
+      type: WatchdogMessageType.LOG_EVENT,
+      payload: {
+        server_start: {
+          flag_usage: flagUsage,
+        },
       },
     });
   }
@@ -57,13 +90,15 @@ export class ClearcutLogger {
           daysSince = Math.ceil(diffTime / MS_PER_DAY);
         }
 
-        await this.#sender.send({
-          daily_active: {
-            days_since_last_active: daysSince,
+        this.#watchdog.send({
+          type: WatchdogMessageType.LOG_EVENT,
+          payload: {
+            daily_active: {
+              days_since_last_active: daysSince,
+            },
           },
         });
 
-        // Update persistence
         state.lastActive = new Date().toISOString();
         await this.#persistence.saveState(state);
       }

src/telemetry/clearcut-sender.ts

@@ -13,8 +13,11 @@ export interface ChromeDevToolsMcpExtension {
   tool_invocation?: ToolInvocation;
   server_start?: ServerStart;
   daily_active?: DailyActive;
+  server_shutdown?: ServerShutdown;
 }
 
+export type ServerShutdown = Record<string, never>;
+
 export interface ToolInvocation {
   tool_name: string;
   success: boolean;
@@ -65,3 +68,14 @@ export enum McpClient {
   MCP_CLIENT_CLAUDE_CODE = 1,
   MCP_CLIENT_GEMINI_CLI = 2,
 }
+
+// IPC types for messages between the main process and the
+// telemetry watchdog process.
+export enum WatchdogMessageType {
+  LOG_EVENT = 'log-event',
+}
+
+export interface WatchdogMessage {
+  type: WatchdogMessageType.LOG_EVENT;
+  payload: ChromeDevToolsMcpExtension;
+}

src/telemetry/types.ts

@@ -0,0 +1,71 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import {spawn, type ChildProcess} from 'node:child_process';
+import {fileURLToPath} from 'node:url';
+
+import {logger} from '../logger.js';
+
+import type {WatchdogMessage, OsType} from './types.js';
+
+export class WatchdogClient {
+  #childProcess: ChildProcess;
+
+  constructor(
+    config: {
+      parentPid: number;
+      appVersion: string;
+      osType: OsType;
+      logFile?: string;
+    },
+    options?: {spawn?: typeof spawn},
+  ) {
+    const watchdogPath = fileURLToPath(
+      new URL('./watchdog/main.js', import.meta.url),
+    );
+
+    const args = [
+      watchdogPath,
+      `--parent-pid=${config.parentPid}`,
+      `--app-version=${config.appVersion}`,
+      `--os-type=${config.osType}`,
+    ];
+
+    if (config.logFile) {
+      args.push(`--log-file=${config.logFile}`);
+    }
+
+    const spawner = options?.spawn ?? spawn;
+    this.#childProcess = spawner(process.execPath, args, {
+      stdio: ['pipe', 'ignore', 'ignore'],
+      detached: true,
+    });
+    this.#childProcess.unref();
+    this.#childProcess.on('error', err => {
+      logger('Watchdog process error:', err);
+    });
+    this.#childProcess.on('exit', (code, signal) => {
+      logger(`Watchdog exited with code ${code} and signal ${signal}`);
+    });
+  }
+
+  send(message: WatchdogMessage): void {
+    if (
+      this.#childProcess.stdin &&
+      !this.#childProcess.stdin.destroyed &&
+      this.#childProcess.pid
+    ) {
+      try {
+        const line = JSON.stringify(message) + '\n';
+        this.#childProcess.stdin.write(line);
+      } catch (err) {
+        logger('Failed to write to watchdog stdin', err);
+      }
+    } else {
+      logger('Watchdog stdin not available, dropping message');
+    }
+  }
+}

src/telemetry/watchdog-client.ts

@@ -0,0 +1,59 @@
+/**
+ * @license
+ * Copyright 2026 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import crypto from 'node:crypto';
+
+import {logger} from '../../logger.js';
+import type {ChromeDevToolsMcpExtension, OsType} from '../types.js';
+
+const SESSION_ROTATION_INTERVAL_MS = 24 * 60 * 60 * 1000;
+
+export class ClearcutSender {
+  #appVersion: string;
+  #osType: OsType;
+  #sessionId: string;
+  #sessionCreated: number;
+
+  constructor(appVersion: string, osType: OsType) {
+    this.#appVersion = appVersion;
+    this.#osType = osType;
+    this.#sessionId = crypto.randomUUID();
+    this.#sessionCreated = Date.now();
+  }
+
+  async send(event: ChromeDevToolsMcpExtension): Promise<void> {
+    this.#rotateSessionIfNeeded();
+    const enrichedEvent = this.#enrichEvent(event);
+    this.transport(enrichedEvent);
+  }
+
+  transport(event: ChromeDevToolsMcpExtension): void {
+    logger('Telemetry event', JSON.stringify(event, null, 2));
+  }
+
+  async sendShutdownEvent(): Promise<void> {
+    const shutdownEvent: ChromeDevToolsMcpExtension = {
+      server_shutdown: {},
+    };
+    await this.send(shutdownEvent);
+  }
+
+  #rotateSessionIfNeeded(): void {
+    if (Date.now() - this.#sessionCreated > SESSION_ROTATION_INTERVAL_MS) {
+      this.#sessionId = crypto.randomUUID();
+      this.#sessionCreated = Date.now();
+    }
+  }
+
+  #enrichEvent(event: ChromeDevToolsMcpExtension): ChromeDevToolsMcpExtension {
+    return {
+      ...event,
+      session_id: this.#sessionId,
+      app_version: this.#appVersion,
+      os_type: this.#osType,
+    };
+  }
+}