@jacebenson/jsn 4.3.13 → 4.4.0

package/src/commands/skill.js

@@ -18,8 +18,6 @@ const SKILL_REPO_PATH = path.join(
   '..', '..', 'skills', SKILL_NAME, 'SKILL.md'
 );
 
-const SKILL_RAW_URL = 'https://raw.githubusercontent.com/jacebenson/jsn/main/skills/servicenow/SKILL.md';
-
 /**
  * Resolve the user's real home directory, even when Hermes overrides $HOME.
  */
@@ -119,62 +117,56 @@ function saveSkillConfig(updates) {
   fs.writeFileSync(globalConfigPath(), JSON.stringify(cfg, null, 2), { mode: 0o600 });
 }
 
-function recordSkillInstall(targetPath) {
-  const bundled = readBundledSkill();
-  const version = extractVersion(bundled) || 'unknown';
+function replaceSkill(targetPath, content) {
+  const temporary = `${targetPath}.${process.pid}.tmp`;
+  try {
+    fs.writeFileSync(temporary, content, { encoding: 'utf-8', mode: 0o600 });
+    fs.renameSync(temporary, targetPath);
+  } finally {
+    fs.rmSync(temporary, { force: true });
+  }
+}
+
+function recordSkillInstall(targetPaths, content) {
+  const version = extractVersion(content) || 'unknown';
   saveSkillConfig({
-    skillLocation: targetPath,
+    skillLocation: targetPaths[0],
+    skillLocations: targetPaths,
     skillVersion: version,
     skillLastChecked: new Date().toISOString(),
   });
 }
 
-// ── Skill version check (once per day, uses recorded location) ──
-
-export function checkSkill() {
+// Compare bytes, including edits that retain the same version number.
+export function checkSkill({ warn = true } = {}) {
   const cfg = loadSkillConfig();
-  const location = cfg.skillLocation;
-  if (!location) return { current: true, note: 'Skill not installed — run "jsn skill install"' };
-
-  // Throttle: skip if checked within last 24 hours
-  if (cfg.skillLastChecked) {
-    const elapsed = Date.now() - new Date(cfg.skillLastChecked).getTime();
-    if (elapsed < 86400000) return { current: true, note: 'Checked within 24h — skipping' };
-  }
-
-  let installed;
-  try {
-    installed = fs.readFileSync(location, 'utf-8');
-  } catch {
-    return { current: true, note: `Skill file not found at ${location} — run "jsn skill install"` };
-  }
-
-  const installedVersion = extractVersion(installed);
+  const locations = cfg.skillLocations || (cfg.skillLocation ? [cfg.skillLocation] : []);
   const bundled = readBundledSkill();
-  const bundledVersion = extractVersion(bundled);
-
-  if (!installedVersion || !bundledVersion) {
-    return { current: true, error: 'Could not determine skill version' };
-  }
-
-  const current = installedVersion === bundledVersion;
-
-  if (!current) {
-    process.stderr.write(
-      `\n⚠ jsn: ServiceNow skill is outdated (installed v${installedVersion}, bundled v${bundledVersion}).\n` +
-      `  Run "jsn skill install" to update.\n\n`
-    );
-  }
-
-  // Update last-checked timestamp
+  if (bundled === null) return { current: false, error: 'Bundled skill missing; reinstall jsn.' };
+  if (!locations.length) return { current: false, note: 'Skill not installed — run "jsn skill install"' };
+  const copies = locations.map(location => {
+    let installed;
+    try { installed = fs.readFileSync(location, 'utf-8'); } catch {
+      return { location, current: false, status: 'missing' };
+    }
+    const current = installed === bundled;
+    const actual = installed.split('\n');
+    const expected = bundled.split('\n');
+    const line = current ? undefined : Array.from({ length: Math.max(actual.length, expected.length) }, (_, i) => i)
+      .find(i => actual[i] !== expected[i]) + 1;
+    return { location, current, status: current ? 'matching' : 'different',
+      installed_version: extractVersion(installed), first_different_line: line };
+  });
+  const current = copies.every(copy => copy.current);
+  if (!current && warn) process.stderr.write('ServiceNow skill differs from the packaged copy. Run "jsn skill check" for locations or "jsn skill install" to replace it.\n');
   saveSkillConfig({ skillLastChecked: new Date().toISOString() });
-
-  return { current, installed_version: installedVersion, bundled_version: bundledVersion };
+  return { current, installed_version: copies[0].installed_version,
+    bundled_version: extractVersion(bundled), copies };
 }
 
 function extractVersion(content) {
   // Matches version in YAML frontmatter (top-level or nested under metadata:)
-  const m = content.match(/^\s*version:\s*["']?(.+?)["']?\s*$/m);
+  const m = (content || '').match(/^\s*version:\s*["']?(.+?)["']?\s*$/m);
   return m ? m[1] : null;
 }
 
@@ -197,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)',
@@ -205,9 +198,9 @@ export function skillCmd(wrap) {
         })
         .command({
           command: 'check',
-          describe: 'Check if the installed skill matches the bundled version',
+          describe: 'Compare installed skill contents with the packaged skill',
           handler: wrap(async (_argv, app) => {
-            const result = checkSkill();
+            const result = checkSkill({ warn: false });
 
             let summary;
             if (result.error) {
@@ -215,21 +208,21 @@ export function skillCmd(wrap) {
             } else if (result.note) {
               summary = result.note;
             } else if (result.current) {
-              summary = `✓ Skill is current (v${result.installed_version} matches bundled v${result.bundled_version})`;
+              summary = `✓ Skill contents match the packaged copy (v${result.bundled_version})`;
             } else {
-              summary = `⚠ Skill outdated: installed v${result.installed_version} vs bundled v${result.bundled_version} — run "jsn skill install" to update`;
+              summary = `⚠ Skill contents differ — run "jsn skill install" to replace installed copies`;
             }
 
-            app.ok(result, { summary });
+            const details = result.copies?.map(copy => `${copy.status}: ${copy.location}${copy.first_different_line ? ` (first difference: line ${copy.first_different_line})` : ''}`).join('\n');
+            app.ok({ ...result, _formatted: [summary, details].filter(Boolean).join('\n') }, { summary });
           }),
         })
         .command({
           command: 'fetch',
-          describe: 'Download the latest skill file from GitHub to stdout',
+          describe: 'Print the packaged skill to stdout (offline)',
           handler: wrap(async (_argv, _app) => {
-            const res = await fetch(SKILL_RAW_URL);
-            if (!res.ok) throw new Error(`Failed to fetch skill: ${res.status} ${res.statusText}`);
-            const content = await res.text();
+            const content = readBundledSkill();
+            if (content === null) throw new Error('Bundled skill missing; reinstall jsn.');
             process.stdout.write(content);
           }),
         })
@@ -246,7 +239,6 @@ export function skillCmd(wrap) {
             app.ok({
               bundled: SKILL_REPO_PATH,
               targets: allPaths,
-              raw_url: SKILL_RAW_URL,
             }, {
               summary: 'Skill file locations and install targets',
               breadcrumbs: [
@@ -260,7 +252,7 @@ export function skillCmd(wrap) {
         })
         .command({
           command: 'install [dir]',
-          describe: 'Download and save the latest skill file',
+          describe: 'Install the bundled skill matched to this CLI version',
           builder: (y) => y
             .positional('dir', {
               type: 'string',
@@ -268,12 +260,13 @@ export function skillCmd(wrap) {
             })
             .option('target', {
               type: 'string',
-              describe: 'Target agent(s): hermes, copilot, vscode, claude, cursor, agents, opencode, openclaw, codex, or "all" (comma-separated). Omit for interactive picker.',
+              describe: 'Target agent(s): hermes, copilot, vscode, claude, cursor, agents, opencode, openclaw, codex, or "all" (comma-separated). Omit to replace recorded copies, or choose targets on first install.',
             }),
           handler: wrap(async (argv, app) => {
-            const res = await fetch(SKILL_RAW_URL);
-            if (!res.ok) throw new Error(`Failed to fetch skill: ${res.status} ${res.statusText}`);
-            const content = await res.text();
+            const content = readBundledSkill();
+            if (!content) {
+              throw new Error('Skill file not found in package (expected at skills/servicenow/SKILL.md). Reinstall jsn to restore it.');
+            }
 
             // Resolve target directories
             let targets = [];
@@ -283,7 +276,7 @@ export function skillCmd(wrap) {
               const p = path.resolve(argv.dir);
               fs.mkdirSync(p, { recursive: true });
               const targetPath = path.join(p, 'SKILL.md');
-              fs.writeFileSync(targetPath, content, 'utf-8');
+              replaceSkill(targetPath, content);
               targets.push({ name: path.basename(argv.dir), path: targetPath });
             } else if (argv.target) {
               // Explicit --target: install to specified agents
@@ -296,38 +289,41 @@ export function skillCmd(wrap) {
                   if (key === 'cursor') {
                     fs.mkdirSync(dir, { recursive: true });
                     const targetPath = path.join(dir, `${SKILL_NAME}.mdc`);
-                    fs.writeFileSync(targetPath, content, 'utf-8');
+                    replaceSkill(targetPath, content);
                     targets.push({ name: TARGET_NAMES[key], path: targetPath });
                   } else {
                     fs.mkdirSync(dir, { recursive: true });
                     const targetPath = path.join(dir, 'SKILL.md');
-                    fs.writeFileSync(targetPath, content, 'utf-8');
+                    replaceSkill(targetPath, content);
                     targets.push({ name: TARGET_NAMES[key], path: targetPath });
                   }
                 }
               }
+            } else if (loadSkillConfig().skillLocation) {
+              const cfg = loadSkillConfig();
+              for (const targetPath of cfg.skillLocations || [cfg.skillLocation]) {
+                fs.mkdirSync(path.dirname(targetPath), { recursive: true });
+                replaceSkill(targetPath, content);
+                targets.push({ name: targetPath, path: targetPath });
+              }
             } 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 = [];
-              if (fetchedVersion) {
-                for (const [key, dir] of Object.entries(AGENT_SKILL_DIRS)) {
+              for (const [key, dir] of Object.entries(AGENT_SKILL_DIRS)) {
                   const skillPath = key === 'cursor'
                     ? path.join(dir, `${SKILL_NAME}.mdc`)
                     : path.join(dir, 'SKILL.md');
                   try {
                     const existing = fs.readFileSync(skillPath, 'utf-8');
-                    const existingVersion = extractVersion(existing);
-                    if (existingVersion && existingVersion !== fetchedVersion) {
+                    if (existing !== content) {
                       outdated.push(TARGET_NAMES[key]);
                     }
                   } catch {
                     // Not installed — skip
                   }
-                }
               }
               const promptMsg = outdated.length > 0
                 ? `Where should the jsn skill be installed? (${outdated.length} outdated)`
@@ -366,12 +362,12 @@ export function skillCmd(wrap) {
                 if (key === 'cursor') {
                   fs.mkdirSync(dir, { recursive: true });
                   const targetPath = path.join(dir, `${SKILL_NAME}.mdc`);
-                  fs.writeFileSync(targetPath, content, 'utf-8');
+                  replaceSkill(targetPath, content);
                   targets.push({ name: TARGET_NAMES[key], path: targetPath });
                 } else {
                   fs.mkdirSync(dir, { recursive: true });
                   const targetPath = path.join(dir, 'SKILL.md');
-                  fs.writeFileSync(targetPath, content, 'utf-8');
+                  replaceSkill(targetPath, content);
                   targets.push({ name: TARGET_NAMES[key], path: targetPath });
                 }
               }
@@ -380,7 +376,7 @@ export function skillCmd(wrap) {
               const dir = AGENT_SKILL_DIRS.hermes;
               fs.mkdirSync(dir, { recursive: true });
               const targetPath = path.join(dir, 'SKILL.md');
-              fs.writeFileSync(targetPath, content, 'utf-8');
+              replaceSkill(targetPath, content);
               targets.push({ name: TARGET_NAMES.hermes, path: targetPath });
             }
 
@@ -389,7 +385,7 @@ export function skillCmd(wrap) {
             }
 
             // Record install location so checkSkill knows where to look
-            recordSkillInstall(targets[0].path);
+            recordSkillInstall(targets.map(target => target.path), content);
 
             const installed = targets.reduce((acc, t) => { acc[t.name] = t.path; return acc; }, {});
             const summary = targets.length === 1
@@ -399,7 +395,7 @@ export function skillCmd(wrap) {
             const okOpts = {
               summary,
               breadcrumbs: [
-                { action: 'reinstall', cmd: 'jsn skill install', description: 'Re-download and reinstall to default target' },
+                { action: 'reinstall', cmd: 'jsn skill install', description: 'Replace recorded copies with the packaged skill' },
               ],
             };
 
@@ -407,7 +403,7 @@ export function skillCmd(wrap) {
               okOpts.notice = 'Installed to multiple agents. Restart or reload your agent to pick up the skill.';
             }
 
-            app.ok({ installed, from: SKILL_RAW_URL }, okOpts);
+            app.ok({ installed, from: SKILL_REPO_PATH }, okOpts);
           }),
         });
     },
@@ -416,7 +412,8 @@ export function skillCmd(wrap) {
       console.log('');
       console.log('Available subcommands:');
       console.log('  show       Show the bundled skill file');
-      console.log('  fetch      Download the latest skill from GitHub');
+      console.log('  fetch      Print the packaged skill (offline)');
+      console.log('  check      Show whether installed contents differ');
       console.log('  path       Show skill file locations');
       console.log('  install    Install skill file to agents directory');
       console.log('');

package/src/commands/tasks.js

@@ -1,7 +1,5 @@
-import { buildTicketCommands } from './_ticket.js';
-
-const taskDefaultColumns = ['number', 'short_description', 'state', 'assigned_to'];
+import { buildProfileCommand } from '../record-profiles.js';
 
 export function tasksCmd(wrap) {
-  return buildTicketCommands('sc_task', 'tasks', 'task', taskDefaultColumns, {}, null, wrap);
+  return buildProfileCommand('tasks', wrap);
 }

package/src/commands/tickets.js

@@ -1,5 +1,7 @@
-import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, buildRecordPayload } from '../helpers.js';
-import { resolveRecord, resolveSysId } from '../resolve-record.js';
+import { enrichRelatedLists, relatedListOptions } from '../related-lists.js';
+import { formatRecordForDisplay, getStringField, buildQuerySuffix, resolveFieldsParam, buildRecordPayload, confirmDelete } from '../helpers.js';
+import { getRecord, listRecords, recordListParams, createRecord, updateRecord, deleteRecord, recordOptions } from '../records-engine.js';
+import { resolveSysId } from '../resolve-record.js';
 import { declareCapabilities } from '../capabilities.js';
 
 declareCapabilities('tickets', { mutationSubcommands: ['create', 'update', 'delete'] });
@@ -15,23 +17,18 @@ export function ticketsCmd(wrap) {
           command: 'list',
           aliases: ['ls'],
           describe: 'List tickets',
-          builder: (y) => y
+          builder: (y) => recordOptions(y)
             .option('query', { type: 'string', describe: 'Encoded query (e.g. "active=true^priority=1")' })
             .option('columns', { alias: ['c', 'fields'], type: 'string', describe: 'Comma-separated columns (e.g. "number,short_description,priority")' })
             .option('limit', { alias: 'l', type: 'number', default: 20, describe: 'Max records' })
             .option('offset', { alias: 'o', type: 'number', default: 0, describe: 'Offset' }),
           handler: wrap(async (argv, app) => {
             const columns = argv.columns ? argv.columns.split(',') : ['number', 'short_description', 'state', 'assigned_to'];
-            const params = new URLSearchParams();
-            params.set('sysparm_limit', String(argv.limit));
-            params.set('sysparm_offset', String(argv.offset));
-            params.set('sysparm_display_value', 'all');
             const fields = resolveFieldsParam(columns);
-            if (fields) params.set('sysparm_fields', fields);
             const q = argv.query ? argv.query + '^ORDERBYDESCsys_updated_on' : 'ORDERBYDESCsys_updated_on';
-            params.set('sysparm_query', q);
-            const records = await app.sdk.list('task', params);
-            const displayRecords = fields ? records.map(r => formatRecordForDisplay(r, columns)) : records;
+            const params = recordListParams({ limit: argv.limit, offset: argv.offset, fields, query: q });
+            const records = await listRecords(app.sdk, { table: 'task', params, displayValues: argv.displayValues });
+            const displayRecords = fields && !argv.displayValues ? records.map(r => formatRecordForDisplay(r, columns)) : records;
             const breadcrumbs = [
               { action: 'create', cmd: 'jsn tickets create -f short_description=New ticket', description: 'Create a new ticket' },
             ];
@@ -63,46 +60,50 @@ export function ticketsCmd(wrap) {
           command: 'show <number>',
           aliases: ['get'],
           describe: 'Show a ticket',
+          builder: y => relatedListOptions(recordOptions(y)),
           handler: wrap(async (argv, app) => {
-            const record = await resolveRecord(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
+            const record = await getRecord(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
+            await enrichRelatedLists(record, { table: 'task', argv, app });
             app.ok(record, { summary: `Ticket ${argv.number}` });
           }),
         })
         .command({
           command: 'create',
           describe: 'Create a new ticket',
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
             .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const recordData = buildRecordPayload(argv);
-            const record = await app.sdk.create('task', recordData);
+            const record = await createRecord(app.sdk, { table: 'task', data: recordData });
             app.ok(record, { summary: `Created ticket ${getStringField(record, 'number')}` });
           }),
         })
         .command({
           command: 'update <number>',
           describe: 'Update a ticket',
-          builder: (y) => y
+          builder: (y) => recordOptions(y, false)
             .option('data', { type: 'string', describe: 'JSON fields' })
             .option('data-file', { type: 'string', describe: 'Read JSON payload from file' })
             .option('data-stdin', { type: 'boolean', describe: 'Read JSON payload from stdin' })
             .option('field', { alias: 'f', type: 'string', array: true, describe: 'Set a field as name=value; repeatable' }),
           handler: wrap(async (argv, app) => {
             const recordData = buildRecordPayload(argv);
-            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
-            const updated = await app.sdk.update('task', sysID, recordData);
+            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
+            const updated = await updateRecord(app.sdk, { table: 'task', record: { sys_id: sysID }, data: recordData });
             app.ok(updated, { summary: `Updated ticket ${argv.number}` });
           }),
         })
         .command({
           command: 'delete <number>',
           describe: 'Delete a ticket',
+          builder: y => recordOptions(y, false).option('force', { type: 'boolean', default: false, describe: 'Skip confirmation after approval' }),
           handler: wrap(async (argv, app) => {
-            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, matchField: 'number', resource: 'Ticket' });
-            await app.sdk.delete('task', sysID);
+            await confirmDelete(app, argv, `Delete ticket ${argv.number}`);
+            const sysID = await resolveSysId(app.sdk, { table: 'task', identifier: argv.number, identifierField: argv.identifierField, displayValues: argv.displayValues, matchField: 'number', resource: 'Ticket' });
+            await deleteRecord(app.sdk, { table: 'task', record: { sys_id: sysID } });
             app.ok({ number: argv.number, message: 'Ticket deleted' }, { summary: `Deleted ticket ${argv.number}` });
           }),
         })

package/src/commands/uipolicies.js

@@ -1,28 +1,3 @@
-import { buildDevCmd } from './_generic.js';
-import { getStringField } from '../helpers.js';
+import { buildProfileCommand } from '../record-profiles.js';
 
-export const uipoliciesCmd = (wrap) => buildDevCmd('uipolicies', 'sys_ui_policy', ['uipolicy', 'up'],
-  ['short_description', 'table', 'sys_class_name', 'active'], wrap, {
-    singular: 'UI policy',
-    scopeValidation: true,
-    onShow: async (record, app) => {
-      const sysID = getStringField(record, 'sys_id') || '';
-      if (!sysID) return;
-      const mp = new URLSearchParams();
-      mp.set('sysparm_query', `ui_policy=${sysID}^ORDERBYorder`);
-      mp.set('sysparm_limit', '100'); mp.set('sysparm_display_value', 'all');
-      mp.set('sysparm_fields', 'name,table,field_name,read_only,mandatory,visible,sys_id');
-      const actions = await app.sdk.list('sys_ui_policy_action', mp);
-      if (actions.length > 0) {
-        console.log(`  Actions (${actions.length}):`);
-        for (const a of actions) {
-          const f = getStringField(a, 'field_name') || '(all fields)';
-          const flags = [];
-          if (getStringField(a, 'mandatory') === 'true') flags.push('mandatory');
-          if (getStringField(a, 'read_only') === 'true') flags.push('read-only');
-          if (getStringField(a, 'visible') === 'false') flags.push('hidden');
-          console.log(`    ${f}  ${flags.length ? `[${flags.join(', ')}]` : ''}`);
-        }
-      }
-    },
-  });
+export const uipoliciesCmd = wrap => buildProfileCommand('uipolicies', wrap);

package/src/commands/updatesets.js

@@ -1,16 +1,20 @@
 import fs from 'node:fs';
+import path from 'node:path';
+import { inspectUpdateSetXML, updateSetFilename, MAX_UPDATE_SET_BYTES } from '../update-set-xml.js';
 import { editor, confirm } from '../prompts.js';
-import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack } from '../helpers.js';
+import { formatRecordForDisplay, getStringField, interactiveList, assertSafeExactMatch, canPrompt, buildRerunCommand, verifyWriteBack, quoteShellArg } 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, errConfirmationRequired } from '../errors.js';
+import { AppError, CodeConfirmationRequired, errAPI, errUsage, errConfirmationRequired } from '../errors.js';
 import { declareCapabilities } from '../capabilities.js';
 import { resolveScope } from './scopes.js';
 import { unwrapSysId } from '../resolve-record.js';
 
 declareCapabilities('updatesets', {
-  mutationSubcommands: ['create', 'set', 'complete', 'ignore', 'parent'],
+  mutationSubcommands: ['create', 'set', 'complete', 'ignore', 'parent', 'import', 'reopen'],
+  mutationContextExemptSubcommands: ['create', 'set', 'import', 'reopen'],
+  localPreviewSubcommands: ['import'],
 });
 
 /**
@@ -27,7 +31,7 @@ export function scopeMismatchWarning(updateSetApp, currentApp) {
   const updateSetAppId = updateSetApp?.value || (typeof updateSetApp === 'string' ? updateSetApp : '');
   if (!updateSetAppId || !currentApp.appSysId || updateSetAppId === currentApp.appSysId) return '';
   const name = updateSetApp?.display_value || updateSetApp;
-  return ` ⚠️ update set is in app "${name}", but current app is "${currentApp.scope}" — changes won't land here. Run: jsn scopes set ${name}`;
+  return ` ⚠️ update set is in app "${name}", but current app is "${currentApp.scope}" — changes may not be captured in this set. Run: jsn scopes set ${quoteShellArg(updateSetAppId)}`;
 }
 
 /** Format a picker label for an update set: "Name [State] (app/scope)". */
@@ -361,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',
@@ -381,7 +386,7 @@ export async function formatUpdateSetDetail(app, record) {
   });
   hints.push({
     action: 'export',
-    cmd: `jsn updatesets export "${name}" --out ${name.replace(/[^a-z0-9]+/gi, '-').toLowerCase()}.xml`,
+    cmd: `jsn updatesets export "${name}" --out ${quoteShellArg(updateSetFilename(name))}`,
     description: 'Export this update set to XML',
   });
   if (!isClosed) {
@@ -424,7 +429,7 @@ export function updateSetsCmd(wrap) {
   return {
     command: 'updatesets [subcommand]',
     aliases: ['updateset', 'us'],
-    describe: 'Manage update sets',
+    describe: 'Manage update sets. Global + Default mutations require approval (--force only after user approval); create/set remain available to select a dedicated capture set. Scope mismatches warn; completed capture sets block writes.',
     builder: (yargs) => {
       return yargs
         .command({
@@ -477,11 +482,14 @@ export function updateSetsCmd(wrap) {
         })
         .command({
           command: 'export <name>',
-          describe: 'Export an update set to XML (raw XML to stdout, or --out file)',
+          describe: 'Export XML without changing state; auto-name a file in a terminal, preserve piped stdout',
           builder: (y) => y
             .positional('name', { describe: 'Update set name', type: 'string' })
-            .option('out', { alias: 'o', type: 'string', describe: 'Write XML to this file instead of stdout' }),
+            .option('out', { alias: 'o', type: 'string', describe: 'Write XML to this file instead of stdout' })
+            .option('out-dir', { type: 'string', describe: 'Write an automatically named XML file in this directory' })
+            .option('stdout', { type: 'boolean', describe: 'Write raw XML to stdout, including in a terminal' }),
           handler: wrap(async (argv, app) => {
+            if ([Boolean(argv.out), Boolean(argv.outDir), Boolean(argv.stdout)].filter(Boolean).length > 1) throw errUsage('Choose one of --out, --out-dir, or --stdout');
             app.requireInstance();
             const record = await resolveUpdateSetByName(app, argv.name);
             const sysID = getStringField(record, 'sys_id');
@@ -503,14 +511,16 @@ export function updateSetsCmd(wrap) {
             }
 
             const bytes = Buffer.byteLength(xml, 'utf-8');
-            if (argv.out) {
-              await fs.promises.writeFile(argv.out, xml);
+            const out = argv.out || (argv.outDir || (process.stdout.isTTY && !argv.stdout && !argv.json && argv.format !== 'json')
+              ? path.join(argv.outDir || '.', updateSetFilename(getStringField(record, 'name'))) : null);
+            if (out) {
+              await fs.promises.writeFile(out, xml, { flag: 'wx' });
               app.ok({
                 update_set: getStringField(record, 'name'),
                 sys_id: sysID,
-                out: argv.out,
+                out,
                 bytes,
-              }, { summary: `Exported update set "${getStringField(record, 'name')}" (${bytes} bytes) to ${argv.out}` });
+              }, { summary: `Exported update set "${getStringField(record, 'name')}" (${bytes} bytes) to ${out}` });
               return;
             }
 
@@ -518,7 +528,7 @@ export function updateSetsCmd(wrap) {
             // (`jsn updatesets export "X" > set.xml`). Only wrap in the JSON
             // envelope when the user explicitly asks for it — auto format
             // detection must NOT hijack the payload for piped consumers.
-            if (argv.json || argv.format === 'json') {
+            if (!argv.stdout && (argv.json || argv.format === 'json')) {
               app.ok({
                 update_set: getStringField(record, 'name'),
                 sys_id: sysID,
@@ -530,6 +540,47 @@ export function updateSetsCmd(wrap) {
             process.stdout.write(xml + (xml.endsWith('\n') ? '' : '\n'));
           }),
         })
+        .command({
+          command: 'import <file>',
+          describe: 'Load XML as a retrieved update set; never preview, commit, or select it automatically',
+          builder: y => y
+            .positional('file', { type: 'string', describe: 'Update set XML export' })
+            .option('dry-run', { type: 'boolean', describe: 'Inspect locally without any instance requests' })
+            .option('yes', { type: 'boolean', describe: 'Confirm loading the displayed XML into the selected target' }),
+          handler: wrap(async (argv, app) => {
+            const stat = await fs.promises.stat(argv.file);
+            if (!stat.isFile() || stat.size > MAX_UPDATE_SET_BYTES) throw errUsage('Expected an XML file no larger than 50 MiB');
+            const xml = await fs.promises.readFile(argv.file, 'utf8');
+            const inspection = inspectUpdateSetXML(xml);
+            const { members, ...summary } = inspection;
+            if (argv.dryRun) return app.ok({ ...summary, members, dry_run: true }, { summary: `XML: ${inspection.name}; ${inspection.count} updates (local inspection only)` });
+            app.requireInstance();
+            const question = `Load "${inspection.name}" (${inspection.count} updates) into ${app.getEffectiveInstance()} as a retrieved update set? This does not commit its changes.`;
+            if (!argv.yes) {
+              if (!canPrompt() || argv.json || argv.get || (argv.format && argv.format !== FormatAuto)) {
+                throw new AppError(CodeConfirmationRequired, `${question} — confirmation required. Pass --yes after approving this target.`,
+                  `Rerun: ${buildRerunCommand(argv, { rerun: ['updatesets', 'import', argv.file, '--yes'] })}`);
+              }
+              if (!await confirm({ message: question, default: false })) return;
+            }
+            const result = await app.sdk.importUpdateSet(xml, inspection, path.basename(argv.file));
+            app.ok({ ...summary, ...result, committed: false }, { summary: `Loaded retrieved update set "${inspection.name}" (${result.count} updates); not committed` });
+          }),
+        })
+        .command({
+          command: 'reopen <name>',
+          describe: 'Explicitly return a complete or ignored local update set to in progress; does not select it',
+          handler: wrap(async (argv, app) => {
+            const target = await resolveCompletionTarget(app, argv.name);
+            const record = await fetchUpdateSetById(app, target.sys_id);
+            const state = String(record?.state?.value ?? record?.state ?? '').toLowerCase();
+            if (!['complete', 'ignore'].includes(state)) throw errUsage(`Cannot reopen an update set in state "${state}"; expected complete or ignore`);
+            await app.sdk.update('sys_update_set', target.sys_id, { state: 'in progress' });
+            const mismatches = await verifyWriteBack(app, 'sys_update_set', target.sys_id, { state: 'in progress' });
+            if (mismatches.length) throw errAPI(200, 'Reopen could not be verified; inspect the update set before retrying');
+            app.ok({ update_set: target.name, sys_id: target.sys_id, state: 'in progress' }, { summary: `Reopened update set: ${target.name}` });
+          }),
+        })
         .command({
           command: 'set [name]',
           describe: 'Set the current update set (interactive picker with scope when run bare)',
@@ -737,6 +788,8 @@ export function updateSetsCmd(wrap) {
         console.log('  list           List update sets (shows scope)');
         console.log('  show <name>    Show an update set (type counts + risky items)');
         console.log('  export <name>  Export an update set to XML (stdout or --out)');
+        console.log('  import <file>  Load retrieved XML (--dry-run inspects locally; --yes confirms)');
+        console.log('  reopen <name>  Explicitly return a closed set to in progress');
         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 [name] Complete a named or current set with --notes (editor when omitted)');