mcp-google-multi 6.0.0-alpha.24 → 6.0.0-alpha.26

package/dist/arg-normalize.d.ts

@@ -11,9 +11,9 @@ export declare function normalizeCallArguments(shape: ArgShape, args: Record<str
     args: Record<string, unknown>;
     renamed: [string, string][];
 };
-export declare function normalizeMessage(msg: JSONRPCMessage, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void): JSONRPCMessage;
+export declare function normalizeMessage(msg: JSONRPCMessage, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void, onRename?: (tool: string, renames: number) => void): JSONRPCMessage;
 /** Wrap a server-side transport so tools/call argument keys are normalized
  * before the SDK validates them. The Protocol assigns `onmessage` during
  * connect(); the interceptor lives in that setter, so the wrapper works
  * identically for stdio and (per-request, stateless) HTTP transports. */
-export declare function withArgNormalization(transport: Transport, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void): Transport;
+export declare function withArgNormalization(transport: Transport, shapeFor: (tool: string) => ArgShape | undefined, log?: (line: string) => void, onRename?: (tool: string, renames: number) => void): Transport;

package/dist/arg-normalize.js

@@ -36,7 +36,7 @@ export function normalizeCallArguments(shape, args) {
     }
     return { args: out ?? args, renamed };
 }
-export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.write(`${l}\n`)) {
+export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.write(`${l}\n`), onRename) {
     const m = msg;
     if (m.method !== 'tools/call' || typeof m.params?.name !== 'string')
         return msg;
@@ -51,6 +51,10 @@ export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.writ
         return msg;
     // Key names only — argument VALUES never reach the log.
     log(`[args] ${m.params.name}: ${renamed.map(([f, t]) => `${f} -> ${t}`).join(', ')}`);
+    try {
+        onRename?.(m.params.name, renamed.length);
+    }
+    catch { /* observers never break dispatch */ }
     return {
         ...msg,
         params: { ...m.params, arguments: normalized },
@@ -60,7 +64,7 @@ export function normalizeMessage(msg, shapeFor, log = (l) => process.stderr.writ
  * before the SDK validates them. The Protocol assigns `onmessage` during
  * connect(); the interceptor lives in that setter, so the wrapper works
  * identically for stdio and (per-request, stateless) HTTP transports. */
-export function withArgNormalization(transport, shapeFor, log) {
+export function withArgNormalization(transport, shapeFor, log, onRename) {
     const wrapper = {
         start: () => transport.start(),
         send: (message, options) => transport.send(message, options),
@@ -70,7 +74,7 @@ export function withArgNormalization(transport, shapeFor, log) {
         get: () => transport.onmessage,
         set: (handler) => {
             transport.onmessage = handler
-                ? (message, extra) => handler(normalizeMessage(message, shapeFor, log), extra)
+                ? (message, extra) => handler(normalizeMessage(message, shapeFor, log, onRename), extra)
                 : undefined;
         },
     });

package/dist/config-file.d.ts

@@ -17,6 +17,7 @@ export interface ConfigFile {
     defaultAccount?: string;
     discovery?: 'lazy' | 'curated' | 'eager';
     toolsets?: string;
+    usageMetrics?: boolean;
 }
 export declare function failStartup(slug: string, message: string): never;
 export declare class ConfigFileError extends Error {

package/dist/config-file.js

@@ -36,6 +36,10 @@ const configSchema = z.strictObject({
     defaultAccount: z.string().optional(),
     discovery: z.enum(['lazy', 'curated', 'eager']).optional(),
     toolsets: z.string().optional(),
+    // Local usage metrics (metrics-feature-spec): absent = off. Downgrade rule:
+    // a pre-6.0 build reading a config carrying this key fails E_CONFIG_INVALID
+    // (strictObject); remove the key first.
+    usageMetrics: z.boolean().optional(),
 });
 export function failStartup(slug, message) {
     process.stderr.write(`${slug}: ${message}\n`);

package/dist/doctor.d.ts

@@ -53,6 +53,9 @@ export interface HttpProbeResult {
 }
 /** Console deep-link to enable one API (section-6 hint, error taxonomy B10). */
 export declare function apiEnableLink(api: string): string;
+/** One line, state AND source, so the people being measured can see both
+ * here and in `diagnose` (metrics spec section 2). Read-only. */
+export declare function usageMetricsStatusLine(env: Record<string, string | undefined>): string;
 /** Roll section verdicts to an overall verdict. `unknown` never worsens it. */
 export declare function overallVerdict(sections: DiagnosticSection[]): Verdict;
 export declare function runDiagnostics(deps?: DiagnosticsDeps): Promise<DiagnosticsReport>;

package/dist/doctor.js

@@ -5,7 +5,9 @@ import { getAccountSet } from './accounts.js';
 import { deriveAccountHealth } from './tools/accounts-tool.js';
 import { peekMasterKeyProvenance, deleteMasterKeyMaterial } from './master-key.js';
 import { hasToken } from './token-store.js';
-import { configDir } from './config-file.js';
+import { configDir, loadConfigFile } from './config-file.js';
+import { envValueSource } from './env-load.js';
+import { describeMetricsDir, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 import { probeApiEnablement } from './api-probe.js';
 import { resolveHttpConfig, HttpConfigError } from './http-config.js';
 import { parseOwnerEmails } from './http-transport.js';
@@ -114,8 +116,24 @@ function sectionConfig(deps, set) {
             hint = (hint ? `${hint} ` : '') + `Move it: \`mv ${envFile} ${target}\`.`;
         }
     }
+    lines.push(usageMetricsStatusLine(deps.env));
     return { id: 2, title: 'Config', verdict, lines, ...(hint ? { hint } : {}), ...(slug ? { slug } : {}) };
 }
+/** One line, state AND source, so the people being measured can see both
+ * here and in `diagnose` (metrics spec section 2). Read-only. */
+export function usageMetricsStatusLine(env) {
+    const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
+    let configValue;
+    try {
+        configValue = loadConfigFile(undefined, 'throw')?.usageMetrics;
+    }
+    catch { /* invalid config is section 2's business, not this line's */ }
+    const state = resolveUsageMetrics(env, configValue, envSrc?.kind === 'file' ? envSrc.file : undefined);
+    if (!state.enabled)
+        return `local usage metrics: off ${sourceLabel(state.source)}`;
+    const d = describeMetricsDir(env);
+    return `local usage metrics: on ${sourceLabel(state.source)} -> ${d.dir} (${d.files} files, ${d.kb} KB)`;
+}
 function sectionKeys(deps, aliases) {
     const provenance = deps.masterKeyProvenance();
     const tokensExist = deps.anyTokensExist(aliases);

package/dist/env-load.d.ts

@@ -9,3 +9,14 @@ export interface EnvLoadPaths {
     configDir?: string;
 }
 export declare function loadEnvFiles(paths?: EnvLoadPaths): EnvLoadResult;
+/**
+ * Which layer supplied `key`: the real process env, or the first loaded .env
+ * file defining it (autoload never overwrites, so first wins). undefined when
+ * the key is unset. Powers self-announcing enablement sources (usage metrics).
+ */
+export declare function envValueSource(key: string): {
+    kind: 'process';
+} | {
+    kind: 'file';
+    file: string;
+} | undefined;

package/dist/env-load.js

@@ -1,4 +1,4 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -48,5 +48,27 @@ export function loadEnvFiles(paths = {}) {
     }
     for (const [k, v] of boot)
         process.env[k] = v;
+    lastLoad = { bootKeys: new Set(boot.keys()), loaded };
     return { loaded, searched: candidates };
 }
+let lastLoad;
+/**
+ * Which layer supplied `key`: the real process env, or the first loaded .env
+ * file defining it (autoload never overwrites, so first wins). undefined when
+ * the key is unset. Powers self-announcing enablement sources (usage metrics).
+ */
+export function envValueSource(key) {
+    if (process.env[key] === undefined)
+        return undefined;
+    if (!lastLoad || lastLoad.bootKeys.has(key))
+        return { kind: 'process' };
+    const re = new RegExp(`^\\s*${key}\\s*=`, 'm');
+    for (const p of lastLoad.loaded) {
+        try {
+            if (re.test(readFileSync(p, 'utf-8')))
+                return { kind: 'file', file: p };
+        }
+        catch { /* file vanished since load: fall through */ }
+    }
+    return { kind: 'process' };
+}

package/dist/http-transport.d.ts

@@ -2,6 +2,7 @@ import { type IncomingMessage, type ServerResponse } from 'node:http';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { HttpConfig } from './http-config.js';
 import { type ArgShape } from './arg-normalize.js';
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 export type AuthOutcome = {
     ok: true;
 } | {
@@ -31,6 +32,10 @@ export interface HttpHostOptions {
     dispatchTimeoutMs?: number;
     /** tools/call argument-key normalization lookup (arg-normalize.ts); absent = off. */
     argShapeFor?: (tool: string) => ArgShape | undefined;
+    /** Usage-metrics transport tap (metrics-tap.ts); absent = off. */
+    metricsTap?: (t: Transport) => Transport;
+    /** Usage-metrics argfix observer, forwarded into arg normalization. */
+    onArgRename?: (tool: string, renames: number) => void;
 }
 export declare function parseOwnerEmails(env?: NodeJS.ProcessEnv): string[];
 /** Front guard: an Origin, if present, must be allowlisted; a Host must be

package/dist/http-transport.js

@@ -183,7 +183,8 @@ export class HttpTransportHost {
                 timer = setTimeout(() => resolve('timeout'), deadlineMs);
                 timer.unref?.();
             });
-            await this.opts.server.connect(this.opts.argShapeFor ? withArgNormalization(transport, this.opts.argShapeFor, this.opts.log) : transport);
+            const tapped = this.opts.metricsTap ? this.opts.metricsTap(transport) : transport;
+            await this.opts.server.connect(this.opts.argShapeFor ? withArgNormalization(tapped, this.opts.argShapeFor, this.opts.log, this.opts.onArgRename) : tapped);
             // Reflect the dispatch into a non-rejecting arm: if the deadline wins the
             // race, an orphaned handler settling later must not surface as an unhandled
             // rejection — but a genuine dispatch error still propagates (rethrown below).

package/dist/index.js

@@ -9,7 +9,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { GENERATED_SERVICES } from './tools/generated/index.js';
 import { GENERATED_GATES, SERVICES } from './services.js';
-import { ToolRegistry } from './registry.js';
+import { ToolRegistry, resolveDiscoveryMode } from './registry.js';
 import { registerDiscoverTools } from './discover.js';
 import { registerEscapeTools } from './tools/google-api.js';
 import { registerAccountTools } from './tools/accounts-tool.js';
@@ -21,12 +21,15 @@ import { buildIdentityContext } from './identity.js';
 import { registerSetupPrompt } from './setup-prompt.js';
 import { applyNetTuning } from './net-tuning.js';
 import { argNormalizationEnabled, withArgNormalization } from './arg-normalize.js';
+import { envValueSource } from './env-load.js';
+import { loadConfigFile } from './config-file.js';
+import { initUsageMetrics, resolveUsageMetrics, sourceLabel } from './usage-metrics.js';
 applyNetTuning();
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const pkg = JSON.parse(readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf-8'));
-function buildRegistry(server, ctx, mode) {
+function buildRegistry(server, ctx, mode, metrics = null) {
     const policy = ctx.policy;
-    const registry = new ToolRegistry(server, policy, mode);
+    const registry = new ToolRegistry(server, policy, mode, metrics);
     const toolsets = getToolsets();
     if (toolsets !== 'all') {
         const known = new Set([...SERVICES.map((s) => s.name), ...GENERATED_SERVICES.map((s) => s.name)]);
@@ -183,15 +186,56 @@ async function main() {
     }
     const wantStdio = httpCfg.transport === 'stdio' || httpCfg.transport === 'both';
     const wantHttp = transportIncludesHttp(httpCfg.transport);
+    // Local usage metrics: fail-closed resolve, self-announcing source, null
+    // when off (no wrapper, no dir, nothing initializes). One instance per
+    // transport so `boots` keys stay honest under `both`.
+    const envSrc = envValueSource('GOOGLE_USAGE_METRICS');
+    const metricsState = resolveUsageMetrics(process.env, loadConfigFile()?.usageMetrics, envSrc?.kind === 'file' ? envSrc.file : undefined);
+    if (metricsState.warning)
+        process.stderr.write(metricsState.warning);
+    const metricsInstances = [];
+    const initMetricsFor = (transport, mode) => {
+        const m = initUsageMetrics(metricsState, { version: pkg.version, mode, transport });
+        if (m) {
+            metricsInstances.push(m);
+            process.stderr.write(`local usage metrics: on ${sourceLabel(metricsState.source)} -> ${m.statusLine()}\n`);
+        }
+        return m;
+    };
+    if (!metricsState.enabled && metricsState.source.kind !== 'default') {
+        process.stderr.write(`local usage metrics: off ${sourceLabel(metricsState.source)}\n`);
+    }
+    const flushMetrics = () => { for (const m of metricsInstances)
+        m.shutdown(); };
+    process.on('exit', flushMetrics);
+    if (metricsState.enabled) {
+        for (const sig of ['SIGTERM', 'SIGINT']) {
+            process.once(sig, () => {
+                flushMetrics();
+                // stdio has no other signal handler; preserve terminate-on-signal.
+                if (!wantHttp)
+                    process.exit(sig === 'SIGINT' ? 130 : 143);
+            });
+        }
+    }
     // Build one McpServer + registry per transport at boot (P1 / BV gap #4:
     // never rebuilt per request); `both` runs the two concurrently.
     if (wantStdio) {
         const server = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
-        const registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }));
+        const stdioMetrics = initMetricsFor('stdio', resolveDiscoveryMode());
+        const registry = buildRegistry(server, buildIdentityContext(process.env, { transport: 'stdio' }), undefined, stdioMetrics);
         registry.installListHandler();
         registerSetupPrompt(server);
-        const stdioTransport = new StdioServerTransport();
-        await server.connect(argNormalizationEnabled() ? withArgNormalization(stdioTransport, (n) => registry.argShape(n)) : stdioTransport);
+        // Tap sits under arg normalization at the same wrap site; it only counts
+        // outbound JSON-RPC error frames (no handler ran) plus id->tool names.
+        let transport = new StdioServerTransport();
+        if (stdioMetrics) {
+            const { tapUsageMetrics } = await import('./metrics-tap.js');
+            transport = tapUsageMetrics(transport, stdioMetrics);
+        }
+        await server.connect(argNormalizationEnabled()
+            ? withArgNormalization(transport, (n) => registry.argShape(n), undefined, stdioMetrics ? (tool, n) => stdioMetrics.recordArgFix(tool, n) : undefined)
+            : transport);
     }
     if (wantHttp) {
         const { HttpTransportHost, parseOwnerEmails } = await import('./http-transport.js');
@@ -208,7 +252,8 @@ async function main() {
             process.stderr.write(`GOOGLE_DISCOVERY="${configuredMode}" is ignored over HTTP; the stateless transport forces "curated".\n`);
         }
         const httpServer = new McpServer({ name: 'mcp-google-multi', version: pkg.version });
-        const registry = buildRegistry(httpServer, buildIdentityContext(process.env, { transport: 'http' }), 'curated');
+        const httpMetrics = initMetricsFor('http', 'curated');
+        const registry = buildRegistry(httpServer, buildIdentityContext(process.env, { transport: 'http' }), 'curated', httpMetrics);
         registry.installListHandler();
         registerSetupPrompt(httpServer);
         // B13: mount the OAuth 2.1 AS (legs A + B) + the Bearer authenticator.
@@ -274,6 +319,11 @@ async function main() {
         // re-auth link into the AS's alias_reauth flow instead of a stdio CLI hint.
         const { setHttpReauthBase } = await import('./reauth-hint.js');
         setHttpReauthBase(httpCfg.publicUrl);
+        let httpTap;
+        if (httpMetrics) {
+            const { tapUsageMetrics } = await import('./metrics-tap.js');
+            httpTap = (t) => tapUsageMetrics(t, httpMetrics);
+        }
         const host = new HttpTransportHost({
             server: httpServer,
             config: httpCfg,
@@ -283,6 +333,8 @@ async function main() {
             routes: authServer.routes,
             log: (l) => process.stderr.write(`[http] ${l}\n`),
             argShapeFor: argNormalizationEnabled() ? (n) => registry.argShape(n) : undefined,
+            metricsTap: httpTap,
+            onArgRename: httpMetrics ? (tool, n) => httpMetrics.recordArgFix(tool, n) : undefined,
         });
         await host.start();
         process.stderr.write(`HTTP transport listening on http://${httpCfg.host}:${httpCfg.port} (public ${httpCfg.publicUrl})\n`);

package/dist/metrics-tap.d.ts

@@ -0,0 +1,3 @@
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
+import type { Metrics } from './usage-metrics.js';
+export declare function tapUsageMetrics(transport: Transport, metrics: Metrics): Transport;

package/dist/metrics-tap.js

@@ -0,0 +1,62 @@
+const PENDING_CAP = 1_000;
+export function tapUsageMetrics(transport, metrics) {
+    const pending = new Map();
+    const wrapper = {
+        start: () => transport.start(),
+        send: (message, options) => {
+            try {
+                const m = message;
+                if (m.id !== undefined) {
+                    const tool = pending.get(m.id);
+                    pending.delete(m.id);
+                    if (m.error && typeof m.error.code === 'number') {
+                        if (m.error.code === -32602) {
+                            if (/unknown tool|not found/i.test(m.error.message ?? ''))
+                                metrics.recordRpc('tool_not_found');
+                            else
+                                metrics.recordRpc('schema_validation', tool);
+                        }
+                        else {
+                            metrics.recordRpc(m.error.code);
+                        }
+                    }
+                }
+            }
+            catch { /* the tap may never break the wire */ }
+            return transport.send(message, options);
+        },
+        close: () => transport.close(),
+    };
+    Object.defineProperty(wrapper, 'onmessage', {
+        get: () => transport.onmessage,
+        set: (handler) => {
+            transport.onmessage = handler
+                ? (message, extra) => {
+                    try {
+                        const m = message;
+                        if (m.id !== undefined && m.method === 'tools/call' && typeof m.params?.name === 'string') {
+                            if (pending.size >= PENDING_CAP)
+                                pending.clear();
+                            pending.set(m.id, m.params.name);
+                        }
+                    }
+                    catch { /* never break the wire */ }
+                    handler(message, extra);
+                }
+                : undefined;
+        },
+    });
+    for (const prop of ['onclose', 'onerror']) {
+        Object.defineProperty(wrapper, prop, {
+            get: () => transport[prop],
+            set: (v) => {
+                transport[prop] = v;
+            },
+        });
+    }
+    Object.defineProperty(wrapper, 'sessionId', { get: () => transport.sessionId });
+    if (transport.setProtocolVersion) {
+        wrapper.setProtocolVersion = (v) => transport.setProtocolVersion(v);
+    }
+    return wrapper;
+}

package/dist/registry.d.ts

@@ -2,6 +2,7 @@ import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { type Policy } from './write-control.js';
 import type { ArgShape } from './arg-normalize.js';
+import type { Metrics } from './usage-metrics.js';
 export type Cud = 'read' | 'create' | 'update' | 'delete';
 export type DiscoveryMode = 'lazy' | 'curated' | 'eager';
 export declare function resolveDiscoveryMode(env?: NodeJS.ProcessEnv): DiscoveryMode;
@@ -34,6 +35,7 @@ export interface CatalogOperation {
 export declare function inferCud(name: string): Cud;
 export declare class ToolRegistry {
     private readonly server;
+    private readonly metrics;
     readonly tools: ToolEntry[];
     readonly policy: Policy;
     readonly registerTool: McpServer['registerTool'];
@@ -47,13 +49,15 @@ export declare class ToolRegistry {
     /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
      * lazy surface to curated without touching the configured mode. */
     private expanded;
-    constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode);
+    constructor(server: McpServer, policy: Policy, mode?: DiscoveryMode, metrics?: Metrics | null);
     registerMeta: McpServer['registerTool'];
     services(): string[];
     /** Declared input-schema keys + scalar kinds for one tool (tools/call arg
      * normalization; the kind drives value coercion on renamed keys). */
     argShape(name: string): ArgShape | undefined;
     catalog(service: string, query?: string): CatalogOperation[];
+    /** The metrics recorder, for hook sites (escape hatch); null when off. */
+    get usageMetrics(): Metrics | null;
     /** Op-name vocabulary for a service, split by provenance so the capped
      * discover descriptions can list curated ops and only summarize the
      * generated long tail. */

package/dist/registry.js

@@ -81,6 +81,7 @@ export function inferCud(name) {
 }
 export class ToolRegistry {
     server;
+    metrics;
     tools = [];
     policy;
     registerTool;
@@ -94,8 +95,9 @@ export class ToolRegistry {
     /** Agent-toggled runtime overlay (discover_all / discover_reset): lifts a
      * lazy surface to curated without touching the configured mode. */
     expanded = false;
-    constructor(server, policy, mode = resolveDiscoveryMode()) {
+    constructor(server, policy, mode = resolveDiscoveryMode(), metrics = null) {
         this.server = server;
+        this.metrics = metrics;
         this.policy = policy;
         this.mode = mode;
         this.registerTool = ((name, config, handler) => {
@@ -194,8 +196,21 @@ export class ToolRegistry {
             const finalHandler = this.compactOutput
                 ? async (...args) => compactResult(await withDefault(...args))
                 : withDefault;
+            // Usage metrics wrap OUTERMOST and only when enabled: off means no
+            // wrapper exists and the chain is byte-identical to the pre-metrics
+            // chain. Fan-out width is derived here (bucketed in the module) so the
+            // metrics module never imports fanout.
+            const instrumented = this.metrics
+                ? this.metrics.wrap({ name, service, meta: this.registeringMeta, generated: config.cud !== undefined }, finalHandler, (a) => {
+                    const v = a?.account;
+                    if (typeof v !== 'string' || (v !== '*' && !v.includes(',')))
+                        return 1;
+                    const sel = parseAccountSelector(v);
+                    return sel.ok ? sel.aliases.length : 1;
+                })
+                : finalHandler;
             const { cud: _cud, ...sdkConfig } = config;
-            return server.registerTool(name, { ...sdkConfig, inputSchema: inputShape, annotations }, finalHandler);
+            return server.registerTool(name, { ...sdkConfig, inputSchema: inputShape, annotations }, instrumented);
         });
     }
     registerMeta = ((name, config, handler) => {
@@ -237,6 +252,10 @@ export class ToolRegistry {
             cud: t.cud,
         }));
     }
+    /** The metrics recorder, for hook sites (escape hatch); null when off. */
+    get usageMetrics() {
+        return this.metrics;
+    }
     /** Op-name vocabulary for a service, split by provenance so the capped
      * discover descriptions can list curated ops and only summarize the
      * generated long tail. */

package/dist/tools/google-api.js

@@ -86,12 +86,15 @@ export function registerEscapeTools(registry, policy, deps = {}) {
         if (api) {
             requested = resolveApiAliases(api);
             if (!requested) {
+                registry.usageMetrics?.recordSearchApi(null);
                 return jsonResult({ error: 'unknown_api', message: `Unknown api "${api}".`, hint: `Known APIs: ${apiList}`, retriable: false }, true);
             }
             const enabled = requested.filter(apiEnabled);
             if (enabled.length === 0)
                 return toolsetDisabled(requested[0]);
             requested = enabled;
+            // Post-resolution SUPPORTED_APIS keys only (closed vocabulary).
+            registry.usageMetrics?.recordSearchApi(requested);
         }
         const apis = requested ?? enabledApis;
         const unavailable = [];
@@ -172,6 +175,7 @@ export function registerEscapeTools(registry, policy, deps = {}) {
             }
         }
         if (!method) {
+            registry.usageMetrics?.recordEscapeMethod(null);
             const near = nearestMethodIds(String(methodId), index);
             return jsonResult({
                 error: 'unknown_method',
@@ -182,6 +186,8 @@ export function registerEscapeTools(registry, policy, deps = {}) {
                 account,
             }, true);
         }
+        // The RESOLVED index id only, never the caller's methodId argument.
+        registry.usageMetrics?.recordEscapeMethod(method.id);
         const cud = cudFromMethod(method);
         const policyService = serviceForAlias(apiKey);
         const lastSegment = method.id.split('.').pop() ?? method.id;

package/dist/usage-metrics.d.ts

@@ -0,0 +1,105 @@
+export declare const METRICS_DIR_NAME = "metrics";
+/** Union of every `error:` slug literal emitted anywhere in src/ (kept honest
+ * by a set-equality grep test). Anything outside buckets to `other`. */
+export declare const KNOWN_ERROR_SLUGS: ReadonlySet<string>;
+export declare function stateDir(env?: NodeJS.ProcessEnv): string;
+export declare function latBucket(ms: number): string;
+export declare function charsBucket(n: number): string;
+export declare function fanBucket(width: number): string | undefined;
+export type MetricsSource = {
+    kind: 'default';
+} | {
+    kind: 'config';
+} | {
+    kind: 'process-env';
+} | {
+    kind: 'env-file';
+    file: string;
+};
+export interface UsageMetricsState {
+    enabled: boolean;
+    source: MetricsSource;
+    /** exactly one stderr warning on a malformed non-empty env value (fail-closed) */
+    warning?: string;
+}
+/**
+ * Fail-closed resolution (mirror of resolveDiscoveryMode's fail-open: here the
+ * safe state is off). Env wins over config; empty env value = unset, silent;
+ * any other value = one warning, off. `envFile` is the .env path that supplied
+ * the variable when it did not come from the real process env (attribution
+ * is computed by the caller; this module never reads env files).
+ */
+export declare function resolveUsageMetrics(env: NodeJS.ProcessEnv, configValue: boolean | undefined, envFile?: string): UsageMetricsState;
+export declare function sourceLabel(source: MetricsSource): string;
+export interface ToolEntryInfo {
+    name: string;
+    service: string;
+    meta: boolean;
+    generated: boolean;
+}
+export interface InitOptions {
+    dir?: string;
+    version: string;
+    mode: string;
+    transport: string;
+    env?: NodeJS.ProcessEnv;
+    now?: () => number;
+    monotonic?: () => number;
+    log?: (line: string) => void;
+}
+export declare class Metrics {
+    private readonly dir;
+    private readonly aggDir;
+    private readonly eventsFile;
+    private readonly now;
+    private readonly mono;
+    private readonly log;
+    private readonly bootKey;
+    private readonly bootId;
+    private seq;
+    private deltas;
+    private events;
+    private lastError;
+    private lastTool;
+    private pendingMid;
+    private timer;
+    private dirty;
+    private failures;
+    private disabled;
+    constructor(opts: InitOptions);
+    private day;
+    private initStorage;
+    private pruneAggs;
+    private day2ms;
+    private pruneEventAge;
+    /** Outermost dispatch wrapper; a throw inside recording never affects the call. */
+    wrap<A extends unknown[], R>(entry: ToolEntryInfo, handler: (...args: A) => Promise<R> | R, widthOf?: (args: unknown) => number): (...args: A) => Promise<R>;
+    private record;
+    /** Escape hatch: only the RESOLVED methodId (double-gated) or a miss. */
+    recordEscapeMethod(idOrNull: string | null): void;
+    /** Search instrument: post-resolution SUPPORTED_APIS keys, or null on failure. */
+    recordSearchApi(resolvedApis: string[] | null): void;
+    recordArgFix(tool: string, by?: number): void;
+    /** Protocol-level failures (no handler ran); wired by the transport tap. */
+    recordRpc(kind: 'schema_validation' | 'tool_not_found' | number, tool?: string): void;
+    private rolloverIfNeeded;
+    /** Merge deltas into the day file under lock; append buffered events. */
+    flush(): void;
+    private rotateIfNeeded;
+    /** Best-effort synchronous flush for shutdown paths. */
+    shutdown(): void;
+    /** For the doctor/diagnose status line. */
+    statusLine(): string;
+}
+/** Read-only description of the metrics dir for doctor/diagnose status lines
+ * (never creates anything; safe to call with the feature off). */
+export declare function describeMetricsDir(env?: NodeJS.ProcessEnv): {
+    dir: string;
+    files: number;
+    kb: number;
+};
+/**
+ * null when off: no directory, no file, no timer, nothing initializes; setting
+ * USAGE_METRICS_PATH alone never enables anything and never creates anything.
+ */
+export declare function initUsageMetrics(state: UsageMetricsState, opts: InitOptions): Metrics | null;

package/dist/usage-metrics.js

@@ -0,0 +1,567 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import { randomBytes } from 'node:crypto';
+import { performance } from 'node:perf_hooks';
+import { withFileLock, atomicWriteFileSync } from './fs-atomic.js';
+// Local usage metrics (metrics-feature-spec.md). Default OFF at every layer;
+// when off, nothing here initializes and the dispatch chain carries no wrapper.
+// Zero network egress is structural: this module's import set is a tested
+// allowlist (fs/path/os/crypto/perf_hooks/fs-atomic), so egress code cannot
+// even be expressed here. Every string persisted is a member of a server-owned
+// closed vocabulary, matches a pinned shape regex, or is other/unknown_*/
+// _overflow; free text is unrepresentable in the file format. No identity
+// dimension of any kind: no aliases, hashes, emails, or exact account counts.
+export const METRICS_DIR_NAME = 'metrics';
+const FLUSH_MS = 60_000;
+const RETRY_WINDOW_MS = 10 * 60_000;
+const BIGRAM_GAP_MS = 5 * 60_000;
+const BIGRAM_CAP = 1_500;
+const ERR_SLUG_CAP = 32;
+const ESCAPE_CAP = 500;
+const EVENTS_ROTATE_BYTES = 4 * 1024 * 1024;
+const RETENTION_DAYS = 180;
+const WRITE_FAILURE_LIMIT = 3;
+const LAT_BOUNDS = [100, 250, 500, 1000, 2500, 5000, 10000, 30000];
+const CHARS_BOUNDS = [64, 256, 1024, 4096, 16384, 65536];
+// methodId backstop shape gate: even a tampered discovery cache cannot turn
+// arbitrary strings into recorded values (spec section 1).
+const METHOD_ID_RE = /^[a-z][a-zA-Z0-9]*(\.[a-zA-Z0-9]+)+$/;
+const METHOD_ID_MAX = 128;
+const TOOL_NAME_RE = /^[a-z][a-z0-9_]{0,63}$/;
+/** Union of every `error:` slug literal emitted anywhere in src/ (kept honest
+ * by a set-equality grep test). Anything outside buckets to `other`. */
+export const KNOWN_ERROR_SLUGS = new Set([
+    'E_CIMD_INVALID', 'E_MCP_TOKEN_INVALID', 'E_NO_DEFAULT_ACCOUNT', 'ambiguous',
+    'api_not_enabled', 'auth_required', 'binary', 'binary_unsupported',
+    'diagnose_failed', 'discovery_unavailable', 'dispatch_timeout', 'forbidden',
+    'insufficient_scope', 'internal', 'invalid_client', 'invalid_client_metadata',
+    'invalid_grant', 'invalid_params', 'invalid_query', 'invalid_request',
+    'invalid_scope', 'network_error', 'not_found', 'rate_limited',
+    'reauth_required', 'too_large', 'toolset_disabled', 'unknown_api',
+    'unknown_method', 'unsupported_grant_type', 'unsupported_type',
+    'untrusted_host', 'upstream_error', 'validation_error', 'write_disabled',
+]);
+const RPC_CODES = new Set([-32700, -32600, -32601, -32603]);
+export function stateDir(env = process.env) {
+    return path.join(env.XDG_STATE_HOME || path.join(os.homedir(), '.local', 'state'), 'mcp-google-multi');
+}
+export function latBucket(ms) {
+    for (const b of LAT_BOUNDS)
+        if (ms <= b)
+            return `le${b}`;
+    return 'gt30000';
+}
+export function charsBucket(n) {
+    for (const b of CHARS_BOUNDS)
+        if (n <= b)
+            return `le${b}`;
+    return 'gt65536';
+}
+export function fanBucket(width) {
+    if (width <= 1)
+        return undefined;
+    if (width === 2)
+        return 'w2';
+    if (width <= 4)
+        return 'w3to4';
+    return 'w5plus';
+}
+const ON = new Set(['on', '1', 'true', 'yes']);
+const OFF = new Set(['off', '0', 'false', 'no']);
+/**
+ * Fail-closed resolution (mirror of resolveDiscoveryMode's fail-open: here the
+ * safe state is off). Env wins over config; empty env value = unset, silent;
+ * any other value = one warning, off. `envFile` is the .env path that supplied
+ * the variable when it did not come from the real process env (attribution
+ * is computed by the caller; this module never reads env files).
+ */
+export function resolveUsageMetrics(env, configValue, envFile) {
+    const raw = env.GOOGLE_USAGE_METRICS;
+    if (raw !== undefined && raw.trim() !== '') {
+        const v = raw.trim().toLowerCase();
+        const source = envFile ? { kind: 'env-file', file: envFile } : { kind: 'process-env' };
+        if (ON.has(v))
+            return { enabled: true, source };
+        if (OFF.has(v))
+            return { enabled: false, source };
+        return {
+            enabled: false,
+            source: { kind: 'default' },
+            warning: `GOOGLE_USAGE_METRICS="${raw}" is not a valid value (on|1|true|yes / off|0|false|no); local usage metrics stay OFF\n`,
+        };
+    }
+    if (configValue === true)
+        return { enabled: true, source: { kind: 'config' } };
+    return { enabled: false, source: { kind: 'default' } };
+}
+export function sourceLabel(source) {
+    switch (source.kind) {
+        case 'config': return '(config)';
+        case 'process-env': return '(process env)';
+        case 'env-file': return `(env file: ${source.file})`;
+        default: return '(default)';
+    }
+}
+function emptyDay(day) {
+    return {
+        v: 1, day, boots: {}, node: process.version, calls: 0, tools: {},
+        hints: {}, retries: {},
+        escape: { methods: {}, _overflow: 0, unknown_method: 0, apis_searched: {}, unknown_api: 0 },
+        validation: {}, rpc: {}, bigrams: {},
+    };
+}
+function addInto(target, key, by = 1) {
+    target[key] = (target[key] ?? 0) + by;
+}
+/** Deep-add b into a for the DayAgg shape (numbers add, maps union). */
+function mergeDay(a, b) {
+    const num = (x, y) => (x ?? 0) + (y ?? 0);
+    const map = (x = {}, y = {}) => {
+        const out = { ...x };
+        for (const [k, v] of Object.entries(y))
+            out[k] = (out[k] ?? 0) + v;
+        return out;
+    };
+    const out = emptyDay(a.day);
+    out.node = b.node || a.node;
+    out.boots = map(a.boots, b.boots);
+    out.calls = num(a.calls, b.calls);
+    const toolNames = new Set([...Object.keys(a.tools), ...Object.keys(b.tools)]);
+    for (const name of toolNames) {
+        const x = a.tools[name];
+        const y = b.tools[name];
+        const t = { n: num(x?.n, y?.n), err: map(x?.err, y?.err), hint: num(x?.hint, y?.hint), lat: map(x?.lat, y?.lat) };
+        if (x?.fanout || y?.fanout)
+            t.fanout = map(x?.fanout, y?.fanout);
+        const argfix = num(x?.argfix, y?.argfix);
+        if (argfix > 0)
+            t.argfix = argfix;
+        out.tools[name] = t;
+    }
+    const slugSet = new Set([...Object.keys(a.hints), ...Object.keys(b.hints)]);
+    for (const s of slugSet) {
+        out.hints[s] = {
+            hinted: num(a.hints[s]?.hinted, b.hints[s]?.hinted),
+            unhinted: num(a.hints[s]?.unhinted, b.hints[s]?.unhinted),
+        };
+    }
+    const retrySet = new Set([...Object.keys(a.retries), ...Object.keys(b.retries)]);
+    for (const s of retrySet) {
+        out.retries[s] = {
+            hintedOk: num(a.retries[s]?.hintedOk, b.retries[s]?.hintedOk),
+            hintedFail: num(a.retries[s]?.hintedFail, b.retries[s]?.hintedFail),
+            unhintedOk: num(a.retries[s]?.unhintedOk, b.retries[s]?.unhintedOk),
+            unhintedFail: num(a.retries[s]?.unhintedFail, b.retries[s]?.unhintedFail),
+        };
+    }
+    out.escape = {
+        methods: map(a.escape.methods, b.escape.methods),
+        _overflow: num(a.escape._overflow, b.escape._overflow),
+        unknown_method: num(a.escape.unknown_method, b.escape.unknown_method),
+        apis_searched: map(a.escape.apis_searched, b.escape.apis_searched),
+        unknown_api: num(a.escape.unknown_api, b.escape.unknown_api),
+    };
+    out.validation = map(a.validation, b.validation);
+    out.rpc = map(a.rpc, b.rpc);
+    out.bigrams = map(a.bigrams, b.bigrams);
+    return out;
+}
+/** Cap open maps at write time (the file may never exceed the caps). */
+function applyCaps(day) {
+    const cap = (m, limit, overflowInto) => {
+        const entries = Object.entries(m);
+        if (entries.length <= limit)
+            return m;
+        entries.sort((x, y) => y[1] - x[1]);
+        const kept = Object.fromEntries(entries.slice(0, limit));
+        const dropped = entries.slice(limit).reduce((s, [, v]) => s + v, 0);
+        if (overflowInto)
+            overflowInto(dropped);
+        else
+            kept.other = (kept.other ?? 0) + dropped;
+        return kept;
+    };
+    for (const t of Object.values(day.tools))
+        t.err = cap(t.err, ERR_SLUG_CAP);
+    day.escape.methods = cap(day.escape.methods, ESCAPE_CAP, (n) => { day.escape._overflow += n; });
+    day.bigrams = cap(day.bigrams, BIGRAM_CAP, (n) => { day.bigrams._overflow = (day.bigrams._overflow ?? 0) + n; });
+    return day;
+}
+export class Metrics {
+    dir;
+    aggDir;
+    eventsFile;
+    now;
+    mono;
+    log;
+    bootKey;
+    bootId = randomBytes(3).toString('hex');
+    seq = 0;
+    deltas;
+    events = [];
+    lastError = new Map();
+    lastTool;
+    pendingMid;
+    timer;
+    dirty = false;
+    failures = 0;
+    disabled = false;
+    constructor(opts) {
+        this.dir = opts.dir ?? path.join(stateDir(opts.env), METRICS_DIR_NAME);
+        this.aggDir = path.join(this.dir, 'agg');
+        this.eventsFile = path.join(this.dir, 'events.jsonl');
+        this.now = opts.now ?? Date.now;
+        this.mono = opts.monotonic ?? (() => performance.now());
+        this.log = opts.log ?? ((l) => process.stderr.write(l));
+        this.bootKey = `${opts.version}/${opts.mode}/${opts.transport}`;
+        this.deltas = emptyDay(this.day());
+        this.deltas.boots[this.bootKey] = 1;
+        this.dirty = true;
+        this.initStorage();
+        this.timer = setInterval(() => this.flush(), FLUSH_MS);
+        this.timer.unref?.();
+    }
+    day() {
+        return new Date(this.now()).toISOString().slice(0, 10);
+    }
+    initStorage() {
+        try {
+            const existed = fs.existsSync(this.dir);
+            fs.mkdirSync(this.aggDir, { recursive: true, mode: 0o700 });
+            if (existed) {
+                const mode = fs.statSync(this.dir).mode & 0o777;
+                if ((mode & 0o077) !== 0) {
+                    this.log(`local usage metrics: ${this.dir} has mode ${mode.toString(8)} (wider than 0700); not changing it, but the files record activity\n`);
+                }
+            }
+            this.pruneAggs();
+            this.pruneEventAge(this.eventsFile);
+        }
+        catch (e) {
+            this.log(`local usage metrics: init failed (${e.message}); disabled for this process\n`);
+            this.disabled = true;
+        }
+    }
+    pruneAggs() {
+        const cutoff = this.day2ms(this.day()) - RETENTION_DAYS * 86_400_000;
+        for (const f of fs.readdirSync(this.aggDir)) {
+            const m = f.match(/^(\d{4}-\d{2}-\d{2})\.json$/);
+            if (m && this.day2ms(m[1]) < cutoff) {
+                try {
+                    fs.rmSync(path.join(this.aggDir, f));
+                }
+                catch { /* prune is best-effort */ }
+            }
+        }
+    }
+    day2ms(day) {
+        return Date.parse(`${day}T00:00:00Z`);
+    }
+    pruneEventAge(file) {
+        if (!fs.existsSync(file))
+            return;
+        const cutoff = this.now() - RETENTION_DAYS * 86_400_000;
+        const lines = fs.readFileSync(file, 'utf-8').split('\n');
+        const kept = lines.filter((l) => {
+            if (!l.trim())
+                return false;
+            try {
+                const ts = JSON.parse(l).ts;
+                return typeof ts === 'string' && Date.parse(ts) >= cutoff;
+            }
+            catch {
+                return false; // torn or corrupt line: drop
+            }
+        });
+        if (kept.length !== lines.filter((l) => l.trim()).length) {
+            atomicWriteFileSync(file, kept.join('\n') + (kept.length ? '\n' : ''));
+        }
+    }
+    /** Outermost dispatch wrapper; a throw inside recording never affects the call. */
+    wrap(entry, handler, widthOf) {
+        return async (...args) => {
+            const started = this.mono();
+            const result = await handler(...args);
+            try {
+                this.record(entry, args[0], result, this.mono() - started, widthOf);
+            }
+            catch { /* metrics may never fail a tool call */ }
+            return result;
+        };
+    }
+    record(entry, firstArg, result, ms, widthOf) {
+        if (this.disabled)
+            return;
+        this.rolloverIfNeeded();
+        const r = result;
+        const ok = !r?.isError;
+        let slug;
+        let hinted;
+        if (!ok) {
+            try {
+                const first = r?.content?.[0]?.text;
+                if (typeof first === 'string' && first.length < 65_536) {
+                    const env = JSON.parse(first);
+                    if (typeof env.error === 'string')
+                        slug = KNOWN_ERROR_SLUGS.has(env.error) ? env.error : 'other';
+                    hinted = typeof env.hint === 'string' && env.hint.length > 0;
+                }
+            }
+            catch {
+                slug = 'other';
+            }
+            slug ??= 'other';
+        }
+        const chars = (r?.content ?? []).reduce((s, c) => s + (typeof c.text === 'string' ? c.text.length : 0), 0);
+        let width = 1;
+        if (widthOf) {
+            try {
+                width = widthOf(firstArg);
+            }
+            catch {
+                width = 1;
+            }
+        }
+        const fan = fanBucket(width);
+        const t = (this.deltas.tools[entry.name] ??= { n: 0, err: {}, hint: 0, lat: {} });
+        t.n += 1;
+        this.deltas.calls += 1;
+        addInto(t.lat, latBucket(ms));
+        if (slug) {
+            addInto(t.err, slug);
+            if (hinted)
+                t.hint += 1;
+            const h = (this.deltas.hints[slug] ??= { hinted: 0, unhinted: 0 });
+            if (hinted)
+                h.hinted += 1;
+            else
+                h.unhinted += 1;
+        }
+        if (fan) {
+            const f = (t.fanout ??= { calls: 0 });
+            f.calls += 1;
+            addInto(f, fan);
+        }
+        // retry self-correction chain (spec section 1): in-memory only.
+        const nowM = this.mono();
+        const prev = this.lastError.get(entry.name);
+        if (prev && nowM - prev.at <= RETRY_WINDOW_MS) {
+            const rr = (this.deltas.retries[prev.slug] ??= { hintedOk: 0, hintedFail: 0, unhintedOk: 0, unhintedFail: 0 });
+            const key = `${prev.hinted ? 'hinted' : 'unhinted'}${ok ? 'Ok' : 'Fail'}`;
+            rr[key] += 1;
+            this.lastError.delete(entry.name);
+        }
+        if (!ok && slug)
+            this.lastError.set(entry.name, { slug, hinted: hinted === true, at: nowM });
+        // bigrams: ordered pairs within the process, 5-minute gap breaks the chain.
+        if (this.lastTool && nowM - this.lastTool.at <= BIGRAM_GAP_MS) {
+            addInto(this.deltas.bigrams, `${this.lastTool.name}>${entry.name}`);
+        }
+        this.lastTool = { name: entry.name, at: nowM };
+        const event = {
+            ts: new Date(this.now()).toISOString().slice(0, 16) + ':00Z',
+            boot: this.bootId,
+            seq: this.seq++,
+            tool: entry.name,
+            ok,
+            ms: Math.round(ms),
+            chars: charsBucket(chars),
+            src: 'handler',
+        };
+        if (slug)
+            event.err = slug;
+        if (hinted !== undefined)
+            event.hint = hinted;
+        if (fan)
+            event.fan = fan;
+        // mid: set mid-dispatch by recordEscapeMethod, attached to the escape
+        // call's own event line (per-event field, never a synthetic event).
+        if (entry.name === 'google_api_call' && this.pendingMid) {
+            event.mid = this.pendingMid;
+            this.pendingMid = undefined;
+        }
+        this.events.push(JSON.stringify(event));
+        this.dirty = true;
+    }
+    /** Escape hatch: only the RESOLVED methodId (double-gated) or a miss. */
+    recordEscapeMethod(idOrNull) {
+        try {
+            this.rolloverIfNeeded();
+            if (idOrNull === null) {
+                this.deltas.escape.unknown_method += 1;
+            }
+            else if (idOrNull.length <= METHOD_ID_MAX && METHOD_ID_RE.test(idOrNull)) {
+                addInto(this.deltas.escape.methods, idOrNull);
+                this.pendingMid = idOrNull;
+            }
+            this.dirty = true;
+        }
+        catch { /* never throws outward */ }
+    }
+    /** Search instrument: post-resolution SUPPORTED_APIS keys, or null on failure. */
+    recordSearchApi(resolvedApis) {
+        try {
+            this.rolloverIfNeeded();
+            if (resolvedApis === null)
+                this.deltas.escape.unknown_api += 1;
+            else
+                for (const k of resolvedApis)
+                    addInto(this.deltas.escape.apis_searched, k);
+            this.dirty = true;
+        }
+        catch { /* never throws outward */ }
+    }
+    recordArgFix(tool, by = 1) {
+        try {
+            this.rolloverIfNeeded();
+            if (!TOOL_NAME_RE.test(tool))
+                return;
+            const t = (this.deltas.tools[tool] ??= { n: 0, err: {}, hint: 0, lat: {} });
+            t.argfix = (t.argfix ?? 0) + by;
+            this.dirty = true;
+        }
+        catch { /* never throws outward */ }
+    }
+    /** Protocol-level failures (no handler ran); wired by the transport tap. */
+    recordRpc(kind, tool) {
+        try {
+            this.rolloverIfNeeded();
+            if (kind === 'schema_validation') {
+                // The tap's name came off the wire; the shape gate keeps a weird
+                // -32602 from writing free text (registered names always pass).
+                if (tool && TOOL_NAME_RE.test(tool))
+                    addInto(this.deltas.validation, tool);
+            }
+            else if (kind === 'tool_not_found') {
+                addInto(this.deltas.rpc, 'tool_not_found');
+            }
+            else {
+                addInto(this.deltas.rpc, RPC_CODES.has(kind) ? `rpc_error_${kind}` : 'rpc_error_other');
+            }
+            this.events.push(JSON.stringify({
+                ts: new Date(this.now()).toISOString().slice(0, 16) + ':00Z',
+                boot: this.bootId, seq: this.seq++,
+                tool: tool && TOOL_NAME_RE.test(tool) ? tool : 'other',
+                ok: false, ms: 0, chars: 'le64', src: 'rpc',
+            }));
+            this.dirty = true;
+        }
+        catch { /* never throws outward */ }
+    }
+    rolloverIfNeeded() {
+        const today = this.day();
+        if (this.deltas.day !== today) {
+            this.flush();
+            this.deltas = emptyDay(today);
+            this.pruneAggs();
+            this.dirty = false;
+        }
+    }
+    /** Merge deltas into the day file under lock; append buffered events. */
+    flush() {
+        if (!this.dirty || this.disabled)
+            return;
+        const deltas = this.deltas;
+        const events = this.events;
+        try {
+            const file = path.join(this.aggDir, `${deltas.day}.json`);
+            withFileLock(file, () => {
+                let current = emptyDay(deltas.day);
+                try {
+                    const onDisk = JSON.parse(fs.readFileSync(file, 'utf-8'));
+                    if (onDisk && onDisk.v === 1 && onDisk.day === deltas.day)
+                        current = onDisk;
+                }
+                catch {
+                    if (fs.existsSync(file))
+                        this.log(`local usage metrics: unreadable day file ${file}; starting fresh\n`);
+                }
+                atomicWriteFileSync(file, JSON.stringify(applyCaps(mergeDay(current, deltas))));
+            });
+            if (events.length > 0) {
+                fs.appendFileSync(this.eventsFile, events.join('\n') + '\n', { mode: 0o600 });
+                this.rotateIfNeeded();
+            }
+            this.deltas = emptyDay(deltas.day);
+            this.events = [];
+            this.dirty = false;
+            this.failures = 0;
+        }
+        catch (e) {
+            this.failures += 1;
+            if (this.failures >= WRITE_FAILURE_LIMIT) {
+                this.disabled = true;
+                if (this.timer)
+                    clearInterval(this.timer);
+                this.log(`local usage metrics: ${WRITE_FAILURE_LIMIT} consecutive write failures (${e.message}); disabled for this process\n`);
+            }
+        }
+    }
+    rotateIfNeeded() {
+        try {
+            if (fs.statSync(this.eventsFile).size < EVENTS_ROTATE_BYTES)
+                return;
+            this.pruneEventAge(this.eventsFile);
+            if (fs.statSync(this.eventsFile).size < EVENTS_ROTATE_BYTES)
+                return;
+            fs.renameSync(this.eventsFile, path.join(this.dir, 'events.1.jsonl'));
+        }
+        catch { /* rotation is best-effort */ }
+    }
+    /** Best-effort synchronous flush for shutdown paths. */
+    shutdown() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.flush();
+    }
+    /** For the doctor/diagnose status line. */
+    statusLine() {
+        try {
+            const files = [
+                ...fs.readdirSync(this.aggDir).map((f) => path.join(this.aggDir, f)),
+                this.eventsFile, path.join(this.dir, 'events.1.jsonl'),
+            ].filter((f) => fs.existsSync(f));
+            const bytes = files.reduce((s, f) => s + fs.statSync(f).size, 0);
+            return `${this.dir} (${files.length} files, ${Math.round(bytes / 1024)} KB)`;
+        }
+        catch {
+            return this.dir;
+        }
+    }
+}
+/** Read-only description of the metrics dir for doctor/diagnose status lines
+ * (never creates anything; safe to call with the feature off). */
+export function describeMetricsDir(env = process.env) {
+    const dir = env.USAGE_METRICS_PATH ?? path.join(stateDir(env), METRICS_DIR_NAME);
+    let files = 0;
+    let bytes = 0;
+    try {
+        const candidates = [
+            ...fs.readdirSync(path.join(dir, 'agg')).map((f) => path.join(dir, 'agg', f)),
+            path.join(dir, 'events.jsonl'),
+            path.join(dir, 'events.1.jsonl'),
+        ];
+        for (const f of candidates) {
+            try {
+                bytes += fs.statSync(f).size;
+                files += 1;
+            }
+            catch { /* absent */ }
+        }
+    }
+    catch { /* dir absent: zeros */ }
+    return { dir, files, kb: Math.round(bytes / 1024) };
+}
+/**
+ * null when off: no directory, no file, no timer, nothing initializes; setting
+ * USAGE_METRICS_PATH alone never enables anything and never creates anything.
+ */
+export function initUsageMetrics(state, opts) {
+    if (!state.enabled)
+        return null;
+    return new Metrics({
+        ...opts,
+        dir: opts.dir ?? (opts.env ?? process.env).USAGE_METRICS_PATH ?? undefined,
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "6.0.0-alpha.24",
+  "version": "6.0.0-alpha.26",
   "description": "Local MCP server for Google Workspace (Gmail, Drive, Calendar, Sheets, Docs, Contacts, Tasks, Meet, Search Console, +Forms/Chat/Admin) across multiple accounts — OAuth-only, encrypted token storage, deny-by-default writes.",
   "type": "module",
   "license": "MIT",