@hs-x/cli 0.2.6 → 0.3.0

package/dist/commands/control-plane-read.js

@@ -1,12 +1,19 @@
 import * as Command from '@effect/cli/Command';
+import * as Options from '@effect/cli/Options';
 import { HttpClientRequest, Schema, schemas } from '@hs-x/types';
 import { Config, Effect, Option } from 'effect';
 import { isLinked } from '../account-store.js';
+import { auditExplorer, filterAuditRows, promptAuditTimeRange, renderAuditDetail, } from '../audit-interactive.js';
+import { checkpointDrilldown, } from '../checkpoint-interactive.js';
 import { CliError, cliError, exitWith } from '../cli-error.js';
 import { accountIdOption, controlPlaneUrlOption, jsonOption, projectIdOption, runHandler, userIdOption, } from '../cli/kit.js';
 import { DEFAULT_CONTROL_PLANE_URL } from '../config.js';
 import { executeCliHttpEffect } from '../effect-http.js';
+import { fetchHubSpotLogsPayload, mergeLogRows, parseHubSpotLogSystemTypes, resolveHubSpotLogsSource, } from '../hubspot-app-logs.js';
+import { promptInteractiveLogsSelection } from '../logs-interactive.js';
 import { readProjectBinding } from '../project-binding.js';
+import { ProjectPickerCancelled, discoverProjects, resolveProjectSelection, } from '../project-picker.js';
+import { isInteractive, promptSelect } from '../prompt.js';
 import { AccountStore } from '../services/account-store.js';
 import { ControlPlaneClient } from '../services/control-plane.js';
 import { Cwd } from '../services/cwd.js';
@@ -81,11 +88,283 @@ function renderCheckpoint(checkpoint) {
     lines.push(`Sources: ${sourceParts.join(', ')}`);
     return `${lines.join('\n')}\n`;
 }
+export function renderCheckpointExemplar(failure) {
+    const exemplar = failure.exemplar;
+    const lines = [
+        `Capability: ${exemplar.capabilityId}`,
+        `Worker: ${exemplar.workerName}`,
+        `Deploy: ${exemplar.deployId}`,
+        `Outcome: ${exemplar.outcome}`,
+        `Observed: ${exemplar.observedAt}`,
+        `Duration: ${exemplar.durationMs}ms`,
+        `Portal: ${exemplar.portalId}`,
+        `Fingerprint: ${failure.fingerprint}`,
+        `Redacted input:\n${JSON.stringify(exemplar.redactedInput, null, 2)}`,
+    ];
+    if (exemplar.redactedOutput !== undefined) {
+        lines.push(`Redacted output:\n${JSON.stringify(exemplar.redactedOutput, null, 2)}`);
+    }
+    if (exemplar.redactedError !== undefined) {
+        lines.push(`Redacted error:\n${JSON.stringify(exemplar.redactedError, null, 2)}`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function clampInt(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(Math.max(Math.trunc(value), min), max);
+}
+function readString(row, key) {
+    const value = row[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function readNumber(row, key) {
+    const value = row[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function parseLogFilters(values) {
+    const filters = [];
+    for (const value of values) {
+        for (const rawPart of value.split(',')) {
+            const part = rawPart.trim();
+            if (!part)
+                continue;
+            const match = /^([a-zA-Z][a-zA-Z0-9_.-]*)(!=|>=|<=|=|>|<|~)(.+)$/.exec(part);
+            if (!match) {
+                return {
+                    ok: false,
+                    message: `Invalid log filter "${part}". Use key=value, key!=value, key~text, or status>=500.`,
+                };
+            }
+            const [, key, op, rawFilterValue] = match;
+            const filterValue = rawFilterValue?.trim() ?? '';
+            if (!key || filterValue.length === 0) {
+                return {
+                    ok: false,
+                    message: `Invalid log filter "${part}". Filters need a key and value.`,
+                };
+            }
+            filters.push({ key, op: op, value: filterValue });
+        }
+    }
+    return { ok: true, filters };
+}
+function parseSampleRate(value) {
+    if (value === undefined || value.trim() === '')
+        return { ok: true };
+    const rate = Number(value);
+    if (!Number.isFinite(rate) || rate <= 0 || rate > 1) {
+        return {
+            ok: false,
+            message: '--sample must be a number greater than 0 and less than or equal to 1.',
+        };
+    }
+    return { ok: true, rate };
+}
+function compareLogFilter(row, filter) {
+    const raw = row[filter.key];
+    if (raw === undefined || raw === null)
+        return false;
+    const rowText = String(raw);
+    const wantedText = filter.value;
+    if (filter.op === '~') {
+        return rowText.toLowerCase().includes(wantedText.toLowerCase());
+    }
+    const rowNumber = typeof raw === 'number' ? raw : Number(rowText);
+    const wantedNumber = Number(wantedText);
+    const canCompareNumber = Number.isFinite(rowNumber) && Number.isFinite(wantedNumber);
+    if (filter.op === '>=' || filter.op === '<=' || filter.op === '>' || filter.op === '<') {
+        if (!canCompareNumber)
+            return false;
+        if (filter.op === '>=')
+            return rowNumber >= wantedNumber;
+        if (filter.op === '<=')
+            return rowNumber <= wantedNumber;
+        if (filter.op === '>')
+            return rowNumber > wantedNumber;
+        return rowNumber < wantedNumber;
+    }
+    const matches = canCompareNumber
+        ? rowNumber === wantedNumber
+        : rowText.toLowerCase() === wantedText.toLowerCase();
+    return filter.op === '=' ? matches : !matches;
+}
+function stableLogRowKey(row) {
+    const invocationId = readString(row, 'invocationId');
+    if (invocationId)
+        return `invocation:${invocationId}`;
+    return [
+        readString(row, 'timestamp') ?? '',
+        readString(row, 'level') ?? '',
+        readString(row, 'message') ?? '',
+        readString(row, 'event') ?? '',
+    ].join('|');
+}
+function orderLogRowsAscending(rows) {
+    return [...rows].sort((a, b) => (readString(a, 'timestamp') ?? '').localeCompare(readString(b, 'timestamp') ?? ''));
+}
+function hashString(value) {
+    let hash = 2166136261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return hash >>> 0;
+}
+function applyLogFilters(rows, filters, sampleRate) {
+    return rows.filter((row) => {
+        if (!filters.every((filter) => compareLogFilter(row, filter)))
+            return false;
+        if (sampleRate === undefined || sampleRate >= 1)
+            return true;
+        return hashString(stableLogRowKey(row)) / 0xffffffff <= sampleRate;
+    });
+}
+function asLogsPayload(body) {
+    if (!isRecord(body))
+        return { rows: [], error: 'invalid_response' };
+    const rows = Array.isArray(body.rows)
+        ? body.rows.filter(isRecord).map((row) => ({ origin: 'workers', ...row }))
+        : [];
+    return {
+        ...(typeof body.projectId === 'string' ? { projectId: body.projectId } : {}),
+        rows,
+        ...(typeof body.error === 'string' && body.error.length > 0 ? { error: body.error } : {}),
+    };
+}
+/** ok/warn/fail for a log row, from level, outcome, and HTTP status. */
+function logRowStatus(row) {
+    const status = readNumber(row, 'status');
+    const outcome = (readString(row, 'outcome') ?? '').toLowerCase();
+    const level = (readString(row, 'level') ?? '').toLowerCase();
+    if (level === 'error' ||
+        outcome === 'error' ||
+        outcome === 'exception' ||
+        (status !== undefined && status >= 500)) {
+        return 'fail';
+    }
+    if (level === 'warn' || (status !== undefined && status >= 400))
+        return 'warn';
+    if (outcome === 'ok' || outcome === 'success' || (status !== undefined && status < 400)) {
+        return 'ok';
+    }
+    return undefined;
+}
+function originTag(row, showOrigin) {
+    if (!showOrigin)
+        return undefined;
+    return readString(row, 'origin') === 'hubspot' ? 'hs' : 'cf';
+}
+/** One railed row per invocation: glyph, cyan route, bright result, dim tail. */
+function invocationReporterRow(row, showOrigin) {
+    const source = readString(row, 'source') ?? 'request';
+    const target = readString(row, 'target');
+    const method = readString(row, 'method');
+    const status = readNumber(row, 'status');
+    const outcome = readString(row, 'outcome');
+    const durationMs = readNumber(row, 'durationMs');
+    const invocationId = readString(row, 'invocationId') ?? 'unknown-invocation';
+    const rowStatus = logRowStatus(row);
+    const value = [method, status === undefined ? undefined : String(status)]
+        .filter((part) => part !== undefined)
+        .join(' ') ||
+        outcome ||
+        'invocation';
+    const detail = [
+        readString(row, 'timestamp') ?? 'unknown-time',
+        durationMs === undefined ? undefined : `${durationMs}ms`,
+        originTag(row, showOrigin),
+        invocationId,
+    ]
+        .filter((part) => part !== undefined)
+        .join(' · ');
+    return {
+        key: target ? `${source}/${target}` : source,
+        value,
+        detail,
+        ...(rowStatus ? { status: rowStatus } : {}),
+        ...(rowStatus === 'fail' || rowStatus === 'warn'
+            ? { hint: `hs-x logs --trace ${invocationId}` }
+            : {}),
+    };
+}
+/** Raw tail/trace view: level-keyed rows; console output follows as a block. */
+function tailReporterRow(row, showOrigin) {
+    const level = readString(row, 'level') ?? 'log';
+    const rowStatus = level === 'error' ? 'fail' : level === 'warn' ? 'warn' : undefined;
+    const detail = [
+        readString(row, 'timestamp') ?? 'unknown-time',
+        readString(row, 'event'),
+        readString(row, 'outcome'),
+        originTag(row, showOrigin),
+    ]
+        .filter((part) => part !== undefined && part.length > 0)
+        .join(' · ');
+    return {
+        key: level,
+        value: readString(row, 'message') ?? '',
+        detail,
+        ...(rowStatus ? { status: rowStatus } : {}),
+    };
+}
+/**
+ * Render a batch of log rows through the railed renderer. Invocations render
+ * as one aligned rail; tail/trace rows render individually so each row's
+ * captured console output can follow it verbatim.
+ */
+function emitLogRows(reporter, rows, view, showOrigin) {
+    return Effect.gen(function* () {
+        if (rows.length === 0) {
+            yield* reporter.info(view === 'invocations'
+                ? 'No invocations found in this window.'
+                : 'No log rows found in this window.');
+            return;
+        }
+        if (view === 'invocations') {
+            yield* reporter.rows(rows.map((row) => invocationReporterRow(row, showOrigin)));
+            return;
+        }
+        for (const row of rows) {
+            yield* reporter.rows([tailReporterRow(row, showOrigin)]);
+            const consoleOutput = readString(row, 'consoleOutput');
+            if (consoleOutput)
+                yield* reporter.block(consoleOutput);
+        }
+    });
+}
+/** Outcome tally for the logs footer; only invocation rows carry outcomes. */
+function logRowCounts(rows) {
+    const counts = { ok: 0, warn: 0, fail: 0 };
+    for (const row of rows) {
+        const status = logRowStatus(row);
+        if (status)
+            counts[status] += 1;
+    }
+    return counts;
+}
 export function auditHelpText() {
     return `hs-x audit
 
+Browse a bounded, redacted account audit feed. Bare hs-x audit opens an
+interactive account, time-range, filter, and event-detail explorer. Scripts use
+the explicit list form; JSON and non-TTY execution never prompt.
+
 Commands:
-  hs-x audit list --control-plane-url <url> --account-id <id> [--user-id <id>] [--json]
+  hs-x audit
+  hs-x audit list [--account-id <id>] [--since <24h|7d|ISO>] [--limit <n>]
+
+Filters:
+  --action <action>         Exact audit action
+  --resource <type[/id]>    Resource type or exact type/id
+  --actor <user-id>         Actor user id
+  --outcome <outcome>       success, failure, or in_progress
+  --since <time>            Relative duration (30m, 24h, 7d) or ISO timestamp
+  --limit <n>               Maximum rows, clamped to 1–200 (default 50)
+  --json                    Emit the bounded redacted result
+
+Advanced:
+  --control-plane-url <url> Override control plane (HSX_CONTROL_PLANE_URL)
+  --user-id <id>            Attribution for control-plane records
 `;
 }
 export function driftHelpText() {
@@ -100,21 +379,70 @@ from the .hs-x/project.json binding that link/deploy maintain.
 `;
 }
 export function checkpointHelpText() {
-    return `hs-x logs
+    return `hs-x checkpoint
 
 Commands:
-  hs-x logs --project <id> [--json]
+  hs-x checkpoint --project <id> [--json]
 
 Find project ids with hs-x list. --project is an alias of --project-id.
 Inside a deployed project directory the flag is optional — the id is read
-from the .hs-x/project.json binding that link/deploy maintain.
+from the .hs-x/project.json binding that link/deploy maintain. In an
+interactive terminal, recent failures can drill into matching Workers error
+logs or their redacted representative invocation. Machine output never prompts.
 
 Advanced:
   --control-plane-url <url>  Override control plane (HSX_CONTROL_PLANE_URL)
   --user-id <id>             Attribution for control-plane records
+`;
+}
+export function logsHelpText() {
+    return `hs-x logs
+
+One timeline for everything your app does: Workers Logs rows from your
+deployed runtime ([cf]) merged with HubSpot's app logs ([hs] — card and
+extension renders, production frontend logger output, webhook deliveries,
+API calls, OAuth authorizations). Each side degrades independently: Workers
+Logs need a linked HS-X account, HubSpot logs need only a deployed app and
+HubSpot CLI credentials.
+
+Run bare hs-x logs in a terminal for a guided project, source, log-type,
+and time-range picker. A project bound in the current directory is selected
+by default. Flags skip the picker for scripts and repeatable workflows.
 
-Alias:
-  hs-x checkpoint ...
+Commands:
+  hs-x logs --project <id> [--account-id <id>] [--json]
+  hs-x logs --project <id> --trace <invocation-id>
+  hs-x logs --project <id> --follow --filter source=action,status>=500
+  hs-x logs --source hubspot --filter outcome=error
+
+Find project ids with hs-x list. --project is an alias of --project-id.
+Inside a deployed project directory the project flag is optional — the id is
+read from the .hs-x/project.json binding that link/deploy maintain.
+
+Options:
+  --account-id <id>          HS-X account (default: the active account)
+  --source <name>            all (default), workers, or hubspot
+  --type <name>              HubSpot log type; repeat or comma-separate values
+  --errors-only              Show errors only (server-side for HubSpot)
+  --limit <count>            Rows to read, clamped to 1-200 (default: 50)
+  --since-minutes <count>    Lookback window, clamped to 1-10080 (default: 15)
+  --trace <id>               Read logger lines for one invocation, or HubSpot
+                             rows matching a trace id (with console output)
+  --invocation <id>          Alias of --trace
+  --raw                      Read raw tail events instead of invocation rows
+  --filter <expr>            Filter rows; supports key=value, key!=value, key~text, status>=500
+                             (rows carry origin=workers|hubspot and, for HubSpot
+                             rows, systemType/errorType/portalId)
+  --sample <rate>            Deterministically sample rows, 0 < rate <= 1
+  --follow                   Poll and append new rows until interrupted
+  --tail                     Alias of --follow
+  --interval-seconds <n>     Follow polling interval, clamped to 1-60 (default: 3)
+
+Advanced:
+  --app-id <id>              HubSpot app id (default: the .hs-x/hubspot.json
+                             binding recorded by deploy)
+  --control-plane-url <url>  Override control plane (HSX_CONTROL_PLANE_URL)
+  --user-id <id>             Attribution for control-plane records
 `;
 }
 export function listHelpText() {
@@ -218,10 +546,17 @@ function resolveFromOptionOrEnv(option, envKey) {
         return fromEnv.length > 0 ? fromEnv : undefined;
     });
 }
-/** Authenticated GET via the `ControlPlaneClient` (bearer session or x-hsx-user-id fallback). */
+/**
+ * Authenticated GET via the `ControlPlaneClient`. The hosted control plane
+ * requires a real login session; only an explicitly overridden/local control
+ * plane may use the x-hsx-user-id development fallback.
+ */
 function cpGet(controlPlaneUrl, path, userId) {
     return Effect.gen(function* () {
         const client = yield* ControlPlaneClient;
+        if (new URL(controlPlaneUrl).origin === new URL(DEFAULT_CONTROL_PLANE_URL).origin) {
+            return yield* client.fetch({ controlPlaneUrl, path });
+        }
         const headers = yield* client.authHeaders(userId);
         const url = new URL(path, controlPlaneUrl);
         const request = HttpClientRequest.get(url).pipe(HttpClientRequest.setHeaders(headers));
@@ -253,27 +588,183 @@ function resolveProjectId(opts) {
         return binding?.projectId;
     });
 }
+/**
+ * Resolve an operations project without changing machine behavior. Explicit
+ * flag/env ids stay authoritative and never trigger catalog discovery. A local
+ * binding remains authoritative outside a TTY, but in a human TTY it is only
+ * the default hint for the account-scoped project picker.
+ */
+export function resolveOperationProjectForRead(opts, input) {
+    return Effect.gen(function* () {
+        const authoritative = yield* resolveFromOptionOrEnv(opts.projectId, 'HSX_PROJECT_ID');
+        if (authoritative)
+            return { projectId: authoritative };
+        const cwd = yield* Cwd;
+        const binding = yield* Effect.promise(() => readProjectBinding(cwd));
+        if (!isInteractive()) {
+            return binding?.projectId ? { projectId: binding.projectId } : undefined;
+        }
+        const accountId = yield* resolveAccountId(opts, binding?.accountId);
+        if (!accountId) {
+            return binding?.projectId ? { projectId: binding.projectId } : undefined;
+        }
+        const controlPlaneUrl = yield* resolveControlPlaneUrl(opts.controlPlaneUrl);
+        const userId = yield* resolveUserId(opts);
+        const client = yield* ControlPlaneClient;
+        const controlPlane = {
+            request: (request) => Effect.runPromise(cpGet(controlPlaneUrl, request.path, userId).pipe(Effect.provideService(ControlPlaneClient, client))),
+        };
+        return yield* Effect.tryPromise({
+            try: async () => {
+                const projects = await discoverProjects({ accountId, controlPlane });
+                if (projects.length === 0)
+                    throw new Error(input.emptyMessage);
+                const project = await resolveProjectSelection({
+                    accountId,
+                    projects,
+                    ...(binding?.projectId ? { localProjectId: binding.projectId } : {}),
+                    allowPrompt: true,
+                    prompts: { select: promptSelect },
+                    message: input.message,
+                });
+                return { projectId: project.id, accountId, project, projects };
+            },
+            catch: (cause) => cause,
+        }).pipe(Effect.catchAll((cause) => cause instanceof ProjectPickerCancelled
+            ? Effect.fail(exitWith(130))
+            : failBespoke(opts.json, input.command, cause instanceof Error ? cause.message : String(cause)).pipe(Effect.as(undefined))));
+    });
+}
 const PROJECT_ID_HINT = 'pass --project <id> (find ids with `hs-x list`) or run inside a deployed project directory';
 // ─── audit ──────────────────────────────────────────────────────────────────
-export const auditCmd = Command.make('audit', cpReadOptions, (opts) => runHandler('audit list', { json: opts.json }, auditBody(opts)));
+const auditOptions = {
+    ...cpReadOptions,
+    limit: Options.integer('limit').pipe(Options.withDefault(50)),
+    since: Options.text('since').pipe(Options.optional),
+    action: Options.text('action').pipe(Options.optional),
+    resource: Options.text('resource').pipe(Options.optional),
+    actor: Options.text('actor').pipe(Options.optional),
+    outcome: Options.text('outcome').pipe(Options.optional),
+};
+export const auditCmd = Command.make('audit', auditOptions, (opts) => runHandler('audit list', { json: opts.json }, auditBody(opts, { explorer: true })));
 // Same handler exposed as the `list` subcommand, so the dispatch can build the
 // legacy `audit list` shape: `Command.make('audit').withSubcommands([auditListCmd])`.
-export const auditListCmd = Command.make('list', cpReadOptions, (opts) => runHandler('audit list', { json: opts.json }, auditBody(opts)));
-function auditBody(opts) {
+export const auditListCmd = Command.make('list', auditOptions, (opts) => runHandler('audit list', { json: opts.json }, auditBody(opts, { explorer: false })));
+export function parseAuditSince(value, now = Date.now()) {
+    if (!value)
+        return { ok: true };
+    const relative = /^(\d+)(m|h|d)$/i.exec(value.trim());
+    if (relative) {
+        const amount = Number(relative[1]);
+        if (!Number.isSafeInteger(amount) || amount <= 0) {
+            return {
+                ok: false,
+                message: `Invalid --since "${value}". Use values like 30m, 24h, 7d, or an ISO timestamp.`,
+            };
+        }
+        const unit = relative[2]?.toLowerCase();
+        const multiplier = unit === 'd' ? 86_400_000 : unit === 'h' ? 3_600_000 : 60_000;
+        return { ok: true, since: new Date(now - amount * multiplier).toISOString() };
+    }
+    const timestamp = Date.parse(value);
+    if (!Number.isFinite(timestamp)) {
+        return {
+            ok: false,
+            message: `Invalid --since "${value}". Use values like 30m, 24h, 7d, or an ISO timestamp.`,
+        };
+    }
+    return { ok: true, since: new Date(timestamp).toISOString() };
+}
+function auditBody(opts, context) {
     return Effect.gen(function* () {
-        const accountId = yield* resolveFromOptionOrEnv(opts.accountId, 'HSX_ACCOUNT_ID');
+        // Fall back to the stored default account (parity with `hs-x list`) so a
+        // logged-in user doesn't have to re-pass --account-id / HSX_ACCOUNT_ID.
+        let accountId = yield* resolveFromOptionOrEnv(opts.accountId, 'HSX_ACCOUNT_ID');
+        const accounts = yield* AccountStore;
+        const store = yield* accounts.load;
+        if (!accountId && context.explorer && !opts.json && isInteractive()) {
+            const candidates = Object.values(store.accounts).sort((left, right) => (left.displayName ?? left.id).localeCompare(right.displayName ?? right.id));
+            if (candidates.length === 1)
+                accountId = candidates[0]?.id;
+            else if (candidates.length > 1) {
+                accountId = yield* Effect.promise(() => promptSelect({
+                    message: 'Which account audit should be inspected?',
+                    options: candidates.map((account) => ({
+                        value: account.id,
+                        label: account.displayName ?? account.id,
+                        description: account.id,
+                    })),
+                    ...(store.defaultAccountId ? { default: store.defaultAccountId } : {}),
+                }));
+                if (!accountId)
+                    return yield* Effect.fail(exitWith(130));
+            }
+        }
+        accountId ??= store.defaultAccountId;
         if (!accountId) {
-            return yield* failBespoke(opts.json, 'audit list', 'Audit list requires --account-id or HSX_ACCOUNT_ID.');
+            return yield* failBespoke(opts.json, 'audit list', 'Audit list requires an HS-X account: run `hs-x login`, or pass --account-id / HSX_ACCOUNT_ID.');
+        }
+        const parsedSince = parseAuditSince(Option.getOrUndefined(opts.since));
+        if (!parsedSince.ok)
+            return yield* failBespoke(opts.json, 'audit list', parsedSince.message);
+        let since = parsedSince.since;
+        if (context.explorer && !opts.json && isInteractive() && Option.isNone(opts.since)) {
+            const range = yield* Effect.promise(() => promptAuditTimeRange());
+            if (range === undefined)
+                return yield* Effect.fail(exitWith(130));
+            since = range === 'all' ? undefined : new Date(Date.now() - range * 60_000).toISOString();
+        }
+        const limit = clampInt(opts.limit, 1, 200);
+        const action = Option.getOrUndefined(opts.action);
+        const resource = Option.getOrUndefined(opts.resource);
+        const actor = Option.getOrUndefined(opts.actor);
+        const outcome = Option.getOrUndefined(opts.outcome);
+        if (outcome && !['success', 'failure', 'in_progress'].includes(outcome)) {
+            return yield* failBespoke(opts.json, 'audit list', `Invalid --outcome "${outcome}". Use success, failure, or in_progress.`);
         }
+        const filters = {
+            limit,
+            ...(since ? { since } : {}),
+            ...(action ? { action } : {}),
+            ...(resource ? { resource } : {}),
+            ...(actor ? { actor } : {}),
+            ...(outcome ? { outcome } : {}),
+        };
+        const params = new URLSearchParams({ limit: String(limit) });
+        if (filters.since)
+            params.set('since', filters.since);
+        if (filters.action)
+            params.set('action', filters.action);
+        if (filters.resource)
+            params.set('resource', filters.resource);
+        if (filters.actor)
+            params.set('actor', filters.actor);
+        if (filters.outcome)
+            params.set('outcome', filters.outcome);
         const controlPlaneUrl = yield* resolveControlPlaneUrl(opts.controlPlaneUrl);
         const userId = yield* resolveUserId(opts);
-        const response = yield* cpGet(controlPlaneUrl, `/v1/accounts/${encodeURIComponent(accountId)}/audit`, userId);
+        const response = yield* cpGet(controlPlaneUrl, `/v1/accounts/${encodeURIComponent(accountId)}/audit?${params.toString()}`, userId);
         const body = yield* Effect.promise(() => response.json());
         if (!response.ok) {
             return yield* failBespoke(opts.json, 'audit list', responseMessage(body, response.status, 'Control-plane audit list failed'));
         }
-        const rows = Schema.decodeUnknownSync(Schema.Array(schemas.AuditRow))(body);
-        const result = { ok: true, command: 'audit list', mode: 'control-plane-audit', accountId, rows };
+        const decodedRows = Schema.decodeUnknownSync(Schema.Array(schemas.AuditRow))(body);
+        // Apply the same constraints client-side for compatibility with older
+        // control planes that ignore the new query parameters.
+        const rows = filterAuditRows(decodedRows, filters);
+        const result = {
+            ok: true,
+            command: 'audit list',
+            mode: 'control-plane-audit',
+            accountId,
+            limit,
+            ...(filters.since ? { since: filters.since } : {}),
+            ...(filters.action ? { action: filters.action } : {}),
+            ...(filters.resource ? { resource: filters.resource } : {}),
+            ...(filters.actor ? { actor: filters.actor } : {}),
+            ...(filters.outcome ? { outcome: filters.outcome } : {}),
+            rows,
+        };
         const reporter = yield* Reporter;
         if (opts.json) {
             yield* reporter.raw(`${JSON.stringify(result, null, 2)}\n`);
@@ -282,6 +773,15 @@ function auditBody(opts) {
         yield* reporter.header(accountId);
         yield* reporter.block(renderAuditRows(rows));
         yield* reporter.done(`${rows.length} row${rows.length === 1 ? '' : 's'}`);
+        if (context.explorer) {
+            yield* auditExplorer(rows, {
+                detail: (row) => Effect.gen(function* () {
+                    yield* reporter.header(`${row.action} audit event`);
+                    yield* reporter.block(renderAuditDetail(row));
+                    yield* reporter.done('Audit event');
+                }),
+            });
+        }
     });
 }
 // ─── drift ────────────────────────────────────────────────────────────────────
@@ -298,7 +798,12 @@ function driftBody(opts) {
                 hint: UNLINKED_DRIFT_HINT,
             });
         }
-        const projectId = yield* resolveProjectId(opts);
+        const selection = yield* resolveOperationProjectForRead(opts, {
+            command: 'drift',
+            message: 'Which project do you want to inspect for drift?',
+            emptyMessage: 'No projects yet. Run `hs-x deploy` from a project to create one.',
+        });
+        const projectId = selection?.projectId;
         if (!projectId) {
             return yield* failBespoke(opts.json, 'drift', `Drift status needs a project: ${PROJECT_ID_HINT}.`);
         }
@@ -344,17 +849,13 @@ function unlinkedRequiresLinkEff(input) {
 }
 // ─── list (projects) ──────────────────────────────────────────────────────────
 export const listCmd = Command.make('list', cpReadOptions, (opts) => runHandler('list', { json: opts.json }, listProjectsBody(opts)));
-function renderProjects(projects) {
-    if (projects.length === 0) {
-        return 'No projects yet. Run `hs-x deploy` from a project to create one.\n';
-    }
-    const widestId = Math.max(...projects.map((p) => p.id.length));
+function projectRows(projects) {
     const widestName = Math.max(...projects.map((p) => p.displayName.length));
-    const lines = projects.map((p) => {
-        const lastDeploy = p.lastDeployAt ? `last deploy ${p.lastDeployAt}` : 'no recorded deploys';
-        return `${p.id.padEnd(widestId)}  ${p.displayName.padEnd(widestName)}  ${lastDeploy}`;
-    });
-    return `${lines.join('\n')}\n`;
+    return projects.map((p) => ({
+        key: p.id,
+        value: p.displayName.padEnd(widestName),
+        detail: p.lastDeployAt ? `last deploy ${p.lastDeployAt}` : 'no recorded deploys',
+    }));
 }
 function listProjectsBody(opts) {
     return Effect.gen(function* () {
@@ -375,14 +876,25 @@ function listProjectsBody(opts) {
             return yield* failBespoke(opts.json, 'list', responseMessage(body, response.status, 'Control-plane project list failed'));
         }
         const { projects } = Schema.decodeUnknownSync(schemas.ListProjectsResponse)(body);
-        const result = { ok: true, command: 'list', mode: 'control-plane-projects', accountId, projects };
+        const result = {
+            ok: true,
+            command: 'list',
+            mode: 'control-plane-projects',
+            accountId,
+            projects,
+        };
         const reporter = yield* Reporter;
         if (opts.json) {
             yield* reporter.raw(`${JSON.stringify(result, null, 2)}\n`);
             return;
         }
         yield* reporter.header(accountId);
-        yield* reporter.block(renderProjects(projects));
+        if (projects.length === 0) {
+            yield* reporter.info('No projects yet. Run `hs-x deploy` from a project to create one.');
+        }
+        else {
+            yield* reporter.rows(projectRows(projects));
+        }
         if (projects.length > 0) {
             yield* reporter.info('Use an id with project-scoped commands: `hs-x logs --project <id>`.');
         }
@@ -400,7 +912,7 @@ function listProjectsBody(opts) {
  * just means the CP has nothing for it — a project with no drift snapshot is
  * healthy, not broken.
  */
-export function fetchRemoteProjectStatus(opts, projectId) {
+export function fetchRemoteProjectStatus(opts, projectId, prefetchedProjects) {
     return Effect.gen(function* () {
         const controlPlaneUrl = yield* resolveControlPlaneUrl(opts.controlPlaneUrl);
         const userId = yield* resolveUserId(opts);
@@ -413,34 +925,30 @@ export function fetchRemoteProjectStatus(opts, projectId) {
             return decoded._tag === 'Right' ? decoded.right : undefined;
         });
         const encodedProject = encodeURIComponent(projectId);
-        const [routing, drift, checkpoint] = yield* Effect.all([
+        const [routing, drift, checkpoint, revisions] = yield* Effect.all([
             fetchSection(`/v1/projects/${encodedProject}/routing`, schemas.ProjectRoutingRead),
             fetchSection(`/v1/projects/${encodedProject}/drift`, schemas.DriftRead),
             fetchSection(`/v1/projects/${encodedProject}/checkpoint`, schemas.CheckpointPanelRead),
-        ], { concurrency: 3 });
-        let accountId = yield* resolveFromOptionOrEnv(opts.accountId, 'HSX_ACCOUNT_ID');
-        if (!accountId) {
-            const accounts = yield* AccountStore;
-            const store = yield* accounts.load;
-            accountId = store.defaultAccountId;
-        }
-        const projectList = accountId
-            ? yield* fetchSection(`/v1/accounts/${encodeURIComponent(accountId)}/projects`, schemas.ListProjectsResponse)
-            : undefined;
-        const project = projectList?.projects.find((candidate) => candidate.id === projectId);
+            fetchSection(`/v1/projects/${encodedProject}/revisions`, schemas.ProjectRevisionRead),
+        ], { concurrency: 4 });
+        const project = prefetchedProjects?.find((candidate) => candidate.id === projectId);
+        const catalogAccountId = prefetchedProjects?.[0]?.accountId;
         return {
             ...(project ? { project } : {}),
             ...(routing ? { routing } : {}),
             ...(drift ? { drift } : {}),
             ...(checkpoint ? { checkpoint } : {}),
-            ...(projectList && !project && accountId ? { missingOnAccountId: accountId } : {}),
+            ...(revisions ? { revisions } : {}),
+            ...(prefetchedProjects && !project && catalogAccountId
+                ? { missingOnAccountId: catalogAccountId }
+                : {}),
         };
     });
 }
 /** `hs-x status --project <id>` — the remote project view as a command body. */
-export function remoteStatusBody(opts, projectId) {
+export function remoteStatusBody(opts, projectId, prefetchedProjects) {
     return Effect.gen(function* () {
-        const remote = yield* fetchRemoteProjectStatus(opts, projectId);
+        const remote = yield* fetchRemoteProjectStatus(opts, projectId, prefetchedProjects);
         if (remote.missingOnAccountId && !remote.routing && !remote.drift && !remote.checkpoint) {
             return yield* failBespoke(opts.json, 'status', `No project ${projectId} on account ${remote.missingOnAccountId}. Find ids with \`hs-x list\`.`);
         }
@@ -465,9 +973,22 @@ export function remoteStatusBody(opts, projectId) {
     });
 }
 export function renderRemoteStatus(input) {
+    // Recorded revisions are the authoritative deploy history — a project can have
+    // many recorded deploys with nothing promoted, so `lastDeployAt` (from the
+    // project list, populated on promotion) is not a reliable "last deploy".
+    const recorded = input.revisions?.revisions ?? [];
+    const lastRecorded = recorded.length > 0 ? recorded[recorded.length - 1] : undefined;
+    const lastDeploy = input.project?.lastDeployAt ??
+        (lastRecorded ? `${lastRecorded.recordedAt} (${lastRecorded.deployId})` : undefined) ??
+        'none recorded';
     const lines = [
         `Project: ${input.projectId}${input.project ? ` (${input.project.displayName})` : ''}`,
-        `Last deploy: ${input.project?.lastDeployAt ?? 'none recorded'}`,
+        `Last deploy: ${lastDeploy}`,
+        ...(recorded.length > 0
+            ? [
+                `Deploys recorded: ${recorded.length} (active ${input.revisions?.activeDeployId ?? 'none'})`,
+            ]
+            : []),
     ];
     if (input.routing && input.routing.routes.length > 0) {
         const widest = Math.max(...input.routing.routes.map((route) => route.environment.length));
@@ -491,30 +1012,30 @@ export function renderRemoteStatus(input) {
     }
     return `${lines.join('\n')}\n`;
 }
-// ─── checkpoint / logs ────────────────────────────────────────────────────────
-/** Single Command value reused for both `checkpoint` and the `logs` alias. */
-function makeCheckpointCmd(name) {
-    return Command.make(name, cpReadOptions, (opts) => runHandler(name, { json: opts.json }, checkpointBody(name, opts)));
-}
-export const checkpointCmd = makeCheckpointCmd('checkpoint');
-export const logsCmd = makeCheckpointCmd('logs');
-function checkpointBody(commandName, opts) {
+// ─── checkpoint ───────────────────────────────────────────────────────────────
+export const checkpointCmd = Command.make('checkpoint', cpReadOptions, (opts) => runHandler('checkpoint', { json: opts.json }, checkpointBody(opts)));
+function checkpointBody(opts) {
     return Effect.gen(function* () {
-        const projectId = yield* resolveProjectId(opts);
+        const selection = yield* resolveOperationProjectForRead(opts, {
+            command: 'checkpoint',
+            message: 'Which project do you want to inspect?',
+            emptyMessage: 'No projects yet. Run `hs-x deploy` from a project to create one.',
+        });
+        const projectId = selection?.projectId;
         if (!projectId) {
-            return yield* failBespoke(opts.json, commandName, `${commandName === 'logs' ? 'Logs need' : 'Checkpoint status needs'} a project: ${PROJECT_ID_HINT}.`);
+            return yield* failBespoke(opts.json, 'checkpoint', `Checkpoint status needs a project: ${PROJECT_ID_HINT}.`);
         }
         const controlPlaneUrl = yield* resolveControlPlaneUrl(opts.controlPlaneUrl);
         const userId = yield* resolveUserId(opts);
         const response = yield* cpGet(controlPlaneUrl, `/v1/projects/${encodeURIComponent(projectId)}/checkpoint`, userId);
         const body = yield* Effect.promise(() => response.json());
         if (!response.ok) {
-            return yield* failBespoke(opts.json, commandName, responseMessage(body, response.status, 'Control-plane checkpoint status failed'));
+            return yield* failBespoke(opts.json, 'checkpoint', responseMessage(body, response.status, 'Control-plane checkpoint status failed'));
         }
         const checkpoint = Schema.decodeUnknownSync(schemas.CheckpointPanelRead)(body);
         const result = {
             ok: true,
-            command: commandName,
+            command: 'checkpoint',
             mode: 'control-plane-checkpoint',
             projectId,
             checkpoint,
@@ -527,8 +1048,459 @@ function checkpointBody(commandName, opts) {
         yield* reporter.header(projectId);
         yield* reporter.block(renderCheckpoint(checkpoint));
         yield* reporter.done();
+        yield* checkpointDrilldown(checkpoint, {
+            actions: {
+                logs: (failure) => logsBodyForCheckpoint(opts, selection ?? { projectId }, checkpoint, failure),
+                exemplar: (failure) => Effect.gen(function* () {
+                    yield* reporter.header(`${failure.errorClass} exemplar`);
+                    yield* reporter.block(renderCheckpointExemplar(failure));
+                    yield* reporter.done('Representative invocation');
+                }),
+            },
+        });
+    });
+}
+// ─── logs ─────────────────────────────────────────────────────────────────────
+const logsOptions = {
+    ...cpReadOptions,
+    limit: Options.integer('limit').pipe(Options.withDefault(50)),
+    sinceMinutes: Options.integer('since-minutes').pipe(Options.withDefault(15)),
+    trace: Options.text('trace').pipe(Options.withAlias('invocation'), Options.optional),
+    raw: Options.boolean('raw').pipe(Options.withDefault(false)),
+    filter: Options.text('filter').pipe(Options.repeated),
+    sample: Options.text('sample').pipe(Options.optional),
+    follow: Options.boolean('follow').pipe(Options.withAlias('tail'), Options.withDefault(false)),
+    intervalSeconds: Options.integer('interval-seconds').pipe(Options.withDefault(3)),
+    source: Options.text('source').pipe(Options.optional),
+    appId: Options.text('app-id').pipe(Options.optional),
+    type: Options.text('type').pipe(Options.repeated),
+    errorsOnly: Options.boolean('errors-only').pipe(Options.withDefault(false)),
+};
+const LOG_SELECTOR_FLAGS = [
+    '--source',
+    '--project',
+    '--project-id',
+    '--app-id',
+    '--type',
+    '--since-minutes',
+    '--limit',
+    '--trace',
+    '--invocation',
+    '--raw',
+    '--filter',
+    '--sample',
+    '--follow',
+    '--tail',
+    '--errors-only',
+];
+function hasExplicitLogSelector(argv = process.argv.slice(2)) {
+    return argv.some((arg) => LOG_SELECTOR_FLAGS.some((flag) => arg === flag || arg.startsWith(`${flag}=`)));
+}
+function isErrorLogRow(row) {
+    if (row.level === 'error' || row.errorType)
+        return true;
+    if (typeof row.status === 'number' && row.status >= 400)
+        return true;
+    return typeof row.outcome === 'string' && row.outcome !== 'ok';
+}
+function parseLogSource(value) {
+    const normalized = (value ?? 'all').toLowerCase();
+    if (normalized === 'all' || normalized === 'merged') {
+        return { ok: true, wantWorkers: true, wantHubspot: true };
+    }
+    if (normalized === 'workers' || normalized === 'cf' || normalized === 'cloudflare') {
+        return { ok: true, wantWorkers: true, wantHubspot: false };
+    }
+    if (normalized === 'hubspot' || normalized === 'hs') {
+        return { ok: true, wantWorkers: false, wantHubspot: true };
+    }
+    return { ok: false, message: `Invalid --source "${value}". Use all, workers, or hubspot.` };
+}
+export const logsCmd = Command.make('logs', logsOptions, (opts) => runHandler('logs', { json: opts.json }, logsBody(opts)));
+function resolveAccountId(opts, localAccountId) {
+    return Effect.gen(function* () {
+        const explicit = yield* resolveFromOptionOrEnv(opts.accountId, 'HSX_ACCOUNT_ID');
+        if (explicit)
+            return explicit;
+        if (localAccountId)
+            return localAccountId;
+        const accounts = yield* AccountStore;
+        const store = yield* accounts.load;
+        return store.defaultAccountId;
     });
 }
+/** Actionable remediation for the known Workers Logs error slugs. */
+function workersErrorHint(error) {
+    if (error === 'cloudflare_credential_invalid') {
+        return 'the stored Cloudflare credential was rejected (expired or revoked) — reconnect with `hs-x connect cloudflare`';
+    }
+    if (error === 'observability_permission_missing') {
+        return 'the stored Cloudflare token cannot read Workers Observability — reconnect with `hs-x connect cloudflare`, or use an API token with the Workers Observability read permission';
+    }
+    if (error === 'cloudflare_not_connected') {
+        return 'no Cloudflare account is connected — run `hs-x connect cloudflare`';
+    }
+    return undefined;
+}
+function withWorkersErrorHint(error) {
+    const hint = workersErrorHint(error);
+    return hint ? `${error} (${hint})` : error;
+}
+function logsBody(opts, context = {}) {
+    return Effect.gen(function* () {
+        const cwd = yield* Cwd;
+        const localProjectBinding = yield* Effect.promise(() => readProjectBinding(cwd));
+        const requestedSource = parseLogSource(Option.getOrUndefined(opts.source));
+        const shouldResolveWorkersProject = requestedSource.ok && requestedSource.wantWorkers;
+        const projectSelection = shouldResolveWorkersProject
+            ? (context.projectSelection ??
+                (yield* resolveOperationProjectForRead(opts, {
+                    command: 'logs',
+                    message: 'Which project do you want logs for?',
+                    emptyMessage: 'No projects yet. Run `hs-x deploy` from a project to create one.',
+                })))
+            : undefined;
+        const currentProjectId = projectSelection?.projectId ??
+            (yield* resolveProjectId(opts)) ??
+            localProjectBinding?.projectId;
+        const accountId = projectSelection?.accountId ??
+            (yield* resolveAccountId(opts, localProjectBinding?.accountId));
+        const controlPlaneUrl = yield* resolveControlPlaneUrl(opts.controlPlaneUrl);
+        const userId = yield* resolveUserId(opts);
+        const shouldPrompt = !opts.json &&
+            isInteractive() &&
+            (context.forceInteractiveSetup === true || !hasExplicitLogSelector());
+        let interactiveSelection = undefined;
+        if (shouldPrompt) {
+            if (!accountId) {
+                return yield* failBespoke(false, 'logs', 'Logs require an HS-X account: run `hs-x login`, or pass --account-id / HSX_ACCOUNT_ID.');
+            }
+            if (!currentProjectId) {
+                return yield* failBespoke(false, 'logs', `Logs need a project: ${PROJECT_ID_HINT}.`);
+            }
+            interactiveSelection = yield* Effect.promise(() => promptInteractiveLogsSelection({
+                projects: projectSelection?.projects ?? [],
+                selectedProjectId: currentProjectId,
+                ...(localProjectBinding?.projectId
+                    ? { hubspotProjectId: localProjectBinding.projectId }
+                    : {}),
+            }));
+            if (!interactiveSelection) {
+                return yield* Effect.fail(exitWith(130));
+            }
+        }
+        const projectId = interactiveSelection?.projectId ?? currentProjectId;
+        const parsedFilters = parseLogFilters(opts.filter);
+        if (!parsedFilters.ok) {
+            return yield* failBespoke(opts.json, 'logs', parsedFilters.message);
+        }
+        const parsedSample = parseSampleRate(Option.getOrUndefined(opts.sample));
+        if (!parsedSample.ok) {
+            return yield* failBespoke(opts.json, 'logs', parsedSample.message);
+        }
+        const follow = interactiveSelection?.follow ?? opts.follow;
+        const errorsOnly = interactiveSelection?.errorsOnly ?? opts.errorsOnly;
+        const parsedSystemTypes = interactiveSelection?.systemTypes
+            ? { ok: true, systemTypes: interactiveSelection.systemTypes }
+            : parseHubSpotLogSystemTypes(opts.type);
+        if (!parsedSystemTypes.ok) {
+            return yield* failBespoke(opts.json, 'logs', parsedSystemTypes.message);
+        }
+        if (follow && opts.json) {
+            return yield* failBespoke(opts.json, 'logs', '`hs-x logs --follow`/`--tail` streams terminal output. Omit --json for follow mode.');
+        }
+        const sourceChoice = parseLogSource(interactiveSelection?.source ?? Option.getOrUndefined(opts.source));
+        if (!sourceChoice.ok) {
+            return yield* failBespoke(opts.json, 'logs', sourceChoice.message);
+        }
+        const { wantWorkers, wantHubspot } = sourceChoice;
+        // The two sources resolve independently: Workers Logs need an HS-X account
+        // and project id (the control plane mediates the read); HubSpot app logs
+        // need only the local `.hs-x/hubspot.json` binding plus PAK credentials.
+        // A missing prerequisite is fatal only when it leaves no source at all.
+        const explicitAppId = Option.getOrUndefined(opts.appId);
+        const selectedDifferentProject = projectSelection?.projects !== undefined && localProjectBinding?.projectId !== projectId;
+        const hubspotResolution = wantHubspot
+            ? selectedDifferentProject && explicitAppId === undefined
+                ? {
+                    ok: false,
+                    reason: 'the selected project is not the project in the current directory; pass --app-id to include its HubSpot app logs',
+                }
+                : yield* Effect.promise(() => resolveHubSpotLogsSource({
+                    cwd,
+                    ...(explicitAppId !== undefined ? { appId: explicitAppId } : {}),
+                }))
+            : undefined;
+        const hubspotSource = hubspotResolution?.ok
+            ? hubspotResolution.source
+            : undefined;
+        const hubspotReason = hubspotResolution && !hubspotResolution.ok ? hubspotResolution.reason : undefined;
+        const workersReason = !wantWorkers
+            ? 'not requested (--source hubspot)'
+            : !accountId
+                ? 'no HS-X account (run `hs-x login`, or pass --account-id / HSX_ACCOUNT_ID)'
+                : !projectId
+                    ? 'no project id'
+                    : undefined;
+        const workersActive = workersReason === undefined;
+        if (!workersActive && !hubspotSource) {
+            if (wantWorkers && !accountId) {
+                return yield* failBespoke(opts.json, 'logs', 'Logs require an HS-X account: run `hs-x login`, or pass --account-id / HSX_ACCOUNT_ID.');
+            }
+            if (wantWorkers && !projectId) {
+                return yield* failBespoke(opts.json, 'logs', `Logs need a project: ${PROJECT_ID_HINT}.`);
+            }
+            return yield* failBespoke(opts.json, 'logs', `HubSpot app logs unavailable: ${hubspotReason ?? 'unknown'}.`);
+        }
+        const trace = Option.getOrUndefined(opts.trace);
+        const limit = clampInt(opts.limit, 1, 200);
+        const sinceMinutes = clampInt(interactiveSelection?.sinceMinutes ?? opts.sinceMinutes, 1, 7 * 24 * 60);
+        const intervalSeconds = clampInt(opts.intervalSeconds, 1, 60);
+        const view = trace ? 'trace' : opts.raw ? 'tail' : 'invocations';
+        // Legacy single-source semantics only when Workers Logs is the sole
+        // source: a control-plane failure hard-fails exactly as before. With a
+        // second source in play, each side degrades to a warning instead.
+        const strictWorkers = workersActive && !hubspotSource;
+        const fetchWorkers = Effect.gen(function* () {
+            const params = new URLSearchParams({ sinceMinutes: String(sinceMinutes) });
+            if (trace) {
+                params.set('invocation', trace);
+            }
+            else {
+                // Workers Observability does not yet expose an errors-only predicate,
+                // so read its maximum page before filtering to avoid hiding an error
+                // behind a page of newer successful requests.
+                params.set('limit', String(errorsOnly ? 200 : limit));
+                if (!opts.raw)
+                    params.set('view', 'invocations');
+            }
+            const response = yield* cpGet(controlPlaneUrl, `/v1/accounts/${encodeURIComponent(accountId ?? '')}/projects/${encodeURIComponent(projectId ?? '')}/tail?${params.toString()}`, userId);
+            const body = yield* Effect.promise(() => response.json());
+            if (!response.ok) {
+                const message = responseMessage(body, response.status, 'Control-plane logs read failed');
+                if (strictWorkers) {
+                    yield* failBespoke(opts.json, 'logs', message);
+                    return { rows: [] };
+                }
+                return { rows: [], error: message };
+            }
+            return asLogsPayload(body);
+        });
+        const fetchHubspot = hubspotSource
+            ? Effect.promise(() => fetchHubSpotLogsPayload({
+                source: hubspotSource,
+                sinceMinutes,
+                limit,
+                systemTypes: parsedSystemTypes.systemTypes,
+                errorsOnly,
+                ...(trace ? { trace } : {}),
+            }).catch((cause) => ({
+                rows: [],
+                error: cause instanceof Error ? cause.message : String(cause),
+            })))
+            : Effect.succeed(undefined);
+        const fetchPayload = Effect.gen(function* () {
+            const [workers, hubspot] = yield* Effect.all([workersActive ? fetchWorkers : Effect.succeed(undefined), fetchHubspot], { concurrency: 2 });
+            const workersRows = errorsOnly
+                ? (workers?.rows ?? []).filter(isErrorLogRow)
+                : (workers?.rows ?? []);
+            const hubspotRows = errorsOnly
+                ? (hubspot?.rows ?? []).filter(isErrorLogRow)
+                : (hubspot?.rows ?? []);
+            const filteredWorkers = applyLogFilters(workersRows, parsedFilters.filters, parsedSample.rate);
+            const filteredHubspot = applyLogFilters(hubspotRows, parsedFilters.filters, parsedSample.rate);
+            const rows = hubspotSource
+                ? mergeLogRows(filteredWorkers, filteredHubspot, trace ? Number.MAX_SAFE_INTEGER : limit)
+                : trace
+                    ? filteredWorkers
+                    : filteredWorkers.slice(0, limit);
+            const workersError = workers?.error;
+            const hubspotError = hubspot && 'error' in hubspot ? hubspot.error : undefined;
+            const allFailed = (workersActive ? workersError !== undefined : true) &&
+                (hubspotSource ? hubspotError !== undefined : true);
+            const failedSystemTypes = hubspot && 'failedSystemTypes' in hubspot
+                ? hubspot.failedSystemTypes
+                : undefined;
+            return {
+                rows,
+                ...(allFailed ? { fatalError: workersError ?? hubspotError ?? 'log read failed' } : {}),
+                ...(workersError !== undefined ? { workersError } : {}),
+                ...(hubspotError !== undefined ? { hubspotError } : {}),
+                ...(failedSystemTypes && failedSystemTypes.length > 0
+                    ? { hubspotFailedSystemTypes: failedSystemTypes }
+                    : {}),
+            };
+        });
+        const payload = yield* fetchPayload;
+        const mode = workersActive && hubspotSource
+            ? 'merged-logs'
+            : hubspotSource
+                ? 'hubspot-app-logs'
+                : 'workers-logs';
+        const result = {
+            ok: !payload.fatalError,
+            command: 'logs',
+            mode,
+            view,
+            ...(accountId ? { accountId } : {}),
+            ...(projectId ? { projectId } : {}),
+            sinceMinutes,
+            limit,
+            ...(wantHubspot ? { hubspotLogTypes: parsedSystemTypes.systemTypes } : {}),
+            ...(errorsOnly ? { errorsOnly: true } : {}),
+            ...(parsedFilters.filters.length > 0 ? { filters: parsedFilters.filters } : {}),
+            ...(parsedSample.rate !== undefined ? { sample: parsedSample.rate } : {}),
+            ...(trace ? { invocationId: trace } : {}),
+            sources: {
+                workers: {
+                    active: workersActive,
+                    ...(workersReason !== undefined ? { reason: workersReason } : {}),
+                    ...(payload.workersError !== undefined ? { error: payload.workersError } : {}),
+                },
+                hubspot: hubspotSource
+                    ? {
+                        active: true,
+                        appId: hubspotSource.appId,
+                        developerAccountId: hubspotSource.developerAccountId,
+                        ...(payload.hubspotError !== undefined ? { error: payload.hubspotError } : {}),
+                        ...(payload.hubspotFailedSystemTypes
+                            ? { failedSystemTypes: payload.hubspotFailedSystemTypes }
+                            : {}),
+                    }
+                    : {
+                        active: false,
+                        ...(wantHubspot && hubspotReason !== undefined
+                            ? { reason: hubspotReason }
+                            : { reason: 'not requested (--source workers)' }),
+                    },
+            },
+            rows: payload.rows,
+            ...(payload.fatalError ? { error: payload.fatalError } : {}),
+        };
+        const reporter = yield* Reporter;
+        const showOrigin = hubspotSource !== undefined && workersActive;
+        const reportPartialFailures = Effect.gen(function* () {
+            if (!payload.fatalError && payload.workersError !== undefined) {
+                yield* reporter.info(`Workers Logs unavailable this read: ${withWorkersErrorHint(payload.workersError)}`);
+            }
+            if (!payload.fatalError && hubspotSource && payload.hubspotError !== undefined) {
+                yield* reporter.info(`HubSpot app logs unavailable this read: ${payload.hubspotError}`);
+            }
+            if (payload.hubspotFailedSystemTypes && payload.hubspotFailedSystemTypes.length > 0) {
+                yield* reporter.info(`HubSpot log types skipped (query failed): ${payload.hubspotFailedSystemTypes.join(', ')}`);
+            }
+            if (wantHubspot && !hubspotSource && workersActive && hubspotReason !== undefined) {
+                yield* reporter.info(`HubSpot app logs skipped: ${hubspotReason}.`);
+            }
+        });
+        const headerLabel = projectId ?? hubspotSource?.projectName ?? `app ${hubspotSource?.appId}`;
+        if (follow) {
+            const seen = new Set();
+            yield* reporter.header(trace ? `${headerLabel} invocation ${trace}` : `${headerLabel} live`);
+            const printNewRows = (rows) => Effect.gen(function* () {
+                const fresh = orderLogRowsAscending(rows.filter((row) => {
+                    const key = stableLogRowKey(row);
+                    if (seen.has(key))
+                        return false;
+                    seen.add(key);
+                    return true;
+                }));
+                if (fresh.length > 0) {
+                    yield* emitLogRows(reporter, fresh, view, showOrigin);
+                }
+            });
+            yield* printNewRows(payload.rows);
+            yield* reportPartialFailures;
+            if (payload.fatalError) {
+                yield* reporter.error('HSX_E_LOGS_UNAVAILABLE', `Logs unavailable: ${withWorkersErrorHint(payload.fatalError)}`);
+                return yield* Effect.fail(exitWith(1, 'HSX_E_LOGS_UNAVAILABLE'));
+            }
+            while (true) {
+                yield* Effect.promise(() => new Promise((resolve) => setTimeout(resolve, intervalSeconds * 1000)));
+                const next = yield* fetchPayload;
+                yield* printNewRows(next.rows);
+                if (next.fatalError) {
+                    yield* reporter.error('HSX_E_LOGS_UNAVAILABLE', `Logs unavailable: ${withWorkersErrorHint(next.fatalError)}`);
+                    return yield* Effect.fail(exitWith(1, 'HSX_E_LOGS_UNAVAILABLE'));
+                }
+            }
+        }
+        if (opts.json) {
+            yield* reporter.raw(`${JSON.stringify(result, null, 2)}\n`);
+            if (payload.fatalError)
+                return yield* Effect.fail(exitWith(1, 'HSX_E_LOGS_UNAVAILABLE'));
+            return;
+        }
+        yield* reporter.header(trace ? `${headerLabel} invocation ${trace}` : headerLabel);
+        yield* emitLogRows(reporter, payload.rows, view, showOrigin);
+        yield* reportPartialFailures;
+        if (payload.fatalError) {
+            yield* reporter.error('HSX_E_LOGS_UNAVAILABLE', `Logs unavailable: ${withWorkersErrorHint(payload.fatalError)}`);
+            return yield* Effect.fail(exitWith(1, 'HSX_E_LOGS_UNAVAILABLE'));
+        }
+        yield* reporter.done(`${payload.rows.length} row${payload.rows.length === 1 ? '' : 's'}`, 0, view === 'invocations' && payload.rows.length > 0 ? logRowCounts(payload.rows) : undefined);
+    });
+}
+function optionsForSelectedProject(opts, selection) {
+    return {
+        json: false,
+        controlPlaneUrl: opts.controlPlaneUrl,
+        userId: opts.userId,
+        projectId: Option.some(selection.projectId),
+        accountId: selection.accountId ? Option.some(selection.accountId) : opts.accountId,
+    };
+}
+function checkpointWindowMinutes(checkpoint) {
+    const from = Date.parse(checkpoint.window.from);
+    const to = Date.parse(checkpoint.window.to);
+    if (!Number.isFinite(from) || !Number.isFinite(to) || to <= from)
+        return 24 * 60;
+    return clampInt(Math.ceil((to - from) / 60_000), 1, 7 * 24 * 60);
+}
+/** In-process logs view used by the human checkpoint failure drill-down. */
+export function logsBodyForCheckpoint(opts, selection, checkpoint, failure) {
+    const selected = optionsForSelectedProject(opts, selection);
+    return logsBody({
+        ...selected,
+        limit: 50,
+        sinceMinutes: checkpointWindowMinutes(checkpoint),
+        trace: Option.none(),
+        raw: false,
+        filter: [`target=${failure.capabilityId}`],
+        sample: Option.none(),
+        follow: false,
+        intervalSeconds: 3,
+        source: Option.some('workers'),
+        appId: Option.none(),
+        type: [],
+        errorsOnly: true,
+    }, { projectSelection: selection });
+}
+/** In-process command bodies used by the human status drill-down. */
+export function logsBodyForStatus(opts, selection) {
+    const selected = optionsForSelectedProject(opts, selection);
+    return logsBody({
+        ...selected,
+        limit: 50,
+        sinceMinutes: 15,
+        trace: Option.none(),
+        raw: false,
+        filter: [],
+        sample: Option.none(),
+        follow: false,
+        intervalSeconds: 3,
+        source: Option.none(),
+        appId: Option.none(),
+        type: [],
+        errorsOnly: false,
+    }, { projectSelection: selection, forceInteractiveSetup: true });
+}
+export function routesBodyForStatus(opts, selection) {
+    return routingBody('routes', optionsForSelectedProject(opts, selection));
+}
+export function driftBodyForStatus(opts, selection) {
+    return driftBody(optionsForSelectedProject(opts, selection));
+}
 // ─── routing / route / routes ──────────────────────────────────────────────────
 /** Single Command value reused for `routing`, the `route` alias, and `routes`. */
 function makeRoutingCmd(name) {
@@ -540,7 +1512,12 @@ export const routesCmd = makeRoutingCmd('routes');
 function routingBody(commandName, opts) {
     return Effect.gen(function* () {
         const reportName = commandName === 'routes' ? 'routes' : 'routing';
-        const projectId = yield* resolveProjectId(opts);
+        const selection = yield* resolveOperationProjectForRead(opts, {
+            command: reportName,
+            message: 'Which project do you want routing for?',
+            emptyMessage: 'No projects yet. Run `hs-x deploy` from a project to create one.',
+        });
+        const projectId = selection?.projectId;
         if (!projectId) {
             return yield* failBespoke(opts.json, reportName, `${commandName === 'routes' ? 'Routes need' : 'Routing status needs'} a project: ${PROJECT_ID_HINT}.`);
         }