@hellcoder/companion 0.98.0 → 0.98.1-preview.20260515064257.15d15e5

package/server/claude-tls.ts

@@ -0,0 +1,84 @@
+/**
+ * Self-signed TLS material for the [::1] CLI ingress listener.
+ *
+ * After we patch the Claude CLI binary so it accepts `wss://[::1]:<port>/...`,
+ * the scheme check still requires TLS. We don't need real PKI: we generate
+ * an ephemeral self-signed cert (SAN IP:::1) once, cache it under
+ * ~/.companion/tls/, and spawn Claude with NODE_TLS_REJECT_UNAUTHORIZED=0
+ * so its WebSocket client trusts it without keychain integration.
+ */
+
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { COMPANION_HOME } from "./paths.js";
+
+const TLS_DIR = join(COMPANION_HOME, "tls");
+const CERT_PATH = join(TLS_DIR, "cli-bridge.cert.pem");
+const KEY_PATH = join(TLS_DIR, "cli-bridge.key.pem");
+
+/** Re-generate if the existing cert is within this many ms of expiry. */
+const RENEW_THRESHOLD_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+
+export interface CliBridgeCert {
+  cert: string;
+  key: string;
+  certPath: string;
+  keyPath: string;
+}
+
+function certIsCurrent(): boolean {
+  if (!existsSync(CERT_PATH) || !existsSync(KEY_PATH)) return false;
+  try {
+    // openssl puts validity into the cert itself, but stat mtime is a cheap
+    // proxy: we issued the cert with `-days 3650`, so any file written less
+    // than ~3620 days ago is still well-within validity.
+    const stat = statSync(CERT_PATH);
+    const ageMs = Date.now() - stat.mtimeMs;
+    const validForMs = 3650 * 24 * 60 * 60 * 1000;
+    return ageMs < validForMs - RENEW_THRESHOLD_MS;
+  } catch {
+    return false;
+  }
+}
+
+async function generateCert(): Promise<void> {
+  mkdirSync(TLS_DIR, { recursive: true });
+  const proc = Bun.spawn(
+    [
+      "openssl", "req", "-x509",
+      "-newkey", "rsa:2048",
+      "-keyout", KEY_PATH,
+      "-out", CERT_PATH,
+      "-days", "3650",
+      "-nodes",
+      "-subj", "/CN=companion-cli-bridge",
+      "-addext", "subjectAltName=IP:::1,IP:127.0.0.1",
+    ],
+    { stdout: "pipe", stderr: "pipe" },
+  );
+  const exitCode = await proc.exited;
+  if (exitCode !== 0) {
+    const stderr = await new Response(proc.stderr).text();
+    throw new Error(
+      `openssl cert generation failed (exit ${exitCode}): ${stderr.trim()}.` +
+      ` Is openssl installed?`,
+    );
+  }
+}
+
+/**
+ * Returns the cert + key for the CLI ingress listener, generating them if
+ * missing or near expiry. The returned strings are the PEM contents, suitable
+ * for passing directly to `Bun.serve({ tls: { cert, key } })`.
+ */
+export async function ensureCliBridgeCert(): Promise<CliBridgeCert> {
+  if (!certIsCurrent()) {
+    await generateCert();
+  }
+  const cert = readFileSync(CERT_PATH, "utf-8");
+  const key = readFileSync(KEY_PATH, "utf-8");
+  return { cert, key, certPath: CERT_PATH, keyPath: KEY_PATH };
+}
+
+/** Test-only: directory the cert lives in (under COMPANION_HOME). */
+export const _TLS_DIR_FOR_TEST = TLS_DIR;

package/server/claude-versions.test.ts

@@ -0,0 +1,96 @@
+import { describe, it, expect } from "vitest";
+import {
+  parseClaudeVersion,
+  compareVersions,
+  formatVersion,
+  isIncompatibleVersion,
+  isKnownGoodVersion,
+  pickPinTarget,
+  KNOWN_GOOD_MAX,
+  KNOWN_BAD_MIN,
+} from "./claude-versions.js";
+
+describe("parseClaudeVersion", () => {
+  // Validates parsing across the two formats Claude has shipped:
+  // the modern "X.Y.Z (Claude Code)" form and the older "Claude Code X.Y.Z" form.
+  it("parses modern format from `claude --version`", () => {
+    expect(parseClaudeVersion("2.1.142 (Claude Code)")).toEqual({ major: 2, minor: 1, patch: 142 });
+  });
+
+  it("parses legacy format", () => {
+    expect(parseClaudeVersion("Claude Code 2.1.119")).toEqual({ major: 2, minor: 1, patch: 119 });
+  });
+
+  it("tolerates trailing whitespace and newlines from stdout", () => {
+    expect(parseClaudeVersion("2.1.120\n")).toEqual({ major: 2, minor: 1, patch: 120 });
+  });
+
+  it("returns null when no version-like substring is present", () => {
+    expect(parseClaudeVersion("Unknown command: --version")).toBeNull();
+    expect(parseClaudeVersion("")).toBeNull();
+  });
+});
+
+describe("compareVersions", () => {
+  it("orders by major then minor then patch", () => {
+    expect(compareVersions({ major: 2, minor: 1, patch: 120 }, { major: 2, minor: 1, patch: 121 })).toBe(-1);
+    expect(compareVersions({ major: 2, minor: 1, patch: 121 }, { major: 2, minor: 1, patch: 120 })).toBe(1);
+    expect(compareVersions({ major: 2, minor: 1, patch: 120 }, { major: 2, minor: 1, patch: 120 })).toBe(0);
+    expect(compareVersions({ major: 1, minor: 9, patch: 999 }, { major: 2, minor: 0, patch: 0 })).toBe(-1);
+  });
+});
+
+describe("isIncompatibleVersion / isKnownGoodVersion", () => {
+  // The lockdown shipped in 2.1.121. 2.1.120 is the last working version.
+  // These tests pin those boundary semantics so the constants don't silently drift.
+  it("treats 2.1.120 as the last known-good version", () => {
+    expect(isKnownGoodVersion({ major: 2, minor: 1, patch: 120 })).toBe(true);
+    expect(isIncompatibleVersion({ major: 2, minor: 1, patch: 120 })).toBe(false);
+  });
+
+  it("treats 2.1.121 as the first incompatible version", () => {
+    expect(isKnownGoodVersion({ major: 2, minor: 1, patch: 121 })).toBe(false);
+    expect(isIncompatibleVersion({ major: 2, minor: 1, patch: 121 })).toBe(true);
+  });
+
+  it("treats 2.1.142 (currently-shipped) as incompatible", () => {
+    expect(isIncompatibleVersion({ major: 2, minor: 1, patch: 142 })).toBe(true);
+  });
+
+  it("aligns with the exported constants", () => {
+    expect(KNOWN_GOOD_MAX).toEqual({ major: 2, minor: 1, patch: 120 });
+    expect(KNOWN_BAD_MIN).toEqual({ major: 2, minor: 1, patch: 121 });
+  });
+});
+
+describe("pickPinTarget", () => {
+  // Companion offers to pin to "the latest cached version that still works".
+  // Important to skip incompatible versions even if they're newest on disk.
+  it("returns the highest known-good version from a mixed list", () => {
+    const result = pickPinTarget([
+      { major: 2, minor: 1, patch: 119 },
+      { major: 2, minor: 1, patch: 120 },
+      { major: 2, minor: 1, patch: 142 },
+    ]);
+    expect(result).toEqual({ major: 2, minor: 1, patch: 120 });
+  });
+
+  it("ignores incompatible versions even if they're the newest available", () => {
+    const result = pickPinTarget([
+      { major: 2, minor: 1, patch: 130 },
+      { major: 2, minor: 1, patch: 119 },
+    ]);
+    expect(result).toEqual({ major: 2, minor: 1, patch: 119 });
+  });
+
+  it("returns null when no candidate is known-good", () => {
+    expect(pickPinTarget([{ major: 2, minor: 1, patch: 142 }])).toBeNull();
+    expect(pickPinTarget([])).toBeNull();
+  });
+});
+
+describe("formatVersion", () => {
+  it("renders X.Y.Z without prefix", () => {
+    expect(formatVersion({ major: 2, minor: 1, patch: 120 })).toBe("2.1.120");
+  });
+});

package/server/claude-versions.ts

@@ -0,0 +1,76 @@
+/**
+ * Claude Code CLI version detection and compatibility.
+ *
+ * Claude Code 2.1.121 (~2026-04-27) added a static hostname allowlist to the
+ * --sdk-url flag, breaking every third-party tool that bridges sessions to a
+ * local server. The validator (function `YR4`, set `KU5` in the bundle)
+ * accepts only:
+ *   api.anthropic.com, api-staging.anthropic.com,
+ *   beacon.claude-ai.staging.ant.dev, claude.fedstart.com,
+ *   claude-staging.fedstart.com
+ * and only with wss:// or https:// schemes. No env-var override exists.
+ *
+ * Last known working version: 2.1.120.
+ * First broken version: 2.1.121.
+ */
+
+export interface ClaudeVersion {
+  major: number;
+  minor: number;
+  patch: number;
+}
+
+/** Last Claude Code CLI version that accepts arbitrary --sdk-url targets. */
+export const KNOWN_GOOD_MAX: ClaudeVersion = { major: 2, minor: 1, patch: 120 };
+
+/** First Claude Code CLI version that rejects non-Anthropic --sdk-url hosts. */
+export const KNOWN_BAD_MIN: ClaudeVersion = { major: 2, minor: 1, patch: 121 };
+
+/**
+ * Parse the output of `claude --version`, which looks like:
+ *   "2.1.142 (Claude Code)"
+ * or sometimes (older builds):
+ *   "Claude Code 2.1.119"
+ */
+export function parseClaudeVersion(raw: string): ClaudeVersion | null {
+  const match = raw.match(/(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+  };
+}
+
+/** Returns -1 / 0 / 1 like Array.sort. */
+export function compareVersions(a: ClaudeVersion, b: ClaudeVersion): number {
+  if (a.major !== b.major) return a.major < b.major ? -1 : 1;
+  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1;
+  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1;
+  return 0;
+}
+
+export function formatVersion(v: ClaudeVersion): string {
+  return `${v.major}.${v.minor}.${v.patch}`;
+}
+
+/** True if the version is on or after the lockdown (2.1.121+). */
+export function isIncompatibleVersion(v: ClaudeVersion): boolean {
+  return compareVersions(v, KNOWN_BAD_MIN) >= 0;
+}
+
+/** True if the version is at or below 2.1.120 (accepts arbitrary --sdk-url). */
+export function isKnownGoodVersion(v: ClaudeVersion): boolean {
+  return compareVersions(v, KNOWN_GOOD_MAX) <= 0;
+}
+
+/**
+ * Pick the best version to roll back to from a list of cached versions.
+ * Returns the highest version that's still known-good (<= 2.1.120),
+ * or null if none of the candidates qualify.
+ */
+export function pickPinTarget(candidates: ClaudeVersion[]): ClaudeVersion | null {
+  const good = candidates.filter(isKnownGoodVersion);
+  if (good.length === 0) return null;
+  return good.reduce((best, v) => (compareVersions(v, best) > 0 ? v : best));
+}

package/server/cli-ingress-server.ts

@@ -0,0 +1,101 @@
+/**
+ * Parallel WSS listener on [::1] for the patched Claude binary's --sdk-url.
+ *
+ * The main companion server stays on its existing port (plain HTTP for the
+ * browser UI). After the binary patch, the spawned Claude CLI connects to
+ * `wss://[::1]:<port>/ws/cli/<sessionId>` instead of the plain ws:// URL —
+ * the lockdown validator demands wss:// even with [::1] hostname allowed.
+ *
+ * We pick a random free port at startup, persist it to settings, and bind
+ * with a self-signed cert (SAN IP:::1). Listens only for the CLI upgrade
+ * path; everything else gets 404. Delegates open/message/close to the
+ * exact same WsBridge methods the main server uses, so the bridge code has
+ * no idea which listener delivered the socket.
+ */
+
+import type { ServerWebSocket } from "bun";
+import type { WsBridge, SocketData } from "./ws-bridge.js";
+import type { CliLauncher } from "./cli-launcher.js";
+import { ensureCliBridgeCert } from "./claude-tls.js";
+
+export interface CliIngressServer {
+  /** Canonical URL prefix to hand to spawned CLIs, e.g. "wss://[::1]:54321". */
+  urlPrefix: string;
+  port: number;
+  stop: () => void;
+}
+
+export async function startCliIngressServer(deps: {
+  wsBridge: WsBridge;
+  launcher: CliLauncher;
+}): Promise<CliIngressServer> {
+  const { cert, key } = await ensureCliBridgeCert();
+
+  const server = Bun.serve<SocketData>({
+    hostname: "::1",
+    port: 0, // Bun picks a free port
+    idleTimeout: 0,
+    tls: { cert, key },
+    fetch(req, server) {
+      const url = new URL(req.url);
+      const match = url.pathname.match(/^\/ws\/cli\/([a-f0-9-]+)$/);
+      if (!match) {
+        return new Response("Not Found", { status: 404 });
+      }
+      const sessionId = match[1];
+
+      // jsonHandoff bridge tokens still apply when set — same logic as the
+      // main server's CLI upgrade handler. Sessions launched in the new
+      // "patched" mode don't use bridgeToken (TLS + loopback is the guard);
+      // but if a session was created with jsonHandoff this listener will
+      // honor the token check too, for symmetry.
+      const session = deps.launcher.getSession(sessionId);
+      if (session?.bridgeToken) {
+        const presented = url.searchParams.get("token")
+          || req.headers.get("sec-websocket-protocol")?.split(",").map((s: string) => s.trim()).find(Boolean);
+        if (presented !== session.bridgeToken) {
+          return new Response("Unauthorized", { status: 401 });
+        }
+      }
+
+      const upgraded = server.upgrade(req, {
+        data: { kind: "cli" as const, sessionId },
+      });
+      if (upgraded) return undefined;
+      return new Response("WebSocket upgrade failed", { status: 400 });
+    },
+    websocket: {
+      idleTimeout: 0,
+      sendPings: false,
+      open(ws: ServerWebSocket<SocketData>) {
+        if (ws.data.kind !== "cli") return;
+        deps.wsBridge.handleCLIOpen(ws, ws.data.sessionId);
+        deps.launcher.markConnected(ws.data.sessionId);
+      },
+      message(ws: ServerWebSocket<SocketData>, msg: string | Buffer) {
+        if (ws.data.kind !== "cli") return;
+        deps.wsBridge.handleCLIMessage(ws, msg);
+      },
+      close(ws: ServerWebSocket<SocketData>) {
+        if (ws.data.kind !== "cli") return;
+        deps.wsBridge.handleCLIClose(ws);
+      },
+    },
+  });
+
+  // Bun.serve types server.port as number | undefined because port: 0 is
+  // technically resolvable late; in practice port is bound synchronously and
+  // populated by the time Bun.serve returns. Crash early if not.
+  const port = server.port;
+  if (typeof port !== "number") {
+    throw new Error("Bun.serve did not assign a port to the CLI ingress listener");
+  }
+  const urlPrefix = `wss://[::1]:${port}`;
+  console.log(`[cli-ingress] Listening on ${urlPrefix} (TLS, patched-bridge mode)`);
+
+  return {
+    urlPrefix,
+    port,
+    stop: () => { server.stop(true); },
+  };
+}

package/server/cli-launcher.ts

@@ -497,12 +497,28 @@ export class CliLauncher {
 
     // When running inside a container, the SDK URL targets the host alias so
     // the CLI can connect back to the Hono server running on the host.
-    // For host sessions, use the numeric loopback (127.0.0.1) instead of
-    // "localhost": Claude Code v1.2.1+ rejects the literal hostname
-    // "localhost" in --sdk-url as a CSWSH hardening measure (issue #655).
+    //
+    // For host sessions there are two paths depending on settings:
+    //   * "patched" — the companion has byte-patched the local Claude binary
+    //     so it accepts [::1] in --sdk-url, and a parallel TLS WS listener is
+    //     running on wss://[::1]:<ingress-port>. We emit that URL and set
+    //     NODE_TLS_REJECT_UNAUTHORIZED=0 below so the self-signed cert is
+    //     accepted. Required on Claude Code >= 2.1.121, where the validator
+    //     rejects every non-Anthropic host. See claude-versions.ts.
+    //   * "none" (default) — plain ws://127.0.0.1:<port>/... Works on
+    //     2.1.120 and earlier; sessions on a stock 2.1.121+ binary will fail
+    //     immediately with "host 127.0.0.1 is not an approved Anthropic
+    //     endpoint" (visible only on direct CLI stderr).
+    const settings = getSettings();
+    const patchedBridge = !isContainerized
+      && settings.claudeBridgeMode === "patched"
+      && typeof settings.claudeBridgeIngressUrl === "string"
+      && settings.claudeBridgeIngressUrl.length > 0;
     const sdkUrl = isContainerized
       ? `ws://${containerSdkHost}:${this.port}/ws/cli/${sessionId}`
-      : `ws://127.0.0.1:${this.port}/ws/cli/${sessionId}`;
+      : patchedBridge
+        ? `${settings.claudeBridgeIngressUrl}/ws/cli/${sessionId}`
+        : `ws://127.0.0.1:${this.port}/ws/cli/${sessionId}`;
 
     // Claude Code rejects bypassPermissions when running with root/sudo.
     // Container sessions are downgraded by default; host sessions are only
@@ -535,7 +551,7 @@ export class CliLauncher {
     // path via CLAUDE_BRIDGE_CONFIG env var instead of --sdk-url on argv.
     // This is forward-compatible if Anthropic further restricts --sdk-url
     // (e.g. drops it entirely or adds origin/handshake checks).
-    const bridgeMode = getSettings().cliBridgeMode ?? "loopback";
+    const bridgeMode = settings.cliBridgeMode ?? "loopback";
     const useJsonHandoff = bridgeMode === "jsonHandoff" && !isContainerized;
     let bridgeConfigPath: string | undefined;
     if (useJsonHandoff) {
@@ -634,6 +650,10 @@ export class CliLauncher {
         ...options.env,
         PATH: getEnrichedPath(),
         ...(bridgeConfigPath ? { CLAUDE_BRIDGE_CONFIG: bridgeConfigPath } : {}),
+        // Patched-bridge mode terminates --sdk-url at our self-signed wss://[::1]
+        // listener. Tell Bun/Node to trust the self-signed cert without involving
+        // the user's CA store.
+        ...(patchedBridge ? { NODE_TLS_REJECT_UNAUTHORIZED: "0" } : {}),
       };
       spawnCwd = info.cwd;
     }

package/server/index.ts

@@ -34,6 +34,12 @@ import { LinearAgentBridge } from "./linear-agent-bridge.js";
 import { NoVncProxy } from "./novnc-proxy.js";
 
 import { startPeriodicCheck, setServiceMode } from "./update-checker.js";
+import {
+  startPeriodicCheck as startClaudeCompatPeriodicCheck,
+} from "./claude-compat-checker.js";
+import { startCliIngressServer } from "./cli-ingress-server.js";
+import { getSettings, updateSettings } from "./settings-manager.js";
+import { setCliIngressServer } from "./routes/system-routes.js";
 import { imagePullManager } from "./image-pull-manager.js";
 import { restoreIfNeeded as restoreTailscaleFunnel, cleanup as cleanupTailscaleFunnel } from "./tailscale-manager.js";
 import { isRunningAsService } from "./service.js";
@@ -360,6 +366,26 @@ restoreTailscaleFunnel(port).catch((err) => {
 
 // ── Update checker ──────────────────────────────────────────────────────────
 startPeriodicCheck();
+
+// ── Claude CLI compatibility checker — surfaces banner when CLI is 2.1.121+ ─
+startClaudeCompatPeriodicCheck();
+
+// ── CLI ingress (TLS WSS on [::1]) — only when the user has patched their
+// Claude binary; otherwise plain ws://127.0.0.1 on the main port is used.
+// We re-bind a new random port each restart and persist it to settings so
+// cli-launcher emits the current URL on next spawn.
+if (getSettings().claudeBridgeMode === "patched") {
+  (async () => {
+    try {
+      const ingress = await startCliIngressServer({ wsBridge, launcher });
+      setCliIngressServer(ingress);
+      updateSettings({ claudeBridgeIngressUrl: ingress.urlPrefix });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      console.warn(`[server] Patched bridge mode active but ingress start failed: ${msg}`);
+    }
+  })();
+}
 if (isRunningAsService()) {
   setServiceMode(true);
   console.log("[server] Running as background service (auto-update available)");

package/server/routes/system-routes.ts

@@ -10,8 +10,24 @@ import {
   setUpdateInProgress,
 } from "../update-checker.js";
 import { refreshServiceDefinition } from "../service.js";
-import { getSettings } from "../settings-manager.js";
+import { getSettings, updateSettings } from "../settings-manager.js";
 import { imagePullManager } from "../image-pull-manager.js";
+import { checkCompat, getCompatState } from "../claude-compat-checker.js";
+import { pinToVersion, patchBinary, unpatch } from "../claude-patcher.js";
+import {
+  startCliIngressServer,
+  type CliIngressServer,
+} from "../cli-ingress-server.js";
+
+/**
+ * Module-level handle to the running CLI ingress server (patched-bridge mode).
+ * Owned by this module so the patch / unpatch routes can start and stop it.
+ * Set by the bootstrap in index.ts when settings indicate patched mode at
+ * startup; otherwise populated by the /claude-compat/patch route.
+ */
+let cliIngress: CliIngressServer | null = null;
+export function getCliIngressServer(): CliIngressServer | null { return cliIngress; }
+export function setCliIngressServer(s: CliIngressServer | null): void { cliIngress = s; }
 
 export function registerSystemRoutes(
   api: Hono,
@@ -225,4 +241,121 @@ export function registerSystemRoutes(
     deps.wsBridge.injectUserMessage(id, body.content);
     return c.json({ ok: true, sessionId: id });
   });
+
+  // ── Claude CLI compatibility (post-2.1.121 --sdk-url lockdown) ──────────────
+  // Read more in claude-versions.ts. The UI consumes /claude-compat to render a
+  // banner offering Pin (downgrade) or Patch (byte-replace + TLS bridge).
+  function compatPayload() {
+    const compat = getCompatState();
+    const settings = getSettings();
+    return {
+      installedVersion: compat.installedVersion,
+      installedPath: compat.installedPath,
+      isIncompatible: compat.isIncompatible,
+      isPatched: compat.isPatched,
+      availableKnownGood: compat.availableKnownGood,
+      suggestedPinTarget: compat.suggestedPinTarget,
+      lastChecked: compat.lastChecked,
+      error: compat.error,
+      bridgeMode: settings.claudeBridgeMode ?? "none",
+      ingressUrl: settings.claudeBridgeIngressUrl ?? "",
+      bannerDismissedVersion: settings.claudeCompatBannerDismissedVersion ?? "",
+    };
+  }
+
+  api.get("/claude-compat", async (c) => {
+    const initial = getCompatState();
+    const staleMs = deps.updateCheckStaleMs;
+    if (initial.lastChecked === 0 || Date.now() - initial.lastChecked > staleMs) {
+      await checkCompat();
+    }
+    return c.json(compatPayload());
+  });
+
+  api.post("/claude-compat/refresh", async (c) => {
+    await checkCompat();
+    return c.json(compatPayload());
+  });
+
+  api.post("/claude-compat/pin", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const version = typeof body.version === "string" && body.version.trim()
+      ? body.version.trim()
+      : getCompatState().suggestedPinTarget;
+    if (!version) {
+      return c.json({ error: "No known-good Claude version is cached locally to pin to." }, 400);
+    }
+    const res = await pinToVersion(version);
+    if (!res.ok) return c.json({ error: res.error }, 400);
+
+    // Pinning means we're back on a non-validator binary; turn off patched
+    // bridge mode so we don't continue routing through wss://[::1].
+    if (cliIngress) {
+      cliIngress.stop();
+      cliIngress = null;
+    }
+    updateSettings({ claudeBridgeMode: "none", claudeBridgeIngressUrl: "" });
+
+    await checkCompat();
+    return c.json({ ok: true, pinnedTo: version, ...compatPayload() });
+  });
+
+  api.post("/claude-compat/patch", async (c) => {
+    const patchRes = await patchBinary();
+    if (!patchRes.ok) return c.json({ error: patchRes.error }, 400);
+
+    // Start (or restart) the TLS ingress listener and persist the URL so
+    // cli-launcher emits it on the next spawn.
+    if (cliIngress) {
+      cliIngress.stop();
+      cliIngress = null;
+    }
+    try {
+      cliIngress = await startCliIngressServer({
+        wsBridge: deps.wsBridge,
+        launcher: deps.launcher,
+      });
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      return c.json({ error: `Patched binary but TLS ingress failed: ${msg}` }, 500);
+    }
+    updateSettings({
+      claudeBridgeMode: "patched",
+      claudeBridgeIngressUrl: cliIngress.urlPrefix,
+    });
+
+    await checkCompat();
+    return c.json({
+      ok: true,
+      patchedPath: patchRes.patchedPath,
+      replacements: patchRes.replacements,
+      ...compatPayload(),
+    });
+  });
+
+  api.post("/claude-compat/unpatch", async (c) => {
+    const res = await unpatch();
+    if (!res.ok) return c.json({ error: res.error }, 400);
+
+    if (cliIngress) {
+      cliIngress.stop();
+      cliIngress = null;
+    }
+    updateSettings({ claudeBridgeMode: "none", claudeBridgeIngressUrl: "" });
+
+    await checkCompat();
+    return c.json({ ok: true, target: res.target, ...compatPayload() });
+  });
+
+  api.post("/claude-compat/dismiss-banner", async (c) => {
+    const body = await c.req.json().catch(() => ({}));
+    const version = typeof body.version === "string" && body.version.trim()
+      ? body.version.trim()
+      : getCompatState().installedVersion ?? "";
+    if (!version) {
+      return c.json({ error: "No version available to record as dismissed" }, 400);
+    }
+    updateSettings({ claudeCompatBannerDismissedVersion: version });
+    return c.json({ ok: true, dismissedVersion: version });
+  });
 }

package/server/settings-manager.test.ts

@@ -49,6 +49,9 @@ describe("settings-manager", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       cliBridgeMode: "loopback",
+      claudeBridgeMode: "none",
+      claudeBridgeIngressUrl: "",
+      claudeCompatBannerDismissedVersion: "",
       updatedAt: 0,
     });
   });
@@ -105,6 +108,9 @@ describe("settings-manager", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       cliBridgeMode: "loopback",
+      claudeBridgeMode: "none",
+      claudeBridgeIngressUrl: "",
+      claudeCompatBannerDismissedVersion: "",
       updatedAt: 123,
     });
   });
@@ -185,6 +191,9 @@ describe("settings-manager", () => {
       updateChannel: "stable",
       dockerAutoUpdate: false,
       cliBridgeMode: "loopback",
+      claudeBridgeMode: "none",
+      claudeBridgeIngressUrl: "",
+      claudeCompatBannerDismissedVersion: "",
       updatedAt: 0,
     });
   });