copillm 0.2.7 → 0.2.9

package/dist/cli/commands/daemon.js

@@ -1,20 +1,23 @@
 import { spawn } from "node:child_process";
 import { inspectStoredCredential } from "../../auth/credentials.js";
 import { loadConfig } from "../../config/config.js";
+import { getCopillmHome } from "../../config/home.js";
 import { clearClaudeGatewayCache } from "../../integrations/claude/cache.js";
+import { resolveStartContext } from "../../integrations/codex/init.js";
 import { inspectLock, releaseLock } from "../../server/lock.js";
 import { buildCodexEnvBundle } from "../agentEnv.js";
 import { ensureAuthenticatedInteractive } from "../auth/ensure.js";
-import { computeUptimeSeconds, stopByPid } from "../daemon/lifecycle.js";
+import { computeUptimeSeconds, formatUptime, stopByPid } from "../daemon/lifecycle.js";
 import { probeHealth, readLiveLock, waitForDaemonReady, warnIfDebugRequestedButInactive } from "../daemon/probes.js";
 import { runDaemon } from "../daemon/runDaemon.js";
 import { daemonSpawnEnv } from "../daemon/spawnEnv.js";
 import { buildClaudeExportCommand } from "../integrations/claudeExport.js";
-import { formatStartBanner, formatStopHumanLine } from "../integrations/banner.js";
+import { formatStartBanner, formatStopHumanLine, displayHomePath } from "../integrations/banner.js";
 import { refreshCodexHome } from "../integrations/refreshCodex.js";
 import { refreshPiHome } from "../integrations/refreshPi.js";
 import { writeAuthStatusLine } from "../shared/backends.js";
 import { currentDebugLogPath, enableRuntimeDebug, getRootLogger, resolveCopillmDebug } from "../shared/debug.js";
+import { isDevModeActive } from "../shared/devMode.js";
 import { writeCommandOutput, writeHealthOutput } from "../shared/output.js";
 import { buildSelfSpawnCommand } from "../daemon/selfSpawn.js";
 export function register(program) {
@@ -25,11 +28,14 @@ export function register(program) {
         .option("--debug", "Enable debug endpoints (e.g. /_debug)")
         .option("--no-codex", "Skip generating ~/.copillm/codex/ for Codex CLI")
         .option("--codex-model <id>", "Default Codex model slug")
-        .option("--no-pi", "Skip generating ~/.pi/agent/models.json for pi coding agent")
+        .option("--no-pi", "Skip generating the copillm-owned pi models.json for pi coding agent")
         .option("--json", "JSON output")
         .action(async (opts) => {
         const debug = resolveCopillmDebug(opts.debug);
         enableRuntimeDebug(debug);
+        if (isDevModeActive()) {
+            process.stderr.write(`dev mode: isolated COPILLM_HOME ${displayHomePath(getCopillmHome())}\n`);
+        }
         if (opts.detach) {
             // Fail fast on missing credentials rather than letting the detached
             // child die silently and surface as a generic "start timed out" error.
@@ -40,8 +46,9 @@ export function register(program) {
             const existingLock = await readLiveLock();
             if (existingLock) {
                 const activeDebug = await warnIfDebugRequestedButInactive(debug, existingLock.port);
-                const codex = opts.codex === false ? null : await refreshCodexHome(existingLock.port, opts.codexModel ?? null);
-                const pi = opts.pi === false ? null : await refreshPiHome(existingLock.port);
+                const shared = await loadSharedStartContextIfNeeded(opts);
+                const codex = opts.codex === false ? null : await refreshCodexHome(existingLock.port, opts.codexModel ?? null, shared);
+                const pi = opts.pi === false ? null : await refreshPiHome(existingLock.port, shared);
                 const claude = buildClaudeExportCommand(existingLock.port, null);
                 const banner = formatStartBanner({
                     port: existingLock.port,
@@ -86,8 +93,9 @@ export function register(program) {
             if (!started) {
                 throw new Error("Detached daemon start timed out.");
             }
-            const codex = opts.codex === false ? null : await refreshCodexHome(started.port, opts.codexModel ?? null);
-            const pi = opts.pi === false ? null : await refreshPiHome(started.port);
+            const sharedDetached = await loadSharedStartContextIfNeeded(opts);
+            const codex = opts.codex === false ? null : await refreshCodexHome(started.port, opts.codexModel ?? null, sharedDetached);
+            const pi = opts.pi === false ? null : await refreshPiHome(started.port, sharedDetached);
             const claude = buildClaudeExportCommand(started.port, null);
             const banner = formatStartBanner({
                 port: started.port,
@@ -127,8 +135,9 @@ export function register(program) {
         const started = await runDaemon({ debug });
         if (started.kind === "already_running") {
             const activeDebug = await warnIfDebugRequestedButInactive(debug, started.lock.port);
-            const codex = opts.codex === false ? null : await refreshCodexHome(started.lock.port, opts.codexModel ?? null);
-            const pi = opts.pi === false ? null : await refreshPiHome(started.lock.port);
+            const sharedAlready = await loadSharedStartContextIfNeeded(opts);
+            const codex = opts.codex === false ? null : await refreshCodexHome(started.lock.port, opts.codexModel ?? null, sharedAlready);
+            const pi = opts.pi === false ? null : await refreshPiHome(started.lock.port, sharedAlready);
             const claude = buildClaudeExportCommand(started.lock.port, null);
             const banner = formatStartBanner({
                 port: started.lock.port,
@@ -159,8 +168,9 @@ export function register(program) {
             });
             return;
         }
-        const codex = opts.codex === false ? null : await refreshCodexHome(started.port, opts.codexModel ?? null);
-        const pi = opts.pi === false ? null : await refreshPiHome(started.port);
+        const sharedForeground = await loadSharedStartContextIfNeeded(opts);
+        const codex = opts.codex === false ? null : await refreshCodexHome(started.port, opts.codexModel ?? null, sharedForeground);
+        const pi = opts.pi === false ? null : await refreshPiHome(started.port, sharedForeground);
         const claude = buildClaudeExportCommand(started.port, started.callerSecret);
         const banner = formatStartBanner({
             port: started.port,
@@ -271,10 +281,13 @@ export function register(program) {
         const status = {
             running: lockState.state === "running",
             stale: lockState.state === "stale",
+            copillm_home: getCopillmHome(),
+            dev_mode: isDevModeActive(),
             pid: lockState.state === "running" ? lockState.lock.pid : null,
             port: lockState.state === "running" ? lockState.lock.port : null,
             started_at_iso: lockState.state === "running" ? lockState.lock.started_at_iso : null,
             uptime_seconds: uptimeSeconds,
+            uptime_human: uptimeSeconds === null ? null : formatUptime(uptimeSeconds),
             url: lockState.state === "running" ? `http://127.0.0.1:${lockState.lock.port}` : null,
             require_caller_secret: config.requireCallerSecret,
             account_type: config.accountType,
@@ -300,6 +313,7 @@ export function register(program) {
             process.stdout.write(JSON.stringify(status, null, 2) + "\n");
             return;
         }
+        process.stdout.write(`home: ${displayHomePath(status.copillm_home)}${status.dev_mode ? " (dev)" : ""}\n`);
         if (lockState.state === "running") {
             process.stdout.write(`running (pid ${lockState.lock.pid}, port ${lockState.lock.port})\n`);
             process.stdout.write(`health: ${status.health_status}`);
@@ -317,7 +331,7 @@ export function register(program) {
                 process.stdout.write(`bearer_ttl_seconds: ${status.bearer_ttl_seconds}\n`);
             }
             if (status.uptime_seconds !== null) {
-                process.stdout.write(`uptime_seconds: ${status.uptime_seconds}\n`);
+                process.stdout.write(`uptime: ${formatUptime(status.uptime_seconds)} (${status.uptime_seconds}s)\n`);
             }
             writeAuthStatusLine(authInfo);
             process.stdout.write(`checked_at: ${status.checked_at_iso}\n`);
@@ -347,12 +361,60 @@ export function register(program) {
             process.exitCode = 1;
             return;
         }
-        const response = await fetch(`http://127.0.0.1:${lockState.lock.port}/healthz`, { signal: AbortSignal.timeout(2_000) });
-        const payload = (await response.json());
-        const output = { ok: response.ok, status_code: response.status, ...payload };
-        writeHealthOutput(opts, output);
-        if (!response.ok) {
+        // Route the /healthz check through `probeHealth` so we inherit retry
+        // on transient transport errors AND a try/catch that turns a transient
+        // ECONNRESET into a structured `health_probe_failed` result instead of
+        // a raw stack trace. The previous bare `fetch` had no try/catch and
+        // would crash `copillm health` if the daemon had just been killed
+        // between `inspectLock` and the request.
+        const health = await probeHealth(lockState.lock.port);
+        const payload = {
+            ok: health.ok,
+            status_code: health.statusCode
+        };
+        if (health.status !== null)
+            payload.status = health.status;
+        if (health.error !== null)
+            payload.error = health.error;
+        if (health.bearerTtlSeconds !== null)
+            payload.bearer_ttl_seconds = health.bearerTtlSeconds;
+        writeHealthOutput(opts, payload);
+        if (!health.ok) {
             process.exitCode = 1;
         }
     });
 }
+/**
+ * Load the shared credential/config/discovery context for `copillm start`'s
+ * codex + pi init steps, ONLY when at least one of them is going to run.
+ *
+ * Without sharing, each step independently re-reads the OS keychain, re-parses
+ * the YAML config, and re-fetches the upstream `/models` catalog. With this
+ * helper, the work happens once and both steps see the same snapshot.
+ *
+ * When both `--no-codex` and `--no-pi` are passed (or both wrappers will skip
+ * for some other reason), there's no consumer for the context, so we skip
+ * the loads entirely — important for `copillm start --no-codex --no-pi` to
+ * stay fast and not surface a credential error if the user genuinely just
+ * wants the proxy daemon up.
+ *
+ * Returning `undefined` (not `null`) so it composes naturally with the
+ * `precomputed?: PrecomputedStartContext` optional parameter on both
+ * `refreshCodexHome` and `refreshPiHome`.
+ */
+async function loadSharedStartContextIfNeeded(opts) {
+    if (opts.codex === false && opts.pi === false) {
+        return undefined;
+    }
+    try {
+        return await resolveStartContext();
+    }
+    catch {
+        // If the load fails (e.g. no credentials, model discovery down), fall
+        // back to per-wrapper loads so each one can fail loudly with its own
+        // wrapper-specific warning. The wrappers already have try/catch that
+        // emit `warning: failed to generate ...` lines — preserving that
+        // surface keeps the user-visible behaviour unchanged from before.
+        return undefined;
+    }
+}

package/dist/cli/commands/models.js

@@ -1,5 +1,4 @@
 import { loadStoredCredential } from "../../auth/credentials.js";
-import { CopilotTokenManager } from "../../auth/copilotToken.js";
 import { loadConfig, saveConfig } from "../../config/config.js";
 import { listModels, resolveModelSelections } from "../../models/discovery.js";
 import { writeCommandOutput } from "../shared/output.js";
@@ -15,8 +14,6 @@ export function register(program) {
         if (!creds) {
             throw new Error("Not authenticated. Run `copillm login`.");
         }
-        const tokenManager = new CopilotTokenManager(creds.token);
-        await tokenManager.ensureToken(false);
         const result = await listModels(config.accountType, creds.token);
         if (opts.json) {
             process.stdout.write(JSON.stringify({
@@ -53,8 +50,6 @@ export function register(program) {
         if (!creds) {
             throw new Error("Not authenticated. Run `copillm login`.");
         }
-        const tokenManager = new CopilotTokenManager(creds.token);
-        await tokenManager.ensureToken(false);
         const discovery = await listModels(config.accountType, creds.token);
         const resolution = resolveModelSelections(requested, discovery.models);
         if (resolution.unresolved.length > 0) {

package/dist/cli/daemon/lifecycle.js

@@ -59,3 +59,29 @@ export function computeUptimeSeconds(startedAtIso) {
     }
     return Math.max(0, Math.floor((Date.now() - startedMs) / 1000));
 }
+/**
+ * Render an uptime duration (in seconds) as a compact human-readable string
+ * broken down into days, hours, minutes, and seconds — e.g. `2d 3h 15m 9s`.
+ *
+ * Leading zero-value units are dropped so short uptimes stay terse
+ * (`45s`, `5m 2s`). Sub-minute and zero durations fall back to a seconds
+ * component so the result is never empty (`0s`). Negative or non-finite
+ * inputs clamp to `0s`.
+ */
+export function formatUptime(totalSeconds) {
+    const seconds = Number.isFinite(totalSeconds) ? Math.max(0, Math.floor(totalSeconds)) : 0;
+    const days = Math.floor(seconds / 86_400);
+    const hours = Math.floor((seconds % 86_400) / 3_600);
+    const minutes = Math.floor((seconds % 3_600) / 60);
+    const secs = seconds % 60;
+    const parts = [];
+    if (days > 0)
+        parts.push(`${days}d`);
+    if (hours > 0)
+        parts.push(`${hours}h`);
+    if (minutes > 0)
+        parts.push(`${minutes}m`);
+    if (secs > 0 || parts.length === 0)
+        parts.push(`${secs}s`);
+    return parts.join(" ");
+}

package/dist/cli/daemon/probes.js

@@ -1,23 +1,77 @@
-import { setTimeout as sleep } from "node:timers/promises";
+import { setTimeout as defaultSleep } from "node:timers/promises";
 import { inspectLock } from "../../server/lock.js";
 import { isPidAlive } from "./lifecycle.js";
-export async function probeLivez(port) {
-    try {
-        const response = await fetch(`http://127.0.0.1:${port}/livez`, { signal: AbortSignal.timeout(800) });
-        return response.ok;
-    }
-    catch {
-        return false;
+/**
+ * Retry helper for loopback fetches. Localhost RTT is sub-millisecond on a
+ * healthy daemon, so a 100ms inter-attempt sleep is enough to give a freshly
+ * spawned process time to bind, while still keeping total wall-clock for a
+ * "probe + 2 retries" sequence well under a second.
+ *
+ * Only AbortError + transport-class errors trigger retries — a 4xx/5xx
+ * response from the daemon is a real signal (the route exists but
+ * disagrees with us), and retrying just delays the answer the caller
+ * needs to surface. The set is narrow on purpose: we don't want to retry
+ * ECONNREFUSED forever on a daemon that genuinely isn't running.
+ */
+const LOOPBACK_PROBE_BACKOFF_MS = 100;
+async function probeWithRetry(attempt, options = {}) {
+    const maxAttempts = Math.max(1, options.attempts ?? 3);
+    const sleepImpl = options.sleepImpl ?? ((ms) => defaultSleep(ms));
+    const backoffMs = options.backoffMs ?? LOOPBACK_PROBE_BACKOFF_MS;
+    let last = { ok: null, failed: true, error: undefined };
+    for (let i = 0; i < maxAttempts; i += 1) {
+        const result = await attempt();
+        if (!result.failed) {
+            return result;
+        }
+        last = result;
+        if (!isRetryableProbeError(result.error)) {
+            return result;
+        }
+        if (i < maxAttempts - 1) {
+            await sleepImpl(backoffMs);
+        }
     }
+    return last;
 }
-export async function probeDebugEndpoint(port) {
-    try {
-        const response = await fetch(`http://127.0.0.1:${port}/_debug`, { signal: AbortSignal.timeout(1_200) });
-        return response.ok;
-    }
-    catch {
+function isRetryableProbeError(error) {
+    if (!error || typeof error !== "object")
         return false;
-    }
+    const typed = error;
+    if (typed.name === "AbortError" || typed.name === "TimeoutError")
+        return true;
+    const code = typed.code?.toUpperCase() ?? typed.cause?.code?.toUpperCase();
+    // ECONNREFUSED *is* retried here even though it usually means "nothing
+    // listening": a daemon racing to bind right after spawn returns
+    // ECONNREFUSED for a tiny window, and probes do call us from spawn-adjacent
+    // paths (`waitForDaemonReady` polls; `acquireLock`'s isRunning callback
+    // checks an existing lock). The 100ms inter-attempt sleep is enough for
+    // the bind race to settle.
+    return code === "ECONNRESET" || code === "ECONNREFUSED" || code === "ETIMEDOUT";
+}
+export async function probeLivez(port, options) {
+    const result = await probeWithRetry(async () => {
+        try {
+            const response = await fetch(`http://127.0.0.1:${port}/livez`, { signal: AbortSignal.timeout(800) });
+            return { ok: response.ok, failed: false };
+        }
+        catch (error) {
+            return { ok: null, failed: true, error };
+        }
+    }, options);
+    return result.failed ? false : result.ok;
+}
+export async function probeDebugEndpoint(port, options) {
+    const result = await probeWithRetry(async () => {
+        try {
+            const response = await fetch(`http://127.0.0.1:${port}/_debug`, { signal: AbortSignal.timeout(1_200) });
+            return { ok: response.ok, failed: false };
+        }
+        catch (error) {
+            return { ok: null, failed: true, error };
+        }
+    }, options);
+    return result.failed ? false : result.ok;
 }
 export async function warnIfDebugRequestedButInactive(debugRequested, port) {
     if (!debugRequested) {
@@ -29,21 +83,29 @@ export async function warnIfDebugRequestedButInactive(debugRequested, port) {
     }
     return active;
 }
-export async function probeHealth(port) {
-    try {
-        const response = await fetch(`http://127.0.0.1:${port}/healthz`, { signal: AbortSignal.timeout(1_500) });
-        const payload = (await response.json());
-        return {
-            ok: response.ok,
-            statusCode: response.status,
-            status: typeof payload.status === "string" ? payload.status : null,
-            error: typeof payload.error === "string" ? payload.error : null,
-            bearerTtlSeconds: response.ok && typeof payload.bearer_ttl_seconds === "number" ? payload.bearer_ttl_seconds : null
-        };
-    }
-    catch {
-        return { ok: false, bearerTtlSeconds: null, statusCode: null, status: null, error: "health_probe_failed" };
-    }
+export async function probeHealth(port, options) {
+    const result = await probeWithRetry(async () => {
+        try {
+            const response = await fetch(`http://127.0.0.1:${port}/healthz`, { signal: AbortSignal.timeout(1_500) });
+            const payload = (await response.json());
+            return {
+                ok: {
+                    ok: response.ok,
+                    statusCode: response.status,
+                    status: typeof payload.status === "string" ? payload.status : null,
+                    error: typeof payload.error === "string" ? payload.error : null,
+                    bearerTtlSeconds: response.ok && typeof payload.bearer_ttl_seconds === "number" ? payload.bearer_ttl_seconds : null
+                },
+                failed: false
+            };
+        }
+        catch (error) {
+            return { ok: null, failed: true, error };
+        }
+    }, options);
+    return result.failed
+        ? { ok: false, bearerTtlSeconds: null, statusCode: null, status: null, error: "health_probe_failed" }
+        : result.ok;
 }
 export async function readLiveLock() {
     const lockState = inspectLock();
@@ -52,17 +114,21 @@ export async function readLiveLock() {
     }
     return (await probeLivez(lockState.lock.port)) ? lockState.lock : null;
 }
-export async function waitForDaemonReady(pid, timeoutMs) {
+export async function waitForDaemonReady(pid, timeoutMs, options) {
+    const sleepImpl = options?.sleepImpl ?? ((ms) => defaultSleep(ms));
     const startedAt = Date.now();
     while (Date.now() - startedAt <= timeoutMs) {
         const lockState = inspectLock();
-        if (lockState.state === "running" && (await probeLivez(lockState.lock.port))) {
+        // Use a single-attempt probe inside this poll loop — the outer 150ms
+        // loop already retries naturally. Letting `probeLivez` retry internally
+        // here would compound delays.
+        if (lockState.state === "running" && (await probeLivez(lockState.lock.port, { attempts: 1 }))) {
             return { pid: lockState.lock.pid, port: lockState.lock.port };
         }
         if (pid !== null && !isPidAlive(pid)) {
             return null;
         }
-        await sleep(150);
+        await sleepImpl(150);
     }
     return null;
 }

package/dist/cli/index.js

@@ -10,18 +10,30 @@ import * as claudeCmd from "./commands/agents/claude.js";
 import * as piCmd from "./commands/agents/pi.js";
 import * as copilotCmd from "./commands/agents/copilot.js";
 import { setRootLogger, setRootProgram } from "./shared/debug.js";
+import { applyDevModeEnv } from "./shared/devMode.js";
 import { getPackageInfo } from "./packageInfo.js";
 import { maybeNotifyAboutUpdate } from "./updateNotifier.js";
 const logger = createLogger();
 const program = new Command();
 setRootProgram(program);
 setRootLogger(logger);
+// Honor COPILLM_DEV before anything reads COPILLM_HOME (e.g. the update
+// notifier). The `--dev` flag form is applied later, in the preAction hook,
+// once commander has parsed global options.
+applyDevModeEnv();
 const pkg = getPackageInfo();
 await maybeNotifyAboutUpdate({ packageInfo: pkg });
 program.name("copillm").description("Local Copilot proxy").version(pkg.version);
 program.enablePositionalOptions();
 program.option("--debug", "Enable copillm debug mode (debug endpoint plus verbose daemon diagnostics)");
+program.option("--dev", "Run against an isolated dev home (COPILLM_HOME=~/.copillm-dev, port 4142) so the dev daemon never conflicts with a production copillm");
 program.option("--no-update-notifier", "Skip the npm registry update check for this run");
+// Apply the `--dev` flag as soon as global options are parsed and before any
+// subcommand action resolves COPILLM_HOME. Idempotent with the env-based call
+// above.
+program.hook("preAction", () => {
+    applyDevModeEnv(Boolean(program.opts().dev));
+});
 authCmd.register(program);
 daemonCmd.register(program);
 modelsCmd.register(program);

package/dist/cli/integrations/refreshCodex.js

@@ -1,6 +1,6 @@
 import { getCopillmHome } from "../../config/home.js";
 import { defaultOutputDir, generateCodexHome } from "../../integrations/codex/init.js";
-export async function refreshCodexHome(port, model) {
+export async function refreshCodexHome(port, model, precomputed) {
     try {
         const home = getCopillmHome();
         return await generateCodexHome({
@@ -8,7 +8,8 @@ export async function refreshCodexHome(port, model) {
             model,
             port,
             providerId: "copillm",
-            reasoningEffort: null
+            reasoningEffort: null,
+            precomputed
         });
     }
     catch (error) {

package/dist/cli/integrations/refreshPi.js

@@ -1,12 +1,13 @@
 import { getCopillmHome } from "../../config/home.js";
 import { defaultOutputDir as defaultPiOutputDir, generatePiHome } from "../../integrations/pi/init.js";
-export async function refreshPiHome(port) {
+export async function refreshPiHome(port, precomputed) {
     try {
         const home = getCopillmHome();
         return await generatePiHome({
             outDir: defaultPiOutputDir(home),
             port,
-            providerId: "copillm"
+            providerId: "copillm",
+            precomputed
         });
     }
     catch (error) {

package/dist/cli/packageInfo.js

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 const FALLBACK_PACKAGE_INFO = {
     name: "copillm",
-    version: "0.2.7"
+    version: "0.2.9"
 };
 export function getPackageInfo() {
     const envName = cleanPackageValue(process.env.COPILLM_PACKAGE_NAME);

package/dist/cli/shared/devMode.js

@@ -0,0 +1,98 @@
+import os from "node:os";
+import path from "node:path";
+/**
+ * Dev-mode isolation.
+ *
+ * Running a locally-built copillm against the SAME `~/.copillm` home and port as
+ * a globally-installed production daemon is a footgun: `stop` reads
+ * `~/.copillm/copillm.pid` and would kill the production daemon, and `start`
+ * sees the production lock and reports "already running" instead of launching
+ * your dev code.
+ *
+ * Dev mode redirects the runtime onto a separate `COPILLM_HOME` (and a distinct
+ * default port) so a dev daemon and a production daemon can run side by side
+ * without ever touching each other's lock, config, model cache, or port. This
+ * is the mechanism that lets you develop copillm WHILE using copillm.
+ *
+ * The override is implemented by setting the same `COPILLM_HOME` / `COPILLM_PORT`
+ * env vars the rest of the codebase already reads (see `src/config/home.ts` and
+ * `src/config/config.ts`). Because detached daemons and spawned agents inherit
+ * `process.env`, the isolation propagates to every child process for free.
+ *
+ * Activated by the global `--dev` flag or by exporting `COPILLM_DEV=1`. The
+ * concrete locations are overridable via `COPILLM_DEV_HOME` / `COPILLM_DEV_PORT`.
+ * An explicitly-set `COPILLM_HOME` / `COPILLM_PORT` always wins — dev mode never
+ * clobbers a home or port the user pinned on purpose.
+ */
+export const DEV_HOME_DIRNAME = ".copillm-dev";
+export const DEFAULT_DEV_PORT = 4142;
+// Set once dev mode has been applied for this process, so command surfaces
+// (start banner, status) can annotate output without re-deriving intent.
+let devModeActive = false;
+/** Whether dev mode has been applied to this process. */
+export function isDevModeActive() {
+    return devModeActive;
+}
+function isTruthyEnv(value) {
+    if (value === undefined) {
+        return false;
+    }
+    return /^(1|true|yes|on)$/i.test(value.trim());
+}
+function nonEmptyEnv(value) {
+    if (value === undefined) {
+        return null;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+/**
+ * Whether dev mode was requested, via the `--dev` flag (passed in) or the
+ * `COPILLM_DEV` env var.
+ */
+export function isDevModeRequested(flag) {
+    return Boolean(flag) || isTruthyEnv(process.env.COPILLM_DEV);
+}
+/** The isolated dev home: `COPILLM_DEV_HOME` if set, else `~/.copillm-dev`. */
+export function resolveDevHome() {
+    const override = nonEmptyEnv(process.env.COPILLM_DEV_HOME);
+    if (override) {
+        return path.resolve(override);
+    }
+    return path.join(os.homedir(), DEV_HOME_DIRNAME);
+}
+/** The isolated dev port: `COPILLM_DEV_PORT` if set, else `4142`. */
+export function resolveDevPort() {
+    const override = nonEmptyEnv(process.env.COPILLM_DEV_PORT);
+    if (override) {
+        return override;
+    }
+    return String(DEFAULT_DEV_PORT);
+}
+/**
+ * Apply dev-mode isolation to `process.env` when requested. Idempotent and
+ * safe to call multiple times.
+ *
+ * - No-op when dev mode is not requested.
+ * - Sets `COPILLM_HOME` to the dev home ONLY when it is not already set, so an
+ *   explicit `COPILLM_HOME` always wins.
+ * - Sets `COPILLM_PORT` to the dev port ONLY when it is not already set, so an
+ *   explicit `COPILLM_PORT` always wins.
+ */
+export function applyDevModeEnv(flag) {
+    if (!isDevModeRequested(flag)) {
+        return { active: false, home: null, port: null };
+    }
+    if (!nonEmptyEnv(process.env.COPILLM_HOME)) {
+        process.env.COPILLM_HOME = resolveDevHome();
+    }
+    if (!nonEmptyEnv(process.env.COPILLM_PORT)) {
+        process.env.COPILLM_PORT = resolveDevPort();
+    }
+    devModeActive = true;
+    return {
+        active: true,
+        home: process.env.COPILLM_HOME ?? null,
+        port: process.env.COPILLM_PORT ?? null
+    };
+}

package/dist/config/config.js

@@ -23,7 +23,7 @@ export function loadConfig() {
     const file = configReadPath();
     if (!fs.existsSync(file)) {
         saveConfig(DEFAULT_CONFIG);
-        return DEFAULT_CONFIG;
+        return applyEnvOverrides(DEFAULT_CONFIG);
     }
     const raw = readFileSync(file, "utf8");
     let parsed;
@@ -33,7 +33,7 @@ export function loadConfig() {
     catch (error) {
         throw new Error(`Invalid YAML in config file: ${file}`, { cause: error });
     }
-    return parseConfigValue(parsed, file);
+    return applyEnvOverrides(parseConfigValue(parsed, file));
 }
 export function saveConfig(config) {
     ensureAppHome();
@@ -49,3 +49,14 @@ function parseConfigValue(value, source) {
     const issues = result.error.issues.map((issue) => `${issue.path.join(".") || "<root>"}: ${issue.message}`).join("; ");
     throw new Error(`Invalid config schema in ${source}: ${issues}`);
 }
+function applyEnvOverrides(config) {
+    const port = process.env.COPILLM_PORT;
+    if (port === undefined || port.trim().length === 0) {
+        return config;
+    }
+    const parsedPort = Number(port.trim());
+    if (!Number.isInteger(parsedPort) || parsedPort < 1 || parsedPort > 65535) {
+        throw new Error("Invalid COPILLM_PORT: expected an integer between 1 and 65535.");
+    }
+    return { ...config, preferredPort: parsedPort };
+}

package/dist/config/home.js

@@ -35,6 +35,40 @@ export function modelsCacheReadPath() {
 export function debugLogPath() {
     return path.join(getCopillmHome(), "debug.log");
 }
+/**
+ * The directory pi (`@earendil-works/pi-coding-agent`) reads its config from.
+ *
+ * pi exposes this via the `PI_CODING_AGENT_DIR` env var — its own `getAgentDir()`
+ * treats the value as the agent dir directly (equivalent to `~/.pi/agent`).
+ * copillm owns this path: it defaults to `<COPILLM_HOME>/pi/agent` so copillm
+ * never writes into the user's real `~/.pi`, and dev mode relocates it for free
+ * via COPILLM_HOME. An explicitly-set `PI_CODING_AGENT_DIR` always wins.
+ */
+export function piAgentDir() {
+    const overridden = process.env.PI_CODING_AGENT_DIR;
+    if (overridden && overridden.trim().length > 0) {
+        return path.resolve(overridden.trim());
+    }
+    return path.join(getCopillmHome(), "pi", "agent");
+}
+/**
+ * The config home Claude Code reads (its `~/.claude` equivalent), exposed by
+ * Claude Code as the `CLAUDE_CONFIG_DIR` env var.
+ *
+ * copillm owns this path: it defaults to `<COPILLM_HOME>/claude/home` and copillm
+ * exports `CLAUDE_CONFIG_DIR` to it when launching Claude (see
+ * `buildClaudeEnvBundle`). This keeps copillm out of the user's real `~/.claude`
+ * — copillm-launched Claude gets a deterministic, copillm-owned config home, and
+ * dev mode relocates it for free via COPILLM_HOME. An explicitly-set
+ * `CLAUDE_CONFIG_DIR` always wins.
+ */
+export function claudeConfigDir() {
+    const overridden = process.env.CLAUDE_CONFIG_DIR;
+    if (overridden && overridden.trim().length > 0) {
+        return path.resolve(overridden.trim());
+    }
+    return path.join(getCopillmHome(), "claude", "home");
+}
 function resolveReadablePath(fileName) {
     const canonical = path.join(getCopillmHome(), fileName);
     if (fs.existsSync(canonical)) {