castle-web-cli 0.4.105 → 0.4.107

package/dist/agent.js

@@ -25,7 +25,9 @@ import { buildRouterPrompt, buildTaskPrompt, userTurnInstruction, CLAUDE_TASK_SY
 import { checkOpenrouterKey, checkOpenrouterModel, openrouterCatalogEntry, primeOpenrouterCatalog, } from "./openrouter-catalog.js";
 import { classifyProviderError, failureCopy, setReaderTimeZone, } from "./agent-failures.js";
 import { fetchBudget, meteringHeaders, newAgentSessionId, reportCursorRun, withCustomHeaders, } from "./metering.js";
-import { anthropicKeyHelperCommand, claudeHasSavedLogin, resolveAnthropicAuth, userKey, ANTHROPIC_CREDENTIAL_ENV, ANTHROPIC_PROXY_ENV, CASTLE_USER_KEYS_PATH, } from "./byo-auth.js";
+import { anthropicKeyHelperCommand, claudeHasSavedLogin, cursorAuthPath, cursorHasUserLogin, resolveAnthropicAuth, userKey, ANTHROPIC_CREDENTIAL_ENV, ANTHROPIC_PROXY_ENV, CASTLE_USER_KEYS_PATH, } from "./byo-auth.js";
+import { accountsSnapshot, loginProviderFor, writeCredential, } from "./byo-accounts.js";
+import { cancelLogin, logout, startLogin, submitLoginCode, } from "./byo-login.js";
 import { runAgentNative } from "./native/loop.js";
 import { createPlaytestBrowserManager } from "./native/playtest-browser.js";
 import { createPlaywrightPlaytestExecutor } from "./native/playtest-executor.js";
@@ -833,32 +835,6 @@ const BACKEND_KEY_ENV = {
     claude: "ANTHROPIC_API_KEY",
     cursor: "CURSOR_API_KEY",
 };
-// cursor-agent rewrites ~/.config/cursor/auth.json on every successful run,
-// including Castle's own CURSOR_API_KEY runs -- so the file existing does NOT
-// mean a user logged in. Distinguish by the apiKey field: a real login is OAuth,
-// which drops apiKey and leaves only session tokens; any auth.json that still
-// carries an apiKey is an env-key cache cursor wrote from an injected key --
-// OURS, including a PREVIOUS key after a rotation. Treating that cache as a login
-// suppresses the injected key and drops cursor into the stale (dead) session.
-//
-// An earlier apiKey === castleKeys().CURSOR_API_KEY comparison misfired on a key
-// switch: the stale cache holds the OLD key, reads as "!= current" => "user
-// login" => key withheld => auth fails until auth.json is deleted by hand.
-// Deferring only on OAuth is rotation-proof. The cost: a tester's own-API-key
-// login is no longer distinguishable from our stale cache, so it is not deferred
-// to -- OAuth login still is (the common bypass path).
-function cursorAuthPath(home) {
-    return path.join(home, ".config", "cursor", "auth.json");
-}
-function cursorHasUserLogin(home) {
-    try {
-        const auth = JSON.parse(fs.readFileSync(cursorAuthPath(home), "utf8"));
-        return !auth.apiKey && !!auth.accessToken;
-    }
-    catch {
-        return false;
-    }
-}
 // When we inject Castle's key, any auth.json cursor cached from a DIFFERENT key
 // -- a rotated-out old key, or a tester's own key we've chosen to override -- is
 // dead weight: cursor re-auths from the injected env key and ignores it. Leaving
@@ -1626,20 +1602,32 @@ function notifyAgentRunFinished() {
 // True when THIS run spends Castle's credential rather than the user's own.
 // Resolves exactly as buildAgentInvocation / runAgentSmith will, one step
 // earlier, so the gate and the run can never disagree about who is paying.
-// Cursor counts: it runs on Castle's key by default, and gating it here is the
-// only gate there is -- its traffic never reaches the proxy.
+//
+// Cursor asks the same question as the others, just from a different file:
+// envForAgentSpawn withholds Castle's key when the user has an OAuth login, so
+// a run with one is already going to their account and the daily limit is not
+// Castle's to enforce over it. It used to answer `true` unconditionally, which
+// refused a user on their own subscription once Castle's budget ran out --
+// while the editor offered them that sign-in and promised it bypassed the
+// limit. Deferring only to a LOGIN is what keeps this from being a hole: a
+// cursor run on Castle's key stays gated, and cursor is unmetered (its traffic
+// never reaches the proxy), so an ungated one would be a free ride.
 function runIsCastlePaid(backend, claudeModel, orAuth) {
     if (backend === "cursor")
-        return true;
+        return !cursorHasUserLogin(os.homedir());
     return roleUsesOpenrouter(backend, claudeModel)
         ? (orAuth ?? resolveOpenrouterAuth()).mode === "proxy"
         : resolveAnthropicAuth().mode === "proxy";
 }
 // Whether Castle's budget is this editor's to spend at all, which is what makes
 // the usage bar worth drawing. Both roles count, and they can disagree: an
-// Anthropic login covers the claude roles while a cursor role still spends
-// Castle's key. Re-read per refresh, so adding or removing a credential (or
-// switching a role's backend) moves the bar on the next one.
+// Anthropic login covers the claude roles while a cursor role on Castle's key
+// still spends Castle's. Re-read per refresh, so adding or removing a
+// credential (or switching a role's backend) moves the bar on the next one.
+//
+// A cursor role on Castle's key does draw a bar its own runs never move --
+// cursor is unmetered by contract. That is a display question, not a payment
+// one, and it is not settled here.
 function anyRoleIsCastlePaid(settings) {
     return (runIsCastlePaid(settings.router, settings.routerClaudeModel, null) ||
         runIsCastlePaid(settings.tasks, settings.tasksClaudeModel, null));
@@ -3034,6 +3022,28 @@ function applyAgentSettings(incoming, ctx) {
     ctx.broadcast({ type: "settings", settings });
     void broadcastSettingsWarnings(ctx);
 }
+// Store or remove one BYO credential for the editor's Accounts rows. Unlike a
+// settings change this persists nothing itself -- byo-accounts owns the file --
+// and it always answers with a fresh snapshot, including on a rejected write,
+// so a client that sent something invalid learns why instead of watching its
+// input silently do nothing. The snapshot carries presence and a hint only; no
+// frame from here ever moves a key value toward a browser.
+function broadcastAccounts(broadcast, error) {
+    broadcast({
+        type: "accounts",
+        accounts: accountsSnapshot(),
+        ...(error ? { accountsError: error } : {}),
+    });
+}
+function applyCredentialChange(msg, ctx) {
+    const clearing = msg.type === "clear-credential";
+    if (!clearing && typeof msg.value !== "string")
+        return;
+    const result = writeCredential(msg.id, clearing ? null : msg.value);
+    broadcastAccounts(ctx.broadcast, result.ok
+        ? undefined
+        : { id: typeof msg.id === "string" ? msg.id : "", message: result.message });
+}
 // Which slugs are worth a verdict: only roles actually routed at OpenRouter
 // (otherwise we'd warn about an inert leftover value), and only when a slug is
 // set at all.
@@ -3585,6 +3595,7 @@ export function createAgentServer(opts) {
             running: routerQueue.isRunning(),
             queued: routerQueue.queuedSnippets(),
             usage: usageFeed.latest(),
+            accounts: accountsSnapshot(),
         };
         socket.send(JSON.stringify(hello));
         // A newly attached client is the one moment the cached value may be stale
@@ -3625,6 +3636,26 @@ export function createAgentServer(opts) {
             else if (msg.type === "set-settings") {
                 applySettings(msg);
             }
+            else if (msg.type === "set-credential" ||
+                msg.type === "clear-credential") {
+                applyCredentialChange(msg, { broadcast });
+            }
+            else if (msg.type === "account-login") {
+                const provider = loginProviderFor(msg.id);
+                if (provider)
+                    startLogin(provider, () => broadcastAccounts(broadcast));
+            }
+            else if (msg.type === "account-login-code" && typeof msg.value === "string") {
+                submitLoginCode(msg.value);
+            }
+            else if (msg.type === "account-login-cancel") {
+                cancelLogin();
+            }
+            else if (msg.type === "account-logout") {
+                const provider = loginProviderFor(msg.id);
+                if (provider)
+                    logout(provider, () => broadcastAccounts(broadcast));
+            }
             else if (msg.type === "client-timezone" && typeof msg.timeZone === "string") {
                 setReaderTimeZone(msg.timeZone);
             }

package/dist/byo-accounts.d.ts

@@ -0,0 +1,38 @@
+import { type LoginProvider, type LoginState } from "./byo-login.js";
+export type ProviderId = "anthropic" | "openrouter" | "cursor";
+export interface ProviderStatus {
+    id: ProviderId;
+    label: string;
+    key?: {
+        placeholder: string;
+        present: boolean;
+        hint?: string;
+    };
+    login?: {
+        provider: LoginProvider;
+        loggedIn: boolean;
+    };
+}
+export interface AccountsState {
+    providers: ProviderStatus[];
+    login: LoginState | null;
+}
+export declare function accountsSnapshot(): AccountsState;
+export type CredentialWriteResult = {
+    ok: true;
+    changed: boolean;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Store one provider's key, or remove it when `value` is null.
+ *
+ * Merges into whatever is already in the file: a hand-added entry this module
+ * has no descriptor for MUST survive, since hand-editing stays a supported way
+ * in. Removing deletes the entry rather than blanking it -- the resolver reads
+ * an empty string as absent either way, but a leftover `"KEY": ""` reads as a
+ * configured key to anyone inspecting the file.
+ */
+export declare function writeCredential(id: unknown, value: string | null): CredentialWriteResult;
+export declare function loginProviderFor(id: unknown): LoginProvider | null;

package/dist/byo-accounts.js

@@ -0,0 +1,186 @@
+// The editor's read/write surface for the user's OWN provider credentials: what
+// the settings popover's Accounts modal shows, and the only thing in this
+// process that writes user-keys.json.
+//
+// Split from byo-auth.ts deliberately. That module is the RESOLVER -- pure,
+// read-only, and imported by the terminal shim's helper on EVERY `claude` run
+// (see installClaudeShim), so it must stay free of anything stateful. This one
+// is allowed to write. The login subprocesses live in byo-login.ts; this module
+// only reports their state as part of one snapshot.
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { CASTLE_USER_KEYS_PATH, claudeHasSavedLogin, cursorHasUserLogin, readUserKeys, } from "./byo-auth.js";
+import { activeLogin } from "./byo-login.js";
+import { inCastleSandbox } from "./metering.js";
+// Providers, not credentials: Anthropic is reachable by EITHER a key or a
+// claude.ai login, and resolveAnthropicAuth already treats them as one
+// question (key wins). Grouping them here is what lets the modal show a user
+// the two ways into one account side by side.
+const PROVIDERS = [
+    {
+        id: "anthropic",
+        label: "Anthropic",
+        key: { env: "ANTHROPIC_API_KEY", placeholder: "sk-ant-…", offered: true },
+        login: "claude",
+    },
+    {
+        id: "openrouter",
+        label: "OpenRouter",
+        key: { env: "OPENROUTER_API_KEY", placeholder: "sk-or-…", offered: true },
+    },
+    {
+        id: "cursor",
+        label: "Cursor",
+        key: { env: "CURSOR_API_KEY", placeholder: "key_…", offered: false },
+        login: "cursor",
+    },
+];
+// A stored value is never sent toward a browser -- only this. Short values get
+// no tail at all rather than a tail that is most of the secret.
+function hintFor(value) {
+    return value.length >= 12 ? `…${value.slice(-4)}` : "…";
+}
+function hasLogin(provider) {
+    return provider === "claude"
+        ? claudeHasSavedLogin()
+        : cursorHasUserLogin(os.homedir());
+}
+// Offered at all: a key field the user may fill, or a login they may start.
+function isOffered(d) {
+    return Boolean(d.key?.offered) || Boolean(d.login);
+}
+function descriptorFor(id) {
+    if (typeof id !== "string")
+        return null;
+    return PROVIDERS.find((d) => isOffered(d) && d.id === id) ?? null;
+}
+export function accountsSnapshot() {
+    // Empty outside a sandbox, which hides the whole surface. A local serve has no
+    // Castle budget to escape, and the host machine's own claude/cursor logins are
+    // ALREADY what its CLIs use -- offering to "sign in" there would report the
+    // developer's existing login back to them as a Castle setting, and invite them
+    // to sign out of it from a deck editor.
+    if (!inCastleSandbox())
+        return { providers: [], login: null };
+    const stored = readUserKeys();
+    return {
+        providers: PROVIDERS.filter(isOffered).map((d) => {
+            // typeof, not just truthiness: the file is hand-editable, and a
+            // non-string value would throw on trim -- see readUserKeys.
+            const raw = d.key?.offered ? stored[d.key.env] : undefined;
+            const value = typeof raw === "string" ? raw.trim() : undefined;
+            return {
+                id: d.id,
+                label: d.label,
+                ...(d.key?.offered
+                    ? {
+                        key: {
+                            placeholder: d.key.placeholder,
+                            present: Boolean(value),
+                            ...(value ? { hint: hintFor(value) } : {}),
+                        },
+                    }
+                    : {}),
+                ...(d.login
+                    ? { login: { provider: d.login, loggedIn: hasLogin(d.login) } }
+                    : {}),
+            };
+        }),
+        login: activeLogin(),
+    };
+}
+// Generous -- provider key formats are not ours to predict -- but bounded, so a
+// stray paste of a whole file can't land in the credential store.
+const MAX_KEY_LENGTH = 500;
+// A credential reaches a child process as an environment value and, for the
+// terminal, as a shell-quoted assignment. A control character in it is never a
+// real key and is exactly the shape that turns one env var into two, so it is
+// REFUSED rather than stripped: silently storing something other than what the
+// user pasted would fail later, somewhere less obvious.
+function hasControlCharacter(value) {
+    for (const ch of value) {
+        const code = ch.codePointAt(0) ?? 0;
+        if (code < 0x20 || code === 0x7f)
+            return true;
+    }
+    return false;
+}
+function writeUserKeys(next) {
+    fs.mkdirSync(path.dirname(CASTLE_USER_KEYS_PATH), { recursive: true });
+    // Staged + renamed, not written in place: the sandbox checkpoints this
+    // directory on a timer, so an in-place write can be snapshotted half-done.
+    // The staged file carries the mode, and rename preserves it, so the result is
+    // 0600 even when an older file was not.
+    const staged = `${CASTLE_USER_KEYS_PATH}.staged`;
+    fs.writeFileSync(staged, JSON.stringify(next, null, 2) + "\n", {
+        mode: 0o600,
+    });
+    fs.renameSync(staged, CASTLE_USER_KEYS_PATH);
+}
+// A full disk or a permissions change comes back as a refusal the client is
+// told about, not as an exception: this runs inside the WS message handler,
+// where nothing catches a throw and it would take the whole serve down.
+function persist(next) {
+    try {
+        writeUserKeys(next);
+        return { ok: true, changed: true };
+    }
+    catch {
+        return { ok: false, message: "could not write user-keys.json" };
+    }
+}
+/**
+ * Store one provider's key, or remove it when `value` is null.
+ *
+ * Merges into whatever is already in the file: a hand-added entry this module
+ * has no descriptor for MUST survive, since hand-editing stays a supported way
+ * in. Removing deletes the entry rather than blanking it -- the resolver reads
+ * an empty string as absent either way, but a leftover `"KEY": ""` reads as a
+ * configured key to anyone inspecting the file.
+ */
+export function writeCredential(id, value) {
+    // accountsSnapshot being empty outside a sandbox HIDES this surface; hiding
+    // is not refusing. The agent socket is reachable over LAN/tailnet hostnames
+    // and a cross-origin page can open a WebSocket to it, so without this check
+    // any client could still write the host's ~/.castle/user-keys.json from a
+    // plain local serve.
+    if (!inCastleSandbox()) {
+        return { ok: false, message: "only available in a Castle sandbox" };
+    }
+    const descriptor = descriptorFor(id);
+    if (!descriptor?.key?.offered)
+        return { ok: false, message: "unknown credential" };
+    const env = descriptor.key.env;
+    const stored = readUserKeys();
+    if (value === null) {
+        if (!(env in stored))
+            return { ok: true, changed: false };
+        delete stored[env];
+        return persist(stored);
+    }
+    const trimmed = value.trim();
+    if (!trimmed)
+        return { ok: false, message: "key is empty" };
+    if (trimmed.length > MAX_KEY_LENGTH) {
+        return { ok: false, message: "key is too long" };
+    }
+    if (hasControlCharacter(trimmed)) {
+        return { ok: false, message: "key contains invalid characters" };
+    }
+    if (stored[env] === trimmed)
+        return { ok: true, changed: false };
+    stored[env] = trimmed;
+    return persist(stored);
+}
+// The login provider a client-supplied id names, or null. Keeps the WS handler
+// from having to know the descriptor table. Null outside a sandbox for the
+// same reason writeCredential refuses there -- most of all so no client can
+// run `claude auth logout` / `cursor-agent logout` against the host machine's
+// own login, which is exactly the outcome hiding the surface was meant to
+// prevent.
+export function loginProviderFor(id) {
+    if (!inCastleSandbox())
+        return null;
+    return descriptorFor(id)?.login ?? null;
+}

package/dist/byo-auth.d.ts

@@ -1,5 +1,7 @@
 export declare const CASTLE_USER_KEYS_PATH: string;
-export declare function userKey(envName: "ANTHROPIC_API_KEY" | "OPENROUTER_API_KEY"): string | null;
+export type UserKeyName = "ANTHROPIC_API_KEY" | "OPENROUTER_API_KEY" | "CURSOR_API_KEY";
+export declare function readUserKeys(): Record<string, string>;
+export declare function userKey(envName: UserKeyName): string | null;
 export type AnthropicAuth = {
     mode: "user-key";
     key: string;
@@ -16,8 +18,12 @@ export type OpenrouterAuth = {
     key: string;
 };
 export declare function claudeHasSavedLogin(): boolean;
+export declare function cursorAuthPath(home: string): string;
+export declare function cursorHasUserLogin(home: string): boolean;
 export declare function resolveAnthropicAuth(): AnthropicAuth;
 export declare const ANTHROPIC_CREDENTIAL_ENV: readonly ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN_HELPER", "CLAUDE_CODE_OAUTH_TOKEN"];
 export declare const ANTHROPIC_PROXY_ENV: readonly ["ANTHROPIC_BASE_URL", "ANTHROPIC_AUTH_TOKEN", "ANTHROPIC_CUSTOM_HEADERS", "ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN_HELPER", "CLAUDE_CODE_OAUTH_TOKEN"];
 export declare function anthropicKeyHelperCommand(): string;
 export declare function envForUserShell(base: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export declare function claudeShellEnvScript(env: NodeJS.ProcessEnv, shimDir: string): string;
+export declare function installClaudeShim(deckDir: string): string | null;

package/dist/byo-auth.js

@@ -4,6 +4,12 @@
 // terminal has to answer the same question for the `claude` a user runs by
 // hand -- and must answer it the SAME way, or the terminal quietly spends
 // Castle's budget while the agent panel spends the user's.
+//
+// The claude-CLI behaviors this file leans on (AUTH_TOKEN outranks a login,
+// apiKeyHelper works headless, an env key alone does not) are measured, not
+// documented, and the agent-qa battery fakes `claude` so it cannot notice them
+// drifting -- scripts/tests/real-claude-smoke.mjs re-verifies them against a
+// real binary; run it when the sandbox image's claude version bumps.
 import * as fs from "fs";
 import * as os from "os";
 import * as path from "path";
@@ -11,26 +17,43 @@ import { fileURLToPath } from "url";
 const DIST_DIR = path.dirname(fileURLToPath(import.meta.url));
 // A user's OWN provider credentials, kept SEPARATE from Castle's keys.json so
 // castle-www's per-serve re-sync of keys.json (cloudSandbox.ts syncCastleKeys)
-// can't clobber them. Same shape as keys.json (env-var-name keys); the user (or
-// a future editor UI) writes this file, nothing in-process does. When a key is
+// can't clobber them. Same shape as keys.json (env-var-name keys). When a key is
 // present the run goes DIRECT to that provider on the user's own credential and
 // is NOT metered -- deleting the key reverts to Castle's proxy on the next run.
 // The path override mirrors CASTLE_KEYS_PATH so the QA battery stays isolated
 // from a developer's real ~/.castle. No env fallback on read: the file is the
 // only source, so a delete fully reverts.
+//
+// Written by hand, or by the editor's Accounts rows -- byo-accounts.ts is the
+// only writer in this process, and it merges rather than replaces so a key it
+// has no descriptor for still survives an edit.
 export const CASTLE_USER_KEYS_PATH = process.env.CASTLE_USER_KEYS_PATH ??
     path.join(os.homedir(), ".castle", "user-keys.json");
-function userKeys() {
+// Exported for byo-accounts.ts, whose writes must preserve entries this file
+// has no name for; every other reader wants userKey() instead.
+//
+// The file is hand-editable, so its shape is user input: a top-level primitive
+// would make every `stored[k]` assignment downstream a strict-mode TypeError
+// inside the serve's WS handler, where nothing catches it. VALUES are not
+// validated -- a non-string entry survives a merge untouched -- so anything
+// that uses one must typeof-check it first.
+export function readUserKeys() {
     try {
-        return JSON.parse(fs.readFileSync(CASTLE_USER_KEYS_PATH, "utf8"));
+        const parsed = JSON.parse(fs.readFileSync(CASTLE_USER_KEYS_PATH, "utf8"));
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+            ? parsed
+            : {};
     }
     catch {
         return {};
     }
 }
 export function userKey(envName) {
-    const v = userKeys()[envName]?.trim();
-    return v ? v : null;
+    const v = readUserKeys()[envName];
+    if (typeof v !== "string")
+        return null;
+    const trimmed = v.trim();
+    return trimmed ? trimmed : null;
 }
 // KNOWN GAP (macOS): a false negative for most logged-in users. `claude /login`
 // stores credentials in the KEYCHAIN there, not in ~/.claude/.credentials.json,
@@ -50,6 +73,32 @@ export function claudeHasSavedLogin() {
         path.join(os.homedir(), ".claude", ".credentials.json");
     return fs.existsSync(credPath);
 }
+// cursor-agent rewrites ~/.config/cursor/auth.json on every successful run,
+// including Castle's own CURSOR_API_KEY runs -- so the file existing does NOT
+// mean a user logged in. Distinguish by the apiKey field: a real login is OAuth,
+// which drops apiKey and leaves only session tokens; any auth.json that still
+// carries an apiKey is an env-key cache cursor wrote from an injected key --
+// OURS, including a PREVIOUS key after a rotation. Treating that cache as a login
+// suppresses the injected key and drops cursor into the stale (dead) session.
+//
+// An earlier apiKey === castleKeys().CURSOR_API_KEY comparison misfired on a key
+// switch: the stale cache holds the OLD key, reads as "!= current" => "user
+// login" => key withheld => auth fails until auth.json is deleted by hand.
+// Deferring only on OAuth is rotation-proof. The cost: a tester's own-API-key
+// login is no longer distinguishable from our stale cache, so it is not deferred
+// to -- OAuth login still is (the common bypass path).
+export function cursorAuthPath(home) {
+    return path.join(home, ".config", "cursor", "auth.json");
+}
+export function cursorHasUserLogin(home) {
+    try {
+        const auth = JSON.parse(fs.readFileSync(cursorAuthPath(home), "utf8"));
+        return !auth.apiKey && !!auth.accessToken;
+    }
+    catch {
+        return false;
+    }
+}
 export function resolveAnthropicAuth() {
     const k = userKey("ANTHROPIC_API_KEY");
     if (k)
@@ -100,13 +149,25 @@ function shellQuote(value) {
 export function anthropicKeyHelperCommand() {
     return `${shellQuote(process.execPath)} ${shellQuote(path.join(DIST_DIR, "anthropic-key-helper.js"))}`;
 }
+// Where the shell's inherited proxy pair goes when a credential of the user's
+// own displaces it. envForUserShell answers "whose credential" once, but
+// claudeShellEnvScript re-answers it per `claude` run and may need to put
+// Castle's routing BACK (the user deleted their key mid-session) -- which it
+// can only do if the values survived somewhere. Nothing reads these names by
+// accident, so stashing doesn't weaken the guarantee below.
+const PROXY_STASH_PREFIX = "CASTLE_PTY_";
 // Env for the editor's PTY terminal. The container env the serve inherits
 // carries the llm-proxy pair, and Claude Code ranks ANTHROPIC_AUTH_TOKEN ABOVE
 // a claude.ai login -- so without this a user who ran `claude /login` in the
 // terminal still gets "claude.ai connectors are disabled because
 // ANTHROPIC_API_KEY or another auth source is set", their login unused and
-// their session billed to Castle. Resolved at shell start, so a login taken in
-// an open terminal applies to the next one.
+// their session billed to Castle.
+//
+// This is the shell's STARTING state only; the per-run answer is the shim's
+// (see installClaudeShim). It still matters on its own, because anything else
+// the user runs in that terminal -- a script that calls claude by absolute
+// path, an SDK program reading ANTHROPIC_API_KEY -- must not find Castle's
+// token sitting in the environment while the user has a credential of their own.
 //
 // A user KEY goes in as ANTHROPIC_API_KEY here, unlike the agent path's
 // apiKeyHelper (see above): an interactive claude CAN show the one-time
@@ -116,8 +177,12 @@ export function envForUserShell(base) {
     const env = { ...base };
     const anthropic = resolveAnthropicAuth();
     if (anthropic.mode !== "proxy") {
-        for (const name of ANTHROPIC_PROXY_ENV)
+        for (const name of ANTHROPIC_PROXY_ENV) {
+            const inherited = env[name];
+            if (inherited !== undefined)
+                env[PROXY_STASH_PREFIX + name] = inherited;
             delete env[name];
+        }
         if (anthropic.mode === "user-key")
             env.ANTHROPIC_API_KEY = anthropic.key;
     }
@@ -128,3 +193,127 @@ export function envForUserShell(base) {
     }
     return env;
 }
+// --- the terminal's per-run credential decision ------------------------------
+//
+// A process's environment is fixed at spawn, and the editor keeps ONE shell per
+// serve -- closing the terminal panel drops the socket, not the shell (see
+// ide.ts ensureSession), so envForUserShell's answer is the answer that shell
+// keeps for as long as the serve lives. That made `claude /login` in the
+// terminal a no-op for the terminal itself: the login lands, the agent panel
+// (which resolves per run) starts using it, and every later `claude` in that
+// same shell still finds the inherited ANTHROPIC_AUTH_TOKEN outranking it and
+// still prints "claude.ai connectors are disabled...". Restarting claude, or
+// the panel, changed nothing -- only restarting the serve did.
+//
+// So the decision moves to a `claude` shim first on the terminal's PATH: it
+// resolves the credential at invocation time, fixes up the environment, and
+// execs the real binary. A login taken thirty seconds ago applies to the very
+// next run, in the same shell.
+//
+// Caveat: PATH ordering is not ours to guarantee. A login shell can reorder it
+// (macOS /etc/zprofile runs path_helper, which demotes an inherited entry below
+// /usr/local/bin) or replace it outright (Debian's /etc/profile does, for root
+// -- though only bash reads it; the sandbox's `zsh -l` keeps our entry first).
+// When the shim loses, the credential is simply the one envForUserShell picked
+// at shell start -- the old behavior, not a broken one.
+function realpath(p) {
+    try {
+        return fs.realpathSync(p);
+    }
+    catch {
+        return path.resolve(p);
+    }
+}
+// The `claude` the shim should exec: the first executable one on `pathValue`
+// that isn't the shim itself. Skipping by resolved directory (not by string) is
+// what keeps the shim from exec'ing itself forever.
+function findRealClaude(pathValue, shimDir) {
+    const shimReal = realpath(shimDir);
+    for (const entry of (pathValue ?? "").split(path.delimiter)) {
+        if (!entry || realpath(entry) === shimReal)
+            continue;
+        const candidate = path.join(entry, "claude");
+        try {
+            fs.accessSync(candidate, fs.constants.X_OK);
+            if (fs.statSync(candidate).isFile())
+                return candidate;
+        }
+        catch {
+            /* not this entry */
+        }
+    }
+    return null;
+}
+// Shell statements the shim evals before exec'ing claude: the environment that
+// makes THIS run use the credential resolveAnthropicAuth picks right now.
+// Emitting `unset` rather than an empty value matters -- Claude Code treats an
+// empty ANTHROPIC_BASE_URL as configured and fails to reach anything.
+export function claudeShellEnvScript(env, shimDir) {
+    const lines = [];
+    const auth = resolveAnthropicAuth();
+    if (auth.mode === "proxy") {
+        for (const name of ANTHROPIC_PROXY_ENV) {
+            const stashed = env[PROXY_STASH_PREFIX + name];
+            if (stashed !== undefined && env[name] === undefined) {
+                lines.push(`${name}=${shellQuote(stashed)}; export ${name}`);
+            }
+        }
+    }
+    else {
+        for (const name of ANTHROPIC_PROXY_ENV)
+            lines.push(`unset ${name}`);
+        if (auth.mode === "user-key") {
+            lines.push(`ANTHROPIC_API_KEY=${shellQuote(auth.key)}; export ANTHROPIC_API_KEY`);
+        }
+    }
+    const real = findRealClaude(env.PATH, shimDir);
+    if (real)
+        lines.push(`CASTLE_REAL_CLAUDE=${shellQuote(real)}`);
+    return lines.length > 0 ? lines.join("\n") + "\n" : "";
+}
+// The baked CASTLE_REAL_CLAUDE is a fallback, not the answer: if the helper
+// runs, its own resolution (against the SHELL's PATH, which a login shell may
+// have rewritten) replaces it. It only survives when the helper failed to run
+// at all, and then it is the difference between the old static behavior and a
+// terminal where `claude` is suddenly missing.
+function shimScript(shimDir) {
+    const helper = [
+        shellQuote(process.execPath),
+        shellQuote(path.join(DIST_DIR, "claude-shim-env.js")),
+        shellQuote(shimDir),
+    ].join(" ");
+    return [
+        "#!/bin/sh",
+        "# Generated by `castle-web serve` -- see installClaudeShim in castle-web-cli.",
+        `CASTLE_REAL_CLAUDE=${shellQuote(findRealClaude(process.env.PATH, shimDir) ?? "")}`,
+        `eval "$(${helper})"`,
+        'if [ -z "$CASTLE_REAL_CLAUDE" ]; then',
+        '  echo "castle-web: claude is not installed on this PATH" >&2',
+        "  exit 127",
+        "fi",
+        'exec "$CASTLE_REAL_CLAUDE" "$@"',
+        "",
+    ].join("\n");
+}
+// Returns the directory to put first on the terminal's PATH, or null when there
+// is no shim to install -- a failure here costs the per-run re-resolution, so it
+// degrades to envForUserShell's spawn-time answer rather than breaking the shell.
+export function installClaudeShim(deckDir) {
+    if (process.platform === "win32")
+        return null;
+    const dir = path.join(deckDir, ".castle", "shims");
+    try {
+        fs.mkdirSync(dir, { recursive: true });
+        // Write-then-rename, because /bin/sh reads a script incrementally: a second
+        // serve reinstalling over this deck while a claude is running through the
+        // shim would otherwise pull the file out from under that sh mid-read.
+        const staged = path.join(dir, "claude.staged");
+        fs.writeFileSync(staged, shimScript(dir));
+        fs.chmodSync(staged, 0o755);
+        fs.renameSync(staged, path.join(dir, "claude"));
+        return dir;
+    }
+    catch {
+        return null;
+    }
+}