@bitkyc08/opencodex 2.5.5-preview.1 → 2.5.5-preview.2

package/src/codex-shim.ts

@@ -3,7 +3,6 @@ import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, renameSync,
 import { getConfigDir } from "./config";
 
 const SHIM_MARKER = "opencodex codex autostart shim";
-const STATE_PATH = join(getConfigDir(), "codex-shim.json");
 const CODEX_INTERNAL_COMMANDS = [
   "app-server",
   "archive",
@@ -34,6 +33,13 @@ interface ShimState {
   wrapperPath: string;
   originalPath: string;
   backupPath: string;
+  wrappers?: ShimFileState[];
+}
+
+interface ShimFileState {
+  wrapperPath: string;
+  originalPath: string;
+  backupPath: string;
 }
 
 function cliEntry(): { bun: string; cli: string } {
@@ -69,6 +75,33 @@ function findCodexOnPath(): string | null {
   return null;
 }
 
+function findWindowsCodexTargets(): ShimFileState[] | null {
+  for (const dir of (process.env.PATH ?? "").split(delimiter).filter(Boolean)) {
+    const cmd = join(dir, "codex.cmd");
+    const ps1 = join(dir, "codex.ps1");
+    const targets: ShimFileState[] = [];
+    for (const path of [cmd, ps1]) {
+      if (!existsSync(path) || isShim(path)) continue;
+      try {
+        if (!lstatSync(path).isDirectory()) {
+          targets.push({ wrapperPath: path, originalPath: path, backupPath: backupPathFor(path) });
+        }
+      } catch { /* keep scanning */ }
+    }
+    if (targets.length > 0) return targets;
+
+    const exe = join(dir, "codex.exe");
+    if (!existsSync(exe) || isShim(exe)) continue;
+    try {
+      if (lstatSync(exe).isDirectory()) continue;
+      const wrapperPath = join(dir, "codex.cmd");
+      if (existsSync(wrapperPath) && !isShim(wrapperPath)) continue;
+      return [{ wrapperPath, originalPath: exe, backupPath: backupPathFor(exe) }];
+    } catch { /* keep scanning */ }
+  }
+  return null;
+}
+
 function backupPathFor(path: string): string {
   const ext = extname(path);
   return ext ? `${path.slice(0, -ext.length)}.opencodex-real${ext}` : `${path}.opencodex-real`;
@@ -107,83 +140,167 @@ if /I "%~1"=="-V" goto run_codex\r
 `;
 }
 
+function psString(value: string): string {
+  return `'${value.replace(/'/g, "''")}'`;
+}
+
+export function buildWindowsPowerShellCodexShim(realCodexPath: string, bunPath: string, cliPath: string): string {
+  const internalCommands = CODEX_INTERNAL_COMMANDS.map(command => psString(command)).join(", ");
+  return `#!/usr/bin/env pwsh
+# ${SHIM_MARKER}
+$internalCommands = @(${internalCommands})
+$firstArg = if ($args.Count -gt 0) { [string]$args[0] } else { "" }
+$skipEnsure = $env:OCX_SHIM_BYPASS -or $internalCommands -contains $firstArg -or @("--help", "-h", "--version", "-V") -contains $firstArg
+if (-not $skipEnsure) {
+  & ${psString(bunPath)} ${psString(cliPath)} ensure *> $null
+}
+& ${psString(realCodexPath)} @args
+exit $LASTEXITCODE
+`;
+}
+
 function readState(): ShimState | null {
   try {
-    return JSON.parse(readFileSync(STATE_PATH, "utf8")) as ShimState;
+    return JSON.parse(readFileSync(statePath(), "utf8")) as ShimState;
   } catch {
     return null;
   }
 }
 
+function statePath(): string {
+  return join(getConfigDir(), "codex-shim.json");
+}
+
 function writeState(state: ShimState): void {
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
-  writeFileSync(STATE_PATH, JSON.stringify(state, null, 2) + "\n", "utf8");
+  writeFileSync(statePath(), JSON.stringify(state, null, 2) + "\n", "utf8");
 }
 
 function writeShim(wrapperPath: string, realCodexPath: string): void {
   const { bun, cli } = cliEntry();
   if (process.platform === "win32") {
-    writeFileSync(wrapperPath, buildWindowsCodexShim(realCodexPath, bun, cli), "utf8");
+    if (wrapperPath.toLowerCase().endsWith(".ps1")) {
+      writeFileSync(wrapperPath, buildWindowsPowerShellCodexShim(realCodexPath, bun, cli), "utf8");
+    } else {
+      writeFileSync(wrapperPath, buildWindowsCodexShim(realCodexPath, bun, cli), "utf8");
+    }
   } else {
     writeFileSync(wrapperPath, buildUnixCodexShim(realCodexPath, bun, cli), "utf8");
     chmodSync(wrapperPath, 0o755);
   }
 }
 
+function stateFiles(state: ShimState): ShimFileState[] {
+  return state.wrappers?.length
+    ? state.wrappers
+    : [{ wrapperPath: state.wrapperPath, originalPath: state.originalPath, backupPath: state.backupPath }];
+}
+
+function primaryState(files: ShimFileState[]): ShimState {
+  const first = files[0];
+  return { platform: process.platform, ...first, wrappers: files };
+}
+
+function replaceOwnedBackup(sourcePath: string, backupPath: string): void {
+  const oldBackupPath = `${backupPath}.old-${process.pid}`;
+  if (existsSync(oldBackupPath)) unlinkSync(oldBackupPath);
+  if (existsSync(backupPath)) renameSync(backupPath, oldBackupPath);
+  try {
+    renameSync(sourcePath, backupPath);
+    if (existsSync(oldBackupPath)) unlinkSync(oldBackupPath);
+  } catch (error) {
+    if (!existsSync(backupPath) && existsSync(oldBackupPath)) renameSync(oldBackupPath, backupPath);
+    throw error;
+  }
+}
+
+function refreshShimFile(file: ShimFileState): boolean {
+  if (existsSync(file.wrapperPath) && !isShim(file.wrapperPath)) {
+    if (file.wrapperPath !== file.originalPath) return false;
+    replaceOwnedBackup(file.wrapperPath, file.backupPath);
+    writeShim(file.wrapperPath, file.backupPath);
+    return true;
+  }
+  if (!existsSync(file.wrapperPath) && existsSync(file.backupPath)) {
+    writeShim(file.wrapperPath, file.backupPath);
+    return true;
+  }
+  if (file.originalPath !== file.wrapperPath && existsSync(file.originalPath) && existsSync(file.wrapperPath) && isShim(file.wrapperPath)) {
+    replaceOwnedBackup(file.originalPath, file.backupPath);
+    writeShim(file.wrapperPath, file.backupPath);
+    return true;
+  }
+  return false;
+}
+
 export function installCodexShim(): { installed: boolean; message: string } {
   const existing = readState();
-  if (existing && existsSync(existing.wrapperPath) && existsSync(existing.backupPath) && isShim(existing.wrapperPath)) {
-    if (process.platform === "win32" && existing.originalPath && existsSync(existing.originalPath)) {
-      renameSync(existing.originalPath, existing.backupPath);
-      writeShim(existing.wrapperPath, existing.backupPath);
-      writeState({ ...existing, platform: process.platform });
+  if (existing) {
+    const files = stateFiles(existing);
+    let refreshed = false;
+    for (const file of files) refreshed = refreshShimFile(file) || refreshed;
+    const allInstalled = files.every(file => existsSync(file.wrapperPath) && existsSync(file.backupPath) && isShim(file.wrapperPath));
+    if (refreshed || allInstalled) {
+      writeState(primaryState(files));
+      if (refreshed) {
+        return {
+          installed: true,
+          message: `Codex update detected. Backed up new launcher and refreshed shim at ${files.map(f => f.wrapperPath).join(", ")}.`,
+        };
+      }
       return {
-        installed: true,
-        message: `Codex update detected. Backed up new binary and refreshed shim at ${existing.wrapperPath}.`,
+        installed: false,
+        message: `Codex autostart shim already installed at ${files.map(f => f.wrapperPath).join(", ")}.`,
       };
     }
-    return { installed: false, message: `Codex autostart shim already installed at ${existing.wrapperPath}.` };
-  }
-  if (existing && existsSync(existing.backupPath) && (!existsSync(existing.wrapperPath) || !isShim(existing.wrapperPath))) {
-    if (existsSync(existing.wrapperPath)) unlinkSync(existing.wrapperPath);
-    writeShim(existing.wrapperPath, existing.backupPath);
-    writeState({ ...existing, platform: process.platform });
-    return {
-      installed: true,
-      message: `Codex autostart shim repaired at ${existing.wrapperPath}. Original remains at ${existing.backupPath}.`,
-    };
   }
 
-  const originalPath = findCodexOnPath();
-  if (!originalPath) return { installed: false, message: "Could not find a codex executable on PATH." };
+  const targets = process.platform === "win32"
+    ? findWindowsCodexTargets()
+    : (() => {
+      const originalPath = findCodexOnPath();
+      return originalPath ? [{ wrapperPath: originalPath, originalPath, backupPath: backupPathFor(originalPath) }] : null;
+    })();
+  if (!targets) return { installed: false, message: "Could not find a codex executable on PATH." };
 
-  const backupPath = backupPathFor(originalPath);
-  if (existsSync(backupPath)) return { installed: false, message: `Refusing to overwrite existing backup: ${backupPath}` };
-
-  const wrapperPath = process.platform === "win32" ? join(dirname(originalPath), "codex.cmd") : originalPath;
-  renameSync(originalPath, backupPath);
-  writeShim(wrapperPath, backupPath);
-  writeState({ platform: process.platform, wrapperPath, originalPath, backupPath });
-  return { installed: true, message: `Codex autostart shim installed at ${wrapperPath}. Original saved at ${backupPath}.` };
+  for (const target of targets) {
+    if (existsSync(target.backupPath)) return { installed: false, message: `Refusing to overwrite existing backup: ${target.backupPath}` };
+  }
+  for (const target of targets) {
+    renameSync(target.originalPath, target.backupPath);
+    writeShim(target.wrapperPath, target.backupPath);
+  }
+  writeState(primaryState(targets));
+  return {
+    installed: true,
+    message: `Codex autostart shim installed at ${targets.map(t => t.wrapperPath).join(", ")}. Original saved at ${targets.map(t => t.backupPath).join(", ")}.`,
+  };
 }
 
 export function uninstallCodexShim(): { removed: boolean; message: string } {
   const state = readState();
   if (!state) return { removed: false, message: "Codex autostart shim is not installed." };
-  if (existsSync(state.wrapperPath) && isShim(state.wrapperPath)) unlinkSync(state.wrapperPath);
-  if (existsSync(state.backupPath) && !existsSync(state.originalPath)) renameSync(state.backupPath, state.originalPath);
-  if (existsSync(STATE_PATH)) unlinkSync(STATE_PATH);
-  return { removed: true, message: `Codex autostart shim removed. Restored ${state.originalPath}.` };
+  const files = stateFiles(state);
+  for (const file of files) {
+    if (existsSync(file.wrapperPath) && isShim(file.wrapperPath)) unlinkSync(file.wrapperPath);
+  }
+  for (const file of files) {
+    if (existsSync(file.backupPath) && !existsSync(file.originalPath)) renameSync(file.backupPath, file.originalPath);
+  }
+  if (existsSync(statePath())) unlinkSync(statePath());
+  return { removed: true, message: `Codex autostart shim removed. Restored ${files.map(f => f.originalPath).join(", ")}.` };
 }
 
 export function codexShimStatus(): string {
   const state = readState();
   if (!state) return "Codex autostart shim is not installed.";
-  const wrapper = existsSync(state.wrapperPath)
-    ? isShim(state.wrapperPath)
-      ? "shim present"
-      : "present but not an opencodex shim"
-    : "missing";
-  const backup = existsSync(state.backupPath) ? "present" : "missing";
-  return `Codex autostart shim: wrapper ${wrapper} at ${state.wrapperPath}; original backup ${backup} at ${state.backupPath}.`;
+  return stateFiles(state).map(file => {
+    const wrapper = existsSync(file.wrapperPath)
+      ? isShim(file.wrapperPath)
+        ? "shim present"
+        : "present but not an opencodex shim"
+      : "missing";
+    const backup = existsSync(file.backupPath) ? "present" : "missing";
+    return `Codex autostart shim: wrapper ${wrapper} at ${file.wrapperPath}; original backup ${backup} at ${file.backupPath}.`;
+  }).join("\n");
 }

package/src/config.ts

@@ -1,3 +1,4 @@
+import { execFileSync } from "node:child_process";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, chmodSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -92,7 +93,7 @@ export function loadConfig(): OcxConfig {
     return getDefaultConfig();
   }
   try {
-    const raw = readFileSync(configPath, "utf-8");
+    const raw = readFileSync(configPath, "utf-8").replace(/^\uFEFF/, "");
     const parsed = JSON.parse(raw);
     const result = configSchema.safeParse(parsed);
     if (result.success) return result.data as OcxConfig;
@@ -172,7 +173,7 @@ export function writePid(pid: number): void {
   } else {
     hardenConfigDir();
   }
-  writeFileSync(getPidPath(), String(pid), "utf-8");
+  atomicWriteFile(getPidPath(), String(pid));
 }
 
 export function readPid(): number | null {
@@ -180,13 +181,15 @@ export function readPid(): number | null {
   if (!existsSync(pidPath)) return null;
   try {
     const raw = readFileSync(pidPath, "utf-8").trim();
-    const pid = parseInt(raw, 10);
-    if (isNaN(pid)) return null;
+    const pid = parsePidFile(raw);
+    if (pid === null) return null;
     try {
       process.kill(pid, 0);
-      return pid;
+      return isLikelyOcxStartProcess(pid) ? pid : null;
     } catch (e: unknown) {
-      if ((e as NodeJS.ErrnoException).code === "EPERM") return pid;
+      if ((e as NodeJS.ErrnoException).code === "EPERM") {
+        return isLikelyOcxStartProcess(pid) ? pid : null;
+      }
       return null;
     }
   } catch {
@@ -194,7 +197,8 @@ export function readPid(): number | null {
   }
 }
 
-export function removePid(): void {
+export function removePid(expectedPid?: number): void {
+  if (expectedPid !== undefined && readPidFileValue() !== expectedPid) return;
   try {
     unlinkSync(getPidPath());
   } catch { /* ignore */ }
@@ -207,6 +211,56 @@ function warnConfigRepaired(configPath: string, error: z.ZodError): void {
   console.error(`opencodex config at ${configPath}: repaired missing field(s) [${fields}] with defaults. Your providers and accounts are preserved.`);
 }
 
+function readPidFileValue(): number | null {
+  try {
+    return parsePidFile(readFileSync(getPidPath(), "utf-8"));
+  } catch {
+    return null;
+  }
+}
+
+export function parsePidFile(raw: string): number | null {
+  const trimmed = raw.trim();
+  if (!/^\d+$/.test(trimmed)) return null;
+  const pid = Number.parseInt(trimmed, 10);
+  return Number.isSafeInteger(pid) && pid > 0 ? pid : null;
+}
+
+export function isOcxStartCommandLine(commandLine: string): boolean {
+  const normalized = commandLine.toLowerCase().replace(/\\/g, "/");
+  const hasOcxEntrypoint = normalized.includes("src/cli.ts")
+    || normalized.includes("@bitkyc08/opencodex")
+    || /(?:^|[\s/"'])(?:ocx|opencodex)(?:\.cmd)?(?:$|[\s"'])/.test(normalized);
+  return hasOcxEntrypoint && /(?:^|[\s"'])start(?:$|[\s"'])/.test(normalized);
+}
+
+function isLikelyOcxStartProcess(pid: number): boolean {
+  const commandLine = readProcessCommandLine(pid);
+  if (commandLine === undefined) return false;
+  return isOcxStartCommandLine(commandLine);
+}
+
+function readProcessCommandLine(pid: number): string | undefined {
+  try {
+    if (process.platform === "win32") {
+      const output = execFileSync("powershell.exe", [
+        "-NoProfile",
+        "-Command",
+        `(Get-CimInstance Win32_Process -Filter "ProcessId = ${pid}").CommandLine`,
+      ], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 3000 });
+      return output.trim() || undefined;
+    }
+    const output = execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 1000,
+    });
+    return output.trim() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function warnAndBackupInvalidConfig(configPath: string, error: unknown): void {
   if (warnedConfigFallbacks.has(configPath)) return;
   warnedConfigFallbacks.add(configPath);

package/src/open-url.ts

@@ -1,10 +1,18 @@
 import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+function windowsRundll32(): string {
+  const windowsRoot = process.env.SystemRoot || process.env.WINDIR || "C:\\Windows";
+  const candidate = join(windowsRoot, "System32", "rundll32.exe");
+  return existsSync(candidate) ? candidate : "rundll32";
+}
 
 export function openUrl(url: string): void {
   if (!/^https?:\/\//i.test(url)) return;
   const cmd =
     process.platform === "darwin" ? "open"
-    : process.platform === "win32" ? "rundll32"
+    : process.platform === "win32" ? windowsRundll32()
     : "xdg-open";
   const args = process.platform === "win32"
     ? ["url.dll,FileProtocolHandler", url]

package/src/server.ts

@@ -522,14 +522,58 @@ async function fetchWithHeaderTimeout(
   }
 }
 
-const requestLog: { timestamp: number; model: string; provider: string; status: number; durationMs: number }[] = [];
+export interface RequestLogEntry {
+  requestId: string;
+  timestamp: number;
+  model: string;
+  provider: string;
+  status: number;
+  durationMs: number;
+  errorCode?: string;
+}
+
+const requestLog: RequestLogEntry[] = [];
 const MAX_LOG_SIZE = 200;
+let requestLogSeq = 0;
 
-function addRequestLog(entry: typeof requestLog[number]) {
+function addRequestLog(entry: RequestLogEntry) {
   requestLog.push(entry);
   if (requestLog.length > MAX_LOG_SIZE) requestLog.shift();
 }
 
+export function nextRequestLogId(timestamp = Date.now()): string {
+  requestLogSeq = (requestLogSeq % 1_000_000) + 1;
+  return `ocx-${timestamp.toString(36)}-${requestLogSeq.toString(36)}`;
+}
+
+export function requestLogErrorCode(status: number): string | undefined {
+  if (status >= 200 && status < 400) return undefined;
+  if (status === 400 || status === 409) return "invalid_request_error";
+  if (status === 401 || status === 403) return "invalid_api_key";
+  if (status === 429) return "rate_limit_exceeded";
+  if (status === 503) return "server_is_overloaded";
+  if (status >= 500) return "upstream_server_error";
+  return `http_${status}`;
+}
+
+export function filterRequestLogs(logs: RequestLogEntry[], params: URLSearchParams): RequestLogEntry[] {
+  let filtered = logs;
+  const provider = params.get("provider")?.trim();
+  if (provider) filtered = filtered.filter(entry => entry.provider === provider);
+  const status = params.get("status")?.trim().toLowerCase();
+  if (status) {
+    filtered = /^[1-5]xx$/.test(status)
+      ? filtered.filter(entry => Math.floor(entry.status / 100) === Number(status[0]))
+      : filtered.filter(entry => String(entry.status) === status);
+  }
+  const tailRaw = params.get("tail")?.trim();
+  if (tailRaw) {
+    const tail = Number.parseInt(tailRaw, 10);
+    if (Number.isFinite(tail) && tail > 0) filtered = filtered.slice(-Math.min(tail, MAX_LOG_SIZE));
+  }
+  return filtered;
+}
+
 /**
  * Relay an upstream body verbatim while wiring client-cancel -> upstream.abort(). A body returned
  * directly from fetch does NOT propagate the consumer's cancel to a signalled fetch, so a client
@@ -941,7 +985,7 @@ async function handleManagementAPI(req: Request, url: URL, config: OcxConfig): P
   }
 
   if (url.pathname === "/api/logs" && req.method === "GET") {
-    return jsonResponse(requestLog);
+    return jsonResponse(filterRequestLogs(requestLog, url.searchParams));
   }
 
   if (url.pathname === "/api/providers" && req.method === "GET") {
@@ -1228,14 +1272,18 @@ export function startServer(port?: number) {
           return formatErrorResponse(403, "origin_rejected", "cross-origin data-plane request blocked");
         }
         const start = Date.now();
+        const requestId = nextRequestLogId(start);
         const logCtx = { model: "unknown", provider: "unknown" };
         const response = await handleResponses(req, config, logCtx);
+        const errorCode = requestLogErrorCode(response.status);
         addRequestLog({
+          requestId,
           timestamp: start,
           model: logCtx.model,
           provider: logCtx.provider,
           status: response.status,
           durationMs: Date.now() - start,
+          ...(errorCode ? { errorCode } : {}),
         });
         return response;
       }

package/src/service.ts

@@ -5,7 +5,7 @@
  * Codex on a service-managed restart (the restarted instance re-injects); explicit stop/uninstall
  * restore it via the command.
  */
-import { execSync } from "node:child_process";
+import { execFileSync, execSync } from "node:child_process";
 import { existsSync, mkdirSync, unlinkSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -95,6 +95,19 @@ function sh(cmd: string): string {
   return execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
 }
 
+function runFile(file: string, args: string[]): string {
+  return execFileSync(file, args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"], windowsHide: true }).trim();
+}
+
+function windowsSchtasks(): string {
+  const candidate = join(process.env.SystemRoot ?? "C:\\Windows", "System32", "schtasks.exe");
+  return existsSync(candidate) ? candidate : "schtasks.exe";
+}
+
+function schtasks(args: string[]): string {
+  return runFile(windowsSchtasks(), args);
+}
+
 function windowsBatchValue(value: string): string {
   return value.replace(/%/g, "%%").replace(/[\r\n]/g, "");
 }
@@ -124,6 +137,10 @@ export function buildWindowsServiceScript(): string {
   return `${lines.join("\r\n")}\r\n`;
 }
 
+export function buildWindowsSchtasksCreateArgs(script = windowsServiceScriptPath()): string[] {
+  return ["/create", "/tn", TASK, "/tr", `"${script}"`, "/sc", "onlogon", "/rl", "highest", "/f"];
+}
+
 // ── macOS (launchd) ──
 function installLaunchd(): void {
   const dir = join(homedir(), "Library", "LaunchAgents");
@@ -148,14 +165,14 @@ function installWindows(): void {
   if (!existsSync(getConfigDir())) mkdirSync(getConfigDir(), { recursive: true });
   const script = windowsServiceScriptPath();
   writeFileSync(script, buildWindowsServiceScript(), "utf8");
-  sh(`schtasks /create /tn ${TASK} /tr "\\"${script}\\"" /sc onlogon /rl highest /f`);
-  sh(`schtasks /run /tn ${TASK}`);
+  schtasks(buildWindowsSchtasksCreateArgs(script));
+  schtasks(["/run", "/tn", TASK]);
 }
-function startWindows(): void { sh(`schtasks /run /tn ${TASK}`); }
-function stopWindows(): void { try { sh(`schtasks /end /tn ${TASK}`); } catch { /* not running */ } }
-function statusWindows(): string { try { return sh(`schtasks /query /tn ${TASK}`); } catch { return ""; } }
+function startWindows(): void { schtasks(["/run", "/tn", TASK]); }
+function stopWindows(): void { try { schtasks(["/end", "/tn", TASK]); } catch { /* not running */ } }
+function statusWindows(): string { try { return schtasks(["/query", "/tn", TASK]); } catch { return ""; } }
 function uninstallWindows(): void {
-  try { sh(`schtasks /delete /tn ${TASK} /f`); } catch { /* absent */ }
+  try { schtasks(["/delete", "/tn", TASK, "/f"]); } catch { /* absent */ }
   if (existsSync(windowsServiceScriptPath())) unlinkSync(windowsServiceScriptPath());
 }
 
@@ -253,7 +270,7 @@ export function stopServiceIfInstalled(): boolean {
     }
   } else if (process.platform === "win32") {
     try {
-      const q = sh(`schtasks /query /tn ${TASK} 2>nul`);
+      const q = schtasks(["/query", "/tn", TASK]);
       if (q.includes(TASK)) { stopWindows(); return true; }
     } catch { /* task not found */ }
   } else if (process.platform === "linux" && isSystemd() && existsSync(unitPath())) {
@@ -274,7 +291,7 @@ export function uninstallServiceIfInstalled(): boolean {
     }
   } else if (process.platform === "win32") {
     try {
-      const q = sh(`schtasks /query /tn ${TASK} 2>nul`);
+      const q = schtasks(["/query", "/tn", TASK]);
       if (q.includes(TASK)) { uninstallWindows(); return true; }
     } catch { /* task not found */ }
   } else if (process.platform === "linux" && isSystemd() && existsSync(unitPath())) {
@@ -283,6 +300,26 @@ export function uninstallServiceIfInstalled(): boolean {
   return false;
 }
 
+export function serviceStatusSummary(): string {
+  if (process.platform === "darwin") {
+    if (!existsSync(plistPath())) return "not installed";
+    const status = statusLaunchd();
+    return status ? "installed (launchd)" : "installed, not loaded";
+  }
+  if (process.platform === "win32") {
+    const status = statusWindows();
+    return status ? "installed (Task Scheduler)" : "not installed";
+  }
+  if (process.platform === "linux") {
+    if (existsSync("/.dockerenv")) return "unsupported in Docker";
+    if (!isSystemd()) return "unsupported: systemd not found";
+    if (!existsSync(unitPath())) return "not installed";
+    const status = statusSystemd();
+    return status ? "installed (systemd user)" : "installed, not running";
+  }
+  return `unsupported on ${process.platform}`;
+}
+
 export function serviceCommand(sub?: string): void {
   const ops = platformOps();
   if (!ops) {