@hienlh/ppm 0.23.5 → 0.23.7

package/src/providers/codex-app-server/codex-provider.ts

@@ -9,6 +9,7 @@ import type {
   SendMessageOpts,
   UsageInfo,
 } from "../provider.interface.ts";
+import { stderrReason, type ProviderProbeResult } from "../provider-probe.ts";
 import { configService } from "../../services/config.service.ts";
 import { withSharedContext } from "../../shared/provider-context.ts";
 import { setSessionMetadata, getSessionProjectPath, setSessionProvider, setSessionCodexAccount, getSessionCodexAccount, getSessionTitles, insertTurnUsage } from "../../services/db.service.ts";
@@ -33,7 +34,7 @@ import {
 import { killProcessTree } from "../../services/windows-process-tree.ts";
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { CodexJsonRpcClient, CONTROL_REQUEST_TIMEOUT_MS } from "./codex-jsonrpc-client.ts";
+import { CodexJsonRpcClient, CONTROL_REQUEST_TIMEOUT_MS, codexCommand } from "./codex-jsonrpc-client.ts";
 import { permissionModeToCodex, type CodexPermission } from "./codex-permission-map.ts";
 import { buildThreadParams, designMcpEnv, requestWithInstructionsFallback, type CodexThreadParams } from "./codex-thread-params.ts";
 import type { DesignMcpAccess } from "../../services/design/mcp/design-mcp-tool.ts";
@@ -1243,22 +1244,53 @@ export class CodexAppServerProvider implements AIProvider {
   }
 
   // ── Capability probes ──
-  async isAvailable(): Promise<boolean> {
+  /**
+   * Whether `bun x @openai/codex` runs here, and when it does not, why.
+   *
+   * The reason is the point: a failure is rarely "codex is not installed" —
+   * bun fetches the package on demand — it is usually the manifest refresh
+   * failing on a host whose network is not up yet. `retryable` is what tells
+   * the registry to ask again instead of hiding the provider until the next
+   * restart; only a missing bun is hopeless, since nothing can run without it.
+   */
+  async probe(): Promise<ProviderProbeResult> {
+    let cmd: string[];
+    try {
+      cmd = codexCommand("--version");
+    } catch (e) {
+      return { ok: false, reason: (e as Error).message, retryable: false };
+    }
     try {
-      const proc = Bun.spawn([process.execPath, "x", "@openai/codex", "--version"], {
+      const proc = Bun.spawn(cmd, {
         stdout: "pipe", stderr: "pipe",
       });
       // 30s: a cold `bun x` may download the package, and the probe runs during
       // heavy concurrent server startup where process spawn can be starved.
-      const timeout = setTimeout(() => { try { proc.kill(); } catch { /* ignore */ } }, 30_000);
+      let timedOut = false;
+      const timeout = setTimeout(() => {
+        timedOut = true;
+        try { proc.kill(); } catch { /* ignore */ }
+      }, 30_000);
       await proc.exited;
       clearTimeout(timeout);
-      return proc.exitCode === 0;
-    } catch {
-      return false;
+      if (proc.exitCode === 0) return { ok: true };
+      const stderr = timedOut ? "" : await new Response(proc.stderr).text();
+      return {
+        ok: false,
+        retryable: true,
+        reason: timedOut
+          ? "`bun x @openai/codex --version` timed out after 30s"
+          : redactTruncate(stderrReason(stderr), 200) || `\`bun x @openai/codex --version\` exited ${proc.exitCode}`,
+      };
+    } catch (e) {
+      return { ok: false, reason: (e as Error).message, retryable: true };
     }
   }
 
+  async isAvailable(): Promise<boolean> {
+    return (await this.probe()).ok;
+  }
+
   async listModels(): Promise<ModelOption[]> {
     if (this.modelsCache && Date.now() < this.modelsCache.expiry) return this.modelsCache.models;
     if (!this.modelsPending) {

package/src/providers/codex-app-server/codex-reset-credit.ts

@@ -0,0 +1,49 @@
+/**
+ * Spend one of Codex's free rate-limit resets, through the app-server's own
+ * `account/rateLimitResetCredit/consume` (codex ≥ 0.157).
+ *
+ * Deliberately thin: one short-lived app-server on the account's CODEX_HOME, one call, the
+ * outcome back. Whether a reset *should* be spent is decided by the caller
+ * (`codex-reset-credit.service.ts`), never here.
+ */
+import { CodexJsonRpcClient, CONTROL_REQUEST_TIMEOUT_MS } from "./codex-jsonrpc-client.ts";
+
+const CLIENT_INFO = { name: "ppm", title: "PPM", version: "0.0.0" };
+const CAPABILITIES = { experimentalApi: true, requestAttestation: false, optOutNotificationMethods: null };
+
+/**
+ * What Codex did. Straight from its protocol: `nothingToReset` means no window was refreshed and
+ * the credit is kept (OpenAI: "If there is nothing eligible to reset, the benefit remains
+ * available"); `alreadyRedeemed` answers a retry of an attempt that already went through.
+ */
+export type ResetCreditOutcome = "reset" | "nothingToReset" | "noCredit" | "alreadyRedeemed";
+
+const OUTCOMES = new Set<ResetCreditOutcome>(["reset", "nothingToReset", "noCredit", "alreadyRedeemed"]);
+
+/**
+ * @param idempotencyKey one logical attempt; Codex treats a repeat of the same key as the same
+ *   attempt, so a retried request cannot spend a second credit.
+ * @param creditId which credit to spend; omitted lets Codex pick the next available one.
+ */
+export async function consumeCodexResetCredit(
+  codexHome: string,
+  idempotencyKey: string,
+  creditId?: string,
+): Promise<ResetCreditOutcome> {
+  const client = new CodexJsonRpcClient();
+  try {
+    client.start({ cwd: process.cwd(), codexHome });
+    await client.request("initialize", { clientInfo: CLIENT_INFO, capabilities: CAPABILITIES }, CONTROL_REQUEST_TIMEOUT_MS);
+    client.notify("initialized");
+    const res = await client.request<{ outcome?: string }>(
+      "account/rateLimitResetCredit/consume",
+      { idempotencyKey, ...(creditId ? { creditId } : {}) },
+      CONTROL_REQUEST_TIMEOUT_MS,
+    );
+    const outcome = res?.outcome as ResetCreditOutcome | undefined;
+    if (!outcome || !OUTCOMES.has(outcome)) throw new Error(`Codex answered the reset with an unknown outcome: ${String(res?.outcome)}`);
+    return outcome;
+  } finally {
+    client.close();
+  }
+}

package/src/providers/provider-probe.ts

@@ -0,0 +1,63 @@
+/**
+ * Why a CLI provider is not registered, and whether asking again could change it.
+ *
+ * The probe that decides whether Codex exists is `bun x @openai/codex --version`,
+ * and bun re-fetches the npm manifest whenever its cached copy has gone stale —
+ * so a server restarting during a network blip probes a perfectly good install
+ * and is told `ConnectionRefused downloading package manifest @openai/codex`.
+ * Registration only ever happened at startup, so that one bad second hid Codex
+ * from the chat composer for the whole life of the process, with nothing but a
+ * log line to say why (the composer's provider chip is hidden while only one
+ * provider is registered, so the option does not even render greyed out).
+ *
+ * Everything except a missing bun is therefore `retryable`: with `bun x` there
+ * is no real "not installed" state — the package is fetched on demand — so a
+ * failure is almost always the network, not the host.
+ */
+export type ProviderProbeResult =
+  | { ok: true }
+  | { ok: false; reason: string; retryable: boolean };
+
+/** What the last probe of a provider concluded — rendered in Settings → AI. */
+export interface ProviderProbeStatus {
+  id: string;
+  registered: boolean;
+  /** Absent while registered. */
+  reason?: string;
+  /** Probes made so far in this process, successful or not. */
+  attempts: number;
+  lastProbeAt: string;
+  /** Absent when nothing is scheduled: registered, or a failure retrying cannot fix. */
+  nextProbeAt?: string;
+}
+
+/**
+ * Backoff between probes: 30s, 1m, 2m, 5m, then every 15 minutes.
+ *
+ * It never gives up. The case this exists for is a host that starts PPM before
+ * its network is up and is not looked at again for hours — a bounded set of
+ * attempts puts that user back in front of the same silent gap. A warm probe is
+ * one ~20ms spawn against bun's cache, so the 15-minute ceiling costs nothing
+ * measurable, and it stops the moment the provider registers.
+ */
+const BACKOFF_MS = [30_000, 60_000, 120_000, 300_000, 900_000];
+
+/** Delay before the next probe, given how many have already failed (1 = the first). */
+export function nextProbeDelayMs(failedAttempts: number): number {
+  const index = Math.min(Math.max(failedAttempts, 1), BACKOFF_MS.length) - 1;
+  return BACKOFF_MS[index]!;
+}
+
+/**
+ * The one line of a failed probe's stderr worth showing a user.
+ *
+ * bun narrates its work before it fails: a cold `bun x` writes "Resolving
+ * dependencies" and "Resolved, downloaded and extracted [6]" ahead of
+ * `error: ConnectionRefused downloading package manifest @openai/codex`.
+ * Handing all three to a settings strip buries the only sentence that says
+ * what went wrong.
+ */
+export function stderrReason(stderr: string): string {
+  const lines = stderr.split("\n").map((line) => line.trim()).filter(Boolean);
+  return lines.find((line) => line.toLowerCase().startsWith("error:")) ?? lines.at(-1) ?? "";
+}

package/src/providers/registry.ts

@@ -2,6 +2,7 @@ import type { AIProvider } from "./provider.interface.ts";
 import { MockProvider } from "./mock-provider.ts";
 import { ClaudeAgentSdkProvider } from "./claude-agent-sdk.ts";
 import { configService } from "../services/config.service.ts";
+import { nextProbeDelayMs, type ProviderProbeStatus } from "./provider-probe.ts";
 import { CODEX_DEFAULT_MODEL } from "../types/config.ts";
 
 export interface ProviderInfo {
@@ -56,6 +57,10 @@ providerRegistry.register(new MockProvider()); // testing only
  * Bootstrap CLI providers asynchronously.
  * Checks isAvailable() before registering — call at server startup.
  *
+ * Cursor's probe is a local `which`, so it answers the same at every restart.
+ * Codex's reaches the network, so its failure is retried rather than final —
+ * see probeCodexProvider() below.
+ *
  * Persists provider entries with set() only, never save(): set() writes just the
  * "ai" row, while save() rewrites every config key and re-syncs the projects
  * table from this process's in-memory config. A caller that bootstraps without
@@ -87,36 +92,111 @@ export async function bootstrapProviders(): Promise<void> {
     console.warn("[registry] Failed to load Cursor provider:", (e as Error).message);
   }
 
-  try {
-    const { CodexAppServerProvider } = await import("./codex-app-server/codex-provider.ts");
-    const codex = new CodexAppServerProvider();
-    if (await codex.isAvailable()) {
-      providerRegistry.register(codex);
-      const ai = configService.get("ai");
-      // Only when codex has never been configured. An absent `model` is a real
-      // choice here — the settings picker writes it for "Auto (default)", which
-      // hands model selection back to codex — so filling one in on every startup
-      // would undo that choice each restart. Existing installs are given the
-      // default once, by migration.
-      if (!ai.providers["codex"]) {
-        configService.set("ai", {
-          ...ai,
-          providers: {
-            ...ai.providers,
-            codex: {
-              type: "cli",
-              cli_command: "codex",
-              permission_mode: "bypassPermissions",
-              model: CODEX_DEFAULT_MODEL,
-            },
-          },
-        });
+  await probeCodexProvider();
+}
+
+// ── Codex availability: probed, remembered, and retried ──────────────────
+
+const probeStatuses = new Map<string, ProviderProbeStatus>();
+let codexRetryTimer: ReturnType<typeof setTimeout> | null = null;
+let codexProbeInFlight: Promise<ProviderProbeStatus> | null = null;
+
+/** What the last probe of each CLI provider concluded. Empty before bootstrap. */
+export function providerProbeStatuses(): ProviderProbeStatus[] {
+  return Array.from(probeStatuses.values());
+}
+
+/** Probe again now, ahead of whatever the backoff had scheduled (Settings' Retry). */
+export function retryProviderProbe(id: string): Promise<ProviderProbeStatus> {
+  if (id !== "codex") throw new Error(`Provider "${id}" has no retryable probe`);
+  return probeCodexProvider();
+}
+
+/**
+ * Give codex a config entry, but only when it has never had one. An absent
+ * `model` is a real choice — the settings picker writes it for "Auto (default)",
+ * which hands model selection back to codex — so filling one in on every probe
+ * would undo that choice. Existing installs are given the default once, by
+ * migration.
+ */
+function ensureCodexConfigEntry(): void {
+  const ai = configService.get("ai");
+  if (ai.providers["codex"]) return;
+  configService.set("ai", {
+    ...ai,
+    providers: {
+      ...ai.providers,
+      codex: {
+        type: "cli",
+        cli_command: "codex",
+        permission_mode: "bypassPermissions",
+        model: CODEX_DEFAULT_MODEL,
+      },
+    },
+  });
+}
+
+/** Arm the next probe. The timer is unref'd so it never holds the process open. */
+function scheduleCodexRetry(failedAttempts: number): string {
+  const delay = nextProbeDelayMs(failedAttempts);
+  codexRetryTimer = setTimeout(() => {
+    codexRetryTimer = null;
+    void probeCodexProvider();
+  }, delay);
+  codexRetryTimer.unref?.();
+  return new Date(Date.now() + delay).toISOString();
+}
+
+/**
+ * Probe codex and register it if it answers. On a retryable failure — which is
+ * nearly every failure, see `provider-probe.ts` — arm the next attempt instead
+ * of leaving the provider missing until someone restarts PPM.
+ */
+async function probeCodexProvider(): Promise<ProviderProbeStatus> {
+  // Probing again once it serves would put a fresh instance in the registry and
+  // orphan the live app-server clients the old one holds — every open codex
+  // session, and the cleanup handle the server shuts down through.
+  const current = probeStatuses.get("codex");
+  if (current?.registered) return current;
+  if (codexProbeInFlight) return codexProbeInFlight;
+  if (codexRetryTimer) {
+    clearTimeout(codexRetryTimer);
+    codexRetryTimer = null;
+  }
+  codexProbeInFlight = (async (): Promise<ProviderProbeStatus> => {
+    const attempts = (probeStatuses.get("codex")?.attempts ?? 0) + 1;
+    const lastProbeAt = new Date().toISOString();
+    let status: ProviderProbeStatus;
+    try {
+      const { CodexAppServerProvider } = await import("./codex-app-server/codex-provider.ts");
+      const codex = new CodexAppServerProvider();
+      const result = await codex.probe();
+      if (result.ok) {
+        providerRegistry.register(codex);
+        ensureCodexConfigEntry();
+        console.log("[registry] Codex provider registered (@openai/codex found)");
+        status = { id: "codex", registered: true, attempts, lastProbeAt };
+      } else {
+        status = { id: "codex", registered: false, attempts, lastProbeAt, reason: result.reason };
+        if (result.retryable) status.nextProbeAt = scheduleCodexRetry(attempts);
+        console.log(
+          `[registry] Codex provider unavailable: ${result.reason}` +
+          (status.nextProbeAt ? ` — retrying at ${status.nextProbeAt}` : ""),
+        );
       }
-      console.log("[registry] Codex provider registered (@openai/codex found)");
-    } else {
-      console.log("[registry] Codex provider skipped (@openai/codex not found)");
+    } catch (e) {
+      // A broken import is a bug, not a flat host — but it is still worth
+      // retrying, since the alternative is silence until the next restart.
+      status = { id: "codex", registered: false, attempts, lastProbeAt, reason: (e as Error).message };
+      status.nextProbeAt = scheduleCodexRetry(attempts);
+      console.warn("[registry] Failed to load Codex provider:", (e as Error).message);
     }
-  } catch (e) {
-    console.warn("[registry] Failed to load Codex provider:", (e as Error).message);
+    probeStatuses.set("codex", status);
+    return status;
+  })();
+  try {
+    return await codexProbeInFlight;
+  } finally {
+    codexProbeInFlight = null;
   }
 }

package/src/server/index.ts

@@ -218,7 +218,9 @@ app.route("/api/fs/sqlite", fsSqliteRoutes);
 
 // System resource monitoring (SSE + JSON)
 import { resourceRoutes } from "./routes/resources.ts";
+import { systemServiceRoutes } from "./routes/system-services.ts";
 app.route("/api/system", resourceRoutes);
+app.route("/api/system", systemServiceRoutes);
 
 // Host OS facts for the file explorer (platform, drives, known + pinned folders)
 import { hostInfoRoutes } from "./routes/host-info.ts";
@@ -290,6 +292,13 @@ app.route("/api/upgrade", upgradeRoutes);
 import { cloudRoutes } from "./routes/cloud.ts";
 app.route("/api/cloud", cloudRoutes);
 
+// Speech-to-text (Whisper on the host) for the chat mic
+import { speechRoutes } from "./routes/speech.ts";
+app.route("/api/speech", speechRoutes);
+// Language servers, machine-wide (the Settings pane). The per-project half is project-scoped.
+import { lspGlobalRoutes } from "./routes/lsp.ts";
+app.route("/api/lsp", lspGlobalRoutes);
+
 // Static files / SPA fallback (non-API routes)
 app.route("/", staticRoutes);
 

package/src/server/middleware/auth.ts

@@ -30,7 +30,11 @@ export async function authMiddleware(c: Context, next: Next) {
   if (c.req.method === "GET") {
     const p = c.req.path;
     const isMediaPath = p.endsWith("/files/raw") || p.endsWith("/files/transcode") || p === "/api/fs/raw" || p === "/api/fs/transcode";
-    if (p.endsWith("/stream") || isMediaPath || p.endsWith("/image")) {
+    // An <img> cannot send an Authorization header either. This one route is safe
+    // to widen to: it takes an APP ID, not a path, and answers only with the icon
+    // that app's own desktop entry already points at.
+    const isAppIcon = p.startsWith("/api/system/app-icon/");
+    if (p.endsWith("/stream") || isMediaPath || isAppIcon || p.endsWith("/image")) {
       const queryToken = c.req.query("token");
       if (queryToken && queryToken === authConfig.token) {
         return next();

package/src/server/routes/codex-accounts.ts

@@ -4,6 +4,7 @@ import { listCodexAccounts, removeCodexAccount, getAllCodexUsages, getCodexStrat
 import { addApiKeyAccount, startDeviceLogin, getDeviceLoginStatus, cancelDeviceLogin, startBrowserLogin, submitBrowserCallback, getBrowserLoginStatus, cancelBrowserLogin } from "../../services/codex-account-login.ts";
 import { exportCodexEncrypted, importCodexEncrypted } from "../../services/codex-account-portability.ts";
 import { isCodexAccountAuthFailed } from "../../services/codex-account-auth-state.ts";
+import { ResetCreditRefusedError, spendCodexResetCredit } from "../../services/codex-reset-credit.service.ts";
 
 /** Codex multi-account management. Mounted under /api/codex-accounts (auth-guarded). */
 export const codexAccountsRoutes = new Hono();
@@ -65,6 +66,19 @@ codexAccountsRoutes.patch("/:id", async (c) => {
   return c.json(ok(updated));
 });
 
+/**
+ * POST /api/codex-accounts/:id/reset-credit — spend one free rate-limit reset.
+ * Refused with 409 unless a limit is reached right now (checked live) and a credit is left.
+ */
+codexAccountsRoutes.post("/:id/reset-credit", async (c) => {
+  try {
+    return c.json(ok(await spendCodexResetCredit(c.req.param("id"))));
+  } catch (e) {
+    if (e instanceof ResetCreditRefusedError) return c.json(err(e.message), e.status);
+    return c.json(err((e as Error).message), 502);
+  }
+});
+
 /** Set the selection strategy. */
 codexAccountsRoutes.put("/strategy", async (c) => {
   const body = await c.req.json<{ strategy?: CodexStrategy }>().catch(() => ({} as { strategy?: CodexStrategy }));

package/src/server/routes/cross-origin-guard.ts

@@ -0,0 +1,20 @@
+/**
+ * The header pair every state-changing system route requires.
+ *
+ * PPM can be configured with auth disabled on a LAN, and a page on any other
+ * origin can submit an HTML form to this server. Such a form can set neither a
+ * JSON content type nor a custom header, so demanding BOTH forces a CORS
+ * preflight the browser will refuse to make on its behalf.
+ *
+ * One function, so the kill, signal and service-action routes cannot drift into
+ * three slightly different ideas of what a same-origin request looks like. A
+ * bodyless action still sends `{}` rather than being granted an exception here.
+ */
+import type { Context } from "hono";
+
+export function crossOriginRefusal(c: Context): string | null {
+  const contentType = c.req.header("content-type") ?? "";
+  if (!contentType.toLowerCase().startsWith("application/json")) return "Content-Type must be application/json";
+  if (c.req.header("x-ppm-request") !== "1") return "Missing X-PPM-Request header";
+  return null;
+}

package/src/server/routes/git.ts

@@ -4,9 +4,11 @@ import { gitService } from "../../services/git.service.ts";
 import { gitHunksService, type HunkRequest, type HunkScope } from "../../services/git-hunks/git-hunks.service.ts";
 import { assertSafeRev, gitBlameService } from "../../services/git-blame/git-blame.service.ts";
 import { branchDiff } from "../../services/git-branch-diff/branch-diff.service.ts";
+import { assertRef } from "../../services/git-branch-diff/branch-diff-parse.ts";
 import { discoverGitRepos, isGitRepo } from "../../services/git-repos/git-repo-discovery.ts";
 import { isInsideDir, realPathOrSelfSync } from "../../services/fs-ops/fs-real-path.ts";
 import { ok, err } from "../../types/api.ts";
+import type { CheckoutMode } from "../../types/git.ts";
 
 type Env = { Variables: { projectPath: string; projectName: string } };
 
@@ -267,6 +269,22 @@ gitRoutes.get("/branches", async (c) => {
   }
 });
 
+/**
+ * GET /git/refs — every checkout target the branch picker offers.
+ *
+ * Separate from `/branches` rather than an enrichment of it: this answer costs
+ * one `for-each-ref` over *three* namespaces and carries a commit per row,
+ * where `/branches` is the cheap list the graph and the review pickers read on
+ * mount.
+ */
+gitRoutes.get("/refs", async (c) => {
+  try {
+    return c.json(ok(await gitService.refs(c.get("projectPath"))));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
 /** GET /git/pr-url?branch= */
 gitRoutes.get("/pr-url", async (c) => {
   try {
@@ -495,20 +513,38 @@ gitRoutes.post("/branch/create", async (c) => {
     const projectPath = c.get("projectPath");
     const { name, from } = await c.req.json<{ name: string; from?: string }>();
     if (!name) return c.json(err("Missing: name"), 400);
-    await gitService.createBranch(projectPath, name, from);
+    // Both land as arguments of `git checkout -b`, so neither may open with a dash.
+    await gitService.createBranch(
+      projectPath,
+      assertRef(name, "name"),
+      from ? assertRef(from, "from") : undefined,
+    );
     return c.json(ok({ created: name }));
   } catch (e) {
     return c.json(err((e as Error).message), 500);
   }
 });
 
-/** POST /git/checkout { ref } */
+/**
+ * POST /git/checkout { ref, mode? }
+ *
+ * `mode` is `checkout` (the default), `detach` or `track` — see
+ * `GitService.checkout`. It is validated rather than passed through because it
+ * decides which flag precedes the ref, and `assertRef` is what stops the ref
+ * itself from *being* a flag: an unchecked `-f` here is a forced checkout that
+ * discards the working tree.
+ */
+const CHECKOUT_MODES = new Set<CheckoutMode>(["checkout", "detach", "track"]);
+
 gitRoutes.post("/checkout", async (c) => {
   try {
     const projectPath = c.get("projectPath");
-    const { ref } = await c.req.json<{ ref: string }>();
+    const { ref, mode } = await c.req.json<{ ref: string; mode?: CheckoutMode }>();
     if (!ref) return c.json(err("Missing: ref"), 400);
-    await gitService.checkout(projectPath, ref);
+    if (mode && !CHECKOUT_MODES.has(mode)) {
+      return c.json(err(`Unknown checkout mode: "${mode}"`), 400);
+    }
+    await gitService.checkout(projectPath, assertRef(ref, "ref"), mode);
     return c.json(ok({ checkedOut: ref }));
   } catch (e) {
     return c.json(err((e as Error).message), 500);

package/src/server/routes/lsp.ts

@@ -6,13 +6,19 @@
  * at all, which is indistinguishable from a broken feature unless something
  * says so — hence the install hint travelling with the availability.
  *
- * Nothing here installs anything. A silent network install triggered by opening
- * a file is not a thing an editor should do on the user's behalf.
+ * Installing is a POST, and nothing else here triggers one. A network install because a file
+ * was opened is not a thing an editor should do on the user's behalf; pressing Install is.
+ *
+ * There are two routers because there are two questions. The editor asks about *this project*
+ * — its `node_modules/.bin` counts, and a rustup component belongs in the toolchain that
+ * project selects. Settings asks about *this machine*, with no project open at all. They share
+ * the install handler, so neither can drift into accepting a package name.
  */
-import { Hono } from "hono";
+import { Hono, type Context } from "hono";
 import { sep } from "node:path";
 import { lspManager } from "../../services/lsp/lsp-manager.ts";
-import { lspLanguageForPath } from "../../services/lsp/server-registry.ts";
+import { installLanguageServer, lspInstallDir, uninstallLanguageServer } from "../../services/lsp/lsp-install.ts";
+import { lspLanguageForPath, serverById, serversSharingInstall } from "../../services/lsp/server-registry.ts";
 import { ok, err } from "../../types/api.ts";
 
 type Env = { Variables: { projectPath: string; projectName: string } };
@@ -55,4 +61,91 @@ lspRoutes.get("/status", async (c) => {
   }
 });
 
+/**
+ * POST /lsp/install — install the missing server, because someone pressed Install.
+ *
+ * The project, because `rustup component add` acts on the toolchain that directory selects.
+ */
+lspRoutes.post("/install", (c) => installServer(c, c.get("projectPath")));
+
+/**
+ * The machine-wide pair, for the Settings pane: `/api/lsp/*`.
+ *
+ * Settings is not open on a project, so there is no `node_modules/.bin` to consider and
+ * `rustup component add` lands in whichever toolchain PPM's own directory selects — the
+ * default one. That is the honest answer to "install rust-analyzer on this machine", and the
+ * pane says so; a project pinning its own toolchain still gets it from the editor's button.
+ */
+export const lspGlobalRoutes = new Hono();
+
+/** GET /api/lsp/servers — every registered server, whether the machine has it, and where installs go. */
+lspGlobalRoutes.get("/servers", async (c) => {
+  try {
+    return c.json(ok({
+      servers: await lspManager.availability(),
+      installDir: lspInstallDir(),
+      running: lspManager.running(),
+    }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+lspGlobalRoutes.post("/install", (c) => installServer(c, undefined));
+
+/**
+ * POST /api/lsp/uninstall — remove a server, from the Settings pane.
+ *
+ * Only here, and not on the editor's router: that dialog is only ever shown for a server that
+ * is *missing*, so it has nothing to remove. The gate is `removable`, which comes from where
+ * the server was found rather than from what the browser claims — a copy on `PATH` is the
+ * user's, and PPM has no business deleting it.
+ */
+lspGlobalRoutes.post("/uninstall", async (c) => {
+  const body = await c.req.json().catch(() => ({}) as Record<string, unknown>);
+  const definition = serverById(String(body.serverId ?? ""));
+  if (!definition) return c.json(err("No such language server"), 400);
+
+  const row = (await lspManager.availability()).find((s) => s.id === definition.id);
+  if (!row?.removable) {
+    return c.json(err(`PPM did not install ${definition.displayName}, so there is nothing for it to remove.`), 400);
+  }
+
+  try {
+    // The idle sessions first: the files are about to go, and on Windows a running binary
+    // cannot be unlinked at all. Every server the package serves, not just the row that was
+    // clicked — `vscode-langservers-extracted` is JSON, HTML and CSS, so removing the JSON
+    // row deletes files an open `.html` buffer is still running out of.
+    for (const id of new Set([definition.id, ...serversSharingInstall(definition).map((s) => s.id)])) {
+      await lspManager.stopIdle(id);
+    }
+    await uninstallLanguageServer(definition);
+    return c.json(ok({ id: definition.id, displayName: definition.displayName }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+});
+
+/**
+ * The one install handler, shared by both routers.
+ *
+ * The body carries a server **id** and nothing else: the packages are the registry's, so no
+ * part of the command being run was chosen by the browser.
+ */
+async function installServer(c: Context, projectPath: string | undefined): Promise<Response> {
+  const body = await c.req.json().catch(() => ({}) as Record<string, unknown>);
+  const definition = serverById(String(body.serverId ?? ""));
+  if (!definition) return c.json(err("No such language server"), 400);
+  if (!definition.install) {
+    return c.json(err(`PPM cannot install ${definition.displayName}. Install it yourself: ${definition.installHint}`), 400);
+  }
+
+  try {
+    await installLanguageServer(definition, { projectPath });
+    return c.json(ok({ id: definition.id, displayName: definition.displayName }));
+  } catch (e) {
+    return c.json(err((e as Error).message), 500);
+  }
+}
+
 export default lspRoutes;