@respan/cli 0.13.3 → 0.14.1

package/dist/commands/integrate/pi.js

@@ -0,0 +1,198 @@
+import { execSync } from 'node:child_process';
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../lib/base-command.js';
+import { isBinaryInstalled } from '../../lib/agents.js';
+import { DEFAULT_BASE_URL, integrateFlags, readJsonFile, writeJsonFile, parseAttrs, resolveScope, findProjectRoot, } from '../../lib/integrate.js';
+import { PI_PACKAGE_SPEC, buildPiRespanConfig, piConfigPath, piInstallArgs, } from '../../lib/pi-integrate.js';
+import { DEFAULT_COLLECTOR_PORT, collectorBaseUrl } from '../../lib/collector.js';
+class IntegratePi extends BaseCommand {
+    async run() {
+        const { flags } = await this.parse(IntegratePi);
+        this.globalFlags = flags;
+        try {
+            const dryRun = flags['dry-run'];
+            // pi loads global packages from ~/.pi/agent, so global is the default.
+            const scope = resolveScope(flags, 'global');
+            const projectRoot = scope === 'local' ? findProjectRoot() : process.cwd();
+            const configPath = piConfigPath(scope, projectRoot);
+            // ── Disable mode ─────────────────────────────────────────────
+            if (flags.disable) {
+                const disabled = buildPiRespanConfig(readJsonFile(configPath), { enabled: false });
+                if (dryRun) {
+                    this.log(`[dry-run] Would write: ${configPath}`);
+                    this.log(JSON.stringify(disabled, null, 2));
+                }
+                else {
+                    writeJsonFile(configPath, disabled);
+                    this.log(`Disabled tracing in: ${configPath}`);
+                }
+                this.log('');
+                this.log('pi tracing disabled (the extension package stays installed). Run "respan integrate pi" to re-enable.');
+                this.log(`To uninstall the extension package: pi remove ${PI_PACKAGE_SPEC}`);
+                return;
+            }
+            // ── Enable mode (default) ────────────────────────────────────
+            // Auth precheck only — the key is read by the extension at runtime.
+            this.resolveApiKey();
+            const baseUrl = flags['base-url'];
+            const projectId = flags['project-id'];
+            const customerId = flags['customer-id'];
+            // The extension treats span_name as an alias of workflow_name.
+            const workflowName = flags['workflow-name'] ?? flags['span-name'];
+            const traceScope = flags['trace-scope'];
+            const attrs = parseAttrs(flags.attrs);
+            const withCollector = flags['with-collector'];
+            const collectorPort = flags['collector-port'] ?? DEFAULT_COLLECTOR_PORT;
+            if (flags['collector-port'] !== undefined && !withCollector) {
+                this.warn('--collector-port has no effect without --with-collector.');
+            }
+            if (withCollector && baseUrl && baseUrl.replace(/\/+$/, '') !== DEFAULT_BASE_URL) {
+                this.warn(`--with-collector overrides --base-url: traces go to ${collectorBaseUrl(collectorPort)}. ` +
+                    'Point the collector at your endpoint with `respan collector start --export-url ...`.');
+            }
+            // ── 1. Install the pi package ─────────────────────────────────
+            const installCommand = ['pi', ...piInstallArgs(scope)].join(' ');
+            if (!isBinaryInstalled('pi')) {
+                const message = 'pi is not installed. Install it with `npm install -g @earendil-works/pi-coding-agent` (see https://pi.dev)';
+                if (dryRun) {
+                    this.warn(message);
+                }
+                else {
+                    this.error(message);
+                }
+            }
+            if (dryRun) {
+                this.log(`[dry-run] Would run: ${installCommand}`);
+            }
+            else {
+                this.log(`Installing ${PI_PACKAGE_SPEC}...`);
+                try {
+                    execSync(installCommand, { stdio: 'pipe', cwd: projectRoot });
+                    this.log(`Installed ${PI_PACKAGE_SPEC} (${scope}).`);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    this.warn(`Failed to install ${PI_PACKAGE_SPEC}: ${msg}`);
+                    this.warn(`You may need to install it manually: ${installCommand}`);
+                }
+            }
+            // ── 2. Write respan.json (non-secret) ─────────────────────────
+            const config = buildPiRespanConfig(readJsonFile(configPath), {
+                enabled: true,
+                customerId,
+                workflowName,
+                projectId,
+                traceScope,
+                baseUrl,
+                collectorPort: withCollector ? collectorPort : undefined,
+                attrs,
+            });
+            if (dryRun) {
+                this.log(`[dry-run] Would write: ${configPath}`);
+                this.log(JSON.stringify(config, null, 2));
+            }
+            else {
+                writeJsonFile(configPath, config);
+                this.log(`Wrote Respan config: ${configPath}`);
+            }
+            // ── Done ──────────────────────────────────────────────────────
+            this.log('');
+            this.log(`pi integration complete (${scope}). Restart pi to load the extension.`);
+            this.log('');
+            this.log('Auth:   RESPAN_API_KEY or ~/.respan/credentials.json  (from `respan auth login`)');
+            this.log(`Config: ${configPath}  (shareable, non-secret)`);
+            if (withCollector) {
+                this.log('');
+                this.log(`Traces go through the local collector at ${collectorBaseUrl(collectorPort)} (base_url in respan.json).`);
+                this.log('Start it once per machine; it keeps running across pi sessions:');
+                this.log(`  respan collector start${collectorPort === DEFAULT_COLLECTOR_PORT ? '' : ` --port ${collectorPort}`}`);
+                this.log('Remove base_url from respan.json to send directly to Respan again.');
+            }
+            this.log('');
+            this.log('Set properties via integrate flags or edit respan.json:');
+            this.log('  respan integrate pi --customer-id "frank" --workflow-name "my-agent"');
+            this.log('  respan integrate pi --attrs \'{"team":"platform","env":"staging"}\'');
+            this.log('  respan integrate pi --trace-scope run       # one trace per prompt instead of one per session ("trace_scope")');
+            this.log('');
+            this.log('Override per-session with env vars:');
+            this.log('  export RESPAN_CUSTOMER_ID="your-name"');
+            this.log('  export RESPAN_PI_TRACE_SCOPE=run       # or session (default)');
+            this.log('  export RESPAN_PI_TRACING=false     # skip tracing for one session');
+            this.log('');
+            this.log('One-off run without installing (from a project that has the package):');
+            this.log('  pi -e ./node_modules/@respan/instrumentation-pi/dist/extension.js');
+            this.log('');
+            this.log('Debug: RESPAN_PI_DEBUG=true pi   (logs to stderr only; nothing is written to disk)');
+        }
+        catch (error) {
+            this.handleError(error);
+        }
+    }
+    resolveApiKey() {
+        const auth = this.getAuth();
+        if (auth.apiKey)
+            return auth.apiKey;
+        if (auth.accessToken) {
+            this.warn('Using access token (JWT) which may expire. Consider using an API key instead.');
+            return auth.accessToken;
+        }
+        this.error('No API key found. Pass --api-key, set RESPAN_API_KEY, or run: respan auth login');
+    }
+}
+IntegratePi.description = `Integrate Respan with the pi coding agent (https://pi.dev).
+
+Installs the @respan/instrumentation-pi pi package — a pi extension that
+traces every agent run as one turn span per prompt with chat and tool spans underneath,
+correlating all runs of a pi session by its session id — and writes a
+non-secret respan.json config for it.
+
+Scope:
+  --global   pi install npm:@respan/instrumentation-pi + ~/.pi/agent/respan.json (default)
+  --local    pi install -l npm:@respan/instrumentation-pi + .pi/respan.json in the project root
+
+Trace scope (--trace-scope, "trace_scope" in respan.json):
+  session    one multi-root trace per pi session, across processes and pauses (default)
+  run        one trace per agent run; runs of a session share a thread id
+
+Durable delivery (--with-collector):
+  Sets base_url to a local Respan collector (http://127.0.0.1:4318) so traces
+  go through its persistent queue and survive Respan outages. Run
+  "respan collector start" once per machine.
+
+Credentials are never written to these files: the extension reads
+RESPAN_API_KEY or ~/.respan/credentials.json (from "respan auth login").`;
+IntegratePi.examples = [
+    'respan integrate pi',
+    'respan integrate pi --disable',
+    'respan integrate pi --local',
+    'respan integrate pi --customer-id frank --workflow-name email-agent',
+    'respan integrate pi --trace-scope run',
+    'respan integrate pi --with-collector',
+    'respan integrate pi --project-id my-project --attrs \'{"env":"prod"}\'',
+    'respan integrate pi --dry-run',
+];
+IntegratePi.flags = {
+    ...BaseCommand.baseFlags,
+    ...integrateFlags,
+    // The shared descriptions advertise the claude-code default; pi's is "pi".
+    'workflow-name': Flags.string({
+        description: 'traceloop.workflow.name on pi turn spans (default: pi)',
+    }),
+    'span-name': Flags.string({
+        description: 'Alias of --workflow-name (default: pi)',
+    }),
+    'trace-scope': Flags.string({
+        description: 'Trace scope: "session" = one multi-root trace per pi session (default), "run" = one trace per agent run',
+        options: ['run', 'session'],
+    }),
+    'with-collector': Flags.boolean({
+        description: 'Send traces through a local Respan collector (respan collector start) for durable delivery',
+        default: false,
+    }),
+    'collector-port': Flags.integer({
+        description: `Port of the local collector, with --with-collector (default: ${DEFAULT_COLLECTOR_PORT})`,
+        min: 1,
+        max: 65535,
+    }),
+};
+export default IntegratePi;

package/dist/lib/collector-runtime.d.ts

@@ -0,0 +1,93 @@
+import { type CollectorMetricsSummary, type CollectorPaths } from './collector.js';
+export type CollectorMode = 'docker' | 'binary';
+/** Smallest --max-size-mib otelcol-contrib 0.160.0 accepts with the config's compaction settings. */
+export declare const MIN_MAX_SIZE_MIB = 100;
+export declare const collectorSizingFlags: {
+    'export-url': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'data-dir': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    'max-size-mib': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    'queue-size': import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+    port: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+};
+export declare const collectorModeFlags: {
+    docker: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    binary: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+};
+/**
+ * Ingest URL for the collector: --export-url / RESPAN_COLLECTOR_EXPORT_URL,
+ * else derived from the resolved auth base URL. Falls back to the configured
+ * base URL (flag / RESPAN_API_BASE_URL / SaaS default) when not logged in, so
+ * `collector config --print` works without credentials.
+ */
+export declare function resolveExportUrl(flags: {
+    'export-url'?: string;
+    'api-key'?: string;
+    'base-url'?: string;
+    profile?: string;
+}): string;
+export interface CommandResult {
+    status: number | null;
+    stdout: string;
+    stderr: string;
+}
+/** Run `docker <args>` to completion. Never rejects; a missing binary is a failed result. */
+export declare function runDocker(args: string[], env?: NodeJS.ProcessEnv): Promise<CommandResult>;
+/** True when the Docker CLI is installed and can reach a daemon. */
+export declare function dockerAvailable(): boolean;
+export interface ContainerState {
+    exists: boolean;
+    running: boolean;
+    /** created | running | paused | restarting | removing | exited | dead */
+    status?: string;
+    startedAt?: string;
+    restartCount?: number;
+    image?: string;
+}
+export declare function dockerContainerState(name?: string): ContainerState;
+export declare function dockerVolumeExists(name?: string): boolean;
+export declare function readPid(pidPath: string): number | undefined;
+export declare function isPidAlive(pid: number): boolean;
+export interface RunningCollector {
+    mode: CollectorMode;
+    pid?: number;
+    container?: ContainerState;
+}
+/**
+ * What this CLI started, if anything: the container (in any state — an exited
+ * container still owns the name) or a live pid from the pid file. A stale pid
+ * file is removed. `mode` restricts the check to one runtime.
+ */
+export declare function detectRunning(paths: CollectorPaths, mode?: CollectorMode): RunningCollector | undefined;
+export declare function spawnCollectorBinary(paths: CollectorPaths, env: NodeJS.ProcessEnv): number;
+export declare function sleep(ms: number): Promise<void>;
+/** SIGTERM, wait for exit, SIGKILL as a last resort. */
+export declare function stopPid(pid: number, timeoutMs?: number): Promise<'stopped' | 'killed' | 'not-running'>;
+export declare function tailFile(filePath: string, lines: number): string;
+export declare function directorySize(dir: string): number;
+export declare function healthUrl(port?: number): string;
+export declare function metricsUrl(port?: number): string;
+export interface HealthStatus {
+    healthy: boolean;
+    /** health_check body status, e.g. "Server available", or "HTTP 503". */
+    status?: string;
+    uptime?: string;
+    upSince?: string;
+    error?: string;
+}
+/** GET the health_check extension (200 once the pipeline is ready). */
+export declare function checkHealth(port?: number): Promise<HealthStatus>;
+/** Poll health until it passes, the timeout elapses, or `isAlive` reports the process gone. */
+export declare function waitForHealth(port: number, timeoutMs: number, isAlive?: () => boolean): Promise<HealthStatus>;
+export declare function fetchMetrics(port?: number): Promise<CollectorMetricsSummary | undefined>;
+export declare function downloadFile(url: string, dest: string): Promise<void>;
+export declare function sha256File(filePath: string): Promise<string>;
+export interface CollectorLogger {
+    log(message: string): void;
+    warn(message: string): void;
+}
+/**
+ * Make sure ~/.respan/collector/bin/otelcol-contrib exists: download the
+ * release tarball, verify its SHA-256 against the published `.sha256` asset
+ * (warn when that cannot be fetched), extract the binary and drop the tarball.
+ */
+export declare function ensureCollectorBinary(paths: CollectorPaths, logger: CollectorLogger): Promise<string>;

package/dist/lib/collector-runtime.js

@@ -0,0 +1,361 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+import { Flags } from '@oclif/core';
+import { DEFAULT_BASE_URL, resolveAuth } from './auth.js';
+import { ensureDir } from './integrate.js';
+import { COLLECTOR_VERSION, CONTAINER_NAME, DEFAULT_COLLECTOR_PORT, DEFAULT_HEALTH_PORT, DEFAULT_METRICS_PORT, DEFAULT_QUEUE_SIZE, VOLUME_NAME, binaryDownloadUrl, checksumUrl, exportUrlFromBaseUrl, parsePrometheusText, parseSha256, summarizeCollectorMetrics, } from './collector.js';
+/** Smallest --max-size-mib otelcol-contrib 0.160.0 accepts with the config's compaction settings. */
+export const MIN_MAX_SIZE_MIB = 100;
+// ── Shared flags ──────────────────────────────────────────────────────────
+export const collectorSizingFlags = {
+    'export-url': Flags.string({
+        description: 'Respan ingest URL (default: <base URL>/api/v2/traces from your auth config)',
+        env: 'RESPAN_COLLECTOR_EXPORT_URL',
+    }),
+    'data-dir': Flags.string({
+        description: 'Persistent queue directory, binary mode only (default: ~/.respan/collector/data)',
+    }),
+    'max-size-mib': Flags.integer({
+        // file_storage rejects a max_size below its compaction rebound threshold (100 MiB by default).
+        description: 'Disk cap for the persistent queue in MiB (minimum 100)',
+        default: 512,
+        min: MIN_MAX_SIZE_MIB,
+    }),
+    'queue-size': Flags.integer({
+        description: 'Batches kept while Respan is unreachable',
+        default: DEFAULT_QUEUE_SIZE,
+        min: 1,
+    }),
+    port: Flags.integer({
+        description: 'Local OTLP/HTTP port the SDKs send to',
+        default: DEFAULT_COLLECTOR_PORT,
+        min: 1,
+        max: 65535,
+    }),
+};
+export const collectorModeFlags = {
+    docker: Flags.boolean({
+        description: 'Use the Docker container (default when Docker is available)',
+        default: false,
+        exclusive: ['binary'],
+    }),
+    binary: Flags.boolean({
+        description: 'Use the otelcol-contrib binary in ~/.respan/collector/bin',
+        default: false,
+        exclusive: ['docker'],
+    }),
+};
+/**
+ * Ingest URL for the collector: --export-url / RESPAN_COLLECTOR_EXPORT_URL,
+ * else derived from the resolved auth base URL. Falls back to the configured
+ * base URL (flag / RESPAN_API_BASE_URL / SaaS default) when not logged in, so
+ * `collector config --print` works without credentials.
+ */
+export function resolveExportUrl(flags) {
+    if (flags['export-url'])
+        return flags['export-url'];
+    let baseUrl;
+    try {
+        baseUrl = resolveAuth(flags).baseUrl;
+    }
+    catch {
+        baseUrl = flags['base-url'] || process.env.RESPAN_API_BASE_URL || DEFAULT_BASE_URL;
+    }
+    return exportUrlFromBaseUrl(baseUrl);
+}
+/** Run `docker <args>` to completion. Never rejects; a missing binary is a failed result. */
+export function runDocker(args, env = process.env) {
+    return new Promise((resolve) => {
+        let stdout = '';
+        let stderr = '';
+        const child = spawn('docker', args, { env, stdio: ['ignore', 'pipe', 'pipe'] });
+        child.stdout.on('data', (chunk) => { stdout += chunk; });
+        child.stderr.on('data', (chunk) => { stderr += chunk; });
+        child.on('error', (err) => resolve({ status: null, stdout, stderr: stderr || err.message }));
+        child.on('close', (status) => resolve({ status, stdout, stderr }));
+    });
+}
+function dockerSync(args) {
+    const result = spawnSync('docker', args, {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 15000,
+    });
+    return { ok: !result.error && result.status === 0, stdout: result.stdout ?? '' };
+}
+/** True when the Docker CLI is installed and can reach a daemon. */
+export function dockerAvailable() {
+    return dockerSync(['info']).ok;
+}
+export function dockerContainerState(name = CONTAINER_NAME) {
+    const result = dockerSync([
+        'inspect', '--format', '{{.State.Status}}|{{.State.StartedAt}}|{{.RestartCount}}|{{.Config.Image}}', name,
+    ]);
+    if (!result.ok)
+        return { exists: false, running: false };
+    const [status, startedAt, restartCount, image] = result.stdout.trim().split('|');
+    return {
+        exists: true,
+        running: status === 'running',
+        status,
+        startedAt,
+        restartCount: Number.parseInt(restartCount ?? '', 10) || 0,
+        image,
+    };
+}
+export function dockerVolumeExists(name = VOLUME_NAME) {
+    return dockerSync(['volume', 'inspect', name]).ok;
+}
+// ── Processes ─────────────────────────────────────────────────────────────
+export function readPid(pidPath) {
+    try {
+        const pid = Number.parseInt(fs.readFileSync(pidPath, 'utf-8').trim(), 10);
+        return Number.isInteger(pid) && pid > 0 ? pid : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        return err.code === 'EPERM';
+    }
+}
+/**
+ * What this CLI started, if anything: the container (in any state — an exited
+ * container still owns the name) or a live pid from the pid file. A stale pid
+ * file is removed. `mode` restricts the check to one runtime.
+ */
+export function detectRunning(paths, mode) {
+    if (mode !== 'binary') {
+        const container = dockerContainerState();
+        if (container.exists)
+            return { mode: 'docker', container };
+    }
+    if (mode !== 'docker') {
+        const pid = readPid(paths.pidPath);
+        if (pid !== undefined) {
+            if (isPidAlive(pid))
+                return { mode: 'binary', pid };
+            fs.rmSync(paths.pidPath, { force: true });
+        }
+    }
+    return undefined;
+}
+export function spawnCollectorBinary(paths, env) {
+    ensureDir(paths.root);
+    const logFd = fs.openSync(paths.logPath, 'a');
+    try {
+        const child = spawn(paths.binaryPath, ['--config', paths.configPath], {
+            detached: true,
+            stdio: ['ignore', logFd, logFd],
+            env,
+        });
+        // Spawn failures surface asynchronously; the caller notices through the
+        // pid liveness check instead of an unhandled 'error' event.
+        child.on('error', () => { });
+        if (child.pid === undefined) {
+            throw new Error(`Failed to start ${paths.binaryPath}`);
+        }
+        child.unref();
+        fs.writeFileSync(paths.pidPath, `${child.pid}\n`);
+        return child.pid;
+    }
+    finally {
+        fs.closeSync(logFd);
+    }
+}
+export function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+/** SIGTERM, wait for exit, SIGKILL as a last resort. */
+export async function stopPid(pid, timeoutMs = 10000) {
+    if (!isPidAlive(pid))
+        return 'not-running';
+    try {
+        process.kill(pid, 'SIGTERM');
+    }
+    catch {
+        return 'not-running';
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!isPidAlive(pid))
+            return 'stopped';
+        await sleep(250);
+    }
+    try {
+        process.kill(pid, 'SIGKILL');
+    }
+    catch {
+        // already gone
+    }
+    return 'killed';
+}
+export function tailFile(filePath, lines) {
+    try {
+        return fs.readFileSync(filePath, 'utf-8').trimEnd().split('\n').slice(-lines).join('\n');
+    }
+    catch {
+        return '';
+    }
+}
+export function directorySize(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return 0;
+    }
+    let total = 0;
+    for (const entry of entries) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            total += directorySize(full);
+        }
+        else if (entry.isFile()) {
+            try {
+                total += fs.statSync(full).size;
+            }
+            catch {
+                // removed while walking
+            }
+        }
+    }
+    return total;
+}
+// ── Health & metrics ──────────────────────────────────────────────────────
+export function healthUrl(port = DEFAULT_HEALTH_PORT) {
+    return `http://127.0.0.1:${port}/`;
+}
+export function metricsUrl(port = DEFAULT_METRICS_PORT) {
+    return `http://127.0.0.1:${port}/metrics`;
+}
+async function fetchWithTimeout(url, timeoutMs) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        return await fetch(url, { signal: controller.signal });
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/** GET the health_check extension (200 once the pipeline is ready). */
+export async function checkHealth(port = DEFAULT_HEALTH_PORT) {
+    try {
+        const response = await fetchWithTimeout(healthUrl(port), 2000);
+        const text = await response.text();
+        let body = {};
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // not JSON
+        }
+        return {
+            healthy: response.ok,
+            status: typeof body.status === 'string' ? body.status : `HTTP ${response.status}`,
+            uptime: typeof body.uptime === 'string' ? body.uptime : undefined,
+            upSince: typeof body.upSince === 'string' ? body.upSince : undefined,
+        };
+    }
+    catch (err) {
+        const cause = err.cause;
+        return { healthy: false, error: cause?.code ?? (err instanceof Error ? err.message : String(err)) };
+    }
+}
+/** Poll health until it passes, the timeout elapses, or `isAlive` reports the process gone. */
+export async function waitForHealth(port, timeoutMs, isAlive) {
+    const deadline = Date.now() + timeoutMs;
+    let last = { healthy: false };
+    while (Date.now() < deadline) {
+        last = await checkHealth(port);
+        if (last.healthy)
+            return last;
+        if (isAlive && !isAlive())
+            return { ...last, error: 'process exited' };
+        await sleep(500);
+    }
+    return last;
+}
+export async function fetchMetrics(port = DEFAULT_METRICS_PORT) {
+    try {
+        const response = await fetchWithTimeout(metricsUrl(port), 2000);
+        if (!response.ok)
+            return undefined;
+        return summarizeCollectorMetrics(parsePrometheusText(await response.text()));
+    }
+    catch {
+        return undefined;
+    }
+}
+// ── Binary download ───────────────────────────────────────────────────────
+export async function downloadFile(url, dest) {
+    const response = await fetch(url, { redirect: 'follow' });
+    if (!response.ok || !response.body) {
+        throw new Error(`Download failed (${response.status} ${response.statusText}): ${url}`);
+    }
+    ensureDir(path.dirname(dest));
+    await pipeline(Readable.fromWeb(response.body), fs.createWriteStream(dest));
+}
+export async function sha256File(filePath) {
+    const hash = createHash('sha256');
+    await pipeline(fs.createReadStream(filePath), hash);
+    return hash.digest('hex');
+}
+/**
+ * Make sure ~/.respan/collector/bin/otelcol-contrib exists: download the
+ * release tarball, verify its SHA-256 against the published `.sha256` asset
+ * (warn when that cannot be fetched), extract the binary and drop the tarball.
+ */
+export async function ensureCollectorBinary(paths, logger) {
+    if (fs.existsSync(paths.binaryPath))
+        return paths.binaryPath;
+    const url = binaryDownloadUrl(COLLECTOR_VERSION);
+    const tarball = path.join(paths.binDir, `otelcol-contrib_${COLLECTOR_VERSION}.tar.gz`);
+    ensureDir(paths.binDir);
+    logger.log(`Downloading otelcol-contrib ${COLLECTOR_VERSION} (about 95 MB)...`);
+    logger.log(`  ${url}`);
+    await downloadFile(url, tarball);
+    let expected;
+    try {
+        const response = await fetchWithTimeout(checksumUrl(COLLECTOR_VERSION), 15000);
+        if (response.ok)
+            expected = parseSha256(await response.text());
+    }
+    catch {
+        // reported below
+    }
+    if (expected) {
+        const actual = await sha256File(tarball);
+        if (actual !== expected) {
+            fs.rmSync(tarball, { force: true });
+            throw new Error(`SHA-256 mismatch for ${url}: expected ${expected}, got ${actual}. The download was discarded.`);
+        }
+        logger.log('Verified SHA-256 checksum.');
+    }
+    else {
+        logger.warn('Could not fetch the release checksum; the download was NOT verified.');
+    }
+    const extract = spawnSync('tar', ['-xzf', tarball, '-C', paths.binDir, 'otelcol-contrib'], {
+        encoding: 'utf-8',
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (extract.error || extract.status !== 0) {
+        throw new Error(`Failed to extract ${tarball}: ${(extract.stderr || extract.error?.message || '').trim()}`);
+    }
+    fs.chmodSync(paths.binaryPath, 0o755);
+    fs.rmSync(tarball, { force: true });
+    logger.log(`Installed ${paths.binaryPath}`);
+    return paths.binaryPath;
+}