primitive-admin 1.2.0-alpha.6 → 1.2.0-alpha.8

package/dist/src/lib/credentials-home.js

@@ -0,0 +1,169 @@
+/**
+ * Where a project's login lives (#4492).
+ *
+ * A project's credentials file is `<projectRoot>/.primitive/credentials.json`,
+ * except in a linked git worktree: there it is the main worktree's file for
+ * the same project, so a new worktree of a logged-in project is logged in.
+ * Every worktree reads and writes that one file; everything else under
+ * `.primitive/` (the selection, machine-local environments, sync state,
+ * backups) stays per worktree.
+ *
+ * The answer is the project root itself whenever there is no main checkout to
+ * share with: outside a git repository, without a git that knows
+ * `--path-format` (2.31), in the main worktree, in a bare repository's
+ * worktrees, and in a linked worktree whose main checkout does not hold the
+ * project. Nothing here throws.
+ */
+import { execFileSync } from "child_process";
+import { existsSync, realpathSync, statSync } from "fs";
+import { basename, dirname, isAbsolute, join, relative } from "path";
+import { PROJECT_CONFIG_FILENAME, PROJECT_LOCAL_STATE_DIR, PROJECT_TREE_DIR, } from "./env-resolver-core.js";
+const resolutions = new Map();
+function git(cwd, args) {
+    return execFileSync("git", args, {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+}
+/** The project root's path relative to its worktree's top level, or null. */
+function relativeToTopLevel(topLevel, projectRoot) {
+    const rel = relative(realpathSync(topLevel), realpathSync(projectRoot));
+    return rel.startsWith("..") || isAbsolute(rel) ? null : rel;
+}
+function holdsProject(projectRoot) {
+    return existsSync(join(projectRoot, PROJECT_TREE_DIR, PROJECT_CONFIG_FILENAME));
+}
+function resolve(projectRoot) {
+    const own = { root: projectRoot, gitFailed: false };
+    let gitDir;
+    let commonDir;
+    let topLevel;
+    try {
+        [gitDir, commonDir, topLevel] = git(projectRoot, [
+            "rev-parse",
+            "--path-format=absolute",
+            "--git-dir",
+            "--git-common-dir",
+            "--show-toplevel",
+        ]).split("\n");
+    }
+    catch {
+        return { root: projectRoot, gitFailed: true };
+    }
+    if (!gitDir || !commonDir || !topLevel)
+        return own;
+    if (gitDir === commonDir)
+        return own; // the main worktree
+    if (basename(commonDir) !== ".git")
+        return own; // a bare repository's worktree
+    try {
+        const rel = relativeToTopLevel(topLevel, projectRoot);
+        if (rel === null)
+            return own;
+        const candidate = join(dirname(commonDir), rel);
+        return holdsProject(candidate) ? { root: candidate, gitFailed: false } : own;
+    }
+    catch {
+        return own;
+    }
+}
+function resolutionFor(projectRoot) {
+    let resolution = resolutions.get(projectRoot);
+    if (!resolution) {
+        resolution = resolve(projectRoot);
+        resolutions.set(projectRoot, resolution);
+    }
+    return resolution;
+}
+/**
+ * The project root whose `.primitive/credentials.json` holds `projectRoot`'s
+ * login: the same project in the main worktree when `projectRoot` is in a
+ * linked git worktree and the main worktree holds the project, otherwise
+ * `projectRoot` itself. Cached per process per project root.
+ */
+export function credentialsRootFor(projectRoot) {
+    return resolutionFor(projectRoot).root;
+}
+/**
+ * Forget every cached {@link credentialsRootFor} answer. One invocation
+ * resolves one project, so nothing in the CLI calls this; it exists for tests.
+ */
+export function resetCredentialsHomeCache() {
+    resolutions.clear();
+}
+/**
+ * Whether the nearest `.git` above `projectRoot` is a file, which is how a
+ * linked worktree is marked. Read without running git.
+ */
+export function linkedWorktreeMarker(projectRoot) {
+    for (let dir = projectRoot;; dir = dirname(dir)) {
+        const marker = join(dir, ".git");
+        try {
+            if (existsSync(marker))
+                return statSync(marker).isFile();
+        }
+        catch {
+            return false;
+        }
+        if (dirname(dir) === dir)
+            return false;
+    }
+}
+/**
+ * Why a linked worktree is not using the main checkout's login, when that is
+ * git's doing: git could not answer and the project sits in a linked
+ * worktree. Null otherwise.
+ */
+export function oldGitHint(projectRoot) {
+    return resolutionFor(projectRoot).gitFailed && linkedWorktreeMarker(projectRoot)
+        ? "This looks like a linked git worktree; sharing the main checkout's login needs git 2.31 or newer."
+        : null;
+}
+/**
+ * The linked worktree's own `.primitive/credentials.json` when it exists but
+ * the main worktree's is the one used, or null. It is never read or changed.
+ */
+export function ignoredLocalCredentialsFile(projectRoot) {
+    if (credentialsRootFor(projectRoot) === projectRoot)
+        return null;
+    const own = join(projectRoot, PROJECT_LOCAL_STATE_DIR, "credentials.json");
+    return existsSync(own) ? own : null;
+}
+function samePath(a, b) {
+    try {
+        return realpathSync(a) === realpathSync(b);
+    }
+    catch {
+        return a === b;
+    }
+}
+/**
+ * How many worktrees of `projectRoot`'s repository hold the project and share
+ * its login: the worktrees `git worktree list` names, except a bare entry,
+ * whose copy of the project resolves to the same credentials home. At least
+ * 1; 1 on any git failure.
+ */
+export function sharedWorktreeCount(projectRoot) {
+    try {
+        const rel = relativeToTopLevel(git(projectRoot, ["rev-parse", "--show-toplevel"]), projectRoot);
+        if (rel === null)
+            return 1;
+        const home = credentialsRootFor(projectRoot);
+        let count = 0;
+        for (const entry of git(projectRoot, ["worktree", "list", "--porcelain"]).split(/\n\s*\n/)) {
+            const lines = entry.split("\n");
+            const worktree = lines.find((line) => line.startsWith("worktree "))?.slice("worktree ".length);
+            if (!worktree || lines.includes("bare"))
+                continue;
+            const candidate = join(worktree, rel);
+            if (holdsProject(candidate) && samePath(credentialsRootFor(candidate), home))
+                count++;
+        }
+        return Math.max(count, 1);
+    }
+    catch {
+        return 1;
+    }
+}
+//# sourceMappingURL=credentials-home.js.map

package/dist/src/lib/credentials-home.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials-home.js","sourceRoot":"","sources":["../../../src/lib/credentials-home.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/credentials-lock.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The cross-process lock and atomic replace every project-mode credentials
+ * write goes through (#4492).
+ *
+ * Several CLI processes write one credentials file — one agent per git
+ * worktree, all sharing the main worktree's login — so a write is a locked
+ * read-modify-write, and the file is replaced by a rename, never rewritten in
+ * place: a reader never sees a partial file.
+ *
+ * The lock is `credentials.json.lock`, created exclusively and holding its
+ * owner's token (`<pid>:<random>`). A lock older than {@link LOCK_STALE_MS}
+ * was left by a crashed process; a contender reclaims it by renaming it to a
+ * name of its own, which exactly one contender can do, and removes it only if
+ * it still holds the token it read — otherwise a live lock was moved, and it
+ * is put back unless another writer took the lock meanwhile. A holder proves,
+ * immediately before it commits, that it still owns the lock and that the file
+ * is still the version it read — a holder whose lock was moved away and put
+ * back may have missed another writer's commit in between — and releases only
+ * its own lock.
+ *
+ * Node has no advisory file lock, so one window remains: between a holder's
+ * checks and its rename, a contender that just misreclaimed that lock could
+ * let a third writer in. Every other interleaving ends in a failed write,
+ * never a lost update.
+ */
+/** A lock untouched for this long was left by a crashed process. */
+export declare const LOCK_STALE_MS = 10000;
+/** How long a writer waits for a held lock before it fails. */
+export declare const LOCK_WAIT_MS = 5000;
+/** The lock on a credentials directory, held by this process. */
+export interface CredentialsLock {
+    /** The lock file. */
+    readonly path: string;
+    /** This holder's token, the lock file's content while it holds it. */
+    readonly token: string;
+    /** Whether the lock file still holds this holder's token. */
+    ownsLock(): boolean;
+    /** Remove the lock if, and only if, this holder still owns it. Never throws. */
+    release(): void;
+}
+/** A write that could not take, or lost, the lock on a credentials file. */
+export declare class CredentialsLockedError extends Error {
+    constructor(lockPath: string);
+}
+/**
+ * Reclaim the stale lock at `lockPath`, whose content was `seen` when it was
+ * judged stale: rename it to a name of `token`'s own, then remove it if it
+ * still holds `seen`, or put it back if it does not (a live writer took the
+ * lock in between). Gone already is not an error: another contender won.
+ */
+export declare function reclaimStaleLock(lockPath: string, token: string, seen: string): void;
+/**
+ * Put a live lock that a reclaimer moved to `moved` back at `lockPath` — but
+ * only if no other writer has taken the lock since, which a rename would
+ * silently replace. When one has, the displaced holder has lost the lock and
+ * fails its ownership check. The caller removes `moved` either way.
+ */
+export declare function restoreDisplacedLock(moved: string, lockPath: string): void;
+/**
+ * The version of the file at `path` as a writer read it: what an atomic
+ * replace changes (the inode) and what an in-place write changes (size and
+ * times). `"absent"` when there is no file.
+ */
+export declare function fileVersion(path: string): string;
+/**
+ * Take the lock on the credentials file in `dir`, waiting up to
+ * {@link LOCK_WAIT_MS} for another writer and reclaiming a stale lock. Throws
+ * {@link CredentialsLockedError} naming the lock when it stays held.
+ */
+export declare function acquireCredentialsLock(dir: string): CredentialsLock;
+/**
+ * Replace `path` with `content` while `lock` is held: write a private
+ * temporary file beside it, check the lock is still this holder's and, when
+ * `readVersion` is given, that `path` is still the {@link fileVersion} the
+ * holder read under the lock, then rename the temporary file over `path`. A
+ * holder that lost the lock, or whose read another writer's commit has
+ * overtaken, removes its temporary file and throws
+ * {@link CredentialsLockedError}, leaving `path` as it was.
+ */
+export declare function replaceFileUnderLock(lock: CredentialsLock, path: string, content: string, readVersion?: string): void;

package/dist/src/lib/credentials-lock.js

@@ -0,0 +1,222 @@
+/**
+ * The cross-process lock and atomic replace every project-mode credentials
+ * write goes through (#4492).
+ *
+ * Several CLI processes write one credentials file — one agent per git
+ * worktree, all sharing the main worktree's login — so a write is a locked
+ * read-modify-write, and the file is replaced by a rename, never rewritten in
+ * place: a reader never sees a partial file.
+ *
+ * The lock is `credentials.json.lock`, created exclusively and holding its
+ * owner's token (`<pid>:<random>`). A lock older than {@link LOCK_STALE_MS}
+ * was left by a crashed process; a contender reclaims it by renaming it to a
+ * name of its own, which exactly one contender can do, and removes it only if
+ * it still holds the token it read — otherwise a live lock was moved, and it
+ * is put back unless another writer took the lock meanwhile. A holder proves,
+ * immediately before it commits, that it still owns the lock and that the file
+ * is still the version it read — a holder whose lock was moved away and put
+ * back may have missed another writer's commit in between — and releases only
+ * its own lock.
+ *
+ * Node has no advisory file lock, so one window remains: between a holder's
+ * checks and its rename, a contender that just misreclaimed that lock could
+ * let a third writer in. Every other interleaving ends in a failed write,
+ * never a lost update.
+ */
+import { randomBytes } from "crypto";
+import { chmodSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync, } from "fs";
+import { basename, dirname, join } from "path";
+/** A lock untouched for this long was left by a crashed process. */
+export const LOCK_STALE_MS = 10_000;
+/** How long a writer waits for a held lock before it fails. */
+export const LOCK_WAIT_MS = 5_000;
+const RETRY_MS = 25;
+const LOCKED_FILE = "credentials.json";
+/** A write that could not take, or lost, the lock on a credentials file. */
+export class CredentialsLockedError extends Error {
+    constructor(lockPath) {
+        super(`credentials file is locked: ${lockPath}`);
+        this.name = "CredentialsLockedError";
+    }
+}
+function sleep(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+const isMissing = (err) => err?.code === "ENOENT";
+/**
+ * Reclaim the stale lock at `lockPath`, whose content was `seen` when it was
+ * judged stale: rename it to a name of `token`'s own, then remove it if it
+ * still holds `seen`, or put it back if it does not (a live writer took the
+ * lock in between). Gone already is not an error: another contender won.
+ */
+export function reclaimStaleLock(lockPath, token, seen) {
+    const moved = `${lockPath}.stale.${token}`;
+    try {
+        renameSync(lockPath, moved);
+    }
+    catch (err) {
+        if (isMissing(err))
+            return;
+        throw err;
+    }
+    let content;
+    try {
+        content = readFileSync(moved, "utf-8");
+    }
+    catch {
+        return;
+    }
+    if (content !== seen)
+        restoreDisplacedLock(moved, lockPath);
+    try {
+        unlinkSync(moved);
+    }
+    catch {
+        // Swept by the next release.
+    }
+}
+/**
+ * Put a live lock that a reclaimer moved to `moved` back at `lockPath` — but
+ * only if no other writer has taken the lock since, which a rename would
+ * silently replace. When one has, the displaced holder has lost the lock and
+ * fails its ownership check. The caller removes `moved` either way.
+ */
+export function restoreDisplacedLock(moved, lockPath) {
+    try {
+        linkSync(moved, lockPath);
+    }
+    catch {
+        // Taken by another writer, or no hard links here: the displaced holder
+        // has lost the lock.
+    }
+}
+/**
+ * The version of the file at `path` as a writer read it: what an atomic
+ * replace changes (the inode) and what an in-place write changes (size and
+ * times). `"absent"` when there is no file.
+ */
+export function fileVersion(path) {
+    try {
+        const s = statSync(path);
+        return `${s.dev}:${s.ino}:${s.size}:${s.mtimeMs}:${s.ctimeMs}`;
+    }
+    catch (err) {
+        if (isMissing(err))
+            return "absent";
+        throw err;
+    }
+}
+/** Remove what crashed writers left in `dir`: old reclaimed locks and temp files. */
+function sweep(dir) {
+    try {
+        for (const name of readdirSync(dir)) {
+            if (!name.startsWith(`${LOCKED_FILE}.lock.stale.`) && !(name.startsWith(`${LOCKED_FILE}.`) && name.endsWith(".tmp"))) {
+                continue;
+            }
+            const path = join(dir, name);
+            if (Date.now() - statSync(path).mtimeMs > LOCK_STALE_MS)
+                unlinkSync(path);
+        }
+    }
+    catch {
+        // Best effort.
+    }
+}
+/**
+ * Take the lock on the credentials file in `dir`, waiting up to
+ * {@link LOCK_WAIT_MS} for another writer and reclaiming a stale lock. Throws
+ * {@link CredentialsLockedError} naming the lock when it stays held.
+ */
+export function acquireCredentialsLock(dir) {
+    const path = join(dir, `${LOCKED_FILE}.lock`);
+    const token = `${process.pid}:${randomBytes(8).toString("hex")}`;
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    for (;;) {
+        try {
+            writeFileSync(path, token, { flag: "wx", mode: 0o600 });
+            break;
+        }
+        catch (err) {
+            if (err?.code !== "EEXIST")
+                throw err;
+        }
+        let held;
+        let seen;
+        try {
+            held = statSync(path);
+            seen = readFileSync(path, "utf-8");
+        }
+        catch (err) {
+            if (isMissing(err))
+                continue;
+            throw err;
+        }
+        if (Date.now() - held.mtimeMs > LOCK_STALE_MS) {
+            reclaimStaleLock(path, token, seen);
+            continue;
+        }
+        if (Date.now() >= deadline)
+            throw new CredentialsLockedError(path);
+        sleep(RETRY_MS);
+    }
+    const ownsLock = () => {
+        try {
+            return readFileSync(path, "utf-8") === token;
+        }
+        catch {
+            return false;
+        }
+    };
+    return {
+        path,
+        token,
+        ownsLock,
+        release() {
+            try {
+                if (ownsLock())
+                    unlinkSync(path);
+            }
+            catch {
+                // Already gone.
+            }
+            sweep(dir);
+        },
+    };
+}
+/**
+ * Replace `path` with `content` while `lock` is held: write a private
+ * temporary file beside it, check the lock is still this holder's and, when
+ * `readVersion` is given, that `path` is still the {@link fileVersion} the
+ * holder read under the lock, then rename the temporary file over `path`. A
+ * holder that lost the lock, or whose read another writer's commit has
+ * overtaken, removes its temporary file and throws
+ * {@link CredentialsLockedError}, leaving `path` as it was.
+ */
+export function replaceFileUnderLock(lock, path, content, readVersion) {
+    const tmp = join(dirname(path), `${basename(path)}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`);
+    writeFileSync(tmp, content, { mode: 0o600 });
+    try {
+        if (!lock.ownsLock())
+            throw new CredentialsLockedError(lock.path);
+        if (readVersion !== undefined && fileVersion(path) !== readVersion) {
+            throw new CredentialsLockedError(lock.path);
+        }
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // Never written, or already renamed.
+        }
+        throw err;
+    }
+    try {
+        chmodSync(path, 0o600);
+    }
+    catch {
+        // Best-effort on Windows / unusual filesystems.
+    }
+}
+//# sourceMappingURL=credentials-lock.js.map

package/dist/src/lib/credentials-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials-lock.js","sourceRoot":"","sources":["../../../src/lib/credentials-lock.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/credentials-store.d.ts

@@ -37,6 +37,26 @@
  * `primitive login` reach the same line, so there is no flag shape for a
  * pre-parse to miss. And it only PERMITS the global file — inside a project
  * all four still use the per-environment slots.
+ *
+ * A child environment (#4511) — a machine-local environment on the server of
+ * the committed environment whose tree it shares — has no slot of its own: it
+ * reads and writes its parent's, so one login and one logout cover the parent
+ * and all of its children.
+ *
+ * A slot records the server that issued it (#4492). A slot is keyed by
+ * environment name while the environment's `apiUrl` is committed, so a branch
+ * switch can point `dev` at another server than the one its stored tokens
+ * came from. A slot recording another server than the invoking environment's
+ * is never used (its tokens are not sent), and credentials from another server
+ * than the slot's environment's are never stored. A slot written before this
+ * records no server; it is read against the environment's `apiUrl`, and its
+ * next write records one.
+ *
+ * In a linked git worktree the project's file is the main worktree's
+ * (#4492, `credentials-home.ts`), so one login serves every worktree of the
+ * repository that holds the project. Every project-mode write is a locked
+ * read-modify-write with an atomic replace (`credentials-lock.ts`), because
+ * several processes — one per worktree — write that one file.
  */
 import type { Credentials } from "../types/index.js";
 export declare const PROJECT_LOCAL_DIR = ".primitive";
@@ -48,6 +68,12 @@ export declare function isProjectMode(): boolean;
  * whether we're in project mode or legacy mode.
  */
 export declare function getCredentialsFilePath(): string;
+/**
+ * The credentials file of the project at `projectRoot`: its own
+ * `.primitive/credentials.json`, or in a linked git worktree the main
+ * worktree's for the same project (#4492).
+ */
+export declare function credentialsFileForProject(projectRoot: string): string;
 /**
  * Declare that THIS command may fall back to `~/.primitive/credentials.json`
  * when no project is in scope. Called at the top of `login`, `logout`, `init`
@@ -60,6 +86,12 @@ export declare function allowGlobalCredentials(): void;
  * boundary in one process, the way `resetEnvResolver()` does for the resolver.
  */
 export declare function resetGlobalCredentialsAllowance(): void;
+/**
+ * Whether two server URLs name the same server: scheme and host compare
+ * case-insensitively and the path with trailing slashes removed. A URL that
+ * does not parse compares as its trailing-slash-trimmed string.
+ */
+export declare function sameServer(a: string, b: string): boolean;
 /** The variable a CI job puts its admin token in (#3890). */
 export declare const PRIMITIVE_TOKEN_VAR = "PRIMITIVE_TOKEN";
 /** The token in `PRIMITIVE_TOKEN`, or null when it is unset or blank. */
@@ -71,26 +103,79 @@ export declare function environmentToken(): string | null;
  *
  * In project mode, we blend the per-env stored creds with the serverUrl
  * and appId from primitive/config.json to produce the Credentials the rest of
- * the CLI expects.
+ * the CLI expects. A child environment reads its parent's slot (#4511), and
+ * any child slot found to be a copy of that login is removed.
  *
  * `PRIMITIVE_TOKEN` (#3890), when set, takes precedence over any stored
  * login and no file is read. It does not loosen the outside-a-project
  * refusal: the environment is resolved first, exactly as for a stored login.
  */
 export declare function loadCredentialsStore(): Credentials | null;
+/**
+ * The current environment's stored login when its slot records another server
+ * than the environment's, blended with the server it RECORDS; null otherwise.
+ * For `logout` alone, which revokes such a login at the server that issued it
+ * and so never sends its tokens anywhere else.
+ */
+export declare function mismatchedLogin(): Credentials | null;
+/**
+ * The environments that share the current environment's login (#4511): the
+ * one whose slot holds it, and its child environments on this machine. Null
+ * outside a project, where there is one global login.
+ */
+export declare function loginEnvironments(): {
+    parent: string;
+    children: string[];
+} | null;
+/**
+ * What a login, logout or not-logged-in refusal adds about a linked git
+ * worktree (#4492). Each is null when it has nothing to say: outside a
+ * project, and where the project's login is its own.
+ */
+export declare const worktreeLoginNotes: {
+    /** After a login stored in another worktree's file: where it went. */
+    storedElsewhere(): string | null;
+    /** After a logout of `slot`'s login, when more than one worktree uses it. */
+    sharedLogout(slot: string): string | null;
+    /** A linked worktree's own credentials file, which is never read. */
+    ignoredFile(): string | null;
+    /** After "not logged in", when git is why a linked worktree has no login. */
+    notLoggedIn(): string | null;
+};
+/**
+ * The logins still held in the slots of the current login's child
+ * environments: sessions signed in to a child before children used their
+ * parent's login, and copies of the parent's that kept a step-up or a refresh
+ * token of their own. No command reads them; `logout` revokes them before
+ * {@link clearLeftoverChildLogins} removes them. Empty outside a project.
+ */
+export declare function leftoverChildLogins(): Credentials[];
 /**
  * Saves credentials. In project mode, writes to the per-env slot in the
  * project credentials file. In legacy mode, writes the global file.
  *
- * The serverUrl on the incoming Credentials is used as-is for legacy
- * mode, and ignored in project mode (the env's apiUrl is canonical).
+ * In project mode the slot records the incoming `serverUrl`, which must be
+ * the same server as the slot's environment's `apiUrl`: credentials from
+ * another server are refused with `server-mismatch` and nothing is written
+ * (#4492). In a child environment the parent's slot is written (#4511).
  */
 export declare function saveCredentialsStore(credentials: Credentials): void;
 /**
  * Clears credentials for the current environment (project mode) or
- * deletes the legacy file (legacy mode).
+ * deletes the legacy file (legacy mode). In project mode that is the slot
+ * holding the environment's login, whichever environment of the tree is
+ * current, and the child slots holding only that login's session (#4511),
+ * which its caller has just revoked. A child slot holding another session or
+ * a step-up of its own stays for `logout` to revoke
+ * ({@link clearLeftoverChildLogins}).
  */
 export declare function clearCredentialsStore(): void;
+/**
+ * Removes every slot the current login's child environments kept, once
+ * `logout` has revoked the logins {@link leftoverChildLogins} returned. No-op
+ * outside a project.
+ */
+export declare function clearLeftoverChildLogins(): void;
 /**
  * Removes the credentials slot for the named environment in a specific
  * project's credentials file. Used by `env remove` so stale tokens from a
@@ -109,7 +194,9 @@ export declare function removeCredentialsSlotInProject(projectRoot: string, envN
  * Writes the credentials slot for the named environment in a specific
  * project's credentials file. Used by `primitive init` to carry the session
  * it just authenticated into the freshly scaffolded project, so the first
- * in-project CLI command works without a second `primitive login`.
+ * in-project CLI command works without a second `primitive login`. The slot
+ * records the credentials' server, which must be the named environment's
+ * `apiUrl` in the project's config (#4492).
  */
 export declare function seedCredentialsForEnvInProject(projectRoot: string, envName: string, credentials: Credentials): void;
 /**