ai-remote 0.4.16 → 0.4.17

package/README.md

@@ -216,21 +216,89 @@ npx ai-remote exec "uname -a"
 npx ai-remote shell                                # Ctrl-] to leave
 ```
 
+### Modifier keys between a Mac and a PC
+
+A Mac's shortcut modifier is Command; Windows and Linux use Control. Send the
+physical key through unchanged and Command-C on a Windows desktop opens the
+Start menu and types a C, because Command is physically the same key as the
+Windows logo key.
+
+Microsoft's own Mac client sends it through unchanged and documents the
+consequence: *"The Command key on the Mac keyboard equals the Windows key. To
+perform actions that use the Command button on the Mac, you will need to use the
+control button in Windows (for example Copy = Ctrl+C)."* That is consistent, and
+it is also the thing people complain about most, because it asks the fingers to
+learn a second shortcut modifier for one application.
+
+So by default, when one end is a Mac and the other is not, **Control and Command
+swap**:
+
+| pressed on the Mac | arrives on the Windows/Linux desktop |
+| --- | --- |
+| Command | Control — `Command-C` copies |
+| Control | the Windows key — `Control-D` shows the desktop |
+| Option | Alt, unchanged |
+
+and the mirror when a PC keyboard drives a Mac desktop (the VNC case):
+
+| pressed on the PC | arrives on the Mac |
+| --- | --- |
+| Control | Command — `Control-C` copies |
+| Windows key | Control |
+| Alt | Option, unchanged |
+
+A swap rather than a redirect, deliberately: it is a bijection, so the Windows
+key is still reachable and nothing becomes impossible to press. Redirecting
+Command to Control and leaving Control alone would give a Mac two Controls and
+no Windows key at all.
+
+```bash
+npx ai-remote open 192.168.1.50 -u owner                   # adapt, the default
+npx ai-remote open 192.168.1.50 -u owner --keys literal     # Microsoft's behaviour
+```
+
+The far end is worked out rather than assumed: RDP is Windows, and for VNC only
+macOS Screen Sharing offers Apple's Diffie-Hellman security type, which is
+already what decides how far a scroll notch goes. Ends that agree -- Mac to Mac,
+PC to PC, Linux to Windows -- are left alone entirely, and `status` reports what
+the mapping is doing under `keys`.
+
+**Only the window's live keyboard goes through this.** `key` and `do` name the
+key they want *on the host*, so they are never remapped -- `key MetaLeft` opens
+the Start menu on Windows whatever keyboard is in front of you, and
+`key ControlLeft+KeyC` means Control-C there. Ctrl+Alt+Del is likewise a
+sequence the session synthesizes from real Windows codes, not three keys somebody
+pressed, so the swap does not turn it into Windows+Alt+Del.
+
 ### The clipboard
 
-Off by default, and turned on either from the **clipboard button in the window's
-toolbar** or from a command line:
+**On by default.** Text copied on this machine reaches the remote clipboard and
+text copied there reaches this one. The **clipboard button in the window's
+toolbar** is the switch, and so is the command line:
 
 ```bash
-npx ai-remote clipboard on                    # both directions, until turned off
 npx ai-remote clipboard                       # what it is doing now
-npx ai-remote open 192.168.1.50 -u owner --clipboard
+npx ai-remote clipboard off                   # stop it for this session
+npx ai-remote open 192.168.1.50 -u owner --no-clipboard
 ```
 
-While it is on, text copied on this machine reaches the remote clipboard and text
-copied there reaches this one. Only a desktop carries a clipboard -- RDP
-negotiates a `cliprdr` channel and VNC has cut-text in the protocol -- so a
-terminal-only session has none and the toolbar button does not appear.
+Only a desktop carries a clipboard -- RDP negotiates a `cliprdr` channel and VNC
+has cut-text in the protocol -- so a terminal-only session has none, the toolbar
+button does not appear, and nothing is started.
+
+Two things follow from it being a default rather than a choice, and both are
+worth knowing:
+
+- **Everything you copy locally is sent** while a session is open. That is the
+  point, and it is also the reason `open` prints one line saying so. If you are
+  about to copy something the remote machine should not have, `clipboard off`
+  first.
+- **It polls, so it costs something.** No platform gives Node a
+  clipboard-change event, so the local side is read twice a second for as long
+  as the session is open. Measured on an M4 that is 5.7 ms per read, about 1% of
+  one core per session. The rate stays at twice a second rather than being
+  slowed to save it, because the failure it prevents -- pasting what was on the
+  clipboard *before* the thing you just copied -- is worse than the cost.
 
 **The bridge is the session's, not the page's.** The obvious place to put it
 would be the viewer, using the browser's `navigator.clipboard` -- but a browser
@@ -355,7 +423,9 @@ where a decrypted key belongs, and it is offered from there.
 - `-s, --security MODE`: `auto` | `nla` | `tls` | `rdp` (default: `auto`).
 - `-W, --width N` / `-H, --height N`: Desktop resolution (default: 1280x800).
 - `--idle MINUTES`: Close an unused session (default: 0, never).
-- `--clipboard`: Share this machine's clipboard with the desktop, both ways.
+- `--no-clipboard`: Do not share this machine's clipboard. Shared by default.
+- `--keys MODE`: `adapt` (default) swaps Control and Command when one end is a
+  Mac and the other is not; `literal` sends every key through as itself.
 - `--headless` / `--no-view`: Run headless without opening the viewer window.
 - `--no-reuse`: A second session beside one that is already open.
 - `--save`: Keep the password for next time, once it has worked.

package/SKILL.md

@@ -114,6 +114,29 @@ screenshot full size and click the coordinates you read off it.
 image tokens and a 800px one is a fraction of that, usually with no loss of
 anything you needed to see.
 
+## Modifier keys between a Mac and a PC
+
+When one end is a Mac and the other is not, **Control and Command swap** so the
+shortcut key the fingers know keeps working:
+
+| pressed on a Mac | arrives on Windows/Linux |
+| --- | --- |
+| Command | Control — so Command-C copies |
+| Control | the Windows key |
+| Option | Alt, unchanged |
+
+and the mirror when a PC keyboard drives a Mac desktop: Control arrives as
+Command, the Windows key as Control, Alt as Option.
+
+`open --keys literal` turns it off and sends every key through as itself, which
+is what Microsoft's own Mac client does — there, Command *is* the Windows key and
+Windows shortcuts want Control.
+
+**This applies only to the window's live keyboard.** `key` and `do` name the key
+they want *on the host*, so they are never remapped: `key MetaLeft` opens the
+Start menu on Windows whatever the local keyboard is, and `key ControlLeft+KeyC`
+means Control-C there.
+
 ## Keys
 
 Key codes are DOM-style physical codes: `MetaLeft`, `Enter`, `Escape`, `Tab`,
@@ -175,23 +198,24 @@ when the second command should only run if the first worked.
 
 ## The clipboard
 
-Off by default. The **clipboard button in the window's toolbar** turns it on, or
-from a command line:
+**On by default**, both ways: text copied on this machine reaches the remote
+clipboard and text copied there reaches this one, so a password, a path or a
+stack trace moves without being typed.
 
 ```bash
-npx ai-remote clipboard on          # both directions, until turned off
 npx ai-remote clipboard             # what it is doing now
-npx ai-remote open HOST -u USER --clipboard    # on from the start
+npx ai-remote clipboard off         # stop it for this session
+npx ai-remote open HOST -u USER --no-clipboard    # never start it
 ```
 
-While it is on, text copied on this machine reaches the remote clipboard and
-text copied there reaches this one — so a password, a path or a stack trace
-moves without being typed. Only a desktop has a clipboard: RDP negotiates one
-and VNC has it in the protocol, while an `--ssh` session has none and the button
-does not appear.
+The toolbar's clipboard button is the same switch. Only a desktop has a
+clipboard — RDP negotiates one and VNC has it in the protocol — so an `--ssh`
+session has none and the button does not appear.
 
-Turn it off before copying anything on this machine that the remote end should
-not see. Off is a real off — nothing is read and nothing is written.
+**Tell the user it is on** if they are about to copy something on their own
+machine that the remote end should not see: while sharing is on, everything
+copied locally is sent. `clipboard off` is a real off — nothing is read and
+nothing is written.
 
 ## Copying files
 
@@ -417,6 +441,7 @@ npx ai-remote do "key MetaLeft; wait 800; type notepad; shot s.png"
 npx ai-remote exec "command" [--reconnect]
 npx ai-remote reconnect                                           # a new login: fresh PATH
 npx ai-remote clipboard [on|off]                                  # share text both ways
+                              # open --keys adapt|literal   modifier mapping
 npx ai-remote cp [-r] SRC DST                                     # ':path' is on the session
 npx ai-remote view [--watch-only] [--close]
 npx ai-remote status | list | close [--all]

package/dist/{cli-chunk-7UHHVT7Q.mjs → cli-chunk-DGHEB4P5.mjs}

@@ -1,8 +1,9 @@
 import {
   ROOT,
+  VERSION,
   isTitlebarDragPoint,
   logicalDisplaySize
-} from "./cli-chunk-K2DYJXC5.mjs";
+} from "./cli-chunk-ZQ32C4LC.mjs";
 
 // src/cli/window.ts
 import { spawn } from "node:child_process";
@@ -208,7 +209,8 @@ var ICON_SVG = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><def
 // src/cli/bundle.ts
 var APP_NAME = "ai-remote";
 var windowsDir = () => join(ROOT, "window");
-var bundleDir = () => join(windowsDir(), `v${ICON_VERSION}`, `${APP_NAME}.app`);
+var bundleName = () => `v${VERSION}-${ICON_VERSION}`;
+var bundleDir = () => join(windowsDir(), bundleName(), `${APP_NAME}.app`);
 var PLIST = `<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
@@ -220,8 +222,8 @@ var PLIST = `<?xml version="1.0" encoding="UTF-8"?>
   <key>CFBundleIconFile</key><string>${APP_NAME}</string>
   <key>CFBundlePackageType</key><string>APPL</string>
   <key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
-  <key>CFBundleShortVersionString</key><string>1.0</string>
-  <key>CFBundleVersion</key><string>${ICON_VERSION}</string>
+  <key>CFBundleShortVersionString</key><string>${VERSION}</string>
+  <key>CFBundleVersion</key><string>${VERSION}</string>
   <key>NSHighResolutionCapable</key><true/>
   <key>LSApplicationCategoryType</key><string>public.app-category.utilities</string>
 </dict>
@@ -248,7 +250,7 @@ function build(app, executable) {
   writeFileSync(join(contents, "Resources", `${APP_NAME}.icns`), iconIcns());
   symlinkSync(process.execPath, executable);
   for (const old of readdirSync(windowsDir())) {
-    if (old !== `v${ICON_VERSION}`) rmSync(join(windowsDir(), old), { recursive: true, force: true });
+    if (old !== bundleName()) rmSync(join(windowsDir(), old), { recursive: true, force: true });
   }
 }
 

package/dist/{cli-chunk-K2DYJXC5.mjs → cli-chunk-ZQ32C4LC.mjs}

@@ -1,3 +1,6 @@
+// src/cli/generated/version.ts
+var VERSION = "0.4.17";
+
 // src/cli/viewer-layout.ts
 var TERMINAL_COLUMNS = 80;
 var TERMINAL_CELL_WIDTH = 7.25;
@@ -48,6 +51,7 @@ var logPath = (name) => join(RUN_DIR, `${name}.log`);
 var currentPath = () => join(ROOT, "current");
 
 export {
+  VERSION,
   SIDE_PANEL_WIDTH,
   isTitlebarDragPoint,
   logicalDisplaySize,

package/dist/{cli-daemon-4VU67MLE.mjs → cli-daemon-4YPQAC5X.mjs}

@@ -7,13 +7,13 @@ import {
   downscale,
   encodePng,
   openWindow
-} from "./cli-chunk-7UHHVT7Q.mjs";
+} from "./cli-chunk-DGHEB4P5.mjs";
 import {
   SIDE_PANEL_WIDTH,
   ensureRunDir,
   metaPath,
   socketPath
-} from "./cli-chunk-K2DYJXC5.mjs";
+} from "./cli-chunk-ZQ32C4LC.mjs";
 import {
   Shell,
   bareUsername
@@ -7861,7 +7861,8 @@ async function startViewer(session, port, {
   watchOnly = false,
   title,
   host,
-  clipboard
+  clipboard,
+  mapKey = (code) => code
 } = {}) {
   const token = randomBytes2(16).toString("hex");
   const peers = /* @__PURE__ */ new Set();
@@ -8006,7 +8007,7 @@ async function startViewer(session, port, {
           shellFor.get(peer)?.resize(size.columns, size.rows);
           return;
         }
-        if (session) applyInput(session, message);
+        if (session) applyInput(session, message, mapKey);
       } catch (error) {
         console.warn("[viewer] dropped an unreadable message", error);
       }
@@ -8121,7 +8122,7 @@ async function startViewer(session, port, {
     }
   };
 }
-function applyInput(session, message) {
+function applyInput(session, message, mapKey) {
   switch (message.type) {
     case "move":
       session.movePointer(message.x, message.y);
@@ -8133,7 +8134,7 @@ function applyInput(session, message) {
       session.scroll(message.x, message.y, message.dx ?? 0, message.dy ?? 0);
       break;
     case "key":
-      session.sendKeyCode(message.code, Boolean(message.pressed));
+      session.sendKeyCode(mapKey(String(message.code)), Boolean(message.pressed));
       break;
     case "text":
       session.typeText(String(message.text ?? ""));
@@ -8325,6 +8326,43 @@ var ClipboardBridge = class {
   }
 };
 
+// src/cli/keys.ts
+function platformOf(nodePlatform) {
+  if (nodePlatform === "darwin") return "macos";
+  if (nodePlatform === "win32") return "windows";
+  return "other";
+}
+var SWAP = {
+  MetaLeft: "ControlLeft",
+  MetaRight: "ControlRight",
+  ControlLeft: "MetaLeft",
+  ControlRight: "MetaRight"
+};
+function needsSwap(local, remote) {
+  if (remote === "none" || local === "none") return false;
+  return local === "macos" !== (remote === "macos");
+}
+function keyMapper(options) {
+  if ((options.style ?? "adapt") === "literal" || !needsSwap(options.local, options.remote)) {
+    return (code) => code;
+  }
+  return (code) => SWAP[code] ?? code;
+}
+function describeKeys(options) {
+  const style = options.style ?? "adapt";
+  const { local, remote } = options;
+  if (remote === "none") {
+    return "No desktop, so no keyboard to map: a terminal session types into a shell.";
+  }
+  if (!needsSwap(local, remote)) {
+    return "Keyboard sent through as it is: both ends use the same shortcut modifier.";
+  }
+  if (style === "literal") {
+    return local === "macos" ? "Keyboard sent through unchanged: Command is the Windows key, so shortcuts want Control (Copy is Control-C). `--keys adapt` swaps them." : "Keyboard sent through unchanged: Control is Control, and the Windows key is Command. `--keys adapt` swaps them.";
+  }
+  return local === "macos" ? "Mac keyboard on a non-Mac desktop: Command acts as Control (so Command-C copies) and Control acts as the Windows key. `--keys literal` sends them through as they are." : "Non-Mac keyboard on a Mac desktop: Control acts as Command (so Control-C copies) and the Windows key acts as Control. `--keys literal` sends them through as they are.";
+}
+
 // src/cli/daemon.ts
 async function runDaemon(options) {
   ensureRunDir();
@@ -8337,6 +8375,17 @@ async function runDaemon(options) {
     log: (message) => console.log(message)
   });
   let unwatchClipboard = null;
+  function remotePlatform() {
+    if (protocol === "rdp") return "windows";
+    if (protocol === "vnc") return session?.client?.appleServer ? "macos" : "other";
+    return "none";
+  }
+  const keyStyle = options.keys === "literal" ? "literal" : "adapt";
+  const mapKey = (code) => keyMapper({
+    local: platformOf(process.platform),
+    remote: remotePlatform(),
+    style: keyStyle
+  })(code);
   function openDesktop(kind, password = options.password, port = desktopPort) {
     if (kind === "rdp") return new RdpSession(options);
     if (kind === "vnc") {
@@ -8445,6 +8494,7 @@ async function runDaemon(options) {
       sidePanel,
       watchOnly,
       host: options.host,
+      mapKey,
       clipboard: {
         state: () => clipboard.state(),
         // The switch belongs to the session, so a viewer that moves it tells
@@ -8556,6 +8606,18 @@ async function runDaemon(options) {
           viewers: viewer?.viewers ?? 0,
           shell: shell ? "open" : shellStarting ? "opening" : "closed",
           clipboard: await clipboard.state(),
+          keys: {
+            style: keyStyle,
+            local: platformOf(process.platform),
+            remote: remotePlatform(),
+            /** True only when a key is actually being rewritten. */
+            swapped: keyStyle === "adapt" && needsSwap(platformOf(process.platform), remotePlatform()),
+            describe: describeKeys({
+              local: platformOf(process.platform),
+              remote: remotePlatform(),
+              style: keyStyle
+            })
+          },
           watchOnly: options.watchOnly,
           sshUser: options.sshUsername || bareUsername(options.username),
           sshPort: options.sshPort,
@@ -8635,6 +8697,16 @@ async function runDaemon(options) {
   await new Promise((resolve) => server.listen(path, resolve));
   writeMeta();
   if (session) watchDesktop(session);
+  if (session) console.log(`[keys] ${describeKeys({
+    local: platformOf(process.platform),
+    remote: remotePlatform(),
+    style: keyStyle
+  })}`);
+  if (session && options.clipboard !== false) {
+    await clipboard.set(true).catch((error) => {
+      console.log(`[clipboard] not shared (${error instanceof Error ? error.message : String(error)})`);
+    });
+  }
   const idleTimer = options.idleMs > 0 ? setInterval(() => {
     if (Date.now() - lastUsed > options.idleMs) shutdown("idle");
   }, 3e4) : null;

package/dist/{cli-window-LN32ONC4.mjs → cli-window-H5VHVL4I.mjs}

@@ -4,8 +4,8 @@ import {
   openWindow,
   readCurrentDisplaySize,
   runWindow
-} from "./cli-chunk-7UHHVT7Q.mjs";
-import "./cli-chunk-K2DYJXC5.mjs";
+} from "./cli-chunk-DGHEB4P5.mjs";
+import "./cli-chunk-ZQ32C4LC.mjs";
 export {
   detectCurrentDisplaySize,
   nativeWindowAvailable,

package/dist/cli.mjs

@@ -5,6 +5,7 @@ import {
 import {
   RUN_DIR,
   SIDE_PANEL_WIDTH,
+  VERSION,
   currentPath,
   ensureRunDir,
   fullscreenRdpSize,
@@ -12,7 +13,7 @@ import {
   metaPath,
   sessionName,
   socketPath
-} from "./cli-chunk-K2DYJXC5.mjs";
+} from "./cli-chunk-ZQ32C4LC.mjs";
 
 // src/cli/cli.ts
 import { basename, resolve as resolvePath } from "node:path";
@@ -184,6 +185,7 @@ The rest drive that session, and take no host:
   ${NAME} forget [<host[:port]>]   throw one away; --all throws all
   ${NAME} close                    close it; --all closes every session
   ${NAME} probe [<host[:port]>]    is anything listening?
+  ${NAME} --version                which version this is
 
 Copying files, like scp but with the session standing in for the host:
   ${NAME} cp ./setup.exe :C:/Users/owner/Desktop/      to the session in hand
@@ -219,7 +221,11 @@ Options for open
       --fullscreen       fill the display; RDP uses its current resolution
       --side-panel       open the SSH terminal docked on the right
       --audio            play the remote computer's sound in the window (RDP)
-      --clipboard        share this machine's clipboard with the desktop
+      --no-clipboard     do not share this machine's clipboard (shared by default)
+      --keys MODE        adapt | literal  (default: adapt)
+                         adapt swaps Control and Command when one end is a Mac,
+                         so Command-C copies on Windows and Control-C copies on
+                         a Mac; literal sends every key through as itself
       --view-port N      port for the window           (default: 7373)
       --idle MINUTES     close an unused session       (default: 0, never)
       --headless         no window (same as --no-view)
@@ -281,7 +287,8 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "ssh-port",
   "settle",
   "vnc-port",
-  "port"
+  "port",
+  "keys"
 ]);
 function parse(argv) {
   const flags = {};
@@ -432,7 +439,7 @@ async function startSession(args, name, host, port, secret) {
   const explicitHeight = flag(args, "H", "height");
   let fullscreenSize = null;
   if (mode === "rdp" && has(args, "fullscreen") && (!explicitWidth || !explicitHeight)) {
-    const { detectCurrentDisplaySize } = await import("./cli-window-LN32ONC4.mjs");
+    const { detectCurrentDisplaySize } = await import("./cli-window-H5VHVL4I.mjs");
     const display = await detectCurrentDisplaySize();
     if (display) fullscreenSize = fullscreenRdpSize(display, has(args, "side-panel"));
   }
@@ -468,12 +475,15 @@ async function startSession(args, name, host, port, secret) {
     // Zero unless asked for: a session stays open until it is closed. An agent
     // that pauses to think is not an agent that has finished.
     "--idle",
-    flag(args, "idle") ?? "0"
+    flag(args, "idle") ?? "0",
+    "--keys",
+    flag(args, "keys") ?? "adapt"
   ];
   if (mode !== "rdp") daemonArgs.push(`--${mode}`);
   for (const identity of args.identities) daemonArgs.push("-i", identity);
   if (has(args, "no-view", "headless")) daemonArgs.push("--no-view");
   if (has(args, "no-open")) daemonArgs.push("--no-open");
+  if (has(args, "no-clipboard")) daemonArgs.push("--no-clipboard");
   if (has(args, "watch-only", "observe")) daemonArgs.push("--watch-only");
   if (has(args, "tab")) daemonArgs.push("--tab");
   if (has(args, "fullscreen")) daemonArgs.push("--fullscreen");
@@ -541,13 +551,18 @@ function sessionFailure(name, died, secret, mode) {
 }
 async function main() {
   const args = parse(process.argv.slice(2));
+  if (has(args, "v", "version") || args.command === "version") {
+    process.stdout.write(`${NAME} ${VERSION}
+`);
+    return;
+  }
   if (!args.command || has(args, "h", "help")) {
     process.stdout.write(USAGE);
     return;
   }
   const json = has(args, "json");
   if (args.command === "__display-size") {
-    const { readCurrentDisplaySize } = await import("./cli-window-LN32ONC4.mjs");
+    const { readCurrentDisplaySize } = await import("./cli-window-H5VHVL4I.mjs");
     const size = await readCurrentDisplaySize();
     if (size) process.stdout.write(`${JSON.stringify(size)}
 `);
@@ -556,7 +571,7 @@ async function main() {
   if (args.command === "__session") {
     const mode = modeFor(args, args.rest[0]);
     const { host, port } = splitTarget(args.rest[0] ?? "", defaultPort(mode));
-    const { runDaemon } = await import("./cli-daemon-4VU67MLE.mjs");
+    const { runDaemon } = await import("./cli-daemon-4YPQAC5X.mjs");
     await runDaemon({
       name: sessionName(host, port, flag(args, "name", "session")),
       host,
@@ -582,12 +597,14 @@ async function main() {
       // RDP is the only protocol here with an audio channel, and a session with
       // no window has nowhere to play what the channel would carry.
       audio: has(args, "audio", "sound") && mode === "rdp" && !has(args, "no-view", "headless"),
-      idleMs: Math.max(0, Number(flag(args, "idle") ?? 0)) * 6e4
+      idleMs: Math.max(0, Number(flag(args, "idle") ?? 0)) * 6e4,
+      keys: flag(args, "keys") === "literal" ? "literal" : "adapt",
+      clipboard: !has(args, "no-clipboard")
     });
     return;
   }
   if (args.command === "__window") {
-    const { runWindow } = await import("./cli-window-LN32ONC4.mjs");
+    const { runWindow } = await import("./cli-window-H5VHVL4I.mjs");
     await runWindow(process.argv.slice(3));
     return;
   }
@@ -634,6 +651,10 @@ Saved, nothing open (\`${NAME} open <host>\` needs no password):
   if (args.command === "open") {
     const target = args.rest[0];
     if (!target) throw new CliError(`Name the machine to connect to: \`${NAME} open <host[:port]>\``, 12);
+    const keys = flag(args, "keys");
+    if (keys && keys !== "adapt" && keys !== "literal") {
+      throw new CliError(`--keys takes "adapt" or "literal", not "${keys}".`, 12);
+    }
     const mode = modeFor(args, target);
     const { host, port } = splitTarget(target, defaultPort(mode));
     const asked = flag(args, "session", "name");
@@ -679,12 +700,10 @@ Saved, nothing open (\`${NAME} open <host>\` needs no password):
         sidePanel: has(args, "side-panel")
       }));
     }
-    if (has(args, "clipboard")) {
-      const shared = await ask(name2, "clipboard", { on: true });
-      if (!shared?.available) {
-        process.stderr.write("The clipboard cannot be shared with this session (it needs a desktop at the far end and a clipboard tool here).\n");
-      }
-      Object.assign(status, { clipboard: shared });
+    const shared = await ask(name2, "clipboard", {});
+    Object.assign(status, { clipboard: shared });
+    if (has(args, "clipboard") && !shared?.available) {
+      process.stderr.write("The clipboard cannot be shared with this session (it needs a desktop at the far end and a clipboard tool here).\n");
     }
     setCurrent(name2);
     report(json, "open", {
@@ -703,6 +722,14 @@ Saved, nothing open (\`${NAME} open <host>\` needs no password):
     if (prompted && !saved) {
       process.stderr.write("Add --save next time to keep that password.\n");
     }
+    if (status.keys?.swapped && status.keys?.describe) {
+      process.stderr.write(`${status.keys.describe}
+`);
+    }
+    if (status.clipboard?.on) {
+      process.stderr.write(`Clipboard shared both ways (${status.clipboard.tool}). \`${NAME} clipboard off\` stops it; --no-clipboard opens without it.
+`);
+    }
     return;
   }
   if (args.command === "probe") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-remote",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "description": "RDP, VNC and SSH protocol engines that run in Node, a Worker or a browser -- plus `npx ai-remote`, a CLI that drives a machine and shows you what it is doing",
   "type": "module",
   "bin": {