copillm 0.2.8 → 0.3.0-beta.1

package/dist/auth/credentials.js

@@ -2,19 +2,72 @@ import fs from "node:fs";
 import { readFileSync } from "node:fs";
 import { z } from "zod";
 import { ensureAppHome } from "../config/config.js";
-import { credentialsPath, credentialsReadPath } from "../config/home.js";
+import { accountCredentialsPath, accountCredentialsReadPath, credentialsPath, credentialsReadPath } from "../config/home.js";
 import { writeFileSecureAtomic } from "../config/fsSecurity.js";
+import { assertValidAccountId, findAccount, readAccountsIndex, upsertAccount } from "./accounts.js";
 const SERVICE = "copillm";
-const ACCOUNT = "github-oauth-token";
+// The legacy keychain account string. Single-account installs (and the default
+// account on multi-account installs) keep using this exact key so upgrading to
+// a multi-account-aware build never invalidates an existing login. Additional
+// accounts are namespaced as `${LEGACY_ACCOUNT}:<id>`.
+const LEGACY_ACCOUNT = "github-oauth-token";
+// Map key for the default account's in-memory session credential. Chosen so it
+// can't collide with a real account id (those can't contain ':').
+const DEFAULT_SESSION_KEY = "::default::";
+function legacyStorage() {
+    return {
+        keychainAccount: LEGACY_ACCOUNT,
+        filePath: credentialsPath(),
+        fileReadPath: credentialsReadPath(),
+        sessionKey: DEFAULT_SESSION_KEY
+    };
+}
+function namespacedStorage(accountId) {
+    assertValidAccountId(accountId);
+    return {
+        keychainAccount: `${LEGACY_ACCOUNT}:${accountId}`,
+        filePath: accountCredentialsPath(accountId),
+        fileReadPath: accountCredentialsReadPath(accountId),
+        sessionKey: accountId
+    };
+}
+function storageForScheme(accountId, scheme) {
+    return scheme === "legacy" ? legacyStorage() : namespacedStorage(accountId);
+}
+/**
+ * Resolve the storage for a specific account id. A registered account uses the
+ * scheme recorded in its index entry (so the default/legacy account keeps the
+ * legacy keys even when addressed by id). An unregistered id is assumed to be a
+ * not-yet-persisted named account and gets namespaced storage.
+ */
+function storageForAccountId(accountId) {
+    const record = findAccount(accountId);
+    return record ? storageForScheme(record.id, record.storage) : namespacedStorage(accountId);
+}
+/**
+ * Storage for the *default* account. With no accounts index this is the legacy
+ * single-account storage — the path every existing install takes — so the
+ * exported `loadStoredCredential` / `saveStoredCredential` / etc. behave
+ * identically to the pre-multi-account build.
+ */
+function defaultAccountStorage() {
+    const index = readAccountsIndex();
+    if (!index) {
+        return legacyStorage();
+    }
+    const record = index.accounts.find((account) => account.id === index.defaultAccount);
+    return record ? storageForScheme(record.id, record.storage) : legacyStorage();
+}
 const FileCredentialSchema = z.object({
     version: z.literal(1),
     github_token: z.string().min(1),
     account_type: z.enum(["individual", "business", "enterprise"]),
     saved_at: z.string().min(1)
 });
-// Module-level in-memory credential. Only populated when SaveMode === "session".
-// Never persisted; cleared on clearStoredCredential() and on process exit.
-let sessionCredential = null;
+// Module-level in-memory credentials, keyed by account session key. Only
+// populated when SaveMode === "session". Never persisted; cleared on
+// clearStoredCredential() and on process exit.
+const sessionCredentials = new Map();
 function forceSessionBackend() {
     return process.env.COPILLM_FORCE_SESSION_BACKEND === "1";
 }
@@ -97,18 +150,17 @@ async function resolveKeyring() {
     }
     return { keyring: null, reason: "keyring module is unavailable on this machine" };
 }
-function parseCredentialFile() {
-    const path = credentialsReadPath();
-    const raw = readFileSync(path, "utf8");
+function parseCredentialFile(readPath) {
+    const raw = readFileSync(readPath, "utf8");
     let parsedJson;
     try {
         parsedJson = JSON.parse(raw);
     }
     catch (error) {
         if (error instanceof Error) {
-            throw new Error(`Credential file exists but contains invalid JSON at ${path}: ${error.message}`);
+            throw new Error(`Credential file exists but contains invalid JSON at ${readPath}: ${error.message}`);
         }
-        throw new Error(`Credential file exists but contains invalid JSON at ${path}.`);
+        throw new Error(`Credential file exists but contains invalid JSON at ${readPath}.`);
     }
     try {
         const parsed = FileCredentialSchema.parse(parsedJson);
@@ -116,12 +168,12 @@ function parseCredentialFile() {
     }
     catch (error) {
         if (error instanceof Error) {
-            throw new Error(`Credential file exists but is invalid at ${path}: ${error.message}`);
+            throw new Error(`Credential file exists but is invalid at ${readPath}: ${error.message}`);
         }
-        throw new Error(`Credential file exists but is invalid at ${path}.`);
+        throw new Error(`Credential file exists but is invalid at ${readPath}.`);
     }
 }
-function writeCredentialFile(token, accountType) {
+function writeCredentialFile(writePath, token, accountType) {
     ensureAppHome();
     const payload = {
         version: 1,
@@ -129,7 +181,7 @@ function writeCredentialFile(token, accountType) {
         account_type: accountType,
         saved_at: new Date().toISOString()
     };
-    writeFileSecureAtomic(credentialsPath(), JSON.stringify(payload, null, 2), 0o600);
+    writeFileSecureAtomic(writePath, JSON.stringify(payload, null, 2), 0o600);
 }
 function canUsePlaintextFallback() {
     if (forceSessionBackend()) {
@@ -152,11 +204,11 @@ function isMissingKeyringError(error) {
  * this helper to avoid accidentally pulling the secret into a code path that
  * might log or print it.
  */
-export async function inspectStoredCredential() {
-    if (sessionCredential) {
+async function inspectStorage(storage) {
+    if (sessionCredentials.has(storage.sessionKey)) {
         return { stored: true, backend: "session" };
     }
-    if (fs.existsSync(credentialsReadPath())) {
+    if (fs.existsSync(storage.fileReadPath)) {
         return { stored: true, backend: "file" };
     }
     const { keyring } = await resolveKeyring();
@@ -164,7 +216,7 @@ export async function inspectStoredCredential() {
         return { stored: false, backend: null };
     }
     try {
-        const token = await keyring.getPassword(SERVICE, ACCOUNT);
+        const token = await keyring.getPassword(SERVICE, storage.keychainAccount);
         if (token) {
             return { stored: true, backend: "keyring" };
         }
@@ -177,12 +229,13 @@ export async function inspectStoredCredential() {
         throw new Error("Failed to read token from OS keychain.");
     }
 }
-export async function loadStoredCredential() {
-    if (sessionCredential) {
-        return { token: sessionCredential.token, accountType: sessionCredential.accountType, source: "session" };
+async function loadStorage(storage) {
+    const session = sessionCredentials.get(storage.sessionKey);
+    if (session) {
+        return { token: session.token, accountType: session.accountType, source: "session" };
     }
-    if (fs.existsSync(credentialsReadPath())) {
-        const parsed = parseCredentialFile();
+    if (fs.existsSync(storage.fileReadPath)) {
+        const parsed = parseCredentialFile(storage.fileReadPath);
         return { token: parsed.token, accountType: parsed.accountType, source: "file" };
     }
     const { keyring } = await resolveKeyring();
@@ -191,7 +244,7 @@ export async function loadStoredCredential() {
     }
     let token;
     try {
-        token = await keyring.getPassword(SERVICE, ACCOUNT);
+        token = await keyring.getPassword(SERVICE, storage.keychainAccount);
     }
     catch (error) {
         if (error instanceof Error) {
@@ -204,21 +257,47 @@ export async function loadStoredCredential() {
     }
     return { token, accountType: "individual", source: "keyring" };
 }
-export async function saveStoredCredential(token, accountType, options = {}) {
-    const mode = options.mode ?? "auto";
+async function loadStorageForStatus(storage) {
+    const session = sessionCredentials.get(storage.sessionKey);
+    if (session) {
+        return { stored: true, backend: "session", token: session.token };
+    }
+    if (fs.existsSync(storage.fileReadPath)) {
+        const parsed = parseCredentialFile(storage.fileReadPath);
+        return { stored: true, backend: "file", token: parsed.token };
+    }
+    const { keyring } = await resolveKeyring();
+    if (!keyring) {
+        return { stored: false, backend: null, token: null };
+    }
+    try {
+        const token = await keyring.getPassword(SERVICE, storage.keychainAccount);
+        if (token) {
+            return { stored: true, backend: "keyring", token };
+        }
+        return { stored: false, backend: null, token: null };
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new Error(`Failed to read token from OS keychain: ${error.message}`);
+        }
+        throw new Error("Failed to read token from OS keychain.");
+    }
+}
+async function saveStorage(storage, token, accountType, mode) {
     if (mode === "session") {
-        sessionCredential = { token, accountType };
+        sessionCredentials.set(storage.sessionKey, { token, accountType });
         return "session";
     }
-    if (fs.existsSync(credentialsReadPath())) {
-        parseCredentialFile();
-        writeCredentialFile(token, accountType);
+    if (fs.existsSync(storage.fileReadPath)) {
+        parseCredentialFile(storage.fileReadPath);
+        writeCredentialFile(storage.filePath, token, accountType);
         return "file";
     }
     const { keyring, reason } = await resolveKeyring();
     if (keyring) {
         try {
-            await keyring.setPassword(SERVICE, ACCOUNT, token);
+            await keyring.setPassword(SERVICE, storage.keychainAccount, token);
             return "keyring";
         }
         catch (error) {
@@ -231,15 +310,14 @@ export async function saveStoredCredential(token, accountType, options = {}) {
     if (!canUsePlaintextFallback()) {
         throw new Error(`OS keychain backend unavailable (${reason ?? "unknown reason"}). Plaintext fallback is disabled in non-interactive mode; set COPILLM_ALLOW_PLAINTEXT_CREDENTIALS=1 to allow it.`);
     }
-    writeCredentialFile(token, accountType);
+    writeCredentialFile(storage.filePath, token, accountType);
     return "file";
 }
-export async function clearStoredCredential() {
+async function clearStorage(storage) {
     // Always clear in-memory session token first; it shadows other backends.
-    const hadSession = sessionCredential !== null;
-    sessionCredential = null;
-    const readablePath = credentialsReadPath();
-    const canonicalPath = credentialsPath();
+    const hadSession = sessionCredentials.delete(storage.sessionKey);
+    const readablePath = storage.fileReadPath;
+    const canonicalPath = storage.filePath;
     if (fs.existsSync(readablePath)) {
         fs.unlinkSync(readablePath);
         if (readablePath !== canonicalPath && fs.existsSync(canonicalPath)) {
@@ -250,7 +328,7 @@ export async function clearStoredCredential() {
     const { keyring, reason } = await resolveKeyring();
     if (keyring) {
         try {
-            const removed = await keyring.deletePassword(SERVICE, ACCOUNT);
+            const removed = await keyring.deletePassword(SERVICE, storage.keychainAccount);
             return { backend: "keyring", removed: removed || hadSession };
         }
         catch (error) {
@@ -265,8 +343,106 @@ export async function clearStoredCredential() {
     }
     throw new Error(`No credential backend available to clear credentials (${reason ?? "unknown reason"}).`);
 }
-// Test seam: forcibly clear the in-memory session credential. Not exported via
+// ---------------------------------------------------------------------------
+// Default-account surface. With no accounts index these operate on the legacy
+// single-account storage, so behaviour is identical to the pre-multi-account
+// build. With an index they target whichever account is currently the default.
+// ---------------------------------------------------------------------------
+export async function inspectStoredCredential() {
+    return inspectStorage(defaultAccountStorage());
+}
+export async function loadStoredCredential() {
+    return loadStorage(defaultAccountStorage());
+}
+/**
+ * Coalesced inspect + load for status surfaces. Returns the same fields
+ * `inspectStoredCredential` exposes (`stored` + `backend`) AND the
+ * `token` — but performs only ONE backend probe.
+ *
+ * Previously, `auth status` with user-lookup enabled did:
+ *   1. `inspectStoredCredential` → one `keyring.getPassword` (backend probe)
+ *   2. `loadStoredCredential` (inside `inspectGithubIdentity`) → another
+ *      `keyring.getPassword` (full token read)
+ *
+ * On macOS, each call is its own keychain audit-log entry and (on a
+ * misconfigured system) its own permission prompt. This helper folds both
+ * into a single backend probe + single read.
+ *
+ * SECURITY: callers MUST treat the `token` field as sensitive — do not log,
+ * print, or persist it. The status JSON output and `formatHumanAuthStatusLine`
+ * only consume `backend` (and the upstream identity summary returned by
+ * `inspectGithubIdentity`), never `token` directly. Enforced at the call
+ * site (`tests/integration/authStatusCli.test.ts` runs a substring-leak
+ * guard on the printed output).
+ */
+export async function loadStoredCredentialForStatus() {
+    return loadStorageForStatus(defaultAccountStorage());
+}
+export async function saveStoredCredential(token, accountType, options = {}) {
+    return saveStorage(defaultAccountStorage(), token, accountType, options.mode ?? "auto");
+}
+export async function clearStoredCredential() {
+    return clearStorage(defaultAccountStorage());
+}
+// ---------------------------------------------------------------------------
+// Account-scoped surface. These address a specific account by id regardless of
+// which one is the default. A registered account uses the storage scheme from
+// its index entry (so the legacy/default account keeps the legacy keys); an
+// unregistered id is treated as a not-yet-persisted namespaced account.
+// ---------------------------------------------------------------------------
+export async function inspectStoredCredentialForAccount(accountId) {
+    return inspectStorage(storageForAccountId(accountId));
+}
+export async function loadStoredCredentialForAccount(accountId) {
+    const loaded = await loadStorage(storageForAccountId(accountId));
+    if (!loaded) {
+        return loaded;
+    }
+    // The keychain backend can't store the account type, so `loadStorage`
+    // defaults it to "individual". The index records the real type per account —
+    // prefer it so model-discovery base-URL selection stays correct.
+    if (loaded.source === "keyring") {
+        const record = findAccount(accountId);
+        if (record) {
+            return { ...loaded, accountType: record.accountType };
+        }
+    }
+    return loaded;
+}
+export async function saveStoredCredentialForAccount(accountId, token, accountType, options = {}) {
+    return saveStorage(storageForAccountId(accountId), token, accountType, options.mode ?? "auto");
+}
+export async function clearStoredCredentialForAccount(accountId) {
+    return clearStorage(storageForAccountId(accountId));
+}
+/**
+ * Materialize the accounts index from a pre-existing single-account install.
+ * Registers the current legacy credential as the default account with
+ * `storage: "legacy"` so its token is **not moved** — the keychain entry and
+ * `credentials.json` stay exactly where they are. Idempotent: if the index
+ * already exists it is returned unchanged. Use this before adding a second
+ * account so the original login is represented without any invalidation risk.
+ */
+export function registerExistingCredentialAsDefault(accountId, accountType) {
+    assertValidAccountId(accountId);
+    const existing = readAccountsIndex();
+    if (existing) {
+        const current = existing.accounts.find((account) => account.id === existing.defaultAccount);
+        if (current) {
+            return current;
+        }
+    }
+    const record = {
+        id: accountId,
+        accountType,
+        storage: "legacy",
+        addedAt: new Date().toISOString()
+    };
+    upsertAccount(record);
+    return record;
+}
+// Test seam: forcibly clear all in-memory session credentials. Not exported via
 // the package surface for end users — only used by unit tests.
 export function __resetSessionCredentialForTests() {
-    sessionCredential = null;
+    sessionCredentials.clear();
 }

package/dist/auth/deviceFlow.js

@@ -1,32 +1,67 @@
+import { setTimeout as defaultSleep } from "node:timers/promises";
+import { isRetryableStatus, isRetryableTransportError, retryDelayMs } from "../server/upstream/retryPolicy.js";
 const GITHUB_CLIENT_ID = "Iv1.b507a08c87ecfe98";
 const DEVICE_CODE_URL = "https://github.com/login/device/code";
 const ACCESS_TOKEN_URL = "https://github.com/login/oauth/access_token";
-export async function loginViaDeviceFlow() {
-    const start = await fetch(DEVICE_CODE_URL, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
-        body: new URLSearchParams({ client_id: GITHUB_CLIENT_ID, scope: "read:user" })
-    });
-    if (!start.ok) {
-        throw new Error(`Device flow init failed (${start.status}).`);
-    }
-    const payload = parseDeviceCodeResponse((await start.json()));
+/**
+ * Per-attempt timeout for the init POST + each poll POST. GitHub's device-
+ * flow endpoints typically respond in <500ms; 10s leaves room for slow
+ * networks without freezing the login flow for a full minute on a network
+ * black-hole. Previously the fetches had no timeout at all.
+ */
+const DEFAULT_FETCH_TIMEOUT_MS = 10_000;
+const DEFAULT_INIT_MAX_ATTEMPTS = 3;
+export async function loginViaDeviceFlow(deps) {
+    const fetchImpl = deps?.fetchImpl ?? ((input, init) => fetch(input, init));
+    const sleepImpl = deps?.sleepImpl ?? ((ms) => defaultSleep(ms));
+    const stdout = deps?.stdout ?? process.stdout;
+    const fetchTimeoutMs = deps?.fetchTimeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+    const initMaxAttempts = deps?.initMaxAttempts ?? DEFAULT_INIT_MAX_ATTEMPTS;
+    // Phase 1: init POST. Retried up to `initMaxAttempts` on transient HTTP
+    // statuses + transport errors. A single 502 used to abort the whole
+    // device-flow login — the user would have to start over from a new code.
+    const payload = await initDeviceFlow({ fetchImpl, sleepImpl, fetchTimeoutMs, initMaxAttempts });
     const verificationUrl = payload.verification_uri_complete ?? payload.verification_uri;
-    process.stdout.write(`Open ${verificationUrl} and enter code ${payload.user_code}\n`);
+    stdout.write(`Open ${verificationUrl} and enter code ${payload.user_code}\n`);
+    // Phase 2: poll loop. The device-flow `expires_in` is the natural deadline.
+    // Inside the loop, transient HTTP / transport failures `continue` instead
+    // of throwing — the loop's own `await sleep(intervalMs)` IS the backoff,
+    // and the `deadline` IS the budget. Previously, a single 503 from
+    // `github.com/login/oauth/access_token` aborted the whole login.
     const deadline = Date.now() + payload.expires_in * 1000;
     let intervalMs = Math.max(1, payload.interval) * 1000;
     while (Date.now() < deadline) {
-        await sleep(intervalMs);
-        const poll = await fetch(ACCESS_TOKEN_URL, {
-            method: "POST",
-            headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
-            body: new URLSearchParams({
-                client_id: GITHUB_CLIENT_ID,
-                device_code: payload.device_code,
-                grant_type: "urn:ietf:params:oauth:grant-type:device_code"
-            })
-        });
+        await sleepImpl(intervalMs);
+        let poll;
+        try {
+            poll = await fetchImpl(ACCESS_TOKEN_URL, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+                body: new URLSearchParams({
+                    client_id: GITHUB_CLIENT_ID,
+                    device_code: payload.device_code,
+                    grant_type: "urn:ietf:params:oauth:grant-type:device_code"
+                }),
+                signal: AbortSignal.timeout(fetchTimeoutMs)
+            });
+        }
+        catch (error) {
+            if (isRetryableTransportError(error)) {
+                // Transient — the next loop iteration will retry naturally. Don't
+                // abort the user's login over an ECONNRESET / DNS soft-fail.
+                continue;
+            }
+            throw error;
+        }
         if (!poll.ok) {
+            // Transient HTTP errors (5xx, 429) keep polling — same justification
+            // as transport errors. Permanent errors (4xx other than 429) abort,
+            // because the device code itself is bad and no amount of polling
+            // will fix it.
+            if (isRetryableStatus(poll.status)) {
+                await discardResponseBody(poll);
+                continue;
+            }
             throw new Error(`Access token poll failed (${poll.status}).`);
         }
         const tokenPayload = parseAccessTokenResponse((await poll.json()));
@@ -51,8 +86,60 @@ export async function loginViaDeviceFlow() {
     }
     throw new Error("Device authorization timed out.");
 }
-function sleep(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * Init POST with bounded retries. Retries on retryable HTTP statuses (5xx,
+ * 429, 408, 409, 425) and on transient transport errors (ECONNRESET, DNS
+ * soft-fails, undici timeouts). Fast-fails on 4xx-other so a misconfigured
+ * client_id or missing scope shows up immediately instead of after three
+ * pointless retries.
+ *
+ * Throws the last error if the budget is exhausted. The wrapping
+ * `loginViaDeviceFlow` does not retry the init separately — this is the
+ * only init retry layer.
+ */
+async function initDeviceFlow(opts) {
+    let lastError;
+    for (let attempt = 1; attempt <= opts.initMaxAttempts; attempt += 1) {
+        let response;
+        try {
+            response = await opts.fetchImpl(DEVICE_CODE_URL, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded", Accept: "application/json" },
+                body: new URLSearchParams({ client_id: GITHUB_CLIENT_ID, scope: "read:user" }),
+                signal: AbortSignal.timeout(opts.fetchTimeoutMs)
+            });
+        }
+        catch (error) {
+            lastError = error;
+            if (isRetryableTransportError(error) && attempt < opts.initMaxAttempts) {
+                await opts.sleepImpl(retryDelayMs(attempt));
+                continue;
+            }
+            throw error;
+        }
+        if (response.ok) {
+            return parseDeviceCodeResponse((await response.json()));
+        }
+        lastError = new Error(`Device flow init failed (${response.status}).`);
+        if (isRetryableStatus(response.status) && attempt < opts.initMaxAttempts) {
+            await discardResponseBody(response);
+            await opts.sleepImpl(retryDelayMs(attempt));
+            continue;
+        }
+        throw lastError;
+    }
+    // Unreachable: every iteration either returns, throws, or continues
+    // (with continue gated on `attempt < initMaxAttempts`). Defend anyway.
+    throw lastError ?? new Error("Device flow init exhausted retries without error context.");
+}
+async function discardResponseBody(response) {
+    try {
+        await response.arrayBuffer();
+    }
+    catch {
+        // Best-effort body drain; ignore failures so we don't surface a
+        // response-cleanup error in place of the real one we already captured.
+    }
 }
 function parseDeviceCodeResponse(value) {
     if (!value || typeof value !== "object") {

package/dist/auth/githubIdentity.js

@@ -14,18 +14,22 @@ import { getGithubUserSummary, GithubUserFetchError } from "../server/debugInfo.
  * null so callers can gracefully fall back to existing offline output.
  */
 export async function inspectGithubIdentity(options = {}) {
-    let credential;
-    try {
-        credential = await loadStoredCredential();
-    }
-    catch {
-        return null;
-    }
-    if (!credential) {
-        return null;
+    let token = options.token;
+    if (typeof token !== "string") {
+        let credential;
+        try {
+            credential = await loadStoredCredential();
+        }
+        catch {
+            return null;
+        }
+        if (!credential) {
+            return null;
+        }
+        token = credential.token;
     }
     try {
-        const summary = await getGithubUserSummary(credential.token, {
+        const summary = await getGithubUserSummary(token, {
             timeoutMs: options.timeoutMs ?? 4_000
         });
         if (!summary.login) {

package/dist/cli/agentEnv.js

@@ -1,10 +1,15 @@
 import { computeAnthropicDefaults, readModelIdsFromCache } from "../models/anthropicDefaults.js";
+import { claudeConfigDir, piAgentDir } from "../config/home.js";
 export function buildClaudeEnvBundle(input) {
     const defaults = input.defaults ?? computeAnthropicDefaults(readModelIdsFromCache());
     const enableGateway = input.enableGatewayDiscovery !== false;
+    const prefix = input.pathPrefix ?? "";
     const env = {
-        ANTHROPIC_BASE_URL: `http://127.0.0.1:${input.port}/anthropic`,
-        ANTHROPIC_AUTH_TOKEN: input.callerSecret ?? "copillm-local"
+        ANTHROPIC_BASE_URL: `http://127.0.0.1:${input.port}${prefix}/anthropic`,
+        ANTHROPIC_AUTH_TOKEN: input.callerSecret ?? "copillm-local",
+        // Point Claude at a copillm-owned config home so copillm-launched Claude
+        // never reads/writes the user's real ~/.claude (and dev mode isolates it).
+        CLAUDE_CONFIG_DIR: claudeConfigDir()
     };
     const trailingNotes = [];
     if (defaults.opus) {
@@ -38,18 +43,19 @@ export function buildCodexEnvBundle(absHomeDir) {
     };
 }
 /**
- * Pi has no environment-variable override for its config directory; it reads
- * `~/.pi/agent/models.json` unconditionally. So this bundle is intentionally
- * empty — the real configuration work happens in `generatePiHome()` writing
- * that file. We expose the helper for symmetry with the other agents and to
- * carry a trailing note explaining what to look at when debugging.
+ * pi reads its config from `<PI_CODING_AGENT_DIR>/models.json`. copillm owns
+ * that directory (see `piAgentDir()` in src/config/home.ts) and exports
+ * `PI_CODING_AGENT_DIR` so the launched pi reads the catalog copillm just wrote
+ * there — never the user's real `~/.pi`. This is also what makes dev mode
+ * isolate pi for free (the dev COPILLM_HOME relocates the agent dir).
  */
 export function buildPiEnvBundle(absMirrorDir) {
+    const agentDir = piAgentDir();
     return {
-        env: {},
+        env: { PI_CODING_AGENT_DIR: agentDir },
         inlineComments: {},
         trailingNotes: [
-            `pi reads ~/.pi/agent/models.json directly (no env var override).`,
+            `pi reads ${agentDir}/models.json (copillm sets PI_CODING_AGENT_DIR).`,
             `copillm regenerated it on \`copillm start\` and mirrored it at ${absMirrorDir}/models.json.`
         ]
     };