quotacap 0.0.24 → 0.0.26

package/README.md

@@ -117,11 +117,11 @@ curl -X PATCH http://localhost:8787/api/providers/claude \
 
 ## Security
 
-QuotaCap is a local daemon. It binds to `127.0.0.1` only (`src/cli/index.ts:56`). It does not listen on `0.0.0.0`. There is no LAN surface.
+QuotaCap is a local daemon. It binds to `127.0.0.1` only (`src/runtime/service.ts` `app.listen`). It does not listen on `0.0.0.0`. There is no LAN surface.
 
 It owns no tokens. It never reads `~/.codex/auth.json`, `~/.kimi-code/credentials/kimi-code.json`, `~/.kimi/credentials/kimi-code.json`, `~/.grok/auth.json`, or `~/.gemini/oauth_creds.json`. It never uses `refresh_token` or `grant_type=refresh_token`. It has no hardcoded client ids. Those OAuth paths and the `.qc-bak` and `.qc-lock` helpers were removed in #14. This is asserted by `tests/adapters/credential-free.test.ts`. Each CLI owns its own session. It never reads `~/.config/muse/auth.json`, `~/.local/share/muse/sessions/`, or `~/.config/muse/tui-history.jsonl`. Each CLI owns its own session. QuotaCap only spawns the CLI and reads its stdout via `exec` (`claude`, `agy`) or PTY (`codex`, `kimi`, `grok`, `muse`).
 
-It stores no `raw` provider payload. The `raw` column was dropped and migrated in `src/store/db.ts:37-48`. `GET /api/quotas` and MCP `get_quotas` never return `raw` (`tests/http/api.test.ts`). History and the token live under `~/.quotacap/` with `0700` on the directory and `0600` on files.
+It stores no `raw` provider payload. The `raw` column was dropped and migrated in `src/store/db.ts` `migrate`. `GET /api/quotas` and MCP `get_quotas` never return `raw` (`tests/http/api.test.ts`). History and the token live under `~/.quotacap/` with `0700` on the directory and `0600` on files.
 
 Every request checks `Host` and `Origin`. `Host` must be loopback (`127.0.0.1`, `localhost`, `[::1]`), otherwise `403`. `Origin` when present must be loopback, otherwise `403`. Absent `Origin` passes for `curl` and MCP. `POST /api/refresh` requires `X-QuotaCap-Token` matching `~/.quotacap/token` with `crypto.timingSafeEqual` (`src/http/server.ts:isValidToken`), otherwise `401`. `GET /assets/*` is rooted with `path.resolve` and a prefix check (`tests/http/api.test.ts`).
 

package/dist/cli/takeover.d.ts

@@ -49,6 +49,7 @@ export interface TakeoverSharedOpts extends WaitOpts {
 export interface ManagedTakeoverOpts extends TakeoverSharedOpts {
     health: HealthView;
     execService?: ExecServiceFn;
+    refreshRegistration?: boolean;
 }
 export declare function takeoverManaged(opts: ManagedTakeoverOpts): Promise<{
     oldVersion: string;

package/dist/cli/takeover.js

@@ -118,9 +118,10 @@ export async function takeoverManaged(opts) {
         ? opts.health.version
         : "unknown";
     const execService = opts.execService ?? ((args, o) => runServiceCommand(args, o ?? {}, {}));
-    const code = await execService(["restart"]);
+    const verb = opts.refreshRegistration ? "install" : "restart";
+    const code = await execService([verb], opts.refreshRegistration ? { version: cliVersion } : undefined);
     if (code !== 0) {
-        throw new TakeoverError(`daemon upgrade failed: service restart exited ${code}`);
+        throw new TakeoverError(`daemon upgrade failed: service ${verb} exited ${code}`);
     }
     const healthy = await waitForHealthy(opts.port, cliVersion, opts);
     if (!healthy) {

package/dist/cli/update.js

@@ -4,7 +4,7 @@ import { ensureConfig, getDbPath } from "../config.js";
 import { createServiceClient, ServiceError, ServiceUnavailable, } from "../runtime/client.js";
 import { readClaim } from "../runtime/owner.js";
 import { compareVersions } from "../runtime/versions.js";
-import { detectChannel, resolveLatestVersion, updateNpm, updateStandalone, writeUpdateCache, } from "../runtime/updates.js";
+import { detectChannel, resolveLatestVersionDetailed, updateNpm, updateStandalone, writeUpdateCache, } from "../runtime/updates.js";
 import { isServiceManaged, runServiceCommand } from "../service/index.js";
 import { checkSkew, formatWedged, olderCliWarning, takeoverManaged, takeoverUnmanaged, WedgedError, } from "./takeover.js";
 export function stoppedDaemonMessage(oldVersion, newVersion) {
@@ -36,8 +36,10 @@ function unknownRefusal() {
 }
 // Restart the running daemon onto the just-installed target version. Unlike
 // the skew paths in web/status/advise, the comparison version is the target
-// (the running CLI is still the old binary), and the unmanaged path leaves
-// the daemon stopped with guidance instead of foreground-starting.
+// (the running CLI is still the old binary), the managed path refreshes the
+// service registration instead of only restarting (regenerating the
+// supervisor PATH), and the unmanaged path leaves the daemon stopped with
+// guidance instead of foreground-starting.
 export async function postUpdateTakeover(opts) {
     const { target, port } = opts;
     const dataDir = opts.dataDir ?? path.dirname(getDbPath());
@@ -87,6 +89,7 @@ export async function postUpdateTakeover(opts) {
                 cliExec: execPath,
                 createClient,
                 execService,
+                refreshRegistration: true,
                 ...takeoverOpts,
             });
             return { notes: [r.message], warnings: [], error: null, exitCode: 0 };
@@ -134,6 +137,17 @@ export async function postUpdateTakeover(opts) {
 function stripV(v) {
     return v.startsWith("v") ? v.slice(1) : v;
 }
+// A rate-limited response names its reset (local HH:MM) and the pin escape
+// hatch; every other failure keeps the generic network message.
+function rateLimitError(resetsAtMs) {
+    const hint = "or run 'quotacap update --to <version>'";
+    if (resetsAtMs === null) {
+        return `GitHub's anonymous API rate limit is exhausted; retry later, ${hint}`;
+    }
+    const d = new Date(resetsAtMs);
+    const hhmm = `${String(d.getHours()).padStart(2, "0")}:${String(d.getMinutes()).padStart(2, "0")}`;
+    return `GitHub's anonymous API rate limit is exhausted (resets ${hhmm}); retry then, ${hint}`;
+}
 export function registerUpdateCommand(program, deps) {
     const exit = deps?.exit ?? process.exit;
     const fetchFn = deps?.fetchFn ?? fetch;
@@ -143,7 +157,7 @@ export function registerUpdateCommand(program, deps) {
         .command("update")
         .description("check for and apply updates")
         .option("--check", "only check for updates, changing nothing")
-        .option("--version <v>", "update to a specific version")
+        .option("--to <version>", "update to a specific version")
         .option("--json", "machine-readable output")
         .action(async (o) => {
         const current = VERSION;
@@ -173,17 +187,24 @@ export function registerUpdateCommand(program, deps) {
             exit(1);
             return;
         }
-        const pin = typeof o.version === "string" && o.version ? stripV(o.version) : null;
+        const pin = typeof o.to === "string" && o.to ? stripV(o.to) : null;
         let latest = null;
+        let rateLimited = null;
         try {
-            latest = await resolveLatestVersion({ fetchFn });
+            const resolved = await resolveLatestVersionDetailed({ fetchFn });
+            if (resolved.status === "ok")
+                latest = resolved.release;
+            else if (resolved.status === "rate-limited")
+                rateLimited = resolved;
         }
         catch {
             latest = null;
         }
         const target = pin ?? latest?.version ?? null;
         if (!target) {
-            const error = "could not resolve the latest release; check your network and retry";
+            const error = rateLimited
+                ? rateLimitError(rateLimited.resetsAtMs)
+                : "could not resolve the latest release; check your network and retry";
             if (asJson) {
                 emit({
                     channel,

package/dist/config.d.ts

@@ -6,18 +6,21 @@ declare const ConfigSchema: z.ZodObject<{
     port: z.ZodDefault<z.ZodNumber>;
     pollMinutes: z.ZodDefault<z.ZodNumber>;
     enabledProviders: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    knownProviders: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
     providerNames: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodEffects<z.ZodString, string, string>, string, string>>>;
     experimentalIngest: z.ZodOptional<z.ZodBoolean>;
 }, "strip", z.ZodTypeAny, {
     port: number;
     pollMinutes: number;
     enabledProviders: string[];
+    knownProviders: string[];
     providerNames: Record<string, string>;
     experimentalIngest?: boolean | undefined;
 }, {
     port?: number | undefined;
     pollMinutes?: number | undefined;
     enabledProviders?: string[] | undefined;
+    knownProviders?: string[] | undefined;
     providerNames?: Record<string, string> | undefined;
     experimentalIngest?: boolean | undefined;
 }>;
@@ -45,6 +48,28 @@ export declare function writeConfig(c: Config, p?: string): Promise<void>;
  */
 export declare function setProviderNameOverride(id: string, displayName: string | null, p?: string): Promise<void>;
 export declare function resetAllProviderNameOverrides(p?: string): Promise<void>;
+export declare const LEGACY_KNOWN_PROVIDERS: string[];
+export interface AutoEnableDeps {
+    configPath?: string;
+    which?: (bin: string) => string | null;
+}
+export interface AutoEnableResult {
+    enabledProviders: string[];
+    knownProviders: string[];
+    changed: boolean;
+}
+/**
+ * Auto-enable newly shipped adapters. For each registered adapter (minus
+ * `manual`, which has no CLI binary) absent from knownProviders, resolve its
+ * binary on PATH and append it to both lists when found. An adapter whose
+ * binary is missing stays unknown so it is re-checked on the next start; a
+ * provider already known but disabled is never re-added. Raw-JSON mutation
+ * like setProviderNameOverride: unknown keys are preserved, never a schema
+ * round-trip. Returns null when the file is missing, unparseable, or
+ * structurally off, so readServiceConfig keeps owning that error; throws
+ * only when a decided write fails. Persists only when something changed.
+ */
+export declare function autoEnableNewProviders(deps?: AutoEnableDeps): Promise<AutoEnableResult | null>;
 export interface ServiceMetadata {
     version: string;
     exec: string;

package/dist/config.js

@@ -1,5 +1,6 @@
 import fs from "node:fs/promises";
 import fsSync from "node:fs";
+import { execFileSync } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
 import { z } from "zod";
@@ -33,6 +34,7 @@ const ConfigSchema = z.object({
     port: z.number().default(8787),
     pollMinutes: z.number().default(15),
     enabledProviders: z.array(z.string()).default(["claude", "codex", "kimi", "grok", "agy", "muse"]),
+    knownProviders: z.array(z.string()).default(["claude", "codex", "kimi", "grok", "agy", "muse"]),
     providerNames: z.record(z.string(), ProviderDisplayNameSchema).default({}),
     // Optional, omitted from defaults and `init` output. Manual ingest stays
     // in-tree but is not a public surface until the product design lands.
@@ -94,6 +96,10 @@ const ServiceConfigSchema = z.object({
             });
         }
     }),
+    // Machine-managed by autoEnableNewProviders: ids are deliberately NOT
+    // validated against the registry, so a stale entry can never brick daemon
+    // start. A non-array still fails naming the field.
+    knownProviders: z.array(z.string()).default(["claude", "codex", "kimi", "grok", "agy", "muse"]),
     providerNames: z.record(z.string(), ProviderDisplayNameSchema).default({}),
     experimentalIngest: z.boolean().optional(),
 });
@@ -220,6 +226,102 @@ export async function resetAllProviderNameOverrides(p) {
     await fs.mkdir(path.dirname(file), { recursive: true });
     await fs.writeFile(file, JSON.stringify(rawObj, null, 2) + "\n");
 }
+// Frozen pre-auto-enable provider set. Configs written before knownProviders
+// existed are seeded with exactly these five, so any adapter shipped later
+// reads as new. Never extend this list: seeding from the live registry would
+// mark every adapter known and silently disable auto-enable.
+export const LEGACY_KNOWN_PROVIDERS = ["claude", "codex", "kimi", "grok", "agy"];
+// PATH lookup kept local: importing the sibling in src/service/macos.ts
+// would create a config<->service import cycle.
+function defaultWhich(bin) {
+    try {
+        const out = execFileSync("which", [bin], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        }).trim();
+        return out.length > 0 ? out : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Auto-enable newly shipped adapters. For each registered adapter (minus
+ * `manual`, which has no CLI binary) absent from knownProviders, resolve its
+ * binary on PATH and append it to both lists when found. An adapter whose
+ * binary is missing stays unknown so it is re-checked on the next start; a
+ * provider already known but disabled is never re-added. Raw-JSON mutation
+ * like setProviderNameOverride: unknown keys are preserved, never a schema
+ * round-trip. Returns null when the file is missing, unparseable, or
+ * structurally off, so readServiceConfig keeps owning that error; throws
+ * only when a decided write fails. Persists only when something changed.
+ */
+export async function autoEnableNewProviders(deps) {
+    const file = getConfigPath(deps?.configPath);
+    let rawObj;
+    try {
+        const parsed = JSON.parse(await fs.readFile(file, "utf8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+            return null;
+        }
+        rawObj = parsed;
+    }
+    catch {
+        return null;
+    }
+    if (("enabledProviders" in rawObj && !Array.isArray(rawObj.enabledProviders)) ||
+        ("knownProviders" in rawObj && !Array.isArray(rawObj.knownProviders))) {
+        return null;
+    }
+    const which = deps?.which ?? defaultWhich;
+    const prevEnabled = Array.isArray(rawObj.enabledProviders)
+        ? rawObj.enabledProviders
+        : defaultConfig().enabledProviders;
+    const prevKnown = Array.isArray(rawObj.knownProviders)
+        ? rawObj.knownProviders
+        : LEGACY_KNOWN_PROVIDERS;
+    const enabled = [...prevEnabled];
+    const known = [...prevKnown];
+    for (const id of Object.keys(adapters)) {
+        if (id === "manual" || known.includes(id))
+            continue;
+        let resolved = null;
+        try {
+            resolved = which(id);
+        }
+        catch {
+            resolved = null;
+        }
+        if (!resolved)
+            continue;
+        if (!enabled.includes(id))
+            enabled.push(id);
+        known.push(id);
+    }
+    const changed = JSON.stringify(enabled) !== JSON.stringify(prevEnabled) ||
+        JSON.stringify(known) !== JSON.stringify(prevKnown);
+    if (!changed) {
+        return {
+            enabledProviders: enabled,
+            knownProviders: known,
+            changed: false,
+        };
+    }
+    rawObj.enabledProviders = enabled;
+    rawObj.knownProviders = known;
+    try {
+        await fs.mkdir(path.dirname(file), { recursive: true });
+        await fs.writeFile(file, JSON.stringify(rawObj, null, 2) + "\n");
+    }
+    catch (err) {
+        throw new Error(`cannot update provider enablement: failed to write ${file}: ${err?.message ?? err}`);
+    }
+    return {
+        enabledProviders: enabled,
+        knownProviders: known,
+        changed: true,
+    };
+}
 export function serviceMetadataPath(dataDir = path.dirname(getDbPath())) {
     return path.join(dataDir, "service.json");
 }

package/dist/runtime/service.js

@@ -11,7 +11,7 @@ import { createCoordinator } from "./poll.js";
 import { killAll } from "./spawn.js";
 import { ensureToken } from "./token.js";
 import { openDb, migrate } from "../store/db.js";
-import { ensureConfig, getConfigPath, getDbPath, isExperimentalIngestEnabled, readServiceConfig, readServiceMetadata } from "../config.js";
+import { autoEnableNewProviders, ensureConfig, getConfigPath, getDbPath, isExperimentalIngestEnabled, readServiceConfig, readServiceMetadata } from "../config.js";
 import { buildApp } from "../http/server.js";
 import { detectChannel, refreshUpdateCache } from "./updates.js";
 import { VERSION } from "../version.js";
@@ -115,10 +115,17 @@ export async function startService(opts) {
         exit(1);
         throw err instanceof Error ? err : new Error(String(err));
     };
-    // 1. Provision config when absent, then strict validation (a present-but-
-    // invalid file still fails naming the field). The daemon always leaves a
-    // real file behind.
+    // 1. Provision config when absent, auto-enable newly shipped adapters,
+    // then strict validation (a present-but-invalid file still fails naming
+    // the field). The daemon always leaves a real file behind. Auto-enable
+    // runs before validation on every start so all upgrade channels (npm,
+    // brew, installer, manual binary swap) pick up new adapters; a failed
+    // migration warns and continues with the unmigrated file instead of
+    // refusing to serve.
     await ensureConfig().catch((e) => fail(e));
+    await autoEnableNewProviders().catch((e) => {
+        console.warn(`[quotacap] provider auto-enable skipped: ${e instanceof Error ? e.message : String(e)}`);
+    });
     const config = await readServiceConfig().catch((e) => fail(e));
     const port = opts?.port ?? config.port;
     const dataDir = opts?.dataDir ?? path.dirname(getDbPath());

package/dist/runtime/updates.d.ts

@@ -13,7 +13,21 @@ export interface ReleaseInfo {
     url: string;
 }
 export declare function releasesApiUrl(): string;
+export declare function releasesPageUrl(): string;
 export declare function releaseDownloadBase(version: string): string;
+export type LatestVersionResolution = {
+    status: "ok";
+    release: ReleaseInfo;
+} | {
+    status: "rate-limited";
+    resetsAtMs: number | null;
+} | {
+    status: "unavailable";
+};
+export declare function resolveLatestVersionDetailed(opts?: {
+    fetchFn?: typeof fetch;
+    timeoutMs?: number;
+}): Promise<LatestVersionResolution>;
 export declare function resolveLatestVersion(opts?: {
     fetchFn?: typeof fetch;
     timeoutMs?: number;
@@ -23,11 +37,13 @@ export interface UpdateCache {
     latest: string;
     channel: string;
     current: string;
+    lastFailureAt?: string;
 }
 export declare function updatesCachePath(): string;
 export declare function readUpdateCache(p?: string): UpdateCache | null;
 export declare function writeUpdateCache(cache: UpdateCache, p?: string): void;
 export declare const UPDATE_CACHE_TTL_MS: number;
+export declare const UPDATE_FAILURE_RETRY_MS: number;
 export declare function updateCacheStale(cache: UpdateCache | null, nowMs?: number): boolean;
 export declare function refreshUpdateCache(opts: {
     channel: string;

package/dist/runtime/updates.js

@@ -129,6 +129,33 @@ export function releasesApiUrl() {
         return `${base}/api/releases/latest`;
     return "https://api.github.com/repos/carlosboeing/quotacap/releases/latest";
 }
+// Default version endpoint: the releases page answers 302 to the latest tag
+// and sits outside the anonymous API rate-limit bucket shared with every
+// other API consumer on the machine.
+export function releasesPageUrl() {
+    return "https://github.com/carlosboeing/quotacap/releases/latest";
+}
+// Header read that tolerates real Headers and the plain-object headers that
+// hermetic fetch mocks use.
+function responseHeader(res, name) {
+    const headers = res.headers;
+    if (!headers)
+        return null;
+    if (typeof headers.get === "function") {
+        return headers.get(name);
+    }
+    if (typeof headers === "object") {
+        for (const [k, v] of Object.entries(headers)) {
+            if (k.toLowerCase() === name && typeof v === "string")
+                return v;
+        }
+    }
+    return null;
+}
+function tagFromReleaseUrl(location) {
+    const m = /\/releases\/tag\/([^/?#]+)/.exec(location);
+    return m ? m[1] : "";
+}
 export function releaseDownloadBase(version) {
     const base = process.env.QUOTACAP_RELEASE_BASE_URL?.replace(/\/+$/, "");
     if (base)
@@ -137,32 +164,66 @@ export function releaseDownloadBase(version) {
         ? "https://github.com/carlosboeing/quotacap/releases/latest/download"
         : `https://github.com/carlosboeing/quotacap/releases/download/v${version}`;
 }
-// Latest published version, or null when the release cannot be resolved
-// (network failure, non-200, bad JSON, unparseable tag). Never throws.
-export async function resolveLatestVersion(opts = {}) {
+function rateLimitOrUnavailable(res) {
+    if (responseHeader(res, "x-ratelimit-remaining") === "0") {
+        const reset = responseHeader(res, "x-ratelimit-reset");
+        const secs = reset !== null && reset.trim() !== "" ? Number(reset) : NaN;
+        return {
+            status: "rate-limited",
+            resetsAtMs: Number.isFinite(secs) ? secs * 1000 : null,
+        };
+    }
+    return { status: "unavailable" };
+}
+// Full resolution outcome: the release, a rate-limited response carrying its
+// reset time, or an undifferentiated failure. Never throws.
+export async function resolveLatestVersionDetailed(opts = {}) {
     const fetchFn = opts.fetchFn ?? fetch;
     const timeoutMs = opts.timeoutMs ?? 10000;
+    const base = process.env.QUOTACAP_RELEASE_BASE_URL?.replace(/\/+$/, "");
     try {
-        const res = await fetchFn(releasesApiUrl(), {
-            headers: { accept: "application/vnd.github+json" },
+        if (base) {
+            const res = await fetchFn(releasesApiUrl(), {
+                headers: { accept: "application/vnd.github+json" },
+                signal: AbortSignal.timeout(timeoutMs),
+            });
+            if (res.ok) {
+                const body = (await res.json());
+                const tag = typeof body?.tag_name === "string" ? body.tag_name : "";
+                const version = tag.startsWith("v") ? tag.slice(1) : tag;
+                if (parseVersion(version)) {
+                    const url = typeof body?.html_url === "string" && body.html_url
+                        ? body.html_url
+                        : "https://github.com/carlosboeing/quotacap/releases/latest";
+                    return { status: "ok", release: { version, url } };
+                }
+            }
+            return rateLimitOrUnavailable(res);
+        }
+        const res = await fetchFn(releasesPageUrl(), {
+            redirect: "manual",
             signal: AbortSignal.timeout(timeoutMs),
         });
-        if (!res.ok)
-            return null;
-        const body = (await res.json());
-        const tag = typeof body?.tag_name === "string" ? body.tag_name : "";
-        const version = tag.startsWith("v") ? tag.slice(1) : tag;
-        if (!parseVersion(version))
-            return null;
-        const url = typeof body?.html_url === "string" && body.html_url
-            ? body.html_url
-            : "https://github.com/carlosboeing/quotacap/releases/latest";
-        return { version, url };
+        if (res.status >= 300 && res.status < 400) {
+            const location = responseHeader(res, "location") ?? "";
+            const tag = tagFromReleaseUrl(location);
+            const version = tag.startsWith("v") ? tag.slice(1) : tag;
+            if (tag && parseVersion(version)) {
+                return { status: "ok", release: { version, url: location } };
+            }
+        }
+        return rateLimitOrUnavailable(res);
     }
     catch {
-        return null;
+        return { status: "unavailable" };
     }
 }
+// Latest published version, or null when the release cannot be resolved
+// (network failure, non-redirect, bad JSON, unparseable tag). Never throws.
+export async function resolveLatestVersion(opts = {}) {
+    const r = await resolveLatestVersionDetailed(opts);
+    return r.status === "ok" ? r.release : null;
+}
 export function updatesCachePath() {
     return path.join(process.env.QUOTACAP_HOME ?? os.homedir(), ".quotacap", "updates.json");
 }
@@ -180,6 +241,11 @@ export function readUpdateCache(p = updatesCachePath()) {
         if (typeof parsed.channel !== "string" || typeof parsed.current !== "string") {
             return null;
         }
+        if (parsed.lastFailureAt !== undefined &&
+            (typeof parsed.lastFailureAt !== "string" ||
+                Number.isNaN(new Date(parsed.lastFailureAt).getTime()))) {
+            return null;
+        }
         return parsed;
     }
     catch {
@@ -201,25 +267,48 @@ export function writeUpdateCache(cache, p = updatesCachePath()) {
     catch { }
 }
 export const UPDATE_CACHE_TTL_MS = 24 * 3600 * 1000;
+// Negative-cache floor: a failed refresh suppresses further network attempts
+// for this long. Short against the daily TTL so a recovered endpoint is
+// re-probed soon, long enough that status/advise/poll storms back off.
+export const UPDATE_FAILURE_RETRY_MS = 30 * 60 * 1000;
 export function updateCacheStale(cache, nowMs = Date.now()) {
     if (!cache)
         return true;
     return nowMs - new Date(cache.checkedAt).getTime() >= UPDATE_CACHE_TTL_MS;
 }
-// Refresh the daily cache when older than 24 hours or absent. Network failure
-// keeps the old cache silently; the result is the cache to read from.
+// Refresh the daily cache when older than 24 hours or absent. A failure
+// inside the retry floor performs no network call and keeps serving the
+// previously cached latest; a fresh failure stamps lastFailureAt so the next
+// attempt backs off. checkedAt is never stamped on failure, so the daily
+// check is unaffected. The result is the cache to read from.
 export async function refreshUpdateCache(opts) {
     const cachePath = opts.cachePath ?? updatesCachePath();
     const existing = readUpdateCache(cachePath);
     const now = opts.now?.() ?? new Date();
     if (!updateCacheStale(existing, now.getTime()))
         return existing;
+    if (existing?.lastFailureAt &&
+        now.getTime() - new Date(existing.lastFailureAt).getTime() < UPDATE_FAILURE_RETRY_MS) {
+        return existing;
+    }
     const latest = await resolveLatestVersion({
         fetchFn: opts.fetchFn,
         timeoutMs: opts.timeoutMs ?? 3000,
     });
-    if (!latest)
-        return existing;
+    if (!latest) {
+        if (!existing)
+            return existing;
+        // Re-read before stamping: a concurrent refresh may have succeeded while
+        // our request was in flight, and stamping our stale snapshot would
+        // clobber its newer write and suppress retries for the floor.
+        const current = readUpdateCache(cachePath);
+        if (current && JSON.stringify(current) !== JSON.stringify(existing)) {
+            return current;
+        }
+        const stamped = { ...existing, lastFailureAt: now.toISOString() };
+        writeUpdateCache(stamped, cachePath);
+        return stamped;
+    }
     const fresh = {
         checkedAt: now.toISOString(),
         latest: latest.version,

package/dist/service/index.js

@@ -73,7 +73,10 @@ export async function runServiceCommand(args, opts = {}, deps = {}) {
     try {
         switch (verb) {
             case "install":
-                await backend.install(deps);
+                // Internal: the post-update refresh passes the target version so
+                // install compares and records it instead of the old in-process
+                // VERSION. The `service install` CLI never sets opts.version.
+                await backend.install({ ...deps, version: opts.version ?? deps.version });
                 break;
             case "uninstall":
                 await backend.uninstall(deps);

package/dist/service/macos.d.ts

@@ -14,17 +14,28 @@ export interface ServiceDeps {
     which?: (bin: string) => string | null;
     lintPlist?: (plistFile: string) => void;
     waitReady?: (port: number) => Promise<boolean>;
+    waitReleased?: (port: number) => Promise<boolean>;
     print?: (msg: string) => void;
     error?: (msg: string) => void;
     now?: () => Date;
     sleep?: (ms: number) => Promise<void>;
     bootstrapTimeoutMs?: number;
+    version?: string;
 }
 export declare function foregroundGuidance(verb: string, platform: string): string;
 export declare function defaultRunLaunchctl(args: string[]): string;
 export declare function defaultWhich(bin: string): string | null;
 export declare function defaultLintPlist(plistFile: string): void;
 export declare function defaultWaitReady(port: number, timeoutMs?: number): Promise<boolean>;
+/**
+ * `launchctl bootout` and `systemctl --user stop` both return before the job
+ * has actually gone, so a restart that starts immediately races the dying
+ * process for the port: the replacement fails to bind and the restart reports
+ * "did not become ready". Wait until nothing answers on the port.
+ *
+ * Resolves true as soon as the port is free, false if it never frees.
+ */
+export declare function defaultWaitReleased(port: number, timeoutMs?: number): Promise<boolean>;
 export interface ServiceExec {
     argv: string[];
     entry: string;