@intflow/sentinelctl 0.4.0 → 0.6.0

package/README.md

@@ -46,39 +46,45 @@ Mistyped commands and options get a suggestion (`Did you mean --range?`), and ev
 ## Fleet overview and metrics
 
 ```bash
-sentinelctl fleet summary                                   # status, attention, busiest devices, log levels, top/rising/new error patterns
-sentinelctl fleet summary -r 1h -o json                     # about 5KB
+sentinelctl fleet summary                                   # status, offline split, attention, busiest devices, trends, log levels, error patterns
+sentinelctl fleet summary -r 1h -o json                     # about 10KB
 sentinelctl metrics top memory -r 7d                        # devices ranked by 7-day average memory + fleet distribution
 sentinelctl metrics top disk --agg last --above 85 --top 50
+sentinelctl metrics top diskDaysLeft --below 14             # disks that fill up within two weeks at the current growth
 sentinelctl metrics top cpu --agg p95 -r 24h --compare --sort change
-sentinelctl metrics top reboots -r 7d --above 0
+sentinelctl metrics top reboots -r 7d --above 0             # many devices reboot daily on schedule; compare with p50
 sentinelctl metrics top networkTx -r 24h --label fleet=edge -o json
+sentinelctl devices correlate <agent-id> --peak cpu -r 24h      # metrics and logs around the CPU peak
+sentinelctl devices correlate <agent-id> --at 2026-09-30T14:58:00+09:00 --window 30m
 ```
 
-`metrics top` runs one query over every device: `--agg avg|max|min|p95|last` per device over `-r 1h|6h|24h|7d|30d` (or `--from/--to`, up to 30 days), ranked, with min/p50/p90/p95/max across devices. Metrics: cpu, memory, disk, swap, load, temperature, processes, tcpConnections, networkRx, networkTx, reboots. `--compare` adds the previous window of the same length. Device filters work like `devices list`; retired devices are excluded by default.
+`metrics top` runs one query over every device: `--agg avg|max|min|p95|last` per device over `-r 1h|6h|24h|7d|30d` (or `--from/--to`, up to 30 days), ranked, with min/p50/p90/p95/max across devices. Metrics: cpu, memory, disk, swap, load, temperature, processes, tcpConnections, networkRx, networkTx, reboots, diskDaysLeft. `--compare` adds the previous window of the same length. Device filters work like `devices list`; retired devices are excluded by default.
 
-## Logs
+## Logs: count first, read last
 
 ```bash
-sentinelctl logs search timeout -r 1h
-sentinelctl logs search -a <agent-id> -l error -r 24h --all
-sentinelctl logs search -s sshd.service --from 2026-09-30T00:00:00Z --to 2026-09-30T06:00:00Z
-sentinelctl logs search -l error -f                        # follow new errors (Ctrl+C to stop)
-sentinelctl logs search -q boom -o ndjson | jq .message
+sentinelctl logs stats -l error -r 24h --by message --compare        # which patterns, what changed
+sentinelctl logs groups -l error -r 24h                              # every device x source x pattern, with count, first/last and latest line
+sentinelctl logs stats -p "<pattern>" --by agent --timeline -r 7d    # where and since when
+sentinelctl logs search -p "<pattern>" -a <agent-id> -r 24h -n 50    # a few raw lines
 sentinelctl logs context -a <agent-id> -s app.service -t 2026-09-30T01:02:03.456Z
-sentinelctl logs histogram -l error -r 24h
-sentinelctl logs stats -l error -r 1h --by source          # exact counts, one server-side query
-sentinelctl logs stats -l error -r 24h --by agent --top 10
-sentinelctl logs stats -a <agent-id> -r 7d --by message    # message patterns, numbers collapsed to <N>
-sentinelctl logs stats -l error -r 24h --by message --compare --sort change   # what is new or growing
+sentinelctl logs facets -l error -r 24h                              # top devices, sources, severities at a glance
+sentinelctl logs histogram -a <agent-id> -r 30d
 sentinelctl logs sources -r 24h
+sentinelctl logs stats --service payment-api --env prod -l error -r 7d --by message   # one application across devices (needs service/env labels)
+sentinelctl logs stats -l error -r 24h --by service
+sentinelctl logs search -l error --since <nextSince> -o ndjson       # poll only new logs
 ```
 
-`logs stats --compare` also counts the previous window of the same length and adds `previousCount`, `change` and `isNew` per group. Message groups carry `searchText`, ready for `logs search -q`.
+- `logs search` returns at most 10,000 lines (250 per request, `--pages N` up to 40 or `--all`). On a busy fleet that covers minutes, so never download logs to count or summarize them: `logs stats` and `logs groups` count every log in the window on the server.
+- `-p/--pattern` takes a pattern exactly as `logs stats --by message` or `logs groups` print it (numbers as `<N>`) and matches only that pattern. `-q` matches words case-insensitively; add `--case-sensitive` for a much faster exact-case match.
+- `--dedupe` folds lines repeated within the same second; `--collapse` on `logs search` is the same as `logs groups`.
+- Windows: `15m`, `1h`, `6h`, `24h`, `7d`, `30d` or `--from/--to` up to the retention period (31 days by default). Fleet-wide aggregations over 7 days need `-a`, `-s`, `-p` or `--case-sensitive`; the server answers `log_query_too_broad` otherwise.
+- Aggregations over a day are computed per day and finished days are cached, so repeating a long query is cheap; the CLI continues automatically when the server needs several requests.
+- Levels: `emergency`, `critical` and `error` include more severe levels; `warning`, `info` (with notice) and `debug` match that level only.
+- `--fields` (raw fields) is admin-only and audited. `--follow` polls at most every 5 seconds and is meant for humans.
 
-Windows are `15m`, `1h`, `6h`, `24h`, `7d`, or `--from`/`--to` up to 30 days. One page holds 50, 100 or 250 logs; when you ask for several pages (`--pages N`, at most 40, or `--all`) the CLI fetches 250 per request and stops at 10,000 logs. To answer "how many" or "which devices the most", use `logs stats`: it aggregates on the server and returns exact counts instead of downloading logs. `--fields` (raw fields) is admin-only and audited. `--follow` polls at most every 5 seconds.
-
-Each user can run 2 log queries and 2 metric aggregations at a time, web and CLI combined; a third concurrent query gets 429 and GET requests retry automatically with backoff.
+Each user can run 2 log queries and 2 metric aggregations at a time (web and CLI combined) and spend 60 seconds of log query time per minute; GET requests that get 429 retry automatically with backoff.
 
 ## Devices and metadata
 
@@ -117,6 +123,10 @@ sentinelctl admin operations -r 7d
 
 Any other endpoint: `sentinelctl api "/api/devices?status=offline"`.
 
+## Updates
+
+The server tells the CLI the latest version; when a newer one exists the CLI prints one notice a day on stderr (`{"notice":{"type":"update_available"}}` with -o json). Update with `npm install -g sentinelctl@latest`. A CLI older than the server minimum gets exit code 3 with the same command. `SENTINELCTL_NO_UPDATE_NOTICE=1` turns the notice off.
+
 ## Output and exit codes
 
 - `--select agentId,displayName,status,metadata.role` keeps only those fields of each item in json/ndjson output (plus top-level scalars), e.g. `devices list --all -o json` drops from ~700KB to ~20KB. `devices show --series none` (or `--series cpu,memory`) drops time series.
@@ -126,9 +136,10 @@ Any other endpoint: `sentinelctl api "/api/devices?status=offline"`.
 
 ## Publishing
 
-Publish the scoped package first, then the alias with the same version (`cli/unscoped/package.json` depends on it). Accounts with two-factor authentication need an interactive terminal for the browser approval.
+GitHub Actions publishes both packages (`.github/workflows/publish-cli.yml`) with npm trusted publishing, so no npm token is stored.
 
-```bash
-cd cli && npm test && npm publish --access public
-cd unscoped && npm publish --access public
-```
+1. Bump `cli/package.json`, `cli/unscoped/package.json` (version and its `@intflow/sentinelctl` dependency) and `cliLatestVersion` in `config/dashboard.json` to the same version; `node scripts/check-cli-release.mjs` checks this.
+2. Commit, then push a tag: `git tag cli-v0.6.0 && git push origin cli-v0.6.0`.
+3. The workflow runs the CLI checks and tests, publishes `@intflow/sentinelctl`, waits for the registry, then publishes the `sentinelctl` alias. Versions already on npm are skipped. Run it manually (Actions → publish-cli) to verify and pack without publishing.
+
+One-time setup on npmjs.com, for each of the two packages: Settings → Trusted Publisher → GitHub Actions, organization or user `yeon3724`, repository `sentinel-fleet-console`, workflow `publish-cli.yml`, environment `npm`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intflow/sentinelctl",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Sentinel Fleet Console CLI: search device logs, inspect status and metrics, edit metadata and manage roles",
   "type": "module",
   "bin": {

package/src/client.mjs

@@ -9,9 +9,7 @@ export class ApiError extends Error {
   }
 }
 
-const userAgent = 'sentinelctl';
-
-export function createClient({ server, token = null, fetch: fetchImplementation = globalThis.fetch, timeoutMs = 60_000, maxRetries = 5, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
+export function createClient({ server, token = null, userAgent = 'sentinelctl', onVersions = null, fetch: fetchImplementation = globalThis.fetch, timeoutMs = 60_000, maxRetries = 5, sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)) }) {
   async function request(method, path, { query, body, auth = true, allowStatuses = [] } = {}) {
     const url = new URL(path, server);
     for (const [key, value] of Object.entries(query ?? {})) {
@@ -36,6 +34,8 @@ export function createClient({ server, token = null, fetch: fetchImplementation
         const reason = error?.name === 'TimeoutError' ? 'timed out' : 'could not connect';
         throw new ApiError(`Request to ${url.origin} ${reason}.`, { code: 'network_error' });
       }
+      const latest = response.headers.get('x-sentinelctl-latest');
+      if (onVersions && latest) onVersions({ latest, minimum: response.headers.get('x-sentinelctl-minimum') });
       const text = await response.text();
       let payload = {};
       try {

package/src/commands.mjs

@@ -4,7 +4,7 @@ import { ageText, localTime, percentText, renderKeyValues, renderTable, singleLi
 
 export const roleLabels = { viewer: 'viewer (read-only)', editor: 'editor', admin: 'admin' };
 export const outputChoices = ['table', 'json', 'ndjson'];
-const logRanges = ['15m', '1h', '6h', '24h', '7d'];
+const logRanges = ['15m', '1h', '6h', '24h', '7d', '30d'];
 const deviceRanges = ['30m', '1h', '6h', '24h', '7d', '30d'];
 const logLevels = ['emergency', 'critical', 'error', 'warning', 'info', 'debug'];
 const deviceStatuses = ['all', 'online', 'delayed', 'offline', 'unknown', 'maintenance', 'retired'];
@@ -13,15 +13,29 @@ const maxPages = 40;
 const deviceSorts = ['attention', 'status', 'displayName', 'cpu', 'memory', 'disk', 'load', 'temperature', 'ageSeconds', 'role', 'site', 'group', 'incidentCount'];
 
 const logFilterOptions = {
-  query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Case-insensitive text in the message. Positional words are appended.' },
-  agent: { alias: 'a', type: 'string', placeholder: 'id', description: 'Exact agent ID (find it with `devices lookup`).' },
-  level: { alias: 'l', type: 'string', choices: logLevels, description: 'This severity and above (error includes emergency/alert/critical).' },
-  source: { alias: 's', type: 'string', placeholder: 'source', description: 'Exact source: systemd unit, container name, syslog identifier (see `logs sources`).' },
-  range: { alias: 'r', type: 'string', choices: logRanges, description: 'Relative window. Default 15m when --from/--to are absent.' },
-  from: { type: 'string', placeholder: 'ISO', description: 'Absolute window start, e.g. 2026-09-30T00:00:00+09:00. Requires --to; at most 30 days.' },
-  to: { type: 'string', placeholder: 'ISO', description: 'Absolute window end.' },
+  query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Words in the message, case-insensitive. Positional words are appended.' },
+  pattern: { alias: 'p', type: 'string', placeholder: 'pattern', description: 'Exact pattern as printed by logs stats --by message or logs groups (<N> = number).' },
+  'case-sensitive': { type: 'boolean', description: 'Case-sensitive -q: much faster, misses other casings.' },
+  agent: { alias: 'a', type: 'string', placeholder: 'id', description: 'Agent ID (see devices lookup).' },
+  level: { alias: 'l', type: 'string', choices: logLevels, description: 'emergency/critical/error include more severe levels; warning, info, debug are exact.' },
+  source: { alias: 's', type: 'string', placeholder: 'source', description: 'systemd unit, container or syslog identifier (see logs sources).' },
+  service: { type: 'string', placeholder: 'name', description: '`service` label, across devices.' },
+  env: { type: 'string', placeholder: 'name', description: '`env` label.' },
+  range: { alias: 'r', type: 'string', choices: logRanges, description: 'Relative window (default 15m).' },
+  from: { type: 'string', placeholder: 'ISO', description: 'Start, e.g. 2026-09-30T09:00:00+09:00 (with --to; up to 31 days).' },
+  to: { type: 'string', placeholder: 'ISO', description: 'End.' },
 };
 
+async function getComplete(context, path, query) {
+  let body = await context.client.get(path, query);
+  for (let round = 0; body.complete === false && round < 20; round += 1) {
+    context.note(`Aggregating step ${body.coverage?.done ?? 0}/${body.coverage?.chunks ?? '?'}, continuing…`);
+    body = await context.client.get(path, query);
+  }
+  if (body.complete === false) context.hint(`Partial result: ${body.coverage?.done}/${body.coverage?.chunks} steps aggregated. Run the same command again to continue (finished days are cached).`);
+  return body;
+}
+
 function logCriteria(options, positionals) {
   const text = [options.query, ...positionals].filter(Boolean).join(' ');
   if ((options.from && !options.to) || (!options.from && options.to)) {
@@ -33,8 +47,10 @@ function logCriteria(options, positionals) {
       throw new UsageError(`Cannot parse --${name}: ${value}`, { hint: 'Use ISO 8601, e.g. 2026-09-30T09:00:00+09:00.' });
     }
   }
+  if (options['case-sensitive'] && !text) throw new UsageError('--case-sensitive needs search text (-q).');
   return {
-    q: text || undefined, agentId: options.agent, level: options.level, source: options.source,
+    q: text || undefined, agentId: options.agent, level: options.level, source: options.source, service: options.service, env: options.env,
+    pattern: options.pattern, match: options['case-sensitive'] ? 'exact' : undefined,
     range: options.from ? undefined : (options.range ?? '15m'),
     from: options.from ? new Date(options.from).toISOString() : undefined,
     to: options.to ? new Date(options.to).toISOString() : undefined,
@@ -94,14 +110,43 @@ function logKey(log) {
 function emptyLogHint(criteria) {
   const tips = [];
   if (criteria.range && criteria.range !== '7d') tips.push('widen the window (-r 24h or -r 7d)');
-  if (criteria.q) tips.push('shorten or drop the search text');
+  if (criteria.q) tips.push(criteria.match === 'exact' ? 'drop --case-sensitive' : 'shorten or drop the search text');
+  if (criteria.pattern) tips.push('check the pattern with `sentinelctl logs stats --by message`');
   if (criteria.source) tips.push('check source names with `sentinelctl logs sources -r 24h`');
   if (criteria.agentId) tips.push('check the agent ID with `sentinelctl devices lookup <name>`');
   if (criteria.level) tips.push('drop -l');
   return tips.length ? `No logs matched. Try: ${tips.join('; ')}.` : 'No logs matched.';
 }
 
+function timestampNanos(value) {
+  const match = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(?:\.(\d{1,9}))?(Z|[+-]\d{2}:\d{2})$/.exec(String(value));
+  if (!match) return BigInt(Date.parse(value)) * 1_000_000n;
+  return BigInt(Date.parse(`${match[1]}${match[3]}`)) * 1_000_000n + BigInt((match[2] ?? '').padEnd(9, '0'));
+}
+
+function dedupeLogs(logs) {
+  const result = [];
+  for (const log of logs) {
+    const previous = result.at(-1);
+    const sameSecond = previous && String(previous.timestamp).slice(0, 19) === String(log.timestamp).slice(0, 19);
+    const strip = (message) => String(message).replace(/^\[[^\]]+\]\s*/, '');
+    if (sameSecond && previous.agentId === log.agentId && previous.source === log.source && strip(previous.message) === strip(log.message)) {
+      previous.repeat = (previous.repeat ?? 1) + 1;
+      continue;
+    }
+    result.push({ ...log });
+  }
+  return result;
+}
+
 async function logsSearch(context, { options, positionals }) {
+  if (options.collapse) return logsGroups(context, { options, positionals });
+  if (options.since) {
+    if (options.from || options.to || options.range) throw new UsageError('--since cannot be combined with --range/--from/--to.');
+    if (!Number.isFinite(Date.parse(options.since))) throw new UsageError(`Cannot parse --since: ${options.since}`, { hint: 'Pass the nextSince value printed by the previous run.' });
+    options.from = options.since;
+    options.to = new Date().toISOString();
+  }
   const criteria = logCriteria(options, positionals);
   const paging = options.all || options.pages > 1;
   const limit = options.fields ? 50 : (options.limit ?? (paging ? 250 : 100));
@@ -120,8 +165,17 @@ async function logsSearch(context, { options, positionals }) {
     if (!last.hasMore || !last.nextCursor) break;
     cursor = last.nextCursor;
   }
-  emit(context, context.global.output === 'json' ? { criteria: last.criteria, window: last.window, count: logs.length, hasMore: last.hasMore, logs } : logs,
-    () => renderTable(logs, logColumns, { width: context.width, wide: options.wide }));
+  if (options.since) {
+    const since = timestampNanos(options.since);
+    for (let index = logs.length - 1; index >= 0; index -= 1) if (timestampNanos(logs[index].timestamp) <= since) logs.splice(index, 1);
+  }
+  const shown = options.dedupe ? dedupeLogs(logs) : logs;
+  const nextSince = logs[0]?.timestamp ?? options.since ?? null;
+  emit(context, context.global.output === 'json'
+    ? { criteria: last.criteria, window: last.window, count: logs.length, ...(options.dedupe ? { rows: shown.length } : {}), hasMore: last.hasMore, ...(options.since ? { nextSince } : {}), logs: shown }
+    : shown,
+  () => renderTable(shown, options.dedupe ? [...logColumns.slice(0, 4), { header: 'x', value: (log) => (log.repeat ? `×${log.repeat}` : ''), max: 5 }, logColumns[4]] : logColumns, { width: context.width, wide: options.wide }));
+  if (options.since) context.hint(`Next time: --since ${nextSince}`);
   if (!logs.length) context.hint(emptyLogHint(criteria));
   else context.note(`${logs.length} logs · ${localTime(last.window.start)} → ${localTime(last.window.end)}`);
   if (last.hasMore && options.all) context.hint(`Stopped at the ${maxPages * 250}-log cap. Narrow the filters, or use \`sentinelctl logs stats\` for counts.`);
@@ -157,17 +211,39 @@ async function followLogs(context, query, options) {
 }
 
 
-const statsDimensions = ['source', 'agent', 'level', 'message'];
+const statsDimensions = ['source', 'agent', 'level', 'message', 'service'];
+
+const sparkBlocks = ['▁', '▂', '▃', '▄', '▅', '▆', '▇', '█'];
+
+function sparkline(points, window, step) {
+  if (!points?.length || !step) return '';
+  const start = Math.floor(Date.parse(window.start) / 1000 / step) * step;
+  const end = Date.parse(window.end) / 1000;
+  const counts = new Map(points);
+  const values = [];
+  for (let at = start; at < end; at += step) values.push(counts.get(at) ?? 0);
+  const peak = Math.max(1, ...values);
+  return values.map((value) => (value ? sparkBlocks[Math.min(7, Math.floor((value / peak) * 7.999))] : ' ')).join('');
+}
+
+function quoteArgument(text) {
+  return `"${String(text).replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
+}
+
+function narrowingHint(criteria) {
+  const window = criteria.range ? `-r ${criteria.range}` : `--from ${criteria.from} --to ${criteria.to}`;
+  return { window, level: criteria.level ? ` -l ${criteria.level}` : '' };
+}
 
 async function logsStats(context, { options, positionals }) {
   const criteria = logCriteria(options, positionals);
   if (options.sort === 'change' && !options.compare) {
     throw new UsageError('--sort change needs --compare.', { hint: 'Example: sentinelctl logs stats -l error -r 24h --by message --compare --sort change' });
   }
-  const body = await context.client.get('/api/logs/stats', {
-    ...criteria, by: options.by, top: options.top, compare: options.compare ? 1 : undefined, sort: options.sort,
+  const body = await getComplete(context, '/api/logs/stats', {
+    ...criteria, by: options.by, top: options.top, compare: options.compare ? 1 : undefined, sort: options.sort, timeline: options.timeline ? 1 : undefined,
   });
-  const label = { source: 'SOURCE', agent: 'DEVICE', level: 'LEVEL', message: 'MESSAGE PATTERN' }[body.criteria.by];
+  const label = { source: 'SOURCE', agent: 'DEVICE', level: 'LEVEL', message: 'MESSAGE PATTERN', service: 'SERVICE' }[body.criteria.by];
   const signed = (value) => (value === null || value === undefined ? '?' : value > 0 ? `+${value}` : String(value));
   emit(context, context.global.output === 'ndjson' ? body.groups : body, () => renderTable(body.groups, [
     { header: 'COUNT', value: (group) => String(group.count) },
@@ -176,10 +252,13 @@ async function logsStats(context, { options, positionals }) {
       { header: 'CHANGE', value: (group) => (group.isNew ? 'new' : signed(group.change)) },
     ] : [{ header: 'SHARE', value: (group) => (body.total ? `${((group.count / body.total) * 100).toFixed(1)}%` : '-') }]),
     { header: 'DEVICES', value: (group) => String(group.devices) },
+    ...(body.timelineStepSeconds ? [{ header: 'TREND', value: (group) => sparkline(group.timeline, body.window, body.timelineStepSeconds), max: 48 }] : []),
+    ...(body.timelineStepSeconds ? [{ header: 'LAST', value: (group) => (group.last ? localTime(group.last).slice(5, 16) : '-'), max: 11 }] : []),
     ...(body.criteria.by === 'agent' ? [{ header: 'AGENT ID', value: (group) => group.key, max: 36 }] : []),
     { header: label, value: (group) => (body.criteria.by === 'agent' ? group.displayName ?? group.host ?? group.key : group.key) },
   ], { width: context.width, wide: options.wide }));
   context.note(`${body.total} logs from ${body.devices} devices · ${localTime(body.window.start)} → ${localTime(body.window.end)}`);
+  if (body.timelineStepSeconds) context.note(`TREND: one column per ${Math.round(body.timelineStepSeconds / 60)} min; first/last (bucket precision) are in -o json.`);
   if (body.previous) {
     context.note(`Previous window ${localTime(body.previous.window.start)} → ${localTime(body.previous.window.end)}: ${body.previous.total} logs (${signed(body.total - body.previous.total)}) · ${body.newGroupCount} new groups`);
     if (body.falling?.length && body.criteria.sort !== 'change') {
@@ -190,13 +269,45 @@ async function logsStats(context, { options, positionals }) {
   if (body.truncated) context.hint(`Showing the top ${body.groups.length} of ${body.groupCount} groups. Raise --top (max 100) or add filters.`);
   if (body.approximate) context.hint('Message patterns are approximate on this server (collapse_nums is unavailable); narrow the window or filters for exact counts.');
   if (!body.total) context.hint(emptyLogHint(criteria));
-  const sample = body.groups.find((group) => group.searchText);
+  const sample = body.groups.find((group) => group.count > 0);
   if (body.criteria.by === 'message' && sample) {
-    context.hint(`See matching logs: sentinelctl logs search -q "${sample.searchText.replaceAll('"', '\\"')}" -r ${criteria.range ?? '24h'}${criteria.level ? ` -l ${criteria.level}` : ''} (searchText in -o json)`);
+    const { window, level } = narrowingHint(criteria);
+    context.hint(`Next: who and where → sentinelctl logs groups -p ${quoteArgument(sample.key)} ${window}${level}; raw lines → sentinelctl logs search -p ${quoteArgument(sample.key)} ${window} -n 50`);
   }
 }
 
-const metricNames = ['cpu', 'memory', 'disk', 'swap', 'load', 'temperature', 'processes', 'tcpConnections', 'networkRx', 'networkTx', 'reboots'];
+const groupColumns = [
+  { header: 'COUNT', value: (group) => String(group.count) },
+  { header: 'LAST', value: (group) => (group.last ? localTime(group.last).slice(5, 16) : '-'), max: 11 },
+  { header: 'DEVICE', value: (group) => group.displayName ?? group.agentId, max: 26 },
+  { header: 'SOURCE', value: (group) => group.source, max: 22 },
+  { header: 'PATTERN', value: (group) => group.pattern },
+];
+
+async function logsGroups(context, { options, positionals }) {
+  const criteria = logCriteria(options, positionals);
+  const body = await getComplete(context, '/api/logs/groups', { ...criteria, top: options.top ?? options.limit });
+  emit(context, context.global.output === 'ndjson' ? body.groups : body, () => renderTable(body.groups, groupColumns, { width: context.width, wide: options.wide }));
+  context.note(`${body.total} logs in ${body.groupCount} groups (${body.patternCount} patterns, ${body.devices} devices) · ${localTime(body.window.start)} → ${localTime(body.window.end)}`);
+  if (body.truncated) context.hint(`Showing ${body.groups.length} of ${body.groupCount} groups, largest first. Raise --top (max 500) or add filters.`);
+  if (body.approximate) context.hint('Patterns are approximate on this server (collapse_nums is unavailable).');
+  if (!body.total) context.hint(emptyLogHint(criteria));
+  const first = body.groups[0];
+  if (first) {
+    const { window } = narrowingHint(criteria);
+    context.hint(`Each group keeps its latest line in -o json (latest.message). Raw lines of one group: sentinelctl logs search -a ${first.agentId} -p ${quoteArgument(first.pattern)} ${window} -n 50`);
+  }
+}
+
+async function logsFacets(context, { options, positionals }) {
+  const criteria = logCriteria({ ...options, range: options.range ?? (options.from ? undefined : '1h') }, positionals);
+  const body = await context.client.get('/api/logs/facets', { ...criteria, top: options.top });
+  emit(context, body, () => Object.entries(body.facets).map(([field, values]) => `${field}:\n${values
+    .map((item) => `  ${String(item.count).padStart(9)}  ${item.displayName && item.displayName !== item.value ? `${item.displayName} (${item.value})` : item.value}`).join('\n')}`).join('\n'));
+  context.note(`${localTime(body.window.start)} → ${localTime(body.window.end)}`);
+}
+
+const metricNames = ['cpu', 'memory', 'disk', 'swap', 'load', 'temperature', 'processes', 'tcpConnections', 'networkRx', 'networkTx', 'reboots', 'diskDaysLeft'];
 const metricWindows = ['1h', '6h', '24h', '7d', '30d'];
 const deviceSeries = ['cpu', 'memory', 'disk', 'load', 'temperature', 'processes', 'tcpConnections', 'networkRx', 'networkTx', 'swap', 'uptime'];
 
@@ -247,7 +358,7 @@ async function metricsTop(context, { options, positionals }) {
 }
 
 async function fleetSummary(context, { options }) {
-  const body = await context.client.get('/api/fleet/summary', { range: options.range, logs: options.logs === false ? 0 : undefined });
+  const body = await context.client.get('/api/fleet/summary', { range: options.range, logs: options.logs === false ? 0 : undefined, trends: options.trends === false ? 0 : undefined });
   emit(context, body, () => {
     const counts = (record) => Object.entries(record ?? {}).sort((left, right) => right[1] - left[1]).map(([key, value]) => `${key} ${value}`).join(', ');
     const names = (devices) => devices.map((device) => device.displayName).join(', ');
@@ -264,9 +375,23 @@ async function fleetSummary(context, { options }) {
         { header: 'EXAMPLES', value: (entry) => names(entry.devices) },
       ], { width: context.width })
       : '  none');
+    const offline = body.devices.offline;
+    if (offline) {
+      sections.push('', `Offline: ${offline.within24h.length} within 24h${offline.within24h.length ? ` (${offline.within24h.map((device) => `${device.displayName} ${device.offlineHours}h`).join(', ')})` : ''} · ${offline.otherCount} for 1-7 days · ${offline.over7dCount} over 7 days`);
+    }
     sections.push('', 'Highest now (online, active):', renderKeyValues(Object.entries(body.resources).map(([field, devices]) => [
       field, devices.map((device) => `${device.displayName} ${field === 'temperature' ? `${device.value}°C` : `${device.value}%`}`).join(', ') || '-',
     ])));
+    if (body.trends?.error) sections.push('', `Trends: ${body.trends.error}`);
+    else if (body.trends) {
+      const list = (devices, format) => devices.map((device) => `${device.displayName} ${format(device)}`).join(', ') || 'none';
+      sections.push('', 'Trends:', renderKeyValues([
+        ['disk full <14d', list(body.trends.diskFullWithin14Days, (device) => `${device.value}d`)],
+        ['temperature +15°C', list(body.trends.temperatureRise, (device) => `${device.previous}→${device.value}°C`)],
+        [`reboots >${body.trends.rebootOutliers.threshold}/7d`, `${list(body.trends.rebootOutliers.devices, (device) => `${device.value}`)} (typical ${body.trends.rebootOutliers.typicalPerWeek}/7d)`],
+      ]));
+    }
+    if (body.logs?.complete === false) sections.push('', 'Logs: partial (some days still aggregating); run again to complete.');
     if (body.logs?.error) sections.push('', `Logs: ${body.logs.error}`);
     else if (body.logs) {
       const errors = body.logs.errors;
@@ -287,7 +412,7 @@ async function fleetSummary(context, { options }) {
     }
     return sections.join('\n');
   });
-  context.hint('Drill down: devices list --focus attention · logs stats -l error --by message --compare · metrics top memory -r 24h');
+  context.hint('Drill down: logs groups -l error -r 24h · logs stats -l error --by message --compare --timeline · metrics top diskDaysLeft · devices overview <id>');
 }
 
 async function logsContext(context, { options }) {
@@ -305,7 +430,7 @@ async function logsContext(context, { options }) {
 }
 
 async function logsHistogram(context, { options, positionals }) {
-  const body = await context.client.get('/api/logs/histogram', logCriteria(options, positionals));
+  const body = await getComplete(context, '/api/logs/histogram', logCriteria(options, positionals));
   emit(context, context.global.output === 'ndjson' ? body.buckets : body, () => {
     const peak = Math.max(1, ...body.buckets.map((bucket) => bucket.total));
     return renderTable(body.buckets, [
@@ -324,7 +449,7 @@ async function logsSources(context, { options }) {
     { header: 'SOURCE', value: (source) => source.value },
     { header: 'COUNT', value: (source) => String(source.count) },
   ], { width: context.width }));
-  context.note(`Top sources in a sample of the latest ${body.sampleSize} logs.`);
+  context.note(`Top ${body.sources.length} sources by exact count over ${body.range} (${body.total} logs).`);
 }
 
 const deviceColumns = [
@@ -427,6 +552,52 @@ async function devicesOverview(context, { options, positionals }) {
   ]));
 }
 
+function durationSeconds(value, name) {
+  const match = /^(\d+)([smh])$/.exec(String(value));
+  if (!match) throw new UsageError(`--${name} must look like 90s, 15m or 2h: ${value}`);
+  return Number(match[1]) * { s: 1, m: 60, h: 3600 }[match[2]];
+}
+
+const correlateMetricNames = ['cpu', 'memory', 'disk', 'load', 'temperature', 'swap', 'processes', 'tcpConnections', 'networkRx', 'networkTx'];
+const correlateUnits = { cpu: '%', memory: '%', disk: '%', swap: '%', temperature: '°C', networkRx: 'B/s', networkTx: 'B/s' };
+
+async function devicesCorrelate(context, { options, positionals }) {
+  const agentId = requireAgentId(positionals);
+  if (!options.at === !options.peak) throw new UsageError('Give exactly one of --at <time> or --peak <metric>.', { hint: 'Example: sentinelctl devices correlate <agent-id> --peak cpu -r 24h' });
+  if (options.at && !Number.isFinite(Date.parse(options.at))) throw new UsageError(`Cannot parse --at: ${options.at}`);
+  const body = await context.client.get(`/api/devices/${encodeURIComponent(agentId)}/correlate`, {
+    at: options.at ? new Date(options.at).toISOString() : undefined, peak: options.peak, range: options.peak ? options.range : undefined,
+    window: durationSeconds(options.window, 'window'), level: options.level, top: options.top, series: options.series ? 1 : undefined,
+  });
+  const value = (name, number) => metricValueText(number, correlateUnits[name]);
+  emit(context, body, () => [
+    renderKeyValues([
+      ['Device', `${body.displayName} (${body.agentId})`],
+      ['At', `${localTime(body.at)}${body.peak ? ` · peak ${body.peak.metric} ${value(body.peak.metric, body.peak.value)} in ${body.peak.range}` : ''}`],
+      ['Window', `${localTime(body.window.start)} → ${localTime(body.window.end)} (${body.stepSeconds}s step)`],
+      ['Reboots', body.reboots.map(localTime).join(', ') || 'none'],
+      ['Logs', `${body.logs.total} (${Object.entries(body.logs.levels).map(([level, count]) => `${level} ${count}`).join(', ') || '-'})`],
+    ]),
+    '',
+    renderTable(Object.entries(body.metrics), [
+      { header: 'METRIC', value: ([name]) => name },
+      { header: 'AT', value: ([name, item]) => value(name, item.atValue) },
+      { header: 'MIN', value: ([name, item]) => value(name, item.min) },
+      { header: 'MAX', value: ([name, item]) => value(name, item.max) },
+      { header: 'BIGGEST STEP', value: ([name, item]) => (item.biggestStep ? `${item.biggestStep.delta > 0 ? '+' : ''}${value(name, item.biggestStep.delta)} at ${localTime(item.biggestStep.at).slice(11)}` : '-') },
+    ], { width: context.width }),
+    '',
+    body.logs.groups.length ? renderTable(body.logs.groups, [
+      { header: 'COUNT', value: (group) => String(group.count) },
+      { header: 'FIRST', value: (group) => localTime(group.first).slice(11) },
+      { header: 'SOURCE', value: (group) => group.source, max: 22 },
+      { header: 'PATTERN', value: (group) => group.pattern },
+    ], { width: context.width, wide: options.wide }) : 'No logs in the window.',
+  ].join('\n'));
+  if (!body.logs.complete) context.hint('Log counts are partial; run again to complete.');
+  if (body.logs.truncated) context.hint(`Showing ${body.logs.groups.length} of ${body.logs.groupCount} log groups. Raise --top or add -l.`);
+}
+
 async function health(context) {
   const body = await context.client.get('/api/health');
   emit(context, body, () => [
@@ -696,50 +867,88 @@ async function rawApi(context, { options, positionals }) {
 const commands = [
   {
     group: 'logs', name: 'search', run: logsSearch, role: 'viewer', mutates: false,
-    summary: 'Search logs by window, device, severity, source and text; or follow live',
-    description: 'Newest first. Default 15m window and 100 logs. When fetching several pages, 250 logs are fetched per request, up to 10,000 in total. To count or rank logs, use `logs stats` instead.',
+    summary: 'Raw log lines, newest first',
+    description: 'Stops at 10,000 lines, which covers minutes of this fleet: read examples here after logs stats/groups, never count with it.',
     args: [{ name: 'text', optional: true, description: 'Same as -q (words are joined with spaces).' }],
     options: {
       ...logFilterOptions,
-      limit: { alias: 'n', type: 'integer', choices: [50, 100, 250], description: 'Logs per page. Default 100 (250 when paging).' },
-      pages: { type: 'integer', placeholder: 'N', description: `Follow the cursor for up to N pages (1-${maxPages}).` },
-      all: { type: 'boolean', description: 'Fetch every page of the window, stopping at 10,000 logs.' },
-      fields: { type: 'boolean', description: 'Include raw fields (admin only, audited, 50 logs per page).' },
-      follow: { alias: 'f', type: 'boolean', description: 'Keep printing new logs (for humans; never ends, agents should not use it).' },
-      interval: { type: 'integer', default: 5, placeholder: 'seconds', description: 'Polling interval for --follow (min 5).' },
-      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate messages in table output.' },
+      limit: { alias: 'n', type: 'integer', choices: [50, 100, 250], description: 'Lines per page (default 100; 250 when paging).' },
+      pages: { type: 'integer', placeholder: 'N', description: `Pages to follow (1-${maxPages}).` },
+      all: { type: 'boolean', description: 'All pages, up to 10,000 lines.' },
+      fields: { type: 'boolean', description: 'Raw fields (admin, audited, 50 per page).' },
+      collapse: { type: 'boolean', description: 'Same as logs groups.' },
+      top: { type: 'integer', placeholder: 'N', description: 'Groups with --collapse (1-500, default 50).' },
+      dedupe: { type: 'boolean', description: 'Fold same-second repeats into one line with a count.' },
+      since: { type: 'string', placeholder: 'ISO', description: 'Only logs after this time; poll with the printed nextSince.' },
+      follow: { alias: 'f', type: 'boolean', description: 'Stream new logs (humans only; never ends).' },
+      interval: { type: 'integer', default: 5, placeholder: 'seconds', description: 'Seconds between --follow polls (min 5).' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate.' },
     },
     roleFor: (options) => (options.fields ? 'admin' : 'viewer'),
     roleNote: '--fields requires admin',
     examples: [
       'sentinelctl logs search -l error -r 1h',
+      'sentinelctl logs search -p "tegra-xusb <N>.usb: not all ports suspended: -<N>" -r 24h -n 50 -o json',
+      'sentinelctl logs search -l error -r 24h --collapse -o json',
+      'sentinelctl logs search -l error --since 2026-09-30T01:02:03.456789Z -o ndjson',
       'sentinelctl logs search "connection reset" -r 24h -o ndjson',
       'sentinelctl logs search -a <agent-id> -s ssh.service -r 6h --all -o json',
       'sentinelctl logs search --from 2026-09-30T09:00:00+09:00 --to 2026-09-30T10:00:00+09:00 -l warning',
     ],
-    output: 'logs[]: timestamp (UTC ISO), severity, priority, agentId, host, displayName, source, message (+fields). -o json wraps them as {criteria, window, count, hasMore, logs}.',
+    output: 'logs[]: {timestamp, severity, agentId, displayName, source, message, repeat?, fields?}; json adds {window, count, hasMore, nextSince?}.',
   },
   {
     group: 'logs', name: 'stats', run: logsStats, role: 'viewer', mutates: false,
-    summary: 'Count and rank logs by source, device, severity or message pattern (one server-side query)',
-    description: 'Aggregates in VictoriaLogs instead of downloading logs, so counts are exact over the whole window. message groups by pattern with numbers collapsed to <N>. Cached for 60s on the server.',
+    summary: 'Exact counts by source, device, level, message pattern or service',
+    description: 'Counts every log in the window on the server. --compare shows what changed, --timeline when.',
     args: [{ name: 'text', optional: true, description: 'Same as -q.' }],
     options: {
       ...logFilterOptions,
-      by: { alias: 'b', type: 'string', choices: statsDimensions, default: 'source', description: 'Group by source, agent (device), level or message pattern.' },
-      top: { type: 'integer', default: 20, placeholder: 'N', description: 'Groups to return (1-100).' },
-      compare: { type: 'boolean', description: 'Also count the previous window of the same length: previousCount, change and isNew per group.' },
-      sort: { type: 'string', choices: ['count', 'change'], description: 'Rank by count (default) or by increase over the previous window (needs --compare).' },
-      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate long keys in table output.' },
+      by: { alias: 'b', type: 'string', choices: statsDimensions, default: 'source', description: 'Grouping (agent = device).' },
+      top: { type: 'integer', default: 20, placeholder: 'N', description: 'Groups (1-100).' },
+      compare: { type: 'boolean', description: 'Add the previous window: previousCount, change, isNew.' },
+      timeline: { type: 'boolean', description: 'Add counts over time per group (~48 buckets).' },
+      sort: { type: 'string', choices: ['count', 'change'], description: 'count or change (needs --compare).' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate.' },
     },
     examples: [
       'sentinelctl logs stats -l error -r 1h --by source',
       'sentinelctl logs stats -l error -r 24h --by agent --top 10 -o json',
       'sentinelctl logs stats -l error -r 24h --by message --compare --sort change',
+      'sentinelctl logs stats -l error -r 7d --by message --timeline --top 10',
       'sentinelctl logs stats -a <agent-id> -r 7d --by message',
       'sentinelctl logs stats "connection refused" -r 24h --by agent',
     ],
-    output: '{criteria, window, total, devices, groupCount, truncated, approximate, groups[]: {key, count, devices (distinct agents), host?, displayName?, searchText? (message: text to pass to logs search -q), previousCount?, change?, isNew?}, previous?: {window, total, devices, exhaustive}, newGroupCount?, rising?[≤5], falling?[≤5] (largest increases and decreases across all groups, not only the returned top)}.',
+    output: '{total, devices, groupCount, truncated, complete, groups[]: {key, count, devices, displayName?, previousCount?, change?, isNew?, timeline?[[epoch, count]], first?, last?}, previous?, newGroupCount?, rising?, falling?}.',
+  },
+  {
+    group: 'logs', name: 'groups', run: logsGroups, role: 'viewer', mutates: false,
+    summary: 'Every device × source × pattern with count, first/last time and latest line',
+    description: 'Lossless summary of the window, typically 50-100x smaller than the raw lines.',
+    args: [{ name: 'text', optional: true, description: 'Same as -q.' }],
+    options: {
+      ...logFilterOptions,
+      top: { type: 'integer', default: 50, placeholder: 'N', description: 'Groups, largest first (1-500).' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate.' },
+    },
+    examples: [
+      'sentinelctl logs groups -l error -r 1h',
+      'sentinelctl logs groups -a <agent-id> -r 7d -o json',
+      'sentinelctl logs groups -p "Failed to start <N>.service" -r 24h',
+    ],
+    output: '{total, devices, groupCount, patternCount, truncated, complete, groups[]: {agentId, displayName, source, pattern, count, first, last, latest{timestamp, severity, message}}}.',
+  },
+  {
+    group: 'logs', name: 'facets', run: logsFacets, role: 'viewer', mutates: false,
+    summary: 'Top devices, severities, sources and labels in one query',
+    description: 'Fleet-wide up to 24h; up to 7 days with -a, -s, --service or -p.',
+    options: {
+      ...logFilterOptions,
+      range: { alias: 'r', type: 'string', choices: logRanges, description: 'Window (default 1h).' },
+      top: { type: 'integer', default: 10, placeholder: 'N', description: 'Values per field (1-50).' },
+    },
+    examples: ['sentinelctl logs facets -l error -r 24h', 'sentinelctl logs facets -a <agent-id> -r 7d -o json'],
+    output: '{facets{agent_id[{value, count, displayName}], severity[], _SYSTEMD_UNIT[], service[], …}}.',
   },
   {
     group: 'logs', name: 'context', run: logsContext, role: 'viewer', mutates: false,
@@ -761,15 +970,15 @@ const commands = [
     summary: 'Log volume and error counts over time',
     args: [{ name: 'text', optional: true, description: 'Same as -q.' }],
     options: logFilterOptions,
-    examples: ['sentinelctl logs histogram -r 24h', 'sentinelctl logs histogram -a <agent-id> -r 7d -o json'],
-    output: '{start, end, stepSeconds, total, buckets[]: {at (epoch seconds), total, errors}}. Cached for 60s on the server.',
+    examples: ['sentinelctl logs histogram -r 24h', 'sentinelctl logs histogram -a <agent-id> -r 30d -o json'],
+    output: '{stepSeconds, total, complete, buckets[]: {at (epoch), total, errors}}.',
   },
   {
     group: 'logs', name: 'sources', run: logsSources, role: 'viewer', mutates: false,
-    summary: 'Log sources (systemd units, containers) seen recently',
+    summary: 'Log sources (systemd units, containers) ranked by exact count',
     options: { range: { alias: 'r', type: 'string', choices: logRanges, default: '24h', description: 'Sample window.' } },
     examples: ['sentinelctl logs sources -r 1h'],
-    output: '{range, sampleSize, sources[]: {value, count}}: top 50 in a sample of the latest 250 logs.',
+    output: '{total, sources[]: {value, count}} (top 50).',
   },
   {
     group: 'devices', name: 'list', run: devicesList, role: 'viewer', mutates: false,
@@ -827,21 +1036,21 @@ const commands = [
   },
   {
     group: 'metrics', name: 'top', run: metricsTop, role: 'viewer', mutates: false,
-    summary: 'Rank devices by a metric aggregated over a window, with the fleet-wide distribution',
-    description: 'One server-side query over every device: avg/max/min/p95/last of the metric per device, ranked, plus min/p50/p90/p95/max across devices. --compare adds the previous window of the same length. reboots counts uptime resets. Device filters work like devices list (retired devices are excluded by default). Cached for 60s.',
+    summary: 'Rank all devices by a metric over a window, with the fleet distribution',
+    description: 'reboots = uptime resets (daily scheduled reboots are normal; compare with p50). diskDaysLeft = days until the root disk is full at the current growth. Device filters match devices list.',
     args: [{ name: 'metric', description: metricNames.join(', ') }],
     options: {
-      agg: { type: 'string', choices: ['avg', 'max', 'min', 'p95', 'last'], default: 'avg', description: 'Per-device aggregation over the window (ignored for reboots).' },
+      agg: { type: 'string', choices: ['avg', 'max', 'min', 'p95', 'last'], default: 'avg', description: 'Per-device aggregation.' },
       range: { alias: 'r', type: 'string', choices: metricWindows, description: 'Window (default 24h).' },
-      from: { type: 'string', placeholder: 'ISO', description: 'Absolute window start (with --to, at most 30 days).' },
-      to: { type: 'string', placeholder: 'ISO', description: 'Absolute window end.' },
-      top: { type: 'integer', default: 10, placeholder: 'N', description: 'Devices to return (1-100).' },
-      order: { type: 'string', choices: ['desc', 'asc'], default: 'desc', description: 'desc = highest first, asc = lowest first.' },
-      compare: { type: 'boolean', description: 'Also aggregate the previous window: previous and change per device.' },
-      sort: { type: 'string', choices: ['value', 'change'], description: 'Rank by value (default) or by change (needs --compare).' },
-      above: { type: 'number', placeholder: 'N', description: 'Only devices whose value is above N (e.g. --above 90).' },
-      below: { type: 'number', placeholder: 'N', description: 'Only devices whose value is below N.' },
-      query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Device text filter (same as devices list).' },
+      from: { type: 'string', placeholder: 'ISO', description: 'Start (with --to; up to 30 days).' },
+      to: { type: 'string', placeholder: 'ISO', description: 'End.' },
+      top: { type: 'integer', default: 10, placeholder: 'N', description: 'Devices (1-100).' },
+      order: { type: 'string', choices: ['desc', 'asc'], description: 'Default desc (asc for diskDaysLeft).' },
+      compare: { type: 'boolean', description: 'Add the previous window: previous, change.' },
+      sort: { type: 'string', choices: ['value', 'change'], description: 'value or change (needs --compare).' },
+      above: { type: 'number', placeholder: 'N', description: 'Only values above N.' },
+      below: { type: 'number', placeholder: 'N', description: 'Only values below N.' },
+      query: { alias: 'q', type: 'string', placeholder: 'text', description: 'Device text.' },
       status: { type: 'string', choices: deviceStatuses, description: 'Reception status.' },
       lifecycle: { type: 'string', choices: lifecycles, description: 'Lifecycle scope (default operational).' },
       role: { type: 'string', placeholder: 'role', description: 'Device role.' },
@@ -856,20 +1065,40 @@ const commands = [
       'sentinelctl metrics top disk --agg last --above 85 --top 50',
       'sentinelctl metrics top cpu --agg p95 -r 24h --compare --sort change',
       'sentinelctl metrics top reboots -r 7d --above 0',
+      'sentinelctl metrics top diskDaysLeft -r 24h --below 14',
       'sentinelctl metrics top networkTx -r 24h --label fleet=edge -o json',
     ],
-    output: '{metric, aggregation, unit, window{start, end, seconds, range}, criteria, scope{devices, withData, withoutData, matched}, distribution{count, min, avg, p50, p90, p95, max}, previousDistribution?, devices[]: {agentId, displayName, host, status, value, previous?, change?}}.',
+    output: '{metric, unit, scope{devices, withData, matched}, distribution{min, avg, p50, p90, p95, max}, devices[]: {agentId, displayName, status, value, previous?, change?}}.',
   },
   {
     group: 'fleet', name: 'summary', run: fleetSummary, role: 'viewer', mutates: false,
-    summary: 'One-call fleet briefing: status counts, attention reasons, busiest devices, log levels and error patterns',
-    description: 'Start here to answer "how is the infrastructure?". Combines the device inventory, attention reasons with example devices, the highest current CPU/memory/disk/temperature, and log statistics for the window: totals by level, top and rising error patterns (compared with the previous window) and the devices with the most errors. About 5KB as JSON.',
+    summary: 'Status, attention, trends and error patterns in one call',
+    description: 'Start here. Trends flag disks full within 14 days, temperature rises of 15°C+ and unusual reboot counts; error patterns are compared with the previous window. ~10KB JSON.',
     options: {
       range: { alias: 'r', type: 'string', choices: logRanges, default: '24h', description: 'Log window.' },
-      logs: { type: 'boolean', description: 'Include log statistics (default on; --no-logs skips them).' },
+      logs: { type: 'boolean', description: 'Log statistics (--no-logs skips).' },
+      trends: { type: 'boolean', description: 'Metric trends (--no-trends skips).' },
     },
     examples: ['sentinelctl fleet summary', 'sentinelctl fleet summary -r 1h -o json', 'sentinelctl fleet summary --no-logs'],
-    output: '{range, stale, devices{total, status, lifecycle, metrics, logs}, attention[]: {reason, count, devices[≤5]}, resources{cpu, memory, disk, temperature: [{agentId, displayName, value}]}, logs{window, total, devices, levels, errors{total, previousTotal, devices, newPatterns}, topErrorPatterns[], risingErrorPatterns[], fallingErrorPatterns[] (shrunk or gone since the previous window), topErrorDevices[]}}.',
+    output: '{devices{status, metrics, logs, offline}, attention[]{reason, count, devices}, resources{cpu, memory, disk, temperature}, trends{diskFullWithin14Days, temperatureRise, rebootOutliers}, logs{levels, errors, topErrorPatterns, risingErrorPatterns, fallingErrorPatterns, topErrorDevices}}.',
+  },
+  {
+    group: 'devices', name: 'correlate', run: devicesCorrelate, role: 'viewer', mutates: false,
+    summary: 'Metrics and logs of one device around a time or metric peak',
+    description: 'For "what happened when X spiked": metric values and biggest change, reboots and log groups around --at or the --peak of a metric.',
+    args: [{ name: 'agent-id' }],
+    options: {
+      at: { type: 'string', placeholder: 'ISO', description: 'Center time.' },
+      peak: { type: 'string', choices: correlateMetricNames, description: 'Center on the highest point of this metric within --range instead.' },
+      range: { alias: 'r', type: 'string', choices: ['1h', '6h', '24h', '7d'], default: '24h', description: 'Where to look for --peak.' },
+      window: { type: 'string', default: '15m', placeholder: 'duration', description: 'Look this far before and after (1m-6h).' },
+      level: { alias: 'l', type: 'string', choices: logLevels, description: 'Only these log levels in the groups.' },
+      top: { type: 'integer', default: 20, placeholder: 'N', description: 'Log groups (1-100).' },
+      series: { type: 'boolean', description: 'Include the metric time series in JSON.' },
+      wide: { alias: 'w', type: 'boolean', description: 'Do not truncate patterns.' },
+    },
+    examples: ['sentinelctl devices correlate <agent-id> --peak cpu -r 24h', 'sentinelctl devices correlate <agent-id> --at 2026-09-30T14:58:00+09:00 --window 30m -o json'],
+    output: '{at, window, peak?, metrics{<name>: {atValue, min, max, change, biggestStep{at, delta}}}, reboots[], logs{total, levels, groups[]: {source, pattern, count, first, last, latest}}}.',
   },
   {
     group: 'metadata', name: 'get', run: metadataGet, role: 'viewer', mutates: false,
@@ -1006,10 +1235,10 @@ const commands = [
 
 export const catalog = commands;
 export const groups = {
-  fleet: 'One-call briefing of the whole fleet',
-  logs: 'Search, count and rank logs; compare windows; context around a log; volume trends; sources',
-  metrics: 'Rank devices by an aggregated metric across the fleet',
-  devices: 'Device list, details, lookup, reception overview',
+  fleet: 'Fleet briefing',
+  logs: 'Log counts, groups, patterns and raw lines',
+  metrics: 'Fleet-wide metric rankings',
+  devices: 'Device list, details, reception history, metric-log correlation',
   metadata: 'Device metadata: read, edit (editor), import/export (admin)',
   sessions: 'Your sessions and CLI tokens',
   admin: 'Roles, all sessions, audit clean-up, capacity (admin)',

package/src/main.mjs

@@ -1,4 +1,6 @@
 import { readFileSync } from 'node:fs';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { closest, parseArguments, UsageError } from './args.mjs';
 import { ApiError, createClient } from './client.mjs';
 import { catalog, commandPath, findCommand, groups, outputChoices, roleLabels, usageLine } from './commands.mjs';
@@ -7,14 +9,23 @@ import { renderKeyValues } from './format.mjs';
 import { browserLogin, openBrowser } from './login.mjs';
 
 const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+const userAgent = `sentinelctl/${version} node/${process.versions.node}`;
+const updateCommand = 'npm install -g sentinelctl@latest';
+
+function newer(latest, current) {
+  const a = latest.split('.').map(Number);
+  const b = current.split('.').map(Number);
+  for (let index = 0; index < 3; index += 1) if (a[index] !== b[index]) return a[index] > b[index];
+  return false;
+}
 const roleRank = { viewer: 0, editor: 1, admin: 2 };
-const exitCodes = { 0: 'success', 1: 'server or network error', 2: 'usage error (fix the arguments)', 3: 'not logged in or insufficient role (retrying will not help)' };
+const exitCodes = { 0: 'success', 1: 'server or network error', 2: 'usage error (fix the arguments)', 3: 'not logged in, insufficient role or CLI too old (retrying will not help)' };
 const globalDefinitions = {
   server: { type: 'string', placeholder: 'url', description: 'Console URL (default https://monitor.intflow.dev; also SENTINEL_URL).' },
   profile: { type: 'string', placeholder: 'name', description: 'Saved login profile (default "default").' },
   output: { alias: 'o', type: 'string', choices: outputChoices, description: 'Output format. Use json or ndjson from agents and scripts.' },
   json: { type: 'boolean', description: 'Same as -o json.' },
-  select: { type: 'string', placeholder: 'fields', description: 'json/ndjson: keep only these comma-separated fields (dotted paths like metadata.role) of each item in the main list, plus top-level scalars. Example: --select agentId,displayName,status,memory' },
+  select: { type: 'string', placeholder: 'fields', description: 'json/ndjson: keep only these fields of each item, e.g. agentId,status,metadata.role.' },
   quiet: { type: 'boolean', description: 'Suppress summaries and hints on stderr (errors are still printed).' },
   help: { alias: 'h', type: 'boolean', description: 'Show help.' },
   version: { alias: 'V', type: 'boolean', description: 'Show the version.' },
@@ -119,67 +130,54 @@ function overviewHelp() {
   return lines.join('\n');
 }
 
-const agentGuide = `Using sentinelctl from AI agents and scripts
+const agentGuide = `sentinelctl for AI agents
+
+Setup   A human runs \`sentinelctl login\` once (30 days), or set SENTINEL_TOKEN and SENTINEL_URL.
+Output  Use -o json. stdout is data; notes, hints and errors go to stderr (--quiet drops notes).
+Errors  One stderr line {"error":{status,code,message,hint,exitCode}}; messages are Korean, hints English.
+        Exit 0 ok · 1 server/network (retry later) · 2 usage (fix arguments) · 3 login/role/too old (stop).
+Updates A stderr {"notice":{"type":"update_available",…}} line means a newer CLI exists; tell the user.
+Help    sentinelctl <command> --help · sentinelctl commands <group> --json
 
-1. A human logs in once: \`sentinelctl login\` and approve in the browser. The token lasts 30 days;
-   every later command is non-interactive. The token carries the logged-in user's role, so log in
-   with a viewer account for agents that should only read. Elsewhere, pass SENTINEL_TOKEN and
-   SENTINEL_URL as environment variables.
-2. Use -o json (one document) or -o ndjson (one item per line). stdout carries data only; summaries,
-   hints and errors go to stderr. --quiet drops summaries and hints. With json/ndjson output an error
-   is one stderr line: {"error":{"status","code","message","hint","exitCode"}}.
-3. Exit codes: 0 success · 1 server/network error · 2 usage error (fix the arguments and retry)
-   · 3 not logged in or insufficient role (do not retry). GET requests that hit 429 are retried
-   automatically after Retry-After.
-4. \`sentinelctl commands --json\` returns every command with its options, choices, required role,
-   whether it changes data, examples and output fields; \`commands logs --json\` or
-   \`commands "logs stats" --json\` returns only that part.
-5. Typical investigation (start broad, then narrow)
-   - overview:       fleet summary -o json                      (~5KB: status, attention, busiest devices,
-                                                                 log levels, top/rising/new error patterns)
-   - what changed:   logs stats -l error -r 24h --by message --compare --sort change -o json
-   - fleet metrics:  metrics top memory -r 7d -o json           (ranked devices + fleet distribution)
-                     metrics top disk --agg last --above 85 · metrics top cpu --agg p95 --compare
-                     metrics top reboots -r 7d --above 0
-   - find a device:  devices lookup <part of name>            -> agentId
-   - status:         devices list --focus attention --all -o json --select agentId,displayName,status,attentionReasons
-                     devices overview <id> -o json
-   - metrics:        devices show <id> -r 24h -o json --series cpu,memory   (series are [epochSeconds, value])
-   - logs:           logs search -q "<searchText from logs stats>" -r 24h -o ndjson
-                     logs search -a <id> -l error -r 24h -o ndjson
-                     then logs context -a <id> -s <source> -t <timestamp> for surrounding lines
-   - counts/ranking: logs stats -l error -r 24h --by agent|source|message -o json
-   - trend:          logs histogram -a <id> -r 7d -o json
-6. Efficiency
-   - Prefer aggregates: fleet summary, logs stats and metrics top answer "how many", "which the most"
-     and "what changed" in one server-side query. Do not download thousands of logs or call
-     devices show per device to compute fleet-wide numbers.
-   - Keep JSON small: --select <fields> keeps only the fields you need (devices list --all -o json is
-     ~700KB without it, ~20KB with a few fields); devices show --series none drops time series.
-   - Narrow the window and filters (-a, -s, -l, -q) first. Use --pages N (max 40) to take only what you
-     need; --all stops at 10,000 logs.
-   - Each user can run 2 log queries and 2 metric aggregations at a time (web and CLI combined); run
-     commands one after another.
-   - Do not use --follow (it never ends). Repeat a -r 15m search instead.
-   - The server caches identical log searches for 5s; stats, histograms, sources and metrics top for 60s.
-7. For commands that change data (metadata set/bulk/rollback/import, admin ...), run with --dry-run
-   first when available, check the result, then apply.
-8. Server error messages are in Korean (shared with the web console); the "hint" field is English.`;
+Workflow: broad to narrow, count before reading
+1. fleet summary                                      status, attention, trends, error patterns
+2. logs stats -l error -r 24h --by message --compare  which patterns, what changed
+   logs groups -l error -r 24h                        device x source x pattern, latest line
+3. logs stats -p "<pattern>" --by agent --timeline    who and since when
+   devices correlate <id> --peak cpu                  metrics and logs around a spike
+4. logs search -p "<pattern>" -a <id> -n 50           a few raw lines (logs context for neighbors)
+Metrics: metrics top <metric>, e.g. memory -r 7d · disk --agg last · diskDaysLeft · reboots
+
+Rules
+- Never count or summarize by downloading: logs search stops at 10,000 lines (minutes of this
+  fleet); logs stats and logs groups count the whole window.
+- Pass patterns to -p exactly as printed (<N> = number). -q is a case-insensitive word match.
+- Narrow first (-a, -s, --service, -l, -p) and start with 1h-24h. Fleet-wide windows over 7 days
+  need one of -a, -s, --service, -p or --case-sensitive (else 422 log_query_too_broad); narrowed
+  queries reach 31 days. Long aggregations are cached per day and continue automatically.
+- Run commands one at a time: per user 2 log queries at once and 60s of log time per minute
+  (429 is retried automatically). Poll with --since <nextSince>, never --follow.
+- Keep output small: --select a,b.c · devices show --series none.
+- Commands that change data (metadata, admin): --dry-run first. Viewer tokens are read-only.`;
+
+function compact(record) {
+  return Object.fromEntries(Object.entries(record).filter(([, value]) => value !== undefined && value !== null && !(Array.isArray(value) && !value.length)));
+}
 
 function commandsCatalog(selected = null) {
   return {
     version,
-    globalOptions: globalDefinitions,
+    globalOptions: Object.fromEntries(Object.entries(globalDefinitions).map(([name, spec]) => [name, compact(spec)])),
     exitCodes,
     commands: [
-      ...(selected ? [] : Object.entries(specialCommands).map(([name, command]) => ({ command: name, usage: command.usage, summary: command.summary, role: null, mutates: name === 'logout' }))),
-      ...(selected ?? catalog).map((command) => ({
-        command: commandPath(command), usage: usageLine(command), summary: command.summary, description: command.description ?? null,
-        role: command.role, roleNote: command.roleNote ?? null, mutates: command.mutates, args: command.args ?? [],
-        options: Object.fromEntries(Object.entries(command.options).map(([name, spec]) => [name, {
-          alias: spec.alias ?? null, type: spec.type, choices: spec.choices ?? null, default: spec.default ?? null,
-          multiple: Boolean(spec.multiple), description: spec.description ?? null,
-        }])),
+      ...(selected ? [] : Object.entries(specialCommands).map(([name, command]) => ({ command: name, usage: command.usage, summary: command.summary, mutates: name === 'logout' }))),
+      ...(selected ?? catalog).map((command) => compact({
+        command: commandPath(command), usage: usageLine(command), summary: command.summary, description: command.description,
+        role: command.role, roleNote: command.roleNote, mutates: command.mutates, args: command.args,
+        options: Object.fromEntries(Object.entries(command.options).map(([name, spec]) => [name, compact({
+          alias: spec.alias, type: spec.type, choices: spec.choices, default: spec.default,
+          multiple: spec.multiple || undefined, description: spec.description,
+        })])),
         examples: command.examples, output: command.output,
       })),
     ],
@@ -188,7 +186,7 @@ function commandsCatalog(selected = null) {
 
 async function login(context, argv) {
   const { options } = parseArguments(argv, { 'no-browser': { type: 'boolean' }, name: { type: 'string' } });
-  const client = createClient({ server: context.connection.server, fetch: context.fetch });
+  const client = createClient({ server: context.connection.server, fetch: context.fetch, userAgent });
   const result = await browserLogin(client, {
     clientName: options.name,
     launchBrowser: !options['no-browser'],
@@ -223,6 +221,21 @@ async function logout(context) {
   context.out(removed ? 'Logged out.' : 'No saved login to remove.');
 }
 
+async function noticeUpdate(context, environment) {
+  const latest = context?.versions?.latest;
+  if (!latest || !newer(latest, version) || environment.SENTINELCTL_NO_UPDATE_NOTICE) return;
+  const path = join(dirname(context.connection.path), 'update-notice.json');
+  let last = {};
+  try { last = JSON.parse(await readFile(path, 'utf8')); } catch {}
+  if (last.latest === latest && Date.now() - (last.at ?? 0) < 86_400_000) return;
+  const message = `sentinelctl ${latest} is available (you have ${version}). Update: ${updateCommand}`;
+  context.err(context.global.output === 'table' ? `notice: ${message}` : JSON.stringify({ notice: { type: 'update_available', current: version, latest, command: updateCommand } }));
+  try {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, JSON.stringify({ latest, at: Date.now() }), { mode: 0o600 });
+  } catch {}
+}
+
 async function rememberRole(context, role) {
   const saved = context.connection.profile;
   if (!saved || context.connection.fromEnvironment || saved.role === role) return;
@@ -237,13 +250,14 @@ async function whoami(context) {
   const identity = await context.client.get('/api/session');
   await rememberRole(context, identity.role);
   if (context.global.output === 'json' || context.global.output === 'ndjson') {
-    context.out(JSON.stringify({ server: context.connection.server, ...identity, tokenExpiresAt: context.connection.profile?.expiresAt ?? null }));
+    context.out(JSON.stringify({ server: context.connection.server, ...identity, tokenExpiresAt: context.connection.profile?.expiresAt ?? null, cli: { version, latest: context.versions?.latest ?? null } }));
     return;
   }
   context.out(renderKeyValues([
     ['Server', context.connection.server], ['User', identity.user], ['Name', identity.name],
     ['Role', roleLabels[identity.role] ?? identity.role], ['Token ID', identity.sessionId],
     ['Token expires', context.connection.profile?.expiresAt],
+    ['CLI', `${version}${context.versions?.latest ? ` (latest ${context.versions.latest})` : ''}`],
   ]));
 }
 
@@ -282,6 +296,16 @@ function apiHint(error, context, command) {
       ? 'Check the agent ID with `sentinelctl devices lookup <part of the name>`.' : 'Not found; check the ID.';
   }
   if (error.status === 409) return 'Someone saved a change first. Run the command again to apply on top of the latest revision.';
+  if (error.code === 'cli_upgrade_required') return `Update the CLI: ${updateCommand} (or @intflow/sentinelctl@latest), then rerun.`;
+  if (error.code === 'log_query_too_broad') {
+    return 'Narrow it: add -a <agent-id>, -s <source>, --service <name>, -p "<pattern>" (from `logs stats --by message`) or --case-sensitive with -q, or use a window of 7 days or less.';
+  }
+  if (error.code === 'log_budget_exceeded') {
+    return `Your log query time for this minute is used up${error.retryAfterSeconds ? `; wait ${error.retryAfterSeconds}s` : ''}. Prefer logs stats/groups with filters over repeated wide searches.`;
+  }
+  if (error.status === 504) {
+    return 'The log/metric backend timed out. Narrow the window or add -a/-s/-l, use -p "<pattern>" instead of -q, or add --case-sensitive. Long aggregations resume from cache if you rerun.';
+  }
   if (error.status === 429) return `Too many requests${error.retryAfterSeconds ? `; wait ${error.retryAfterSeconds}s` : ''} and retry. Narrower filters reduce load.`;
   if ([400, 413, 415, 422].includes(error.status)) {
     return command ? `Check the input: sentinelctl ${commandPath(command)} --help` : 'Check the input.';
@@ -386,7 +410,7 @@ export async function main(argv, {
       select: global.select ? global.select.split(',').map((field) => field.trim()).filter(Boolean) : null,
       hint: (text) => { if (!global.quiet) err(`hint: ${text}`); },
       note: (text) => { if (!global.quiet && global.output === 'table') err(text); },
-      client: createClient({ server: connection.server, token: connection.token, fetch, sleep }),
+      client: createClient({ server: connection.server, token: connection.token, fetch, sleep, userAgent, onVersions: (versions) => { context.versions = versions; } }),
     };
     if (name === 'login') { await login(context, commandArgv); return 0; }
     if (name === 'logout') { await logout(context); return 0; }
@@ -412,9 +436,11 @@ export async function main(argv, {
         `Ask an admin to run \`sentinelctl admin grant <your-email> --role ${error.required}\`. Nothing was sent to the server.`, 3);
     }
     if (error instanceof ApiError) {
-      const exitCode = error.status === 401 || error.status === 403 || error.code === 'not_logged_in' ? 3 : 1;
+      const exitCode = error.status === 401 || error.status === 403 || error.status === 426 || error.code === 'not_logged_in' ? 3 : 1;
       return report(error, apiHint(error, context ?? { connection: {} }, command), exitCode);
     }
     return report(error, null, 1);
+  } finally {
+    if (context) await noticeUpdate(context, environment);
   }
 }