@sequenceholdings/studio-cli 0.1.13 → 0.1.21

package/dist/config.js

@@ -5,6 +5,7 @@ import { dirname, join } from 'node:path';
 import { parse as parseToml, stringify as stringifyToml } from 'smol-toml';
 import { M2mTokenError } from './auth.js';
 import { fetchCatalog, readCachedCatalog, } from './env-catalog.js';
+import { readRegisteredEnvironmentUrls } from './env-registry.js';
 import { resolvePreviewFromSlug } from './preview.js';
 /**
  * `--env preview:<branch-or-slug>` targets a per-PR Vercel preview deployment
@@ -45,10 +46,10 @@ export function defaultConfig() {
  *   1. built-in `local`
  *   2. the cached discovered catalog (`~/.config/lattice/environments.json`)
  *   3. user entries in config.toml (an override for `local`, or net-new envs)
+ *   4. OpCo registrations shared with seqapi (`~/.config/sequence-api/config.json`)
  *
- * If the config.toml file does not exist, defaults are returned — no
- * auto-write, since seq-studio should work out of the box without any
- * state on disk.
+ * Registered OpCo routes are authoritative for their names so a lower-trust
+ * config.toml override cannot send a tenant token to another origin.
  */
 export async function readConfig() {
     const merged = defaultConfig();
@@ -60,18 +61,22 @@ export async function readConfig() {
         }
     }
     const path = configPath();
-    if (!existsSync(path))
-        return merged;
-    const raw = parseToml(await readFile(path, 'utf8'));
-    if (raw.env) {
-        for (const [name, value] of Object.entries(raw.env)) {
-            if (typeof value?.url === 'string') {
-                merged.envs[name] = { url: value.url };
+    if (existsSync(path)) {
+        const raw = parseToml(await readFile(path, 'utf8'));
+        if (raw.env) {
+            for (const [name, value] of Object.entries(raw.env)) {
+                if (typeof value?.url === 'string') {
+                    merged.envs[name] = { url: value.url };
+                }
             }
         }
+        if (typeof raw.default_env === 'string') {
+            merged.defaultEnv = raw.default_env;
+        }
     }
-    if (typeof raw.default_env === 'string') {
-        merged.defaultEnv = raw.default_env;
+    const registered = await readRegisteredEnvironmentUrls();
+    for (const [name, value] of Object.entries(registered)) {
+        merged.envs[name] = value;
     }
     return merged;
 }
@@ -111,7 +116,7 @@ export function manualEnvConfigHint() {
     return (`Or add an environment manually in ${configPath()} (append-safe):\n` +
         `\n` +
         `  [env.my-env]\n` +
-        `  url = "https://your-atlas-host.example.com"\n` +
+        `  url = "https://my-atlas.seqholdings.com"\n` +
         `\n` +
         `To make it the default, put \`default_env = "my-env"\` at the TOP of ` +
         `that file — before any [env.*] table.`);

package/dist/env-catalog.js

@@ -2,6 +2,7 @@ import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join } from 'node:path';
+import { authenticatedRequestUrl } from '@sequenceholdings/artifact-studio/deployment-validation';
 import { currentIdentitySubject, decodeJwtSub, tryGetAccessToken } from './auth.js';
 const DEFAULT_BOOTSTRAP_URL = 'https://atlas.seqholdings.com';
 /** The host the discovery call goes to. Override for tests / self-hosting. */
@@ -74,23 +75,32 @@ export async function clearCatalog() {
  * callers can distinguish "offline" from "not authorized".
  */
 export async function fetchCatalog() {
+    const targetUrl = bootstrapUrl();
+    const requestUrl = authenticatedRequestUrl({
+        baseUrl: targetUrl,
+        path: '/api/platform/environments',
+    });
     // Fail closed when an M2M secret is configured but minting fails, so
     // headless callers (CI) see the real Auth0 error instead of a silent
     // downgrade to the anonymous tier.
-    const token = await tryGetAccessToken({ failClosedForM2m: true });
+    const token = await tryGetAccessToken({
+        failClosedForM2m: true,
+        targetUrl,
+    });
     if (!token) {
         await clearCatalog();
         return null;
     }
-    const response = await fetch(`${bootstrapUrl()}/api/platform/environments`, {
+    const response = await fetch(requestUrl, {
         headers: { Authorization: `Bearer ${token}` },
+        redirect: 'manual',
     });
     if (response.status === 401 || response.status === 403) {
         await clearCatalog();
         return null;
     }
     if (!response.ok) {
-        throw new Error(`Environment discovery failed (${response.status}) against ${bootstrapUrl()}.`);
+        throw new Error(`Environment discovery failed (${response.status}) against ${targetUrl}.`);
     }
     const body = (await response.json());
     if ((body.tier !== 'sequence' && body.tier !== 'partner') ||

package/dist/env-flags.d.ts

@@ -3,6 +3,8 @@
  * CLIs only recognize the two-token `--env <value>` form, so every `-e value`
  * / `-e=value` / `--env=value` spelling is rewritten before forwarding.
  */
+/** Shared copy for network commands that must not silently fall back to `local`. */
+export declare const REQUIRE_EXPLICIT_ENV_MESSAGE = "You must specify an environment you have access to with `-e <env>`. Run `seq-studio envs list` to see available environments.";
 export declare function normalizeShortEnvFlag(argv: readonly string[]): string[];
 /** Only valid AFTER normalizeShortEnvFlag — recognizes the two-token form. */
 export declare function readEnvFromArgv(rest: readonly string[]): string | undefined;

package/dist/env-flags.js

@@ -3,6 +3,8 @@
  * CLIs only recognize the two-token `--env <value>` form, so every `-e value`
  * / `-e=value` / `--env=value` spelling is rewritten before forwarding.
  */
+/** Shared copy for network commands that must not silently fall back to `local`. */
+export const REQUIRE_EXPLICIT_ENV_MESSAGE = 'You must specify an environment you have access to with `-e <env>`. Run `seq-studio envs list` to see available environments.';
 export function normalizeShortEnvFlag(argv) {
     const out = [];
     for (let i = 0; i < argv.length; i++) {

package/dist/env-registry.d.ts

@@ -0,0 +1,27 @@
+interface DiscoveredRealm {
+    domain: string;
+    clientId: string;
+    audience: string;
+    organization?: string;
+    m2mClientId?: string;
+}
+interface RegistrationResult {
+    name: string;
+    baseUrl: string;
+    replacing: boolean;
+    realm: DiscoveredRealm;
+}
+export declare function seqapiConfigPath(): string;
+export declare function readRegisteredEnvironmentUrls({ configFile, }?: {
+    configFile?: string;
+}): Promise<Record<string, {
+    url: string;
+}>>;
+export declare function registerEnvironment({ baseUrl: rawBaseUrl, clearCredentials, configFile, fetchImpl, name: rawName, }: {
+    baseUrl: string;
+    clearCredentials?: (name: string) => Promise<void>;
+    configFile?: string;
+    fetchImpl?: typeof fetch;
+    name: string;
+}): Promise<RegistrationResult>;
+export {};

package/dist/env-registry.js

@@ -0,0 +1,204 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { validateDeploymentAudience, validateDeploymentBaseUrl, } from '@sequenceholdings/artifact-studio/deployment-validation';
+import { deleteRealmTokens, isSequenceAuthEnvName, validateAuth0Domain, } from './auth.js';
+import { withCrossProcessFileLock } from './file-lock.js';
+const DISCOVERY_PATH = '/api/auth/cli-config';
+const ENV_NAME_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function hasErrorCode(error, code) {
+    return error instanceof Error && Reflect.get(error, 'code') === code;
+}
+function optionalString(value) {
+    return typeof value === 'string' && value ? value : undefined;
+}
+export function seqapiConfigPath() {
+    return join(homedir(), '.config', 'sequence-api', 'config.json');
+}
+function validateEnvironmentName(input) {
+    const name = input.toLowerCase();
+    if (!ENV_NAME_PATTERN.test(name)) {
+        throw new Error(`Invalid environment name '${input}': use lowercase letters, digits, and hyphens.`);
+    }
+    if (isSequenceAuthEnvName(name)) {
+        throw new Error(`'${name}' is a reserved built-in environment name.`);
+    }
+    return name;
+}
+async function discoverRealm({ baseUrl, fetchImpl, }) {
+    const url = `${baseUrl}${DISCOVERY_PATH}`;
+    let response;
+    try {
+        response = await fetchImpl(url, {
+            redirect: 'manual',
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (error) {
+        throw new Error(`Could not reach ${url}: ${error instanceof Error ? error.message : error}`, {
+            cause: error,
+        });
+    }
+    if (response.status >= 300 && response.status < 400) {
+        throw new Error(`${url} redirected to ${JSON.stringify(response.headers.get('location'))}; ` +
+            'CLI discovery redirects are not allowed.');
+    }
+    if (response.status === 404) {
+        throw new Error(`${url} returned 404 — this deployment does not expose the CLI discovery endpoint yet.`);
+    }
+    if (!response.ok) {
+        throw new Error(`${url} returned HTTP ${response.status}: ${(await response.text()).slice(0, 300)}`);
+    }
+    let data;
+    try {
+        data = await response.json();
+    }
+    catch (error) {
+        throw new Error(`${url} did not return JSON.`, { cause: error });
+    }
+    const auth0 = isRecord(data) ? Reflect.get(data, 'auth0') : undefined;
+    if (!isRecord(auth0)) {
+        throw new Error(`${url} response is missing auth0 configuration.`);
+    }
+    const domain = optionalString(Reflect.get(auth0, 'domain'));
+    const clientId = optionalString(Reflect.get(auth0, 'clientId'));
+    const audience = optionalString(Reflect.get(auth0, 'audience'));
+    const missing = [
+        !domain ? 'domain' : null,
+        !clientId ? 'clientId' : null,
+        !audience ? 'audience' : null,
+    ].filter((key) => key !== null);
+    if (missing.length > 0 || !domain || !clientId || !audience) {
+        throw new Error(`${url} response is missing auth0.{${missing.join(', ')}}.`);
+    }
+    return {
+        domain: validateAuth0Domain(domain),
+        clientId,
+        audience: validateDeploymentAudience({ audience, baseUrl }),
+        organization: optionalString(Reflect.get(auth0, 'organization')),
+        m2mClientId: optionalString(Reflect.get(auth0, 'm2mClientId')),
+    };
+}
+async function loadConfig(configFile) {
+    try {
+        const parsed = JSON.parse(await readFile(configFile, 'utf8'));
+        if (!isRecord(parsed))
+            throw new Error('root value must be an object');
+        return parsed;
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return {};
+        throw new Error(`Could not read tenant auth registry ${configFile}.`, { cause: error });
+    }
+}
+export async function readRegisteredEnvironmentUrls({ configFile = seqapiConfigPath(), } = {}) {
+    let config;
+    try {
+        config = await loadConfig(configFile);
+    }
+    catch {
+        // Aggregate routing degrades to built-ins/catalog/config.toml when the
+        // registry is corrupt. Explicit auth use still fails loudly in realmForEnv.
+        return {};
+    }
+    const stored = Reflect.get(config, 'environments');
+    if (!isRecord(stored))
+        return {};
+    const valid = {};
+    for (const [name, value] of Object.entries(stored)) {
+        try {
+            if (validateEnvironmentName(name) !== name || !isRecord(value))
+                continue;
+            const auth0 = Reflect.get(value, 'auth0');
+            const rawUrl = Reflect.get(value, 'url');
+            if (!isRecord(auth0) || typeof rawUrl !== 'string')
+                continue;
+            const domain = optionalString(Reflect.get(auth0, 'domain'));
+            const clientId = optionalString(Reflect.get(auth0, 'client_id'));
+            const audience = optionalString(Reflect.get(auth0, 'audience'));
+            if (!domain || !clientId || !audience)
+                continue;
+            validateAuth0Domain(domain);
+            const url = validateDeploymentBaseUrl(rawUrl);
+            validateDeploymentAudience({ audience, baseUrl: url });
+            valid[name] = { url };
+        }
+        catch {
+            // Aggregate routing skips malformed entries; explicit auth use still
+            // fails closed with a detailed error from realmForEnv.
+        }
+    }
+    return valid;
+}
+async function writeConfig(configFile, config) {
+    await mkdir(dirname(configFile), { recursive: true });
+    const temporary = `${configFile}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(config, null, 2) + '\n', {
+            encoding: 'utf8',
+            mode: 0o600,
+            flag: 'wx',
+        });
+        await rename(temporary, configFile);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function clearImpersonationForEnv({ configFile, name, }) {
+    const impersonationFile = join(dirname(configFile), 'impersonation.json');
+    try {
+        const parsed = JSON.parse(await readFile(impersonationFile, 'utf8'));
+        const env = isRecord(parsed) ? Reflect.get(parsed, 'env') : undefined;
+        if (env === undefined || env === null || env === name) {
+            await rm(impersonationFile, { force: true });
+        }
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'ENOENT'))
+            throw error;
+    }
+}
+async function clearEnvironmentCredentials({ configFile, name, }) {
+    await deleteRealmTokens(name);
+    await clearImpersonationForEnv({ configFile, name });
+}
+export async function registerEnvironment({ baseUrl: rawBaseUrl, clearCredentials, configFile = seqapiConfigPath(), fetchImpl = fetch, name: rawName, }) {
+    const name = validateEnvironmentName(rawName);
+    const baseUrl = validateDeploymentBaseUrl(rawBaseUrl);
+    const realm = await discoverRealm({ baseUrl, fetchImpl });
+    // Lock ordering contract: credential cleanup may acquire tokens.json.lock
+    // while this is held; token-file code must never acquire config.json.lock.
+    const replacing = await withCrossProcessFileLock({
+        path: configFile,
+        operation: async () => {
+            const config = await loadConfig(configFile);
+            const existingEnvironments = Reflect.get(config, 'environments');
+            const environments = isRecord(existingEnvironments) ? { ...existingEnvironments } : {};
+            const isReplacement = Reflect.has(environments, name);
+            // Clear unconditionally: a manually removed or partially written
+            // registration can leave orphaned credentials even when no entry exists.
+            await (clearCredentials
+                ? clearCredentials(name)
+                : clearEnvironmentCredentials({ configFile, name }));
+            environments[name] = {
+                url: baseUrl,
+                auth0: {
+                    domain: realm.domain,
+                    client_id: realm.clientId,
+                    audience: realm.audience,
+                    organization: realm.organization ?? null,
+                    m2m_client_id: realm.m2mClientId ?? null,
+                },
+            };
+            await writeConfig(configFile, { ...config, environments });
+            return isReplacement;
+        },
+    });
+    return { name, baseUrl, replacing, realm };
+}

package/dist/envs/commands.d.ts

@@ -1 +1 @@
-export declare function runEnvsCommand(sub: string | undefined, _rest: string[]): Promise<number>;
+export declare function runEnvsCommand(sub: string | undefined, rest: string[]): Promise<number>;

package/dist/envs/commands.js

@@ -1,9 +1,12 @@
 import { tryGetAccessToken } from '../auth.js';
 import { readConfig, configPath, manualEnvConfigHint } from '../config.js';
+import { readRegisteredEnvironmentUrls, registerEnvironment, } from '../env-registry.js';
 import { bootstrapUrl, fetchCatalog, readCachedCatalog, } from '../env-catalog.js';
 const ENVS_USAGE = `usage:
   seq-studio envs list      show the environments visible to your identity
   seq-studio envs refresh   re-fetch the environment catalog for your identity
+  seq-studio envs add <name> <url>
+                            register an OpCo deployment from public discovery
 
   The published CLI ships with only the "local" environment. After you
   authenticate (seq-studio login, or AUTH0_M2M_CLIENT_SECRET for headless use),
@@ -13,8 +16,10 @@ const ENVS_USAGE = `usage:
 
   Custom entries in ${configPath()} are always honored on top.
 `;
-export async function runEnvsCommand(sub, _rest) {
+export async function runEnvsCommand(sub, rest) {
     switch (sub) {
+        case 'add':
+            return addCommand(rest);
         case 'list':
             return listCommand();
         case 'refresh':
@@ -31,6 +36,32 @@ export async function runEnvsCommand(sub, _rest) {
             return 1;
     }
 }
+async function addCommand(rest) {
+    const [name, baseUrl, ...extra] = rest;
+    if (!name || !baseUrl || extra.length > 0) {
+        console.error('usage: seq-studio envs add <name> <url>');
+        return 1;
+    }
+    try {
+        const registration = await registerEnvironment({ name, baseUrl });
+        const verb = registration.replacing ? 'Updated' : 'Registered';
+        console.log(`${verb} environment '${registration.name}' -> ${registration.baseUrl}`);
+        console.log(`  auth0 domain:   ${registration.realm.domain}`);
+        console.log(`  audience:       ${registration.realm.audience}`);
+        console.log(`  organization:   ${registration.realm.organization ?? '(none)'}`);
+        if (registration.realm.m2mClientId) {
+            const suffix = registration.name.toUpperCase().replaceAll('-', '_');
+            console.log(`  m2m client:     ${registration.realm.m2mClientId} ` +
+                `(headless: export AUTH0_M2M_CLIENT_SECRET_${suffix}=...)`);
+        }
+        console.log(`Next: seq-studio login --env ${registration.name}`);
+        return 0;
+    }
+    catch (error) {
+        console.error(`envs add: FAIL — ${error instanceof Error ? error.message : String(error)}`);
+        return 1;
+    }
+}
 /**
  * Tier `anonymous` means "no catalog cached", not necessarily "no token".
  * Shared by list + refresh so they don't contradict each other.
@@ -50,8 +81,13 @@ async function printNoCatalogGuidance(log = console.log) {
     log(manualEnvConfigHint());
 }
 async function listCommand() {
-    const [config, catalog] = await Promise.all([readConfig(), readCachedCatalog()]);
+    const [config, catalog, registered] = await Promise.all([
+        readConfig(),
+        readCachedCatalog(),
+        readRegisteredEnvironmentUrls(),
+    ]);
     const discovered = new Set(catalog?.environments.map((env) => env.name) ?? []);
+    const registeredNames = new Set(Object.keys(registered));
     console.log(`tier: ${config.tier}`);
     if (catalog) {
         console.log(`catalog fetched: ${new Date(catalog.fetchedAt).toISOString()}`);
@@ -63,7 +99,9 @@ async function listCommand() {
             ? 'built-in'
             : discovered.has(name)
                 ? 'discovered'
-                : 'config.toml';
+                : registeredNames.has(name)
+                    ? 'registered'
+                    : 'config.toml';
         console.log(`  ${name.padEnd(width)}  ${url}  (${source})`);
     }
     if (config.tier === 'anonymous') {

package/dist/file-lock.d.ts

@@ -0,0 +1,5 @@
+export declare function tryReapStaleLock(lockPath: string, observedOwner: string): Promise<void>;
+export declare function withCrossProcessFileLock<T>({ operation, path, }: {
+    operation: () => Promise<T>;
+    path: string;
+}): Promise<T>;

package/dist/file-lock.js

@@ -0,0 +1,187 @@
+import { randomUUID } from 'node:crypto';
+import { link, mkdir, open, readFile, rename, stat, unlink } from 'node:fs/promises';
+import { dirname } from 'node:path';
+const LOCK_TIMEOUT_MS = 10_000;
+const LOCK_STALE_MS = 30_000;
+function hasErrorCode(error, code) {
+    return error instanceof Error && Reflect.get(error, 'code') === code;
+}
+function ownerProcessIsAlive(owner) {
+    const separator = owner.indexOf('-');
+    const pid = Number(owner.slice(0, separator));
+    if (separator <= 0 || !Number.isSafeInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !hasErrorCode(error, 'ESRCH');
+    }
+}
+async function createExclusiveFile(path, contents) {
+    const temporary = `${path}.publish.${process.pid}.${randomUUID()}`;
+    const handle = await open(temporary, 'wx', 0o600);
+    try {
+        await handle.writeFile(contents, { encoding: 'utf8' });
+    }
+    catch (error) {
+        await handle.close().catch(() => undefined);
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    try {
+        await handle.close();
+    }
+    catch (error) {
+        await unlink(temporary).catch(() => undefined);
+        throw error;
+    }
+    try {
+        await link(temporary, path);
+    }
+    finally {
+        await unlink(temporary).catch(() => undefined);
+    }
+}
+async function restoreClaimedLock(reapPath, lockPath) {
+    try {
+        await link(reapPath, lockPath);
+    }
+    catch (error) {
+        if (!hasErrorCode(error, 'EEXIST'))
+            throw error;
+    }
+}
+async function claimObservedOwnerFile({ claimLabel, observedOwner, path, }) {
+    const claimedPath = `${path}.${claimLabel}.${process.pid}.${randomUUID()}`;
+    try {
+        await rename(path, claimedPath);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'ENOENT'))
+            return undefined;
+        throw error;
+    }
+    try {
+        if ((await readFile(claimedPath, 'utf8')) !== observedOwner) {
+            await restoreClaimedLock(claimedPath, path);
+            await unlink(claimedPath);
+            return undefined;
+        }
+        return claimedPath;
+    }
+    catch {
+        // The process-unique claim may have been concurrently cleaned up.
+        return undefined;
+    }
+}
+async function tryReapOrphanedGuard(guardPath) {
+    let observedOwner;
+    try {
+        observedOwner = await readFile(guardPath, 'utf8');
+    }
+    catch {
+        return;
+    }
+    if (ownerProcessIsAlive(observedOwner))
+        return;
+    const orphanPath = await claimObservedOwnerFile({
+        claimLabel: 'orphan',
+        observedOwner,
+        path: guardPath,
+    });
+    if (orphanPath) {
+        await unlink(orphanPath).catch(() => undefined);
+    }
+}
+export async function tryReapStaleLock(lockPath, observedOwner) {
+    const guardPath = `${lockPath}.reaper`;
+    try {
+        await createExclusiveFile(guardPath, `${process.pid}-${randomUUID()}`);
+    }
+    catch (error) {
+        if (hasErrorCode(error, 'EEXIST')) {
+            await tryReapOrphanedGuard(guardPath);
+            return;
+        }
+        throw error;
+    }
+    try {
+        let stillCurrent;
+        let stillStale;
+        try {
+            stillCurrent = (await readFile(lockPath, 'utf8')) === observedOwner;
+            stillStale = Date.now() - (await stat(lockPath)).mtimeMs > LOCK_STALE_MS;
+        }
+        catch {
+            return;
+        }
+        if (!stillCurrent || !stillStale || ownerProcessIsAlive(observedOwner))
+            return;
+        const reapPath = await claimObservedOwnerFile({
+            claimLabel: 'reap',
+            observedOwner,
+            path: lockPath,
+        });
+        if (reapPath) {
+            await unlink(reapPath).catch(() => undefined);
+        }
+    }
+    finally {
+        try {
+            await unlink(guardPath);
+        }
+        catch {
+            // The guard was already removed; never mask the protected operation.
+        }
+    }
+}
+export async function withCrossProcessFileLock({ operation, path, }) {
+    const lockPath = `${path}.lock`;
+    const owner = `${process.pid}-${randomUUID()}`;
+    const deadline = Date.now() + LOCK_TIMEOUT_MS;
+    await mkdir(dirname(path), { recursive: true });
+    while (true) {
+        try {
+            await createExclusiveFile(lockPath, owner);
+            break;
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'EEXIST'))
+                throw error;
+            let observed;
+            let isStale;
+            try {
+                observed = await readFile(lockPath, 'utf8');
+                isStale = Date.now() - (await stat(lockPath)).mtimeMs > LOCK_STALE_MS;
+            }
+            catch (checkError) {
+                if (hasErrorCode(checkError, 'ENOENT'))
+                    continue;
+                throw checkError;
+            }
+            if (isStale && !ownerProcessIsAlive(observed)) {
+                await tryReapStaleLock(lockPath, observed);
+                continue;
+            }
+            if (Date.now() >= deadline) {
+                throw new Error(`Timed out waiting for another CLI to update ${path}.`);
+            }
+            await new Promise((resolve) => setTimeout(resolve, 50));
+        }
+    }
+    try {
+        return await operation();
+    }
+    finally {
+        try {
+            if ((await readFile(lockPath, 'utf8')) === owner) {
+                await unlink(lockPath);
+            }
+        }
+        catch {
+            // Never mask the operation result when the lock was already recovered.
+        }
+    }
+}