securenow 8.17.0 → 8.19.0

package/README.md

@@ -174,8 +174,11 @@ Everything the MCP server can do is also a command. Run `npx securenow help` for
 
 | Command | Description |
 |---|---|
-| `securenow human list` / `human show <row>` | Review AI-prepared decisions awaiting a human |
+| `securenow review` / `review show <row>` | Alert Review: rules that fired too wide and paused themselves |
+| `securenow review group <row> --outcome rule_tuning --reason "..." --yes` | Close every run of a group after fixing its rule |
+| `securenow human list` / `human show <row>` | Requires Human: AI-prepared decisions awaiting a human |
 | `securenow human block <row> --yes --reason "..."` | Approve a proposed block |
+| `securenow human close <row> --outcome deferred --reason "..." --yes` | Close a row without blocking |
 | `securenow blocklist add <ip> [--route /admin*] [--mode prefix] [--duration 24h] [--reason "..."]` | Block an IP globally or per-route |
 | `securenow blocklist unblock <id> --reason "..."` | Stop enforcement, keep the history |
 | `securenow ratelimit from-text "5 per minute per IP on POST /api/login for 2h" --yes` | Rate-limit rule from natural language |

package/SKILL-CLI.md

@@ -28,6 +28,22 @@ npx -p securenow securenow-mcp
 
 The MCP server reads admin/control-plane auth from `.securenow/admin.json` and SDK runtime app credentials from `.securenow/runtime.json`, with legacy `.securenow/credentials.json` still supported. Admin/global tools use admin auth; runtime-scoped read tools can use the runtime API key where its scopes allow it. Write tools require `confirm:true` plus a reason.
 
+**For agents, prefer the hosted MCP** (`https://api.securenow.ai/mcp`, OAuth sign-in, no install and always the current tools). With the local stdio server, warm the package once so the first connection doesn't time out on the download (`npx -y securenow@latest --version`), and give the client a longer connect timeout (Claude Code: `MCP_TIMEOUT=120000`).
+
+**Tool profiles** (stdio server): `securenow mcp --profile <name>` (or `SECURENOW_MCP_PROFILE=<name>`) serves only the tools one job needs, so the agent carries less context. Every profile keeps `securenow_auth_status`, `securenow_apps_list` and `securenow_apps_info`; calling a tool outside the profile returns an error naming the profile.
+
+| Profile | Tools | What's in it |
+|---|---|---|
+| `all` (default) | 112 | everything |
+| `investigator` | 58 | every read-only tool, plus forensics question/chat/confirm |
+| `detection` | 47 | `securenow_alert_rule*` (draft, create, test, run, runs, explain, versions, exclusions, request promotion…), traces, logs, forensics, IP intelligence, notifications list/get |
+| `responder` | 77 | notifications, human queue, alert reviews, blocklist, allowlist, trusted IPs, rate limits, challenges, automations, firewall, IP intelligence, plus rule get/runs/explain and traces/logs for context |
+
+```bash
+claude mcp add securenow-investigator -- npx -y securenow@latest mcp --profile investigator
+codex mcp add securenow-detection -- npx securenow mcp --profile detection
+```
+
 ### Authenticate
 
 ```bash
@@ -213,8 +229,11 @@ securenow traces analyze <traceId> --env production   # AI-powered trace analysi
 securenow logs [--app <key>] [--env production] [--limit N] [--minutes M] [--level error|warn|info]
 securenow logs list --app my-app --env production --minutes 30 --level error
 securenow logs trace <traceId> --env production       # logs correlated to a specific trace
+securenow logs errors --app my-app --since 6h [--warn]  # what is failing: error lines grouped by message (ids/numbers normalized), counts, first/last seen, sample traces
 ```
 
+For "what's broken right now?", start with `logs errors` (MCP `securenow_logs_errors`): one call returns the distinct failures, not hundreds of raw lines.
+
 ### Notifications
 
 ```bash
@@ -225,7 +244,41 @@ securenow notifications read-all             # mark all as read
 securenow notifications unread               # unread count
 ```
 
-### Human Actions — AI-Prepared Decision Queue
+### Two review queues
+
+SecureNow decides most things alone (instant blocks, automations, IP investigations, self-pausing
+rules). What it won't decide alone waits in two queues. Work **Alert Review** first: one rule fix
+closes every run it caused and the Requires Human rows that came from the same noise.
+
+| Queue | Question | Decisions | CLI |
+|---|---|---|---|
+| Alert Review | "Is this rule right?" A rule fired far too wide, or on an IP treated as your own infrastructure; it usually pauses itself | tune the rule, keep it on, close/dismiss with a reason (never blocks or unblocks) | `securenow review` |
+| Requires Human | "What do we do about this IP or plan?" An investigated IP with a verdict SecureNow won't act on alone, or a proposed plan | block, false positive, close without blocking, approve/reject a plan | `securenow human` |
+
+### Alert Review — is this rule right?
+
+```bash
+securenow review                             # open runs grouped by root cause (rule + route + evidence shape)
+securenow review list --search lab-auth      # one app (name or key), rule, route or IP
+securenow review show 1                      # group 1: rule, route, IPs, proposed guard, its runs
+securenow review show <notificationId>       # one run
+securenow review keep <notificationId> --reason "Correct detection" --yes     # turn the rule back on, stop it auto-pausing, close the run
+securenow review close <notificationId> --outcome rule_tuning --reason "..." --yes
+securenow review dismiss <notificationId> --reason "Not worth acting on" --yes
+securenow review group 1 --outcome rule_tuning --reason "Guard added in v4" --preview   # what would close
+securenow review group 1 --outcome rule_tuning --reason "Guard added in v4" --yes       # close the whole group
+```
+
+Outcomes: `rule_tuning`, `false_positive`, `clean`, `deferred`, `new_alert_rule`, `rate_limited`,
+`ambiguous`, `skipped`, `other`. Closing writes a decision report on the alert and changes no
+enforcement. Tune the rule first (`securenow alerts rules change <id> "..."`), then close its group.
+A mixed group (rows disagree on verdict or sender) needs `--allow-mixed` after reviewing every row.
+
+MCP parity: `securenow_alert_review_runs_list`, `securenow_alert_review_run_get`,
+`securenow_alert_review_run_keep_alive`, `securenow_alert_review_run_resolve`,
+`securenow_alert_review_run_dismiss`, `securenow_alert_review_run_apply_group_decision`; prompt `work_alert_review`.
+
+### Requires Human — what do we do about this IP or plan?
 
 Use this for the same work shown in **Requires Human**: AI has already grouped alerts, fetched traces, built a report, and left a final Block IP or False Positive decision.
 
@@ -235,6 +288,7 @@ securenow human list --limit 20
 securenow human show 1                       # inspect row 1 with AI report, investigation steps, proofs, trace links
 securenow human block 1 --yes --reason "AI evidence confirmed malicious"
 securenow human fp 1 --yes --reason "Scoped false positive after evidence review"
+securenow human close 1 --outcome deferred --reason "Scanner, nothing reachable; not worth a block" --yes   # leaves the queue, nothing blocked
 securenow human action 1 --status rejected --yes --reason "Tuning guard is too broad"
 securenow human prompt 1                     # print a Codex/Claude MCP prompt for this row
 securenow human work --limit 10              # list queue + print MCP runbook for deep queue work
@@ -247,9 +301,26 @@ MCP parity:
 - `securenow_human_action_report`
 - `securenow_human_action_block`
 - `securenow_human_action_false_positive`
+- `securenow_human_action_close_no_write`
 - `securenow_human_case_action_update`
 - prompts: `investigate_human_action_row`, `work_human_actions`
 
+`human report` only adds a note: the row stays. `human close` removes it without enforcement.
+Approving a `tune_rule` or `create_exclusion` plan with `human action` records the decision and
+changes nothing: change the rule first, then approve. Only `approve_block` blocks.
+
+### Run the queues with your own agent
+
+```bash
+claude "$(npx -y securenow@latest agent prompt patrol)"                     # read-only pass: a plan
+claude -p "$(npx -y securenow@latest agent prompt patrol --search my-app --confirm-writes)"   --allowedTools "mcp__securenow"                                           # unattended, acts on one app
+```
+
+`soc_patrol` works Alert Review then Requires Human, up to 10 groups and 10 rows per pass
+(`--max-alert-review-groups`, `--max-human-rows`). The API key's scopes are the hard limit: a
+Read Only key cannot change anything; acting needs `notifications:write`, `alerts:write` and
+`rate_limits:write`. Setup for Claude Code, Codex and Cursor: dashboard → Run With Your Agent.
+
 Write tools still require `confirm:true` plus a reason. False positives should stay restrictive to the app, alert rule, path, method/status, user-agent, body pattern, or other exact evidence the AI report supports. Notification IP investigations can include `metadata.matchedSubdetectors`; prefer that exact field over inferring which subdetector fired from the title or sample body.
 
 ### Alerts
@@ -295,6 +366,7 @@ securenow alerts rules delete <id> --yes    # delete a custom rule (system rules
 securenow alerts rules update <id> --applications-all   # all current & future apps
 securenow alerts rules update <id> --apps key1,key2     # explicit app keys only
 securenow alerts rules test <id> --wait       # dry-run an existing rule's query (default; --mode live inserts 6 synthetic attack requests)
+securenow alerts rules change <id> "raise the threshold to 20"   # rewrite a rule from English: checked, shown before/after, applied as a new version
 securenow alerts rules runs <id> [--since 1h] # what each run saw and why it did or didn't notify (+ next scheduled run)
 securenow alerts rules run <id>               # run a periodic rule now and print the run (--no-wait to just queue it)
 securenow alerts rules why <id> --ip <ip> [--since 1h]   # why the rule did or didn't alert on one address: verdict + findings
@@ -322,6 +394,8 @@ right tenant-scope column per table: logs (`signoz_logs.distributed_logs_v2`) us
 
 MCP parity for quiet rules: `securenow_alert_rule_runs` (run history), `securenow_alert_rule_run_now` (write, confirm) and `securenow_alert_rule_explain` (`ip`, `since`: verdict + findings).
 
+**Agents don't promote rules; they ask.** When a test-mode rule has proved itself, an agent runs `securenow alerts rules request-promotion <id> --reason "..." --evidence "..."` (MCP `securenow_alert_rule_request_promotion`). A person sees it on the rules page or with `securenow human promotions` and runs `securenow human approve-promotion <request-id> --yes` (the rule goes to prod, recorded as a rule version naming the approver) or `deny-promotion <request-id> --reason "..."`. API keys and MCP tokens can ask but not decide.
+
 MCP parity for noisy alert-rule reviews:
 
 - `securenow_alert_rule_get`

package/cli/human.js

@@ -509,13 +509,60 @@ async function report(args, flags) {
     }
     s.stop('Decision report recorded');
     if (flags.json) ui.json(data);
-    else ui.success(`Recorded decision report: ${decisionReport.outcome}`);
+    else {
+      ui.success(`Recorded decision report: ${decisionReport.outcome}`);
+      if (task.ip) ui.info(`A report is a note: the row stays in the queue. To close it without enforcement: securenow human close ${task.notificationId}:${task.ip} --outcome ${decisionReport.outcome}`);
+    }
   } catch (err) {
     s.fail('Failed to record decision report');
     throw err;
   }
 }
 
+const CLOSE_OUTCOMES = ['rate_limited', 'deferred', 'rule_tuning', 'new_alert_rule', 'ambiguous', 'skipped', 'other'];
+
+// Close an IP row without blocking or marking it a false positive ("not now", "rule needs tuning",
+// "already rate-limited"...). Unlike `report`, the row leaves the queue.
+async function close(args, flags) {
+  requireAuth();
+  const ref = args[0];
+  const { task } = await resolveTask(ref, flags);
+  if (!task.ip) {
+    ui.error('`close` is for IP rows. For a case-level plan use: securenow human action <row> --status approved|rejected');
+    process.exit(1);
+  }
+  const outcome = flags.outcome || 'skipped';
+  if (!CLOSE_OUTCOMES.includes(outcome)) {
+    ui.error(`--outcome must be one of: ${CLOSE_OUTCOMES.join(', ')}`);
+    process.exit(1);
+  }
+  const summary = flags.summary || flags.reason;
+  if (!summary) {
+    ui.error('Say why with --reason "..." (and --missing-proof "..." when evidence is missing): the reason is kept on the case.');
+    process.exit(1);
+  }
+
+  if (!flags.yes && !flags.force) {
+    const ok = await ui.confirm(`Close ${task.ip} without blocking it (${outcome})?`);
+    if (!ok) return;
+  }
+
+  const s = ui.spinner(`Closing ${task.ip}`);
+  try {
+    const decisionReport = buildDecisionReport(task, flags, outcome, summary);
+    const data = await api.post(
+      `/notifications/${encodeURIComponent(task.notificationId)}/ips/${encodeURIComponent(task.ip)}/close-no-write`,
+      { reportSource: 'cli', reason: flags.reason || summary, summary, outcome, decisionReport }
+    );
+    s.stop(`${task.ip} closed (${outcome})`);
+    if (flags.json) ui.json(data);
+    else ui.success(`Closed without enforcement: ${task.ip} is out of the queue, nothing was blocked. The reason is on the case.`);
+  } catch (err) {
+    s.fail('Failed to close the row');
+    throw err;
+  }
+}
+
 function mcpPromptText(ref, flags = {}) {
   const rowText = ref ? `Start with human action row/id: ${ref}.` : 'Work the human action queue from most urgent to least urgent.';
   const limit = flags.limit || 10;
@@ -569,6 +616,66 @@ async function work(args, flags) {
   console.log('');
 }
 
+// ── Rule promotion requests ──
+// Agents create rules in test mode and ask a person to promote them. A person approves (the rule
+// goes to prod, recorded as a rule version) or denies here or on the dashboard's rules page.
+
+async function promotions(args, flags) {
+  requireAuth();
+  const status = typeof flags.status === 'string' ? flags.status : 'pending';
+  const s = ui.spinner('Fetching promotion requests');
+  let data;
+  try {
+    data = await api.get('/alert-rules/promotion-requests', { query: { status, limit: flags.limit || 50 } });
+    s.stop(`Found ${(data.requests || []).length} ${status === 'all' ? '' : `${status} `}request${(data.requests || []).length === 1 ? '' : 's'}`);
+  } catch (err) {
+    s.fail('Failed to fetch promotion requests');
+    throw err;
+  }
+  if (flags.json) { ui.json(data); return; }
+  const requests = data.requests || [];
+  if (requests.length === 0) { ui.info('No promotion requests waiting.'); return; }
+  console.log('');
+  for (const r of requests) {
+    console.log(`  ${ui.c.bold(r.ruleName || r.ruleId)}  ${ui.c.dim(r.id)}  ${r.status}`);
+    console.log(`    asked by ${r.requestedBy?.name || r.requestedBy?.kind || 'unknown'} ${ui.timeAgo(r.createdAt)}: ${r.reason}`);
+    if (r.evidence) console.log(ui.c.dim(`    evidence: ${ui.truncate(String(r.evidence).replace(/\s+/g, ' '), 160)}`));
+    if (r.status !== 'pending') console.log(ui.c.dim(`    ${r.status} by ${r.decidedByName || 'someone'}${r.decisionNote ? `: ${r.decisionNote}` : ''}`));
+  }
+  console.log('');
+  if (requests.some((r) => r.status === 'pending')) {
+    console.log(ui.c.dim('  Approve: securenow human approve-promotion <id> --yes [--note "..."]   Deny: securenow human deny-promotion <id> --reason "..."'));
+    console.log(ui.c.dim('  Before approving, check what it would arm: securenow alerts rules show <ruleId> and securenow alerts rules runs <ruleId>'));
+    console.log('');
+  }
+}
+
+async function decidePromotion(args, flags, decision) {
+  requireAuth();
+  const id = args[0];
+  const verb = decision === 'approve' ? 'approve-promotion' : 'deny-promotion';
+  if (!id) {
+    ui.error(`Usage: securenow human ${verb} <request-id> ${decision === 'approve' ? '--yes [--note "..."]' : '--reason "..."'}`);
+    process.exit(1);
+  }
+  if (decision === 'approve' && !flags.yes && !flags.force) {
+    ui.warn('Approving moves the rule to prod: its instant block, matching automations and the AI pipeline can act on its alerts.');
+    const ok = await ui.confirm('Approve this promotion?');
+    if (!ok) { ui.info('Cancelled'); return; }
+  }
+  const note = flags.note || flags.reason || '';
+  const s = ui.spinner(decision === 'approve' ? 'Approving' : 'Denying');
+  try {
+    const data = await api.post(`/alert-rules/promotion-requests/${id}/${decision}`, { note });
+    s.stop(decision === 'approve' ? `Approved: "${data.alertRule?.name || data.request?.ruleName}" is in prod` : 'Denied: the rule stays in test mode');
+    for (const warning of data.warnings || []) ui.warn(warning);
+    if (flags.json) ui.json(data);
+  } catch (err) {
+    s.fail(`Failed to ${decision} the promotion`);
+    throw err;
+  }
+}
+
 module.exports = {
   list,
   show,
@@ -576,6 +683,10 @@ module.exports = {
   block,
   fp,
   report,
+  close,
   prompt,
   work,
+  promotions,
+  approvePromotion: (args, flags) => decidePromotion(args, flags, 'approve'),
+  denyPromotion: (args, flags) => decidePromotion(args, flags, 'deny'),
 };

package/cli/monitor.js

@@ -294,6 +294,48 @@ async function logsList(args, flags) {
   }
 }
 
+// Error lines grouped by message (ids and numbers normalized): what is failing, how often, since when.
+async function logsErrors(args, flags) {
+  requireAuth();
+  const appKey = resolveApp(flags);
+  if (!appKey) {
+    ui.error('No app specified. Use --app <key> or set a default.');
+    process.exit(1);
+  }
+  const query = { appKeys: appKey, since: flags.since || '1h', limit: flags.limit || 20 };
+  if (flags.warn) query.includeWarn = 'true';
+  addEnvironment(query, flags);
+  const s = ui.spinner('Grouping error logs');
+  let data;
+  try {
+    data = await api.get('/logs/errors', { query });
+    const kind = data.includeWarn ? 'error/warning' : 'error';
+    s.stop(`${data.total} ${kind} line${data.total === 1 ? '' : 's'} in ${data.distinct} group${data.distinct === 1 ? '' : 's'}`);
+  } catch (err) {
+    s.fail('Failed to summarize error logs');
+    throw err;
+  }
+  if (flags.json) { ui.json(data); return; }
+  const groups = data.groups || [];
+  console.log('');
+  if (groups.length === 0) { ui.info(`No ${data.includeWarn ? 'warnings or errors' : 'errors'} since ${data.window?.from}.`); return; }
+  for (const g of groups) {
+    const last = g.lastSeen ? ui.timeAgo(g.lastSeen) : '';
+    console.log(`  ${ui.c.red(String(g.occurrences).padStart(5))}  ${ui.truncate(String(g.sample || g.signature).replace(/\s+/g, ' '), 110)}`);
+    const meta = [
+      (g.severities || []).join('/'),
+      (g.environments || []).join(', '),
+      g.exceptionType,
+      last && `last ${last}`,
+      g.sampleTraceIds?.[0] && `trace ${g.sampleTraceIds[0]}`,
+    ].filter(Boolean).join(' · ');
+    if (meta) console.log(ui.c.dim(`         ${meta}`));
+  }
+  console.log('');
+  console.log(ui.c.dim('  A group\'s requests: securenow logs trace <traceId>   Ask why: securenow forensics chat --app <key> "<question>"'));
+  console.log('');
+}
+
 async function logsTrace(args, flags) {
   requireAuth();
   const traceId = args[0];
@@ -499,6 +541,7 @@ module.exports = {
   tracesAnalyze,
   logsList,
   logsTrace,
+  logsErrors,
   notificationsList,
   notificationsRead,
   notificationsReadAll,

package/cli/review.js

@@ -0,0 +1,295 @@
+'use strict';
+
+// Alert Review: "is this rule right?". A rule fired on too many IPs, or on an IP SecureNow treats as
+// your own infrastructure, so it was paused and the run waits for a person. Rows that share one root
+// cause (same rule, route, evidence shape) are grouped so one decision can close them all. Closing a
+// row never blocks or unblocks anything; keeping a rule on is the only write to the rule itself.
+
+const { api, requireAuth } = require('./client');
+const ui = require('./ui');
+
+const OUTCOMES = ['rule_tuning', 'false_positive', 'clean', 'deferred', 'new_alert_rule', 'rate_limited', 'ambiguous', 'skipped', 'other'];
+
+const VERDICTS = {
+  false_positive_pattern: 'looks benign',
+  rule_tuning: 'rule needs tuning',
+  real_probe: 'real probe',
+  ambiguous: 'unclear',
+};
+
+function verdictLabel(decisionTypes = {}) {
+  const keys = Object.keys(decisionTypes);
+  if (keys.length === 0) return '-';
+  if (keys.length > 1) return 'mixed';
+  return VERDICTS[keys[0]] || keys[0];
+}
+
+// Alerts carry app keys; print the names people know them by.
+async function appNames() {
+  try {
+    const data = await api.get('/applications');
+    return new Map((data.applications || []).map((app) => [app.key, app.name]));
+  } catch {
+    return new Map();
+  }
+}
+
+function namesOf(keys, names) {
+  return (keys || []).map((key) => names.get(key) || key).join(', ') || '-';
+}
+
+function isNotificationId(ref) {
+  return /^[0-9a-f]{24}$/i.test(String(ref || ''));
+}
+
+async function fetchGroups(flags = {}) {
+  const query = { page: flags.page || 1, limit: flags.limit || 20 };
+  if (flags.search) query.search = flags.search;
+  return api.get('/notifications/alert-review-runs', { query });
+}
+
+// A group is named by its row on the current page or by its root-cause key (arc_...).
+async function resolveGroup(ref, flags = {}) {
+  if (!ref) {
+    ui.error('Group row or root-cause key required. Use `securenow review list` first.');
+    process.exit(1);
+  }
+  const text = String(ref).trim();
+  if (/^\d+$/.test(text)) {
+    // Rows are numbered across pages, as `review list` prints them.
+    const row = Math.max(1, parseInt(text, 10));
+    const limit = Number(flags.limit) || 20;
+    const data = await fetchGroups({ ...flags, limit, page: Math.ceil(row / limit) });
+    const group = (data.groups || [])[(row - 1) % limit];
+    if (!group) {
+      ui.error(`Row ${text} was not found. Run \`securenow review list\` again: the queue may have changed.`);
+      process.exit(1);
+    }
+    return group;
+  }
+  const data = await api.get('/notifications/alert-review-runs', { query: { rootCauseKey: text, limit: 1 } });
+  const group = (data.groups || [])[0];
+  if (!group) {
+    ui.error(`No open group "${text}". It may already be closed.`);
+    process.exit(1);
+  }
+  return group;
+}
+
+function requireReason(flags) {
+  const reason = flags.reason || flags.summary;
+  if (!reason) {
+    ui.error('Say why with --reason "...": the reason is kept on the alert as its decision report.');
+    process.exit(1);
+  }
+  return reason;
+}
+
+function requireOutcome(flags, fallback) {
+  const outcome = flags.outcome || fallback;
+  if (!OUTCOMES.includes(outcome)) {
+    ui.error(`--outcome must be one of: ${OUTCOMES.join(', ')}`);
+    process.exit(1);
+  }
+  return outcome;
+}
+
+async function list(args, flags) {
+  requireAuth();
+  const s = ui.spinner('Fetching Alert Review');
+  let data;
+  try {
+    data = await fetchGroups(flags);
+    const summary = data.summary || {};
+    s.stop(`${summary.totalRuns ?? 0} alert run${summary.totalRuns === 1 ? '' : 's'} to review in ${summary.totalGroups ?? 0} group${summary.totalGroups === 1 ? '' : 's'}`);
+  } catch (err) {
+    s.fail('Failed to fetch Alert Review');
+    throw err;
+  }
+  if (flags.json) { ui.json(data); return; }
+
+  const groups = data.groups || [];
+  console.log('');
+  if (!groups.length) {
+    ui.info('Nothing to review: no paused or noisy rule is waiting for a decision.');
+    console.log('');
+    return;
+  }
+  const offset = ((data.pagination?.page || 1) - 1) * (data.pagination?.limit || groups.length);
+  const rows = groups.map((group, index) => [
+    String(offset + index + 1),
+    String(group.count || 0),
+    ui.truncate(group.rootCause?.detectionName || group.title || '-', 40),
+    ui.truncate(group.rootCause?.routeTemplate || '-', 28),
+    verdictLabel(group.decisionTypes),
+    group.batchActionPreview?.canApplyOneDecision ? 'yes' : 'no',
+    group.lastOccurredAt ? ui.timeAgo(group.lastOccurredAt) : '-',
+  ]);
+  ui.table(['Row', 'Runs', 'Rule', 'Route', 'Looks like', 'One decision', 'Last'], rows, { maxColWidth: 44 });
+  console.log('');
+  ui.info('Inspect a group:            securenow review show <row>');
+  ui.info('Rule is right, keep it on:  securenow review keep <notificationId> --reason "..."');
+  ui.info('Close a whole group:        securenow review group <row> --outcome rule_tuning --reason "..." [--preview]');
+  console.log('');
+}
+
+function printRun(run, names) {
+  ui.keyValue([
+    ['Alert', `${run.title || '-'} ${ui.c.dim(run.notificationId)}`],
+    ['Rule', `${run.alertRule?.name || run.rootCause?.alertRuleName || '-'}${run.alertRule?.status ? ` (${run.alertRule.status})` : ''}`],
+    ['Route', run.rootCause?.routeTemplate || '-'],
+    ['Looks like', VERDICTS[run.rootCause?.decisionType] || run.rootCause?.decisionType || '-'],
+    ['Who sent it', run.rootCause?.attributionType || '-'],
+    ['Apps', namesOf(run.applications, names)],
+    ['IP', run.primaryIp || '-'],
+    ['Evidence', `${run.evidenceQuality?.score ?? '-'} / 100${run.proofContract?.missingProof?.length ? `, missing: ${run.proofContract.missingProof.join(', ')}` : ''}`],
+    ['Proposed guard', run.rootCause?.proposedGuard || '-'],
+    ['Last seen', run.lastOccurredAt ? ui.timeAgo(run.lastOccurredAt) : '-'],
+  ]);
+}
+
+async function show(args, flags) {
+  requireAuth();
+  const ref = args[0];
+  if (isNotificationId(ref)) {
+    const data = await api.get(`/notifications/alert-review-runs/${ref}`);
+    if (flags.json) { ui.json(data); return; }
+    ui.heading('Alert run');
+    printRun(data.run, await appNames());
+    if (data.group) {
+      console.log('');
+      ui.info(`${data.group.count} open run${data.group.count === 1 ? '' : 's'} share this root cause (${data.group.key}).`);
+    }
+    console.log('');
+    return;
+  }
+
+  const group = await resolveGroup(ref, flags);
+  if (flags.json) { ui.json(group); return; }
+  const names = await appNames();
+  ui.heading(group.title || 'Alert Review group');
+  ui.keyValue([
+    ['Key', group.key],
+    ['Runs', String(group.count)],
+    ['Looks like', verdictLabel(group.decisionTypes)],
+    ['Apps', namesOf(group.applications, names)],
+    ['IPs', `${(group.ips || []).length}${group.ips?.length ? `: ${group.ips.slice(0, 5).join(', ')}${group.ips.length > 5 ? ' ...' : ''}` : ''}`],
+    ['Evidence', `${group.evidenceQuality?.min ?? '-'}-${group.evidenceQuality?.max ?? '-'} / 100`],
+    ['Proposed guard', group.rootCause?.proposedGuard || '-'],
+    ['One decision', group.batchActionPreview?.canApplyOneDecision ? 'yes' : `no: ${group.batchActionPreview?.reason || 'single run'}`],
+  ]);
+  if (group.runs?.length) {
+    console.log('');
+    ui.table(['Alert id', 'IP', 'Evidence', 'Last'], group.runs.map((run) => [
+      run.notificationId,
+      run.primaryIp || '-',
+      String(run.evidenceQuality?.score ?? '-'),
+      run.lastOccurredAt ? ui.timeAgo(run.lastOccurredAt) : '-',
+    ]));
+  }
+  console.log('');
+  ui.info(`One run:   securenow review show <alert id>`);
+  ui.info(`All runs:  securenow review group ${group.key} --outcome rule_tuning --reason "..." --preview`);
+  console.log('');
+}
+
+async function keep(args, flags) {
+  requireAuth();
+  const id = args[0];
+  if (!isNotificationId(id)) {
+    ui.error('Usage: securenow review keep <notificationId> --reason "..." --yes');
+    process.exit(1);
+  }
+  const reason = requireReason(flags);
+  if (!flags.yes && !flags.force) {
+    ui.warn('This turns the rule back on and stops it from pausing itself again.');
+    const ok = await ui.confirm('Keep the rule on and close this run?');
+    if (!ok) return;
+  }
+  const s = ui.spinner('Keeping the rule on');
+  try {
+    const data = await api.post(`/notifications/alert-review-runs/${id}/keep-alive`, { confirm: true, reason, reportSource: 'cli' });
+    s.stop(`"${data.alertRule?.name || 'Rule'}" is ${data.verification?.ruleActive ? 'on' : data.alertRule?.status || 'unchanged'}; the run is closed`);
+    if (flags.json) ui.json(data);
+  } catch (err) {
+    s.fail('Failed to keep the rule on');
+    throw err;
+  }
+}
+
+async function closeOne(args, flags, mode) {
+  requireAuth();
+  const id = args[0];
+  if (!isNotificationId(id)) {
+    ui.error(`Usage: securenow review ${mode} <notificationId> ${mode === 'close' ? '--outcome rule_tuning ' : ''}--reason "..." --yes`);
+    process.exit(1);
+  }
+  const outcome = requireOutcome(flags, 'skipped');
+  const reason = requireReason(flags);
+  if (!flags.yes && !flags.force) {
+    const ok = await ui.confirm(`${mode === 'close' ? 'Close' : 'Dismiss'} this run (${outcome})? Nothing is blocked or unblocked.`);
+    if (!ok) return;
+  }
+  const route = mode === 'close' ? 'resolve' : 'dismiss';
+  const s = ui.spinner(mode === 'close' ? 'Closing the run' : 'Dismissing the run');
+  try {
+    const data = await api.post(`/notifications/alert-review-runs/${id}/${route}`, {
+      confirm: true,
+      outcome,
+      reason,
+      summary: flags.summary || reason,
+      reportSource: 'cli',
+    });
+    s.stop(data.alreadyClosed ? 'Already closed' : `Run ${mode === 'close' ? 'closed' : 'dismissed'} (${outcome}); the reason is on the alert`);
+    if (flags.json) ui.json(data);
+  } catch (err) {
+    s.fail(`Failed to ${mode} the run`);
+    throw err;
+  }
+}
+
+async function group(args, flags) {
+  requireAuth();
+  const target = await resolveGroup(args[0], flags);
+  const preview = Boolean(flags.preview);
+  const outcome = preview ? flags.outcome : requireOutcome(flags);
+  const reason = preview ? flags.reason : requireReason(flags);
+  if (!preview && !flags.yes && !flags.force) {
+    ui.warn(`This closes ${target.count} run${target.count === 1 ? '' : 's'} of "${target.title}". Nothing is blocked or unblocked.`);
+    const ok = await ui.confirm(`Close the group (${outcome})?`);
+    if (!ok) return;
+  }
+  const s = ui.spinner(preview ? 'Previewing the group decision' : 'Closing the group');
+  try {
+    const data = await api.post('/notifications/alert-review-runs/apply-group-decision', {
+      rootCauseKey: target.key,
+      previewOnly: preview,
+      confirm: !preview,
+      allowMixed: Boolean(flags['allow-mixed']),
+      outcome,
+      reason,
+      summary: flags.summary || reason,
+      reportSource: 'cli',
+    });
+    if (preview) {
+      s.stop(`Would close ${data.willApplyCount} run${data.willApplyCount === 1 ? '' : 's'}`);
+      if (target.mixed) ui.warn('Mixed group: rows disagree on verdict or sender. Review each row, then pass --allow-mixed.');
+    } else {
+      s.stop(`Closed ${data.closedCount} of ${data.requestedCount}${data.failedCount ? `, ${data.failedCount} failed` : ''}; ${data.verification?.remainingOpenInGroup ?? 0} still open in the group`);
+    }
+    if (flags.json) ui.json(data);
+  } catch (err) {
+    s.fail(preview ? 'Preview failed' : 'Failed to close the group');
+    throw err;
+  }
+}
+
+module.exports = {
+  list,
+  show,
+  keep,
+  close: (args, flags) => closeOne(args, flags, 'close'),
+  dismiss: (args, flags) => closeOne(args, flags, 'dismiss'),
+  group,
+  OUTCOMES,
+};