anyray-connect 0.11.89 → 0.11.91

package/dist/cli.js

@@ -10,7 +10,8 @@
  * personal gateway authentication, and content-free attribution.
  */
 import { isPersonalClientKey, isInsecureRemoteOrigin, normalizeOrigin, resolveOrigin, resolveTarget, withLocalProxy, } from "./target.js";
-import { pickLoopbackPort, installProxyService, uninstallProxyService, probeHealth, DEFAULT_LOOPBACK_PORT, } from "./util/proxyService.js";
+import { pickLoopbackPort, installProxyService, uninstallProxyService, probeHealth, proxyUnitFileExists, DEFAULT_LOOPBACK_PORT, } from "./util/proxyService.js";
+import { stat } from "node:fs/promises";
 import { isDraining } from "./util/drainMarker.js";
 import { installRefreshScheduler, uninstallRefreshScheduler, } from "./util/refreshScheduler.js";
 import { detectRemoteDevBackend, isContainerBackend, } from "./util/remoteContext.js";
@@ -32,8 +33,10 @@ import { checkGateway } from "./util/preflight.js";
 import { maskKey } from "./util/redeem.js";
 import { parseEnrollLink, isEnrollArg, resolveEnrollLink, } from "./util/enrollLink.js";
 import { canReuseEnrolledCert, enrollAndVerify, enrollTokenHash, GatewayVerifyError, STABLE_KEY_HEARTBEAT_CAPABILITY, verifyWithGateway, } from "./util/devVerify.js";
-import { detectDisplayName } from "./util/identity.js";
+import { detectEnrollmentIdentity, } from "./util/identity.js";
 import { parseSsoLink, ssoEnroll } from "./util/ssoEnroll.js";
+import { canMultiSelect, multiSelect } from "./util/multiSelect.js";
+import { withSpinner } from "./util/spinner.js";
 import { recordMintSuccess, refreshIfDue, repathManagedTools, reserveMint, } from "./util/devRefresh.js";
 import { runSelfUpdate } from "./util/selfUpdate.js";
 import { migrateToDirectHeartbeat } from "./util/directHeartbeatMigration.js";
@@ -42,10 +45,10 @@ import { staleShellExportsForTargets } from "./tools/shellEnv.js";
 import { effectiveSubscription, metadataHeaderValue } from "./types.js";
 import { quitTargetKey, quitTargetLabel, relaunchResolvable, quitTargetSupported, relaunchApp, requestGracefulQuit, waitForQuit, } from "./util/appQuit.js";
 import { bold, cyan, dim, fail, heading, info, note, ok, warn, } from "./util/log.js";
-import { clearDevKey, clearEnrollment, hasEnrollment, loadProfile, recordManagedTools, saveProfile, saveDevKey, loadDevKey, stateDir, ensureStateDir, purgeRetiredFallbackState, } from "./util/persist.js";
+import { clearDevKey, clearEnrollment, hasEnrollment, loadProfile, profilePath, recordManagedTools, saveProfile, saveDevKey, loadDevKey, stateDir, ensureStateDir, purgeRetiredFallbackState, } from "./util/persist.js";
 import { revokeDeviceToken } from "./util/deviceToken.js";
 import { isFleetLockedTool } from "./util/policySync.js";
-import { confirm, isInteractive, prompt, resolveDisplayName, resolveTeam, } from "./commands/shared.js";
+import { confirm, isInteractive, PromptCancelledError, prompt, resolveDisplayName, resolveTeam, } from "./commands/shared.js";
 import { verifyConnection } from "./util/verify.js";
 import { detectSeatState } from "./util/seatState.js";
 import { isRemoteDevContext } from "./tools/copilotChat.js";
@@ -71,6 +74,42 @@ import { CLAUDE_DESKTOP_CREDENTIAL_ARG, } from "./tools/claudeDesktopCredentialP
 import { platform } from "node:os";
 const HELP = `${bold("anyray-connect")} — point your local coding tools at the Anyray gateway
 
+${bold("Usage")}
+  npx anyray-connect [options]
+  npx anyray-connect <gateway-url> [options]
+
+${bold("Subcommands")}
+  login             Sign in through browser SSO
+  wizard            Interactive guided setup (also the default on a TTY)
+  status            Show the current gateway and connected tools
+  doctor            Diagnose gateway reachability and tool configuration
+  sync              Pull the team's shared skills and instructions
+  update            Update Connect or configure automatic updates
+
+${bold("Options")}
+  --gateway <url>   Gateway origin
+  --enroll <link>   Connect with a passwordless enrollment link or token
+  --sso <link>      Connect with an enterprise SSO link or tenant id
+  --tools <ids>     Comma-separated subset: ${REGISTRY.map((t) => t.id).join(", ")}
+  --user <id>       Attribute spend to this user
+  --team <id>       Attribute spend to this team
+  --dry-run         Show what would change without writing anything
+  --yes, -y         Don't prompt for confirmation (for scripted rollout)
+  --revert          Undo a previous run and clear stored enrollment
+  --verbose         Show the curl re-test recipe and revert hint
+  --help, -h        Show this help
+
+Run \`npx anyray-connect --help --all\` for every command and option.
+
+${bold("What it does")}
+  Writes each tool's supported routing config plus the enrolled developer's
+  personal gateway key so requests flow through the gateway. The real provider
+  key stays server-side (ANYRAY_PROVIDER_KEY_*); your tools never hold it. Only
+  metadata (user/team) is attached — never prompt content.
+  ~/.anyray (mode 600) remembers your gateway, name/team, personal key, and the
+  per-skill versions ${dim("sync")} last wrote — for zero-question re-runs.`;
+const HELP_ALL = `${bold("anyray-connect")} — point your local coding tools at the Anyray gateway
+
 ${bold("Usage")}
   npx anyray-connect <gateway-url> [options]
   npx anyray-connect [options]   (gateway from $ANYRAY_GATEWAY_URL, the ~/.anyray cache, or http://localhost:8787)
@@ -224,6 +263,7 @@ ${bold("Options")}
                     clear the stored enrollment. Reconnecting needs --sso (or a
                     fresh --enroll link). Cannot be combined with --sso or
                     --enroll. Restart any editor that was running.
+  --verbose         Show the curl re-test recipe and revert hint after apply
   --help, -h        Show this help
 
 ${bold("What it does")}
@@ -237,16 +277,16 @@ ${bold("What it does")}
  * The identity submitted with an `--enroll` redemption. A SHARED link binds no
  * identity, and the control plane refuses an identity-less redemption (it has
  * nothing to put in the DevCert / attribute spend to) — so when `--user` is
- * absent, fall back to the same detected identity the apply flow attributes
- * spend with. Personal links ignore this server-side (pre-bound identity wins),
+ * absent, use an email-first automatic identity with a human-readable
+ * fallback. Personal links ignore this server-side (pre-bound identity wins),
  * and connect adopts the cert's user afterwards, so roster, cert, and spend
- * attribution all carry one identity. `--user ''` is the documented cache-clear
- * sentinel (and `?? ` would pass it through), so blank values fall back too —
- * the CP refuses an identity-less shared redemption.
+ * attribution all carry one verified identity. `--user ''` is the documented
+ * cache-clear sentinel (and `?? ` would pass it through), so blank values fall
+ * back too — the CP refuses an identity-less shared redemption.
  */
 export const enrollIdentity = (user) => {
     const explicit = user?.trim();
-    return explicit ? explicit : detectDisplayName();
+    return explicit ? explicit : detectEnrollmentIdentity();
 };
 export const parseArgs = (argv) => {
     const args = {
@@ -257,7 +297,9 @@ export const parseArgs = (argv) => {
         revert: false,
         force: false,
         skipVerify: false,
+        verbose: false,
         help: false,
+        helpAll: false,
     };
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -362,10 +404,23 @@ export const parseArgs = (argv) => {
             case "--security-review":
                 args.securityReview = true;
                 break;
+            case "--verbose":
+                args.verbose = true;
+                break;
             case "--help":
             case "-h":
                 args.help = true;
                 break;
+            case "--help-all":
+                args.help = true;
+                args.helpAll = true;
+                break;
+            case "--all":
+                if (!argv.includes("--help") && !argv.includes("-h")) {
+                    throw new Error(`unknown option: ${a}`);
+                }
+                args.helpAll = true;
+                break;
             default:
                 // First non-flag token is the gateway URL; a second positional is an error.
                 if (!a.startsWith("-") && args.gateway === undefined) {
@@ -440,6 +495,18 @@ const printTarget = (target, adapters) => {
     }
     info(`  Attribution: ${metadataHeaderValue(target.metadata) ?? dim("(none — pass --user)")}`);
 };
+const printSelectedTools = async (adapters, mode) => {
+    heading("Selected tools");
+    for (const adapter of adapters) {
+        const detected = await adapter.detect();
+        if (detected.installed) {
+            info(`  ${adapter.title} ${dim(`(${adapter.id})`)} — ${mode === "plan" ? "will configure" : "would configure after enrollment"}${detected.detail ? `; ${detected.detail}` : ""}`);
+        }
+        else {
+            note(`  ${adapter.title} ${dim(`(${adapter.id})`)} — not found${detected.detail ? `; ${detected.detail}` : ""}`);
+        }
+    }
+};
 /**
  * Reuse a cached key only when it has the required `ark_` shape and its locally
  * recorded expiry, when present, is still in the future. Older profiles did not
@@ -521,13 +588,14 @@ explicitIds) => {
     let changes = 0;
     const manual = [];
     const results = [];
+    const skipped = [];
     for (const adapter of adapters) {
         const detected = await adapter.detect();
-        heading(`${adapter.title} ${dim(`(${adapter.id})`)}`);
         if (!detected.installed && !revert) {
-            note(`  not found — ${detected.detail ?? "skipping"}`);
+            skipped.push(adapter.title);
             continue;
         }
+        heading(`${adapter.title} ${dim(`(${adapter.id})`)}`);
         try {
             const result = revert
                 ? await adapter.revert(opts)
@@ -567,6 +635,9 @@ explicitIds) => {
             fail(`  failed: ${error instanceof Error ? error.message : String(error)}`);
         }
     }
+    if (skipped.length > 0) {
+        note(`Skipped ${skipped.length} not installed (${skipped.join(", ")})`);
+    }
     // Upgrade cleanup, deliberately AFTER the adapters: every managed tool now
     // names the current runtime, so the copies left by earlier npx-launched
     // versions are unreferenced and can go. Nothing ever reaped them before, so an
@@ -752,55 +823,154 @@ export const relaunchApps = (closed, deps = {}) => {
  * which the adapter must be named to get (see `ToolAdapter.changesBilling`).
  */
 export const wizardSuggests = (adapter) => adapter.changesBilling !== true;
-/**
- * Interactive wizard — guided first-run setup on a TTY. Detects installed
- * tools, lets the dev pick which to configure, confirms the gateway URL, name,
- * and team, then hands back the chosen args for the apply flow. Mutates and
- * returns `args`; falls through untouched if anything is already specified.
- *
- * Only the questions the dev hasn't already answered via flags are asked, so
- * `wizard --user x` stays terse. The apply flow still does the real work (and
- * its own preflight + persistence) — the wizard only gathers input.
- */
-const runWizard = async (args, profile) => {
+/** Gather first-run choices without writing configuration. */
+export const runWizard = async (args, profile, deps = {}) => {
+    const enrollmentPresent = deps.hasEnrollment ?? hasEnrollment;
+    const supportsMultiSelect = deps.canMultiSelect ?? canMultiSelect;
+    const selectMany = deps.multiSelect ?? multiSelect;
+    const ask = deps.prompt ?? prompt;
+    const registry = deps.registry ?? REGISTRY;
     info(bold("Anyray connect — guided setup"));
     info(dim("Point your local coding tools at the Anyray gateway. Ctrl-C to abort."));
-    // Tool selection: show what's installed, let the dev narrow it down.
+    if (await enrollmentPresent()) {
+        info("Stored enrollment will be reused. Run with --revert to clear it.");
+    }
+    else if (!args.enroll && !args.sso && !args.gateway) {
+        heading("How do you want to connect?");
+        let method;
+        for (let attempt = 0; attempt < 3 && !method; attempt++) {
+            if (supportsMultiSelect()) {
+                const outcome = await selectMany({
+                    title: "Choose a connection method",
+                    single: true,
+                    items: [
+                        { value: "enroll", label: "Paste an enrollment link", selected: true },
+                        { value: "sso", label: "Sign in with SSO" },
+                        { value: "gateway", label: "I already have a gateway URL" },
+                    ],
+                });
+                if (outcome.kind === "cancelled")
+                    throw new PromptCancelledError();
+                method = outcome.values[0];
+            }
+            else {
+                info("  1. Paste an enrollment link");
+                info("  2. Sign in with SSO");
+                info("  3. I already have a gateway URL");
+                const choice = await ask("? Connection method (1-3)", "1");
+                method =
+                    choice === "1"
+                        ? "enroll"
+                        : choice === "2"
+                            ? "sso"
+                            : choice === "3"
+                                ? "gateway"
+                                : undefined;
+            }
+            if (!method)
+                warn("Choose one of the three connection methods.");
+        }
+        if (!method)
+            throw new PromptCancelledError();
+        for (let attempt = 0; attempt < 3; attempt++) {
+            if (method === "enroll") {
+                const answer = await ask("? Enrollment link or token");
+                if (answer && isEnrollArg(answer) && parseEnrollLink(answer)) {
+                    args.enroll = answer;
+                    break;
+                }
+                warn("That is not a valid enrollment link or token. Try again.");
+            }
+            else if (method === "sso") {
+                const answer = await ask("? SSO link or tenant id");
+                if (answer && parseSsoLink(answer)) {
+                    args.sso = answer;
+                    break;
+                }
+                warn("That is not a valid SSO link or tenant id. Try again.");
+            }
+            else {
+                const answer = await ask("? Gateway URL", profile.gateway || process.env.ANYRAY_GATEWAY_URL);
+                if (answer && isEnrollArg(answer)) {
+                    args.enroll = answer;
+                    info("That looks like an enrollment link — using passwordless enrollment.");
+                    break;
+                }
+                try {
+                    if (!answer)
+                        throw new Error("missing gateway");
+                    args.gateway = resolveOrigin(answer);
+                    break;
+                }
+                catch {
+                    warn("That is not a valid http(s) gateway URL. Try again.");
+                }
+            }
+        }
+        if (!args.enroll && !args.sso && !args.gateway) {
+            throw new PromptCancelledError();
+        }
+    }
     if (!args.tools || args.tools.length === 0) {
         heading("Tools detected");
-        // Billing-switching tools are listed with their consequence but kept OUT of
-        // the prefilled default: pressing Enter accepts a suggestion, which is not
-        // a decision about where someone's inference is billed. Naming one is.
-        const suggested = [];
-        for (const adapter of REGISTRY) {
+        const installed = [];
+        const absent = [];
+        for (const adapter of registry) {
             const detected = await adapter.detect();
             if (!detected.installed) {
-                note(`  ${adapter.title} — not installed`);
+                absent.push(adapter);
                 continue;
             }
-            if (wizardSuggests(adapter)) {
-                suggested.push(adapter.id);
-                ok(`  ${adapter.title} ${dim(`(${adapter.id})`)}`);
-            }
-            else {
-                note(`  ${adapter.title} ${dim(`(${adapter.id})`)} — routing this moves its spend off your subscription onto the org API bill; add it by name to opt in`);
+            installed.push(adapter);
+        }
+        const suggested = installed
+            .filter((adapter) => wizardSuggests(adapter))
+            .map((adapter) => adapter.id);
+        if (installed.length > 0) {
+            for (let attempt = 0; attempt < 3 && !args.tools; attempt++) {
+                let chosen;
+                if (supportsMultiSelect()) {
+                    const outcome = await selectMany({
+                        title: "Tools to configure",
+                        items: installed.map((adapter) => ({
+                            value: adapter.id,
+                            label: `${adapter.title} (${adapter.id})`,
+                            hint: wizardSuggests(adapter)
+                                ? undefined
+                                : "moves inference spend from your subscription to the org API bill",
+                            selected: wizardSuggests(adapter),
+                            requiresExplicitChoice: !wizardSuggests(adapter),
+                        })),
+                    });
+                    if (outcome.kind === "cancelled")
+                        throw new PromptCancelledError();
+                    chosen = outcome.values;
+                }
+                else {
+                    const pick = await ask("? Tools to configure (comma-separated, blank = all suggested)", suggested.join(",") || undefined);
+                    chosen = (pick ?? "")
+                        .split(",")
+                        .map((value) => value.trim())
+                        .filter(Boolean);
+                    const installedIds = new Set(installed.map((adapter) => adapter.id));
+                    const invalid = chosen.filter((id) => !installedIds.has(id));
+                    if (invalid.length > 0) {
+                        warn(`Unknown or unavailable tool id${invalid.length === 1 ? "" : "s"}. Choose from: ${installed.map((adapter) => adapter.id).join(", ")}.`);
+                        continue;
+                    }
+                }
+                if (chosen.length === 0) {
+                    warn("Choose at least one installed tool.");
+                    continue;
+                }
+                args.tools = chosen;
             }
+            if (!args.tools)
+                throw new PromptCancelledError();
+        }
+        if (absent.length > 0) {
+            note(`${absent.length} others not installed (${absent.map((adapter) => adapter.id).join(", ")})`);
         }
-        const pick = await prompt("? Tools to configure (comma-separated, blank = all suggested)", suggested.join(",") || undefined);
-        const chosen = (pick ?? "")
-            .split(",")
-            .map((s) => s.trim())
-            .filter(Boolean);
-        if (chosen.length > 0)
-            args.tools = chosen;
-    }
-    // Gateway URL: default to the cached/env/default origin.
-    if (!args.gateway) {
-        heading("Gateway");
-        const fallback = profile.gateway || process.env.ANYRAY_GATEWAY_URL;
-        const answer = await prompt("? Gateway URL", fallback);
-        if (answer)
-            args.gateway = answer;
     }
     // Identity is resolved by the apply flow's resolveDisplayName/resolveTeam,
     // which already prompt on a TTY — leave args.user/args.team untouched so the
@@ -819,7 +989,7 @@ const runVerify = async (target, toolIds) => {
     heading("Verifying the connection");
     // Pass the configured tool ids so the org-key remedy can be tool-specific
     // (e.g. OpenCode's Claude provider has no personal-subscription fallback).
-    const verdict = await verifyConnection(target, { tools: toolIds });
+    const verdict = await withSpinner("Checking the gateway…", () => verifyConnection(target, { tools: toolIds }));
     if (verdict.kind === "ok")
         ok(`  ${verdict.detail}`);
     else if (verdict.kind === "unreachable" ||
@@ -839,13 +1009,37 @@ const runVerify = async (target, toolIds) => {
 const RECONCILE_RETRY_PROBE_TIMEOUT_MS = 5_000;
 const RECONCILE_PROBE_GAP_MS = 500;
 const RECONCILE_PROBE_ATTEMPTS = 3;
-// Scheduler-tick self-heal: EDR kills/quarantines the daemon service; a silent
-// port with key refresh enabled reinstalls it (the probe-first check is what
-// leaves a live daemon alone — including a healthy one on an older build).
+const PROFILE_SETTLE_MS = 10 * 60 * 1000;
+const defaultProfileAgeMs = async () => {
+    try {
+        const s = await stat(await profilePath());
+        return Date.now() - s.mtimeMs;
+    }
+    catch {
+        return Number.POSITIVE_INFINITY;
+    }
+};
+// Scheduler-tick self-heal, both directions: reinstall a daemon EDR killed
+// while refresh is on; reap a disowned unit file (it re-registers on login).
 export const reconcileProxyService = async (deps = {}) => {
     try {
         const profile = await (deps.load ?? loadProfile)();
-        if (profile.keyRefreshEnabled !== true || !profile.gateway)
+        if (profile.keyRefreshEnabled !== true) {
+            if ((deps.draining ?? isDraining)())
+                return;
+            // Unit-file-gated: a port probe would reap the profile-less fleet
+            // daemon (RFC 0007); a file-less zombie dies at reboot anyway.
+            if (!(await (deps.unitExists ?? proxyUnitFileExists)()))
+                return;
+            // An apply persists the direct profile before repointing tools — only
+            // sweep a settled profile so a racing tick never strands them.
+            const age = await (deps.profileAgeMs ?? defaultProfileAgeMs)();
+            if (age < PROFILE_SETTLE_MS)
+                return;
+            await (deps.uninstall ?? uninstallProxyService)(profile.fallbackPort ?? DEFAULT_LOOPBACK_PORT);
+            return;
+        }
+        if (!profile.gateway)
             return;
         // RFC 0010 §6 P4: while a verified signed tray app owns launch-at-login,
         // it — not launchd — respawns a dead daemon, so reinstalling the
@@ -1027,7 +1221,31 @@ const SUBCOMMANDS = new Set([
     "sync",
     "device-url",
 ]);
-export const run = async (argv) => {
+const runApplySafely = async (argv, forceWizard) => {
+    try {
+        return await runApplyCommand(argv, forceWizard);
+    }
+    catch (error) {
+        if (error instanceof PromptCancelledError) {
+            console.error(dim("Cancelled — nothing was written."));
+            return 130;
+        }
+        throw error;
+    }
+};
+export const confirmApplyPlan = async (args, wizardRan, targetCount, deps = {}) => {
+    if (args.yes || args.dryRun)
+        return "proceed";
+    if (!(deps.isInteractive ?? isInteractive)())
+        return "non-interactive";
+    // Flag-driven runs keep their original question so scripted use is unchanged.
+    const verb = args.revert ? "remove Anyray config from" : "configure";
+    const question = wizardRan
+        ? "Apply this configuration?"
+        : `\n${verb} ${targetCount} tool target(s)?`;
+    return (await (deps.confirm ?? confirm)(question)) ? "proceed" : "declined";
+};
+const dispatch = async (argv) => {
     // Hidden hook entrypoint: Claude Code invokes `anyray-connect __anyray-hook`
     // as a PostToolUse hook. It speaks the hook stdin/stdout JSON protocol, so it
     // must run BEFORE any human-facing logging touches stdout. Never throws.
@@ -1247,7 +1465,7 @@ export const run = async (argv) => {
             return 1;
         }
         if (parsed.help) {
-            info(HELP);
+            info(parsed.helpAll ? HELP_ALL : HELP);
             return 0;
         }
         if (sub === "status")
@@ -1267,11 +1485,25 @@ export const run = async (argv) => {
         if (sub === "device-url")
             return runDeviceUrl();
         // 'wizard' → apply flow with the wizard enabled.
-        return runApplyCommand(rest, true);
+        return runApplySafely(rest, true);
+    }
+    return runApplySafely(argv, false);
+};
+// Not just apply: without this, index.ts dumps the raw error and exits 1.
+export const run = async (argv) => {
+    try {
+        return await dispatch(argv);
+    }
+    catch (error) {
+        if (error instanceof PromptCancelledError) {
+            console.error(dim("Cancelled."));
+            return 130;
+        }
+        throw error;
     }
-    return runApplyCommand(argv, false);
 };
-const runApplyCommand = async (argv, forceWizard) => {
+export const runApplyCommand = async (argv, forceWizard, deps = {}) => {
+    const interactive = deps.isInteractive ?? isInteractive;
     let args;
     try {
         args = parseArgs(argv);
@@ -1282,7 +1514,7 @@ const runApplyCommand = async (argv, forceWizard) => {
         return 1;
     }
     if (args.help) {
-        info(HELP);
+        info(args.helpAll ? HELP_ALL : HELP);
         return 0;
     }
     // These commands have opposite effects. In particular, accepting
@@ -1372,8 +1604,10 @@ const runApplyCommand = async (argv, forceWizard) => {
         !args.dryRun &&
         !args.enroll &&
         !args.sso;
-    if ((forceWizard || bareInteractive) && isInteractive()) {
-        args = await runWizard(args, profile);
+    let wizardRan = false;
+    if ((forceWizard || bareInteractive) && interactive()) {
+        args = await (deps.runWizard ?? runWizard)(args, profile);
+        wizardRan = true;
     }
     let adapters;
     try {
@@ -1390,21 +1624,32 @@ const runApplyCommand = async (argv, forceWizard) => {
     if (args.gateway && !args.enroll && isEnrollArg(args.gateway)) {
         args.enroll = args.gateway;
         args.gateway = undefined;
-        note("That looks like an enrollment link — treating it as --enroll.");
-    }
-    // An --enroll link carries no gateway URL of its own; resolve the bound
-    // gateway from the control plane's enroll-info endpoint so `--enroll <link>`
-    // is self-sufficient. An explicit --gateway wins — we only fill the gap. The
-    // lookup is read-only and does not consume the enrollment token.
+        info("That looks like an enrollment link — treating it as --enroll.");
+    }
+    // Resolve enrollment info when the gateway is unknown or a cached cert might
+    // be reused. Besides the gateway URL it carries a personal link's pre-bound
+    // identity. For a shared link, the absence of that identity tells reuse logic
+    // to compare the stored cert with today's automatic identity, so a legacy
+    // `unknown` binding can self-heal on re-run. A fresh enrollment with an
+    // explicit gateway keeps the old one-round-trip path. The lookup is read-only
+    // and does not consume the token.
     let enrollDeploymentId;
-    if (args.enroll && !args.gateway) {
+    let enrollBoundIdentity;
+    let enrollInfoResolved = false;
+    if (args.enroll && (!args.gateway || profile.enrolledCert)) {
         const enrollLink = parseEnrollLink(args.enroll);
         if (enrollLink) {
             try {
-                const resolved = await resolveEnrollLink(enrollLink);
-                args.gateway = resolved.gatewayUrl;
+                const resolved = await withSpinner("Resolving enrollment link…", () => resolveEnrollLink(enrollLink));
+                const filledGateway = !args.gateway;
+                if (filledGateway)
+                    args.gateway = resolved.gatewayUrl;
                 enrollDeploymentId = resolved.deploymentId;
-                note(`Enrollment link${resolved.org ? ` for ${resolved.org}` : ""}: gateway ${resolved.gatewayUrl}`);
+                enrollBoundIdentity = resolved.email;
+                enrollInfoResolved = true;
+                if (filledGateway) {
+                    note(`Enrollment link${resolved.org ? ` for ${resolved.org}` : ""}: gateway ${resolved.gatewayUrl}`);
+                }
                 if (resolved.seatMode && !args.subscription) {
                     args.subscription = true;
                     note("Subscription org: using pass-through auth (--subscription) — your own seat sign-in is used.");
@@ -1415,7 +1660,9 @@ const runApplyCommand = async (argv, forceWizard) => {
                 // one (e.g. a returning dev re-minting while the control plane is briefly
                 // unreachable) — the cache/env logic below fills it. Only fail when the
                 // gateway is genuinely unknown.
-                const fallback = process.env.ANYRAY_GATEWAY_URL?.trim() || profile.gateway;
+                const fallback = args.gateway ||
+                    process.env.ANYRAY_GATEWAY_URL?.trim() ||
+                    profile.gateway;
                 if (fallback) {
                     note(`Could not resolve the gateway from the enrollment link — using ${fallback}.`);
                 }
@@ -1442,12 +1689,12 @@ const runApplyCommand = async (argv, forceWizard) => {
                 return 1;
             }
             try {
-                const result = await ssoEnroll({
+                const result = await withSpinner("Waiting for SSO sign-in…", () => ssoEnroll({
                     cpOrigin: ssoLink.cpOrigin,
                     tenantId: ssoLink.tenantId,
                     gatewayUrl: args.gateway,
                     log: (m) => note(m),
-                });
+                }));
                 ssoEnrollment = {
                     cert: result.cert,
                     privateKeyPem: result.privateKeyPem,
@@ -1526,7 +1773,7 @@ const runApplyCommand = async (argv, forceWizard) => {
         // the window once we already hold a key.
         await reserveMint();
         const presentedTokenHash = enrollTokenHash(input.token);
-        const storedValid = canReuseEnrolledCert(profile.enrolledCert, profile.enrolledCertExpiry, input.deploymentId, Date.now(), presentedTokenHash, profile.enrolledTokenHash);
+        const storedValid = canReuseEnrolledCert(profile.enrolledCert, profile.enrolledCertExpiry, input.deploymentId, Date.now(), presentedTokenHash, profile.enrolledTokenHash, input.expectedUser);
         const storedPrivateKey = storedValid ? await loadDevKey() : undefined;
         const reuse = storedValid && storedPrivateKey && profile.enrolledCert
             ? {
@@ -1593,13 +1840,20 @@ const runApplyCommand = async (argv, forceWizard) => {
             }
             try {
                 const machineId = args.machine ? deriveMachineId() : undefined;
+                const detectedIdentity = enrollBoundIdentity ?? enrollIdentity(args.user);
+                const expectedUser = args.machine
+                    ? `machine:${machineId}`
+                    : enrollInfoResolved
+                        ? detectedIdentity
+                        : undefined;
                 await runEnrollment({
                     cpOrigin: link.cpOrigin,
                     token: link.token,
-                    email: enrollIdentity(args.user),
+                    email: detectedIdentity,
                     team: args.team,
                     machineId,
                     deploymentId: enrollDeploymentId,
+                    expectedUser,
                 });
             }
             catch (error) {
@@ -1714,34 +1968,27 @@ const runApplyCommand = async (argv, forceWizard) => {
         }
         warn(`  ${message}`);
         note("  Dry run only — no placeholder configuration will be written.");
-        heading("Selected tools");
-        for (const adapter of adapters) {
-            const detected = await adapter.detect();
-            if (detected.installed) {
-                info(`  ${adapter.title} ${dim(`(${adapter.id})`)} — would configure after enrollment${detected.detail ? `; ${detected.detail}` : ""}`);
-            }
-            else {
-                note(`  ${adapter.title} ${dim(`(${adapter.id})`)} — not found${detected.detail ? `; ${detected.detail}` : ""}`);
-            }
-        }
+        await printSelectedTools(adapters, "after-enrollment");
         note("\nDry run complete — no files were written.");
         return 0;
     }
     if (!args.revert)
         printTarget(target, adapters);
+    if (wizardRan && !args.revert) {
+        await printSelectedTools(adapters, "plan");
+    }
     if (args.dryRun)
         note("\nDry run — no files will be written.");
-    if (!args.yes && !args.dryRun) {
-        if (!isInteractive()) {
-            fail("\nNon-interactive session — cannot ask for confirmation. Pass --yes to proceed.");
-            return 1;
-        }
-        const verb = args.revert ? "remove Anyray config from" : "configure";
-        const proceed = await confirm(`\n${verb} ${adapters.length} tool target(s)?`);
-        if (!proceed) {
-            note("Aborted. Nothing changed.");
-            return 0;
-        }
+    const confirmation = await confirmApplyPlan(args, wizardRan, adapters.length, { isInteractive: interactive, confirm: deps.confirm });
+    if (confirmation === "non-interactive") {
+        fail("\nNon-interactive session — cannot ask for confirmation. Pass --yes to proceed.");
+        return 1;
+    }
+    if (confirmation === "declined") {
+        note(wizardRan
+            ? "Nothing was written. Re-run `npx anyray-connect wizard` when you're ready."
+            : "Aborted. Nothing changed.");
+        return 0;
     }
     // Preflight: never repoint a working tool at a gateway that isn't answering.
     // Skipped for dry-run (writes nothing) and revert (removing config, not adding
@@ -2023,8 +2270,8 @@ const runApplyCommand = async (argv, forceWizard) => {
             }
         }
         else if (args.revert && !args.dryRun) {
-            note("\nKeeping the stored enrollment — the tools you did not name still need it.");
-            note("Run --revert with no --tools to remove it.");
+            info("\nKeeping the stored enrollment — the tools you did not name still need it.");
+            info("Run --revert with no --tools to remove it.");
         }
         // A named `--tools` list (the wizard writes its checklist here too) is the
         // developer choosing these adapters by hand; the default sweep names none.
@@ -2165,7 +2412,21 @@ const runApplyCommand = async (argv, forceWizard) => {
                 // separately at install time (and by `doctor`).
                 await runVerify(target, adapters.map((a) => a.id));
             }
-            info("\nRe-test by hand any time:");
+            heading("What's next");
+            const configuredIds = new Set(results
+                .filter((result) => result.status === "configured")
+                .map((result) => result.id));
+            const connected = adapters
+                .filter((adapter) => configuredIds.has(adapter.id))
+                .map((adapter) => adapter.title);
+            info(connected.length > 0
+                ? `  Connected: ${connected.join(", ")}`
+                : "  Connected: no tools completed automatic configuration.");
+            info("  Restart any editor that was already running — it loaded our config at startup.");
+            info("  If something looks wrong: npx anyray-connect doctor");
+            if (!args.verbose)
+                return 0;
+            info("\n  Re-test by hand any time:");
             const nativeCursorOnly = target.authMode !== "placeholder" &&
                 adapters.length === 1 &&
                 adapters[0]?.id === "cursor";