@skrr-ai/cli 0.1.8

package/dist/lib/daemonBroker.js

@@ -0,0 +1,516 @@
+"use strict";
+/**
+ * daemonBroker.ts — Sky CLI client for the local `oversky` daemon's
+ * cli-handoff endpoint.
+ *
+ * When the daemon is already authenticated for the user on this machine,
+ * the CLI can skip its own browser-based login entirely by asking the
+ * daemon to broker a sibling cli-scope refresh family. See
+ * `daemon/src/auth/cliHandoff.ts` for the daemon-side handler and
+ * `api/server/routes/daemons.js::cli-handoff` for the server route.
+ *
+ * ## Design constraints
+ *
+ * - **Read-only on the daemon's auth.** The CLI never touches the
+ *   daemon's keychain entries directly — it goes through the loopback
+ *   HTTP broker which uses the daemon's bearer to call the server. That
+ *   means a logged-out daemon = clean fall-through to PKCE, not a CLI
+ *   that tries to read stale credentials.
+ * - **Bounded total time.** The broker call must not hang the CLI on a
+ *   wedged daemon. Combined header + body + upstream is capped at 20s
+ *   (matches the daemon's own 15s upstream cap + a 5s buffer).
+ * - **Distinct exit semantics.** Any error short-circuits to "fall
+ *   through to PKCE" — only an explicit 403 with `code:
+ *   'CI_TOKEN_REFUSED'` is surfaced to the user (skrr shouldn't silently
+ *   reauthenticate a CI process). Everything else returns `null`.
+ *
+ * ## Bootstrap file location
+ *
+ * Mirrors `daemon/src/local-bootstrap.ts::bootstrapPath()`. On macOS the
+ * file is `~/Library/Application Support/skrr/daemon-island.<profile>.json`;
+ * on Linux/Windows it's `~/.skrr/profiles/<profile>/daemon-island.json`
+ * with a pre-Phase-K fallback to `~/.skrr/daemon-island.json`. We
+ * default `<profile>` to `'default'` to match the CLI's existing keychain
+ * service-name suffix; a future `--profile` flag would override this.
+ *
+ * The bootstrap file carries `{ pid, host, port, secret }`. We check pid
+ * liveness with `process.kill(pid, 0)` to filter stale files left behind
+ * by a force-killed daemon.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeBaseUrl = normalizeBaseUrl;
+exports.resolveBootstrapPath = resolveBootstrapPath;
+exports.resolveProfileBootstrapPaths = resolveProfileBootstrapPaths;
+exports.resolveBootstrapCandidatePaths = resolveBootstrapCandidatePaths;
+exports.findLiveDaemonBootstrap = findLiveDaemonBootstrap;
+exports.readBootstrap = readBootstrap;
+exports.attemptDaemonBrokerLogin = attemptDaemonBrokerLogin;
+exports.attemptDaemonBrokerLoginAndPersist = attemptDaemonBrokerLoginAndPersist;
+exports.maybeAutoBroker = maybeAutoBroker;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const os = __importStar(require("node:os"));
+const auth_storage_1 = require("./auth-storage");
+const config_1 = require("./config");
+const device_id_1 = require("./device-id");
+const REQUEST_TIMEOUT_MS = 20_000;
+/**
+ * Normalize a base URL for equality comparison. Mirrors the daemon-side
+ * `normalizeBaseUrl` in `daemon/src/auth/cliHandoff.ts` so both ends
+ * compare identical strings. Trailing slashes stripped, scheme + host
+ * lowercased, path preserved as-is.
+ */
+function normalizeBaseUrl(u) {
+    if (typeof u !== 'string' || u.length === 0)
+        return null;
+    const trimmed = u.trim().replace(/\/+$/, '');
+    if (trimmed.length === 0)
+        return null;
+    try {
+        const url = new URL(trimmed);
+        const port = url.port ? `:${url.port}` : '';
+        const path = url.pathname === '/' ? '' : url.pathname;
+        return (0, config_1.canonicalizeKnownBaseURL)(`${url.protocol.toLowerCase()}//${url.hostname.toLowerCase()}${port}${path}${url.search}`);
+    }
+    catch {
+        return (0, config_1.canonicalizeKnownBaseURL)(trimmed.toLowerCase());
+    }
+}
+/**
+ * Compute the bootstrap file path. Exported for tests so they can assert
+ * the platform fork without monkeypatching `os.platform()`.
+ */
+function resolveBootstrapPath(profile = 'default') {
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'skrr', `daemon-island.${profile}.json`);
+    }
+    // Phase K per-profile layout. The pre-Phase-K fallback is checked at
+    // read time in `readBootstrap` so an upgrade-in-progress machine still
+    // works.
+    return path.join(os.homedir(), '.skrr', 'profiles', profile, 'daemon-island.json');
+}
+/** Build deterministic non-default bootstrap paths from a daemon config directory. */
+function resolveProfileBootstrapPaths(primary, entryNames) {
+    const extras = entryNames
+        .filter((name) => /^daemon-island\.(?!default\.json$)[^.]+\.json$/.test(name))
+        .sort()
+        .map((name) => path.join(path.dirname(primary), name));
+    return [primary, ...extras];
+}
+/**
+ * List the bootstrap files that a Sky CLI may use for a local daemon
+ * handoff. `default` stays first for backwards compatibility; any other
+ * profile is a fallback for users who run their daemon with `--profile`.
+ *
+ * Profile names are derived from filenames/directories created by the
+ * daemon, never interpolated from user input. Sorting makes the fallback
+ * deterministic when more than one matching daemon is running.
+ */
+function resolveBootstrapCandidatePaths(profile = 'default') {
+    const primary = resolveBootstrapPath(profile);
+    if (profile !== 'default')
+        return [primary];
+    try {
+        if (process.platform === 'darwin') {
+            const dir = path.dirname(primary);
+            const entryNames = fs
+                .readdirSync(dir, { withFileTypes: true })
+                .filter((entry) => entry.isFile())
+                .map((entry) => entry.name);
+            return resolveProfileBootstrapPaths(primary, entryNames);
+        }
+        const profilesDir = path.dirname(path.dirname(primary));
+        const extras = fs
+            .readdirSync(profilesDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && entry.name !== 'default')
+            .map((entry) => path.join(profilesDir, entry.name, 'daemon-island.json'))
+            .sort();
+        return [primary, ...extras, legacyBootstrapPath()];
+    }
+    catch {
+        return process.platform === 'darwin' ? [primary] : [primary, legacyBootstrapPath()];
+    }
+}
+/**
+ * Pre-Phase-K bootstrap path (non-darwin). Read-only fallback consulted
+ * when the canonical path is absent — covers a freshly-upgraded daemon
+ * that has not yet rewritten the new file.
+ */
+function legacyBootstrapPath() {
+    return path.join(os.homedir(), '.skrr', 'daemon-island.json');
+}
+/**
+ * Resolve the first live daemon bootstrap for a profile. Message-intent
+ * submission reuses the same authenticated loopback discovery as the login
+ * broker, including the pre-Phase-K non-darwin fallback.
+ */
+function findLiveDaemonBootstrap({ profile = 'default', bootstrapPathOverride, } = {}) {
+    const candidates = bootstrapPathOverride
+        ? [bootstrapPathOverride]
+        : resolveBootstrapCandidatePaths(profile);
+    for (const candidate of candidates) {
+        const bootstrap = readBootstrap(candidate);
+        if (bootstrap)
+            return bootstrap;
+    }
+    return null;
+}
+/**
+ * Read and validate the bootstrap file. Returns null on absent / stale /
+ * unparseable so the caller can fall through to its own login flow
+ * without distinguishing those cases (the daemon owns recovery — if the
+ * file is malformed, the CLI shouldn't try to repair it).
+ */
+function readBootstrap(filePath) {
+    let raw;
+    try {
+        if (!fs.existsSync(filePath))
+            return null;
+        raw = fs.readFileSync(filePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed?.host !== '127.0.0.1' ||
+        typeof parsed?.port !== 'number' ||
+        !Number.isInteger(parsed.port) ||
+        parsed.port < 1 ||
+        parsed.port > 65_535 ||
+        typeof parsed?.secret !== 'string' ||
+        Buffer.from(parsed.secret, 'base64').length !== 32) {
+        return null;
+    }
+    // PID liveness — ESRCH means the daemon was force-killed and the file
+    // outlived the process. EPERM means alive but not signalable by us,
+    // which on a same-UID file is unusual but not disqualifying.
+    if (typeof parsed.pid === 'number' && parsed.pid > 0) {
+        try {
+            process.kill(parsed.pid, 0);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === 'ESRCH')
+                return null;
+            // EPERM / other: keep going.
+        }
+    }
+    return parsed;
+}
+/**
+ * Try the daemon-as-broker handoff. Returns a tagged outcome so callers
+ * can decide between fall-through and surface-to-user without parsing
+ * messages.
+ *
+ * The CLI's `cliLogin()` dispatcher calls this BEFORE the PKCE branch;
+ * any `ok: false` outcome (except `ci_token_refused`) means "continue to
+ * PKCE", and `ok: true` means "we're done, persist + return".
+ */
+async function attemptDaemonBrokerLogin(opts) {
+    const profile = opts.profile ?? 'default';
+    const candidates = opts.bootstrapPathOverride
+        ? [opts.bootstrapPathOverride]
+        : resolveBootstrapCandidatePaths(profile);
+    let bootstrap = null;
+    let usedPath = null;
+    let unboundBootstrap = null;
+    let unboundPath = null;
+    let mismatchedBootstrap = null;
+    for (const candidate of candidates) {
+        const candidateBootstrap = readBootstrap(candidate);
+        if (!candidateBootstrap)
+            continue;
+        if (typeof candidateBootstrap.serverUrl === 'string' &&
+            candidateBootstrap.serverUrl.length > 0 &&
+            typeof opts.baseURL === 'string' &&
+            opts.baseURL.length > 0 &&
+            normalizeBaseUrl(opts.baseURL) !== normalizeBaseUrl(candidateBootstrap.serverUrl)) {
+            mismatchedBootstrap ??= candidateBootstrap;
+            continue;
+        }
+        if (typeof candidateBootstrap.serverUrl !== 'string' ||
+            candidateBootstrap.serverUrl.length === 0) {
+            unboundBootstrap ??= candidateBootstrap;
+            unboundPath ??= candidate;
+            continue;
+        }
+        bootstrap = candidateBootstrap;
+        usedPath = candidate;
+        break;
+    }
+    if (!bootstrap && unboundBootstrap && unboundPath) {
+        bootstrap = unboundBootstrap;
+        usedPath = unboundPath;
+    }
+    if (!bootstrap || !usedPath) {
+        if (mismatchedBootstrap?.serverUrl) {
+            return {
+                ok: false,
+                reason: 'base_url_mismatch',
+                detail: `No local oversky daemon is logged in to ${opts.baseURL}; available daemon is logged in to ${mismatchedBootstrap.serverUrl}.`,
+                daemonServerUrl: mismatchedBootstrap.serverUrl,
+            };
+        }
+        return {
+            ok: false,
+            reason: 'no_bootstrap',
+            detail: `No daemon bootstrap file found (looked in ${candidates.join(', ')})`,
+        };
+    }
+    const url = `http://${bootstrap.host}:${bootstrap.port}/v1/auth/cli-handoff`;
+    const timeoutMs = opts.timeoutMs ?? REQUEST_TIMEOUT_MS;
+    const controller = new AbortController();
+    const abortTimer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetch(url, {
+            method: 'POST',
+            headers: {
+                Authorization: `Bearer ${bootstrap.secret}`,
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+            },
+            body: JSON.stringify({
+                cliId: opts.cliId,
+                // Sent so the daemon can re-validate; older daemons that don't
+                // know about the field ignore it. Pre-flight already handled
+                // the modern-daemon case above; the server-side body check is
+                // for safety when the bootstrap was missing the serverUrl
+                // field (e.g. a daemon that updated its binary mid-flight).
+                ...(typeof opts.baseURL === 'string' && opts.baseURL.length > 0
+                    ? { baseURL: opts.baseURL }
+                    : {}),
+            }),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (err.name === 'AbortError') {
+            return { ok: false, reason: 'timeout', detail: `Broker call timed out after ${timeoutMs}ms` };
+        }
+        return { ok: false, reason: 'network', detail: msg };
+    }
+    finally {
+        clearTimeout(abortTimer);
+    }
+    let parsedBody = null;
+    try {
+        parsedBody = (await response.json());
+    }
+    catch {
+        parsedBody = null;
+    }
+    if (!response.ok) {
+        const code = typeof parsedBody?.code === 'string' ? parsedBody.code : undefined;
+        const message = typeof parsedBody?.message === 'string'
+            ? parsedBody.message
+            : `Broker returned HTTP ${response.status}`;
+        if (response.status === 403 && code === 'CI_TOKEN_REFUSED') {
+            return { ok: false, reason: 'ci_token_refused', detail: message, status: 403, code };
+        }
+        if (response.status === 503 && code === 'DAEMON_NOT_AUTHED') {
+            return { ok: false, reason: 'daemon_not_authed', detail: message, status: 503, code };
+        }
+        if (response.status === 400 && code === 'BASE_URL_MISMATCH') {
+            // Older daemon binary that lacked the bootstrap.serverUrl field
+            // ended up here despite the CLI sending baseURL. Treat as the
+            // same outcome as the pre-flight catch.
+            const daemonServerUrl = typeof parsedBody?.daemonServerUrl === 'string'
+                ? parsedBody.daemonServerUrl
+                : undefined;
+            return {
+                ok: false,
+                reason: 'base_url_mismatch',
+                detail: message,
+                status: 400,
+                code,
+                ...(daemonServerUrl ? { daemonServerUrl } : {}),
+            };
+        }
+        return {
+            ok: false,
+            reason: response.status >= 500 ? 'server_error' : 'unknown',
+            detail: message,
+            status: response.status,
+            ...(code ? { code } : {}),
+        };
+    }
+    // Happy path — validate the response shape minimally.
+    if (!parsedBody ||
+        typeof parsedBody.accessToken !== 'string' ||
+        typeof parsedBody.refreshToken !== 'string' ||
+        typeof parsedBody.cliId !== 'string' ||
+        typeof parsedBody.userId !== 'string') {
+        return {
+            ok: false,
+            reason: 'server_error',
+            detail: 'Broker returned 200 but the response body did not match the expected shape',
+            status: response.status,
+        };
+    }
+    return {
+        ok: true,
+        accessToken: parsedBody.accessToken,
+        accessExpiresAt: parsedBody.accessExpiresAt,
+        refreshToken: parsedBody.refreshToken,
+        refreshExpiresAt: parsedBody.refreshExpiresAt,
+        cliId: parsedBody.cliId,
+        userId: parsedBody.userId,
+        email: parsedBody.email ?? null,
+    };
+}
+/**
+ * Helper: coerce an ISO-string or numeric expiry to epoch ms for
+ * `writeToBackend`. Returns undefined on missing / unparseable input.
+ */
+function expiryToEpochMs(v) {
+    if (typeof v === 'number' && Number.isFinite(v))
+        return v;
+    if (typeof v === 'string' && v.length > 0) {
+        const t = Date.parse(v);
+        return Number.isFinite(t) ? t : undefined;
+    }
+    return undefined;
+}
+/**
+ * Convenience wrapper: run the broker call and, on success, persist the
+ * returned bundle through the canonical Sky CLI auth backend (Keychain
+ * on macOS, `cli-auth.json` elsewhere). Returns the same outcome shape
+ * so the caller can branch on `ok`.
+ */
+async function attemptDaemonBrokerLoginAndPersist(opts) {
+    const outcome = await attemptDaemonBrokerLogin(opts);
+    if (!outcome.ok)
+        return outcome;
+    const serverOrigin = normalizeBaseUrl(opts.baseURL);
+    if (!serverOrigin) {
+        throw new Error('Daemon-broker credential persistence requires a valid CLI baseURL.');
+    }
+    (0, auth_storage_1.writeToBackend)({
+        token: outcome.accessToken,
+        refreshToken: outcome.refreshToken,
+        ...(expiryToEpochMs(outcome.accessExpiresAt) !== undefined
+            ? { expiresAt: expiryToEpochMs(outcome.accessExpiresAt) }
+            : {}),
+        ...(expiryToEpochMs(outcome.refreshExpiresAt) !== undefined
+            ? { refreshExpiresAt: expiryToEpochMs(outcome.refreshExpiresAt) }
+            : {}),
+    }, { serverOrigin, clearReauth: true });
+    return outcome;
+}
+// ---------------------------------------------------------------------
+// Auto-broker on first command (BaseCommand.init hook)
+// ---------------------------------------------------------------------
+/**
+ * Commands that manage their own auth lifecycle. The auto-broker MUST
+ * NOT fire for these — `login` and `pair` run their own minting flows
+ * (auto-brokering first would burn a needless server round-trip and
+ * mint a token that `cliLogin()` would immediately supersede), and
+ * `logout` is about CLEARING auth (auto-brokering first would mint a
+ * token only to revoke it on the next line).
+ *
+ * `generate-recovery-code` also stays out: it's already a
+ * non-interactive token-management primitive whose `requireAuth()`
+ * call should fail explicitly if the user isn't signed in, rather
+ * than silently logging them in via a side channel.
+ */
+const AUTH_SELF_MANAGED_COMMANDS = new Set([
+    'login',
+    'logout',
+    'pair',
+    'generate-recovery-code',
+]);
+/**
+ * Auto-broker pre-flight for `BaseCommand.init()`. When the credential
+ * resolver returns no token, this attempts a silent daemon broker so
+ * a user with `oversky login` already done never has to type
+ * `skrr login` at all.
+ *
+ * Skip rules (any single trigger short-circuits):
+ *   - `bareMode` — operator said "don't touch the keychain/file"
+ *   - `isEnvAuthOverride()` — `OVERSKY_TOKEN` / `OVERSKY_REFRESH_TOKEN`
+ *     supplied; operator owns auth lifecycle
+ *   - `OVERSKY_SKIP_DAEMON_BROKER=1` — explicit opt-out
+ *   - `commandId` is in `AUTH_SELF_MANAGED_COMMANDS`
+ *
+ * Side effects:
+ *   - Calls `attemptDaemonBrokerLoginAndPersist` which writes to the
+ *     keychain / cli-auth.json on success (this is the whole point —
+ *     subsequent commands read the persisted token via the normal
+ *     resolver chain, no broker round-trip per command).
+ *   - May generate a new `cliId` if the config doesn't have one. The
+ *     caller MUST persist `updatedConfig` so the next invocation
+ *     presents the same id to the server's refresh rotator.
+ *
+ * Never throws — broker call failures are surfaced via the typed
+ * `outcome` discriminator (or absent on skip).
+ */
+async function maybeAutoBroker(opts) {
+    if (opts.bareMode)
+        return { triggered: false };
+    if ((0, config_1.isEnvAuthOverride)())
+        return { triggered: false };
+    if (process.env.OVERSKY_SKIP_DAEMON_BROKER === '1')
+        return { triggered: false };
+    if (opts.commandId && AUTH_SELF_MANAGED_COMMANDS.has(opts.commandId)) {
+        return { triggered: false };
+    }
+    // Mint a cliId on the fly when missing. Persisted by the caller on
+    // success so the rotation row stays bound across processes.
+    let cliId = opts.cliConfig.cliId;
+    let updatedConfig;
+    if (!cliId) {
+        cliId = (0, device_id_1.generateCliId)();
+        updatedConfig = { ...opts.cliConfig, cliId };
+    }
+    const outcome = await attemptDaemonBrokerLoginAndPersist({
+        cliId,
+        baseURL: opts.cliConfig.baseURL,
+        ...(opts.bootstrapPathOverride ? { bootstrapPathOverride: opts.bootstrapPathOverride } : {}),
+    });
+    return {
+        triggered: true,
+        outcome,
+        ...(updatedConfig && outcome.ok ? { updatedConfig } : {}),
+    };
+}

package/dist/lib/delegated-cli.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Daemon-owned delegated CLI credentials for autonomous Agent sessions.
+ *
+ * A spawned Agent never reads the human Keychain or a refresh token. Instead
+ * it holds a random loopback capability and asks its parent daemon for a
+ * short-lived normal `scope=cli` access token. The daemon rotates the refresh
+ * family, so each Sky invocation retains the full command surface for the
+ * duration of a long-running Agent session.
+ */
+import { type ResolvedCredential } from '@skrr-ai/auth-core';
+export declare function isDelegatedCliSession(env?: Record<string, string | undefined>): boolean;
+/** Drop the memoized credential. Exported for tests. */
+export declare function resetDelegatedCliCredentialCache(): void;
+/** Fetch a full-permission CLI access token from the local daemon. */
+export declare function fetchDelegatedCliCredential(env?: Record<string, string | undefined>, options?: {
+    forceRefresh?: boolean;
+}): Promise<ResolvedCredential | null>;

package/dist/lib/delegated-cli.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isDelegatedCliSession = isDelegatedCliSession;
+exports.resetDelegatedCliCredentialCache = resetDelegatedCliCredentialCache;
+exports.fetchDelegatedCliCredential = fetchDelegatedCliCredential;
+/**
+ * Daemon-owned delegated CLI credentials for autonomous Agent sessions.
+ *
+ * A spawned Agent never reads the human Keychain or a refresh token. Instead
+ * it holds a random loopback capability and asks its parent daemon for a
+ * short-lived normal `scope=cli` access token. The daemon rotates the refresh
+ * family, so each Sky invocation retains the full command surface for the
+ * duration of a long-running Agent session.
+ */
+const auth_core_1 = require("@skrr-ai/auth-core");
+function isDelegatedCliSession(env = process.env) {
+    return Boolean(env.OVERSKY_AUTONOMOUS_SESSION === '1' &&
+        env.OVERSKY_DELEGATED_CLI_BROKER_URL?.trim() &&
+        env.OVERSKY_DELEGATED_CLI_CAPABILITY?.trim() &&
+        env.OVERSKY_SESSION_ID?.trim());
+}
+function trustedLoopbackUrl(raw) {
+    const url = new URL(raw);
+    if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '::1'].includes(url.hostname)) {
+        throw new Error('Delegated Sky CLI broker must be a loopback HTTP URL.');
+    }
+    return url.toString();
+}
+/**
+ * Process-lifetime cache of the last credential the broker issued.
+ *
+ * A `skrr` invocation is short-lived and the daemon already caches the access
+ * token behind its own broker, but without this every `apiFetch` in a
+ * paginating command would still pay a loopback round-trip. Keyed by
+ * capability so a (hypothetical) capability change invalidates it; cleared
+ * whenever a caller asks for a forced rotation.
+ */
+let _cached = null;
+/** Drop the memoized credential. Exported for tests. */
+function resetDelegatedCliCredentialCache() {
+    _cached = null;
+}
+/** Fetch a full-permission CLI access token from the local daemon. */
+async function fetchDelegatedCliCredential(env = process.env, options = {}) {
+    if (!isDelegatedCliSession(env))
+        return null;
+    const cacheKey = env.OVERSKY_DELEGATED_CLI_CAPABILITY.trim();
+    if (!options.forceRefresh && _cached?.capability === cacheKey) {
+        return _cached.credential;
+    }
+    _cached = null;
+    const brokerUrl = trustedLoopbackUrl(env.OVERSKY_DELEGATED_CLI_BROKER_URL.trim());
+    const capability = env.OVERSKY_DELEGATED_CLI_CAPABILITY.trim();
+    const sessionId = env.OVERSKY_SESSION_ID.trim();
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 5_000);
+    try {
+        const res = await fetch(brokerUrl, {
+            method: 'POST',
+            headers: { Accept: 'application/json', 'Content-Type': 'application/json' },
+            body: JSON.stringify({ capability, sessionId, forceRefresh: options.forceRefresh === true }),
+            signal: controller.signal,
+        });
+        if (!res.ok) {
+            // A DELIBERATE decline is not a broker failure — WL-5 Step 1.
+            //
+            // The daemon already distinguishes the two on the wire: 403 +
+            // `DELEGATED_CLI_CAPABILITY_REJECTED` means it chose not to release a
+            // wide credential (a narrowed `OVERSKY_DELEGATED_CLI_SURFACE`, or a
+            // revoked capability), while 503 means the broker itself is unavailable.
+            // Collapsing both into a throw is what made the surface flag unflippable:
+            // refusing the wide token turned every `skrr` call into a hard error
+            // instead of a fall back to the session-scoped token the child already
+            // holds.
+            //
+            // 503 stays terminal, deliberately. The original reasoning holds — an
+            // Agent whose daemon cannot rotate its family must surface that rather
+            // than quietly degrade, because a degraded credential path is exactly
+            // where a human's stored family gets adopted by accident.
+            if (res.status === 403) {
+                const body = (await res.json().catch(() => null));
+                if (body?.code === 'DELEGATED_CLI_CAPABILITY_REJECTED')
+                    return null;
+            }
+            throw new Error(`Delegated Sky CLI credential broker returned HTTP ${res.status}.`);
+        }
+        const body = (await res.json());
+        if (typeof body.accessToken !== 'string' || body.accessToken.length === 0) {
+            throw new Error('Delegated Sky CLI credential broker returned no access token.');
+        }
+        const credential = {
+            token: body.accessToken,
+            source: 'env-token',
+            kind: (0, auth_core_1.classifyTokenKind)(body.accessToken),
+        };
+        _cached = { capability: cacheKey, credential };
+        return credential;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}