@jacebenson/jsn 4.3.9-dev.63 → 4.3.9-dev.64

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jacebenson/jsn",
-  "version": "4.3.9-dev.63",
+  "version": "4.3.9-dev.64",
   "description": "A command-line interface for ServiceNow that follows the Unix philosophy: simple, composable, and scriptable.",
   "type": "module",
   "bin": {

package/src/auth.js

@@ -8,9 +8,10 @@ import fs from 'node:fs';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { execFileSync } from 'node:child_process';
-import { password as passwordPrompt } from '@inquirer/prompts';
+import { password as passwordPrompt } from './prompts.js';
 import { globalConfigDir, normalizeInstanceURL } from './config.js';
 import { errAuth } from './errors.js';
+import { pendingBrowserLogin } from './browser-auth.js';
 
 // ─── Credential key helpers ───
 
@@ -699,7 +700,7 @@ export class AuthManager {
     if (method === 'basic' && (!resolved.username || !resolved.password)) throw errAuth('Invalid basic auth credentials');
     if (method === 'oauth' && !resolved.access_token) throw errAuth('Invalid OAuth credentials');
     // Check expiry — refresh if less than 5 minutes remaining
-    if (resolved.expires_at && Date.now() >= (resolved.expires_at - 300) * 1000) {
+    if (options.refresh !== false && resolved.expires_at && Date.now() >= (resolved.expires_at - 300) * 1000) {
       if (resolved.refresh_token) return this.refreshToken(instance, resolved, credentialUsername);
       throw errAuth('Token expired, please login again');
     }
@@ -712,17 +713,17 @@ export class AuthManager {
     const pkce = generatePKCE();
     const authURL = buildAuthURL(instanceURL, clientID, pkce);
 
-    console.log();
-    console.log('Open this URL in your browser to authenticate:');
-    console.log(authURL);
-    console.log();
-    console.log('(The browser is not opened automatically — if a browser tab opens,');
-    console.log(' use the URL above if the opened page shows an error.)');
-    console.log();
+    console.error();
+    console.error('Open this URL in your browser to authenticate:');
+    console.error(authURL);
+    console.error();
+    console.error('(The browser is not opened automatically — if a browser tab opens,');
+    console.error(' use the URL above if the opened page shows an error.)');
+    console.error();
 
-    console.log('After authenticating in the browser, copy the authorization code shown on the page.');
-    console.log('(input is hidden for security — just paste and press Enter)');
-    console.log();
+    console.error('After authenticating in the browser, copy the authorization code shown on the page.');
+    console.error('(input is hidden for security — just paste and press Enter)');
+    console.error();
 
     const authCode = await askHidden('Authorization code (hidden on paste for security): ');
     const code = authCode.trim();
@@ -730,7 +731,7 @@ export class AuthManager {
       throw errAuth('Authorization code is required');
     }
 
-    console.log('\nExchanging authorization code for tokens...');
+    console.error('\nExchanging authorization code for tokens...');
     const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
     // Save with the selected profile username when one is already known.
     this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
@@ -751,10 +752,10 @@ export class AuthManager {
     savePKCEState(instanceURL, pkce, username);
     const url = buildAuthURL(instanceURL, clientID, pkce);
     if (waitFile) {
-      console.log(url);
-      console.log();
-      console.log(`Waiting for authorization code in file: ${waitFile}`);
-      console.log('(polling every 2 seconds — write the code to the file to complete login)');
+      console.error(url);
+      console.error();
+      console.error(`Waiting for authorization code in file: ${waitFile}`);
+      console.error('(polling every 2 seconds — write the code to the file to complete login)');
       return this._waitForCodeFile(instanceURL, clientID, pkce, waitFile, 300000, username);
     }
     return url;
@@ -764,18 +765,15 @@ export class AuthManager {
     const start = Date.now();
     const pollInterval = 2000;
     while (Date.now() - start < timeout) {
-      try {
-        const code = fs.readFileSync(filePath, 'utf-8').trim();
-        if (code) {
-          console.log(`\nAuthorization code found in ${filePath}`);
-          removePKCEState(instanceURL, username);
-          const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
-          this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
-          console.log('Token exchange successful!\n');
-          return newCreds;
-        }
-      } catch {
-        // File not ready yet
+      let code = '';
+      try { code = fs.readFileSync(filePath, 'utf-8').trim(); } catch { /* File not ready yet. */ }
+      if (code) {
+        console.error(`\nAuthorization code found in ${filePath}`);
+        const newCreds = await this.exchangeCode(instanceURL, clientID, code, pkce);
+        removePKCEState(instanceURL, username);
+        this.saveCredentials(instanceURL, newCreds, username || newCreds.username);
+        console.error('Token exchange successful!\n');
+        return newCreds;
       }
       await new Promise(r => setTimeout(r, pollInterval));
     }
@@ -787,11 +785,13 @@ export class AuthManager {
    * Reads SN_USERNAME/SN_PASSWORD (or SN_<INSTANCE>_USERNAME/SN_<INSTANCE>_PASSWORD).
    * Stores the basic auth credentials so they persist across sessions.
    */
-  async loginWithPassword(instanceURL, username = this._activeUsername()) {
+  async loginWithPassword(instanceURL, username = this._activeUsername(), suppliedCredentials) {
     instanceURL = normalizeInstanceURL(instanceURL);
     const envCreds = getBasicAuthFromEnv(instanceURL);
     const storedCreds = this.loadCredentials(instanceURL, username);
-    const creds = envCreds || storedCreds;
+    const creds = suppliedCredentials
+      ? { auth_method: 'basic', ...suppliedCredentials }
+      : envCreds || storedCreds;
     if (!creds || creds.auth_method !== 'basic' || !creds.username || !creds.password) {
       throw errAuth(
         `No basic auth credentials found in environment or stored profile.\n\n` +
@@ -802,8 +802,10 @@ export class AuthManager {
         `  jsn auth login --basic ${instanceURL}`
       );
     }
+    if (username && creds.username !== username) {
+      throw errAuth('The Basic credentials do not match the selected profile user. Use matching credentials or create a new named profile.');
+    }
     this.saveCredentials(instanceURL, creds, creds.username);
-    console.log(`✓ Basic auth credentials saved for ${instanceURL}`);
     return creds;
   }
 
@@ -812,28 +814,69 @@ export class AuthManager {
    * The PKCE state must have been saved by an earlier buildAuthURL() call.
    */
   async loginWithGck(instanceURL, input, username = this._activeUsername()) {
+    return this._loginWithBrowserSession(instanceURL, parseBrowserSessionInput(input), username);
+  }
+
+  async loginWithBrowser(instanceURL, options = {}, username = this._activeUsername()) {
+    if (options.launch) {
+      const { launchBrowserSession } = await import('./browser-launch.js');
+      const credentials = await launchBrowserSession(instanceURL, {
+        ...options,
+        verify: (creds, verification) => this._verifyBrowserSession(instanceURL, creds, username, { ...verification, requireIdentity: true }),
+      });
+      this.saveCredentials(normalizeInstanceURL(instanceURL), credentials, credentials.username);
+      return credentials;
+    }
+    const { readBrowserSession } = await import('./browser-auth.js');
+    const creds = await readBrowserSession(instanceURL, options);
+    return this._loginWithBrowserSession(instanceURL, creds, username, { requireIdentity: true });
+  }
+
+  async _loginWithBrowserSession(instanceURL, creds, username, { requireIdentity = false } = {}) {
+    const credentials = await this._verifyBrowserSession(instanceURL, creds, username, { requireIdentity });
+    this.saveCredentials(normalizeInstanceURL(instanceURL), credentials, credentials.username);
+    return credentials;
+  }
+
+  async _verifyBrowserSession(instanceURL, creds, username, { requireIdentity = false, signal, timeout = this.httpClient.timeout } = {}) {
     instanceURL = normalizeInstanceURL(instanceURL);
-    const creds = parseBrowserSessionInput(input);
+    const query = new URLSearchParams({
+      sysparm_limit: '1',
+      sysparm_fields: 'user_name',
+      sysparm_query: 'user_name=javascript:gs.getUserName()',
+    });
     let response;
     try {
-      response = await fetch(`${instanceURL}/api/now/table/sys_user?sysparm_limit=1`, {
+      response = await fetch(`${instanceURL}/api/now/table/sys_user?${query}`, {
         method: 'GET',
+        redirect: 'error',
+        signal: signal ? AbortSignal.any([signal, AbortSignal.timeout(timeout)]) : AbortSignal.timeout(timeout),
         headers: {
           Accept: 'application/json',
           'X-UserToken': creds.access_token,
           Cookie: creds.cookies,
         },
       });
-    } catch (error) {
-      throw errAuth(`Could not test the browser session against ${instanceURL}. Nothing was saved. Retry with: jsn auth login ${instanceURL} --gck (${error.message})`);
+    } catch {
+      throw errAuth(`Could not test the browser session against ${instanceURL}. Nothing was saved. Retry browser-session login.`);
     }
     if (!response.ok) {
+      if (requireIdentity && [401, 403].includes(response.status)) {
+        throw pendingBrowserLogin('The session is not authorized for current-user verification. Finish signing in, or check current-user API access.');
+      }
       throw errAuth(`Browser session rejected by ${instanceURL} (HTTP ${response.status}). Nothing was saved. Retry with: jsn auth login ${instanceURL} --gck`);
     }
-    const body = await response.json();
+    let body;
+    try { body = await response.json(); } catch { throw errAuth('Browser session verification did not return JSON. Nothing was saved.'); }
     const user = body?.result?.[0];
     const verifiedUsername = typeof user?.user_name === 'string' ? user.user_name : username;
-    this.saveCredentials(instanceURL, { ...creds, username: verifiedUsername || undefined }, verifiedUsername || undefined);
+    if (requireIdentity && verifiedUsername === 'guest') throw pendingBrowserLogin('Waiting for browser login.');
+    if (requireIdentity && (!user?.user_name || typeof user.user_name !== 'string')) {
+      throw pendingBrowserLogin('Could not verify the browser account. Nothing was saved. Check current-user API access.');
+    }
+    if (requireIdentity && username && username !== verifiedUsername) {
+      throw errAuth('The browser account does not match the selected profile. Nothing was saved. Use the matching account or create a new profile.');
+    }
     return { ...creds, username: verifiedUsername || undefined };
   }
 

package/src/browser-auth.js

@@ -0,0 +1,162 @@
+import { errAuth, errUsage } from './errors.js';
+import { normalizeInstanceURL } from './config.js';
+
+export const DEFAULT_BROWSER_URL = 'http://127.0.0.1:9222';
+
+export function pendingBrowserLogin(message) {
+  return Object.assign(errAuth(message), { browserLoginPending: true });
+}
+
+// Only called for a fresh browser owned by the login launcher. Never use
+// Browser.close for the advanced connection to a user's existing browser.
+export async function closeLoginBrowser(browserUrl) {
+  const endpoint = localEndpoint(browserUrl, 'http:');
+  const response = await fetch(new URL('/json/version', endpoint), {
+    signal: AbortSignal.timeout(1000), redirect: 'error',
+  });
+  if (!response.ok) throw errAuth('Could not close the login browser.');
+  const version = await response.json();
+  const ws = localEndpoint(version.webSocketDebuggerUrl, 'ws:');
+  if (ws.hostname !== endpoint.hostname || ws.port !== endpoint.port) throw errAuth('Unexpected login browser endpoint.');
+  const client = await connect(ws, 1000);
+  try { await client.send('Browser.close'); } finally { client.close(); }
+}
+
+// Browser access is opt-in and confined to a local debugging connection.
+// Never inspect profile databases or enumerate cookies for unrelated sites.
+function localEndpoint(value, protocol) {
+  let url;
+  try { url = new URL(value); } catch { throw errUsage('Invalid browser debugging URL.'); }
+  if (url.protocol !== protocol || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
+    || url.username || url.password || url.search || url.hash) {
+    throw errUsage('Browser debugging must use a loopback URL without credentials, query, or fragment.');
+  }
+  return url;
+}
+
+function connect(url, timeout) {
+  return new Promise((resolve, reject) => {
+    const socket = new WebSocket(url);
+    const pending = new Map();
+    let nextId = 0;
+    const fail = () => {
+      for (const { reject, timer } of pending.values()) {
+        clearTimeout(timer);
+        reject(pendingBrowserLogin('Browser debugging connection closed. Retry the import.'));
+      }
+      pending.clear();
+    };
+    const timer = setTimeout(() => {
+      reject(pendingBrowserLogin('Timed out connecting to the browser debugging port.'));
+      socket.close();
+    }, timeout);
+    socket.addEventListener('error', () => {
+      clearTimeout(timer);
+      reject(pendingBrowserLogin('Could not connect to the browser debugging port.'));
+      fail();
+    });
+    socket.addEventListener('close', () => {
+      clearTimeout(timer);
+      reject(pendingBrowserLogin('Browser debugging connection closed. Retry the import.'));
+      fail();
+    });
+    socket.addEventListener('message', ({ data }) => {
+      let message;
+      try { message = JSON.parse(data); } catch { return; }
+      const request = pending.get(message.id);
+      if (!request) return;
+      pending.delete(message.id);
+      clearTimeout(request.timer);
+      // Provider errors can contain evaluated values; never echo them.
+      if (message.error) request.reject(pendingBrowserLogin('The browser could not read the selected session.'));
+      else request.resolve(message.result);
+    });
+    socket.addEventListener('open', () => {
+      clearTimeout(timer);
+      resolve({
+        send(method, params = {}) {
+          return new Promise((resolve, reject) => {
+            const id = ++nextId;
+            const timer = setTimeout(() => {
+              pending.delete(id);
+              reject(pendingBrowserLogin('Timed out reading the browser session.'));
+            }, timeout);
+            pending.set(id, { resolve, reject, timer });
+            try { socket.send(JSON.stringify({ id, method, params })); } catch {
+              clearTimeout(timer);
+              pending.delete(id);
+              reject(pendingBrowserLogin('Browser debugging connection closed. Retry the import.'));
+            }
+          });
+        },
+        close: () => socket.close(),
+      });
+    });
+  });
+}
+
+// Only read the token from the matching origin, including classic UI frames.
+// This does not navigate, reload, or initiate requests in the user's browser.
+const TOKEN_EXPRESSION = `(() => {
+  const origin = location.origin;
+  function read(win) {
+    try {
+      if (win.location.origin !== origin) return '';
+      if (typeof win.g_ck === 'string' && win.g_ck) return win.g_ck;
+      for (let i = 0; i < win.frames.length; i++) {
+        const token = read(win.frames[i]);
+        if (token) return token;
+      }
+    } catch {}
+    return '';
+  }
+  return { origin, token: read(window) };
+})()`;
+
+export async function readBrowserSession(instance, { browserUrl = DEFAULT_BROWSER_URL, timeout = 10000 } = {}) {
+  const origin = normalizeInstanceURL(instance);
+  const endpoint = localEndpoint(browserUrl, 'http:');
+  if (endpoint.pathname !== '/') throw errUsage('Browser debugging URL must be an origin, for example http://127.0.0.1:9222.');
+  let tabs;
+  try {
+    const response = await fetch(new URL('/json/list', endpoint), {
+      signal: AbortSignal.timeout(timeout), redirect: 'error',
+    });
+    if (!response.ok) throw new Error();
+    tabs = await response.json();
+  } catch {
+    throw pendingBrowserLogin('Could not list browser tabs. Enable local Chromium remote debugging, then retry with --browser --browser-url http://127.0.0.1:9222.');
+  }
+  const matching = Array.isArray(tabs) ? tabs.filter(tab => {
+    try { return tab.type === 'page' && new URL(tab.url).origin === origin; } catch { return false; }
+  }) : [];
+  if (!matching.length) throw pendingBrowserLogin('No matching ServiceNow tab. Open the selected instance in the connected browser and sign in first.');
+  if (matching.length > 1) throw errAuth('Multiple tabs match this instance. Keep one tab open for the account to import, then retry.');
+  const ws = localEndpoint(matching[0].webSocketDebuggerUrl, 'ws:');
+  if (ws.hostname !== endpoint.hostname || ws.port !== endpoint.port) {
+    throw errAuth('Browser returned a debugging connection outside the selected endpoint.');
+  }
+  const client = await connect(ws, timeout);
+  try {
+    const evaluated = await client.send('Runtime.evaluate', { expression: TOKEN_EXPRESSION, returnByValue: true });
+    const session = evaluated?.result?.value;
+    if (evaluated?.exceptionDetails || session?.origin !== origin || typeof session?.token !== 'string' || !session.token) {
+      throw pendingBrowserLogin('No user token in the matching tab. Sign in and open a ServiceNow application page, then retry; pasted headers with --gck remain available.');
+    }
+    const result = await client.send('Network.getCookies', { urls: [`${origin}/api/now/table/sys_user`] });
+    const cookies = result?.cookies;
+    if (!Array.isArray(cookies) || !cookies.length) throw pendingBrowserLogin('No cookies available for the selected instance. Sign in and retry.');
+    // Confirm the page did not navigate to another origin during the read.
+    const location = await client.send('Runtime.evaluate', { expression: 'location.origin', returnByValue: true });
+    if (location?.result?.value !== origin) throw pendingBrowserLogin('The browser tab changed during import. Retry on the selected instance.');
+    const cookieHeader = cookies.map(({ name, value }) => {
+      if (typeof name !== 'string' || !/^[!#$%&'*+.^_`|~0-9a-z-]+$/i.test(name)
+        || typeof value !== 'string' || /[\r\n;]/.test(value)) throw errAuth('The browser returned invalid cookies.');
+      return `${name}=${value}`;
+    }).join('; ');
+    if (/[\r\n]/.test(session.token)) throw errAuth('The browser returned an invalid user token.');
+    return { auth_method: 'gck', access_token: session.token, cookies: cookieHeader, auth_source: 'gck' };
+  } finally {
+    client.close();
+  }
+}

package/src/browser-launch.js

@@ -0,0 +1,148 @@
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { setTimeout as delay } from 'node:timers/promises';
+import { readBrowserSession, closeLoginBrowser } from './browser-auth.js';
+import { normalizeInstanceURL } from './config.js';
+import { errAuth, errUsage } from './errors.js';
+
+const BROWSERS = [
+  { name: 'Chromium', value: 'chromium', binaries: ['chromium', 'chromium-browser'] },
+  { name: 'Google Chrome', value: 'chrome', binaries: ['google-chrome', 'google-chrome-stable', 'chrome'] },
+  { name: 'Microsoft Edge', value: 'edge', binaries: ['microsoft-edge', 'microsoft-edge-stable', 'msedge'] },
+];
+
+export function browserCandidates({ platform = process.platform, env = process.env, home = os.homedir() } = {}) {
+  const paths = platform === 'win32' ? path.win32 : path.posix;
+  const environment = name => platform === 'win32'
+    ? Object.entries(env).find(([key]) => key.toLowerCase() === name.toLowerCase())?.[1]
+    : env[name];
+  return BROWSERS.map(browser => {
+    const candidates = [];
+    for (const entry of (environment('PATH') || '').split(platform === 'win32' ? ';' : ':').filter(Boolean)) {
+      const dir = platform === 'win32' ? entry.replace(/^"(.*)"$/, '$1') : entry;
+      for (const binary of browser.binaries) candidates.push(paths.join(dir, binary + (platform === 'win32' ? '.exe' : '')));
+    }
+    if (platform === 'darwin') {
+      const app = { chromium: 'Chromium.app/Contents/MacOS/Chromium', chrome: 'Google Chrome.app/Contents/MacOS/Google Chrome', edge: 'Microsoft Edge.app/Contents/MacOS/Microsoft Edge' }[browser.value];
+      candidates.push(paths.join('/Applications', app), paths.join(home, 'Applications', app));
+    }
+    if (platform === 'win32') {
+      const app = { chromium: 'Chromium/Application/chrome.exe', chrome: 'Google/Chrome/Application/chrome.exe', edge: 'Microsoft/Edge/Application/msedge.exe' }[browser.value];
+      for (const dir of ['ProgramW6432', 'ProgramFiles', 'ProgramFiles(x86)', 'LocalAppData'].map(environment).filter(Boolean)) candidates.push(paths.join(dir, app));
+    }
+    return { ...browser, candidates: [...new Set(candidates)] };
+  });
+}
+
+export async function findBrowsers(options = {}) {
+  const found = [];
+  for (const browser of browserCandidates(options)) {
+    for (const executable of browser.candidates) {
+      try {
+        await fs.access(executable, fs.constants.X_OK);
+        if (!(await fs.stat(executable)).isFile()) continue;
+        found.push({ name: browser.name, value: browser.value, executable });
+        break;
+      } catch { /* Try another installation location. */ }
+    }
+  }
+  return found;
+}
+
+export async function chooseBrowser({ browserName, interactive = false } = {}) {
+  if (browserName && !BROWSERS.some(browser => browser.value === browserName)) {
+    throw errUsage('Choose chromium, chrome, or edge with --browser-name. Firefox login is not supported yet.');
+  }
+  const browsers = await findBrowsers();
+  if (browserName) {
+    const browser = browsers.find(browser => browser.value === browserName);
+    if (!browser) throw errUsage(`The selected browser (${browserName}) was not found. Install it or choose another browser.`);
+    return browser;
+  }
+  if (!browsers.length) throw errUsage('No supported browser found. Install Chrome/Chromium or Edge, or use --gck to paste a browser request. Firefox login is not supported yet.');
+  if (!interactive || browsers.length === 1) return browsers[0];
+  const { select } = await import('./prompts.js');
+  const selected = await select({ message: 'Log in using which browser?', choices: browsers });
+  return browsers.find(browser => browser.value === selected);
+}
+
+// Each login gets a fresh browser profile and an OS-assigned debugging port.
+// Neither the user's regular browser nor a previous login account is reused.
+export async function launchBrowserSession(instance, {
+  browser, verify = async credentials => credentials, timeout = 300000,
+  onProgress = () => {}, spawnBrowser = spawn, signal,
+} = {}) {
+  if (!browser?.executable) throw errUsage('Select an installed browser before login.');
+  const origin = normalizeInstanceURL(instance);
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), 'jsn-browser-login-'));
+  await fs.chmod(directory, 0o700);
+  const controller = new AbortController();
+  const cancel = () => controller.abort();
+  process.once('SIGINT', cancel);
+  signal?.addEventListener('abort', cancel, { once: true });
+  if (signal?.aborted) cancel();
+  let child;
+  let exited = false;
+  let launchFailed = false;
+  let closed = Promise.resolve();
+  let lastCheck = '';
+  let browserUrl;
+  const deadline = Date.now() + timeout;
+  try {
+    if (controller.signal.aborted) throw errAuth('Browser login cancelled.');
+    child = spawnBrowser(browser.executable, [
+      '--remote-debugging-address=127.0.0.1', '--remote-debugging-port=0',
+      `--user-data-dir=${directory}`, '--no-first-run', '--no-default-browser-check',
+      '--new-window', origin,
+    ], { stdio: 'ignore', shell: false, windowsHide: true });
+    closed = new Promise(resolve => {
+      child.once('error', () => { launchFailed = true; exited = true; resolve(); });
+      child.once('close', () => { exited = true; resolve(); });
+    });
+    onProgress(`Opening ${browser.name}. Log in to ServiceNow in the new window; JSN will continue automatically.`);
+    while (Date.now() < deadline) {
+      if (controller.signal.aborted) throw errAuth('Browser login cancelled.');
+      if (exited) throw errAuth(launchFailed ? 'Could not launch the selected browser.' : 'The login window was closed before authentication completed.');
+      if (!browserUrl) {
+        try {
+          const port = (await fs.readFile(path.join(directory, 'DevToolsActivePort'), 'utf8')).split('\n')[0].trim();
+          if (/^\d+$/.test(port) && Number(port) > 0 && Number(port) < 65536) browserUrl = `http://127.0.0.1:${port}`;
+        } catch { /* Browser is still starting. */ }
+      }
+      if (browserUrl) {
+        try {
+          const credentials = await readBrowserSession(origin, { browserUrl, timeout: Math.min(2000, Math.max(1, deadline - Date.now())) });
+          if (controller.signal.aborted) throw errAuth('Browser login cancelled.');
+          const verified = await verify(credentials, {
+            signal: controller.signal, timeout: Math.min(5000, Math.max(1, deadline - Date.now())),
+          });
+          if (controller.signal.aborted) throw errAuth('Browser login cancelled.');
+          return verified;
+        } catch (error) {
+          if (controller.signal.aborted) throw errAuth('Browser login cancelled.');
+          if (!error.browserLoginPending) throw error;
+          lastCheck = error.message;
+        }
+      }
+      try { await delay(Math.min(500, Math.max(1, deadline - Date.now())), undefined, { signal: controller.signal }); } catch { throw errAuth('Browser login cancelled.'); }
+    }
+    throw errAuth(`Timed out waiting for browser login. ${lastCheck || 'Run browser login again when ready.'}`);
+  } finally {
+    process.removeListener('SIGINT', cancel);
+    signal?.removeEventListener('abort', cancel);
+    if (child && !exited) {
+      // Ask Chromium to exit normally so renderer processes release profile
+      // files. Windows child.kill() is forceful, not POSIX graceful SIGTERM.
+      if (browserUrl) {
+        try { await closeLoginBrowser(browserUrl); } catch { /* Fall back to the owned process handle. */ }
+        await Promise.race([closed, delay(2000, undefined, { ref: false })]);
+      }
+      if (!exited) child.kill();
+      await Promise.race([closed, delay(2000, undefined, { ref: false })]);
+      if (!exited) { child.kill('SIGKILL'); await Promise.race([closed, delay(1000, undefined, { ref: false })]); }
+    }
+    await fs.rm(directory, { recursive: true, force: true, maxRetries: 10, retryDelay: 200 });
+  }
+}

package/src/capabilities.js

@@ -14,6 +14,8 @@
 //     // Skip the once-per-day npm-version / skill freshness checks and the
 //     // interactive context header.
 //     skipDailyChecks: true,
+//     // Suppress the current instance header for profile management commands.
+//     skipContextHeader: true,
 //   }
 //
 // cli.js derives every skip-list and the mutation guard's path list from
@@ -91,6 +93,14 @@ export function dailyCheckSkipCommands(caps = collectCapabilities()) {
   return out;
 }
 
+export function contextHeaderSkipCommands(caps = collectCapabilities()) {
+  const out = dailyCheckSkipCommands(caps);
+  for (const [name, capability] of caps) {
+    if (capability.skipContextHeader) out.add(name);
+  }
+  return out;
+}
+
 /**
  * Derive the mutation command-path list (argv._ token arrays) from the
  * capability registry. Each entry is a prefix pattern: an argv._ path that

package/src/cli.js

@@ -10,7 +10,7 @@ import { resolveSession, applySession } from './session.js';
 import { renderHelp } from './help.js';
 import { isMutationCommand, refreshMutationCommands } from './mutations.js';
 import { skippedUpdatesCmd } from './commands/skipped-updates.js';
-import { noInstanceCommands, dailyCheckSkipCommands } from './capabilities.js';
+import { noInstanceCommands, dailyCheckSkipCommands, contextHeaderSkipCommands } from './capabilities.js';
 import { guardExit, exitWithError, AppError, CodeUsage } from './errors.js';
 import { formatCommandList } from './helpers.js';
 
@@ -320,7 +320,7 @@ export function buildCLI() {
       }
 
       // Print context header for interactive terminals
-      if (!dailySkips.has(cmd)) {
+      if (!contextHeaderSkipCommands().has(cmd)) {
         await argv.app.printContextHeader(argv);
       }
     })