@velaro/cli 1.4.97 → 1.4.99

package/bin/velaro.js

@@ -10,10 +10,12 @@ import { botCommand }        from '../lib/commands/bot.js';
 import { indexCommand }      from '../lib/commands/index.js';
 import { ingestCommand }     from '../lib/commands/ingest.js';
 import { indexMoveCommand }  from '../lib/commands/index-move.js';
+import { safetyCommand }     from '../lib/commands/safety.js';
 import { knowledgeAdvisorCommand } from '../lib/commands/knowledge-advisor.js';
 import { productCommand }    from '../lib/commands/product.js';
 import { mcpKeyCommand }     from '../lib/commands/mcp-key.js';
 import { opsCommand }        from '../lib/commands/ops.js';
+import { deployStateCommand } from '../lib/commands/deploy-state.js';
 import { checkCommand }      from '../lib/commands/check.js';
 import { logsCommand }       from '../lib/commands/logs.js';
 import { aiModelsCommand }   from '../lib/commands/ai-models.js';
@@ -24,6 +26,7 @@ import { statusCommand }     from '../lib/commands/status.js';
 import { activityCommand }   from '../lib/commands/activity.js';
 import { ruleCommand }       from '../lib/commands/rule.js';
 import { teamCommand }       from '../lib/commands/team.js';
+import { dynamicsCommand }   from '../lib/commands/dynamics.js';
 import { workflowCommand }   from '../lib/commands/workflow.js';
 import { aiConfigCommand }   from '../lib/commands/ai-config.js';
 import { deploymentCommand } from '../lib/commands/deployment.js';
@@ -37,6 +40,7 @@ import { calendlyCommand }   from '../lib/commands/calendly.js';
 import { copilotStudioCommand } from '../lib/commands/copilotstudio.js';
 import { acuityCommand }     from '../lib/commands/acuity.js';
 import { avatarCommand }     from '../lib/commands/avatar.js';
+import { imageAnalysisCommand } from '../lib/commands/image-analysis.js';
 import { integrationCommand } from '../lib/commands/integration.js';
 import { appointmentsCommand } from '../lib/commands/appointments.js';
 import { bookingCommand } from '../lib/commands/booking.js';
@@ -109,6 +113,7 @@ import { paymentRecoveryCommand }   from '../lib/commands/payment-recovery.js';
 import { recruitingCommand }        from '../lib/commands/recruiting.js';
 import { surveyCommand }            from '../lib/commands/survey.js';
 import { bundleCommand }            from '../lib/commands/bundle.js';
+import { chatWindowCommand }        from '../lib/commands/chat-window.js';
 import { featureDiscoveryCommand }  from '../lib/commands/feature-discovery.js';
 import { tourPolicyCommand }  from '../lib/commands/tour-policy.js';
 import { scraperCommand }      from '../lib/commands/scraper.js';
@@ -141,10 +146,12 @@ await yargs(hideBin(process.argv))
   .command(indexCommand)
   .command(ingestCommand)
   .command(indexMoveCommand)
+  .command(safetyCommand)
   .command(knowledgeAdvisorCommand)
   .command(productCommand)
   .command(mcpKeyCommand)
   .command(opsCommand)
+  .command(deployStateCommand)
   .command(checkCommand)
   .command(logsCommand)
   .command(aiModelsCommand)
@@ -155,6 +162,7 @@ await yargs(hideBin(process.argv))
   .command(activityCommand)
   .command(ruleCommand)
   .command(teamCommand)
+  .command(dynamicsCommand)
   .command(workflowCommand)
   .command(aiConfigCommand)
   .command(deploymentCommand)
@@ -168,6 +176,7 @@ await yargs(hideBin(process.argv))
   .command(copilotStudioCommand)
   .command(acuityCommand)
   .command(avatarCommand)
+  .command(imageAnalysisCommand)
   .command(integrationCommand)
   .command(appointmentsCommand)
   .command(bookingCommand)
@@ -242,6 +251,7 @@ await yargs(hideBin(process.argv))
   .command(recruitingCommand)
   .command(surveyCommand)
   .command(bundleCommand)
+  .command(chatWindowCommand)
   .command({ command: 'feature-discovery', desc: 'View and act on feature-discovery suggestions for this site', builder: featureDiscoveryCommand, handler: () => {} })
   .command({ command: 'scraper', desc: 'Velaro staff: scraper / upload / chunk usage for any site', builder: scraperCommand, handler: () => {} })
   .command({ command: 'tour-policy', desc: 'Velaro staff: guided-tour auto-open policy (versioned, rollback-able)', builder: tourPolicyCommand, handler: () => {} })

package/lib/commands/canned-learning.js

@@ -3,22 +3,25 @@ import { runCommand } from '../run.js';
 
 const print = (data) => console.log(JSON.stringify(data, null, 2));
 
-// velaro canned-learning <list|generate|approve|reject|rollback|edits|record-edit>  (REST: messaging /CannedLearning/*)
+// velaro canned-learning <list|generate|approve|reject|rollback|edits|record-edit|teams>  (REST: messaging /CannedLearning/*)
 export const cannedLearningCommand = {
   command: 'canned-learning <action> [id]',
   describe: 'AI canned message learning: list/generate suggestions, approve/reject/rollback (human review)',
   builder: (y) => y
-    .positional('action', { choices: ['list', 'generate', 'approve', 'reject', 'rollback', 'edits', 'record-edit'] })
+    .positional('action', { choices: ['list', 'generate', 'approve', 'reject', 'rollback', 'edits', 'record-edit', 'teams'] })
     .positional('id', { type: 'number' })
+    .option('team-id', { type: 'number', describe: 'list/edits: only this team; generate: run for this team (team managers must pass one they manage)' })
     .option('state', { type: 'string', default: 'pending_review', describe: 'pending_review|approved|rejected|rolled_back|all' })
     .option('text', { type: 'string', describe: 'approve: edited replacement text (defaults to the AI proposal)' })
     .option('notes', { type: 'string', describe: 'rollback: reason' })
     .option('final-text', { type: 'string', describe: 'record-edit: the text the agent actually sent (redacted server-side)' }),
   handler: runCommand(async (a) => {
     const base = '/CannedLearning';
-    if (a.action === 'list') return print(await messagingGet(`${base}/suggestions?state=${encodeURIComponent(a.state)}`));
-    if (a.action === 'generate') return print(await messagingPost(`${base}/generate`, {}));
-    if (a.action === 'edits') return print(await messagingGet(`${base}/edit-events`));
+    const teamQs = a.teamId != null ? `&teamId=${encodeURIComponent(a.teamId)}` : '';
+    if (a.action === 'list') return print(await messagingGet(`${base}/suggestions?state=${encodeURIComponent(a.state)}${teamQs}`));
+    if (a.action === 'generate') return print(await messagingPost(`${base}/generate`, { teamId: a.teamId ?? null }));
+    if (a.action === 'edits') return print(await messagingGet(`${base}/edit-events${a.teamId != null ? `?teamId=${encodeURIComponent(a.teamId)}` : ''}`));
+    if (a.action === 'teams') return print(await messagingGet(`${base}/teams`));
     if (a.action === 'record-edit') {
       if (a.id == null || !a.finalText) throw new Error('record-edit requires a canned response id and --final-text');
       return print(await messagingPost(`${base}/edit-events`, { cannedResponseId: a.id, finalText: a.finalText }));

package/lib/commands/chat-intelligence-topics.js

@@ -4,14 +4,16 @@ import { runCommand } from '../run.js';
 const print = (data) => console.log(JSON.stringify(data, null, 2));
 const list = (v) => (v == null ? [] : String(v).split(',').map((s) => s.trim()).filter(Boolean));
 
-// velaro chat-topics <show|set|template|merge|rename|retire|group|group-suggestions|suggestions|accept|dismiss|
+// velaro chat-topics <show|settings|set|template|merge|rename|retire|group|group-suggestions|suggestions|accept|dismiss|
 //                     reclassify-estimate|reclassify|analysis-estimate|analysis|proposal>
 // REST: messaging /ChatIntelligenceTopics/*  (site comes from the CLI session, never an argument)
 export const chatIntelligenceTopicsCommand = {
   command: 'chat-topics <action>',
   describe: 'Chat Intelligence topics: edit the list, merge/rename/group (no AI cost), suggested topics, optional reclassify and analysis',
   builder: (y) => y
-    .positional('action', { choices: ['show', 'set', 'template', 'merge', 'rename', 'retire', 'group', 'group-suggestions', 'suggestions', 'accept', 'dismiss', 'reclassify-estimate', 'reclassify', 'analysis-estimate', 'analysis', 'proposal'] })
+    .positional('action', { choices: ['show', 'settings', 'set', 'template', 'merge', 'rename', 'retire', 'group', 'group-suggestions', 'suggestions', 'accept', 'dismiss', 'reclassify-estimate', 'reclassify', 'analysis-estimate', 'analysis', 'proposal'] })
+    .option('multi-topic', { type: 'boolean', describe: 'settings: turn multi-topic tracking on (--multi-topic) or off (--no-multi-topic); omit to just show' })
+    .option('re-eval', { type: 'number', describe: 'settings: re-check after N new visitor messages (1-50)' })
     .option('topics', { type: 'string', describe: 'set: comma-separated topic list' })
     .option('industry', { type: 'string', describe: 'template: insurance|healthcare|retail|ecommerce|financial|saas|government|manufacturing' })
     .option('from', { type: 'string', describe: 'merge/rename/retire/group: comma-separated topics' })
@@ -29,6 +31,9 @@ export const chatIntelligenceTopicsCommand = {
     const ops = (op) => messagingPost(`${base}/mapping`, { ops: [{ op, from: list(a.from), to: a.to ?? null, group: a.group ?? null }] });
     switch (a.action) {
       case 'show': return print(await messagingGet(base));
+      case 'settings':
+        if (a.multiTopic == null && a.reEval == null) return print(await messagingGet(`${base}/settings`));
+        return print(await messagingPut(`${base}/settings`, { themeMultiTopicEnabled: a.multiTopic ?? null, themeReEvalEveryNMessages: a.reEval ?? null }));
       case 'set': return print(await messagingPut(base, { topics: list(a.topics) }));
       case 'template': return print(await messagingPost(`${base}/template`, { industry: a.industry }));
       case 'merge': case 'rename': case 'retire': case 'group': return print(await ops(a.action));

package/lib/commands/chat-window.js

@@ -0,0 +1,47 @@
+// velaro chat-window — per-page launcher label + opening greeting (ChatWindow/* on velaro-messaging).
+// Site isolation is enforced server-side (ClientControllerBase SiteId), never passed by the client.
+// To show different copy on different pages: create one chat window per page type, set its
+// label/greeting here, then pick it with a Select Chat Window workflow node.
+import { messagingGet, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+
+export const chatWindowCommand = {
+  command:  'chat-window <subcommand>',
+  describe: 'Chat window launcher label and greeting — list, set-copy',
+  builder:  (yargs) =>
+    yargs
+      .command({
+        command: 'list',
+        describe: 'List chat windows with launcher label and greeting',
+        handler: runCommand(async () => {
+          const rows = (await messagingGet('/ChatWindow/list')) ?? [];
+          if (!rows.length) { console.log('No chat windows found.'); return; }
+          for (const w of rows) {
+            console.log(`${w.id}  ${w.name ?? '(unnamed)'}  [${w.languageConfig?.language ?? '?'}]`);
+            console.log(`     launcherText: ${w.styleConfig?.launcherText ?? '(none)'}`);
+            console.log(`     greeting:     ${w.languageConfig?.greeting ?? '(none)'}`);
+          }
+          console.log(`\n${rows.length} chat window(s)`);
+        }),
+      })
+      .command({
+        command: 'set-copy <id>',
+        describe: 'Set launcher label and/or greeting on one chat window (empty string clears)',
+        builder: (y) => y
+          .positional('id', { type: 'number', describe: 'Chat window ID' })
+          .option('launcher-text', { type: 'string', describe: 'Launcher label, max 60 chars' })
+          .option('greeting', { type: 'string', describe: 'Opening greeting, max 256 chars' }),
+        handler: runCommand(async (argv) => {
+          const body = {};
+          if (argv.launcherText !== undefined) body.launcherText = argv.launcherText;
+          if (argv.greeting !== undefined) body.greeting = argv.greeting;
+          if (!Object.keys(body).length) throw new Error('Pass --launcher-text and/or --greeting.');
+          const r = await messagingPut(`/ChatWindow/${argv.id}/launcher-copy`, body);
+          console.log(`Updated chat window ${r.id}.`);
+          console.log(`  launcherText: ${r.launcherText ?? '(none)'}`);
+          console.log(`  greeting:     ${r.greeting ?? '(none)'}`);
+        }),
+      })
+      .demandCommand(1, 'Specify a subcommand: list, set-copy'),
+  handler: () => {},
+};

package/lib/commands/db.js

@@ -26,6 +26,7 @@ const DB_SECRETS = {
     staging: { vault: 'velaro-eastus-stg-kv', secret: 'KnowledgeBaseConnectionString-Staging' },
   },
   messaging: {
+    staging: { vault: 'velaro-eastus-stg-kv', secret: 'MessagingConnectionString-Staging' },
     prod: { vault: 'velaro-eastus-prd-kv', secret: 'MessagingReadOnlyConnectionString' },
   },
 };

package/lib/commands/deploy-state.js

@@ -0,0 +1,26 @@
+import { collectAll, render, PRODUCTS } from '../deploy-state.js';
+
+// velaro deploy-state: what is on the staging environment, on staging slot 1 of production and in
+// production for Admin and Messaging, what is merged to dev but not in production, which gate is
+// waiting and the merge-freeze file. Uses only `gh` (logged in) and public /Version endpoints.
+export const deployStateCommand = {
+  command:  'deploy-state',
+  describe: 'Where each push landed: staging environment, staging slot 1 of production, production (Velaro staff, needs gh)',
+  builder:  (yargs) => yargs
+    .option('product', { type: 'string', choices: ['admin', 'messaging'], describe: 'Only one product (default both)' })
+    .option('json',    { type: 'boolean', describe: 'Print the raw state as JSON' })
+    .option('compact', { type: 'boolean', describe: 'One line per place' }),
+  handler: async (argv) => {
+    try {
+      const products = argv.product
+        ? [Object.keys(PRODUCTS).find((n) => n.toLowerCase() === argv.product)]
+        : undefined;
+      const state = await collectAll({ products });
+      console.log(argv.json ? JSON.stringify(state, null, 2) : render(state, { compact: !!argv.compact }));
+    } catch (e) {
+      console.error(`deploy-state failed: ${e.message}`);
+      console.error('This command needs the GitHub CLI (gh) installed and logged in with access to velaro/velaro-admin and velaro/velaro-messaging. Run: gh auth login');
+      process.exit(1);
+    }
+  },
+};

package/lib/commands/dynamics.js

@@ -0,0 +1,44 @@
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+// ── velaro dynamics team-overrides ────────────────────────────────────────────
+// Per-team (group) override of Dynamics field mappings + activity type.
+// Effective value = team override ?? the connection's own setting ("apply to all groups" default).
+// Site is resolved server-side from the caller's credentials, never passed by the client.
+
+const base = (config) => `/Dynamics/Configs/${config}/team-overrides`;
+
+export const dynamicsCommand = {
+  command:  'dynamics <subcommand>',
+  describe: 'Dynamics 365 integration settings',
+  builder:  yargs => yargs
+    .command({
+      command:  'team-overrides <action>',
+      describe: 'Per-team overrides of field mappings / activity type (get | set | reset)',
+      builder:  y => y
+        .positional('action', { choices: ['get', 'set', 'reset'] })
+        .option('config',   { type: 'number', demandOption: true, describe: 'Dynamics config id (velaro dynamics config list in the admin UI)' })
+        .option('team',     { type: 'number', describe: 'Team id (required for set/reset; see: velaro team list)' })
+        .option('activity', { type: 'string', describe: 'Activity logical name (e.g. phonecall, task). Empty string = inherit the default.' })
+        .option('mappings', { type: 'string', describe: 'customFieldMappingsJson (JSON array). Empty string = inherit the default.' }),
+      handler:  runCommand(async argv => {
+        if (argv.action === 'get') {
+          const data = await request('GET', base(argv.config));
+          console.log(JSON.stringify(data, null, 2));
+          return;
+        }
+        if (!argv.team) throw new Error('--team is required for set/reset');
+        if (argv.action === 'reset') {
+          console.log(JSON.stringify(await request('DELETE', `${base(argv.config)}/${argv.team}`), null, 2));
+          return;
+        }
+        const body = {};
+        if (argv.activity !== undefined) body.activityLogicalName = argv.activity;
+        if (argv.mappings !== undefined) body.customFieldMappingsJson = argv.mappings;
+        if (!Object.keys(body).length) throw new Error('Pass --activity and/or --mappings (omitted fields are left unchanged).');
+        console.log(JSON.stringify(await request('PUT', `${base(argv.config)}/${argv.team}`, body), null, 2));
+      }),
+    })
+    .demandCommand(1, 'Specify a subcommand: team-overrides'),
+  handler: () => {},
+};

package/lib/commands/image-analysis.js

@@ -0,0 +1,27 @@
+import { request } from '../api.js';
+import { runCommand } from '../run.js';
+
+// velaro image-analysis limits --site N
+// Shows the Image Analysis (analyze_image) add-on cap and usage for any site (Velaro admin only).
+// To change the cap: velaro support set-limit --site N --key MaxImageAnalysesPerMonth --value 500
+export const imageAnalysisCommand = {
+  command:  'image-analysis <subcommand>',
+  describe: 'Image Analysis add-on limits and usage (Velaro admin only)',
+  builder:  yargs => yargs
+    .command({
+      command:  'limits',
+      describe: 'Show monthly cap, usage this month and per-chat cap for a site',
+      builder:  y => y.option('site', { type: 'number', demandOption: true, describe: 'Site ID' }),
+      handler:  runCommand(async argv => {
+        const d = await request('GET', `/ImageAnalysisLimits/superadmin?siteId=${argv.site}`);
+        const ent = d.entitled === null ? 'unknown' : d.entitled ? 'yes' : 'no';
+        console.log(`\nSite ${argv.site}: Image Analysis`);
+        console.log(`  Entitled:         ${ent}`);
+        console.log(`  Monthly cap:      ${d.monthlyCap} (effective ${d.effectiveMonthlyCap}, hard cap, no automatic overage)`);
+        console.log(`  Used this month:  ${d.usedThisMonth === null ? 'unknown' : d.usedThisMonth}`);
+        console.log(`  Per-chat cap:     ${d.perConversationCap}`);
+        console.log(`  Extra block size: ${d.blockSize}\n`);
+      }),
+    })
+    .demandCommand(1),
+};

package/lib/commands/ops.js

@@ -1,6 +1,7 @@
 import { describeRawMeta, fetchRetry429 } from '../log-search.js';
 import { get, del, post, getCredentials } from '../api.js';
 import { readConfig, ENVS }   from '../config.js';
+import { collectAll, render as renderDeployState } from '../deploy-state.js';
 
 // ── helpers ──────────────────────────────────────────────────────────────────
 
@@ -154,6 +155,17 @@ export const opsCommand = {
       }
     }
 
+    // ── 1b. Where each push landed: staging environment, staging slot 1 of production, production ──
+    // Same data as `velaro deploy-state` (needs gh). Never blocks the rest of ops if gh is missing.
+    console.log('\n\x1b[1m── Where each push landed ──────────────────────────────────\x1b[0m');
+    try {
+      const state = await collectAll();
+      console.log(renderDeployState(state, { compact: true }).split('\n').map(l => '  ' + l).join('\n'));
+      console.log('  Full detail: velaro deploy-state');
+    } catch (e) {
+      console.log(`  ${WARN}  Deploy state unavailable (${e.message}). Needs gh logged in; run velaro deploy-state.`);
+    }
+
     // ── 2. API health (admin + messaging, both envs) ──────────────────────────
     const prodMsgBase    = cfg.envs?.prod?.messagingApiBase    ?? ENVS.prod.messagingApiBase;
     const stagingMsgBase = cfg.envs?.staging?.messagingApiBase ?? ENVS.staging.messagingApiBase;

package/lib/commands/quality-reports.js

@@ -108,9 +108,10 @@ export const qualityCommand = {
 export const chatIntelligenceThemesCommand = {
   command: 'chat-intelligence',
   describe: 'Chat Intelligence themes, optionally per website/team',
-  builder: (y) => scope(y.option('from', { type: 'string' }).option('to', { type: 'string' }).option('group-by', { type: 'string', default: 'month' })),
+  builder: (y) => scope(y.option('from', { type: 'string' }).option('to', { type: 'string' }).option('group-by', { type: 'string', default: 'month' }).option('include-secondary', { type: 'boolean', default: false, describe: 'Also show secondary topics (needs the site multi-topic setting on)' })),
   handler: runCommand(async (a) => {
     const qs = new URLSearchParams({ groupBy: a.groupBy });
+    if (a.includeSecondary) qs.set('includeSecondary', 'true');
     if (a.from) qs.set('startDate', a.from);
     if (a.to) qs.set('endDate', a.to);
     if (a.deployment != null) qs.set('deploymentId', String(a.deployment));

package/lib/commands/safety.js

@@ -0,0 +1,111 @@
+// velaro safety — see safety events, acknowledge them, and manage alert settings. Wraps velaro-messaging
+// SafetyEventsController. The site always comes from your login, never from an argument. Same routes the
+// admin "Safety and alerts" page uses. Needs the EnableTroubleshootingKnowledge entitlement.
+import { messagingGet, messagingPost, messagingPut } from '../api.js';
+import { runCommand } from '../run.js';
+
+const enc = encodeURIComponent;
+
+const out = (argv, data, printer) => {
+  if (argv.json) console.log(JSON.stringify(data, null, 2));
+  else printer(data);
+};
+
+const list = (v) => (v === undefined ? undefined : [].concat(v).flatMap((x) => String(x).split(',')).map((s) => s.trim()).filter(Boolean));
+
+function printEvents(r) {
+  const items = r.items ?? [];
+  if (!items.length) { console.log('No safety events.'); return; }
+  for (const e of items) {
+    console.log(`[${e.id}] ${e.createdUtc}  ${e.type}  (${e.channel})  ${e.status}`);
+    if (e.reason) console.log(`    Why: ${e.reason}`);
+    if (e.excerpt) console.log(`    "${e.excerpt}"`);
+  }
+  console.log(`\n${items.length} of ${r.total ?? items.length} shown.`);
+}
+
+function printSummary(s) {
+  console.log('Totals:');
+  for (const [k, v] of Object.entries(s.totals ?? {})) console.log(`  ${k}: ${v}`);
+  console.log('\nBy day:');
+  for (const d of s.days ?? []) console.log(`  ${d.date}  ${JSON.stringify(d.counts)}`);
+}
+
+function printSettings(s) {
+  console.log(`Alerts:            ${s.enabled ? 'on' : 'off'}`);
+  console.log(`Email recipients:  ${(s.emailRecipients ?? []).join(', ') || '(none)'}`);
+  console.log(`SMS recipients:    ${(s.smsRecipients ?? []).join(', ') || '(none)'}`);
+  console.log(`Alert right away:  ${(s.immediateTypes ?? []).join(', ') || '(none)'}`);
+  console.log(`Summary email:     ${s.digest}`);
+  console.log(`Count alert:       ${s.threshold?.count ?? 0} events in ${s.threshold?.windowMinutes ?? 60} minutes`);
+}
+
+export const safetyCommand = {
+  command: 'safety',
+  describe: 'Safety events and alerts: list events, acknowledge, alert settings, test alert, ask Velaro for help',
+  builder: (yargs) => yargs
+    .command('events', 'List safety events', (y) => y
+      .option('from', { type: 'string', describe: 'ISO start' })
+      .option('to', { type: 'string', describe: 'ISO end' })
+      .option('type', { type: 'string' })
+      .option('status', { type: 'string', choices: ['open', 'acknowledged'] })
+      .option('take', { type: 'number', default: 25 })
+      .option('skip', { type: 'number', default: 0 })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      const q = new URLSearchParams();
+      for (const k of ['from', 'to', 'type', 'status']) if (a[k]) q.set(k, a[k]);
+      q.set('take', String(a.take));
+      q.set('skip', String(a.skip));
+      out(a, await messagingGet(`/SafetyEvents?${q}`), printEvents);
+    }))
+    .command('summary', 'Counts by type and by day', (y) => y
+      .option('days', { type: 'number', default: 7 })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => out(a, await messagingGet(`/SafetyEvents/summary?days=${a.days}`), printSummary)))
+    .command('ack', 'Mark an event as reviewed', (y) => y.option('id', { type: 'string', demandOption: true }),
+    runCommand(async (a) => {
+      await messagingPost(`/SafetyEvents/${enc(a.id)}/acknowledge`);
+      console.log(`Event ${a.id} marked as reviewed.`);
+    }))
+    .command('settings <action>', 'Read or change alert settings (get | set)', (y) => y
+      .positional('action', { choices: ['get', 'set'] })
+      .option('enabled', { type: 'boolean' })
+      .option('email', { type: 'string', describe: 'Email recipients, comma separated (replaces the list)' })
+      .option('sms', { type: 'string', describe: 'SMS recipients in +15551234567 form, comma separated (replaces the list)' })
+      .option('immediate', { type: 'string', describe: 'Event types that alert right away, comma separated (replaces the list)' })
+      .option('digest', { type: 'string', choices: ['off', 'daily', 'weekly'] })
+      .option('threshold-count', { type: 'number', describe: 'Alert at this many events inside the window. 0 turns it off.' })
+      .option('threshold-window', { type: 'number', describe: 'Window in minutes, 1 to 10080' })
+      .option('json', { type: 'boolean' }),
+    runCommand(async (a) => {
+      const cur = (await messagingGet('/SafetyEvents/settings')) ?? {};
+      if (a.action === 'get') return out(a, cur, printSettings);
+      const next = { ...cur };
+      if (a.enabled !== undefined) next.enabled = a.enabled;
+      if (a.email !== undefined) next.emailRecipients = list(a.email);
+      if (a.sms !== undefined) next.smsRecipients = list(a.sms);
+      if (a.immediate !== undefined) next.immediateTypes = list(a.immediate);
+      if (a.digest !== undefined) next.digest = a.digest;
+      if (a['threshold-count'] !== undefined || a['threshold-window'] !== undefined) {
+        next.threshold = {
+          count: a['threshold-count'] ?? cur.threshold?.count ?? 0,
+          windowMinutes: a['threshold-window'] ?? cur.threshold?.windowMinutes ?? 60,
+        };
+      }
+      out(a, await messagingPut('/SafetyEvents/settings', next), (s) => { console.log('Saved.\n'); printSettings(s); });
+    }))
+    .command('test', 'Send a test alert to the configured recipients', (y) => y,
+    runCommand(async () => {
+      await messagingPost('/SafetyEvents/settings/test');
+      console.log('Test alert sent. Check the inboxes and phones on the recipient list.');
+    }))
+    .command('need-help', 'Tell the Velaro team the bot is going off the rails', (y) => y
+      .option('message', { type: 'string', demandOption: true, describe: 'What is happening' }),
+    runCommand(async (a) => {
+      await messagingPost('/SafetyEvents/need-help', { message: a.message });
+      console.log('Sent. The Velaro team has been alerted.');
+    }))
+    .demandCommand(1, 'Specify a subcommand: events, summary, ack, settings, test, need-help'),
+  handler: () => {},
+};

package/lib/deploy-state.js

@@ -0,0 +1,408 @@
+// What is on the staging environment, on staging slot 1 of production, and in production, for Admin
+// and Messaging. Needs only `gh` (already logged in) and public /Version endpoints, no other
+// credentials. Used by `velaro deploy-state`, scripts/deploy-state.mjs, `velaro ops` and the staff MCP
+// tool deploy_state. Docs: docs/architecture/deploy-state.md.
+//
+// The three landing places (docs/architecture/alert-voice.md): every dev push lands on the staging
+// environment (admin-staging, messaging-staging); Gate 1 lands the build on staging slot 1 of
+// production (healthy, NOT taking customer traffic); Gate 2 swaps it live in production. All three
+// are steps of ONE deploy workflow run, so each place is read from that run's job and step results.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const execFileAsync = promisify(execFile);
+
+export const PRODUCTS = {
+  Admin: {
+    repo: 'velaro/velaro-admin',
+    stagingEnv: 'admin-staging',
+    versionUrls: {
+      staging: 'https://velaro-admin-staging.azurewebsites.net/Version',
+      slot1: 'https://api-admin-us-east-green.velaro.com/Version',
+      prod: 'https://api-admin-us-east.velaro.com/Version',
+    },
+  },
+  Messaging: {
+    repo: 'velaro/velaro-messaging',
+    stagingEnv: 'messaging-staging',
+    versionUrls: {
+      staging: 'https://velaro-messaging-api-staging.azurewebsites.net/Version',
+      slot1: 'https://api-messaging-us-east-green.velaro.com/Version',
+      prod: 'https://api-messaging-us-east.velaro.com/Version',
+    },
+  },
+};
+
+export const PLACE_NAMES = {
+  staging: 'the staging environment',
+  slot1: 'staging slot 1 of production',
+  prod: 'production',
+};
+
+// Job and step names of deploy-staging.yml, which differ a little between the two repos.
+const JOB = {
+  staging: /^build-and-deploy-staging$|^Deploy to Staging Environment$/,
+  gate1Wait: /^\[Gate 1\] Await Approval$/,
+  gate1: /^\[Gate 1\] Deploy to Production Slot$/,
+  gate2: /^\[Gate 2\] Deploy to Production Environment$/,
+  unitGate: /^Gate: Unit Tests must be green/,
+};
+const STEP = {
+  gate1Landed: /^Warm up and verify green slot/,
+  gate2Landed: /^Swap green slot to production/,
+};
+
+// ── time ─────────────────────────────────────────────────────────────────────────────────────────
+export function pt(iso) {
+  if (!iso) return 'unknown';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return 'unknown';
+  const f = new Intl.DateTimeFormat('en-US', {
+    timeZone: 'America/Los_Angeles', month: 'numeric', day: 'numeric', hour: 'numeric', minute: '2-digit',
+  }).format(d);
+  return `${f.replace(',', '')} PT`;
+}
+
+// ── gh access (injectable for tests) ───────────────────────────────────────────────────────────────
+export async function ghApi(apiPath) {
+  const { stdout } = await execFileAsync('gh', ['api', apiPath], { maxBuffer: 64 * 1024 * 1024, timeout: 60000 });
+  return JSON.parse(stdout);
+}
+
+async function pool(items, size, fn) {
+  const out = new Array(items.length);
+  let i = 0;
+  await Promise.all(Array.from({ length: Math.min(size, items.length) }, async () => {
+    while (i < items.length) {
+      const n = i++;
+      out[n] = await fn(items[n], n);
+    }
+  }));
+  return out;
+}
+
+// ── job classification ──────────────────────────────────────────────────────────────────────────
+export function jobState(job) {
+  if (!job) return null;
+  if (job.status !== 'completed') {
+    if (job.status === 'waiting') return 'waiting';
+    if (job.status === 'in_progress') return 'running';
+    return 'queued';
+  }
+  return job.conclusion || 'unknown';
+}
+
+const find = (jobs, re) => jobs.find((j) => re.test(j.name));
+const stepOk = (job, re) => !!job && (job.steps || []).some((s) => re.test(s.name) && s.conclusion === 'success');
+
+// What one workflow run did at each of the three places.
+export function classifyRun(jobs) {
+  const stg = find(jobs, JOB.staging);
+  const g1 = find(jobs, JOB.gate1);
+  const g1Wait = find(jobs, JOB.gate1Wait);
+  const g2 = find(jobs, JOB.gate2);
+  const unitGate = find(jobs, JOB.unitGate);
+  return {
+    staging: { state: jobState(stg), landed: jobState(stg) === 'success', at: stg?.completed_at || null },
+    slot1: {
+      state: jobState(g1),
+      // a run whose slot deploy passed its health warm-up IS on the slot even if a later step failed
+      landed: jobState(g1) === 'success' || stepOk(g1, STEP.gate1Landed),
+      at: g1?.completed_at || null,
+      waiting: jobState(g1) === 'waiting' || jobState(g1Wait) === 'waiting',
+      blockedByUnitTests: jobState(unitGate) === 'failure' || jobState(unitGate) === 'cancelled',
+      unitGateState: jobState(unitGate),
+    },
+    prod: {
+      state: jobState(g2),
+      // the swap step landing means customers are on it, even when a later verify step failed
+      landed: jobState(g2) === 'success' || stepOk(g2, STEP.gate2Landed),
+      at: g2?.completed_at || null,
+      waiting: jobState(g2) === 'waiting',
+    },
+  };
+}
+
+// ── PR resolution ────────────────────────────────────────────────────────────────────────────────
+const PR_FROM_MESSAGE = [/^Merge pull request #(\d+)\b/, /\(#(\d+)\)\s*$/];
+export function prNumberFromSubject(subject) {
+  for (const re of PR_FROM_MESSAGE) {
+    const m = (subject || '').match(re);
+    if (m) return Number(m[1]);
+  }
+  return null;
+}
+
+export function makePrResolver(repo, api) {
+  const cache = new Map();
+  return async function resolvePr(n) {
+    if (!cache.has(n)) {
+      cache.set(n, api(`repos/${repo}/pulls/${n}`).then(
+        (p) => ({ number: n, title: p.title, mergedAt: p.merged_at }),
+        () => ({ number: n, title: `PR ${n}`, mergedAt: null }),
+      ));
+    }
+    return cache.get(n);
+  };
+}
+
+// What `git log --first-parent head` would show among the given commits, newest first. A PR merged
+// with a merge commit brings in its whole branch of commits; only the merge commit itself is a
+// change to dev, so follow first parents from the head and ignore the branch commits.
+export function firstParentChain(commits, headSha) {
+  const bySha = new Map(commits.map((c) => [c.sha, c]));
+  const chain = [];
+  let cur = bySha.get(headSha) || commits[commits.length - 1];
+  const guard = new Set();
+  while (cur && !guard.has(cur.sha)) {
+    guard.add(cur.sha);
+    chain.push(cur);
+    cur = bySha.get(cur.parents?.[0]?.sha);
+  }
+  return chain;
+}
+
+// PRs (and direct pushes) in base..head on the dev line, newest first. base null => just head.
+export async function changesBetween(repo, base, head, api, resolvePr) {
+  if (!head) return null;
+  if (base === head) return [];
+  let commits;
+  try {
+    if (base) {
+      // compare lists oldest first, 100 per page, so read the LAST pages (the newest commits) first;
+      // up to 6 pages, i.e. the newest 600 commits, which is where the head is.
+      const first = await api(`repos/${repo}/compare/${base}...${head}?per_page=100&page=1`);
+      const total = first.total_commits ?? (first.commits || []).length;
+      const lastPage = Math.max(Math.ceil(total / 100), 1);
+      const wanted = Array.from({ length: Math.min(lastPage, 6) }, (_, k) => lastPage - k);
+      const all = [];
+      const pagesData = await Promise.all(wanted.map((pg) => pg === 1 ? Promise.resolve(first.commits || [])
+        : api(`repos/${repo}/compare/${base}...${head}?per_page=100&page=${pg}`).then((r) => r.commits || [])));
+      pagesData.reverse().forEach((r) => all.push(...r));
+      if (!all.some((c) => c.sha === head)) return null; // head not in what was read: say unknown, never a quiet partial list
+      commits = firstParentChain(all, head);
+    } else {
+      const c = await api(`repos/${repo}/commits/${head}`);
+      commits = [c];
+    }
+  } catch {
+    return null;
+  }
+  const seen = new Set();
+  const items = [];
+  for (const c of commits) {
+    const subject = (c.commit?.message || '').split('\n')[0];
+    const n = prNumberFromSubject(subject);
+    if (n) {
+      if (seen.has(n)) continue;
+      seen.add(n);
+      items.push({ pr: n, subject, date: c.commit?.committer?.date || c.commit?.author?.date });
+    } else if (!/^Merge branch /i.test(subject)) {
+      items.push({ pr: null, subject, date: c.commit?.committer?.date || c.commit?.author?.date });
+    }
+  }
+  return pool(items, 6, async (it) => {
+    if (!it.pr) return { number: null, title: it.subject, mergedAt: it.date };
+    const p = await resolvePr(it.pr);
+    return { number: p.number, title: p.title, mergedAt: p.mergedAt || it.date };
+  });
+}
+
+// ── collection ───────────────────────────────────────────────────────────────────────────────────────
+export function readFreeze(file = path.join(os.homedir(), 'DEV-MERGE-FREEZE.txt')) {
+  try {
+    return fs.readFileSync(file, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+async function probeVersion(url, fetchFn) {
+  try {
+    const res = await fetchFn(url, { signal: AbortSignal.timeout(6000) });
+    if (!res.ok) return { ok: false, status: res.status };
+    const j = await res.json();
+    return { ok: true, version: j.version, deployedAt: j.deployedAt };
+  } catch (e) {
+    return { ok: false, err: e.message };
+  }
+}
+
+export async function collectProduct(name, { api = ghApi, fetchFn = fetch, maxRuns = 60 } = {}) {
+  const { repo, versionUrls } = PRODUCTS[name];
+  const resolvePr = makePrResolver(repo, api);
+
+  // Newest first. Three pages so a production deploy that is a few days old is still found.
+  const runs = [];
+  for (let page = 1; page <= 3; page++) {
+    const r = await api(`repos/${repo}/actions/workflows/deploy-staging.yml/runs?branch=dev&per_page=100&page=${page}`);
+    runs.push(...(r.workflow_runs || []));
+    if ((r.workflow_runs || []).length < 100) break;
+  }
+  const dev = await api(`repos/${repo}/commits/dev`);
+  const unit = await api(`repos/${repo}/actions/workflows/ci-tests.yml/runs?branch=dev&per_page=10`)
+    .then((r) => r.workflow_runs || [], () => []);
+
+  // Walk newest to oldest, loading each run's jobs, until all three places are known.
+  const found = { staging: null, slot1: null, prod: null };
+  const pending = [];
+  const BATCH = 6;
+  const blockedRuns = [];
+  const activeRuns = [];
+  for (let i = 0; i < runs.length && Object.values(found).some((v) => !v); i += BATCH) {
+    // Past the newest maxRuns runs only production is still being looked for, and a cancelled run
+    // never reaches Gate 2, so skip those to keep the GitHub calls down.
+    const batch = runs.slice(i, i + BATCH).filter((r) => i < maxRuns || r.conclusion !== 'cancelled');
+    const jobSets = await pool(batch, BATCH, (run) =>
+      api(`repos/${repo}/actions/runs/${run.id}/jobs?per_page=100`).then((r) => r.jobs || [], () => null));
+    batch.forEach((run, k) => {
+      const jobs = jobSets[k];
+      if (!jobs) return;
+      const c = classifyRun(jobs);
+      const base = { runId: run.id, sha: run.head_sha, event: run.event, createdAt: run.created_at, runStatus: run.status, runConclusion: run.conclusion };
+      for (const place of ['staging', 'slot1', 'prod']) {
+        if (!found[place] && c[place].landed) found[place] = { ...base, at: c[place].at, jobState: c[place].state };
+      }
+      if (run.status !== 'completed') {
+        activeRuns.push({ ...base, staging: c.staging.state, slot1: c.slot1.state, prod: c.prod.state });
+        if (c.prod.waiting) pending.push({ gate: 'Gate 2 waiting for approval', ...base });
+        else if (c.slot1.waiting) pending.push({ gate: 'Gate 1 waiting for approval', ...base });
+      }
+      if (c.slot1.blockedByUnitTests && run.conclusion !== 'cancelled' && blockedRuns.length < 1) {
+        blockedRuns.push({ gate: 'Gate 1 blocked, the unit tests are not green for this build', ...base });
+      }
+    });
+  }
+  // A build that never reached slot 1 because its unit tests are red only matters while it is newer
+  // than what already landed on slot 1 or in production.
+  for (const b of blockedRuns) {
+    const newest = [found.slot1?.at, found.prod?.at].filter(Boolean).sort().pop();
+    if (!newest || new Date(b.createdAt) > new Date(newest)) pending.push(b);
+  }
+
+  // After a Gate 2 swap, slot 1 holds the PREVIOUS production build, not the one that went live.
+  let slot1Note = null;
+  if (found.slot1 && found.prod && found.prod.runId === found.slot1.runId) {
+    slot1Note = 'swapped into production by Gate 2; slot 1 now holds the previous production build';
+  } else if (found.slot1 && found.prod && new Date(found.prod.at) > new Date(found.slot1.at)) {
+    slot1Note = 'a later Gate 2 swap put another build in production; slot 1 holds the build that was live before that swap';
+  }
+
+  const prodSha = found.prod?.sha || null;
+  const slotSha = slot1Note ? null : found.slot1?.sha || null;
+  const stgSha = found.staging?.sha || null;
+  const devSha = dev.sha;
+  // Each place lists the PRs it adds over the next more-live place.
+  const [prodTip, slotAdds, stgAdds, devAdds, notInProd] = await Promise.all([
+    changesBetween(repo, null, prodSha, api, resolvePr),
+    changesBetween(repo, prodSha, slotSha, api, resolvePr),
+    changesBetween(repo, slotSha || prodSha, stgSha, api, resolvePr),
+    changesBetween(repo, stgSha || slotSha || prodSha, devSha, api, resolvePr),
+    changesBetween(repo, prodSha, devSha, api, resolvePr),
+  ]);
+
+  const [vStg, vSlot, vProd] = await Promise.all(
+    ['staging', 'slot1', 'prod'].map((k) => probeVersion(versionUrls[k], fetchFn)));
+
+  return {
+    product: name,
+    repo,
+    devTip: { sha: devSha, subject: (dev.commit?.message || '').split('\n')[0], date: dev.commit?.committer?.date },
+    places: {
+      staging: { ...found.staging, adds: stgAdds, version: vStg },
+      slot1: { ...found.slot1, adds: slotAdds, note: slot1Note, version: vSlot },
+      prod: { ...found.prod, adds: prodTip, version: vProd },
+    },
+    devAdds,
+    notInProduction: notInProd,
+    pendingGates: pending,
+    activeRuns,
+    unitTestsOnDev: unit
+      .filter((r) => r.status !== 'completed')
+      .map((r) => ({ runId: r.id, status: r.status, sha: r.head_sha, createdAt: r.created_at })),
+    latestUnitTests: unit.find((r) => r.status === 'completed')
+      ? { conclusion: unit.find((r) => r.status === 'completed').conclusion, createdAt: unit.find((r) => r.status === 'completed').created_at }
+      : null,
+  };
+}
+
+export async function collectAll(opts = {}) {
+  const names = opts.products || Object.keys(PRODUCTS);
+  const states = await Promise.all(names.map((n) => collectProduct(n, opts)));
+  return { generatedAt: new Date().toISOString(), freeze: readFreeze(opts.freezeFile), products: states };
+}
+
+// ── rendering ───────────────────────────────────────────────────────────────────────────────────────
+function titles(adds, max = 3) {
+  if (adds == null) return 'unknown (could not compare)';
+  if (!adds.length) return 'nothing newer than the place below';
+  const shown = adds.slice(0, max).map((a) => (a.number ? `${a.title} (PR ${a.number})` : a.title));
+  return shown.join('; ') + (adds.length > max ? `; and ${adds.length - max} more` : '');
+}
+
+function runLine(p) {
+  if (!p || !p.runId) return 'no landed deploy found in the last 60 dev runs';
+  const how = p.runConclusion || p.runStatus;
+  return `deploy run ${p.runId}, this place ${p.jobState}, whole run ${how}, landed ${pt(p.at)}`;
+}
+
+function verLine(v) {
+  if (!v) return '';
+  if (v.ok) return `app reports version ${v.version}, deployed ${pt(v.deployedAt)}`;
+  return `app version unreachable (${v.err || 'HTTP ' + v.status})`;
+}
+
+export function render(state, { compact = false } = {}) {
+  const out = [];
+  out.push(`Deploy state at ${pt(state.generatedAt)}`);
+  out.push(state.freeze ? `Merge freeze is ON: ${state.freeze}` : 'Merge freeze: none (no ~/DEV-MERGE-FREEZE.txt)');
+  for (const p of state.products) {
+    const env = PRODUCTS[p.product].stagingEnv;
+    out.push('');
+    out.push('='.repeat(78));
+    out.push(`${p.product.toUpperCase()}   dev tip: ${p.devTip.subject}, ${pt(p.devTip.date)}`);
+    out.push('='.repeat(78));
+    const rows = [
+      [`${PLACE_NAMES.staging}, ${env}`, p.places.staging],
+      [PLACE_NAMES.slot1, p.places.slot1],
+      [PLACE_NAMES.prod, p.places.prod],
+    ];
+    for (const [label, pl] of rows) {
+      out.push(`${label.toUpperCase()}`);
+      if (!pl.runId) { out.push('  ' + runLine(pl)); continue; }
+      if (pl.note) out.push(`  Note: ${pl.note}`);
+      if (pl.note) { /* slot 1 holds the previous production build, nothing new to list */ }
+      else if (!compact) out.push(`  ${label === PLACE_NAMES.prod ? 'Newest change' : 'Adds'}: ${titles(pl.adds, label === PLACE_NAMES.prod ? 1 : 3)}`);
+      else out.push(`  Tip: ${titles(pl.adds, 1)}`);
+      const first = pl.adds && pl.adds[0];
+      if (first && !compact) out.push(`  Merged: ${pt(first.mergedAt)}`);
+      out.push(`  ${runLine(pl)}`);
+      if (!compact && pl.version) out.push(`  ${verLine(pl.version)}`);
+    }
+    if (p.devAdds && p.devAdds.length) {
+      out.push(`MERGED TO DEV, NOT YET ON THE STAGING ENVIRONMENT: ${titles(p.devAdds, 5)}`);
+    }
+    out.push('');
+    const nip = p.notInProduction;
+    if (nip == null) out.push('Merged to dev but not yet in production: unknown (no production deploy found)');
+    else if (!nip.length) out.push('Merged to dev but not yet in production: nothing, production has everything on dev');
+    else {
+      out.push(`Merged to dev but not yet in production: ${nip.length}`);
+      for (const a of nip.slice(0, compact ? 8 : 40)) out.push(`  ${pt(a.mergedAt).padEnd(16)} ${a.title}${a.number ? ` (PR ${a.number})` : ''}`);
+      if (nip.length > (compact ? 8 : 40)) out.push(`  and ${nip.length - (compact ? 8 : 40)} more`);
+    }
+    if (p.pendingGates.length) {
+      for (const g of p.pendingGates) out.push(`PENDING: ${g.gate}, deploy run ${g.runId}, started ${pt(g.createdAt)}`);
+    } else out.push('Pending gates: none waiting');
+    for (const a of p.activeRuns || []) {
+      out.push(`DEPLOY RUN IN PROGRESS: run ${a.runId}, started ${pt(a.createdAt)}, staging environment ${a.staging || 'not started'}, staging slot 1 ${a.slot1 || 'not started'}, production ${a.prod || 'not started'}`);
+    }
+    if (p.unitTestsOnDev.length) {
+      for (const u of p.unitTestsOnDev) out.push(`UNIT TESTS ${u.status.toUpperCase()} on dev: run ${u.runId}, started ${pt(u.createdAt)}. Do not merge to dev.`);
+    } else out.push(`Unit Tests on dev: none in progress${p.latestUnitTests ? `, last finished standalone run ${p.latestUnitTests.conclusion} at ${pt(p.latestUnitTests.createdAt)}` : ''}`);
+  }
+  return out.join('\n');
+}

package/lib/deploy-state.test.js

@@ -0,0 +1,133 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  classifyRun, firstParentChain, prNumberFromSubject, pt, jobState, collectProduct, render,
+} from './deploy-state.js';
+
+const job = (name, status, conclusion, steps = [], completed_at = '2026-10-12T20:00:00Z') =>
+  ({ name, status, conclusion, steps, completed_at });
+
+test('prNumberFromSubject reads both merge-commit and squash styles', () => {
+  assert.equal(prNumberFromSubject('Merge pull request #2400 from velaro/fix/red-tests-1012'), 2400);
+  assert.equal(prNumberFromSubject('Let admins renew an expiring secret (#1474)'), 1474);
+  assert.equal(prNumberFromSubject('docs(handoff): final PR states'), null);
+});
+
+test('pt formats Pacific, not UTC', () => {
+  // 2026-10-13T01:00Z is 6:00 PM on 10/12 in Pacific daylight time
+  assert.equal(pt('2026-10-13T01:00:00Z'), '10/12 6:00 PM PT');
+  assert.equal(pt(null), 'unknown');
+});
+
+test('classifyRun: staging landed, Gate 1 waiting', () => {
+  const c = classifyRun([
+    job('build-and-deploy-staging', 'completed', 'success'),
+    job('[Gate 1] Await Approval', 'waiting', null),
+    job('[Gate 1] Deploy to Production Slot', 'queued', null),
+    job('[Gate 2] Deploy to Production Environment', 'queued', null),
+  ]);
+  assert.equal(c.staging.landed, true);
+  assert.equal(c.slot1.landed, false);
+  assert.equal(c.slot1.waiting, true);
+  assert.equal(c.prod.landed, false);
+});
+
+test('classifyRun: Gate 1 blocked by red unit tests is not landed', () => {
+  const c = classifyRun([
+    job('Deploy to Staging Environment', 'completed', 'success'),
+    job('Gate: Unit Tests must be green for this commit before Gate 1 can approve', 'completed', 'failure'),
+    job('[Gate 1] Deploy to Production Slot', 'completed', 'skipped'),
+  ]);
+  assert.equal(c.staging.landed, true);
+  assert.equal(c.slot1.landed, false);
+  assert.equal(c.slot1.blockedByUnitTests, true);
+});
+
+test('classifyRun: a swap step that landed counts as live even if the job failed after it', () => {
+  const c = classifyRun([
+    job('[Gate 2] Deploy to Production Environment', 'completed', 'failure',
+      [{ name: 'Swap green slot to production', conclusion: 'success' }, { name: 'Verify', conclusion: 'failure' }]),
+  ]);
+  assert.equal(c.prod.landed, true);
+});
+
+test('classifyRun: Gate 2 waiting is pending, not landed', () => {
+  const c = classifyRun([job('[Gate 2] Deploy to Production Environment', 'waiting', null)]);
+  assert.equal(c.prod.waiting, true);
+  assert.equal(c.prod.landed, false);
+  assert.equal(jobState(job('x', 'in_progress', null)), 'running');
+});
+
+test('firstParentChain ignores commits that only live on a merged PR branch', () => {
+  const commits = [
+    { sha: 'b1', parents: [{ sha: 'base' }] },          // branch commit
+    { sha: 'm1', parents: [{ sha: 'base' }, { sha: 'b1' }] }, // merge commit of the PR, on dev
+    { sha: 'm2', parents: [{ sha: 'm1' }] },            // direct push to dev
+  ];
+  assert.deepEqual(firstParentChain(commits, 'm2').map((c) => c.sha), ['m2', 'm1']);
+});
+
+// A fake gh api for one product, to prove production, slot 1 and the staging environment are read
+// from the right jobs, and that the merged-but-not-in-production list is what is past production.
+function fakeApi() {
+  const runs = [
+    { id: 3, head_sha: 'sC', event: 'push', created_at: '2026-10-12T22:00:00Z', status: 'in_progress', conclusion: null },
+    { id: 2, head_sha: 'sB', event: 'push', created_at: '2026-10-12T18:00:00Z', status: 'completed', conclusion: 'success' },
+    { id: 1, head_sha: 'sA', event: 'push', created_at: '2026-10-11T18:00:00Z', status: 'completed', conclusion: 'success' },
+  ];
+  const jobs = {
+    3: [job('build-and-deploy-staging', 'completed', 'success', [], '2026-10-12T22:30:00Z'),
+      job('[Gate 1] Await Approval', 'waiting', null)],
+    2: [job('build-and-deploy-staging', 'completed', 'success', [], '2026-10-12T18:30:00Z'),
+      job('[Gate 1] Deploy to Production Slot', 'completed', 'success', [], '2026-10-12T19:00:00Z'),
+      job('[Gate 2] Deploy to Production Environment', 'completed', 'skipped')],
+    1: [job('build-and-deploy-staging', 'completed', 'success', [], '2026-10-11T18:30:00Z'),
+      job('[Gate 1] Deploy to Production Slot', 'completed', 'success', [], '2026-10-11T19:00:00Z'),
+      job('[Gate 2] Deploy to Production Environment', 'completed', 'success', [], '2026-10-11T20:00:00Z')],
+  };
+  const commit = (sha, msg, parent, date) => ({ sha, parents: parent ? [{ sha: parent }] : [], commit: { message: msg, committer: { date } } });
+  const log = {
+    sA: commit('sA', 'Prod change (#10)', null, '2026-10-11T17:00:00Z'),
+    sB: commit('sB', 'Slot change (#11)', 'sA', '2026-10-12T17:00:00Z'),
+    sC: commit('sC', 'Staging change (#12)', 'sB', '2026-10-12T21:00:00Z'),
+  };
+  return async (p) => {
+    let m;
+    if ((m = p.match(/workflows\/deploy-staging\.yml\/runs/))) return { workflow_runs: runs };
+    if (p.includes('workflows/ci-tests.yml/runs')) return { workflow_runs: [] };
+    if ((m = p.match(/actions\/runs\/(\d+)\/jobs/))) return { jobs: jobs[m[1]] };
+    if (p.endsWith('/commits/dev')) return log.sC;
+    if ((m = p.match(/compare\/(\w+)\.\.\.(\w+)/))) {
+      const order = ['sA', 'sB', 'sC'];
+      const [a, b] = [order.indexOf(m[1]), order.indexOf(m[2])];
+      const commits = order.slice(a + 1, b + 1).map((s) => log[s]);
+      return { total_commits: commits.length, commits };
+    }
+    if ((m = p.match(/commits\/(\w+)$/))) return log[m[1]];
+    if ((m = p.match(/pulls\/(\d+)$/))) return { title: `PR title ${m[1]}`, merged_at: `2026-10-12T0${m[1] % 10}:00:00Z` };
+    throw new Error('unexpected ' + p);
+  };
+}
+
+test('collectProduct reads each place from its own gate', async () => {
+  const state = await collectProduct('Admin', { api: fakeApi(), fetchFn: async () => ({ ok: false, status: 503 }) });
+  assert.equal(state.places.prod.sha, 'sA');
+  assert.equal(state.places.slot1.sha, 'sB');
+  assert.equal(state.places.staging.sha, 'sC');
+  assert.deepEqual(state.notInProduction.map((x) => x.number), [12, 11]);
+  assert.equal(state.pendingGates.length, 1);
+  assert.match(state.pendingGates[0].gate, /Gate 1 waiting/);
+  assert.equal(state.activeRuns.length, 1);
+});
+
+test('render names the three places in the exact words and never says prod-green', async () => {
+  const state = await collectProduct('Admin', { api: fakeApi(), fetchFn: async () => ({ ok: false, status: 503 }) });
+  const text = render({ generatedAt: '2026-10-13T01:00:00Z', freeze: 'FROZEN for candidate abc', products: [state] });
+  assert.match(text, /THE STAGING ENVIRONMENT, ADMIN-STAGING/);
+  assert.match(text, /STAGING SLOT 1 OF PRODUCTION/);
+  assert.match(text, /\nPRODUCTION\n/);
+  assert.match(text, /Merged to dev but not yet in production: 2/);
+  assert.match(text, /Merge freeze is ON: FROZEN for candidate abc/);
+  assert.match(text, /PENDING: Gate 1 waiting for approval, deploy run 3/);
+  assert.doesNotMatch(text, /prod-green/i);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.97",
+  "version": "1.4.99",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {