@velaro/cli 1.4.56 → 1.4.58

package/README.md

@@ -104,6 +104,17 @@ client using the old key; the command does not edit client configurations.
 velaro mcp-key rotate 2
 ```
 
+### `velaro routing <subcommand>`
+Auto-routing policy and the agent inactivity chain (v20 only).
+
+```bash
+velaro routing policy get                                   # includes reassignment mode + chain
+velaro routing policy set --reassignment-mode Reassign --chain true --backup-team 5 --backup-after 120 --no-agent-after 300 --terminal-action EndChat
+velaro routing simulate --no-agent-seconds 400 --step 1     # DRY RUN, nothing is sent
+velaro routing precedence                                   # which rule wins + conflict warnings
+velaro routing inactivity-transfers --days 30 --agent-name Sam
+```
+
 ### `velaro kb article <subcommand>`
 Manage your help.velaro.com knowledge base articles. Full reference (including the REST/MCP equivalents and the screenshot pipeline): [`docs/architecture/kb-publishing-system.md`](../docs/architecture/kb-publishing-system.md).
 

package/lib/commands/logs.js

@@ -18,6 +18,16 @@ function parseDuration(s) {
   return n * 24 * 3600 * 1000;
 }
 
+// FIXED 2026-09-24: velaro-messaging's /superadmin/logs/search used to return a bare JSON array
+// for some queries and {entries, nextCursor} for others, depending on which internal code path
+// served the request. It now always returns {entries, nextCursor} -- this helper also accepts a
+// bare array so the CLI degrades gracefully rather than crashing if pointed at an older deploy.
+function extractLogEntries(response) {
+  if (Array.isArray(response)) return response;
+  if (response && Array.isArray(response.entries)) return response.entries;
+  return [];
+}
+
 function printEntry(e) {
   const ts      = new Date(e.timestamp ?? e.LogTimestamp).toISOString().replace('T', ' ').slice(0, 19);
   const lvl     = (e.Level ?? e.level ?? '?').padEnd(5);
@@ -52,12 +62,15 @@ async function searchLogs(argv) {
 
   const from = new Date(Date.now() - parseDuration(argv.last ?? '2h'));
   const params = new URLSearchParams({ from: from.toISOString(), take: String(argv.take ?? 50) });
-  if (argv.query)       params.set('q',           argv.query);
-  if (argv.level)       params.set('level',        argv.level.toUpperCase());
-  if (argv.integration) params.set('integration',  argv.integration);
-  if (argv.site)        params.set('siteId',        String(argv.site));
-  if (argv.source)      params.set('source',        argv.source);
-  if (argv.regex)       params.set('regex',         'true');
+  if (argv.query)         params.set('q',             argv.query);
+  if (argv.level)         params.set('level',         argv.level.toUpperCase());
+  if (argv.integration)   params.set('integration',   argv.integration);
+  if (argv.site)          params.set('siteId',        String(argv.site));
+  if (argv.source)        params.set('source',        argv.source);
+  if (argv.platform)      params.set('platform',      argv.platform);
+  if (argv.environment)   params.set('environment',   argv.environment);
+  if (argv.correlationId) params.set('correlationId', argv.correlationId);
+  if (argv.regex)         params.set('regex',         'true');
 
   const res = await fetch(`${msgBase}/superadmin/logs/search?${params}`, {
     headers: {
@@ -72,8 +85,8 @@ async function searchLogs(argv) {
     process.exit(1);
   }
 
-  const entries = await res.json();
-  if (!Array.isArray(entries) || !entries.length) {
+  const entries = extractLogEntries(await res.json());
+  if (!entries.length) {
     console.log('No results.');
     return;
   }
@@ -210,8 +223,7 @@ async function diagnoseLogs(argv) {
       signal: AbortSignal.timeout(15000),
     });
     if (!r.ok) return [];
-    const d = await r.json();
-    return Array.isArray(d) ? d : [];
+    return extractLogEntries(await r.json());
   }
 
   const [errors, perfAndRouting] = await Promise.all([
@@ -675,14 +687,17 @@ export const logsCommand = {
       describe: 'Search application logs',
       builder:  y => y
         .positional('query', { describe: 'Text to search for (or regex with --regex)', type: 'string' })
-        .option('level',       { describe: 'Filter by level: ERROR, WARN, INFO, DEBUG', type: 'string' })
-        .option('integration', { describe: 'Integration tag (HubSpot, NetSuite, [Skill], etc.)', type: 'string' })
-        .option('site',        { describe: 'Filter by site ID', type: 'number' })
-        .option('source',      { describe: 'App source (velaro-messaging-Staging, etc.)', type: 'string' })
-        .option('last',        { describe: 'Time window: 30m, 2h, 1d', default: '2h', type: 'string' })
-        .option('regex',       { describe: 'Treat query as regex', boolean: true, default: false })
-        .option('take',        { describe: 'Max results (max 500)', default: 50, type: 'number' })
-        .option('env',         { describe: 'staging or prod', type: 'string' }),
+        .option('level',         { describe: 'Filter by level: ERROR, WARN, INFO, DEBUG', type: 'string' })
+        .option('integration',   { describe: 'Integration tag (HubSpot, NetSuite, [Skill], etc.)', type: 'string' })
+        .option('site',          { describe: 'Filter by site ID', type: 'number' })
+        .option('source',        { describe: 'App source (velaro-messaging-Staging, etc.)', type: 'string' })
+        .option('platform',      { describe: 'Filter by platform: v10, v20, admin', type: 'string' })
+        .option('environment',   { describe: 'Filter by environment: Production, Staging, Development', type: 'string' })
+        .option('correlationId', { describe: 'Exact correlation/trace ID filter', type: 'string' })
+        .option('last',          { describe: 'Time window: 30m, 2h, 1d', default: '2h', type: 'string' })
+        .option('regex',         { describe: 'Treat query as regex', boolean: true, default: false })
+        .option('take',          { describe: 'Max results (max 500)', default: 50, type: 'number' })
+        .option('env',           { describe: 'staging or prod', type: 'string' }),
       handler: searchLogs,
     })
     .command({

package/lib/commands/ops.js

@@ -14,6 +14,17 @@ function ago(dateStr) {
   return `${Math.round(hrs / 24)}d ago`;
 }
 
+// FIXED 2026-09-24: velaro-messaging's /superadmin/logs/search used to return a bare JSON array
+// for some queries and {entries, nextCursor} for others, depending on which internal code path
+// served the request. It now always returns {entries, nextCursor} -- this helper also accepts a
+// bare array so this command degrades gracefully rather than crashing if pointed at an older
+// deploy.
+function extractLogEntries(response) {
+  if (Array.isArray(response)) return response;
+  if (response && Array.isArray(response.entries)) return response.entries;
+  return [];
+}
+
 function utcLabel(dateStr) {
   if (!dateStr) return '';
   const d = new Date(dateStr);
@@ -236,8 +247,8 @@ export const opsCommand = {
         }),
       ]);
 
-      const errors   = errRes.ok  ? (await errRes.json().catch(() => [])) : [];
-      const perfLogs = perfRes.ok ? (await perfRes.json().catch(() => [])) : [];
+      const errors   = errRes.ok  ? extractLogEntries(await errRes.json().catch(() => [])) : [];
+      const perfLogs = perfRes.ok ? extractLogEntries(await perfRes.json().catch(() => [])) : [];
 
       const perfCount  = perfLogs.filter(e => (e.Message ?? e.message ?? '').includes('PERF-SLOW')).length;
       const routeCount = perfLogs.filter(e => (e.Message ?? e.message ?? '').includes('WF-AI-ROUTE')).length;

package/lib/commands/routing.js

@@ -1,4 +1,8 @@
-import { messagingGet, messagingPut, messagingDel, get as adminGet } from '../api.js';
+import { messagingGet, messagingPut, messagingPost, messagingDel, get as adminGet } from '../api.js';
+import {
+  TERMINAL_ACTION_NAMES, buildPolicyUpdate, validatePolicyUpdate, describeChain,
+  describeSimulation, describeTransfers,
+} from '../routing-inactivity.js';
 
 // ── helpers ───────────────────────────────────────────────────────────────────
 
@@ -26,8 +30,18 @@ const TERMINAL_LABELS = {
   3: 'Queue',
   4: 'Offline Message',
   5: 'No Action',
+  6: 'End Chat',
+  7: 'Notify Manager',
+  8: 'Run Workflow',
 };
 
+// The API returns the terminal action as a NAME (e.g. "EndChat"); older builds returned an int.
+function terminalText(v) {
+  if (v == null) return 'Default (Survey)';
+  if (typeof v === 'number') return TERMINAL_LABELS[v] ?? String(v);
+  return String(v);
+}
+
 // ── velaro routing engine get ─────────────────────────────────────────────────
 
 const engineGetCommand = {
@@ -129,10 +143,8 @@ const policyGetCommand = {
     console.log(`  ${DIM}Agent follow-up flag:      ${RESET}${p.agentFollowUpFlagEnabled ? `${GRN}yes${RESET}` : 'no'}`);
     console.log(`  ${DIM}Queue unavailable grace:   ${RESET}${p.queueUnavailableGracePeriodSeconds}s`);
 
-    const terminalLabel = p.terminalActionOverride != null
-      ? (TERMINAL_LABELS[p.terminalActionOverride] ?? String(p.terminalActionOverride))
-      : 'Default (Survey)';
-    console.log(`  ${DIM}Terminal action:           ${RESET}${terminalLabel}`);
+    console.log(`  ${DIM}Terminal action:           ${RESET}${terminalText(p.terminalActionOverride)}`);
+    for (const line of describeChain(p)) console.log(`  ${line}`);
     console.log();
   },
 };
@@ -168,26 +180,37 @@ const policySetCommand = {
       describe: 'Prefer previous agent on timeout (true/false)',
     })
     .option('terminal-action', {
-      type:     'number',
-      describe: 'Terminal action: 0=Survey 1=CreateTicket 2=SurveyAndCreateTicket 3=Queue 4=OfflineMessage 5=NoOp',
-    }),
+      type:     'string',
+      describe: `Terminal action, name or 0-8: ${TERMINAL_ACTION_NAMES.map((n, i) => `${i}=${n}`).join(' ')}`,
+    })
+    .option('exhaustion-message', { type: 'string', describe: 'Visitor message when the final action runs' })
+    .option('reassignment-mode', {
+      type: 'string', choices: ['Observe', 'QueueOnly', 'Reassign'],
+      describe: 'Observe = log only (default), QueueOnly = return chat to the queue, Reassign = move to another agent',
+    })
+    .option('chain', { type: 'boolean', describe: 'Turn the agent inactivity chain on/off' })
+    .option('backup-team', { type: 'number', describe: 'Backup group (team) id to offer the chat to' })
+    .option('backup-after', { type: 'number', describe: 'Seconds with no same-group agent before the backup group (0-7200)' })
+    .option('no-agent-after', { type: 'number', describe: 'Seconds with no agent available before the final action (0-14400)' })
+    .option('presence-trigger', { type: 'boolean', describe: 'Reroute when the agent goes Away/Offline' })
+    .option('alert-on-release', { type: 'boolean', describe: 'Alert available agents when a chat is released' })
+    .option('notify-managers', { type: 'boolean', describe: 'Notify managers on inactivity' })
+    .option('cooldown', { type: 'number', describe: 'Seconds between moves of the same chat (0-3600)' })
+    .option('queue-escalation-minutes', { type: 'number', describe: 'Minutes in queue before escalation alert (1-240)' })
+    .option('terminal-workflow', { type: 'number', describe: 'Workflow id to run when the terminal action is RunWorkflow' })
+    .option('visitor-text', { type: 'string', describe: 'Visitor status text (max 500). Tokens: {{releasedFromAgent}} {{reason}} {{teamName}}' })
+    .option('agent-text', { type: 'string', describe: 'Agent status text (max 500)' }),
   handler:  async (argv) => {
     // Load current policy first, then merge
     const current = await messagingGet('/AutoRoutingPolicy');
 
-    const updated = {
-      ...current,
-      initialResponseTimeoutSeconds:  argv['initial-timeout']  ?? current.initialResponseTimeoutSeconds,
-      idleAfterResponseTimeoutSeconds: argv['idle-timeout']     ?? current.idleAfterResponseTimeoutSeconds,
-      idleAlertGraceSeconds:           argv['grace']            ?? current.idleAlertGraceSeconds,
-      maxRerouteAttempts:              argv['max-reroutes']     ?? current.maxRerouteAttempts,
-      allowBounceBack:                 argv['allow-bounceback'] ?? current.allowBounceBack,
-      preferPreviousAgentOnTimeout:    argv['prefer-previous']  ?? current.preferPreviousAgentOnTimeout,
-      terminalActionOverride:
-        argv['terminal-action'] !== undefined
-          ? argv['terminal-action']
-          : current.terminalActionOverride,
-    };
+    const updated = buildPolicyUpdate(current, argv);
+    const problems = validatePolicyUpdate(updated);
+    if (problems.length) {
+      for (const m of problems) console.error(`  ${RED}x${RESET} ${m}`);
+      process.exitCode = 1;
+      return;
+    }
 
     await messagingPut('/AutoRoutingPolicy', updated);
     console.log(`\n  ${GRN}✓${RESET} Routing policy updated.\n`);
@@ -279,7 +302,7 @@ const explainCommand = {
       console.log(`  Initial timeout:    ${p.initialResponseTimeoutSeconds}s`);
       console.log(`  Idle timeout:       ${p.idleAfterResponseTimeoutSeconds}s`);
       console.log(`  Max reroutes:       ${p.maxRerouteAttempts}`);
-      console.log(`  Terminal action:    ${p.terminalActionOverride != null ? TERMINAL_LABELS[p.terminalActionOverride] ?? p.terminalActionOverride : 'default (Survey)'}`);
+      console.log(`  Terminal action:    ${terminalText(p.terminalActionOverride)}`);
       console.log(`  Anti-bounce:        ${!p.allowBounceBack ? `${GRN}ON${RESET}` : `${DIM}off${RESET}`}`);
       console.log(`  Prefer prev agent:  ${p.preferPreviousAgentOnTimeout ? `${GRN}yes${RESET}` : 'no'}`);
     }
@@ -287,6 +310,76 @@ const explainCommand = {
   },
 };
 
+// ── velaro routing simulate ───────────────────────────────────────────────────
+
+const simulateCommand = {
+  command:  'simulate',
+  describe: 'DRY RUN: what would the agent inactivity chain do for a mocked scenario (sends nothing)',
+  builder:  (y) => y
+    .option('team', { type: 'number', describe: 'Group id whose policy to simulate (default: site default)' })
+    .option('no-agent-seconds', { type: 'number', default: 0, describe: 'Seconds nobody has been available' })
+    .option('attempts-used', { type: 'number', default: 0, describe: 'Moves already used on the chat' })
+    .option('step', { type: 'number', default: 0, describe: '0 nothing tried, 1 backup group offered, 2 final action applied' })
+    .option('since-last-transfer', { type: 'number', describe: 'Seconds since the chat was last moved' })
+    .option('already-handled', { type: 'boolean', default: false, describe: 'Simulate the same silence delivered twice' })
+    .option('agent-name', { type: 'string', describe: 'Silent agent name for the alert text' }),
+  handler:  async (argv) => {
+    const r = await messagingPost('/Routing/Inactivity/simulate', {
+      teamId: argv.team ?? null,
+      noAgentSeconds: argv['no-agent-seconds'],
+      attemptsUsed: argv['attempts-used'],
+      inactivityStep: argv.step,
+      secondsSinceLastTransfer: argv['since-last-transfer'] ?? null,
+      sameEpisodeAlreadyHandled: argv['already-handled'],
+      fromAgentName: argv['agent-name'] ?? null,
+    });
+    console.log();
+    for (const l of describeSimulation(r)) console.log(`  ${l}`);
+    console.log();
+  },
+};
+
+// ── velaro routing precedence ─────────────────────────────────────────────────
+
+const precedenceCommand = {
+  command:  'precedence',
+  describe: 'Which routing rule wins when an agent goes silent, plus policy conflict warnings',
+  builder:  (y) => y,
+  handler:  async () => {
+    const [defaults, conflicts] = await Promise.all([
+      messagingGet('/Routing/Inactivity/defaults'),
+      messagingGet('/Routing/Inactivity/conflicts'),
+    ]);
+    console.log(`\n${BOLD}Evaluation order (top to bottom)${RESET}`);
+    for (const p of defaults.precedence ?? []) console.log(`  ${p}`);
+    const list = conflicts.conflicts ?? [];
+    console.log(`\n${BOLD}Warnings${RESET}`);
+    if (!list.length) console.log('  None. No group policy cancels out the site default.');
+    for (const c of list) console.log(`  [${String(c.severity).toUpperCase()}] ${c.teamId != null ? `group ${c.teamId}` : 'site default'}: ${c.message}`);
+    console.log();
+  },
+};
+
+// ── velaro routing inactivity-transfers ───────────────────────────────────────
+
+const inactivityTransfersCommand = {
+  command:  'inactivity-transfers',
+  describe: 'Count agent inactivity transfers (chats taken from a silent agent), total, per agent, per day',
+  builder:  (y) => y
+    .option('days', { type: 'number', default: 30, describe: 'Lookback in days (1-92)' })
+    .option('agent-name', { type: 'string', describe: 'Agent display name (partial match)' })
+    .option('agent-id', { type: 'number', describe: 'Exact agent id' }),
+  handler:  async (argv) => {
+    let path = `RoutingDiagnostics/inactivity-transfers?days=${argv.days}`;
+    if (argv['agent-id'] != null) path += `&agentId=${argv['agent-id']}`;
+    if (argv['agent-name']) path += `&agentName=${encodeURIComponent(argv['agent-name'])}`;
+    const r = await adminGet(path);
+    console.log();
+    for (const l of describeTransfers(r)) console.log(`  ${l}`);
+    console.log();
+  },
+};
+
 // ── top-level routing command ─────────────────────────────────────────────────
 
 export const routingCommand = {
@@ -298,7 +391,10 @@ export const routingCommand = {
     .command(policyCommand)
     .command(decisionLogCommand)
     .command(explainCommand)
-    .demandCommand(1, 'Specify a subcommand: engine, circuit-breaker, policy, decision-log, explain')
+    .command(simulateCommand)
+    .command(precedenceCommand)
+    .command(inactivityTransfersCommand)
+    .demandCommand(1, 'Specify a subcommand: engine, circuit-breaker, policy, decision-log, explain, simulate, precedence, inactivity-transfers')
     .strict(),
   handler:  () => {},
 };

package/lib/routing-inactivity.js

@@ -0,0 +1,160 @@
+// Pure logic for `velaro routing ...` agent inactivity chain commands (velaro-messaging PR #1471).
+// v20 ONLY. No I/O here so it can be unit tested (see routing-inactivity.test.js).
+
+// Persisted as ints by messaging (append-only enum); the API accepts and returns the NAME.
+export const TERMINAL_ACTION_NAMES = [
+  'Survey', 'CreateTicket', 'SurveyAndCreateTicket', 'Queue', 'OfflineMessage', 'NoOp',
+  'EndChat', 'NotifyManager', 'RunWorkflow',
+];
+
+export function terminalLabel(v) {
+  if (v === null || v === undefined || v === '') return 'Default (Survey)';
+  if (typeof v === 'number') return TERMINAL_ACTION_NAMES[v] ?? String(v);
+  return String(v);
+}
+
+/** Accepts an int (0-8) or a name (any case). Returns the enum name, or null for "default". Throws on junk. */
+export function terminalForSave(v) {
+  if (v === null || v === undefined || v === '') return null;
+  if (typeof v === 'number' || /^\d+$/.test(String(v))) {
+    const name = TERMINAL_ACTION_NAMES[Number(v)];
+    if (!name) throw new Error(`Unknown terminal action ${v}. Use 0-8: ${TERMINAL_ACTION_NAMES.map((n, i) => `${i}=${n}`).join(' ')}`);
+    return name;
+  }
+  const hit = TERMINAL_ACTION_NAMES.find(n => n.toLowerCase() === String(v).toLowerCase());
+  if (!hit) throw new Error(`Unknown terminal action "${v}". Use one of: ${TERMINAL_ACTION_NAMES.join(', ')}`);
+  return hit;
+}
+
+// CLI flag -> AutoRoutingPolicy.InactivityChain field
+export const CHAIN_FLAGS = {
+  'chain': 'enabled',
+  'backup-team': 'backupTeamId',
+  'backup-after': 'backupTeamAfterSeconds',
+  'no-agent-after': 'noTargetActionAfterSeconds',
+  'presence-trigger': 'rerouteOnAgentUnavailable',
+  'alert-on-release': 'alertAvailableAgentsOnRelease',
+  'notify-managers': 'notifyManagersOnInactivity',
+  'cooldown': 'rerouteCooldownSeconds',
+  'queue-escalation-minutes': 'queueEscalationAfterMinutes',
+  'terminal-workflow': 'terminalWorkflowId',
+  'visitor-text': 'visitorStatusText',
+  'agent-text': 'agentStatusText',
+};
+
+/**
+ * Merges CLI flags onto the current policy and returns the PUT body.
+ * reassignmentMode is ALWAYS sent (an absent value is treated as Observe by the API and would silently
+ * switch reassignment off). The chain block is only sent when the server reports one or a chain flag is set.
+ */
+export function buildPolicyUpdate(current, argv) {
+  const merged = { ...current };
+  const map = {
+    'initial-timeout': 'initialResponseTimeoutSeconds',
+    'idle-timeout': 'idleAfterResponseTimeoutSeconds',
+    'grace': 'idleAlertGraceSeconds',
+    'max-reroutes': 'maxRerouteAttempts',
+    'allow-bounceback': 'allowBounceBack',
+    'prefer-previous': 'preferPreviousAgentOnTimeout',
+    'exhaustion-message': 'exhaustionMessageTemplate',
+  };
+  for (const [flag, field] of Object.entries(map)) if (argv[flag] !== undefined) merged[field] = argv[flag];
+
+  merged.terminalActionOverride = terminalForSave(
+    argv['terminal-action'] !== undefined ? argv['terminal-action'] : current.terminalActionOverride
+  );
+  // Actions 6-8 exist only on a messaging build with the inactivity chain; an older one would store a different value.
+  if (['EndChat', 'NotifyManager', 'RunWorkflow'].includes(merged.terminalActionOverride) && !('inactivityChain' in current))
+    throw new Error(`Terminal action ${merged.terminalActionOverride} needs a messaging build with the agent inactivity chain; this one does not report it. Use 0-5.`);
+
+  const mode = argv['reassignment-mode'] ?? current.reassignmentMode ?? 'Observe';
+  if (!['Observe', 'QueueOnly', 'Reassign'].includes(mode)) {
+    throw new Error(`Unknown reassignment mode "${mode}". Use Observe, QueueOnly or Reassign.`);
+  }
+  merged.reassignmentMode = mode;
+
+  const patched = Object.keys(CHAIN_FLAGS).filter(f => argv[f] !== undefined);
+  if (current.inactivityChain || patched.length) {
+    const chain = { ...(current.inactivityChain ?? {}) };
+    for (const f of patched) chain[CHAIN_FLAGS[f]] = argv[f];
+    merged.inactivityChain = chain;
+  }
+  return merged;
+}
+
+/** Client-side mirror of the server's cross-field rules, so the CLI fails before the round trip. */
+export function validatePolicyUpdate(p) {
+  const errors = [];
+  const c = p.inactivityChain;
+  // RunWorkflow with no workflow is invalid whatever the chain switch says: the final action also runs
+  // when the chain is off (hop cap reached), so it would have nothing to run.
+  if (p.terminalActionOverride === 'RunWorkflow' && (!c || c.terminalWorkflowId == null))
+    errors.push('Terminal action RunWorkflow needs --terminal-workflow <id>.');
+  if (!c || !c.enabled) return errors;
+  if ((c.backupTeamId != null || c.noTargetActionAfterSeconds != null) && p.reassignmentMode !== 'Reassign')
+    errors.push("The backup group and no-agent-available steps need --reassignment-mode Reassign.");
+  if (c.backupTeamId != null && c.noTargetActionAfterSeconds != null && c.noTargetActionAfterSeconds < (c.backupTeamAfterSeconds ?? 120))
+    errors.push('--no-agent-after must be at least as long as --backup-after (the backup group step runs first).');
+  return errors;
+}
+
+export function describeChain(p) {
+  const c = p.inactivityChain;
+  if (!c) return ['(This messaging build does not report the inactivity chain.)'];
+  const out = [
+    `Reassignment mode:     ${p.reassignmentMode ?? 'Observe'}`,
+    `Inactivity chain:      ${c.enabled ? 'ON' : 'off'}`,
+  ];
+  if (c.enabled) {
+    out.push(
+      `  Backup group:        ${c.backupTeamId ?? 'none'}${c.backupTeamId != null ? ` after ${c.backupTeamAfterSeconds}s` : ''}`,
+      `  Final action after:  ${c.noTargetActionAfterSeconds != null ? `${c.noTargetActionAfterSeconds}s with no agent available` : 'only when the hop cap is used up'}`,
+      `  Cooldown:            ${c.rerouteCooldownSeconds}s`,
+      `  Presence trigger:    ${c.rerouteOnAgentUnavailable}`,
+      `  Alert on release:    ${c.alertAvailableAgentsOnRelease}`,
+      `  Notify managers:     ${c.notifyManagersOnInactivity}`,
+      `  Queue escalation:    ${c.queueEscalationAfterMinutes != null ? `${c.queueEscalationAfterMinutes} min` : 'never'}`,
+      `  Terminal workflow:   ${c.terminalWorkflowId ?? 'none'}`,
+    );
+  }
+  return out;
+}
+
+const GATE = {
+  NotEnabled: "The inactivity chain is off for this rule, so today's behavior applies and nothing new happens.",
+  Proceed: 'Allowed to move the chat.',
+  SkipDedupe: 'Blocked: this exact silence was already handled (double-transfer guard).',
+  SkipCooldown: 'Blocked: the chat was moved too recently (cooldown).',
+  HopCapReached: 'Hop cap reached: no more moves, so the final action applies.',
+};
+const ACTION = {
+  LegacyDefer: 'Nothing new is configured, so the chat stays with its current owner.',
+  Hold: 'Still inside the wait window, nothing happens yet.',
+  WidenToBackupTeam: 'The chat is offered to the backup group.',
+  ApplyTerminal: 'The final action runs.',
+};
+
+export function describeSimulation(r) {
+  const lines = [
+    'DRY RUN (nothing sent, no live chat touched)',
+    `Settings used: ${r.ruleSource}`,
+    `Safety gate:   ${GATE[r.gate] ?? r.gate}`,
+    `Decision:      ${ACTION[r.noTargetAction] ?? r.noTargetAction}`,
+  ];
+  if (r.explanation) lines.push(`Why:           ${r.explanation}`);
+  if (r.nextStepAtSeconds != null) lines.push(`Next step after ${r.nextStepAtSeconds}s with no agent available.`);
+  lines.push(`Visitor would see: "${r.visitorMessage}"`, `Agents would see:  "${r.queueAlert || r.agentStatus}"`);
+  for (const l of r.otherRulesThatMatchedButLost ?? []) lines.push(`Also matched but lost: ${l.rule} (${l.reason})`);
+  return lines;
+}
+
+export function describeTransfers(r) {
+  if (r.note && !r.total && !(r.byAgent ?? []).length) return [r.note];
+  const lines = [`Agent inactivity transfers, site ${r.siteId}, last ${r.days} days: ${r.total}${r.capped ? ' (capped at 5000)' : ''}`];
+  if (r.note) lines.push(r.note);
+  if (r.matchedAgentsCapped) lines.push('The name matched more agents than are counted here. Use a longer name or --agent-id.');
+  for (const a of r.byAgent ?? []) lines.push(`  ${a.name}${a.agentId != null ? ` (id ${a.agentId})` : ''}: ${a.count}`);
+  if ((r.byDay ?? []).length) lines.push('', 'By day (Pacific): ' + r.byDay.map(d => `${d.date}=${d.count}`).join(', '));
+  if (!r.total) lines.push('None. Check that the inactivity chain is on and reassignment mode is not Observe.');
+  return lines;
+}

package/lib/routing-inactivity.test.js

@@ -0,0 +1,101 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import {
+  buildPolicyUpdate, validatePolicyUpdate, terminalForSave, terminalLabel,
+  describeChain, describeSimulation, describeTransfers,
+} from './routing-inactivity.js';
+
+const current = {
+  enabled: true, maxRerouteAttempts: 3, terminalActionOverride: 'Survey', reassignmentMode: 'Reassign',
+  inactivityChain: { enabled: true, backupTeamId: 5, backupTeamAfterSeconds: 120, noTargetActionAfterSeconds: 300, rerouteCooldownSeconds: 60 },
+};
+
+test('terminal action accepts ints and names, rejects junk', () => {
+  assert.equal(terminalForSave(6), 'EndChat');
+  assert.equal(terminalForSave('7'), 'NotifyManager');
+  assert.equal(terminalForSave('runworkflow'), 'RunWorkflow');
+  assert.equal(terminalForSave(undefined), null);
+  assert.throws(() => terminalForSave(9), /Unknown terminal action/);
+  assert.throws(() => terminalForSave('Bogus'), /Unknown terminal action/);
+  assert.equal(terminalLabel(null), 'Default (Survey)');
+  assert.equal(terminalLabel(8), 'RunWorkflow');
+});
+
+test('an update with no chain flags keeps the saved mode and chain (mode is always sent)', () => {
+  const body = buildPolicyUpdate(current, { 'max-reroutes': 4 });
+  assert.equal(body.maxRerouteAttempts, 4);
+  assert.equal(body.reassignmentMode, 'Reassign');
+  assert.deepEqual(body.inactivityChain, current.inactivityChain);
+  assert.equal(body.terminalActionOverride, 'Survey');
+});
+
+test('a server without reassignmentMode still sends Observe explicitly and no chain block', () => {
+  const body = buildPolicyUpdate({ enabled: true }, { 'max-reroutes': 2 });
+  assert.equal(body.reassignmentMode, 'Observe');
+  assert.equal('inactivityChain' in body, false);
+});
+
+test('chain flags patch the chain block', () => {
+  const body = buildPolicyUpdate(current, { 'cooldown': 90, 'chain': false, 'visitor-text': 'Hi' });
+  assert.equal(body.inactivityChain.rerouteCooldownSeconds, 90);
+  assert.equal(body.inactivityChain.enabled, false);
+  assert.equal(body.inactivityChain.visitorStatusText, 'Hi');
+  assert.equal(body.inactivityChain.backupTeamId, 5);
+});
+
+test('chain flags create the block on a server that had none', () => {
+  const body = buildPolicyUpdate({ enabled: true }, { chain: true, 'backup-team': 5, 'reassignment-mode': 'Reassign' });
+  assert.equal(body.inactivityChain.enabled, true);
+  assert.equal(body.reassignmentMode, 'Reassign');
+});
+
+test('rejects an unknown reassignment mode', () => {
+  assert.throws(() => buildPolicyUpdate(current, { 'reassignment-mode': 'Yolo' }), /Unknown reassignment mode/);
+});
+
+test('validation mirrors the server cross-field rules', () => {
+  assert.deepEqual(validatePolicyUpdate(buildPolicyUpdate(current, {})), []);
+  assert.match(validatePolicyUpdate(buildPolicyUpdate(current, { 'reassignment-mode': 'QueueOnly' }))[0], /Reassign/);
+  assert.match(validatePolicyUpdate(buildPolicyUpdate(current, { 'backup-after': 600 }))[0], /at least as long/);
+  assert.match(validatePolicyUpdate(buildPolicyUpdate(current, { 'terminal-action': 'RunWorkflow' }))[0], /--terminal-workflow/);
+  assert.deepEqual(validatePolicyUpdate(buildPolicyUpdate(current, { chain: false, 'reassignment-mode': 'Observe' })), []);
+  // RunWorkflow without a workflow is rejected even with the chain off (the final action still runs at the hop cap).
+  assert.match(
+    validatePolicyUpdate(buildPolicyUpdate(current, { chain: false, 'reassignment-mode': 'Observe', 'terminal-action': 'RunWorkflow' }))[0],
+    /--terminal-workflow/
+  );
+  assert.deepEqual(
+    validatePolicyUpdate(buildPolicyUpdate(current, { 'terminal-action': 'RunWorkflow', 'terminal-workflow': 9 })),
+    []
+  );
+});
+
+test('terminal actions 6-8 are rejected when the current policy has no inactivityChain block', () => {
+  const legacy = { enabled: true, maxRerouteAttempts: 3, terminalActionOverride: 'Survey', reassignmentMode: 'Observe' };
+  assert.throws(() => buildPolicyUpdate(legacy, { 'terminal-action': 'EndChat' }), /inactivity chain/);
+  assert.throws(() => buildPolicyUpdate(legacy, { 'terminal-action': 8 }), /inactivity chain/);
+  assert.equal(buildPolicyUpdate(legacy, { 'terminal-action': 3 }).terminalActionOverride, 'Queue');
+});
+
+test('describeTransfers keeps results when a site override was ignored', () => {
+  const lines = describeTransfers({
+    siteId: 1, days: 30, total: 2, siteOverrideIgnored: true,
+    note: 'siteIdOverride=5 was ignored because only Velaro admins may query another site. These results are for site 1.',
+    byAgent: [{ agentId: 7, name: 'Sam', count: 2 }], byDay: [{ date: '2026-09-24', count: 2 }],
+  }).join('\n');
+  assert.match(lines, /was ignored/);
+  assert.match(lines, /Sam \(id 7\): 2/);
+  assert.match(lines, /By day \(Pacific\): 2026-09-24=2/);
+});
+
+test('describe helpers render the chain, a simulation and a transfer count', () => {
+  assert.match(describeChain(current).join('\n'), /Inactivity chain:\s+ON/);
+  assert.match(describeChain({}).join('\n'), /does not report/);
+  const sim = describeSimulation({ ruleSource: 'SiteDefault', gate: 'SkipCooldown', noTargetAction: 'Hold', explanation: 'x', nextStepAtSeconds: 60, visitorMessage: 'v', agentStatus: 'a', queueAlert: '', otherRulesThatMatchedButLost: [{ rule: 'R', reason: 'why' }] });
+  assert.match(sim.join('\n'), /DRY RUN/);
+  assert.match(sim.join('\n'), /cooldown/);
+  assert.match(sim.join('\n'), /Also matched but lost: R \(why\)/);
+  assert.match(describeTransfers({ siteId: 1, days: 30, total: 0, byAgent: [], byDay: [] }).join('\n'), /None\./);
+  assert.match(describeTransfers({ siteId: 1, days: 30, total: 2, byAgent: [{ agentId: 7, name: 'Sam', count: 2 }], byDay: [] }).join('\n'), /Sam \(id 7\): 2/);
+  assert.deepEqual(describeTransfers({ note: 'No agent found' }), ['No agent found']);
+});

package/package.json

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