claude-code-cache-fix 3.0.5 → 3.1.1

package/README.ko.md

@@ -125,7 +125,7 @@ VSIX 없이 수동 VS Code 래퍼를 설정하려면 [docs/preload-setup.md](doc
 
 **하는 것:** 캐시 버그 수정을 위해 발신 요청 구조(블록 순서, 핑거프린트, TTL, git-status)를 수정합니다. 모니터링을 위해 응답 헤더와 SSE 사용량 데이터를 읽습니다.
 
-**하지 않는 것:** 프록시 또는 인터셉터에서 네트워크 호출을 하지 않습니다. 모든 텔레메트리는 `~/.claude/` 아래 로컬 파일에 기록됩니다. [claude-code-meter](https://github.com/cnighswonger/claude-code-meter) 공유에 명시적으로 동의하지 않는 한 데이터가 외부로 전송되지 않습니다(별도 패키지, 대화형 동의 필요).
+**하지 않는 것:** 프록시 또는 인터셉터에서 네트워크 호출을 하지 않습니다. 모든 텔레메트리는 `~/.claude/` 아래 로컬 파일에 기록됩니다. 데이터는 사용자의 컴퓨터를 떠나지 않습니다.
 
 **공급망:** 프록시 모드: `proxy/extensions/`에 7개 소형 확장 모듈(각 200줄 미만). 프리로드 모드: 단일 비축소 파일(`preload.mjs`, ~1,700줄). 개발 의존성 1개(`zod`, 테스트 스키마 검증용). 설치 전 코드를 직접 검토하십시오. npm provenance로 각 버전이 소스 커밋에 연결됩니다.
 

package/README.md

@@ -45,40 +45,44 @@ Extensions are hot-reloadable — add, remove, or modify `.mjs` files in `proxy/
 
 ### Running as a service
 
-**Linux (systemd — recommended):**
+**Recommended (Linux/macOS) — `install-service` subcommand:**
 
-Create `~/.config/systemd/user/cache-fix-proxy.service`:
+```bash
+cache-fix-proxy install-service
+```
 
-```ini
-[Unit]
-Description=Claude Code Cache Fix Proxy (v3.x)
-After=network.target
+Detects your platform and writes the appropriate config:
 
-[Service]
-Type=simple
-ExecStart=/usr/local/bin/node /path/to/claude-code-cache-fix/proxy/server.mjs
-Restart=on-failure
-RestartSec=5
-Environment=CACHE_FIX_PROXY_PORT=9801
+- **Linux** → `~/.config/systemd/user/cache-fix-proxy.service` (systemd user unit)
+- **macOS** → `~/Library/LaunchAgents/com.cnighswonger.cache-fix-proxy.plist` (launchd agent)
 
-[Install]
-WantedBy=default.target
-```
+The output prints the next-step commands to enable and start the service. On Linux:
 
 ```bash
 systemctl --user daemon-reload
 systemctl --user enable --now cache-fix-proxy
+systemctl --user enable --now cache-fix-proxy-healthcheck.timer   # auto-recovery — see below
+sudo loginctl enable-linger $USER   # optional: start on boot, not just on login
+```
+
+**Auto-recovery (Linux):** `install-service` also drops a healthcheck companion (`cache-fix-proxy-healthcheck.service` + `.timer`). The timer fires every 2 minutes; the oneshot service runs `curl -fs http://127.0.0.1:<port>/health` and `systemctl --user start cache-fix-proxy.service` if the probe fails. This recovers the proxy from any stop — clean or unclean, expected or unexpected — within 2 minutes. Background: `Restart=on-failure` doesn't fire on clean stops, so before this companion existed, a `systemctl stop` from any source (including unidentified ones during an Anthropic outage on 2026-04-25) would leave the proxy down indefinitely. macOS doesn't need the companion — launchd's `KeepAlive` already auto-restarts on any exit.
 
-# Optional: start on boot (before login)
-sudo loginctl enable-linger $USER
+On macOS:
+
+```bash
+launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.cnighswonger.cache-fix-proxy.plist
+launchctl enable gui/$(id -u)/com.cnighswonger.cache-fix-proxy
+launchctl kickstart gui/$(id -u)/com.cnighswonger.cache-fix-proxy
 ```
 
-A `cache-fix-proxy install-service` subcommand is planned for v3.1.0 ([#48](https://github.com/cnighswonger/claude-code-cache-fix/issues/48)).
+The installed config picks up `CACHE_FIX_PROXY_PORT`, `CACHE_FIX_PROXY_UPSTREAM`, and `CACHE_FIX_DEBUG` from the env at install time. Re-run `install-service --force` to regenerate after env changes, or edit the service file directly. Pair with `cache-fix-proxy uninstall-service` to remove cleanly (stops, disables, deletes).
 
-**Fallback (any OS):**
+The service runs `cache-fix-proxy server` in the foreground, which is just the proxy without the wrapper-mode claude launcher.
+
+**Manual (any platform):**
 
 ```bash
-nohup node "$(npm root -g)/claude-code-cache-fix/proxy/server.mjs" > /tmp/cache-fix-proxy.log 2>&1 &
+nohup cache-fix-proxy server > /tmp/cache-fix-proxy.log 2>&1 &
 echo 'export ANTHROPIC_BASE_URL=http://127.0.0.1:9801' >> ~/.bashrc
 ```
 
@@ -162,7 +166,7 @@ For manual VS Code wrapper setup (without the VSIX), see [docs/preload-setup.md]
 
 **What it does:** Modifies outgoing request structure (block order, fingerprint, TTL, git-status) to fix cache bugs. Reads response headers and SSE usage data for monitoring.
 
-**What it does NOT do:** No network calls from the proxy or interceptor. All telemetry is written to local files under `~/.claude/`. No data leaves your machine unless you explicitly opt in to [claude-code-meter](https://github.com/cnighswonger/claude-code-meter) sharing (separate package, requires interactive consent).
+**What it does NOT do:** No network calls from the proxy or interceptor. All telemetry is written to local files under `~/.claude/`. No data leaves your machine.
 
 **Supply chain:** Proxy mode: 7 small extension modules in `proxy/extensions/` (each under 200 lines). Preload mode: single unminified file (`preload.mjs`, ~1,700 lines). One dev dependency (`zod` for schema validation in tests only). Review before installing. npm provenance links each published version to its source commit.
 
@@ -281,6 +285,8 @@ export CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1
 
 Or add `"includeGitInstructions": false` to `~/.claude/settings.json`. Claude Code can still run `git status` via the Bash tool when it needs context. Community-validated by [@wadabum](https://github.com/cnighswonger/claude-code-cache-fix/issues/11): 18-token cache creation across git state changes (vs thousands without the flag).
 
+**Why we don't ship a proxy extension for this:** the proxy intercepts requests after Claude Code has already composed the system prompt — by then the volatile `git status` text is already part of the prefix that the model conditioned on in the previous turn, and stripping it post-hoc would itself bust the cache. The fix has to happen at the source. `CLAUDE_CODE_DISABLE_GIT_INSTRUCTIONS=1` prevents the injection before the prompt is composed, which is why the native flag is the right tool. Stripping post-hoc would also remove model-visible context that an explicit Bash call can recover, and would risk false-positive matches against assistant-written text.
+
 ## Image stripping (preload mode)
 
 Images read via the Read tool persist as base64 in conversation history, riding along on every subsequent API call. A single 500KB image costs ~62,500 tokens per turn on Opus 4.6, and **~85,000+ on Opus 4.7** due to the new tokenizer. Image stripping is strongly recommended on 4.7.

package/README.zh.md

@@ -137,7 +137,7 @@ NODE_OPTIONS="--import claude-code-cache-fix" claude
 
 **它做什么：** 修改出站请求结构（块排序、指纹、TTL、git-status）以修复缓存 bug。读取响应头和 SSE 使用量数据用于监控。
 
-**它不做什么：** 代理或拦截器不会发起网络调用。所有遥测数据写入 `~/.claude/` 下的本地文件。除非你明确选择加入 [claude-code-meter](https://github.com/cnighswonger/claude-code-meter) 共享（独立包，需要交互式同意），否则数据不会离开你的机器。
+**它不做什么：** 代理或拦截器不会发起网络调用。所有遥测数据写入 `~/.claude/` 下的本地文件。数据不会离开你的机器。
 
 **供应链：** 代理模式：7 个小型扩展模块在 `proxy/extensions/` 中（每个不到 200 行）。预加载模式：单个未压缩文件（`preload.mjs`，约 1,700 行）。一个开发依赖（`zod`，仅用于测试中的模式验证）。安装前请审查代码。npm 出处（provenance）将每个发布版本链接到其源代码提交。
 

package/bin/claude-via-proxy.mjs

@@ -9,6 +9,63 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const SERVER_PATH = resolve(__dirname, "../proxy/server.mjs");
 
 const args = process.argv.slice(2);
+const SUBCOMMAND = args[0];
+
+// Subcommand dispatch (must come before the wrapper-arg parser so subcommand
+// names don't get treated as claude args). Returns null when no subcommand
+// matched, signaling fall-through to wrapper mode below.
+async function dispatch() {
+  if (SUBCOMMAND === "server") {
+    return new Promise((resolveP) => {
+      const serverProc = spawn(process.execPath, [SERVER_PATH, ...args.slice(1)], {
+        stdio: "inherit",
+        env: process.env,
+      });
+      serverProc.on("close", (code) => resolveP(code ?? 0));
+      serverProc.on("error", (err) => {
+        process.stderr.write(`Failed to start proxy server: ${err.message}\n`);
+        resolveP(1);
+      });
+    });
+  }
+  if (SUBCOMMAND === "install-service") {
+    const force = args.includes("--force");
+    const { install } = await import("./install-service.mjs");
+    return install({ force });
+  }
+  if (SUBCOMMAND === "uninstall-service") {
+    const { uninstall } = await import("./install-service.mjs");
+    return uninstall();
+  }
+  if (SUBCOMMAND === "--help" || SUBCOMMAND === "-h" || SUBCOMMAND === "help") {
+    process.stdout.write(
+      "Usage: cache-fix-proxy [subcommand] [args]\n\n" +
+        "Subcommands:\n" +
+        "  (no subcommand)        Spawn the proxy + launch claude with ANTHROPIC_BASE_URL set.\n" +
+        "                         Pass any claude args after optional --proxy-port / --proxy-upstream.\n" +
+        "  server                 Run just the proxy in the foreground (for systemd/launchd ExecStart).\n" +
+        "  install-service        Install a systemd user service (Linux) or launchd agent (macOS).\n" +
+        "                         Pass --force to overwrite an existing config.\n" +
+        "  uninstall-service      Stop, disable, and remove the installed service.\n" +
+        "  help                   Show this help.\n\n" +
+        "Wrapper-mode flags:\n" +
+        "  --proxy-port <N>       Port for the spawned proxy (default 9801)\n" +
+        "  --proxy-upstream <URL> Upstream URL the proxy forwards to (default api.anthropic.com)\n" +
+        "\nEnvironment:\n" +
+        "  CACHE_FIX_PROXY_PORT     Port for the proxy server\n" +
+        "  CACHE_FIX_PROXY_UPSTREAM Upstream URL\n" +
+        "  CACHE_FIX_DEBUG=1        Verbose proxy logging\n" +
+        "  CACHE_FIX_CLAUDE_CMD     Override the `claude` command for the wrapper\n",
+    );
+    return 0;
+  }
+  return null;
+}
+
+const subcommandExit = await dispatch();
+if (subcommandExit !== null) process.exit(subcommandExit);
+
+// No subcommand matched → wrapper mode (back-compat with v3.0.x behavior).
 let proxyPort = 9801;
 let proxyUpstream = undefined;
 const claudeArgs = [];

package/bin/install-service.mjs

@@ -0,0 +1,476 @@
+// install-service / uninstall-service subcommands.
+//
+// Detects platform and installs an appropriate service definition for the
+// cache-fix proxy:
+//   - linux  → systemd user service at ~/.config/systemd/user/cache-fix-proxy.service
+//   - darwin → launchd agent at ~/Library/LaunchAgents/com.cnighswonger.cache-fix-proxy.plist
+//   - other  → prints manual instructions and exits non-zero
+//
+// Pure helpers exported for tests; orchestration lives in main().
+
+import { readFile, writeFile, mkdir, unlink, stat } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { dirname, resolve, join } from "node:path";
+import { homedir, platform } from "node:os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = resolve(__dirname, "..", "templates");
+const SERVER_PATH = resolve(__dirname, "..", "proxy", "server.mjs");
+
+function getDefaults() {
+  return {
+    port: validatePort(process.env.CACHE_FIX_PROXY_PORT || "9801"),
+    upstream: process.env.CACHE_FIX_PROXY_UPSTREAM || "",
+    debug: process.env.CACHE_FIX_DEBUG || "",
+    workingDir: resolve(__dirname, ".."),
+  };
+}
+
+// Validate that a port string is a plain decimal integer in [1, 65535].
+// We render this value into both a systemd Environment= line (safe) AND a
+// /bin/sh -c command in the healthcheck oneshot — DANGEROUS without
+// validation: shell metacharacters or quotes in a port string would let a
+// hostile env var change the executed command. Throw on invalid input so
+// callers report it cleanly via reportFsError.
+function validatePort(raw) {
+  if (typeof raw !== "string" && typeof raw !== "number") {
+    throw new InvalidPortError(`port must be a number or numeric string, got ${typeof raw}`);
+  }
+  const s = String(raw).trim();
+  if (!/^\d+$/.test(s)) {
+    throw new InvalidPortError(`port must be a positive integer (got ${JSON.stringify(raw)})`);
+  }
+  const n = Number(s);
+  if (n < 1 || n > 65535) {
+    throw new InvalidPortError(`port must be in 1..65535 (got ${n})`);
+  }
+  return s;
+}
+
+class InvalidPortError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "InvalidPortError";
+    this.code = "EINVAL";
+  }
+}
+
+function getPaths(plat = platform()) {
+  if (plat === "linux") {
+    return {
+      kind: "systemd",
+      configDir: join(homedir(), ".config", "systemd", "user"),
+      configFile: "cache-fix-proxy.service",
+      label: "cache-fix-proxy",
+      // Healthcheck companion units (oneshot service + timer) for
+      // auto-recovery if the proxy is ever stopped from any cause:
+      // a crash, an external `systemctl stop`, an OOM, anything.
+      // The timer runs the service every 2 minutes; the oneshot does
+      // a curl /health probe and `systemctl --user start` if it fails.
+      healthcheckServiceFile: "cache-fix-proxy-healthcheck.service",
+      healthcheckTimerFile: "cache-fix-proxy-healthcheck.timer",
+    };
+  }
+  if (plat === "darwin") {
+    return {
+      kind: "launchd",
+      configDir: join(homedir(), "Library", "LaunchAgents"),
+      configFile: "com.cnighswonger.cache-fix-proxy.plist",
+      label: "com.cnighswonger.cache-fix-proxy",
+      logDir: join(homedir(), "Library", "Logs"),
+      // launchd's KeepAlive already auto-restarts the agent on any exit
+      // (clean or unclean), so a separate healthcheck isn't needed on macOS.
+    };
+  }
+  return { kind: "unsupported", platform: plat };
+}
+
+function renderSystemdTemplate(template, vars) {
+  const upstreamLine = vars.upstream
+    ? `Environment=CACHE_FIX_PROXY_UPSTREAM=${vars.upstream}`
+    : "";
+  const debugLine = vars.debug
+    ? `Environment=CACHE_FIX_DEBUG=${vars.debug}`
+    : "";
+  // Allow callers to wire a Requires= line (e.g. another service the proxy
+  // chains to). Empty string by default so the unit has no extra deps.
+  const requiresLine = vars.requires
+    ? `Requires=${vars.requires}\nAfter=${vars.requires}`
+    : "";
+  return template
+    .replaceAll("{{NODE}}", vars.node)
+    .replaceAll("{{SERVER_PATH}}", vars.serverPath)
+    .replaceAll("{{PORT}}", vars.port)
+    .replaceAll("{{UPSTREAM_LINE}}", upstreamLine)
+    .replaceAll("{{DEBUG_LINE}}", debugLine)
+    .replaceAll("{{REQUIRES_LINE}}", requiresLine)
+    .replaceAll("{{WORKING_DIR}}", vars.workingDir)
+    // Collapse triple newlines from empty optional lines down to single blank
+    .replace(/\n\n\n+/g, "\n\n");
+}
+
+function renderLaunchdTemplate(template, vars) {
+  const upstreamPlist = vars.upstream
+    ? `        <key>CACHE_FIX_PROXY_UPSTREAM</key>\n        <string>${vars.upstream}</string>`
+    : "";
+  const debugPlist = vars.debug
+    ? `        <key>CACHE_FIX_DEBUG</key>\n        <string>${vars.debug}</string>`
+    : "";
+  return template
+    .replaceAll("{{NODE}}", vars.node)
+    .replaceAll("{{SERVER_PATH}}", vars.serverPath)
+    .replaceAll("{{PORT}}", vars.port)
+    .replaceAll("{{UPSTREAM_PLIST}}", upstreamPlist)
+    .replaceAll("{{DEBUG_PLIST}}", debugPlist)
+    .replaceAll("{{WORKING_DIR}}", vars.workingDir)
+    .replaceAll("{{LOG_DIR}}", vars.logDir)
+    .replace(/\n\n+/g, "\n");
+}
+
+function renderHealthcheckServiceTemplate(template, vars) {
+  return template.replaceAll("{{PORT}}", vars.port);
+}
+
+function renderHealthcheckTimerTemplate(template) {
+  // No placeholders today, but keep the function for symmetry + future expansion.
+  return template;
+}
+
+async function fileExists(path) {
+  try {
+    await stat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runCmd(cmd, args, opts = {}) {
+  return new Promise((resolveP) => {
+    const p = spawn(cmd, args, { stdio: "inherit", ...opts });
+    p.on("close", (code) => resolveP(code ?? 0));
+    p.on("error", () => resolveP(127));
+  });
+}
+
+async function installSystemd({ paths, defaults, force = false } = {}) {
+  paths = paths || getPaths("linux");
+  defaults = defaults || getDefaults();
+  const targetPath = join(paths.configDir, paths.configFile);
+  if ((await fileExists(targetPath)) && !force) {
+    return {
+      ok: false,
+      reason: "already-installed",
+      path: targetPath,
+      hint: "Re-run with --force to overwrite, or `cache-fix-proxy uninstall-service` first.",
+    };
+  }
+  const template = await readFile(
+    join(TEMPLATE_DIR, "cache-fix-proxy.service.template"),
+    "utf-8",
+  );
+  const rendered = renderSystemdTemplate(template, {
+    node: process.execPath,
+    serverPath: SERVER_PATH,
+    port: defaults.port,
+    upstream: defaults.upstream,
+    debug: defaults.debug,
+    workingDir: defaults.workingDir,
+    requires: "",
+  });
+  await mkdir(paths.configDir, { recursive: true });
+  await writeFile(targetPath, rendered);
+
+  // Healthcheck companion: oneshot service + timer. Auto-recovery from any
+  // proxy stop, including clean stops where Restart=on-failure does NOT fire
+  // (see incident analysis: 2026-04-25 01:46:53 UTC — proxy was stopped by
+  // an unidentified caller during the Anthropic outage and stayed down for
+  // 10 hours because no auto-recovery existed).
+  //
+  // If the healthcheck install fails (template missing, write error, etc.),
+  // roll back the main unit so the user isn't left in a half-installed
+  // state. Without rollback the proxy unit would exist but the auto-recovery
+  // story we just promised in the install message would be incomplete.
+  let healthcheckPaths;
+  try {
+    healthcheckPaths = await installSystemdHealthcheck({ paths, defaults, force });
+  } catch (err) {
+    try {
+      await unlink(targetPath);
+    } catch {
+      /* best-effort rollback */
+    }
+    throw err;
+  }
+
+  return {
+    ok: true,
+    path: targetPath,
+    healthcheck: healthcheckPaths,
+  };
+}
+
+async function installSystemdHealthcheck({ paths, defaults, force = false } = {}) {
+  paths = paths || getPaths("linux");
+  defaults = defaults || getDefaults();
+  const servicePath = join(paths.configDir, paths.healthcheckServiceFile);
+  const timerPath = join(paths.configDir, paths.healthcheckTimerFile);
+
+  // Symmetric existence check: if EITHER the service file OR the timer file
+  // already exists, refuse to overwrite without force. Catches both the
+  // "service exists, timer missing" and "timer exists, service missing"
+  // half-states — those are the artifacts most likely to need explicit
+  // operator review (e.g. a previous install crashed mid-write, or the
+  // operator has hand-edited one of the two).
+  const serviceExists = await fileExists(servicePath);
+  const timerExists = await fileExists(timerPath);
+  if ((serviceExists || timerExists) && !force) {
+    const which = serviceExists && timerExists
+      ? "both files"
+      : serviceExists
+        ? "service file"
+        : "timer file";
+    return {
+      installed: false,
+      reason: "already-installed",
+      servicePath,
+      timerPath,
+      hint: `${which} already present. Re-run with --force to overwrite, or \`cache-fix-proxy uninstall-service\` first.`,
+    };
+  }
+
+  const serviceTpl = await readFile(
+    join(TEMPLATE_DIR, "cache-fix-proxy-healthcheck.service.template"),
+    "utf-8",
+  );
+  const timerTpl = await readFile(
+    join(TEMPLATE_DIR, "cache-fix-proxy-healthcheck.timer.template"),
+    "utf-8",
+  );
+  await writeFile(servicePath, renderHealthcheckServiceTemplate(serviceTpl, { port: defaults.port }));
+  await writeFile(timerPath, renderHealthcheckTimerTemplate(timerTpl));
+  return { installed: true, servicePath, timerPath };
+}
+
+async function installLaunchd({ paths, defaults, force = false } = {}) {
+  paths = paths || getPaths("darwin");
+  defaults = defaults || getDefaults();
+  const targetPath = join(paths.configDir, paths.configFile);
+  if ((await fileExists(targetPath)) && !force) {
+    return {
+      ok: false,
+      reason: "already-installed",
+      path: targetPath,
+      hint: "Re-run with --force to overwrite, or `cache-fix-proxy uninstall-service` first.",
+    };
+  }
+  const template = await readFile(
+    join(TEMPLATE_DIR, "com.cnighswonger.cache-fix-proxy.plist.template"),
+    "utf-8",
+  );
+  const rendered = renderLaunchdTemplate(template, {
+    node: process.execPath,
+    serverPath: SERVER_PATH,
+    port: defaults.port,
+    upstream: defaults.upstream,
+    debug: defaults.debug,
+    workingDir: defaults.workingDir,
+    logDir: paths.logDir,
+  });
+  await mkdir(paths.configDir, { recursive: true });
+  await writeFile(targetPath, rendered);
+  return { ok: true, path: targetPath };
+}
+
+async function uninstallSystemd({ paths } = {}) {
+  paths = paths || getPaths("linux");
+  const targetPath = join(paths.configDir, paths.configFile);
+  if (!(await fileExists(targetPath))) {
+    return { ok: false, reason: "not-installed", path: targetPath };
+  }
+  await unlink(targetPath);
+  // Also remove the healthcheck companion if it exists. Best-effort —
+  // missing files are not an error here.
+  const healthcheckRemoved = await uninstallSystemdHealthcheck({ paths });
+  return { ok: true, path: targetPath, healthcheck: healthcheckRemoved };
+}
+
+async function uninstallSystemdHealthcheck({ paths } = {}) {
+  paths = paths || getPaths("linux");
+  const servicePath = join(paths.configDir, paths.healthcheckServiceFile);
+  const timerPath = join(paths.configDir, paths.healthcheckTimerFile);
+  let removed = 0;
+  for (const p of [timerPath, servicePath]) {
+    if (await fileExists(p)) {
+      try {
+        await unlink(p);
+        removed++;
+      } catch {
+        /* best-effort */
+      }
+    }
+  }
+  return { removed, servicePath, timerPath };
+}
+
+async function uninstallLaunchd({ paths } = {}) {
+  paths = paths || getPaths("darwin");
+  const targetPath = join(paths.configDir, paths.configFile);
+  if (!(await fileExists(targetPath))) {
+    return { ok: false, reason: "not-installed", path: targetPath };
+  }
+  await unlink(targetPath);
+  return { ok: true, path: targetPath };
+}
+
+async function install({ force = false } = {}) {
+  const paths = getPaths();
+  if (paths.kind === "unsupported") {
+    process.stderr.write(
+      `[install-service] Unsupported platform: ${paths.platform}\n` +
+        `Manual install: run \`node ${SERVER_PATH}\` under your platform's service manager.\n`,
+    );
+    return 1;
+  }
+  if (paths.kind === "systemd") {
+    let r;
+    try {
+      r = await installSystemd({ paths, force });
+    } catch (err) {
+      return reportFsError("install-service", err);
+    }
+    if (!r.ok) {
+      process.stderr.write(`[install-service] ${r.reason}: ${r.path}\n`);
+      if (r.hint) process.stderr.write(`  ${r.hint}\n`);
+      return 1;
+    }
+    const hcLines =
+      r.healthcheck?.installed
+        ? `Wrote healthcheck companion: ${r.healthcheck.servicePath}\n` +
+          `Wrote healthcheck timer:     ${r.healthcheck.timerPath}\n\n`
+        : r.healthcheck?.reason === "already-installed"
+          ? `Healthcheck companion already installed (use --force to overwrite).\n\n`
+          : "";
+    process.stdout.write(
+      `Wrote systemd unit: ${r.path}\n` +
+        hcLines +
+        `Next steps:\n` +
+        `  systemctl --user daemon-reload\n` +
+        `  systemctl --user enable --now cache-fix-proxy\n` +
+        `  systemctl --user enable --now cache-fix-proxy-healthcheck.timer  # auto-recovery if proxy is ever stopped\n` +
+        `  loginctl enable-linger ${process.env.USER || "<your-user>"}      # optional: start on boot vs login\n`,
+    );
+    return 0;
+  }
+  if (paths.kind === "launchd") {
+    let r;
+    try {
+      r = await installLaunchd({ paths, force });
+    } catch (err) {
+      return reportFsError("install-service", err);
+    }
+    if (!r.ok) {
+      process.stderr.write(`[install-service] ${r.reason}: ${r.path}\n`);
+      if (r.hint) process.stderr.write(`  ${r.hint}\n`);
+      return 1;
+    }
+    process.stdout.write(
+      `Wrote launchd plist: ${r.path}\n\n` +
+        `Next steps:\n` +
+        `  launchctl bootstrap gui/$(id -u) ${r.path}\n` +
+        `  launchctl enable gui/$(id -u)/com.cnighswonger.cache-fix-proxy\n` +
+        `  launchctl kickstart gui/$(id -u)/com.cnighswonger.cache-fix-proxy\n`,
+    );
+    return 0;
+  }
+  return 1;
+}
+
+// Translate raw fs / validation errors into operator-friendly one-liners.
+// Returns the exit code so callers can pass it straight back.
+function reportFsError(prefix, err) {
+  const code = err?.code ?? "";
+  let hint = "";
+  if (err?.name === "InvalidPortError") hint = err.message;
+  else if (code === "ENOENT") hint = "file or directory not found";
+  else if (code === "EACCES" || code === "EPERM") hint = "permission denied";
+  else if (code === "ENOSPC") hint = "no space left on device";
+  else hint = err?.message || String(err);
+  process.stderr.write(`[${prefix}] ${hint}${err?.path ? `: ${err.path}` : ""}\n`);
+  return 1;
+}
+
+async function uninstall() {
+  const paths = getPaths();
+  if (paths.kind === "unsupported") {
+    process.stderr.write(`[uninstall-service] Unsupported platform: ${paths.platform}\n`);
+    return 1;
+  }
+  if (paths.kind === "systemd") {
+    // Best-effort stop + disable for the healthcheck companion FIRST so it
+    // doesn't immediately restart the proxy we're about to stop.
+    await runCmd("systemctl", ["--user", "stop", "cache-fix-proxy-healthcheck.timer"]);
+    await runCmd("systemctl", ["--user", "disable", "cache-fix-proxy-healthcheck.timer"]);
+    // Then stop + disable the main service.
+    await runCmd("systemctl", ["--user", "stop", "cache-fix-proxy"]);
+    await runCmd("systemctl", ["--user", "disable", "cache-fix-proxy"]);
+    let r;
+    try {
+      r = await uninstallSystemd({ paths });
+    } catch (err) {
+      return reportFsError("uninstall-service", err);
+    }
+    if (!r.ok) {
+      process.stderr.write(`[uninstall-service] ${r.reason}: ${r.path}\n`);
+      return 1;
+    }
+    await runCmd("systemctl", ["--user", "daemon-reload"]);
+    const hcMsg =
+      r.healthcheck?.removed > 0
+        ? ` (+ ${r.healthcheck.removed} healthcheck file${r.healthcheck.removed === 1 ? "" : "s"})`
+        : "";
+    process.stdout.write(`Removed: ${r.path}${hcMsg}\n`);
+    return 0;
+  }
+  if (paths.kind === "launchd") {
+    const targetPath = join(paths.configDir, paths.configFile);
+    await runCmd("launchctl", ["bootout", `gui/${process.getuid()}`, targetPath]);
+    let r;
+    try {
+      r = await uninstallLaunchd({ paths });
+    } catch (err) {
+      return reportFsError("uninstall-service", err);
+    }
+    if (!r.ok) {
+      process.stderr.write(`[uninstall-service] ${r.reason}: ${r.path}\n`);
+      return 1;
+    }
+    process.stdout.write(`Removed: ${r.path}\n`);
+    return 0;
+  }
+  return 1;
+}
+
+export {
+  // Pure helpers (test surface)
+  renderSystemdTemplate,
+  renderLaunchdTemplate,
+  renderHealthcheckServiceTemplate,
+  renderHealthcheckTimerTemplate,
+  getPaths,
+  getDefaults,
+  validatePort,
+  InvalidPortError,
+  installSystemd,
+  installSystemdHealthcheck,
+  installLaunchd,
+  uninstallSystemd,
+  uninstallSystemdHealthcheck,
+  uninstallLaunchd,
+  // Orchestration
+  install,
+  uninstall,
+  TEMPLATE_DIR,
+  SERVER_PATH,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-cache-fix",
-  "version": "3.0.5",
+  "version": "3.1.1",
   "description": "Cache optimization proxy and interceptor for Claude Code. Fixes prompt cache bugs, stabilizes prefix, reduces quota burn.",
   "type": "module",
   "exports": "./preload.mjs",
@@ -14,7 +14,8 @@
     "tools/",
     "claude-fixed.bat",
     "proxy/",
-    "bin/"
+    "bin/",
+    "templates/"
   ],
   "engines": {
     "node": ">=18"

package/proxy/extensions/cache-control-normalize.mjs

@@ -24,6 +24,8 @@ function countUserCacheControlMarkers(body) {
   return n;
 }
 
+export { stripCacheControlMarkers, countUserCacheControlMarkers };
+
 export default {
   name: "cache-control-normalize",
   description: "Strip scattered cache_control markers from user messages and apply canonical placement",