runcloud 0.2.165 → 0.2.166

package/dist/commands/run-cloud-fleet.js

@@ -0,0 +1,447 @@
+import { readFileSync, statSync } from 'node:fs';
+import { ApiClient, ApiError } from '../api.js';
+import { requireCredentials } from '../config.js';
+const ROOT = '/run-cloud/admin/simulators';
+const RANGES = ['1h', '6h', '24h', '7d', '30d', '90d', '1y', '2y'];
+export const ACCESSIBILITY_CODES = ['accessibility_device_unavailable', 'accessibility_capture_failed'];
+const row = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+const rows = (value) => Array.isArray(value) ? value.map(row) : [];
+const str = (value) => typeof value === 'string' && value.length > 0 ? value : null;
+const num = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+const stamp = (value) => str(value) && Number.isFinite(Date.parse(String(value))) ? new Date(String(value)).toISOString() : null;
+const time = (value) => stamp(value) ? Date.parse(String(value)) : 0;
+export function safeFleetText(value) {
+    const text = str(value);
+    return text ? text.slice(0, 8000)
+        .replace(/\bBearer\s+[^\s"'<>]+/gi, 'Bearer [redacted]')
+        .replace(/\b(?:rc_live_|rcsf_|rc_dev_)[A-Za-z0-9_.-]+/g, '[redacted]')
+        .replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/g, '[redacted]')
+        .replace(/\b([a-zA-Z0-9_]*(?:token|password|secret|api[_-]?key)|authorization)\s*[=:]\s*[^\s,;]+/gi, '$1=[redacted]')
+        .replace(/(?:https?|wss?):\/\/[^\s<>"']+/gi, '[url redacted]') : null;
+}
+function observation(value, now, ttl, error) {
+    const observedAt = stamp(value);
+    const ageSeconds = observedAt ? Math.round((now - Date.parse(observedAt)) / 1000) : null;
+    if (error)
+        return { observedAt, ageSeconds, state: 'unavailable', reason: 'collection_failed; retained evidence only' };
+    if (!observedAt)
+        return { observedAt, ageSeconds, state: 'missing', reason: 'observation_timestamp_missing' };
+    if (ageSeconds < -5)
+        return { observedAt, ageSeconds, state: 'unavailable', reason: 'observation_timestamp_in_future' };
+    return { observedAt, ageSeconds, state: ageSeconds > ttl ? 'stale' : 'fresh', reason: ageSeconds > ttl ? 'observation_expired' : null };
+}
+function hostedObservation(host, now, ttl) {
+    const heartbeat = observation(host.observedAt, now, ttl);
+    const freshness = row(host.freshness);
+    if (!Object.keys(freshness).length)
+        return { ...heartbeat, ingestion: null, reportedFreshness: null };
+    const ingestion = observation(freshness.lastSuccessfulUpdateAt, now, ttl);
+    const reportedFreshness = str(freshness.status);
+    if (heartbeat.state === 'fresh' && (reportedFreshness !== 'fresh' || ingestion.state !== 'fresh')) {
+        const state = ingestion.state === 'unavailable' ? 'unavailable' : reportedFreshness === 'never' ? 'missing' : 'stale';
+        return { ...heartbeat, state: state, reason: `hosted_ingestion_${ingestion.state === 'fresh' ? reportedFreshness ?? 'unknown' : ingestion.state}`, ingestion, reportedFreshness };
+    }
+    return { ...heartbeat, ingestion, reportedFreshness };
+}
+function bound(value, fallback, max, name) {
+    const result = value ?? fallback;
+    if (!Number.isSafeInteger(result) || result < 1 || result > max)
+        throw new Error(`${name} must be an integer from 1 to ${max}`);
+    return result;
+}
+function validate(options) {
+    if (!RANGES.includes(options.range ?? '24h'))
+        throw new Error(`range must be ${RANGES.join(', ')}`);
+    if (options.hostId && !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/.test(options.hostId))
+        throw new Error('Invalid host ID');
+    if (options.deep && !options.hostId)
+        throw new Error('--deep requires a host ID');
+    bound(options.limit, 200, 500, 'limit');
+    bound(options.eventPages, 1, 10, 'event-pages');
+}
+async function readSource(client, path) {
+    try {
+        const data = await client.get(path, { signal: AbortSignal.timeout(30000) });
+        if (!data || typeof data !== 'object' || Array.isArray(data) || data instanceof Response)
+            return { state: 'unavailable', data: {}, reason: 'invalid_json_response' };
+        return { state: 'available', data: row(data), reason: null };
+    }
+    catch (error) {
+        return { state: 'unavailable', data: {}, reason: error instanceof ApiError ? `HTTP ${error.status}` : 'read_failed' };
+    }
+}
+export async function readFleetEvents(client, options = {}) {
+    validate(options);
+    const items = [];
+    let cursor = null, pagesRead = 0, reason = null, generatedAt = null;
+    const cursors = new Set();
+    for (let page = 0; page < (options.eventPages ?? 1); page++) {
+        const query = new URLSearchParams({ range: options.range ?? '24h', limit: String(options.limit ?? 200) });
+        if (options.hostId)
+            query.set('hostId', options.hostId);
+        if (cursor)
+            query.set('cursor', cursor);
+        const result = await readSource(client, `${ROOT}/events?${query}`);
+        if (result.state === 'unavailable') {
+            reason = result.reason;
+            break;
+        }
+        if (!Array.isArray(result.data.items)) {
+            reason = 'invalid_events_response';
+            break;
+        }
+        generatedAt ??= stamp(result.data.generatedAt);
+        items.push(...rows(result.data.items));
+        pagesRead++;
+        cursor = str(result.data.nextCursor);
+        if (!cursor)
+            break;
+        if (cursors.has(cursor)) {
+            reason = 'repeated_event_cursor';
+            break;
+        }
+        cursors.add(cursor);
+    }
+    return { items, coverage: { range: options.range ?? '24h', pagesRead, rowsRead: items.length,
+            complete: reason === null && cursor === null && pagesRead > 0, nextCursor: cursor,
+            reason: reason ?? (cursor ? 'page_budget_reached; matching failures may be outside returned pages' : null), generatedAt,
+            oldestReturnedAt: stamp(items.at(-1)?.timestamp), newestReturnedAt: stamp(items[0]?.timestamp) } };
+}
+function componentHosts(shared) {
+    const result = new Map();
+    const snapshots = rows(shared.snapshots).map(entry => row(entry.snapshot));
+    for (const snapshot of snapshots)
+        for (const host of rows(snapshot.hosts)) {
+            const id = str(host.id);
+            if (!id)
+                continue;
+            const before = result.get(id) ?? {};
+            const newest = !result.has(id) || time(host.observedAt) > time(before.observedAt) ? host : before;
+            const merged = { ...before, ...newest };
+            for (const key of ['hostTelemetry', 'hostDiagnostics', 'processScan']) {
+                const candidate = row(host[key]), previous = row(before[key]);
+                const observationKey = key === 'processScan' ? 'attemptedAt' : 'observedAt';
+                merged[key] = time(candidate[observationKey] ?? candidate.observedAt) > time(previous[observationKey] ?? previous.observedAt) ? candidate : previous;
+            }
+            result.set(id, merged);
+        }
+    return result;
+}
+function cpuReading(host, extra, now, fleetTtl) {
+    const telemetry = row(extra.hostTelemetry), cpu = row(telemetry.cpu);
+    const cpuValue = (value) => num(value) !== null && Number(value) <= 100 ? Number(value) : null;
+    const candidates = [
+        { percent: cpuValue(cpu.busyPercent), source: 'operator_resource_probe', ...observation(telemetry.observedAt, now, num(telemetry.staleAfterSeconds) ?? 45, telemetry.collectionError) },
+        { percent: cpuValue(host.cpuUtilizationPercent), source: 'host_heartbeat', ...hostedObservation(host, now, fleetTtl) },
+    ].map(entry => entry.percent === null && entry.state === 'fresh' ? { ...entry, state: 'missing', reason: 'cpu_value_missing' } : entry);
+    candidates.sort((a, b) => Number(b.state === 'fresh') - Number(a.state === 'fresh') || time(b.observedAt) - time(a.observedAt));
+    return { ...candidates[0], candidates, meaning: 'host busy percent, 0..100; fresh samples only in fleet mean' };
+}
+const pick = (source, keys) => Object.fromEntries(keys.filter(key => source[key] !== undefined).map(key => [key, source[key]]));
+function fence(value) {
+    const source = row(value);
+    return Object.keys(source).length ? { ...pick(source, ['id', 'kind', 'state', 'createdAt', 'expiresAt', 'component']), reason: safeFleetText(source.reason) } : null;
+}
+function hostReport(host, canonical, extra, diagnoses, now, fleetTtl, deep = {}) {
+    const id = String(host.id ?? canonical.id ?? extra.id);
+    const health = hostedObservation(host, now, fleetTtl);
+    const diagnostic = row(extra.hostDiagnostics), process = row(extra.processScan);
+    const supplementalChecks = observation(diagnostic.observedAt, now, num(diagnostic.staleAfterSeconds) ?? 900, diagnostic.collectionError);
+    const deepChecks = observation(row(deep.security).checkedAt, now, fleetTtl);
+    const useDeep = deepChecks.state === 'fresh' && Array.isArray(deep.services) && deep.services.length > 0 && time(deepChecks.observedAt) > time(supplementalChecks.observedAt);
+    const checks = useDeep ? deepChecks : supplementalChecks;
+    const processCheck = observation(process.observedAt, now, num(process.staleAfterSeconds) ?? 900, process.error);
+    const release = row(host.release);
+    const services = rows(useDeep ? deep.services : diagnostic.services).map(service => ({ name: safeFleetText(service.name), state: safeFleetText(service.state), lastExitCode: service.lastExitCode ?? null,
+        error: safeFleetText(service.lastError ?? service.error) }));
+    const faults = checks.state === 'fresh' ? services.filter(service => ['stopped', 'failed', 'crashed', 'inactive', 'missing', 'exited', 'disabled'].includes(service.state ?? '')) : [];
+    const findings = rows(process.findings).map(finding => ({ ...pick(finding, ['fingerprint', 'reason', 'confidence', 'firstObservedAt', 'lastObservedAt', 'ownerUid', 'ageSeconds']), message: safeFleetText(finding.message ?? finding.summary) }));
+    const diagnosesForHost = diagnoses.filter(diagnosis => diagnosis.hostId === id).map(diagnosis => ({ ...pick(diagnosis, ['code', 'severity', 'deviceId']),
+        title: safeFleetText(diagnosis.title), message: safeFleetText(diagnosis.message), reportedAt: stamp(diagnosis.observedAt) }));
+    const requestedFence = fence(canonical.requestedFence ?? host.requestedFence), appliedFence = fence(canonical.fence ?? host.fence);
+    const state = health.state === 'fresh' ? str(host.state) ?? 'unknown' : 'unknown';
+    const sentences = [`${id}: ${state}${health.state === 'fresh' ? '' : ` (${health.state} heartbeat)`}.`];
+    if (appliedFence || requestedFence)
+        sentences.push(`Hold ${appliedFence ? 'reported applied' : 'requested'}; admission evidence is separate.`);
+    if (health.state === 'fresh' && release.matches === false)
+        sentences.push('Release drift reported.');
+    if (faults.length)
+        sentences.push(`Service faults: ${faults.map(service => `${service.name} ${service.state}`).join(', ')}.`);
+    if (checks.state !== 'fresh')
+        sentences.push(`Service checks ${checks.state}; current service health unproved.`);
+    if (processCheck.state !== 'fresh')
+        sentences.push(`Process checks ${processCheck.state}.`);
+    if (process.status === 'critical' || rows(process.iocs).some(ioc => ioc.status === 'present') || rows(process.findings).some(finding => finding.reason === 'known_ioc'))
+        sentences.push('Known malicious scanner evidence retained; inspect signals and scan age.');
+    else if (rows(process.findings).some(finding => ['rooted_workload', 'long_lived_workload', 'identity_changed', 'unreviewed_persistence'].includes(String(finding.reason))))
+        sentences.push('Process identities require review; inspect findings and scan age.');
+    if (rows(process.iocs).some(ioc => ioc.contained === true))
+        sentences.push('Contained IOC evidence retained.');
+    const cpu = cpuReading(host, extra, now, fleetTtl);
+    sentences.push(cpu.state === 'fresh' ? `CPU ${cpu.percent.toFixed(1)}%.` : `CPU ${cpu.state}.`);
+    return { id, name: safeFleetText(canonical.name ?? host.name ?? extra.name), platform: canonical.platform ?? host.platform ?? extra.platform ?? null,
+        role: canonical.machineType ?? extra.role ?? null, inventoryPresent: Object.keys(canonical).length > 0, livePresent: Object.keys(host).length > 0,
+        health: { reportedState: str(host.state), effectiveState: state, ...health }, diagnosis: sentences.join(' '), cpu,
+        release: { ...pick(release, ['expectedPackage', 'actualPackage', 'expectedVersion', 'actualVersion', 'expectedBuild', 'actualBuild', 'matches']), version: str(host.version), build: str(host.build), observedAt: stamp(host.observedAt) },
+        admission: { enabled: canonical.enabled ?? null, acceptsLeases: canonical.acceptsLeases ?? null, observedAt: stamp(canonical.admissionObservedAt), reason: safeFleetText(canonical.admissionReason), requestedFence, fence: appliedFence },
+        capacity: pick(row(host.capacity), ['clean', 'leased', 'installing', 'dirty', 'preparing', 'recycling', 'total']),
+        serviceChecks: { ...checks, source: useDeep ? 'hosted_deep_evidence' : 'operator_diagnostics', services,
+            software: { ...pick(row(diagnostic.software), ['serveSimPackage', 'serveSimVersion', 'serveSimRevision', 'xcodeVersion']), observation: supplementalChecks, packageMatchesService: diagnostic.packageMatchesService ?? null } },
+        processChecks: { ...processCheck, ...pick(process, ['attemptedAt', 'inventoryObservedAt', 'maxVariableAgeSeconds', 'root', 'mode', 'coverage', 'counts']),
+            status: process.status ?? null, baseline: pick(row(process.baseline), ['state', 'profileIds', 'methods']),
+            transportTrust: pick(row(process.transportTrust), ['state', 'verifiedAt', 'pinsSha256']), findings,
+            iocs: rows(process.iocs).map(ioc => ({ ...pick(ioc, ['family', 'status', 'contained', 'lastObservedAt']), signals: Array.isArray(ioc.signals) ? ioc.signals.map(safeFleetText) : [] })) },
+        resources: { ...observation(row(extra.hostTelemetry).observedAt, now, 45, row(extra.hostTelemetry).collectionError),
+            memory: pick(row(row(extra.hostTelemetry).memory), ['totalBytes', 'usedBytes', 'availableBytes', 'swapUsedBytes']),
+            perDeviceCpu: rows(row(row(extra.hostTelemetry).cpu).perDevice).map(device => pick(device, ['id', 'cpuPercent', 'rssBytes', 'processes'])),
+            processCpuMeaning: 'OS process percent may exceed 100 on multicore hosts; independent from host busy percent' },
+        devices: rows(host.devices).map(device => ({ id: str(device.id), ...pick(device, ['state', 'sessionId', 'leaseId', 'updatedAt']), helper: {
+                ...pick(row(device.helper), ['state', 'pid', 'lastSeenAt']), observation: observation(row(device.helper).lastSeenAt, now, fleetTtl),
+                observationMeaning: 'last helper evidence; freshness uses fleet heartbeat threshold', error: safeFleetText(row(device.helper).error)
+            }, lastError: safeFleetText(device.lastError) })),
+        diagnoses: diagnosesForHost,
+    };
+}
+function originalLogsUrl(value) {
+    try {
+        const url = new URL(String(value));
+        return url.protocol === 'https:' && url.hostname === 'console.cloud.google.com' && url.pathname.startsWith('/logs/') &&
+            !url.username && !url.password && !/token|secret|signature|api.?key|credential/i.test(url.search) ? url.href : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function failureEvidence(value) {
+    const entry = row(value), payload = row(entry.jsonPayload ?? entry), context = { ...row(payload.context), ...row(payload.metadata), ...payload };
+    let error = row(context.err ?? context.error);
+    const errorProviderSessionId = str(error.sessionId);
+    const causeCodes = Array.isArray(context.causeCodes) ? context.causeCodes.filter(value => typeof value === 'string') : [];
+    const errorChain = [];
+    for (let depth = 0; depth < 8 && Object.keys(error).length; depth++) {
+        if (str(error.code))
+            causeCodes.push(String(error.code));
+        errorChain.push({ ...pick(error, ['code', 'httpStatus', 'status', 'retryable', 'stage']), message: safeFleetText(error.message) });
+        error = row(error.cause);
+    }
+    const service = str(row(row(entry.resource).labels).service_name) ?? '';
+    const session = str(context.sessionId), explicitProvider = str(context.providerSessionId);
+    const providerSessionId = explicitProvider ?? errorProviderSessionId ?? (/^rc-api(?:-|$)/.test(service) ? session : null);
+    const newlySessionId = str(context.newlySessionId ?? context['newly.session_id']) ?? (/^cp-(?:api|worker)(?:-|$)/.test(service) ? session : null);
+    const timestamp = stamp(entry.timestamp ?? context.timestamp ?? context.observedAt);
+    const atFailureObservation = (observedAt) => timestamp ? observation(observedAt, time(timestamp), 45) :
+        { observedAt: stamp(observedAt), ageSeconds: null, state: 'unavailable', reason: 'original_failure_timestamp_missing' };
+    const helper = row(context.helper), resources = row(context.resourceTelemetry);
+    const project = str(row(row(entry.resource).labels).project_id);
+    const trace = str(entry.trace ?? context.traceId);
+    let generatedLogsUrl = null;
+    if (project && /^[a-z][a-z0-9-]{4,62}$/.test(project) && timestamp) {
+        const identity = trace ? `trace="${trace.replace(/[^a-zA-Z0-9_/-]/g, '')}"` : providerSessionId ?
+            `(jsonPayload.providerSessionId="${providerSessionId.replace(/[^a-zA-Z0-9_-]/g, '')}" OR jsonPayload.sessionId="${providerSessionId.replace(/[^a-zA-Z0-9_-]/g, '')}")` : null;
+        if (identity)
+            generatedLogsUrl = `https://console.cloud.google.com/logs/query?${new URLSearchParams({ project, query: `${identity}\ntimestamp>="${new Date(time(timestamp) - 60000).toISOString()}"\ntimestamp<="${new Date(time(timestamp) + 60000).toISOString()}"` })}`;
+    }
+    return { source: 'original_failure_export', timestamp, insertId: str(entry.insertId),
+        code: str(context.code ?? context.errorCode) ?? causeCodes.at(-1) ?? null, causeCodes, errorChain, type: str(context.event ?? context.type),
+        severity: str(entry.severity ?? context.severity), message: safeFleetText(context.message ?? entry.textPayload),
+        hostId: str(context.hostId), deviceId: str(context.deviceId), providerSessionId, newlySessionId,
+        unclassifiedSessionId: providerSessionId || newlySessionId ? null : session,
+        platform: str(context.platform), retryable: context.retryable ?? errorChain[0]?.retryable ?? null, httpStatus: context.httpStatus ?? errorChain[0]?.httpStatus ?? null,
+        serviceAtFailure: { name: service || null, revision: str(context.revision), version: str(context.version) },
+        traceId: trace, requestId: str(context.requestId ?? context.reqId), launchId: str(context.launchId), operation: str(context.operation),
+        releaseVersionAtFailure: str(context.serveSimVersion ?? context.hostVersion ?? context.releaseVersion),
+        helperAtFailure: Object.keys(helper).length ? { ...pick(helper, ['state', 'lastSeenAt', 'observedAt']), observation: atFailureObservation(helper.observedAt ?? helper.lastSeenAt) } : null,
+        resourceTelemetryAtFailure: Object.keys(resources).length ? { ...pick(resources, ['observedAt', 'cpuUtilizationPercent', 'memoryUsedBytes', 'memoryTotalBytes']), observation: atFailureObservation(resources.observedAt) } : null,
+        originalFailureLogsUrl: originalLogsUrl(context.originalFailureLogsUrl ?? context.logsUrl) ?? generatedLogsUrl,
+        originalFailureLogsUrlBasis: originalLogsUrl(context.originalFailureLogsUrl ?? context.logsUrl) ? 'provided_link' : generatedLogsUrl ? 'derived_from_original_log_identity_and_timestamp' : 'missing',
+    };
+}
+function eventEvidence(value) {
+    return { ...failureEvidence({ ...value, code: value.code ?? value.type, providerSessionId: value.providerSessionId }), source: 'hosted_event' };
+}
+function selectedFailure(event, codes) {
+    return codes.length ? codes.some(code => event.code === code || event.causeCodes.includes(code) || event.type === code || event.message?.includes(code)) : ['warning', 'critical', 'error', 'ERROR', 'CRITICAL'].includes(event.severity ?? '');
+}
+function correlate(event, fleetHosts, reports, now) {
+    let hostId = event.hostId, basis = hostId ? 'reported_host_id' : 'unresolved', deviceId = event.deviceId;
+    const matches = [];
+    if (!hostId && event.providerSessionId && event.timestamp) {
+        for (const host of fleetHosts)
+            for (const session of rows(host.activeSessions)) {
+                const end = session.expiresAt === null && ['active', 'provisioning'].includes(String(session.status)) ? now : time(session.expiresAt);
+                if (session.id === event.providerSessionId && time(session.createdAt) > 0 && end > 0 &&
+                    time(session.createdAt) <= time(event.timestamp) && time(event.timestamp) <= end) {
+                    matches.push({ hostId: String(host.id), deviceId: str(session.deviceId) });
+                }
+            }
+        if (matches.length === 1) {
+            hostId = matches[0].hostId;
+            deviceId ??= matches[0].deviceId;
+            basis = 'exact_provider_session_and_lease_interval';
+        }
+        else if (matches.length > 1)
+            basis = 'ambiguous_provider_session';
+    }
+    const host = reports.find(candidate => candidate.id === hostId);
+    const device = host?.devices.find(candidate => candidate.id === deviceId);
+    return { ...event, hostId, deviceId, correlation: { basis, historicalHostResolved: hostId !== null,
+            missingEvidence: [!hostId && 'historical_host', !deviceId && 'device', !event.providerSessionId && 'provider_session',
+                !event.releaseVersionAtFailure && 'release_at_failure', event.helperAtFailure?.observation.state !== 'fresh' && 'fresh_helper_at_failure',
+                event.resourceTelemetryAtFailure?.observation.state !== 'fresh' && 'fresh_resources_at_failure'].filter(Boolean),
+            currentSnapshot: host ? { observedAt: host.health.observedAt, diagnosis: host.diagnosis, release: host.release, cpu: host.cpu,
+                helper: device?.helper ?? null, helperBasis: device ? 'current_device_snapshot; not helper state at failure' : 'device_missing_in_current_snapshot' } : null,
+            causation: 'unproved; current telemetry does not establish conditions at failure' } };
+}
+export async function inspectFleet(client, options = {}, now) {
+    validate(options);
+    const query = new URLSearchParams(options.hostId ? { hostId: options.hostId } : {});
+    if (options.deep)
+        query.set('include', 'details');
+    const fleet = await readSource(client, ROOT);
+    if (fleet.state === 'unavailable' || !Array.isArray(fleet.data.hosts))
+        throw new Error(`Fleet read unavailable (${fleet.reason ?? 'invalid_response'}); use an admin identity with read permission`);
+    const [inventory, shared, diagnostics, events, history] = await Promise.all([
+        readSource(client, '/run-cloud/admin/fleet-inventory'),
+        readSource(client, `${ROOT}/operator-inventory`),
+        readSource(client, `${ROOT}/diagnostics?${query}`),
+        readFleetEvents(client, options),
+        options.hostId ? readSource(client, `${ROOT}/history?${new URLSearchParams({ range: options.range ?? '24h', hostId: options.hostId })}`) : Promise.resolve(null),
+    ]);
+    for (const [source, key] of [[inventory, 'hosts'], [shared, 'snapshots'], [diagnostics, 'diagnoses']]) {
+        if (source.state === 'available' && !Array.isArray(source.data[key])) {
+            source.state = 'unavailable';
+            source.reason = 'invalid_response_shape';
+            source.data = {};
+        }
+    }
+    if (history?.state === 'available' && !Array.isArray(history.data.points)) {
+        history.state = 'unavailable';
+        history.reason = 'invalid_response_shape';
+        history.data = {};
+    }
+    now ??= Date.now();
+    const supplemental = componentHosts(shared.data);
+    const live = new Map(rows(fleet.data.hosts).map(host => [String(host.id), host]));
+    const expected = new Map(rows(inventory.data.hosts).map(host => [String(host.id), host]));
+    const ids = new Set([...expected.keys(), ...live.keys(), ...supplemental.keys()]);
+    if (options.hostId && !ids.has(options.hostId))
+        throw new Error(`Host ${options.hostId} is absent from returned inventories`);
+    const hosts = [...ids].filter(id => !options.hostId || id === options.hostId).sort().map(id => hostReport(live.get(id) ?? {}, expected.get(id) ?? {}, supplemental.get(id) ?? {}, rows(diagnostics.data.diagnoses), now, num(fleet.data.staleAfterSeconds) ?? 45, options.deep ? row(row(diagnostics.data.hostDetails)[id]) : {}));
+    const freshCpu = hosts.filter(host => host.cpu.state === 'fresh' && host.cpu.percent !== null);
+    const codes = options.codes ?? [];
+    const failureInputs = [...events.items.map(eventEvidence), ...(options.failures ?? []).map(failureEvidence)];
+    const start = now - ({ '1h': 3600, '6h': 21600, '24h': 86400, '7d': 604800, '30d': 2592000, '90d': 7776000, '1y': 31536000, '2y': 63072000 }[options.range ?? '24h']) * 1000;
+    const failures = failureInputs.filter(event => selectedFailure(event, codes) && (!event.timestamp || (time(event.timestamp) >= start && time(event.timestamp) <= now)))
+        .map(event => ({ ...correlate(event, rows(fleet.data.hosts), hosts, now), windowMembership: event.timestamp ? 'inside_requested_window' : 'unknown; original timestamp missing' }))
+        .filter(event => !options.hostId || event.hostId === options.hostId || event.hostId === null);
+    const sourceStatus = (source) => ({ state: source.state, reason: source.reason, generatedAt: stamp(source.data.generatedAt), meaning: 'response generation time; does not renew component observations' });
+    return { schemaVersion: 1, generatedAt: new Date(now).toISOString(), readOnly: true,
+        sources: { fleet: sourceStatus(fleet), inventory: sourceStatus(inventory), shared: sourceStatus(shared), diagnostics: sourceStatus(diagnostics),
+            ...(history ? { history: sourceStatus(history) } : {}) },
+        summary: { hosts: hosts.length, canonicalInventoryHosts: inventory.state === 'available' ? expected.size : null, liveHosts: live.size,
+            healthCounts: hosts.reduce((counts, host) => { const state = host.health.effectiveState; counts[state] = (counts[state] ?? 0) + 1; return counts; }, { ready: 0, degraded: 0, unreachable: 0, unknown: 0 }),
+            cpu: { meanBusyPercent: freshCpu.length ? freshCpu.reduce((sum, host) => sum + host.cpu.percent, 0) / freshCpu.length : null,
+                meaning: 'arithmetic mean across fresh host samples; not CPU core weighted; aliases may represent the same physical machine',
+                freshHosts: freshCpu.length, totalHosts: hosts.length, oldestObservedAt: freshCpu.map(host => host.cpu.observedAt).sort()[0] ?? null,
+                staleHosts: hosts.filter(host => host.cpu.state === 'stale').length, missingHosts: hosts.filter(host => host.cpu.state === 'missing').length,
+                unavailableHosts: hosts.filter(host => host.cpu.state === 'unavailable').length }, matchingFailureRows: failures.length,
+            failures: { meaning: 'log/event rows, not distinct incidents; provider and consumer layers can describe the same failure',
+                uniqueProviderSessions: new Set(failures.map(event => event.providerSessionId).filter(Boolean)).size,
+                unresolvedHostRows: failures.filter(event => !event.hostId).length,
+                bySourceAndCode: failures.reduce((counts, event) => {
+                    const key = `${event.source}:${event.code ?? event.type ?? 'unknown'}`;
+                    counts[key] = (counts[key] ?? 0) + 1;
+                    return counts;
+                }, {}) } },
+        eventCoverage: events.coverage, originalFailureCoverage: { importedRows: options.failures?.length ?? 0, meaning: 'caller supplied export; completeness unverified' },
+        failureFilter: { codes, range: options.range ?? '24h', since: new Date(start).toISOString(), until: new Date(now).toISOString() },
+        hosts, failures,
+        historicalTelemetry: history ? { ...sourceStatus(history), hostId: options.hostId, range: options.range ?? '24h',
+            meaning: 'aggregated time buckets; not instantaneous resource conditions at failure',
+            points: rows(history.data.points).map(point => pick(point, ['timestamp', 'cpuUtilizationPercent', 'memoryUtilizationPercent', 'storageUtilizationPercent', 'activeSessions'])) } : null,
+        deepDetails: options.deep ? sanitizeDeep(row(row(diagnostics.data.hostDetails)[options.hostId])) : null,
+    };
+}
+function sanitizeDeep(details) {
+    return { observedAt: stamp(row(details.security).checkedAt), services: rows(details.services).map(service => ({ ...pick(service, ['name', 'state', 'pid', 'lastExitCode']), error: safeFleetText(service.lastError ?? service.error) })),
+        processes: rows(details.processes).map(process => pick(process, ['name', 'pid', 'uptimeSeconds', 'cpuUtilizationPercent', 'memoryBytes'])),
+        toolchain: pick(row(details.toolchain), ['nodeVersion', 'xcodeVersion', 'simctlVersion', 'architecture', 'runtimes']),
+        logs: rows(details.logs).map(log => ({ ...pick(log, ['source', 'timestamp', 'severity']), message: safeFleetText(log.message) })) };
+}
+export function readFailureExport(path) {
+    if (!statSync(path).isFile() || statSync(path).size > 16 * 1024 * 1024)
+        throw new Error('Failure export must be a file at most 16 MiB');
+    const text = readFileSync(path, 'utf8').trim();
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        try {
+            parsed = text.split('\n').filter(Boolean).map(line => JSON.parse(line));
+        }
+        catch {
+            throw new Error('Failure export is not valid JSON or JSONL');
+        }
+    }
+    const entries = Array.isArray(parsed) ? parsed : Array.isArray(row(parsed).entries) ? row(parsed).entries : [parsed];
+    if (entries.length > 500)
+        throw new Error('Failure export exceeds 500 rows; narrow the log query');
+    return entries;
+}
+export async function readFleetLogs(client, hostId, source = 'service', limit = 100) {
+    validate({ hostId, limit });
+    if (!['service', 'warm_pool', 'event_log'].includes(source))
+        throw new Error('source must be service, warm_pool, or event_log');
+    const result = await readSource(client, `${ROOT}/diagnostics/logs?${new URLSearchParams({ hostId, source, limit: String(limit) })}`);
+    if (result.state === 'available' && !Array.isArray(result.data.lines)) {
+        result.state = 'unavailable';
+        result.reason = 'invalid_response_shape';
+    }
+    return { state: result.state, reason: result.reason, hostId, source, readAt: stamp(result.data.generatedAt),
+        observationMeaning: 'readAt is retrieval time; original timestamps, when present, remain inside lines',
+        truncated: result.state === 'unavailable' || typeof result.data.truncated !== 'boolean' ? null : result.data.truncated,
+        lines: Array.isArray(result.data.lines) ? result.data.lines.map(safeFleetText) : [] };
+}
+function credentialsClient() { const credentials = requireCredentials(); return new ApiClient(credentials.apiUrl, credentials.token); }
+function action(fn) {
+    return fn().catch(error => { console.error(safeFleetText(error instanceof Error ? error.message : 'Fleet read failed')); process.exitCode = 1; });
+}
+function printReport(report, json) {
+    if (json) {
+        console.log(JSON.stringify(report, null, 2));
+        return;
+    }
+    console.log(`${report.generatedAt}: ${report.summary.hosts} hosts, ${report.summary.cpu.freshHosts} fresh CPU samples; mean ${report.summary.cpu.meanBusyPercent?.toFixed(1) ?? 'unknown'}%.`);
+    for (const host of report.hosts)
+        console.log(host.diagnosis);
+    console.log(`Matching failure rows: ${report.failures.length}. Event window ${report.eventCoverage.complete ? 'fully read' : 'incomplete'} (${report.eventCoverage.rowsRead} rows).`);
+    for (const failure of report.failures)
+        console.log(`${failure.timestamp ?? 'time missing'} ${failure.code ?? failure.type ?? 'failure'} host=${failure.hostId ?? 'unknown'} device=${failure.deviceId ?? 'unknown'} providerSession=${failure.providerSessionId ?? 'unknown'}; ${failure.correlation.causation}`);
+}
+export function registerRunCloudFleet(program) {
+    const fleet = program.command('fleet').description('Read-only admin fleet telemetry, diagnosis, events and original failure evidence');
+    fleet.command('inspect [hostId]').description('Inspect whole fleet or one machine; existing admin read authorization required')
+        .option('--json', 'Structured evidence with source observations and missing data')
+        .option('--range <range>', 'Event/history window', '24h').option('--limit <rows>', 'Events per page (1..500)', '200')
+        .option('--event-pages <pages>', 'Maximum GET event pages (1..10)', '1')
+        .option('--code <code>', 'Failure code to correlate; repeatable', (value, previous) => [...previous, value], [])
+        .option('--deep', 'Read existing detailed diagnostics for one host')
+        .option('--failure-log <path>', 'Import original JSON/JSONL logs; repeatable, 500 rows/16 MiB per file', (value, previous) => [...previous, value], [])
+        .action((hostId, opts) => action(async () => {
+        const options = { hostId, range: opts.range, limit: Number(opts.limit), eventPages: Number(opts.eventPages), deep: opts.deep,
+            codes: opts.code, failures: opts.failureLog.flatMap((path) => readFailureExport(path)) };
+        validate(options);
+        printReport(await inspectFleet(credentialsClient(), options), opts.json);
+    }));
+    fleet.command('events').description('Read bounded admin event pages; emits coverage and sanitized event metadata')
+        .option('--host <hostId>').option('--range <range>', 'Event window', '24h').option('--limit <rows>', 'Rows per page', '200')
+        .option('--event-pages <pages>', 'Maximum pages (1..10)', '1')
+        .action(opts => action(async () => {
+        const result = await readFleetEvents(credentialsClient(), { hostId: opts.host, range: opts.range, limit: Number(opts.limit), eventPages: Number(opts.eventPages) });
+        console.log(JSON.stringify({ coverage: result.coverage, items: result.items.map(eventEvidence) }, null, 2));
+    }));
+    fleet.command('logs <hostId>').description('Read bounded retained host logs; no SSH or host changes')
+        .option('--source <source>', 'service, warm_pool, or event_log', 'service').option('--limit <rows>', 'Maximum lines (1..500)', '100')
+        .action((hostId, opts) => action(async () => { console.log(JSON.stringify(await readFleetLogs(credentialsClient(), hostId, opts.source, Number(opts.limit)), null, 2)); }));
+}

package/dist/run-cloud.js

@@ -3,6 +3,7 @@ import { Command } from 'commander';
 import { registerImage } from './commands/image.js';
 import { registerLogin } from './commands/login.js';
 import { registerRunCloud } from './commands/run-cloud.js';
+import { registerRunCloudFleet } from './commands/run-cloud-fleet.js';
 import { registerSandbox } from './commands/sandbox.js';
 import { registerSecrets } from './commands/secrets.js';
 import { registerToken } from './commands/token.js';
@@ -13,6 +14,7 @@ const program = new Command('runcloud')
     .version(CLI_VERSION);
 registerLogin(program);
 registerRunCloud(program);
+registerRunCloudFleet(program);
 registerSandbox(program);
 registerSecrets(program);
 registerToken(program);

package/dist/version.js

@@ -1 +1 @@
-export const CLI_VERSION = '0.2.165';
+export const CLI_VERSION = '0.2.166';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runcloud",
-  "version": "0.2.165",
+  "version": "0.2.166",
   "description": "Create and control run.cloud remote mobile simulators and cloud sandboxes",
   "license": "Apache-2.0",
   "keywords": [