@vincentt-xr/cli 0.19.0 → 0.20.0

package/MIGRATION.md

@@ -3,6 +3,16 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.20.0
+
+required: false
+No action required. Behaviour that changed:
+- `vincentt login` signs in this machine on its own and leaves your other machines signed in. It sends a machine label, `"<OS> <arch>, <d Mon>"` by default (never the hostname), or the name given with `--label "<name>"`; a `--label` the platform would refuse (empty, over 64 characters, control or invisible characters, or a platform-reserved name) exits 1 before any browser opens.
+- The `vincentt login` success line names the machine: `✓ Signed in as <email> on this machine (<label>)`. Against an api older than machine sign-ins the line is unchanged.
+- When a login leaves more than 10 signed-in machines, the least recently used are signed out and each is named on its own line after the workspace line: `Signed out "<label>", the least recently used of your 10 signed-in machines (last used <d Mon>).`
+- `vincentt logout` also ends this machine's sign-in on the platform (best-effort, 5 seconds), then always removes the local token; when the api cannot be reached it says the machine stays listed in the console. `vincentt login --force` keeps the old token until the new one is saved, then ends the old sign-in.
+- A refused token now reads ``✗ This machine is no longer signed in to Vincentt. Run `vincentt login` to sign in again.`` (it read "Your Vincentt access token is no longer valid."). A script matching the old wording exactly needs updating. The exit code is unchanged (4).
+
 ## 0.19.0
 
 required: false

package/README.md

@@ -53,8 +53,9 @@ registers the project, which is what needs an account.
 
 ```
 Auth
-  login              Sign in; save an access token to ~/.vincentt/config.json
-  logout             Remove the saved access token
+  login              Sign in this machine; save an access token to ~/.vincentt/config.json
+                       [--label <name>] names this machine (default: OS, arch, date)
+  logout             Sign this machine out and remove the saved access token
   whoami             Show the signed-in account
 
 Project

package/dist/cli/index.js

@@ -15,8 +15,9 @@ import { createRequire } from "node:module";
 import os from "node:os";
 import path from "node:path";
 import { runPkceLogin } from "../login/pkceLogin.js";
-import { httpAuthBackend } from "../login/authBackend.js";
-import { loginCommand } from "../login/loginCommand.js";
+import { httpAuthBackend, revokeCurrent } from "../login/authBackend.js";
+import { resolveLoginLabel } from "../login/machineLabel.js";
+import { loginCommand, logoutLines as logoutCommand } from "../login/loginCommand.js";
 import { ensureLoggedIn } from "../login/ensure.js";
 import { clearMachineToken, loadMachineConfig, locateProjectBinding, machineApiUrl, resolveConfig, writeDxEnablement, MACHINE_CONFIG_PATH, } from "../shared/config.js";
 import { fileLocationStore } from "../shared/locationStore.js";
@@ -120,16 +121,33 @@ function machineCredentials(machine) {
     return pat ? { apiUrl: machineApiUrl(machine), pat } : undefined;
 }
 /** The PKCE loopback + code-exchange login (f1). The raw PAT never rides a redirect query. */
-async function runLoginFlow() {
+async function runLoginFlow(label) {
     const { consoleUrl, apiUrl } = await resolveAuthUrls();
     return runPkceLogin({
         consoleUrl,
         apiUrl,
+        label,
         onProgress: (line) => console.log(line),
     });
 }
-/** `vincentt login` [--force] — the L1/L2/L4 transcripts. */
+/** The label this login sends, or undefined when --label was refused (the refusal is printed). */
+function loginLabel() {
+    const eq = valueOfEqualsFlag(argv, "--label");
+    const resolved = resolveLoginLabel(has("--label") || eq !== undefined, flag("--label") ?? eq);
+    if (!resolved.ok) {
+        for (const line of resolved.lines)
+            console.log(line);
+        return undefined;
+    }
+    return resolved.label;
+}
+/** `vincentt login` [--force] [--label <name>] — the L1/L2/L4/L5 transcripts. */
 async function login() {
+    const label = loginLabel();
+    if (label === undefined) {
+        process.exitCode = EXIT.FAILED;
+        return;
+    }
     const { apiUrl } = await resolveAuthUrls();
     const code = await loginCommand({
         print: (line) => console.log(line),
@@ -140,10 +158,12 @@ async function login() {
                 throw new NotSignedInError();
             return httpAuthBackend(apiUrl).me(pat);
         },
-        runLogin: runLoginFlow,
+        runLogin: () => runLoginFlow(label),
         clearToken: async () => {
             await clearMachineToken();
         },
+        storedToken: async () => (await loadMachineConfig()).pat,
+        revokeToken: (pat) => revokeCurrent(apiUrl, pat),
         home: os.homedir(),
         configPath: MACHINE_CONFIG_PATH,
     }, { force: has("--force") });
@@ -169,8 +189,13 @@ async function requireLogin() {
     return ok;
 }
 async function logout() {
-    const { path: p, hadToken } = await clearMachineToken();
-    console.log(hadToken ? `✓ Signed out. Token removed from ${p}` : "Already signed out.");
+    const machine = await loadMachineConfig();
+    const outcome = machine.pat
+        ? await revokeCurrent(machineApiUrl(machine), machine.pat)
+        : "done";
+    const lines = await logoutCommand({ clear: clearMachineToken, outcome });
+    for (const line of lines)
+        console.log(line);
 }
 /**
  * `whoami` reads the MACHINE config's API host, never the folder's binding — it

package/dist/cli/usage-text.js

@@ -11,9 +11,10 @@ export const USAGE_TEXT = `Vincentt CLI: the local-first AR dev loop\n\n` +
     `     Wait for the developer to describe what to build.\n` +
     `  Full guide: npm view @vincentt-xr/cli readme\n\n` +
     `Auth\n` +
-    `  login              Sign in; save an access token to ~/.vincentt/config.json\n` +
+    `  login              Sign in this machine; save an access token to ~/.vincentt/config.json\n` +
+    `                       [--label <name>] names this machine (default: OS, arch, date)\n` +
     `                       [--api <url>] [--console <url>] to target a non-prod env\n` +
-    `  logout             Remove the saved access token\n` +
+    `  logout             Sign this machine out and remove the saved access token\n` +
     `  whoami             Show the signed-in account\n\n` +
     `Project\n` +
     `  init [dir]         Scaffold a Vincentt XR app; no account needed, ever\n` +

package/dist/login/authBackend.d.ts

@@ -10,18 +10,43 @@ export interface Identity {
     /** All orgs the signed-in user belongs to (switcher source). */
     memberships: Membership[];
 }
+/** A machine sign-in the api signed out to stay within the 10-machine cap. */
+export interface EvictedMachine {
+    label: string;
+    /** ISO 8601, or null for a machine that was never used. */
+    lastUsedAt: string | null;
+}
+export interface ExchangeResult {
+    /** The raw PAT ("vct_…"), delivered once. */
+    token: string;
+    /** The label the api stored, echoed. Absent from an api older than machine sign-ins. */
+    label?: string;
+    /** Machines signed out by this login (the cap). Absent when none were. */
+    evicted?: EvictedMachine[];
+}
+/** How a self sign-out ended: the api ended it (or it had nothing to end), or it could not be reached. */
+export type RevokeOutcome = "done" | "unreachable";
 /**
  * The auth-flow backend seam. `exchange` redeems the PKCE code for a raw PAT; `me` confirms
  * identity + orgs with that PAT. Both are injected so a stub backend drives the CLI tests.
  */
 export interface AuthBackend {
-    /** POST /access-tokens/exchange {code, code_verifier} → the raw PAT ("vct_…"). */
-    exchange(code: string, codeVerifier: string): Promise<string>;
+    /** POST /access-tokens/exchange {code, code_verifier, label?} → the raw PAT and what the api reports. */
+    exchange(code: string, codeVerifier: string, label?: string): Promise<ExchangeResult>;
     /** GET /me with Bearer <pat> → identity + orgs. */
     me(pat: string): Promise<Identity>;
 }
+/** DELETE /access-tokens/current gives up after this long: sign-out never hangs on the api. */
+export declare const REVOKE_CURRENT_TIMEOUT_MS = 5000;
 /** The real HTTP-backed AuthBackend, pointed at a Vincentt API base URL. */
 export declare function httpAuthBackend(apiBase: string): AuthBackend;
+/**
+ * End THIS machine's sign-in on the platform (DELETE /access-tokens/current),
+ * best-effort. 204 is done; 400, 401, 403, 404 and 405 count as done too: an
+ * older api has no such route, or the sign-in had already ended. A network
+ * failure, a timeout or a 5xx is "unreachable".
+ */
+export declare function revokeCurrent(apiBase: string, pat: string, fetchImpl?: typeof fetch, timeoutMs?: number): Promise<RevokeOutcome>;
 /**
  * Map the /me response shape onto our Identity. The backend returns memberships with an org
  * name + kind; we keep the projection resilient to the exact field names the Go handler emits

package/dist/login/authBackend.js

@@ -3,12 +3,16 @@
 // backend (QA-F1-C2/C4/C5) without real HTTP.
 //
 // Note the CLI does NOT call POST /access-tokens — the browser/console does that (it holds
-// the JWT session; a PAT may not mint a PAT). The CLI only redeems the returned auth_code:
-//   POST /access-tokens/exchange {code, code_verifier} → {token}   (raw PAT, once, in body)
-//   GET  /me            Bearer <PAT>                    → identity + orgs (confirm)
+// the session; a PAT may not mint a PAT). The CLI only redeems the returned auth_code:
+//   POST /access-tokens/exchange {code, code_verifier, label}
+//                                    → {token, label, evicted?}  (raw PAT, once, in body)
+//   GET  /me            Bearer <PAT> → identity + orgs (confirm)
+// and, to end this machine's own sign-in, DELETE /access-tokens/current Bearer <PAT>.
 import { authFailureMessage } from "../shared/authError.js";
 import { clientHeaders } from "../shared/clientHeader.js";
-import { apiFetch } from "../shared/http.js";
+import { apiFetch, withDeadline } from "../shared/http.js";
+/** DELETE /access-tokens/current gives up after this long: sign-out never hangs on the api. */
+export const REVOKE_CURRENT_TIMEOUT_MS = 5_000;
 class AuthError extends Error {
     status;
     constructor(message, status) {
@@ -25,23 +29,64 @@ async function safeText(res) {
         return "";
     }
 }
+/** The error code a JSON error body carries, if any. */
+function errorCode(text) {
+    try {
+        const body = JSON.parse(text);
+        return typeof body.code === "string" ? body.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function readEvicted(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    return raw.map((e) => {
+        const r = (e ?? {});
+        return {
+            label: typeof r.label === "string" ? r.label : "",
+            lastUsedAt: typeof r.lastUsedAt === "string" ? r.lastUsedAt : null,
+        };
+    });
+}
 /** The real HTTP-backed AuthBackend, pointed at a Vincentt API base URL. */
 export function httpAuthBackend(apiBase) {
     const base = apiBase.replace(/\/$/, "");
+    const post = (body) => apiFetch(`${base}/access-tokens/exchange`, {
+        method: "POST",
+        headers: { ...clientHeaders(), "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
     return {
-        async exchange(code, codeVerifier) {
-            const res = await apiFetch(`${base}/access-tokens/exchange`, {
-                method: "POST",
-                headers: { ...clientHeaders(), "content-type": "application/json" },
-                body: JSON.stringify({ code, code_verifier: codeVerifier }),
-            });
+        async exchange(code, codeVerifier, label) {
+            const body = { code, code_verifier: codeVerifier };
+            if (label !== undefined)
+                body.label = label;
+            let res = await post(body);
+            if (!res.ok && res.status === 400 && label !== undefined) {
+                const text = await safeText(res);
+                // An api older than machine sign-ins decodes strictly and refuses the
+                // unknown `label` field with bad_request BEFORE it consumes the code, so
+                // the same code and verifier are still good: retry once without it. Any
+                // other refusal (label_invalid included) is final.
+                if (errorCode(text) !== "bad_request") {
+                    throw new AuthError(`Token exchange failed (${res.status}): ${text}`, res.status);
+                }
+                res = await post({ code, code_verifier: codeVerifier });
+            }
             if (!res.ok) {
                 throw new AuthError(`Token exchange failed (${res.status}): ${await safeText(res)}`, res.status);
             }
-            const body = (await res.json());
-            if (!body.token)
+            const out = (await res.json());
+            if (typeof out.token !== "string" || !out.token) {
                 throw new AuthError("Token exchange returned no token.");
-            return body.token;
+            }
+            return {
+                token: out.token,
+                label: typeof out.label === "string" ? out.label : undefined,
+                evicted: readEvicted(out.evicted),
+            };
         },
         async me(pat) {
             const res = await apiFetch(`${base}/me`, {
@@ -54,6 +99,27 @@ export function httpAuthBackend(apiBase) {
         },
     };
 }
+/**
+ * End THIS machine's sign-in on the platform (DELETE /access-tokens/current),
+ * best-effort. 204 is done; 400, 401, 403, 404 and 405 count as done too: an
+ * older api has no such route, or the sign-in had already ended. A network
+ * failure, a timeout or a 5xx is "unreachable".
+ */
+export async function revokeCurrent(apiBase, pat, fetchImpl = (input, init) => globalThis.fetch(input, init), timeoutMs = REVOKE_CURRENT_TIMEOUT_MS) {
+    const base = apiBase.replace(/\/$/, "");
+    try {
+        const res = await withDeadline(fetchImpl, timeoutMs)(`${base}/access-tokens/current`, {
+            method: "DELETE",
+            headers: { ...clientHeaders(), authorization: `Bearer ${pat}` },
+        });
+        if (res.ok || [400, 401, 403, 404, 405].includes(res.status))
+            return "done";
+        return "unreachable";
+    }
+    catch {
+        return "unreachable";
+    }
+}
 /**
  * Map the /me response shape onto our Identity. The backend returns memberships with an org
  * name + kind; we keep the projection resilient to the exact field names the Go handler emits

package/dist/login/loginCommand.d.ts

@@ -1,4 +1,4 @@
-import type { Identity, Membership } from "./authBackend.js";
+import type { EvictedMachine, Identity, Membership, RevokeOutcome } from "./authBackend.js";
 /** Collapse the home dir to `~` for display. `~/.vincentt/config.json` in every transcript. */
 export declare function displayConfigPath(absPath: string, home: string): string;
 /** The active org is the personal one (login lands on personal; the CLI never prompts). */
@@ -9,6 +9,12 @@ export declare function activeOrg(memberships: Membership[]): Membership | undef
  * org gets just the active-org line (no trailing clause).
  */
 export declare function orgSummaryLine(identity: Identity): string;
+/**
+ * The line naming a machine the 10-machine cap signed out (Flow L5). No glyph:
+ * it is not an advisory about this machine; no command: the other machine signs
+ * in again if someone wants it.
+ */
+export declare function evictionLine(e: EvictedMachine): string;
 export interface LoginCommandDeps {
     /** Print a line to the user (stdout for the transcript). */
     print: (line: string) => void;
@@ -16,13 +22,22 @@ export interface LoginCommandDeps {
     currentToken: () => Promise<string | undefined>;
     /** Confirm who the present token belongs to (GET /me). Throws the client's error unchanged. */
     whoAmI: () => Promise<Identity>;
-    /** Run the loopback + PKCE flow; resolves identity + the saved config path. */
+    /** Run the loopback + PKCE flow; resolves identity, the saved config path and what the api reported. */
     runLogin: () => Promise<{
         identity: Identity;
         configPath: string;
+        label?: string;
+        evicted?: EvictedMachine[];
     }>;
-    /** Forget the existing token before a --force re-login. */
+    /** Forget a stored token the api no longer accepts. */
     clearToken: () => Promise<void>;
+    /** The token saved in this machine's config (never the env override), read before a --force login. */
+    storedToken?: () => Promise<string | undefined>;
+    /**
+     * End a replaced token's sign-in on the platform, best-effort and silent. Called with
+     * the OLD token only after the new one is saved.
+     */
+    revokeToken?: (pat: string) => Promise<unknown>;
     /** For displaying the config path as ~/…. */
     home: string;
     /** Absolute config path (for the L2 already-signed-in line). */
@@ -37,3 +52,20 @@ export interface LoginCommandOptions {
  * exact retry command and return 1. No stack trace, no token printed.
  */
 export declare function loginCommand(deps: LoginCommandDeps, opts?: LoginCommandOptions): Promise<number>;
+export interface LogoutDeps {
+    /** Delete the local token; reports whether there was one. */
+    clear: () => Promise<{
+        path: string;
+        hadToken: boolean;
+    }>;
+    /** How the platform sign-out (DELETE /access-tokens/current) ended, asked BEFORE clearing. */
+    outcome: RevokeOutcome;
+    /** For displaying the config path as ~/…. */
+    home?: string;
+}
+/**
+ * `vincentt logout` (Flow L7): the platform sign-out was already attempted; the
+ * local token is ALWAYS deleted, and only an api that could not be reached adds
+ * a fact line, because that machine then stays listed in the console.
+ */
+export declare function logoutLines(deps: LogoutDeps): Promise<string[]>;

package/dist/login/loginCommand.js

@@ -5,8 +5,10 @@
 //
 // The IO boundary (print, current identity, run the PKCE flow, clock) is injected so every
 // L1–L4 branch is unit-testable with no real browser, socket, or config file.
+import os from "node:os";
 import { isAuthRefused } from "../shared/authError.js";
 import { EXIT } from "../lib/exitCodes.js";
+import { dayMonth, sanitizeServerLabel } from "./machineLabel.js";
 /** Collapse the home dir to `~` for display. `~/.vincentt/config.json` in every transcript. */
 export function displayConfigPath(absPath, home) {
     if (home && absPath.startsWith(home))
@@ -32,6 +34,18 @@ export function orgSummaryLine(identity) {
     const base = `  Active workspace: ${activeName}`;
     return others.length ? `${base}   ·   also a member of: ${others.join(", ")}` : base;
 }
+/**
+ * The line naming a machine the 10-machine cap signed out (Flow L5). No glyph:
+ * it is not an advisory about this machine; no command: the other machine signs
+ * in again if someone wants it.
+ */
+export function evictionLine(e) {
+    const label = sanitizeServerLabel(e.label);
+    const when = e.lastUsedAt
+        ? `last used ${dayMonth(new Date(e.lastUsedAt))}`
+        : "never used";
+    return `  Signed out "${label}", the least recently used of your 10 signed-in machines (${when}).`;
+}
 /**
  * Drive `vincentt login`. Returns an exit code (0 ok, 1 failed). Never throws for expected
  * failure states (timeout, cancel, state-mismatch) — they print a ✗ line ending with the
@@ -41,7 +55,19 @@ export async function loginCommand(deps, opts = {}) {
     const displayPath = displayConfigPath(deps.configPath, deps.home);
     if (opts.force) {
         deps.print("→ Replacing the existing token on this machine…");
-        await deps.clearToken();
+        // The old token stays on disk until the new one is saved: a failed login must
+        // never leave the machine with neither.
+        const old = deps.storedToken ? await deps.storedToken() : undefined;
+        const code = await runLoginFlow(deps);
+        if (code === EXIT.OK && old && deps.revokeToken) {
+            try {
+                await deps.revokeToken(old);
+            }
+            catch {
+                /* best-effort: the old sign-in ages out or is signed out in the console */
+            }
+        }
+        return code;
     }
     else {
         // L2: already signed in, but only once the api confirms the token.
@@ -78,9 +104,15 @@ function isTokenRejected(err) {
 async function runLoginFlow(deps) {
     // L1 / L4 — run the loopback + PKCE flow.
     try {
-        const { identity, configPath } = await deps.runLogin();
-        deps.print(`✓ Signed in as ${identity.email}`);
+        const { identity, configPath, label, evicted } = await deps.runLogin();
+        // The label is the api's ECHO, never what was sent: an older api never saw it.
+        const named = label ? sanitizeServerLabel(label) : "";
+        deps.print(named
+            ? `✓ Signed in as ${identity.email} on this machine (${named})`
+            : `✓ Signed in as ${identity.email}`);
         deps.print(orgSummaryLine(identity));
+        for (const e of evicted ?? [])
+            deps.print(evictionLine(e));
         deps.print(`  Token saved to ${displayConfigPath(configPath, deps.home)}`);
         deps.print("");
         deps.print("Run `vincentt --help` to see what you can do.");
@@ -94,3 +126,20 @@ async function runLoginFlow(deps) {
         return 1;
     }
 }
+/**
+ * `vincentt logout` (Flow L7): the platform sign-out was already attempted; the
+ * local token is ALWAYS deleted, and only an api that could not be reached adds
+ * a fact line, because that machine then stays listed in the console.
+ */
+export async function logoutLines(deps) {
+    const { path: p, hadToken } = await deps.clear();
+    if (!hadToken)
+        return ["Already signed out."];
+    const lines = [
+        `✓ Signed out. Token removed from ${displayConfigPath(p, deps.home ?? os.homedir())}`,
+    ];
+    if (deps.outcome === "unreachable") {
+        lines.push("  The api could not be reached. This machine stays listed under Signed-in machines until it is", "  signed out there or goes 90 days unused.");
+    }
+    return lines;
+}

package/dist/login/machineLabel.d.ts

@@ -0,0 +1,46 @@
+export declare const MACHINE_LABEL_MAX_CODE_POINTS = 64;
+export declare const MACHINE_LABEL_MAX_MARK_RUN = 4;
+export declare const LEGACY_MACHINE_LABEL = "Signed in before machine names";
+export declare const DEFAULT_MACHINE_LABEL_PREFIX = "Unnamed machine,";
+export declare const MACHINE_LABEL_REFUSED_LINES: readonly string[];
+/** "d Mon" in the given date's own calendar fields (local time unless the caller says otherwise). */
+export declare function dayMonth(d: Date, utc?: boolean): string;
+/** The default label, "<OS> <arch>, <d Mon>", from injected platform, arch and clock. */
+export declare function defaultMachineLabel(platform?: string, arch?: string, now?: Date): string;
+export type LabelCheck = {
+    ok: true;
+    label: string;
+} | {
+    ok: false;
+};
+/**
+ * The api's label rules, for a label the person typed: NFC, trim U+0020 only,
+ * then 1 to 64 code points, each a letter, mark, number, punctuation, symbol or
+ * plain space, no run of more than 4 marks, and not a platform-only string. An
+ * empty label is refused here (the api would store its default, but `--label ""`
+ * is a mistake, not a request for the default).
+ */
+export declare function validateMachineLabel(raw: string): LabelCheck;
+/**
+ * Drop every code point outside the label allowlist before a server-sent label
+ * is printed. The api already refuses such labels; this keeps a later
+ * validation bug from writing escape sequences or bidi controls to a terminal.
+ */
+export declare function sanitizeServerLabel(label: unknown): string;
+export type LoginLabel = {
+    ok: true;
+    label: string;
+} | {
+    ok: false;
+    lines: readonly string[];
+};
+/**
+ * The label a `vincentt login` sends. Without --label it is the default; with it,
+ * the typed value must pass the api's rules, or the refusal lines are returned
+ * and the login must stop before any browser or network.
+ */
+export declare function resolveLoginLabel(given: boolean, raw: string | undefined, defaults?: {
+    platform?: string;
+    arch?: string;
+    now?: Date;
+}): LoginLabel;

package/dist/login/machineLabel.js

@@ -0,0 +1,119 @@
+// The machine label `vincentt login` sends with the exchange: a name for this
+// machine's sign-in that the console lists and the eviction line prints.
+//
+// It is built from the OS, the architecture and today's date, NEVER the hostname:
+// a hostname often carries a person's name or an employer's asset tag, and the
+// label is shown back to the person. `--label` overrides it.
+//
+// validateMachineLabel applies the api's exact rules, counting CODE POINTS after
+// NFC (not UTF-16 units), so `--label` is refused here, before any browser or
+// network, for exactly what the api would refuse. The shared corpus
+// (__fixtures__/machine_label_corpus.json, copied from the api) pins agreement.
+export const MACHINE_LABEL_MAX_CODE_POINTS = 64;
+export const MACHINE_LABEL_MAX_MARK_RUN = 4;
+export const LEGACY_MACHINE_LABEL = "Signed in before machine names";
+export const DEFAULT_MACHINE_LABEL_PREFIX = "Unnamed machine,";
+const MONTHS = [
+    "Jan",
+    "Feb",
+    "Mar",
+    "Apr",
+    "May",
+    "Jun",
+    "Jul",
+    "Aug",
+    "Sep",
+    "Oct",
+    "Nov",
+    "Dec",
+];
+export const MACHINE_LABEL_REFUSED_LINES = [
+    "✗ A machine label must be 1 to 64 letters, numbers, spaces, punctuation or symbols.",
+    '  Run `vincentt login --label "<name>"` with a shorter name, or leave out --label.',
+];
+/** "d Mon" in the given date's own calendar fields (local time unless the caller says otherwise). */
+export function dayMonth(d, utc = false) {
+    const day = utc ? d.getUTCDate() : d.getDate();
+    const month = utc ? d.getUTCMonth() : d.getMonth();
+    return `${day} ${MONTHS[month]}`;
+}
+function osName(platform) {
+    if (platform === "darwin")
+        return "macOS";
+    if (platform === "win32")
+        return "Windows";
+    if (platform === "linux")
+        return "Linux";
+    return platform;
+}
+/** The default label, "<OS> <arch>, <d Mon>", from injected platform, arch and clock. */
+export function defaultMachineLabel(platform = process.platform, arch = process.arch, now = new Date()) {
+    return `${osName(platform)} ${arch}, ${dayMonth(now)}`;
+}
+const ALLOWED = /^[\p{L}\p{M}\p{N}\p{P}\p{S} ]$/u;
+const MARK = /^\p{M}$/u;
+function trimSpaces(s) {
+    return s.replace(/^ +| +$/g, "");
+}
+function fold(s) {
+    return s.normalize("NFKC").toLowerCase();
+}
+const FOLDED_LEGACY = fold(LEGACY_MACHINE_LABEL);
+const FOLDED_DEFAULT_PREFIX = fold(DEFAULT_MACHINE_LABEL_PREFIX);
+/**
+ * The api's label rules, for a label the person typed: NFC, trim U+0020 only,
+ * then 1 to 64 code points, each a letter, mark, number, punctuation, symbol or
+ * plain space, no run of more than 4 marks, and not a platform-only string. An
+ * empty label is refused here (the api would store its default, but `--label ""`
+ * is a mistake, not a request for the default).
+ */
+export function validateMachineLabel(raw) {
+    const label = trimSpaces(raw.normalize("NFC"));
+    const points = [...label];
+    if (points.length < 1 || points.length > MACHINE_LABEL_MAX_CODE_POINTS)
+        return { ok: false };
+    let markRun = 0;
+    for (const cp of points) {
+        if (!ALLOWED.test(cp))
+            return { ok: false };
+        if (MARK.test(cp)) {
+            markRun++;
+            if (markRun > MACHINE_LABEL_MAX_MARK_RUN)
+                return { ok: false };
+        }
+        else {
+            markRun = 0;
+        }
+    }
+    // Case folding approximated by NFKC + toLowerCase; the shared corpus pins
+    // agreement with the api's NFKC + Unicode case fold.
+    const folded = trimSpaces(fold(label));
+    if (folded === FOLDED_LEGACY || folded.startsWith(FOLDED_DEFAULT_PREFIX))
+        return { ok: false };
+    return { ok: true, label };
+}
+/**
+ * Drop every code point outside the label allowlist before a server-sent label
+ * is printed. The api already refuses such labels; this keeps a later
+ * validation bug from writing escape sequences or bidi controls to a terminal.
+ */
+export function sanitizeServerLabel(label) {
+    if (typeof label !== "string")
+        return "";
+    return [...label].filter((cp) => ALLOWED.test(cp)).join("");
+}
+/**
+ * The label a `vincentt login` sends. Without --label it is the default; with it,
+ * the typed value must pass the api's rules, or the refusal lines are returned
+ * and the login must stop before any browser or network.
+ */
+export function resolveLoginLabel(given, raw, defaults = {}) {
+    if (!given) {
+        return {
+            ok: true,
+            label: defaultMachineLabel(defaults.platform, defaults.arch, defaults.now),
+        };
+    }
+    const check = validateMachineLabel(raw ?? "");
+    return check.ok ? check : { ok: false, lines: MACHINE_LABEL_REFUSED_LINES };
+}

package/dist/login/pkceLogin.d.ts

@@ -1,4 +1,4 @@
-import { type AuthBackend, type Identity } from "./authBackend.js";
+import { type AuthBackend, type EvictedMachine, type Identity } from "./authBackend.js";
 export interface PkceLoginOptions {
     /** Console origin that serves /cli-auth (browser target). */
     consoleUrl: string;
@@ -6,6 +6,8 @@ export interface PkceLoginOptions {
     apiUrl: string;
     /** Abort if the browser round-trip doesn't complete in time. Default 5 min. */
     timeoutMs?: number;
+    /** The machine label sent with the exchange (already validated). */
+    label?: string;
     /** Backend calls (exchange + me). Default: real HTTP against apiUrl. */
     backend?: AuthBackend;
     /** Pick a free loopback port. Default: the OS ephemeral picker. */
@@ -20,6 +22,10 @@ export interface PkceLoginOptions {
 export interface PkceLoginResult {
     identity: Identity;
     configPath: string;
+    /** The label the api stored, echoed back; absent from an older api. */
+    label?: string;
+    /** Machines this login signed out at the 10-machine cap. */
+    evicted?: EvictedMachine[];
 }
 /** Thrown when the wait elapses with no approval; drives the L4 timeout transcript. */
 export declare class LoginTimeoutError extends Error {

package/dist/login/pkceLogin.js

@@ -5,7 +5,8 @@
 //   2. Mint state + PKCE code_verifier/code_challenge (S256).
 //   3. Open the browser to /cli-auth?redirect_uri=<loopback>&state=…&code_challenge=….
 //   4. On the loopback callback: verify state constant-time (reject mismatch → no exchange).
-//   5. POST /access-tokens/exchange {code, code_verifier} → raw PAT (in body, once).
+//   5. POST /access-tokens/exchange {code, code_verifier, label} → raw PAT (in body, once),
+//      the stored label, and any machines the 10-machine cap signed out.
 //   6. Write ~/.vincentt/config.json, then GET /me Bearer <PAT> to confirm identity + orgs.
 //
 // Every external boundary is injected (getFreePort, listen, openBrowser, backend, clock/
@@ -14,7 +15,7 @@
 import { getFreePort } from "../preview/net.js";
 import { writeMachineConfig } from "../shared/config.js";
 import { makePkceMaterial, buildCliAuthUrl, parseCallback, } from "./pkce.js";
-import { httpAuthBackend } from "./authBackend.js";
+import { httpAuthBackend, } from "./authBackend.js";
 import { waitForLoopbackCallback } from "./loopback.js";
 /** Thrown when the wait elapses with no approval; drives the L4 timeout transcript. */
 export class LoginTimeoutError extends Error {
@@ -166,8 +167,9 @@ export async function runPkceLogin(opts) {
         },
     });
     // (5) redeem the code for the raw PAT; (6) persist then confirm identity.
-    const pat = await backend.exchange(code, material.codeVerifier);
+    const exchanged = await backend.exchange(code, material.codeVerifier, opts.label);
+    const pat = exchanged.token;
     const configPath = await saveToken(opts.apiUrl.replace(/\/$/, ""), pat);
     const identity = await backend.me(pat);
-    return { identity, configPath };
+    return { identity, configPath, label: exchanged.label, evicted: exchanged.evicted };
 }

package/dist/preview/copy.js

@@ -448,7 +448,7 @@ export function endedUnreachable(orgName) {
 export function endedAuthExpired() {
     return [
         "",
-        "✗ Preview ended. Your Vincentt access token is no longer valid.",
+        "✗ Preview ended. This machine is no longer signed in to Vincentt.",
         "",
         "  Sign in again:  vincentt login",
         "  Then start a new preview:  vincentt preview",

package/dist/shared/authError.d.ts

@@ -1,4 +1,4 @@
-export declare const AUTH_EXPIRED_MESSAGE = "Your Vincentt access token is no longer valid. Run `vincentt login` to sign in again.";
+export declare const AUTH_EXPIRED_MESSAGE = "This machine is no longer signed in to Vincentt. Run `vincentt login` to sign in again.";
 export declare function authFailureMessage(label: string, status: number, detail: string): string;
 /**
  * The api refused the token. Distinct from every other refusal because the

package/dist/shared/authError.js

@@ -3,7 +3,9 @@
 // "(401): <body>" is unactionable noise for every user at once. Name the cause and give
 // the one instruction that fixes it. Any other status keeps its existing "(<n>): <body>"
 // shape: a 500/timeout is a different problem and must not be mislabeled a stale token.
-export const AUTH_EXPIRED_MESSAGE = "Your Vincentt access token is no longer valid. Run `vincentt login` to sign in again.";
+// A machine's sign-in ends when it is signed out in the console, signed out at the
+// 10-machine cap, or left unused for 90 days; all three reach the CLI as this 401.
+export const AUTH_EXPIRED_MESSAGE = "This machine is no longer signed in to Vincentt. Run `vincentt login` to sign in again.";
 export function authFailureMessage(label, status, detail) {
     if (status === 401)
         return AUTH_EXPIRED_MESSAGE;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",