copillm 0.2.7 → 0.2.9

package/dist/integrations/claude/cache.js

@@ -1,8 +1,11 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
+import { claudeConfigDir } from "../../config/home.js";
 export function claudeGatewayCachePath() {
-    return path.join(os.homedir(), ".claude", "cache", "gateway-models.json");
+    // Claude stores the gateway model-picker cache under its config home
+    // (CLAUDE_CONFIG_DIR). copillm owns that home, so we clear the copillm-owned
+    // copy — never the user's real ~/.claude.
+    return path.join(claudeConfigDir(), "cache", "gateway-models.json");
 }
 export function clearClaudeGatewayCache() {
     const target = claudeGatewayCachePath();

package/dist/integrations/claude/settingsConflict.js

@@ -1,8 +1,11 @@
 import fs from "node:fs";
-import os from "node:os";
+import { claudeConfigDir } from "../../config/home.js";
 import path from "node:path";
 export function claudeSettingsPath() {
-    return path.join(os.homedir(), ".claude", "settings.json");
+    // copillm-launched Claude reads settings from its copillm-owned config home
+    // (CLAUDE_CONFIG_DIR), so the conflict check inspects that file — not the
+    // user's real ~/.claude/settings.json.
+    return path.join(claudeConfigDir(), "settings.json");
 }
 export function detectClaudeSettingsConflicts(launcherEnv, settingsPathOverride) {
     const settingsPath = settingsPathOverride ?? claudeSettingsPath();

package/dist/integrations/codex/init.js

@@ -1,6 +1,5 @@
 import fs from "node:fs";
 import path from "node:path";
-import { CopilotTokenManager } from "../../auth/copilotToken.js";
 import { loadStoredCredential } from "../../auth/credentials.js";
 import { loadConfig } from "../../config/config.js";
 import { listModelsUnion } from "../../models/discovery.js";
@@ -8,14 +7,7 @@ import { ensureSecureDirectory, writeFileSecureAtomic } from "../../config/fsSec
 import { buildCodexCatalog } from "../../server/codexSchema.js";
 import { inspectLock } from "../../server/lock.js";
 export async function generateCodexHome(options) {
-    const config = loadConfig();
-    const creds = await loadStoredCredential();
-    if (!creds) {
-        throw new Error("Not authenticated. Run `copillm login` first.");
-    }
-    const tokenManager = new CopilotTokenManager(creds.token);
-    await tokenManager.ensureToken(false);
-    const discovery = await listModelsUnion(config.accountType, creds.token, 3);
+    const { discovery } = await resolveStartContext(options.precomputed);
     const catalog = buildCodexCatalog(discovery.models);
     if (catalog.models.length === 0) {
         throw new Error("No Codex-eligible models found in the live catalog.");
@@ -47,6 +39,26 @@ export async function generateCodexHome(options) {
         exportCommand: `CODEX_HOME=${absOutDir} codex`
     };
 }
+/**
+ * Load credentials / config / model discovery once. When the caller has
+ * already done this work (e.g. `copillm start` orchestrating multiple init
+ * steps), it can pass them in via `precomputed` to skip the work.
+ *
+ * Exported so `generatePiHome` (and any future agent init) can use the
+ * same loader and the same "if precomputed, reuse it" contract.
+ */
+export async function resolveStartContext(precomputed) {
+    if (precomputed) {
+        return precomputed;
+    }
+    const config = loadConfig();
+    const creds = await loadStoredCredential();
+    if (!creds) {
+        throw new Error("Not authenticated. Run `copillm login` first.");
+    }
+    const discovery = await listModelsUnion(config.accountType, creds.token, 3);
+    return { config, creds, discovery };
+}
 function pickDefaultModel(slugs) {
     const preferred = ["gpt-5.3-codex", "gpt-5.2-codex", "gpt-5.4", "gpt-5.2", "claude-opus-4.5", "claude-sonnet-4.6"];
     for (const candidate of preferred) {

package/dist/integrations/pi/init.js

@@ -1,20 +1,10 @@
 import fs from "node:fs";
-import os from "node:os";
 import path from "node:path";
-import { CopilotTokenManager } from "../../auth/copilotToken.js";
-import { loadStoredCredential } from "../../auth/credentials.js";
-import { loadConfig } from "../../config/config.js";
-import { listModelsUnion } from "../../models/discovery.js";
 import { ensureSecureDirectory, writeFileSecureAtomic } from "../../config/fsSecurity.js";
+import { piAgentDir } from "../../config/home.js";
+import { resolveStartContext } from "../codex/init.js";
 export async function generatePiHome(options) {
-    const config = loadConfig();
-    const creds = await loadStoredCredential();
-    if (!creds) {
-        throw new Error("Not authenticated. Run `copillm login` first.");
-    }
-    const tokenManager = new CopilotTokenManager(creds.token);
-    await tokenManager.ensureToken(false);
-    const discovery = await listModelsUnion(config.accountType, creds.token, 3);
+    const { discovery } = await resolveStartContext(options.precomputed);
     const eligible = discovery.models.filter(isPickerEligible);
     // Split the catalog by which upstream endpoint each model supports. Models
     // that advertise `/chat/completions` flow through copillm's Anthropic surface
@@ -79,9 +69,9 @@ export async function generatePiHome(options) {
 export function defaultOutputDir(home) {
     return path.join(home, "pi");
 }
-/** Absolute path to `~/.pi/agent/models.json`. Honors $HOME for tests. */
+/** Absolute path to pi's `models.json`, under the copillm-owned pi agent dir. */
 export function piModelsJsonPath() {
-    return path.join(os.homedir(), ".pi", "agent", "models.json");
+    return path.join(piAgentDir(), "models.json");
 }
 /**
  * Eligibility filter shared by both pi providers. Mirrors the gating in

package/dist/models/discovery.js

@@ -1,4 +1,5 @@
 import fs from "node:fs";
+import { setTimeout as defaultSleep } from "node:timers/promises";
 import { z } from "zod";
 import { modelsCachePath, modelsCacheReadPath } from "../config/home.js";
 import { writeFileSecureAtomic } from "../config/fsSecurity.js";
@@ -20,18 +21,47 @@ const MODEL_RESOLUTION_RULES = [
     { id: "separator-normalized", normalize: (value) => normalizeModelId(value) },
     { id: "snapshot-trimmed", normalize: (value) => trimDateSnapshot(normalizeModelId(value)) }
 ];
+/**
+ * Per-attempt timeout for the `/models` fetch. The catalog is typically
+ * <50ms on a healthy connection, so 15s leaves plenty of room for slow
+ * networks without freezing `copillm start` for a full minute.
+ */
+const DEFAULT_FETCH_TIMEOUT_MS = 15_000;
+/**
+ * Exponential backoff base for `listModelsUnion` retry loop. Mirrors the
+ * 200ms / 400ms / 800ms shape used by `src/server/upstream/copilotClient.ts`
+ * and the new `CopilotTokenManager.exchange()` retry path. Boundary rules
+ * (`eslint.config.js`) keep `models` from importing the shared
+ * `retryPolicy.ts`, so we re-declare the small handful of constants here
+ * rather than introduce a new architectural dependency.
+ */
+const DEFAULT_BACKOFF_BASE_MS = 200;
+/**
+ * Statuses worth retrying — same set as `retryPolicy.ts`. 401/403/404 are
+ * NOT here because they signal terminal credential / endpoint failures
+ * and retrying just delays the error the user needs to see.
+ *
+ * `canUseCacheFallback` (further down) is intentionally MORE permissive:
+ * it also includes 401/403/408 so that a misbehaving upstream serving 401
+ * to a perfectly-good token can degrade to the cached snapshot instead of
+ * surfacing a misleading auth error.
+ */
+const RETRYABLE_DISCOVERY_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
 export function accountBaseUrl(accountType) {
     return copilotBaseUrl(accountType);
 }
-export async function listModels(accountType, bearerToken) {
+export async function listModels(accountType, bearerToken, deps) {
+    const fetchImpl = deps?.fetchImpl ?? ((input, init) => fetch(input, init));
+    const timeoutMs = deps?.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
     try {
-        const response = await fetch(`${accountBaseUrl(accountType)}/models`, {
+        const response = await fetchImpl(`${accountBaseUrl(accountType)}/models`, {
             method: "GET",
             headers: {
                 Authorization: `Bearer ${bearerToken}`,
                 "Content-Type": "application/json",
                 "User-Agent": "copillm/0.1.0"
-            }
+            },
+            signal: AbortSignal.timeout(timeoutMs)
         });
         if (!response.ok) {
             throw new ModelDiscoveryHttpError(response.status);
@@ -40,7 +70,7 @@ export async function listModels(accountType, bearerToken) {
         const candidateModels = extractModelArray(payload);
         const parsed = z.array(ModelSchema).safeParse(candidateModels);
         if (!parsed.success) {
-            throw new Error("Model discovery response is invalid.");
+            throw new ModelDiscoverySchemaError("Model discovery response is invalid.");
         }
         saveModelCache(accountType, parsed.data);
         return {
@@ -69,14 +99,37 @@ export async function listModels(accountType, bearerToken) {
         };
     }
 }
-export async function listModelsUnion(accountType, bearerToken, attempts = 3) {
+/**
+ * Run multiple discovery attempts and union the results across them.
+ *
+ * Two changes from the previous version:
+ *
+ *   1. **Exponential backoff between attempts** — was a tight loop that
+ *      hammered Copilot 3× immediately on a 429 burst, extending the
+ *      rate-limit lockout. Now sleeps 200ms × 2^(attempt-1) between
+ *      iterations, matching the curve used in `copilotClient.ts` and the
+ *      token-exchange retry.
+ *   2. **Short-circuit on terminal failures** — a schema-invalid 200 or
+ *      a `Model discovery failed and no cache snapshot is available`
+ *      surface no longer retries; both are deterministic failures that
+ *      retrying can't fix and the misleading "across all attempts" error
+ *      hid the real cause.
+ *
+ * `attempts` keeps its previous default of 3 for callers that don't
+ * specify. Each attempt's own retry budget lives inside `listModels`'s
+ * cache-fallback path; this loop runs once per upstream call.
+ */
+export async function listModelsUnion(accountType, bearerToken, attempts = 3, deps) {
+    const sleepImpl = deps?.sleepImpl ?? ((ms) => defaultSleep(ms));
     const seen = new Map();
     let lastResult = null;
     let lastError;
+    let consecutiveFailures = 0;
     for (let i = 0; i < attempts; i += 1) {
         try {
-            const result = await listModels(accountType, bearerToken);
+            const result = await listModels(accountType, bearerToken, deps);
             lastResult = result;
+            consecutiveFailures = 0;
             for (const model of result.models) {
                 if (typeof model.id === "string" && !seen.has(model.id)) {
                     seen.set(model.id, model);
@@ -85,6 +138,26 @@ export async function listModelsUnion(accountType, bearerToken, attempts = 3) {
         }
         catch (error) {
             lastError = error;
+            consecutiveFailures += 1;
+            // Schema failures are deterministic — same response shape, same error.
+            // Don't burn the rest of the retry budget; surface the real cause now.
+            if (error instanceof ModelDiscoverySchemaError) {
+                throw error;
+            }
+            // HTTP failures that aren't on the retryable list (e.g. 401/403 with
+            // no cache, 404) are also deterministic. The cache-fallback path
+            // inside `listModels` has already had its chance to engage; if we got
+            // here it didn't.
+            if (error instanceof ModelDiscoveryHttpError && !RETRYABLE_DISCOVERY_STATUSES.has(error.status)) {
+                throw error;
+            }
+        }
+        // Only sleep between attempts if the most recent attempt FAILED. Sleeping
+        // between successful attempts would burn wall-clock for no benefit when
+        // the union is already populated. Sleep schedule mirrors the rest of the
+        // codebase: 200ms × 2^(failure-1), so 200 → 400 → 800 between failures.
+        if (i < attempts - 1 && consecutiveFailures > 0) {
+            await sleepImpl(DEFAULT_BACKOFF_BASE_MS * Math.pow(2, consecutiveFailures - 1));
         }
     }
     if (lastResult === null) {
@@ -157,19 +230,50 @@ export function resolveModelSelections(requestedModelIds, models) {
     }
     return { resolved, unresolved };
 }
-class ModelDiscoveryHttpError extends Error {
+export class ModelDiscoveryHttpError extends Error {
     status;
     constructor(status) {
         super(`Model discovery failed (${status}).`);
         this.status = status;
+        this.name = "ModelDiscoveryHttpError";
     }
 }
+export class ModelDiscoverySchemaError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ModelDiscoverySchemaError";
+    }
+}
+/**
+ * Statuses + error types that allow degrading to the on-disk cache instead
+ * of failing the caller.
+ *
+ * Widened from the previous `429 || >= 500` to include 401, 403, 408 — the
+ * exact case the seed audit hit: a transient 401 from `api.github.com/...`
+ * or its proxy in front of `/models` would re-throw and tell the user
+ * `Model discovery failed and no cache snapshot is available.` even when
+ * a perfectly good cached catalog existed. With this widening, a fresh
+ * cache (typical for users who've run `copillm start` recently) hides the
+ * blip from agent surfaces.
+ *
+ * Schema errors are intentionally NOT cache-eligible: a 200 with a body
+ * shape we don't recognize is a deterministic failure that the cache
+ * can't paper over, and surfacing the real `Model discovery response is
+ * invalid.` error is more useful than silently serving stale data.
+ *
+ * Non-HTTP errors (transport / AbortError / generic) DO fall back — those
+ * are exactly the kinds of transient failures the cache exists for.
+ */
 function canUseCacheFallback(error) {
+    if (error instanceof ModelDiscoverySchemaError) {
+        return false;
+    }
     if (error instanceof ModelDiscoveryHttpError) {
-        return error.status === 429 || error.status >= 500;
+        return CACHE_FALLBACK_STATUSES.has(error.status) || error.status >= 500;
     }
     return true;
 }
+const CACHE_FALLBACK_STATUSES = new Set([401, 403, 408, 409, 425, 429]);
 function saveModelCache(accountType, models) {
     const payload = {
         version: 1,

package/dist/server/debugInfo.js

@@ -1,37 +1,82 @@
+import { setTimeout as defaultSleep } from "node:timers/promises";
 import { githubUserUrl } from "../config/upstream.js";
+import { isRetryableStatus, isRetryableTransportError, retryDelayMs } from "./upstream/retryPolicy.js";
 const CACHE_TTL_MS = 5 * 60 * 1_000;
+const DEFAULT_MAX_ATTEMPTS = 3;
 let cached = null;
+/**
+ * Fetch the GitHub user summary with bounded retries on transient failures.
+ *
+ * Was: single fetch, single attempt. A transient 502 from `api.github.com/user`
+ * caused `auth status` to hide the user's login and `/_debug` to report
+ * `user_error: github_user_lookup_failed_502` instead of the user object.
+ *
+ * Now: retries 5xx/429/408/409/425 + transient transport errors up to
+ * `maxAttempts` (default 3) with exponential backoff (200ms / 400ms). Does
+ * NOT retry 401/403/404 — those are terminal credential / endpoint signals
+ * and retrying just delays the error the caller needs to surface.
+ *
+ * Cache write only happens on success.
+ */
 export async function getGithubUserSummary(githubToken, options = {}) {
     const now = Date.now();
     if (cached && now - cached.fetchedAt < CACHE_TTL_MS) {
         return cached.summary;
     }
-    const response = await fetch(githubUserUrl(), {
-        headers: {
-            Authorization: `token ${githubToken}`,
-            Accept: "application/vnd.github+json",
-            "User-Agent": "copillm/0.1.0",
-            "X-GitHub-Api-Version": "2022-11-28"
-        },
-        signal: typeof options.timeoutMs === "number" ? AbortSignal.timeout(options.timeoutMs) : undefined
-    });
-    if (!response.ok) {
+    const fetchImpl = options.fetchImpl ?? ((input, init) => fetch(input, init));
+    const sleepImpl = options.sleepImpl ?? ((ms) => defaultSleep(ms));
+    const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    let lastError;
+    for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
+        let response;
+        try {
+            response = await fetchImpl(githubUserUrl(), {
+                headers: {
+                    Authorization: `token ${githubToken}`,
+                    Accept: "application/vnd.github+json",
+                    "User-Agent": "copillm/0.1.0",
+                    "X-GitHub-Api-Version": "2022-11-28"
+                },
+                signal: typeof options.timeoutMs === "number" ? AbortSignal.timeout(options.timeoutMs) : undefined
+            });
+        }
+        catch (error) {
+            lastError = error;
+            if (isRetryableTransportError(error) && attempt < maxAttempts) {
+                await sleepImpl(retryDelayMs(attempt));
+                continue;
+            }
+            throw error;
+        }
+        if (response.ok) {
+            const payload = (await response.json());
+            const summary = {
+                login: typeof payload.login === "string" ? payload.login : "",
+                id: typeof payload.id === "number" ? payload.id : 0,
+                name: typeof payload.name === "string" ? payload.name : null,
+                email: typeof payload.email === "string" ? payload.email : null,
+                type: typeof payload.type === "string" ? payload.type : "User",
+                avatar_url: typeof payload.avatar_url === "string" ? payload.avatar_url : null,
+                html_url: typeof payload.html_url === "string" ? payload.html_url : null,
+                plan_name: typeof payload.plan?.name === "string" ? payload.plan.name : null
+            };
+            cached = { fetchedAt: Date.now(), summary };
+            return summary;
+        }
+        // Non-OK. 401/403/404 are terminal — fast-fail. Other retryable statuses
+        // (429, 5xx) drain the body and retry.
         const detail = await response.text();
-        throw new GithubUserFetchError(response.status, detail.slice(0, 256));
+        const snippet = detail.slice(0, 256);
+        lastError = new GithubUserFetchError(response.status, snippet);
+        if (isRetryableStatus(response.status) && attempt < maxAttempts) {
+            await sleepImpl(retryDelayMs(attempt));
+            continue;
+        }
+        throw lastError;
     }
-    const payload = (await response.json());
-    const summary = {
-        login: typeof payload.login === "string" ? payload.login : "",
-        id: typeof payload.id === "number" ? payload.id : 0,
-        name: typeof payload.name === "string" ? payload.name : null,
-        email: typeof payload.email === "string" ? payload.email : null,
-        type: typeof payload.type === "string" ? payload.type : "User",
-        avatar_url: typeof payload.avatar_url === "string" ? payload.avatar_url : null,
-        html_url: typeof payload.html_url === "string" ? payload.html_url : null,
-        plan_name: typeof payload.plan?.name === "string" ? payload.plan.name : null
-    };
-    cached = { fetchedAt: now, summary };
-    return summary;
+    // Unreachable: every loop iteration either returns, throws, or continues
+    // (and continue is gated on `attempt < maxAttempts`). Defend anyway.
+    throw lastError ?? new Error("GitHub user lookup exhausted retries without error context.");
 }
 export function clearGithubUserCache() {
     cached = null;

package/dist/server/errors.js

@@ -141,6 +141,24 @@ export function upstreamStatusCategory(status) {
     return "upstream_error";
 }
 export function healthFailure(error) {
+    return tokenErrorToHttpResponse(error);
+}
+/**
+ * Map a `CopilotTokenManagerError` (or any unknown error from the token
+ * exchange / refresh path) to an HTTP response. Single source of truth for
+ * the `/healthz`, `/models`, `/codex/v1/models`, and `/anthropic/v1/models`
+ * routes — previously `routes/models.ts` collapsed every token failure to a
+ * flat 503 `token_refresh_failed`, hiding the credential-vs-blip
+ * distinction that callers (codex, pi, claude) need to decide whether to
+ * retry. The discrimination logic now lives here.
+ *
+ * Maps:
+ *   - 401/403 from the upstream token endpoint   → HTTP 401 `github_auth_invalid`
+ *   - 5xx/429/other transient from upstream      → HTTP 503 `token_exchange_failed`
+ *   - other `CopilotTokenManagerError`           → HTTP 401 `token_refresh_failed`
+ *   - anything else                              → HTTP 503 `token_refresh_unavailable`
+ */
+export function tokenErrorToHttpResponse(error) {
     if (error instanceof CopilotTokenExchangeError) {
         if (error.statusCode === 401 || error.statusCode === 403) {
             return {

package/dist/server/routes/debug.js

@@ -8,7 +8,10 @@ export async function handleDebug(res, input) {
     let userError = null;
     if (input.githubToken) {
         try {
-            const summary = await getGithubUserSummary(input.githubToken);
+            // Bound the GitHub user lookup so a slow `api.github.com` cannot hang
+            // the `/_debug` handler indefinitely. Matches the bound used by the
+            // CLI's `auth status` path (`githubIdentity.ts:42-44`).
+            const summary = await getGithubUserSummary(input.githubToken, { timeoutMs: 4_000 });
             user = {
                 login: summary.login,
                 id: summary.id,

package/dist/server/routes/models.js

@@ -2,6 +2,7 @@ import { CopilotTokenManagerError } from "../../auth/copilotToken.js";
 import { listModels, listModelsUnion } from "../../models/discovery.js";
 import { buildCodexCatalog } from "../codexSchema.js";
 import { buildAnthropicModelsResponse } from "../anthropicModelsResponse.js";
+import { tokenErrorToHttpResponse } from "../errors.js";
 import { safeSendJson } from "../requestLifecycle.js";
 export async function handleModels(res, routeKind, config, tokenManager, githubToken) {
     try {
@@ -33,7 +34,12 @@ export async function handleModels(res, routeKind, config, tokenManager, githubT
     }
     catch (error) {
         if (error instanceof CopilotTokenManagerError) {
-            safeSendJson(res, 503, { error: "token_refresh_failed" });
+            // Discriminate credential failure (401/403 from upstream — terminal)
+            // from transient blip (5xx/429 from upstream — retryable by caller).
+            // Was: flat `503 token_refresh_failed` for both, which made codex/pi/
+            // claude blindly retry on the permanent case.
+            const mapped = tokenErrorToHttpResponse(error);
+            safeSendJson(res, mapped.httpStatus, mapped.payload);
             return;
         }
         throw error;

package/dist/server/upstream/copilotClient.js

@@ -1,6 +1,7 @@
 import { setTimeout as sleep } from "node:timers/promises";
 import { accountBaseUrl } from "../../models/discovery.js";
 import { isBenignSocketError } from "../requestLifecycle.js";
+import { isRetryableStatus, isRetryableTransportError, retryDelayMs } from "./retryPolicy.js";
 const COPILOT_HEADERS = {
     "Content-Type": "application/json",
     "Copilot-Integration-Id": "vscode-chat",
@@ -17,9 +18,7 @@ const COPILOT_HEADERS = {
     // flow through immediately.
     "Accept-Encoding": "identity"
 };
-const RETRYABLE_UPSTREAM_STATUSES = new Set([408, 409, 425, 429, 500, 502, 503, 504]);
 const MAX_UPSTREAM_ATTEMPTS = 3;
-const BASE_BACKOFF_MS = 200;
 export async function postToCopilot(input) {
     let forceRefresh = false;
     let authRefreshRetried = false;
@@ -99,34 +98,6 @@ function abortErrorFromSignal(signal) {
     err.name = "AbortError";
     return err;
 }
-function isRetryableStatus(status) {
-    return RETRYABLE_UPSTREAM_STATUSES.has(status);
-}
-function retryDelayMs(attempt) {
-    return BASE_BACKOFF_MS * Math.pow(2, Math.max(0, attempt - 1));
-}
-function isRetryableTransportError(error) {
-    if (!error || typeof error !== "object") {
-        return false;
-    }
-    const typedError = error;
-    const directCode = typedError.code?.toUpperCase();
-    const causeCode = typedError.cause?.code?.toUpperCase();
-    if (directCode === "ECONNRESET" || directCode === "ECONNREFUSED" || directCode === "ETIMEDOUT") {
-        return true;
-    }
-    if (causeCode === "ECONNRESET" || causeCode === "ECONNREFUSED" || causeCode === "ETIMEDOUT") {
-        return true;
-    }
-    if (!(typedError instanceof Error)) {
-        return false;
-    }
-    const message = typedError.message.toLowerCase();
-    if (message.includes("timed out") || message.includes("timeout")) {
-        return true;
-    }
-    return message.includes("econnreset") || message.includes("econnrefused") || message.includes("enotfound");
-}
 async function discardUpstreamBody(response) {
     try {
         await response.arrayBuffer();

package/dist/server/upstream/retryPolicy.js

@@ -0,0 +1,99 @@
+// Shared retry primitives for upstream HTTP calls.
+//
+// Originally lived inline in `copilotClient.ts` only. Extracted so that
+// other upstream-facing fetch sites (token exchange in `auth/copilotToken.ts`,
+// future device-flow / model-discovery sites) can share the same policy
+// instead of each rolling its own slightly-different version. The numerical
+// constants and the retryable-status set must match `copilotClient.ts`'s
+// previous behaviour exactly so existing tests and production semantics
+// don't drift.
+/**
+ * HTTP statuses that warrant a retry: transient server-side congestion /
+ * upstream outages. 401 is NOT here — auth failures are handled by a
+ * separate caller-driven "force refresh once" path in `copilotClient.ts`,
+ * and by `CopilotTokenManager.exchange()` as a terminal "bad credentials"
+ * signal.
+ */
+export const RETRYABLE_UPSTREAM_STATUSES = new Set([
+    408, 409, 425, 429, 500, 502, 503, 504
+]);
+export function isRetryableStatus(status) {
+    return RETRYABLE_UPSTREAM_STATUSES.has(status);
+}
+/** Base exponential backoff: 200ms × 2^(attempt-1). */
+export const BASE_BACKOFF_MS = 200;
+export function retryDelayMs(attempt) {
+    return BASE_BACKOFF_MS * Math.pow(2, Math.max(0, attempt - 1));
+}
+/**
+ * Node `fetch` / undici transport error codes worth retrying. Excludes
+ * permanent errors like EACCES, ENOSPC, certificate failures. Both the
+ * direct `error.code` and the wrapped `error.cause.code` are checked
+ * because undici wraps the underlying socket error in a `TypeError:
+ * fetch failed` whose `.cause` carries the real code.
+ *
+ * EAI_AGAIN, EHOSTUNREACH, ENETUNREACH catch the common transient DNS
+ * and routing failures (home networks, corp VPN flaps, macOS wake-from-
+ * sleep). UND_ERR_* are undici's own timeouts and socket errors.
+ */
+const RETRYABLE_TRANSPORT_CODES = new Set([
+    "ECONNRESET",
+    "ECONNREFUSED",
+    "ETIMEDOUT",
+    "EAI_AGAIN",
+    "EHOSTUNREACH",
+    "ENETUNREACH",
+    "EPIPE",
+    "UND_ERR_SOCKET",
+    "UND_ERR_CONNECT_TIMEOUT",
+    "UND_ERR_HEADERS_TIMEOUT",
+    "UND_ERR_BODY_TIMEOUT"
+]);
+const RETRYABLE_TRANSPORT_MESSAGE_SUBSTRINGS = [
+    "timed out",
+    "timeout",
+    "econnreset",
+    "econnrefused",
+    "enotfound",
+    "eai_again",
+    "ehostunreach",
+    "enetunreach",
+    "socket hang up",
+    "other side closed",
+    "fetch failed"
+];
+export function isRetryableTransportError(error) {
+    if (!error || typeof error !== "object") {
+        return false;
+    }
+    const typedError = error;
+    if (matchesRetryableCode(typedError.code)) {
+        return true;
+    }
+    // Recurse into .cause to handle undici's `TypeError: fetch failed` wrapper
+    // (and any other wrapper layers); bounded depth so a self-referential
+    // cause chain can't run away.
+    if (causeHasRetryableCode(typedError.cause, 0)) {
+        return true;
+    }
+    if (!(typedError instanceof Error)) {
+        return false;
+    }
+    const message = typedError.message.toLowerCase();
+    return RETRYABLE_TRANSPORT_MESSAGE_SUBSTRINGS.some((needle) => message.includes(needle));
+}
+function matchesRetryableCode(code) {
+    if (typeof code !== "string")
+        return false;
+    return RETRYABLE_TRANSPORT_CODES.has(code.toUpperCase());
+}
+function causeHasRetryableCode(cause, depth) {
+    if (!cause || typeof cause !== "object" || depth > 5) {
+        return false;
+    }
+    const inner = cause;
+    if (matchesRetryableCode(inner.code)) {
+        return true;
+    }
+    return causeHasRetryableCode(inner.cause, depth + 1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "copillm",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Local Copilot proxy CLI (OpenAI/Anthropic-compatible)",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,9 @@
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/cli.ts",
+    "dev:start": "npm run build && node dist/cli.js --dev start",
+    "dev:stop": "npm run build && node dist/cli.js --dev stop",
+    "dev:status": "node dist/cli.js --dev status",
     "lint": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.tests.json --noEmit && eslint src",
     "lint:boundaries": "eslint src",
     "test": "vitest run",