flipstream 0.5.0 → 0.6.1

package/dist/commands/workspaces/connections.js

@@ -10,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.';
@@ -25,9 +25,10 @@ export default class WorkspacesConnections extends BaseCommand {
         assertUuid(this.args.id, 'workspace id'); // exit 2, no request
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await 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,
@@ -37,6 +38,7 @@ export default class WorkspacesConnections extends BaseCommand {
             workspace: this.args.id,
         });
         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',
@@ -31,7 +31,7 @@ export default class WorkspacesGet extends BaseCommand {
         assertUuid(this.args.id, 'workspace id'); // exit 2, no request issued
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = createAuthedAdminClient({
             accessTokenIfFresh: (authHost) => store.accessTokenIfFresh(authHost),
@@ -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

@@ -32,7 +32,7 @@ export default class WorkspacesList extends BaseCommand {
         // The admin host == the OAuth issuer (creds live here); --host overrides both.
         const host = this.resolvedHost();
         const store = createStore();
-        if (!store.load(host))
+        if (!(await store.load(host)))
             throw AuthRequiredError.notLoggedIn();
         const client = createAuthedAdminClient({
             accessTokenIfFresh: (authHost) => store.accessTokenIfFresh(authHost),
@@ -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/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>;

package/dist/lib/api/http.js

@@ -1,5 +1,29 @@
 import { DataHttpError, NetworkError, TimeoutError } from '../errors.js';
+import { traceFailure, traceRequest, traceResponse } from '../output/trace.js';
 const DEFAULT_TIMEOUT_MS = 30_000;
+// Ceiling for a server-stated retry wait. A hostile or misconfigured header
+// must never park an agent for hours ("Retry-After: 999999999" is ~31 years);
+// anything above this clamps down, and the contract documents the bound.
+export const MAX_RETRY_AFTER_MS = 3_600_000;
+// Retry-After is either delta-seconds (1*DIGIT — parsed strictly, so no hex,
+// exponents, fractions or signs) or an HTTP-date (RFC 9110 §10.2.3). Returns
+// milliseconds clamped to [0, MAX_RETRY_AFTER_MS], or undefined when
+// absent/unparseable — never a guess, because a wrong wait is worse than none.
+export function parseRetryAfterMs(header) {
+    if (header === null)
+        return undefined;
+    const trimmed = header.trim();
+    if (/^\d{1,10}$/.test(trimmed))
+        return Math.min(MAX_RETRY_AFTER_MS, Number(trimmed) * 1000);
+    // An HTTP-date always carries letters (day/month names, GMT); refusing the
+    // rest keeps Date.parse's lenient number handling ('1.5', '0x10') out.
+    if (!/[A-Za-z]/.test(trimmed))
+        return undefined;
+    const dateMs = Date.parse(trimmed);
+    if (Number.isNaN(dateMs))
+        return undefined;
+    return Math.min(MAX_RETRY_AFTER_MS, Math.max(0, dateMs - Date.now()));
+}
 function withQuery(url, query) {
     if (!query)
         return url;
@@ -24,11 +48,18 @@ export async function requestJson(req) {
         headers['content-type'] = 'application/json';
     if (req.token)
         headers.authorization = `Bearer ${req.token}`;
+    // Wire tracing (E11-6): emitted AS IT HAPPENS, so the failure path carries
+    // diagnostics too (#92) — headers are never traced, bodies only via the
+    // explicit sanitize escape hatch. Only first-party API calls route through
+    // here; the token-bearing OAuth flows use fetch() directly (lint-enforced).
+    const fullUrl = withQuery(req.url, req.query);
+    const started = Date.now();
+    traceRequest(req.method, fullUrl, req.body);
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), timeoutMs);
     let response;
     try {
-        response = await fetch(withQuery(req.url, req.query), {
+        response = await fetch(fullUrl, {
             body: req.body === undefined ? undefined : JSON.stringify(req.body),
             headers,
             method: req.method,
@@ -36,16 +67,21 @@ export async function requestJson(req) {
         });
     }
     catch (error) {
-        if (controller.signal.aborted)
+        if (controller.signal.aborted) {
+            traceFailure(req.method, fullUrl, `timeout after ${timeoutMs}ms`, Date.now() - started);
             throw new TimeoutError(`Request timed out after ${timeoutMs}ms`);
+        }
+        traceFailure(req.method, fullUrl, error.message, Date.now() - started);
         throw new NetworkError(`Request failed: ${error.message}`);
     }
     finally {
         clearTimeout(timer);
     }
     const text = await response.text();
-    if (response.status < 200 || response.status >= 300)
-        throw new DataHttpError(response.status, text);
+    traceResponse({ bodyText: text, method: req.method, ms: Date.now() - started, status: response.status, url: fullUrl });
+    if (response.status < 200 || response.status >= 300) {
+        throw new DataHttpError(response.status, text, parseRetryAfterMs(response.headers.get('retry-after')));
+    }
     try {
         return JSON.parse(text);
     }

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

@@ -1 +1,2 @@
 export declare function assertUuid(id: string, label?: string): void;
+export declare function isUuid(value: string): boolean;

package/dist/lib/api/ids.js

@@ -6,3 +6,8 @@ export function assertUuid(id, label = 'id') {
     if (!UUID_RE.test(id))
         throw new UsageError(`Invalid ${label} — expected a UUID.`);
 }
+// Is this already a UUID? Used where a flag accepts EITHER a UUID or a name, so
+// only the non-UUID case pays for a lookup.
+export function isUuid(value) {
+    return UUID_RE.test(value);
+}

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

@@ -1,6 +1,6 @@
 import { type DataClient } from './client.js';
 export interface RefreshDeps {
-    accessTokenIfFresh: (authHost: string) => null | string;
+    accessTokenIfFresh: (authHost: string) => Promise<null | string>;
     authHost: string;
     refresh: (authHost: string) => Promise<null | string>;
 }

package/dist/lib/api/retry.js

@@ -8,7 +8,7 @@ import { requestJson } from './http.js';
 // session_expired (exit 4). Non-401 errors (403/5xx/network/timeout) are never
 // retried; a second consecutive 401 propagates. Refresh always targets authHost.
 export async function withFreshToken(deps, fn) {
-    let token = deps.accessTokenIfFresh(deps.authHost) ?? (await deps.refresh(deps.authHost));
+    let token = (await deps.accessTokenIfFresh(deps.authHost)) ?? (await deps.refresh(deps.authHost));
     if (!token)
         throw AuthRequiredError.sessionExpired();
     try {

package/dist/lib/api/short-uuid.d.ts

@@ -0,0 +1 @@
+export declare function uuidToShort(uuid: string): string;

package/dist/lib/api/short-uuid.js

@@ -0,0 +1,30 @@
+// UUID → the 22-character short id pulse-fe puts in its URLs.
+//
+// A port of `short-uuid`'s default translator (flickrBase58), which is what
+// front_end/src/utils/routing/urlEncoding.ts uses (`uuidToShort`). Ported rather
+// than depended on: this is a fixed alphabet and one bignum conversion, and a
+// new runtime dependency on a CLI that ships five is a worse trade than 20 lines
+// with a locked-down test.
+//
+// The correctness risk here is specific and quiet: a wrong encoding does not
+// throw, it produces a plausible-looking URL that 404s. So the test carries a
+// vector captured from a REAL pulse-fe URL, not one this code generated.
+//
+// flickrBase58 omits 0/O/I/l — the characters people misread when copying a link
+// out of a terminal, which is the whole reason the alphabet exists.
+const ALPHABET = '123456789abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ';
+const SHORT_LENGTH = 22;
+// Left-padded to a fixed 22 chars, matching short-uuid: without the pad, a UUID
+// with leading zero bytes encodes shorter and the route stops resolving.
+export function uuidToShort(uuid) {
+    const hex = uuid.replaceAll('-', '');
+    let value = BigInt(`0x${hex}`);
+    const base = BigInt(ALPHABET.length);
+    let out = '';
+    while (value > 0n) {
+        const digit = Number(value % base);
+        out = `${ALPHABET[digit] ?? ''}${out}`;
+        value /= base;
+    }
+    return out.padStart(SHORT_LENGTH, ALPHABET[0] ?? '1');
+}

package/dist/lib/auth/claims.d.ts

@@ -1,3 +1,3 @@
 import type { TokenStore } from '../store/index.js';
 export declare function decodeJwtClaimsUnverified(accessToken: string): null | Record<string, unknown>;
-export declare function tokenClaims(host: string, store: TokenStore): null | Record<string, unknown>;
+export declare function tokenClaims(host: string, store: TokenStore): Promise<null | Record<string, unknown>>;

package/dist/lib/auth/claims.js

@@ -14,7 +14,7 @@ export function decodeJwtClaimsUnverified(accessToken) {
     }
 }
 // Decoded claims of the stored access token for `host` (display only), or null.
-export function tokenClaims(host, store) {
-    const creds = store.load(host);
+export async function tokenClaims(host, store) {
+    const creds = await store.load(host);
     return creds ? decodeJwtClaimsUnverified(creds.accessToken) : null;
 }

package/dist/lib/auth/flow.js

@@ -8,7 +8,14 @@ import { DEFAULT_REDIRECT_TIMEOUT_MS, startLoopback } from './loopback.js';
 import { generatePair } from './pkce.js';
 import { buildAuthorizeUrl } from './provider.js';
 export { decodeJwtClaimsUnverified } from './claims.js';
-const DEFAULT_SCOPES = ['read', 'write'];
+// The whole forwarding chain, not just the first hop (E8-0). The query planner
+// presents this token to pulse-data (grid_data:read), and pulse-data presents it
+// onward to pulse-admin to resolve the connection (connections:read). A caller
+// holding only the first gets a 403 raised two services away and wrapped as an
+// opaque PULSE_SERVICE_ERROR, which says nothing about what to fix.
+//
+// `read`/`write` stay for the admin API (workspaces, connections, log).
+const DEFAULT_SCOPES = ['read', 'write', 'grid_data:read', 'connections:read'];
 function tokenErrorMessage(status, body) {
     try {
         const parsed = JSON.parse(body);
@@ -101,7 +108,8 @@ export async function login(options = {}) {
             const pasted = await (options.promptRedirect ?? defaultPromptRedirect)(authorizeUrl);
             if (!pasted || !pasted.trim()) {
                 throw new AuthFailedError('No redirected URL was provided. Browser login is not possible in a non-interactive ' +
-                    'environment; use a service-account / client_credentials flow instead (PLANNED).', 'headless_no_input');
+                    'environment; over SSH or any other remote access, use a Flipstream service account ' +
+                    '(client_credentials) from your Flipstream account instead — it needs no browser.', 'headless_no_input');
             }
             return parseRedirect(pasted, state).code;
         };

package/dist/lib/auth/headless.js

@@ -1,5 +1,5 @@
-import { createInterface } from 'node:readline';
 import { LoopbackError } from '../errors.js';
+import { readAnswer } from '../output/dialogs.js';
 // True when there is no interactive browser to drive the OAuth redirect: an
 // explicit open() failure, a CI run, an SSH session, or Linux without a display.
 export function detectHeadless(probe = {}) {
@@ -44,18 +44,22 @@ export function parseRedirect(pasted, expectedState) {
     return { code, state };
 }
 // Default manual-mode reader: print the authorize URL + instructions to STDERR
-// (stdout stays clean for the eventual JSON) and read the pasted redirect from stdin.
-export function defaultPromptRedirect(authorizeUrl) {
+// (stdout stays clean for the eventual JSON) and read the pasted redirect from
+// stdin — through dialogs.readAnswer, the ONE prompt chokepoint, so EOF and
+// Ctrl-C settle (prompt_aborted) instead of leaving an unresolved promise
+// (E11-4 review: this file used to carry a second, unhardened readline).
+export async function defaultPromptRedirect(authorizeUrl) {
     process.stderr.write('\nNo browser is available here (headless / SSH / CI).\n' +
         'Open this URL in a browser on any machine and approve access:\n\n' +
         `  ${authorizeUrl}\n\n` +
         'Your browser will then try to load a http://127.0.0.1/... address that fails to\n' +
         'connect. Copy that full URL from the address bar and paste it below.\n\n');
-    const rl = createInterface({ input: process.stdin, output: process.stderr });
-    return new Promise((resolve) => {
-        rl.question('Paste the redirected URL here: ', (answer) => {
-            rl.close();
-            resolve(answer);
-        });
-    });
+    try {
+        return await readAnswer('Paste the redirected URL here: ');
+    }
+    catch {
+        // Aborted/EOF: the flow's own empty-input handling produces the right
+        // headless_no_input error with its auth exit code.
+        return '';
+    }
 }

package/dist/lib/auth/refresh.js

@@ -1,3 +1,4 @@
+import { freshAccessToken } from '../store/credentials.js';
 import { createStore } from '../store/index.js';
 import { fetchMetadata } from './discovery.js';
 // Silent refresh via the refresh_token grant. Returns the new access token, or
@@ -10,7 +11,7 @@ import { fetchMetadata } from './discovery.js';
 export async function refresh(host, options = {}) {
     const store = options.store ?? createStore();
     const timeoutMs = options.timeoutMs ?? 10_000;
-    const creds = store.load(host);
+    const creds = await store.load(host);
     if (!creds || !creds.refreshToken)
         return null;
     let tokenEndpoint;
@@ -43,7 +44,36 @@ export async function refresh(host, options = {}) {
         clearTimeout(timer);
     }
     if (response.status >= 400 && response.status < 500) {
-        store.clear(host); // invalid_grant / revoked session — force re-login.
+        // COMPARE-AND-DELETE. A 4xx here usually means invalid_grant, and with refresh-
+        // token rotation the most likely reason is that ANOTHER process already
+        // refreshed: it exchanged this same token, got a new one, and saved it. Our
+        // token is dead — but the one now in the keychain is not, and clearing blindly
+        // would delete a working session and log the user out for no reason.
+        //
+        // Re-read past any cache. If somebody else's token is there now, their
+        // session is live: HAND OFF to it rather than reporting failure, because
+        // returning null would surface as "Session expired. Run `flipstream auth
+        // login`" while perfectly good credentials sit in the keychain.
+        const current = await store.reload(host);
+        if (current !== null && current.refreshToken !== creds.refreshToken) {
+            // May still be null if their access token is also stale; either way we do
+            // not touch a session we do not own.
+            return freshAccessToken(current);
+        }
+        // AND WE DO NOT DELETE, even though this token looks dead to us.
+        //
+        // The check above cannot be made atomic. Every store operation is its own
+        // child process now (~125ms), so between that reload and any delete there is
+        // a wide window in which the process that DID win the rotation completes its
+        // save — and we would then erase credentials that had just become valid. One
+        // command would return a token while every later command looked logged out.
+        //
+        // The two mistakes are not the same size. Deleting wrongly destroys a live
+        // session silently. Keeping a genuinely dead token costs one more failed
+        // refresh, which returns null here, surfaces as session_expired, and is
+        // overwritten by the next login anyway. Given a race we cannot close without
+        // a cross-process lock that every save would also have to respect, the
+        // cheaper mistake is the right default.
         return null;
     }
     if (!response.ok)
@@ -64,6 +94,6 @@ export async function refresh(host, options = {}) {
         // Rotate the refresh token ONLY when the server issued a new one.
         refreshToken: token.refresh_token ?? creds.refreshToken,
     };
-    store.save(host, updated);
+    await store.save(host, updated);
     return token.access_token;
 }

package/dist/lib/auth/session.js

@@ -6,7 +6,7 @@ import { refresh } from './refresh.js';
 // client (E4) uses to obtain a bearer token.
 export async function getFreshAccessToken(host, options = {}) {
     const store = options.store ?? createStore();
-    const cached = store.accessTokenIfFresh(host);
+    const cached = await store.accessTokenIfFresh(host);
     if (cached)
         return cached;
     return refresh(host, { store, timeoutMs: options.timeoutMs });

package/dist/lib/command/base.d.ts

@@ -11,10 +11,14 @@ export declare abstract class BaseCommand<T extends typeof Command> extends Comm
     static enableJsonFlag: boolean;
     protected args: BaseArgs<T>;
     protected flags: BaseFlags<T>;
+    private startedAtMs;
     protected catch(error: Error & {
         exitCode?: number;
     }): Promise<never>;
+    protected finally(error: Error | undefined): Promise<void>;
+    protected footer(text: string): void;
     init(): Promise<void>;
+    protected note(message: string): void;
     protected resolvedHost(): string;
     protected respond<D>(data: D, human: (data: D) => void): D;
     protected respondList<R>(envelope: {

package/dist/lib/command/base.js

@@ -1,8 +1,18 @@
 import { Command, Flags } from '@oclif/core';
+import { CONTRACT_VERSION } from '../config/constants.js';
 import { resolveHost } from '../config/xdg.js';
-import { renderError, UsageError } from '../errors.js';
+import { classifyError, renderError, UsageError } from '../errors.js';
+import { setMachineMode } from '../output/machine-mode.js';
 import { renderNdjson } from '../output/ndjson.js';
 import { redact } from '../output/redact.js';
+import { appendRunLog, currentRunLogPath } from '../output/runlog.js';
+import { sanitizeTerminal } from '../output/sanitize.js';
+import { writeOutputEntry } from '../output/sidecar.js';
+import { enableStderrTrace } from '../output/trace.js';
+// Cap on any single argv element / message written to a persistent file, so a
+// huge --body can neither balloon the log nor tear an NDJSON line under
+// concurrent O_APPEND (E11-6 review).
+const DISK_FIELD_MAX = 2000;
 // Repo-wide clig.dev conventions in one place (E3-5). Every command extends this:
 //   - stdout = data, stderr = help/prompts/progress/diagnostics
 //   - --json (machine JSON, oclif-serialized) / --ndjson (one object per line),
@@ -19,11 +29,65 @@ export class BaseCommand extends Command {
     static enableJsonFlag = true;
     args;
     flags;
+    // Command start, for the sidecar's duration_ms.
+    startedAtMs = 0;
     // Centralized error rendering: redacted, machine {error:{code,message}} under
     // --json/--ndjson, a human line otherwise. Replaces oclif's default reporter.
     async catch(error) {
         const machine = this.jsonEnabled() || Boolean(this.flags?.ndjson);
-        this.exit(renderError(error, { json: machine }));
+        // Sidecar + run log see every failure (E11-6): structured for the
+        // supervising process, one line for the post-mortem trail. Message is
+        // redacted and capped so it can't tear a shared NDJSON line.
+        const classified = classifyError(error);
+        const message = redact(classified.message).slice(0, DISK_FIELD_MAX);
+        appendRunLog(`command-failed ${this.id ?? ''}: [${classified.code}] ${message}`);
+        writeOutputEntry({
+            command: this.id ?? '',
+            error_code: classified.code,
+            exit: classified.exitCode,
+            log_file_path: currentRunLogPath(),
+            message,
+            type: 'command-failed',
+            version: 1,
+            ...(classified.details.retryAfterMs === undefined ? {} : { retry_after_ms: classified.details.retryAfterMs }),
+        });
+        const exitCode = renderError(error, { json: machine });
+        // The pointer to the full trace, human mode only (machine consumers get
+        // log_file_path in the sidecar entry instead — stderr stays quiet).
+        const logPath = currentRunLogPath();
+        if (!machine && logPath !== null)
+            process.stderr.write(`🪵 Logs were written to ${logPath}\n`);
+        this.exit(exitCode);
+    }
+    // Success bookkeeping for the sidecar. oclif calls finally() with undefined on
+    // the clean path (the failure entry is written in catch()), so only a success
+    // logs a result here.
+    async finally(error) {
+        if (error === undefined && this.startedAtMs > 0) {
+            writeOutputEntry({
+                command: this.id ?? '',
+                duration_ms: Date.now() - this.startedAtMs,
+                exit: 0,
+                type: 'result',
+                version: 1,
+            });
+        }
+        await super.finally(error);
+    }
+    // A multi-line guidance BLOCK on stderr, human mode only (E11-3/E11-6
+    // review): shares note()'s redact + sanitize + machine-mode gating, but
+    // emits the text verbatim without the `→ ` prefix. This is the one writer
+    // for the command footers (catalog example, connections usage, login next),
+    // so mode gating no longer depends on each call sitting inside a human
+    // closure. Newlines are preserved (it is a block); each line is sanitized.
+    footer(text) {
+        if (this.jsonEnabled() || Boolean(this.flags?.ndjson))
+            return;
+        const safe = redact(text)
+            .split('\n')
+            .map((line) => sanitizeTerminal(line))
+            .join('\n');
+        process.stderr.write(safe.endsWith('\n') ? safe : `${safe}\n`);
     }
     async init() {
         await super.init();
@@ -36,11 +100,46 @@ export class BaseCommand extends Command {
         });
         this.flags = flags;
         this.args = args;
+        // Tell the rest of the process which stream discipline applies, so code far
+        // from here — the keychain's "still waiting" notice, for one — can honour
+        // the empty-stderr guarantee without being handed the command object.
+        setMachineMode(this.jsonEnabled() || Boolean(this.flags.ndjson));
         // --json and --ndjson both claim stdout; refuse the ambiguous combination.
         // UsageError carries exit 2 (oclif's {exit:2} would map to GENERIC instead).
         if (this.jsonEnabled() && this.flags.ndjson) {
             throw new UsageError('--json and --ndjson are mutually exclusive.');
         }
+        // E11-6 wiring: --verbose mirrors the wire trace to stderr (the run log
+        // always gets it), and the sidecar records the session before any work.
+        // argv is REDACTED (a --body/flag can carry a token) and capped — the run
+        // log's own contract is "callers redact before appendRunLog".
+        this.startedAtMs = Date.now();
+        if (this.flags.verbose)
+            enableStderrTrace();
+        const safeArgv = redact([this.id ?? '', ...this.argv]).map((part) => part.slice(0, DISK_FIELD_MAX));
+        appendRunLog(`session ${this.config.version} contract=${CONTRACT_VERSION} argv=${JSON.stringify(safeArgv)}`);
+        writeOutputEntry({
+            argv: safeArgv,
+            cli_version: this.config.version,
+            contract_version: CONTRACT_VERSION,
+            log_file_path: currentRunLogPath(),
+            type: 'session',
+            version: 1,
+        });
+    }
+    // Context narration (E11-2, #101): resolved state and environmental inferences,
+    // one `→ ` line each, HUMAN MODE ONLY. Under --json/--ndjson these vanish
+    // entirely — stdout purity is untouchable and machine consumers branch on the
+    // envelope/sidecar, not prose. stderr, redacted, terminal-sanitized.
+    note(message) {
+        if (this.jsonEnabled() || Boolean(this.flags?.ndjson))
+            return;
+        // ONE line per note, enforced: a newline smuggled inside an interpolated
+        // value (a service-supplied connection name, a filter column) would
+        // otherwise forge additional arrow-prefixed lines — misleading context
+        // injected into the exact channel agents read (sec review, #109).
+        const line = sanitizeTerminal(redact(message)).replaceAll(/[\t\n\r]+/g, ' ');
+        process.stderr.write(`→ ${line}\n`);
     }
     // The resolved active host (flag > config.defaultHost > DEFAULT_HOST).
     resolvedHost() {
@@ -70,6 +169,6 @@ export class BaseCommand extends Command {
     // always redacted (never leaks a token).
     verboseLog(message) {
         if (this.flags.verbose)
-            process.stderr.write(`${redact(message)}\n`);
+            process.stderr.write(`${sanitizeTerminal(redact(message))}\n`);
     }
 }

package/dist/lib/command/flags.d.ts

@@ -1,3 +1,7 @@
+export declare const plannerFlags: {
+    'auth-host': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+    url: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+};
 export declare const paginationFlags: {
     all: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     limit: import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;

package/dist/lib/command/flags.js

@@ -1,4 +1,15 @@
 import { Flags } from '@oclif/core';
+// Shared flags for the commands that target the QUERY PLANNER (E8). `--url` is
+// how you drive a locally-run planner; `--auth-host` names the issuer holding the
+// credentials, which is a DIFFERENT origin from the planner itself.
+export const plannerFlags = {
+    'auth-host': Flags.string({
+        description: 'OAuth issuer host for credentials/refresh (defaults to the prod issuer).',
+    }),
+    url: Flags.string({
+        description: 'Query-planner base URL (default: the prod planner; env FLIPSTREAM_PLANNER_URL).',
+    }),
+};
 // Shared pagination/filter flags for admin list commands (E7-1b). `limit`
 // defaults to 50 to force the {count, records} shape; `--all` drains every page.
 export const paginationFlags = {

package/dist/lib/command/planner.d.ts

@@ -0,0 +1,9 @@
+import { type PlannerClient } from '../planner/client.js';
+import { type TokenStore } from '../store/keyring.js';
+export interface PlannerClientOptions {
+    authHost: string;
+    store: TokenStore;
+    timeoutMs?: number;
+    url: string;
+}
+export declare function authedPlannerClient(options: PlannerClientOptions): PlannerClient;

package/dist/lib/command/planner.js

@@ -0,0 +1,14 @@
+import { refresh } from '../auth/refresh.js';
+import { createAuthedPlannerClient } from '../planner/client.js';
+// Build the authed planner client for a command. Mirrors authedAdminClient, but
+// keeps the two origins explicit — conflating them is how a refresh ends up
+// pointed at a host that cannot issue anything.
+export function authedPlannerClient(options) {
+    return createAuthedPlannerClient({
+        accessTokenIfFresh: (host) => options.store.accessTokenIfFresh(host),
+        authHost: options.authHost,
+        refresh: (host) => refresh(host, { store: options.store, timeoutMs: options.timeoutMs }),
+        timeoutMs: options.timeoutMs,
+        url: options.url,
+    });
+}