diggylab 0.1.41 → 0.1.43

package/README.md

@@ -7,7 +7,6 @@ headless Chromium — the Electron app is not involved.
 ## Requirements
 
 - Node.js 20+
-- Linux packages: `xvfb` and `x11vnc` — run `diggylab install-display` (Debian/Ubuntu) or install them yourself. The Docker image below bundles them.
 - Chromium for Playwright: downloaded automatically during `npm install`; rerun `diggylab install-browser` if that download failed.
 
 ## Install
@@ -37,7 +36,7 @@ npm publish apps/desktop-agent/dist-npm --access public
 ```
 
 `cli:pack` bundles the workspace code into a single `cli.js`, so the published package only depends
-on `playwright`, `qrcode-terminal`, and `ws`. The packed manifest copies the version from
+on `playwright` and `ws`. The packed manifest copies the version from
 `apps/desktop-agent/package.json`; use the override below when the app release has not caught up yet.
 
 ### Publishing ahead of an app release
@@ -57,61 +56,44 @@ npm publish apps/desktop-agent/dist-npm --access public
 
 | Command | What it does |
 | --- | --- |
-| `pair --code <code> [--name <device name>] [--api <origin>]` | Pairs the server as a device. Create the code on `/settings/desktop-agent` in the web app. |
-| `login` | Renders the Facebook login page on a virtual screen and prints a DiggyLab link + QR code. Open it on any phone or laptop — no ports, no tunnel — and the session is stored encrypted on the server. |
+| `pair [--code <code>] [--name <device name>]` | Pairs the server as a device. Create the code on `/settings/desktop-agent` in the web app; leave `--code` out and the command asks for it. |
+| `login` | Opens Facebook's real login page in a browser window when the machine has a screen. On a server without one it asks for `facebook.com` cookies pasted from your own browser, and the session is stored encrypted. |
+| `logout` | Removes the stored Facebook session from this server (the device pairing stays). |
+| `rename [--name <new name>]` | Renames the device shown in the web app; leave `--name` out and the command asks for it. |
 | `run` | Connects the WebSocket worker, receives assigned scans, scans headlessly, uploads results. |
 | `status` | Shows the config directory, API origin, paired device, and Facebook session state. |
 | `install-browser` | Downloads the Chromium build Playwright needs (~150 MB). It also runs during `npm install`, so you only need it if that download failed. |
-| `install-display` | On Debian/Ubuntu, installs `xvfb` and `x11vnc` for the login screen. |
+| `install-service` | On a Linux server with systemd, writes the unit for `run`, enables it, and starts it now and on every boot. |
+| `uninstall-service` | Stops that service and removes the unit. |
 | `unpair` | Removes device credentials, the Facebook session, and pending scans. |
 
-Useful options: `--api <origin>` (default `https://api.diggylab.com`), `--web-url <origin>` (only for a
-self-hosted web app, or `DIGGYLAB_WEB_URL`), `--display <number>` to avoid an Xvfb collision.
+Useful options: `--api <origin>` (default `https://api.diggylab.com`), `--cookies <file>` to import
+cookies directly.
 
-## How `login` works on a server
-
-A server has no screen, so the agent starts `Xvfb` (virtual screen) and `x11vnc` (shares it), then
-carries that screen to the customer through the API connection it already uses for scans:
+`pair` and `login` finish by printing what is still missing, so you do not need to run `status`
+between steps:
 
 ```
-Xvfb → Chromium opens Facebook's real login page → encrypted over the API → link + QR → phone logs in
+Paired:   "DiggyLab" (device-1)
+Facebook: missing
+Next: run `diggylab login` — on a server without a screen it asks you to paste cookies.
 ```
 
-Nothing has to be opened on the server: no port, no tunnel, no firewall change. The link points at
-the web app (`https://diggylab.com/agent-login/<session>#<key>`), and everything is torn down when the
-login finishes or times out (10 minutes).
-
-### The screen is encrypted end to end
-
-The part of the link after `#` is the decryption key, and browsers never send a fragment to a server —
-so the relay passes bytes it cannot read. DiggyLab stores nothing: no frames, no keystrokes, no
-session. The Facebook cookies stay on the customer's server, sealed with `~/.diggylab/key`.
-
-The link itself is the only way in: it is single use, expires with the login window, and the session
-is created per `login` run.
-
-### When the screen does not appear
-
-`login` checks the virtual screen before printing the link: it reads x11vnc's greeting, so a broken
-screen stops the command with the reason instead of leaving the customer with a blank page.
+## How `login` works
 
-Each process writes a log to `~/.diggylab/logs/` (`xvfb.log`, `x11vnc.log`). The tail is printed when
-the screen fails or a process dies during the login, and the files stay there for later inspection.
+Two paths, depending on the machine:
 
-Manual checks while `login` is running:
-
-```bash
-pgrep -a Xvfb; pgrep -a x11vnc                                        # both must be running
-ss -ltnp | grep :5999                                                 # x11vnc listens on loopback
-timeout 2 bash -c 'exec 3<>/dev/tcp/127.0.0.1/5999 && head -c 12 <&3' # expect: RFB 003.008
-```
+| Machine | What `login` does |
+| --- | --- |
+| Desktop, or Linux with a display (`$DISPLAY` set) | Opens Chromium on that display with Facebook's real login page; you log in normally. |
+| Server without a screen | Prints a short prompt and asks you to paste `facebook.com` cookies exported from your own browser. |
 
-If the browser says the link expired, run `diggylab login` again — each run mints a new session.
+Both paths save the session encrypted with `~/.diggylab/key`, and `diggylab run` then uses it for scans.
 
 ### Logging in with cookies from your own browser
 
-If you would rather not share a screen, log into Facebook in your own browser and import those
-cookies instead — no Xvfb, no link, no port:
+On a machine without a screen this is the only path, and you can also pick it on a desktop with
+`diggylab login cookies`:
 
 1. Get the `facebook.com` cookies, in whichever way is easiest:
    - **DevTools → Network** (fastest): open facebook.com, click any request, copy the whole
@@ -119,12 +101,15 @@ cookies instead — no Xvfb, no link, no port:
    - **DevTools → Application → Cookies → `https://www.facebook.com`**: select the table and copy the
      rows.
    - **Cookie-Editor** (Chrome, Edge, Firefox): *Export → JSON*.
-2. On the server:
+2. On the server, run the friendly form and paste when asked (Enter finishes the paste):
 
 ```bash
-diggylab login --cookies cookies.json     # or: diggylab login --cookies -   and paste, then Ctrl-D
+diggylab login cookies
 ```
 
+The equivalents: `diggylab login --cookies 'name=value; ...'` for a quoted one-liner, or
+`diggylab login --cookies cookies.json` for a saved file.
+
 Only `name` and `value` are required; the agent fills in the rest (`.facebook.com`, `/`, session
 expiry). Every `facebook.com` cookie is kept, and at least `c_user` plus `xs` must be present — those
 two carry the session, and `datr` is worth keeping too.
@@ -139,6 +124,16 @@ instead of failing during a scan.
 Note: Facebook sometimes asks for a security check when a session moves to a server's IP. If that
 happens the command says so — approve the login from your phone and import again.
 
+## Troubleshooting
+
+- `socket closed: 4009` right after `session: ONLINE` means **two workers use the same device** — for
+  example the systemd service plus a manual `diggylab run`. The worker that connected last keeps the
+  device and the older one stops with a message. Check `pgrep -af "diggylab run"` and
+  `systemctl status diggylab --no-pager`, then keep only one.
+- `socket closed: 1006` with reconnects is a dropped connection; the worker keeps retrying with
+  backoff. If it never settles, check that the server can reach the API origin.
+- `Facebook: missing` after a login means the session did not survive; run `diggylab login` again.
+
 ## Security notes
 
 - `~/.diggylab/key` (mode `600`) encrypts device credentials, the Facebook session, and the
@@ -149,28 +144,46 @@ happens the command says so — approve the login from your phone and import aga
 
 ## Run as a service
 
+On a Linux server with systemd, let the CLI write the unit for you:
+
+```bash
+diggylab install-service      # writes /etc/systemd/system/diggylab.service, enables + starts it
+diggylab uninstall-service    # stops it and removes the unit
+journalctl -u diggylab -f     # follow the worker log
+```
+
+The unit keeps the same state directory and API origin you are using, restarts the worker if it
+crashes, and starts it on boot. It points at npm's `diggylab` symlink, so upgrading the package is
+enough — no need to reinstall the service. Run it as root (or with `sudo`) to write the unit.
+
+<details>
+<summary>Equivalent unit, if you prefer to write it yourself</summary>
+
 ```ini
 [Unit]
-Description=DiggyLab Desktop Agent CLI
+Description=DiggyLab Desktop Agent
 After=network-online.target
+Wants=network-online.target
 
 [Service]
-User=diggylab
-WorkingDirectory=/opt/diggylab
-ExecStart=/usr/bin/node /opt/diggylab/dist-cli/cli/cli.js run
-Restart=always
+ExecStart=/usr/local/bin/diggylab run
+Environment=DIGGYLAB_AGENT_DIR=/root/.diggylab
 Environment=DIGGYLAB_API_URL=https://api.diggylab.com
+Restart=always
+RestartSec=10
 
 [Install]
 WantedBy=multi-user.target
 ```
 
+</details>
+
 ## Docker
 
 ```bash
 docker build -f apps/desktop-agent/Dockerfile.cli -t diggylab .
-docker run -it --rm -p 6080:6080 -v diggylab:/data diggylab pair --code ABC123
-docker run -it --rm -p 6080:6080 -v diggylab:/data diggylab login
+docker run -it --rm -v diggylab:/data diggylab pair --code ABC123
+docker run -it --rm -v diggylab:/data diggylab login cookies
 docker run -d --restart unless-stopped -v diggylab:/data diggylab run
 ```
 

package/cli.js

@@ -2,10 +2,10 @@
 
 // src/cli/cli.ts
 import { randomUUID as randomUUID3 } from "node:crypto";
-import { spawn as spawn2 } from "node:child_process";
-import { existsSync as existsSync2, readdirSync, readFileSync as readFileSync2, realpathSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync, rmSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { hostname, homedir } from "node:os";
-import { dirname as dirname3, join as join4 } from "node:path";
+import { dirname as dirname3, join as join3 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // ../../packages/facebook-scanner/dist/parser.js
@@ -513,7 +513,7 @@ function withTimeout(promise, timeoutMs) {
 
 // src/cli/cli.ts
 import { chromium } from "playwright";
-import WebSocket2 from "ws";
+import WebSocket from "ws";
 
 // src/main/activity-log.ts
 import { gzip } from "node:zlib";
@@ -727,6 +727,16 @@ var DeviceCredentialManager = class {
     });
     return this.refreshPromise;
   }
+  /** Renames the device on the server and in the stored session, so `status` and the web agree. */
+  async rename(name) {
+    const access = this.access ?? await this.refresh();
+    const device = await this.http.rename(access.accessToken, name);
+    const session = { ...access.session, device };
+    await this.store.save(session);
+    this.stored = session;
+    this.access = { ...access, session };
+    return device;
+  }
   getStoredSession() {
     return this.stored;
   }
@@ -816,6 +826,15 @@ var DesktopAgentHttpClient = class {
     if (!isDeviceSummary(value)) throw new DesktopAgentClientError("DESKTOP_RESPONSE_INVALID");
     return value;
   }
+  async rename(accessToken, name) {
+    const value = await this.request("/desktop-agent-auth/me", {
+      body: JSON.stringify({ name }),
+      headers: { authorization: `Bearer ${accessToken}`, "content-type": "application/json" },
+      method: "PATCH"
+    });
+    if (!isDeviceSummary(value)) throw new DesktopAgentClientError("DESKTOP_RESPONSE_INVALID");
+    return value;
+  }
   async requestCredential(path, body) {
     const value = await this.request(path, {
       body: JSON.stringify(body),
@@ -1031,13 +1050,13 @@ var DesktopAgentSession = class {
     this.socket = socket;
     socket.on("message", (data) => this.handleMessage(socket, data, access, generation));
     socket.on("error", () => this.handleDisconnect(socket, access.session, generation));
-    socket.on("close", () => this.handleDisconnect(socket, access.session, generation));
+    socket.on("close", (code) => this.handleDisconnect(socket, access.session, generation, typeof code === "number" ? code : void 0));
   }
   handleMessage(socket, data, access, generation) {
     if (generation !== this.generation || socket !== this.socket) return;
     const envelope = parseServerEnvelope(data);
     if (!envelope || envelope.deviceId !== access.session.device.id || envelope.protocolVersion !== DESKTOP_AGENT_PROTOCOL_VERSION || Math.abs(Date.now() - Date.parse(envelope.sentAt)) > MESSAGE_FRESHNESS_MS || this.replayIds.has(envelope.messageId)) {
-      this.protocolFailure(socket, access.session, generation);
+      this.protocolFailure(socket, access.session, generation, describeEnvelopeProblem(envelope, access.session.device.id, this.replayIds));
       return;
     }
     this.rememberMessage(envelope.messageId);
@@ -1147,19 +1166,23 @@ var DesktopAgentSession = class {
       void this.start(false);
     }, delay);
   }
-  handleDisconnect(socket, stored, generation) {
+  handleDisconnect(socket, stored, generation, code) {
     if (generation !== this.generation || socket !== this.socket) return;
     this.socket = null;
     this.clearHeartbeat();
     this.clearAccessRefresh();
+    if (code === 4009) {
+      this.update(snapshotForSession("RECONNECTING", stored, "CONNECTION_REPLACED"));
+      return;
+    }
     this.scheduleReconnect(stored, generation, "NETWORK_ERROR");
   }
-  protocolFailure(socket, stored, generation) {
+  protocolFailure(socket, stored, generation, reason = "malformed message") {
     if (socket === this.socket) this.socket = null;
     socket.close();
     this.clearHeartbeat();
     this.clearAccessRefresh();
-    this.scheduleReconnect(stored, generation, "PROTOCOL_VIOLATION");
+    this.scheduleReconnect(stored, generation, `PROTOCOL_VIOLATION: ${reason}`);
   }
   scheduleReconnect(stored, generation, errorCode) {
     if (generation !== this.generation || this.reconnectTimer) return;
@@ -1248,6 +1271,15 @@ function parseServerEnvelope(data) {
     return null;
   }
 }
+function describeEnvelopeProblem(envelope, deviceId, replayIds) {
+  if (!envelope) return "unreadable message";
+  if (envelope.deviceId !== deviceId) return `wrong device ${envelope.deviceId}`;
+  if (envelope.protocolVersion !== DESKTOP_AGENT_PROTOCOL_VERSION) return `protocol version ${envelope.protocolVersion}`;
+  const offsetMs = Date.now() - Date.parse(envelope.sentAt);
+  if (Math.abs(offsetMs) > MESSAGE_FRESHNESS_MS) return `stale message (sentAt ${envelope.sentAt}, offset ${Math.round(offsetMs / 1e3)}s)`;
+  if (replayIds.has(envelope.messageId)) return `replayed message ${envelope.messageId}`;
+  return "unknown";
+}
 function emptySnapshot(state) {
   return {
     state,
@@ -2315,9 +2347,7 @@ var FLAGS = {
   "--code": { key: "code", type: "string" },
   "--config": { key: "config", type: "string" },
   "--cookies": { key: "cookies", type: "string" },
-  "--display": { key: "display", type: "number" },
-  "--name": { key: "name", type: "string" },
-  "--web-url": { key: "webUrl", type: "string" }
+  "--name": { key: "name", type: "string" }
 };
 function parseCliArgs(argv) {
   const options = {};
@@ -2495,276 +2525,25 @@ function createFileCrypto(keyPath) {
   };
 }
 
-// src/cli/login-screen-relay.ts
-import { createConnection } from "node:net";
-import WebSocket from "ws";
-
-// src/cli/relay-crypto.ts
-import { createCipheriv as createCipheriv2, createDecipheriv as createDecipheriv2, hkdfSync, randomBytes as randomBytes2 } from "node:crypto";
-var FRAME_VERSION = 1;
-var IV_BYTES2 = 12;
-var KEY_BYTES2 = 32;
-var TAG_BYTES2 = 16;
-function createRelayKey() {
-  return randomBytes2(KEY_BYTES2).toString("base64url");
-}
-function deriveRelayKeys(key, sessionId) {
-  const secret = Buffer.from(key, "base64url");
-  const salt = Buffer.from(sessionId, "utf8");
-  const derive = (info) => Buffer.from(hkdfSync("sha256", secret, salt, Buffer.from(info, "utf8"), KEY_BYTES2));
-  return { fromAgent: derive("agent-to-browser"), toAgent: derive("browser-to-agent") };
-}
-function sealFrame(key, payload) {
-  const iv = randomBytes2(IV_BYTES2);
-  const cipher = createCipheriv2("aes-256-gcm", key, iv);
-  const sealed = Buffer.concat([cipher.update(payload), cipher.final()]);
-  return Buffer.concat([Buffer.from([FRAME_VERSION]), iv, sealed, cipher.getAuthTag()]);
-}
-function openFrame(key, frame) {
-  if (frame.length < 1 + IV_BYTES2 + TAG_BYTES2 || frame[0] !== FRAME_VERSION) {
-    throw new Error("Invalid login screen frame.");
-  }
-  const decipher = createDecipheriv2("aes-256-gcm", key, frame.subarray(1, 1 + IV_BYTES2));
-  decipher.setAuthTag(frame.subarray(frame.length - TAG_BYTES2));
-  return Buffer.concat([
-    decipher.update(frame.subarray(1 + IV_BYTES2, frame.length - TAG_BYTES2)),
-    decipher.final()
-  ]);
-}
-
-// src/cli/login-screen-relay.ts
-var RELAY_PATH = "/desktop-agent/login-screen";
-var READY_TIMEOUT_MS = 1e4;
-var DEFAULT_WEB_ORIGIN = "https://diggylab.com";
-async function openLoginScreenRelay(options) {
-  const socket = new WebSocket(`${toWebSocketOrigin(options.apiOrigin)}${RELAY_PATH}`, {
-    headers: { authorization: `Bearer ${options.accessToken}` }
-  });
-  let closed = false;
-  let keys = null;
-  let vnc = null;
-  let resolveScreen = () => void 0;
-  let rejectFailure = () => void 0;
-  const failure = new Promise((_resolve, reject) => {
-    rejectFailure = reject;
-  });
-  const screenConnected = new Promise((resolve) => {
-    resolveScreen = resolve;
-  });
-  failure.catch(() => void 0);
-  const close = () => {
-    closed = true;
-    vnc?.destroy();
-    vnc = null;
-    if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) socket.close();
-  };
-  const fail = (message) => {
-    close();
-    rejectFailure(new Error(message));
-  };
-  const openScreen = () => {
-    if (closed || vnc) return;
-    const connection = createConnection({ host: "127.0.0.1", port: options.rfbPort });
-    vnc = connection;
-    connection.on("data", (chunk) => {
-      if (closed || !keys || socket.readyState !== WebSocket.OPEN) return;
-      socket.send(sealFrame(keys.fromAgent, chunk), { binary: true });
-    });
-    connection.once("error", () => {
-      if (vnc === connection) vnc = null;
-      fail("Could not reach the virtual screen.");
-    });
-    connection.once("close", () => {
-      if (vnc === connection) vnc = null;
-    });
-  };
-  socket.on("message", (data, isBinary) => {
-    if (isBinary) {
-      if (!keys || !vnc || vnc.destroyed) return;
-      try {
-        vnc.write(openFrame(keys.toAgent, Buffer.from(data)));
-      } catch {
-        fail("The login screen received a corrupted frame.");
-      }
-      return;
-    }
-    const message = parseRelayMessage(data.toString());
-    if (message?.type === "screen-connected") {
-      openScreen();
-      resolveScreen();
-    } else if (message?.type === "screen-disconnected") {
-      vnc?.destroy();
-      vnc = null;
-    }
-  });
-  socket.once("error", () => fail("Could not reach the DiggyLab relay."));
-  socket.once("close", () => {
-    if (!closed) fail("The DiggyLab relay closed the login screen.");
-  });
-  const ready = await waitForReady(socket);
-  keys = deriveRelayKeys(options.key, ready.id);
-  const webOrigin = (options.webUrl ?? ready.webUrl ?? DEFAULT_WEB_ORIGIN).replace(/\/+$/, "");
-  return {
-    close,
-    failure,
-    screenConnected,
-    url: `${webOrigin}/agent-login/${encodeURIComponent(ready.id)}#${options.key}`
-  };
-}
-function parseRelayMessage(value) {
-  try {
-    const parsed = JSON.parse(value);
-    if (parsed && typeof parsed === "object" && typeof parsed.type === "string") {
-      return parsed;
-    }
-  } catch {
-  }
-  return null;
-}
-function waitForReady(socket) {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => reject(new Error("The DiggyLab relay did not answer in time.")), READY_TIMEOUT_MS);
-    timer.unref();
-    socket.once("message", (data, isBinary) => {
-      clearTimeout(timer);
-      if (isBinary) {
-        reject(new Error("The DiggyLab relay answered with an unexpected frame."));
-        return;
-      }
-      const message = parseRelayMessage(data.toString());
-      if (message?.type !== "ready") {
-        reject(new Error("The DiggyLab relay did not accept the login screen."));
-        return;
-      }
-      resolve(message);
-    });
-    socket.once("error", () => {
-      clearTimeout(timer);
-      reject(new Error("Could not reach the DiggyLab relay."));
-    });
-    socket.once("close", () => {
-      clearTimeout(timer);
-      reject(new Error("The DiggyLab relay refused the login screen."));
-    });
-  });
-}
-function toWebSocketOrigin(origin) {
-  return origin.replace(/^http/i, "ws").replace(/\/+$/, "");
-}
-
-// src/cli/qr.ts
-import qrcode from "qrcode-terminal";
-function terminalQr(value) {
-  let output = "";
-  qrcode.generate(value, { small: true }, (rendered) => {
-    output = rendered;
-  });
-  return output;
-}
+// src/cli/systemd.ts
+var SERVICE_NAME = "diggylab";
+var SERVICE_PATH = `/etc/systemd/system/${SERVICE_NAME}.service`;
+function buildSystemdUnit(options) {
+  return `[Unit]
+Description=DiggyLab Desktop Agent
+After=network-online.target
+Wants=network-online.target
 
-// src/cli/virtual-display.ts
-import { spawn } from "node:child_process";
-import { createWriteStream, mkdirSync as mkdirSync2 } from "node:fs";
-import { createConnection as createConnection3 } from "node:net";
-import { join as join3 } from "node:path";
+[Service]
+ExecStart=${options.execStart} run
+Environment=DIGGYLAB_AGENT_DIR=${options.configDirectory}
+Environment=DIGGYLAB_API_URL=${options.apiOrigin}
+Restart=on-failure
+RestartSec=10
 
-// src/cli/vnc-probe.ts
-import { createConnection as createConnection2 } from "node:net";
-var PROBE_TIMEOUT_MS = 4e3;
-var GREETING_BYTES = 12;
-var GREETING_PATTERN = /^RFB \d{3}\.\d{3}\n$/;
-function probeRfb(host, port, timeoutMs = PROBE_TIMEOUT_MS) {
-  return new Promise((resolve) => {
-    const socket = createConnection2({ host, port });
-    const finish = (result) => {
-      clearTimeout(timer);
-      socket.destroy();
-      resolve(result);
-    };
-    const timer = setTimeout(() => finish(false), timeoutMs);
-    let received = "";
-    socket.on("data", (chunk) => {
-      received += chunk.toString("latin1");
-      if (received.length >= GREETING_BYTES) finish(GREETING_PATTERN.test(received.slice(0, GREETING_BYTES)));
-    });
-    socket.once("error", () => finish(false));
-    socket.once("close", () => finish(false));
-  });
-}
-
-// src/cli/virtual-display.ts
-var START_TIMEOUT_MS = 15e3;
-function waitForPort(host, port, timeoutMs) {
-  const deadline = Date.now() + timeoutMs;
-  return new Promise((resolve, reject) => {
-    const attempt = () => {
-      const socket = createConnection3({ host, port });
-      socket.once("connect", () => {
-        socket.destroy();
-        resolve();
-      });
-      socket.once("error", () => {
-        socket.destroy();
-        if (Date.now() >= deadline) {
-          reject(new Error(`Timed out waiting for ${host}:${port}.`));
-          return;
-        }
-        setTimeout(attempt, 250).unref();
-      });
-    };
-    attempt();
-  });
-}
-function start(name, command, args, env, deps, logDirectory) {
-  const child = deps.spawnProcess(command, args, env);
-  const log = createWriteStream(join3(logDirectory, `${name}.log`), { mode: 384 });
-  const failure = new Promise((_resolve, reject) => {
-    child.on("error", (error) => reject(error instanceof Error ? error : new Error(String(error))));
-    child.on("exit", (code) => reject(new Error(`${command} exited with code ${String(code)}.`)));
-  });
-  log.on("error", () => void 0);
-  log.write(`# ${command} ${args.join(" ")}
-`);
-  child.stdout?.pipe?.(log, { end: false });
-  child.stderr?.pipe?.(log, { end: false });
-  return { child, failure };
-}
-async function startVirtualDisplay(options, overrides = {}) {
-  const deps = {
-    probeRfb,
-    spawnProcess: spawn,
-    waitForPort,
-    ...overrides
-  };
-  const displayNumber = options.displayNumber ?? 99;
-  const display = `:${displayNumber}`;
-  const height = options.height ?? 900;
-  const rfbPort = 5900 + displayNumber;
-  mkdirSync2(options.logDirectory, { mode: 448, recursive: true });
-  const xvfb = start("xvfb", "Xvfb", [display, "-screen", "0", `${options.width ?? 1280}x${height}x24`, "-nolisten", "tcp"], process.env, deps, options.logDirectory);
-  const vnc = start("x11vnc", "x11vnc", ["-display", display, "-localhost", "-rfbport", String(rfbPort), "-forever", "-shared", "-nopw", "-quiet"], process.env, deps, options.logDirectory);
-  const failure = Promise.race([vnc.failure, xvfb.failure]);
-  failure.catch(() => void 0);
-  const stop = async () => {
-    for (const { child } of [vnc, xvfb]) {
-      child.kill("SIGTERM");
-      await new Promise((resolve) => setTimeout(resolve, 200));
-      child.kill("SIGKILL");
-    }
-  };
-  try {
-    await Promise.race([
-      deps.waitForPort("127.0.0.1", rfbPort, options.timeoutMs ?? START_TIMEOUT_MS),
-      failure
-    ]);
-    if (!await deps.probeRfb("127.0.0.1", rfbPort)) {
-      throw new Error(`The virtual screen did not answer on 127.0.0.1:${rfbPort}.`);
-    }
-  } catch (error) {
-    await stop();
-    throw error;
-  }
-  return { display, failure, logDirectory: options.logDirectory, rfbPort, stop };
+[Install]
+WantedBy=multi-user.target
+`;
 }
 
 // src/cli/cli.ts
@@ -2773,25 +2552,27 @@ var CONFIG_DIRECTORY = ".diggylab";
 var USAGE = `DiggyLab Desktop Agent CLI
 
 Usage:
-  diggylab pair --code <code> [--name <device name>] [--api <https://api.diggylab.com>]
-  diggylab login [--display <number>] [--web-url <https://diggylab.com>]
-  diggylab login cookies                  (asks you to paste facebook.com cookies)
-  diggylab login --cookies <file>        (or --cookies 'name=value; ...')
+  diggylab pair [--code <code>] [--name <device name>]   (asks for the code when you leave it out)
+  diggylab login                          (opens a browser window when the machine has a screen)
+  diggylab login cookies                  (no screen: paste facebook.com cookies when asked)
+  diggylab login --cookies <file>         (or --cookies 'name=value; ...')
+  diggylab logout
+  diggylab rename [--name <new name>]        (asks for the name when you leave it out)
   diggylab run
+  diggylab install-service                   (systemd: start "run" on boot)
+  diggylab uninstall-service
   diggylab status
   diggylab install-browser
-  diggylab install-display
   diggylab unpair
 
 Global options:
   --config <directory>   Agent state directory (default ~/.diggylab)
   --api <origin>         API origin (default $DIGGYLAB_API_URL or https://api.diggylab.com)`;
 var MISSING_BROWSER_HINT = "Chromium for Playwright is not installed yet. Run `diggylab install-browser` once.";
-var MISSING_DISPLAY_HINT = "The login screen needs Xvfb and x11vnc. Run `diggylab install-display` (Debian/Ubuntu) or use the Docker image.";
 function agentVersion() {
   let directory = fileURLToPath(new URL(".", import.meta.url));
   for (let depth = 0; depth < 4; depth += 1) {
-    const manifest = join4(directory, "package.json");
+    const manifest = join3(directory, "package.json");
     if (existsSync2(manifest)) {
       try {
         const version = JSON.parse(readFileSync2(manifest, "utf8")).version;
@@ -2808,7 +2589,7 @@ function resolvePlatform() {
   return process.platform === "linux" ? "LINUX" : "WINDOWS";
 }
 function resolveConfigDirectory(options) {
-  return options.config?.trim() || process.env.DIGGYLAB_AGENT_DIR?.trim() || join4(homedir(), CONFIG_DIRECTORY);
+  return options.config?.trim() || process.env.DIGGYLAB_AGENT_DIR?.trim() || join3(homedir(), CONFIG_DIRECTORY);
 }
 function resolveEndpoint(options) {
   const configured = (options.api ?? process.env.DIGGYLAB_API_URL)?.trim() || "https://api.diggylab.com";
@@ -2818,28 +2599,18 @@ function resolveEndpoint(options) {
 function createRuntime(options) {
   const directory = resolveConfigDirectory(options);
   const endpoint = resolveEndpoint(options);
-  const crypto2 = createFileCrypto(join4(directory, "key"));
-  const credentials = new CredentialStore(join4(directory, "credentials.json"), crypto2);
+  const crypto2 = createFileCrypto(join3(directory, "key"));
+  const credentials = new CredentialStore(join3(directory, "credentials.json"), crypto2);
   const sessions = new DeviceSessionStore(credentials);
   const facebook = new FacebookSessionStore(credentials);
-  const spool = new EncryptedScanSpool(join4(directory, "scan-spool"), crypto2);
-  const activity = new ActivityLog({ directory: join4(directory, "activity") });
+  const spool = new EncryptedScanSpool(join3(directory, "scan-spool"), crypto2);
+  const activity = new ActivityLog({ directory: join3(directory, "activity") });
   const http = new DesktopAgentHttpClient(endpoint.httpOrigin);
   const manager = new DeviceCredentialManager(sessions, http, createDeviceIdentity);
   return { activity, browserType: createBrowserLauncher(chromium), directory, endpoint, facebook, manager, sessions, spool };
 }
-function printDisplayLogs(directory, io, lines = 12) {
-  io.error(`Login screen logs: ${directory}`);
-  try {
-    for (const name of readdirSync(directory).sort()) {
-      if (!name.endsWith(".log")) continue;
-      const tail = readFileSync2(join4(directory, name), "utf8").split("\n").filter((line) => line.trim() !== "").slice(-lines);
-      if (tail.length === 0) continue;
-      io.error(`--- ${name} ---`);
-      for (const line of tail) io.error(line);
-    }
-  } catch {
-  }
+function stamp() {
+  return `[${(/* @__PURE__ */ new Date()).toTimeString().slice(0, 8)}]`;
 }
 function waitForFacebookLogin(login, timeoutMs) {
   return new Promise((resolve, reject) => {
@@ -2885,9 +2656,9 @@ function pairErrorMessage(error, origin) {
   }
 }
 async function commandPair(runtime, options, io) {
-  const code = options.code?.trim();
+  const code = options.code?.trim() || await promptForPairingCode(io);
   if (!code) {
-    io.error("Missing --code <pairing code>. Create one on the Desktop Agent page of the web app.");
+    io.error("No pairing code entered. Create one in the web app: Settings \u2192 Desktop Agent \u2192 Create pairing code.");
     return 2;
   }
   try {
@@ -2898,15 +2669,73 @@ async function commandPair(runtime, options, io) {
       platform: resolvePlatform()
     });
     io.log(`Paired as "${access.session.device.name}".`);
-    io.log("Next: run `diggylab login` to connect a Facebook account.");
+    await printReadiness(runtime, io);
     return 0;
   } catch (error) {
     io.error(pairErrorMessage(error, runtime.endpoint.httpOrigin));
     return 1;
   }
 }
+async function promptForPairingCode(io) {
+  if (process.stdin.isTTY) {
+    io.log("Create a pairing code in the web app: Settings \u2192 Desktop Agent \u2192 Create pairing code.");
+    io.log("It works once and expires after 10 minutes.");
+    io.log("Paste the code here, then press Enter.");
+  }
+  return (await readAnswer()).trim();
+}
+async function printReadiness(runtime, io) {
+  const stored = await runtime.sessions.load();
+  const facebook = await runtime.facebook.load();
+  const hasUser = Boolean(facebook?.cookies?.some((cookie) => cookie.name === "c_user" && cookie.value));
+  io.log(`Paired:   ${stored ? `"${stored.device.name}" (${stored.device.id})` : "no"}`);
+  io.log(`Facebook: ${hasUser ? "connected" : "missing"}`);
+  if (!stored) {
+    io.log("Next: create a pairing code in the web app, then run `diggylab pair`.");
+  } else if (!hasUser) {
+    io.log("Next: run `diggylab login` \u2014 on a server without a screen it asks you to paste cookies.");
+  } else {
+    io.log("Ready: start the worker with `diggylab run`.");
+  }
+}
+async function commandLogout(runtime, io) {
+  await runtime.facebook.clear();
+  io.log("Facebook session removed from this server.");
+  await printReadiness(runtime, io);
+  return 0;
+}
+async function commandRename(runtime, options, io) {
+  const stored = await runtime.manager.load();
+  if (!stored) {
+    io.error("This server is not paired yet. Run `diggylab pair` first.");
+    return 1;
+  }
+  const requested = options.name?.trim() || await promptForName(io);
+  const name = sanitizeDeviceName(requested);
+  if (!name) {
+    io.error('A device name is required, for example `diggylab rename --name "VPS H\xE0 N\u1ED9i"`.');
+    return 2;
+  }
+  try {
+    const device = await runtime.manager.rename(name);
+    io.log(`Renamed to "${device.name}".`);
+    await printReadiness(runtime, io);
+    return 0;
+  } catch (error) {
+    io.error(`Could not rename this device: ${error instanceof Error ? error.message : String(error)}`);
+    return 1;
+  }
+}
+async function promptForName(io) {
+  if (process.stdin.isTTY) io.log("Type the new device name, then press Enter.");
+  return (await readAnswer()).trim();
+}
 async function commandLogin(runtime, options, io) {
   if (options.cookies !== void 0) return importFacebookCookies(runtime, options.cookies || "-", io);
+  if (process.platform === "linux" && !process.env.DISPLAY) {
+    io.log("This server has no screen, so the login uses cookies from your browser.");
+    return importFacebookCookies(runtime, "-", io);
+  }
   const login = new FacebookLoginService({
     browserType: runtime.browserType,
     clearTimer: (timer) => clearTimeout(timer),
@@ -2924,71 +2753,21 @@ async function commandLogin(runtime, options, io) {
     io.log("Facebook is already connected.");
     return 0;
   }
-  let display = null;
-  let relay = null;
   try {
-    const needsVirtualDisplay = process.platform === "linux" && !process.env.DISPLAY;
-    if (!needsVirtualDisplay) {
-      io.log(process.env.DISPLAY ? `Opening the Facebook login page on display ${process.env.DISPLAY}.` : "Opening the Facebook login page in a browser window.");
-    } else {
-      const stored = await runtime.manager.load();
-      if (!stored) {
-        io.error("This server is not paired yet. Run `diggylab pair --code <code>` first.");
-        return 1;
-      }
-      const access = await runtime.manager.refresh();
-      const webUrl = options.webUrl ?? process.env.DIGGYLAB_WEB_URL?.trim();
-      display = await startVirtualDisplay({
-        displayNumber: options.display,
-        logDirectory: join4(runtime.directory, "logs")
-      });
-      relay = await openLoginScreenRelay({
-        accessToken: access.accessToken,
-        apiOrigin: runtime.endpoint.httpOrigin,
-        key: createRelayKey(),
-        rfbPort: display.rfbPort,
-        webUrl: webUrl || void 0
-      });
-      process.env.DISPLAY = display.display;
-      io.log(terminalQr(relay.url));
-      io.log(`Open this link on your phone, or scan the QR above:
-${relay.url}`);
-      io.log("Log into Facebook on that screen; the agent saves the session automatically.");
-      void relay.screenConnected.then(() => io.log("Login screen opened in the browser."));
-    }
-    const waiting = waitForFacebookLogin(login, LOGIN_TIMEOUT_MS + 6e4);
-    const failures = [display?.failure, relay?.failure].filter((value) => Boolean(value));
-    await (failures.length > 0 ? Promise.race([waiting, ...failures]) : waiting);
+    io.log(process.env.DISPLAY ? `Opening the Facebook login page on display ${process.env.DISPLAY}.` : "Opening the Facebook login page in a browser window.");
+    await waitForFacebookLogin(login, LOGIN_TIMEOUT_MS + 6e4);
     io.log("Facebook session saved.");
+    await printReadiness(runtime, io);
     return 0;
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
-    if (/spawn (?:Xvfb|x11vnc) ENOENT/.test(message)) {
-      io.error(MISSING_DISPLAY_HINT);
-      return 1;
-    }
-    if (/CREDENTIAL_REVOKED|not paired/i.test(message)) {
-      io.error("This server is not paired (or was unpaired). Run `diggylab pair --code <code>` again.");
-      return 1;
-    }
-    if (/NETWORK_ERROR|SERVER_UNAVAILABLE|fetch failed/i.test(message)) {
-      io.error(`Could not reach the API: ${message}`);
-      return 1;
-    }
-    if (/virtual screen|login screen|DiggyLab relay|Xvfb exited|x11vnc exited/i.test(message)) {
-      io.error(`The login screen failed: ${message}`);
-      printDisplayLogs(join4(runtime.directory, "logs"), io);
-      return 1;
-    }
     if (/Executable doesn't exist|playwright install/i.test(message)) {
       io.error(MISSING_BROWSER_HINT);
       return 1;
     }
     throw error;
   } finally {
-    relay?.close();
     await login.close();
-    await display?.stop();
   }
 }
 async function importFacebookCookies(runtime, source, io) {
@@ -3040,6 +2819,7 @@ async function importFacebookCookies(runtime, source, io) {
     return 1;
   }
   io.log("Facebook session saved.");
+  await printReadiness(runtime, io);
   return 0;
 }
 async function validateImportedSession(runtime, state) {
@@ -3065,9 +2845,12 @@ function readStdin() {
   });
 }
 function readPastedCookies(io) {
-  if (!process.stdin.isTTY) return readStdin();
   io.log("Paste the facebook.com cookies here, then press Enter.");
   io.log("In your browser: F12 \u2192 Network \u2192 click any facebook.com request \u2192 copy the whole `cookie:` value.");
+  return readAnswer({ until: (value) => value.includes("c_user") });
+}
+function readAnswer(options = {}) {
+  if (!process.stdin.isTTY) return readStdin();
   return new Promise((resolve) => {
     let value = "";
     let idle;
@@ -3079,11 +2862,11 @@ function readPastedCookies(io) {
     };
     const handleData = (chunk) => {
       value += chunk;
-      if (idle) clearTimeout(idle);
-      if (value.includes("\n") && value.includes("c_user")) {
+      if (value.includes("\n") && (!options.until || options.until(value))) {
         finish();
         return;
       }
+      if (idle) clearTimeout(idle);
       idle = setTimeout(finish, 350);
     };
     process.stdin.setEncoding("utf8");
@@ -3107,7 +2890,7 @@ async function commandInstallBrowser(io) {
   }
   io.log("Downloading Chromium for Playwright...");
   const run = (args) => new Promise((resolve, reject) => {
-    const child = spawn2(process.execPath, [cli, ...args], { stdio: "inherit" });
+    const child = spawn(process.execPath, [cli, ...args], { stdio: "inherit" });
     child.once("error", reject);
     child.once("exit", (value) => resolve(value ?? 1));
   });
@@ -3124,31 +2907,6 @@ async function commandInstallBrowser(io) {
   io.log("Chromium installed.");
   return 0;
 }
-async function commandInstallDisplay(io) {
-  if (process.platform !== "linux") {
-    io.log("The shared login screen is only needed on a Linux server; desktops open a browser window.");
-    return 0;
-  }
-  if (!existsSync2("/usr/bin/apt-get")) {
-    io.error("Automatic installation supports Debian/Ubuntu. Install xvfb and x11vnc with your package manager.");
-    return 1;
-  }
-  const sudo = typeof process.getuid === "function" && process.getuid() !== 0 ? ["sudo"] : [];
-  const run = (args) => new Promise((resolve, reject) => {
-    const child = spawn2(args[0], args.slice(1), { stdio: "inherit" });
-    child.once("error", reject);
-    child.once("exit", (value) => resolve(value ?? 1));
-  });
-  io.log("Installing xvfb and x11vnc...");
-  await run([...sudo, "apt-get", "update"]).catch(() => 1);
-  const code = await run([...sudo, "apt-get", "install", "-y", "xvfb", "x11vnc"]);
-  if (code !== 0) {
-    io.error("Installation failed. Run the same command with apt manually.");
-    return code;
-  }
-  io.log("Login screen packages installed.");
-  return 0;
-}
 async function commandRun(runtime, io) {
   const stored = await runtime.manager.load();
   if (!stored) {
@@ -3163,12 +2921,13 @@ async function commandRun(runtime, io) {
     agentVersion: agentVersion(),
     clearTimer: (timer) => clearTimeout(timer),
     createSocket: (url, accessToken) => {
-      const socket = new WebSocket2(url, {
+      const socket = new WebSocket(url, {
         headers: { authorization: `Bearer ${accessToken}` },
         maxPayload: 16 * 1024
       });
+      socket.on("error", (error) => io.log(`${stamp()} socket error: ${error.message}`));
       socket.on("close", (code, reason) => {
-        io.log(`socket closed: ${code}${reason?.length ? ` (${reason.toString()})` : ""}`);
+        io.log(`${stamp()} socket closed: ${code}${reason?.length ? ` (${reason.toString()})` : ""}`);
       });
       return socket;
     },
@@ -3212,9 +2971,18 @@ async function commandRun(runtime, io) {
     spool: runtime.spool,
     wait: abortableDelay
   });
+  let onReplaced = () => void 0;
+  const replaced = new Promise((resolve) => {
+    onReplaced = resolve;
+  });
   session.subscribe((snapshot) => {
-    io.log(`session: ${snapshot.state}`);
+    io.log(`${stamp()} session: ${snapshot.state}${snapshot.errorCode ? ` (${snapshot.errorCode})` : ""}`);
     recordActivity(`Session state changed to ${snapshot.state}.`, snapshot.state);
+    if (snapshot.errorCode === "CONNECTION_REPLACED") {
+      io.error("Another worker is already running with this device, so this one stopped.");
+      io.error("Stop the other worker (for example: systemctl stop diggylab), then start this one again.");
+      onReplaced();
+    }
   });
   scanRunner.subscribe((snapshot) => {
     io.log(`scanner: ${snapshot.state}${snapshot.jobId ? ` (job ${snapshot.jobId})` : ""}`);
@@ -3223,13 +2991,16 @@ async function commandRun(runtime, io) {
   scanRunner.start();
   await scanRunner.recover();
   await session.start();
-  io.log(`Worker running as "${stored.device.name}". Press Ctrl+C to stop.`);
+  io.log(`Worker running as "${stored.device.name}" (API ${runtime.endpoint.httpOrigin}). Press Ctrl+C to stop.`);
   const keepAlive = setInterval(() => void 0, 6e4);
   try {
-    await new Promise((resolve) => {
-      process.once("SIGINT", resolve);
-      process.once("SIGTERM", resolve);
-    });
+    await Promise.race([
+      new Promise((resolve) => {
+        process.once("SIGINT", resolve);
+        process.once("SIGTERM", resolve);
+      }),
+      replaced
+    ]);
   } finally {
     clearInterval(keepAlive);
     session.stop();
@@ -3255,6 +3026,66 @@ async function commandUnpair(runtime, io) {
   io.log("Device unpaired; local credentials, Facebook session, and pending scans were removed.");
   return 0;
 }
+function runCommand(command, args) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (value) => resolve(value ?? 1));
+  });
+}
+function resolveServiceExecStart() {
+  const candidates = [join3(dirname3(process.execPath), "diggylab"), "/usr/local/bin/diggylab", "/usr/bin/diggylab"];
+  const link = candidates.find((candidate) => existsSync2(candidate));
+  return link ?? `${process.execPath} ${fileURLToPath(import.meta.url)}`;
+}
+async function commandInstallService(runtime, io) {
+  if (process.platform !== "linux") {
+    io.error("Automatic service setup supports Linux (systemd). Use the Docker image or your platform's service manager.");
+    return 1;
+  }
+  if (!existsSync2("/usr/bin/systemctl") && !existsSync2("/bin/systemctl")) {
+    io.error("systemd is not available on this machine.");
+    return 1;
+  }
+  const unit = buildSystemdUnit({
+    apiOrigin: runtime.endpoint.httpOrigin,
+    configDirectory: runtime.directory,
+    execStart: resolveServiceExecStart()
+  });
+  try {
+    writeFileSync2(SERVICE_PATH, unit, { mode: 420 });
+  } catch {
+    io.error(`Could not write ${SERVICE_PATH}. Run this command as root (or with sudo).`);
+    return 1;
+  }
+  io.log(`Wrote ${SERVICE_PATH}.`);
+  await runCommand("systemctl", ["daemon-reload"]).catch(() => 1);
+  const code = await runCommand("systemctl", ["enable", "--now", SERVICE_NAME]);
+  if (code !== 0) {
+    io.error(`systemctl could not enable the service. Check it with: systemctl status ${SERVICE_NAME}`);
+    return code;
+  }
+  io.log(`Service ${SERVICE_NAME} is enabled: it runs now and after every reboot.`);
+  io.log(`Follow its log with: journalctl -u ${SERVICE_NAME} -f`);
+  await printReadiness(runtime, io);
+  return 0;
+}
+async function commandUninstallService(io) {
+  if (process.platform !== "linux") {
+    io.error("Automatic service setup supports Linux (systemd).");
+    return 1;
+  }
+  await runCommand("systemctl", ["disable", "--now", SERVICE_NAME]).catch(() => 1);
+  try {
+    rmSync(SERVICE_PATH, { force: true });
+  } catch {
+    io.error(`Could not remove ${SERVICE_PATH}. Run this command as root (or with sudo).`);
+    return 1;
+  }
+  await runCommand("systemctl", ["daemon-reload"]).catch(() => 1);
+  io.log(`Service ${SERVICE_NAME} removed.`);
+  return 0;
+}
 async function main(argv, io = console) {
   if (argv.includes("--help") || argv.includes("-h")) {
     io.log(USAGE);
@@ -3271,19 +3102,26 @@ async function main(argv, io = console) {
     io.log(USAGE);
     return 0;
   }
-  if (!["install-browser", "install-display", "login", "pair", "run", "status", "unpair"].includes(command)) {
+  if (!["install-browser", "install-service", "login", "logout", "pair", "rename", "run", "status", "uninstall-service", "unpair"].includes(command)) {
     io.error(`Unknown command "${command}".`);
     io.error(USAGE);
     return 2;
   }
   if (command === "install-browser") return commandInstallBrowser(io);
-  if (command === "install-display") return commandInstallDisplay(io);
   const runtime = createRuntime(parsed.options);
   switch (command) {
     case "pair":
       return commandPair(runtime, parsed.options, io);
     case "login":
       return commandLogin(runtime, parsed.options, io);
+    case "logout":
+      return commandLogout(runtime, io);
+    case "rename":
+      return commandRename(runtime, parsed.options, io);
+    case "install-service":
+      return commandInstallService(runtime, io);
+    case "uninstall-service":
+      return commandUninstallService(io);
     case "run":
       return commandRun(runtime, io);
     case "status":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diggylab",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "description": "DiggyLab Desktop Agent collects posts and information from Facebook Groups on a paired computer. (headless CLI)",
   "type": "module",
   "bin": {
@@ -15,7 +15,6 @@
   },
   "dependencies": {
     "playwright": "^1.62.0",
-    "qrcode-terminal": "^0.12.0",
     "ws": "^8.21.3"
   },
   "scripts": {