feat(cli): add Remote Control for the web UI (#222)

## Related Issue

None — direct feature request.

## Problem

The web UI only reaches devices that can already talk to this machine:
localhost, or the LAN with `--host`. Off-network there is no way to pick
up a running session from a phone, and setting up a tunnel by hand is
not something most users will do.

## What changed

Remote Control: the CLI opens an outbound tunnel to a relay, and the
relay serves the local web UI to a remote device. Sessions keep running
on this machine — only the screen moves. This also gives a mobile client
a stable endpoint to talk to.

Entry points:

- `pythinker rc` (alias `remote`) — starts the server with Remote
Control on
- `pythinker web --rc` / `--remote-control` — same, on the existing
command
- `/remote-control` or `/rc` in the terminal UI — hands the current
session over

The terminal prints a QR code, the link, and the path of a PNG copy of
the QR for terminals that cannot render it inline.

**Transport.** Two WebSockets to the relay — a management channel and an
HTTP tunnel — plus one stream socket per browser WebSocket. HTTP
requests arrive base64-framed and capped at 10 MiB, are replayed against
the local server with hop-by-hop and credential headers stripped, and
HTML/JS/CSS responses get asset paths rewritten under the device prefix.
A liveness watchdog pings every 30s and reconnects after 300s of
silence, so a relay that dies without a close frame does not strand the
client.

**Auth.** No accounts. The device authenticates to the relay with the
existing persistent `server.token`. The link itself carries no
credential: the CLI adds the bearer to every request it replays against
the local server, so the token never leaves this machine — not into the
QR image on disk, not into the remote browser's URL bar.

**Guards.** Loopback bind only, `--dangerous-bypass-auth` refused, and
one instance per machine via a pid+nonce lock at
`<data-dir>/server/rc.json` — a second start reports the link the first
one is using.

Experimental and hidden from `--help` unless
`PYTHINKER_CODE_EXPERIMENTAL_REMOTE_CONTROL=1` (or
`PYTHINKER_CODE_EXPERIMENTAL_FLAG=1`).

**Relay.** No relay server is included in this change. Point Remote
Control at your own with `--relay-origin <url>` or
`PYTHINKER_CODE_REMOTE_CONTROL_RELAY`; the default is
`https://code-rc.pythinker.com`.

Supporting changes: `StartForegroundHooks` gained an `onShutdown` hook
and `onReady` became awaitable, so the tunnel closes with the server;
`supportsHyperlinks` was added next to `toTerminalHyperlink`.

## Checklist

- [x] I have read the
[CONTRIBUTING](https://github.com/PyModel/pythinker-code/blob/main/CONTRIBUTING.md)
document.
- [ ] I have linked a related issue (external PRs: the issue must have a
maintainer's `/approve`).
- [x] I have added tests that prove my feature works.
- [x] Ran `gen-changesets` skill, or this PR needs no changeset.
- [x] Ran `gen-docs` skill, or this PR needs no doc update.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* Added experimental Remote Control for accessing the local web
interface from phones or other computers.
* Start it with `pythinker rc` or `/remote-control` (also `/rc`);
connection links and QR codes appear in the terminal.
* Added configurable relay support, secure single-session handling,
token-free URLs, and improved connection reliability.
  * Remote Control requires explicit experimental feature activation.
* **Documentation**
* Added a guide covering setup, authentication, relay configuration, and
shutdown.
* **Tests**
* Added comprehensive coverage for startup, connections, QR codes,
relays, authentication, and error handling.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: elkaix

.changeset/remote-control.md

@@ -0,0 +1,5 @@
+---
+"@pymodel/pythinker-code": minor
+---
+
+Add Remote Control, which makes the local web UI reachable from a phone or another computer. Run `pythinker rc`, or use `/rc` in the terminal UI, and scan the printed QR code. Enable it with `PYTHINKER_CODE_EXPERIMENTAL_REMOTE_CONTROL=1`.

apps/pythinker-code/dist-web/.web-bundle-manifest.json

@@ -1,4 +1,4 @@
 {
-  "sourceHash": "c05b9ce73324f5a446966d9f931dc804f0f1e73e78daf14e1479d86e58669c1a",
+  "sourceHash": "d84e17f04092f5fb9afa9f4d323b614d3945ec8e33abbbc92f5793ad2c30959e",
   "sourceFileCount": 404
 }

apps/pythinker-code/package.json

@@ -94,17 +94,21 @@
     "@pymodel/pythinker-telemetry": "workspace:^",
     "@pymodel/vis-server": "workspace:^",
     "@pymodel/vis-web": "workspace:*",
+    "@types/qrcode": "^1.5.6",
     "@types/semver": "^7.7.0",
+    "@types/ws": "^8.18.0",
     "@types/yazl": "^2.4.6",
     "chalk": "^5.4.1",
     "cli-highlight": "^2.1.11",
     "commander": "^13.1.0",
     "jimp": "^1.6.1",
     "pathe": "^2.0.3",
     "postject": "1.0.0-alpha.6",
+    "qrcode": "^1.5.4",
     "semver": "^7.7.4",
     "smol-toml": "^1.6.1",
     "tsx": "^4.23.5",
+    "ws": "^8.21.3",
     "yazl": "^3.3.1",
     "zod": "^4.3.6"
   },

apps/pythinker-code/src/cli/sub/web/index.ts

@@ -15,6 +15,7 @@ import type { Command } from 'commander';
 import { registerDeprecatedServerCommand } from './deprecated-server';
 import { registerRotateTokenCommand } from './rotate-token';
 import { buildWebCommand } from './run';
+import { isRemoteControlEnabled } from './remote-control';
 
 export function registerWebCommand(program: Command): void {
   const web = buildWebCommand(
@@ -23,5 +24,14 @@ export function registerWebCommand(program: Command): void {
       .description('Run the local Pythinker server and open the web UI.'),
   );
   registerRotateTokenCommand(web);
+  buildWebCommand(
+    program
+      .command('rc', { hidden: !isRemoteControlEnabled() })
+      .alias('remote')
+      .description(
+        'Run the local Pythinker server and open the web UI through Remote Control (experimental).',
+      ),
+    { forceRemoteControl: true },
+  );
   registerDeprecatedServerCommand(program);
 }

apps/pythinker-code/src/cli/sub/web/remote-control-lock.ts

@@ -0,0 +1,194 @@
+import { randomBytes } from 'node:crypto';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { mkdir, open, readFile, unlink } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+export interface RemoteControlLockInfo {
+  readonly pid: number;
+  readonly nonce: string;
+  readonly localOrigin: string;
+  readonly deviceId: string;
+  readonly url: string;
+  readonly startedAt: number;
+}
+
+interface RemoteControlLockDisk {
+  readonly pid: number;
+  readonly nonce: string;
+  readonly local_origin: string;
+  readonly device_id: string;
+  readonly url: string;
+  readonly started_at: number;
+}
+
+export class RemoteControlAlreadyRunningError extends Error {
+  readonly holder: RemoteControlLockInfo;
+
+  constructor(holder: RemoteControlLockInfo) {
+    super(formatRemoteControlAlreadyRunning(holder));
+    this.name = 'RemoteControlAlreadyRunningError';
+    this.holder = holder;
+  }
+}
+
+export function formatRemoteControlAlreadyRunning(holder: RemoteControlLockInfo): string {
+  return [
+    `Remote Control is already running on this machine (pid ${holder.pid}, ${holder.localOrigin}, since ${new Date(holder.startedAt).toLocaleString()}).`,
+    `Use the existing link: ${holder.url}`,
+    'To start a new one here, stop the other `pythinker web --remote-control` process first.',
+  ].join('\n');
+}
+
+export function remoteControlLockPath(homeDir: string): string {
+  return join(homeDir, 'server', 'rc.json');
+}
+
+export interface RemoteControlLock {
+  release(): Promise<void>;
+}
+
+const MAX_ACQUIRE_ATTEMPTS = 3;
+const ACQUIRE_RETRY_DELAY_MS = 25;
+
+export async function acquireRemoteControlLock(
+  homeDir: string,
+  details: { localOrigin: string; deviceId: string; url: string },
+): Promise<RemoteControlLock> {
+  const lockPath = remoteControlLockPath(homeDir);
+  // The lock sits beside `server.token`; keep the same owner-only permissions.
+  await mkdir(dirname(lockPath), { recursive: true, mode: 0o700 });
+  const info: RemoteControlLockInfo = {
+    pid: process.pid,
+    nonce: randomBytes(8).toString('hex'),
+    localOrigin: details.localOrigin,
+    deviceId: details.deviceId,
+    url: details.url,
+    startedAt: Date.now(),
+  };
+  for (let attempt = 0; ; attempt += 1) {
+    try {
+      const handle = await open(lockPath, 'wx', 0o600);
+      try {
+        await handle.writeFile(encodeLock(info));
+      } finally {
+        await handle.close();
+      }
+      return { release: () => releaseRemoteControlLock(lockPath, info.nonce) };
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') {
+        throw error;
+      }
+      // Read the holder even on the last attempt: a second process can recreate
+      // the lock between our unlink and our open, and a raw EEXIST tells the
+      // user nothing about who holds it or how to stop them.
+      const holder = await readRemoteControlLock(lockPath);
+      if (holder !== undefined && pidAlive(holder.pid)) {
+        throw new RemoteControlAlreadyRunningError(holder);
+      }
+      // `open(…, 'wx')` publishes an empty file before its JSON is written, so
+      // an unreadable lock may simply be a rival mid-write. Deleting it there
+      // would let both processes believe they hold the lock. Give the writer a
+      // moment and re-read; only sweep it once it is still unreadable at the
+      // end, which is the genuinely corrupt case.
+      if (holder === undefined && attempt < MAX_ACQUIRE_ATTEMPTS) {
+        await sleep(ACQUIRE_RETRY_DELAY_MS);
+        continue;
+      }
+      if (attempt >= MAX_ACQUIRE_ATTEMPTS) {
+        throw new Error(
+          `Unable to acquire the Remote Control lock at ${lockPath}. Another process keeps recreating it.`, { cause: error },
+        );
+      }
+      await removeFile(lockPath);
+    }
+  }
+}
+
+export async function inspectRemoteControlLock(
+  homeDir: string,
+): Promise<RemoteControlLockInfo | undefined> {
+  const lockPath = remoteControlLockPath(homeDir);
+  const info = await readRemoteControlLock(lockPath);
+  if (info === undefined) return undefined;
+  if (!pidAlive(info.pid)) {
+    await removeFile(lockPath);
+    return undefined;
+  }
+  return info;
+}
+
+async function releaseRemoteControlLock(lockPath: string, nonce: string): Promise<void> {
+  const info = await readRemoteControlLock(lockPath);
+  if (info === undefined || info.nonce !== nonce) return;
+  await removeFile(lockPath);
+}
+
+async function readRemoteControlLock(lockPath: string): Promise<RemoteControlLockInfo | undefined> {
+  let raw: string;
+  try {
+    raw = await readFile(lockPath, 'utf8');
+  } catch {
+    return undefined;
+  }
+  return decodeLock(raw);
+}
+
+function encodeLock(info: RemoteControlLockInfo): string {
+  const disk: RemoteControlLockDisk = {
+    pid: info.pid,
+    nonce: info.nonce,
+    local_origin: info.localOrigin,
+    device_id: info.deviceId,
+    url: info.url,
+    started_at: info.startedAt,
+  };
+  return JSON.stringify(disk);
+}
+
+function decodeLock(raw: string): RemoteControlLockInfo | undefined {
+  try {
+    const parsed = JSON.parse(raw) as Partial<RemoteControlLockDisk>;
+    if (
+      typeof parsed.pid === 'number' &&
+      // `process.kill(0, 0)` signals our own process group and reports "alive",
+      // so a corrupt `"pid": 0` would pin the lock forever.
+      Number.isInteger(parsed.pid) &&
+      parsed.pid > 0 &&
+      typeof parsed.nonce === 'string' &&
+      typeof parsed.local_origin === 'string' &&
+      typeof parsed.device_id === 'string' &&
+      typeof parsed.url === 'string' &&
+      typeof parsed.started_at === 'number'
+    ) {
+      return {
+        pid: parsed.pid,
+        nonce: parsed.nonce,
+        localOrigin: parsed.local_origin,
+        deviceId: parsed.device_id,
+        url: parsed.url,
+        startedAt: parsed.started_at,
+      };
+    }
+    return undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function removeFile(lockPath: string): Promise<void> {
+  try {
+    await unlink(lockPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+}
+
+function pidAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false;
+    return true;
+  }
+}