@reticlehq/server 2.4.0 → 2.6.0

package/dist/journal/attach-journal.d.ts

@@ -7,7 +7,7 @@ export interface JournalTarget {
     elapsed(): number;
     setJournal(recorder: JournalRecorder, reader?: JournalReader): void;
 }
-export interface JournalAttachDeps {
+interface JournalAttachDeps {
     fs: FileSystemPort;
     reticleRoot: string;
     /** Journaling is on by default; the opt-out (`.reticle.json` journal:false / env) sets this false. */
@@ -19,3 +19,4 @@ export interface JournalAttachDeps {
  * journaling concern). The recorder's clock is the session's own elapsed time.
  */
 export declare function makeJournalAttach(deps: JournalAttachDeps): (session: JournalTarget) => void;
+export {};

package/dist/journal/deviation-report.js

@@ -6,13 +6,13 @@ function headlineFor(report) {
     if (report.insufficientSamples) {
         return `envelope too new (need ${String(MIN_ENVELOPE_SAMPLES)} runs) — see causal summary${truncNote}`;
     }
-    if (report.deviations.length === 0) {
-        const s = report.nominalSegments === 1 ? '' : 's';
+    if (0 === report.deviations.length) {
+        const s = 1 === report.nominalSegments ? '' : 's';
         return `${String(report.nominalSegments)} segment${s} nominal${truncNote}`;
     }
     const routes = [...new Set(report.deviations.map((d) => d.route))].join(', ');
     const n = report.deviations.length;
-    return `${String(n)} deviation${n === 1 ? '' : 's'}: ${routes}${truncNote}`;
+    return `${String(n)} deviation${1 === n ? '' : 's'}: ${routes}${truncNote}`;
 }
 /**
  * Judge observed segments against their per-route envelopes. Segments without a route, or whose
@@ -27,7 +27,7 @@ export function buildDeviationReport(envelopes, segments, zThreshold) {
         if (segment.route === undefined)
             continue;
         // A truncated segment's counts understate reality — judging it could read a false "nominal".
-        if (segment.truncated === true) {
+        if (true === segment.truncated) {
             truncated += 1;
             continue;
         }
@@ -36,7 +36,7 @@ export function buildDeviationReport(envelopes, segments, zThreshold) {
             continue;
         judged += 1;
         const segDeviations = compareSegment(envelope, segment, zThreshold);
-        if (segDeviations.length === 0)
+        if (0 === segDeviations.length)
             nominal += 1;
         else
             deviations.push(...segDeviations);
@@ -47,7 +47,7 @@ export function buildDeviationReport(envelopes, segments, zThreshold) {
         nominalSegments: nominal,
         judgedSegments: judged,
         truncatedSegments: truncated,
-        insufficientSamples: judged === 0,
+        insufficientSamples: 0 === judged,
     };
     return { ...base, headline: headlineFor(base) };
 }

package/dist/journal/deviation-service.js

@@ -20,7 +20,7 @@ export async function reportAndAccumulate(store, segments, zThreshold) {
             if (segment.route === undefined)
                 continue;
             // Never learn from a truncated sample — its understated counts would poison the baseline.
-            if (segment.truncated === true)
+            if (true === segment.truncated)
                 continue;
             const current = envelopes.get(segment.route) ?? emptyEnvelope(segment.route);
             envelopes.set(segment.route, addSegmentToEnvelope(current, segment));

package/dist/journal/envelope-store.d.ts

@@ -1,7 +1,5 @@
 import type { FileSystemPort } from '../project/fs-port.js';
 import { type RouteEnvelope } from './envelope.js';
-/** Bumped on any breaking change to the persisted envelope shape (matches the runs/contract convention). */
-export declare const ENVELOPE_FILE_VERSION = 1;
 /**
  * Persists the learned per-route envelopes at `.reticle/envelopes.json`. Local, single-project statistics
  * (single-player memory stays OSS — OSS-VS-SERVER). Loads never throw: a missing, malformed, or

package/dist/journal/envelope-store.js

@@ -3,7 +3,7 @@ import { dirname } from 'node:path';
 import { reticleDirPaths } from '../project/reticle-dir.js';
 import { RouteEnvelopeSchema } from './envelope.js';
 /** Bumped on any breaking change to the persisted envelope shape (matches the runs/contract convention). */
-export const ENVELOPE_FILE_VERSION = 1;
+const ENVELOPE_FILE_VERSION = 1;
 const EnvelopeFileSchema = z.object({
     version: z.literal(ENVELOPE_FILE_VERSION),
     routes: z.record(RouteEnvelopeSchema),

package/dist/journal/envelope.d.ts

@@ -21,7 +21,7 @@ export declare function stddev(stats: MetricStats): number;
 /** How many stddevs above the mean `x` sits (0 when there's no spread yet). */
 export declare function zScore(stats: MetricStats, x: number): number;
 /** The metrics an envelope tracks per route. */
-export declare const ENVELOPE_METRICS: readonly ["durationMs", "net", "netErrors", "consoleErrors"];
+declare const ENVELOPE_METRICS: readonly ["durationMs", "net", "netErrors", "consoleErrors"];
 export type EnvelopeMetric = (typeof ENVELOPE_METRICS)[number];
 export interface RouteEnvelope {
     route: string;
@@ -31,8 +31,6 @@ export interface RouteEnvelope {
 }
 /** Below this, an envelope is noise — the deviation report falls back to the causal summary. */
 export declare const MIN_ENVELOPE_SAMPLES = 3;
-/** Default flag threshold in stddevs. The number is a placeholder for fleet-calibrated priors. */
-export declare const DEFAULT_Z_THRESHOLD = 3;
 /** Persisted shape of a route envelope. Validated on load; a bad file degrades to no envelope. */
 export declare const RouteEnvelopeSchema: z.ZodObject<{
     route: z.ZodString;
@@ -229,3 +227,4 @@ export interface Deviation {
  * falls back to the causal summary in that case.
  */
 export declare function compareSegment(envelope: RouteEnvelope, segment: SegmentRollup, zThreshold?: number): Deviation[];
+export {};

package/dist/journal/envelope.js

@@ -15,14 +15,14 @@ export function stddev(stats) {
 /** How many stddevs above the mean `x` sits (0 when there's no spread yet). */
 export function zScore(stats, x) {
     const sd = stddev(stats);
-    return sd === 0 ? 0 : (x - stats.mean) / sd;
+    return 0 === sd ? 0 : (x - stats.mean) / sd;
 }
 /** The metrics an envelope tracks per route. */
-export const ENVELOPE_METRICS = ['durationMs', 'net', 'netErrors', 'consoleErrors'];
+const ENVELOPE_METRICS = ['durationMs', 'net', 'netErrors', 'consoleErrors'];
 /** Below this, an envelope is noise — the deviation report falls back to the causal summary. */
 export const MIN_ENVELOPE_SAMPLES = 3;
 /** Default flag threshold in stddevs. The number is a placeholder for fleet-calibrated priors. */
-export const DEFAULT_Z_THRESHOLD = 3;
+const DEFAULT_Z_THRESHOLD = 3;
 const MetricStatsSchema = z.object({
     count: z.number(),
     mean: z.number(),

package/dist/journal/journal-query.js

@@ -8,7 +8,7 @@ export function mergeEventsBySeq(journal, buffer) {
     const bySeq = new Map();
     const noSeq = [];
     for (const event of [...journal, ...buffer]) {
-        if (typeof event.seq === 'number')
+        if ('number' === typeof event.seq)
             bySeq.set(event.seq, event);
         else
             noSeq.push(event);

package/dist/journal/journal-recorder.d.ts

@@ -8,7 +8,7 @@ export interface JournalSink {
 export interface JournalReader {
     readEvents(): Promise<ReticleEvent[]>;
 }
-export interface JournalRecorderOptions {
+interface JournalRecorderOptions {
     /** Injected elapsed-ms clock (never read from Date here — the clock-injection rule). */
     now: () => number;
     /** Flush the pending-event batch once this many accumulate. */
@@ -35,3 +35,4 @@ export declare class JournalRecorder {
     /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
     flush(): Promise<void>;
 }
+export {};

package/dist/journal/journal-recorder.js

@@ -27,7 +27,7 @@ export class JournalRecorder {
         const active = this.#active;
         if (active !== undefined) {
             out = { ...event, actionId: active.actionId, attribution: EventAttribution.WINDOW };
-            if (typeof event.seq === 'number') {
+            if ('number' === typeof event.seq) {
                 active.seqFrom =
                     active.seqFrom === undefined ? event.seq : Math.min(active.seqFrom, event.seq);
                 active.seqTo = active.seqTo === undefined ? event.seq : Math.max(active.seqTo, event.seq);
@@ -71,7 +71,7 @@ export class JournalRecorder {
         await this.#chain;
     }
     #enqueueFlush() {
-        if (this.#pending.length === 0)
+        if (0 === this.#pending.length)
             return;
         const batch = this.#pending;
         this.#pending = [];

package/dist/journal/rollups.js

@@ -1,4 +1,4 @@
-import { EventType } from '@reticlehq/core';
+import { EventType, StreamDirection } from '@reticlehq/core';
 function finalize(acc) {
     return {
         ...(acc.route === undefined ? {} : { route: acc.route }),
@@ -9,13 +9,13 @@ function finalize(acc) {
         net: { total: acc.netTotal, errors: acc.netErrors },
         consoleErrors: acc.consoleErrors,
         statePathsChanged: acc.statePaths,
-        ...(acc.streams.frames === 0 ? {} : { streams: acc.streams }),
+        ...(0 === acc.streams.frames ? {} : { streams: acc.streams }),
         ...(acc.truncated ? { truncated: true } : {}),
     };
 }
 function isNetError(event) {
     const status = event.data['status'];
-    return event.data['ok'] === false || (typeof status === 'number' && status >= 400);
+    return false === event.data['ok'] || ('number' === typeof status && status >= 400);
 }
 /**
  * Fold an ordered event list into route segments split at each ROUTE_CHANGE. Pure: no clock, no IO —
@@ -41,13 +41,13 @@ export function computeSegments(events) {
             if (acc !== undefined)
                 segments.push(finalize(acc));
             const pathname = event.data['pathname'];
-            acc = open(typeof pathname === 'string' ? pathname : undefined, event.t);
+            acc = open('string' === typeof pathname ? pathname : undefined, event.t);
             continue;
         }
         if (acc === undefined)
             acc = open(undefined, event.t);
         acc.to = event.t;
-        if (typeof event.actionId === 'string')
+        if ('string' === typeof event.actionId)
             acc.actionIds.add(event.actionId);
         if (event.type === EventType.NET_REQUEST) {
             acc.netTotal += 1;
@@ -59,17 +59,17 @@ export function computeSegments(events) {
         }
         if (event.type === EventType.STATE_CHANGE) {
             const name = event.data['name'];
-            if (typeof name === 'string' && !acc.statePaths.includes(name))
+            if ('string' === typeof name && !acc.statePaths.includes(name))
                 acc.statePaths.push(name);
         }
         if (event.type === EventType.NET_STREAM) {
             acc.streams.frames += 1;
             const direction = event.data['direction'];
-            if (direction === 'open')
+            if (StreamDirection.OPEN === direction)
                 acc.streams.opened += 1;
-            else if (direction === 'in')
+            else if (StreamDirection.IN === direction)
                 acc.streams.in += 1;
-            else if (direction === 'out')
+            else if (StreamDirection.OUT === direction)
                 acc.streams.out += 1;
         }
         if (event.type === EventType.TRUNCATED || event.type === EventType.TRANSPORT_OVERFLOW) {

package/dist/journal/session-end.d.ts

@@ -17,7 +17,7 @@ export interface SessionEndTarget {
     ambientCounts(): AmbientCounts;
     ownAmbientCounts(): AmbientCounts;
 }
-export interface SessionEndDeps {
+interface SessionEndDeps {
     fs: FileSystemPort;
     reticleRoot: string;
     /** Journaling/persistence off (opt-out) → teardown is a no-op. */
@@ -29,3 +29,4 @@ export interface SessionEndDeps {
  * starts already knowing which regions churn.
  */
 export declare function makeSessionEnd(deps: SessionEndDeps): (session: SessionEndTarget) => Promise<void>;
+export {};

package/dist/journal/session-journal.js

@@ -37,7 +37,7 @@ export class SessionJournal {
         this.#sessionId = sessionId;
     }
     async appendEvents(events) {
-        if (events.length === 0)
+        if (0 === events.length)
             return;
         await this.#ensureDir();
         const text = `${events.map((e) => JSON.stringify(e)).join('\n')}\n`;
@@ -108,11 +108,11 @@ export class SessionJournal {
     #ingestTail(tail) {
         const cache = this.#eventCache ?? (this.#eventCache = []);
         const end = tail.lastIndexOf('\n') + 1;
-        if (end === 0)
+        if (0 === end)
             return 0; // no complete line yet
         const complete = tail.slice(0, end);
         for (const line of complete.split('\n')) {
-            if (line.length === 0)
+            if (0 === line.length)
                 continue;
             let parsed;
             try {
@@ -148,7 +148,7 @@ export class SessionJournal {
         }
         const out = [];
         for (const line of text.split('\n')) {
-            if (line.length === 0)
+            if (0 === line.length)
                 continue;
             let parsed;
             try {

package/dist/license/license.d.ts

@@ -70,20 +70,6 @@ export declare function assertEnterprise(feature: string, ctx: GateContext): voi
 /** Env names that carry the activation: the operator's key, and the issuer public key baked at release. */
 export declare const LICENSE_KEY_ENV = "RETICLE_LICENSE_KEY";
 export declare const LICENSE_PUBLIC_KEY_ENV = "RETICLE_LICENSE_PUBLIC_KEY";
-/**
- * Issuer public key COMPILED INTO the build. Empty in the source tree; the release pipeline replaces
- * this literal with the real spki PEM. Baking it (rather than only reading env) is what makes the
- * enterprise gate fail closed: a self-hosted operator can no longer disable enforcement by simply
- * never setting RETICLE_LICENSE_PUBLIC_KEY, because the baked key takes precedence. The public key is
- * safe to ship openly — it can only verify licenses, never mint them (that needs the private key).
- */
-export declare const BAKED_ISSUER_PUBLIC_KEY_PEM = "";
-/**
- * Resolve the issuer public-key PEM enforcement uses: the baked-in release key wins, so it can't be
- * turned off from the environment. Only when nothing is baked (dev/repo) does the env var apply — that
- * env path is the test/self-eval escape hatch, not the production switch.
- */
-export declare function resolveIssuerPublicKeyPem(env: NodeJS.ProcessEnv, baked?: string): string | undefined;
 /** The human-facing state of enterprise activation on this machine (what `reticle license status` shows). */
 interface LicenseReport {
     status: 'active' | 'missing' | 'invalid' | 'expired' | 'eval';

package/dist/license/license.js

@@ -37,13 +37,13 @@ export function signLicenseKey(payload, privateKey) {
 }
 /** Verify a key against the issuer public key. Never throws — returns a structured status. */
 export function verifyLicenseKey(key, publicKey, now) {
-    if (key === undefined || key.length === 0)
+    if (key === undefined || 0 === key.length)
         return { status: LicenseStatus.MISSING };
     const parts = key.split(KEY_SEP);
     if (parts.length !== 2 ||
         parts[0] === undefined ||
         parts[1] === undefined ||
-        parts[0].length === 0) {
+        0 === parts[0].length) {
         return { status: LicenseStatus.MALFORMED };
     }
     let json;
@@ -85,7 +85,7 @@ export class EnterpriseLicenseError extends Error {
 /** The issuer public key from the environment (set at release / by the operator); undefined if unset. */
 function issuerPublicKey() {
     const pem = process.env[LICENSE_PUBLIC_KEY_ENV];
-    if (pem === undefined || pem.length === 0)
+    if (pem === undefined || 0 === pem.length)
         return undefined;
     try {
         return createPublicKey(pem);
@@ -122,20 +122,20 @@ export const LICENSE_PUBLIC_KEY_ENV = 'RETICLE_LICENSE_PUBLIC_KEY';
  * never setting RETICLE_LICENSE_PUBLIC_KEY, because the baked key takes precedence. The public key is
  * safe to ship openly — it can only verify licenses, never mint them (that needs the private key).
  */
-export const BAKED_ISSUER_PUBLIC_KEY_PEM = '';
+const BAKED_ISSUER_PUBLIC_KEY_PEM = '';
 /**
  * Resolve the issuer public-key PEM enforcement uses: the baked-in release key wins, so it can't be
  * turned off from the environment. Only when nothing is baked (dev/repo) does the env var apply — that
  * env path is the test/self-eval escape hatch, not the production switch.
  */
-export function resolveIssuerPublicKeyPem(env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
+function resolveIssuerPublicKeyPem(env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
     if (baked.length > 0)
         return baked;
     const envPem = env[LICENSE_PUBLIC_KEY_ENV];
     return envPem !== undefined && envPem.length > 0 ? envPem : undefined;
 }
 function loadPublicKey(pem) {
-    if (pem === undefined || pem.length === 0)
+    if (pem === undefined || 0 === pem.length)
         return undefined;
     try {
         return createPublicKey(pem);
@@ -151,7 +151,7 @@ function loadPublicKey(pem) {
  */
 export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUBLIC_KEY_PEM) {
     const pem = resolveIssuerPublicKeyPem(env, baked);
-    if (pem === undefined || pem.length === 0) {
+    if (pem === undefined || 0 === pem.length) {
         // In a production runtime this is NOT a benign eval session — it is a mis-built release whose gate
         // is off, and assertEnterpriseFromEnv now denies rather than unlocking. Say so loudly here too.
         return isProductionEnv(env)
@@ -196,7 +196,7 @@ export function describeLicense(now, env = process.env, baked = BAKED_ISSUER_PUB
 /** True in a production runtime (NODE_ENV=production) — where a missing issuer key is a mis-built
  *  release, not an eval session, so the gate must fail CLOSED rather than run features free. */
 function isProductionEnv(env) {
-    return env['NODE_ENV'] === 'production';
+    return 'production' === env['NODE_ENV'];
 }
 /**
  * Gate an enterprise feature using env-resolved activation. Enforcement is ON when the issuer public key

package/dist/log.d.ts

@@ -1,5 +1,15 @@
 /**
  * Structured logging to stderr. stdout is reserved for the MCP stdio transport — never
  * write logs there.
+ *
+ * Every line carries `t`, an ISO-8601 wall clock, FIRST.
+ *
+ * It did not, and that cost a real investigation its conclusion: `~/.reticle/daemon-4400.log` had
+ * grown to 24MB of events and not one of them could be placed in time, so "the daemon vanished right
+ * behind the proxy" could only ever be "points at" and never "is". Ordering the key first also means
+ * a huge log can be bisected by eye, and by `sort`, without parsing it.
+ *
+ * The clock is read here rather than injected: this is the I/O boundary, not pure logic, and a
+ * logger that needs its caller to supply the time is a logger callers will route around.
  */
 export declare function log(event: string, fields?: Record<string, unknown>): void;

package/dist/log.js

@@ -1,8 +1,18 @@
 /**
  * Structured logging to stderr. stdout is reserved for the MCP stdio transport — never
  * write logs there.
+ *
+ * Every line carries `t`, an ISO-8601 wall clock, FIRST.
+ *
+ * It did not, and that cost a real investigation its conclusion: `~/.reticle/daemon-4400.log` had
+ * grown to 24MB of events and not one of them could be placed in time, so "the daemon vanished right
+ * behind the proxy" could only ever be "points at" and never "is". Ordering the key first also means
+ * a huge log can be bisected by eye, and by `sort`, without parsing it.
+ *
+ * The clock is read here rather than injected: this is the I/O boundary, not pure logic, and a
+ * logger that needs its caller to supply the time is a logger callers will route around.
  */
 export function log(event, fields = {}) {
-    const line = JSON.stringify({ event, ...fields });
+    const line = JSON.stringify({ t: new Date().toISOString(), event, ...fields });
     process.stderr.write(`${line}\n`);
 }

package/dist/mcp/mcp-is-error.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Does a SUCCESSFUL tool result actually describe a refusal?
+ *
+ * `isError` used to be set only when a handler threw. Every tool that returns a well-formed
+ * `{ error, recovery }` object instead — and that is half the surface — came back as protocol
+ * success with the flag unset, so anything branching on `isError` read a refusal as a result.
+ * Reported from a field sweep that had to special-case each tool's shape to score a run at all.
+ *
+ * A top-level `error` STRING is this codebase's refusal convention (see buildErrorPayload), so that
+ * is the whole test. Deliberately top-level only: `error` appears inside console entries and network
+ * rows as ordinary data, and flipping the flag for those would make it useless in the other direction.
+ */
+export declare function resultIsError(result: unknown): boolean;

package/dist/mcp/mcp-is-error.js

@@ -0,0 +1,18 @@
+/**
+ * Does a SUCCESSFUL tool result actually describe a refusal?
+ *
+ * `isError` used to be set only when a handler threw. Every tool that returns a well-formed
+ * `{ error, recovery }` object instead — and that is half the surface — came back as protocol
+ * success with the flag unset, so anything branching on `isError` read a refusal as a result.
+ * Reported from a field sweep that had to special-case each tool's shape to score a run at all.
+ *
+ * A top-level `error` STRING is this codebase's refusal convention (see buildErrorPayload), so that
+ * is the whole test. Deliberately top-level only: `error` appears inside console entries and network
+ * rows as ordinary data, and flipping the flag for those would make it useless in the other direction.
+ */
+export function resultIsError(result) {
+    if (typeof result !== 'object' || null === result || Array.isArray(result))
+        return false;
+    const error = result.error;
+    return 'string' === typeof error && error.length > 0;
+}

package/dist/mcp/mcp-outage.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Reporting that the agent lost its Reticle tools.
+ *
+ * The proxy already writes a full account of an outage to ~/.reticle/mcp-proxy.log, which is exactly
+ * where nobody looks and nothing aggregates. So the one question the transport must answer — how
+ * often does a real user's MCP server go down, and does it come back — had no answer outside the
+ * machine it happened on.
+ *
+ * Capped at two events per proxy process, and the cap is the design rather than a limitation. One
+ * measured afternoon produced 547 proxy reconnects; an event per reconnect would bill for the
+ * pathology instead of measuring it, which is the same mistake the per-call `tool` event made before
+ * it was removed. What a dashboard needs is the SHARE OF SESSIONS that lose MCP at all (the first
+ * outage) and the share where it never came back on its own (the budget being spent).
+ */
+import { OutageReason, OutageStage } from '@reticlehq/core';
+/**
+ * `OutageStage` and `OutageReason` are core's — this re-export only saves the proxy an import. They
+ * cross the wire, so the vocabulary lives in the contract package and is never re-listed here.
+ */
+export { OutageReason, OutageStage };
+/** Reset between tests; a real process reports each stage at most once. */
+export declare function resetOutageReporting(): void;
+/**
+ * Report one stage of an outage, at most once per process. Fire-and-forget on purpose: this runs on
+ * the transport's recovery path, and a telemetry POST must never be the thing that delays — or
+ * fails — the reconnect it is describing.
+ */
+export declare function reportMcpOutage(stage: OutageStage, facts: {
+    reason: string;
+    attempts: number;
+    pendingLost?: number;
+}): void;

package/dist/mcp/mcp-outage.js

@@ -0,0 +1,55 @@
+/**
+ * Reporting that the agent lost its Reticle tools.
+ *
+ * The proxy already writes a full account of an outage to ~/.reticle/mcp-proxy.log, which is exactly
+ * where nobody looks and nothing aggregates. So the one question the transport must answer — how
+ * often does a real user's MCP server go down, and does it come back — had no answer outside the
+ * machine it happened on.
+ *
+ * Capped at two events per proxy process, and the cap is the design rather than a limitation. One
+ * measured afternoon produced 547 proxy reconnects; an event per reconnect would bill for the
+ * pathology instead of measuring it, which is the same mistake the per-call `tool` event made before
+ * it was removed. What a dashboard needs is the SHARE OF SESSIONS that lose MCP at all (the first
+ * outage) and the share where it never came back on its own (the budget being spent).
+ */
+import { OutageReason, OutageStage, TelemetryEventKind } from '@reticlehq/core';
+import { getTelemetry } from '../telemetry/telemetry.js';
+/**
+ * `OutageStage` and `OutageReason` are core's — this re-export only saves the proxy an import. They
+ * cross the wire, so the vocabulary lives in the contract package and is never re-listed here.
+ */
+export { OutageReason, OutageStage };
+/**
+ * The proxy's reason strings are free text: they also feed `proxyLog`, where prose is fine, and the
+ * wire refuses anything unbounded. Unrecognised reports as `other` rather than being forwarded, so a
+ * new drop path can appear in the proxy without an unclassified string leaving the machine.
+ */
+const KNOWN_REASONS = new Set(Object.values(OutageReason));
+function outageReason(raw) {
+    return KNOWN_REASONS.has(raw) ? raw : OutageReason.OTHER;
+}
+const reported = new Set();
+/** Reset between tests; a real process reports each stage at most once. */
+export function resetOutageReporting() {
+    reported.clear();
+}
+/**
+ * Report one stage of an outage, at most once per process. Fire-and-forget on purpose: this runs on
+ * the transport's recovery path, and a telemetry POST must never be the thing that delays — or
+ * fails — the reconnect it is describing.
+ */
+export function reportMcpOutage(stage, facts) {
+    if (reported.has(stage))
+        return;
+    reported.add(stage);
+    void getTelemetry().emit(TelemetryEventKind.MCP_CONNECTION_LOST, {
+        outage: {
+            stage,
+            reason: outageReason(facts.reason),
+            attempts: facts.attempts,
+            // Always sent, including zero: zero is the finding — a drop no agent could feel. See
+            // McpOutageSchema.pendingLost.
+            pendingLost: facts.pendingLost ?? 0,
+        },
+    });
+}