runcloud 0.2.165 → 0.2.167

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

@@ -0,0 +1,194 @@
+import { jenkinsObservedState, machineDiagnosis } from './run-cloud-machine-diagnosis.js';
+export const row = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : {};
+export const rows = (value) => Array.isArray(value) ? value.map(row) : [];
+export const str = (value) => typeof value === 'string' && value.length > 0 ? value : null;
+export const num = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
+export const stamp = (value) => str(value) && Number.isFinite(Date.parse(String(value))) ? new Date(String(value)).toISOString() : null;
+export const time = (value) => stamp(value) ? Date.parse(String(value)) : 0;
+export const validFleetId = (value) => typeof value === 'string' && /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,255}$/.test(value);
+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;
+}
+export function observation(value, now, ttl, error) {
+    const observedAt = stamp(value);
+    const ageSeconds = observedAt ? (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 };
+}
+export 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, ingestionHeartbeat: null, reportedFreshness: null };
+    const ingestion = observation(freshness.lastSuccessfulUpdateAt, now, ttl);
+    const ingestionHeartbeat = observation(freshness.lastHeartbeatAt, now, ttl);
+    const reportedFreshness = str(freshness.status);
+    if (heartbeat.state === 'fresh' && (reportedFreshness !== 'fresh' || ingestion.state !== 'fresh' || ingestionHeartbeat.state !== 'fresh')) {
+        const state = [ingestion, ingestionHeartbeat].some(sample => sample.state === 'unavailable') ? 'unavailable' : reportedFreshness === 'never' ? 'missing' : 'stale';
+        const reason = ingestion.state !== 'fresh' ? `hosted_ingestion_${ingestion.state}` : ingestionHeartbeat.state !== 'fresh' ? `hosted_heartbeat_${ingestionHeartbeat.state}` : `hosted_ingestion_${reportedFreshness ?? 'unknown'}`;
+        return { ...heartbeat, state: state, reason, ingestion, ingestionHeartbeat, reportedFreshness };
+    }
+    return { ...heartbeat, ingestion, ingestionHeartbeat, reportedFreshness };
+}
+export function componentHosts(shared) {
+    const result = new Map();
+    const snapshots = rows(shared.snapshots).map(entry => row(entry.snapshot));
+    for (const snapshot of snapshots)
+        for (const raw of rows(snapshot.hosts)) {
+            const host = { ...raw, inventorySource: 'shared', collectorError: snapshot.collectorError ?? null };
+            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) && Object.keys(candidate).length ? candidate : previous;
+            }
+            result.set(id, merged);
+        }
+    return result;
+}
+export 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' };
+}
+export 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', 'owner', 'operationId']), reason: safeFleetText(source.reason) } : null;
+}
+export function hostReport(host, canonical, extra, diagnoses, now, fleetTtl, deep = {}, context = {}) {
+    const id = String(host.id ?? canonical.id ?? extra.id);
+    const machineType = str(canonical.machineType ?? host.machineType) ?? (extra.role === 'jenkins' ? 'build' : str(extra.role)) ?? 'simulator';
+    const role = machineType === 'build' ? 'jenkins' : machineType;
+    const sharedHealth = observation(extra.observedAt, now, context.operatorTtl ?? 120, extra.collectorError);
+    const useShared = sharedHealth.state === 'fresh' && time(extra.observedAt) > time(host.observedAt);
+    const primary = useShared ? extra : host;
+    const capacitySource = primary.capacity != null ? primary : useShared ? host : extra;
+    const capacity = row(capacitySource.capacity);
+    let health = useShared ? sharedHealth : hostedObservation(host, now, fleetTtl);
+    let state = health.state === 'fresh' ? str(primary.state) ?? 'unknown' : 'unknown';
+    let reportedState = str(primary.state);
+    let diagnosisTtl = useShared ? context.operatorTtl ?? 120 : fleetTtl;
+    let diagnosisSource = useShared ? 'shared' : 'hosted';
+    if (role === 'jenkins') {
+        const jenkins = context.jenkins ?? {};
+        const node = rows(jenkins.nodes).find(node => node.id === id || node.id === `${id}-jenkins`);
+        reportedState = node?.offline === true ? 'offline' : node?.offline === false ? 'ready' : null;
+        diagnosisTtl = num(jenkins.staleAfterSeconds) ?? 30;
+        health = observation(jenkins.observedAt, now, diagnosisTtl, jenkins.error || jenkins.state === 'unavailable');
+        state = jenkinsObservedState(node ? { offline: typeof node.offline === 'boolean' ? node.offline : undefined } : undefined, health.observedAt, now, diagnosisTtl, health.state === 'unavailable');
+        if (!node && health.state === 'fresh')
+            health = { ...health, state: 'missing', reason: 'jenkins_node_missing' };
+        diagnosisSource = 'jenkins';
+    }
+    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 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 admissionObservation = observation(canonical.admissionObservedAt, now, context.inventoryTtl ?? 30);
+    const acceptsLeases = canonical.enabled === false || machineType !== 'simulator' || canonical.admissionReason === 'routing-disabled' ? false :
+        admissionObservation.state === 'fresh' && typeof canonical.acceptsLeases === 'boolean' ? canonical.acceptsLeases : null;
+    const rawRequestedFence = Object.hasOwn(canonical, 'requestedFence') ? canonical.requestedFence : host.requestedFence ?? extra.requestedFence;
+    const rawFence = Object.hasOwn(canonical, 'fence') ? canonical.fence : host.fence ?? extra.fence;
+    const requestedFence = fence(rawRequestedFence), appliedFence = fence(rawFence);
+    if (appliedFence && admissionObservation.state !== 'fresh')
+        appliedFence.state = 'unknown';
+    const operation = context.operations?.filter(operation => operation.id === id).sort((a, b) => time(b.updatedAt) - time(a.updatedAt))[0];
+    const operationFence = operation && acceptsLeases !== true ? fence(operation.fence) : null;
+    if (operationFence && (operation.stale || (!['complete', 'reserved', 'cancelled', 'rolled-back'].includes(String(operation.status)) && now - time(operation.updatedAt) > 60000)))
+        operationFence.state = 'unknown';
+    const displayFence = appliedFence ?? requestedFence ?? operationFence;
+    const sample = useDeep ? { observedAt: deepChecks.observedAt, staleAfterSeconds: fleetTtl, services: deep.services } : diagnostic;
+    const diagnosisHost = {
+        id, role, observedAt: health.observedAt, acceptsLeases,
+        capacity: role === 'jenkins' ? null : { dirty: num(capacity.dirty) },
+        fence: displayFence ? { kind: str(displayFence.kind) ?? 'unknown', state: str(displayFence.state), reason: str(row(rawFence ?? rawRequestedFence ?? operation?.fence).reason) ?? 'reason missing' } : null,
+        requestedFence: requestedFence ? { kind: str(requestedFence.kind) ?? 'unknown' } : null,
+        hostDiagnostics: Object.keys(sample).length ? {
+            observedAt: stamp(sample.observedAt), staleAfterSeconds: num(sample.staleAfterSeconds) ?? 900,
+            collectionError: str(sample.collectionError) ?? (!Array.isArray(sample.services) ? 'service list missing' : null),
+            services: rows(sample.services).map(service => ({ name: str(service.name) ?? '', state: str(service.state) })),
+            packageMatchesService: typeof sample.packageMatchesService === 'boolean' ? sample.packageMatchesService : null,
+            power: { thermalWarning: row(sample.power).thermalWarning === true, performanceWarning: row(sample.power).performanceWarning === true },
+            coreSimulator: { orphaned: num(row(sample.coreSimulator).orphaned), externalBooted: num(row(sample.coreSimulator).externalBooted) },
+            recording: { failed: num(row(sample.recording).failed) },
+        } : null,
+        processScan: Object.keys(process).length ? {
+            observedAt: stamp(process.observedAt), staleAfterSeconds: num(process.staleAfterSeconds) ?? 900,
+            sourceUnavailable: process.sourceUnavailable === true || Boolean(extra.collectorError), status: str(process.status) ?? 'unknown', error: str(process.error), root: process.root === true,
+            iocs: rows(process.iocs).map(ioc => ({ status: str(ioc.status) ?? 'unknown', contained: ioc.contained === true })),
+            findings: rows(process.findings).map(finding => ({ reason: str(finding.reason) ?? 'unknown' })),
+            coverage: { iocs: str(row(process.coverage).iocs) ?? 'partial' }, baseline: { state: str(row(process.baseline).state) ?? 'missing' },
+        } : null,
+    };
+    const observedState = role === 'jenkins' ? state : health.state === 'fresh' ? state : health.state === 'missing' ? 'unknown' : 'stale';
+    const releaseFacts = {
+        matches: typeof release.matches === 'boolean' ? release.matches : null,
+        expectedPackage: str(release.expectedPackage), actualPackage: str(release.actualPackage),
+        expectedVersion: str(release.expectedVersion), actualVersion: str(release.actualVersion),
+        expectedBuild: str(release.expectedBuild), actualBuild: str(release.actualBuild),
+    };
+    const diagnosisDetails = machineDiagnosis(diagnosisHost, { release: releaseFacts }, observedState, now, diagnosisTtl);
+    const cpu = cpuReading(host, extra, now, fleetTtl);
+    return { id, name: safeFleetText(canonical.name ?? host.name ?? extra.name), platform: canonical.platform ?? host.platform ?? extra.platform ?? null,
+        role, machineType, inventoryPresent: Object.keys(canonical).length > 0, livePresent: Object.keys(host).length > 0,
+        health: { reportedState, effectiveState: state, source: diagnosisSource, ...health,
+            ...(role === 'jenkins' ? { hostedEvidence: { reportedState: str(host.state), ...hostedObservation(host, now, fleetTtl) } } : {}) }, diagnosis: diagnosisDetails.summary, diagnosisDetails, cpu,
+        diagnosisObservation: { observedAt: health.observedAt, observedState, staleAfterSeconds: diagnosisTtl, source: diagnosisSource,
+            hostedObservedAt: stamp(host.observedAt), diagnosticsObservedAt: stamp(sample.observedAt), processObservedAt: stamp(process.observedAt) },
+        release: { ...releaseFacts, version: str(host.version), build: str(host.build), observedAt: stamp(host.observedAt) },
+        admission: { enabled: canonical.enabled ?? null, acceptsLeases, observation: admissionObservation, observedAt: stamp(canonical.admissionObservedAt), reason: safeFleetText(canonical.admissionReason), requestedFence, fence: appliedFence, operationFence,
+            operation: operation ? { operationId: safeFleetText(operation.operationId), kind: safeFleetText(operation.kind), component: safeFleetText(operation.component),
+                phase: safeFleetText(operation.phase), status: safeFleetText(operation.status), progress: num(operation.progress), updatedAt: stamp(operation.updatedAt), owner: safeFleetText(operation.owner),
+                ...observation(operation.updatedAt, now, 60, operation.stale), error: safeFleetText(operation.error) } : null },
+        capacity: role === 'jenkins' ? null : pick(capacity, ['clean', 'leased', 'installing', 'dirty', 'preparing', 'recycling', 'total']),
+        capacityObservation: capacitySource === host ? { source: 'hosted', ...hostedObservation(host, now, fleetTtl) } : {
+            source: 'shared', ...observation(extra.observedAt, now, context.operatorTtl ?? 120, extra.collectorError)
+        },
+        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) })),
+        deviceObservation: { source: 'hosted', ...hostedObservation(host, now, fleetTtl), meaning: 'provider device records only; shared discovery does not establish current leases' },
+        diagnoses: diagnosesForHost,
+    };
+}

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

@@ -0,0 +1,252 @@
+import { ApiError } from '../api.js';
+import { componentHosts, hostReport, hostedObservation, num, observation, row, rows, safeFleetText, stamp, str, time, validFleetId } from './run-cloud-fleet-observations.js';
+export const SURVEY_REQUEST_BUDGET_MS = 8000;
+const ROOT = '/run-cloud/admin/simulators';
+const RANGES = ['1h', '6h', '24h', '7d'];
+const DEVICE_LIMIT = 512, POINT_LIMIT = 800, TYPE_LIMIT = 100;
+function count(value) { const number = num(value); return number !== null && Number.isSafeInteger(number) ? number : null; }
+function counts(value) {
+    const data = row(value), errors = count(data.errors), warnings = count(data.warnings), sessions = count(data.sessions);
+    return errors === null || warnings === null || sessions === null ? null : { errors, warnings, sessions };
+}
+const unavailable = (reason) => ({ state: 'unavailable', data: {}, reason });
+function resourceReading(host, extra, kind, now, fleetTtl) {
+    const telemetry = row(extra.hostTelemetry), volumes = rows(row(telemetry.storage).volumes);
+    const probe = kind === 'memory' ? row(telemetry.memory) : volumes.find(volume => volume.label === 'data') ?? volumes[0] ?? {};
+    const candidate = (values, source, observed) => {
+        const usedBytes = num(values.usedBytes), totalBytes = num(values.totalBytes), availableBytes = num(values.availableBytes);
+        const missing = usedBytes === null || totalBytes === null;
+        return { source, ...observed, usedBytes, totalBytes, availableBytes,
+            percent: usedBytes !== null && totalBytes !== null && totalBytes > 0 ? usedBytes / totalBytes * 100 : null,
+            ...(missing && observed.state === 'fresh' ? { state: 'missing', reason: `${kind}_value_missing` } : {}) };
+    };
+    const candidates = [
+        candidate(probe, 'operator_resource_probe', observation(telemetry.observedAt, now, num(telemetry.staleAfterSeconds) ?? 45, telemetry.collectionError)),
+        candidate({ usedBytes: host[`${kind}UsedBytes`], totalBytes: host[`${kind}TotalBytes`] }, 'host_heartbeat', hostedObservation(host, now, fleetTtl)),
+    ].sort((a, b) => Number(b.state === 'fresh') - Number(a.state === 'fresh') || time(b.observedAt) - time(a.observedAt));
+    return { ...candidates[0], candidates, ...(kind === 'storage' ? { volumes: volumes.map(volume => ({ label: safeFleetText(volume.label),
+                usedBytes: num(volume.usedBytes), totalBytes: num(volume.totalBytes), availableBytes: num(volume.availableBytes) })),
+            volumeObservation: observation(telemetry.observedAt, now, num(telemetry.staleAfterSeconds) ?? 45, telemetry.collectionError),
+            meaning: 'one reported volume or heartbeat capacity; volumes may share backing storage and are never summed' } : {}) };
+}
+function alertReport(source, now, requestedRange, hostId) {
+    const data = source.data;
+    const raw = rows(data.points);
+    const valid = source.state === 'available' && data.range === requestedRange && stamp(data.generatedAt) && time(data.generatedAt) <= now + 5000 && num(data.bucketSeconds) &&
+        raw.every(point => stamp(point.timestamp) && time(point.timestamp) <= time(data.generatedAt) && counts(point) && Array.isArray(point.errorTypes) && rows(point.errorTypes).every(type => str(type.type) && count(type.errors) !== null && count(type.warnings) !== null));
+    if (!valid)
+        return { state: 'unavailable', reason: source.reason ?? 'invalid_alert_aggregate', byType: null, totals: null, trend: null,
+            coverage: { ingestionCompleteness: 'unknown; aggregate API does not certify event ingestion', hostScope: hostId ? [hostId] : 'all hosts' } };
+    const points = raw.slice(-POINT_LIMIT).sort((a, b) => time(a.timestamp) - time(b.timestamp));
+    const generatedAt = stamp(data.generatedAt), bucketSeconds = Number(data.bucketSeconds);
+    const completeBuckets = points.filter(point => time(point.timestamp) + bucketSeconds * 1000 <= time(generatedAt));
+    const recent = completeBuckets.at(-1), previous = completeBuckets.at(-2);
+    const comparable = recent && previous && time(recent.timestamp) - time(previous.timestamp) === bucketSeconds * 1000;
+    const types = new Map();
+    let omittedTypeRows = 0;
+    for (const point of points) {
+        const entries = rows(point.errorTypes);
+        omittedTypeRows += Math.max(0, entries.length - TYPE_LIMIT);
+        for (const entry of entries.slice(0, TYPE_LIMIT)) {
+            const type = String(entry.type), before = types.get(type) ?? { type, errors: 0, warnings: 0, recent: null, previous: null, delta: null };
+            before.errors += Number(entry.errors);
+            before.warnings += Number(entry.warnings);
+            types.set(type, before);
+        }
+    }
+    for (const entry of types.values())
+        if (comparable && omittedTypeRows === 0) {
+            const inBucket = (point) => rows(point.errorTypes).filter(type => type.type === entry.type).reduce((sum, type) => sum + Number(type.errors) + Number(type.warnings), 0);
+            entry.recent = inBucket(recent);
+            entry.previous = inBucket(previous);
+            entry.delta = entry.recent - entry.previous;
+        }
+    const window = (point) => ({ since: stamp(point.timestamp), until: new Date(time(point.timestamp) + bucketSeconds * 1000).toISOString(), ...counts(point) });
+    return { state: 'available', reason: null, generatedAt, responseAgeSeconds: (now - time(generatedAt)) / 1000,
+        byType: [...types.values()].sort((a, b) => b.errors + b.warnings - a.errors - a.warnings || a.type.localeCompare(b.type)),
+        observedBucketCounts: points.reduce((total, point) => ({ errors: total.errors + Number(point.errors), warnings: total.warnings + Number(point.warnings) }), { errors: 0, warnings: 0 }),
+        totals: { hour: counts(row(data.totals).hour), today: counts(row(data.totals).today), yesterday: counts(row(data.totals).yesterday) },
+        windows: { hour: stamp(row(data.windows).hour), today: stamp(row(data.windows).today), yesterday: stamp(row(data.windows).yesterday), yesterdayEnd: stamp(row(data.windows).yesterdayEnd),
+            timeZone: str(data.timeZone), until: generatedAt },
+        trend: comparable ? { recent: window(recent), previous: window(previous), delta: Number(recent.errors) + Number(recent.warnings) - Number(previous.errors) - Number(previous.warnings),
+            meaning: 'last two complete equal buckets; current partial bucket excluded' } : null,
+        coverage: { requestedRange, hostScope: hostId ? [hostId] : 'all hosts', bucketSeconds, firstBucketAt: stamp(points[0]?.timestamp), lastBucketAt: stamp(points.at(-1)?.timestamp),
+            buckets: points.length, omittedBuckets: Math.max(0, raw.length - POINT_LIMIT), omittedTypeRows, unattributedAlertRows: count(data.unattributedAlerts),
+            unattributedMeaning: 'missing customer attribution over the API query window, which may extend before the plotted range',
+            meaning: 'observed warning/critical event rows after server bookkeeping exclusions; retries can repeat rows; not unique incidents or a failure rate',
+            ingestionCompleteness: 'unknown; aggregate API does not certify event ingestion', windowAlignment: 'API bucket boundaries can extend before the requested rolling window' } };
+}
+function lagReport(source, selection, eligibleDevices, now, range) {
+    const data = source.data, selected = new Set(selection.map(([host, device]) => `${host} ${device}`));
+    const validSample = (sample) => count(sample.samples) !== null && (sample.samples === 0 ? sample.medianMs === null : num(sample.medianMs) !== null);
+    const valid = source.state === 'available' && data.metric === 'input_lag_visual_v1' && data.range === range && stamp(data.generatedAt) && time(data.generatedAt) <= now + 5000 &&
+        num(data.bucketSeconds) && count(data.selectedDevices) === selection.length && Array.isArray(data.points) &&
+        rows(data.points).every(point => stamp(point.timestamp) && time(point.timestamp) <= time(data.generatedAt) && validSample(point) && count(point.missing) !== null) &&
+        data.devices && typeof data.devices === 'object' && !Array.isArray(data.devices) && Object.values(row(data.devices)).every(sample => validSample(row(sample)));
+    const points = valid ? rows(data.points).slice(-POINT_LIMIT).sort((a, b) => time(a.timestamp) - time(b.timestamp)) : [];
+    const observed = points.filter(point => stamp(point.timestamp) && count(point.samples) !== null && Number(point.samples) > 0 && num(point.medianMs) !== null);
+    const latest = observed.at(-1);
+    const devices = valid && data.devices && typeof data.devices === 'object' && !Array.isArray(data.devices) ? Object.entries(row(data.devices))
+        .filter(([key]) => selected.has(key)).map(([key, value]) => {
+        const sample = row(value), samples = count(sample.samples), medianMs = samples !== null && samples > 0 ? num(sample.medianMs) : null;
+        const [hostId, deviceId] = key.split(' ');
+        return { hostId, deviceId, medianMs, samples, outcomes: sample.outcomes ? outcomeCounts(sample.outcomes) : null,
+            observationAgeSeconds: null, meaning: 'median across valid changed samples in query window; API provides no per-device last sample time' };
+    }) : null;
+    return { state: valid ? 'available' : source.state === 'not_requested' ? 'not_requested' : 'unavailable',
+        reason: valid ? null : source.reason ?? 'invalid_input_lag_aggregate', metric: 'input_lag_visual_v1', generatedAt: stamp(data.generatedAt),
+        responseAgeSeconds: stamp(data.generatedAt) ? (now - time(data.generatedAt)) / 1000 : null,
+        latestSampledBucket: latest ? { timestamp: stamp(latest.timestamp), bucketSeconds: Number(data.bucketSeconds), bucketAgeSeconds: (now - time(latest.timestamp)) / 1000,
+            medianMs: Number(latest.medianMs), samples: count(latest.samples), missing: count(latest.missing),
+            meaning: 'bucket aggregate for selected devices; bucket age is not the age of its last individual sample' } : null,
+        outcomes: valid && data.totals ? outcomeCounts(data.totals) : null, devices,
+        coverage: { requestedRange: range, eligibleDevices, requestedDevices: selection.length, apiSelectedDevices: valid ? count(data.selectedDevices) : null,
+            omittedDevices: Math.max(0, eligibleDevices - selection.length), deviceLimit: DEVICE_LIMIT,
+            unrequestedDeviceRecords: valid ? Object.keys(row(data.devices)).filter(key => !selected.has(key)).length : null,
+            returnedDevices: devices?.length ?? null, sampledDevices: devices?.filter(device => device.medianMs !== null).length ?? null,
+            firstBucketAt: stamp(points[0]?.timestamp), lastBucketAt: stamp(points.at(-1)?.timestamp), bucketSeconds: valid ? num(data.bucketSeconds) : null,
+            omittedBuckets: valid ? Math.max(0, rows(data.points).length - POINT_LIMIT) : null,
+            ingestionCompleteness: 'unknown; missing, no-change, superseded, hidden and sample-error outcomes are not successful latency samples' } };
+}
+function outcomeCounts(value) {
+    const data = row(value);
+    return Object.fromEntries(['changed', 'no_change', 'superseded', 'hidden', 'sample_error'].map(key => [key, count(data[key])]));
+}
+export async function surveyFleet(client, options = {}, now, requestBudgetMs = SURVEY_REQUEST_BUDGET_MS) {
+    const range = options.range ?? '24h';
+    if (!RANGES.includes(range))
+        throw new Error(`survey range must be ${RANGES.join(', ')}`);
+    if (options.hostId && !validFleetId(options.hostId))
+        throw new Error('Invalid host ID');
+    if (!Number.isSafeInteger(requestBudgetMs) || requestBudgetMs < 1 || requestBudgetMs > SURVEY_REQUEST_BUDGET_MS)
+        throw new Error('Invalid survey request budget');
+    const started = performance.now(), signal = AbortSignal.timeout(requestBudgetMs);
+    const read = async (path, key, body) => {
+        try {
+            const value = body ? await client.post(path, body, { signal }) : await client.get(path, { signal });
+            const data = row(value);
+            if (value instanceof Response || !Array.isArray(data[key]))
+                return unavailable('invalid_response_shape');
+            if (path === '/run-cloud/admin/jenkins' && data.state === 'unavailable')
+                return { state: 'unavailable', data, reason: 'jenkins_collection_unavailable' };
+            if (path === '/run-cloud/admin/fleet-operations' && (data.unavailable === true || data.configured === false))
+                return { state: 'unavailable', data, reason: 'operation_storage_unavailable_or_unconfigured' };
+            return { state: 'available', data, reason: null };
+        }
+        catch (error) {
+            return unavailable(error instanceof ApiError ? `HTTP ${error.status}` : signal.aborted ? 'request_budget_exhausted' : 'read_failed');
+        }
+    };
+    const fleetPromise = read(ROOT, 'hosts');
+    const inventoryPromise = read('/run-cloud/admin/fleet-inventory', 'hosts');
+    const sharedPromise = read(`${ROOT}/operator-inventory`, 'snapshots');
+    const jenkinsPromise = read('/run-cloud/admin/jenkins', 'nodes');
+    const operationsPromise = read('/run-cloud/admin/fleet-operations', 'hosts');
+    const analyticsPromise = read(`${ROOT}/analytics`, 'points', { range, ...(options.hostId ? { hostIds: [options.hostId] } : {}) });
+    let selection = [], eligibleDevices = 0;
+    const lagPromise = fleetPromise.then(async (fleet) => {
+        if (fleet.state !== 'available')
+            return unavailable('fleet_device_selection_unavailable');
+        const unique = new Map();
+        for (const host of rows(fleet.data.hosts))
+            if (!host.monitoringOnly && (!options.hostId || host.id === options.hostId)) {
+                for (const device of rows(host.devices))
+                    if (validFleetId(host.id) && validFleetId(device.id))
+                        unique.set(`${host.id} ${device.id}`, [String(host.id), String(device.id)]);
+            }
+        const devices = [...unique.values()].sort((a, b) => a.join(' ').localeCompare(b.join(' ')));
+        eligibleDevices = devices.length;
+        selection = devices.slice(0, DEVICE_LIMIT);
+        return selection.length ? read(`${ROOT}/input-lag/history`, 'points', { range, devices: selection }) : { state: 'not_requested', data: {}, reason: 'no_queryable_devices' };
+    });
+    const [fleet, inventory, shared, jenkins, operations, analytics, lag] = await Promise.all([
+        fleetPromise, inventoryPromise, sharedPromise, jenkinsPromise, operationsPromise, analyticsPromise, lagPromise,
+    ]);
+    if (fleet.state !== 'available')
+        throw new Error(`Fleet read unavailable (${fleet.reason}); use an admin identity with read permission`);
+    now ??= Date.now();
+    const live = new Map(rows(fleet.data.hosts).filter(host => validFleetId(host.id)).map(host => [String(host.id), host]));
+    const canonical = new Map(rows(inventory.data.hosts).filter(host => validFleetId(host.id)).map(host => [String(host.id), host]));
+    const components = componentHosts(shared.data), supplemental = new Map([...components].filter(([id]) => validFleetId(id))), ids = new Set([...canonical.keys(), ...live.keys(), ...supplemental.keys()]);
+    if (options.hostId && !ids.has(options.hostId))
+        throw new Error(`Host ${options.hostId} is absent from returned inventories`);
+    const inputLag = lagReport(lag, selection, eligibleDevices, now, range), fleetTtl = num(fleet.data.staleAfterSeconds) ?? 45;
+    const hosts = [...ids].filter(id => !options.hostId || id === options.hostId).sort().map(id => {
+        const host = live.get(id) ?? {}, extra = supplemental.get(id) ?? {};
+        const report = hostReport(host, canonical.get(id) ?? {}, extra, [], now, fleetTtl, {}, {
+            inventoryTtl: num(inventory.data.staleAfterSeconds) ?? 30, jenkins: jenkins.data,
+            operations: rows(operations.data.hosts).map(operation => ({ ...operation, stale: operation.stale || operations.state !== 'available' })),
+        });
+        const devices = inputLag.devices?.filter(device => device.hostId === id) ?? null;
+        const sampled = devices?.filter(device => device.medianMs !== null) ?? [];
+        return { ...report, memory: resourceReading(host, extra, 'memory', now, fleetTtl), storage: resourceReading(host, extra, 'storage', now, fleetTtl),
+            inputLag: { devices, selectedDevices: selection.filter(([hostId]) => hostId === id).length, sampledDevices: devices ? sampled.length : null,
+                highestDeviceMedianMs: sampled.length ? Math.max(...sampled.map(device => device.medianMs)) : null,
+                meaning: 'per-device window medians; highest is a device ranking, not a host or fleet percentile; no per-device observation time' } };
+    });
+    const alerts = alertReport(analytics, now, range, options.hostId);
+    const sources = Object.fromEntries(Object.entries({ fleet, inventory, shared, jenkins, operations,
+        analytics: { ...analytics, state: alerts.state, reason: alerts.reason }, inputLag: { ...lag, state: inputLag.state, reason: inputLag.reason } }).map(([key, source]) => [key, {
+            state: source.state, reason: source.reason, generatedAt: stamp(source.data.generatedAt ?? source.data.observedAt),
+            responseAgeSeconds: stamp(source.data.generatedAt ?? source.data.observedAt) ? (now - time(source.data.generatedAt ?? source.data.observedAt)) / 1000 : null,
+            meaning: 'response/collector generation time; does not renew component observations',
+        }]));
+    const cpu = hosts.filter(host => host.cpu.state === 'fresh' && host.cpu.percent !== null);
+    return { schemaVersion: 1, generatedAt: new Date(now).toISOString(), readOnly: true, scope: options.hostId ?? 'whole fleet', range,
+        durationSeconds: (performance.now() - started) / 1000, requestBudgetSeconds: requestBudgetMs / 1000, sources,
+        summary: { hosts: hosts.length, canonicalHosts: inventory.state === 'available' ? canonical.size : null, hostedHosts: live.size,
+            diagnosisStates: hosts.reduce((counts, host) => { counts[host.diagnosisDetails.status] = (counts[host.diagnosisDetails.status] ?? 0) + 1; return counts; }, {}),
+            cpu: { meanBusyPercent: cpu.length ? cpu.reduce((sum, host) => sum + host.cpu.percent, 0) / cpu.length : null, freshHosts: cpu.length, totalHosts: hosts.length,
+                meaning: 'arithmetic mean across fresh host busy percentages; not core weighted; inventory aliases can share physical machines' } },
+        coverage: { sourcesAvailable: Object.values(sources).filter(source => source.state === 'available').length, sourcesTotal: 7,
+            invalidHostedRecords: rows(fleet.data.hosts).length - live.size, invalidCanonicalRecords: rows(inventory.data.hosts).length - canonical.size,
+            invalidSupplementalRecords: components.size - supplemental.size,
+            sharedSnapshots: rows(shared.data.snapshots).map(entry => {
+                const snapshot = row(entry.snapshot);
+                return { publisherId: safeFleetText(entry.publisherId), hosts: rows(snapshot.hosts).length,
+                    ...observation(snapshot.observedAt, now, num(snapshot.staleAfterSeconds) ?? 120, snapshot.collectorError) };
+            }),
+            localCollector: 'not queried; shared published samples only',
+            limits: 'one read per source; at most 512 devices, 800 buckets and 100 alert types per bucket; no event pagination, SSH, scans or new latency probes',
+            missingSources: Object.entries(sources).filter(([, source]) => source.state !== 'available').map(([name, source]) => ({ name, reason: source.reason })),
+            consistency: 'independent source reads, not a transaction; component observations and ages retained' }, alerts, inputLag, hosts };
+}
+function age(value) { return `${value.state}, age ${value.ageSeconds === null ? 'unknown' : `${Math.round(value.ageSeconds)}s`}${value.reason ? `, ${value.reason}` : ''}`; }
+function bytes(value) { return value === null ? 'unknown' : `${(value / 1024 ** 3).toFixed(1)} GiB`; }
+export function surveyText(report) {
+    const lines = [`Fleet survey · ${report.scope} · ${report.generatedAt} · ${report.durationSeconds.toFixed(2)}s (request budget ${report.requestBudgetSeconds}s)`,
+        `${report.summary.hosts} machine records (${report.summary.canonicalHosts ?? 'unknown'} canonical); ${report.coverage.sourcesAvailable}/7 sources available.`,
+        `Diagnosis states: ${Object.entries(report.summary.diagnosisStates).map(([state, count]) => `${state}=${count}`).join(', ')}.`,
+        `CPU mean: ${report.summary.cpu.meanBusyPercent?.toFixed(1) ?? 'unknown'}% from ${report.summary.cpu.freshHosts}/${report.summary.cpu.totalHosts} fresh host samples. ${report.summary.cpu.meaning}.`];
+    if (report.alerts.state === 'available') {
+        lines.push(`Alerts · ${report.range} aligned buckets · ${report.alerts.observedBucketCounts.errors} critical / ${report.alerts.observedBucketCounts.warnings} warning rows; retries can repeat rows. Aggregate ends ${report.alerts.generatedAt} (response age ${Math.round(report.alerts.responseAgeSeconds)}s).`);
+        for (const type of report.alerts.byType)
+            lines.push(`  ${type.type}: ${type.errors} critical, ${type.warnings} warning; complete-bucket trend ${type.previous ?? 'unknown'} → ${type.recent ?? 'unknown'}${type.delta === null ? '' : ` (${type.delta >= 0 ? '+' : ''}${type.delta})`}`);
+        if (!report.alerts.byType.length)
+            lines.push('  No observed alert rows in returned buckets; ingestion completeness is unknown.');
+        if (report.alerts.trend)
+            lines.push(`  Trend windows: ${report.alerts.trend.previous.since}..${report.alerts.trend.previous.until} → ${report.alerts.trend.recent.since}..${report.alerts.trend.recent.until}; current partial bucket excluded.`);
+        for (const period of ['hour', 'today', 'yesterday']) {
+            const totals = report.alerts.totals[period], windows = report.alerts.windows;
+            lines.push(`  ${period}: ${totals ? `${totals.errors} critical, ${totals.warnings} warning, ${totals.sessions} sessions` : 'unknown'}; ${windows[period] ?? 'unknown'}..${period === 'yesterday' ? windows.yesterdayEnd ?? 'unknown' : windows.until} (${windows.timeZone ?? 'timezone unknown'}).`);
+        }
+        lines.push(`  Customer-unattributed alert rows: ${report.alerts.coverage.unattributedAlertRows ?? 'unknown'} (API query window may be wider). Ingestion completeness unknown; counts are not incident counts or failure rates.`);
+        if (report.alerts.coverage.omittedBuckets || report.alerts.coverage.omittedTypeRows)
+            lines.push(`  Capped coverage: ${report.alerts.coverage.omittedBuckets} buckets / ${report.alerts.coverage.omittedTypeRows} type rows omitted.`);
+    }
+    else
+        lines.push(`Alerts: unavailable (${report.alerts.reason}); counts and trends unknown.`);
+    const lag = report.inputLag.latestSampledBucket, coverage = report.inputLag.coverage;
+    lines.push(`Input lag: ${lag ? `${lag.medianMs.toFixed(1)}ms median, ${lag.samples} samples in bucket ${lag.timestamp} (bucket age ${Math.round(lag.bucketAgeSeconds)}s; individual sample age unknown)` : `no sampled bucket (${report.inputLag.reason ?? 'no changed samples'})`}.`, `  Device coverage ${coverage.sampledDevices ?? 'unknown'} sampled / ${coverage.requestedDevices} requested / ${coverage.eligibleDevices} eligible; ${coverage.omittedDevices} omitted (limit ${coverage.deviceLimit}).`, `  Outcomes: ${report.inputLag.outcomes ? Object.entries(report.inputLag.outcomes).map(([key, count]) => `${key}=${count ?? 'unknown'}`).join(', ') : 'unknown'}. Missing outcomes are not successful latency samples.`);
+    for (const host of report.hosts) {
+        lines.push('', `${host.id} · ${host.role} · CPU ${host.cpu.percent?.toFixed(1) ?? 'unknown'}% [${age(host.cpu)}] · RAM ${bytes(host.memory.usedBytes)}/${bytes(host.memory.totalBytes)} [${age(host.memory)}] · Storage ${bytes(host.storage.usedBytes)}/${bytes(host.storage.totalBytes)} [${age(host.storage)}]`, `  ${host.diagnosis}`, `  Service ${age(host.health)} at ${host.health.observedAt ?? 'missing'}; details ${age(host.serviceChecks)}; process ${age(host.processChecks)}; admission ${age(host.admission.observation)}.`, `  Release ${host.release.actualVersion ?? host.release.version ?? 'unknown'} / expected ${host.release.expectedVersion ?? 'unknown'} at ${host.release.observedAt ?? 'missing'}; input lag highest device median ${host.inputLag.highestDeviceMedianMs?.toFixed(1) ?? 'unknown'}ms (${host.inputLag.sampledDevices ?? 'unknown'}/${host.inputLag.selectedDevices} selected devices sampled; window median, individual age unknown).`);
+        if (host.admission.operation)
+            lines.push(`  Operation ${host.admission.operation.operationId ?? 'unknown'} · owner ${host.admission.operation.owner ?? 'unknown'} · ${host.admission.operation.phase ?? 'unknown'} / ${host.admission.operation.status ?? 'unknown'} [${age(host.admission.operation)}].`);
+    }
+    for (const source of report.coverage.missingSources)
+        lines.push(`Missing source: ${source.name} · ${source.reason}.`);
+    for (const [name, source] of Object.entries(report.sources))
+        lines.push(`Source ${name}: ${source.state}, generated ${source.generatedAt ?? 'unknown'}, response age ${source.responseAgeSeconds === null ? 'unknown' : `${Math.round(source.responseAgeSeconds)}s`}${source.reason ? `, ${source.reason}` : ''}.`);
+    lines.push(`Coverage: ${report.coverage.localCollector}. ${report.coverage.consistency}. ${report.coverage.limits}.`);
+    return lines.join('\n');
+}

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

@@ -0,0 +1,331 @@
+import { row, rows, str, num, stamp, time, pick, observation, componentHosts, hostReport, safeFleetText, validFleetId } from './run-cloud-fleet-observations.js';
+export { safeFleetText } from './run-cloud-fleet-observations.js';
+import { readFileSync, statSync } from 'node:fs';
+import { ApiClient, ApiError } from '../api.js';
+import { requireCredentials } from '../config.js';
+import { surveyFleet, surveyText } from './run-cloud-fleet-survey.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'];
+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 && !validFleetId(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 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, jenkins] = 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),
+        readSource(client, '/run-cloud/admin/jenkins'),
+    ]);
+    for (const [source, key] of [[inventory, 'hosts'], [shared, 'snapshots'], [diagnostics, 'diagnoses'], [jenkins, 'nodes']]) {
+        if (source.state === 'available' && !Array.isArray(source.data[key])) {
+            source.state = 'unavailable';
+            source.reason = 'invalid_response_shape';
+            source.data = {};
+        }
+    }
+    if (jenkins.data.state === 'unavailable') {
+        jenkins.state = 'unavailable';
+        jenkins.reason = 'jenkins_collection_unavailable';
+    }
+    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]) : {}, {
+        inventoryTtl: num(inventory.data.staleAfterSeconds) ?? 30, jenkins: jenkins.data,
+    }));
+    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 ?? source.data.observedAt), 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), jenkins: sourceStatus(jenkins),
+            ...(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('survey [hostId]').description('Survey all fleet signals in seconds; authenticated admin reads, no local services')
+        .option('--json', 'Structured metrics, diagnosis, observations and coverage')
+        .option('--range <range>', 'Alert/input-lag window: 1h, 6h, 24h, 7d', '24h')
+        .action((hostId, opts) => action(async () => {
+        const credentials = requireCredentials(), apiOrigin = new URL(credentials.apiUrl).origin;
+        const report = await surveyFleet(new ApiClient(credentials.apiUrl, credentials.token), { hostId, range: opts.range });
+        console.log(opts.json ? JSON.stringify({ ...report, apiOrigin }, null, 2) : `${apiOrigin}\n${surveyText(report)}`);
+    }));
+    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/commands/run-cloud-machine-diagnosis.js

@@ -0,0 +1,136 @@
+export function processFreshness(scan, now) {
+    if (!scan?.observedAt)
+        return 'never observed';
+    if (scan.sourceUnavailable)
+        return 'source unavailable';
+    if (scan.error)
+        return 'collection failed';
+    const timestamp = Date.parse(scan.observedAt);
+    if (!Number.isFinite(timestamp) || timestamp > now + 5000 || now - timestamp > scan.staleAfterSeconds * 1000)
+        return 'stale';
+    return 'fresh';
+}
+export function leaseStateLabel(state) {
+    return { accepting: 'Lease gate open', rejecting: 'Lease gate closed', unknown: 'Lease gate unknown', held: 'Operator hold' }[state] ?? state;
+}
+export function operatorHeld(host) {
+    return [host.fence, host.requestedFence].some(fence => fence && ['experiment', 'maintenance'].includes(fence.kind));
+}
+export function hostLeaseState(host) {
+    if (operatorHeld(host))
+        return 'held';
+    return host.acceptsLeases === true ? 'accepting' : host.acceptsLeases === false ? 'rejecting' : 'unknown';
+}
+export function hostLeaseStatus(host) {
+    const gate = leaseStateLabel(host.acceptsLeases === true ? 'accepting' : host.acceptsLeases === false ? 'rejecting' : 'unknown');
+    return operatorHeld(host) ? `Operator hold · ${gate.toLowerCase()}` : gate;
+}
+export function redactSensitiveText(value) {
+    if (!value)
+        return value ?? '';
+    return value
+        .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(/(\bBearer\s+)[A-Za-z0-9._~+/=-]+/gi, '$1[redacted]')
+        .replace(/([?&](?:token|authorization|secret|credential|signature|api[_-]?key|x-amz-(?:credential|signature)|x-goog-(?:credential|signature))=)[^\s&#]+/gi, '$1[redacted]')
+        .replace(/((?:token|authorization|secret|credential|signature|api[_-]?key)\s*[:=]\s*)[^\s,;}]+/gi, '$1[redacted]');
+}
+const ready = (state) => ['clean', 'ready', 'healthy', 'serving', 'connected'].includes(state);
+const responding = (state) => ready(state) || state === 'busy';
+export const observationCurrent = (at, now, seconds) => {
+    const time = at ? Date.parse(at) : NaN;
+    return Number.isFinite(time) && time <= now + 5000 && now - time <= seconds * 1000;
+};
+export function jenkinsObservedState(node, at, now, seconds = 30, unavailable = false) {
+    if (unavailable || !node || !at || !Number.isFinite(Date.parse(at)) || Date.parse(at) > now + 5000)
+        return 'unknown';
+    if (!observationCurrent(at, now, seconds))
+        return 'stale';
+    return node.offline === true ? 'offline' : node.offline === false ? 'ready' : 'unknown';
+}
+export function machineDiagnosis(host, hosted, observedState, now, staleAfterSeconds = 120) {
+    const faults = [], findings = [], checks = [];
+    let status = ready(observedState) ? 'ready' : observedState;
+    const observed = observationCurrent(host.observedAt, now, staleAfterSeconds);
+    const serviceCurrent = !['stale', 'unknown', 'inspection-unavailable'].includes(observedState) && observed;
+    if (host.observedAt && !observed && status !== 'unknown')
+        status = 'stale';
+    if (!host.observedAt) {
+        status = 'unknown';
+        checks.push('service never observed');
+    }
+    else if (!serviceCurrent)
+        checks.push('service checks stale or unavailable; last state retained');
+    else if (observedState === 'unreachable')
+        checks.push('service unreachable from collector; cause unconfirmed');
+    else if (['down', 'runtime-unavailable', 'agent-running-no-health', 'offline'].includes(observedState))
+        faults.push(`service reports ${observedState}`);
+    const release = hosted?.release;
+    const drift = release?.matches === false && [
+        [release.expectedPackage, release.actualPackage], [release.expectedVersion, release.actualVersion], [release.expectedBuild, release.actualBuild],
+    ].some(([expected, actual]) => expected && actual && expected !== actual);
+    if (drift)
+        findings.push(`release drift: ${release.actualVersion ?? 'reported artifact'}; expected ${release.expectedVersion ?? 'configured artifact'}`);
+    else if (release?.matches !== true && host.role !== 'jenkins')
+        checks.push('release match not verified');
+    if (observedState === 'degraded' && !drift)
+        checks.push('reported degradation has no confirmed cause');
+    const sample = host.hostDiagnostics;
+    if (!sample)
+        checks.push('detailed service checks missing');
+    else if (sample.collectionError || !observationCurrent(sample.observedAt, now, sample.staleAfterSeconds))
+        checks.push('detailed service checks stale or unavailable');
+    else {
+        const service = sample.services.find(row => row.name === 'serve-sim');
+        if (host.role === 'simulator' && service && ['failed', 'stopped', 'exited', 'disabled'].includes(service.state ?? ''))
+            faults.push(`serve-sim is ${service.state}`);
+        if (host.role === 'simulator' && sample.packageMatchesService === false)
+            faults.push('service executable differs from installed package');
+        if (sample.power.thermalWarning || sample.power.performanceWarning)
+            findings.push('host reports thermal or performance warnings');
+        if ((sample.coreSimulator.orphaned ?? 0) > 0)
+            findings.push(`${sample.coreSimulator.orphaned} orphaned CoreSimulator bootstrap(s)`);
+        if ((sample.coreSimulator.externalBooted ?? 0) > 0)
+            findings.push(`${sample.coreSimulator.externalBooted} external booted simulator(s) consume memory`);
+        if ((sample.recording.failed ?? 0) > 0)
+            checks.push(`${sample.recording.failed} retained recording failure(s); current service scored separately`);
+    }
+    if (serviceCurrent && (host.capacity?.dirty ?? 0) > 0)
+        faults.push(`${host.capacity.dirty} dirty pool record(s)`);
+    const scan = host.processScan;
+    if (!scan)
+        checks.push('process checks missing');
+    else {
+        const freshness = processFreshness(scan, now);
+        const malicious = scan.iocs.some(ioc => ['present', 'active'].includes(ioc.status)) || scan.findings.some(finding => finding.reason === 'known_ioc');
+        if (malicious)
+            findings.unshift(`known malicious daemon detected${freshness === 'fresh' ? '' : ' in retained evidence; recheck required'}`);
+        else if (scan.status === 'critical')
+            findings.unshift('critical process finding requires review');
+        const review = scan.findings.filter(finding => ['rooted_workload', 'long_lived_workload', 'identity_changed', 'unreviewed_persistence'].includes(finding.reason));
+        if (review.length)
+            findings.push(`${review.length} process or persistence finding(s) need review`);
+        if (scan.iocs.some(ioc => ioc.contained))
+            findings.push('quarantined daemon evidence is contained');
+        if (freshness !== 'fresh' || scan.error)
+            checks.push(`process checks ${scan.error ?? freshness}`);
+        else if (!scan.root || scan.coverage.iocs === 'partial' || scan.iocs.some(ioc => ioc.status === 'unknown'))
+            checks.push('process checks incomplete; privileged visibility not established');
+        if (scan.baseline.state !== 'reviewed')
+            checks.push('process baseline not enrolled');
+        if (scan.status === 'warning' && !review.length && !malicious)
+            checks.push('process checks warning; see scanner details');
+    }
+    const actionable = findings.filter(finding => !finding.startsWith('quarantined'));
+    if (faults.length || actionable.length)
+        status = 'degraded';
+    const parts = [`${host.id}: ${status}.`,
+        faults.length ? `Service faults: ${faults.join('; ')}.` : serviceCurrent && (responding(observedState) || (observedState === 'degraded' && drift)) ? `Service responding${observedState === 'busy' ? '; capacity busy' : ''}.` : 'Current service health unverified.',
+        findings.length ? `Findings: ${findings.join('; ')}.` : '',
+        `Admission: ${hostLeaseStatus(host)}${host.fence ? `; ${host.fence.state ?? 'unconfirmed'} ${host.fence.kind} fence — ${host.fence.reason}` : ''}.`,
+        checks.length ? `Checks: ${checks.join('; ')}.` : 'Checks current.',
+        faults.length ? 'Next: inspect retained service diagnostics.' : actionable.length ? 'Next: review the release or scanner evidence.' : checks.length ? 'Next: confirm missing checks with read-only collection.' : '',
+    ];
+    return { status, summary: redactSensitiveText(parts.filter(Boolean).join(' ')),
+        faults: faults.map(redactSensitiveText), findings: findings.map(redactSensitiveText), checks: checks.map(redactSensitiveText) };
+}

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.167';

package/package.json

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