@jacebenson/jsn 4.3.7 → 4.3.8-dev.46

package/src/commands/perf.js

@@ -1,14 +1,22 @@
 import { errUsageHint, errUsage } from '../errors.js';
 import { captureRun, listRuns, getRun, compareRuns, formatRunDetailed, formatRunList, formatComparisonDetailed } from '../perf.js';
+import { topTransactionsCmd } from './transactions.js';
 import { paginatedSearch } from '../paginated-search.js';
+import { canUsePicker } from '../helpers.js';
 
-function pickerEnabled(app) {
-  return Boolean(process.stdin.isTTY && process.stdout.isTTY && app.output?.effectiveFormat?.() !== 'json' && app.output?.effectiveFormat?.() !== 'quiet');
+/**
+ * A picker is only safe when a human is reachable AND the invocation did
+ * not ask for machine output (`--json`/`--quiet`) or a one-shot extraction
+ * (`--get`). canUsePicker() owns that rule so CI/agent markers and
+ * JSN_NO_PROMPTS are honored too.
+ */
+function pickerEnabled(app, argv = {}) {
+  return canUsePicker(app, argv);
 }
 
-async function pickRun(app, { exclude = new Set(), message = 'Select a performance capture' } = {}) {
+async function pickRun(app, { exclude = new Set(), message = 'Select a performance capture', argv = {} } = {}) {
   const runs = listRuns({ limit: 1000 }).filter(run => !exclude.has(run.run_id));
-  if (!pickerEnabled(app) || runs.length === 0) return null;
+  if (!pickerEnabled(app, argv) || runs.length === 0) return null;
   const selected = await paginatedSearch({
     message,
     totalCount: runs.length,
@@ -77,7 +85,7 @@ export function perfCmd(wrap) {
         builder: (b) => b.option('limit', { alias: 'l', type: 'number', default: 50, describe: 'Maximum runs to show' }),
         handler: wrap(async (argv, app) => {
           const runs = listRuns({ limit: argv.limit });
-          const picked = await pickRun(app, { message: 'Select a performance capture' });
+          const picked = await pickRun(app, { message: 'Select a performance capture', argv });
           if (picked) {
             const run = getRun(picked.run_id);
             app.ok({ ...run, _formatted: formatRunDetailed(run) }, {
@@ -99,22 +107,41 @@ export function perfCmd(wrap) {
         command: 'show [run_id]',
         describe: 'Show one saved performance capture',
         handler: wrap(async (argv, app) => {
-          const run = argv.run_id ? requireRun(argv.run_id, 'target') : await pickRun(app);
-          if (!run) return;
+          // No run ID and no human to pick one: fail with a usable error
+          // instead of exiting 0 with no output at all.
+          if (!argv.run_id && !pickerEnabled(app, argv)) {
+            throw errUsageHint(
+              'Missing run ID: `jsn perf show` needs a run ID when prompts are unavailable.',
+              'Find a capture with `jsn perf list`, then run `jsn perf show <run_id>`.'
+            );
+          }
+          const run = argv.run_id ? requireRun(argv.run_id, 'target') : await pickRun(app, { argv });
+          if (!run) return; // cancelled at the picker
           app.ok({ ...run, _formatted: formatRunDetailed(run) }, {
             summary: `Performance capture ${run.run_id}`,
             breadcrumbs: [listHint(), compareHint(run.run_id)],
           });
         }),
       })
+      .command({
+        command: 'transactions [subcommand]',
+        describe: 'Inspect Client Transaction Timings',
+        builder: (b) => b.command(topTransactionsCmd(wrap)),
+      })
       .command({
         command: 'compare [baseline] [new]',
         describe: 'Compare exactly two saved captures',
         handler: wrap(async (argv, app) => {
           if (!argv.baseline && !argv.new) {
-            const baseline = await pickRun(app, { message: 'Select the baseline capture' });
+            if (!pickerEnabled(app, argv)) {
+              throw errUsageHint(
+                'Compare requires exactly two run IDs when prompts are unavailable.',
+                'Run `jsn perf compare <baseline> <new>` with two run IDs from `jsn perf list`.'
+              );
+            }
+            const baseline = await pickRun(app, { message: 'Select the baseline capture', argv });
             if (!baseline) return;
-            const newer = await pickRun(app, { exclude: new Set([baseline.run_id]), message: 'Select the new capture' });
+            const newer = await pickRun(app, { exclude: new Set([baseline.run_id]), message: 'Select the new capture', argv });
             if (!newer) return;
             const baselineRun = getRun(baseline.run_id);
             const newerRun = getRun(newer.run_id);

package/src/commands/platform.js

@@ -1,3 +1,6 @@
+import { declareCapabilities } from '../capabilities.js';
+import { formatCommandList } from '../helpers.js';
+
 function numberOrString(value) {
   const n = Number(value);
   return value !== '' && Number.isFinite(n) ? n : value;
@@ -24,6 +27,179 @@ function statsForWindow(xml, parent, window) {
   return tagAttributes(parentMatch[1], window);
 }
 
+export const XMLSTATS_MAX_BYTES = 4 * 1024 * 1024;
+
+function metric(value) {
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return { value: null, availability: 'unavailable' };
+  }
+  return { value: numberOrString(String(value).trim()), availability: 'available' };
+}
+
+function firstNestedText(xml, parent, child) {
+  const parentMatch = xml.match(new RegExp(`<${parent}\\b[^>]*>([\\s\\S]*?)</${parent}>`));
+  return parentMatch ? tagText(parentMatch[1], child) : undefined;
+}
+
+function allowlistedStats(xml) {
+  const unavailable = [];
+  const add = (path, value) => {
+    const result = metric(value);
+    if (result.availability === 'unavailable') unavailable.push(path);
+    return result;
+  };
+
+  const cluster = xml.match(/<cluster\.status\b[^>]*>([\s\S]*?)<\/cluster\.status>/);
+  const nodeXml = cluster?.[1]?.match(/<node\b[^>]*>([\s\S]*?)<\/node>/)?.[1] || '';
+  const daily = statsForWindow(xml, 'all_transactions', 'daily') || {};
+  const semaphores = [];
+  for (const match of xml.matchAll(/<semaphores([^>]*)\/>/g)) {
+    const attrs = {};
+    for (const [, key, value] of match[1].matchAll(/([\w.-]+)="([^"]*)"/g)) attrs[key] = value;
+    if (!attrs.name && !attrs.available && !attrs.borrowed && !attrs.maximum_concurrency && !attrs.queue_depth) continue;
+    semaphores.push({
+      name: attrs.name || 'unnamed',
+      available: add(`semaphores[${attrs.name || 'unnamed'}].available`, attrs.available),
+      borrowed: add(`semaphores[${attrs.name || 'unnamed'}].borrowed`, attrs.borrowed),
+      maximum: add(`semaphores[${attrs.name || 'unnamed'}].maximum`, attrs.maximum_concurrency),
+      queue_depth: add(`semaphores[${attrs.name || 'unnamed'}].queue_depth`, attrs.queue_depth),
+    });
+  }
+  if (semaphores.length === 0) unavailable.push('semaphores');
+
+  return {
+    node: {
+      status: add('node.status', tagText(nodeXml, 'status')),
+      type: add('node.type', firstNestedText(nodeXml, 'node_type', 'name')),
+    },
+    queue: {
+      length: add('queue.length', tagText(xml, 'queue.length')),
+      age: add('queue.age', tagText(xml, 'queue.age')),
+    },
+    active_sessions: add('active_sessions', tagText(xml, 'servlet.active.sessions')),
+    memory_pressure: add('memory_pressure', tagText(xml, 'memory_pressure')),
+    semaphores,
+    transactions: {
+      daily: {
+        count: add('transactions.daily.count', daily.count),
+        mean: add('transactions.daily.mean', daily.mean),
+        median: add('transactions.daily.median', daily.median),
+        ninetypercent: add('transactions.daily.ninetypercent', daily.ninetypercent),
+        max: add('transactions.daily.max', daily.max),
+      },
+    },
+    unavailable,
+  };
+}
+
+export function parsePlatformStatsXml(xml) {
+  const source = String(xml || '');
+  if (Buffer.byteLength(source) > XMLSTATS_MAX_BYTES) throw new Error('xmlstats response exceeds the bounded size limit');
+  if (!/^\s*(?:<\?xml[\s\S]*?\?>\s*)?<xmlstats\b[^>]*>/i.test(source)
+    || !/<\/xmlstats>\s*$/i.test(source)) {
+    throw new Error('Malformed XML: expected an xmlstats document');
+  }
+  const stack = [];
+  for (const match of source.matchAll(/<\/?([A-Za-z][\w.:-]*)(?:\s[^>]*)?>/g)) {
+    const token = match[0];
+    const name = match[1];
+    if (/^<\//.test(token)) {
+      if (stack.pop() !== name) throw new Error('Malformed XML: mismatched tags');
+    } else if (!/\/\s*>$/.test(token)) {
+      stack.push(name);
+    }
+  }
+  if (stack.length !== 0) throw new Error('Malformed XML: unclosed tags');
+  return allowlistedStats(source);
+}
+
+async function readBoundedResponse(response, maxBytes = XMLSTATS_MAX_BYTES) {
+  if (!response.body?.getReader) {
+    const text = await response.text();
+    return Buffer.byteLength(text) > maxBytes ? { tooLarge: true, bytes: Buffer.byteLength(text) } : { text, bytes: Buffer.byteLength(text) };
+  }
+  const reader = response.body.getReader();
+  const chunks = [];
+  let bytes = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    bytes += value.byteLength;
+    if (bytes > maxBytes) {
+      await reader.cancel();
+      return { tooLarge: true, bytes };
+    }
+    chunks.push(value);
+  }
+  const body = new Uint8Array(bytes);
+  let offset = 0;
+  for (const chunk of chunks) {
+    body.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return { text: new TextDecoder().decode(body), bytes };
+}
+
+function looksLikeLoginHtml(response, body) {
+  const contentType = response.headers?.get?.('content-type') || '';
+  return /text\/html/i.test(contentType) || /^\s*<(?:!doctype\s+html|html\b)/i.test(body);
+}
+
+export async function collectPlatformStats(sdk, instance) {
+  let response;
+  try {
+    response = await sdk.fetchResponse(`${instance}/xmlstats.do`, {
+      method: 'GET',
+      headers: { Accept: 'application/xml,text/xml' },
+    });
+  } catch (error) {
+    const message = String(error?.message || '').toLowerCase();
+    return { status: /timeout|timed out/.test(message) ? 'timeout' : 'unavailable', reason: /timeout|timed out/.test(message) ? 'request timed out' : 'request failed' };
+  }
+
+  if (response.status === 401 || response.status === 403) return { status: 'permission_denied', reason: `HTTP ${response.status}` };
+  if (response.status === 404 || response.status === 405) return { status: 'unsupported', reason: `HTTP ${response.status}` };
+  if (!response.ok) return { status: 'unavailable', reason: `HTTP ${response.status}` };
+
+  const body = await readBoundedResponse(response);
+  if (body.tooLarge) return { status: 'too_large', reason: `response exceeded ${XMLSTATS_MAX_BYTES} bytes`, bytes: body.bytes };
+  if (looksLikeLoginHtml(response, body.text)) return { status: 'login_redirect', reason: 'received HTML instead of xmlstats XML', bytes: body.bytes };
+
+  try {
+    const metrics = parsePlatformStatsXml(body.text);
+    const status = metrics.unavailable.length > 0 ? 'partial' : 'success';
+    return {
+      status,
+      reason: status === 'partial' ? 'some allowlisted metrics were unavailable' : null,
+      bytes: body.bytes,
+      metrics,
+    };
+  } catch {
+    return { status: 'malformed_xml', reason: 'response was not a valid xmlstats document', bytes: body.bytes };
+  }
+}
+
+function metricText(item) {
+  return item?.availability === 'available' ? String(item.value) : 'unavailable';
+}
+
+export function formatPlatformStats(result) {
+  const lines = [`STATUS: ${result.status}`];
+  if (result.reason) lines.push(`REASON: ${result.reason}`);
+  const m = result.metrics;
+  if (!m) return `${lines.join('\\n')}\\n`;
+  lines.push(`NODE: ${metricText(m.node.status)} / ${metricText(m.node.type)}`);
+  lines.push(`QUEUE: ${metricText(m.queue.length)} length, ${metricText(m.queue.age)} age`);
+  lines.push(`SESSIONS: ${metricText(m.active_sessions)}`);
+  lines.push(`MEMORY PRESSURE: ${metricText(m.memory_pressure)}`);
+  lines.push(`TRANSACTIONS DAILY: ${metricText(m.transactions.daily.count)} count, ${metricText(m.transactions.daily.mean)} mean, ${metricText(m.transactions.daily.ninetypercent)} p90, ${metricText(m.transactions.daily.max)} max`);
+  if (m.semaphores.length === 0) lines.push('SEMAPHORES: unavailable');
+  else for (const semaphore of m.semaphores) {
+    lines.push(`SEMAPHORE ${semaphore.name}: ${metricText(semaphore.available)} available, ${metricText(semaphore.borrowed)} borrowed, ${metricText(semaphore.maximum)} maximum, ${metricText(semaphore.queue_depth)} queue`);
+  }
+  return `${lines.join('\\n')}\\n`;
+}
+
 export function parseNodeStatsXml(xml) {
   const source = String(xml || '');
   const result = {};
@@ -91,9 +267,26 @@ function formatHealth(nodes) {
 }
 
 export function platformCmd(wrap) {
+  declareCapabilities('platform', { mutationSubcommands: [] });
   return {
     command: 'platform',
     describe: 'Inspect read-only platform health and node statistics',
+    // Parent discovery. This parent had no handler, so `jsn platform` and
+    // `jsn platform --json` exited 0 with no output at all — silent success.
+    // Children come from the registry, not a second hand-written list.
+    handler: wrap(async (argv, app) => {
+      const subcommands = argv.subcommands || [];
+      const summary = 'Inspect read-only platform health and node statistics.';
+      app.ok({
+        command: 'platform',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn platform <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
     builder: (y) => y.command({
       command: 'health',
       describe: 'Show cluster, queue, semaphore, and node health',
@@ -122,6 +315,15 @@ export function platformCmd(wrap) {
         }
         app.ok({ table: 'sys_cluster_state', node_count: nodes.length, nodes, _formatted: formatHealth(nodes), security: { raw_xml: 'excluded', sensitive_fields: 'excluded' }, context: { instance_url: app.getEffectiveInstance() } }, { summary: `Platform health: ${nodes.length} node(s)` });
       }),
+    }).command({
+      command: 'stats',
+      describe: 'Show bounded, read-only platform statistics from xmlstats.do',
+      handler: wrap(async (argv, app) => {
+        app.requireInstance();
+        const result = await collectPlatformStats(app.sdk, app.getEffectiveInstance());
+        result._formatted = formatPlatformStats(result);
+        app.ok(result, { summary: `Platform stats: ${result.status}` });
+      }),
     }),
   };
 }

package/src/commands/records.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
+import { formatCommandList, formatRecordForDisplay, buildQuerySuffix, parseDataArg, getStringField, interactiveList, resolveFieldsParam, checkDerivedFields, confirmDelete, assertSafeExactMatch, verifyWriteBack } from '../helpers.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('records', {
@@ -514,20 +514,24 @@ export function recordsCmd(wrap) {
         })
 
     },
-    handler: (argv) => {
+    // Parent discovery through the output controller: the subcommand list is
+    // registry-derived (argv.subcommands), so `jsn records --json` returns a
+    // structured envelope instead of prose, and the descriptions can no longer
+    // describe a different surface than the registrations (the previous
+    // hand-written list advertised `inspect` as table schema/statistics).
+    handler: wrap(async (argv, app) => {
       if (argv._[1]) return; // a subcommand ran — its own handler handled it
-      console.log('Query and manage records in any ServiceNow table.');
-      console.log('');
-      console.log('Available subcommands:');
-      console.log('  list                  List records from a table (includes total by default)');
-      console.log('  get                   Get a single record by sys_id (--attachments to include files)');
-      console.log('  create                Create a record');
-      console.log('  update                Update a record');
-      console.log('  delete                Delete a record');
-      console.log('  aggregate              Run Stats API aggregation with optional grouping');
-      console.log('  inspect                Inspect table schema and statistics');
-      console.log('');
-      console.log('Run "jsn records <command> --help" for details.');
-    },
+      const subcommands = argv.subcommands || [];
+      const summary = 'Query and manage records in any ServiceNow table.';
+      app.ok({
+        command: 'records',
+        subcommands,
+        _formatted: formatCommandList({
+          title: summary,
+          commands: subcommands,
+          footer: 'Run "jsn records <command> --help" for details.',
+        }),
+      }, { summary });
+    }),
   };
 }

package/src/commands/skill.js

@@ -8,6 +8,7 @@ import { execSync } from 'node:child_process';
 
 import { globalConfigPath } from '../config.js';
 import { declareCapabilities } from '../capabilities.js';
+import { canUsePicker } from '../helpers.js';
 
 declareCapabilities('skill', { noInstance: true, skipDailyChecks: true });
 
@@ -305,8 +306,10 @@ export function skillCmd(wrap) {
                   }
                 }
               }
-            } else if (process.stdin.isTTY) {
-              // Interactive: show multi-select picker
+            } else if (canUsePicker(app, argv)) {
+              // Interactive: show multi-select picker. canUsePicker() (not a
+              // bare stdin TTY check) keeps a PTY allocated for an agent,
+              // CI, JSN_NO_PROMPTS, --json/--quiet or --get out of a prompt.
               const fetchedVersion = extractVersion(content);
               // Check if any existing installed copies are outdated
               const outdated = [];

package/src/commands/transactions.js

@@ -39,6 +39,7 @@ export function classifyTransactionType(type, url = '') {
 }
 
 function numericValue(value) {
+  if (value == null || String(value).trim() === '') return null;
   const n = Number(String(value ?? '').replaceAll(',', ''));
   return Number.isFinite(n) ? n : null;
 }
@@ -65,6 +66,83 @@ function summarizeGroup(group) {
   };
 }
 
+function topQuery(argv = {}) {
+  const parts = [];
+  if (argv.query) parts.push(String(argv.query));
+  for (const field of ['type', 'table', 'view']) if (argv[field]) parts.push(`${field}=${argv[field]}`);
+  if (argv.window != null && String(argv.window) !== '') {
+    const days = Math.max(1, Math.min(30, Number(argv.window) || 1));
+    parts.push(`sys_created_on>=javascript:gs.daysAgoStart(${days})`);
+  }
+  if (argv.since) parts.push(`sys_created_on>=${argv.since}`);
+  if (argv.until) parts.push(`sys_created_on<=${argv.until}`);
+  return normalizeTransactionQuery(parts.join('^'));
+}
+
+function topGroup(group) {
+  const stats = group?.stats || {};
+  return {
+    type: groupValue(group, 'type') || 'unavailable',
+    table: groupValue(group, 'table') || 'unavailable',
+    view: groupValue(group, 'view') || 'unavailable',
+    count: numericValue(stats.count) ?? 0,
+    avg_response_time_ms: metricValue(stats, 'avg', 'response_time'),
+    min_response_time_ms: metricValue(stats, 'min', 'response_time'),
+    max_response_time_ms: metricValue(stats, 'max', 'response_time'),
+  };
+}
+
+function formatTopTransactions(groups) {
+  const value = metric => metric == null ? 'unavailable' : `${Math.round(metric * 100) / 100} ms`;
+  const lines = [
+    'TYPE         TABLE              VIEW             COUNT  AVG          MIN          MAX',
+    '-----------  -----------------  ---------------  -----  -----------  -----------  -----------',
+  ];
+  for (const row of groups) lines.push(`${String(row.type).slice(0, 11).padEnd(11)}  ${String(row.table).slice(0, 17).padEnd(17)}  ${String(row.view).slice(0, 15).padEnd(15)}  ${String(row.count).padStart(5)}  ${value(row.avg_response_time_ms).padEnd(11)}  ${value(row.min_response_time_ms).padEnd(11)}  ${value(row.max_response_time_ms)}`);
+  if (groups.length === 0) lines.push('(no transaction groups)');
+  return `${lines.join('\\n')}\\n`;
+}
+
+export function topTransactionsCmd(wrap) {
+  return {
+    command: 'top',
+    describe: 'Rank Client Transaction Timings by type, table, and view',
+    builder: (y) => y
+      .option('type', { type: 'string', describe: 'Filter transaction type' })
+      .option('table', { type: 'string', describe: 'Filter transaction table' })
+      .option('view', { type: 'string', describe: 'Filter transaction view' })
+      .option('query', { type: 'string', describe: 'Additional encoded query' })
+      .option('window', { type: 'number', default: 1, describe: 'Look back this many days (max 30)' })
+      .option('since', { type: 'string', describe: 'Only records on or after this timestamp' })
+      .option('until', { type: 'string', describe: 'Only records on or before this timestamp' })
+      .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Maximum groups to return' }),
+    handler: wrap(async (argv, app) => {
+      app.requireInstance();
+      const query = topQuery(argv);
+      const limit = Math.max(1, Math.min(100, Number(argv.limit) || 20));
+      const result = await app.sdk.aggregate('syslog_transaction', {
+        query,
+        groupBy: ['type', 'table', 'view'],
+        count: true,
+        averageFields: ['response_time'],
+        minimumFields: ['response_time'],
+        maximumFields: ['response_time'],
+        orderBy: 'countDESC',
+      });
+      const groups = (Array.isArray(result.groups) ? result.groups : []).map(topGroup).slice(0, limit);
+      app.ok({
+        table: 'syslog_transaction',
+        query,
+        group_by: ['type', 'table', 'view'],
+        response_time_unit: 'ms',
+        groups,
+        _formatted: formatTopTransactions(groups),
+        context: { instance_url: app.getEffectiveInstance() },
+      }, { summary: `Top transaction groups: ${groups.length}` });
+    }),
+  };
+}
+
 export function transactionsCmd(wrap) {
   return {
     command: 'transactions',

package/src/commands/updatesets.js

@@ -1,7 +1,10 @@
 import fs from 'node:fs';
-import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch } from '../helpers.js';
+import { editor, confirm } from '@inquirer/prompts';
+import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack } from '../helpers.js';
+import { getActiveProfile } from '../config.js';
+import { FormatAuto } from '../output.js';
 import { getCurrentApplication, getCurrentUpdateSet, requireCurrentUserSysId, setCurrentApplication, setCurrentUpdateSet } from '../context.js';
-import { errAPI, errUsage } from '../errors.js';
+import { errAPI, errUsage, errConfirmationRequired } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('updatesets', {
@@ -133,6 +136,28 @@ async function fetchUpdateSetById(app, sysID) {
   return Array.isArray(records) && records.length > 0 ? records[0] : null;
 }
 
+/** Completion refuses duplicate names rather than guessing a mutation target. */
+async function resolveCompletionTarget(app, name) {
+  if (name !== undefined) {
+    if (!String(name).trim()) throw errUsage('Update set name must not be empty');
+    assertSafeExactMatch(name);
+    const params = new URLSearchParams({
+      sysparm_query: `name=${name}`, sysparm_limit: '2',
+      sysparm_display_value: 'all', sysparm_fields: 'sys_id,name',
+    });
+    const records = await app.sdk.list('sys_update_set', params);
+    if (!records.length) throw errUsage(`Update set not found: ${name}`);
+    if (records.length !== 1) {
+      throw errUsage(`Multiple update sets named "${name}". Select the intended set with "jsn updatesets set", then run "jsn updatesets complete" without a name.`);
+    }
+    return { sys_id: rawReferenceId(records[0].sys_id), name: getStringField(records[0], 'name') };
+  }
+  const userSysID = await requireCurrentUserSysId(app.sdk);
+  const current = await getCurrentUpdateSet(app.sdk, userSysID);
+  if (!current?.sys_id) throw errUsage('No current update set. Set one first:\n  jsn updatesets set');
+  return current;
+}
+
 /** Build a safe, flat preorder hierarchy with ancestors before the selected set. */
 export async function buildUpdateSetHierarchy(app, selectedRecord) {
   const selectedID = getStringField(selectedRecord, 'sys_id');
@@ -631,16 +656,57 @@ export function updateSetsCmd(wrap) {
           }),
         })
         .command({
-          command: 'complete',
-          describe: 'Mark the current update set as complete',
+          command: 'complete [name]',
+          describe: 'Complete a named or current update set with completion notes',
+          builder: (y) => y
+            .positional('name', { type: 'string', describe: 'Unique update set name, defaults to the current set' })
+            .option('notes', { type: 'string', describe: 'Completion notes, one bullet per line; opens an editor when omitted interactively' }),
           handler: wrap(async (argv, app) => {
-            const userSysID = await requireCurrentUserSysId(app.sdk);
-            const current = await getCurrentUpdateSet(app.sdk, userSysID);
-            if (!current?.sys_id) {
-              throw errUsage('No current update set. Set one first:\n  jsn updatesets set');
+            const current = await resolveCompletionTarget(app, argv.name);
+            const record = await fetchUpdateSetById(app, current.sys_id);
+            if (!record) throw errUsage(`Update set not found or unreadable: ${current.sys_id}`);
+            if (!Object.hasOwn(record, 'description')
+              || (record.description && typeof record.description === 'object' && !Object.hasOwn(record.description, 'value'))) {
+              throw errUsage(`Description is unreadable for update set "${current.name}" (${current.sys_id}); refusing to replace unknown text.`);
+            }
+            const existing = String(record.description && typeof record.description === 'object'
+              ? record.description.value ?? '' : record.description ?? '');
+            const interactive = !argv.json && !argv.get && (!argv.format || argv.format === FormatAuto)
+              && app.output?.getFormat() === FormatAuto && canPrompt();
+            let notes = argv.notes;
+            let description;
+            try {
+              if (notes === undefined) {
+                if (!interactive) throw errUsage('Provide nonempty completion notes with --notes in noninteractive mode');
+                notes = await editor({ message: `Completion notes for "${current.name}". Write concise bullets, one per line` });
+              }
+              const bullets = String(notes).split(/\r?\n/)
+                .map(line => line.trim().replace(/^[-*•]\s*/, '').trim()).filter(Boolean)
+                .map(line => `- ${line}`).join('\n');
+              if (!bullets) throw errUsage('Provide nonempty completion notes with --notes');
+              description = existing ? `${existing}\n\n${bullets}` : bullets;
+              if (existing && !argv.force && getActiveProfile(app.config)?.skip_confirmations !== true) {
+                const question = `Append notes and complete "${current.name}"?\nExisting Description:\n${existing}\n\nNew notes:\n${bullets}`;
+                if (!interactive) throw errConfirmationRequired(question, buildRerunCommand(argv, {
+                  rerun: ['updatesets', 'complete', ...(argv.name !== undefined ? [argv.name] : []), '--notes', String(notes)],
+                }));
+                if (!await confirm({ message: question, default: false })) return;
+              }
+            } catch (error) {
+              if (['ExitPromptError', 'AbortPromptError'].includes(error.name)) return;
+              throw error;
+            }
+            const data = { state: 'complete', description };
+            try {
+              await app.sdk.update('sys_update_set', current.sys_id, data);
+            } catch (error) {
+              throw errAPI(error.status || 0, `Could not complete update set "${current.name}" (${current.sys_id}): ${error.message}. Check the record before retrying.`);
+            }
+            const mismatches = await verifyWriteBack(app, 'sys_update_set', current.sys_id, data);
+            if (mismatches.length) {
+              throw errAPI(200, `Could not verify completion of update set "${current.name}" (${current.sys_id}): ${mismatches.map(item => item.field).join(', ')} did not persist or could not be read. The write may have partially succeeded; inspect the set before retrying.`);
             }
-            await app.sdk.update('sys_update_set', current.sys_id, { state: 'complete' });
-            app.ok({ update_set: current.name, state: 'complete' }, { summary: `Update set marked complete: ${current.name}` });
+            app.ok({ update_set: current.name, sys_id: current.sys_id, state: 'complete', description }, { summary: `Update set marked complete: ${current.name}` });
           }),
         })
         .command({
@@ -667,7 +733,7 @@ export function updateSetsCmd(wrap) {
         console.log('  export <name>  Export an update set to XML (stdout or --out)');
         console.log('  set  [name]    Set the current update set (picker when run bare)');
         console.log('  create         Create a new update set (auto-sets as current)');
-        console.log('  complete       Mark the current update set as complete');
+        console.log('  complete [name] Complete a named or current set with --notes (editor when omitted)');
         console.log('  ignore         Ignore the current update set');
         console.log('  parent <name>  Set the parent of an update set');
         console.log('\nRun "jsn updatesets <command> --help" for details.');