@notis_ai/cli 0.2.18 → 0.2.20

package/src/runtime/delegated-context.js

@@ -5,11 +5,11 @@
  * is already running has no business handing the same work back to Notis, and
  * nothing about the loop it would create is self-limiting.
  *
- * This is the polite half of the guard. The server refuses the same call unless
- * it carries a purpose-scoped CLI/MCP OAuth token, which a delegated runtime
- * never has -- that is the half that actually holds. What this adds is a clear
- * message at the point of the mistake, instead of a permission error the agent
- * will try to work around.
+ * The guard covers the friendly command only. Agents start and steer threads
+ * on purpose through `LOCAL_NOTIS_CONTROL_THREADS`, so `notis tools exec` is
+ * not refused here and the server applies no extra check. What this adds is a
+ * clear message at the point of the common mistake: an agent running the
+ * hand-over its own instructions describe.
  */
 
 import { existsSync } from 'node:fs';
@@ -50,19 +50,3 @@ export function assertNotDelegated(commandLabel, env = process.env) {
     ],
   });
 }
-
-/**
- * Tools that hand work to a Notis agent, by canonical name.
- *
- * `notis handover` is not the only way to reach these: `notis tools exec` takes
- * any tool name, and `tools exec-parallel` takes a list of them. Guarding only
- * the friendly command would leave the escape hatch it exists to wrap.
- */
-export const HANDOVER_TOOL_NAMES = new Set(['LOCAL_NOTIS_HAND_OVER']);
-
-export function assertToolNotDelegated(toolName, env = process.env) {
-  if (!HANDOVER_TOOL_NAMES.has(String(toolName || '').toUpperCase())) {
-    return;
-  }
-  assertNotDelegated(`tools exec ${toolName}`, env);
-}

package/src/runtime/native-record-files.js

@@ -0,0 +1,47 @@
+import { open } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { basename, extname } from 'node:path';
+import { httpRequest } from './transport.js';
+import { usageError } from './errors.js';
+
+const MAX_BYTES = 8 * 1024 * 1024;
+const UUID = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i;
+const MIME = { '.html': 'text/html', '.htm': 'text/html', '.txt': 'text/plain', '.md': 'text/markdown',
+  '.json': 'application/json', '.pdf': 'application/pdf', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.webp': 'image/webp' };
+
+/** Reads a bounded local file, never interprets it and never attaches it to a row. */
+export async function uploadNativeRecordFileWithCliRuntime({ runtime, target, recordKey, schemaRevision, requestId,
+  filePath, name = basename(filePath || ''), contentType = MIME[extname(filePath || '').toLowerCase()] || 'application/octet-stream',
+  signal, request = httpRequest }) {
+  if (!UUID.test(recordKey || '') || !UUID.test(requestId || '') || !Number.isSafeInteger(schemaRevision) || schemaRevision < 0
+    || !target || typeof target !== 'object' || Array.isArray(target) || !filePath) {
+    throw usageError('Choose a local file, native target, record key, schema revision and stable request ID.');
+  }
+  const handle = await open(filePath, 'r');
+  let data;
+  try {
+    const stat = await handle.stat();
+    if (!stat.isFile() || stat.size < 1 || stat.size > MAX_BYTES) throw usageError('Choose a regular file up to 8 MB.');
+    const buffer = Buffer.alloc(MAX_BYTES + 1);
+    let length = 0;
+    while (length < buffer.length) {
+      const read = await handle.read(buffer, length, buffer.length - length, length);
+      if (!read.bytesRead) break;
+      length += read.bytesRead;
+    }
+    if (!length || length > MAX_BYTES) throw usageError('Choose a file up to 8 MB.');
+    data = buffer.subarray(0, length);
+  } finally { await handle.close(); }
+  const digest = createHash('sha256').update(data).digest('hex');
+  const body = { protocol: 1, target, record_key: recordKey, schema_revision: schemaRevision, request_id: requestId,
+    name, content_type: contentType, base64: data.toString('base64') };
+  // No automatic retry: repeating this command with the same request ID is the
+  // exact immutable intent; a mismatched request fails instead of overwriting.
+  const result = (await request({ runtime, method: 'POST', path: '/portal_native_files/upload', spacesProtocol: true, body, signal })).payload;
+  if (result?.protocol !== 1 || result.record_key !== recordKey || result.request_id !== requestId
+    || result.sha256 !== digest || result.size_bytes !== data.length || result.file?.name !== name
+    || typeof result.file?.url !== 'string' || !/^https?:\/\//.test(result.file.url) || result.url !== result.file.url) {
+    throw usageError('The file upload is not confirmed. Repeat the same request ID and file bytes.');
+  }
+  return result;
+}

package/src/runtime/oauth.js

@@ -3,6 +3,7 @@ import {
   randomBytes,
   timingSafeEqual,
 } from 'node:crypto';
+import { subscribe, unsubscribe } from 'node:diagnostics_channel';
 import {
   mkdirSync,
   readdirSync,
@@ -11,6 +12,7 @@ import {
   rmdirSync,
   rmSync,
   statSync,
+  utimesSync,
   writeFileSync,
 } from 'node:fs';
 import { createServer } from 'node:http';
@@ -21,7 +23,8 @@ import { execFileSync, spawn } from 'node:child_process';
 import { createInterface } from 'node:readline/promises';
 
 import { CliError, EXIT_CODES, usageError } from './errors.js';
-import { getAuthRecovery, quoteShellArgument } from './auth-recovery.js';
+import { readComputerIdentity } from './computer-identity.js';
+import { getAuthRecovery, getRetryRecovery, quoteShellArgument } from './auth-recovery.js';
 import {
   channelFromProfile,
   cliCommandForChannel,
@@ -38,19 +41,48 @@ import {
   updateConfig,
 } from './profiles.js';
 
+// A login without --scope asks for every permission the server advertises for
+// the CLI resource, so a permission added on the server reaches the next sign-in
+// without a CLI release. This list only stands in for a server that advertises
+// none.
 export const DEFAULT_CLI_OAUTH_SCOPES = [
   'notis:read',
   'notis:write',
   'notis:connections',
-  'notis:apps',
+  'notis:spaces',
 ];
-const OAUTH_LOCK_DIR = join(homedir(), '.notis', 'oauth.lock');
+
+export function defaultCliOAuthScopes(metadata) {
+  const advertised = (metadata?.scopesSupported || [])
+    .filter((scope) => typeof scope === 'string' && scope.startsWith('notis:'));
+  return advertised.length > 0 ? [...new Set(advertised)] : DEFAULT_CLI_OAUTH_SCOPES;
+}
+// Read at call time so a test, or a caller with its own HOME, never touches
+// the lock another process on this computer is using.
+function oauthLockDir() {
+  return join(homedir(), '.notis', 'oauth.lock');
+}
 const DEFAULT_LOGIN_TIMEOUT_MS = 300_000;
 const DEFAULT_REFRESH_EXPIRES_IN = 30 * 24 * 60 * 60;
 // A parked authorization outlives the terminal that started it: the user may
 // still have to sign up, verify an email, and consent before pasting the code.
 const PENDING_LOGIN_TTL_SECONDS = 30 * 60;
 const OAUTH_HTTP_TIMEOUT_MS = 10_000;
+// A refresh rotates the token it presents as soon as the server reads it, so
+// the token request is budgeted by phase (docs/no-dead-ends.md). Reaching the
+// server costs nothing: a slow or stalled link (a VPN over a phone hotspot)
+// may take this long, and a request never written is retried. Once written,
+// the server has very likely already answered, so the client waits this long
+// for that answer instead of abandoning it and keeping a rotated token.
+const OAUTH_TOKEN_SEND_TIMEOUT_MS = 30_000;
+const OAUTH_TOKEN_RESPONSE_TIMEOUT_MS = 60_000;
+const OAUTH_TOKEN_UNSENT_RETRY_DELAYS_MS = [1_000, 3_000];
+// Another process waits for a refresh in progress rather than failing.
+const OAUTH_REFRESH_LOCK_WAIT_MS = OAUTH_TOKEN_SEND_TIMEOUT_MS + OAUTH_TOKEN_RESPONSE_TIMEOUT_MS + 30_000;
+// A refresh keeps its lock folders fresh so that no process, current or older,
+// takes them over as stale while the token request is still running.
+const OAUTH_REFRESH_LOCK_TOUCH_MS = 5_000;
+const OAUTH_REFRESH_SAVE_RETRY_DELAYS_MS = [250, 1_000];
 const RESPONSE_FLUSH_GRACE_MS = 2_000;
 const MAX_NODE_TIMER_MS = 2_147_483_647;
 
@@ -112,6 +144,231 @@ async function fetchJson(url, init = {}, fetchImpl = fetch) {
   }
 }
 
+// Token requests in flight, by the request id each one carries in a header.
+// Node's fetch reports through these diagnostics channels when it creates a
+// request and when it writes the request to a socket; the id ties each report
+// to its request.
+const tokenRequestPhases = new Map();
+const REQUEST_CREATED_CHANNEL = 'undici:request:create';
+const REQUEST_WRITTEN_CHANNEL = 'undici:client:sendHeaders';
+// Failures that happen before a request can be written anywhere.
+const UNSENT_FAILURE_CODES = new Set([
+  'ENOTFOUND',
+  'EAI_AGAIN',
+  'ECONNREFUSED',
+  'EHOSTUNREACH',
+  'ENETUNREACH',
+  'ENETDOWN',
+  'UND_ERR_CONNECT_TIMEOUT',
+]);
+
+function diagnosticHeaderText(value) {
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) return value.map((item) => String(item)).join('\n');
+  return '';
+}
+
+function trackedTokenRequest(message) {
+  if (tokenRequestPhases.size === 0) return null;
+  const text = `${diagnosticHeaderText(message?.headers)}\n${diagnosticHeaderText(message?.request?.headers)}`;
+  for (const [requestId, phase] of tokenRequestPhases) {
+    if (text.includes(requestId)) return phase;
+  }
+  return null;
+}
+
+function onTokenRequestCreated(message) {
+  const phase = trackedTokenRequest(message);
+  if (phase) phase.created = true;
+}
+
+function onTokenRequestWritten(message) {
+  const phase = trackedTokenRequest(message);
+  if (phase && !phase.sent) {
+    phase.sent = true;
+    phase.onSent?.();
+  }
+}
+
+function watchTokenRequest(requestId) {
+  const phase = { created: false, sent: false, onSent: null };
+  if (tokenRequestPhases.size === 0) {
+    subscribe(REQUEST_CREATED_CHANNEL, onTokenRequestCreated);
+    subscribe(REQUEST_WRITTEN_CHANNEL, onTokenRequestWritten);
+  }
+  tokenRequestPhases.set(requestId, phase);
+  const stop = () => {
+    if (!tokenRequestPhases.delete(requestId)) return;
+    if (tokenRequestPhases.size === 0) {
+      unsubscribe(REQUEST_CREATED_CHANNEL, onTokenRequestCreated);
+      unsubscribe(REQUEST_WRITTEN_CHANNEL, onTokenRequestWritten);
+    }
+  };
+  return { phase, stop };
+}
+
+function networkFailureCode(error) {
+  return error?.cause?.code || error?.cause?.errors?.[0]?.code || error?.code || null;
+}
+
+class TokenRequestFailure extends Error {
+  constructor(error, { sent, timedOut }) {
+    super(error instanceof Error ? error.message : String(error));
+    this.name = 'TokenRequestFailure';
+    this.cause = error;
+    this.sent = sent;
+    this.timedOut = timedOut;
+  }
+}
+
+async function attemptTokenRequest(url, body, fetchImpl, { sendDeadline, responseTimeoutMs }) {
+  const requestId = `cli_${randomBytes(12).toString('hex')}`;
+  const { phase, stop } = watchTokenRequest(requestId);
+  const controller = new AbortController();
+  let answered = false;
+  let timedOut = false;
+  let timer = null;
+  // Timers run before the event loop reads sockets, so an answer that arrived
+  // just as a deadline passed is still waiting to be read. Let the loop read
+  // it first and give up only if it is still missing.
+  const giveUp = (stage) => setImmediate(() => {
+    if (answered || (stage === 'send' && phase.sent)) return;
+    timedOut = true;
+    controller.abort();
+  });
+  const waitForAnswer = () => {
+    clearTimeout(timer);
+    timer = setTimeout(() => giveUp('answer'), responseTimeoutMs);
+  };
+  phase.onSent = waitForAnswer;
+  timer = setTimeout(() => {
+    if (phase.sent) return;
+    // Provably never written: stop waiting, nothing was consumed.
+    if (phase.created) giveUp('send');
+    // A fetch that does not report its writes may already have sent it.
+    else waitForAnswer();
+  }, Math.max(0, sendDeadline - Date.now()));
+  try {
+    const response = await fetchImpl(url, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        'X-Request-Id': requestId,
+      },
+      body,
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    answered = true;
+    return { response, text };
+  } catch (error) {
+    const code = networkFailureCode(error);
+    const sent = phase.sent || (!phase.created && !UNSENT_FAILURE_CODES.has(code));
+    throw new TokenRequestFailure(error, { sent, timedOut });
+  } finally {
+    clearTimeout(timer);
+    stop();
+  }
+}
+
+/**
+ * POST to the token endpoint without abandoning an answer the server may
+ * already have acted on. A request that provably never reached the server is
+ * retried within the send budget; once written, a failure leaves the outcome
+ * unknown and is never replayed here (the server forgives a retry of the same
+ * token for a few minutes, so the next command recovers).
+ */
+async function postTokenRequest(url, body, fetchImpl = fetch, {
+  sendTimeoutMs = OAUTH_TOKEN_SEND_TIMEOUT_MS,
+  responseTimeoutMs = OAUTH_TOKEN_RESPONSE_TIMEOUT_MS,
+  unsentRetryDelaysMs = OAUTH_TOKEN_UNSENT_RETRY_DELAYS_MS,
+} = {}) {
+  const sendDeadline = Date.now() + sendTimeoutMs;
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      return await attemptTokenRequest(url, body, fetchImpl, { sendDeadline, responseTimeoutMs });
+    } catch (failure) {
+      const delay = unsentRetryDelaysMs[attempt];
+      if (failure.sent || delay === undefined || Date.now() + delay >= sendDeadline) throw failure;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+
+function refreshRetryError(runtime, code, message, cause) {
+  return new CliError({
+    code,
+    message,
+    exitCode: EXIT_CODES.network,
+    retryable: true,
+    hints: getRetryRecovery(runtime).hints,
+    cause,
+  });
+}
+
+// The answer to a refresh, or a retryable error that keeps the stored sign-in
+// untouched when the answer is missing or unreadable.
+function readRefreshAnswer(runtime, { response, text }) {
+  let payload = null;
+  try {
+    payload = JSON.parse(text);
+  } catch {
+    payload = null;
+  }
+  if (!response.ok) {
+    const details = payload && typeof payload === 'object' ? payload : {};
+    if (response.status >= 500 || response.status === 429) {
+      throw refreshRetryError(
+        runtime,
+        details.error || 'oauth_refresh_unavailable',
+        'The Notis sign-in server could not renew your session right now. Your sign-in is kept; run the command again.',
+      );
+    }
+    throw oauthError(
+      details.error || 'oauth_request_failed',
+      details.error_description || details.message || `OAuth request failed with status ${response.status}`,
+      null,
+      details,
+    );
+  }
+  if (
+    !payload
+    || typeof payload.access_token !== 'string'
+    || !payload.access_token
+    || typeof payload.refresh_token !== 'string'
+    || !payload.refresh_token
+  ) {
+    throw refreshRetryError(
+      runtime,
+      'oauth_refresh_outcome_unknown',
+      'The Notis sign-in server answered, but the renewed session could not be read. Your sign-in is kept; run the command again.',
+    );
+  }
+  return payload;
+}
+
+async function persistRefreshedSignIn(runtime, metadata, tokenResponse) {
+  let lastError = null;
+  for (const delay of [0, ...OAUTH_REFRESH_SAVE_RETRY_DELAYS_MS]) {
+    if (delay) await new Promise((resolve) => setTimeout(resolve, delay));
+    try {
+      return persistOAuthTokenResponse(runtime, metadata, tokenResponse);
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  // Never revoke the renewed sign-in here: it is the only valid one left. The
+  // server forgives presenting the previous token again for a few minutes.
+  throw new CliError({
+    code: 'oauth_refresh_not_saved',
+    message: 'Your renewed sign-in could not be saved on this computer. Run the command again in the next few minutes.',
+    exitCode: EXIT_CODES.unexpected,
+    retryable: true,
+    hints: getRetryRecovery(runtime).hints,
+    cause: lastError,
+  });
+}
+
 export async function discoverCliOAuth(apiBase, fetchImpl = fetch) {
   const normalizedApiBase = apiBase.replace(/\/+$/, '');
   const protectedResource = await fetchJson(
@@ -144,6 +401,9 @@ export async function discoverCliOAuth(apiBase, fetchImpl = fetch) {
     apiBase: normalizedApiBase,
     issuer,
     resource: protectedResource.resource,
+    scopesSupported: Array.isArray(protectedResource.scopes_supported)
+      ? protectedResource.scopes_supported
+      : [],
     clientId: protectedResource.notis_cli_client_id || 'notis_cli',
     copyPasteRedirectUri: protectedResource.notis_cli_copy_paste_redirect_uri,
     // A deployment that predates channel advertising, or a local one with no
@@ -407,7 +667,7 @@ function connectedCallbackHtml({ portalOrigin }) {
           <button class="button button-primary" id="download-desktop" type="button">Download Notis Desktop</button>
           <a class="button" href="${escapeHtml(webAppUrl)}">Open Web App</a>
         </div>
-        <p class="helper">The CLI stays connected even if you continue in the web app.</p>
+        <p class="helper">Desktop is available for macOS and Windows. The CLI stays connected even if you continue in the web app.</p>
       </section>
       <section class="next-step" id="desktop-ready-view" aria-labelledby="desktop-ready-title" hidden>
         <div class="status"><span class="status-dot"></span> Download started</div>
@@ -433,7 +693,6 @@ function connectedCallbackHtml({ portalOrigin }) {
         const resolveDownload = async () => {
           const ua = navigator.userAgent || '';
           if (/Windows/i.test(ua)) return downloads.base + '/win32/x64/notis-x64.exe';
-          if (/Linux/i.test(ua) && !/Android/i.test(ua)) return downloads.base + '/linux/x64/notis-linux-x64.zip';
           if (/Macintosh|Mac OS X/i.test(ua)) {
             let architecture = '';
             try {
@@ -450,6 +709,7 @@ function connectedCallbackHtml({ portalOrigin }) {
         const startDownload = async () => {
           const downloadUrl = await resolveDownload();
           window.open(downloadUrl, '_blank', 'noopener,noreferrer');
+          if (downloadUrl === downloads.fallback) return;
           connectedView.hidden = true;
           readyView.hidden = false;
           document.title = 'Quick login to Notis Desktop';
@@ -674,7 +934,19 @@ function storedOAuthMetadata(runtime, profile) {
   };
 }
 
-function buildAuthorizeUrl(metadata, {
+// This computer's id and name, so the server keeps one CLI sign-in per
+// computer and lists it as "Notis CLI on <computer>". Best effort: a sign-in
+// without them still works and maps to the shared legacy grant.
+function cliDeviceParams() {
+  try {
+    const identity = readComputerIdentity({ configFile: resolveConfigFile() });
+    return { device_id: identity.computerId, device_name: identity.displayName };
+  } catch {
+    return {};
+  }
+}
+
+export function buildAuthorizeUrl(metadata, {
   redirectUri,
   challenge,
   state,
@@ -689,6 +961,9 @@ function buildAuthorizeUrl(metadata, {
   url.searchParams.set('code_challenge', challenge);
   url.searchParams.set('code_challenge_method', 'S256');
   url.searchParams.set('state', state);
+  for (const [key, value] of Object.entries(cliDeviceParams())) {
+    url.searchParams.set(key, value);
+  }
   return url.toString();
 }
 
@@ -1969,7 +2244,7 @@ export async function loginWithOAuth(
   const metadata = await discoverCliOAuth(runtime.apiBase, fetchImpl);
   const scopes = options.scope?.length
     ? [...new Set(options.scope)]
-    : DEFAULT_CLI_OAUTH_SCOPES;
+    : defaultCliOAuthScopes(metadata);
   const timeoutMs = requestedTimeoutMs ?? DEFAULT_LOGIN_TIMEOUT_MS;
   // A detached listener is not a terminal waiting on a prompt: nobody is held
   // up by it, and the user still has to sign up and verify an email, so its
@@ -2393,18 +2668,18 @@ function pendingAuthorizationProfiles() {
 
 function lockIsStale() {
   try {
-    return Date.now() - statSync(OAUTH_LOCK_DIR).mtimeMs > 45_000;
+    return Date.now() - statSync(oauthLockDir()).mtimeMs > 45_000;
   } catch {
     return false;
   }
 }
 
-async function acquireRefreshLock(runtime, waitMs = 60_000) {
+async function acquireRefreshLock(runtime, waitMs = OAUTH_REFRESH_LOCK_WAIT_MS) {
   mkdirSync(join(homedir(), '.notis'), { recursive: true });
   const deadline = Date.now() + waitMs;
   for (;;) {
     try {
-      mkdirSync(OAUTH_LOCK_DIR);
+      mkdirSync(oauthLockDir());
       return true;
     } catch (error) {
       if (error?.code !== 'EEXIST') throw error;
@@ -2419,7 +2694,7 @@ async function acquireRefreshLock(runtime, waitMs = 60_000) {
       }
       if (lockIsStale()) {
         try {
-          rmdirSync(OAUTH_LOCK_DIR);
+          rmdirSync(oauthLockDir());
           continue;
         } catch {
           // The owner may have completed between stat and removal.
@@ -2433,20 +2708,38 @@ async function acquireRefreshLock(runtime, waitMs = 60_000) {
   }
 }
 
-export async function refreshOAuthCredential(runtime, fetchImpl = fetch) {
+// Touch lock folders while a refresh holds them, so their age keeps saying
+// "in use" for as long as the token request runs.
+function keepLockFoldersFresh(paths) {
+  const touch = () => {
+    const now = new Date();
+    for (const path of paths) {
+      try {
+        utimesSync(path, now, now);
+      } catch {
+        // Released, or retired by stale-lock recovery; nothing to keep.
+      }
+    }
+  };
+  const interval = setInterval(touch, OAUTH_REFRESH_LOCK_TOUCH_MS);
+  interval.unref?.();
+  return () => clearInterval(interval);
+}
+
+export async function refreshOAuthCredential(runtime, fetchImpl = fetch, tokenRequestOptions = {}) {
   // Refresh rotates the same stored grant that login publishes and logout
   // removes. Join their global -> profile lock order so a token rotation can
   // never be mistaken for a successor authorization by a concurrent logout.
-  const globalLock = await acquireListenerGlobalLock();
+  const globalLock = await acquireListenerGlobalLock({ waitMs: OAUTH_REFRESH_LOCK_WAIT_MS });
   let profileLock = null;
   let ownsLock = false;
+  let stopTouchingLocks = () => {};
   let metadata = null;
-  let rotatedResponse = null;
-  let rotatedPersisted = false;
   try {
     profileLock = await acquireListenerStartLock(runtime);
     ownsLock = await acquireRefreshLock(runtime);
     if (!ownsLock) return true;
+    stopTouchingLocks = keepLockFoldersFresh([profileLock, oauthLockDir()]);
     const config = loadConfig();
     const profile = getProfile(config, runtime.profileName);
     assertOAuthApiTarget(runtime, profile);
@@ -2463,28 +2756,43 @@ export async function refreshOAuthCredential(runtime, fetchImpl = fetch) {
     }
 
     metadata = storedOAuthMetadata(runtime, profile);
-    rotatedResponse = await fetchJson(
-      metadata.tokenEndpoint,
-      {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-        body: new URLSearchParams({
+    let answer;
+    try {
+      answer = await postTokenRequest(
+        metadata.tokenEndpoint,
+        new URLSearchParams({
           grant_type: 'refresh_token',
           refresh_token: profile.oauth_refresh_token,
           client_id: profile.oauth_client_id,
           resource: metadata.resource,
+          ...cliDeviceParams(),
         }),
-      },
-      fetchImpl,
-    );
-    const updated = persistOAuthTokenResponse(runtime, metadata, rotatedResponse);
-    rotatedPersisted = true;
+        fetchImpl,
+        tokenRequestOptions,
+      );
+    } catch (failure) {
+      if (!(failure instanceof TokenRequestFailure)) throw failure;
+      // The stored sign-in stays exactly as it was: either the server never
+      // saw this request, or it forgives the same token again for a while.
+      throw failure.sent
+        ? refreshRetryError(
+          runtime,
+          'oauth_refresh_outcome_unknown',
+          'The Notis sign-in server did not answer in time. Your sign-in is kept; run the command again.',
+          failure.cause,
+        )
+        : refreshRetryError(
+          runtime,
+          'oauth_refresh_unreachable',
+          'Could not reach the Notis sign-in server. Your sign-in is kept; check the connection and run the command again.',
+          failure.cause,
+        );
+    }
+    const rotatedResponse = readRefreshAnswer(runtime, answer);
+    const updated = await persistRefreshedSignIn(runtime, metadata, rotatedResponse);
     updateRuntimeFromOAuthProfile(runtime, updated);
     return true;
   } catch (error) {
-    if (rotatedResponse && !rotatedPersisted) {
-      await revokeCancelledToken(metadata, rotatedResponse, fetchImpl);
-    }
     if (error instanceof CliError) {
       throw new CliError({
         code: error.code,
@@ -2492,16 +2800,19 @@ export async function refreshOAuthCredential(runtime, fetchImpl = fetch) {
         exitCode: error.exitCode,
         retryable: error.retryable,
         details: error.details,
-        hints: getAuthRecovery(runtime).hints,
+        // A retryable failure keeps the sign-in, so its hint is to try again,
+        // never to sign in again.
+        hints: error.retryable ? error.hints : getAuthRecovery(runtime).hints,
         warnings: error.warnings,
         cause: error,
       });
     }
     throw error;
   } finally {
+    stopTouchingLocks();
     if (ownsLock) {
       try {
-        rmdirSync(OAUTH_LOCK_DIR);
+        rmdirSync(oauthLockDir());
       } catch {
         // A process exit or external cleanup may already have removed the lock.
       }