flipstream 0.4.0 → 0.6.0

package/dist/commands/query.js

@@ -1,76 +1,289 @@
 import { Flags } from '@oclif/core';
 import { readFileSync } from 'node:fs';
-import { mapDataError } from '../lib/api/errors.js';
-import { createAuthedDataClient } from '../lib/api/retry.js';
-import { refresh } from '../lib/auth/refresh.js';
+import { tokenClaims } from '../lib/auth/claims.js';
+import { authedAdminClient } from '../lib/command/admin.js';
 import { BaseCommand } from '../lib/command/base.js';
-import { DATA_HOST } from '../lib/config/constants.js';
-import { resolveHost } from '../lib/config/xdg.js';
-import { AuthRequiredError, UsageError } from '../lib/errors.js';
+import { plannerFlags } from '../lib/command/flags.js';
+import { authedPlannerClient } from '../lib/command/planner.js';
+import { resolveHost, resolvePlannerUrl } from '../lib/config/xdg.js';
+import { AuthRequiredError, DataHttpError, UsageError } from '../lib/errors.js';
 import { redact } from '../lib/output/redact.js';
+import { assertConnectionActive, connectionIsVisible, resolveConnection } from '../lib/planner/connection.js';
+import { attachVocabularyDiagnosis } from '../lib/planner/diagnose.js';
+import { mapPlannerError, plannerCode } from '../lib/planner/errors.js';
+import { describeSelections } from '../lib/planner/filters.js';
+import { buildLogicalRequest } from '../lib/planner/request.js';
 import { createStore } from '../lib/store/index.js';
+// The connection_id carried by a body, whoever built it.
+function readConnectionId(body) {
+    const value = body?.connection_id;
+    return typeof value === 'string' ? value : undefined;
+}
+// Sub-second runs read as milliseconds — "0.0s" looks like a broken timer.
+function formatElapsed(ms) {
+    return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+// Row count of a planner/engine response, when it has the conventional shape.
+// undefined (not 0) when the shape is anything else — the narration then simply
+// omits the count rather than asserting a wrong one.
+function countRows(response) {
+    const rows = response?.rows;
+    return Array.isArray(rows) ? rows.length : undefined;
+}
 export default class Query extends BaseCommand {
-    static description = 'Send an OPAQUE JSON body (--body, --body-file, or piped stdin) to the Flipstream data API and print the ' +
-        'structured JSON response. The CLI never constructs, validates, or transforms the query payload — the body is ' +
-        'forwarded verbatim (your agent/Skill builds it).';
+    static description = 'Send a LOGICAL query (source + dimensions + metrics + filters) to the Flipstream query planner, which ' +
+        'resolves which physical table answers it and returns the rows. Run `flipstream catalog <source>` first — the ' +
+        'names it prints ARE what -d, -m and filter keys take. --body/--body-file/stdin still forwards a JSON body ' +
+        'verbatim for shapes the flags cannot express.';
     static examples = [
-        '<%= config.bin %> query --body \'{"opaque":true}\'',
-        'echo \'{"opaque":true}\' | <%= config.bin %> query',
-        '<%= config.bin %> query --body-file query.json --json',
+        '<%= config.bin %> catalog gsc',
+        "<%= config.bin %> query --source gsc --connection-id <id|name> -d search_date -d query -m clicks -f 'search_date=2026-01-01..2026-02-01' --rows 20",
+        '<%= config.bin %> query --source gsc --connection-id <id> -d query -m clicks --dry-run',
+        '<%= config.bin %> query --body-file request.json --json',
     ];
     static flags = {
-        'auth-host': Flags.string({
-            description: 'OAuth issuer host for credentials/refresh (defaults to the prod issuer).',
+        ...plannerFlags,
+        body: Flags.string({ description: 'Send this JSON body verbatim.', exclusive: ['body-file'] }),
+        'body-file': Flags.string({ description: 'Path to a file holding the JSON body verbatim ("-" reads stdin).' }),
+        'connection-id': Flags.string({ description: 'Connection UUID, or a name to look up.' }),
+        dimension: Flags.string({ char: 'd', description: 'Dimension name (repeatable).', multiple: true }),
+        'dry-run': Flags.boolean({ description: 'Print the request body and send nothing.' }),
+        filter: Flags.string({
+            char: 'f',
+            description: "Filter as col=a,b | col=from..to | col=<json> (repeatable). 'col=' is refused.",
+            multiple: true,
         }),
-        body: Flags.string({ description: 'Opaque JSON request body as a string.', exclusive: ['body-file'] }),
-        'body-file': Flags.string({ description: 'Path to a file holding the opaque JSON request body.' }),
+        metric: Flags.string({ char: 'm', description: 'Metric name (repeatable).', multiple: true }),
+        offset: Flags.integer({ description: 'Row offset.' }),
+        rows: Flags.integer({ description: 'Row limit (default 100).' }),
+        sort: Flags.string({ char: 's', description: 'FIELD[:asc|desc] (repeatable).', multiple: true }),
+        source: Flags.string({ description: 'The dataset discriminator, e.g. gsc.' }),
+        table: Flags.string({ description: 'Physical table — honoured only for an unmodelled source.' }),
     };
-    static summary = 'Run an opaque query against the Flipstream data API.';
+    static summary = 'Run a logical query against the Flipstream query planner.';
     async run() {
-        // --host overrides the DATA query target; --auth-host the issuer holding creds.
-        const dataHost = this.flags.host ?? DATA_HOST;
-        const authHost = resolveHost({ hostFlag: this.flags['auth-host'] });
+        const url = resolvePlannerUrl({ urlFlag: this.flags.url });
+        const authHost = resolveHost({ hostFlag: this.flags['auth-host'] ?? this.flags.host });
+        const verbatim = this.readVerbatimBody();
+        const built = verbatim === undefined
+            ? buildLogicalRequest({
+                connectionId: this.flags['connection-id'],
+                dimensions: this.flags.dimension,
+                filters: this.flags.filter,
+                metrics: this.flags.metric,
+                offset: this.flags.offset,
+                rows: this.flags.rows,
+                sort: this.flags.sort,
+                source: this.flags.source,
+                table: this.flags.table,
+            }, this.config.bin)
+            : undefined;
+        const body = verbatim ?? built;
+        // Narrate the filter interpretation (E11-2): the selection-length predicate
+        // routes silently, so say which reading each filter got — in the encoder
+        // module's own words (filters.ts owns the predicate). Flags path only; a
+        // verbatim body is the caller's own construction.
+        if (built !== undefined)
+            for (const line of describeSelections(built.filters))
+                this.note(line);
+        // Deliberately OFFLINE, and deliberately BEFORE the credential check: it
+        // prints what you typed, so a connection NAME is left as you wrote it.
+        // Resolving it would make a dry run need a token, which defeats the point —
+        // `flipstream connections list` is the command for that.
+        if (this.flags['dry-run']) {
+            return this.respond(body, (data) => this.log(JSON.stringify(data, null, 2)));
+        }
         const store = createStore();
-        // Distinguish never-logged-in (no creds) from a later expired/refresh-rejected
-        // session (the wrapper raises session_expired on a null refresh).
         if (!store.load(authHost))
             throw AuthRequiredError.notLoggedIn();
-        const body = this.parseBody();
-        const client = createAuthedDataClient({
-            accessTokenIfFresh: (host) => store.accessTokenIfFresh(host),
-            authHost,
-            host: dataHost,
-            refresh: (host) => refresh(host, { store, timeoutMs: this.flags.timeout }),
-            timeoutMs: this.flags.timeout,
-        });
+        const admin = authedAdminClient(authHost, store, this.flags.timeout);
+        // Resolve + check the connection for BOTH paths. Name resolution is only for
+        // the flags path (a verbatim body stays verbatim), but the inactive check
+        // applies to whatever connection_id is about to be sent — otherwise --body
+        // would be a one-flag bypass of it.
+        const target = verbatim === undefined ? this.flags['connection-id'] : readConnectionId(body);
+        let connectionLabel = target === undefined || target.length === 0 ? 'unspecified' : target;
+        if (target !== undefined && target.length > 0) {
+            // The resolution note ("connection acme → uuid") is an environmental
+            // inference like any other narration: routed through note() so it is
+            // redacted, sanitized, and silent under --json/--ndjson (E11-2).
+            const resolved = await resolveConnection(admin, target, {
+                note: (message) => this.note(message),
+            });
+            assertConnectionActive(resolved);
+            if (verbatim === undefined)
+                body.connection_id = resolved.id;
+            connectionLabel = resolved.name.length > 0 ? `${resolved.name} (${resolved.id})` : resolved.id;
+        }
+        const client = authedPlannerClient({ authHost, store, timeoutMs: this.flags.timeout, url });
+        const started = Date.now();
         let response;
         try {
             response = await client.postQuery(body, { timeoutMs: this.flags.timeout });
         }
         catch (error) {
-            throw mapDataError(error);
+            const engine = await this.engineFailureDetails(error, admin, body);
+            throw await this.enrichPlannerError(mapPlannerError(error), body, { authHost, client, engine, store });
         }
-        // Redact known secret KEY NAMES (E3-4) so a token-like key echoed by the DATA
-        // host never reaches --json/NDJSON/human output.
+        const elapsedMs = Date.now() - started;
+        // Timing to STDERR — diagnostics, never part of the data (protects --json).
+        this.verboseLog(`POST ${url}/query (${elapsedMs} ms)`);
+        // Resolved-context line (E11-2): which host answered, as which connection,
+        // for which source, and how much came back — the facts an agent (or a human
+        // sanity-checking numbers) otherwise has to reconstruct from four places.
+        const source = body?.source;
+        const rows = countRows(response);
+        this.note(`planner ${url} · connection ${connectionLabel} · source ${typeof source === 'string' ? source : 'unspecified'}` +
+            `${rows === undefined ? '' : ` · ${rows} row${rows === 1 ? '' : 's'}`} in ${formatElapsed(elapsedMs)}`);
+        // Redact known secret KEY NAMES so a token-like key echoed by the planner or
+        // the engine behind it never reaches --json/NDJSON/human output.
         const safe = redact(response);
         return this.respond(safe, (data) => this.log(JSON.stringify(data, null, 2)));
     }
-    // Forward the body VERBATIM: parse-only, no schema and no field handling.
-    parseBody() {
+    // ENGINE_FAILED covers everything from a bad connection to broken SQL, and the
+    // distinguishing detail stays in the planner's log on purpose (it names tables).
+    // The most common cause by far is a connection this token cannot resolve — a
+    // question we CAN ask pulse-admin ourselves. Returns envelope DETAILS (not a
+    // stderr side effect) so the --json consumer — the one the contract is written
+    // for — sees the diagnosis too. Only speaks on a definite no; a confident
+    // wrong hint in front of a real failure is worse than none.
+    async engineFailureDetails(error, admin, body) {
+        if (!(error instanceof DataHttpError) || plannerCode(error.bodyText) !== 'ENGINE_FAILED')
+            return undefined;
+        const connectionId = readConnectionId(body);
+        if (connectionId === undefined || connectionId.length === 0)
+            return undefined;
+        if ((await connectionIsVisible(admin, connectionId)) !== false)
+            return undefined;
+        return {
+            hint: 'Your token cannot see this connection — pulse-data resolves it through pulse-admin as you, ' +
+                'and gets nothing. Pick one your token can reach.',
+            next: [`${this.config.bin} connections list --json`],
+            retryable: false,
+        };
+    }
+    // Post-map enrichment (E11-1): attach the remediation only a command with the
+    // full request in hand can know. The mapper stays generic; this layer knows the
+    // source that was queried and the token that was used.
+    async enrichPlannerError(error, body, context) {
+        if (context.engine !== undefined)
+            error.withDetails(context.engine);
+        // An UNKNOWN_* vocabulary rejection: diagnose against the catalog FIRST
+        // (specific hint + runnable next — lib/planner/diagnose.ts), then fill any
+        // remaining gap with generic remediation, never displacing the diagnosis.
+        if (error.details.upstreamCode?.startsWith('UNKNOWN_')) {
+            // Diagnosis never triggers a token refresh: an error-path bonus fetch
+            // must not be able to mutate persistent auth state (review, #110).
+            if (context.store.accessTokenIfFresh(context.authHost) === null) {
+                this.verboseLog('vocabulary diagnosis skipped: no fresh access token (diagnosis never refreshes)');
+            }
+            else {
+                await attachVocabularyDiagnosis(error, {
+                    bin: this.config.bin,
+                    body,
+                    // A bonus fetch gets a bonus-sized budget — a hanging catalog must
+                    // not double the time-to-error of a fast deterministic 400.
+                    fetchCatalog: (catalogSource) => context.client.getCatalog(catalogSource, { timeoutMs: Math.min(this.flags.timeout ?? 30_000, 5000) }),
+                    onSkip: (reason) => this.verboseLog(`vocabulary diagnosis skipped: ${reason}`),
+                });
+            }
+            // Gap-filling generic remediation. The interpolated source comes from
+            // the request body (caller-supplied JSON under --body/stdin) and `next`
+            // strings are commands the contract tells an agent to RUN: only a
+            // catalog-key-shaped name is embedded, and never for UNKNOWN_SOURCE —
+            // that would suggest the very name the planner just rejected.
+            const source = body?.source;
+            const sourceName = typeof source === 'string' && /^[\w.-]{1,64}$/.test(source) ? source : undefined;
+            if (error.details.next === undefined) {
+                const useSource = error.details.upstreamCode !== 'UNKNOWN_SOURCE' && sourceName !== undefined;
+                error.withDetails({ next: [`${this.config.bin} catalog${useSource ? ` ${sourceName}` : ''}`] });
+            }
+            if (error.details.hint === undefined) {
+                error.withDetails({
+                    hint: 'Names for -d, -m and filter keys must come from the catalog — no aliases, no guessing.',
+                });
+            }
+            error.withDetails({ retryable: false });
+        }
+        // A 403 two services away is near-undebuggable without knowing what the token
+        // actually carried. Scopes/roles are display-only claims (never used to gate
+        // anything client-side) and are not secrets; both lists are bounded so a
+        // token from a hostile --auth-host issuer cannot balloon the envelope.
+        if (error.code === 'role_forbidden') {
+            const claims = tokenClaims(context.authHost, context.store) ?? {};
+            const roles = (Array.isArray(claims.roles) ? claims.roles.filter((r) => typeof r === 'string') : [])
+                .slice(0, 20)
+                .map((role) => role.slice(0, 64));
+            const scopes = (context.store.load(context.authHost)?.scopes ?? [])
+                .slice(0, 20)
+                .map((scope) => scope.slice(0, 64));
+            error.withDetails({
+                hint: `Your token carries scopes [${scopes.join(' ')}] and roles [${roles.join(' ')}]. ` +
+                    'The planner admits a caller with ANY allowed role OR all required scopes ' +
+                    '(grid_data:read + connections:read) — re-login if these look stale.',
+                next: [`${this.config.bin} auth status`, `${this.config.bin} auth login`],
+                retryable: false,
+            });
+        }
+        return error;
+    }
+    // A verbatim body short-circuits the whole builder. Returns undefined when the
+    // flags path should be used instead.
+    readVerbatimBody() {
+        const file = this.flags['body-file'];
         let raw;
-        if (this.flags.body !== undefined)
+        let label;
+        if (this.flags.body !== undefined) {
             raw = this.flags.body;
-        else if (this.flags['body-file'] !== undefined)
-            raw = readFileSync(this.flags['body-file'], 'utf8');
-        else if (process.stdin.isTTY)
-            throw new UsageError('Provide a body via --body, --body-file <path>, or piped stdin.');
-        else
+            label = '--body';
+        }
+        else if (file !== undefined) {
+            raw = file === '-' ? readFileSync(0, 'utf8') : readFileSync(file, 'utf8');
+            label = file === '-' ? 'stdin (--body-file -)' : `--body-file ${file}`;
+        }
+        else if (this.flags.source === undefined && this.flags['connection-id'] === undefined && !process.stdin.isTTY) {
+            // Piped stdin with no flags: the pre-E8 invocation, still supported. This
+            // is an INFERENCE — a spawned process has non-TTY stdin by default — so
+            // it is announced, never silent (E11-2), and an empty read means "no
+            // request was given at all", not "bad JSON" (E11-1).
+            this.note('reading the request body from stdin (no query flags given and stdin is piped)');
             raw = readFileSync(0, 'utf8');
+            label = 'stdin';
+            if (raw.trim() === '') {
+                // Empty stdin + builder flags (-d/-m/-f/...) means the caller wanted
+                // the FLAGS path: fall through to the builder, whose missing_source_*
+                // errors name exactly what is absent — never claim "no flags" when
+                // flags were passed (#100's own rule).
+                const builderFlagGiven = this.flags.dimension !== undefined ||
+                    this.flags.metric !== undefined ||
+                    this.flags.filter !== undefined ||
+                    this.flags.sort !== undefined ||
+                    this.flags.rows !== undefined ||
+                    this.flags.offset !== undefined ||
+                    this.flags.table !== undefined;
+                if (builderFlagGiven)
+                    return undefined;
+                throw new UsageError('No request given: no --source/--connection-id flags, and stdin was empty.', 'missing_request').withDetails({
+                    docs: 'docs/AGENT-CONTRACT.md#the-query-request-shape-logicalrequest',
+                    hint: 'Build the query from flags (--source, --connection-id, -d, -m), or pipe a JSON body on stdin.',
+                    next: [`${this.config.bin} catalog`, `${this.config.bin} connections list --json`],
+                    retryable: false,
+                });
+            }
+        }
+        else
+            return undefined;
         try {
             return JSON.parse(raw);
         }
         catch {
-            throw new UsageError('Request body is not valid JSON.');
+            // Name where the body came from — under the stdin inference the caller may
+            // not even realise a body was being read.
+            throw new UsageError(`Request body from ${label} is not valid JSON.`, 'invalid_body_json').withDetails({
+                hint: 'The body must be one JSON object in LogicalRequest shape; flags build it for you.',
+                next: [`${this.config.bin} query --source <source> --connection-id <id> -d <dim> -m <metric> --dry-run`],
+                retryable: false,
+            });
         }
     }
 }

package/dist/commands/skills/install.d.ts

@@ -0,0 +1,16 @@
+import { BaseCommand } from '../../lib/command/base.js';
+export default class SkillsInstall extends BaseCommand<typeof SkillsInstall> {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        agent: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        yes: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    static summary: string;
+    run(): Promise<{
+        installed: Array<{
+            agent: string;
+            path: string;
+        }>;
+    }>;
+}

package/dist/commands/skills/install.js

@@ -0,0 +1,55 @@
+import { Flags } from '@oclif/core';
+import { BaseCommand } from '../../lib/command/base.js';
+import { confirm } from '../../lib/output/dialogs.js';
+import { isCI } from '../../lib/output/interactivity.js';
+import { installSkill, resolveTargets, SUPPORTED_AGENTS } from '../../lib/skills/install.js';
+export default class SkillsInstall extends BaseCommand {
+    static description = 'Install the flipstream skill (SKILL.md) into the global skills directory of every detected AI coding agent ' +
+        '(Claude Code, Codex, Cursor, OpenCode). Detection is local env/dir inspection only — nothing is reported ' +
+        'anywhere. The skill teaches an agent to retrieve the command surface and data vocabulary from the CLI ' +
+        'instead of guessing.';
+    static examples = [
+        '<%= config.bin %> skills install',
+        '<%= config.bin %> skills install --yes',
+        '<%= config.bin %> skills install --agent claude-code --agent codex',
+    ];
+    static flags = {
+        agent: Flags.string({
+            description: `Install for this agent id only (repeatable). Known: ${SUPPORTED_AGENTS.map((a) => a.id).join(', ')}.`,
+            multiple: true,
+            options: SUPPORTED_AGENTS.map((a) => a.id),
+        }),
+        yes: Flags.boolean({ char: 'y', default: false, description: 'Install without asking.' }),
+    };
+    static summary = 'Install the flipstream skill for detected AI coding agents.';
+    async run() {
+        // CI never installs skills: the runner's home is ephemeral and nobody asked.
+        if (isCI()) {
+            // Diagnostics, not data — stderr, per the catalog-footer precedent.
+            return this.respond({ installed: [] }, () => process.stderr.write('CI environment detected — skipping skill install.\n'));
+        }
+        const targets = resolveTargets({ explicit: this.flags.agent });
+        if (targets.length === 0) {
+            return this.respond({ installed: [] }, () => process.stderr.write('No supported agents detected (looked for a driving agent and for ' +
+                `${SUPPORTED_AGENTS.map((a) => a.id).join(', ')} home directories).\n`));
+        }
+        // Running `skills install` already states intent, so the non-interactive
+        // fallback is yes (announced) — --yes exists to skip the question entirely.
+        const proceed = this.flags.yes ||
+            (await confirm(`Install the flipstream skill for: ${targets.map((t) => t.name).join(', ')}?`, {
+                defaultValue: true,
+                fallbackValue: true,
+                unblockFlag: '--yes',
+            }));
+        if (!proceed) {
+            return this.respond({ installed: [] }, () => process.stderr.write('Skipped.\n'));
+        }
+        const result = installSkill(targets);
+        return this.respond(result, () => {
+            for (const entry of result.installed) {
+                const backup = entry.backup === undefined ? '' : ` (previous copy preserved at ${entry.backup})`;
+                this.log(`${entry.status} ${entry.agent}: ${entry.path}${backup}`);
+            }
+        });
+    }
+}

package/dist/commands/workspaces/connections.js

@@ -1,5 +1,6 @@
 import { Args } from '@oclif/core';
-import { fetchConnections, resolveWorkspaceNames } from '../../lib/api/connections.js';
+import { fetchConnections } from '../../lib/api/connections.js';
+import { hydrate, WORKSPACE_NAME } from '../../lib/api/hydrate.js';
 import { assertUuid } from '../../lib/api/ids.js';
 import { authedAdminClient, renderConnectionsTable } from '../../lib/command/admin.js';
 import { BaseCommand } from '../../lib/command/base.js';
@@ -9,7 +10,7 @@ import { createStore } from '../../lib/store/index.js';
 export default class WorkspacesConnections extends BaseCommand {
     static aliases = ['ws:connections'];
     static args = {
-        id: Args.string({ description: 'Workspace id (UUID).', required: true }),
+        id: Args.string({ description: 'Workspace id (UUID).', ignoreStdin: true, required: true }),
     };
     static description = "List one workspace's connections — the ergonomic form of `connections list --workspace <id>`. " +
         'Targets the OAuth/admin host.';
@@ -27,6 +28,7 @@ export default class WorkspacesConnections extends BaseCommand {
         if (!store.load(host))
             throw AuthRequiredError.notLoggedIn();
         const client = authedAdminClient(host, store, this.flags.timeout);
+        const startedMs = Date.now();
         const projected = await fetchConnections(client, {
             all: this.flags.all,
             limit: this.flags.limit,
@@ -35,7 +37,8 @@ export default class WorkspacesConnections extends BaseCommand {
             sort: this.flags.sort,
             workspace: this.args.id,
         });
-        await resolveWorkspaceNames(client, projected.records);
+        await hydrate(client, projected.records, [WORKSPACE_NAME]);
+        this.verboseLog(`GET ${host}/connections (${Date.now() - startedMs} ms)`);
         return this.respondList(projected, (records) => renderConnectionsTable(records));
     }
 }

package/dist/commands/workspaces/get.js

@@ -11,10 +11,10 @@ import { createStore } from '../../lib/store/index.js';
 export default class WorkspacesGet extends BaseCommand {
     static aliases = ['ws:get'];
     static args = {
-        id: Args.string({ description: 'Workspace id (UUID).', required: true }),
+        id: Args.string({ description: 'Workspace id (UUID).', ignoreStdin: true, required: true }),
     };
     static description = 'Fetch one workspace by id (the admin API "Client"). A foreign or missing id collapses to a single ' +
-        "not-found message (no existence leak). Targets the OAuth/admin host.";
+        'not-found message (no existence leak). Targets the OAuth/admin host.';
     static examples = [
         '<%= config.bin %> workspaces get <id>',
         '<%= config.bin %> ws get <id> --json',
@@ -42,7 +42,9 @@ export default class WorkspacesGet extends BaseCommand {
         });
         let raw;
         try {
+            const startedMs = Date.now();
             raw = await client.get(`/clients/${this.args.id}`, { query: { refresh: this.flags.refresh || undefined } });
+            this.verboseLog(`GET ${host}/clients/${this.args.id} (${Date.now() - startedMs} ms)`);
         }
         catch (error) {
             // Collapse a foreign-id 403 and a 404 to ONE message so neither leaks existence.

package/dist/commands/workspaces/list.js

@@ -53,7 +53,10 @@ export default class WorkspacesList extends BaseCommand {
             }
         };
         const start = { limit: this.flags.limit, offset: this.flags.offset };
+        const startedMs = Date.now();
         const envelope = this.flags.all ? await drainPages(fetchPage, start) : await fetchPage(start);
+        // Which origin answered (E11-2): planner vs admin is the first debugging question.
+        this.verboseLog(`GET ${host}/clients (${Date.now() - startedMs} ms)`);
         const projected = { count: envelope.count, records: envelope.records.map((record) => projectWorkspace(record)) };
         if (this.flags['with-connection-counts'])
             await this.addConnectionCounts(client, projected.records);

package/dist/lib/api/admin-client.d.ts

@@ -3,8 +3,13 @@ export interface AdminGetOptions {
     query?: Record<string, boolean | number | string | undefined>;
     timeoutMs?: number;
 }
+export interface AdminPostOptions {
+    body?: unknown;
+    timeoutMs?: number;
+}
 export interface AdminClient {
     get(path: string, options?: AdminGetOptions): Promise<unknown>;
+    post(path: string, options?: AdminPostOptions): Promise<unknown>;
 }
 export interface AdminClientOptions {
     getToken: () => null | Promise<null | string> | string;

package/dist/lib/api/admin-client.js

@@ -22,6 +22,16 @@ export function createAdminClient(options) {
                 url: `${base}${path}`,
             });
         },
+        async post(path, postOptions = {}) {
+            const token = await options.getToken();
+            return requestJson({
+                body: postOptions.body,
+                method: 'POST',
+                timeoutMs: postOptions.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}${path}`,
+            });
+        },
     };
 }
 // The authed admin client: the SAME withFreshToken 401->refresh->retry-once
@@ -40,5 +50,14 @@ export function createAuthedAdminClient(deps) {
                 url: `${base}${path}`,
             }));
         },
+        post(path, postOptions = {}) {
+            return withFreshToken(deps, (token) => requestJson({
+                body: postOptions.body,
+                method: 'POST',
+                timeoutMs: postOptions.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}${path}`,
+            }));
+        },
     };
 }

package/dist/lib/api/connections.d.ts

@@ -11,4 +11,3 @@ export declare function fetchConnections(client: AdminClient, query: Connections
     count: number;
     records: Array<Record<string, unknown>>;
 }>;
-export declare function resolveWorkspaceNames(client: AdminClient, records: Array<Record<string, unknown>>): Promise<void>;

package/dist/lib/api/connections.js

@@ -17,28 +17,3 @@ export async function fetchConnections(client, query) {
     const envelope = query.all ? await drainPages(fetchPage, start) : await fetchPage(start);
     return { count: envelope.count, records: envelope.records.map((record) => projectConnection(record)) };
 }
-// Fill `client_name` for connections that lack it (the API didn't nest the
-// client): one drained workspace lookup, keyed by id. Skipped when all already
-// have it; best-effort (leaves names unresolved rather than failing the list).
-export async function resolveWorkspaceNames(client, records) {
-    const missing = records.some((record) => record.client_name === undefined && record.client_id !== undefined);
-    if (!missing)
-        return;
-    const names = new Map();
-    try {
-        const workspaces = await drainPages(async (page) => normalizeList(await client.get('/clients', { query: { limit: page.limit, offset: page.offset } })), { limit: 100, offset: 0 });
-        for (const workspace of workspaces.records) {
-            const ws = workspace;
-            if (ws.id)
-                names.set(ws.id, ws.name ?? '');
-        }
-    }
-    catch {
-        return;
-    }
-    for (const record of records) {
-        if (record.client_name === undefined && typeof record.client_id === 'string') {
-            record.client_name = names.get(record.client_id) ?? null;
-        }
-    }
-}

package/dist/lib/api/errors.d.ts

@@ -4,4 +4,5 @@ export declare function parseDataErrorMessage(status: number, bodyText: string):
     message: string;
 };
 export declare function notFoundError(): CliError;
+export declare function rateLimited(message: string, retryAfterMs?: number): CliError;
 export declare function mapDataError(error: unknown): CliError;

package/dist/lib/api/errors.js

@@ -1,4 +1,4 @@
-import { AuthFailedError, CliError, DataHttpError, NetworkError } from '../errors.js';
+import { AuthFailedError, CliError, DataHttpError, NetworkError, retryPolicy } from '../errors.js';
 import { ExitCode } from '../exit-codes.js';
 import { redact } from '../output/redact.js';
 const DETAIL_MAX = 500;
@@ -33,6 +33,15 @@ export function parseDataErrorMessage(status, bodyText) {
 export function notFoundError() {
     return new CliError('Resource not found or not in your organization.', 'not_found', ExitCode.GENERIC);
 }
+// The one 429 mapping, shared by the generic and planner mappers so the two
+// can never drift: code `rate_limited`, exit 7 (transient), retry policy with
+// the server-stated wait when one was sent.
+export function rateLimited(message, retryAfterMs) {
+    return new CliError(message, 'rate_limited', ExitCode.NETWORK).withDetails({
+        hint: 'Wait, then re-run the same command.',
+        ...retryPolicy(retryAfterMs),
+    });
+}
 // Map a DataClient/retry failure onto the E3 error model with a deterministic exit
 // code (AuthRequired->4, AuthFailed->5, Network->7, Timeout->8). Network, Timeout
 // and AuthRequired (session_expired) pass through unchanged; a DataHttpError is
@@ -54,8 +63,10 @@ export function mapDataError(error) {
         }
         if (error.status === 404)
             return notFoundError();
+        if (error.status === 429)
+            return rateLimited('Rate limited by the service.', error.retryAfterMs);
         if (error.status >= 500) {
-            return new NetworkError(message, 'data_upstream_error');
+            return new NetworkError(message, 'data_upstream_error').withDetails(retryPolicy(error.retryAfterMs));
         }
         return new CliError(message, providerError ?? 'data_request_failed', ExitCode.GENERIC);
     }

package/dist/lib/api/http.d.ts

@@ -6,4 +6,6 @@ export interface JsonRequest {
     token?: null | string;
     url: string;
 }
+export declare const MAX_RETRY_AFTER_MS = 3600000;
+export declare function parseRetryAfterMs(header: null | string): number | undefined;
 export declare function requestJson(req: JsonRequest): Promise<unknown>;