@jacebenson/jsn 4.3.13 → 4.4.0-dev.113.1

package/src/midserver-remote.js

@@ -0,0 +1,221 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
+import process from 'node:process';
+
+const FILE = '.jsn-mid-remote.json';
+const PREFIX = 'io.jsn.mid';
+const SSH_OPTIONS = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', '-o', 'RemoteCommand=none', '-o', 'RequestTTY=no', '--'];
+
+export function validateRemoteTarget(target) {
+  if (typeof target !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,252}$/.test(target)) throw new Error('Use a configured SSH alias containing only letters, numbers, dots, underscores or dashes');
+  return target;
+}
+
+function defaultRun(command, args, options) {
+  const { mergeStderr, ...settings } = options;
+  const execution = { ...settings, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 4 * 1024 * 1024 };
+  if (!mergeStderr) return execFileSync(command, args, execution);
+  const result = spawnSync(command, args, execution);
+  if (result.error || result.status !== 0) throw new Error('Remote log snapshot failed');
+  return `${result.stdout || ''}${result.stderr || ''}`;
+}
+
+function sshArgs(target, args) {
+  validateRemoteTarget(target);
+  // OpenSSH joins the command for the remote shell. Every argument is constrained,
+  // including format expressions; secrets and manifests travel only on stdin.
+  if (args.some(arg => typeof arg !== 'string' || !/^[A-Za-z0-9_./:{}=,@+-]+$/.test(arg))) throw new Error('Unsafe remote Docker argument');
+  return [...SSH_OPTIONS, target, `docker ${args.join(' ')}`];
+}
+
+function docker(target, args, { run = defaultRun, input, timeout = 30000, signal, mergeStderr = false } = {}) {
+  const commandArgs = sshArgs(target, args);
+  try { return String(run('ssh', commandArgs, { input, timeout, signal, mergeStderr }) || '').trim(); }
+  catch { throw new Error(`Remote Docker ${args[0]} failed; inspect the selected target and retained local metadata`); }
+}
+
+function probe(target, options) {
+  const platform = docker(target, ['info', '--format', '{{.OSType}}/{{.Architecture}}'], options);
+  if (!/^linux\/(amd64|x86_64)$/.test(platform)) throw new Error('Remote MID containers require a Linux amd64 Docker engine');
+  docker(target, ['compose', 'version'], options);
+  const engineId = docker(target, ['info', '--format', '{{.ID}}'], options);
+  if (!engineId) throw new Error('Remote Docker did not report an engine ID');
+  return engineId;
+}
+
+function save(directory, metadata) {
+  fs.writeFileSync(path.join(directory, FILE), `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+  fs.chmodSync(path.join(directory, FILE), 0o600);
+}
+
+function load(directory) {
+  const dir = fs.lstatSync(directory);
+  const file = fs.lstatSync(path.join(directory, FILE));
+  if (!dir.isDirectory() || dir.isSymbolicLink() || !file.isFile() || file.isSymbolicLink() || (dir.mode & 0o077) || (file.mode & 0o077)) throw new Error('Remote MID metadata directory and file must be private and must not be symlinks');
+  const metadata = JSON.parse(fs.readFileSync(path.join(directory, FILE), 'utf8'));
+  validateRemoteTarget(metadata.target);
+  if (metadata.version !== 1 || !/^[a-f0-9-]{36}$/.test(metadata.owner)) throw new Error('Invalid remote MID ownership metadata');
+  for (const key of ['project', 'container', 'volume', 'image', ...(metadata.network ? ['network'] : [])]) if (!/^[a-z0-9][a-z0-9_.:-]+$/.test(metadata[key])) throw new Error('Invalid remote MID resource metadata');
+  return metadata;
+}
+
+function labels(metadata) {
+  return { [`${PREFIX}.owner`]: metadata.owner, [`${PREFIX}.instance`]: metadata.instanceURL, [`${PREFIX}.target`]: metadata.target, [`${PREFIX}.name`]: metadata.name };
+}
+
+function checkEngine(metadata, options) {
+  if (probe(metadata.target, options) !== metadata.engineId) throw new Error('SSH target now selects a different Docker engine; refusing lifecycle operation');
+}
+
+function inspect(metadata, kind, resource, options) {
+  let value;
+  try { value = JSON.parse(docker(metadata.target, [kind, 'inspect', resource], options))[0]; } catch { throw new Error(`Cannot verify owned remote ${kind}; no destructive action taken`); }
+  const actual = value?.Config?.Labels || value?.Labels;
+  if (!actual || Object.entries(labels(metadata)).some(([key, expected]) => actual[key] !== expected)) throw new Error(`Remote ${kind} ownership mismatch; refusing operation`);
+  return value;
+}
+
+export function prepareRemoteMidServer({ target, instanceURL, name, directory, platform = process.platform, ...options }) {
+  if (platform === 'win32') throw new Error('Remote MID management requires a POSIX controller to enforce private local metadata permissions; Windows Docker hosts remain supported over SSH');
+  validateRemoteTarget(target);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name || '')) throw new Error('Invalid MID Server name');
+  const url = new URL(instanceURL);
+  if (url.protocol !== 'https:' || url.username || url.password || url.search || url.hash || url.pathname !== '/') throw new Error('Use an HTTPS instance origin without credentials');
+  if (fs.existsSync(directory)) throw new Error('Remote MID local directory already exists; refusing to overwrite or adopt');
+  const owner = randomUUID();
+  const project = `jsn-mid-${owner}`;
+  const metadata = { version: 1, target, instanceURL: url.origin, name, owner, project, container: project, image: `${project}:local`, volume: `${project}-export`, network: `${project}-network`, engineId: probe(target, options), state: 'prepared' };
+  fs.mkdirSync(directory, { recursive: false, mode: 0o700 });
+  fs.chmodSync(directory, 0o700);
+  save(directory, metadata);
+  return metadata;
+}
+
+export function buildRemoteMidManifest(metadata, { username, password }) {
+  if (!username || !password) throw new Error('MID username and password are required');
+  const ownership = labels(metadata);
+  const literal = value => String(value).replaceAll('$', () => '$$');
+  return { services: { mid: { container_name: metadata.container, image: metadata.image, pull_policy: 'never', restart: 'unless-stopped', labels: ownership, environment: { MID_INSTANCE_URL: `${metadata.instanceURL}/`, MID_INSTANCE_USERNAME: literal(username), MID_INSTANCE_PASSWORD: literal(password), MID_SERVER_NAME: literal(metadata.name) }, volumes: [`${metadata.volume}:/opt/snc_mid_server/agent/export`], networks: ['mid'] } }, volumes: { [metadata.volume]: { name: metadata.volume, labels: ownership } }, networks: { mid: { name: metadata.network, labels: ownership } } };
+}
+
+function resources(metadata, options) {
+  const checks = [ ['container', ['container', 'ls', '-a', '--filter', `name=${metadata.container}`, '--format', '{{.Names}}'], metadata.container], ['volume', ['volume', 'ls', '--filter', `name=${metadata.volume}`, '--format', '{{.Name}}'], metadata.volume], ['image', ['image', 'ls', '--filter', `reference=${metadata.image}`, '--format', '{{.Repository}}:{{.Tag}}'], metadata.image] ];
+  if (metadata.network) checks.push(['network', ['network', 'ls', '--filter', `name=${metadata.network}`, '--format', '{{.Name}}'], metadata.network]);
+  return checks.filter(([, args, resource]) => docker(metadata.target, args, options).split(/\r?\n/).includes(resource)).map(([kind]) => kind);
+}
+
+function absent(metadata, options) {
+  if (resources(metadata, options).length) throw new Error('Remote resources already exist; refusing to overwrite or adopt');
+}
+
+export function installRemoteMidServer({ directory, context, username, password, ...options }) {
+  const metadata = load(directory);
+  if (metadata.state !== 'prepared') throw new Error('Install requires a fresh prepared deployment; retained partial deployments must be inspected and removed explicitly');
+  if (!Buffer.isBuffer(context) || context.length === 0) throw new Error('An official recipe tar build context is required');
+  const manifest = buildRemoteMidManifest(metadata, { username, password });
+  checkEngine(metadata, options);
+  absent(metadata, options);
+  metadata.state = 'building'; save(directory, metadata);
+  try {
+    const buildLabels = Object.entries(labels(metadata)).flatMap(([key, value]) => ['--label', `${key}=${value}`]);
+    docker(metadata.target, ['build', ...buildLabels, '--tag', metadata.image, '-'], { ...options, input: context, timeout: 1200000 });
+    inspect(metadata, 'image', metadata.image, options);
+    metadata.state = 'deploying'; save(directory, metadata);
+    docker(metadata.target, ['compose', '-p', metadata.project, '-f', '-', 'up', '-d'], { ...options, input: JSON.stringify(manifest), timeout: 300000 });
+    inspect(metadata, 'container', metadata.container, options);
+    inspect(metadata, 'volume', metadata.volume, options);
+    inspect(metadata, 'network', metadata.network, options);
+    metadata.state = 'running'; save(directory, metadata);
+    return metadata;
+  } catch (error) { metadata.state = 'uncertain'; save(directory, metadata); throw error; }
+}
+
+export function inspectRemoteMidServer({ directory, ...options }) {
+  const metadata = load(directory); checkEngine(metadata, options);
+  const container = inspect(metadata, 'container', metadata.container, options);
+  return { ...metadata, status: container.State?.Status || 'unknown' };
+}
+
+function lifecycle(operation, { directory, ...options }) {
+  const metadata = load(directory); checkEngine(metadata, options);
+  inspect(metadata, 'container', metadata.container, options);
+  try { docker(metadata.target, ['container', operation, metadata.container], options); }
+  catch (error) { metadata.state = 'uncertain'; save(directory, metadata); throw error; }
+  metadata.state = operation === 'start' ? 'running' : 'stopped'; save(directory, metadata);
+  return metadata;
+}
+export const startRemoteMidServer = options => lifecycle('start', options);
+export const stopRemoteMidServer = options => lifecycle('stop', options);
+
+export function logsRemoteMidServer({ directory, tail = 100, ...options }) {
+  if (!Number.isInteger(tail) || tail < 1 || tail > 10000) throw new Error('Log tail must be between 1 and 10000');
+  const metadata = load(directory); checkEngine(metadata, options);
+  inspect(metadata, 'container', metadata.container, options);
+  return docker(metadata.target, ['container', 'logs', '--tail', String(tail), metadata.container], { ...options, mergeStderr: true });
+}
+
+export async function followRemoteMidServer({ directory, tail = 100, spawnImpl = spawn, stdout = process.stdout, stderr = process.stderr, signalSource = process, ...options }) {
+  if (!Number.isInteger(tail) || tail < 1 || tail > 10000) throw new Error('Log tail must be between 1 and 10000');
+  const metadata = load(directory); checkEngine(metadata, options);
+  inspect(metadata, 'container', metadata.container, options);
+  const args = sshArgs(metadata.target, ['container', 'logs', '--follow', '--tail', String(tail), metadata.container]);
+  return new Promise((resolve, reject) => {
+    let child;
+    let cancelled = false;
+    let timer;
+    let settled = false;
+    const cleanup = () => {
+      signalSource.removeListener('SIGINT', cancel);
+      clearTimeout(timer);
+      child?.stdout?.unpipe(stdout);
+      child?.stderr?.unpipe(stderr);
+      child?.removeListener('error', failed);
+      child?.removeListener('close', closed);
+    };
+    const finish = error => {
+      if (settled) return;
+      settled = true; cleanup();
+      if (error) reject(new Error('Remote Docker log viewer failed; the container was not stopped'));
+      else resolve({ cancelled });
+    };
+    const failed = () => finish(true);
+    const closed = code => finish(!cancelled && code !== 0);
+    const cancel = () => {
+      if (cancelled || settled) return;
+      cancelled = true;
+      child.kill('SIGINT');
+      timer = setTimeout(() => { child.kill('SIGKILL'); finish(false); }, 2000);
+      timer.unref?.();
+    };
+    try {
+      child = spawnImpl('ssh', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+      child.on('error', failed);
+      child.on('close', closed);
+      child.stdout?.pipe(stdout, { end: false });
+      child.stderr?.pipe(stderr, { end: false });
+      signalSource.on('SIGINT', cancel);
+    } catch { finish(true); }
+  });
+}
+
+export function removeRemoteMidServer({ directory, ...options }) {
+  const metadata = load(directory); checkEngine(metadata, options);
+  // A partial install may have only an image or volume. Verify every present
+  // resource before deleting any, and preserve metadata for retries/diagnosis.
+  const present = resources(metadata, options);
+  for (const kind of present) inspect(metadata, kind, metadata[kind], options);
+  metadata.state = 'removing'; save(directory, metadata);
+  try {
+    if (present.includes('container')) {
+      docker(metadata.target, ['container', 'stop', metadata.container], options);
+      docker(metadata.target, ['container', 'rm', metadata.container], options);
+    }
+    if (present.includes('volume')) docker(metadata.target, ['volume', 'rm', metadata.volume], options);
+    if (present.includes('network')) docker(metadata.target, ['network', 'rm', metadata.network], options);
+    if (present.includes('image')) docker(metadata.target, ['image', 'rm', metadata.image], options);
+  } catch (error) { metadata.state = 'uncertain'; save(directory, metadata); throw error; }
+  metadata.state = 'removed'; save(directory, metadata);
+  return metadata;
+}

package/src/midserver-windows-remote.js

@@ -0,0 +1,318 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import process from 'node:process';
+import { randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { validateRemoteTarget } from './midserver-remote.js';
+import { buildMidZipUrl } from './midserver-direct.js';
+
+const FILE = '.jsn-mid-windows-remote.json';
+const SSH = ['-T', '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', '-o', 'RemoteCommand=none', '-o', 'RequestTTY=no', '--'];
+const PHASES = new Set(['initialization', 'validate', 'reserve-directory', 'protect-directory', 'download', 'verify-archive', 'inspect-archive', 'extract', 'vendor-contract', 'configure', 'register-service', 'verify-service', 'enforce-permissions', 'remove-files', 'recover-file-acl', 'stop-owned-processes']);
+const HEADER = `$ErrorActionPreference='Stop'; $ProgressPreference='SilentlyContinue'; $phase='initialization';
+trap { [Console]::Error.WriteLine(('JSN_PHASE_FAILED:' + $phase)); exit 1 }
+$p=([Console]::In.ReadToEnd() | ConvertFrom-Json)
+function Result($v) { [Console]::Out.WriteLine(('JSN_RESULT:' + ($v | ConvertTo-Json -Compress -Depth 8))) }
+function Assert-Admin { if ($env:OS -ne 'Windows_NT') { throw 'Windows required' }; $i=[Security.Principal.WindowsIdentity]::GetCurrent(); $principal=New-Object Security.Principal.WindowsPrincipal($i); if (!$principal.IsInRole([Security.Principal.WindowsBuiltInRole]::Administrator)) { throw 'Elevated service installation rights required' } }
+function Assert-Owned {
+  Assert-Admin
+  if (!(Test-Path -LiteralPath $p.remoteDirectory -PathType Container)) { throw 'Owned directory missing' }
+  $item=Get-Item -LiteralPath $p.remoteDirectory
+  if ($item.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Reparse point forbidden' }
+  $marker=Get-Content -Raw -LiteralPath (Join-Path $p.remoteDirectory '.jsn-owner.json') | ConvertFrom-Json
+  if ($marker.owner -ne $p.owner -or $marker.serviceName -ne $p.serviceName -or $marker.instanceURL -ne $p.instanceURL -or $marker.name -ne $p.name) { throw 'Ownership mismatch' }
+}
+function Owned-Service {
+  $s=Get-CimInstance Win32_Service -Filter ('Name="' + $p.serviceName + '"')
+  if ($s) {
+    $expected=[IO.Path]::GetFullPath((Join-Path $p.remoteDirectory 'agent\\bin\\wrapper-windows-x86-64.exe'))
+    $command=[regex]::Match($s.PathName,'^\\s*(?:"([^"\\r\\n]+)"|(.+?\\.exe))(?:\\s|$)',[Text.RegularExpressions.RegexOptions]::IgnoreCase)
+    if (!$command.Success) { throw 'Service binary ownership mismatch' }
+    $binary=$command.Groups[1].Value; if (!$binary) { $binary=$command.Groups[2].Value }
+    if ([IO.Path]::GetFullPath($binary) -ne $expected) { throw 'Service binary ownership mismatch' }
+    if ($s.StartName -ne 'NT AUTHORITY\\LocalService' -and $s.StartName -ne 'LocalService') { throw 'Unexpected runtime service account' }
+  }
+  return $s
+}
+`;
+
+function remote(target, script, payload, { run = execFileSync, timeout = 30000 } = {}) {
+  validateRemoteTarget(target);
+  const bootstrap = `$ErrorActionPreference='Stop'; try { [Console]::InputEncoding=New-Object Text.UTF8Encoding($false); [Console]::OutputEncoding=New-Object Text.UTF8Encoding($false); $source=[Text.Encoding]::UTF8.GetString([Convert]::FromBase64String([Console]::In.ReadLine())); & ([ScriptBlock]::Create($source)) } catch { [Console]::Error.WriteLine('Remote MID bootstrap failed'); exit 1 }`;
+  const encoded = Buffer.from(bootstrap, 'utf16le').toString('base64');
+  const input = `${Buffer.from(HEADER + script, 'utf8').toString('base64')}\n${JSON.stringify(payload)}`;
+  let output;
+  try { output = String(run('ssh', [...SSH, target, `powershell.exe -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ${encoded}`], { input, timeout, encoding: 'utf8', maxBuffer: 4 * 1024 * 1024, stdio: ['pipe', 'pipe', 'pipe'] })); }
+  catch (error) {
+    const candidate = String(error.stderr || '').split(/\r?\n/).findLast(line => /^JSN_PHASE_FAILED:[a-z-]+$/.test(line));
+    const phase = candidate?.slice('JSN_PHASE_FAILED:'.length);
+    const failure = new Error(`Remote Windows MID operation failed${PHASES.has(phase) ? ` during ${phase}` : ''}; inspect retained ownership metadata and service status`);
+    if (PHASES.has(phase)) failure.phase = phase;
+    throw failure;
+  }
+  const line = output.split(/\r?\n/).findLast(value => value.startsWith('JSN_RESULT:'));
+  if (!line) throw new Error('Remote Windows MID returned no verified result');
+  try { return JSON.parse(line.slice('JSN_RESULT:'.length)); } catch { throw new Error('Invalid remote Windows MID result'); }
+}
+
+function save(directory, metadata) {
+  fs.writeFileSync(path.join(directory, FILE), `${JSON.stringify(metadata, null, 2)}\n`, { mode: 0o600 });
+  fs.chmodSync(path.join(directory, FILE), 0o600);
+}
+function load(directory) {
+  const dir = fs.lstatSync(directory); const file = fs.lstatSync(path.join(directory, FILE));
+  if (!dir.isDirectory() || dir.isSymbolicLink() || !file.isFile() || file.isSymbolicLink() || (dir.mode & 0o077) || (file.mode & 0o077)) throw new Error('Windows MID local metadata must be private');
+  const m = JSON.parse(fs.readFileSync(path.join(directory, FILE), 'utf8'));
+  validateRemoteTarget(m.target);
+  if (m.version !== 1 || !/^[a-f0-9-]{36}$/.test(m.owner) || m.serviceName !== `jsn-mid-${m.owner}` || !/^[A-Z]:\\[A-Za-z0-9 _.-]+(?:\\[A-Za-z0-9 _.-]+)*$/i.test(m.remoteDirectory) || !m.remoteDirectory.endsWith(`\\${m.owner}`)) throw new Error('Invalid Windows MID ownership metadata');
+  return m;
+}
+
+export function prepareWindowsRemoteMidServer({ target, instanceURL, name, directory, platform = process.platform, ...options }) {
+  if (platform === 'win32') throw new Error('A POSIX controller is required for private local metadata');
+  validateRemoteTarget(target);
+  if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name || '')) throw new Error('Invalid MID name');
+  const url = new URL(instanceURL);
+  if (url.protocol !== 'https:' || url.username || url.password || url.pathname !== '/' || url.search || url.hash) throw new Error('Use an HTTPS instance origin');
+  if (fs.existsSync(directory)) throw new Error('Local deployment directory already exists; no adoption or overwrite');
+  const owner = randomUUID(); const serviceName = `jsn-mid-${owner}`;
+  const probe = remote(target, `Assert-Admin
+if ([Environment]::Is64BitOperatingSystem -ne $true) { throw 'x64 Windows required' }
+$base=Join-Path $env:ProgramData 'jsn-mid'
+$remoteDirectory=Join-Path $base $p.owner
+if (Test-Path -LiteralPath $remoteDirectory) { throw 'Deployment directory exists' }
+if (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { throw 'Service already exists' }
+Result @{remoteDirectory=$remoteDirectory; elevated=$true; platform='windows-x64'}`, { owner, serviceName }, options);
+  if (!probe.elevated || probe.platform !== 'windows-x64' || !probe.remoteDirectory?.endsWith(`\\${owner}`)) throw new Error('Windows preflight failed');
+  const metadata = { version: 1, target, owner, serviceName, instanceURL: url.origin, name, remoteDirectory: probe.remoteDirectory, state: 'prepared', runtimeAccount: 'NT AUTHORITY\\LocalService' };
+  fs.mkdirSync(directory, { mode: 0o700 }); fs.chmodSync(directory, 0o700); save(directory, metadata);
+  return metadata;
+}
+
+const INSTALL = String.raw`$phase='validate'; Assert-Admin
+if (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { throw 'Service already exists; no adoption' }
+if (Test-Path -LiteralPath $p.remoteDirectory) { throw 'Directory already exists; no adoption' }
+$phase='reserve-directory'
+$parent=Split-Path -Parent $p.remoteDirectory
+if (!(Test-Path -LiteralPath $parent)) { $null=New-Item -ItemType Directory -Path $parent }
+$ancestor=Get-Item -LiteralPath $parent
+while ($ancestor) { if ($ancestor.Attributes -band [IO.FileAttributes]::ReparsePoint) { throw 'Reparse ancestor forbidden' }; $ancestor=$ancestor.Parent }
+$null=New-Item -ItemType Directory -Path $p.remoteDirectory
+$phase='protect-directory'
+$sid=[Security.Principal.WindowsIdentity]::GetCurrent().User
+$acl=New-Object Security.AccessControl.DirectorySecurity
+$acl.SetOwner($sid); $acl.SetAccessRuleProtection($true,$false)
+foreach ($id in @($sid.Value,'S-1-5-18','S-1-5-32-544') | Select-Object -Unique) {
+  $who=New-Object Security.Principal.SecurityIdentifier($id)
+  $acl.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule($who,'FullControl','ContainerInherit,ObjectInherit','None','Allow')))
+}
+$localService=New-Object Security.Principal.SecurityIdentifier('S-1-5-19')
+$acl.AddAccessRule((New-Object Security.AccessControl.FileSystemAccessRule($localService,'Modify','ContainerInherit,ObjectInherit','None','Allow')))
+Set-Acl -LiteralPath $p.remoteDirectory -AclObject $acl
+$actual=Get-Acl -LiteralPath $p.remoteDirectory
+if (!$actual.AreAccessRulesProtected) { throw 'ACL protection failed' }
+$allowed=@($sid.Value,'S-1-5-18','S-1-5-32-544','S-1-5-19')
+foreach ($r in $actual.Access) { if ($r.AccessControlType -ne 'Allow' -or $r.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value -notin $allowed) { throw 'Unexpected ACL rule' } }
+$marker=@{owner=$p.owner;serviceName=$p.serviceName;instanceURL=$p.instanceURL;name=$p.name}
+$marker | ConvertTo-Json -Compress | Set-Content -Encoding UTF8 -LiteralPath (Join-Path $p.remoteDirectory '.jsn-owner.json')
+$phase='download'
+$archive=Join-Path $p.remoteDirectory '.download.zip'
+if ($p.archivePath) { Copy-Item -LiteralPath $p.archivePath -Destination $archive } else { [Net.ServicePointManager]::SecurityProtocol=[Net.SecurityProtocolType]::Tls12; Invoke-WebRequest -UseBasicParsing -Uri $p.archiveURL -OutFile $archive -TimeoutSec 600 }
+$phase='verify-archive'
+if ((Get-Item -LiteralPath $archive).Length -gt 1GB) { throw 'Archive too large' }
+$archiveHash=(Get-FileHash -Algorithm SHA256 -LiteralPath $archive).Hash
+if ($p.archiveSha256 -and $archiveHash -ne $p.archiveSha256) { throw 'Archive hash mismatch' }
+$phase='inspect-archive'
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+$zip=[IO.Compression.ZipFile]::OpenRead($archive)
+try {
+  if ($zip.Entries.Count -gt 20000) { throw 'Too many archive entries' }
+  $total=0; $seen=@{}
+  foreach ($entry in $zip.Entries) {
+    $entryName=$entry.FullName
+    if ($entryName.Contains('\') -or $entryName.StartsWith('/') -or $entryName.Contains(':')) { throw 'Unsafe archive path' }
+    $parts=$entryName.TrimEnd('/').Split('/')
+    if ($parts[0] -notin @('agent','META-INF')) { throw 'Unexpected archive root' }
+    foreach ($part in $parts) { if (!$part -or $part -eq '.' -or $part -eq '..' -or $part -match '[<>"|?*\x00-\x1f]' -or $part -match '[. ]$' -or $part -match '^(?i:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)') { throw 'Unsafe archive entry' } }
+    $key=$entryName.TrimEnd('/').ToLowerInvariant(); if ($seen.ContainsKey($key)) { throw 'Duplicate archive entry' }; $seen[$key]=$true
+    $mode=($entry.ExternalAttributes -shr 16) -band 0xF000
+    if ($mode -ne 0 -and $mode -ne 0x8000 -and $mode -ne 0x4000) { throw 'Archive links forbidden' }
+    $total+=$entry.Length; if ($total -gt 2GB) { throw 'Expanded archive too large' }
+  }
+} finally { $zip.Dispose() }
+$phase='extract'
+Expand-Archive -LiteralPath $archive -DestinationPath $p.remoteDirectory
+Remove-Item -LiteralPath $archive
+$phase='vendor-contract'
+$agent=Join-Path $p.remoteDirectory 'agent'
+foreach ($relative in @('config.xml','conf\wrapper.conf','conf\wrapper-override.conf','bin\mid.bat','bin\wrapper-windows-x86-64.exe','jre\bin\java.exe')) { if (!(Test-Path -LiteralPath (Join-Path $agent $relative) -PathType Leaf)) { throw 'Unsupported vendor ZIP layout' } }
+$batch=Get-Content -Raw -LiteralPath (Join-Path $agent 'bin\mid.bat')
+$wrapper=Get-Content -Raw -LiteralPath (Join-Path $agent 'conf\wrapper.conf')
+if ($batch -notmatch '\[install\]' -or $batch -notmatch '\[remove\]' -or $batch -notmatch '(?m)^\s*%_WRAPPER_EXE% -i ' -or $batch -notmatch '(?m)^\s*%_WRAPPER_EXE% -r ' -or $wrapper -notmatch '(?m)^wrapper.java.command=jre/bin/java' -or $wrapper -notmatch '(?m)^#include ../conf/wrapper-override.conf') { throw 'Unsupported vendor service contract' }
+$modules=@(Get-ChildItem -LiteralPath $agent -Filter 'EnforceFilePermissions.psm1' -File -Recurse)
+if ($modules.Count -ne 1 -or (Get-Content -Raw -LiteralPath $modules[0].FullName) -notmatch 'function\s+enforcePerms\s*\{') { throw 'Unsupported vendor permission enforcement contract' }
+$phase='configure'
+$config=Join-Path $agent 'config.xml'
+$xml=New-Object Xml.XmlDocument; $xml.XmlResolver=$null; $xml.PreserveWhitespace=$true; $xml.Load($config)
+if ($xml.DocumentElement.Name -ne 'parameters') { throw 'Unsupported configuration XML root' }
+$values=@{url=($p.instanceURL+'/');'mid.instance.username'=$p.username;'mid.instance.password'=$p.password;name=$p.name;'mid.windows_host.file_permissions.allow_list'='S-1-5-19'}
+foreach ($key in @($values.Keys)) {
+  $nodes=@($xml.SelectNodes('/parameters/parameter') | Where-Object { $_.GetAttribute('name') -eq $key })
+  if ($nodes.Count -gt 1) { throw 'Duplicate configuration parameter' }
+  if ($nodes.Count -eq 0) { $node=$xml.CreateElement('parameter'); $node.SetAttribute('name',$key); $null=$xml.DocumentElement.AppendChild($node) } else { $node=$nodes[0] }
+  if ($key -eq 'mid.windows_host.file_permissions.allow_list') {
+    $entries=@($node.GetAttribute('value').Split(',') | ForEach-Object { $_.Trim() } | Where-Object { $_ })
+    $values[$key]=(@($entries + 'S-1-5-19') | Select-Object -Unique) -join ','
+  }
+  $node.SetAttribute('value',[string]$values[$key])
+  if ($key -eq 'mid.instance.password' -and !$node.HasAttribute('secure')) { $node.SetAttribute('secure','true') }
+}
+$xml.Save($config)
+$override=Join-Path $agent 'conf\wrapper-override.conf'
+$text=Get-Content -Raw -LiteralPath $override
+$text=[regex]::Replace($text,'(?m)^wrapper\.(?:name|displayname|ntservice\.(?:account|account\.prompt|password|password\.prompt|starttype|permissions\.1\.(?:account|allow|service)))=.*\r?$','')
+$text+="
+wrapper.name=$($p.serviceName)
+wrapper.displayname=ServiceNow MID $($p.serviceName)
+wrapper.ntservice.account=NT AUTHORITY\LocalService
+wrapper.ntservice.password=
+wrapper.ntservice.account.prompt=FALSE
+wrapper.ntservice.password.prompt=FALSE
+wrapper.ntservice.starttype=AUTO_START
+wrapper.ntservice.permissions.1.account=NT AUTHORITY\LocalService
+wrapper.ntservice.permissions.1.allow=START, STOP
+wrapper.ntservice.permissions.1.service=$($p.serviceName)
+"
+[IO.File]::WriteAllText($override,$text,(New-Object Text.UTF8Encoding($false)))
+$phase='register-service'
+Push-Location $agent
+try { & cmd.exe /d /s /c 'bin\mid.bat install' 2>&1 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Vendor install failed' } } finally { Pop-Location }
+$phase='verify-service'
+Assert-Owned; $s=Owned-Service; if (!$s) { throw 'Service registration missing' }
+if ($s.StartMode -ne 'Auto') { throw 'Service automatic startup was not configured' }
+$phase='enforce-permissions'
+Import-Module -Name $modules[0].FullName -Force -ErrorAction Stop
+$enforce=Get-Command -Name enforcePerms -CommandType Function -ErrorAction Stop
+if ($enforce.Module.Path -ne $modules[0].FullName) { throw 'Wrong enforcement module' }
+# The vendor allow-list includes a second service principal when USERDOMAIN
+# resolves it. Match the LocalService runtime context so its saved list/hash is
+# identical on startup; let the unmodified vendor module compute the hash.
+$previousUserDomain=$env:USERDOMAIN
+try {
+  $env:USERDOMAIN=($s.StartName -split '\\',2)[0]
+  enforcePerms -folder $agent -serviceName $p.serviceName -debug $false -additionWhiteListedGroups $values['mid.windows_host.file_permissions.allow_list'] | Out-Null
+} finally { $env:USERDOMAIN=$previousUserDomain }
+$serviceRules=@((Get-Acl -LiteralPath $agent).Access | Where-Object { $_.AccessControlType -eq 'Allow' -and $_.IdentityReference.Translate([Security.Principal.SecurityIdentifier]).Value -eq 'S-1-5-19' -and ($_.FileSystemRights -band [Security.AccessControl.FileSystemRights]::FullControl) -eq [Security.AccessControl.FileSystemRights]::FullControl })
+if (!$serviceRules.Count) { throw 'Runtime account lacks enforced permissions' }
+foreach ($receipt in @('fileperm.aclsave','fileperm.grphash')) { if (!(Test-Path -LiteralPath (Join-Path (Join-Path $agent 'etc') $receipt) -PathType Leaf)) { throw 'Vendor enforcement receipt missing' } }
+Result @{status=$s.State;runtimeAccount=$s.StartName;serviceRegistered=$true;archiveSha256=$archiveHash;startMode=$s.StartMode}
+`;
+
+export function installWindowsRemoteMidServer({ directory, releaseName, username, password, archivePath, archiveSha256, ...options }) {
+  const m = load(directory);
+  if (m.state !== 'prepared') throw new Error('Install requires a fresh prepared deployment');
+  if (!username || !password || [...String(username) + String(password)].some(char => char.codePointAt(0) < 32 && !['\t', '\n', '\r'].includes(char))) throw new Error('Valid MID credentials are required');
+  const archiveURL = buildMidZipUrl(releaseName, 'win32');
+  if (archiveSha256 && !/^[a-f0-9]{64}$/i.test(archiveSha256)) throw new Error('Invalid archive SHA256');
+  if (archivePath && (!archiveSha256 || !/^[A-Z]:\\[A-Za-z0-9 _.-]+(?:\\[A-Za-z0-9 _.-]+)*$/i.test(archivePath))) throw new Error('Cached remote archive requires an absolute safe path and inspected SHA256');
+  m.state = 'installing'; m.releaseName = releaseName; save(directory, m);
+  try {
+    const result = remote(m.target, INSTALL, { ...m, archiveURL, username, password, archivePath, archiveSha256 }, { ...options, timeout: 1200000 });
+    if (!result.serviceRegistered || !['NT AUTHORITY\\LocalService', 'LocalService'].includes(result.runtimeAccount)) throw new Error('Service installation was not verified under LocalService');
+    if (result.startMode !== 'Auto') throw new Error('Service automatic startup was not verified');
+    if (!/^[a-f0-9]{64}$/i.test(result.archiveSha256 || '')) throw new Error('Archive hash verification result missing');
+    m.startMode = result.startMode; m.archiveSha256 = result.archiveSha256.toLowerCase(); m.state = 'installed'; save(directory, m); return m;
+  } catch (error) { m.state = 'uncertain'; if (error.phase) m.failedPhase = error.phase; save(directory, m); throw error; }
+}
+
+export function removeWindowsRemoteMidServer({ directory, ...options }) {
+  const m = load(directory);
+  m.state = 'removing'; save(directory, m);
+  try {
+    remote(m.target, String.raw`Assert-Owned; $s=Owned-Service
+if ($s) {
+  Stop-Service -Name $p.serviceName -ErrorAction Stop
+  (Get-Service -Name $p.serviceName).WaitForStatus('Stopped',[TimeSpan]::FromSeconds(60))
+  $null=Owned-Service
+  $agent=Join-Path $p.remoteDirectory 'agent'
+  Push-Location $agent
+  try { & cmd.exe /d /s /c 'bin\mid.bat remove' 2>&1 | Out-Null; if ($LASTEXITCODE -ne 0) { throw 'Vendor removal failed' } } finally { Pop-Location }
+  $deadline=(Get-Date).AddSeconds(30)
+  while (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { if ((Get-Date) -gt $deadline) { throw 'Service still registered' }; Start-Sleep -Milliseconds 500 }
+}
+Assert-Owned
+$links=@(Get-ChildItem -LiteralPath $p.remoteDirectory -Force -Recurse | Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+if ($links.Count) { throw 'Refusing recursive cleanup through reparse points' }
+$phase='stop-owned-processes'
+if (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { throw 'Service still registered; refusing process cleanup' }
+$ownedBinaries=@('agent\bin\wrapper-windows-x86-64.exe','agent\bin\wrapper.exe','agent\jre\bin\java.exe') | ForEach-Object { [IO.Path]::GetFullPath((Join-Path $p.remoteDirectory $_)) }
+$candidates=@(Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -and [IO.Path]::GetFullPath($_.ExecutablePath) -in $ownedBinaries })
+foreach ($candidate in $candidates) {
+  $current=Get-CimInstance Win32_Process -Filter ('ProcessId=' + [uint32]$candidate.ProcessId)
+  if (!$current) { continue }
+  if (!$current.ExecutablePath -or [IO.Path]::GetFullPath($current.ExecutablePath) -notin $ownedBinaries -or $current.ExecutablePath -ne $candidate.ExecutablePath -or $current.CreationDate -ne $candidate.CreationDate) { throw 'Owned process identity changed; refusing to kill reused PID' }
+  $process=Get-Process -Id $current.ProcessId -ErrorAction Stop
+  try {
+    $null=$process.Handle
+    if (!$process.Path -or [IO.Path]::GetFullPath($process.Path) -ne [IO.Path]::GetFullPath($current.ExecutablePath)) { throw 'Process executable changed' }
+    $process.Kill()
+    if (!$process.WaitForExit(30000)) { throw 'Owned process did not exit' }
+  } finally { $process.Dispose() }
+}
+$remaining=@(Get-CimInstance Win32_Process | Where-Object { $_.ExecutablePath -and [IO.Path]::GetFullPath($_.ExecutablePath) -in $ownedBinaries })
+if ($remaining.Count) { throw 'Owned runtime process remains; files retained' }
+function Remove-OwnedFiles {
+  # Keep the owner receipt until all other children are gone, allowing a failed
+  # teardown to be safely retried without adopting an unmarked directory.
+  Get-ChildItem -LiteralPath $p.remoteDirectory -Force | Where-Object { $_.Name -ne '.jsn-owner.json' } | ForEach-Object { Remove-Item -LiteralPath $_.FullName -Recurse -Force -ErrorAction Stop }
+  $receipt=Join-Path $p.remoteDirectory '.jsn-owner.json'
+  if (Test-Path -LiteralPath $receipt) { Remove-Item -LiteralPath $receipt -Force -ErrorAction Stop }
+  Remove-Item -LiteralPath $p.remoteDirectory -Force -ErrorAction Stop
+}
+$phase='remove-files'
+try { Remove-OwnedFiles } catch [UnauthorizedAccessException] {
+  $phase='recover-file-acl'
+  # Service absence and the full tree scan were verified above. Do not expand
+  # recovery to any parent, sibling, global policy or unowned service.
+  if (Get-Service -Name $p.serviceName -ErrorAction SilentlyContinue) { throw 'Service reappeared; refusing ACL recovery' }
+  $remainingLinks=@(Get-ChildItem -LiteralPath $p.remoteDirectory -Force -Recurse | Where-Object { $_.Attributes -band [IO.FileAttributes]::ReparsePoint })
+  if ($remainingLinks.Count) { throw 'Refusing ACL recovery through reparse points' }
+  & takeown.exe /F $p.remoteDirectory /R /D Y 2>&1 | Out-Null
+  if ($LASTEXITCODE -ne 0) { throw 'Scoped ownership recovery failed; localized takeown prompts may require manual recovery' }
+  $controllerSid=[Security.Principal.WindowsIdentity]::GetCurrent().User.Value
+  $grant='*' + $controllerSid + ':(OI)(CI)F'
+  & icacls.exe $p.remoteDirectory /grant $grant /T /C 2>&1 | Out-Null
+  if ($LASTEXITCODE -ne 0) { throw 'Scoped controller ACL recovery failed' }
+  $phase='remove-files'
+  Remove-OwnedFiles
+}
+if (Test-Path -LiteralPath $p.remoteDirectory) { throw 'Owned directory remains' }
+Result @{removed=$true}`, m, { ...options, timeout: 180000 });
+    m.state = 'removed'; save(directory, m); return m;
+  } catch (error) { m.state = 'uncertain'; if (error.phase) m.failedPhase = error.phase; save(directory, m); throw error; }
+}
+
+export function inspectWindowsRemoteMidServer({ directory, ...options }) {
+  const m = load(directory);
+  return { ...m, ...remote(m.target, `Assert-Owned; $s=Owned-Service; if (!$s) { throw 'Service missing' }; Result @{status=$s.State; runtimeAccount=$s.StartName; startMode=$s.StartMode}`, m, options) };
+}
+
+function lifecycle(operation, { directory, ...options }) {
+  const m = load(directory);
+  try {
+    remote(m.target, `Assert-Owned; $s=Owned-Service; if (!$s) { throw 'Service missing' }; ${operation}-Service -Name $p.serviceName -ErrorAction Stop
+(Get-Service -Name $p.serviceName).WaitForStatus('${operation === 'Start' ? 'Running' : 'Stopped'}',[TimeSpan]::FromSeconds(60))
+Result @{status='${operation === 'Start' ? 'Running' : 'Stopped'}'}`, m, { ...options, timeout: 90000 });
+    m.state = operation === 'Start' ? 'running' : 'stopped'; save(directory, m); return m;
+  } catch (error) { m.state = 'uncertain'; if (error.phase) m.failedPhase = error.phase; save(directory, m); throw error; }
+}
+export const startWindowsRemoteMidServer = options => lifecycle('Start', options);
+export const stopWindowsRemoteMidServer = options => lifecycle('Stop', options);
+
+export function logsWindowsRemoteMidServer({ directory, tail = 100, ...options }) {
+  if (!Number.isInteger(tail) || tail < 1 || tail > 10000) throw new Error('Log tail must be between 1 and 10000');
+  const m = load(directory);
+  return remote(m.target, `Assert-Owned; $null=Owned-Service
+$logs=@(Get-ChildItem -LiteralPath (Join-Path $p.remoteDirectory 'agent\\logs') -File | Where-Object { $_.Name -match '^agent.*\\.log(?:\\.[0-9]+)?$' } | Sort-Object LastWriteTime -Descending)
+$text=''; if ($logs.Count -gt 0) { $text=(Get-Content -LiteralPath $logs[0].FullName -Tail $p.tail) -join [Environment]::NewLine }; Result @{logs=$text}`, { ...m, tail }, options).logs;
+}

package/src/midserver-zip.js

@@ -17,7 +17,7 @@ function read(fd, size, offset) {
 
 // Inspect every entry before extracting anything. ZIP64, split ZIPs, links and
 // Windows aliases are deliberately unsupported, not delegated to a shell tool.
-export function inspectMidZip(archive) {
+export function inspectMidZip(archive, { allowedRoots = ['agent', 'META-INF'] } = {}) {
   const fd = fs.openSync(archive, 'r');
   try {
     const size = fs.fstatSync(fd).size;
@@ -44,7 +44,7 @@ export function inspectMidZip(archive) {
       const localOffset = directory.readUInt32LE(pos + 42);
       const folder = name.endsWith('/');
       const parts = name.replace(/\/$/, '').split('/');
-      if (!['agent', 'META-INF'].includes(parts[0]) || parts.some(part => !part || part === '.' || part === '..' || /[\\:<>"|?*]/.test(part) || [...part].some(char => char.codePointAt(0) < 32) || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) throw new Error('Unsafe ZIP path');
+      if ((allowedRoots && !allowedRoots.includes(parts[0])) || parts.some(part => !part || part === '.' || part === '..' || /[\\:<>"|?*]/.test(part) || [...part].some(char => char.codePointAt(0) < 32) || /[. ]$/.test(part) || /^(con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part))) throw new Error('Unsafe ZIP path');
       const type = mode & 0o170000;
       if (type && type !== 0o100000 && type !== 0o040000) throw new Error('ZIP links and special files are forbidden');
       if ((flags & 1) || ![0, 8].includes(method) || compressedSize === 0xffffffff || uncompressedSize === 0xffffffff || localOffset === 0xffffffff) throw new Error('Unsupported ZIP encoding');

package/src/mutation-context.js

@@ -0,0 +1,74 @@
+// Capture-context approval is independent of delete confirmation preferences.
+import process from 'node:process';
+import { collectCapabilities } from './capabilities.js';
+import { isMutationCommand } from './mutations.js';
+import { getCurrentUser, getCurrentApplication, getCurrentUpdateSet } from './context.js';
+import { canUsePicker, getStringField, quoteShellArg } from './helpers.js';
+import { confirm } from './prompts.js';
+import { AppError, CodeConfirmationRequired, errUsageHint } from './errors.js';
+
+export function needsMutationContext(argv) {
+  if (!isMutationCommand(argv)) return false;
+  const caps = collectCapabilities().get(argv._?.[0]) || {};
+  if (caps.mutationContextReadMethods?.includes(String(argv.method || 'GET').toUpperCase())) return false;
+  return !caps.mutationContextExemptSubcommands?.some(sub =>
+    sub.split(' ').every((part, index) => argv._?.[index + 1] === part));
+}
+
+function diagnostic(code, message, command, severity = 'warning') {
+  return { code, severity, message, remediation: { command } };
+}
+
+export async function guardMutationContext(app, argv, { ask = confirm, rawArgs = process.argv.slice(2) } = {}) {
+  if (!needsMutationContext(argv) || !app.sdk) return null;
+  let application, updateSet;
+  try {
+    const user = await getCurrentUser(app.sdk);
+    if (user?.sys_id) [application, updateSet] = await Promise.all([
+      getCurrentApplication(app.sdk, user.sys_id, { unknownWhenMissing: true }),
+      getCurrentUpdateSet(app.sdk, user.sys_id),
+    ]);
+  } catch {
+    // Failed reads are unknown context, never evidence of Global + Default.
+  }
+  const context = { scope: application?.scope || null, application_id: application?.appSysId || null,
+    update_set: updateSet ? { name: updateSet.name, sys_id: updateSet.sys_id, state: updateSet.state || null } : null,
+    diagnostics: [], approval_required: false, approved: false };
+  if (!context.scope || !updateSet) context.diagnostics.push(diagnostic('capture_context_unknown',
+    'Capture context could not be determined. Identify the intended scope and update set before development changes.', 'jsn updatesets list'));
+  const appId = getStringField(updateSet || {}, 'application');
+  const rawAppId = updateSet?.application?.value || appId;
+  if (application?.appSysId && rawAppId && application.appSysId !== rawAppId) {
+    context.diagnostics.push(diagnostic('update_set_scope_mismatch',
+      `Selected scope ${context.scope} and update set ${updateSet.name} belong to different applications; changes may not be captured in this set.`,
+      `jsn scopes set ${quoteShellArg(rawAppId)}`));
+  }
+  if (updateSet?.state && !['in progress', 'in_progress'].includes(updateSet.state.toLowerCase())) {
+    context.diagnostics.push(diagnostic('update_set_not_in_progress', `Selected update set ${updateSet.name} is ${updateSet.state}; select an in-progress capture set.`, 'jsn updatesets set', 'error'));
+    const error = errUsageHint('Selected capture update set is not in progress.', 'Run: jsn updatesets set');
+    error.context = context; throw error;
+  }
+  const globalDefault = context.scope?.toLowerCase() === 'global' && updateSet?.name?.toLowerCase() === 'default';
+  if (globalDefault) {
+    context.approval_required = true;
+    context.diagnostics.push(diagnostic('global_default_update_set',
+      'Global scope + Default update set can capture customization in the wrong place or leave changes untracked. Select or create a dedicated update set; not all record changes are update-set tracked.',
+      'jsn updatesets create --name "My Feature"'));
+    if (argv.force) context.approved = true;
+    else if (canUsePicker(app, argv)) {
+      context.approved = await ask({ message: `Scope: Global; update set: Default. ${context.diagnostics.at(-1).message} Approve this exact mutation: ${['jsn', ...rawArgs].map(quoteShellArg).join(' ')}?`, default: false });
+    }
+    if (!context.approved) {
+      const target = app.session?.profileName ? ` --profile ${quoteShellArg(app.session.profileName)}` : '';
+      const rerun = ['jsn', ...rawArgs.filter(arg => arg !== '--force')].map(quoteShellArg).join(' ') + (rawArgs.includes('--profile') ? '' : target);
+      const error = new AppError(CodeConfirmationRequired, 'Mutation in Global scope + Default update set requires explicit approval.',
+        `Select a dedicated set: jsn updatesets set; or jsn updatesets create --name "My Feature". Ask the user to approve this exact operation, then rerun: ${rerun} --force`);
+      error.context = context; throw error;
+    }
+  }
+  if (canUsePicker(app, argv)) {
+    process.stderr.write(`Mutation context: scope ${context.scope || 'unknown'}; update set ${updateSet?.name || 'unknown'}${updateSet?.sys_id ? ` (${updateSet.sys_id})` : ''}.\n`);
+    for (const item of context.diagnostics) process.stderr.write(`Warning (${item.code}): ${item.message} Run: ${item.remediation.command}\n`);
+  }
+  return context;
+}