flipstream 0.4.0 → 0.6.0

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/hydrate.d.ts

@@ -0,0 +1,10 @@
+import { type AdminClient } from './admin-client.js';
+export interface HydrateSpec {
+    endpoint: string;
+    idField: string;
+    label: (entity: Record<string, unknown>) => unknown;
+    labelField: string;
+}
+export declare const WORKSPACE_NAME: HydrateSpec;
+export declare const CREATOR_EMAIL: HydrateSpec;
+export declare function hydrate(client: AdminClient, records: Array<Record<string, unknown>>, specs: HydrateSpec[]): Promise<void>;

package/dist/lib/api/hydrate.js

@@ -0,0 +1,46 @@
+import { drainPages, normalizeList } from './list.js';
+// The shared workspace-name and author-email specs (used across list commands).
+export const WORKSPACE_NAME = {
+    endpoint: '/clients',
+    idField: 'client_id',
+    label: (entity) => entity.name,
+    labelField: 'client_name',
+};
+export const CREATOR_EMAIL = {
+    endpoint: '/users',
+    idField: 'created_by_id',
+    label: (entity) => entity.email ?? entity.name,
+    labelField: 'created_by_email',
+};
+async function hydrateOne(client, records, spec) {
+    const needs = (record) => record[spec.labelField] === undefined &&
+        typeof record[spec.idField] === 'string' &&
+        record[spec.idField].length > 0;
+    if (!records.some((record) => needs(record)))
+        return;
+    const byId = new Map();
+    try {
+        const entities = await drainPages(async (page) => normalizeList(await client.get(spec.endpoint, { query: { limit: page.limit, offset: page.offset } })), { limit: 100, offset: 0 });
+        for (const raw of entities.records) {
+            const entity = (raw ?? {});
+            if (typeof entity.id === 'string') {
+                const label = spec.label(entity);
+                byId.set(entity.id, typeof label === 'string' ? label : '');
+            }
+        }
+    }
+    catch {
+        return; // best-effort: leave the label unresolved rather than fail the list
+    }
+    for (const record of records) {
+        if (needs(record))
+            record[spec.labelField] = byId.get(record[spec.idField]) ?? null;
+    }
+}
+// Hydrate a record set against one or more specs, running each lookup CONCURRENTLY
+// and ONCE. Each spec is skipped when no record needs it, and is best-effort: a
+// forbidden/unavailable lookup leaves its label unresolved rather than failing.
+// Mutates `records` in place.
+export async function hydrate(client, records, specs) {
+    await Promise.all(specs.map((spec) => hydrateOne(client, records, spec)));
+}

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/log.d.ts

@@ -0,0 +1,22 @@
+import { type AdminClient } from './admin-client.js';
+export interface LogQuery {
+    all?: boolean;
+    limit: number;
+    offset: number;
+    q?: string;
+    sort?: string;
+    workspace: string;
+}
+export declare function fetchLog(client: AdminClient, query: LogQuery): Promise<{
+    count: number;
+    records: Array<Record<string, unknown>>;
+}>;
+export interface NewLogEntry {
+    clientId: string;
+    description: string;
+    endDate: string;
+    organizationId: string;
+    startDate: string;
+}
+export declare function addLogEntry(client: AdminClient, entry: NewLogEntry): Promise<Record<string, unknown>>;
+export declare function resolveWorkspaceOrg(client: AdminClient, workspaceId: string): Promise<string>;

package/dist/lib/api/log.js

@@ -0,0 +1,56 @@
+import { DataHttpError } from '../errors.js';
+import { mapDataError, notFoundError } from './errors.js';
+import { drainPages, normalizeList } from './list.js';
+import { projectLogEntry, projectWorkspace } from './projections.js';
+// Fetch + project a workspace's log (event-log) entries via the per-client
+// endpoint, draining pages when requested. Errors are mapped to the E3 model.
+export async function fetchLog(client, query) {
+    const path = `/clients/${query.workspace}/event-logs`;
+    const fetchPage = async (page) => {
+        try {
+            return normalizeList(await client.get(path, { query: { limit: page.limit, offset: page.offset, q: query.q, sort: query.sort } }));
+        }
+        catch (error) {
+            throw mapDataError(error);
+        }
+    };
+    const start = { limit: query.limit, offset: query.offset };
+    const envelope = query.all ? await drainPages(fetchPage, start) : await fetchPage(start);
+    return { count: envelope.count, records: envelope.records.map((record) => projectLogEntry(record)) };
+}
+// Add a log entry: POST /event-logs (the workspace + org go in the body). The
+// body is a structured builder, so future fields (e.g. tags) drop in here.
+// Returns the projected created entry. Errors are mapped to the E3 model.
+export async function addLogEntry(client, entry) {
+    const body = {
+        client_id: entry.clientId,
+        description: entry.description,
+        end_date: entry.endDate,
+        organization_id: entry.organizationId,
+        start_date: entry.startDate,
+    };
+    try {
+        return projectLogEntry(await client.post('/event-logs', { body }));
+    }
+    catch (error) {
+        throw mapDataError(error);
+    }
+}
+// Derive a workspace's organization_id (required to create an entry) via one
+// workspace lookup. A foreign or missing id collapses to a single not-found
+// message (no existence leak), mirroring `ws get`.
+export async function resolveWorkspaceOrg(client, workspaceId) {
+    let raw;
+    try {
+        raw = await client.get(`/clients/${workspaceId}`);
+    }
+    catch (error) {
+        if (error instanceof DataHttpError && (error.status === 403 || error.status === 404))
+            throw notFoundError();
+        throw mapDataError(error);
+    }
+    const org = projectWorkspace(raw).organization_id;
+    if (typeof org !== 'string' || org.length === 0)
+        throw notFoundError();
+    return org;
+}

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

@@ -1,2 +1,3 @@
 export declare function projectWorkspace(raw: unknown): Record<string, unknown>;
 export declare function projectConnection(raw: unknown): Record<string, unknown>;
+export declare function projectLogEntry(raw: unknown): Record<string, unknown>;

package/dist/lib/api/projections.js

@@ -1,6 +1,7 @@
 import { redact } from '../output/redact.js';
 const WORKSPACE_CORE = ['organization_id', 'slug', 'business_type', 'client_main_goal', 'created_on'];
 const CONNECTION_CORE = ['name', 'client_id', 'type', 'active', 'backfill', 'data_refresh_status', 'created_on'];
+const LOG_CORE = ['description', 'start_date', 'end_date', 'client_id', 'organization_id', 'created_on', 'created_by_id'];
 // Project a raw admin Client into a stable "workspace" shape: id + name + present
 // core fields + owner_email (from the nested owner) + a redacted `raw` passthrough
 // so it survives schema drift. Adds/invents no fields.
@@ -32,3 +33,25 @@ export function projectConnection(raw) {
     out.raw = redact(raw);
     return out;
 }
+// Project a raw EventLog (the "log" / logbook entry) into a stable shape: id +
+// present core fields + the workspace name (nested `client`) and author (nested
+// `created_by`) + a redacted `raw` passthrough. New API fields (e.g. `tags`)
+// flow through `raw` automatically under --json; surface them by adding to
+// LOG_CORE + a table column when they ship.
+export function projectLogEntry(raw) {
+    const entry = (raw ?? {});
+    const out = { id: entry.id };
+    for (const key of LOG_CORE)
+        if (entry[key] !== undefined)
+            out[key] = entry[key];
+    const client = entry.client;
+    if (client?.name)
+        out.client_name = client.name;
+    const by = entry.created_by;
+    if (by?.name)
+        out.created_by_name = by.name;
+    if (by?.email)
+        out.created_by_email = by.email;
+    out.raw = redact(raw);
+    return out;
+}

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.js

@@ -2,11 +2,11 @@
 // MUST NOT be used for any authorization / request-gating decision (the CLI is a
 // thin client; the server validates tokens). A convention test guards this.
 export function decodeJwtClaimsUnverified(accessToken) {
-    const parts = accessToken.split('.');
-    if (parts.length < 2)
+    const [, payload] = accessToken.split('.');
+    if (payload === undefined)
         return null;
     try {
-        const padded = parts[1] + '='.repeat((4 - (parts[1].length % 4)) % 4);
+        const padded = payload + '='.repeat((4 - (payload.length % 4)) % 4);
         return JSON.parse(Buffer.from(padded, 'base64url').toString('utf8'));
     }
     catch {

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);

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
@@ -43,7 +44,26 @@ 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 and only delete if what is stored is still the token
+        // we just tried. Note this race predates the read cache: two processes could
+        // always interleave a load and a rotation.
+        const current = store.reload(host);
+        if (current !== null && current.refreshToken !== creds.refreshToken) {
+            // Someone else won the race and their session is live. HAND OFF to it rather
+            // than reporting failure: returning null here would surface as "Session
+            // expired. Run `flipstream auth login`" while perfectly good credentials sit
+            // in the keychain — telling the user to fix something that is not broken.
+            // May still be null if their access token is also stale; either way we do
+            // not clear a session we do not own.
+            return freshAccessToken(current);
+        }
+        store.clear(host); // genuinely invalid_grant / revoked session — force re-login.
         return null;
     }
     if (!response.ok)

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

@@ -2,3 +2,4 @@ import { type AdminClient } from '../api/admin-client.js';
 import { type TokenStore } from '../store/keyring.js';
 export declare function authedAdminClient(host: string, store: TokenStore, timeoutMs?: number): AdminClient;
 export declare function renderConnectionsTable(records: Array<Record<string, unknown>>): void;
+export declare function renderLogEntriesTable(records: Array<Record<string, unknown>>): void;

package/dist/lib/command/admin.js

@@ -28,3 +28,24 @@ export function renderConnectionsTable(records) {
         { key: 'id', name: 'ID' },
     ], 'No connections.');
 }
+// The log (event-log) human table — shared by `log list`. Date prefers
+// created_on (falls back to start_date); By prefers the author name then email;
+// Workspace falls back to the id when its name couldn't be resolved.
+// First non-empty string among the candidates, else an em-dash placeholder.
+function firstLabel(...values) {
+    return values.find((value) => typeof value === 'string' && value.length > 0) ?? '—';
+}
+export function renderLogEntriesTable(records) {
+    const rows = records.map((record) => ({
+        ...record,
+        by: firstLabel(record.created_by_name, record.created_by_email, record.created_by_id),
+        client_name: firstLabel(record.client_name, record.client_id),
+        when: firstLabel(record.created_on, record.start_date),
+    }));
+    renderTable(rows, [
+        { key: 'when', name: 'Date' },
+        { key: 'client_name', name: 'Workspace' },
+        { key: 'description', name: 'Entry' },
+        { key: 'by', name: 'By' },
+    ], 'No log entries.');
+}

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,17 @@
 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 { 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 +28,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();
@@ -41,6 +104,37 @@ export class BaseCommand extends Command {
         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 +164,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,
+    });
+}