@juspay/neurolink 12.17.1 → 12.17.3

package/dist/proxy/codexFallback.js

@@ -7,18 +7,88 @@
  * rules as a native Codex request.
  */
 import { ClaudeStreamSerializer, generateToolUseId } from "./claudeFormat.js";
+import { classifyProxyFailureCode } from "./proxyFailureDetails.js";
 import { extractCodexUsage } from "./codexUsage.js";
 import { proxyTokenUsage } from "./proxyTokenUsage.js";
+import { sanitizeForLog } from "../utils/logSanitize.js";
 export class CodexFallbackResponseError extends Error {
     status;
     responseBody;
+    code;
+    retryable;
     constructor(status, responseBody) {
         super(`Codex fallback request returned HTTP ${status}`);
         this.name = "CodexFallbackResponseError";
         this.status = status;
         this.responseBody = responseBody;
+        try {
+            const payload = JSON.parse(responseBody);
+            if (isRecord(payload)) {
+                const detail = streamFailureDetails(payload, "http_error");
+                this.code = detail.code;
+                this.retryable = detail.retryable;
+                if (detail.message) {
+                    this.message = detail.message;
+                }
+            }
+        }
+        catch {
+            // Non-JSON upstream responses retain the HTTP status without exposing HTML.
+        }
     }
 }
+/** A provider terminal event, preserved through the format adapter. */
+export class CodexFallbackStreamError extends Error {
+    status;
+    code;
+    retryable;
+    usage;
+    constructor(payload, eventType, usage) {
+        const detail = streamFailureDetails(payload, eventType);
+        super(detail.message ?? `Codex fallback stream terminated with ${eventType}`);
+        this.name = "CodexFallbackStreamError";
+        this.code = detail.code;
+        this.status = detail.status;
+        this.retryable = detail.retryable;
+        const observed = extractCodexUsage(payload);
+        this.usage = observed
+            ? {
+                ...proxyTokenUsage({
+                    inputTokens: observed.inputTokens,
+                    outputTokens: observed.outputTokens,
+                    reasoningTokens: observed.reasoningTokensObserved
+                        ? observed.reasoningTokens
+                        : undefined,
+                    cacheReadTokens: observed.cacheReadTokens,
+                    cacheCreationTokens: observed.cacheCreationTokens,
+                    inputIncludesCachedTokens: true,
+                }),
+                inputTokensObserved: observed.inputTokensObserved,
+                outputTokensObserved: observed.outputTokensObserved,
+            }
+            : usage;
+    }
+}
+function streamFailureDetails(payload, eventType) {
+    const response = isRecord(payload.response) ? payload.response : payload;
+    const error = isRecord(response.error) ? response.error : response;
+    const incomplete = isRecord(response.incomplete_details)
+        ? response.incomplete_details
+        : {};
+    const code = sanitizeForLog(asNonEmptyString(error.code) ??
+        asNonEmptyString(incomplete.reason) ??
+        eventType, 200);
+    const known = classifyProxyFailureCode(code);
+    return {
+        code,
+        status: known.status ?? 502,
+        retryable: known.retryable ??
+            (typeof error.retryable === "boolean" ? error.retryable : undefined),
+        message: typeof error.message === "string"
+            ? sanitizeForLog(error.message, 500)
+            : undefined,
+    };
+}
 function isRecord(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value);
 }
@@ -338,7 +408,7 @@ export function parseCodexFallbackSSE(sse) {
         if (type === "error" ||
             type === "response.failed" ||
             type === "response.incomplete") {
-            throw new Error(`Codex fallback stream terminated with ${type}`);
+            throw new CodexFallbackStreamError(payload, type, usage);
         }
         if (type === "response.output_text.delta") {
             if (typeof payload.delta !== "string") {
@@ -368,16 +438,20 @@ export function parseCodexFallbackSSE(sse) {
         }
         const parsedUsage = extractCodexUsage(payload);
         if (parsedUsage) {
-            usage = proxyTokenUsage({
-                inputTokens: parsedUsage.inputTokens,
-                outputTokens: parsedUsage.outputTokens,
-                reasoningTokens: parsedUsage.reasoningTokensObserved
-                    ? parsedUsage.reasoningTokens
-                    : undefined,
-                cacheReadTokens: parsedUsage.cacheReadTokens,
-                cacheCreationTokens: parsedUsage.cacheCreationTokens,
-                inputIncludesCachedTokens: true,
-            });
+            usage = {
+                ...proxyTokenUsage({
+                    inputTokens: parsedUsage.inputTokens,
+                    outputTokens: parsedUsage.outputTokens,
+                    reasoningTokens: parsedUsage.reasoningTokensObserved
+                        ? parsedUsage.reasoningTokens
+                        : undefined,
+                    cacheReadTokens: parsedUsage.cacheReadTokens,
+                    cacheCreationTokens: parsedUsage.cacheCreationTokens,
+                    inputIncludesCachedTokens: true,
+                }),
+                inputTokensObserved: parsedUsage.inputTokensObserved,
+                outputTokensObserved: parsedUsage.outputTokensObserved,
+            };
         }
         textFromResponse = outputTextFromResponse(payload);
     }
@@ -387,7 +461,10 @@ export function parseCodexFallbackSSE(sse) {
     const text = textFromDeltas || textFromCompletedItems || textFromResponse;
     const resolvedToolCalls = [...toolCalls.values()];
     if (!text && resolvedToolCalls.length === 0) {
-        throw new Error("Codex fallback returned no content or tool calls");
+        throw new CodexFallbackStreamError({
+            code: "empty_response",
+            message: "Codex fallback returned no content or tool calls",
+        }, "empty_response", usage);
     }
     return {
         text,
@@ -498,7 +575,7 @@ export async function createCodexFallbackStream(response, model) {
                 if (type === "error" ||
                     type === "response.failed" ||
                     type === "response.incomplete") {
-                    throw new Error(`Codex fallback stream terminated with ${type}`);
+                    throw new CodexFallbackStreamError(payload, type, usage);
                 }
                 const index = typeof payload.output_index === "number" ? payload.output_index : 0;
                 if (type === "response.output_text.delta") {
@@ -520,16 +597,20 @@ export async function createCodexFallbackStream(response, model) {
                     completed = true;
                     const parsedUsage = extractCodexUsage(payload);
                     if (parsedUsage) {
-                        usage = proxyTokenUsage({
-                            inputTokens: parsedUsage.inputTokens,
-                            outputTokens: parsedUsage.outputTokens,
-                            reasoningTokens: parsedUsage.reasoningTokensObserved
-                                ? parsedUsage.reasoningTokens
-                                : undefined,
-                            cacheReadTokens: parsedUsage.cacheReadTokens,
-                            cacheCreationTokens: parsedUsage.cacheCreationTokens,
-                            inputIncludesCachedTokens: true,
-                        });
+                        usage = {
+                            ...proxyTokenUsage({
+                                inputTokens: parsedUsage.inputTokens,
+                                outputTokens: parsedUsage.outputTokens,
+                                reasoningTokens: parsedUsage.reasoningTokensObserved
+                                    ? parsedUsage.reasoningTokens
+                                    : undefined,
+                                cacheReadTokens: parsedUsage.cacheReadTokens,
+                                cacheCreationTokens: parsedUsage.cacheCreationTokens,
+                                inputIncludesCachedTokens: true,
+                            }),
+                            inputTokensObserved: parsedUsage.inputTokensObserved,
+                            outputTokensObserved: parsedUsage.outputTokensObserved,
+                        };
                     }
                     const responseBody = payload.response;
                     if (isRecord(responseBody) && Array.isArray(responseBody.output)) {
@@ -573,7 +654,10 @@ export async function createCodexFallbackStream(response, model) {
                 throw new Error("Codex fallback stream ended before response.completed");
             }
             if (textLength === 0 && toolCalls.size === 0) {
-                throw new Error("Codex fallback returned no content or tool calls");
+                throw new CodexFallbackStreamError({
+                    code: "empty_response",
+                    message: "Codex fallback returned no content or tool calls",
+                }, "empty_response", usage);
             }
             const finishReason = toolCalls.size > 0 ? "tool_use" : "end_turn";
             yield* serializer.finish(usage?.output, finishReason, {

package/dist/proxy/codexUsage.js

@@ -104,6 +104,8 @@ export function extractCodexUsage(payload) {
     return {
         inputTokens: nonNegativeInt(input),
         outputTokens: nonNegativeInt(output),
+        inputTokensObserved: typeof input === "number" && Number.isFinite(input) && input >= 0,
+        outputTokensObserved: typeof output === "number" && Number.isFinite(output) && output >= 0,
         cacheReadTokens: nonNegativeInt(inputDetails?.cached_tokens),
         cacheCreationTokens: nonNegativeInt(inputDetails?.cache_write_tokens),
         reasoningTokens: nonNegativeInt(outputDetails?.reasoning_tokens),

package/dist/proxy/globalInstaller.d.ts

@@ -1,4 +1,4 @@
-import type { GlobalInstallerKind, GlobalInstallerResolution, InstalledVersionValidation, ResolveGlobalInstallerOptions, ValidateInstalledVersionOptions } from "../types/index.js";
+import type { ProxyServiceInstallSettings, ProxyPackageSelection, ProxyStagedInstallOptions, GlobalInstallerExecFile, GlobalInstallerKind, GlobalInstallerResolution, InstalledVersionValidation, ResolveGlobalInstallerOptions, ValidateInstalledVersionOptions } from "../types/index.js";
 /** Resolve a package manager that can update the installation currently running. */
 export declare function resolveGlobalInstaller(options?: ResolveGlobalInstallerOptions): GlobalInstallerResolution;
 export declare function getGlobalInstallArgs(kind: GlobalInstallerKind, packageSpec: string): string[];
@@ -17,3 +17,34 @@ export declare function isTransientInstallFailure(error: unknown): boolean;
  */
 export declare function validateInstalledVersion(options: ValidateInstalledVersionOptions): Promise<InstalledVersionValidation>;
 export declare function describeInstallFailure(error: unknown): string;
+/** Read package metadata without importing the CLI/provider/telemetry graph. */
+export declare function inspectProxyPackage(entryScript: string, nodePath?: string): ProxyPackageSelection;
+export declare function readProxyPackageSelection(packagesDir: string, previous?: boolean): ProxyPackageSelection | null;
+/** Resolve immutable selections before consulting an older mutable global entry. */
+export declare function resolveProxyWorkerPackage(options: {
+    packagesDir: string;
+    entryScript: string;
+    expectedVersion: string;
+}): ProxyPackageSelection;
+/** Persist only package selection; runtime env, config and launchd settings are untouched. */
+export declare function selectProxyPackage(packagesDir: string, selection: ProxyPackageSelection, isCurrentOwner?: () => boolean): void;
+/** No startup probes: IPC descriptors and OTel initialization belong to the real process. */
+export declare function writeProxyPackageLauncher(path: string, selection: ProxyPackageSelection, isCurrentOwner?: () => boolean): void;
+/** Install in a private tree, then publish the immutable directory after validation. */
+export declare function installStagedProxyPackage(options: ProxyStagedInstallOptions): Promise<ProxyPackageSelection>;
+/** Only operator runtime settings survive reinstall, never worker IPC identity. */
+export declare function isProxyServiceEnvironmentKey(name: string): boolean;
+/** Parse plutil JSON without exposing credentials or invoking the saved launcher. */
+export declare function parseProxyServiceInstallSettings(value: unknown): ProxyServiceInstallSettings;
+/** Distinguish an absent launchd job from permission failures without logging plist/env data. */
+export declare function probeProxyLaunchdPresence(options: {
+    label: string;
+    uid: number;
+    execFileSync?: GlobalInstallerExecFile;
+}): "loaded" | "not_loaded" | "unknown";
+/** Read-only guard: callers must run this before every reinstall mutation. */
+export declare function assertProxyServiceInstallIdle(options: {
+    pids: number[];
+    getProcessStatus: (pid: number) => "running" | "not_running" | "unknown";
+    launchdPresence: "loaded" | "not_loaded" | "unknown";
+}): void;

package/dist/proxy/globalInstaller.js

@@ -1,7 +1,9 @@
-import { execFileSync as nodeExecFileSync } from "node:child_process";
-import { accessSync, constants, existsSync, realpathSync } from "node:fs";
+import { execFileSync as nodeExecFileSync, spawn as nodeSpawn, } from "node:child_process";
+import { accessSync, constants, existsSync, realpathSync, readFileSync, mkdirSync, writeFileSync, renameSync, chmodSync, rmSync, } from "node:fs";
+import { mkdir, mkdtemp, rename, rm, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, dirname, isAbsolute, join, resolve } from "node:path";
+import { randomUUID } from "node:crypto";
+import { basename, dirname, isAbsolute, join, resolve, relative, } from "node:path";
 function runText(execFileSync, bin, args) {
     return String(execFileSync(bin, args, {
         encoding: "utf8",
@@ -246,3 +248,384 @@ export function describeInstallFailure(error) {
         .filter(Boolean)
         .join("\n");
 }
+/** Read package metadata without importing the CLI/provider/telemetry graph. */
+export function inspectProxyPackage(entryScript, nodePath = process.execPath) {
+    const entry = realpathSync(entryScript);
+    let directory = dirname(entry);
+    while (true) {
+        const manifestPath = join(directory, "package.json");
+        if (existsSync(manifestPath)) {
+            const manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+            if (manifest.name === "@juspay/neurolink") {
+                if (typeof manifest.version !== "string" ||
+                    !/^\d+\.\d+\.\d+$/.test(manifest.version)) {
+                    throw new Error("Invalid proxy package version");
+                }
+                return { version: manifest.version, entryScript: entry, nodePath };
+            }
+        }
+        const parent = dirname(directory);
+        if (parent === directory) {
+            throw new Error("Proxy entrypoint has no package manifest");
+        }
+        directory = parent;
+    }
+}
+function validateProxyPackageSelection(value) {
+    try {
+        if (!value || typeof value !== "object") {
+            return null;
+        }
+        const selection = value;
+        if (typeof selection.entryScript !== "string" ||
+            typeof selection.nodePath !== "string" ||
+            !isAbsolute(selection.entryScript) ||
+            !isAbsolute(selection.nodePath)) {
+            return null;
+        }
+        const actual = inspectProxyPackage(selection.entryScript, selection.nodePath);
+        return actual.version === selection.version ? actual : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Read active and rollback selections from one committed generation. */
+function readProxyPackageSelections(packagesDir) {
+    let value;
+    try {
+        value = JSON.parse(readFileSync(join(packagesDir, "selections.json"), "utf8"));
+    }
+    catch (error) {
+        // Legacy migration is allowed only when no atomic record has ever been
+        // published. Invalid/unreadable committed state must not revive stale files.
+        if (error.code !== "ENOENT") {
+            return null;
+        }
+        const readLegacy = (file) => {
+            try {
+                return validateProxyPackageSelection(JSON.parse(readFileSync(join(packagesDir, file), "utf8")));
+            }
+            catch {
+                return null;
+            }
+        };
+        return {
+            schemaVersion: 1,
+            active: readLegacy("active.json"),
+            previous: readLegacy("previous.json"),
+        };
+    }
+    if (!value || typeof value !== "object") {
+        return null;
+    }
+    const state = value;
+    if (state.schemaVersion !== 1 ||
+        !("active" in state) ||
+        !("previous" in state)) {
+        return null;
+    }
+    return {
+        schemaVersion: 1,
+        active: validateProxyPackageSelection(state.active),
+        previous: validateProxyPackageSelection(state.previous),
+    };
+}
+export function readProxyPackageSelection(packagesDir, previous = false) {
+    const state = readProxyPackageSelections(packagesDir);
+    return (previous ? state?.previous : state?.active) ?? null;
+}
+/** Resolve immutable selections before consulting an older mutable global entry. */
+export function resolveProxyWorkerPackage(options) {
+    const state = readProxyPackageSelections(options.packagesDir);
+    for (const selection of [state?.active, state?.previous]) {
+        if (selection?.version === options.expectedVersion) {
+            return selection;
+        }
+    }
+    try {
+        const original = inspectProxyPackage(options.entryScript);
+        if (original.version === options.expectedVersion) {
+            return original;
+        }
+    }
+    catch {
+        // A global upgrade/removal may invalidate the original entry while an
+        // already selected private package remains the valid recovery target.
+    }
+    throw new Error(`No validated package selection for worker v${options.expectedVersion}`);
+}
+function assertPackageSelectionOwner(isCurrentOwner) {
+    if (isCurrentOwner && !isCurrentOwner()) {
+        throw new Error("Proxy update owner changed; package selection was not modified");
+    }
+}
+/** Persist only package selection; runtime env, config and launchd settings are untouched. */
+export function selectProxyPackage(packagesDir, selection, isCurrentOwner) {
+    assertPackageSelectionOwner(isCurrentOwner);
+    mkdirSync(packagesDir, { recursive: true, mode: 0o700 });
+    const current = readProxyPackageSelections(packagesDir);
+    if (!current) {
+        throw new Error("Proxy package selection state is unreadable or invalid");
+    }
+    // Manifest reads can outlive a service owner, even before private staging.
+    assertPackageSelectionOwner(isCurrentOwner);
+    const state = {
+        schemaVersion: 1,
+        active: selection,
+        previous: current.active && current.active.version !== selection.version
+            ? current.active
+            : current.previous,
+    };
+    const temporary = join(packagesDir, `selections-${process.pid}-${randomUUID()}.tmp`);
+    try {
+        writeFileSync(temporary, JSON.stringify(state), {
+            mode: 0o600,
+            flag: "wx",
+        });
+        assertPackageSelectionOwner(isCurrentOwner);
+        // One rename publishes both versions. A stale owner never mutates rollback
+        // state independently, and must never attempt to restore a newer owner's state.
+        renameSync(temporary, join(packagesDir, "selections.json"));
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
+/** No startup probes: IPC descriptors and OTel initialization belong to the real process. */
+export function writeProxyPackageLauncher(path, selection, isCurrentOwner) {
+    assertPackageSelectionOwner(isCurrentOwner);
+    const quote = (value) => `'${value.replace(/'/g, "'\\''")}'`;
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    // --version reads the manifest in a tiny isolated Node process. This proves
+    // the selected files still exist without cold-loading every provider twice.
+    const probe = `const fs=require('node:fs');let p=${JSON.stringify(dirname(selection.entryScript))};for(;;){const f=p+'/package.json';if(fs.existsSync(f)){const m=JSON.parse(fs.readFileSync(f,'utf8'));if(m.name==='@juspay/neurolink'){if(m.version!==${JSON.stringify(selection.version)})process.exit(1);console.log(m.version);break;}}const q=require('node:path').dirname(p);if(q===p)process.exit(1);p=q;}`;
+    const script = `#!/bin/sh\n# Generated proxy package selection. Service environment is inherited.\n[ -f ${quote(selection.entryScript)} ] || exit 127\nif [ "$#" = "1" ] && [ "$1" = "--version" ]; then\n  exec ${quote(selection.nodePath)} -e ${quote(probe)}\nfi\nexec ${quote(selection.nodePath)} ${quote(selection.entryScript)} "$@"\n`;
+    const temporary = `${path}.${process.pid}.tmp`;
+    writeFileSync(temporary, script, { mode: 0o755 });
+    chmodSync(temporary, 0o755);
+    assertPackageSelectionOwner(isCurrentOwner);
+    renameSync(temporary, path);
+}
+/** Install in a private tree, then publish the immutable directory after validation. */
+export async function installStagedProxyPackage(options) {
+    if (!/^\d+\.\d+\.\d+$/.test(options.version)) {
+        throw new Error("Invalid proxy package version");
+    }
+    await mkdir(options.packagesDir, { recursive: true, mode: 0o700 });
+    const destination = join(options.packagesDir, options.version);
+    const validate = (root) => {
+        const packageRoot = join(root, "node_modules", "@juspay", "neurolink");
+        const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        const bin = typeof manifest.bin === "string" ? manifest.bin : manifest.bin?.neurolink;
+        if (!bin) {
+            throw new Error("Candidate package is missing its neurolink executable");
+        }
+        const entry = realpathSync(resolve(packageRoot, bin));
+        const rel = relative(realpathSync(packageRoot), entry);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            throw new Error("Candidate executable escapes its package");
+        }
+        const selection = inspectProxyPackage(entry);
+        if (selection.version !== options.version) {
+            throw new Error(`Candidate version ${selection.version} does not match ${options.version}`);
+        }
+        (options.execFileSync ?? nodeExecFileSync)(selection.nodePath, ["--check", selection.entryScript], { timeout: 10_000, stdio: "pipe" });
+        return selection;
+    };
+    if (existsSync(destination)) {
+        return validate(destination);
+    }
+    const staging = await mkdtemp(join(options.packagesDir, `.install-${options.version}-`));
+    try {
+        await writeFile(join(staging, "package.json"), JSON.stringify({ private: true }), { mode: 0o600 });
+        const spec = `@juspay/neurolink@${options.version}`;
+        const args = options.installer.kind === "npm"
+            ? [
+                "install",
+                "--prefix",
+                staging,
+                "--no-save",
+                "--package-lock=false",
+                "--no-audit",
+                "--no-fund",
+                "--omit=dev",
+                "--loglevel=http",
+                spec,
+            ]
+            : [
+                "add",
+                "--dir",
+                staging,
+                "--no-lockfile",
+                "--prod",
+                "--reporter=ndjson",
+                spec,
+            ];
+        await new Promise((resolveInstall, rejectInstall) => {
+            const started = Date.now();
+            let lastProgress = started;
+            let bytes = 0;
+            let failureCode;
+            let failure;
+            let killTimer;
+            const child = (options.spawn ?? nodeSpawn)(options.installer.bin, args, {
+                cwd: staging,
+                env: { ...process.env, npm_config_update_notifier: "false" },
+                stdio: ["ignore", "pipe", "pipe"],
+                detached: process.platform !== "win32",
+            });
+            const progress = (chunk) => {
+                bytes += Buffer.byteLength(chunk);
+                lastProgress = Date.now();
+                // Retain a machine code only: npm output can include authenticated URLs.
+                const text = String(chunk);
+                const code = text.match(/npm (?:ERR!|error) code ([A-Z][A-Z0-9_]+)/)?.[1] ??
+                    text.match(/\b(?:ECONNRESET|ECONNREFUSED|EAI_AGAIN|EHOSTUNREACH|ENETUNREACH|ENOTFOUND|EPIPE|ETIMEDOUT)\b/)?.[0];
+                if (code) {
+                    failureCode = code;
+                }
+            };
+            child.stdout?.on("data", progress);
+            child.stderr?.on("data", progress);
+            const signal = (value) => {
+                try {
+                    if (process.platform !== "win32" && child.pid) {
+                        process.kill(-child.pid, value);
+                    }
+                    else {
+                        child.kill(value);
+                    }
+                }
+                catch {
+                    /* child already exited */
+                }
+            };
+            const interval = setInterval(() => {
+                const now = Date.now();
+                options.onProgress?.({
+                    elapsedMs: now - started,
+                    outputBytes: bytes,
+                });
+                if (!failure &&
+                    (now - started >= (options.maxDurationMs ?? 15 * 60_000) ||
+                        now - lastProgress >= (options.idleTimeoutMs ?? 120_000))) {
+                    failure = Object.assign(new Error(`Staged install timed out after ${now - started}ms (${bytes} output bytes, idle ${now - lastProgress}ms)`), { code: "ETIMEDOUT" });
+                    signal("SIGTERM");
+                    killTimer = setTimeout(() => signal("SIGKILL"), options.killGraceMs ?? 5_000);
+                }
+            }, Math.min(5_000, Math.max(10, (options.idleTimeoutMs ?? 120_000) / 4)));
+            const cleanup = () => {
+                clearInterval(interval);
+                clearTimeout(killTimer);
+            };
+            child.once("error", (error) => {
+                cleanup();
+                rejectInstall(error);
+            });
+            child.once("close", (code, signalName) => {
+                cleanup();
+                if (failure) {
+                    rejectInstall(failure);
+                }
+                else if (code !== 0) {
+                    rejectInstall(Object.assign(new Error(`Staged install exited code=${code} signal=${signalName ?? "none"} errorCode=${failureCode ?? "unknown"}`), {
+                        code: failureCode ??
+                            (code === null ? "ECONNRESET" : "INSTALL_FAILED"),
+                    }));
+                }
+                else {
+                    resolveInstall();
+                }
+            });
+        });
+        validate(staging);
+        await rename(staging, destination);
+        return validate(destination);
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+/** Only operator runtime settings survive reinstall, never worker IPC identity. */
+export function isProxyServiceEnvironmentKey(name) {
+    return ((name.startsWith("OTEL_") ||
+        name.startsWith("NEUROLINK_PROXY_") ||
+        [
+            "NEUROLINK_PACKAGE_MANAGER",
+            "NEUROLINK_PACKAGE_MANAGER_PATH",
+            "NEUROLINK_PNPM_PATH",
+            "PNPM_HOME",
+        ].includes(name)) &&
+        ![
+            "NEUROLINK_PROXY_SOCKET_WORKER",
+            "NEUROLINK_PROXY_WORKER_GENERATION",
+            "NEUROLINK_PROXY_WORKER_EXPECTED_VERSION",
+            "NEUROLINK_PROXY_UPDATE_CONTROL_TOKEN",
+            "NEUROLINK_PROXY_ROLLING_SUPERVISOR",
+            "NEUROLINK_PROXY_TRAMPOLINE_EXEC_ONLY",
+            "NEUROLINK_PROXY_TEST_ISOLATED",
+        ].includes(name));
+}
+/** Parse plutil JSON without exposing credentials or invoking the saved launcher. */
+export function parseProxyServiceInstallSettings(value) {
+    const settings = { environment: {} };
+    if (!value || typeof value !== "object") {
+        return settings;
+    }
+    const plist = value;
+    const args = Array.isArray(plist.ProgramArguments)
+        ? plist.ProgramArguments
+        : [];
+    const option = (name) => {
+        const index = args.indexOf(name);
+        return index >= 0 && typeof args[index + 1] === "string"
+            ? args[index + 1]
+            : undefined;
+    };
+    settings.envFile = option("--env-file");
+    settings.configFile = option("--config");
+    settings.host = option("--host");
+    const port = Number(option("--port"));
+    if (Number.isInteger(port) && port > 0 && port <= 65535) {
+        settings.port = port;
+    }
+    if (plist.EnvironmentVariables &&
+        typeof plist.EnvironmentVariables === "object") {
+        for (const [name, entry] of Object.entries(plist.EnvironmentVariables)) {
+            if (isProxyServiceEnvironmentKey(name) && typeof entry === "string") {
+                settings.environment[name] = entry;
+            }
+        }
+    }
+    return settings;
+}
+/** Distinguish an absent launchd job from permission failures without logging plist/env data. */
+export function probeProxyLaunchdPresence(options) {
+    try {
+        (options.execFileSync ?? nodeExecFileSync)("launchctl", ["print", `gui/${options.uid}/${options.label}`], { encoding: "utf8", timeout: 5_000, stdio: ["ignore", "pipe", "pipe"] });
+        // A loaded but currently idle KeepAlive job can start immediately. It must
+        // be explicitly unloaded before regenerating its launcher and environment.
+        return "loaded";
+    }
+    catch (error) {
+        if (error &&
+            typeof error === "object" &&
+            "status" in error &&
+            error.status === 113 &&
+            "stderr" in error &&
+            /could not find service/i.test(String(error.stderr))) {
+            return "not_loaded";
+        }
+        return "unknown";
+    }
+}
+/** Read-only guard: callers must run this before every reinstall mutation. */
+export function assertProxyServiceInstallIdle(options) {
+    if (options.launchdPresence !== "not_loaded" ||
+        options.pids.some((pid) => Number.isSafeInteger(pid) &&
+            pid > 0 &&
+            options.getProcessStatus(pid) !== "not_running")) {
+        throw new Error("Proxy service is running or could still run. Reinstall was refused before changing files or processes. Use 'neurolink proxy restart' for a safe rolling replacement, or explicitly stop and unload the service before an intended reinstall.");
+    }
+}

package/dist/proxy/otelLogSink.d.ts

@@ -3,9 +3,9 @@ import type { ProxyBodyChunkEmitter, ProxyBodyDeliveryResult } from "../types/in
 /** Explicit opt-in; configuration never silently falls back to file logging. */
 export declare function isProxyOtelOnly(): boolean;
 /**
- * Own a whole capture within byte/count bounds, then pace its chunks by actual
- * export callbacks. SDK forceFlush alone does not await an automatic export
- * already in flight. Serial publication prevents bursts from dropping tails.
+ * Publish bounded captures concurrently into a shared batch queue. Transport
+ * callbacks settle each chunk once; a flush is a process fence, not a per-body
+ * network round trip. Metadata has a separate queue and transport.
  */
 export declare function publishProxyOtelBody(captureId: string, body: string, emit: ProxyBodyChunkEmitter): Promise<ProxyBodyDeliveryResult>;
 /** Initialize a log-only provider in every proxy process, including the supervisor. */