castle-web-cli 0.4.106 → 0.4.108

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, watchCredentials, 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,76 @@ function applyAgentSettings(incoming, ctx) {
     ctx.broadcast({ type: "settings", settings });
     void broadcastSettingsWarnings(ctx);
 }
+// Belt to watchCredentials' braces: a directory that didn't exist at boot has
+// no watcher on it, and an inotify watch can be lost. Slow, because the watch is
+// what makes this feel live -- this only has to stop a miss from lasting.
+const ACCOUNTS_POLL_MS = 15_000;
+// The editor's view of which credentials exist, kept live. Unlike settings --
+// which nothing outside this process writes -- a credential changes behind the
+// editor's back all the time: `claude /login` or `cursor-agent logout` in the
+// terminal panel, a hand-edited user-keys.json, an agent run that refreshes an
+// OAuth token. Push those, or the popover reports whatever was true when the
+// page loaded and a terminal sign-in reads as having done nothing.
+//
+// The snapshot carries presence and a hint only; no frame from here ever moves
+// a key value toward a browser.
+function createAccountsFeed(opts) {
+    let last = "";
+    // Tracked apart from the whole snapshot so a sign-in's phase transitions
+    // (starting -> awaiting-code -> ...) don't each cost a budget fetch: they
+    // move `login`, never a credential.
+    let lastProviders = "";
+    function push(error) {
+        const accounts = accountsSnapshot();
+        const serialized = JSON.stringify(accounts);
+        const providers = JSON.stringify(accounts.providers);
+        if (providers !== lastProviders) {
+            lastProviders = providers;
+            opts.onCredentialChange();
+        }
+        // A refusal always goes out. It is the only answer a rejected write gets,
+        // and a rejected write leaves the snapshot identical by definition -- so
+        // deduping on the snapshot alone would swallow exactly the frame that
+        // carries the reason.
+        if (serialized === last && !error)
+            return;
+        last = serialized;
+        opts.broadcast({
+            type: "accounts",
+            accounts,
+            ...(error ? { accountsError: error } : {}),
+        });
+    }
+    function snapshot() {
+        const accounts = accountsSnapshot();
+        last = JSON.stringify(accounts);
+        lastProviders = JSON.stringify(accounts.providers);
+        return accounts;
+    }
+    const stopWatch = watchCredentials(() => push());
+    const timer = setInterval(() => {
+        if (opts.hasClients())
+            push();
+    }, ACCOUNTS_POLL_MS);
+    timer.unref?.();
+    return {
+        snapshot,
+        push,
+        stop: () => {
+            stopWatch();
+            clearInterval(timer);
+        },
+    };
+}
+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);
+    ctx.pushAccounts(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.
@@ -3508,6 +3566,11 @@ export function createAgentServer(opts) {
         hasClients: () => clients.size > 0,
         castlePaid: () => anyRoleIsCastlePaid(settings),
     });
+    const accountsFeed = createAccountsFeed({
+        broadcast,
+        hasClients: () => clients.size > 0,
+        onCredentialChange: () => usageFeed.refresh(),
+    });
     const applySettings = (incoming) => {
         applyAgentSettings(incoming, { settings, settingsPath, broadcast });
         // A backend switch can change who pays (a cursor role always spends
@@ -3585,6 +3648,7 @@ export function createAgentServer(opts) {
             running: routerQueue.isRunning(),
             queued: routerQueue.queuedSnippets(),
             usage: usageFeed.latest(),
+            accounts: accountsFeed.snapshot(),
         };
         socket.send(JSON.stringify(hello));
         // A newly attached client is the one moment the cached value may be stale
@@ -3625,6 +3689,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, { pushAccounts: accountsFeed.push });
+            }
+            else if (msg.type === "account-login") {
+                const provider = loginProviderFor(msg.id);
+                if (provider)
+                    startLogin(provider, () => accountsFeed.push());
+            }
+            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, () => accountsFeed.push());
+            }
             else if (msg.type === "client-timezone" && typeof msg.timeZone === "string") {
                 setReaderTimeZone(msg.timeZone);
             }
@@ -3659,6 +3743,7 @@ export function createAgentServer(opts) {
         }
         stopChildRegistry();
         usageFeed.stop();
+        accountsFeed.stop();
         wss.close();
         void playtestBrowserManager.shutdown();
     }

package/dist/byo-accounts.d.ts

@@ -0,0 +1,55 @@
+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;
+/**
+ * Call `onChange` when a credential this module reports on changes on disk.
+ *
+ * The editor is not the only writer: `claude /login` and `cursor-agent login`
+ * in the terminal panel, an agent run that refreshes an OAuth token, and a
+ * hand-edited `user-keys.json` all change the answer behind its back. Without
+ * this the account state is whatever was true when the page loaded, so a
+ * terminal sign-in looks like it did nothing until a reload.
+ *
+ * Directories, never the credential files themselves: the CLIs replace those by
+ * rename, which leaves a file watch holding the old inode and silently deaf --
+ * the same reason castle-sandboxes persists these paths as directory symlinks.
+ * A directory that doesn't exist yet (no `~/.castle` until the first key) simply
+ * isn't watched; the caller's poll is what covers that, and losing a watcher
+ * costs freshness, never correctness.
+ */
+export declare function watchCredentials(onChange: () => void): () => void;
+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,240 @@
+// 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 installCliShims), 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, claudeCredentialsPath, claudeHasSavedLogin, cursorAuthPath, 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(),
+    };
+}
+// Several events land for one credential change (a rename is a delete plus a
+// create, and the CLIs write neighbouring files in the same breath); one
+// snapshot after the burst is what the editor wants.
+const WATCH_DEBOUNCE_MS = 250;
+/**
+ * Call `onChange` when a credential this module reports on changes on disk.
+ *
+ * The editor is not the only writer: `claude /login` and `cursor-agent login`
+ * in the terminal panel, an agent run that refreshes an OAuth token, and a
+ * hand-edited `user-keys.json` all change the answer behind its back. Without
+ * this the account state is whatever was true when the page loaded, so a
+ * terminal sign-in looks like it did nothing until a reload.
+ *
+ * Directories, never the credential files themselves: the CLIs replace those by
+ * rename, which leaves a file watch holding the old inode and silently deaf --
+ * the same reason castle-sandboxes persists these paths as directory symlinks.
+ * A directory that doesn't exist yet (no `~/.castle` until the first key) simply
+ * isn't watched; the caller's poll is what covers that, and losing a watcher
+ * costs freshness, never correctness.
+ */
+export function watchCredentials(onChange) {
+    const dirs = new Set([
+        claudeCredentialsPath(),
+        cursorAuthPath(os.homedir()),
+        CASTLE_USER_KEYS_PATH,
+    ].map((p) => path.dirname(p)));
+    let timer = null;
+    const fire = () => {
+        if (timer)
+            clearTimeout(timer);
+        timer = setTimeout(onChange, WATCH_DEBOUNCE_MS);
+        timer.unref?.();
+    };
+    const watchers = [];
+    for (const dir of dirs) {
+        try {
+            const w = fs.watch(dir, fire);
+            // A watch that dies later (the directory is removed, inotify runs out)
+            // must not take the serve with it -- fs.watch reports those as an error
+            // event, which is fatal when nothing is listening.
+            w.on("error", () => undefined);
+            watchers.push(w);
+        }
+        catch {
+            /* not watchable here */
+        }
+    }
+    return () => {
+        if (timer)
+            clearTimeout(timer);
+        for (const w of watchers)
+            w.close();
+    };
+}
+// 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;
@@ -15,9 +17,19 @@ export type OpenrouterAuth = {
     mode: "proxy";
     key: string;
 };
+export declare function claudeCredentialsPath(): 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 const SHIMMED_CLIS: readonly ["claude", "cursor-agent"];
+export type ShimmedCli = (typeof SHIMMED_CLIS)[number];
+export declare function claudeShellEnvScript(env: NodeJS.ProcessEnv, args?: readonly string[]): string;
+export declare function cursorShellEnvScript(env: NodeJS.ProcessEnv): string;
+export declare function shimEnvScript(cli: string, env: NodeJS.ProcessEnv, shimDir: string, args?: readonly string[]): string;
+export declare function ensureClaudeOnboarded(): void;
+export declare function installCliShims(deckDir: string): string | null;