turboflux 1.0.0

package/dist/cli/telemetry/localFlowTelemetry.d.ts

@@ -0,0 +1,42 @@
+export type FlowTelemetryMetric = 'ui.key_received' | 'ui.key_to_terminal_flush_ms' | 'ui.submit_to_echo_flush_ms' | 'ui.delta_to_tail_flush_ms' | 'ui.frame_render_ms' | 'ui.approval_requested' | 'ui.approval_presented_ms' | 'ui.stream_flush' | 'ui.stream_batch_depth' | 'ui.stream_oldest_age_ms' | 'ui.transcript_mounted_cells' | 'ui.transcript_total_cells' | 'ui.markdown_cache_hit_rate' | 'journal.physical_writes' | 'journal.streaming_batches' | 'flow.reducer_violation';
+export interface NumericHistogram {
+    count: number;
+    sum: number;
+    min: number;
+    max: number;
+    buckets: Record<string, number>;
+}
+export interface LocalFlowTelemetrySnapshot {
+    version: 1;
+    generatedAt: number;
+    platform: NodeJS.Platform;
+    counters: Partial<Record<FlowTelemetryMetric, number>>;
+    histograms: Partial<Record<FlowTelemetryMetric, NumericHistogram>>;
+}
+export interface LocalFlowTelemetryOptions {
+    enabled?: boolean;
+    flushIntervalMs?: number;
+    outputFile?: string;
+    autoFlush?: boolean;
+    now?: () => number;
+}
+export declare class LocalFlowTelemetry {
+    private readonly enabled;
+    private readonly flushIntervalMs;
+    private readonly outputFile;
+    private readonly autoFlush;
+    private readonly now;
+    private snapshot;
+    private timer;
+    private dirty;
+    private closed;
+    constructor(workspacePath: string, options?: LocalFlowTelemetryOptions);
+    count(metric: FlowTelemetryMetric, amount?: number): void;
+    observe(metric: FlowTelemetryMetric, rawValue: number): void;
+    getSnapshot(): LocalFlowTelemetrySnapshot;
+    flush(): boolean;
+    destroy(): void;
+    private changed;
+    private loadSnapshot;
+    private clearTimer;
+}

package/dist/cli/telemetry/localFlowTelemetry.js

@@ -0,0 +1,131 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+const HISTOGRAM_BUCKETS = [1, 4, 8, 16, 33, 50, 100, 250, 500, 1_000, 5_000];
+function emptySnapshot(now) {
+    return {
+        version: 1,
+        generatedAt: now,
+        platform: process.platform,
+        counters: {},
+        histograms: {},
+    };
+}
+function isFiniteRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    return Object.values(value).every(item => Number.isFinite(item));
+}
+export class LocalFlowTelemetry {
+    enabled;
+    flushIntervalMs;
+    outputFile;
+    autoFlush;
+    now;
+    snapshot;
+    timer = null;
+    dirty = false;
+    closed = false;
+    constructor(workspacePath, options = {}) {
+        this.enabled = options.enabled ?? process.env.TURBOFLUX_TELEMETRY !== '0';
+        this.flushIntervalMs = Math.max(100, options.flushIntervalMs ?? 5_000);
+        this.outputFile = options.outputFile ?? join(workspacePath, '.turboflux', 'telemetry', 'flow-metrics-v1.json');
+        this.autoFlush = options.autoFlush ?? true;
+        this.now = options.now ?? Date.now;
+        this.snapshot = this.loadSnapshot() ?? emptySnapshot(this.now());
+    }
+    count(metric, amount = 1) {
+        if (!this.enabled || this.closed || !Number.isFinite(amount))
+            return;
+        this.snapshot.counters[metric] = (this.snapshot.counters[metric] ?? 0) + amount;
+        this.changed();
+    }
+    observe(metric, rawValue) {
+        if (!this.enabled || this.closed || !Number.isFinite(rawValue))
+            return;
+        const value = Math.max(0, rawValue);
+        const histogram = this.snapshot.histograms[metric] ?? {
+            count: 0,
+            sum: 0,
+            min: value,
+            max: value,
+            buckets: {},
+        };
+        histogram.count += 1;
+        histogram.sum += value;
+        histogram.min = Math.min(histogram.min, value);
+        histogram.max = Math.max(histogram.max, value);
+        const bucket = HISTOGRAM_BUCKETS.find(limit => value <= limit);
+        const bucketName = bucket === undefined ? '+Inf' : String(bucket);
+        histogram.buckets[bucketName] = (histogram.buckets[bucketName] ?? 0) + 1;
+        this.snapshot.histograms[metric] = histogram;
+        this.changed();
+    }
+    getSnapshot() {
+        return JSON.parse(JSON.stringify({ ...this.snapshot, generatedAt: this.now() }));
+    }
+    flush() {
+        this.clearTimer();
+        if (!this.enabled || !this.dirty)
+            return true;
+        try {
+            mkdirSync(dirname(this.outputFile), { recursive: true });
+            const nextSnapshot = { ...this.snapshot, generatedAt: this.now() };
+            const temporaryFile = `${this.outputFile}.tmp-${process.pid}`;
+            writeFileSync(temporaryFile, `${JSON.stringify(nextSnapshot, null, 2)}\n`, 'utf8');
+            renameSync(temporaryFile, this.outputFile);
+            this.snapshot = nextSnapshot;
+            this.dirty = false;
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    destroy() {
+        this.flush();
+        this.clearTimer();
+        this.closed = true;
+    }
+    changed() {
+        this.dirty = true;
+        if (!this.autoFlush || this.timer)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = null;
+            this.flush();
+        }, this.flushIntervalMs);
+        this.timer.unref?.();
+    }
+    loadSnapshot() {
+        if (!this.enabled || !existsSync(this.outputFile))
+            return null;
+        try {
+            const parsed = JSON.parse(readFileSync(this.outputFile, 'utf8'));
+            if (parsed.version !== 1 || !isFiniteRecord(parsed.counters ?? {}))
+                return null;
+            const histograms = parsed.histograms ?? {};
+            for (const histogram of Object.values(histograms)) {
+                if (!histogram || !Number.isFinite(histogram.count) || !Number.isFinite(histogram.sum) ||
+                    !Number.isFinite(histogram.min) || !Number.isFinite(histogram.max) || !isFiniteRecord(histogram.buckets)) {
+                    return null;
+                }
+            }
+            return {
+                version: 1,
+                generatedAt: Number.isFinite(parsed.generatedAt) ? parsed.generatedAt : this.now(),
+                platform: parsed.platform === process.platform ? parsed.platform : process.platform,
+                counters: { ...parsed.counters },
+                histograms: JSON.parse(JSON.stringify(histograms)),
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    clearTimer() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+}
+//# sourceMappingURL=localFlowTelemetry.js.map

package/dist/cli/telemetry/localFlowTelemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"localFlowTelemetry.js","sourceRoot":"","sources":["../../../src/cli/telemetry/localFlowTelemetry.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AACxF,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AA4CzC,MAAM,iBAAiB,GAAG,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,KAAK,CAAC,CAAA;AAE5E,SAAS,aAAa,CAAC,GAAW;IAChC,OAAO;QACL,OAAO,EAAE,CAAC;QACV,WAAW,EAAE,GAAG;QAChB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,QAAQ,EAAE,EAAE;QACZ,UAAU,EAAE,EAAE;KACf,CAAA;AACH,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,IAAI,CAAC,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAA;IACrD,OAAO,MAAM,CAAC,MAAM,CAAC,KAAgC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;AAC7F,CAAC;AAED,MAAM,OAAO,kBAAkB;IACZ,OAAO,CAAS;IAChB,eAAe,CAAQ;IACvB,UAAU,CAAQ;IAClB,SAAS,CAAS;IAClB,GAAG,CAAc;IAC1B,QAAQ,CAA4B;IACpC,KAAK,GAAyC,IAAI,CAAA;IAClD,KAAK,GAAG,KAAK,CAAA;IACb,MAAM,GAAG,KAAK,CAAA;IAEtB,YAAY,aAAqB,EAAE,UAAqC,EAAE;QACxE,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,mBAAmB,KAAK,GAAG,CAAA;QACzE,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,OAAO,CAAC,eAAe,IAAI,KAAK,CAAC,CAAA;QACtE,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,IAAI,CAAC,aAAa,EAAE,YAAY,EAAE,WAAW,EAAE,sBAAsB,CAAC,CAAA;QAC9G,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,IAAI,CAAA;QAC1C,IAAI,CAAC,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAA;QAClC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC,YAAY,EAAE,IAAI,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAA;IAClE,CAAC;IAED,KAAK,CAAC,MAA2B,EAAE,MAAM,GAAG,CAAC;QAC3C,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC;YAAE,OAAM;QACpE,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,GAAG,MAAM,CAAA;QAC/E,IAAI,CAAC,OAAO,EAAE,CAAA;IAChB,CAAC;IAED,OAAO,CAAC,MAA2B,EAAE,QAAgB;QACnD,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,MAAM,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC;YAAE,OAAM;QACtE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAA;QACnC,MAAM,SAAS,GAAG,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,IAAI;YACpD,KAAK,EAAE,CAAC;YACR,GAAG,EAAE,CAAC;YACN,GAAG,EAAE,KAAK;YACV,GAAG,EAAE,KAAK;YACV,OAAO,EAAE,EAAE;SACZ,CAAA;QACD,SAAS,CAAC,KAAK,IAAI,CAAC,CAAA;QACpB,SAAS,CAAC,GAAG,IAAI,KAAK,CAAA;QACtB,SAAS,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAC9C,SAAS,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;QAC9C,MAAM,MAAM,GAAG,iBAAiB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,IAAI,KAAK,CAAC,CAAA;QAC9D,MAAM,UAAU,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAA;QACjE,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAA;QACxE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,SAAS,CAAA;QAC5C,IAAI,CAAC,OAAO,EAAE,CAAA;IAChB,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAA+B,CAAA;IAChH,CAAC;IAED,KAAK;QACH,IAAI,CAAC,UAAU,EAAE,CAAA;QACjB,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAA;QAC7C,IAAI,CAAC;YACH,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YACxD,MAAM,YAAY,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAA;YAClE,MAAM,aAAa,GAAG,GAAG,IAAI,CAAC,UAAU,QAAQ,OAAO,CAAC,GAAG,EAAE,CAAA;YAC7D,aAAa,CAAC,aAAa,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;YAClF,UAAU,CAAC,aAAa,EAAE,IAAI,CAAC,UAAU,CAAC,CAAA;YAC1C,IAAI,CAAC,QAAQ,GAAG,YAAY,CAAA;YAC5B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;YAClB,OAAO,IAAI,CAAA;QACb,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAA;QACd,CAAC;IACH,CAAC;IAED,OAAO;QACL,IAAI,CAAC,KAAK,EAAE,CAAA;QACZ,IAAI,CAAC,UAAU,EAAE,CAAA;QACjB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAA;IACpB,CAAC;IAEO,OAAO;QACb,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;QACjB,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,IAAI,CAAC,KAAK;YAAE,OAAM;QACzC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YAC3B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;YACjB,IAAI,CAAC,KAAK,EAAE,CAAA;QACd,CAAC,EAAE,IAAI,CAAC,eAAe,CAAC,CAAA;QACxB,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,EAAE,CAAA;IACtB,CAAC;IAEO,YAAY;QAClB,IAAI,CAAC,IAAI,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC;YAAE,OAAO,IAAI,CAAA;QAC9D,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,CAAC,CAAwC,CAAA;YACvG,IAAI,MAAM,CAAC,OAAO,KAAK,CAAC,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,QAAQ,IAAI,EAAE,CAAC;gBAAE,OAAO,IAAI,CAAA;YAC/E,MAAM,UAAU,GAAG,MAAM,CAAC,UAAU,IAAI,EAAE,CAAA;YAC1C,KAAK,MAAM,SAAS,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;gBAClD,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC;oBACpF,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;oBAC3G,OAAO,IAAI,CAAA;gBACb,CAAC;YACH,CAAC;YACD,OAAO;gBACL,OAAO,EAAE,CAAC;gBACV,WAAW,EAAE,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,WAAY,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,EAAE;gBACnF,QAAQ,EAAE,MAAM,CAAC,QAAQ,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ;gBACnF,QAAQ,EAAE,EAAE,GAAG,MAAM,CAAC,QAAQ,EAAE;gBAChC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,CAAC;aACnD,CAAA;QACH,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAA;QACb,CAAC;IACH,CAAC;IAEO,UAAU;QAChB,IAAI,IAAI,CAAC,KAAK;YAAE,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACxC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAA;IACnB,CAAC;CACF"}

package/dist/cli/telemetry/terminalBaseline.d.ts

@@ -0,0 +1,93 @@
+import type { LocalFlowTelemetrySnapshot, NumericHistogram } from './localFlowTelemetry';
+export type TerminalTransport = 'local' | 'conpty' | 'ssh' | 'container' | 'unknown';
+export interface DistributionSummary {
+    count: number;
+    min: number;
+    mean: number;
+    max: number;
+    p50UpperBound: number;
+    p95UpperBound: number;
+    p99UpperBound: number;
+}
+export interface ExternalPaintEvidence {
+    schemaVersion: 1;
+    method: string;
+    capturedAt: string;
+    sampleCount: number;
+    keyToPaintMs: {
+        p50: number;
+        p95: number;
+        p99: number;
+    };
+    submitToEchoMs: {
+        p50: number;
+        p95: number;
+        p99: number;
+    };
+    deltaToTailMs: {
+        p50: number;
+        p95: number;
+        p99: number;
+    };
+    notes?: string;
+}
+export interface TerminalBaselineOptions {
+    label?: string;
+    transport?: TerminalTransport;
+    environment?: NodeJS.ProcessEnv;
+    platform?: NodeJS.Platform;
+    arch?: string;
+    nodeVersion?: string;
+    interactive?: boolean;
+    columns?: number;
+    rows?: number;
+    minimumSamples?: number;
+    terminalAckSamples?: number[];
+    physicalPaint?: ExternalPaintEvidence;
+    now?: () => number;
+}
+export declare function summarizeHistogram(histogram: NumericHistogram | undefined): DistributionSummary | null;
+export declare function summarizeSamples(samples: number[]): DistributionSummary | null;
+export declare function inferTerminalTransport(environment: NodeJS.ProcessEnv, platform?: NodeJS.Platform): TerminalTransport;
+export declare function buildTerminalBaselineReport(snapshot: LocalFlowTelemetrySnapshot, options?: TerminalBaselineOptions): {
+    schemaVersion: 1;
+    generatedAt: number;
+    label: string;
+    environment: {
+        platform: NodeJS.Platform;
+        arch: string;
+        node: string;
+        terminalProgram: string;
+        terminalVersion: string;
+        transport: TerminalTransport;
+        shell: string;
+        interactive: boolean;
+        columns: number;
+        rows: number;
+        ci: boolean;
+    };
+    evidenceBoundary: {
+        stdoutFlush: string;
+        terminalAck: string;
+        physicalPaint: string;
+    };
+    proxyMetrics: Record<"ui.key_to_terminal_flush_ms" | "ui.submit_to_echo_flush_ms" | "ui.delta_to_tail_flush_ms" | "ui.frame_render_ms", DistributionSummary | null>;
+    terminalAckMs: DistributionSummary | null;
+    physicalPaint: ExternalPaintEvidence | null;
+    safetySignals: {
+        reducerViolations: number;
+    };
+    privacy: {
+        automaticallyIncludesContent: boolean;
+        automaticallyIncludesAbsolutePaths: boolean;
+        operatorSuppliedFields: string[];
+        environmentAllowlist: string[];
+    };
+    gate: {
+        proxyStatus: string;
+        safetyStatus: string;
+        physicalPaintStatus: string;
+        releaseReady: boolean;
+        blockers: string[];
+    };
+};

package/dist/cli/telemetry/terminalBaseline.js

@@ -0,0 +1,199 @@
+import { basename } from 'node:path';
+const PROXY_METRICS = [
+    'ui.key_to_terminal_flush_ms',
+    'ui.submit_to_echo_flush_ms',
+    'ui.delta_to_tail_flush_ms',
+    'ui.frame_render_ms',
+];
+const PROXY_P95_TARGETS = {
+    'ui.key_to_terminal_flush_ms': 50,
+    'ui.submit_to_echo_flush_ms': 50,
+    'ui.delta_to_tail_flush_ms': 100,
+    'ui.frame_render_ms': 33,
+};
+export function summarizeHistogram(histogram) {
+    if (!histogram || histogram.count <= 0)
+        return null;
+    return {
+        count: histogram.count,
+        min: round(histogram.min),
+        mean: round(histogram.sum / histogram.count),
+        max: round(histogram.max),
+        p50UpperBound: percentileBucketUpperBound(histogram, 0.5),
+        p95UpperBound: percentileBucketUpperBound(histogram, 0.95),
+        p99UpperBound: percentileBucketUpperBound(histogram, 0.99),
+    };
+}
+export function summarizeSamples(samples) {
+    const finite = samples.filter(Number.isFinite).map(value => Math.max(0, value)).sort((left, right) => left - right);
+    if (finite.length === 0)
+        return null;
+    const percentile = (ratio) => finite[Math.min(finite.length - 1, Math.ceil(finite.length * ratio) - 1)] ?? 0;
+    return {
+        count: finite.length,
+        min: round(finite[0] ?? 0),
+        mean: round(finite.reduce((sum, value) => sum + value, 0) / finite.length),
+        max: round(finite[finite.length - 1] ?? 0),
+        p50UpperBound: round(percentile(0.5)),
+        p95UpperBound: round(percentile(0.95)),
+        p99UpperBound: round(percentile(0.99)),
+    };
+}
+export function inferTerminalTransport(environment, platform = process.platform) {
+    if (environment.SSH_CONNECTION || environment.SSH_TTY || environment.SSH_CLIENT)
+        return 'ssh';
+    if (environment.container || environment.CONTAINER || environment.KUBERNETES_SERVICE_HOST)
+        return 'container';
+    if (platform === 'win32' && (environment.WT_SESSION || environment.ConEmuANSI || environment.TERM_PROGRAM))
+        return 'conpty';
+    return 'local';
+}
+export function buildTerminalBaselineReport(snapshot, options = {}) {
+    const environment = options.environment ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const minimumSamples = Math.max(1, options.minimumSamples ?? 20);
+    const proxyMetrics = Object.fromEntries(PROXY_METRICS.map(metric => [
+        metric,
+        summarizeHistogram(snapshot.histograms[metric]),
+    ]));
+    const proxyFailures = [];
+    const proxyInsufficient = [];
+    for (const metric of PROXY_METRICS) {
+        const summary = proxyMetrics[metric];
+        if (!summary || summary.count < minimumSamples) {
+            proxyInsufficient.push(`${metric} requires at least ${minimumSamples} samples`);
+            continue;
+        }
+        const target = PROXY_P95_TARGETS[metric];
+        if (target !== undefined && summary.p95UpperBound > target) {
+            proxyFailures.push(`${metric} p95 upper bound ${summary.p95UpperBound}ms exceeds ${target}ms`);
+        }
+    }
+    const paintFailures = validatePhysicalPaint(options.physicalPaint, minimumSamples);
+    const reducerViolations = snapshot.counters['flow.reducer_violation'] ?? 0;
+    const safetyFailures = [
+        ...(reducerViolations > 0 ? [`flow.reducer_violation is ${reducerViolations}, expected 0`] : []),
+    ];
+    const blockers = [
+        ...proxyFailures,
+        ...proxyInsufficient,
+        ...safetyFailures,
+        ...(options.physicalPaint ? paintFailures : ['physical paint evidence is required for release acceptance']),
+    ];
+    return {
+        schemaVersion: 1,
+        generatedAt: options.now?.() ?? Date.now(),
+        label: options.label?.trim() || 'unnamed-terminal-baseline',
+        environment: {
+            platform,
+            arch: options.arch ?? process.arch,
+            node: options.nodeVersion ?? process.version,
+            terminalProgram: terminalProgram(environment),
+            terminalVersion: safeEnvironmentLabel(environment.TERM_PROGRAM_VERSION),
+            transport: options.transport ?? inferTerminalTransport(environment, platform),
+            shell: shellName(environment),
+            interactive: options.interactive ?? Boolean(process.stdin.isTTY && process.stdout.isTTY),
+            columns: Math.max(0, options.columns ?? process.stdout.columns ?? 0),
+            rows: Math.max(0, options.rows ?? process.stdout.rows ?? 0),
+            ci: truthy(environment.CI),
+        },
+        evidenceBoundary: {
+            stdoutFlush: 'measured: application event to stdout write callback; not physical paint',
+            terminalAck: options.terminalAckSamples?.length
+                ? 'measured: ANSI DSR round trip; terminal processing acknowledgement, not physical paint'
+                : 'not measured; run with --probe-ack',
+            physicalPaint: options.physicalPaint
+                ? `external evidence supplied via ${options.physicalPaint.method}`
+                : 'external evidence required; use camera/high-frame-rate or platform compositor instrumentation',
+        },
+        proxyMetrics,
+        terminalAckMs: summarizeSamples(options.terminalAckSamples ?? []),
+        physicalPaint: options.physicalPaint ?? null,
+        safetySignals: {
+            reducerViolations,
+        },
+        privacy: {
+            automaticallyIncludesContent: false,
+            automaticallyIncludesAbsolutePaths: false,
+            operatorSuppliedFields: ['label', 'physicalPaint.method', 'physicalPaint.notes'],
+            environmentAllowlist: ['platform', 'arch', 'node', 'terminal program/version', 'transport', 'shell basename', 'TTY geometry', 'CI boolean'],
+        },
+        gate: {
+            proxyStatus: proxyFailures.length > 0 ? 'failed' : proxyInsufficient.length > 0 ? 'insufficient-samples' : 'passed',
+            safetyStatus: safetyFailures.length > 0 ? 'failed' : 'passed',
+            physicalPaintStatus: options.physicalPaint
+                ? paintFailures.length > 0 ? 'failed' : 'passed'
+                : 'external-required',
+            releaseReady: blockers.length === 0,
+            blockers,
+        },
+    };
+}
+function percentileBucketUpperBound(histogram, ratio) {
+    const buckets = Object.entries(histogram.buckets)
+        .map(([label, count]) => ({ upper: label === '+Inf' ? Number.POSITIVE_INFINITY : Number(label), count }))
+        .filter(bucket => Number.isFinite(bucket.count) && bucket.count > 0 && !Number.isNaN(bucket.upper))
+        .sort((left, right) => left.upper - right.upper);
+    const targetRank = Math.max(1, Math.ceil(histogram.count * ratio));
+    let seen = 0;
+    for (const bucket of buckets) {
+        seen += bucket.count;
+        if (seen >= targetRank)
+            return round(Number.isFinite(bucket.upper) ? bucket.upper : histogram.max);
+    }
+    return round(histogram.max);
+}
+function validatePhysicalPaint(evidence, minimumSamples) {
+    if (!evidence)
+        return [];
+    const failures = [];
+    if (evidence.schemaVersion !== 1)
+        failures.push('physical paint evidence schemaVersion must be 1');
+    if (!evidence.method.trim())
+        failures.push('physical paint evidence method is required');
+    if (evidence.sampleCount < minimumSamples)
+        failures.push(`physical paint evidence requires at least ${minimumSamples} samples`);
+    for (const [name, distribution] of Object.entries({
+        keyToPaintMs: evidence.keyToPaintMs,
+        submitToEchoMs: evidence.submitToEchoMs,
+        deltaToTailMs: evidence.deltaToTailMs,
+    })) {
+        const values = [distribution.p50, distribution.p95, distribution.p99];
+        if (values.some(value => !Number.isFinite(value) || value < 0)) {
+            failures.push(`${name} must contain finite non-negative values`);
+        }
+        else if (distribution.p50 > distribution.p95 || distribution.p95 > distribution.p99) {
+            failures.push(`${name} percentiles must be monotonic`);
+        }
+    }
+    if (evidence.keyToPaintMs.p95 > 50 || evidence.keyToPaintMs.p99 > 100) {
+        failures.push('physical key-to-paint exceeds p95 50ms or p99 100ms');
+    }
+    if (evidence.submitToEchoMs.p95 > 50)
+        failures.push('physical submit-to-echo exceeds p95 50ms');
+    if (evidence.deltaToTailMs.p95 > 100)
+        failures.push('physical delta-to-tail exceeds p95 100ms');
+    return failures;
+}
+function terminalProgram(environment) {
+    if (environment.WT_SESSION)
+        return 'Windows Terminal';
+    if (environment.ConEmuANSI)
+        return 'ConEmu';
+    return safeEnvironmentLabel(environment.TERM_PROGRAM) || safeEnvironmentLabel(environment.TERM) || 'unknown';
+}
+function shellName(environment) {
+    const shell = environment.ComSpec || environment.COMSPEC || environment.SHELL;
+    return shell ? basename(shell) : 'unknown';
+}
+function safeEnvironmentLabel(value) {
+    return value?.replace(/[\u0000-\u001f\u007f]/g, '').trim().slice(0, 80) || '';
+}
+function truthy(value) {
+    const normalized = value?.trim().toLowerCase();
+    return normalized === '1' || normalized === 'true' || normalized === 'yes' || normalized === 'on';
+}
+function round(value) {
+    return Number(value.toFixed(3));
+}
+//# sourceMappingURL=terminalBaseline.js.map

package/dist/cli/telemetry/terminalBaseline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminalBaseline.js","sourceRoot":"","sources":["../../../src/cli/telemetry/terminalBaseline.ts"],"names":[],"mappings":"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"}

package/dist/cli/telemetry/terminalLatencyTracker.d.ts

@@ -0,0 +1,24 @@
+import type { FlowTelemetryMetric } from './localFlowTelemetry';
+type TerminalLatencyMetric = Extract<FlowTelemetryMetric, 'ui.key_to_terminal_flush_ms' | 'ui.submit_to_echo_flush_ms' | 'ui.delta_to_tail_flush_ms'>;
+export interface TerminalLatencyTrackerOptions {
+    now?: () => number;
+    maxPendingSamples?: number;
+}
+export declare class TerminalLatencyTracker {
+    private readonly observe;
+    private readonly now;
+    private readonly maxPendingSamples;
+    private pending;
+    private inFlight;
+    constructor(observe: (metric: TerminalLatencyMetric, value: number) => void, options?: TerminalLatencyTrackerOptions);
+    noteKeyReceived(at?: number): void;
+    noteSubmit(at?: number): void;
+    noteDeltaReceived(at?: number): void;
+    hasPending(): boolean;
+    beginTerminalFlush(): boolean;
+    completeTerminalFlush(at?: number): void;
+    cancelTerminalFlush(): void;
+    private push;
+    private observeSamples;
+}
+export {};

package/dist/cli/telemetry/terminalLatencyTracker.js

@@ -0,0 +1,59 @@
+import { performance } from 'node:perf_hooks';
+function emptySamples() {
+    return { key: [], submit: [], delta: [] };
+}
+export class TerminalLatencyTracker {
+    observe;
+    now;
+    maxPendingSamples;
+    pending = emptySamples();
+    inFlight = null;
+    constructor(observe, options = {}) {
+        this.observe = observe;
+        this.now = options.now ?? performance.now.bind(performance);
+        this.maxPendingSamples = Math.max(1, options.maxPendingSamples ?? 256);
+    }
+    noteKeyReceived(at = this.now()) {
+        this.push(this.pending.key, at);
+    }
+    noteSubmit(at = this.now()) {
+        this.push(this.pending.submit, at);
+    }
+    noteDeltaReceived(at = this.now()) {
+        this.push(this.pending.delta, at);
+    }
+    hasPending() {
+        return this.pending.key.length > 0 || this.pending.submit.length > 0 || this.pending.delta.length > 0;
+    }
+    beginTerminalFlush() {
+        if (this.inFlight || !this.hasPending())
+            return false;
+        this.inFlight = this.pending;
+        this.pending = emptySamples();
+        return true;
+    }
+    completeTerminalFlush(at = this.now()) {
+        const samples = this.inFlight;
+        this.inFlight = null;
+        if (!samples)
+            return;
+        this.observeSamples('ui.key_to_terminal_flush_ms', samples.key, at);
+        this.observeSamples('ui.submit_to_echo_flush_ms', samples.submit, at);
+        this.observeSamples('ui.delta_to_tail_flush_ms', samples.delta, at);
+    }
+    cancelTerminalFlush() {
+        this.inFlight = null;
+    }
+    push(samples, at) {
+        if (!Number.isFinite(at))
+            return;
+        samples.push(at);
+        if (samples.length > this.maxPendingSamples)
+            samples.splice(0, samples.length - this.maxPendingSamples);
+    }
+    observeSamples(metric, samples, flushedAt) {
+        for (const startedAt of samples)
+            this.observe(metric, Math.max(0, flushedAt - startedAt));
+    }
+}
+//# sourceMappingURL=terminalLatencyTracker.js.map

package/dist/cli/telemetry/terminalLatencyTracker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminalLatencyTracker.js","sourceRoot":"","sources":["../../../src/cli/telemetry/terminalLatencyTracker.ts"],"names":[],"mappings":"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"}

package/dist/cli/terminalLayout.d.ts

@@ -0,0 +1,2 @@
+export declare function getSafeFrameWidth(columns: number, reserveColumns?: number, minWidth?: number): number;
+export declare function getSafeViewportWidth(columns: number): number;

package/dist/cli/terminalLayout.js

@@ -0,0 +1,16 @@
+export function getSafeFrameWidth(columns, reserveColumns = 4, minWidth = 20) {
+    const terminalColumns = Number.isFinite(columns) && columns > 0
+        ? Math.floor(columns)
+        : 80;
+    const reserved = Math.max(1, Math.floor(reserveColumns));
+    const maxSafeWidth = Math.max(1, terminalColumns - reserved);
+    const preferred = Math.max(minWidth, maxSafeWidth);
+    return Math.min(preferred, maxSafeWidth);
+}
+export function getSafeViewportWidth(columns) {
+    const terminalColumns = Number.isFinite(columns) && columns > 0
+        ? Math.floor(columns)
+        : 80;
+    return Math.max(1, terminalColumns - 1);
+}
+//# sourceMappingURL=terminalLayout.js.map

package/dist/cli/terminalLayout.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminalLayout.js","sourceRoot":"","sources":["../../src/cli/terminalLayout.ts"],"names":[],"mappings":"AAAA,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,cAAc,GAAG,CAAC,EAAE,QAAQ,GAAG,EAAE;IAClF,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC;QAC7D,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;QACrB,CAAC,CAAC,EAAE,CAAA;IACN,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAA;IACxD,MAAM,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,GAAG,QAAQ,CAAC,CAAA;IAC5D,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;IAElD,OAAO,IAAI,CAAC,GAAG,CAAC,SAAS,EAAE,YAAY,CAAC,CAAA;AAC1C,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,MAAM,eAAe,GAAG,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC;QAC7D,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;QACrB,CAAC,CAAC,EAAE,CAAA;IAEN,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,eAAe,GAAG,CAAC,CAAC,CAAA;AACzC,CAAC"}

package/dist/cli/terminalMouse.d.ts

@@ -0,0 +1,10 @@
+export interface TerminalMouseWheelEvent {
+    direction: 'up' | 'down';
+    x: number;
+    y: number;
+}
+export declare const ENABLE_MOUSE_TRACKING = "\u001B[?1000h\u001B[?1006h";
+export declare const DISABLE_MOUSE_TRACKING = "\u001B[?1006l\u001B[?1000l";
+export declare function parseTerminalMouseWheel(input: string): TerminalMouseWheelEvent[];
+export declare function isTerminalMouseInput(input: string): boolean;
+export declare function shouldEnableMouseTracking(interactive: boolean, fixedViewport: boolean, environment?: NodeJS.ProcessEnv): boolean;

package/dist/cli/terminalMouse.js

@@ -0,0 +1,29 @@
+export const ENABLE_MOUSE_TRACKING = '\u001b[?1000h\u001b[?1006h';
+export const DISABLE_MOUSE_TRACKING = '\u001b[?1006l\u001b[?1000l';
+export function parseTerminalMouseWheel(input) {
+    const events = [];
+    const pattern = /(?:\u001b)?\[<(\d+);(\d+);(\d+)[mM]/g;
+    for (const match of input.matchAll(pattern)) {
+        const button = Number(match[1]);
+        if ((button & 64) !== 64)
+            continue;
+        events.push({
+            direction: (button & 1) === 0 ? 'up' : 'down',
+            x: Number(match[2]),
+            y: Number(match[3]),
+        });
+    }
+    return events;
+}
+export function isTerminalMouseInput(input) {
+    return /(?:\u001b)?\[<\d+;\d+;\d+[mM]/.test(input);
+}
+export function shouldEnableMouseTracking(interactive, fixedViewport, environment = process.env) {
+    if (!interactive || !fixedViewport)
+        return false;
+    if (environment.TERM?.trim().toLowerCase() === 'dumb')
+        return false;
+    const preference = environment.TURBOFLUX_MOUSE?.trim().toLowerCase();
+    return !['0', 'false', 'off', 'no'].includes(preference || '');
+}
+//# sourceMappingURL=terminalMouse.js.map

package/dist/cli/terminalMouse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"terminalMouse.js","sourceRoot":"","sources":["../../src/cli/terminalMouse.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,qBAAqB,GAAG,4BAA4B,CAAA;AACjE,MAAM,CAAC,MAAM,sBAAsB,GAAG,4BAA4B,CAAA;AAElE,MAAM,UAAU,uBAAuB,CAAC,KAAa;IACnD,MAAM,MAAM,GAA8B,EAAE,CAAA;IAC5C,MAAM,OAAO,GAAG,sCAAsC,CAAA;IAEtD,KAAK,MAAM,KAAK,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5C,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAC/B,IAAI,CAAC,MAAM,GAAG,EAAE,CAAC,KAAK,EAAE;YAAE,SAAQ;QAClC,MAAM,CAAC,IAAI,CAAC;YACV,SAAS,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM;YAC7C,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACnB,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACpB,CAAC,CAAA;IACJ,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,KAAa;IAChD,OAAO,+BAA+B,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;AACpD,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,WAAoB,EACpB,aAAsB,EACtB,cAAiC,OAAO,CAAC,GAAG;IAE5C,IAAI,CAAC,WAAW,IAAI,CAAC,aAAa;QAAE,OAAO,KAAK,CAAA;IAChD,IAAI,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,KAAK,MAAM;QAAE,OAAO,KAAK,CAAA;IACnE,MAAM,UAAU,GAAG,WAAW,CAAC,eAAe,EAAE,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;IACpE,OAAO,CAAC,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,QAAQ,CAAC,UAAU,IAAI,EAAE,CAAC,CAAA;AAChE,CAAC"}