@skrr-ai/cli 0.1.8

package/dist/lib/api-fetch.js

@@ -0,0 +1,248 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiFetchError = void 0;
+exports.apiFetch = apiFetch;
+exports.hasHumanSession = hasHumanSession;
+/**
+ * api-fetch.ts — authenticated fetch helper for endpoints not yet in
+ * @skrr-ai/data-provider's `dataService`.
+ *
+ * The data-provider covers the long-established REST surface (messages,
+ * agents, files, etc). New server endpoints — e.g. Phase I CI-token
+ * management — ship in the CLI before they're added to dataService, so
+ * the CLI needs a minimal auth'd fetch it can call directly.
+ *
+ * Design rules:
+ *   - Read the token exactly like the node-adapter does (via the
+ *     pre-resolved override in base-command), so CI tokens, env tokens,
+ *     and helper-script tokens all work uniformly.
+ *   - Stamp the same `X-Oversky-Origin` header so server-side
+ *     benign-grace-window matching is consistent across refresh and
+ *     resource calls.
+ *   - Surface 4xx/5xx as structured errors with `status` + `body` the
+ *     caller can branch on, matching what `node-adapter.ts` does for
+ *     dataService calls.
+ *
+ * This is deliberately NOT wired through the HttpAdapter — doing so
+ * would require extending `HttpAdapter`'s type interface for every new
+ * endpoint we add, which defeats the purpose of a narrow escape hatch.
+ * When a CI-token endpoint graduates into dataService, commands can
+ * switch to `dataService.*` without touching the wire contract.
+ */
+const config_1 = require("./config");
+// ADD-CLI8 — `readFromBackend` is only used inside `hasHumanSession()`
+// (see below), NOT by `apiFetch`. Kept as a module-scope import
+// rather than inlined into `hasHumanSession` because (a) ES modules
+// hoist imports anyway so there's no load-time difference, and
+// (b) tests that mock './auth-storage' get a single mock target.
+const auth_storage_1 = require("./auth-storage");
+const credential_resolver_1 = require("./credential-resolver");
+const node_adapter_1 = require("./node-adapter");
+const refresh_1 = require("./refresh");
+const delegated_cli_1 = require("./delegated-cli");
+const workspace_header_1 = require("./workspace-header");
+const non_json_response_1 = require("./non-json-response");
+class ApiFetchError extends Error {
+    status;
+    body;
+    code;
+    constructor(message, status, body, code) {
+        super(message);
+        this.name = 'ApiFetchError';
+        this.status = status;
+        this.body = body;
+        this.code = code;
+    }
+}
+exports.ApiFetchError = ApiFetchError;
+/**
+ * Call an skrr API endpoint with the current credential. Throws
+ * `ApiFetchError` on any non-2xx status so callers can branch on
+ * `err.status` / `err.code`.
+ */
+async function apiFetch(pathOrUrl, opts = {}) {
+    const sessionCredential = (0, credential_resolver_1.resolveTrustedAutonomousCredential)();
+    // A few Agent-only APIs (message/voice/telephony intents) deliberately pass
+    // the daemon-issued session token explicitly. Keep those endpoints bound to
+    // the session principal; every other CLI API call in a delegated Agent uses
+    // the renewable, full-permission CLI principal.
+    //
+    // Compare against the raw env var rather than `sessionCredential.token`:
+    // those callers all read `OVERSKY_SESSION_TOKEN` themselves, and the
+    // resolver yields a null token when the var is absent — which would make an
+    // equality check against it silently fail open.
+    const envSessionToken = process.env.OVERSKY_SESSION_TOKEN?.trim() || null;
+    const explicitSessionCredential = Boolean(opts.credential?.token && envSessionToken && opts.credential.token === envSessionToken);
+    const delegatedCli = (0, delegated_cli_1.isDelegatedCliSession)() && !explicitSessionCredential;
+    const autonomousCredential = delegatedCli
+        ? await (0, delegated_cli_1.fetchDelegatedCliCredential)()
+        : sessionCredential;
+    const baseURL = autonomousCredential ? trustedAutonomousBaseUrl() : (0, config_1.loadConfig)().baseURL;
+    const method = opts.method ?? 'GET';
+    const url = /^https?:\/\//i.test(pathOrUrl)
+        ? autonomousCredential
+            ? assertTrustedAutonomousUrl(pathOrUrl, baseURL)
+            : pathOrUrl
+        : `${baseURL.replace(/\/+$/, '')}${pathOrUrl.startsWith('/') ? '' : '/'}${pathOrUrl}`;
+    let body;
+    if (opts.body !== undefined && method !== 'GET') {
+        body = JSON.stringify(opts.body);
+    }
+    // A trusted Agent process cannot smuggle an explicit human credential into
+    // this escape hatch. The daemon-issued session token is the sole principal.
+    //
+    // The delegated branch is spelled out separately because `??` would walk on
+    // to `resolveCredential()`, which reads the KEYCHAIN. That is unreachable
+    // today — `fetchDelegatedCliCredential` throws rather than returning null
+    // whenever the session IS delegated — but WL-5 Step 1 makes null a real
+    // outcome: a daemon that deliberately declines the wide credential now
+    // answers 403 `DELEGATED_CLI_CAPABILITY_REJECTED`, and the child should use
+    // the session-scoped token it already holds.
+    //
+    // Written explicitly rather than left to the chain, because "the next link
+    // happens to be unreachable" is a property of code elsewhere, and the cost of
+    // being wrong about it is a managed child sending the user's own credential.
+    let cred;
+    if (delegatedCli) {
+        const delegated = autonomousCredential ?? (sessionCredential?.token ? sessionCredential : null);
+        if (!delegated?.token) {
+            throw new Error('Delegated CLI session has no usable credential: the daemon declined the delegated ' +
+                'grant and no OVERSKY_SESSION_TOKEN is present. Refusing to fall back to a stored ' +
+                'human credential.');
+        }
+        cred = delegated;
+    }
+    else {
+        // `getAdapterCredentialOverride()` is what `BaseCommand.init()` resolved for
+        // this invocation — it already encodes `--token` and `--bare`. Consulting it
+        // BEFORE `resolveCredential()` is what stops those flags from being silently
+        // discarded by every apiFetch-based library (OSK-4691); it can only replace
+        // "read the keychain", never the delegated or autonomous principals decided
+        // above, so the isolation invariants those branches exist for are untouched.
+        cred =
+            autonomousCredential ??
+                opts.credential ??
+                (0, node_adapter_1.getAdapterCredentialOverride)() ??
+                (await (0, credential_resolver_1.resolveCredential)());
+    }
+    const fetchWithCredential = (credential) => {
+        const headers = {
+            Accept: 'application/json',
+            'X-Oversky-Origin': (0, refresh_1.getCliOrigin)(),
+        };
+        if (opts.body !== undefined && method !== 'GET') {
+            headers['Content-Type'] = 'application/json';
+        }
+        if (credential.token) {
+            headers.Authorization = `Bearer ${credential.token}`;
+        }
+        // Caller headers are applied BEFORE the auth header below is read, and
+        // deliberately cannot clobber Authorization / Content-Type: an idempotency
+        // key is additive metadata, not a way to re-auth the request.
+        for (const [k, v] of Object.entries(opts.headers ?? {})) {
+            const lower = k.toLowerCase();
+            if (lower === 'authorization' || lower === 'content-type')
+                continue;
+            headers[k] = v;
+        }
+        return fetch(url, {
+            method,
+            headers: (0, workspace_header_1.withWorkspaceHeader)(headers),
+            body,
+            ...(opts.signal ? { signal: opts.signal } : {}),
+        });
+    };
+    let res = await fetchWithCredential(cred);
+    if (res.status === 401 && delegatedCli) {
+        // Deliberately terminal on broker failure: an Agent whose daemon cannot
+        // rotate its family must surface the 401, never fall through to
+        // `ensureFreshCliCredential` and adopt the human's stored refresh family.
+        const fresh = await (0, delegated_cli_1.fetchDelegatedCliCredential)(process.env, { forceRefresh: true });
+        if (fresh?.token) {
+            cred = fresh;
+            (0, node_adapter_1.setAdapterCredentialOverride)(cred);
+            res = await fetchWithCredential(cred);
+        }
+    }
+    else if (res.status === 401 && !autonomousCredential && !isAuthEndpoint(pathOrUrl)) {
+        const fresh = await (0, refresh_1.ensureFreshCliCredential)({ credential: cred, force: true });
+        if (fresh.refreshed && fresh.credential.token) {
+            cred = fresh.credential;
+            (0, node_adapter_1.setAdapterCredentialOverride)(cred);
+            res = await fetchWithCredential(cred);
+        }
+    }
+    if (!res.ok) {
+        let text = '';
+        let code;
+        try {
+            text = await res.text();
+            try {
+                const parsed = JSON.parse(text);
+                if (typeof parsed.code === 'string')
+                    code = parsed.code;
+            }
+            catch {
+                /* non-JSON body */
+            }
+        }
+        catch {
+            /* ignore body read failures */
+        }
+        throw new ApiFetchError(`HTTP ${res.status} ${res.statusText} — ${method} ${pathOrUrl}`, res.status, text, code);
+    }
+    // 204/205 carry no body by definition; an empty body has no content-type
+    // worth judging. Neither is an error.
+    if (res.status === 204 || res.status === 205) {
+        return undefined;
+    }
+    const contentType = res.headers.get('content-type') ?? '';
+    if (!contentType.includes('application/json')) {
+        const text = await res.text().catch(() => '');
+        if (text.trim() === '') {
+            return undefined;
+        }
+        // See non-json-response.ts: a 2xx that is not JSON is a response from
+        // something other than the endpoint we asked for (usually the SPA
+        // catch-all). Casting it to T makes an HTML page look like data.
+        throw (0, non_json_response_1.nonJsonResponseError)(method, pathOrUrl, res.status, contentType, text);
+    }
+    return (await res.json());
+}
+function trustedAutonomousBaseUrl() {
+    // Only the daemon-owned alias is accepted. OVERSKY_BASE_URL is a normal
+    // user/CLI override and may originate in request-carried provider env.
+    const baseURL = (process.env.OVERSKY_SERVER_URL || '').trim();
+    if (baseURL)
+        return baseURL;
+    throw new Error('Trusted autonomous API request is missing OVERSKY_SERVER_URL; refusing to read user CLI configuration.');
+}
+function assertTrustedAutonomousUrl(url, baseURL) {
+    const requested = new URL(url);
+    const trusted = new URL(baseURL);
+    if (requested.origin !== trusted.origin) {
+        throw new Error('Trusted autonomous API request cannot send its session credential to a different origin.');
+    }
+    return url;
+}
+function isAuthEndpoint(pathOrUrl) {
+    try {
+        const path = /^https?:\/\//i.test(pathOrUrl) ? new URL(pathOrUrl).pathname : pathOrUrl;
+        return path.includes('/api/auth/');
+    }
+    catch {
+        return pathOrUrl.includes('/api/auth/');
+    }
+}
+/**
+ * True when the current process has a persisted refresh-capable session
+ * (`skrr login` has been run and survived). Used by CI-token commands
+ * to reject an operator trying to mint a CI token with only a CI token
+ * already in their env (which would be privilege escalation — see
+ * `api/server/middleware/refuseDaemonScope.js`).
+ */
+function hasHumanSession() {
+    const cfg = (0, config_1.loadConfig)();
+    const read = (0, auth_storage_1.readFromBackend)(cfg.baseURL);
+    return Boolean(read.bundle?.refreshToken);
+}

package/dist/lib/assignee-resolver.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Space-scoped assignee resolution.
+ *
+ * `--assignee-user` / `--assignee-agent` have always required raw ids: a Mongo
+ * ObjectId for a person, a UUID for an agent. That is fine for a script that
+ * already holds the id and hostile for everything else — an agent wanting to
+ * hand a task to "Frank" had to run `spaces members list`, eyeball the table,
+ * and copy a hex string into a second command. This module turns a human-typed
+ * reference into exactly one member of the task's space, or an actionable
+ * failure that names the candidates.
+ *
+ * Scoping to the space is not just ergonomics. The server rejects assignees
+ * that are not space members (`SpacePermissionService.validateAssigneeSpaceMembership`
+ * → `ASSIGNEE_NOT_IN_SPACE`), so resolving against the space membership list
+ * means a name that resolves is a name that will be accepted — we never build
+ * a request the server is guaranteed to refuse, and we cannot accidentally
+ * leak a directory-wide user search into a space the caller can't see.
+ */
+export type MemberKind = 'user' | 'agent';
+export type SpaceMember = {
+    kind: MemberKind;
+    /** The id to put in `assigneeUserIds` / `assigneeAgentIds`. */
+    id: string;
+    name?: string;
+    email?: string;
+};
+export type ResolutionFailure = {
+    ok: false;
+    /**
+     * NOT_FOUND  — nothing matched.
+     * AMBIGUOUS  — several equally-good matches; refusing to guess.
+     * NO_SPACE   — the reference needs a membership list to match against, but
+     *              the task/payload has no space, so only raw ids are possible.
+     */
+    code: 'NOT_FOUND' | 'AMBIGUOUS' | 'NO_SPACE';
+    query: string;
+    kind: MemberKind;
+    /** For AMBIGUOUS: the tied matches. For NOT_FOUND: everything available. */
+    candidates: SpaceMember[];
+};
+export type ResolutionSuccess = {
+    ok: true;
+    member: SpaceMember;
+};
+export type Resolution = ResolutionSuccess | ResolutionFailure;
+/** Does this string already look like an id we can pass straight through? */
+export declare function looksLikeRawId(value: string, kind: MemberKind): boolean;
+/**
+ * Map the `principals` array from `GET /api/permissions/:type/:id` onto the
+ * flat shape this module matches against. Agent principals carry the agent's
+ * public UUID in `idOnTheSource` (`id` is the Mongo `_id`), which is what the
+ * task assignee fields expect — the same distinction `principalIdForDisplay`
+ * makes for the members table.
+ */
+export declare function membersFromPrincipals(principals: Array<Record<string, unknown>>): SpaceMember[];
+/**
+ * Resolve `query` against `members`, narrowest match first.
+ *
+ * The tiers exist so a precise reference always beats a loose one: someone
+ * named "Sam" is not ambiguous just because "Samantha" also exists, and an
+ * exact email is never outvoted by a name that happens to contain it. A tier
+ * that matches nothing falls through; a tier that matches more than one stops
+ * and reports AMBIGUOUS rather than silently picking — assigning work to the
+ * wrong person is worse than making the caller disambiguate.
+ */
+export declare function resolveMember(query: string, members: SpaceMember[], kind: MemberKind): Resolution;
+export declare function describeMember(m: SpaceMember): string;
+/** Render the candidate list for an error message, bounded so it stays readable. */
+export declare function describeCandidates(candidates: SpaceMember[], limit?: number): string;
+export type AssigneeResolution = {
+    /** Resolved ids, in input order, ready for the assignee fields. */
+    ids: string[];
+    /** Only the entries that actually needed resolving (for confirmation output). */
+    resolved: Array<{
+        query: string;
+        member: SpaceMember;
+    }>;
+    failures: ResolutionFailure[];
+};
+/**
+ * Resolve a batch of assignee references, fetching space membership at most
+ * once and only when something actually needs it.
+ *
+ * The pass-through rule is deliberate and load-bearing for backwards
+ * compatibility: a value that already looks like a raw id is forwarded
+ * untouched, with **no** membership request. Every script and agent prompt
+ * that passes ObjectIds/UUIDs today keeps its exact previous behavior and
+ * its exact previous request count — name resolution is purely additive,
+ * reached only by inputs that would otherwise have been rejected by the
+ * server anyway.
+ */
+export declare function resolveAssigneeReferences({ queries, kind, spaceId, loadMembers, resolveSelfId, }: {
+    queries: string[];
+    kind: MemberKind;
+    spaceId?: string;
+    loadMembers: (spaceId: string) => Promise<SpaceMember[]>;
+    resolveSelfId: () => Promise<string>;
+}): Promise<AssigneeResolution>;
+/**
+ * One human-readable line per failure, suitable for a CLI error body.
+ * `bin` is threaded through so the suggested fix is copy-pasteable.
+ */
+export declare function formatResolutionFailure(failure: ResolutionFailure, bin?: string): string;

package/dist/lib/assignee-resolver.js

@@ -0,0 +1,204 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.looksLikeRawId = looksLikeRawId;
+exports.membersFromPrincipals = membersFromPrincipals;
+exports.resolveMember = resolveMember;
+exports.describeMember = describeMember;
+exports.describeCandidates = describeCandidates;
+exports.resolveAssigneeReferences = resolveAssigneeReferences;
+exports.formatResolutionFailure = formatResolutionFailure;
+const data_provider_1 = require("@skrr-ai/data-provider");
+const OBJECT_ID_RE = /^[0-9a-fA-F]{24}$/;
+const UUID_RE = /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$/;
+// Agent ids are transitioning from public UUIDs to opaque `agent_…` ids.
+// Treat the latter as already-resolved ids as well; otherwise `tasks create
+// --project … --assignee-agent agent_…` tries to resolve the opaque id as a
+// display name before the server can inherit the project's space.
+const OPAQUE_AGENT_ID_RE = /^agent_[A-Za-z0-9_-]{8,}$/;
+/** Does this string already look like an id we can pass straight through? */
+function looksLikeRawId(value, kind) {
+    return kind === 'user'
+        ? OBJECT_ID_RE.test(value)
+        : UUID_RE.test(value) || OPAQUE_AGENT_ID_RE.test(value);
+}
+function norm(value) {
+    return typeof value === 'string' ? value.trim().toLowerCase() : '';
+}
+function emailLocalPart(email) {
+    const at = email.indexOf('@');
+    return at === -1 ? email : email.slice(0, at);
+}
+/**
+ * Map the `principals` array from `GET /api/permissions/:type/:id` onto the
+ * flat shape this module matches against. Agent principals carry the agent's
+ * public UUID in `idOnTheSource` (`id` is the Mongo `_id`), which is what the
+ * task assignee fields expect — the same distinction `principalIdForDisplay`
+ * makes for the members table.
+ */
+function membersFromPrincipals(principals) {
+    const members = [];
+    for (const p of principals ?? []) {
+        if (p?.type === data_provider_1.PrincipalType.USER) {
+            const id = typeof p.id === 'string' ? p.id : '';
+            if (!id)
+                continue;
+            members.push({
+                kind: 'user',
+                id,
+                name: typeof p.name === 'string' ? p.name : undefined,
+                email: typeof p.email === 'string' ? p.email : undefined,
+            });
+        }
+        else if (p?.type === data_provider_1.PrincipalType.AGENT) {
+            // Prefer the source UUID; fall back to `id` so a principal shape that
+            // omits `idOnTheSource` still produces a usable (if less correct) row
+            // rather than vanishing from the candidate list.
+            const sourceId = typeof p.idOnTheSource === 'string' ? p.idOnTheSource : '';
+            const fallbackId = typeof p.id === 'string' ? p.id : '';
+            const id = sourceId || fallbackId;
+            if (!id)
+                continue;
+            members.push({
+                kind: 'agent',
+                id,
+                name: typeof p.name === 'string' ? p.name : undefined,
+            });
+        }
+    }
+    return members;
+}
+/**
+ * Resolve `query` against `members`, narrowest match first.
+ *
+ * The tiers exist so a precise reference always beats a loose one: someone
+ * named "Sam" is not ambiguous just because "Samantha" also exists, and an
+ * exact email is never outvoted by a name that happens to contain it. A tier
+ * that matches nothing falls through; a tier that matches more than one stops
+ * and reports AMBIGUOUS rather than silently picking — assigning work to the
+ * wrong person is worse than making the caller disambiguate.
+ */
+function resolveMember(query, members, kind) {
+    const pool = members.filter((m) => m.kind === kind);
+    const raw = query.trim();
+    const q = norm(raw);
+    if (!q) {
+        return { ok: false, code: 'NOT_FOUND', query: raw, kind, candidates: pool };
+    }
+    const tiers = [
+        // 1. Exact id. Case-sensitive on purpose — ids are opaque.
+        (m) => m.id === raw,
+        // 2. Exact email.
+        (m) => Boolean(m.email) && norm(m.email) === q,
+        // 3. Exact display name.
+        (m) => norm(m.name) === q,
+        // 4. Exact email local-part ("frank" matching frank@example.com).
+        (m) => Boolean(m.email) && emailLocalPart(norm(m.email)) === q,
+        // 5. Name prefix ("fra" → "Frank Du").
+        (m) => norm(m.name).startsWith(q),
+        // 6. Anywhere in name or email ("du" → "Frank Du").
+        (m) => norm(m.name).includes(q) || norm(m.email).includes(q),
+    ];
+    for (const match of tiers) {
+        const hits = pool.filter(match);
+        if (hits.length === 1)
+            return { ok: true, member: hits[0] };
+        if (hits.length > 1) {
+            return { ok: false, code: 'AMBIGUOUS', query: raw, kind, candidates: hits };
+        }
+    }
+    return { ok: false, code: 'NOT_FOUND', query: raw, kind, candidates: pool };
+}
+function describeMember(m) {
+    const label = m.name || m.email || m.id;
+    const detail = m.email && m.email !== label ? ` <${m.email}>` : '';
+    return `${label}${detail} (${m.id})`;
+}
+/** Render the candidate list for an error message, bounded so it stays readable. */
+function describeCandidates(candidates, limit = 10) {
+    if (candidates.length === 0)
+        return '';
+    const shown = candidates.slice(0, limit).map((m) => `  - ${describeMember(m)}`);
+    if (candidates.length > limit) {
+        shown.push(`  … and ${candidates.length - limit} more`);
+    }
+    return shown.join('\n');
+}
+/**
+ * Resolve a batch of assignee references, fetching space membership at most
+ * once and only when something actually needs it.
+ *
+ * The pass-through rule is deliberate and load-bearing for backwards
+ * compatibility: a value that already looks like a raw id is forwarded
+ * untouched, with **no** membership request. Every script and agent prompt
+ * that passes ObjectIds/UUIDs today keeps its exact previous behavior and
+ * its exact previous request count — name resolution is purely additive,
+ * reached only by inputs that would otherwise have been rejected by the
+ * server anyway.
+ */
+async function resolveAssigneeReferences({ queries, kind, spaceId, loadMembers, resolveSelfId, }) {
+    const ids = [];
+    const resolved = [];
+    const failures = [];
+    let members = null;
+    const members0 = async () => {
+        if (members === null)
+            members = spaceId ? await loadMembers(spaceId) : [];
+        return members;
+    };
+    for (const rawQuery of queries) {
+        const query = (rawQuery ?? '').trim();
+        if (!query)
+            continue;
+        if (kind === 'user' && query.toLowerCase() === 'me') {
+            const selfId = await resolveSelfId();
+            if (!ids.includes(selfId))
+                ids.push(selfId);
+            const known = (await members0()).find((m) => m.kind === 'user' && m.id === selfId);
+            resolved.push({ query, member: known ?? { kind: 'user', id: selfId } });
+            continue;
+        }
+        if (looksLikeRawId(query, kind)) {
+            if (!ids.includes(query))
+                ids.push(query);
+            continue;
+        }
+        if (!spaceId) {
+            failures.push({ ok: false, code: 'NO_SPACE', query, kind, candidates: [] });
+            continue;
+        }
+        const outcome = resolveMember(query, await members0(), kind);
+        if (outcome.ok) {
+            if (!ids.includes(outcome.member.id))
+                ids.push(outcome.member.id);
+            resolved.push({ query, member: outcome.member });
+        }
+        else {
+            failures.push(outcome);
+        }
+    }
+    return { ids, resolved, failures };
+}
+/**
+ * One human-readable line per failure, suitable for a CLI error body.
+ * `bin` is threaded through so the suggested fix is copy-pasteable.
+ */
+function formatResolutionFailure(failure, bin = 'skrr') {
+    const noun = failure.kind === 'user' ? 'person' : 'agent';
+    const plural = failure.kind === 'user' ? 'people' : 'agents';
+    switch (failure.code) {
+        case 'AMBIGUOUS':
+            return (`"${failure.query}" matches ${failure.candidates.length} ${plural} in this space:\n` +
+                `${describeCandidates(failure.candidates)}\n` +
+                `  → use a full email or the id to disambiguate.`);
+        case 'NO_SPACE':
+            return (`"${failure.query}" cannot be resolved by name — the task is not in a space.\n` +
+                `  → pass the raw ${noun} id, or set a space first.`);
+        default: {
+            const available = describeCandidates(failure.candidates);
+            return available
+                ? `No ${noun} matching "${failure.query}" in this space. Members:\n${available}`
+                : `No ${noun} matching "${failure.query}" — this space has no ${plural} ` +
+                    `(add one with \`${bin} spaces members add\`).`;
+        }
+    }
+}

package/dist/lib/auth-core-init.d.ts

@@ -0,0 +1,44 @@
+import { type AuthBundle } from './auth-storage';
+export declare function ensureAuthCoreConfigured(): void;
+export declare class CliCredentialInitializationError extends Error {
+    readonly code = "CREDENTIAL_INITIALIZATION_UNAVAILABLE";
+    readonly exitCode = 75;
+    readonly retryable = true;
+    readonly oclif: {
+        exit: number;
+    };
+    constructor(message: string);
+}
+/**
+ * Initialize L12 envelope + L11 device identity for the active profile.
+ * Idempotent across calls in the same process — repeated invocations
+ * adopt the in-flight promise. Fresh/plaintext installs are bounded by
+ * PREFETCH_TIMEOUT_MS; an already-encrypted credential gets a larger hard
+ * bound so lock contention cannot be mistaken for a missing login.
+ *
+ * Order matters:
+ *   1. `initCredEnvelope` first — `initDeviceIdentity` queries
+ *      `isCredEnvelopeActive()` to decide whether to wrap the private
+ *      key on persist.
+ *   2. `initDeviceIdentity` second.
+ *   3. Server enrollment is fire-and-forget; only attempts if a current
+ *      access token is already on disk (peek via the file backend slot
+ *      so a missing token short-circuits cleanly without creating a
+ *      whole CredentialResolver chain here).
+ *
+ * The peek path uses `backends.readKeychainToken / readFileToken`
+ * directly so we don't accidentally trigger an interactive prompt or
+ * spawn the auth-helper when the user is unauthenticated. Mirrors the
+ * daemon's `peekAuthAccessToken()` shape.
+ */
+export declare function prefetchCliAuth(): Promise<void>;
+/**
+ * Finish credential-envelope initialization after a backend read observed an
+ * encrypted value while the local state was inactive. This is intentionally
+ * separate from the eager prefetch: only a command that truly reaches stored
+ * credentials pays the larger bound or receives the typed local-store error.
+ */
+export declare function waitForCliCredentialEnvelope(): Promise<void>;
+/** @internal Test seam — reset the module-level one-shot initialization. */
+export declare function __resetPrefetchCliAuthForTest(): void;
+export declare function shouldUseAccessTokenForEnrollment(bundle: Pick<AuthBundle, 'token' | 'expiresAt'> | null | undefined, nowMs?: number, minTtlMs?: number): boolean;