tmux-ide 2.9.0-beta.19 → 2.9.0-beta.21

package/packages/daemon/src/lib/fleet-preview-model.ts

@@ -9,5 +9,6 @@ export interface FleetPreviewWindow {
 export interface FleetPreviewSnapshot {
   windows: FleetPreviewWindow[];
   selectedWindowId: string | null;
+  selectedPaneId?: string;
   text: string;
 }

package/packages/daemon/src/lib/headless-daemon.ts

@@ -348,6 +348,7 @@ async function runHeadlessDaemonGeneration(
     for (let startAttempt = 0; startAttempt < 2 && !handle; startAttempt += 1) {
       try {
         handle = await deps.startEmbeddedDaemon({
+          launcher: "headless",
           ...(options.supervisionId
             ? { supervisionId: options.supervisionId, predecessor: lifecycle.predecessor }
             : {}),

package/packages/daemon/src/lib/log-sanitize.ts

@@ -0,0 +1,248 @@
+/**
+ * PURE — credential redaction, byte budgets and reserved-metadata protection
+ * for the shared structured logger (`log.ts`).
+ *
+ * Every record the daemon emits passes through `sanitizeLogPayload` before it
+ * reaches the ring buffer, subscribers or the wire. The rules are deliberately
+ * conservative: a value that looks like a credential is replaced, oversized
+ * payloads are truncated with an explicit marker, and caller data can never
+ * overwrite the identity fields (`ts`, `level`, `component`, `msg`, `pid`,
+ * `instanceId`, `version`) that incident triage relies on.
+ */
+
+export const REDACTED = "[redacted]";
+
+/** Wire keys owned by the logger; caller payloads with these keys are renamed. */
+export const RESERVED_LOG_KEYS = Object.freeze([
+  "ts",
+  "level",
+  "component",
+  "msg",
+  "pid",
+  "instanceId",
+  "version",
+] as const);
+const RESERVED = new Set<string>(RESERVED_LOG_KEYS);
+
+/** Prefix applied to caller keys that collide with reserved metadata. */
+export const RESERVED_COLLISION_PREFIX = "payload_";
+
+export interface LogBudget {
+  /** Serialized-bytes ceiling for one record's `data` payload. */
+  readonly maxDataBytes: number;
+  /** Longest string value retained inside a payload (bytes). */
+  readonly maxStringBytes: number;
+  /** Longest `msg` retained (bytes). */
+  readonly maxMessageBytes: number;
+  /** Deepest nesting retained; deeper values become a marker. */
+  readonly maxDepth: number;
+  /** Most array elements / object keys retained per container. */
+  readonly maxContainerSize: number;
+}
+
+export const DEFAULT_LOG_BUDGET: LogBudget = Object.freeze({
+  maxDataBytes: 8 * 1024,
+  maxStringBytes: 2 * 1024,
+  maxMessageBytes: 4 * 1024,
+  maxDepth: 6,
+  maxContainerSize: 64,
+});
+
+/** Total serialized bytes the in-memory ring may retain across all entries. */
+export const DEFAULT_LOG_RING_BYTES = 512 * 1024;
+
+/**
+ * Keys whose values are credentials regardless of shape. Matched on the key
+ * with separators removed and case folded so `auth_token`, `AuthToken`,
+ * `X-API-Key` and `authorization` all hit.
+ */
+const SECRET_KEY =
+  /(token|secret|password|passwd|authorization|cookie|apikey|credential|capability|privatekey|bearer|ticket|lease)/u;
+
+export function isSecretKey(key: string): boolean {
+  return SECRET_KEY.test(key.toLowerCase().replace(/[^a-z0-9]/gu, ""));
+}
+
+const BEARER = /\bBearer\s+[^\s"',;]+/giu;
+const BASIC = /\bBasic\s+[A-Za-z0-9+/=]{8,}/gu;
+const URL_QUERY_SECRET =
+  /([?&](?:[A-Za-z0-9_-]*(?:token|ticket|lease|capability|password|secret|auth|key|signature)[A-Za-z0-9_-]*)=)[^&#\s"']*/giu;
+const URL_USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)([^/\s@"']+)@/giu;
+// Values already handled by the header/URL passes (Bearer/Basic schemes, an
+// earlier redaction marker) are skipped so a second pass cannot eat the
+// surrounding text.
+const KEY_VALUE_SECRET =
+  /\b((?:auth[-_]?token|access[-_]?token|refresh[-_]?token|authorization|capability|password|passwd|secret|token|ticket|lease|api[-_]?key)\s*[:=]\s*["']?)(?!Bearer\b|Basic\b|\[redacted\])[^\s,;"'}]+/giu;
+
+/** Redact credential-shaped substrings inside free text (URLs, headers, k=v). */
+export function redactText(text: string, secrets: ReadonlySet<string> = EMPTY): string {
+  let out = text;
+  for (const secret of secrets)
+    if (secret && out.includes(secret)) out = out.split(secret).join(REDACTED);
+  return out
+    .replace(BEARER, `Bearer ${REDACTED}`)
+    .replace(BASIC, `Basic ${REDACTED}`)
+    .replace(URL_USERINFO, `$1${REDACTED}@`)
+    .replace(URL_QUERY_SECRET, `$1${REDACTED}`)
+    .replace(KEY_VALUE_SECRET, `$1${REDACTED}`);
+}
+
+const EMPTY: ReadonlySet<string> = new Set();
+
+function byteLength(text: string): number {
+  return Buffer.byteLength(text, "utf8");
+}
+
+function truncateString(text: string, maxBytes: number): string {
+  if (byteLength(text) <= maxBytes) return text;
+  // Trim on code points so a multi-byte character is never split.
+  let kept = "";
+  let used = 0;
+  for (const char of text) {
+    const size = byteLength(char);
+    if (used + size > maxBytes) break;
+    kept += char;
+    used += size;
+  }
+  return `${kept}…[truncated ${byteLength(text) - used} bytes]`;
+}
+
+function describeError(error: Error): Record<string, unknown> {
+  const out: Record<string, unknown> = { name: error.name, message: error.message };
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code !== undefined) out.code = code;
+  if (error.stack) out.stack = error.stack;
+  return out;
+}
+
+interface RedactOptions {
+  readonly budget: LogBudget;
+  readonly secrets: ReadonlySet<string>;
+}
+
+function redactValue(
+  value: unknown,
+  depth: number,
+  options: RedactOptions,
+  seen: WeakSet<object>,
+): unknown {
+  const { budget, secrets } = options;
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string")
+    return truncateString(redactText(value, secrets), budget.maxStringBytes);
+  if (typeof value === "number" || typeof value === "boolean") return value;
+  if (typeof value === "bigint") return value.toString();
+  if (typeof value === "symbol" || typeof value === "function") return `[${typeof value}]`;
+  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Error) return redactValue(describeError(value), depth, options, seen);
+  if (Buffer.isBuffer(value) || ArrayBuffer.isView(value))
+    return `[binary ${value.byteLength} bytes]`;
+  if (typeof value !== "object") return String(value);
+  if (seen.has(value)) return "[circular]";
+  if (depth >= budget.maxDepth) return "[depth exceeded]";
+  seen.add(value);
+  try {
+    if (Array.isArray(value)) {
+      const items = value
+        .slice(0, budget.maxContainerSize)
+        .map((item) => redactValue(item, depth + 1, options, seen));
+      if (value.length > budget.maxContainerSize)
+        items.push(`[+${value.length - budget.maxContainerSize} items]`);
+      return items;
+    }
+    if (value instanceof Map) return redactValue(Object.fromEntries(value), depth, options, seen);
+    if (value instanceof Set) return redactValue([...value], depth, options, seen);
+    const out: Record<string, unknown> = {};
+    const keys = Object.keys(value);
+    for (const key of keys.slice(0, budget.maxContainerSize)) {
+      const child = (value as Record<string, unknown>)[key];
+      out[key] =
+        isSecretKey(key) && child != null ? REDACTED : redactValue(child, depth + 1, options, seen);
+    }
+    if (keys.length > budget.maxContainerSize)
+      out["[+keys]"] = keys.length - budget.maxContainerSize;
+    return out;
+  } finally {
+    seen.delete(value);
+  }
+}
+
+/** Redact one arbitrary value (strings, nested objects, errors) under the default budget. */
+export function redactLogValue(
+  value: unknown,
+  secrets: ReadonlySet<string> = EMPTY,
+  budget: LogBudget = DEFAULT_LOG_BUDGET,
+): unknown {
+  return redactValue(value, 0, { budget, secrets }, new WeakSet());
+}
+
+export interface SanitizedLogPayload {
+  /** Redacted, budgeted payload; never contains reserved keys. */
+  readonly data: Record<string, unknown> | undefined;
+  /** Serialized bytes of `data` (0 when absent). */
+  readonly bytes: number;
+  /** True when the payload had to be summarized to fit `maxDataBytes`. */
+  readonly truncated: boolean;
+  /** Caller keys that collided with reserved metadata and were renamed. */
+  readonly renamedKeys: readonly string[];
+}
+
+/**
+ * Redact, protect reserved keys and bound a caller payload. Deterministic:
+ * the same input always yields the same output, so tests can assert exact
+ * shapes.
+ */
+export function sanitizeLogPayload(
+  data: Record<string, unknown> | undefined,
+  options: { secrets?: ReadonlySet<string>; budget?: LogBudget } = {},
+): SanitizedLogPayload {
+  if (!data) return { data: undefined, bytes: 0, truncated: false, renamedKeys: [] };
+  const budget = options.budget ?? DEFAULT_LOG_BUDGET;
+  const secrets = options.secrets ?? EMPTY;
+  const redacted = redactValue(data, 0, { budget, secrets }, new WeakSet()) as Record<
+    string,
+    unknown
+  >;
+  const renamedKeys: string[] = [];
+  const protectedData: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(redacted)) {
+    if (RESERVED.has(key)) {
+      renamedKeys.push(key);
+      protectedData[`${RESERVED_COLLISION_PREFIX}${key}`] = value;
+    } else {
+      protectedData[key] = value;
+    }
+  }
+  let serialized = safeStringify(protectedData);
+  let bytes = byteLength(serialized);
+  if (bytes <= budget.maxDataBytes) {
+    return { data: protectedData, bytes, truncated: false, renamedKeys };
+  }
+  // Over budget even after per-string limits: keep the key list so the record
+  // stays diagnosable, and say how much was dropped.
+  const summary: Record<string, unknown> = {
+    truncated: true,
+    droppedBytes: bytes,
+    keys: Object.keys(protectedData).slice(0, budget.maxContainerSize),
+  };
+  serialized = safeStringify(summary);
+  bytes = byteLength(serialized);
+  return { data: summary, bytes, truncated: true, renamedKeys };
+}
+
+/** Bound a log message: redact and truncate to the message budget. */
+export function sanitizeLogMessage(
+  message: string,
+  secrets: ReadonlySet<string> = EMPTY,
+  budget: LogBudget = DEFAULT_LOG_BUDGET,
+): string {
+  return truncateString(redactText(String(message), secrets), budget.maxMessageBytes);
+}
+
+function safeStringify(value: unknown): string {
+  try {
+    return JSON.stringify(value) ?? "null";
+  } catch {
+    return '"[unserializable]"';
+  }
+}

package/packages/daemon/src/lib/log.ts

@@ -1,4 +1,22 @@
-/** Minimal structured logger for tmux-ide daemon processes. */
+/**
+ * Minimal structured logger for tmux-ide daemon processes.
+ *
+ * Every record is sanitized centrally (`log-sanitize.ts`): credential-shaped
+ * keys and substrings are redacted, payloads are bounded per record and for
+ * the in-memory ring, and the identity metadata a triage relies on (`ts`,
+ * `level`, `component`, `msg`, `pid`, `instanceId`, `version`) can never be
+ * overwritten by caller data. Stream write failures (closed pipe, full disk)
+ * degrade to ring-only logging with one explicit warning; they never crash
+ * the process.
+ */
+
+import {
+  DEFAULT_LOG_BUDGET,
+  DEFAULT_LOG_RING_BYTES,
+  sanitizeLogMessage,
+  sanitizeLogPayload,
+  type LogBudget,
+} from "./log-sanitize.ts";
 
 type Level = "debug" | "info" | "warn" | "error";
 
@@ -10,13 +28,63 @@ export function setLogLevel(level: Level): void {
   minLevel = level;
 }
 
+// ---------------------------------------------------------------------------
+// Identity + secrets
+//
+// The daemon stamps its instance identity once at startup so every record it
+// emits (ring, subscribers and wire) carries `pid`, `instanceId` and
+// `version`. Registered secret literals are redacted wherever they appear.
+// ---------------------------------------------------------------------------
+
+export interface LogIdentity {
+  readonly instanceId?: string;
+  readonly version?: string;
+}
+
+let identity: LogIdentity = {};
+const secrets = new Set<string>();
+
+/** Stamp reserved identity metadata onto every subsequent record. */
+export function setLogIdentity(next: LogIdentity | null): void {
+  identity = next ? { ...next } : {};
+}
+
+export function getLogIdentity(): LogIdentity {
+  return { ...identity };
+}
+
+/** Register a credential literal to redact wherever it appears in a record. */
+export function registerLogSecret(secret: string | null | undefined): void {
+  if (typeof secret === "string" && secret.length >= 8) secrets.add(secret);
+}
+
+/** @internal test seam */
+export function _resetLogStateForTests(): void {
+  identity = {};
+  secrets.clear();
+  logBuffer.length = 0;
+  ringBytes = 0;
+  streamState.stdout = { failed: false, listening: false };
+  streamState.stderr = { failed: false, listening: false };
+  budget = DEFAULT_LOG_BUDGET;
+  ringBudgetBytes = DEFAULT_LOG_RING_BYTES;
+}
+
+/** @internal test seam — shrink budgets to make bounds observable. */
+export function _setLogBudgetForTests(next: Partial<LogBudget> & { ringBytes?: number }): void {
+  const { ringBytes, ...rest } = next;
+  budget = { ...DEFAULT_LOG_BUDGET, ...rest };
+  if (ringBytes !== undefined) ringBudgetBytes = ringBytes;
+}
+
 // ---------------------------------------------------------------------------
 // Ring buffer + subscriber bus
 //
 // Every structured log entry is also captured in an in-memory ring (last
-// `LOG_BUFFER_SIZE` entries) and broadcast to any subscriber. Used by the
-// command-center's `/api/logs/:channel` SSE endpoint so the dashboard
-// BottomPanel Output tab can stream daemon logs without scraping stderr.
+// `LOG_BUFFER_SIZE` entries, at most `ringBudgetBytes` serialized bytes) and
+// broadcast to any subscriber. Used by the command-center's
+// `/api/logs/:channel` SSE endpoint so the dashboard BottomPanel Output tab
+// can stream daemon logs without scraping stderr.
 // ---------------------------------------------------------------------------
 
 export interface LogEntry {
@@ -24,11 +92,18 @@ export interface LogEntry {
   level: Level;
   component: string;
   msg: string;
+  pid?: number;
+  instanceId?: string;
+  version?: string;
   data?: Record<string, unknown>;
 }
 
 const LOG_BUFFER_SIZE = 1_000;
 const logBuffer: LogEntry[] = [];
+const entryBytes = new WeakMap<LogEntry, number>();
+let ringBytes = 0;
+let budget: LogBudget = DEFAULT_LOG_BUDGET;
+let ringBudgetBytes = DEFAULT_LOG_RING_BYTES;
 type Subscriber = (entry: LogEntry) => void;
 const subscribers = new Set<Subscriber>();
 
@@ -37,6 +112,11 @@ export function getLogBuffer(): ReadonlyArray<LogEntry> {
   return logBuffer.slice();
 }
 
+/** Ring occupancy for diagnostics: entry count and retained serialized bytes. */
+export function getLogBufferStats(): { entries: number; bytes: number; budgetBytes: number } {
+  return { entries: logBuffer.length, bytes: ringBytes, budgetBytes: ringBudgetBytes };
+}
+
 /**
  * Subscribe to live log entries. Returns an unsubscribe function. The
  * handler runs synchronously inside the writer — keep it cheap; throw
@@ -50,6 +130,58 @@ export function subscribeLogs(handler: Subscriber): () => void {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Stream degradation
+// ---------------------------------------------------------------------------
+
+type StreamName = "stdout" | "stderr";
+interface StreamState {
+  failed: boolean;
+  listening: boolean;
+}
+const streamState: Record<StreamName, StreamState> = {
+  stdout: { failed: false, listening: false },
+  stderr: { failed: false, listening: false },
+};
+
+/** Which process streams the logger has given up on (diagnostics only). */
+export function getLogStreamFailures(): readonly StreamName[] {
+  return (Object.keys(streamState) as StreamName[]).filter((name) => streamState[name].failed);
+}
+
+function markStreamFailed(name: StreamName, error: unknown): void {
+  if (streamState[name].failed) return;
+  streamState[name].failed = true;
+  const detail = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+  const warning = `[log.ts] ${name} write failed (${detail}); further records are retained in memory only\n`;
+  const other: StreamName = name === "stdout" ? "stderr" : "stdout";
+  if (!streamState[other].failed) {
+    try {
+      process[other].write(warning);
+    } catch {
+      streamState[other].failed = true;
+    }
+  }
+}
+
+function writeToStream(name: StreamName, line: string): void {
+  const state = streamState[name];
+  if (state.failed) return;
+  const stream = process[name];
+  if (!state.listening) {
+    state.listening = true;
+    // A closed pipe (EPIPE) or full disk (ENOSPC) surfaces asynchronously as
+    // an 'error' event; without a listener Node raises it as an uncaught
+    // exception and the daemon dies mid-triage.
+    stream.on("error", (error: unknown) => markStreamFailed(name, error));
+  }
+  try {
+    stream.write(line);
+  } catch (error) {
+    markStreamFailed(name, error);
+  }
+}
+
 function writeStructuredLog(
   level: Level,
   component: string,
@@ -57,38 +189,57 @@ function writeStructuredLog(
   data?: Record<string, unknown>,
 ): void {
   if (LEVEL_RANK[level] < LEVEL_RANK[minLevel]) return;
+  const payload = sanitizeLogPayload(data, { secrets, budget });
   const entry: LogEntry = {
     ts: new Date().toISOString(),
     level,
-    component,
-    msg: message,
-    ...(data ? { data } : {}),
+    component: sanitizeLogMessage(String(component), secrets, budget).slice(0, 128),
+    msg: sanitizeLogMessage(message, secrets, budget),
+    pid: process.pid,
+    ...(identity.instanceId ? { instanceId: identity.instanceId } : {}),
+    ...(identity.version ? { version: identity.version } : {}),
+    ...(payload.data ? { data: payload.data } : {}),
   };
-  // Push to ring + drop oldest when over budget.
+  const size = payload.bytes + Buffer.byteLength(entry.msg, "utf8") + 96;
+  entryBytes.set(entry, size);
+  // Push to ring + drop oldest while over either budget.
   logBuffer.push(entry);
-  if (logBuffer.length > LOG_BUFFER_SIZE) logBuffer.shift();
+  ringBytes += size;
+  while (
+    logBuffer.length > 0 &&
+    (logBuffer.length > LOG_BUFFER_SIZE || ringBytes > ringBudgetBytes)
+  ) {
+    const evicted = logBuffer.shift()!;
+    ringBytes -= entryBytes.get(evicted) ?? 0;
+    if (logBuffer.length === 0) ringBytes = 0;
+  }
   // Fan out to subscribers; isolate failures.
   for (const sub of subscribers) {
     try {
       sub(entry);
     } catch (err) {
       // Avoid recursion via the logger; write directly to stderr.
-      process.stderr.write(
+      writeToStream(
+        "stderr",
         `[log.ts] subscriber threw: ${err instanceof Error ? err.message : String(err)}\n`,
       );
     }
   }
   // Stream form for humans tailing the process. The data field is
-  // serialized inline (matches the previous wire shape).
+  // serialized inline (matches the previous wire shape); reserved metadata
+  // is written last so a caller payload can never shadow it.
   const wire: Record<string, unknown> = {
+    ...(entry.data ?? {}),
     ts: entry.ts,
     level: entry.level,
     component: entry.component,
     msg: entry.msg,
+    pid: entry.pid,
+    ...(entry.instanceId ? { instanceId: entry.instanceId } : {}),
+    ...(entry.version ? { version: entry.version } : {}),
   };
-  if (data) Object.assign(wire, data);
-  const out = level === "error" ? process.stderr : process.stdout;
-  out.write(JSON.stringify(wire) + "\n");
+  if (payload.renamedKeys.length > 0) wire.reservedKeysRenamed = payload.renamedKeys;
+  writeToStream(level === "error" ? "stderr" : "stdout", JSON.stringify(wire) + "\n");
 }
 
 export const logger = {

package/packages/daemon/src/lib/soak-diagnostics.ts

@@ -0,0 +1,183 @@
+/** Pure, allowlisted evidence projection. Never retain response bodies or errors. */
+export const DIAGNOSTICS_MAX_BYTES = 16_384;
+export const RESOURCE_KEYS = [
+  "Timeout",
+  "Immediate",
+  "TCPServerWrap",
+  "TCPSocketWrap",
+  "PipeWrap",
+  "ProcessWrap",
+  "FSEventWrap",
+  "other",
+] as const;
+export const MEMORY_KEYS = ["rss", "heapTotal", "heapUsed", "external", "arrayBuffers"] as const;
+export interface DiagnosticsIdentity {
+  protocolVersion: number;
+  productVersion: string;
+  instanceId: string;
+  startedAt: string;
+  environmentId?: string;
+}
+export interface DiagnosticsSample {
+  daemon: DiagnosticsIdentity;
+  pid: number;
+  uptimeMs: number;
+  sampledAtMs: number;
+  memory: Record<(typeof MEMORY_KEYS)[number], number>;
+  cpu: { user: number; system: number };
+  eventLoop: { idle: number; active: number; utilization: number };
+  activeResources: Record<(typeof RESOURCE_KEYS)[number], number> | null;
+}
+export type DiagnosticsResult =
+  | { status: "ok"; sample: DiagnosticsSample }
+  | {
+      status:
+        | "missing"
+        | "unsupported-endpoint"
+        | "http-error"
+        | "transport-error"
+        | "malformed"
+        | "identity-mismatch";
+      sample: null;
+    };
+const object = (v: unknown): v is Record<string, unknown> =>
+  !!v && typeof v === "object" && !Array.isArray(v);
+const number = (v: unknown): v is number => typeof v === "number" && Number.isFinite(v) && v >= 0;
+const text = (v: unknown): v is string => typeof v === "string" && v.length > 0 && v.length <= 256;
+function numeric<K extends string>(
+  v: unknown,
+  keys: readonly K[],
+  integer = false,
+): Record<K, number> | null {
+  if (!object(v) || !keys.every((k) => number(v[k]) && (!integer || Number.isSafeInteger(v[k]))))
+    return null;
+  return Object.fromEntries(keys.map((k) => [k, v[k]])) as Record<K, number>;
+}
+export function parseSoakDiagnostics(
+  body: string | null,
+  status: number,
+  expected: DiagnosticsIdentity & { pid: number },
+): DiagnosticsResult {
+  const fail = (status: Exclude<DiagnosticsResult["status"], "ok">): DiagnosticsResult => ({
+    status,
+    sample: null,
+  });
+  if (status === 404) return fail("unsupported-endpoint");
+  if (status !== 200) return fail("http-error");
+  if (body === null || body === "") return fail("missing");
+  if (new TextEncoder().encode(body).length > DIAGNOSTICS_MAX_BYTES) return fail("malformed");
+  let raw: unknown;
+  try {
+    raw = JSON.parse(body);
+  } catch {
+    return fail("malformed");
+  }
+  if (!object(raw) || !object(raw.daemon)) return fail("malformed");
+  const d = raw.daemon;
+  if (
+    !Number.isSafeInteger(d.protocolVersion) ||
+    !number(d.protocolVersion) ||
+    !text(d.productVersion) ||
+    !text(d.instanceId) ||
+    !text(d.startedAt) ||
+    !Number.isFinite(Date.parse(d.startedAt)) ||
+    (d.environmentId !== undefined && !text(d.environmentId)) ||
+    !Number.isSafeInteger(raw.pid) ||
+    !number(raw.pid) ||
+    raw.pid === 0
+  )
+    return fail("malformed");
+  if (
+    ["protocolVersion", "productVersion", "instanceId", "startedAt", "environmentId"].some(
+      (k) => d[k] !== expected[k as keyof DiagnosticsIdentity],
+    ) ||
+    raw.pid !== expected.pid
+  )
+    return fail("identity-mismatch");
+  const memory = numeric(raw.memory, MEMORY_KEYS, true);
+  const cpu = numeric(raw.cpu, ["user", "system"], true);
+  const eventLoop = numeric(raw.eventLoop, ["idle", "active", "utilization"]);
+  const activeResources =
+    raw.activeResources === null ? null : numeric(raw.activeResources, RESOURCE_KEYS, true);
+  if (
+    !memory ||
+    !cpu ||
+    !eventLoop ||
+    eventLoop.utilization > 1 ||
+    !number(raw.uptimeMs) ||
+    !number(raw.sampledAtMs) ||
+    (raw.activeResources !== null && !activeResources)
+  )
+    return fail("malformed");
+  return {
+    status: "ok",
+    sample: {
+      daemon: {
+        protocolVersion: d.protocolVersion,
+        productVersion: d.productVersion,
+        instanceId: d.instanceId,
+        startedAt: d.startedAt,
+        ...(d.environmentId !== undefined ? { environmentId: d.environmentId } : {}),
+      },
+      pid: raw.pid,
+      uptimeMs: raw.uptimeMs,
+      sampledAtMs: raw.sampledAtMs,
+      memory,
+      cpu,
+      eventLoop,
+      activeResources,
+    },
+  };
+}
+export type DiagnosticsDelta =
+  | {
+      status: "ok";
+      intervalMs: number;
+      cpuUserMicros: number;
+      cpuSystemMicros: number;
+      cpuPercent: number;
+      eventLoopIdleMs: number;
+      eventLoopActiveMs: number;
+      eventLoopUtilization: number | null;
+    }
+  | {
+      status: "missing-baseline" | "identity-mismatch" | "counter-regression" | "invalid-interval";
+    };
+/** Uptime is monotonic; wall-clock jumps do not change interval rates. */
+export function diagnosticsDelta(
+  previous: DiagnosticsSample | null,
+  current: DiagnosticsSample,
+): DiagnosticsDelta {
+  if (!previous) return { status: "missing-baseline" };
+  if (
+    previous.pid !== current.pid ||
+    ["protocolVersion", "productVersion", "instanceId", "startedAt", "environmentId"].some(
+      (key) =>
+        previous.daemon[key as keyof DiagnosticsIdentity] !==
+        current.daemon[key as keyof DiagnosticsIdentity],
+    )
+  )
+    return { status: "identity-mismatch" };
+  const intervalMs = current.uptimeMs - previous.uptimeMs;
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) return { status: "invalid-interval" };
+  const cpuUserMicros = current.cpu.user - previous.cpu.user;
+  const cpuSystemMicros = current.cpu.system - previous.cpu.system;
+  const eventLoopIdleMs = current.eventLoop.idle - previous.eventLoop.idle;
+  const eventLoopActiveMs = current.eventLoop.active - previous.eventLoop.active;
+  if (![cpuUserMicros, cpuSystemMicros, eventLoopIdleMs, eventLoopActiveMs].every(number))
+    return { status: "counter-regression" };
+  const cpuPercent = (cpuUserMicros + cpuSystemMicros) / (intervalMs * 10);
+  if (!Number.isFinite(cpuPercent)) return { status: "invalid-interval" };
+  const eventTotal = eventLoopIdleMs + eventLoopActiveMs;
+  if (!Number.isFinite(eventTotal)) return { status: "invalid-interval" };
+  return {
+    status: "ok",
+    intervalMs,
+    cpuUserMicros,
+    cpuSystemMicros,
+    cpuPercent,
+    eventLoopIdleMs,
+    eventLoopActiveMs,
+    eventLoopUtilization: eventTotal === 0 ? null : eventLoopActiveMs / eventTotal,
+  };
+}