feat: show server version in UI + resolve codex CLI before launch

Two user-facing improvements for the Windows test path:

1. Show the running agent's git short-SHA in the desktop console
   sidebar so it is obvious whether a 'git pull' actually landed.
   - New server-version.ts: tries 'git rev-parse --short HEAD',
     falls back to reading .git/HEAD and packed-refs, caches the
     result on first read. Degrades to 'unknown' if git / .git
     are unavailable.
   - /api/config now returns 'serverVersion'.
   - mac-web desktop sidebar renders a small pill under the
     Screen Pilot title showing 'version: <sha>'.

2. Resolve the codex binary BEFORE opening a new cmd window.
   Previously, clicking codex authenticate on Windows would:
     a) spawn 'cmd /c start "" <temp.bat>'
     b) the bat would try to run 'codex' which was not on PATH
     c) user saw ''codex' 不是内部或外部命令' buried inside a
        popup window and the server thought launch succeeded.
   New flow: resolveCodexBinaryOnWindows() checks absolute path,
   'where.exe codex' for PATH, and the %APPDATA%\npm global
   install location before writing the bat. If nothing is
   found, the launcher throws a clear Chinese error that
   surfaces in the UI telling the user to install codex or set
   CODEX_BIN. No more mystery popup.

Author: ouyyyyang

apps/mac-web/public/app.js

@@ -183,6 +183,10 @@ async function init() {
   wireEvents();
   state.config = await fetchJson("/api/config");
   serviceState.textContent = `${state.config.serviceName} 已连接，当前桌面网页控制台可用。`;
+  const versionEl = document.querySelector("#server-version");
+  if (versionEl) {
+    versionEl.textContent = `version: ${state.config.serverVersion || "unknown"}`;
+  }
   populateProviderOptions(state.config.modelProviders || [], state.config.defaults?.modelProvider || "codex");
   populateModelOptions(codexModelSelect, state.config.codexModels || [], state.config.defaults?.codexModel || "gpt-5.4");
   populateModelOptions(

apps/mac-web/public/index.html

@@ -12,6 +12,7 @@
         <div class="brand-block">
           <p class="eyebrow">Desktop Console</p>
           <h1>Screen Pilot</h1>
+          <p id="server-version" class="server-version">version: &hellip;</p>
           <p class="muted-copy">面向 Mac 与 Windows 的网页控制台，用来做配置、认证、抓屏测试、模型测试和历史查看。</p>
         </div>
 

apps/mac-web/public/styles.css

@@ -85,6 +85,18 @@ img { display: block; max-width: 100%; }
   line-height: 1.5;
 }
 
+.brand-block .server-version {
+  margin: 0 0 10px;
+  padding: 2px 8px;
+  display: inline-block;
+  border-radius: 999px;
+  background: rgba(0, 0, 0, 0.28);
+  color: rgba(255, 255, 255, 0.95);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  font-size: 0.72rem;
+  letter-spacing: 0.02em;
+}
+
 .brand-block .eyebrow {
   color: rgba(255, 255, 255, 0.7);
 }

core/agent/src/app.ts

@@ -22,6 +22,7 @@ import {
   loadLocalVisionModelCatalog,
   loadModelProviderCatalog
 } from "./model-catalog.js";
+import { resolveServerVersion } from "./server-version.js";
 import { SessionStore } from "./session-store.js";
 import { SettingsStore } from "./settings-store.js";
 import type {
@@ -251,6 +252,7 @@ async function routeRequest(input: {
   if (method === "GET" && pathname === "/api/config") {
     const payload: AgentConfigPayload = {
       serviceName: input.config.serviceName,
+      serverVersion: resolveServerVersion(input.config.workspaceRoot),
       auth: {
         pairingRequired: true
       },

core/agent/src/codex-login.ts

@@ -1,7 +1,8 @@
 import { spawn } from "node:child_process";
-import { writeFile } from "node:fs/promises";
+import { access, writeFile } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { isAbsolute, join } from "node:path";
 import type { SpawnProcess, SpawnedProcessLike } from "./codex.js";
 
 export interface CodexLoginStatus {
@@ -137,6 +138,17 @@ async function launchCodexLoginOnWindows(input: {
   codexBin: string;
   workspaceRoot: string;
 }): Promise<void> {
+  // Resolve the codex binary before opening a console window, otherwise
+  // the user just sees '"codex" 不是内部或外部命令' inside a popup and
+  // has no signal that the problem is a missing install.
+  const resolvedBin = await resolveCodexBinaryOnWindows(input.codexBin);
+  if (!resolvedBin) {
+    throw new Error(
+      `Codex CLI 未找到。已尝试 "${input.codexBin}" 以及 PATH 和常见 Windows 安装位置。请先安装 codex CLI(https://codex.openai.com),或把 CODEX_BIN 环境变量指向 codex 可执行文件的完整路径,再重启 Screen Pilot。`
+    );
+  }
+  const effectiveInput = { ...input, codexBin: resolvedBin };
+
   // Why a .bat file instead of 'cmd /c start cmd /k "..."':
   //
   // The nested form forced the command line through four parsers in a
@@ -149,7 +161,7 @@ async function launchCodexLoginOnWindows(input: {
   // to a single layer inside the bat's own cmd.exe, where the quotes
   // are interpreted exactly as typed.
   const batPath = buildCodexLoginBatPath();
-  const batContent = buildCodexLoginBatContent(input);
+  const batContent = buildCodexLoginBatContent(effectiveInput);
   await writeFile(batPath, batContent, { encoding: "ascii" });
 
   await new Promise<void>((resolve, reject) => {
@@ -190,6 +202,66 @@ export function buildCodexLoginBatPath(): string {
   return join(tmpdir(), "screen-pilot-codex-login.bat");
 }
 
+export async function resolveCodexBinaryOnWindows(configuredBin: string): Promise<string | null> {
+  // 1. If the user gave us an absolute path, honor it verbatim as long as
+  //    the file exists.
+  if (isAbsolute(configuredBin)) {
+    if (await fileExists(configuredBin)) return configuredBin;
+    return null;
+  }
+
+  // 2. Ask Windows where.exe to search PATH. This matches exactly what
+  //    cmd.exe would do when the user types the command manually.
+  const fromPath = await runWhere(configuredBin);
+  if (fromPath) return fromPath;
+
+  // 3. Fall back to the well-known npm global install location, which is
+  //    where '@openai/codex' ends up for most Windows users.
+  const appdata = process.env.APPDATA;
+  if (appdata) {
+    for (const candidate of [
+      join(appdata, "npm", `${configuredBin}.cmd`),
+      join(appdata, "npm", `${configuredBin}.ps1`),
+      join(appdata, "npm", `${configuredBin}.exe`),
+      join(appdata, "npm", configuredBin)
+    ]) {
+      if (await fileExists(candidate)) return candidate;
+    }
+  }
+
+  return null;
+}
+
+async function fileExists(path: string): Promise<boolean> {
+  try {
+    await access(path, fsConstants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runWhere(binaryName: string): Promise<string | null> {
+  return new Promise((resolve) => {
+    const child = spawn("where.exe", [binaryName], {
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    let stdout = "";
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk.toString("utf8");
+    });
+    child.on("error", () => resolve(null));
+    child.on("close", (code) => {
+      if (code !== 0) {
+        resolve(null);
+        return;
+      }
+      const firstLine = stdout.split(/\r?\n/).map((line) => line.trim()).find(Boolean);
+      resolve(firstLine || null);
+    });
+  });
+}
+
 export function buildCodexLoginBatContent(input: {
   codexBin: string;
   workspaceRoot: string;

core/agent/src/server-version.ts

@@ -0,0 +1,72 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+let cached: string | null = null;
+
+export function resolveServerVersion(workspaceRoot: string): string {
+  if (cached) {
+    return cached;
+  }
+  cached = readServerVersion(workspaceRoot);
+  return cached;
+}
+
+function readServerVersion(workspaceRoot: string): string {
+  const viaGit = tryGitCommand(workspaceRoot);
+  if (viaGit) return viaGit;
+
+  const viaHead = tryReadGitHead(workspaceRoot);
+  if (viaHead) return viaHead;
+
+  return "unknown";
+}
+
+function tryGitCommand(workspaceRoot: string): string | null {
+  try {
+    const out = execFileSync("git", ["rev-parse", "--short", "HEAD"], {
+      cwd: workspaceRoot,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+    const trimmed = out.trim();
+    return trimmed || null;
+  } catch {
+    return null;
+  }
+}
+
+function tryReadGitHead(workspaceRoot: string): string | null {
+  try {
+    const headPath = join(workspaceRoot, ".git", "HEAD");
+    const headContent = readFileSync(headPath, "utf8").trim();
+    if (headContent.startsWith("ref: ")) {
+      const refPath = join(workspaceRoot, ".git", headContent.slice(5).trim());
+      try {
+        const sha = readFileSync(refPath, "utf8").trim();
+        return sha.slice(0, 7) || null;
+      } catch {
+        return readPackedRef(workspaceRoot, headContent.slice(5).trim());
+      }
+    }
+    return headContent.slice(0, 7) || null;
+  } catch {
+    return null;
+  }
+}
+
+function readPackedRef(workspaceRoot: string, ref: string): string | null {
+  try {
+    const packed = readFileSync(join(workspaceRoot, ".git", "packed-refs"), "utf8");
+    for (const line of packed.split(/\r?\n/)) {
+      if (line.startsWith("#") || !line.trim()) continue;
+      const [sha, refName] = line.split(/\s+/);
+      if (refName === ref && sha) {
+        return sha.slice(0, 7);
+      }
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}

core/agent/src/types.ts

@@ -108,6 +108,7 @@ export interface SessionSummary {
 
 export interface AgentConfigPayload {
   serviceName: string;
+  serverVersion: string;
   auth: {
     pairingRequired: true;
   };