anyray-connect 0.11.74 → 0.11.76

package/dist/cli.js

@@ -10,13 +10,15 @@
  * personal gateway authentication, and content-free attribution.
  */
 import { isPersonalClientKey, isInsecureRemoteOrigin, normalizeOrigin, resolveOrigin, resolveTarget, withLocalProxy, } from "./target.js";
-import { pickLoopbackPort, installProxyService, uninstallProxyService, probeHealth, } from "./util/proxyService.js";
+import { pickLoopbackPort, installProxyService, uninstallProxyService, probeHealth, DEFAULT_LOOPBACK_PORT, } from "./util/proxyService.js";
 import { installRefreshScheduler, uninstallRefreshScheduler, } from "./util/refreshScheduler.js";
+import { detectRemoteDevBackend, isContainerBackend, } from "./util/remoteContext.js";
 import { runRefreshProxy } from "./commands/refreshProxy.js";
 import { loopbackEngaged } from "./util/loopback.js";
-import { runCursorWatch } from "./commands/cursorWatch.js";
+import { runQuitWatch } from "./commands/quitWatch.js";
 import { runManaged } from "./commands/managed.js";
 import { runPrintKey } from "./commands/printKey.js";
+import { runProjectApply } from "./commands/projectApply.js";
 import { runClaudeDesktopCredential, } from "./commands/claudeDesktopCredential.js";
 import { runDesktop } from "./commands/desktop.js";
 import { runRecallCommand, runRetrieveCommand } from "./commands/retrieval.js";
@@ -33,11 +35,13 @@ import { runSelfUpdate } from "./util/selfUpdate.js";
 import { REGISTRY, byId } from "./tools/index.js";
 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 { confirm, isInteractive, 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";
 import { runStatus } from "./commands/status.js";
 import { runDoctor } from "./commands/doctor.js";
 import { runSync } from "./commands/sync.js";
@@ -56,6 +60,7 @@ import { runAcpAgent } from "./commands/acpAgent.js";
 import { deriveMachineId } from "./util/machineId.js";
 import { relaunchFromDurableRuntime } from "./util/durableRuntime.js";
 import { CLAUDE_DESKTOP_CREDENTIAL_ARG, } from "./tools/claudeDesktopCredentialProtocol.js";
+import { platform } from "node:os";
 const HELP = `${bold("anyray-connect")} — point your local coding tools at the Anyray gateway
 
 ${bold("Usage")}
@@ -70,9 +75,11 @@ ${bold("Subcommands")}
   doctor            Diagnose gateway reachability + tool config (incl. each tool's
                     retrieval MCP-server registration); exits non-zero on problems.
                     --json prints a shareable content-free report (send it to support);
-                    --verify also runs the auth smoke probe and a retrieval-loop
-                    probe (two tiny requests; the loop probe never latches
-                    model retrieve capability);
+                    the auth smoke probe runs by DEFAULT (one tiny request) so an
+                    all-clear means a request actually worked, not just that the
+                    config looks right; --no-verify skips it for offline runs;
+                    --verify additionally runs a retrieval-loop probe (which
+                    never latches model retrieve capability);
                     --repair re-applies managed tools whose routing drifted
                     (only tools a previous apply recorded — a reverted tool
                     is never resurrected) and deletes the retired fallback
@@ -173,6 +180,12 @@ ${bold("Options")}
                     LiteLLM virtual key). Stored locally (mode 600) and in the
                     tool config, never sent to Anyray's control plane.
   --tools <ids>     Comma-separated subset: ${REGISTRY.map((t) => t.id).join(", ")}
+  --project         Write committable, credential-free routing config into the
+                    CURRENT repo (.claude/settings.json + .codex/config.toml)
+                    instead of this machine's user config — so devcontainers,
+                    Codespaces, SSH checkouts, and CI route without a per-machine
+                    apply. Org API lane only; each machine still enrolls once.
+                    Combine with --revert to remove it.
   --dry-run         Show what would change without writing anything
   --yes, -y         Don't prompt for confirmation (for scripted rollout)
   --force           Skip the gateway reachability check before writing
@@ -183,6 +196,15 @@ ${bold("Options")}
                     daemon fills a freshly re-minted key on each request so a
                     long session never 401s on an expired key mid-flight; this
                     forces the legacy lane that bakes the key once at launch.
+  --quit-apps       Close the apps this run reconfigures — and reopen them when
+                    it finishes — without asking. Only apps that are open AND
+                    whose configuration actually changes; the quit is always the
+                    polite one the app may refuse, never a force kill. An
+                    interactive run is asked once and defaults to NO; --yes, a
+                    non-TTY, --dry-run and the managed/MDM payloads close
+                    nothing unless this flag is passed explicitly.
+  --no-quit-apps    Never close anything, overriding --quit-apps. Apps that were
+                    open keep their old routing until you restart them yourself.
   --revert          Undo a previous run: unpick every tool config we wrote and
                     clear the stored enrollment. Reconnecting needs --sso (or a
                     fresh --enroll link). Cannot be combined with --sso or
@@ -275,6 +297,9 @@ export const parseArgs = (argv) => {
                     .map((s) => s.trim())
                     .filter(Boolean);
                 break;
+            case "--project":
+                args.project = true;
+                break;
             case "--dry-run":
                 args.dryRun = true;
                 break;
@@ -295,6 +320,12 @@ export const parseArgs = (argv) => {
             case "--no-key-refresh":
                 args.noKeyRefresh = true;
                 break;
+            case "--quit-apps":
+                args.quitApps = true;
+                break;
+            case "--no-quit-apps":
+                args.noQuitApps = true;
+                break;
             case "--revert":
                 args.revert = true;
                 break;
@@ -304,6 +335,9 @@ export const parseArgs = (argv) => {
             case "--verify":
                 args.verify = true;
                 break;
+            case "--no-verify":
+                args.noVerify = true;
+                break;
             case "--repair":
                 args.repair = true;
                 break;
@@ -482,6 +516,10 @@ explicitIds) => {
                 : await adapter.apply(target, {
                     ...opts,
                     explicit: explicitIds?.has(adapter.id) === true,
+                    // This loop prints every message below, so an adapter may take a
+                    // side action on the developer's own files here. The background
+                    // lanes call `apply` directly and never set this.
+                    reportsToUser: true,
                 });
             for (const m of result.messages)
                 info(`  ${m}`);
@@ -530,6 +568,153 @@ export const manualStepsNotice = (titles) => {
         "Then restart or reload the app as instructed; use `npx anyray-connect status` for the available route checks.",
     ];
 };
+/**
+ * The plan pass: which open apps would this apply actually affect?
+ *
+ * An editor caches its environment at launch and Cursor / Claude Desktop cannot
+ * have their stores rewritten while they are open, so a config written now does
+ * not take effect until the app restarts. Rather than printing "restart X" and
+ * hoping, Connect offers to do it — but only for an adapter that is
+ * installed, declares how its app is named to each platform
+ * (`quitGated.quitTarget`, read off the REGISTRY so this file never names an
+ * app), is running, and is NOT already pointed at this gateway.
+ *
+ * That last clause is what keeps a no-op re-run silent: nothing changes, so
+ * nobody's apps get closed.
+ *
+ * KNOWN BLIND SPOT, deliberately not guessed at: `pointsAt` reads the tool's
+ * CONFIG on disk, so it cannot see "configured, but the running process still
+ * holds the environment it cached at launch" — that app reads as correctly
+ * configured here and is left alone. `doctor` owns that case; inferring it
+ * would mean offering to close apps on every single re-run.
+ *
+ * Read-only and best-effort throughout: an adapter probe that throws simply
+ * drops out of the plan.
+ */
+export const planAppRestarts = async (adapters, origin, 
+// Explicit so a test can assert a platform deliberately. Reading the host's
+// real platform made three of these tests pass on macOS and fail on Linux CI,
+// because the fixture named no Linux spelling and the skip was invisible.
+runtimePlatform = platform()) => {
+    const candidates = [];
+    // One APP, not one adapter. VS Code carries both Copilot adapters, so without
+    // this the developer is asked twice about the same window and it is closed
+    // twice — the second quit landing on an app that is already gone.
+    const claimedApps = new Set();
+    for (const adapter of adapters) {
+        const seam = adapter.quitGated;
+        const quitTarget = seam?.quitTarget;
+        if (!seam || !quitTarget)
+            continue;
+        // A target that doesn't name this platform can't be honoured here, and an
+        // offer we can't honour reads as a broken promise.
+        if (!quitTargetSupported(quitTarget, runtimePlatform))
+            continue;
+        // Never close what we cannot reopen (Flatpak/AppImage editors on Linux).
+        if (!relaunchResolvable(quitTarget, runtimePlatform))
+            continue;
+        const app = quitTargetKey(quitTarget, runtimePlatform);
+        if (claimedApps.has(app))
+            continue;
+        try {
+            const detected = await adapter.detect();
+            if (!detected.installed)
+                continue;
+            if (!seam.isRunning())
+                continue;
+            if ((await adapter.pointsAt?.(origin)) === true)
+                continue;
+        }
+        catch {
+            // Never let a probe failure turn into an offer to close someone's editor.
+            continue;
+        }
+        claimedApps.add(app);
+        candidates.push({
+            id: adapter.id,
+            // The APP's name, not the adapter's — see `quitTargetLabel`.
+            title: quitTargetLabel(quitTarget),
+            quitTarget,
+            isRunning: () => seam.isRunning(),
+        });
+    }
+    return candidates;
+};
+/**
+ * May this invocation close apps at all? Consent has to be present on the
+ * command line or at a prompt:
+ * - `--no-quit-apps` refuses, and wins over everything else.
+ * - `--dry-run` writes nothing, so it closes nothing (it reports the offer).
+ * - `--quit-apps` is an operator asking for it explicitly — the only way a
+ *   scripted run gets it.
+ * - otherwise: an interactive TTY that was not handed `--yes` may ASK (the
+ *   prompt itself defaults to no).
+ *
+ * `--yes`, a non-TTY and the managed/MDM payloads therefore close NOTHING by
+ * default. That is the hard rule: a buyer rolling Connect out to 500 seats must
+ * never have it close an app on someone's machine.
+ */
+export const quitAppsAllowed = (args, interactive) => {
+    if (args.noQuitApps === true)
+        return false;
+    if (args.dryRun)
+        return false;
+    if (args.quitApps === true)
+        return true;
+    return !args.yes && interactive;
+};
+/** The one-line offer. Returned as a string so it's testable without a TTY. */
+export const appRestartOffer = (titles) => {
+    const which = titles.length === 1
+        ? `${titles[0]} is open and won't pick this up until it restarts. Quit it now?`
+        : `${titles.slice(0, -1).join(", ")} and ${titles[titles.length - 1]} are open and won't pick this up until they restart. Quit them now?`;
+    return `\n${which}`;
+};
+/**
+ * Ask each accepted app to quit and confirm it actually went away. Returns the
+ * ones Connect really closed — the exact set the relaunch is allowed to reopen.
+ *
+ * An app that refuses (an unsaved buffer, a modal) is a legitimate answer: say
+ * so plainly and carry on with the apply, which leaves the adapter's own
+ * queue-on-quit path to finish the job whenever the developer closes it. Never
+ * escalate to a force kill, never retry — these apps write state on exit.
+ */
+export const quitAppsNow = async (candidates, deps = {}) => {
+    const requestQuit = deps.requestQuit ?? ((target) => requestGracefulQuit(target));
+    const waitFor = deps.waitFor ?? ((isRunning) => waitForQuit(isRunning));
+    const closed = [];
+    for (const candidate of candidates) {
+        const delivered = requestQuit(candidate.quitTarget);
+        const gone = delivered && (await waitFor(candidate.isRunning));
+        if (gone) {
+            closed.push(candidate);
+            ok(`  Closed ${candidate.title}.`);
+            continue;
+        }
+        warn(`  ${candidate.title} is still open — leaving it alone.`);
+        note(`  Its configuration is written either way; ${candidate.title} picks it up the next time you close it.`);
+    }
+    return closed;
+};
+/**
+ * Reopen exactly what we closed, under the consent that closed it — never a
+ * second prompt, and never an app the developer closed themselves. Leaving
+ * someone's IDE shut is a worse outcome than never having offered.
+ */
+export const relaunchApps = (closed, deps = {}) => {
+    const relaunch = deps.relaunch ?? ((target) => relaunchApp(target));
+    const reopened = [];
+    for (const candidate of closed) {
+        if (relaunch(candidate.quitTarget)) {
+            reopened.push(candidate.title);
+            ok(`  Reopened ${candidate.title}.`);
+        }
+        else {
+            warn(`  Could not reopen ${candidate.title} — start it when you're ready.`);
+        }
+    }
+    return reopened;
+};
 /**
  * May the wizard put this tool in its prefilled selection?
  *
@@ -623,6 +808,46 @@ const runVerify = async (target, toolIds) => {
     for (const line of verdict.remedy)
         info(dim(`  ${line}`));
 };
+/** Per-probe timeout for the reconcile retries — generous, a wedged daemon fails them all. */
+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).
+export const reconcileProxyService = async (deps = {}) => {
+    try {
+        const profile = await (deps.load ?? loadProfile)();
+        if (profile.keyRefreshEnabled !== true || !profile.gateway)
+            return;
+        const port = profile.fallbackPort ?? DEFAULT_LOOPBACK_PORT;
+        // Patience before the bounce: a 1.5s probe blip on a busy-but-alive daemon
+        // must not trigger a reinstall (greptile P1 on #1389). A quarantined daemon
+        // fails every probe instantly (connection refused), so healing stays prompt;
+        // a wedged one fails them all slowly and still heals this tick.
+        const probe = deps.probe ?? probeHealth;
+        const probeGapMs = deps.probeGapMs ?? RECONCILE_PROBE_GAP_MS;
+        for (let attempt = 0; attempt < RECONCILE_PROBE_ATTEMPTS; attempt++) {
+            const timeoutMs = attempt === 0 ? undefined : RECONCILE_RETRY_PROBE_TIMEOUT_MS;
+            if ((await probe(port, timeoutMs)) !== null)
+                return;
+            if (attempt < RECONCILE_PROBE_ATTEMPTS - 1 && probeGapMs > 0)
+                await new Promise((r) => setTimeout(r, probeGapMs));
+        }
+        const svc = await (deps.install ?? installProxyService)({
+            port,
+            remoteOrigin: new URL(profile.gateway).origin,
+        });
+        // Lands in the scheduler's log file — a permanent install failure must not
+        // retry silently twice an hour forever.
+        if (!svc.ok)
+            for (const m of svc.messages)
+                console.error(m);
+    }
+    catch {
+        // Malformed profile/gateway URL or install failure — next tick retries.
+    }
+};
 /**
  * Install + health-check the loopback daemon, then return the target the tools
  * should be pointed at. On health-check success the tools point at the loopback
@@ -635,7 +860,7 @@ export const setupLoopbackProxy = async (target, port, deps = {}) => {
     const probe = deps.probe ?? probeHealth;
     const pollDelayMs = deps.pollDelayMs ?? 300;
     heading("Seamless key refresh");
-    const svc = await install();
+    const svc = await install({ port, remoteOrigin: target.origin });
     for (const m of svc.messages)
         info(`  ${m}`);
     // A freshly-installed supervisor may take a moment to bind, so poll. But
@@ -660,9 +885,13 @@ export const setupLoopbackProxy = async (target, port, deps = {}) => {
         ? // Install succeeded but the port never bound — a transient miss the
             // next run retries against the same supervisor.
             "  It will retry on the next run; check the service logs if it persists."
-        : // No supervised daemon on this platform (svc.messages said why); the
-            // scheduled ~30-min re-mint still keeps the seat's key fresh.
-            "  Your key still refreshes on a schedule — no daemon needed here."));
+        : isContainerBackend(detectRemoteDevBackend())
+            ? // Container: the OS schedule is skipped too (no service manager), so
+                // don't promise one — the helper + re-runs are what refresh here.
+                "  In a container the key refreshes via Claude Code's helper and on each `anyray-connect` run instead."
+            : // No supervised daemon on this platform (svc.messages said why); the
+                // scheduled ~30-min re-mint still keeps the seat's key fresh.
+                "  Your key still refreshes on a schedule — no daemon needed here."));
     return target;
 };
 /**
@@ -810,6 +1039,7 @@ export const run = async (argv) => {
     // it just runs the gated refresh and exits 0.
     if (argv[0] === "__anyray-refresh") {
         await refreshIfDue();
+        await reconcileProxyService();
         // Same tick keeps the binary itself current (util/selfUpdate.ts). Runs
         // AFTER the key re-mint — that's the credential-critical half — and never
         // throws, so a GitHub outage can't cost a seat its key.
@@ -826,12 +1056,14 @@ export const run = async (argv) => {
     if (argv[0] === "__anyray-fallback-proxy") {
         return runRefreshProxy();
     }
-    // Hidden entrypoint: the Cursor adapter spawns this DETACHED when Cursor was
-    // running at apply/revert time. It waits for Cursor to quit, completes the
+    // Hidden entrypoint: a quit-gated adapter spawns this DETACHED when its app
+    // was running at apply time. It waits for that app to quit, completes the
     // queued operation through the normal adapter path, and exits. Silent +
-    // best-effort (never throws, never prints).
-    if (argv[0] === "__anyray-cursor-watch") {
-        return runCursorWatch();
+    // best-effort (never throws, never prints). Takes the adapter id, so it
+    // serves Cursor's exact-row write and Claude Desktop's profile migration
+    // through one mechanism.
+    if (argv[0] === "__anyray-quit-watch") {
+        return runQuitWatch(argv.slice(1));
     }
     // Hidden credential-helper protocol for Claude Desktop subscription mode.
     // Dispatch before durable-runtime relaunch and all human-facing logging:
@@ -928,6 +1160,7 @@ export const run = async (argv) => {
                 gateway: parsed.gateway,
                 json: parsed.json,
                 verify: parsed.verify,
+                noVerify: parsed.noVerify,
                 repair: parsed.repair,
                 securityReview: parsed.securityReview,
             });
@@ -960,6 +1193,22 @@ const runApplyCommand = async (argv, forceWizard) => {
         fail("--revert cannot be combined with --sso or --enroll. It removes Anyray configuration; re-run with --sso <link> --yes (without --revert) to configure a new CLI.");
         return 1;
     }
+    if (args.project) {
+        // Project scope writes a machine-independent artifact: enrollment is
+        // per-machine (--sso/--enroll) and seat/BYO lanes are per-dev credentials —
+        // none of them can ride a committed file.
+        if (args.sso || args.enroll || args.subscription || args.upstream) {
+            fail("--project cannot be combined with --sso/--enroll (per-machine enrollment) or --subscription/--upstream (per-dev credential lanes). It writes an org-lane, credential-free repo config.");
+            return 1;
+        }
+        return runProjectApply({
+            gateway: args.gateway,
+            tools: args.tools,
+            revert: args.revert,
+            dryRun: args.dryRun,
+            yes: args.yes,
+        });
+    }
     if (Boolean(args.upstream) !== Boolean(args.upstreamKey)) {
         fail("--upstream and --upstream-key go together: the URL says where your personal key is valid, the key is what the gateway forwards there.");
         return 1;
@@ -1307,6 +1556,17 @@ const runApplyCommand = async (argv, forceWizard) => {
         info(`  Codex (ChatGPT):    ${seat.openai
             ? cyan("signed in → your subscription")
             : dim("not signed in → org key")}`);
+        // Seat probes are machine-scoped. On a remote box with nothing signed in,
+        // "falls back to the org key" is a silent trap: the developer's sign-ins are
+        // on their laptop, and a subscription-only deployment has no working org key
+        // for that lane to use — so every tool we configure here would 401. Say it
+        // BEFORE the adapters write, so the fix is obvious rather than archaeology.
+        if (!seat.anthropic && !seat.openai && !seat.copilot && isRemoteDevContext()) {
+            warn("  No subscription sign-ins found on this host. Sign-ins do not cross the");
+            warn("  Remote-SSH hop — your laptop's are invisible here, and these tools run");
+            warn("  HERE. Sign in on this machine (`copilot` → /login, Claude Code, Codex)");
+            warn("  and re-run, or everything below routes on the org key instead.");
+        }
     }
     const target = resolveTarget({
         origin,
@@ -1386,317 +1646,379 @@ const runApplyCommand = async (argv, forceWizard) => {
         }
         ok(`Gateway reachable (${probe.detail}).`);
     }
-    // Adapters now keep durable helper/journal files below ~/.anyray. Existing
-    // global-install users may still have the historical plain-file profile at
-    // that path, so migrate it once before any apply/revert mutation. Dry-run
-    // stays strictly read-only.
-    if (!args.dryRun) {
-        try {
-            await ensureStateDir();
-        }
-        catch {
-            fail("Could not prepare the owner-only Anyray state directory.");
-            return 1;
-        }
-    }
-    // Seamless key refresh: ON by default for subscription/passthrough Claude Code
-    // + Codex — the only tools whose traffic actually traverses the loopback. They
-    // bake a short-TTL client key as a STATIC header read once at launch, so
-    // without the daemon a long session 401s the moment the key lapses mid-flight,
-    // curable only by a re-run + a tool relaunch. The daemon's surface is
-    // deliberately tiny (fill the empty key slot, forward the bytes unchanged) —
-    // that is what lets it default on where the retired provider-direct lane could
-    // not. --no-key-refresh forces the legacy direct static-key lane. Other tools
-    // (native Cursor, the Copilot extension, ACP launchers) rebuild their own
-    // target and bypass the loopback, so they are unaffected either way — see the
-    // scope boundary in commands/refreshProxy.ts.
-    const keyRefreshSeatSelected = (adapters.some((a) => a.id === "claude-code") &&
-        effectiveSubscription(target, "anthropic")) ||
-        (adapters.some((a) => a.id === "codex") &&
-            effectiveSubscription(target, "openai"));
-    const wantKeyRefresh = !args.revert && args.noKeyRefresh !== true && keyRefreshSeatSelected;
-    // A scoped apply (`--tools x`) that doesn't itself engage the loopback must
-    // not tear down the DEFAULT-ON key-refresh lane the tools it did NOT name
-    // still depend on — the apply-side mirror of the scoped-revert credential rule
-    // below. Without this, `anyray-connect --tools cursor` after a full connect
-    // would uninstall the refresh daemon and drop Claude Code / Codex back to the
-    // 401-prone static-key lane. An explicit --no-key-refresh still wins, and a
-    // full, unscoped apply falls through to the normal want-driven teardown below.
-    const scopedApply = !args.revert && (args.tools?.length ?? 0) > 0;
-    const preserveKeyRefresh = scopedApply &&
-        args.noKeyRefresh !== true &&
-        Boolean(profile.keyRefreshEnabled);
-    // The refresh SCHEDULER is the universal trigger: a per-user launchd/systemd/
-    // Task Scheduler task that runs `__anyray-refresh` every ~30 min to re-mint
-    // the short-TTL ark_ key for EVERY configured tool. The loopback daemon above
-    // only covers
-    // CC/Codex (their traffic traverses it); Cursor/Copilot/Claude-Desktop/
-    // shell-env read a static key from their own config with no daemon or hook to
-    // renew it, so they 401 mid-session when it lapses — the exact bug this fixes.
-    // Installed for every ENROLLED seat (an env-key seat has no cert to refresh),
-    // gated by the same --no-key-refresh opt-out the daemon lane uses. It coexists
-    // with the daemon: the shared refresh-state throttle stops the two triggers
-    // double-minting, and if the daemon is ever down the scheduler's refresh
-    // degrades those seats' tools to gateway-direct with a fresh key.
-    const usingEnvironmentKey = Boolean(envClientKey && target.clientKey === envClientKey && !enrolledCert);
-    const hasRefreshableCert = !usingEnvironmentKey && Boolean(enrolledCert ?? profile.enrolledCert);
-    const wantRefreshScheduler = !args.revert && args.noKeyRefresh !== true && hasRefreshableCert;
-    let applyTarget = target;
-    const resolvedKeyRefreshEnabled = wantKeyRefresh || preserveKeyRefresh;
-    // Hold the port when the loopback is wanted now, or preserved for the tools
-    // this scoped apply didn't name; otherwise clear it so the persisted profile
-    // and the teardown below agree the daemon is gone.
-    let resolvedFallbackPort = resolvedKeyRefreshEnabled
-        ? profile.fallbackPort
-        : undefined;
-    if (wantKeyRefresh && !args.dryRun) {
-        resolvedFallbackPort = profile.fallbackPort ?? (await pickLoopbackPort());
-    }
-    // ACP agents and Claude Desktop's credential helper intentionally persist no
-    // static key: they load this owner-only profile when the app launches them.
-    // Commit the complete target + enrollment pair before any adapter or loopback
-    // service can register such a launcher. A persistence failure is fatal here,
-    // while no tool configuration has changed yet.
-    if (!args.revert && !args.dryRun) {
-        // An explicit pre-minted environment key is a complete, non-refreshable
-        // credential source (see `usingEnvironmentKey` above). Never retain a
-        // possibly unrelated enrollment cert or expiry beside it: a later helper
-        // refresh could otherwise replace the operator-supplied identity with the
-        // old certificate's identity.
-        const nextProfile = {
-            ...profile,
-            gateway: target.origin,
-            name: resolvedUser,
-            team: resolvedTeam,
-            clientKey: target.clientKey ?? profile.clientKey,
-            enrolledCert: usingEnvironmentKey
-                ? undefined
-                : (enrolledCert ?? profile.enrolledCert),
-            enrolledCertExpiry: usingEnvironmentKey
-                ? undefined
-                : (enrolledCertExpiry ?? profile.enrolledCertExpiry),
-            enrolledTokenHash: usingEnvironmentKey
-                ? undefined
-                : (enrolledTokenHash ?? profile.enrolledTokenHash),
-            ssoLink: usingEnvironmentKey
-                ? undefined
-                : ssoEnrollment
-                    ? enrolledSsoLink
-                    : enrolledCert
-                        ? undefined
-                        : profile.ssoLink,
-            clientKeyExpiresAt: usingEnvironmentKey
-                ? undefined
-                : (clientKeyExpiresAt ??
-                    (target.clientKey === profile.clientKey?.trim()
-                        ? profile.clientKeyExpiresAt
-                        : undefined)),
-            authMode: target.authMode,
-            byoUpstream: target.byoUpstream,
-            keyRefreshEnabled: resolvedKeyRefreshEnabled,
-            refreshSchedulerEnabled: wantRefreshScheduler,
-            fallbackPort: resolvedFallbackPort,
-        };
-        try {
-            await persistApplyProfile(profile, nextProfile, enrolledPrivateKeyPem, undefined, usingEnvironmentKey);
-        }
-        catch {
-            fail("Could not save the owner-only Anyray runtime profile. No tool configuration was changed.");
-            return 1;
+    // Quit-aware apply, planned BEFORE anything is written and after the preflight
+    // (no point closing an editor for a gateway that turned out to be down). The
+    // plan only contains apps that are open and that this run actually changes —
+    // see `planAppRestarts` for the "already pointed at us" filter and for what it
+    // deliberately cannot see. Revert is out of scope: the filter is apply-shaped
+    // (a revert has work precisely when the tool IS pointed at us), and the
+    // adapters' queue-on-quit path already covers a revert that finds an app open.
+    const quitPlan = args.revert
+        ? []
+        : await planAppRestarts(adapters, target.origin);
+    let closedByConnect = [];
+    /**
+     * Give back every app we took away — from ANY exit after the quit, not just
+     * the happy one. Two failure paths below return before the apply finishes,
+     * and each of them used to leave the developer's editors closed with nothing
+     * ever reopening them. Closing someone's editor is only defensible if
+     * reopening it is unconditional.
+     */
+    const reopenClosed = () => {
+        if (closedByConnect.length === 0)
+            return;
+        heading("Reopening");
+        relaunchApps(closedByConnect);
+        closedByConnect = [];
+    };
+    if (quitPlan.length > 0) {
+        const titles = quitPlan.map((candidate) => candidate.title);
+        const plural = titles.length === 1 ? "it" : "them";
+        heading("Open apps");
+        // One gate decides whether anything closes, so a path that must not act
+        // cannot drift out of step with the one that may.
+        if (!quitAppsAllowed(args, isInteractive())) {
+            // Headless-complete: report, never act. Dry-run says what it would offer.
+            const hint = args.noQuitApps === true ? "" : " (or pass --quit-apps)";
+            note(args.dryRun
+                ? `  Would offer to quit ${titles.join(", ")} — dry run, nothing was closed.`
+                : `  ${titles.join(", ")} ${titles.length === 1 ? "is" : "are"} open; restart ${plural} to pick this up${hint}.`);
         }
-        // This run minted a key (--enroll / --sso). Share that with the
-        // auto-refresher's bookkeeping: with no successful mint on record, the next
-        // detached refresh sees a credential "not rotated in hours", re-mints
-        // immediately, and rotates the key out from under the session just set up.
-        if (clientKeyExpiresAt && !usingEnvironmentKey) {
-            await recordMintSuccess({ expiresAt: clientKeyExpiresAt });
+        else {
+            // `--quit-apps` is consent already given; otherwise ask once, default NO.
+            const agreed = args.quitApps === true || (await confirm(appRestartOffer(titles)));
+            if (agreed)
+                closedByConnect = await quitAppsNow(quitPlan);
+            else
+                note(`  Leaving ${plural} open — restart when convenient.`);
         }
     }
-    if (wantKeyRefresh && !args.dryRun) {
-        applyTarget = await setupLoopbackProxy(target, resolvedFallbackPort);
-    }
-    // Drop the enrollment credential FIRST, before a single config is unpicked —
-    // see util/persist `clearEnrollment` for why a revert that leaves it behind
-    // undoes itself. Order matters: `refreshIfDue` re-reads the profile on every
-    // run, so clearing up front means a hook that fires *during* the revert finds
-    // nothing to mint and leaves our work alone. Clearing last would leave a
-    // window — config already removed, cert still live — where that hook restores
-    // the configs and we then strip the cert they now depend on, stranding the
-    // tools on a key that can never refresh.
-    //
-    // A partial revert (`--tools`) is scoped to the tools it names, so it must
-    // leave the credential alone: the tools it did NOT touch still need to
-    // refresh their key.
-    const fullRevert = args.revert && (args.tools?.length ?? 0) === 0;
-    if (fullRevert) {
-        if (args.dryRun) {
-            if (await hasEnrollment()) {
-                heading("Enrollment");
-                info("  would remove the stored gateway credential");
+    // Everything from here on runs with the developer's editors CLOSED, so
+    // the reopen has to be in a `finally`. Guarding only the explicit early
+    // returns was not enough: any throw in between — a filesystem error, an
+    // adapter probe, the loopback setup — would unwind past it and leave
+    // them shut. Closing someone's editor is only defensible if reopening
+    // it happens on every path out.
+    try {
+        // Adapters now keep durable helper/journal files below ~/.anyray. Existing
+        // global-install users may still have the historical plain-file profile at
+        // that path, so migrate it once before any apply/revert mutation. Dry-run
+        // stays strictly read-only.
+        if (!args.dryRun) {
+            try {
+                await ensureStateDir();
+            }
+            catch {
+                fail("Could not prepare the owner-only Anyray state directory.");
+                return 1;
             }
         }
-        else {
+        // Seamless key refresh: ON by default for subscription/passthrough Claude Code
+        // + Codex — the only tools whose traffic actually traverses the loopback. They
+        // bake a short-TTL client key as a STATIC header read once at launch, so
+        // without the daemon a long session 401s the moment the key lapses mid-flight,
+        // curable only by a re-run + a tool relaunch. The daemon's surface is
+        // deliberately tiny (fill the empty key slot, forward the bytes unchanged) —
+        // that is what lets it default on where the retired provider-direct lane could
+        // not. --no-key-refresh forces the legacy direct static-key lane. Other tools
+        // (native Cursor, the Copilot extension, ACP launchers) rebuild their own
+        // target and bypass the loopback, so they are unaffected either way — see the
+        // scope boundary in commands/refreshProxy.ts.
+        const keyRefreshSeatSelected = (adapters.some((a) => a.id === "claude-code") &&
+            effectiveSubscription(target, "anthropic")) ||
+            (adapters.some((a) => a.id === "codex") &&
+                effectiveSubscription(target, "openai"));
+        const wantKeyRefresh = !args.revert && args.noKeyRefresh !== true && keyRefreshSeatSelected;
+        // A scoped apply (`--tools x`) that doesn't itself engage the loopback must
+        // not tear down the DEFAULT-ON key-refresh lane the tools it did NOT name
+        // still depend on — the apply-side mirror of the scoped-revert credential rule
+        // below. Without this, `anyray-connect --tools cursor` after a full connect
+        // would uninstall the refresh daemon and drop Claude Code / Codex back to the
+        // 401-prone static-key lane. An explicit --no-key-refresh still wins, and a
+        // full, unscoped apply falls through to the normal want-driven teardown below.
+        const scopedApply = !args.revert && (args.tools?.length ?? 0) > 0;
+        const preserveKeyRefresh = scopedApply &&
+            args.noKeyRefresh !== true &&
+            Boolean(profile.keyRefreshEnabled);
+        // The refresh SCHEDULER is the universal trigger: a per-user launchd/systemd/
+        // Task Scheduler task that runs `__anyray-refresh` every ~30 min to re-mint
+        // the short-TTL ark_ key for EVERY configured tool. The loopback daemon above
+        // only covers
+        // CC/Codex (their traffic traverses it); Cursor/Copilot/Claude-Desktop/
+        // shell-env read a static key from their own config with no daemon or hook to
+        // renew it, so they 401 mid-session when it lapses — the exact bug this fixes.
+        // Installed for every ENROLLED seat (an env-key seat has no cert to refresh),
+        // gated by the same --no-key-refresh opt-out the daemon lane uses. It coexists
+        // with the daemon: the shared refresh-state throttle stops the two triggers
+        // double-minting, and if the daemon is ever down the scheduler's refresh
+        // degrades those seats' tools to gateway-direct with a fresh key.
+        const usingEnvironmentKey = Boolean(envClientKey && target.clientKey === envClientKey && !enrolledCert);
+        const hasRefreshableCert = !usingEnvironmentKey && Boolean(enrolledCert ?? profile.enrolledCert);
+        const wantRefreshScheduler = !args.revert && args.noKeyRefresh !== true && hasRefreshableCert;
+        let applyTarget = target;
+        const resolvedKeyRefreshEnabled = wantKeyRefresh || preserveKeyRefresh;
+        // Hold the port when the loopback is wanted now, or preserved for the tools
+        // this scoped apply didn't name; otherwise clear it so the persisted profile
+        // and the teardown below agree the daemon is gone.
+        let resolvedFallbackPort = resolvedKeyRefreshEnabled
+            ? profile.fallbackPort
+            : undefined;
+        if (wantKeyRefresh && !args.dryRun) {
+            resolvedFallbackPort = profile.fallbackPort ?? (await pickLoopbackPort());
+        }
+        // ACP agents and Claude Desktop's credential helper intentionally persist no
+        // static key: they load this owner-only profile when the app launches them.
+        // Commit the complete target + enrollment pair before any adapter or loopback
+        // service can register such a launcher. A persistence failure is fatal here,
+        // while no tool configuration has changed yet.
+        if (!args.revert && !args.dryRun) {
+            // An explicit pre-minted environment key is a complete, non-refreshable
+            // credential source (see `usingEnvironmentKey` above). Never retain a
+            // possibly unrelated enrollment cert or expiry beside it: a later helper
+            // refresh could otherwise replace the operator-supplied identity with the
+            // old certificate's identity.
+            const nextProfile = {
+                ...profile,
+                gateway: target.origin,
+                name: resolvedUser,
+                team: resolvedTeam,
+                clientKey: target.clientKey ?? profile.clientKey,
+                enrolledCert: usingEnvironmentKey
+                    ? undefined
+                    : (enrolledCert ?? profile.enrolledCert),
+                enrolledCertExpiry: usingEnvironmentKey
+                    ? undefined
+                    : (enrolledCertExpiry ?? profile.enrolledCertExpiry),
+                enrolledTokenHash: usingEnvironmentKey
+                    ? undefined
+                    : (enrolledTokenHash ?? profile.enrolledTokenHash),
+                ssoLink: usingEnvironmentKey
+                    ? undefined
+                    : ssoEnrollment
+                        ? enrolledSsoLink
+                        : enrolledCert
+                            ? undefined
+                            : profile.ssoLink,
+                clientKeyExpiresAt: usingEnvironmentKey
+                    ? undefined
+                    : (clientKeyExpiresAt ??
+                        (target.clientKey === profile.clientKey?.trim()
+                            ? profile.clientKeyExpiresAt
+                            : undefined)),
+                authMode: target.authMode,
+                byoUpstream: target.byoUpstream,
+                keyRefreshEnabled: resolvedKeyRefreshEnabled,
+                refreshSchedulerEnabled: wantRefreshScheduler,
+                fallbackPort: resolvedFallbackPort,
+            };
             try {
-                if (await clearEnrollment()) {
-                    heading("Enrollment");
-                    ok("  Removed the stored gateway credential.");
-                    note("  Reconnect any time with `npx anyray-connect@latest --sso`.");
-                }
+                await persistApplyProfile(profile, nextProfile, enrolledPrivateKeyPem, undefined, usingEnvironmentKey);
             }
-            catch (error) {
-                // Local disk failure — say so plainly and keep going: the tool configs
-                // below still come out, and a half-reverted install is worth more than
-                // a stack trace. Never echo the error value (it can quote a path).
-                heading("Enrollment");
-                warn("  Could not remove the stored gateway credential.");
-                warn(`  Delete ${stateDir()} by hand, or the key-refresh hook may restore your tool config.`);
-                void error;
+            catch {
+                fail("Could not save the owner-only Anyray runtime profile. No tool configuration was changed.");
+                return 1;
+            }
+            // This run minted a key (--enroll / --sso). Share that with the
+            // auto-refresher's bookkeeping: with no successful mint on record, the next
+            // detached refresh sees a credential "not rotated in hours", re-mints
+            // immediately, and rotates the key out from under the session just set up.
+            if (clientKeyExpiresAt && !usingEnvironmentKey) {
+                await recordMintSuccess({ expiresAt: clientKeyExpiresAt });
             }
         }
-    }
-    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.");
-    }
-    // A named `--tools` list (the wizard writes its checklist here too) is the
-    // developer choosing these adapters by hand; the default sweep names none.
-    const { changes, manual, results } = await runApply(adapters, applyTarget, opts, args.revert, new Set(args.tools ?? []));
-    // Keep the managed-tool record in step: apply records landed tools, revert
-    // removes them, a full revert clears the record. Drift repair (`doctor
-    // --repair`, the detached refresh) only ever re-applies recorded ids, so
-    // this is what makes an intentional revert stick (#1031).
-    if (!args.dryRun) {
-        await recordManagedTools(results, args.revert, fullRevert).catch(() => undefined);
-    }
-    // Tear down the loopback daemon whenever it isn't wanted but a previous run
-    // left it installed — covers an explicit --revert, --no-key-refresh, or a
-    // subscription→api-key switch that no longer needs the refresh lane. Runs
-    // AFTER the adapters above re-pointed tools straight at the gateway, so
-    // uninstalling the loopback service strands nothing.
-    if (!resolvedKeyRefreshEnabled &&
-        !args.dryRun &&
-        (loopbackEngaged(profile) || profile.fallbackPort)) {
-        heading("Local loopback proxy");
-        const svc = await uninstallProxyService(profile.fallbackPort);
-        for (const m of svc.messages)
-            info(`  ${m}`);
-        // Re-read: on a --revert `clearEnrollment` already stripped the credential
-        // from disk, so spreading the pre-run `profile` snapshot would write it
-        // straight back. loadProfile() reflects what is actually persisted now.
-        await saveProfile({
-            ...(await loadProfile()),
-            keyRefreshEnabled: false,
-            fallbackPort: undefined,
-        });
-        ok("  Removed the local loopback proxy.");
-    }
-    // Reconcile the universal refresh scheduler: (re)install it for an enrolled
-    // seat, or tear down one a prior run left when the seat no longer wants it (a
-    // full revert dropped the enrollment, or --no-key-refresh opted out). A SCOPED
-    // revert (`--tools x --revert`) leaves it — the tools it did not name still
-    // depend on the refresh. Independent of the daemon teardown above: a
-    // Cursor-only seat has the scheduler but never had a daemon.
-    await reconcileRefreshScheduler({
-        want: wantRefreshScheduler,
-        announcePrimary: !wantKeyRefresh,
-        scopedRevert: Boolean(args.revert) && !fullRevert,
-        dryRun: Boolean(args.dryRun),
-        wasEnabled: Boolean(profile.refreshSchedulerEnabled),
-    });
-    heading("Summary");
-    if (args.dryRun) {
-        note("Dry run complete — re-run without --dry-run to apply.");
-    }
-    else if (args.revert) {
-        ok(`Reverted (${changes} file(s) touched).`);
-        // Editors read our hooks at startup and keep them in memory, so one that was
-        // already open goes on running them until it restarts. Say so — otherwise
-        // the leftover hook lines read as a revert that missed something.
-        note("Restart any editor or agent that was running — it loaded our hooks at startup.");
-        // The same "gone from disk, still live in memory" trap, but for the shell
-        // exports — and this one doesn't just look wrong, it BREAKS the dev's tools
-        // (see tools/shellEnv `staleShellExports`). We can prove it: the vars are in
-        // our own env. Say it loudly and hand over the exact command.
-        const priorTargets = [
-            target,
-            ...(profile.fallbackPort
-                ? [withLocalProxy(target, profile.fallbackPort)]
-                : []),
-        ];
-        const stale = staleShellExportsForTargets(priorTargets);
-        if (stale.length > 0) {
-            heading("This terminal still points at the gateway");
-            warn(`  Still exported here: ${stale.join(", ")}`);
-            warn("  Removing the block from your shell profile cannot reach a shell");
-            warn("  that already ran it. Until these are gone, your tools keep");
-            warn("  reaching the gateway and now fail with 401.");
-            info("\n  Fix this terminal:");
-            info(dim(`    unset ${stale.join(" ")}`));
-            info("\n  Every other open terminal needs the same — or just open a new one.");
-            info("  VS Code injects a copy it captured when IT launched, so its");
-            info("  terminals stay stale even if you open a new one: quit the app");
-            info("  entirely (Cmd+Q). Reloading the window keeps the old copy.");
+        if (wantKeyRefresh && !args.dryRun) {
+            applyTarget = await setupLoopbackProxy(target, resolvedFallbackPort);
         }
-    }
-    else {
-        ok(`Done (${changes} file(s) written).`);
-        // Tools whose config we can't script (Claude desktop, JetBrains, Windsurf)
-        // are the easiest thing to overlook — the loop printed their steps, but a
-        // dev skimming for the green "Done" can miss that no file was actually
-        // written for them. Re-surface them loudly, and on an interactive run make
-        // the dev explicitly acknowledge before we move on. Scripted runs
-        // (--yes / non-TTY) just get the reminder — never a hanging prompt.
-        if (manual.length > 0) {
-            heading("Action required — manual steps");
-            for (const line of manualStepsNotice(manual))
-                warn(line);
-            if (isInteractive() && !args.yes) {
-                const acknowledged = await confirm("Have you applied the manual settings shown above?");
-                if (acknowledged) {
-                    ok("Acknowledged.");
+        // Drop the enrollment credential FIRST, before a single config is unpicked —
+        // see util/persist `clearEnrollment` for why a revert that leaves it behind
+        // undoes itself. Order matters: `refreshIfDue` re-reads the profile on every
+        // run, so clearing up front means a hook that fires *during* the revert finds
+        // nothing to mint and leaves our work alone. Clearing last would leave a
+        // window — config already removed, cert still live — where that hook restores
+        // the configs and we then strip the cert they now depend on, stranding the
+        // tools on a key that can never refresh.
+        //
+        // A partial revert (`--tools`) is scoped to the tools it names, so it must
+        // leave the credential alone: the tools it did NOT touch still need to
+        // refresh their key.
+        const fullRevert = args.revert && (args.tools?.length ?? 0) === 0;
+        if (fullRevert) {
+            if (args.dryRun) {
+                if (await hasEnrollment()) {
+                    heading("Enrollment");
+                    info("  would remove the stored gateway credential");
                 }
-                else {
-                    warn("Apply them before using the tool, or it will keep sending traffic straight to the provider (unattributed).");
+            }
+            else {
+                try {
+                    if (await clearEnrollment()) {
+                        heading("Enrollment");
+                        ok("  Removed the stored gateway credential.");
+                        note("  Reconnect any time with `npx anyray-connect@latest --sso`.");
+                    }
+                }
+                catch (error) {
+                    // Local disk failure — say so plainly and keep going: the tool configs
+                    // below still come out, and a half-reverted install is worth more than
+                    // a stack trace. Never echo the error value (it can quote a path).
+                    heading("Enrollment");
+                    warn("  Could not remove the stored gateway credential.");
+                    warn(`  Delete ${stateDir()} by hand, or the key-refresh hook may restore your tool config.`);
+                    void error;
                 }
             }
         }
-        // Smoke-test the connection so a routing/sign-in problem surfaces NOW with a
-        // concrete fix, not as a cryptic 4xx on the dev's first real request.
-        if (args.skipVerify) {
-            note("\nSkipped the connection smoke test (--skip-verify).");
+        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.");
         }
-        else {
-            // MUST probe `target` (the remote gateway), NOT `applyTarget` (the local
-            // key-refresh daemon the tools were pointed at). The verify classifiers
-            // sniff response bodies, and a daemon-synthesized 502 ("gateway
-            // unreachable") would confuse them into reporting a routing fault the
-            // gateway itself never returned. The daemon hop is health-checked
-            // separately at install time (and by `doctor`).
-            await runVerify(target, adapters.map((a) => a.id));
+        // A named `--tools` list (the wizard writes its checklist here too) is the
+        // developer choosing these adapters by hand; the default sweep names none.
+        const { changes, manual, results } = await runApply(adapters, applyTarget, opts, args.revert, new Set(args.tools ?? []));
+        // Keep the managed-tool record in step: apply records landed tools, revert
+        // removes them, a full revert clears the record. Drift repair (`doctor
+        // --repair`, the detached refresh) only ever re-applies recorded ids, so
+        // this is what makes an intentional revert stick (#1031).
+        if (!args.dryRun) {
+            await recordManagedTools(results, args.revert, fullRevert).catch(() => undefined);
+        }
+        // Tear down the loopback daemon whenever it isn't wanted but a previous run
+        // left it installed — covers an explicit --revert, --no-key-refresh, or a
+        // subscription→api-key switch that no longer needs the refresh lane. Runs
+        // AFTER the adapters above re-pointed tools straight at the gateway, so
+        // uninstalling the loopback service strands nothing.
+        if (!resolvedKeyRefreshEnabled &&
+            !args.dryRun &&
+            (loopbackEngaged(profile) || profile.fallbackPort)) {
+            heading("Local loopback proxy");
+            const svc = await uninstallProxyService(profile.fallbackPort);
+            for (const m of svc.messages)
+                info(`  ${m}`);
+            // Re-read: on a --revert `clearEnrollment` already stripped the credential
+            // from disk, so spreading the pre-run `profile` snapshot would write it
+            // straight back. loadProfile() reflects what is actually persisted now.
+            await saveProfile({
+                ...(await loadProfile()),
+                keyRefreshEnabled: false,
+                fallbackPort: undefined,
+            });
+            ok("  Removed the local loopback proxy.");
+        }
+        // Reconcile the universal refresh scheduler: (re)install it for an enrolled
+        // seat, or tear down one a prior run left when the seat no longer wants it (a
+        // full revert dropped the enrollment, or --no-key-refresh opted out). A SCOPED
+        // revert (`--tools x --revert`) leaves it — the tools it did not name still
+        // depend on the refresh. Independent of the daemon teardown above: a
+        // Cursor-only seat has the scheduler but never had a daemon.
+        await reconcileRefreshScheduler({
+            want: wantRefreshScheduler,
+            announcePrimary: !wantKeyRefresh,
+            scopedRevert: Boolean(args.revert) && !fullRevert,
+            dryRun: Boolean(args.dryRun),
+            wasEnabled: Boolean(profile.refreshSchedulerEnabled),
+        });
+        // Reopen here on the happy path so it reads in the right order, before the
+        // summary. `reopenClosed` clears its list, so the `finally` below is a
+        // no-op once this has run — it exists for the paths that never reach here.
+        reopenClosed();
+        heading("Summary");
+        if (args.dryRun) {
+            note("Dry run complete — re-run without --dry-run to apply.");
         }
-        info("\nRe-test by hand any time:");
-        const nativeCursorOnly = target.authMode !== "placeholder" &&
-            adapters.length === 1 &&
-            adapters[0]?.id === "cursor";
-        if (nativeCursorOnly) {
-            info(dim(`  curl -sS ${target.origin}/connect/savings \\\n` +
-                `    -H "x-anyray-api-key: $(anyray-connect print-key)"`));
-            info(dim("  Validate Opus itself inside Cursor: keep the Team login, select a native Claude Opus model, and run an Agent prompt."));
+        else if (args.revert) {
+            ok(`Reverted (${changes} file(s) touched).`);
+            // Editors read our hooks at startup and keep them in memory, so one that was
+            // already open goes on running them until it restarts. Say so — otherwise
+            // the leftover hook lines read as a revert that missed something.
+            note("Restart any editor or agent that was running — it loaded our hooks at startup.");
+            // The same "gone from disk, still live in memory" trap, but for the shell
+            // exports — and this one doesn't just look wrong, it BREAKS the dev's tools
+            // (see tools/shellEnv `staleShellExports`). We can prove it: the vars are in
+            // our own env. Say it loudly and hand over the exact command.
+            const priorTargets = [
+                target,
+                ...(profile.fallbackPort
+                    ? [withLocalProxy(target, profile.fallbackPort)]
+                    : []),
+            ];
+            const stale = staleShellExportsForTargets(priorTargets);
+            if (stale.length > 0) {
+                heading("This terminal still points at the gateway");
+                warn(`  Still exported here: ${stale.join(", ")}`);
+                warn("  Removing the block from your shell profile cannot reach a shell");
+                warn("  that already ran it. Until these are gone, your tools keep");
+                warn("  reaching the gateway and now fail with 401.");
+                info("\n  Fix this terminal:");
+                info(dim(`    unset ${stale.join(" ")}`));
+                info("\n  Every other open terminal needs the same — or just open a new one.");
+                info("  VS Code injects a copy it captured when IT launched, so its");
+                info("  terminals stay stale even if you open a new one: quit the app");
+                info("  entirely (Cmd+Q). Reloading the window keeps the old copy.");
+            }
         }
         else {
-            // A minimal chat completion is the one request every API-routed gateway
-            // serves. `anyray-default` lets gateway policy choose model/provider.
-            info(dim(
-            // Never echo a personal key — point at the tool config it landed in.
-            `  curl -sS ${target.openaiBaseUrl}/chat/completions \\\n` +
-                `    -H "Content-Type: application/json" \\\n` +
-                `    -H "Authorization: Bearer ${target.clientKey
-                    ? `<your personal key (${maskKey(target.clientKey)}) — see your tool config>`
-                    : "<enrollment required>"}" \\\n` +
-                `    -d '{"model":"anyray-default","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'`));
+            ok(`Done (${changes} file(s) written).`);
+            // Tools whose config we can't script (Claude desktop, JetBrains, Windsurf)
+            // are the easiest thing to overlook — the loop printed their steps, but a
+            // dev skimming for the green "Done" can miss that no file was actually
+            // written for them. Re-surface them loudly, and on an interactive run make
+            // the dev explicitly acknowledge before we move on. Scripted runs
+            // (--yes / non-TTY) just get the reminder — never a hanging prompt.
+            if (manual.length > 0) {
+                heading("Action required — manual steps");
+                for (const line of manualStepsNotice(manual))
+                    warn(line);
+                if (isInteractive() && !args.yes) {
+                    const acknowledged = await confirm("Have you applied the manual settings shown above?");
+                    if (acknowledged) {
+                        ok("Acknowledged.");
+                    }
+                    else {
+                        warn("Apply them before using the tool, or it will keep sending traffic straight to the provider (unattributed).");
+                    }
+                }
+            }
+            // Smoke-test the connection so a routing/sign-in problem surfaces NOW with a
+            // concrete fix, not as a cryptic 4xx on the dev's first real request.
+            if (args.skipVerify) {
+                note("\nSkipped the connection smoke test (--skip-verify).");
+            }
+            else {
+                // MUST probe `target` (the remote gateway), NOT `applyTarget` (the local
+                // key-refresh daemon the tools were pointed at). The verify classifiers
+                // sniff response bodies, and a daemon-synthesized 502 ("gateway
+                // unreachable") would confuse them into reporting a routing fault the
+                // gateway itself never returned. The daemon hop is health-checked
+                // separately at install time (and by `doctor`).
+                await runVerify(target, adapters.map((a) => a.id));
+            }
+            info("\nRe-test by hand any time:");
+            const nativeCursorOnly = target.authMode !== "placeholder" &&
+                adapters.length === 1 &&
+                adapters[0]?.id === "cursor";
+            if (nativeCursorOnly) {
+                info(dim(`  curl -sS ${target.origin}/connect/savings \\\n` +
+                    `    -H "x-anyray-api-key: $(anyray-connect print-key)"`));
+                info(dim("  Validate Opus itself inside Cursor: keep the Team login, select a native Claude Opus model, and run an Agent prompt."));
+            }
+            else {
+                // A minimal chat completion is the one request every API-routed gateway
+                // serves. `anyray-default` lets gateway policy choose model/provider.
+                info(dim(
+                // Never echo a personal key — point at the tool config it landed in.
+                `  curl -sS ${target.openaiBaseUrl}/chat/completions \\\n` +
+                    `    -H "Content-Type: application/json" \\\n` +
+                    `    -H "Authorization: Bearer ${target.clientKey
+                        ? `<your personal key (${maskKey(target.clientKey)}) — see your tool config>`
+                        : "<enrollment required>"}" \\\n` +
+                    `    -d '{"model":"anyray-default","messages":[{"role":"user","content":"ping"}],"max_tokens":16}'`));
+            }
+            info(dim("  Revert: npx anyray-connect --revert"));
         }
-        info(dim("  Revert: npx anyray-connect --revert"));
+        return 0;
+    }
+    finally {
+        reopenClosed();
     }
-    return 0;
 };
 //# sourceMappingURL=cli.js.map