@juspay/neurolink 9.95.3 → 10.0.1

package/dist/cli/commands/observability.js

@@ -1,5 +1,4 @@
 #!/usr/bin/env node
-/* eslint-disable no-console, curly */
 /**
  * NeuroLink CLI Observability Commands
  *
@@ -14,6 +13,7 @@ import ora from "ora";
 import { logger } from "../../lib/utils/logger.js";
 import { NeuroLink } from "../../lib/neurolink.js";
 import { formatRow, formatCost } from "../utils/formatters.js";
+import { redactUrlCredentials } from "../../lib/utils/logSanitize.js";
 /**
  * Observability Command Factory
  */
@@ -70,67 +70,72 @@ export class ObservabilityCommandFactory {
                 try {
                     const neurolink = new NeuroLink();
                     const status = neurolink.getTelemetryStatus();
-                    if (spinner)
+                    if (spinner) {
                         spinner.succeed("Status retrieved");
+                    }
                     if (args.format === "json") {
-                        console.log(JSON.stringify(status, null, 2));
+                        logger.always(JSON.stringify(status, (_key, value) => typeof value === "string" &&
+                            (_key === "baseUrl" || _key === "endpoint")
+                            ? redactUrlCredentials(value)
+                            : value, 2));
                     }
                     else {
-                        console.log("");
-                        console.log(chalk.bold.cyan("=== Observability Status ==="));
-                        console.log("");
+                        logger.always("");
+                        logger.always(chalk.bold.cyan("=== Observability Status ==="));
+                        logger.always("");
                         // Telemetry enabled status
                         const enabledIcon = status.enabled
                             ? chalk.green("ON")
                             : chalk.red("OFF");
-                        console.log(formatRow("Telemetry:", enabledIcon));
+                        logger.always(formatRow("Telemetry:", enabledIcon));
                         // Langfuse status
                         if (status.langfuse) {
-                            console.log("");
-                            console.log(chalk.bold("Langfuse:"));
+                            logger.always("");
+                            logger.always(chalk.bold("Langfuse:"));
                             const lfStatus = status.langfuse.enabled
                                 ? chalk.green("Enabled")
                                 : chalk.gray("Disabled");
-                            console.log(formatRow("  Status:", lfStatus));
+                            logger.always(formatRow("  Status:", lfStatus));
                             if (status.langfuse.baseUrl) {
-                                console.log(formatRow("  URL:", status.langfuse.baseUrl));
+                                logger.always(formatRow("  URL:", redactUrlCredentials(status.langfuse.baseUrl)));
                             }
                             if (status.langfuse.environment) {
-                                console.log(formatRow("  Environment:", status.langfuse.environment));
+                                logger.always(formatRow("  Environment:", status.langfuse.environment));
                             }
                         }
                         // OpenTelemetry status
                         if (status.openTelemetry) {
-                            console.log("");
-                            console.log(chalk.bold("OpenTelemetry:"));
+                            logger.always("");
+                            logger.always(chalk.bold("OpenTelemetry:"));
                             const otelStatus = status.openTelemetry.enabled
                                 ? chalk.green("Enabled")
                                 : chalk.gray("Disabled");
-                            console.log(formatRow("  Status:", otelStatus));
+                            logger.always(formatRow("  Status:", otelStatus));
                             if (status.openTelemetry.endpoint) {
-                                console.log(formatRow("  Endpoint:", status.openTelemetry.endpoint));
+                                logger.always(formatRow("  Endpoint:", redactUrlCredentials(status.openTelemetry.endpoint)));
                             }
                             if (status.openTelemetry.serviceName) {
-                                console.log(formatRow("  Service:", status.openTelemetry.serviceName));
+                                logger.always(formatRow("  Service:", status.openTelemetry.serviceName));
                             }
                         }
                         // Exporters summary
                         if (status.exporters && status.exporters.length > 0) {
-                            console.log("");
-                            console.log(chalk.bold("Active Exporters:"));
+                            logger.always("");
+                            logger.always(chalk.bold("Active Exporters:"));
                             for (const exporter of status.exporters) {
                                 const exporterStatus = exporter.healthy
                                     ? chalk.green("Healthy")
                                     : chalk.red("Unhealthy");
-                                console.log(formatRow(`  ${exporter.name}:`, exporterStatus));
+                                logger.always(formatRow(`  ${exporter.name}:`, exporterStatus));
                             }
                         }
-                        console.log("");
+                        logger.always("");
                     }
                 }
                 catch (error) {
-                    if (spinner)
+                    if (spinner) {
                         spinner.fail("Failed to get status");
+                    }
                     logger.error("Error:", error instanceof Error ? error.message : String(error));
                     process.exit(1);
                 }
@@ -171,74 +176,76 @@ export class ObservabilityCommandFactory {
                 try {
                     const neurolink = new NeuroLink();
                     const metrics = neurolink.getMetrics();
-                    if (spinner)
+                    if (spinner) {
                         spinner.succeed("Metrics retrieved");
+                    }
                     if (args.format === "json") {
-                        console.log(JSON.stringify(metrics, null, 2));
+                        logger.always(JSON.stringify(metrics, null, 2));
                     }
                     else {
-                        console.log("");
-                        console.log(chalk.bold.cyan("=== Metrics Summary ==="));
-                        console.log("");
+                        logger.always("");
+                        logger.always(chalk.bold.cyan("=== Metrics Summary ==="));
+                        logger.always("");
                         // Request statistics
-                        console.log(chalk.bold("Request Statistics:"));
-                        console.log(formatRow("  Total requests:", metrics.totalSpans.toLocaleString()));
-                        console.log(formatRow("  Successful:", metrics.successfulSpans.toLocaleString()));
-                        console.log(formatRow("  Failed:", metrics.failedSpans.toLocaleString()));
-                        console.log(formatRow("  Success rate:", `${(metrics.successRate * 100).toFixed(2)}%`));
+                        logger.always(chalk.bold("Request Statistics:"));
+                        logger.always(formatRow("  Total requests:", metrics.totalSpans.toLocaleString()));
+                        logger.always(formatRow("  Successful:", metrics.successfulSpans.toLocaleString()));
+                        logger.always(formatRow("  Failed:", metrics.failedSpans.toLocaleString()));
+                        logger.always(formatRow("  Success rate:", `${(metrics.successRate * 100).toFixed(2)}%`));
                         // Latency statistics
                         if (metrics.latency && metrics.latency.count > 0) {
-                            console.log("");
-                            console.log(chalk.bold("Latency (ms):"));
-                            console.log(formatRow("  Min:", metrics.latency.min.toFixed(2)));
-                            console.log(formatRow("  Max:", metrics.latency.max.toFixed(2)));
-                            console.log(formatRow("  Mean:", metrics.latency.mean.toFixed(2)));
-                            console.log(formatRow("  P50:", metrics.latency.p50.toFixed(2)));
-                            console.log(formatRow("  P95:", metrics.latency.p95.toFixed(2)));
-                            console.log(formatRow("  P99:", metrics.latency.p99.toFixed(2)));
+                            logger.always("");
+                            logger.always(chalk.bold("Latency (ms):"));
+                            logger.always(formatRow("  Min:", metrics.latency.min.toFixed(2)));
+                            logger.always(formatRow("  Max:", metrics.latency.max.toFixed(2)));
+                            logger.always(formatRow("  Mean:", metrics.latency.mean.toFixed(2)));
+                            logger.always(formatRow("  P50:", metrics.latency.p50.toFixed(2)));
+                            logger.always(formatRow("  P95:", metrics.latency.p95.toFixed(2)));
+                            logger.always(formatRow("  P99:", metrics.latency.p99.toFixed(2)));
                             if (args.detailed) {
-                                console.log(formatRow("  P75:", metrics.latency.p75.toFixed(2)));
-                                console.log(formatRow("  P90:", metrics.latency.p90.toFixed(2)));
-                                console.log(formatRow("  Std Dev:", metrics.latency.stdDev.toFixed(2)));
+                                logger.always(formatRow("  P75:", metrics.latency.p75.toFixed(2)));
+                                logger.always(formatRow("  P90:", metrics.latency.p90.toFixed(2)));
+                                logger.always(formatRow("  Std Dev:", metrics.latency.stdDev.toFixed(2)));
                             }
                         }
                         // Token statistics
                         if (metrics.tokens) {
-                            console.log("");
-                            console.log(chalk.bold("Token Usage:"));
-                            console.log(formatRow("  Input tokens:", metrics.tokens.totalInputTokens.toLocaleString()));
-                            console.log(formatRow("  Output tokens:", metrics.tokens.totalOutputTokens.toLocaleString()));
-                            console.log(formatRow("  Total tokens:", metrics.tokens.totalTokens.toLocaleString()));
+                            logger.always("");
+                            logger.always(chalk.bold("Token Usage:"));
+                            logger.always(formatRow("  Input tokens:", metrics.tokens.totalInputTokens.toLocaleString()));
+                            logger.always(formatRow("  Output tokens:", metrics.tokens.totalOutputTokens.toLocaleString()));
+                            logger.always(formatRow("  Total tokens:", metrics.tokens.totalTokens.toLocaleString()));
                             if (args.detailed &&
                                 metrics.tokens.cacheReadTokens &&
                                 metrics.tokens.cacheReadTokens > 0) {
-                                console.log(formatRow("  Cache read:", metrics.tokens.cacheReadTokens.toLocaleString()));
+                                logger.always(formatRow("  Cache read:", metrics.tokens.cacheReadTokens.toLocaleString()));
                             }
                             if (args.detailed &&
                                 metrics.tokens.reasoningTokens &&
                                 metrics.tokens.reasoningTokens > 0) {
-                                console.log(formatRow("  Reasoning:", metrics.tokens.reasoningTokens.toLocaleString()));
+                                logger.always(formatRow("  Reasoning:", metrics.tokens.reasoningTokens.toLocaleString()));
                             }
                         }
                         // Cost
                         if (metrics.totalCost !== undefined && metrics.totalCost > 0) {
-                            console.log("");
-                            console.log(chalk.bold("Cost:"));
-                            console.log(formatRow("  Total:", formatCost(metrics.totalCost)));
+                            logger.always("");
+                            logger.always(chalk.bold("Cost:"));
+                            logger.always(formatRow("  Total:", formatCost(metrics.totalCost)));
                         }
                         // Tracking duration
                         if (metrics.trackingDurationMs) {
                             const durationSec = metrics.trackingDurationMs / 1000;
                             const throughput = metrics.totalSpans > 0 ? metrics.totalSpans / durationSec : 0;
-                            console.log("");
-                            console.log(chalk.gray(`Tracking: ${durationSec.toFixed(1)}s (${throughput.toFixed(2)} req/s)`));
+                            logger.always("");
+                            logger.always(chalk.gray(`Tracking: ${durationSec.toFixed(1)}s (${throughput.toFixed(2)} req/s)`));
                         }
-                        console.log("");
+                        logger.always("");
                     }
                 }
                 catch (error) {
-                    if (spinner)
+                    if (spinner) {
                         spinner.fail("Failed to get metrics");
+                    }
                     logger.error("Error:", error instanceof Error ? error.message : String(error));
                     process.exit(1);
                 }
@@ -276,60 +283,62 @@ export class ObservabilityCommandFactory {
                 try {
                     const neurolink = new NeuroLink();
                     const status = neurolink.getTelemetryStatus();
-                    if (spinner)
+                    if (spinner) {
                         spinner.succeed("Exporters retrieved");
+                    }
                     const exporters = status.exporters ?? [];
                     if (args.format === "json") {
-                        console.log(JSON.stringify(exporters, null, 2));
+                        logger.always(JSON.stringify(exporters, null, 2));
                     }
                     else {
-                        console.log("");
-                        console.log(chalk.bold.cyan("=== Configured Exporters ==="));
-                        console.log("");
+                        logger.always("");
+                        logger.always(chalk.bold.cyan("=== Configured Exporters ==="));
+                        logger.always("");
                         if (exporters.length === 0) {
-                            console.log(chalk.gray("No exporters configured."));
-                            console.log("");
-                            console.log("Available exporters:");
-                            console.log("  - Langfuse (langfuse)");
-                            console.log("  - LangSmith (langsmith)");
-                            console.log("  - OpenTelemetry (otel)");
-                            console.log("  - Datadog (datadog)");
-                            console.log("  - Sentry (sentry)");
-                            console.log("  - Braintrust (braintrust)");
-                            console.log("  - Arize (arize)");
-                            console.log("  - PostHog (posthog)");
-                            console.log("  - Laminar (laminar)");
+                            logger.always(chalk.gray("No exporters configured."));
+                            logger.always("");
+                            logger.always("Available exporters:");
+                            logger.always("  - Langfuse (langfuse)");
+                            logger.always("  - LangSmith (langsmith)");
+                            logger.always("  - OpenTelemetry (otel)");
+                            logger.always("  - Datadog (datadog)");
+                            logger.always("  - Sentry (sentry)");
+                            logger.always("  - Braintrust (braintrust)");
+                            logger.always("  - Arize (arize)");
+                            logger.always("  - PostHog (posthog)");
+                            logger.always("  - Laminar (laminar)");
                         }
                         else {
                             for (const exporter of exporters) {
                                 const healthIcon = exporter.healthy
                                     ? chalk.green("[OK]")
                                     : chalk.red("[ERROR]");
-                                console.log(`${healthIcon} ${chalk.bold(exporter.name)}`);
+                                logger.always(`${healthIcon} ${chalk.bold(exporter.name)}`);
                                 if (exporter.latencyMs !== undefined) {
-                                    console.log(formatRow("    Latency:", `${exporter.latencyMs.toFixed(2)}ms`));
+                                    logger.always(formatRow("    Latency:", `${exporter.latencyMs.toFixed(2)}ms`));
                                 }
                                 if (exporter.pendingSpans !== undefined) {
-                                    console.log(formatRow("    Pending spans:", exporter.pendingSpans.toLocaleString()));
+                                    logger.always(formatRow("    Pending spans:", exporter.pendingSpans.toLocaleString()));
                                 }
                                 if (exporter.lastExportTime) {
                                     const lastExport = new Date(exporter.lastExportTime);
-                                    console.log(formatRow("    Last export:", lastExport.toISOString()));
+                                    logger.always(formatRow("    Last export:", lastExport.toISOString()));
                                 }
                                 if (exporter.errors && exporter.errors.length > 0) {
-                                    console.log(chalk.yellow("    Errors:"));
+                                    logger.always(chalk.yellow("    Errors:"));
                                     for (const error of exporter.errors.slice(0, 3)) {
-                                        console.log(chalk.red(`      - ${error}`));
+                                        logger.always(chalk.red(`      - ${error}`));
                                     }
                                 }
-                                console.log("");
+                                logger.always("");
                             }
                         }
                     }
                 }
                 catch (error) {
-                    if (spinner)
+                    if (spinner) {
                         spinner.fail("Failed to get exporters");
+                    }
                     logger.error("Error:", error instanceof Error ? error.message : String(error));
                     process.exit(1);
                 }
@@ -377,8 +386,9 @@ export class ObservabilityCommandFactory {
                 try {
                     const neurolink = new NeuroLink();
                     const metrics = neurolink.getMetrics();
-                    if (spinner)
+                    if (spinner) {
                         spinner.succeed("Costs calculated");
+                    }
                     if (args.format === "json") {
                         const jsonOutput = {
                             totalCost: metrics.totalCost,
@@ -389,60 +399,61 @@ export class ObservabilityCommandFactory {
                         if (args.byModel !== false) {
                             jsonOutput.costByModel = metrics.costByModel;
                         }
-                        console.log(JSON.stringify(jsonOutput, null, 2));
+                        logger.always(JSON.stringify(jsonOutput, null, 2));
                     }
                     else {
-                        console.log("");
-                        console.log(chalk.bold.cyan("=== Cost Breakdown ==="));
-                        console.log("");
+                        logger.always("");
+                        logger.always(chalk.bold.cyan("=== Cost Breakdown ==="));
+                        logger.always("");
                         // Total cost
-                        console.log(chalk.bold(`Total Cost: ${formatCost(metrics.totalCost ?? 0)}`));
+                        logger.always(chalk.bold(`Total Cost: ${formatCost(metrics.totalCost ?? 0)}`));
                         // Cost by provider
                         if (args.byProvider !== false &&
                             metrics.costByProvider &&
                             metrics.costByProvider.length > 0) {
-                            console.log("");
-                            console.log(chalk.bold("By Provider:"));
+                            logger.always("");
+                            logger.always(chalk.bold("By Provider:"));
                             // Sort by cost descending
                             const sortedProviders = [...metrics.costByProvider].sort((a, b) => b.totalCost - a.totalCost);
                             for (const provider of sortedProviders) {
                                 const costStr = formatCost(provider.totalCost);
                                 const avgCost = formatCost(provider.avgCostPerRequest);
-                                console.log(`  ${chalk.cyan(provider.provider.padEnd(15))} ${costStr}`);
-                                console.log(chalk.gray(`    ${provider.requestCount} requests, avg ${avgCost}/req`));
+                                logger.always(`  ${chalk.cyan(provider.provider.padEnd(15))} ${costStr}`);
+                                logger.always(chalk.gray(`    ${provider.requestCount} requests, avg ${avgCost}/req`));
                             }
                         }
                         // Cost by model
                         if (args.byModel !== false &&
                             metrics.costByModel &&
                             metrics.costByModel.length > 0) {
-                            console.log("");
-                            console.log(chalk.bold("By Model:"));
+                            logger.always("");
+                            logger.always(chalk.bold("By Model:"));
                             // Sort by cost descending
                             const sortedModels = [...metrics.costByModel].sort((a, b) => b.totalCost - a.totalCost);
                             for (const model of sortedModels) {
                                 const costStr = formatCost(model.totalCost);
                                 const avgCost = formatCost(model.avgCostPerRequest);
-                                console.log(`  ${chalk.cyan(model.model)}`);
-                                console.log(`    Cost: ${costStr}`);
-                                console.log(chalk.gray(`    ${model.requestCount} requests, avg ${avgCost}/req`));
-                                console.log(chalk.gray(`    ${model.inputTokens.toLocaleString()} input, ${model.outputTokens.toLocaleString()} output tokens`));
+                                logger.always(`  ${chalk.cyan(model.model)}`);
+                                logger.always(`    Cost: ${costStr}`);
+                                logger.always(chalk.gray(`    ${model.requestCount} requests, avg ${avgCost}/req`));
+                                logger.always(chalk.gray(`    ${model.inputTokens.toLocaleString()} input, ${model.outputTokens.toLocaleString()} output tokens`));
                             }
                         }
                         // No cost data
                         if ((!metrics.costByProvider ||
                             metrics.costByProvider.length === 0) &&
                             (!metrics.costByModel || metrics.costByModel.length === 0)) {
-                            console.log("");
-                            console.log(chalk.gray("No cost data available."));
-                            console.log(chalk.gray("Cost tracking is recorded when observability is enabled."));
+                            logger.always("");
+                            logger.always(chalk.gray("No cost data available."));
+                            logger.always(chalk.gray("Cost tracking is recorded when observability is enabled."));
                         }
-                        console.log("");
+                        logger.always("");
                     }
                 }
                 catch (error) {
-                    if (spinner)
+                    if (spinner) {
                         spinner.fail("Failed to get costs");
+                    }
                     logger.error("Error:", error instanceof Error ? error.message : String(error));
                     process.exit(1);
                 }

package/dist/cli/commands/proxy.d.ts

@@ -13,6 +13,32 @@ import type { CommandModule } from "yargs";
 import type { Hono } from "hono";
 import type { AccountAllowlist, LoadedProxyConfig, ModelRouterInterface, ProxyGuardArgs, ProxyNeurolinkRuntime, ProxyStartArgs, ProxyStartStrategy, ProxyStatusArgs, ProxyTelemetryArgs, ProxyReadinessState } from "../../lib/types/index.js";
 import { ProxyRuntimeConfigStore } from "../../lib/proxy/runtimeConfig.js";
+/**
+ * Best-effort check that a pid actually belongs to a neurolink proxy process,
+ * so a stale/recycled supervisor pid is never mistaken for a live supervisor
+ * and signalled. Returns false when the process cannot be confirmed as ours.
+ *
+ * @param expectedStartTimeIso - The `ProxySupervisorState.startTime` (ISO
+ *   string) recorded when the supervisor we expect at `pid` was launched.
+ *   When provided, this is cross-checked against `pid`'s actual OS-reported
+ *   start time (see {@link getProcessStartTime}) — the args match alone
+ *   ("neurolink" + "proxy" both present) is not airtight, since an
+ *   unrelated process (e.g. a shell running this very test suite, or a
+ *   coincidentally-named script) could match it too. A pid recycled by such
+ *   a process would have a start time far from the recorded supervisor
+ *   startTime, which this catches.
+ *
+ *   Deliberately fail-open on anything unparseable: `ps -o lstart=` output
+ *   parsing is inherently a little fragile (locale/format quirks), and the
+ *   cost of a false "can't confirm" is silently regressing to pre-hardening
+ *   behavior, while the cost of a false "confirmed mismatch" is leaving a
+ *   real supervisor running and orphaning its socket during uninstall — the
+ *   former is the safer failure mode. So this only ever returns false for
+ *   the startTime check when BOTH timestamps parsed successfully AND their
+ *   drift exceeds the tolerance; any parse failure is treated as "can't
+ *   confirm a mismatch" and falls through to the args-only result.
+ */
+export declare function processLooksLikeProxySupervisor(pid: number, expectedStartTimeIso?: string): Promise<boolean>;
 export declare function mapClaudeErrorTypeToStatus(errorType?: string): number;
 export declare function createProxyStartApp(params: {
     neurolink: ProxyNeurolinkRuntime["neurolink"];

package/dist/cli/commands/proxy.js

@@ -41,6 +41,14 @@ const _require = createRequire(import.meta.url);
 const PROXY_VERSION = packageJson.version;
 const PROXY_TELEMETRY_SCRIPT_PATH = fileURLToPath(new URL("../../../scripts/observability/manage-local-openobserve.sh", import.meta.url));
 const PROXY_LIFECYCLE_SHUTDOWN_TIMEOUT_MS = 5_000;
+// Allowed drift between a pid's OS-reported start time and the persisted
+// ProxySupervisorState.startTime before processLooksLikeProxySupervisor
+// treats it as a confident mismatch (recycled pid). Generous on purpose:
+// `supervisorStartedAt` is captured inside runLaunchdProxySupervisor, which
+// runs after Node has already booted and done setup, so it always lags the
+// OS-level fork/exec by a little — a tight tolerance would produce false
+// mismatches on a slow/cold-started machine.
+const PROXY_SUPERVISOR_START_TIME_TOLERANCE_MS = 10_000;
 const PROXY_UPDATE_CONTROL_TOKEN = process.env.NEUROLINK_PROXY_UPDATE_CONTROL_TOKEN?.trim() ||
     crypto.randomUUID();
 // =============================================================================
@@ -98,23 +106,131 @@ function getProcessStatus(pid) {
     }
 }
 /**
- * Best-effort check that a pid actually belongs to a neurolink proxy process,
- * so a stale/recycled supervisor pid is never mistaken for a live supervisor
- * and signalled. Returns false when the process cannot be confirmed as ours.
+ * Read a single `ps -o <field>=` field for `pid`, off the event loop (async
+ * `execFile`, not `execFileSync`) and bounded by a short timeout, so a
+ * hung/zombie `ps` invocation can never block the event loop or hang the
+ * (often uninstall-path) async caller. Shared by {@link getProcessStartTime}
+ * and {@link processLooksLikeProxySupervisor}, which both read a single
+ * `ps -o <field>=` column for the same pid.
+ *
+ * Returns null — never throws — on any error, timeout, or empty output, so
+ * callers uniformly treat "couldn't read" as "can't confirm either way"
+ * rather than distinguishing the failure mode.
  */
-async function processLooksLikeProxySupervisor(pid) {
+async function readPsField(pid, field) {
     try {
-        const { execFileSync } = await import("node:child_process");
-        const args = execFileSync("ps", ["-p", String(pid), "-o", "args="], {
+        const { execFile } = await import("node:child_process");
+        const { promisify } = await import("node:util");
+        const execFileAsync = promisify(execFile);
+        const { stdout } = await withTimeout(execFileAsync("ps", ["-p", String(pid), "-o", `${field}=`], {
             encoding: "utf-8",
-            stdio: ["ignore", "pipe", "ignore"],
-        });
-        return /neurolink/i.test(args);
+        }), 2000, `ps -o ${field}= timed out for pid ${pid}`);
+        const trimmed = stdout.trim();
+        return trimmed || null;
     }
     catch {
-        // `ps` unavailable or the pid vanished — do not signal an unverified pid.
+        return null;
+    }
+}
+/**
+ * Best-effort, macOS-only (uninstall is macOS-only) read of `pid`'s
+ * OS-reported start time via `ps -o lstart=`, which prints a fixed-width
+ * `Www Mmm dd hh:mm:ss yyyy` timestamp — the same shape `Date`'s parser
+ * already understands (it's the format `Date#toString()` itself produces
+ * modulo the trailing timezone). Returns null (never throws) when `ps`
+ * fails or its output doesn't parse, so callers can tell "confirmed
+ * mismatch" apart from "couldn't confirm either way".
+ */
+async function getProcessStartTime(pid) {
+    const out = await readPsField(pid, "lstart");
+    if (!out) {
+        return null;
+    }
+    // `ps -o lstart=` prints the OS start time in the machine's LOCAL timezone
+    // with no offset, e.g. "Sun Jul 19 20:12:41 2026". Parse the components and
+    // build the Date via the local-time constructor rather than relying on the
+    // engine's implementation-defined parsing of non-ISO date strings. The
+    // result is the same absolute instant the supervisor persisted as an
+    // ISO-UTC string, so the drift comparison against it is timezone-safe.
+    const m = out.match(/^\w{3}\s+(\w{3})\s+(\d{1,2})\s+(\d{2}):(\d{2}):(\d{2})\s+(\d{4})$/);
+    if (!m) {
+        return null;
+    }
+    const monthIndex = [
+        "Jan",
+        "Feb",
+        "Mar",
+        "Apr",
+        "May",
+        "Jun",
+        "Jul",
+        "Aug",
+        "Sep",
+        "Oct",
+        "Nov",
+        "Dec",
+    ].indexOf(m[1]);
+    if (monthIndex < 0) {
+        return null;
+    }
+    const parsed = new Date(Number(m[6]), monthIndex, Number(m[2]), Number(m[3]), Number(m[4]), Number(m[5]));
+    return Number.isNaN(parsed.getTime()) ? null : parsed;
+}
+/**
+ * Best-effort check that a pid actually belongs to a neurolink proxy process,
+ * so a stale/recycled supervisor pid is never mistaken for a live supervisor
+ * and signalled. Returns false when the process cannot be confirmed as ours.
+ *
+ * @param expectedStartTimeIso - The `ProxySupervisorState.startTime` (ISO
+ *   string) recorded when the supervisor we expect at `pid` was launched.
+ *   When provided, this is cross-checked against `pid`'s actual OS-reported
+ *   start time (see {@link getProcessStartTime}) — the args match alone
+ *   ("neurolink" + "proxy" both present) is not airtight, since an
+ *   unrelated process (e.g. a shell running this very test suite, or a
+ *   coincidentally-named script) could match it too. A pid recycled by such
+ *   a process would have a start time far from the recorded supervisor
+ *   startTime, which this catches.
+ *
+ *   Deliberately fail-open on anything unparseable: `ps -o lstart=` output
+ *   parsing is inherently a little fragile (locale/format quirks), and the
+ *   cost of a false "can't confirm" is silently regressing to pre-hardening
+ *   behavior, while the cost of a false "confirmed mismatch" is leaving a
+ *   real supervisor running and orphaning its socket during uninstall — the
+ *   former is the safer failure mode. So this only ever returns false for
+ *   the startTime check when BOTH timestamps parsed successfully AND their
+ *   drift exceeds the tolerance; any parse failure is treated as "can't
+ *   confirm a mismatch" and falls through to the args-only result.
+ */
+export async function processLooksLikeProxySupervisor(pid, expectedStartTimeIso) {
+    const args = await readPsField(pid, "args");
+    if (args === null) {
+        // `ps` unavailable, timed out, or the pid vanished — do not signal an
+        // unverified pid.
+        return false;
+    }
+    // `/neurolink/i` alone is too broad: any process whose args merely
+    // *mention* "neurolink" (e.g. a shell running in a directory named
+    // "neurolink", an editor with a neurolink file open) would match, and a
+    // stale/recycled pid running such a process could then be SIGTERM'd/
+    // SIGKILL'd by `ensureSupervisorStoppedBeforeClear` during uninstall.
+    // Require the actual proxy-supervisor invocation — both "neurolink" AND
+    // the "proxy" subcommand present in args.
+    if (!(/neurolink/i.test(args) && /\bproxy\b/i.test(args))) {
         return false;
     }
+    if (!expectedStartTimeIso) {
+        return true;
+    }
+    const expected = new Date(expectedStartTimeIso);
+    if (Number.isNaN(expected.getTime())) {
+        return true; // recorded startTime itself is unparseable — can't confirm a mismatch
+    }
+    const actual = await getProcessStartTime(pid);
+    if (!actual) {
+        return true; // ps -o lstart= unavailable/unparseable — can't confirm a mismatch
+    }
+    const driftMs = Math.abs(actual.getTime() - expected.getTime());
+    return driftMs <= PROXY_SUPERVISOR_START_TIME_TOLERANCE_MS;
 }
 /**
  * Ensure any supervisor recorded in state is actually stopped before its state
@@ -124,14 +240,17 @@ async function processLooksLikeProxySupervisor(pid) {
  * the uninstall instead of silently discarding the record.
  */
 async function ensureSupervisorStoppedBeforeClear() {
-    const pid = loadProxySupervisorState()?.pid;
+    const supervisorState = loadProxySupervisorState();
+    const pid = supervisorState?.pid;
     if (!pid || getProcessStatus(pid) === "not_running") {
         return true;
     }
     // Guard against a stale/recycled pid: only signal a process that still looks
     // like a neurolink proxy supervisor, so uninstall never terminates an
-    // unrelated, same-user process that inherited the recorded pid.
-    if (!(await processLooksLikeProxySupervisor(pid))) {
+    // unrelated, same-user process that inherited the recorded pid. Also cross-
+    // checks the pid's actual OS start time against the recorded
+    // supervisorState.startTime (see processLooksLikeProxySupervisor).
+    if (!(await processLooksLikeProxySupervisor(pid, supervisorState?.startTime))) {
         return true;
     }
     try {