@nordbyte/nordrelay 0.5.1 → 0.5.2

package/.env.example

@@ -209,6 +209,8 @@ NORDRELAY_AUDIT_MAX_EVENTS=1000
 NORDRELAY_SESSION_LOCK_TTL_MS=1800000
 # NPM version cache TTL.
 NORDRELAY_VERSION_CACHE_TTL_MS=3600000
+# Installed agent CLI version cache TTL.
+NORDRELAY_CLI_VERSION_CACHE_TTL_MS=60000
 
 # Voice
 # Optional voice transcription settings.

package/README.md

@@ -183,9 +183,9 @@ Authentication and safety:
 Operations:
 
 - Plugin command/skill starts, stops, restarts, and inspects the connector process.
-- Manual process commands support `start`, `stop`, `restart`, `status`, and `foreground`.
+- Manual process commands support `start`, `stop`, `restart`, `status`, `update`, and `foreground`.
 - Telegram admin commands support `/logs`, `/diagnostics`, `/support`, `/restart`, and `/update` for NordRelay and agent CLIs.
-- `/update` detects the install type: npm installs update with `npm install -g @nordbyte/nordrelay@latest`; source checkouts pull `origin/main`, install dependencies, run check, tests, and build, then restart.
+- `nordrelay update`, `/update`, and the WebUI update button detect the install type: npm installs update with `npm install -g @nordbyte/nordrelay@latest`; source checkouts pull `origin/main`, install dependencies, run check, tests, and build, then restart if the connector is running.
 - `/update agents`, `/update <agent>`, `/update install <agent>`, `/update jobs`, `/update log <id>`, `/update cancel <id>`, and `/update input <id> <text>` manage Codex, Pi, Hermes, OpenClaw, and Claude Code updater or installer jobs from Telegram.
 - `/logs` renders redacted connector, NordRelay update, and agent update logs with local-time timestamps, levels, file path, last-modified time, and highlighted warnings/errors.
 - Logs can be emitted as timestamped plain text or JSON records with `CONNECTOR_LOG_FORMAT`.
@@ -199,7 +199,7 @@ Operations:
 - The WebUI exposes REST and SSE endpoints for chat streaming, sessions, settings, queue, artifacts, logs, health, diagnostics, and redacted diagnostics bundle export.
 - The dashboard can bind to `127.0.0.1` or `0.0.0.0`; user login and session cookies are mandatory in both modes.
 - Telegram can run with long polling or an HTTP webhook via `TELEGRAM_TRANSPORT=webhook`.
-- Version freshness checks are cached with `NORDRELAY_VERSION_CACHE_TTL_MS` to keep `/version` responsive.
+- Version freshness checks are cached with `NORDRELAY_VERSION_CACHE_TTL_MS`, and installed agent CLI version checks are cached with `NORDRELAY_CLI_VERSION_CACHE_TTL_MS`, to keep `/version` and adapter health responsive.
 - CI runs on Ubuntu, Windows, and macOS with typecheck, Vitest, Playwright WebUI browser tests, package dry run, npm audit, and a separate secret-scan workflow.
 - `npm run dev`, `npm run build`, `npm run check`, `npm test`, `npm run test:e2e`, `npm start`, `npm stop`, and `npm run status` are available.
 - Dockerfile and `docker-compose.yml` are included for containerized operation.
@@ -356,6 +356,7 @@ nordrelay init
 nordrelay doctor
 nordrelay start
 nordrelay status
+nordrelay update
 nordrelay restart
 nordrelay stop
 nordrelay foreground
@@ -367,6 +368,7 @@ Source checkout process commands:
 ```bash
 node plugins/nordrelay/scripts/nordrelay.mjs start
 node plugins/nordrelay/scripts/nordrelay.mjs status
+node plugins/nordrelay/scripts/nordrelay.mjs update
 node plugins/nordrelay/scripts/nordrelay.mjs restart
 node plugins/nordrelay/scripts/nordrelay.mjs stop
 node plugins/nordrelay/scripts/nordrelay.mjs foreground
@@ -737,6 +739,7 @@ Agent selection:
 - `NORDRELAY_AUDIT_MAX_EVENTS`: maximum audit events retained. Defaults to `1000`.
 - `NORDRELAY_SESSION_LOCK_TTL_MS`: session write-lock TTL. Defaults to `1800000`.
 - `NORDRELAY_VERSION_CACHE_TTL_MS`: npm version freshness cache TTL. Defaults to `3600000`; set `0` to disable.
+- `NORDRELAY_CLI_VERSION_CACHE_TTL_MS`: installed agent CLI version cache TTL. Defaults to `60000`; set `0` to disable.
 
 Dashboard:
 
@@ -837,7 +840,7 @@ NordRelay wrapper:
 
 - `NORDRELAY_HOME`: config/state/log directory override. Defaults to `~/.nordrelay`.
 - `NORDRELAY_SOURCE_ROOT`: runtime source root override. Useful when the plugin is launched from Codex cache.
-- `NORDRELAY_UPDATE_METHOD`: optional `auto`, `npm`, or `git` self-update method override. Auto uses git when the runtime root has a `.git` directory and npm otherwise.
+- `NORDRELAY_UPDATE_METHOD`: optional `auto`, `npm`, or `git` self-update method override used by `nordrelay update`, `/update`, and the WebUI update button. Auto uses git when the runtime root has a `.git` directory and npm otherwise.
 - Agent updates from the dashboard and Telegram use each agent's native updater where possible: `codex update`, `pi update pi`, `hermes update --yes`, `openclaw update --yes`, and `claude update`. Not-installed agents can be installed from the dashboard or with `/update install <agent>` using npm global installs.
 - `NORDRELAY_KEEP_PENDING_UPDATES`: set true to avoid dropping pending Telegram updates on start.
 - `NORDRELAY_FORWARD_TOOL_OUTPUT`: backward-compatible alias that sets `TOOL_VERBOSITY=all` when `TOOL_VERBOSITY` is unset.

package/dist/agent-updates.js

@@ -105,10 +105,11 @@ export class AgentUpdateManager {
             `Working directory: ${job.cwd}`,
             "",
         ].join("\n"));
-        const child = spawn(plan.command, plan.args, {
+        const useShell = process.platform === "win32";
+        const child = spawn(useShell ? formatShellCommand(plan.command, plan.args) : plan.command, useShell ? [] : plan.args, {
             cwd: plan.cwd,
             env: { ...process.env, ...(this.options.env ?? {}), ...(context.env ?? {}) },
-            shell: process.platform === "win32",
+            shell: useShell,
             windowsHide: true,
             stdio: "pipe",
         });
@@ -342,6 +343,21 @@ function looksLikePrompt(text) {
     const tail = text.split(/\r?\n/).slice(-4).join("\n");
     return /\b(y\/n|yes\/no|continue|proceed|confirm|password|passphrase|token|api key|enter|select)\b|[?>]\s*$/i.test(tail);
 }
+function formatShellCommand(command, args) {
+    return [command, ...args].map(quoteWindowsCmdArg).join(" ");
+}
+function quoteWindowsCmdArg(value) {
+    if (value.length === 0) {
+        return "\"\"";
+    }
+    if (!/[\s"&|<>()^%]/.test(value)) {
+        return value;
+    }
+    return `"${value
+        .replace(/%/g, "%%")
+        .replace(/(\\*)"/g, '$1$1\\"')
+        .replace(/(\\+)$/g, "$1$1")}"`;
+}
 function capitalize(value) {
     return value.charAt(0).toUpperCase() + value.slice(1);
 }

package/dist/bot.js

@@ -453,6 +453,30 @@ export function createBot(config, registry) {
             await drainQueuedPrompts(createSystemContext(contextKey), contextKey, parsed.chatId, session);
         }
     };
+    const sendExternalMirrorTyping = async (chatId, messageThreadId, state) => {
+        const now = Date.now();
+        if (state.lastTypingAt && now - state.lastTypingAt < TYPING_INTERVAL_MS) {
+            return;
+        }
+        state.lastTypingAt = now;
+        await sendChatActionSafe(bot.api, chatId, "typing", messageThreadId).catch(() => { });
+    };
+    const sendExternalWorkingNotice = async (chatId, messageThreadId, state, snapshot) => {
+        const turnKey = snapshot.activity.turnId ?? snapshot.activity.startedAt?.toISOString() ?? "unknown";
+        if (state.workingNoticeTurnKey === turnKey) {
+            return;
+        }
+        const prompt = trimLine(snapshot.latestUserMessage ?? "", 250);
+        const fallbackText = prompt ? `Working on ${prompt}` : `Working on external ${snapshot.agentLabel} task...`;
+        const html = prompt
+            ? `<b>Working on</b> ${escapeHTML(prompt)}`
+            : `<b>Working on</b> external ${escapeHTML(snapshot.agentLabel)} task...`;
+        await sendTextMessage(bot.api, chatId, html, {
+            fallbackText,
+            messageThreadId,
+        });
+        state.workingNoticeTurnKey = turnKey;
+    };
     const mirrorExternalSnapshot = async (contextKey, chatId, session, snapshot) => {
         const parsed = parseContextKey(contextKey);
         const previous = externalMirrors.get(contextKey);
@@ -471,7 +495,15 @@ export function createBot(config, registry) {
         if (snapshot.activity.active) {
             state.turnId = snapshot.activity.turnId;
             state.startedAt = snapshot.activity.startedAt;
-            if (mirrorMode === "off" || mirrorMode === "final") {
+            if (mirrorMode !== "off") {
+                await sendExternalMirrorTyping(chatId, parsed.messageThreadId, state);
+            }
+            if (mirrorMode === "final") {
+                await sendExternalWorkingNotice(chatId, parsed.messageThreadId, state, snapshot);
+                state.lastLine = Math.max(state.lastLine, snapshot.lineCount);
+                return;
+            }
+            if (mirrorMode === "off") {
                 state.lastLine = Math.max(state.lastLine, snapshot.lineCount);
                 return;
             }
@@ -510,7 +542,6 @@ export function createBot(config, registry) {
                     state.latestMirroredEventLine = event.lineNumber;
                 }
             }
-            await sendChatActionSafe(bot.api, chatId, "typing", parsed.messageThreadId).catch(() => { });
             state.lastLine = Math.max(state.lastLine, snapshot.lineCount);
             return;
         }
@@ -551,6 +582,7 @@ export function createBot(config, registry) {
             }
             await deliverCliGeneratedArtifacts(contextKey, chatId, session, state.startedAt, terminalEvent.turnId, parsed.messageThreadId);
         }
+        state.workingNoticeTurnKey = undefined;
         state.lastLine = Math.max(state.lastLine, snapshot.lineCount);
     };
     const canSendSystemMessagesToContext = (contextKey) => {

package/dist/codex-cli.js

@@ -26,7 +26,7 @@ export function findExecutableOnPath(command, pathValue) {
         return undefined;
     }
     const extensions = process.platform === "win32"
-        ? (process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";")
+        ? ["", ...(process.env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";")]
         : [""];
     for (const rawDirectory of pathValue.split(path.delimiter)) {
         const directory = rawDirectory.trim();

package/dist/config-metadata.js

@@ -88,6 +88,7 @@ export const SETTING_DEFINITIONS = [
     setting("NORDRELAY_AUDIT_MAX_EVENTS", "Audit max events", "Workspace", "number", "Retained audit events.", true),
     setting("NORDRELAY_SESSION_LOCK_TTL_MS", "Session lock TTL", "Workspace", "number", "Write-lock TTL.", true),
     setting("NORDRELAY_VERSION_CACHE_TTL_MS", "Version cache TTL", "Workspace", "number", "NPM version cache TTL.", true),
+    setting("NORDRELAY_CLI_VERSION_CACHE_TTL_MS", "CLI version cache TTL", "Workspace", "number", "Installed agent CLI version cache TTL.", true),
     setting("OPENAI_API_KEY", "OpenAI API key", "Voice", "secret", "Whisper fallback API key.", true),
     setting("VOICE_PREFERRED_BACKEND", "Voice backend", "Voice", "string", "auto, parakeet, faster-whisper, or openai.", false, ["auto", "parakeet", "faster-whisper", "openai"]),
     setting("VOICE_DEFAULT_LANGUAGE", "Voice language", "Voice", "string", "Default transcription language.", false),
@@ -180,6 +181,7 @@ const EXAMPLE_VALUES = {
     "NORDRELAY_AUDIT_MAX_EVENTS": "1000",
     "NORDRELAY_SESSION_LOCK_TTL_MS": "1800000",
     "NORDRELAY_VERSION_CACHE_TTL_MS": "3600000",
+    "NORDRELAY_CLI_VERSION_CACHE_TTL_MS": "60000",
     "NORDRELAY_DASHBOARD_HOST": "127.0.0.1",
     "NORDRELAY_DASHBOARD_PORT": "31878",
     "NORDRELAY_ENV_FILE": "",

package/dist/operations.js

@@ -1,5 +1,5 @@
-import { spawn, spawnSync } from "node:child_process";
-import { closeSync, existsSync, mkdirSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { execFile, spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
@@ -21,6 +21,8 @@ const CLAUDE_CODE_SDK_PACKAGE_NAME = "@anthropic-ai/claude-agent-sdk";
 const DEFAULT_HOME = path.join(os.homedir(), ".nordrelay");
 const SECRET_RE = /(bot|token|api[_-]?key|authorization|bearer|password|secret)(["'=: ]+)([^\s"',]+)/gi;
 const DEFAULT_VERSION_CACHE_TTL_MS = 60 * 60 * 1000;
+const DEFAULT_CLI_VERSION_CACHE_TTL_MS = 60 * 1000;
+const cliVersionCache = new Map();
 export function getConnectorHome() {
     return process.env.NORDRELAY_HOME || DEFAULT_HOME;
 }
@@ -96,97 +98,86 @@ export async function getPackageVersion() {
     }
 }
 export async function getVersionChecks(options = {}) {
-    const nordrelayVersion = await getPackageVersion();
-    const codexCli = resolveCodexCli();
-    const piCli = resolvePiCli(process.env, options.piCliPath);
-    const hermesCli = resolveHermesCli(process.env, options.hermesCliPath);
-    const openClawCli = resolveOpenClawCli(process.env, options.openClawCliPath);
-    const claudeCodeCli = resolveClaudeCodeCli(process.env, options.claudeCodeCliPath);
-    const codexVersionLabel = codexCli.path
-        ? detectCliVersion(codexCli.path)
-        : readInstalledPackageVersion(CODEX_PACKAGE_NAME) ?? "not installed";
-    const piVersionLabel = piCli.path
-        ? detectCliVersion(piCli.path)
-        : readInstalledPackageVersion(PI_PACKAGE_NAME) ?? readInstalledPackageVersion(LEGACY_PI_PACKAGE_NAME) ?? "not installed";
-    const legacyPiPackageVersion = readInstalledPackageVersion(LEGACY_PI_PACKAGE_NAME);
-    const hermesVersionLabel = hermesCli.path ? detectCliVersion(hermesCli.path) : "not installed";
-    const openClawVersionLabel = openClawCli.path ? detectCliVersion(openClawCli.path) : "not installed";
-    const claudeCodeVersionLabel = claudeCodeCli.path
-        ? detectCliVersion(claudeCodeCli.path)
-        : readInstalledPackageVersion(CLAUDE_CODE_SDK_PACKAGE_NAME) ?? "bundled";
-    const claudeCodePackageName = claudeCodeCli.path ? CLAUDE_CODE_PACKAGE_NAME : CLAUDE_CODE_SDK_PACKAGE_NAME;
-    return {
-        nordrelay: buildVersionCheck({
+    const [nordrelayVersion, cliVersions] = await Promise.all([
+        getPackageVersion(),
+        resolveAgentCliVersions(options),
+    ]);
+    const [nordrelay, codex, pi, hermes, openclaw, claudeCode,] = await Promise.all([
+        buildVersionCheck({
             label: "NordRelay",
             packageName: PACKAGE_NAME,
             installedLabel: nordrelayVersion,
             installedVersion: extractVersion(nordrelayVersion),
         }),
-        codex: buildVersionCheck({
+        buildVersionCheck({
             label: "Codex",
             packageName: CODEX_PACKAGE_NAME,
-            installedLabel: codexVersionLabel,
-            installedVersion: extractVersion(codexVersionLabel),
-            notInstalled: codexVersionLabel === "not installed",
+            installedLabel: cliVersions.codexVersionLabel,
+            installedVersion: extractVersion(cliVersions.codexVersionLabel),
+            notInstalled: cliVersions.codexVersionLabel === "not installed",
         }),
-        pi: buildVersionCheck({
+        buildVersionCheck({
             label: "Pi",
             packageName: PI_PACKAGE_NAME,
-            installedLabel: piVersionLabel,
-            installedVersion: extractVersion(piVersionLabel),
-            notInstalled: piVersionLabel === "not installed",
-            detail: legacyPiPackageVersion ? `Legacy package ${LEGACY_PI_PACKAGE_NAME} is present; current package is ${PI_PACKAGE_NAME}.` : undefined,
+            installedLabel: cliVersions.piVersionLabel,
+            installedVersion: extractVersion(cliVersions.piVersionLabel),
+            notInstalled: cliVersions.piVersionLabel === "not installed",
+            detail: cliVersions.legacyPiPackageVersion ? `Legacy package ${LEGACY_PI_PACKAGE_NAME} is present; current package is ${PI_PACKAGE_NAME}.` : undefined,
         }),
-        hermes: buildHermesVersionCheck(hermesVersionLabel),
-        openclaw: buildVersionCheck({
+        buildHermesVersionCheck(cliVersions.hermesVersionLabel),
+        buildVersionCheck({
             label: "OpenClaw",
             packageName: OPENCLAW_PACKAGE_NAME,
-            installedLabel: openClawVersionLabel,
-            installedVersion: extractVersion(openClawVersionLabel),
-            notInstalled: openClawVersionLabel === "not installed",
+            installedLabel: cliVersions.openClawVersionLabel,
+            installedVersion: extractVersion(cliVersions.openClawVersionLabel),
+            notInstalled: cliVersions.openClawVersionLabel === "not installed",
         }),
-        claudeCode: buildVersionCheck({
+        buildVersionCheck({
             label: "Claude Code",
-            packageName: claudeCodePackageName,
-            installedLabel: claudeCodeVersionLabel,
-            installedVersion: extractVersion(claudeCodeVersionLabel),
-            notInstalled: claudeCodeVersionLabel === "not installed",
+            packageName: cliVersions.claudeCodePackageName,
+            installedLabel: cliVersions.claudeCodeVersionLabel,
+            installedVersion: extractVersion(cliVersions.claudeCodeVersionLabel),
+            notInstalled: cliVersions.claudeCodeVersionLabel === "not installed",
         }),
+    ]);
+    return {
+        nordrelay,
+        codex,
+        pi,
+        hermes,
+        openclaw,
+        claudeCode,
     };
 }
 export async function getConnectorHealth(options = {}) {
-    const rawState = await readConnectorState();
-    const version = await getPackageVersion();
+    const [rawState, version, cliVersions] = await Promise.all([
+        readConnectorState(),
+        getPackageVersion(),
+        resolveAgentCliVersions(options),
+    ]);
     const pidRunning = isProcessRunning(rawState.pid);
     const appPidRunning = isProcessRunning(rawState.appPid);
     const state = normalizeConnectorState(rawState, pidRunning, appPidRunning);
-    const codexCli = resolveCodexCli();
-    const piCli = resolvePiCli(process.env, options.piCliPath);
-    const hermesCli = resolveHermesCli(process.env, options.hermesCliPath);
-    const openClawCli = resolveOpenClawCli(process.env, options.openClawCliPath);
-    const claudeCodeCli = resolveClaudeCodeCli(process.env, options.claudeCodeCliPath);
     return {
         version,
         state,
         pidRunning,
         appPidRunning,
-        codexCli: describeCodexCli(codexCli),
-        codexCliPath: codexCli.path ?? null,
-        codexCliVersion: detectCliVersion(codexCli.path),
-        piCli: describePiCli(piCli),
-        piCliPath: piCli.path ?? null,
-        piCliVersion: detectCliVersion(piCli.path),
-        hermesCli: describeHermesCli(hermesCli),
-        hermesCliPath: hermesCli.path ?? null,
-        hermesCliVersion: detectCliVersion(hermesCli.path),
-        openClawCli: describeOpenClawCli(openClawCli),
-        openClawCliPath: openClawCli.path ?? null,
-        openClawCliVersion: detectCliVersion(openClawCli.path),
-        claudeCodeCli: describeClaudeCodeCli(claudeCodeCli),
-        claudeCodeCliPath: claudeCodeCli.path ?? null,
-        claudeCodeCliVersion: claudeCodeCli.path
-            ? detectCliVersion(claudeCodeCli.path)
-            : readInstalledPackageVersion(CLAUDE_CODE_SDK_PACKAGE_NAME) ?? "bundled",
+        codexCli: describeCodexCli(cliVersions.codexCli),
+        codexCliPath: cliVersions.codexCli.path ?? null,
+        codexCliVersion: cliVersions.codexVersionLabel,
+        piCli: describePiCli(cliVersions.piCli),
+        piCliPath: cliVersions.piCli.path ?? null,
+        piCliVersion: cliVersions.piVersionLabel,
+        hermesCli: describeHermesCli(cliVersions.hermesCli),
+        hermesCliPath: cliVersions.hermesCli.path ?? null,
+        hermesCliVersion: cliVersions.hermesVersionLabel,
+        openClawCli: describeOpenClawCli(cliVersions.openClawCli),
+        openClawCliPath: cliVersions.openClawCli.path ?? null,
+        openClawCliVersion: cliVersions.openClawVersionLabel,
+        claudeCodeCli: describeClaudeCodeCli(cliVersions.claudeCodeCli),
+        claudeCodeCliPath: cliVersions.claudeCodeCli.path ?? null,
+        claudeCodeCliVersion: cliVersions.claudeCodeVersionLabel,
         stateFile: getConnectorStatePath(),
         logFile: getConnectorLogPath(),
         databasePath: findLatestDatabase(),
@@ -208,23 +199,22 @@ export function spawnSelfUpdate() {
     const script = getWrapperScriptPath();
     const updateLog = getUpdateLogPath();
     const method = detectSelfUpdateMethod(sourceRoot);
-    const commands = method === "npm"
-        ? buildNpmSelfUpdateCommands()
-        : buildGitSelfUpdateCommands(script);
-    const logFd = openSync(updateLog, "a");
-    const command = [
-        "set -e",
-        `printf '\\n[%s] Starting ${method} connector self-update\\n' "$(date -Is)"`,
-        ...commands,
-    ].join(" && ");
-    const child = spawn("sh", ["-lc", command], {
+    mkdirSync(path.dirname(updateLog), { recursive: true });
+    const child = spawn(process.execPath, [
+        script,
+        "update",
+        "--method",
+        method,
+        "--home",
+        getConnectorHome(),
+        "--keep-pending-updates",
+    ], {
         cwd: sourceRoot,
         detached: true,
         env: process.env,
-        stdio: ["ignore", logFd, logFd],
+        stdio: "ignore",
     });
     child.unref();
-    closeSync(logFd);
     return {
         logPath: updateLog,
         method,
@@ -274,41 +264,62 @@ function normalizeConnectorState(state, pidRunning, appPidRunning) {
 function redactSecrets(text) {
     return text.replace(SECRET_RE, "$1$2[redacted]");
 }
-function buildGitSelfUpdateCommands(script) {
-    return [
-        "git pull --ff-only origin main",
-        "npm install",
-        "npm run check",
-        "npm test",
-        "npm run build",
-        `printf '[%s] Checks passed; restarting connector\\n' "$(date -Is)"`,
-        `${shellQuote(process.execPath)} ${shellQuote(script)} restart --keep-pending-updates`,
-    ];
-}
-function buildNpmSelfUpdateCommands() {
-    return [
-        `${resolveNpmCommand()} install -g ${PACKAGE_NAME}@latest`,
-        "nordrelay version",
-        `printf '[%s] npm update finished; restarting connector\\n' "$(date -Is)"`,
-        "nordrelay restart --keep-pending-updates",
-    ];
-}
-function resolveNpmCommand() {
-    const npm = resolveNpmSpawnCommand();
-    if (npm) {
-        return [npm.command, ...npm.argsPrefix].map(shellQuote).join(" ");
-    }
-    return "npm";
+async function resolveAgentCliVersions(options = {}) {
+    const codexCli = resolveCodexCli();
+    const piCli = resolvePiCli(process.env, options.piCliPath);
+    const hermesCli = resolveHermesCli(process.env, options.hermesCliPath);
+    const openClawCli = resolveOpenClawCli(process.env, options.openClawCliPath);
+    const claudeCodeCli = resolveClaudeCodeCli(process.env, options.claudeCodeCliPath);
+    const legacyPiPackageVersion = readInstalledPackageVersion(LEGACY_PI_PACKAGE_NAME);
+    const [codexVersionLabel, piVersionLabel, hermesVersionLabel, openClawVersionLabel, claudeCodeVersionLabel,] = await Promise.all([
+        codexCli.path ? detectCliVersion(codexCli.path) : Promise.resolve(readInstalledPackageVersion(CODEX_PACKAGE_NAME) ?? "not installed"),
+        piCli.path ? detectCliVersion(piCli.path) : Promise.resolve(readInstalledPackageVersion(PI_PACKAGE_NAME) ?? legacyPiPackageVersion ?? "not installed"),
+        hermesCli.path ? detectCliVersion(hermesCli.path) : Promise.resolve("not installed"),
+        openClawCli.path ? detectCliVersion(openClawCli.path) : Promise.resolve("not installed"),
+        claudeCodeCli.path ? detectCliVersion(claudeCodeCli.path) : Promise.resolve(readInstalledPackageVersion(CLAUDE_CODE_SDK_PACKAGE_NAME) ?? "bundled"),
+    ]);
+    return {
+        codexCli,
+        piCli,
+        hermesCli,
+        openClawCli,
+        claudeCodeCli,
+        codexVersionLabel,
+        piVersionLabel,
+        hermesVersionLabel,
+        openClawVersionLabel,
+        claudeCodeVersionLabel,
+        claudeCodePackageName: claudeCodeCli.path ? CLAUDE_CODE_PACKAGE_NAME : CLAUDE_CODE_SDK_PACKAGE_NAME,
+        legacyPiPackageVersion,
+    };
 }
-function detectCliVersion(commandPath) {
+async function detectCliVersion(commandPath) {
     if (!commandPath) {
         return "not installed";
     }
-    const result = spawnSync(commandPath, ["--version"], {
-        encoding: "utf8",
+    const ttlMs = parseCliVersionCacheTtlMs();
+    if (ttlMs > 0) {
+        const cached = cliVersionCache.get(commandPath);
+        if (cached && Date.now() < cached.expiresAt) {
+            if (cached.value !== undefined) {
+                return cached.value;
+            }
+            if (cached.promise) {
+                return cached.promise;
+            }
+        }
+        const promise = detectCliVersionUncached(commandPath);
+        cliVersionCache.set(commandPath, { promise, expiresAt: Date.now() + ttlMs });
+        const value = await promise;
+        cliVersionCache.set(commandPath, { value, expiresAt: Date.now() + ttlMs });
+        return value;
+    }
+    return detectCliVersionUncached(commandPath);
+}
+async function detectCliVersionUncached(commandPath) {
+    const result = await runCommand(commandPath, ["--version"], {
         shell: isWindowsShellScript(commandPath),
         timeout: 3000,
-        windowsHide: true,
     });
     const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
     if (result.error) {
@@ -319,9 +330,9 @@ function detectCliVersion(commandPath) {
     }
     return output || "unknown";
 }
-function buildHermesVersionCheck(installedLabel) {
+async function buildHermesVersionCheck(installedLabel) {
     if (installedLabel === "not installed") {
-        const latest = detectLatestNpmVersion(HERMES_PACKAGE_NAME);
+        const latest = await detectLatestNpmVersion(HERMES_PACKAGE_NAME);
         return {
             label: "Hermes",
             packageName: HERMES_PACKAGE_NAME,
@@ -346,9 +357,9 @@ function buildHermesVersionCheck(installedLabel) {
         detail: updateLine ?? (installedVersion ? undefined : "Could not parse Hermes version or update status"),
     };
 }
-function buildVersionCheck(options) {
+async function buildVersionCheck(options) {
     if (options.notInstalled) {
-        const latest = options.skipLatest ? { version: null, error: undefined } : detectLatestNpmVersion(options.packageName);
+        const latest = options.skipLatest ? { version: null, error: undefined } : await detectLatestNpmVersion(options.packageName);
         return {
             label: options.label,
             packageName: options.packageName,
@@ -370,7 +381,7 @@ function buildVersionCheck(options) {
             detail: options.detail ?? "Latest-version lookup is not available for this package source",
         };
     }
-    const latest = detectLatestNpmVersion(options.packageName);
+    const latest = await detectLatestNpmVersion(options.packageName);
     if (!options.installedVersion || !latest.version) {
         return {
             label: options.label,
@@ -392,7 +403,7 @@ function buildVersionCheck(options) {
         detail: [options.detail, latest.error].filter(Boolean).join(" ") || undefined,
     };
 }
-function detectLatestNpmVersion(packageName) {
+async function detectLatestNpmVersion(packageName) {
     const cached = readVersionCache(packageName);
     if (cached) {
         return cached;
@@ -401,11 +412,9 @@ function detectLatestNpmVersion(packageName) {
     if (!npm) {
         return { version: null, error: "npm was not found on PATH; latest-version lookup is unavailable" };
     }
-    const result = spawnSync(npm.command, [...npm.argsPrefix, "view", packageName, "version", "--registry=https://registry.npmjs.org"], {
-        encoding: "utf8",
+    const result = await runCommand(npm.command, [...npm.argsPrefix, "view", packageName, "version", "--registry=https://registry.npmjs.org"], {
         shell: npm.shell,
         timeout: 5000,
-        windowsHide: true,
     });
     const output = [result.stdout, result.stderr].filter(Boolean).join("\n").trim();
     if (result.error) {
@@ -418,6 +427,49 @@ function detectLatestNpmVersion(packageName) {
     writeVersionCache(packageName, resolved.version);
     return resolved;
 }
+function runCommand(command, args, options) {
+    return new Promise((resolve) => {
+        const useShell = Boolean(options.shell);
+        execFile(useShell ? formatShellCommand(command, args) : command, useShell ? [] : args, {
+            encoding: "utf8",
+            shell: useShell,
+            timeout: options.timeout,
+            windowsHide: true,
+            env: process.env,
+            maxBuffer: 1024 * 1024,
+        }, (error, stdout, stderr) => {
+            const enriched = error;
+            resolve({
+                stdout: typeof stdout === "string" ? stdout : "",
+                stderr: typeof stderr === "string" ? stderr : "",
+                status: typeof enriched?.code === "number" ? enriched.code : error ? 1 : 0,
+                signal: enriched?.signal,
+                error: enriched ?? undefined,
+            });
+        });
+    });
+}
+function formatShellCommand(command, args) {
+    return [command, ...args].map(quoteShellArg).join(" ");
+}
+function quoteShellArg(value) {
+    if (process.platform === "win32") {
+        return quoteWindowsCmdArg(value);
+    }
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function quoteWindowsCmdArg(value) {
+    if (value.length === 0) {
+        return "\"\"";
+    }
+    if (!/[\s"&|<>()^%]/.test(value)) {
+        return value;
+    }
+    return `"${value
+        .replace(/%/g, "%%")
+        .replace(/(\\*)"/g, '$1$1\\"')
+        .replace(/(\\+)$/g, "$1$1")}"`;
+}
 export function resolveNpmSpawnCommand(env = process.env) {
     const npmExecPath = env.npm_execpath?.trim();
     if (npmExecPath && existsSync(npmExecPath)) {
@@ -512,6 +564,14 @@ function parseVersionCacheTtlMs() {
     const parsed = Number(raw);
     return Number.isFinite(parsed) ? Math.max(0, Math.floor(parsed)) : DEFAULT_VERSION_CACHE_TTL_MS;
 }
+function parseCliVersionCacheTtlMs() {
+    const raw = process.env.NORDRELAY_CLI_VERSION_CACHE_TTL_MS;
+    if (!raw) {
+        return DEFAULT_CLI_VERSION_CACHE_TTL_MS;
+    }
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? Math.max(0, Math.floor(parsed)) : DEFAULT_CLI_VERSION_CACHE_TTL_MS;
+}
 function readInstalledPackageVersion(packageName) {
     try {
         const packagePath = path.join(getSourceRoot(), "node_modules", ...packageName.split("/"), "package.json");
@@ -543,9 +603,6 @@ function compareVersions(left, right) {
 function parseVersionParts(value) {
     return value.split(/[.-]/).slice(0, 3).map((part) => Number.parseInt(part, 10) || 0);
 }
-function shellQuote(value) {
-    return `'${value.replace(/'/g, `'\\''`)}'`;
-}
 function formatLogLine(line) {
     const trimmed = line.trim();
     if (!trimmed) {

package/dist/relay-runtime.js

@@ -105,10 +105,16 @@ export class RelayRuntime {
         };
     }
     async status() {
+        const cliOptions = this.cliPathOptions();
+        const [health, versionChecks, snapshot] = await Promise.all([
+            getConnectorHealth(cliOptions),
+            getVersionChecks(cliOptions),
+            this.snapshot(),
+        ]);
         return {
-            health: await getConnectorHealth({ piCliPath: this.config.piCliPath, hermesCliPath: this.config.hermesCliPath, openClawCliPath: this.config.openClawCliPath, claudeCodeCliPath: this.config.claudeCodeCliPath }),
-            versionChecks: await getVersionChecks({ piCliPath: this.config.piCliPath, hermesCliPath: this.config.hermesCliPath, openClawCliPath: this.config.openClawCliPath, claudeCodeCliPath: this.config.claudeCodeCliPath }),
-            snapshot: await this.snapshot(),
+            health,
+            versionChecks,
+            snapshot,
         };
     }
     async bootstrapStatus() {
@@ -121,10 +127,16 @@ export class RelayRuntime {
         };
     }
     async version() {
+        const cliOptions = this.cliPathOptions();
+        const [health, state, versionChecks] = await Promise.all([
+            getConnectorHealth(cliOptions),
+            readConnectorState(),
+            getVersionChecks(cliOptions),
+        ]);
         return {
-            health: await getConnectorHealth({ piCliPath: this.config.piCliPath, hermesCliPath: this.config.hermesCliPath, openClawCliPath: this.config.openClawCliPath, claudeCodeCliPath: this.config.claudeCodeCliPath }),
-            state: await readConnectorState(),
-            versionChecks: await getVersionChecks({ piCliPath: this.config.piCliPath, hermesCliPath: this.config.hermesCliPath, openClawCliPath: this.config.openClawCliPath, claudeCodeCliPath: this.config.claudeCodeCliPath }),
+            health,
+            state,
+            versionChecks,
         };
     }
     updateConnector() {
@@ -199,22 +211,32 @@ export class RelayRuntime {
         return this.agentUpdates.cancel(id);
     }
     async diagnostics() {
+        const cliOptions = this.cliPathOptions();
+        const [health, versionChecks, snapshot, session] = await Promise.all([
+            getConnectorHealth(cliOptions),
+            getVersionChecks(cliOptions),
+            this.snapshot(),
+            this.getSession(true),
+        ]);
         return {
-            health: await getConnectorHealth({ piCliPath: this.config.piCliPath, hermesCliPath: this.config.hermesCliPath, openClawCliPath: this.config.openClawCliPath, claudeCodeCliPath: this.config.claudeCodeCliPath }),
-            versionChecks: await getVersionChecks({ piCliPath: this.config.piCliPath, hermesCliPath: this.config.hermesCliPath, openClawCliPath: this.config.openClawCliPath, claudeCodeCliPath: this.config.claudeCodeCliPath }),
-            snapshot: await this.snapshot(),
+            health,
+            versionChecks,
+            snapshot,
             runtime: {
                 stateBackend: this.config.stateBackend,
                 sourceWorkspace: this.config.workspace,
                 queuePaused: this.queueService.isPaused(),
                 externalMirror: this.externalActivityMonitor.snapshot(),
-                agentDiagnostics: getAgentDiagnostics(await this.getSession(true), this.config),
+                agentDiagnostics: getAgentDiagnostics(session, this.config),
             },
         };
     }
     async adapterHealth() {
-        const health = await getConnectorHealth({ piCliPath: this.config.piCliPath, hermesCliPath: this.config.hermesCliPath, openClawCliPath: this.config.openClawCliPath, claudeCodeCliPath: this.config.claudeCodeCliPath });
-        const versions = await getVersionChecks({ piCliPath: this.config.piCliPath, hermesCliPath: this.config.hermesCliPath, openClawCliPath: this.config.openClawCliPath, claudeCodeCliPath: this.config.claudeCodeCliPath });
+        const cliOptions = this.cliPathOptions();
+        const [health, versions] = await Promise.all([
+            getConnectorHealth(cliOptions),
+            getVersionChecks(cliOptions),
+        ]);
         return Promise.all(listAgentAdapterDescriptors().map(async (descriptor) => {
             const enabled = enabledAgents(this.config).includes(descriptor.id);
             const auth = descriptor.capabilities.auth && enabled
@@ -945,6 +967,14 @@ export class RelayRuntime {
         });
         return { session, dispose: true };
     }
+    cliPathOptions() {
+        return {
+            piCliPath: this.config.piCliPath,
+            hermesCliPath: this.config.hermesCliPath,
+            openClawCliPath: this.config.openClawCliPath,
+            claudeCodeCliPath: this.config.claudeCodeCliPath,
+        };
+    }
     async ensureActiveThread(session) {
         if (!session.hasActiveThread()) {
             await session.newThread();

package/dist/state-backend.js

@@ -79,5 +79,8 @@ function tryCreateSqliteDocumentStore(options) {
                 "ON CONFLICT(key) DO UPDATE SET json = excluded.json, updated_at = excluded.updated_at",
             ].join(" ")).run(options.sqliteKey, JSON.stringify(value), new Date().toISOString());
         },
+        close() {
+            db.close();
+        },
     };
 }

package/dist/support-bundle.js

@@ -178,7 +178,8 @@ function systemInfo() {
     };
 }
 function detectNpmVersion(npm) {
-    const result = spawnSync(npm.command, [...npm.argsPrefix, "--version"], {
+    const args = [...npm.argsPrefix, "--version"];
+    const result = spawnSync(npm.shell ? formatShellCommand(npm.command, args) : npm.command, npm.shell ? [] : args, {
         encoding: "utf8",
         shell: npm.shell,
         timeout: 3000,
@@ -189,6 +190,21 @@ function detectNpmVersion(npm) {
     }
     return String(result.stdout || "").trim() || null;
 }
+function formatShellCommand(command, args) {
+    return [command, ...args].map(quoteWindowsCmdArg).join(" ");
+}
+function quoteWindowsCmdArg(value) {
+    if (value.length === 0) {
+        return "\"\"";
+    }
+    if (!/[\s"&|<>()^%]/.test(value)) {
+        return value;
+    }
+    return `"${value
+        .replace(/%/g, "%%")
+        .replace(/(\\*)"/g, '$1$1\\"')
+        .replace(/(\\+)$/g, "$1$1")}"`;
+}
 function formatTimestamp(date) {
     return [
         date.getFullYear(),

package/dist/web-dashboard.js

@@ -584,6 +584,7 @@ function activeSettingsValues(current) {
         NORDRELAY_AUDIT_MAX_EVENTS: String(current.auditMaxEvents),
         NORDRELAY_SESSION_LOCK_TTL_MS: String(current.sessionLockTtlMs),
         NORDRELAY_VERSION_CACHE_TTL_MS: process.env.NORDRELAY_VERSION_CACHE_TTL_MS,
+        NORDRELAY_CLI_VERSION_CACHE_TTL_MS: process.env.NORDRELAY_CLI_VERSION_CACHE_TTL_MS,
         VOICE_PREFERRED_BACKEND: current.voicePreferredBackend,
         VOICE_DEFAULT_LANGUAGE: current.voiceDefaultLanguage,
         VOICE_TRANSCRIBE_ONLY: boolValue(current.voiceTranscribeOnly),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nordbyte/nordrelay",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Remote control plane for coding agents across messaging channels.",
   "type": "module",
   "author": "Ricardo",

package/plugins/nordrelay/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "nordrelay",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Run a remote-control bridge for coding agents. Current adapters connect Codex, Pi, Hermes, and OpenClaw sessions to Telegram with streaming replies, multi-session controls, attachments, voice input, model selection, thread browsing, and handback.",
   "author": {
     "name": "Ricardo",

package/plugins/nordrelay/scripts/nordrelay.mjs

@@ -51,6 +51,8 @@ function parseArgs(argv) {
     force: false,
     host: undefined,
     port: undefined,
+    restartAfterUpdate: true,
+    updateMethod: undefined,
   };
 
   for (let i = 0; i < copy.length; i += 1) {
@@ -60,6 +62,9 @@ function parseArgs(argv) {
     else if (arg === "--force") options.force = true;
     else if (arg === "--host") options.host = requireValue(copy, ++i, arg);
     else if (arg === "--port") options.port = Number.parseInt(requireValue(copy, ++i, arg), 10);
+    else if (arg === "--method") options.updateMethod = requireValue(copy, ++i, arg);
+    else if (arg === "--no-restart") options.restartAfterUpdate = false;
+    else if (arg === "--restart") options.restartAfterUpdate = true;
     else if (arg === "--token") options.telegramBotToken = requireValue(copy, ++i, arg);
     else if (arg === "--admin-email") options.adminEmail = requireValue(copy, ++i, arg);
     else if (arg === "--admin-name") options.adminName = requireValue(copy, ++i, arg);
@@ -326,6 +331,244 @@ async function commandStatus(options) {
   if (state.error) console.log(`Error: ${state.error}`);
 }
 
+async function commandUpdate(options) {
+  await mkdirp(options.home);
+  loadEnvFiles(options.home);
+  const method = resolveUpdateMethod(options);
+  const updateLog = path.join(options.home, "update.log");
+  await mkdirp(path.dirname(updateLog));
+  const log = fs.createWriteStream(updateLog, { flags: "a" });
+  const sourceRoot = RUNTIME_ROOT;
+  const wasRunning = isProcessRunning(await readPid(options.pidFile));
+  const summary = method === "npm"
+    ? "Install latest @nordbyte/nordrelay with npm, verify the CLI, and restart if the connector is running."
+    : "Pull origin/main, install dependencies, run check, tests, build, and restart if the connector is running.";
+
+  console.log(`Starting NordRelay update (${method}).`);
+  console.log(`Source: ${sourceRoot}`);
+  console.log(`Log: ${updateLog}`);
+  logUpdateLine(log, `Starting ${method} connector self-update`);
+  logUpdateLine(log, summary);
+
+  try {
+    if (method === "npm") {
+      await runNpmSelfUpdate(sourceRoot, log);
+    } else {
+      await runGitSelfUpdate(sourceRoot, log);
+    }
+
+    if (options.restartAfterUpdate && wasRunning) {
+      await runLoggedStep(log, "Restart NordRelay connector", process.execPath, [
+        SCRIPT_PATH,
+        "restart",
+        "--keep-pending-updates",
+        "--home",
+        options.home,
+      ], { cwd: sourceRoot });
+    } else if (options.restartAfterUpdate) {
+      logUpdateLine(log, "Connector was not running; restart skipped.");
+      console.log("Connector was not running; restart skipped.");
+    } else {
+      logUpdateLine(log, "Restart skipped by --no-restart.");
+      console.log("Restart skipped by --no-restart.");
+    }
+
+    logUpdateLine(log, "NordRelay update completed.");
+    console.log("NordRelay update completed.");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    logUpdateLine(log, `ERROR ${message}`);
+    console.error(`Update failed: ${message}`);
+    process.exitCode = 1;
+  } finally {
+    await closeLogStream(log);
+  }
+}
+
+function resolveUpdateMethod(options) {
+  const requested = (options.updateMethod || process.env.NORDRELAY_UPDATE_METHOD || "auto").trim().toLowerCase();
+  if (!requested || requested === "auto") {
+    return fs.existsSync(path.join(RUNTIME_ROOT, ".git")) ? "git" : "npm";
+  }
+  if (requested === "npm" || requested === "git") {
+    return requested;
+  }
+  throw new Error(`Unsupported update method "${requested}". Use auto, npm, or git.`);
+}
+
+async function runNpmSelfUpdate(sourceRoot, log) {
+  const npm = resolveNpmSpawnCommand();
+  if (!npm) {
+    throw new Error("npm was not found. Install Node.js/npm or add npm to PATH.");
+  }
+  await runLoggedStep(log, "Install latest NordRelay package", npm.command, [
+    ...npm.argsPrefix,
+    "install",
+    "-g",
+    "@nordbyte/nordrelay@latest",
+  ], { cwd: os.homedir(), shell: npm.shell });
+  await runVerifyNordRelayCli(sourceRoot, log);
+}
+
+async function runGitSelfUpdate(sourceRoot, log) {
+  const git = resolveRequiredCommand("git");
+  const npm = resolveNpmSpawnCommand();
+  if (!npm) {
+    throw new Error("npm was not found. Install Node.js/npm or add npm to PATH.");
+  }
+  await runLoggedStep(log, "Pull latest source", git.command, ["pull", "--ff-only", "origin", "main"], { cwd: sourceRoot, shell: git.shell });
+  await runLoggedStep(log, "Install dependencies", npm.command, [...npm.argsPrefix, "install"], { cwd: sourceRoot, shell: npm.shell });
+  await runLoggedStep(log, "Run checks", npm.command, [...npm.argsPrefix, "run", "check"], { cwd: sourceRoot, shell: npm.shell });
+  await runLoggedStep(log, "Run tests", npm.command, [...npm.argsPrefix, "test"], { cwd: sourceRoot, shell: npm.shell });
+  await runLoggedStep(log, "Build runtime", npm.command, [...npm.argsPrefix, "run", "build"], { cwd: sourceRoot, shell: npm.shell });
+  await runVerifyNordRelayCli(sourceRoot, log);
+}
+
+async function runVerifyNordRelayCli(sourceRoot, log) {
+  if (fs.existsSync(SCRIPT_PATH)) {
+    await runLoggedStep(log, "Verify NordRelay CLI", process.execPath, [SCRIPT_PATH, "version"], { cwd: sourceRoot });
+    return;
+  }
+  const nordrelay = resolveRequiredCommand("nordrelay");
+  await runLoggedStep(log, "Verify NordRelay CLI", nordrelay.command, ["version"], { cwd: os.homedir(), shell: nordrelay.shell });
+}
+
+async function runLoggedStep(log, label, command, args, settings = {}) {
+  logUpdateLine(log, `${label}: ${formatCommand(command, args)}`);
+  console.log(`\n${label}`);
+  const useShell = Boolean(settings.shell);
+  const child = spawn(useShell ? formatShellCommand(command, args) : command, useShell ? [] : args, {
+    cwd: settings.cwd || RUNTIME_ROOT,
+    env: process.env,
+    shell: useShell,
+    stdio: ["inherit", "pipe", "pipe"],
+    windowsHide: false,
+  });
+
+  child.stdout?.on("data", (chunk) => {
+    safeWrite(process.stdout, chunk);
+    safeWrite(log, chunk);
+  });
+  child.stderr?.on("data", (chunk) => {
+    safeWrite(process.stderr, chunk);
+    safeWrite(log, chunk);
+  });
+
+  const exit = await new Promise((resolve, reject) => {
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolve({ code, signal }));
+  });
+
+  if (exit.signal) {
+    throw new Error(`${label} stopped with signal ${exit.signal}`);
+  }
+  if (exit.code !== 0) {
+    throw new Error(`${label} failed with exit code ${exit.code ?? "unknown"}`);
+  }
+  logUpdateLine(log, `${label} completed`);
+}
+
+function resolveRequiredCommand(command) {
+  const resolved = findExecutable(command);
+  if (!resolved) {
+    throw new Error(`${command} was not found on PATH.`);
+  }
+  return {
+    command: resolved,
+    shell: isWindowsShellScript(resolved),
+  };
+}
+
+function resolveNpmSpawnCommand(env = process.env) {
+  const npmExecPath = env.npm_execpath?.trim();
+  if (npmExecPath && fs.existsSync(npmExecPath)) {
+    return {
+      command: process.execPath,
+      argsPrefix: [npmExecPath],
+      shell: false,
+    };
+  }
+
+  const pathMatch = findExecutable("npm", env.PATH);
+  if (pathMatch) {
+    return {
+      command: pathMatch,
+      argsPrefix: [],
+      shell: isWindowsShellScript(pathMatch),
+    };
+  }
+
+  for (const candidate of commonNpmCandidates(env)) {
+    if (!fs.existsSync(candidate)) continue;
+    return {
+      command: candidate,
+      argsPrefix: [],
+      shell: isWindowsShellScript(candidate),
+    };
+  }
+  return null;
+}
+
+function commonNpmCandidates(env) {
+  const names = process.platform === "win32" ? ["npm.cmd", "npm.bat", "npm"] : ["npm"];
+  const directories = [
+    path.dirname(process.execPath),
+    env.APPDATA ? path.join(env.APPDATA, "npm") : undefined,
+    env.ProgramFiles ? path.join(env.ProgramFiles, "nodejs") : undefined,
+    env["ProgramFiles(x86)"] ? path.join(env["ProgramFiles(x86)"], "nodejs") : undefined,
+  ].filter(Boolean);
+  return directories.flatMap((directory) => names.map((name) => path.join(directory, name)));
+}
+
+function logUpdateLine(log, message) {
+  safeWrite(log, `[${nowIso()}] ${message}\n`);
+}
+
+function safeWrite(stream, chunk) {
+  try {
+    stream.write(chunk);
+  } catch {
+    // Logging must not break the updater if stdout/stderr disappears.
+  }
+}
+
+function closeLogStream(log) {
+  return new Promise((resolve) => {
+    log.end(resolve);
+  });
+}
+
+function formatCommand(command, args) {
+  return [command, ...args].map((part) => {
+    const text = String(part);
+    return /[\s"'$`\\]/.test(text) ? JSON.stringify(text) : text;
+  }).join(" ");
+}
+
+function formatShellCommand(command, args) {
+  return [command, ...args].map(quoteShellArg).join(" ");
+}
+
+function quoteShellArg(value) {
+  if (process.platform === "win32") {
+    return quoteWindowsCmdArg(String(value));
+  }
+  return `'${String(value).replace(/'/g, `'\\''`)}'`;
+}
+
+function quoteWindowsCmdArg(value) {
+  if (value.length === 0) {
+    return "\"\"";
+  }
+  if (!/[\s"&|<>()^%]/.test(value)) {
+    return value;
+  }
+  return `"${value
+    .replace(/%/g, "%%")
+    .replace(/(\\*)"/g, '$1$1\\"')
+    .replace(/(\\+)$/g, "$1$1")}"`;
+}
+
 async function commandInit(options) {
   await mkdirp(options.home);
   const envPath = path.join(options.home, "nordrelay.env");
@@ -858,17 +1101,26 @@ function check(name, ok, detail, status = "fail") {
   };
 }
 
-function findExecutable(command) {
+function findExecutable(command, pathValue = process.env.PATH, pathextValue = process.env.PATHEXT) {
   if (!command) return null;
   if (command.includes(path.sep) && fs.existsSync(command)) return command;
-  const paths = (process.env.PATH || "").split(path.delimiter);
+  const paths = (pathValue || "").split(path.delimiter);
+  const extensions = process.platform === "win32"
+    ? ["", ...(pathextValue || ".COM;.EXE;.BAT;.CMD").split(";")]
+    : [""];
   for (const dir of paths) {
-    const candidate = path.join(dir, command);
-    if (fs.existsSync(candidate)) return candidate;
+    for (const extension of extensions) {
+      const candidate = path.join(dir, `${command}${extension}`);
+      if (fs.existsSync(candidate)) return candidate;
+    }
   }
   return null;
 }
 
+function isWindowsShellScript(filePath) {
+  return process.platform === "win32" && /\.(?:cmd|bat)$/i.test(filePath);
+}
+
 function validateStateBackend() {
   const backend = process.env.NORDRELAY_STATE_BACKEND || "json";
   if (backend === "json") return { ok: true, detail: "NORDRELAY_STATE_BACKEND=json" };
@@ -920,6 +1172,7 @@ async function main() {
   if (options.command === "init") return commandInit(options);
   if (options.command === "user") return commandUser(options);
   if (options.command === "doctor") return commandDoctor(options);
+  if (options.command === "update") return commandUpdate(options);
   if (options.command === "web" || options.command === "dashboard") return commandWeb(options);
   if (options.command === "restart") {
     await commandStop(options);
@@ -932,7 +1185,7 @@ async function main() {
   }
 
   console.error(`Unknown command: ${options.command}`);
-  console.error("Usage: nordrelay [init|user|doctor|web|start|stop|restart|status|foreground|version]");
+  console.error("Usage: nordrelay [init|user|doctor|web|start|stop|restart|status|update|foreground|version]");
   process.exitCode = 2;
 }