@jacebenson/jsn 4.3.13-dev.99.1 → 4.4.0

package/README.md

@@ -23,8 +23,12 @@ npm install -g @jacebenson/jsn@dev
 
 Dev builds check the dev channel for updates during normal use, at most once
 per day. Run `jsn version --check` to check immediately. To install the newest
-dev build, run `npm install -g @jacebenson/jsn@dev` again. Updates are manual.
-Return to stable with `npm install -g @jacebenson/jsn@latest`.
+dev build, run `jsn upgrade` (alias: `jsn update`). It preserves your installed
+channel and skips installation when no newer version is available. Use
+`--dry-run` to print the npm command without network access or installation,
+`--force` to reinstall, or `--channel dev|latest` to switch channels explicitly.
+For example, `jsn upgrade --channel latest` returns to stable. npm installation
+permissions still apply; the command does not elevate privileges automatically.
 
 Pushes to `main` promote the commit to `dev` and publish a tested prerelease
 under npm's `dev` tag. Versions include the workflow run number and attempt
@@ -32,6 +36,66 @@ under npm's `dev` tag. Versions include the workflow run number and attempt
 The npm trusted publisher for `publish-dev.yml` must authorize the repository's
 `dev` GitHub environment, alongside the production publishing configuration.
 
+### Knowledge search
+
+Use `jsn knowledge search "VPN setup" --profile work` (alias `kb`) to search
+accessible articles, then `jsn knowledge show KB0000010 --profile work` to read
+one. Search supports bounded `--limit`/`--offset`, knowledge-base sys_ids with
+`--kb`, and `--language`. JSON preserves native HTML; human output uses Markdown.
+Hints preserve an explicitly selected profile/instance. The Knowledge API plugin
+(`sn_km_api`) must be available; access is evaluated by that API, with no fallback
+to direct table reads. Reads do not request view-count updates. See the
+[Knowledge API reference](https://www.servicenow.com/docs/r/yokohama/api-reference/rest-apis/knowledge-api.html).
+
+### Instance Scan
+
+`jsn scan` manages checks and suites and runs scans against an explicit target.
+Use `jsn scan --help` and each subcommand's `--help` to discover the options.
+
+```bash
+jsn scan checks list --profile dev
+jsn scan checks create --type table --data-file check.json --profile dev
+jsn scan checks activate <check-id> --profile dev
+jsn scan suites add-check <suite-id> --check <check-id> --profile dev
+jsn scan run --update-set "My change" --suite "My suite" --wait --profile dev
+jsn scan run --table sys_script_include --record <record-id> --profile dev
+jsn scan results <execution-id> --profile dev
+```
+
+Check types are `table`, `column`, `linter`, and `script`. Definitions are created
+inactive unless the payload explicitly sets `active: true`; activation never
+starts a scan. Both checks and suites support list/show/create/update/delete and
+activate/deactivate. Suites also support add-check/remove-check.
+
+Runs require an update set, scope, record plus table, or explicit `--full`.
+Instance-wide scans may traverse many tables even when a check's script only
+examines a few records. Starting and cancelling a scan require confirmation;
+use `--force` only after approving that operation. `--wait --timeout 120` bounds
+the wait, not the scan's lifetime. A timed-out wait keeps the execution id and
+does not cancel or resubmit the scan. Use `status`, `results`, or `cancel` next.
+
+Update-set scans examine current instance records, not the historical XML
+versions. Inactive records may be skipped. Script-only checks do not participate
+in record/update-set scans; use an explicitly instance-wide suite run to execute
+them. Execution success does not mean zero findings or complete test coverage:
+results report recorded check executions, finding counts, unreadable sources,
+and truncated lists separately. A result's rerun hint preserves the previous
+target combination and requires `--full` again for instance-wide scans.
+
+Every command returns next-step breadcrumbs in human and JSON output, retaining
+an explicitly selected profile or instance. `updatesets show` also offers a scan
+hint. Recommendation/generation of new checks is not part of this command;
+JSN contains no AI and does not infer missing business requirements.
+
+### CMDB search
+
+`jsn cmdb search "web" --profile work` searches names, FQDNs, IP addresses and
+serial numbers on `cmdb_ci`. Use `--class cmdb_ci_server` for an exact class
+match (excluding subclasses), and bounded `--limit`/`--offset` pagination.
+Search text is literal; encoded-query operators and query scripts are rejected.
+Existing `cmdb list --query` remains available for deliberate encoded queries.
+Results include show/relationship hints and preserve the selected connection.
+
 ### Supported versions
 
 Only the current release and the two preceding releases in each channel are
@@ -39,20 +103,15 @@ supported (three stable releases and three dev builds). For example, with
 stable `4.3.11`, versions `4.3.11`, `4.3.10`, and `4.3.9` are supported.
 Update to the newest version in your channel before reporting an issue.
 
-After each successful npm publish, deployment deprecates older versions in that
-channel. Deprecated versions remain installable and appear in history, but npm
-prints an update warning on installation. Existing deprecation messages are
-preserved. No versions are unpublished.
-
-The deprecation step uses the repository's `NPM_TOKEN` secret with permission to
-modify `@jacebenson/jsn` and noninteractive authentication (including bypass 2FA
-where required). Publishing continues to use OIDC. A deprecation failure fails
-the workflow after publishing; it does not roll back the published package.
-To retry only deprecation after fixing authentication, use the matching release
-checkout and run `node scripts/deprecate-old-versions.mjs latest --apply` (or
-`dev --apply`) with npm authentication configured and `NODE_AUTH_TOKEN` set.
-Omit `--apply` to preview the affected versions without changing npm. The script
-requires the checkout's package version to match the channel's current npm tag.
+Publishing uses npm trusted publishing (OIDC) and advances the channel's dist-tag.
+CI/CD does not deprecate older versions or require an `NPM_TOKEN` secret. Older
+versions remain available; their availability does not extend the support window.
+
+The optional maintenance script `scripts/deprecate-old-versions.mjs` can preview
+older versions with `node scripts/deprecate-old-versions.mjs latest` (or `dev`).
+Applying deprecations with `--apply` requires npm authentication and
+`NODE_AUTH_TOKEN`; it is separate from publishing. The script requires the
+checkout's package version to match the channel's current npm tag.
 
 ## Try it
 
@@ -92,3 +151,26 @@ This applies to root help, root JSON, `discover`, and root shell completion.
 Use `jsn --all-commands --help` or `jsn discover --all-commands --json` to inspect
 every registered command. Explicit command paths remain available and ServiceNow
 ACLs decide access. Reauthenticate (or refresh OAuth) after roles change.
+
+### Ordering catalog items
+
+Use `jsn catalogitems search "laptop" --profile work`, then
+`jsn catalogitems describe <item-sys-id> --profile work` to inspect pricing and
+variable definitions through the native Service Catalog API. Create a JSON file
+mapping variable names to values, then preview with
+`jsn catalogitems order <item-sys-id> --variables-file variables.json --dry-run --profile work`.
+Omit `--dry-run` to submit after confirmation. `--quantity` defaults to one;
+`--requested-for` accepts a user sys_id subject to instance delegation rules.
+
+Orders use `order_now`, preserving catalog fulfillment rather than inserting an
+RITM directly. The command handles standard catalog items; record producers and
+order guides require separate workflows. Server rules validate mandatory and
+dynamic variables at submission; a preview does not validate those rules. Preview
+output lists variable names, not entered values. This operation requires a
+write-enabled profile (also for previews), but no development update set.
+Confirmation follows the existing profile policy; automation can supply `--force`
+only for an approved order. Timeout or incomplete response is an uncertain
+outcome: inspect requests before retrying. JSN does not automatically submit a
+second order. `create/list/show` retain their definition-management behavior.
+
+See the [Service Catalog API reference](https://www.servicenow.com/docs/r/api-reference/rest-apis/c_ServiceCatalogAPI.html).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.13-dev.99.1",
+  "version": "4.4.0",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {
@@ -28,8 +28,8 @@
     "node": ">=22.5.0"
   },
   "dependencies": {
-    "@inquirer/core": "^10.1.0",
-    "@inquirer/prompts": "^7.5.1",
+    "@inquirer/core": "^10.3.2",
+    "@inquirer/prompts": "^7.10.1",
     "better-sqlite3": "^13.0.3",
     "js-yaml": "^5.5.0",
     "saxes": "^6.0.0",

package/skills/servicenow/SKILL.md

@@ -24,7 +24,7 @@ For development:
 1. Choose or create the application scope and update set.
 2. Do the work, keeping related changes together.
 3. Verify the results on the instance and report where changes were captured.
-4. Offer to create ATFs and instance scans to verify the outcomes.
+4. Offer to run relevant existing ATFs and instance scans, or create missing checks.
 5. Ask whether anything else belongs in the update set. If the user confirms
    it is finished, complete it with notes.
 

package/src/auth-recovery.js

@@ -67,7 +67,7 @@ export function createAuthRecovery({ app, session, argv = () => app._authArgv ||
       && canInteract(app, argv())) {
       try {
         if ((profile?.reauth ?? 'confirm') === 'confirm'
-          && !await prompt({ message: `Sign in again in a browser for ${label}?`, default: false })) throw provider.error;
+          && !await prompt({ message: `Sign in again in a browser for ${label}?`, default: true })) throw provider.error;
         // Reuse the canonical GCK refresh/login operation without emitting a
         // second success envelope or replacing the in-flight command's SDK.
         const targetApp = Object.create(app);

package/src/cli.js

@@ -22,6 +22,7 @@ import { authCmd } from './commands/auth.js';
 import { recordsCmd } from './commands/records.js';
 import { attachmentsCmd } from './commands/attachments.js';
 import { cmdbCmd } from './commands/cmdb.js';
+import { knowledgeCmd } from './commands/knowledge.js';
 import { snippetsCmd } from './commands/snippets.js';
 import { catalogCmd } from './commands/catalog.js';
 import { incidentsCmd } from './commands/incidents.js';
@@ -38,6 +39,7 @@ import { transactionsCmd } from './commands/transactions.js';
 import { platformCmd } from './commands/platform.js';
 import { codesearchCmd } from './commands/codesearch.js';
 import { versionCmd } from './commands/version.js';
+import { upgradeCmd } from './commands/upgrade.js';
 import { skillCmd, checkSkill } from './commands/skill.js';
 import { getVersion, checkLatest, getReleaseChannel, getInstallCommand } from './commands/version.js';
 import { docsCmd } from './commands/docs/docs.js';
@@ -72,6 +74,7 @@ import { logsCmd } from './commands/logs.js';
 import { scrapiCmd } from './commands/scrapi.js';
 import { b4rulesCmd } from './commands/b4rules.js';
 import { atfCmd } from './commands/atf.js';
+import { scanCmd } from './commands/scan.js';
 import { approvalsCmd } from './commands/approvals.js';
 import { historyCmd } from './commands/history.js';
 import { perfCmd } from './commands/perf.js';
@@ -411,6 +414,7 @@ export function buildCLI() {
     .command(propertiesCmd(wrap))
     // DATA
     .command(cmdbCmd(wrap))
+    .command(knowledgeCmd(wrap))
     .command(recordsCmd(wrap))
     .command(attachmentsCmd(wrap))
     .command(transactionsCmd(wrap))
@@ -421,6 +425,7 @@ export function buildCLI() {
     .command(codesearchCmd(wrap))
     // DEVELOPER
     .command(atfCmd(wrap))
+    .command(scanCmd(wrap))
     .command(approvalsCmd(wrap))
     .command(skippedUpdatesCmd(wrap))
     .command(perfCmd(wrap))
@@ -434,6 +439,7 @@ export function buildCLI() {
     .command(skillCmd(wrap))
     .command(docsCmd(wrap))
     .command(versionCmd(wrap))
+    .command(upgradeCmd(wrap))
     .command(discoverCmd(wrap, (argv) => visibleCommandRegistry(cliInstance.commandRegistry(), app.config, argv)))
     .demandCommand(1, 'You must specify a command')
     // Completion plumbing under a hidden command name, so the explicit

package/src/command-audience.js

@@ -2,8 +2,11 @@
 // Explicit command paths and --all-commands remain available to every account.
 const BASIC_COMMANDS = new Set([
   'incidents', 'changes', 'requests', 'tasks', 'tickets', 'approvals', 'records',
+  'knowledge',
   'groups', 'groupmembers', 'grouproles', 'users', 'setup', 'auth', 'skill',
-  'version', 'docs', 'history', 'discover', 'completion',
+  'cmdb',
+  'version', 'upgrade', 'docs', 'history', 'discover', 'completion',
+  'catalogitems',
 ]);
 
 export async function detectCommandAudience(sdk, username, instanceURL = sdk?.baseURL) {

package/src/commands/catalog-order.js

@@ -0,0 +1,93 @@
+import { parseDataArg, confirmDelete, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const ID = /^[a-f0-9]{32}$/i;
+const API = '/api/sn_sc/servicecatalog/items';
+const object = v => v && typeof v === 'object' && !Array.isArray(v);
+
+function emit(app, argv, data, summary, breadcrumbs = []) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { summary, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+}
+function requireId(id) { if (!ID.test(id || '')) throw errUsage('Use the full catalog item sys_id; find it with catalogitems search.'); }
+async function describe(app, id) {
+  requireId(id);
+  const response = await app.sdk.request(`${app.sdk.baseURL}${API}/${id}`, { method: 'GET' });
+  if (!object(response?.result) || response.result.sys_id !== id) throw errAPI(200, 'Catalog API returned no readable item with the requested identity.');
+  return response.result;
+}
+function itemHints(id) {
+  return [{ action: 'describe', cmd: `jsn catalogitems describe ${id}`, description: 'Inspect catalog inputs and pricing' },
+    { action: 'preview', cmd: `jsn catalogitems order ${id} --dry-run --variables-file variables.json`, description: 'Preview an order without submitting' }];
+}
+
+export function catalogOrderCommands(wrap) {
+  return [
+    { command: 'search <text>', describe: 'Find requestable items through the Service Catalog API',
+      builder: y => y.positional('text', { type: 'string' }).option('limit', { type: 'number', default: 20, describe: 'Maximum items (1–100)' }),
+      handler: wrap(async (argv, app) => {
+        if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty catalog search text.');
+        if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+        const params = new URLSearchParams({ sysparm_text: argv.text.trim(), sysparm_limit: String(argv.limit) });
+        const response = await app.sdk.request(`${app.sdk.baseURL}${API}?${params}`, { method: 'GET' });
+        if (!Array.isArray(response?.result) || response.result.some(i => !object(i) || !ID.test(i.sys_id || ''))) throw errAPI(200, 'Catalog API returned no valid item list.');
+        emit(app, argv, { items: response.result, count: response.result.length, limit: argv.limit,
+          possibly_truncated: response.result.length === argv.limit }, `${response.result.length} catalog item(s)`,
+        response.result.flatMap(i => itemHints(i.sys_id).slice(0, 1)));
+      }) },
+    { command: 'describe <id>', aliases: ['inputs'], describe: 'Read requestable item details, pricing and variable definitions',
+      builder: y => y.positional('id', { type: 'string' }),
+      handler: wrap(async (argv, app) => {
+        const item = await describe(app, argv.id);
+        emit(app, argv, item, item.name || item.short_description || argv.id, itemHints(argv.id));
+      }) },
+    { command: 'order <id>', describe: 'Submit a catalog order with explicit confirmation',
+      builder: y => y.positional('id', { type: 'string' })
+        .option('variables', { type: 'string', describe: 'JSON object of catalog variable names/values' })
+        .option('variables-file', { type: 'string', describe: 'Read the variables object from a JSON file' })
+        .option('quantity', { type: 'number', default: 1, describe: 'Positive integer quantity (max 1000)' })
+        .option('requested-for', { type: 'string', describe: 'User sys_id; instance delegation rules still apply' })
+        .option('dry-run', { type: 'boolean', default: false, describe: 'Read item details and preview variable names; no order is submitted' })
+        .epilogue('Use describe to inspect variables first. Server-side rules validate the order; a preview does not prove submission will succeed. Existing create/list/show commands manage definitions. Orders require a write-enabled profile, including dry runs. No application/update-set selection is needed.'),
+      handler: wrap(async (argv, app) => {
+        requireId(argv.id);
+        if (!Number.isInteger(argv.quantity) || argv.quantity < 1 || argv.quantity > 1000) throw errUsage('--quantity must be an integer from 1 to 1000.');
+        const requestedFor = argv.requestedFor ?? argv['requested-for'];
+        if (requestedFor !== undefined && !ID.test(requestedFor)) throw errUsage('--requested-for requires a user sys_id.');
+        const file = argv.variablesFile ?? argv['variables-file'];
+        if (argv.variables !== undefined && file !== undefined) throw errUsage('Choose --variables or --variables-file, not both.');
+        const variables = argv.variables !== undefined || file !== undefined
+          ? parseDataArg({ data: argv.variables, 'data-file': file }) : {};
+        if (!object(variables)) throw errUsage('Catalog variables must be a JSON object.');
+        const item = await describe(app, argv.id);
+        if (item.sys_class_name && item.sys_class_name !== 'sc_cat_item') throw errUsage('order supports standard catalog items; record producers and order guides need their own submission workflows.');
+        if (item.active === false || item.active === 'false' || item.can_order === false) throw errUsage('This item is not currently orderable.');
+        const plan = { item_id: argv.id, name: item.name || item.short_description, quantity: argv.quantity,
+          requested_for: requestedFor || null, variable_names: Object.keys(variables) };
+        if (argv.dryRun ?? argv['dry-run']) return emit(app, argv, { ...plan, submitted: false, server_validation: 'not performed' }, 'Catalog order preview; nothing submitted', itemHints(argv.id));
+        const rerun = ['catalogitems', 'order', argv.id, '--quantity', String(argv.quantity),
+          ...(requestedFor ? ['--requested-for', requestedFor] : []),
+          ...(file ? ['--variables-file', file] : Object.keys(variables).length ? ['--variables-file', '<variables.json>'] : [])];
+        try {
+          await confirmDelete(app, argv, `Order ${argv.quantity} × ${plan.name || argv.id}${requestedFor ? ` for ${requestedFor}` : ''}?`, { rerun });
+        } catch (error) {
+          if (error.message === 'Deletion cancelled') throw errUsage('Catalog order cancelled.');
+          throw error;
+        }
+        const body = { sysparm_quantity: argv.quantity, variables, ...(requestedFor ? { sysparm_requested_for: requestedFor } : {}) };
+        let response;
+        try {
+          response = await app.sdk.request(`${app.sdk.baseURL}${API}/${argv.id}/order_now`, { method: 'POST', body: JSON.stringify(body) });
+        } catch (error) {
+          if (error.status >= 400 && error.status < 500 && error.status !== 408) throw errAPI(error.status, 'Catalog order was rejected. Check item access, required variables and requested-for eligibility.');
+          throw errAPI(error.status || 0, 'Catalog submission did not return a confirmed order. Inspect your requests before retrying; the order may have been placed.');
+        }
+        const result = response?.result;
+        const requestId = result?.request_id || result?.sys_id, number = result?.request_number || result?.number;
+        if (!object(result) || result.error || !ID.test(requestId || '') || typeof number !== 'string' || !number.trim()) throw errAPI(200, 'Catalog response did not confirm an order identity. Inspect your requests before retrying; do not resubmit automatically.');
+        emit(app, argv, { item_id: argv.id, quantity: argv.quantity, request_id: requestId, request_number: number, submitted: true },
+          `Ordered: ${number}`, [{ action: 'request', cmd: `jsn records get --table sc_request --sys-id ${requestId}`, description: 'Read the request header' },
+            { action: 'items', cmd: `jsn requests list --query ${quoteShellArg(`request=${requestId}`)}`, description: 'Track the requested items' }]);
+      }) },
+  ];
+}

package/src/commands/catalog.js

@@ -1,9 +1,10 @@
-import { getStringField, interactiveList, resolveItemOptionType } from '../helpers.js';
+import { getStringField, interactiveList, resolveItemOptionType, formatCommandList, quoteShellArg } from '../helpers.js';
+import { catalogOrderCommands } from './catalog-order.js';
 import { resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 import { enrichCatalogItem, buildCatalogFormatted } from './catalog/enrich.js';
 
-declareCapabilities('catalogitems', { mutationSubcommands: ['create'] });
+declareCapabilities('catalogitems', { mutationSubcommands: ['create', 'order'], mutationContextExemptSubcommands: ['order'], localPreviewSubcommands: ['order'] });
 
 export function catalogCmd(wrap) {
   return {
@@ -11,6 +12,7 @@ export function catalogCmd(wrap) {
     aliases: ['ci'],
     describe: 'Manage Service Catalog items',
     builder: (yargs) => {
+      for (const command of catalogOrderCommands(wrap)) yargs.command(command);
       return yargs
         .command({
           command: 'create',
@@ -148,14 +150,10 @@ export function catalogCmd(wrap) {
           }),
         });
     },
-    handler: () => {
-      console.log('Service Catalog management.');
-      console.log('');
-      console.log('Commands:');
-      console.log('  create     Create a catalog item');
-      console.log('  list       Browse catalog items');
-      console.log('  show <id>  Show catalog item');
-    },
+    handler: wrap(async (argv, app) => app.ok({ subcommands: argv.subcommands || [],
+      _formatted: formatCommandList({ title: 'Service Catalog', commands: argv.subcommands || [] }) },
+    { summary: 'Service Catalog: search, describe and order items; manage definitions with create/list/show',
+      breadcrumbs: [{ action: 'search', cmd: 'jsn catalogitems search <text>' + (argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : ''), description: 'Find requestable items' }] })),
   };
 }
 

package/src/commands/cmdb-search.js

@@ -0,0 +1,38 @@
+import { assertSafeExactMatch, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const FIELDS = ['name', 'fqdn', 'ip_address', 'serial_number'];
+const raw = v => v && typeof v === 'object' ? v.value : v;
+
+export function cmdbSearchCmd(wrap) {
+  return { command: 'search <text>', describe: 'Find CIs by name, FQDN, IP address, or serial number',
+    builder: y => y.positional('text', { type: 'string', describe: 'Literal text; quote multiple words' })
+      .option('class', { type: 'string', describe: 'Exact CI class name (not descendants)' })
+      .option('limit', { type: 'number', default: 20, describe: 'Maximum CIs (1–100)' })
+      .option('offset', { type: 'number', default: 0, describe: 'Starting result offset' }),
+    handler: wrap(async (argv, app) => {
+      if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty CI search text.');
+      const text = argv.text.trim();
+      assertSafeExactMatch(text);
+      if ([...text].some(c => c.codePointAt(0) < 32 || c.codePointAt(0) === 127) || /javascript:/i.test(text)) throw errUsage('Search text must not contain query scripts or control characters.');
+      if (argv.class !== undefined && !/^[a-z][a-z0-9_]*$/.test(argv.class)) throw errUsage('--class must be an exact CI table name.');
+      if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+      if (!Number.isInteger(argv.offset) || argv.offset < 0) throw errUsage('--offset must be a nonnegative integer.');
+      // Repeat the class restriction in each OR branch: no branch may escape it.
+      const query = FIELDS.map(f => `${f}LIKE${text}${argv.class ? `^sys_class_name=${argv.class}` : ''}`).join('^NQ') + '^ORDERBYname^ORDERBYsys_id';
+      const params = new URLSearchParams({ sysparm_query: query, sysparm_limit: String(argv.limit + 1), sysparm_offset: String(argv.offset),
+        sysparm_fields: 'sys_id,name,sys_class_name,fqdn,ip_address,serial_number', sysparm_display_value: 'all' });
+      const rows = await app.sdk.listStrict('cmdb_ci', params);
+      if (!Array.isArray(rows) || rows.some(r => !r || typeof r !== 'object' || Array.isArray(r))) throw errAPI(200, 'CMDB search returned no valid record list.');
+      const hasMore = rows.length > argv.limit, records = rows.slice(0, argv.limit);
+      const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}` : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+      const breadcrumbs = records.flatMap(r => /^[a-f0-9]{32}$/i.test(raw(r.sys_id) || '') ? [
+        { action: 'show', cmd: `jsn cmdb show ${raw(r.sys_id)}`, description: String(raw(r.name) || 'Inspect CI') },
+        { action: 'relationships', cmd: `jsn cmdb relationships --ci ${raw(r.sys_id)}`, description: 'Inspect CI dependencies' },
+      ] : []);
+      if (hasMore) breadcrumbs.push({ action: 'next', cmd: `jsn cmdb search ${quoteShellArg(text)} --limit ${argv.limit} --offset ${argv.offset + argv.limit}${argv.class ? ` --class ${argv.class}` : ''}`, description: 'Next matching CIs' });
+      app.ok({ table: 'cmdb_ci', search: text, fields: FIELDS, records, count: records.length,
+        pagination: { limit: argv.limit, offset: argv.offset, has_more: hasMore } },
+      { summary: `${records.length} matching CI(s)`, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+    }) };
+}

package/src/commands/cmdb.js

@@ -15,6 +15,7 @@ import {
   resolveFieldsParam,
 } from '../helpers.js';
 import { errNotFound, errUsage } from '../errors.js';
+import { cmdbSearchCmd } from './cmdb-search.js';
 
 const SYS_ID_RE = /^[0-9a-f]{32}$/i;
 const MAX_DEPTH = 5;
@@ -371,6 +372,7 @@ export function cmdbCmd(wrap) {
     }),
     builder: (yargs) => {
       return yargs
+        .command(cmdbSearchCmd(wrap))
         .command({
           command: 'list',
           describe: 'List CIs from the CMDB (cmdb_ci)',

package/src/commands/knowledge.js

@@ -0,0 +1,75 @@
+import TurndownService from 'turndown';
+import { formatCommandList, quoteShellArg } from '../helpers.js';
+import { errAPI, errUsage } from '../errors.js';
+
+const API = '/api/sn_km_api/knowledge/articles';
+const markdown = new TurndownService();
+const sysId = /^[a-f0-9]{32}$/i;
+const articleId = value => typeof value === 'string' && (sysId.test(value) || /^KB\d+$/i.test(value));
+
+function emit(app, argv, data, summary, breadcrumbs = []) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}`
+    : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { summary, breadcrumbs: breadcrumbs.map(h => ({ ...h, cmd: h.cmd + connection })) });
+}
+
+async function read(sdk, path, params) {
+  const response = await sdk.request(`${sdk.baseURL}${API}${path}?${params}`, { method: 'GET' });
+  const result = response?.result;
+  if (!result || typeof result !== 'object' || Array.isArray(result)) throw errAPI(200, 'Malformed Knowledge API response.');
+  const code = result.meta?.status?.code;
+  if (code !== undefined && Number(code) !== 200) throw errAPI(Number(code) || 500, 'Knowledge API rejected the request.');
+  return result;
+}
+
+export function knowledgeCmd(wrap) {
+  return {
+    command: 'knowledge [subcommand]', aliases: ['kb'],
+    describe: 'Search and read knowledge articles through the Knowledge API',
+    handler: wrap(async (argv, app) => emit(app, argv,
+      { subcommands: argv.subcommands || [], _formatted: formatCommandList({ title: 'Knowledge articles', commands: argv.subcommands || [] }) },
+      'Search and read knowledge articles', [{ action: 'search', cmd: 'jsn knowledge search <text>', description: 'Find accessible articles' }])),
+    builder: y => y
+      .epilogue('Requires the Knowledge API (sn_km_api). Uses its access checks; no fallback to direct knowledge-table reads. Reading does not request view-count updates.')
+      .command({ command: 'search <text>', describe: 'Search accessible knowledge articles',
+        builder: p => p.positional('text', { type: 'string', describe: 'Search text; quote multiple words' })
+          .option('limit', { type: 'number', default: 20, describe: 'Maximum articles (1–100)' })
+          .option('offset', { type: 'number', default: 0, describe: 'Starting result offset' })
+          .option('kb', { type: 'string', describe: 'Comma-separated knowledge-base sys_ids' })
+          .option('language', { type: 'string', describe: 'Two-letter language codes, comma-separated, or all' }),
+        handler: wrap(async (argv, app) => {
+          if (typeof argv.text !== 'string' || !argv.text.trim()) throw errUsage('Provide nonempty search text.');
+          if (!Number.isInteger(argv.limit) || argv.limit < 1 || argv.limit > 100) throw errUsage('--limit must be from 1 to 100.');
+          if (!Number.isInteger(argv.offset) || argv.offset < 0) throw errUsage('--offset must be a nonnegative integer.');
+          if (argv.kb !== undefined && !String(argv.kb).split(',').every(id => sysId.test(id))) throw errUsage('--kb requires knowledge-base sys_ids.');
+          if (argv.language !== undefined && !/^(all|[a-z]{2}(,[a-z]{2})*)$/i.test(argv.language)) throw errUsage('Use two-letter --language codes or all.');
+          const params = new URLSearchParams({ query: argv.text.trim(), limit: String(argv.limit), offset: String(argv.offset) });
+          if (argv.kb) params.set('kb', argv.kb);
+          if (argv.language) params.set('language', argv.language);
+          const result = await read(app.sdk, '', params);
+          if (!Array.isArray(result.articles) || result.articles.some(a => !a || typeof a !== 'object' || Array.isArray(a))) throw errAPI(200, 'Knowledge API returned no valid article list.');
+          const breadcrumbs = result.articles.flatMap(a => {
+            const id = articleId(a.number) ? a.number : String(a.id || '').replace(/^kb_knowledge:/, '');
+            return articleId(id) ? [{ action: 'show', cmd: `jsn knowledge show ${id}`, description: a.title || id }] : [];
+          });
+          const base = `jsn knowledge search ${quoteShellArg(argv.text.trim())} --limit ${argv.limit}`
+            + (argv.kb ? ` --kb ${quoteShellArg(argv.kb)}` : '') + (argv.language ? ` --language ${quoteShellArg(argv.language)}` : '');
+          const total = result.meta?.count;
+          const hasMore = typeof total === 'number' ? argv.offset + result.articles.length < total : result.articles.length === argv.limit;
+          if (hasMore) breadcrumbs.push({ action: 'next', cmd: `${base} --offset ${argv.offset + argv.limit}`, description: 'Next result page' });
+          emit(app, argv, { ...result, count: result.articles.length,
+            _formatted: result.articles.map(a => `${a.number || a.id || ''}  ${a.title || ''}\n${a.snippet || ''}`).join('\n\n') || 'No accessible articles matched.' },
+          `${result.articles.length} knowledge article(s)`, breadcrumbs);
+        }) })
+      .command({ command: 'show <id>', describe: 'Read an article by KB number or sys_id',
+        builder: p => p.positional('id', { type: 'string' }),
+        handler: wrap(async (argv, app) => {
+          if (!articleId(argv.id)) throw errUsage('Use a KB number or full article sys_id.');
+          const article = await read(app.sdk, `/${encodeURIComponent(argv.id)}`, new URLSearchParams());
+          if (!sysId.test(article.sys_id || '') || typeof article.content !== 'string') throw errAPI(200, 'Knowledge API returned no readable article content.');
+          emit(app, argv, { ...article, _formatted: `${article.number || argv.id}: ${article.short_description || ''}\n\n${markdown.turndown(article.content)}` },
+            article.short_description || article.number || argv.id,
+            [{ action: 'search', cmd: 'jsn knowledge search <text>', description: 'Find more articles' }]);
+        }) }),
+  };
+}

package/src/commands/records.js

@@ -101,6 +101,9 @@ export function recordsCmd(wrap) {
               'and press Enter to select or Esc to cancel. --sys-id skips the picker.',
               'Use --json for noninteractive structured output; pipes and explicit formats also skip the picker.',
               'Example: jsn records list --table incident --query "active=true" --limit 5 --json',
+              'JSON shape (abbreviated): {"ok":true,"data":{"records":[{"sys_id":"...","number":"INC0010001"}]},...}',
+              'Records are at data.records; fields are directly on each record (e.g. record.number).',
+              'Array only: jsn records list --table incident --get data.records',
               'Discover fields with: jsn columns --table incident',
             ].join('\n')),
           handler: wrap(async (argv, app) => {

package/src/commands/scan.js

@@ -0,0 +1,234 @@
+import { buildRecordPayload, confirmDelete, getStringField, quoteShellArg, verifyWriteBack } from '../helpers.js';
+import { createRecord, updateRecord, deleteRecord } from '../records-engine.js';
+import { unwrapSysId } from '../resolve-record.js';
+import { getCurrentApplication, getCurrentUser } from '../context.js';
+import { declareCapabilities } from '../capabilities.js';
+import { errAPI, errUsage } from '../errors.js';
+import { CHECK_TABLES, active, raw, referenceId, boundedLimit, scanList, resolveScanRecord,
+  validateScanPayload, checkKind, prepareScan, startScan, scanStatus, scanResults, cancelScan } from '../scan.js';
+
+declareCapabilities('scan', { mutationSubcommands: [
+  ...['checks', 'suites'].flatMap(group => ['create', 'update', 'delete', 'activate', 'deactivate'].map(verb => `${group} ${verb}`)),
+  'suites add-check', 'suites remove-check', 'run', 'cancel',
+] });
+
+const hint = (action, cmd, description) => ({ action, cmd, description });
+function report(app, argv, data, options) {
+  const connection = argv.profile ? ` --profile ${quoteShellArg(argv.profile)}`
+    : argv.instance ? ` --instance ${quoteShellArg(argv.instance)}` : '';
+  app.ok(data, { ...options, breadcrumbs: options.breadcrumbs.map(item => ({ ...item, cmd: item.cmd + connection })) });
+}
+const rootHints = () => [hint('checks', 'jsn scan checks list', 'Browse available checks'),
+  hint('suites', 'jsn scan suites list', 'Browse suites'), hint('run', 'jsn scan run --help', 'Choose an explicit scan target')];
+const itemHints = (group, record) => {
+  const id = unwrapSysId(record);
+  return [hint('list', `jsn scan ${group} list`, `Browse ${group}`),
+    hint('show', `jsn scan ${group} show ${id}`, 'Inspect this definition'),
+    hint('update', `jsn scan ${group} update ${id} --data-file ${group === 'checks' ? 'check' : 'suite'}.json`, 'Update selected fields'),
+    hint(active(record) ? 'deactivate' : 'activate', `jsn scan ${group} ${active(record) ? 'deactivate' : 'activate'} ${id}`, 'Change eligibility without starting a scan'),
+    ...(group === 'suites' ? [hint('add-check', `jsn scan suites add-check ${id} --check '<check-id-or-name>'`, 'Add an existing check'),
+      hint('run', `jsn scan run --suite ${id} --update-set '<update-set>'`, 'Run against an explicit update set')] :
+      [hint('suites', 'jsn scan suites list', 'Choose a suite for this check')]),
+    hint('delete', `jsn scan ${group} delete ${id}`, 'Delete this definition after confirmation')];
+};
+
+function executionHints(data) {
+  const id = data.execution_id;
+  return [hint('status', `jsn scan status ${id}`, 'Read execution progress'),
+    hint('results', `jsn scan results ${id}`, 'Inspect findings and recorded check executions'),
+    ...(!data.terminal ? [hint('cancel', `jsn scan cancel ${id}`, 'Request cancellation')] : []),
+    ...(data.reusable_target ? [hint('rerun', `jsn scan run --previous ${id}${data.rerun_full ? ' --full' : ''}`, 'Rerun the previous target with current check definitions')] : []),
+    hint('checks', 'jsn scan checks list', 'Review available checks')];
+}
+
+const payloadOptions = y => y.option('data', { type: 'string', describe: 'JSON fields' })
+  .option('data-file', { type: 'string', describe: 'Read JSON fields from a file (recommended for scripts)' })
+  .option('data-stdin', { type: 'boolean', describe: 'Read JSON fields from stdin' })
+  .option('field', { alias: 'f', type: 'array', describe: 'Set field=value; repeatable' });
+const lookupOptions = y => y.positional('identifier', { type: 'string', describe: 'Unique name or sys_id' });
+
+async function guardScope(app, record) {
+  const scopeId = referenceId(record.sys_scope) || raw(record.sys_scope);
+  if (!scopeId) throw errUsage('The definition scope is unreadable; inspect permissions before changing it.');
+  const user = await getCurrentUser(app.sdk);
+  if (!user) throw errUsage('Could not verify the current scope.');
+  const scope = await getCurrentApplication(app.sdk, user.sys_id, { unknownWhenMissing: true });
+  if (scope.appSysId !== scopeId && scope.scope !== scopeId) {
+    throw errUsage(`Select the definition scope before changing it: jsn scopes set ${quoteShellArg(scopeId)}`);
+  }
+}
+
+async function verify(app, table, id, data) {
+  if (!id) throw errAPI(200, 'The write returned no sys_id. Inspect the instance before retrying.');
+  const mismatches = await verifyWriteBack(app, table, id, data);
+  if (mismatches.length) throw errAPI(200, `Write-back verification failed for ${table}/${id}: ${mismatches.map(item => item.field).join(', ')}. The write may have succeeded partially; inspect before retrying.`);
+}
+
+function definitions(group, wrap) {
+  const suite = group === 'suites';
+  const baseTable = suite ? 'scan_check_suite' : 'scan_check';
+  const emit = (app, argv, record, summary) => report(app, argv, record, { summary, breadcrumbs: itemHints(group, record) });
+  return {
+    command: `${group} [subcommand]`,
+    describe: suite ? 'Manage scan suites and their check memberships' : 'Manage typed Instance Scan check definitions',
+    builder: y => {
+      y.command({ command: 'list', describe: `List ${group}`,
+        builder: p => {
+          p.option('query', { type: 'string', describe: 'Encoded query' })
+            .option('limit', { type: 'number', default: 50, describe: 'Maximum records (1–200)' })
+            .option('offset', { type: 'number', default: 0, describe: 'Pagination offset' });
+          return suite ? p : p.option('type', { choices: Object.keys(CHECK_TABLES), type: 'string', describe: 'Filter by check type' });
+        }, handler: wrap(async (argv, app) => {
+          const table = suite ? baseTable : (argv.type ? CHECK_TABLES[argv.type] : baseTable);
+          const records = await scanList(app.sdk, table, { limit: argv.limit, offset: argv.offset, query: argv.query,
+            fields: ['sys_id', 'name', 'active', ...(suite ? ['description'] : ['sys_class_name', 'short_description'])] });
+          report(app, argv, { table, records, count: records.length, limit: argv.limit, offset: argv.offset,
+            more_available: records.length === argv.limit ? null : false }, {
+            summary: `${records.length} scan ${group}`, breadcrumbs: [
+              ...records.slice(0, 5).map(record => hint('show', `jsn scan ${group} show ${unwrapSysId(record)}`, `Inspect ${getStringField(record, 'name')}`)),
+              hint('create', `jsn scan ${group} create${suite ? '' : ' --type table'} --data-file ${suite ? 'suite' : 'check'}.json`, 'Create an inactive definition'),
+              ...(records.length === argv.limit ? [hint('next', `jsn scan ${group} list --offset ${argv.offset + argv.limit} --limit ${argv.limit}${argv.type ? ` --type ${argv.type}` : ''}${argv.query ? ` --query ${quoteShellArg(argv.query)}` : ''}`, 'Next page')] : []),
+            ],
+          });
+        }) });
+      y.command({ command: 'show <identifier>', describe: `Inspect a ${suite ? 'suite and its members' : 'check'}`, builder: lookupOptions,
+        handler: wrap(async (argv, app) => {
+          const record = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          if (suite) {
+            const members = await scanList(app.sdk, 'scan_check_suite_check', { limit: 200, query: `suite=${unwrapSysId(record)}^ORDERBYsys_id`, fields: ['sys_id', 'check'] });
+            record.members = members;
+            record.members_may_be_truncated = members.length === 200;
+          }
+          emit(app, argv, record, `Scan ${suite ? 'suite' : 'check'}: ${getStringField(record, 'name')}`);
+        }) });
+      y.command({ command: 'create', describe: `Create an inactive ${suite ? 'suite' : 'typed check'} unless active is explicitly supplied`,
+        builder: p => suite ? payloadOptions(p) : payloadOptions(p).option('type', { choices: Object.keys(CHECK_TABLES), type: 'string', demandOption: true, describe: 'Check type' }),
+        handler: wrap(async (argv, app) => {
+          const data = validateScanPayload(argv.type, buildRecordPayload(argv), { create: true, suite });
+          const table = suite ? baseTable : CHECK_TABLES[argv.type];
+          const record = await createRecord(app.sdk, { table, data });
+          await verify(app, table, unwrapSysId(record), data);
+          emit(app, argv, record, `Created scan ${suite ? 'suite' : 'check'}`);
+        }) });
+      for (const operation of ['update', 'activate', 'deactivate']) y.command({
+        command: `${operation} <identifier>`, describe: `${operation} a scan ${suite ? 'suite' : 'check'} without running it`,
+        builder: p => operation === 'update' ? payloadOptions(lookupOptions(p)) : lookupOptions(p),
+        handler: wrap(async (argv, app) => {
+          const record = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          const kind = suite ? null : checkKind(record);
+          const patch = operation === 'update' ? validateScanPayload(kind, buildRecordPayload(argv), { suite, current: record }) : { active: operation === 'activate' };
+          if (!suite && operation === 'activate') validateScanPayload(kind, {
+            name: raw(record.name), script: raw(record.script), ...(kind === 'table' ? { table: raw(record.table), advanced: raw(record.advanced) } : {}),
+            ...(kind === 'column' ? { column_type: raw(record.column_type) } : {}),
+          }, { create: true });
+          await guardScope(app, record);
+          const table = suite ? baseTable : CHECK_TABLES[kind];
+          const updated = await updateRecord(app.sdk, { table, record, data: patch });
+          await verify(app, table, unwrapSysId(record), patch);
+          emit(app, argv, updated, `Updated scan ${suite ? 'suite' : 'check'}`);
+        }),
+      });
+      y.command({ command: 'delete <identifier>', describe: `Delete a ${suite ? 'suite' : 'check'} definition after confirmation`, builder: lookupOptions,
+        handler: wrap(async (argv, app) => {
+          const record = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          await guardScope(app, record);
+          await confirmDelete(app, argv, `Delete scan ${suite ? 'suite' : 'check'} "${getStringField(record, 'name')}"?`);
+          const id = await deleteRecord(app.sdk, { table: suite ? baseTable : CHECK_TABLES[checkKind(record)], record });
+          report(app, argv, { sys_id: id, deleted: true }, { summary: 'Deleted scan definition', breadcrumbs: [hint('list', `jsn scan ${group} list`, 'Browse remaining definitions')] });
+        }) });
+      if (suite) for (const operation of ['add-check', 'remove-check']) y.command({
+        command: `${operation} <identifier>`, describe: `${operation === 'add-check' ? 'Add a check to' : 'Remove a check from'} a suite`,
+        builder: p => lookupOptions(p).option('check', { type: 'string', demandOption: true, describe: 'Check name or sys_id' }),
+        handler: wrap(async (argv, app) => {
+          const suiteRecord = await resolveScanRecord(app.sdk, baseTable, argv.identifier);
+          const check = await resolveScanRecord(app.sdk, 'scan_check', argv.check);
+          await guardScope(app, suiteRecord);
+          const data = { suite: unwrapSysId(suiteRecord), check: unwrapSysId(check) };
+          const table = 'scan_check_suite_check';
+          const members = await scanList(app.sdk, table, { query: `suite=${data.suite}^check=${data.check}`, limit: 2 });
+          if (members.length > 1) throw errUsage('Duplicate suite memberships exist; inspect and reconcile them before changing membership.');
+          let changed = false;
+          if (operation === 'add-check' && !members.length) {
+            const member = await createRecord(app.sdk, { table, data });
+            await verify(app, table, unwrapSysId(member), data);
+            changed = true;
+          } else if (operation === 'remove-check' && members.length) {
+            await confirmDelete(app, argv, 'Remove this check from the suite? The check definition will be retained.');
+            await deleteRecord(app.sdk, { table, record: members[0] });
+            changed = true;
+          }
+          report(app, argv, { ...data, changed, member: operation === 'add-check' }, { summary: 'Suite membership reconciled', breadcrumbs: itemHints(group, suiteRecord) });
+        }),
+      });
+      return y;
+    },
+    handler: wrap(async (argv, app) => report(app, argv, { commands: ['list', 'show', 'create', 'update', 'delete', 'activate', 'deactivate', ...(suite ? ['add-check', 'remove-check'] : [])] }, {
+      summary: `Scan ${group}`, breadcrumbs: [hint('list', `jsn scan ${group} list`, `Browse ${group}`)],
+    })),
+  };
+}
+
+export function scanCmd(wrap) {
+  return {
+    command: 'scan [subcommand]', describe: 'Instance Scan checks, suites, explicit targets, progress and findings',
+    builder: y => y.command(definitions('checks', wrap)).command(definitions('suites', wrap))
+      .command({ command: 'run', describe: 'Start an explicit target scan (confirmation required; no implicit full scan)',
+        builder: p => p.option('update-set', { type: 'string', describe: 'Update set name or sys_id; scans current records' })
+          .option('scope', { type: 'string', describe: 'Application scope value or sys_id' })
+          .option('record', { type: 'string', describe: 'Record sys_id; requires --table' })
+          .option('table', { type: 'string', describe: 'Table for --record' })
+          .option('full', { type: 'boolean', describe: 'Explicitly allow an instance-wide scan' })
+          .option('previous', { type: 'string', describe: 'Rerun a previous execution target; full scans also require --full' })
+          .option('suite', { type: 'string', describe: 'Optional active suite name or sys_id' })
+          .option('wait', { type: 'boolean', default: false, describe: 'Wait for completion; timeout does not cancel the scan' })
+          .option('timeout', { type: 'number', default: 120, describe: 'Maximum wait in seconds (1–3600)' }),
+        handler: wrap(async (argv, app) => {
+          if (!Number.isFinite(argv.timeout) || argv.timeout < 1 || argv.timeout > 3600) throw errUsage('--timeout must be from 1 to 3600 seconds.');
+          const plan = await prepareScan(app.sdk, argv);
+          await confirmDelete(app, argv, `Start scan of ${plan.target.kind} ${plan.target.name || plan.target.sys_id || plan.target.execution_id || 'the full instance'}${plan.suite_id ? ` using suite ${plan.suite_id}` : ''}?`);
+          const scheduled = await startScan(app.sdk, plan);
+          let data = { ...scheduled, status: 'scheduled', terminal: false };
+          if (argv.wait) {
+            try {
+              const deadline = Date.now() + argv.timeout * 1000;
+              while (Date.now() < deadline) {
+                try {
+                  data = { ...scheduled, ...await scanStatus(app.sdk, scheduled.execution_id, { allowInitializing: true }) };
+                } catch (error) {
+                  if (error.code !== 'not_found' && error.status !== 404) throw error;
+                  // The processor can return before its execution tracker is visible.
+                  data = { ...scheduled, status: 'scheduled', terminal: false };
+                }
+                if (data.terminal) { data = { ...scheduled, ...await scanResults(app.sdk, scheduled.execution_id) }; break; }
+                await new Promise(resolve => setTimeout(resolve, Math.min(2000, Math.max(0, deadline - Date.now()))));
+              }
+              if (!data.terminal) data.wait_timed_out = true;
+            } catch (error) {
+              throw errAPI(error.status || 0, `Scan ${scheduled.execution_id} was scheduled, but progress could not be read: ${error.message}. Use jsn scan status ${scheduled.execution_id}; do not resubmit automatically.`);
+            }
+          }
+          const breadcrumbs = executionHints(data);
+          if (data.terminal && !data.reusable_target) breadcrumbs.push(hint('rerun', 'jsn scan run --help', 'Choose a target for another scan'));
+          report(app, argv, data, { summary: `Scan ${data.execution_id}: ${data.status}${data.wait_timed_out ? ' (still running; wait timed out)' : ''}`, breadcrumbs });
+        }) })
+      .command({ command: 'status <id>', describe: 'Read scan execution progress',
+        handler: wrap(async (argv, app) => {
+          const data = await scanStatus(app.sdk, argv.id);
+          report(app, argv, data, { summary: `Scan ${data.status}: ${data.message}`, breadcrumbs: executionHints(data) });
+        }) })
+      .command({ command: 'results <id>', describe: 'Read findings and check execution coverage; unreadable data is not zero',
+        builder: p => p.option('limit', { type: 'number', default: 50, describe: 'Maximum findings/check rows (1–200); truncation is reported' }),
+        handler: wrap(async (argv, app) => {
+          const data = await scanResults(app.sdk, argv.id, boundedLimit(argv.limit));
+          report(app, argv, data, { summary: `Scan ${data.status}; ${data.findings_count ?? 'unknown'} findings; ${data.checks_executed ?? 'unknown'} recorded check executions${data.incomplete ? '; incomplete data' : ''}`, breadcrumbs: executionHints(data) });
+        }) })
+      .command({ command: 'cancel <id>', describe: 'Request cancellation of this scan after confirmation',
+        handler: wrap(async (argv, app) => {
+          const status = await scanStatus(app.sdk, argv.id);
+          if (!status.terminal) await confirmDelete(app, argv, `Cancel scan ${argv.id}?`);
+          const data = status.terminal ? { ...status, cancellation_requested: false } : await cancelScan(app.sdk, argv.id);
+          report(app, argv, data, { summary: data.cancellation_requested ? `Cancellation requested: ${argv.id}` : 'Scan already finished; no cancellation sent', breadcrumbs: executionHints(data) });
+        }) }),
+    handler: wrap(async (argv, app) => report(app, argv, { commands: ['checks', 'suites', 'run', 'status', 'results', 'cancel'] }, { summary: 'Instance Scan', breadcrumbs: rootHints() })),
+  };
+}

package/src/commands/skill.js

@@ -189,6 +189,7 @@ export function skillCmd(wrap) {
             }
             app.ok({
               content,
+              _formatted: content.endsWith('\n') ? content : `${content}\n`,
               bundled: SKILL_REPO_PATH,
             }, {
               summary: 'jsn AI agent skill file (bundled)',

package/src/commands/updatesets.js

@@ -365,6 +365,7 @@ export async function formatUpdateSetDetail(app, record) {
   const stateRaw = String(full.state?.value ?? full.state ?? '').toLowerCase();
   const isClosed = ['complete', 'committed'].includes(stateRaw);
   const hints = [];
+  hints.push({ action: 'scan', cmd: `jsn scan run --update-set ${sysID}${app.session?.profileName ? ` --profile ${quoteShellArg(app.session.profileName)}` : ''}`, description: 'Offer an explicit scan of current records before completing or promoting this set' });
   if (isClosed) {
     hints.push({
       action: 'set',

package/src/commands/upgrade.js

@@ -0,0 +1,69 @@
+import { spawnSync } from 'node:child_process';
+import { declareCapabilities } from '../capabilities.js';
+import { AppError, CodeAPI, CodeNetwork } from '../errors.js';
+import { checkLatest, getReleaseChannel, getVersion } from './version.js';
+
+for (const name of ['upgrade', 'update']) {
+  declareCapabilities(name, { noInstance: true, skipDailyChecks: true });
+}
+
+function installPackage(args, { structured }) {
+  const result = spawnSync('npm', args, { stdio: structured ? 'pipe' : 'inherit', encoding: 'utf8' });
+  if (result.error || result.status !== 0) {
+    throw new AppError(CodeAPI, 'npm could not upgrade jsn.', 'Check npm installation permissions and connectivity, then retry.');
+  }
+}
+
+function isNewer(candidate, installed) {
+  const parse = (value) => {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value);
+    if (!match) throw new AppError(CodeAPI, 'The registry returned an invalid package version.');
+    return { core: match.slice(1, 4).map(Number), pre: match[4]?.split('.') };
+  };
+  const a = parse(candidate), b = parse(installed);
+  for (let i = 0; i < 3; i++) {
+    if (a.core[i] !== b.core[i]) return a.core[i] > b.core[i];
+  }
+  if (!a.pre || !b.pre) return !a.pre && Boolean(b.pre);
+  for (let i = 0; i < Math.max(a.pre.length, b.pre.length); i++) {
+    if (a.pre[i] === b.pre[i]) continue;
+    if (a.pre[i] === undefined) return false;
+    if (b.pre[i] === undefined) return true;
+    const an = /^\d+$/.test(a.pre[i]), bn = /^\d+$/.test(b.pre[i]);
+    if (an && bn) return Number(a.pre[i]) > Number(b.pre[i]);
+    if (an !== bn) return !an;
+    return a.pre[i] > b.pre[i];
+  }
+  return false;
+}
+
+export function upgradeCmd(wrap, { version = getVersion, check = checkLatest, install = installPackage } = {}) {
+  return {
+    command: 'upgrade',
+    aliases: ['update'],
+    describe: 'Upgrade jsn through npm (preserves the installed release channel)',
+    builder: (y) => y
+      .option('channel', { type: 'string', choices: ['dev', 'latest'], describe: 'Choose the npm release channel' })
+      .option('dry-run', { type: 'boolean', describe: 'Show the install command without installing' })
+      .option('force', { type: 'boolean', describe: 'Reinstall even when the selected version is not newer' }),
+    handler: wrap(async (argv, app) => {
+      const current = version();
+      const channel = argv.channel || getReleaseChannel(current);
+      const args = ['install', '-g', `@jacebenson/jsn@${channel}`];
+      const command = `npm ${args.join(' ')}`;
+      if (argv.dryRun || argv['dry-run']) {
+        app.ok({ version: current, channel, dryRun: true, installCmd: command }, { summary: command });
+        return;
+      }
+      const latest = await check({ version: current, channel });
+      if (!latest) throw new AppError(CodeNetwork, 'Could not check the npm release channel.', 'Check connectivity and retry; use --dry-run to inspect the command.');
+      const switching = argv.channel && channel !== getReleaseChannel(current);
+      if (!argv.force && !switching && !isNewer(latest, current)) {
+        app.ok({ version: current, latest, channel, upToDate: true }, { summary: `jsn ${current} — no newer version available` });
+        return;
+      }
+      await install(args, { structured: Boolean(!process.stdout.isTTY || argv.json || argv.get || argv.format === 'json') });
+      app.ok({ previousVersion: current, version: latest, channel, upgraded: true }, { summary: `Installed jsn from the ${channel} channel (registry version ${latest})` });
+    }),
+  };
+}

package/src/commands/version.js

@@ -32,13 +32,13 @@ export function cancelBackgroundChecks() {
   backgroundChecks.clear();
 }
 
-export async function checkLatest({ timeout = 1500, background = false, version = getVersion() } = {}) {
+export async function checkLatest({ timeout = 1500, background = false, version = getVersion(), channel = getReleaseChannel(version) } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeout);
   timer.unref();
   if (background) backgroundChecks.add(controller);
   try {
-    const res = await fetch(`https://registry.npmjs.org/${NPM_PKG}/${getReleaseChannel(version)}`, { signal: controller.signal });
+    const res = await fetch(`https://registry.npmjs.org/${NPM_PKG}/${channel}`, { signal: controller.signal });
     if (!res.ok) return null;
     const data = await res.json();
     return typeof data.version === 'string' ? data.version : null;

package/src/help.js

@@ -28,6 +28,7 @@ function renderGroup(name, commands) {
 }
 
 const CORE_COMMANDS = [
+  { name: 'knowledge', alias: 'kb', desc: 'Search and read knowledge articles' },
   { name: 'incidents', alias: 'inc', desc: 'Manage incidents' },
   { name: 'changes', alias: 'chg', desc: 'Manage change requests' },
   { name: 'requests', alias: 'req', desc: 'Manage service catalog requests' },
@@ -132,6 +133,7 @@ const CONFIG_COMMANDS = [
 ];
 
 const DEVELOPER_COMMANDS = [
+  { name: 'scan', desc: 'Instance Scan checks, suites, explicit targets, progress and findings' },
   { name: 'atf', desc: 'Automated Test Framework (list, suites, run, results)' },
   { name: 'eval', desc: 'Run server-side JavaScript' },
   { name: 'rest', desc: 'Raw REST API calls' },

package/src/scan.js

@@ -0,0 +1,249 @@
+import { SaxesParser } from 'saxes';
+import { getRecord, recordListParams } from './records-engine.js';
+import { isSysId, unwrapSysId } from './resolve-record.js';
+import { errAPI, errNotFound, errUsage } from './errors.js';
+
+export const CHECK_TABLES = {
+  table: 'scan_table_check', column: 'scan_column_type_check',
+  linter: 'scan_linter_check', script: 'scan_script_only_check',
+};
+export const raw = value => value && typeof value === 'object' ? (value.value ?? '') : value;
+export const active = record => [true, 'true', '1', 1].includes(raw(record?.active));
+export const referenceId = value => {
+  const id = raw(value) || value?.link?.split('/').at(-1);
+  return isSysId(id) ? id : '';
+};
+
+export function requireId(value, label = 'execution') {
+  if (!isSysId(value)) throw errUsage(`Use a full 32-character sys_id for ${label}.`);
+  return value;
+}
+
+export function boundedLimit(value = 50) {
+  if (!Number.isInteger(value) || value < 1 || value > 200) throw errUsage('--limit must be an integer from 1 to 200.');
+  return value;
+}
+
+export async function scanList(sdk, table, { limit = 50, offset = 0, fields, query } = {}) {
+  boundedLimit(limit);
+  if (!Number.isInteger(offset) || offset < 0) throw errUsage('--offset must be a nonnegative integer.');
+  const params = recordListParams({ limit, offset, fields, query, displayValue: 'false' });
+  return sdk.listStrict(table, params);
+}
+
+export async function resolveScanRecord(sdk, table, identifier, matchField = 'name') {
+  const record = await getRecord(sdk, { table, identifier, matchField, displayValues: 'raw', resource: table });
+  if (table !== 'scan_check') return record;
+  const subtype = String(raw(record.sys_class_name) || '');
+  if (!Object.values(CHECK_TABLES).includes(subtype)) return record;
+  const concrete = await sdk.get(subtype, unwrapSysId(record));
+  if (!concrete || unwrapSysId(concrete) !== unwrapSysId(record)) throw errUsage('The concrete check definition is unavailable; inspect its class and permissions before changing it.');
+  return { ...record, ...concrete };
+}
+
+const COMMON_FIELDS = ['name', 'description', 'short_description', 'active', 'category', 'priority',
+  'script', 'run_condition', 'finding_type', 'resolution_details', 'documentation_url', 'score_min', 'score_max', 'score_scale'];
+
+export function validateScanPayload(kind, input, { create = false, suite = false, current = {} } = {}) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw errUsage('The payload must be a JSON object.');
+  if (!suite && !CHECK_TABLES[kind]) throw errUsage('Choose --type table, column, linter, or script.');
+  const fields = suite ? ['name', 'description', 'active', 'private'] : [...COMMON_FIELDS,
+    ...(kind === 'table' ? ['table', 'conditions', 'advanced', 'use_manifest'] : []),
+    ...(kind === 'column' ? ['column_type'] : [])];
+  for (const field of Object.keys(input)) {
+    if (!fields.includes(field)) throw errUsage(`Unsupported ${suite ? 'suite' : kind + ' check'} field: ${field}`);
+  }
+  const data = { ...input };
+  for (const field of ['active', 'private', 'advanced', 'use_manifest']) {
+    if (data[field] === undefined) continue;
+    if (![true, false, 'true', 'false'].includes(data[field])) throw errUsage(`${field} must be true or false.`);
+    data[field] = data[field] === true || data[field] === 'true';
+  }
+  if ((create || data.name !== undefined) && (typeof data.name !== 'string' || !data.name.trim())) throw errUsage('A nonempty name is required.');
+  if (data.script !== undefined && typeof data.script !== 'string') throw errUsage('script must be a string.');
+  if (create && data.active === undefined) data.active = false;
+  if (data.table !== undefined && !/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(data.table)) throw errUsage('Invalid target table name.');
+  if (data.column_type !== undefined && !['script', 'xml', 'html'].includes(data.column_type)) throw errUsage('column_type must be script, xml, or html.');
+  if (!suite) {
+    const script = data.script ?? raw(current.script);
+    const advanced = data.advanced ?? active({ active: current.advanced });
+    if (create && kind === 'table' && !data.table) throw errUsage('Table checks require a table.');
+    if (create && kind === 'column' && !data.column_type) throw errUsage('Column checks require column_type.');
+    if ((create || Object.hasOwn(data, 'script') || Object.hasOwn(data, 'advanced'))
+      && (kind !== 'table' || advanced) && (typeof script !== 'string' || !script.trim())) {
+      throw errUsage('This check type requires a nonempty script.');
+    }
+  }
+  return data;
+}
+
+export function checkKind(record) {
+  const table = String(raw(record.sys_class_name) || '');
+  const kind = Object.keys(CHECK_TABLES).find(key => CHECK_TABLES[key] === table);
+  if (!kind) throw errUsage('Unknown or unreadable check class; inspect the check before changing it.');
+  return kind;
+}
+
+function decodeAjax(xml) {
+  let answer;
+  const parser = new SaxesParser();
+  parser.on('doctype', () => { throw errAPI(200, 'Unexpected document type in scan response.'); });
+  parser.on('opentag', node => { if (node.name === 'xml') answer = node.attributes.answer; });
+  try { parser.write(xml).close(); } catch { throw errAPI(200, 'Malformed scan processor XML response.'); }
+  if (typeof answer !== 'string') throw errAPI(200, 'Scan processor returned no answer; check endpoint access.');
+  return answer;
+}
+
+export async function scanAjax(sdk, method, parameters) {
+  const query = new URLSearchParams({ sysparm_processor: 'ScanAjaxProcessor', sysparm_name: method, ...parameters });
+  return decodeAjax(await sdk.rawRequest(`${sdk.baseURL}/xmlhttp.do?${query}`, { method: 'POST' }));
+}
+
+const TERMINAL = new Set(['successful', 'failed', 'cancelled']);
+const STATES = { '0': 'pending', '1': 'running', '2': 'successful', '3': 'failed', '4': 'cancelled',
+  pending: 'pending', running: 'running', successful: 'successful', failed: 'failed',
+  cancelled: 'cancelled', canceled: 'cancelled' };
+
+export async function scanStatus(sdk, id, { allowInitializing = false } = {}) {
+  requireId(id);
+  const tracker = await sdk.get('sys_execution_tracker', id);
+  if (!tracker) throw errNotFound('scan execution', id);
+  if (!raw(tracker.type) && allowInitializing) return { execution_id: id, status: 'pending', terminal: false,
+    percent_complete: null, message: 'Execution tracker is initializing', result_id: null };
+  if (raw(tracker.type) === 'sys.instance_scan.queue') return { execution_id: id, status: 'pending', terminal: false,
+    percent_complete: raw(tracker.percent_complete) ?? null, message: raw(tracker.message) || 'Scan is queued', result_id: null };
+  if (raw(tracker.type) !== 'instance_scan') throw errUsage('This execution tracker is not an Instance Scan.');
+  const state = STATES[String(raw(tracker.state)).toLowerCase()] || 'unknown';
+  let resultId = '';
+  if (raw(tracker.result)) {
+    try { resultId = referenceId(JSON.parse(raw(tracker.result)).result_id); } catch { /* reported as unavailable below */ }
+  }
+  return { execution_id: id, status: state, terminal: TERMINAL.has(state),
+    percent_complete: raw(tracker.percent_complete) ?? null,
+    message: raw(tracker.message) || '', result_id: resultId || null };
+}
+
+async function resolveSuite(sdk, identifier) {
+  const suite = await resolveScanRecord(sdk, 'scan_check_suite', identifier);
+  if (!active(suite)) throw errUsage('The selected suite is inactive or its active state is unreadable. Activate it explicitly first.');
+  return unwrapSysId(suite);
+}
+
+export async function prepareScan(sdk, argv) {
+  const previous = argv.previous;
+  const updateSet = argv.updateSet ?? argv['update-set'];
+  for (const value of [previous, updateSet, argv.scope, argv.record, argv.suite]) {
+    if (value !== undefined && (typeof value !== 'string' || !value.trim())) throw errUsage('Scan target and suite identifiers must be nonempty strings.');
+  }
+  const selectors = [updateSet, argv.scope, argv.record, previous].filter(value => value !== undefined).length;
+  if (selectors + Number(Boolean(argv.full)) !== 1 && !(previous && argv.full && selectors === 1)) {
+    throw errUsage('Choose exactly one target: --update-set, --scope, --record with --table, --full, or --previous.');
+  }
+  if (Boolean(argv.table) !== Boolean(argv.record)) throw errUsage('--record and --table must be supplied together.');
+  if (previous && argv.suite) throw errUsage('--previous preserves its source suite; do not combine it with --suite.');
+  let target;
+  if (previous) {
+    const status = await scanStatus(sdk, previous);
+    if (!status.terminal || !status.result_id) throw errUsage('The previous scan must have finished and have a readable result.');
+    const result = await sdk.get('scan_result', status.result_id);
+    const comboId = referenceId(result?.combo);
+    if (!comboId) throw errUsage('The previous scan has no reusable target combination. Choose an explicit target.');
+    const combo = await sdk.get('scan_combo', comboId);
+    if (!combo) throw errUsage('The previous scan combination is unavailable.');
+    if (!raw(combo.targets) && !argv.full) throw errUsage('The previous scan was instance-wide. Repeat with --full to approve that breadth.');
+    target = { kind: 'previous', execution_id: previous, combo_id: comboId, full: !raw(combo.targets) };
+  } else if (updateSet !== undefined) {
+    const record = await resolveScanRecord(sdk, 'sys_update_set', updateSet);
+    target = { kind: 'update_set', sys_id: unwrapSysId(record), name: raw(record.name),
+      note: 'Scans current instance records referenced by this update set, not historical XML versions. Script-only checks do not participate.' };
+  } else if (argv.scope !== undefined) {
+    const record = await resolveScanRecord(sdk, 'sys_scope', argv.scope, 'scope');
+    target = { kind: 'scope', sys_id: unwrapSysId(record), name: raw(record.scope) };
+  } else if (argv.record !== undefined) {
+    if (!/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(argv.table)) throw errUsage('Invalid target table.');
+    const record = await resolveScanRecord(sdk, argv.table, argv.record, 'sys_id');
+    target = { kind: 'record', table: argv.table, sys_id: unwrapSysId(record),
+      inactive: raw(record.active) === false || raw(record.active) === 'false',
+      note: 'Inactive target records may be skipped by the scan engine. Script-only checks do not participate.' };
+  } else target = { kind: 'full', note: 'Instance-wide scans can traverse many tables and take substantially longer.' };
+  if (!target.sys_id && !['full', 'previous'].includes(target.kind)) throw errUsage('The target has no readable sys_id.');
+  const suiteId = argv.suite ? await resolveSuite(sdk, argv.suite) : null;
+  return { target, suite_id: suiteId };
+}
+
+export async function startScan(sdk, plan) {
+  const { target, suite_id: suite } = plan;
+  let response;
+  if (suite && ['update_set', 'scope'].includes(target.kind)) {
+    const kind = target.kind === 'scope' ? 'scoped_apps' : 'update_sets';
+    const field = target.kind === 'scope' ? 'app_scope_sys_ids' : 'update_set_sys_ids';
+    const data = await sdk.request(`${sdk.baseURL}/api/sn_cicd/instance_scan/suite_scan/${requireId(suite, 'suite')}/${kind}`, {
+      method: 'POST', body: JSON.stringify({ [field]: [target.sys_id] }),
+    });
+    response = data?.result;
+    if (response?.error || !['0', '1', '2'].includes(String(response?.status))) throw errAPI(200, 'Scan dispatch was rejected by the provider.');
+    const executionId = response?.links?.progress?.id;
+    if (!isSysId(executionId)) throw errAPI(200, 'Scan dispatch returned no valid execution id. Inspect existing scans before retrying.');
+    return { execution_id: executionId, via: 'sn_cicd', ...plan };
+  }
+  let method, parameters;
+  if (target.kind === 'previous') { method = 'executeScanFromCombo'; parameters = { sysparm_combo_id: target.combo_id }; }
+  else if (suite && target.kind === 'full') { method = 'executeSuiteScan'; parameters = { sysparm_sys_id: suite }; }
+  else if (suite) {
+    method = 'executeSuiteScanWithTargets'; parameters = { sysparm_suite_sys_id: suite,
+      sysparm_target_table: target.table, sysparm_target_sys_ids: JSON.stringify([target.sys_id]) };
+  } else if (target.kind === 'update_set') { method = 'executeUpdateSetScan'; parameters = { sysparm_sys_id: target.sys_id }; }
+  else if (target.kind === 'scope') { method = 'executeAppScan'; parameters = { sysparm_scope_id: target.sys_id }; }
+  else if (target.kind === 'record') { method = 'executePointScan'; parameters = { sysparm_sys_id: target.sys_id, sysparm_table_name: target.table }; }
+  else { method = 'executeFullScan'; parameters = {}; }
+  try { response = JSON.parse(await scanAjax(sdk, method, parameters)); }
+  catch (error) { if (error.code) throw error; throw errAPI(200, 'Malformed scan dispatch answer. Inspect existing scans before retrying.'); }
+  if (response.status !== 0 || !isSysId(response.progressId)) throw errAPI(200, 'Scan dispatch failed or returned no valid execution id. Inspect existing scans before retrying.');
+  return { execution_id: response.progressId, via: 'ScanAjaxProcessor', ...plan };
+}
+
+export async function scanResults(sdk, id, limit = 50) {
+  boundedLimit(limit);
+  const status = await scanStatus(sdk, id);
+  const data = { ...status, checks_executed: null, findings_count: null, checks: [], findings: [],
+    incomplete: !status.terminal, unavailable: [], truncated: {}, rerun_full: false, reusable_target: false };
+  if (!status.result_id) { data.unavailable.push('scan_result'); data.incomplete = true; return data; }
+  let result;
+  try {
+    result = await sdk.get('scan_result', status.result_id);
+    if (!result) throw new Error('Result unavailable');
+    data.scan_number = raw(result.number);
+    const value = raw(result.finding_count);
+    const count = Number(value);
+    if ((typeof value === 'number' || (typeof value === 'string' && /^\d+$/.test(value))) && Number.isInteger(count) && count >= 0) data.findings_count = count;
+    else { data.unavailable.push('scan_result.finding_count'); data.incomplete = true; }
+  } catch { data.unavailable.push('scan_result'); data.incomplete = true; }
+  for (const [key, table, fields] of [
+    ['checks', 'scan_check_execution', ['check', 'message', 'execution_time']],
+    ['findings', 'scan_finding', ['check', 'source_table', 'source', 'finding_details', 'count']],
+  ]) {
+    try {
+      const rows = await sdk.listStrict(table, recordListParams({ limit: limit + 1,
+        query: `result=${status.result_id}^ORDERBYsys_id`, fields, displayValue: 'all' }));
+      data[key] = rows.slice(0, limit);
+      data.truncated[key] = rows.length > limit;
+      if (key === 'checks' && !data.truncated[key] && status.terminal) data.checks_executed = rows.length;
+    } catch { data.unavailable.push(table); data.incomplete = true; }
+  }
+  const comboId = referenceId(result?.combo);
+  if (comboId) {
+    try { const combo = await sdk.get('scan_combo', comboId); if (combo) { data.reusable_target = true; data.rerun_full = !raw(combo.targets); } }
+    catch { /* Optional rerun hint is omitted when target metadata is inaccessible. */ }
+  }
+  data.coverage_note = 'Execution success does not prove functional correctness or complete coverage. Zero findings may mean records or checks were skipped.';
+  return data;
+}
+
+export async function cancelScan(sdk, id) {
+  const status = await scanStatus(sdk, id);
+  if (status.terminal) return { ...status, cancellation_requested: false };
+  const answer = await scanAjax(sdk, 'cancelScan', { sysparm_progress_id: id });
+  const after = await scanStatus(sdk, id);
+  if (after.status !== 'cancelled' && !/cancelled successfully/i.test(answer)) throw errAPI(200, 'Cancellation was not confirmed. Check the execution status before retrying.');
+  return { ...after, cancellation_requested: true };
+}