nx 23.1.0-beta.2 → 23.1.0-beta.4

package/dist/src/tasks-runner/life-cycles/performance-life-cycle.d.ts

@@ -0,0 +1,59 @@
+import type { BatchInfo, PerformanceSummaryPayload } from '../../native';
+import { TaskGraph } from '../../config/task-graph';
+import { LifeCycle, TaskResult } from '../life-cycle';
+import { type PerformanceLifeCycleOptions, type PerformanceSummary } from './performance-analysis';
+/**
+ * Measures how much wall-clock a run loses to parallelism contention versus its
+ * critical-path floor, and reports it at the end of a run. Added on every run by
+ * `constructLifeCycles`, but only emitted where the report is flushed (the CLI
+ * `invokeTasksRunner` path) — the programmatic `init-tasks-runner` path collects
+ * timings but never displays them.
+ *
+ * overhead = runDuration − criticalPathDuration, split by CAUSE off the occupancy
+ * timeline: slot-queued time (recoverable by parallelism / machines) versus
+ * coordinator time (hashing, scheduling, continuous-dep waits).
+ *
+ * Scope: discrete tasks only. Continuous tasks (no end time) are excluded; a
+ * discrete task's wait for a continuous dependency to start is eligibility, not
+ * contention.
+ */
+export declare class PerformanceLifeCycle implements LifeCycle {
+    private readonly taskGraph;
+    private readonly options;
+    private readonly timings;
+    /** taskId → terminal status (cache hit vs ran), for the cache summary. */
+    private readonly statuses;
+    /** taskId → other tasks in its batch (batches run sequentially). */
+    private readonly batchSiblings;
+    /** Resolved `--parallel`, set by the runner via {@link startCommand}'s second arg once the thread pool is sized. */
+    private parallel;
+    constructor(taskGraph: TaskGraph, options?: PerformanceLifeCycleOptions);
+    /**
+     * The runner passes the resolved `--parallel` (getThreadPoolSize's `discrete`) as the
+     * second arg; the first (thread count) is for the TUI and ignored here.
+     */
+    startCommand(_threadCount?: number, parallel?: number): void;
+    registerRunningBatch(_batchId: string, batchInfo: BatchInfo): void;
+    endTasks(taskResults: TaskResult[]): void;
+    private entry;
+    /** Analyze the collected timings into a structured summary, or `null` when no discrete task timings were recorded. */
+    getSummary(): PerformanceSummary | null;
+}
+/**
+ * Structured report for the TUI's exit-countdown popup, or null when nothing to
+ * show. Clears the active lifecycle so the popup owns the report and a later terminal
+ * flush can't re-print it. Best-effort: a throw degrades to null.
+ */
+export declare function getPerformanceSummaryPayload(): PerformanceSummaryPayload | null;
+/**
+ * The performance report payload for `endCommand`'s TUI exit popup, or undefined when the
+ * report should instead be flushed to the terminal — non-TUI runs, or a single task (the
+ * complement of run-command's flush gate). Reading it consumes the report so the flush
+ * won't reprint it.
+ */
+export declare function getPerformanceReport(taskCount: number): PerformanceSummaryPayload | undefined;
+/**
+ * Print the performance report (if enabled) after the run summary. Called once the
+ * terminal is restored, so it appears in every output mode including the TUI.
+ */
+export declare function flushPerformanceReport(): void;

package/dist/src/tasks-runner/life-cycles/performance-life-cycle.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PerformanceLifeCycle = void 0;
+exports.getPerformanceSummaryPayload = getPerformanceSummaryPayload;
+exports.getPerformanceReport = getPerformanceReport;
+exports.flushPerformanceReport = flushPerformanceReport;
+const performance_report_1 = require("./performance-report");
+const is_tui_enabled_1 = require("../is-tui-enabled");
+const performance_analysis_1 = require("./performance-analysis");
+/**
+ * Measures how much wall-clock a run loses to parallelism contention versus its
+ * critical-path floor, and reports it at the end of a run. Added on every run by
+ * `constructLifeCycles`, but only emitted where the report is flushed (the CLI
+ * `invokeTasksRunner` path) — the programmatic `init-tasks-runner` path collects
+ * timings but never displays them.
+ *
+ * overhead = runDuration − criticalPathDuration, split by CAUSE off the occupancy
+ * timeline: slot-queued time (recoverable by parallelism / machines) versus
+ * coordinator time (hashing, scheduling, continuous-dep waits).
+ *
+ * Scope: discrete tasks only. Continuous tasks (no end time) are excluded; a
+ * discrete task's wait for a continuous dependency to start is eligibility, not
+ * contention.
+ */
+class PerformanceLifeCycle {
+    constructor(taskGraph, options = {}) {
+        this.taskGraph = taskGraph;
+        this.options = options;
+        this.timings = new Map();
+        /** taskId → terminal status (cache hit vs ran), for the cache summary. */
+        this.statuses = new Map();
+        /** taskId → other tasks in its batch (batches run sequentially). */
+        this.batchSiblings = new Map();
+        /** Resolved `--parallel`, set by the runner via {@link startCommand}'s second arg once the thread pool is sized. */
+        this.parallel = 1;
+        activePerformanceLifeCycle = this;
+    }
+    // === Lifecycle hooks (called by the orchestrator as the run progresses) ===
+    /**
+     * The runner passes the resolved `--parallel` (getThreadPoolSize's `discrete`) as the
+     * second arg; the first (thread count) is for the TUI and ignored here.
+     */
+    startCommand(_threadCount, parallel) {
+        if (parallel != null) {
+            this.parallel = parallel;
+        }
+    }
+    registerRunningBatch(_batchId, batchInfo) {
+        for (const id of batchInfo.taskIds) {
+            this.batchSiblings.set(id, batchInfo.taskIds.filter((other) => other !== id));
+        }
+    }
+    endTasks(taskResults) {
+        // Called incrementally (per group/batch); accumulate so the last call sees every timing.
+        for (const { task, status } of taskResults) {
+            const entry = this.entry(task.id);
+            // `!= null`, not truthiness: synthetic/relative timelines can legitimately start at 0.
+            if (task.startTime != null) {
+                entry.startTime = task.startTime;
+            }
+            if (task.endTime != null) {
+                entry.endTime = task.endTime;
+            }
+            if (status != null) {
+                this.statuses.set(task.id, status);
+            }
+        }
+    }
+    entry(taskId) {
+        let entry = this.timings.get(taskId);
+        if (!entry) {
+            entry = { continuous: this.taskGraph.tasks[taskId]?.continuous ?? false };
+            this.timings.set(taskId, entry);
+        }
+        return entry;
+    }
+    /** Analyze the collected timings into a structured summary, or `null` when no discrete task timings were recorded. */
+    getSummary() {
+        return new performance_analysis_1.PerformanceAnalysis(this.timings, this.statuses, this.taskGraph, this.batchSiblings, this.parallel, this.options).summary();
+    }
+}
+exports.PerformanceLifeCycle = PerformanceLifeCycle;
+/** The most recently constructed performance lifecycle, read after the run. Cleared once consumed. */
+let activePerformanceLifeCycle = null;
+/**
+ * Structured report for the TUI's exit-countdown popup, or null when nothing to
+ * show. Clears the active lifecycle so the popup owns the report and a later terminal
+ * flush can't re-print it. Best-effort: a throw degrades to null.
+ */
+function getPerformanceSummaryPayload() {
+    const lifeCycle = activePerformanceLifeCycle;
+    if (!lifeCycle) {
+        return null;
+    }
+    try {
+        const summary = lifeCycle.getSummary();
+        if (!summary) {
+            return null;
+        }
+        activePerformanceLifeCycle = null;
+        return (0, performance_report_1.buildExitSummaryPayload)(summary);
+    }
+    catch (e) {
+        // Best-effort: the report must never break the run. Surface the cause only under
+        // verbose logging so a missing report stays debuggable.
+        if (process.env.NX_VERBOSE_LOGGING === 'true') {
+            console.error(e);
+        }
+        return null;
+    }
+}
+/**
+ * The performance report payload for `endCommand`'s TUI exit popup, or undefined when the
+ * report should instead be flushed to the terminal — non-TUI runs, or a single task (the
+ * complement of run-command's flush gate). Reading it consumes the report so the flush
+ * won't reprint it.
+ */
+function getPerformanceReport(taskCount) {
+    if (!(0, is_tui_enabled_1.isTuiEnabled)() || taskCount <= 1) {
+        return undefined;
+    }
+    return getPerformanceSummaryPayload() ?? undefined;
+}
+/**
+ * Print the performance report (if enabled) after the run summary. Called once the
+ * terminal is restored, so it appears in every output mode including the TUI.
+ */
+function flushPerformanceReport() {
+    const lifeCycle = activePerformanceLifeCycle;
+    activePerformanceLifeCycle = null;
+    if (!lifeCycle) {
+        return;
+    }
+    // Cosmetic report; a throw (e.g. EPIPE to a closed pipe) must never mask the
+    // real task error or fail an otherwise successful run.
+    try {
+        const summary = lifeCycle.getSummary();
+        if (!summary) {
+            return;
+        }
+        // restore_terminal cooks the terminal back post-TUI, so console.log's plain \n
+        // renders fine; it also supplies the single trailing newline formatReport omits.
+        console.log((0, performance_report_1.formatReport)(summary));
+    }
+    catch (e) {
+        // Best-effort report; never let it affect the run's exit behavior. Surface the
+        // cause only under verbose logging.
+        if (process.env.NX_VERBOSE_LOGGING === 'true') {
+            console.error(e);
+        }
+    }
+}

package/dist/src/tasks-runner/life-cycles/performance-report.d.ts

@@ -0,0 +1,62 @@
+import type { PerformanceSummaryPayload } from '../../native';
+import { formatDuration } from '../../native';
+import type { PerformanceSummary } from './performance-analysis';
+/**
+ * A recommendation built from structured parts so the link text comes from the
+ * link definition (not a substring scanned out of the assembled report). A part
+ * is either literal text or a {@link RecLink}; the renderers below project the
+ * same parts to the terminal string, the payload string, and the popup links.
+ */
+type RecPart = string | RecLink;
+export type Recommendation = RecPart[];
+/**
+ * A docs link inside a recommendation, in one of two styles:
+ *
+ * - `url`   — the URL itself is the visible text. The clean URL shows (and is the
+ *   OSC 8 label), the utm-tagged URL is the click target. Without OSC 8 the tagged
+ *   URL prints verbatim (e.g. the agents recs, the footer).
+ * - `phrase` — a sentence is the visible text and the whole of it links to the
+ *   tagged URL. Without OSC 8 the tagged URL is appended as ` → <url>` (the
+ *   remote-cache CTA). The payload string for a phrase link is URL-less: the Rust
+ *   popup re-links the phrase from {@link PerformanceSummaryPayload.links}.
+ */
+interface RecLink {
+    /** Visible label: the clean URL (`url`) or the sentence (`phrase`). */
+    visible: string;
+    /** OSC 8 click target / appended URL: always the utm-tagged URL. */
+    href: string;
+    style: 'url' | 'phrase';
+}
+/**
+ * The recommendation string the napi payload ships and the Rust popup matches
+ * against. A `url` link keeps its tagged URL inline; a `phrase` link is URL-less
+ * (the popup re-links it from {@link PerformanceSummaryPayload.links}).
+ */
+export declare function recommendationToPayloadString(rec: Recommendation): string;
+/** Below this (ms) overhead is noise, not worth a recommendation. */
+export declare const MEANINGFUL_OVERHEAD = 1000;
+export { formatDuration };
+/** Actionable levers to go faster, one rec per lever. The critical-path case has two (shorten the chain, distribute the rest). Agents advice is omitted unless `canDistribute`. */
+export declare function buildRecommendation(args: {
+    recoverableByParallel: number;
+    recoverableByMachines: number;
+    coordinatorDominated: boolean;
+    runDuration: number;
+    parallel: number;
+    cores: number;
+    canDistribute: boolean;
+    distributing: boolean;
+    criticalPathTop: Array<{
+        id: string;
+        duration: number;
+    }>;
+}): Recommendation[];
+/** The full performance report as a terminal string (the TUI popup renders natively from {@link buildExitSummaryPayload} instead). */
+export declare function formatReport(s: PerformanceSummary): string;
+/**
+ * Build the payload for the TUI's exit-countdown popup, which renders natively in Rust
+ * (the terminal path uses {@link formatReport}). The shape is the generated napi
+ * {@link PerformanceSummaryPayload}, imported not re-declared so the producer and the
+ * Rust struct can't drift.
+ */
+export declare function buildExitSummaryPayload(s: PerformanceSummary): PerformanceSummaryPayload;

package/dist/src/tasks-runner/life-cycles/performance-report.js

@@ -0,0 +1,318 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatDuration = exports.MEANINGFUL_OVERHEAD = void 0;
+exports.recommendationToPayloadString = recommendationToPayloadString;
+exports.buildRecommendation = buildRecommendation;
+exports.formatReport = formatReport;
+exports.buildExitSummaryPayload = buildExitSummaryPayload;
+const native_1 = require("../../native");
+Object.defineProperty(exports, "formatDuration", { enumerable: true, get: function () { return native_1.formatDuration; } });
+const terminal_link_1 = require("../../utils/terminal-link");
+const NX_AGENTS_URL = 'https://nx.dev/ci/features/distribute-task-execution';
+const NX_REMOTE_CACHE_URL = 'https://nx.dev/ci/features/remote-cache';
+const NX_PERFORMANCE_URL = 'https://nx.dev/docs/concepts/ci-concepts/parallelization-distribution';
+/** utm tag attributing report clicks back to it. */
+const UTM = '?utm=performance-report';
+const NX_PERFORMANCE_LINK = `${NX_PERFORMANCE_URL}${UTM}`;
+const NX_AGENTS_LINK = `${NX_AGENTS_URL}${UTM}`;
+const NX_REMOTE_CACHE_LINK = `${NX_REMOTE_CACHE_URL}${UTM}`;
+const NX_PERFORMANCE_LABEL = `Learn how to improve your run's performance`;
+/**
+ * Whole-phrase CTA: the whole sentence is the link. The Rust TUI popup keeps no
+ * copy of this string; it gets the phrase + href from the exit payload's `links`.
+ */
+const NX_REMOTE_CACHE_CTA = 'Drastically reduce your run duration by sharing a cache across your team and CI';
+function urlLink(cleanUrl, taggedUrl) {
+    return { visible: cleanUrl, href: taggedUrl, style: 'url' };
+}
+function phraseLink(phrase, taggedUrl) {
+    return { visible: phrase, href: taggedUrl, style: 'phrase' };
+}
+function isRecLink(part) {
+    return typeof part !== 'string';
+}
+/**
+ * The recommendation string the napi payload ships and the Rust popup matches
+ * against. A `url` link keeps its tagged URL inline; a `phrase` link is URL-less
+ * (the popup re-links it from {@link PerformanceSummaryPayload.links}).
+ */
+function recommendationToPayloadString(rec) {
+    return rec
+        .map((part) => !isRecLink(part) ? part : part.style === 'url' ? part.href : part.visible)
+        .join('');
+}
+/**
+ * The recommendation as a terminal string. With OSC 8 each link becomes a
+ * hyperlink (clean URL or whole phrase as the visible label, tagged URL the
+ * target). Without it, a `url` link prints its tagged URL and a `phrase` link
+ * gets ` → <tagged url>` appended — `terminalLink` can't do this since it drops
+ * the URL entirely when hyperlinks are off.
+ */
+function recommendationToTerminalString(rec, hyperlinks) {
+    return rec
+        .map((part) => {
+        if (!isRecLink(part)) {
+            return part;
+        }
+        if (hyperlinks) {
+            return (0, terminal_link_1.terminalLink)(part.visible, part.href);
+        }
+        return part.style === 'url'
+            ? part.href
+            : `${part.visible} → ${part.href}`;
+    })
+        .join('');
+}
+/** The popup links for the phrase-style CTAs in a recommendation list (url links live inline in the strings). */
+function recommendationLinks(recommendations) {
+    return recommendations.flatMap((rec) => rec
+        .filter(isRecLink)
+        .filter((part) => part.style === 'phrase')
+        .map((part) => ({ text: part.visible, href: part.href })));
+}
+/** At/below this hit rate, recommend remote cache (if off); above it caching works. */
+const LOW_CACHE_HIT_RATE = 0.1;
+/** Below this (ms) overhead is noise, not worth a recommendation. */
+exports.MEANINGFUL_OVERHEAD = 1000;
+/** Recommend --parallel when recoverable slot time is at least this fraction of the run. */
+const PARALLEL_LEAD_FRACTION = 0.2;
+/** Append "s" unless `count` is 1 (regular plurals only). */
+function pluralize(count, noun) {
+    return count === 1 ? noun : `${noun}s`;
+}
+/** Slot-contention time recoverable by parallelism or more machines (the "recoverable" number both the report and TUI payload show). Derived, never stored, so the halves can't drift from their sum. */
+function recoverableTime(s) {
+    return s.recoverableByParallel + s.recoverableByMachines;
+}
+/** Render the longest critical-path tasks as aligned columns: task (left), duration (right). */
+function formatTopTaskRows(tasks) {
+    // The only caller returns early when empty, so `tasks` is non-empty here.
+    const idWidth = Math.max(...tasks.map((t) => t.id.length));
+    const durations = tasks.map((t) => (0, native_1.formatDuration)(t.duration));
+    const durWidth = Math.max(...durations.map((d) => d.length));
+    return tasks.map((t, i) => {
+        const id = t.id.padEnd(idWidth);
+        const dur = durations[i].padStart(durWidth);
+        return `  ${id}    ${dur}`;
+    });
+}
+/** An Nx Agents URL link, built from the link definition so the URL text never has to be scanned back out of the assembled report. */
+const agentsLink = urlLink(NX_AGENTS_URL, NX_AGENTS_LINK);
+/** Actionable levers to go faster, one rec per lever. The critical-path case has two (shorten the chain, distribute the rest). Agents advice is omitted unless `canDistribute`. */
+function buildRecommendation(args) {
+    const { recoverableByParallel, recoverableByMachines, coordinatorDominated, runDuration, parallel, cores, canDistribute, distributing, criticalPathTop, } = args;
+    if (distributing) {
+        // Already on agents: more agents (not local --parallel) is the parallelism lever;
+        // the cores/machine framing below doesn't apply to a distributed run.
+        const recoverable = recoverableByParallel + recoverableByMachines;
+        if (runDuration > 0 &&
+            recoverable >= PARALLEL_LEAD_FRACTION * runDuration) {
+            return [
+                [`Add more Nx Agents to recover up to ${(0, native_1.formatDuration)(recoverable)}.`],
+            ];
+        }
+    }
+    else {
+        // Slot-bound with spare cores: the lever is local --parallel, not agents.
+        if (runDuration > 0 &&
+            recoverableByParallel >= PARALLEL_LEAD_FRACTION * runDuration &&
+            recoverableByParallel >= recoverableByMachines) {
+            return [
+                [
+                    `Increase parallelism to recover up to ${(0, native_1.formatDuration)(recoverableByParallel)}.`,
+                ],
+            ];
+        }
+        // Machine-bound: contention a higher local --parallel can't recover.
+        if (recoverableByMachines >= exports.MEANINGFUL_OVERHEAD) {
+            if (parallel >= cores) {
+                // At the core ceiling and still queuing. Agents for CPU-bound work;
+                // otherwise only the I/O-bound --parallel tip applies.
+                const base = `You're at this machine's ${cores} ${pluralize(cores, 'core')} and tasks are still queuing for a slot.`;
+                return [
+                    canDistribute
+                        ? [
+                            `${base} If they're CPU-bound, distribute across machines with Nx Agents → `,
+                            agentsLink,
+                            `; if they're I/O-bound, a higher --parallel may help instead.`,
+                        ]
+                        : [`${base} If they're I/O-bound, a higher --parallel may help.`],
+                ];
+            }
+            // Below the core ceiling but still machine-bound (a parallelism:false task
+            // monopolizes the pool, or volume exceeds the cores): only more machines can
+            // free those slots, and that lever only exists in CI.
+            return canDistribute
+                ? [
+                    [
+                        `Tasks are queuing for a slot that a higher --parallel can't free on one machine. Distribute across machines with Nx Agents → `,
+                        agentsLink,
+                        `.`,
+                    ],
+                ]
+                : [];
+        }
+        // Coordinator-dominated (tasks fast or cached), machine ~maxed: in CI agents are
+        // the only lever; locally nothing actionable.
+        if (coordinatorDominated) {
+            return canDistribute
+                ? [
+                    [
+                        `This run was about as fast as this machine can do it. Distribute the work across multiple machines with Nx Agents to make it faster → `,
+                        agentsLink,
+                        `.`,
+                    ],
+                ]
+                : [];
+        }
+    }
+    // Critical-path-bound: shorten the chain's longest tasks and distribute the rest.
+    // Nothing ran (fully cached) → no rec.
+    if (criticalPathTop.length === 0) {
+        return [];
+    }
+    const speedUp = [
+        [
+            `Speed up or split the longest tasks on the critical path:`,
+            ...formatTopTaskRows(criticalPathTop),
+        ].join('\n'),
+    ];
+    const recommendations = [speedUp];
+    if (canDistribute) {
+        recommendations.push([
+            `Distribute tasks across multiple machines with Nx Agents to increase parallelism without overwhelming resource usage → `,
+            agentsLink,
+            `.`,
+        ]);
+    }
+    return recommendations;
+}
+/**
+ * Recommendations in display order, cheapest first: "recover up to X" → remote-cache
+ * → other levers → "speed up / split" LAST (deepest manual work, the only multi-line
+ * rec). Shared by the report and TUI payload.
+ */
+function orderedRecommendations(s) {
+    const levers = [...s.structuredRecommendations];
+    const cacheAdvice = buildCacheAdvice(s);
+    // Classify by the rec's plain text — the structured link parts don't affect order.
+    const text = recommendationToPayloadString;
+    const isRecoverLever = (r) => text(r).includes('recover up to');
+    const isLongestTasks = (r) => text(r).includes('\n');
+    return [
+        ...levers.filter(isRecoverLever),
+        ...(cacheAdvice ? [cacheAdvice] : []),
+        ...levers.filter((r) => !isRecoverLever(r) && !isLongestTasks(r)),
+        ...levers.filter(isLongestTasks),
+    ];
+}
+/** Top-of-report cache stat: hit rate or skip marker. Null when there's no cache outcome. */
+function cacheStat(s) {
+    if (s.cacheSkipped) {
+        return 'Skipped (--skip-nx-cache)';
+    }
+    if (s.cacheableCount === 0) {
+        return null;
+    }
+    const pct = Math.round((s.cacheHits / s.cacheableCount) * 100);
+    return `${s.cacheHits}/${s.cacheableCount} hit (${pct}%)`;
+}
+/**
+ * Bottom-of-report cache advice, only when there's a lever: a skipped cache (drop
+ * the flag) or a barely-used cache with no remote (set up Nx Cloud).
+ */
+function buildCacheAdvice(s) {
+    if (s.cacheSkipped) {
+        return [
+            `Cache: drop --skip-nx-cache to restore unchanged tasks instantly.`,
+        ];
+    }
+    if (s.cacheableCount === 0) {
+        return null;
+    }
+    const hitRate = s.cacheHits / s.cacheableCount;
+    if (!s.remoteCacheEnabled && hitRate <= LOW_CACHE_HIT_RATE) {
+        // Whole-phrase link: the sentence is the visible text, the tagged URL the
+        // target. The payload string stays URL-less (the popup re-links the phrase).
+        return [phraseLink(NX_REMOTE_CACHE_CTA, NX_REMOTE_CACHE_LINK), `.`];
+    }
+    return null;
+}
+/** The full performance report as a terminal string (the TUI popup renders natively from {@link buildExitSummaryPayload} instead). */
+function formatReport(s) {
+    const fmt = native_1.formatDuration;
+    // Shows two of run duration's three parts (critical path + recoverable); the third,
+    // coordinator overhead, isn't displayed, so the two don't sum to run duration.
+    const recoverable = recoverableTime(s);
+    const recoverablePct = s.runDuration > 0 ? Math.round((recoverable / s.runDuration) * 100) : 0;
+    // Pad to the widest label ("Recoverable time:" = 17) so values align without a
+    // gaping gap. Keep in sync with the Rust popup's stat_line.
+    const stat = (label, value) => `  ${`${label}:`.padEnd(17)}  ${value}`;
+    // No leading blank line: nx's run summary already prints trailing blanks before this.
+    const cache = cacheStat(s);
+    const lines = [
+        stat('Run duration', fmt(s.runDuration)),
+        ...(cache ? [stat('Cache', cache)] : []),
+        stat('Critical path', `${fmt(s.criticalPathDuration)} (${s.criticalPathTaskCount} ${pluralize(s.criticalPathTaskCount, 'task')})`),
+        stat('Recoverable time', recoverable > 0
+            ? `${fmt(recoverable)} (${recoverablePct}% of the run)`
+            : fmt(recoverable)),
+    ];
+    const hyperlinks = (0, terminal_link_1.supportsHyperlinks)();
+    const recommendations = orderedRecommendations(s);
+    const render = (r) => recommendationToTerminalString(r, hyperlinks);
+    // A rec may be multi-line (the critical-path one embeds a task list); indent
+    // continuation lines under the bullet.
+    const renderRec = (r) => {
+        const [first, ...rest] = r.split('\n');
+        return [`    - ${first}`, ...rest.map((l) => `      ${l}`)];
+    };
+    if (recommendations.length > 0) {
+        const onlySingleLine = recommendations.length === 1 &&
+            !recommendationToPayloadString(recommendations[0]).includes('\n');
+        if (onlySingleLine) {
+            lines.push('', `  Recommendation: ${render(recommendations[0])}`);
+        }
+        else {
+            lines.push('', '  Recommendations:', ...recommendations.flatMap((r) => renderRec(render(r))));
+        }
+    }
+    // utm-tagged footer (a url link): with OSC 8 the clean URL shows and hides the utm
+    // in the target; without it the tagged URL prints verbatim.
+    const footer = [
+        `  ${NX_PERFORMANCE_LABEL} → `,
+        urlLink(NX_PERFORMANCE_URL, NX_PERFORMANCE_LINK),
+    ];
+    lines.push('', render(footer));
+    // No trailing newline — the caller's console.log adds the line terminator.
+    return lines.join('\n');
+}
+/**
+ * Build the payload for the TUI's exit-countdown popup, which renders natively in Rust
+ * (the terminal path uses {@link formatReport}). The shape is the generated napi
+ * {@link PerformanceSummaryPayload}, imported not re-declared so the producer and the
+ * Rust struct can't drift.
+ */
+function buildExitSummaryPayload(s) {
+    const hasCache = s.cacheableCount > 0;
+    const recommendations = orderedRecommendations(s);
+    return {
+        runDurationMs: s.runDuration,
+        criticalPathMs: s.criticalPathDuration,
+        criticalPathTaskCount: s.criticalPathTaskCount,
+        recoverableMs: recoverableTime(s),
+        // One nested field, not a hits/total pair: "one set, the other not" is
+        // unrepresentable, so the Rust side drops its defensive match.
+        cache: hasCache
+            ? { hits: s.cacheHits, total: s.cacheableCount }
+            : undefined,
+        cacheSkipped: s.cacheSkipped,
+        // The napi payload ships plain strings; a phrase link (the remote-cache CTA)
+        // stays URL-less here and is re-linked from `links` by the popup.
+        recommendations: recommendations.map(recommendationToPayloadString),
+        footer: { text: NX_PERFORMANCE_LABEL, href: NX_PERFORMANCE_LINK },
+        // Phrase links (e.g. the remote-cache CTA) carry their href as data so the
+        // popup hyperlinks the phrase in place; surfaced only when shown.
+        links: recommendationLinks(recommendations),
+    };
+}

package/dist/src/tasks-runner/run-command.d.ts

@@ -34,7 +34,7 @@ export declare function invokeTasksRunner({ tasks, projectGraph, taskGraph, life
 }): Promise<{
     [id: string]: TaskResult;
 }>;
-export declare function constructLifeCycles(lifeCycle: LifeCycle): LifeCycle[];
+export declare function constructLifeCycles(lifeCycle: LifeCycle, taskGraph: TaskGraph, nxJson?: NxJsonConfiguration, skipNxCache?: boolean): LifeCycle[];
 export declare function getRunner(nxArgs: NxArgs, nxJson: NxJsonConfiguration): {
     tasksRunner: TasksRunner;
     runnerOptions: any;

package/dist/src/tasks-runner/run-command.js

@@ -37,6 +37,7 @@ const static_run_one_terminal_output_life_cycle_1 = require("./life-cycles/stati
 const store_run_information_life_cycle_1 = require("./life-cycles/store-run-information-life-cycle");
 const task_history_life_cycle_1 = require("./life-cycles/task-history-life-cycle");
 const task_profiling_life_cycle_1 = require("./life-cycles/task-profiling-life-cycle");
+const performance_life_cycle_1 = require("./life-cycles/performance-life-cycle");
 const task_results_life_cycle_1 = require("./life-cycles/task-results-life-cycle");
 const task_telemetry_life_cycle_1 = require("./life-cycles/task-telemetry-life-cycle");
 const task_timings_life_cycle_1 = require("./life-cycles/task-timings-life-cycle");
@@ -139,6 +140,8 @@ async function getTerminalOutputLifeCycle(initiatingProject, initiatingTasks, pr
         // Only run the TUI if there are tasks to run
         if (tasks.length > 0) {
             appLifeCycle = new AppLifeCycle(tasks, initiatingTasks.map((t) => t.id), isRunOne ? 0 /* RunMode.RunOne */ : 1 /* RunMode.RunMany */, pinnedTasks, nxArgs ?? {}, nxJson.tui ?? {}, titleText, workspace_root_1.workspaceRoot, taskGraph);
+            // The native endCommand renders the perf report in the exit popup; the runner
+            // sources the payload and CompositeLifeCycle forwards it here.
             lifeCycles.unshift(appLifeCycle);
             /**
              * Patch stdout.write and stderr.write methods to pass Nx Cloud client logs to the TUI via the lifecycle
@@ -365,6 +368,12 @@ async function runCommandForTasks(projectsToRun, currentProjectGraph, { nxJson }
         restoreTerminal?.();
         throw e;
     }
+    finally {
+        // Print the report once, on success or failure (restoreTerminal has run in both
+        // paths). No-ops if a multi-task TUI run already delivered it via the popup; its own
+        // try/catch means it never masks `e`.
+        (0, performance_life_cycle_1.flushPerformanceReport)();
+    }
 }
 async function printConfigureAiAgentsDisclaimer() {
     try {
@@ -643,7 +652,7 @@ async function invokeTasksRunner({ tasks, projectGraph, taskGraph, lifeCycle, nx
     await (0, hash_task_1.hashTasksThatDoNotDependOnOutputsOfOtherTasks)(hasher, projectGraph, taskGraph, nxJson, taskDetails);
     const taskResultsLifecycle = new task_results_life_cycle_1.TaskResultsLifeCycle();
     const compositedLifeCycle = new life_cycle_1.CompositeLifeCycle([
-        ...constructLifeCycles(lifeCycle),
+        ...constructLifeCycles(lifeCycle, taskGraph, nxJson, nxArgs.skipNxCache),
         taskResultsLifecycle,
     ]);
     let promiseOrObservable = tasksRunner(tasks, {
@@ -714,7 +723,7 @@ async function invokeTasksRunner({ tasks, projectGraph, taskGraph, lifeCycle, nx
     await promiseOrObservable;
     return taskResultsLifecycle.getTaskResults();
 }
-function constructLifeCycles(lifeCycle) {
+function constructLifeCycles(lifeCycle, taskGraph, nxJson, skipNxCache) {
     const lifeCycles = [];
     lifeCycles.push(new store_run_information_life_cycle_1.StoreRunInformationLifeCycle());
     lifeCycles.push(lifeCycle);
@@ -724,6 +733,7 @@ function constructLifeCycles(lifeCycle) {
     if (process.env.NX_PROFILE) {
         lifeCycles.push(new task_profiling_life_cycle_1.TaskProfilingLifeCycle(process.env.NX_PROFILE));
     }
+    lifeCycles.push(new performance_life_cycle_1.PerformanceLifeCycle(taskGraph, { skipNxCache, nxJson }));
     lifeCycles.push(new task_telemetry_life_cycle_1.TaskTelemetryLifeCycle());
     const historyLifeCycle = (0, task_history_life_cycle_1.getTasksHistoryLifeCycle)();
     lifeCycles.push(historyLifeCycle);