pinggy 0.6.1 → 0.6.3

package/dist/{chunk-7F67A6LY.js → chunk-TG6LBCPG.js}

@@ -1,29 +1,33 @@
 import {
-  ErrorCode,
   TunnelClient,
+  TunnelConfigV1Schema,
   TunnelOperations,
   buildRemoteManagementWsUrl,
   daemonIpcVersion,
+  ensureDaemonRunning,
   getDaemonInfo,
   initiateRemoteManagement,
   ipcMismatchMessage,
   isDaemonRunning,
-  isErrorResponse,
   isIpcCompatible,
   startDaemon,
   startRemoteManagement,
   stopDaemon
-} from "./chunk-QVV3MRKY.js";
+} from "./chunk-GESMZQHI.js";
 import {
   readDaemonConfig
-} from "./chunk-MT44NAXX.js";
+} from "./chunk-PD7HXVQ3.js";
 import {
   DaemonHost,
+  DeviceAgentState,
+  HTTP_NOT_FOUND,
+  IPCClient,
+  IPCHttpError,
   IPC_VERSION,
   Route,
   SessionMode,
   ShutdownStatus
-} from "./chunk-I4HXBP5G.js";
+} from "./chunk-7EQKHVQX.js";
 import {
   ConfigVerb,
   SUBCOMMANDS,
@@ -39,36 +43,46 @@ import {
   saveConfig,
   updateConfigAutoStart,
   updateTunnelConfig,
-  validateName
-} from "./chunk-DJ5WX37D.js";
+  upsertConfig,
+  validateName,
+  validateNameStrict
+} from "./chunk-Y435RMHQ.js";
 import {
+  createQrCodes
+} from "./chunk-XZ64ZAGO.js";
+import {
+  ErrorCode,
   TunnelManager,
+  TunnelStateType,
   detachAllTunnelLoggers,
   errorMessage,
   getLocalAddress,
   getRandomId,
   getVersion,
+  isErrorResponse,
   isTunnelLoggingEnabled,
   isValidPort,
+  newErrorResponse,
   printer_default,
   setTunnelLoggingEnabled
-} from "./chunk-LV3J6TAV.js";
+} from "./chunk-QNUVQ6KD.js";
 import {
   configureLogger,
   enablePackageLogging,
   getLogLevel,
   logger,
   setLogLevel
-} from "./chunk-JQAQRJPE.js";
+} from "./chunk-MV56U3E6.js";
 import {
   ensurePinggyConfigDir,
   ensurePinggyLogDir,
   getDaemonInfoPath,
   getDaemonLogPath,
+  getDeviceConfigPath,
   getPinggyConfigDir,
   getTunnelLogDir,
   getTunnelLogPath
-} from "./chunk-GBYF2H4H.js";
+} from "./chunk-AFMTIELL.js";
 
 // src/cli/options.ts
 var cliOptions = {
@@ -798,10 +812,10 @@ function parseArgs2(finalConfig, remainingPositionals) {
 }
 function storeJson(config, saveconf) {
   if (saveconf) {
-    const path5 = saveconf;
+    const path6 = saveconf;
     try {
-      fs.writeFileSync(path5, JSON.stringify(config, null, 2), { encoding: "utf-8", flag: "w" });
-      logger.info(`Configuration saved to ${path5}`);
+      fs.writeFileSync(path6, JSON.stringify(config, null, 2), { encoding: "utf-8", flag: "w" });
+      logger.info(`Configuration saved to ${path6}`);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       logger.error("Error loading configuration:", msg);
@@ -1051,7 +1065,7 @@ async function printAlreadyRunning(client, configId, label) {
 async function startTunnel(client, config, opts) {
   const result = await client.handleStartV2(config, false, opts.mode);
   const prefix = opts.label ? `[${opts.label}] ` : "";
-  const fail = (reason) => {
+  const fail2 = (reason) => {
     const msg = `${prefix}Failed to start tunnel: ${reason}`;
     if (opts.onError === "fatal") {
       printer_default.error(msg);
@@ -1066,11 +1080,11 @@ async function startTunnel(client, config, opts) {
       await printAlreadyRunning(client, config.configId, opts.label);
       return null;
     }
-    return fail(result.message);
+    return fail2(result.message);
   }
   const lastError = result.status?.lastError;
   if (lastError?.isFatal) {
-    return fail(lastError.message);
+    return fail2(lastError.message);
   }
   return result;
 }
@@ -1126,7 +1140,7 @@ async function connectTui(opts) {
   const exitMessage = opts.exitMessage || "Stopping tunnel...";
   if (!noTui && process.stdin.isTTY) {
     try {
-      const { TunnelTui } = await import("./TunnelTui-GBRJDOQD.js");
+      const { TunnelTui } = await import("./TunnelTui-UCG2YSLX.js");
       const tui = new TunnelTui({
         urls,
         greet,
@@ -1349,7 +1363,7 @@ async function startBackgroundTunnels(configs, values, positionals) {
   client.close();
 }
 async function startAutoStartTunnels() {
-  const { getAutoStartConfigs: getAutoStartConfigs2 } = await import("./configStore-XRWOTTA4.js");
+  const { getAutoStartConfigs: getAutoStartConfigs2 } = await import("./configStore-RR5ZU4E3.js");
   const configs = getAutoStartConfigs2();
   if (configs.length === 0) {
     printer_default.warn("No configs marked for auto-start. Use: pinggy config auto <name>");
@@ -1757,218 +1771,3062 @@ function printStartHelp() {
   console.log("  pinggy start tunnela tunnelb           Start multiple tunnels");
   console.log("  pinggy start --all                     Start all auto-start tunnels\n");
 }
+function printDeviceHelp() {
+  console.log("\nUsage: pinggy device <command> [options]\n");
+  console.log("Run this machine as a Pinggy device.\n");
+  console.log("Commands:");
+  console.log("  login                    Sign this machine in with your email, then stay connected");
+  console.log("  connect --token <TOKEN>  Enrol, then stay connected until interrupted");
+  console.log("  stop                     Stop the agent running in the background");
+  console.log("  status                   Show the enrolment, and the agent running in the background");
+  console.log("  remove                   Forget the local credential (does not delete the device)\n");
+  console.log("Options:");
+  console.log("  -b                       login and connect: run the agent in the background, in the daemon.");
+  console.log("                           It stays connected after this terminal closes");
+  console.log("  --token <TOKEN>          Device token from the dashboard");
+  console.log("  --manage <HOST>          Dashboard address. Default: dashboard.pinggy.io");
+  console.log("  --name <NAME>            login only: the device's name. Default: this machine's hostname\n");
+  console.log("Environment:");
+  console.log("  DEVICE_AGENT_TOKEN       connect only: the device token, when --token is not given. With no");
+  console.log("                           --manage, it dials dashboard.pinggy.io. Removed once read\n");
+}
 
-// src/cli/subcommand/handlers/daemonCommandsHandler.ts
-async function handleDaemon(args) {
-  if (args.length === 0) {
-    printDaemonHelp();
-    return;
+// src/devices/deviceIdentity.ts
+import fs3 from "fs";
+var SECRET_FILE_MODE = 384;
+function readDeviceIdentity() {
+  const filePath = getDeviceConfigPath();
+  if (!fs3.existsSync(filePath)) {
+    return null;
   }
-  const verb = args[0];
-  switch (verb) {
-    case "start":
-      await handleDaemonStart();
-      return;
-    case "stop":
-      await handleDaemonStop();
-      return;
-    case "status":
-      handleDaemonStatus();
-      return;
-    case "service-install":
-      installService();
-      return;
-    case "service-uninstall":
-      uninstallService();
-      return;
-    default:
-      printer_default.error(`Unknown daemon command: "${verb}"`);
-      printDaemonHelp();
-      return;
+  try {
+    return JSON.parse(fs3.readFileSync(filePath, "utf-8"));
+  } catch (e) {
+    logger.warn("Could not read device identity file", { error: String(e) });
+    return null;
   }
 }
-async function handleDaemonStart() {
-  const info = getDaemonInfo();
-  if (info) {
-    if (!isIpcCompatible(info)) {
-      printer_default.error(ipcMismatchMessage(info));
-      process.exit(1);
-    }
-    printer_default.print(pico2.yellow(`Daemon already running (PID ${info.pid}, port ${info.port}). Use: pinggy daemon status for details.`));
-    return;
-  }
-  const autoConfigs = getAutoStartConfigs();
-  if (autoConfigs.length > 0) {
-    printer_default.print(pico2.cyanBright(`Starting daemon with ${autoConfigs.length} auto-start tunnel(s):`));
-    for (const c of autoConfigs) {
-      printer_default.print(`  ${pico2.bold(c.name)} (${c.configId.slice(0, 8)})`);
-    }
-  } else {
-    printer_default.print(pico2.cyanBright("Starting daemon..."));
+function writeDeviceIdentity(identity) {
+  ensurePinggyConfigDir();
+  const filePath = getDeviceConfigPath();
+  fs3.writeFileSync(filePath, JSON.stringify(identity, null, 2), {
+    encoding: "utf-8",
+    mode: SECRET_FILE_MODE
+  });
+  fs3.chmodSync(filePath, SECRET_FILE_MODE);
+}
+function clearDeviceIdentity() {
+  const filePath = getDeviceConfigPath();
+  if (!fs3.existsSync(filePath)) {
+    return false;
   }
+  fs3.unlinkSync(filePath);
+  return true;
+}
+function maskToken(token) {
+  return token.length <= 8 ? "***" : `${token.slice(0, 8)}...${token.slice(-4)}`;
+}
+
+// src/devices/deviceAgent.ts
+import WebSocket from "ws";
+import os8 from "os";
+
+// src/devices/envelope.ts
+import { randomUUID } from "crypto";
+var PROTOCOL_VERSION = 1;
+var CHANNEL_SYSTEM = "system";
+var CHANNEL_DEVICE = "device";
+var OP_HELLO = "hello";
+var OP_WELCOME = "welcome";
+var OP_HEARTBEAT = "heartbeat";
+var OP_DISCONNECT = "disconnect";
+var OP_INFO = "info";
+var OP_METRICS = "metrics";
+var OP_TUNNELS = "tunnels";
+var CHANNEL_TUNNEL = "tunnel";
+var OP_START = "start";
+var OP_STOP = "stop";
+var OP_RESTART = "restart";
+var OP_UPDATE = "update";
+function nowSeconds() {
+  return Math.floor(Date.now() / 1e3);
+}
+function request(ch, op, payload) {
+  return { v: PROTOCOL_VERSION, kind: "req", ch, op, id: randomUUID(), seq: 0, ts: nowSeconds(), payload };
+}
+function response(to, op, payload) {
+  return { v: PROTOCOL_VERSION, kind: "res", ch: to.ch, op, id: to.id, seq: 0, ts: nowSeconds(), payload };
+}
+function event(ch, op, payload) {
+  return { v: PROTOCOL_VERSION, kind: "event", ch, op, id: "", seq: 0, ts: nowSeconds(), payload };
+}
+function parseEnvelope(raw) {
   try {
-    const info2 = await startDaemon();
-    printer_default.success(`Daemon started PID ${info2.pid}.`);
-  } catch (err) {
-    printer_default.error(`Failed to start daemon: ${errorMessage(err)}`);
-    process.exit(1);
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null) return null;
+    if (typeof parsed.ch !== "string" || typeof parsed.op !== "string") return null;
+    return parsed;
+  } catch {
+    return null;
   }
 }
-async function handleDaemonStop() {
-  if (!isDaemonRunning()) {
-    printer_default.print(pico2.yellow("No daemon is running."));
-    return;
+
+// src/devices/device_schema.ts
+import { z } from "zod";
+var WelcomeSchema = z.object({
+  device_agent_id: z.string(),
+  accepted_proto: z.number(),
+  heartbeat_interval_seconds: z.number(),
+  stats_interval_seconds: z.number(),
+  server_time: z.number(),
+  max_frame_bytes: z.number(),
+  // Optional: a dashboard that predates terminals sends none of these.
+  terminal_enabled: z.boolean().optional(),
+  max_terminals_per_device: z.number().optional(),
+  // No default on the agent. Without it, terminals stay unavailable rather than unbraked.
+  terminal_window_bytes: z.number().optional(),
+  // No default either. Without them the agent runs no expiry timers, and the dashboard's sweep
+  // still ends an expired shell, only later.
+  terminal_idle_timeout_seconds: z.number().optional(),
+  terminal_max_session_seconds: z.number().optional(),
+  // Optional: a dashboard older than these sends neither, and the agent prints only the device id.
+  email: z.string().optional(),
+  device_url: z.string().optional()
+});
+var ErrorPayloadSchema = z.object({
+  error: z.object({
+    code: z.string(),
+    message: z.string()
+  })
+});
+var DisconnectSchema = z.object({
+  reason: z.string()
+});
+var TunnelActionSchema = z.object({
+  tunnel_id: z.string().min(1).max(128).optional(),
+  source: z.enum(["device", "dashboard"]).optional(),
+  config_id: z.string().min(1).max(128).optional(),
+  config: z.record(z.string(), z.unknown()).optional()
+});
+
+// src/devices/deviceAgentReporter.ts
+function printConnected(welcome) {
+  printer_default.success(`Connected as device ${welcome.device_agent_id}`);
+  if (welcome.email) {
+    printer_default.print(`Signed in as ${welcome.email}`);
   }
-  const result = await stopDaemon();
-  if (result.ok) {
-    printer_default.success("Daemon stopped.");
-  } else if (result.reason === DaemonHost.APP) {
-    printer_default.print(pico2.yellow("The Pinggy daemon is running inside the Pinggy desktop app. Please quit the Pinggy app to stop it."));
-  } else {
-    printer_default.error(result.error);
+  if (welcome.device_url) {
+    printer_default.print("Open the device in a browser:");
+    printer_default.print(`  ${welcome.device_url}`);
   }
 }
-function handleDaemonStatus() {
-  const info = getDaemonInfo();
-  if (!info) {
-    printer_default.print(pico2.yellow("No daemon is running. Start with: pinggy daemon start"));
-    return;
-  }
-  const uptimeSec = Math.floor((Date.now() - new Date(info.startedAt).getTime()) / 1e3);
-  const h = Math.floor(uptimeSec / 3600);
-  const m = Math.floor(uptimeSec % 3600 / 60);
-  const s = uptimeSec % 60;
-  const uptimeStr = h > 0 ? `${h}h ${m}m ${s}s` : m > 0 ? `${m}m ${s}s` : `${s}s`;
-  printer_default.print(pico2.cyanBright("Daemon Status"));
-  printer_default.print(`  PID:       ${info.pid}`);
-  printer_default.print(`  Port:      ${info.port}`);
-  printer_default.print(`  Started:   ${info.startedAt}`);
-  printer_default.print(`  Uptime:    ${uptimeStr}`);
-  printer_default.print(`  Host:      ${info.host === DaemonHost.APP ? "Pinggy app (in-process)" : "standalone (CLI)"}`);
-  printer_default.print(`  IPC:       v${daemonIpcVersion(info)}`);
-  if (!isIpcCompatible(info)) {
-    printer_default.print(pico2.yellow(`  Warning:   ${ipcMismatchMessage(info)}`));
-  }
+function formatSeconds(millis) {
+  return (millis / 1e3).toFixed(1);
 }
+var printingReporter = {
+  connecting: (server) => printer_default.print(`Connecting to ${server}`),
+  connected: printConnected,
+  reconnecting: (delayMillis, attempt) => printer_default.warn(
+    `Disconnected. Reconnecting in ${formatSeconds(delayMillis)} seconds (attempt ${attempt}).`
+  ),
+  warn: (message) => printer_default.warn(message),
+  failed: (error) => printer_default.error(error.message),
+  replacingDevice: (oldDeviceAgentId) => printer_default.print(`This machine was device ${oldDeviceAgentId}. Connecting it with the token from the command.`)
+};
 
-// src/cli/subcommand/handlers/psCommand.ts
-import pico3 from "picocolors";
-async function handlePs() {
-  const client = new TunnelClient();
+// src/devices/collectors/systemInfo.ts
+import os3 from "os";
+var UNKNOWN_CPU_MODEL = "unknown";
+function collectSystemInfo() {
+  const cpus = os3.cpus();
+  return {
+    hostname: os3.hostname(),
+    os: os3.platform(),
+    os_version: os3.release(),
+    // os.machine() reports what uname does (x86_64, arm64, aarch64). os.arch() reports the Node
+    // build target (x64), which is not what an operator reads on the machine itself.
+    arch: os3.machine(),
+    kernel: os3.type(),
+    // os.cpus() is empty on some Android and container builds.
+    cpu_model: cpus[0]?.model?.trim() || UNKNOWN_CPU_MODEL,
+    cpu_cores: cpus.length,
+    total_memory_bytes: os3.totalmem()
+  };
+}
+
+// src/devices/collectors/metrics.ts
+import os4 from "os";
+var CPU_SAMPLE_WINDOW_MS = 200;
+function sumCpuTicks(cpus) {
+  let idleTicks = 0;
+  let totalTicks = 0;
+  for (const cpu of cpus) {
+    const { user, nice, sys, idle, irq } = cpu.times;
+    idleTicks += idle;
+    totalTicks += user + nice + sys + idle + irq;
+  }
+  return { idleTicks, totalTicks };
+}
+function cpuPercentBetween(earlier, later) {
+  const totalDelta = later.totalTicks - earlier.totalTicks;
+  if (totalDelta <= 0) {
+    return 0;
+  }
+  const busyDelta = totalDelta - (later.idleTicks - earlier.idleTicks);
+  const percent = Math.min(100, Math.max(0, 100 * busyDelta / totalDelta));
+  return Math.round(percent * 10) / 10;
+}
+function buildMetrics(readings) {
+  const [oneMinute = 0, fiveMinutes = 0, fifteenMinutes = 0] = readings.loadAverages;
+  return {
+    cpu_percent: readings.cpuPercent,
+    load_avg_1m: oneMinute,
+    load_avg_5m: fiveMinutes,
+    load_avg_15m: fifteenMinutes,
+    memory_used_bytes: readings.totalMemoryBytes - readings.freeMemoryBytes,
+    memory_total_bytes: readings.totalMemoryBytes,
+    uptime_seconds: Math.floor(readings.uptimeSeconds),
+    collected_at: readings.collectedAtEpochSeconds
+  };
+}
+async function collectMetrics() {
+  const earlier = sumCpuTicks(os4.cpus());
+  await new Promise((resolve) => setTimeout(resolve, CPU_SAMPLE_WINDOW_MS));
+  const later = sumCpuTicks(os4.cpus());
+  return buildMetrics({
+    cpuPercent: cpuPercentBetween(earlier, later),
+    loadAverages: os4.loadavg(),
+    totalMemoryBytes: os4.totalmem(),
+    freeMemoryBytes: os4.freemem(),
+    uptimeSeconds: os4.uptime(),
+    collectedAtEpochSeconds: Math.floor(Date.now() / 1e3)
+  });
+}
+
+// src/devices/tunnels/tunnelList.ts
+var TUNNEL_POLL_INTERVAL_MILLIS = 5e3;
+var MAX_TUNNELS = 50;
+var MAX_SAVED_CONFIGS = 100;
+var ERROR_MESSAGE_MAX_LENGTH = 256;
+var REASON_IPC_VERSION_MISMATCH = "ipc_version_mismatch";
+var REASON_DAEMON_UNREACHABLE = "daemon_unreachable";
+var FORWARDING_TYPES = /* @__PURE__ */ new Set(["http", "tcp", "udp", "tls", "tlstcp"]);
+var DEFAULT_FORWARDING_TYPE = "http";
+var MODES = /* @__PURE__ */ new Set(["foreground", "detached"]);
+var STATES = new Set(Object.values(TunnelStateType));
+var STOPPED_STATES = /* @__PURE__ */ new Set(["closed" /* Closed */, "exited" /* Exited */]);
+async function readDaemonOnPort(port) {
   try {
-    await client.ensureDaemon();
+    const answer = await new IPCClient(port, "cli").listTunnels();
+    return { running: true, tunnels: Array.isArray(answer) ? answer : [] };
   } catch (err) {
-    printer_default.error(`Cannot connect to daemon: ${errorMessage(err)}`);
-    return;
+    logger.debug("Device agent could not list the daemon's tunnels", { error: String(err) });
+    return { running: false, reason: REASON_DAEMON_UNREACHABLE };
   }
-  try {
-    const tunnels = await client.handleListV2();
-    if (isErrorResponse(tunnels)) {
-      printer_default.error(`Failed to list tunnels: ${tunnels.message}`);
-      return;
+}
+var machineTunnelListSource = {
+  async readDaemon() {
+    const info = getDaemonInfo();
+    if (!info) {
+      return { running: false, reason: null };
     }
-    if (tunnels.length === 0) {
-      printer_default.print("No tunnels running.");
-      return;
+    if (!isIpcCompatible(info)) {
+      return { running: false, reason: REASON_IPC_VERSION_MISMATCH };
     }
-    const header = `${pad("ID", 14)} ${pad("NAME", 16)} ${pad("STATUS", 10)} ${pad("LOCAL", 20)} URL`;
-    printer_default.print(pico3.gray(header));
-    printer_default.print(pico3.gray("\u2500".repeat(90)));
-    for (const t of tunnels) {
-      const id = t.tunnelid.slice(0, 12);
-      const name = t.tunnelconfig?.name || "-";
-      const status = t.status.state;
-      const local = getLocalAddress(t.tunnelconfig);
-      const url = t.remoteurls?.[0] || "-";
-      const statusColor = status === "running" ? pico3.green : status === "starting" ? pico3.yellow : pico3.red;
-      printer_default.print(
-        `${pico3.cyan(pad(id, 14))} ${pad(name, 16)} ${statusColor(pad(status, 10))} ${pad(local, 20)} ${pico3.magentaBright(url)}`
-      );
+    return readDaemonOnPort(info.port);
+  },
+  readSavedConfigs: listSavedConfigs
+};
+function selfTunnelListSource(port) {
+  return {
+    readDaemon: () => readDaemonOnPort(port),
+    readSavedConfigs: listSavedConfigs
+  };
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function stringOrNull(value) {
+  return typeof value === "string" && value !== "" ? value : null;
+}
+function toEpochSeconds(value) {
+  if (typeof value !== "string" || value === "") return null;
+  const millis = Date.parse(value);
+  return Number.isNaN(millis) ? null : Math.floor(millis / 1e3);
+}
+function sanitizeErrorMessage(value) {
+  if (typeof value !== "string") return null;
+  const printable = value.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").trim();
+  return printable === "" ? null : printable.slice(0, ERROR_MESSAGE_MAX_LENGTH);
+}
+function forwardingType(value) {
+  return typeof value === "string" && FORWARDING_TYPES.has(value) ? value : DEFAULT_FORWARDING_TYPE;
+}
+function toForwarding(forwarding) {
+  if (typeof forwarding === "string") {
+    if (forwarding.trim() === "") return [];
+    const schemeMatch = /^([a-z]+):\/\/(.+)$/i.exec(forwarding.trim());
+    if (!schemeMatch) {
+      return [{ type: DEFAULT_FORWARDING_TYPE, local_address: forwarding.trim() }];
     }
-  } catch (err) {
-    printer_default.error(`Failed to list tunnels: ${errorMessage(err)}`);
-  } finally {
-    client.close();
-  }
+    const scheme = schemeMatch[1].toLowerCase();
+    return [{
+      type: scheme === "https" ? DEFAULT_FORWARDING_TYPE : forwardingType(scheme),
+      local_address: schemeMatch[2]
+    }];
+  }
+  if (!Array.isArray(forwarding)) return [];
+  return forwarding.filter(isObject).filter((entry) => typeof entry.address === "string").map((entry) => ({ type: forwardingType(entry.type), local_address: entry.address }));
 }
-function pad(str, len) {
-  return str.length >= len ? str.slice(0, len) : str + " ".repeat(len - str.length);
+function toFullConfig(rawConfig) {
+  const parsed = TunnelConfigV1Schema.safeParse(rawConfig);
+  return parsed.success ? parsed.data : null;
 }
-
-// src/cli/subcommand/handlers/stopCommand.ts
-async function handleStop(args) {
-  if (args.length === 0) {
-    printer_default.error("Usage: pinggy stop <name|id> [<name|id> ...]");
-    return;
-  }
-  const client = new TunnelClient();
+function toTunnelRow(daemonTunnel) {
+  if (!isObject(daemonTunnel) || typeof daemonTunnel.tunnelid !== "string") return null;
+  const config = isObject(daemonTunnel.tunnelconfig) ? daemonTunnel.tunnelconfig : {};
+  const status = isObject(daemonTunnel.status) ? daemonTunnel.status : {};
+  const remoteUrls = Array.isArray(daemonTunnel.remoteurls) ? daemonTunnel.remoteurls.filter((url) => typeof url === "string") : [];
+  return {
+    tunnel_id: daemonTunnel.tunnelid,
+    config_id: stringOrNull(config.configId),
+    name: stringOrNull(config.name),
+    state: typeof status.state === "string" && STATES.has(status.state) ? status.state : "idle" /* New */,
+    error_message: sanitizeErrorMessage(status.errormsg),
+    remote_urls: remoteUrls,
+    forwarding: toForwarding(config.forwarding),
+    mode: typeof daemonTunnel.mode === "string" && MODES.has(daemonTunnel.mode) ? daemonTunnel.mode : null,
+    created_at: toEpochSeconds(status.createdtimestamp),
+    started_at: toEpochSeconds(status.starttimestamp),
+    tunnel_config: toFullConfig(daemonTunnel.tunnelconfig)
+  };
+}
+function newestFirst(rows, timeOf) {
+  return [...rows].sort((a, b) => (timeOf(b) ?? 0) - (timeOf(a) ?? 0));
+}
+function buildTunnelList(reading, savedConfigs, collectedAtEpochSeconds) {
+  const allTunnels = reading.running ? newestFirst(
+    reading.tunnels.map(toTunnelRow).filter((row) => row !== null),
+    (row) => row.created_at
+  ) : [];
+  const runningConfigIds = new Set(allTunnels.filter((row) => row.config_id !== null && !STOPPED_STATES.has(row.state)).map((row) => row.config_id));
+  const allSaved = newestFirst(savedConfigs, (config) => toEpochSeconds(config.createdAt)).map((config) => ({
+    config_id: config.configId,
+    name: config.name,
+    running: runningConfigIds.has(config.configId),
+    // The same shape tunnelActions.ts sends the daemon to start this exact config.
+    tunnel_config: { ...config.tunnelConfig, configId: config.configId, name: config.name }
+  }));
+  return {
+    daemon_running: reading.running,
+    daemon_unavailable_reason: reading.running ? null : reading.reason,
+    tunnels: allTunnels.slice(0, MAX_TUNNELS),
+    saved_configs: allSaved.slice(0, MAX_SAVED_CONFIGS),
+    truncated: allTunnels.length > MAX_TUNNELS || allSaved.length > MAX_SAVED_CONFIGS,
+    collected_at: collectedAtEpochSeconds
+  };
+}
+async function collectTunnelList(source = machineTunnelListSource) {
+  const reading = await source.readDaemon();
+  let savedConfigs = [];
   try {
-    await client.ensureDaemon();
+    savedConfigs = source.readSavedConfigs();
   } catch (err) {
-    printer_default.error(`Cannot connect to daemon: ${errorMessage(err)}`);
-    return;
+    logger.debug("Device agent could not read saved tunnel configs", { error: String(err) });
   }
-  try {
-    const tunnels = await client.handleListV2();
-    if (isErrorResponse(tunnels)) {
-      printer_default.error(`Failed to list tunnels: ${tunnels.message}`);
-      return;
-    }
-    const targets = resolveTargets(tunnels, args);
-    if (targets.matched.length === 0) {
-      printer_default.error(`No tunnel found matching: ${args.join(", ")}. Use: pinggy ps`);
+  return buildTunnelList(reading, savedConfigs, Math.floor(Date.now() / 1e3));
+}
+function changeKey(list) {
+  const { collected_at: _collectedAt, ...comparable } = list;
+  return JSON.stringify(comparable);
+}
+function startTunnelReporting(collect, send, intervalMillis = TUNNEL_POLL_INTERVAL_MILLIS) {
+  let stopped = false;
+  let inFlight = false;
+  let pollAgain = false;
+  let lastSentKey = null;
+  const poll = () => {
+    if (stopped) return;
+    if (inFlight) {
+      pollAgain = true;
       return;
     }
-    for (const { input, tunnel } of targets.matched) {
-      const result = await client.handleStop(tunnel.tunnelid);
-      if (isErrorResponse(result)) {
-        printer_default.error(`Failed to stop "${input}": ${result.message}`);
-        continue;
+    inFlight = true;
+    collect().then((list) => {
+      if (stopped) return;
+      const key = changeKey(list);
+      if (key === lastSentKey) return;
+      lastSentKey = key;
+      send(list);
+    }).catch((err) => logger.warn("Device tunnel list collection failed", { error: String(err) })).finally(() => {
+      inFlight = false;
+      if (pollAgain) {
+        pollAgain = false;
+        poll();
       }
-      const name = tunnel.tunnelconfig.name || tunnel.tunnelid.slice(0, 12);
-      printer_default.success(`Tunnel "${name}" stopped.`);
+    });
+  };
+  poll();
+  const timer = setInterval(poll, intervalMillis);
+  const stop = () => {
+    stopped = true;
+    clearInterval(timer);
+  };
+  return Object.assign(stop, { pollNow: poll });
+}
+
+// src/devices/tunnels/tunnelActions.ts
+var ERROR_INVALID_PAYLOAD = "invalid_payload";
+var ERROR_UNSUPPORTED_OP = "unsupported_op";
+var ERROR_TUNNEL_NOT_FOUND = "tunnel_not_found";
+var ERROR_SAVED_CONFIG_NOT_FOUND = "saved_config_not_found";
+var ERROR_SAVED_CONFIG_NAME_TAKEN = "saved_config_name_taken";
+var ERROR_TUNNEL_ACTION_FAILED = "tunnel_action_failed";
+var STATE_STARTING = "starting";
+var DaemonUnusableError = class extends Error {
+};
+var machineTunnelActionDependencies = {
+  async daemon(startIfMissing) {
+    const info = getDaemonInfo();
+    if (info) {
+      if (!isIpcCompatible(info)) {
+        throw new DaemonUnusableError(ipcMismatchMessage(info));
+      }
+      return new IPCClient(info.port, "device");
     }
-    for (const m of targets.missing) {
-      printer_default.warn(`No tunnel found matching "${m}".`);
+    if (!startIfMissing) {
+      return null;
     }
-  } catch (err) {
-    printer_default.error(`Failed to stop tunnel: ${errorMessage(err)}`);
-  } finally {
-    client.close();
+    const started = await ensureDaemonRunning();
+    return new IPCClient(started.port, "device");
+  },
+  readSavedConfigs: listSavedConfigs,
+  writeSavedConfig: (saved) => {
+    upsertConfig(saved);
   }
+};
+function selfTunnelActionDependencies(port) {
+  return {
+    daemon: () => Promise.resolve(new IPCClient(port, "device")),
+    readSavedConfigs: machineTunnelActionDependencies.readSavedConfigs,
+    writeSavedConfig: machineTunnelActionDependencies.writeSavedConfig
+  };
 }
-function resolveTargets(tunnels, args) {
-  if (args.length > 1) {
-    const input = args.join(" ");
-    const tunnel = findTunnel(tunnels, input);
-    if (tunnel) return { matched: [{ input, tunnel }], missing: [] };
+function failure(code, message) {
+  return { error: { code, message } };
+}
+function actionFailed(message) {
+  return failure(ERROR_TUNNEL_ACTION_FAILED, sanitizeErrorMessage(message) ?? "The tunnel action failed.");
+}
+var NO_DAEMON = failure(ERROR_TUNNEL_NOT_FOUND, "No tunnel daemon is running on this machine.");
+function toResult(daemonAnswer, fallbackTunnelId) {
+  if (isErrorResponse(daemonAnswer)) {
+    if (daemonAnswer.code === ErrorCode.TunnelNotFound) {
+      return failure(ERROR_TUNNEL_NOT_FOUND, sanitizeErrorMessage(daemonAnswer.message) ?? "No such tunnel.");
+    }
+    return actionFailed(daemonAnswer.message);
   }
-  const matched = [];
-  const missing = [];
-  for (const input of args) {
-    const tunnel = findTunnel(tunnels, input);
-    if (tunnel) matched.push({ input, tunnel });
-    else missing.push(input);
+  const answer = typeof daemonAnswer === "object" && daemonAnswer !== null ? daemonAnswer : {};
+  const tunnelId = typeof answer.tunnelid === "string" && answer.tunnelid !== "" ? answer.tunnelid : fallbackTunnelId;
+  if (!tunnelId) {
+    return actionFailed("The daemon did not name the tunnel.");
   }
-  return { matched, missing };
+  const state = typeof answer.status?.state === "string" ? answer.status.state : STATE_STARTING;
+  return { tunnel_id: tunnelId, state };
 }
-
-// src/cli/subcommand/handlers/attachCommand.ts
-import pico4 from "picocolors";
-async function handleAttach(args) {
-  if (args.length === 0) {
-    printer_default.error("Usage: pinggy attach <name|id>");
-    return;
+function withoutNulls(config) {
+  return Object.fromEntries(Object.entries(config).filter(([, value]) => value !== null));
+}
+function targetOf(op, action) {
+  const namesTunnel = action.tunnel_id !== void 0;
+  if (op === OP_UPDATE) {
+    if (namesTunnel || action.config === void 0) {
+      return null;
+    }
+    if (action.source === "dashboard" && action.config_id === void 0) {
+      return { kind: "dashboard", config: action.config };
+    }
+    if (action.source === "device" && action.config_id !== void 0) {
+      return { kind: "savedEdit", configId: action.config_id, config: action.config };
+    }
+    return null;
   }
-  const nameOrId = args[0];
-  const client = new TunnelClient();
-  try {
-    await client.ensureDaemon();
-  } catch (err) {
-    printer_default.error(`Cannot connect to daemon: ${errorMessage(err)}`);
-    return;
+  if (op !== OP_START) {
+    return namesTunnel ? { kind: "tunnel", tunnelId: action.tunnel_id } : null;
   }
-  try {
+  if (namesTunnel) {
+    return action.source === void 0 && action.config_id === void 0 && action.config === void 0 ? { kind: "tunnel", tunnelId: action.tunnel_id } : null;
+  }
+  if (action.source === "device" && action.config_id !== void 0 && action.config === void 0) {
+    return { kind: "saved", configId: action.config_id };
+  }
+  if (action.source === "dashboard" && action.config !== void 0 && action.config_id === void 0) {
+    return { kind: "dashboard", config: action.config };
+  }
+  return null;
+}
+async function perform(op, action, dependencies) {
+  const target = targetOf(op, action);
+  if (!target) {
+    return failure(ERROR_INVALID_PAYLOAD, "The tunnel request names no tunnel or config.");
+  }
+  if (target.kind === "tunnel") {
+    const client2 = await dependencies.daemon(false);
+    if (!client2) {
+      return NO_DAEMON;
+    }
+    const answer = op === OP_STOP ? await client2.stopTunnel(target.tunnelId) : await client2.restartTunnel(target.tunnelId, true);
+    return toResult(answer, target.tunnelId);
+  }
+  if (target.kind === "savedEdit") {
+    return rewriteSavedConfig(target.configId, target.config, dependencies);
+  }
+  let config;
+  if (target.kind === "saved") {
+    const saved = dependencies.readSavedConfigs().find((candidate) => candidate.configId === target.configId);
+    if (!saved) {
+      return failure(ERROR_SAVED_CONFIG_NOT_FOUND, "No config with that id is saved on this machine.");
+    }
+    config = { ...saved.tunnelConfig, configId: saved.configId, name: saved.name };
+  } else {
+    const parsed = TunnelConfigV1Schema.safeParse(withoutNulls(target.config));
+    if (!parsed.success) {
+      return failure(ERROR_INVALID_PAYLOAD, "The dashboard config could not be read.");
+    }
+    config = parsed.data;
+  }
+  if (op === OP_UPDATE) {
+    return updateTunnel(config, dependencies);
+  }
+  const client = await dependencies.daemon(true);
+  if (!client) {
+    return actionFailed("The tunnel daemon could not be started.");
+  }
+  return toResult(await client.startTunnelWithConfig(config, SessionMode.Detached, true), null);
+}
+function rewriteSavedConfig(configId, rawConfig, dependencies) {
+  const parsed = TunnelConfigV1Schema.safeParse(withoutNulls(rawConfig));
+  if (!parsed.success) {
+    return failure(ERROR_INVALID_PAYLOAD, "The config could not be read.");
+  }
+  const savedConfigs = dependencies.readSavedConfigs();
+  const saved = savedConfigs.find((candidate) => candidate.configId === configId);
+  if (!saved) {
+    return failure(ERROR_SAVED_CONFIG_NOT_FOUND, "No config with that id is saved on this machine.");
+  }
+  const name = parsed.data.name || saved.name;
+  if (name !== saved.name) {
+    const nameError = validateNameStrict(name);
+    if (nameError) {
+      return failure(ERROR_INVALID_PAYLOAD, nameError.message);
+    }
+    if (savedConfigs.some((candidate) => candidate.name === name)) {
+      return failure(ERROR_SAVED_CONFIG_NAME_TAKEN, `A config named "${name}" is already saved on this machine.`);
+    }
+  }
+  dependencies.writeSavedConfig({
+    ...saved,
+    name,
+    updatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    tunnelConfig: { ...parsed.data, configId, name }
+  });
+  return { config_id: configId };
+}
+async function updateTunnel(config, dependencies) {
+  const client = await dependencies.daemon(false);
+  if (!client) {
+    return NO_DAEMON;
+  }
+  const listed = await client.listTunnels();
+  if (!Array.isArray(listed)) {
+    return actionFailed(isErrorResponse(listed) ? listed.message : "The daemon did not list its tunnels.");
+  }
+  const running = listed.find((candidate) => candidate.tunnelconfig?.configId === config.configId);
+  if (!running) {
+    return failure(ERROR_TUNNEL_NOT_FOUND, "No tunnel on this machine runs that config.");
+  }
+  return toResult(await client.updateConfigV2(config, true), running.tunnelid);
+}
+async function handleTunnelAction(envelope, send, dependencies = machineTunnelActionDependencies) {
+  if (envelope.kind !== "req") {
+    return;
+  }
+  const op = envelope.op;
+  if (op !== OP_START && op !== OP_STOP && op !== OP_RESTART && op !== OP_UPDATE) {
+    send(response(envelope, op, failure(ERROR_UNSUPPORTED_OP, `Unsupported operation: tunnel/${op}`)));
+    return;
+  }
+  const parsed = TunnelActionSchema.safeParse(envelope.payload);
+  if (!parsed.success) {
+    send(response(envelope, op, failure(ERROR_INVALID_PAYLOAD, "The tunnel request could not be read.")));
+    return;
+  }
+  let result;
+  try {
+    result = await perform(op, parsed.data, dependencies);
+  } catch (err) {
+    result = actionFailed(err instanceof Error ? err.message : String(err));
+  }
+  logger.info("Device agent tunnel action", {
+    op,
+    tunnelId: parsed.data.tunnel_id ?? null,
+    configId: parsed.data.config_id ?? null,
+    source: parsed.data.source ?? null,
+    outcome: "error" in result ? result.error.code : "accepted"
+  });
+  send(response(envelope, op, result));
+}
+
+// src/devices/reconnect.ts
+var INITIAL_DELAY_MILLIS = 1e3;
+var MAX_DELAY_MILLIS = 6e4;
+var STABLE_CONNECTION_MILLIS = 6e4;
+var MAX_ATTEMPT = Math.ceil(Math.log2(MAX_DELAY_MILLIS / INITIAL_DELAY_MILLIS));
+function backoffCeilingMillis(attempt) {
+  const uncapped = INITIAL_DELAY_MILLIS * 2 ** Math.max(0, attempt);
+  return Math.min(uncapped, MAX_DELAY_MILLIS);
+}
+function fullJitterMillis(ceilingMillis, random) {
+  return Math.floor(random() * ceilingMillis);
+}
+var ReconnectPolicy = class {
+  constructor(options = {}) {
+    this.attemptCount = 0;
+    this.connectedAtMillis = null;
+    this.now = options.now ?? Date.now;
+    this.random = options.random ?? Math.random;
+  }
+  /** Attempts taken since the last reset. Exposed for logging and for tests. */
+  get attempt() {
+    return this.attemptCount;
+  }
+  /** The ceiling the next delay will be drawn from, before jitter. */
+  get nextCeilingMillis() {
+    return backoffCeilingMillis(this.attemptCount);
+  }
+  markConnected() {
+    this.connectedAtMillis = this.now();
+  }
+  /**
+   * Ends the current connection. Returns true when it had held long enough to reset the
+   * schedule, which the caller logs.
+   */
+  markDisconnected() {
+    const heldMillis = this.connectedAtMillis === null ? 0 : this.now() - this.connectedAtMillis;
+    this.connectedAtMillis = null;
+    const wasStable = heldMillis >= STABLE_CONNECTION_MILLIS;
+    if (wasStable) {
+      this.attemptCount = 0;
+    }
+    return wasStable;
+  }
+  /** The delay before the next dial, and advances the schedule. */
+  nextDelayMillis() {
+    const delay = fullJitterMillis(this.nextCeilingMillis, this.random);
+    this.attemptCount = Math.min(this.attemptCount + 1, MAX_ATTEMPT);
+    return delay;
+  }
+};
+
+// src/devices/terminal/terminal_schema.ts
+import { z as z2 } from "zod";
+var CHANNEL_TERMINAL = "terminal";
+var OP_OPEN = "open";
+var OP_OPENED = "opened";
+var OP_CLOSE = "close";
+var OP_DATA = "data";
+var OP_ACK = "ack";
+var OP_EXIT = "exit";
+var OP_RESIZE = "resize";
+var OP_SIGNAL = "signal";
+var OP_CONTEXT = "context";
+var OP_SNAPSHOT = "snapshot";
+var TERMINAL_SIGNALS = ["INT", "TERM", "QUIT", "HUP"];
+var MIN_GRID = 1;
+var MAX_GRID = 1e3;
+var CLOSE_REASON_USER_CLOSED = "user_closed";
+var CLOSE_REASON_IDLE_TIMEOUT = "idle_timeout";
+var CLOSE_REASON_MAX_SESSION = "max_session";
+var ERROR_INVALID_PAYLOAD2 = "invalid_payload";
+var ERROR_TERMINAL_LIMIT_REACHED = "terminal_limit_reached";
+var ERROR_TERMINAL_DISABLED = "terminal_disabled";
+var ERROR_SHELL_NOT_ALLOWED = "shell_not_allowed";
+var ERROR_SPAWN_FAILED = "spawn_failed";
+var TerminalOpenSchema = z2.object({
+  terminal_id: z2.string().min(1),
+  cols: z2.number().int().optional(),
+  rows: z2.number().int().optional(),
+  shell: z2.string().nullable().optional(),
+  cwd: z2.string().nullable().optional()
+});
+var TerminalCloseSchema = z2.object({
+  terminal_id: z2.string().min(1),
+  reason: z2.string().optional()
+});
+var TerminalResizeSchema = z2.object({
+  terminal_id: z2.string().min(1),
+  cols: z2.number().int(),
+  rows: z2.number().int()
+});
+var TerminalInputSchema = z2.object({
+  terminal_id: z2.string().min(1),
+  data: z2.string()
+});
+var TerminalSignalSchema = z2.object({
+  terminal_id: z2.string().min(1),
+  signal: z2.enum(TERMINAL_SIGNALS)
+});
+var TerminalAckSchema = z2.object({
+  terminal_id: z2.string().min(1),
+  ack_seq: z2.number().optional(),
+  ack_bytes: z2.number()
+});
+var TerminalSnapshotRequestSchema = z2.object({
+  terminal_id: z2.string().min(1),
+  snapshot_id: z2.string().min(1)
+});
+function clampGrid(requested, fallback) {
+  if (requested === void 0 || !Number.isFinite(requested)) return fallback;
+  return Math.max(MIN_GRID, Math.min(MAX_GRID, Math.trunc(requested)));
+}
+
+// src/devices/terminal/terminalHandler.ts
+import os6 from "os";
+
+// src/devices/terminal/flowWindow.ts
+var FlowWindow = class {
+  constructor(windowBytes) {
+    this.sentBytes = 0;
+    this.ackedBytes = 0;
+    if (!Number.isFinite(windowBytes) || windowBytes <= 0) {
+      throw new Error("A terminal flow window needs a positive size from welcome");
+    }
+    this.windowBytes = Math.trunc(windowBytes);
+  }
+  /** How many more raw bytes may go out before the browser has to catch up. */
+  remaining() {
+    return Math.max(0, this.windowBytes - (this.sentBytes - this.ackedBytes));
+  }
+  /** False means stop reading the pty. Nothing else is an acceptable response. */
+  isOpen() {
+    return this.remaining() > 0;
+  }
+  recordSent(byteCount) {
+    if (!Number.isFinite(byteCount) || byteCount <= 0) return;
+    this.sentBytes += Math.trunc(byteCount);
+  }
+  /**
+   * Cumulative totals, never increments, so a dropped ack self-heals on the next one.
+   *
+   * A browser is not a trusted input. An ack beyond what was sent is clamped rather than believed,
+   * and one that arrives out of order never moves the counter backwards.
+   */
+  recordAck(ackBytes) {
+    if (!Number.isFinite(ackBytes)) return;
+    const clamped = Math.min(Math.max(Math.trunc(ackBytes), 0), this.sentBytes);
+    if (clamped > this.ackedBytes) {
+      this.ackedBytes = clamped;
+    }
+  }
+  get sent() {
+    return this.sentBytes;
+  }
+  get acked() {
+    return this.ackedBytes;
+  }
+  get size() {
+    return this.windowBytes;
+  }
+};
+
+// src/devices/terminal/frameSplitter.ts
+var ENVELOPE_OVERHEAD_BYTES = 512;
+var BASE64_NUMERATOR = 3;
+var BASE64_DENOMINATOR = 4;
+var BUNDLE_MILLIS = 8;
+function rawBundleBytes(maxFrameBytes) {
+  const available = maxFrameBytes - ENVELOPE_OVERHEAD_BYTES;
+  if (available <= 0) {
+    throw new Error("max_frame_bytes leaves no room for a terminal payload");
+  }
+  return Math.floor(available * BASE64_NUMERATOR / BASE64_DENOMINATOR);
+}
+var FrameSplitter = class {
+  constructor(emit, bundleBytes, bundleMillis = BUNDLE_MILLIS) {
+    this.emit = emit;
+    this.bundleBytes = bundleBytes;
+    this.bundleMillis = bundleMillis;
+    this.pending = [];
+    this.pendingBytes = 0;
+    if (!Number.isFinite(bundleBytes) || bundleBytes <= 0) {
+      throw new Error("A frame splitter needs a positive bundle size");
+    }
+  }
+  /** A chunk over the cap is split across frames, never truncated. */
+  push(chunk) {
+    if (chunk.length === 0) return;
+    this.pending.push(chunk);
+    this.pendingBytes += chunk.length;
+    while (this.pendingBytes >= this.bundleBytes) {
+      this.emitBytes(this.bundleBytes);
+    }
+    if (this.pendingBytes > 0) {
+      this.arm();
+    } else {
+      this.disarm();
+    }
+  }
+  /** Sends whatever is held, if anything. Used when the terminal closes and by the timer. */
+  flush() {
+    this.disarm();
+    if (this.pendingBytes > 0) {
+      this.emitBytes(this.pendingBytes);
+    }
+  }
+  dispose() {
+    this.disarm();
+    this.pending = [];
+    this.pendingBytes = 0;
+  }
+  get buffered() {
+    return this.pendingBytes;
+  }
+  emitBytes(byteCount) {
+    const joined = Buffer.concat(this.pending, this.pendingBytes);
+    const frame = joined.subarray(0, byteCount);
+    const rest = joined.subarray(byteCount);
+    this.pending = rest.length > 0 ? [rest] : [];
+    this.pendingBytes = rest.length;
+    this.emit(frame);
+  }
+  arm() {
+    if (this.timer !== void 0) return;
+    this.timer = setTimeout(() => {
+      this.timer = void 0;
+      this.flush();
+    }, this.bundleMillis);
+    this.timer.unref?.();
+  }
+  disarm() {
+    if (this.timer === void 0) return;
+    clearTimeout(this.timer);
+    this.timer = void 0;
+  }
+};
+
+// src/devices/terminal/shellContext.ts
+import { execFile } from "child_process";
+import fs4 from "fs";
+import os5 from "os";
+var SHELL_CONTEXT_POLL_MILLIS = 5e3;
+var MAX_CWD_CHARACTERS = 1024;
+var MAX_COMMAND_CHARACTERS = 64;
+var PROCESS_READ_TIMEOUT_MILLIS = 2e3;
+var HOME_PREFIX = "~";
+function processTableReader(platform2 = process.platform) {
+  if (platform2 === "linux") return readFromProc;
+  if (platform2 === "darwin") return readFromPsAndLsof;
+  return null;
+}
+function programName(rawName) {
+  const text = cleanText(rawName, Number.MAX_SAFE_INTEGER);
+  if (text === null) return null;
+  const firstWord = text.split(/\s+/, 1)[0];
+  const baseName = firstWord.slice(firstWord.lastIndexOf("/") + 1).replace(/:+$/, "");
+  return baseName === "" ? null : truncate(baseName, MAX_COMMAND_CHARACTERS);
+}
+function displayCwd(rawCwd, resolvedHome) {
+  const cwd = cleanText(rawCwd, Number.MAX_SAFE_INTEGER);
+  if (cwd === null) return null;
+  let shown = cwd;
+  if (resolvedHome && cwd === resolvedHome) {
+    shown = HOME_PREFIX;
+  } else if (resolvedHome && cwd.startsWith(resolvedHome + "/")) {
+    shown = HOME_PREFIX + cwd.slice(resolvedHome.length);
+  }
+  return truncate(shown, MAX_CWD_CHARACTERS);
+}
+function resolvedHomeDirectory() {
+  try {
+    return fs4.realpathSync(os5.homedir());
+  } catch {
+    return null;
+  }
+}
+function cleanText(raw, maxCharacters) {
+  if (raw === null || raw === void 0) return null;
+  const text = raw.replace(/[\u0000-\u001f\u007f-\u009f]/g, "").trim();
+  return text === "" ? null : truncate(text, maxCharacters);
+}
+function truncate(text, maxCharacters) {
+  const codePoints = Array.from(text);
+  return codePoints.length <= maxCharacters ? text : codePoints.slice(0, maxCharacters).join("");
+}
+var ShellContextTracker = class {
+  constructor() {
+    this.known = /* @__PURE__ */ new Map();
+  }
+  /** The event to send, or null when nothing changed since the last one. */
+  observe(terminalId, raw, resolvedHome) {
+    const previous = this.known.get(terminalId);
+    const command = programName(raw.foregroundName);
+    const previousCommand = previous?.command ?? null;
+    const lastCommand = previousCommand !== null && previousCommand !== command ? previousCommand : previous?.last_command ?? null;
+    const next = {
+      terminal_id: terminalId,
+      cwd: displayCwd(raw.cwd, resolvedHome),
+      command,
+      last_command: lastCommand
+    };
+    if (previous && previous.cwd === next.cwd && previous.command === next.command && previous.last_command === next.last_command) {
+      return null;
+    }
+    this.known.set(terminalId, next);
+    return next;
+  }
+  /** What was last sent for every shell, to send again after a reconnect. */
+  current() {
+    return [...this.known.values()];
+  }
+  forget(terminalId) {
+    this.known.delete(terminalId);
+  }
+  clear() {
+    this.known.clear();
+  }
+};
+async function readFromProc(shellPids) {
+  const contexts = /* @__PURE__ */ new Map();
+  await Promise.all(shellPids.map(async (shellPid) => {
+    const groups = await readProcGroups(shellPid);
+    if (!groups) return;
+    const cwd = await readOrNull(() => fs4.promises.readlink(`/proc/${shellPid}/cwd`));
+    const foregroundName = groups.foregroundGroupId === groups.shellGroupId ? null : await readOrNull(() => fs4.promises.readFile(`/proc/${groups.foregroundGroupId}/comm`, "utf8"));
+    contexts.set(shellPid, { cwd, foregroundName });
+  }));
+  return contexts;
+}
+async function readProcGroups(shellPid) {
+  const stat = await readOrNull(() => fs4.promises.readFile(`/proc/${shellPid}/stat`, "utf8"));
+  if (stat === null) return null;
+  const afterName = stat.slice(stat.lastIndexOf(")") + 2).split(" ");
+  const shellGroupId = Number.parseInt(afterName[2], 10);
+  const foregroundGroupId = Number.parseInt(afterName[5], 10);
+  if (!(shellGroupId > 0) || !(foregroundGroupId > 0)) return null;
+  return { shellGroupId, foregroundGroupId };
+}
+async function readFromPsAndLsof(shellPids) {
+  const contexts = /* @__PURE__ */ new Map();
+  if (shellPids.length === 0) return contexts;
+  const groups = parseColumns(await run("ps", ["-o", "pid=,pgid=,tpgid=", "-p", shellPids.join(",")]));
+  const foregroundGroupIds = [...groups.values()].filter(([shellGroupId, foregroundGroupId]) => foregroundGroupId > 0 && foregroundGroupId !== shellGroupId).map(([, foregroundGroupId]) => foregroundGroupId);
+  const [names, cwds] = await Promise.all([
+    foregroundGroupIds.length === 0 ? Promise.resolve(/* @__PURE__ */ new Map()) : run("ps", ["-o", "pid=,comm=", "-p", foregroundGroupIds.join(",")]).then(parseNames),
+    run("lsof", ["-a", "-d", "cwd", "-Fpn", "-p", shellPids.join(",")]).then(parseLsofCwds)
+  ]);
+  for (const shellPid of shellPids) {
+    const group = groups.get(shellPid);
+    if (!group) continue;
+    const [shellGroupId, foregroundGroupId] = group;
+    contexts.set(shellPid, {
+      cwd: cwds.get(shellPid) ?? null,
+      foregroundName: foregroundGroupId === shellGroupId ? null : names.get(foregroundGroupId) ?? null
+    });
+  }
+  return contexts;
+}
+function parseColumns(stdout) {
+  const columns = /* @__PURE__ */ new Map();
+  for (const line of (stdout ?? "").split("\n")) {
+    const [pid, groupId, foregroundGroupId] = line.trim().split(/\s+/).map((field) => Number.parseInt(field, 10));
+    if (pid > 0 && groupId > 0) columns.set(pid, [groupId, foregroundGroupId]);
+  }
+  return columns;
+}
+function parseNames(stdout) {
+  const names = /* @__PURE__ */ new Map();
+  for (const line of (stdout ?? "").split("\n")) {
+    const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+    if (match) names.set(Number.parseInt(match[1], 10), match[2]);
+  }
+  return names;
+}
+function parseLsofCwds(stdout) {
+  const cwds = /* @__PURE__ */ new Map();
+  let pid = 0;
+  for (const line of (stdout ?? "").split("\n")) {
+    if (line.startsWith("p")) pid = Number.parseInt(line.slice(1), 10);
+    else if (line.startsWith("n") && pid > 0) cwds.set(pid, line.slice(1));
+  }
+  return cwds;
+}
+function run(program, args) {
+  return new Promise((resolve) => {
+    execFile(program, args, { timeout: PROCESS_READ_TIMEOUT_MILLIS }, (err, stdout) => {
+      const output = String(stdout ?? "");
+      resolve(err && output === "" ? null : output);
+    });
+  });
+}
+async function readOrNull(read) {
+  try {
+    return await read();
+  } catch {
+    return null;
+  }
+}
+
+// src/devices/terminal/screenMirror.ts
+import { createRequire } from "module";
+var SCROLLBACK_LINES = 1e3;
+var MAX_SNAPSHOT_BYTES = 1024 * 1024;
+var SCROLLBACK_LINES_TO_TRY = [SCROLLBACK_LINES, 200, 0];
+var require2 = createRequire(import.meta.url);
+var loadedModules;
+function loadModules() {
+  if (loadedModules !== void 0) return loadedModules;
+  try {
+    const headless = require2("@xterm/headless");
+    const serialize = require2("@xterm/addon-serialize");
+    loadedModules = { Terminal: headless.Terminal, SerializeAddon: serialize.SerializeAddon };
+  } catch (err) {
+    logger.warn("Screen restore unavailable: the headless terminal did not load", { error: errorName(err) });
+    loadedModules = null;
+  }
+  return loadedModules;
+}
+function isScreenMirrorSupported() {
+  return loadModules() !== null;
+}
+var ScreenMirror = class _ScreenMirror {
+  constructor(terminal, serializer) {
+    this.terminal = terminal;
+    this.serializer = serializer;
+    this.disposed = false;
+  }
+  /** Null when the headless terminal cannot load. The shell then works as before, without restore. */
+  static create(cols, rows) {
+    const modules = loadModules();
+    if (!modules) return null;
+    const terminal = new modules.Terminal({ cols, rows, scrollback: SCROLLBACK_LINES, allowProposedApi: true });
+    const serializer = new modules.SerializeAddon();
+    terminal.loadAddon(serializer);
+    return new _ScreenMirror(terminal, serializer);
+  }
+  /** Bytes exactly as they were sent. xterm parses them later, in order, and joins split characters. */
+  feed(bytes) {
+    if (!this.disposed) this.terminal.write(bytes);
+  }
+  resize(cols, rows) {
+    if (!this.disposed) this.terminal.resize(cols, rows);
+  }
+  /**
+   * The screen after everything fed before this call, and nothing fed after it. Null when the
+   * mirror was disposed first.
+   *
+   * xterm parses writes in batches, on a timer. An empty write queued now has its callback run
+   * after every earlier chunk is parsed and before the next one is, so serialising inside it sees
+   * exactly what was fed before this call.
+   */
+  snapshot() {
+    return new Promise((resolve) => {
+      if (this.disposed) {
+        resolve(null);
+        return;
+      }
+      this.terminal.write("", () => resolve(this.disposed ? null : this.serialise()));
+    });
+  }
+  dispose() {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.terminal.dispose();
+  }
+  /** Null when even the screen alone is over the cap. The tab then waits out its fallback. */
+  serialise() {
+    for (const scrollback of SCROLLBACK_LINES_TO_TRY) {
+      const text = this.serializer.serialize({ scrollback });
+      if (Buffer.byteLength(text, "utf-8") <= MAX_SNAPSHOT_BYTES) {
+        return { text, cols: this.terminal.cols, rows: this.terminal.rows };
+      }
+    }
+    return null;
+  }
+};
+function errorName(err) {
+  return err instanceof Error ? err.name : typeof err;
+}
+
+// src/devices/terminal/terminalHandler.ts
+var DEFAULT_COLS = 80;
+var DEFAULT_ROWS = 24;
+var EXPIRY_CHECK_MILLIS = 5e3;
+var MILLIS_PER_SECOND = 1e3;
+var TerminalHandler = class {
+  constructor(dependencies) {
+    this.dependencies = dependencies;
+    this.enabled = true;
+    this.suspended = false;
+    this.expiryTimer = null;
+    this.contextTimer = null;
+    this.contextPollInFlight = false;
+    this.contextTracker = new ShellContextTracker();
+    this.streams = /* @__PURE__ */ new Map();
+  }
+  /**
+   * From welcome. An older dashboard sends no terminal fields, and `terminal_enabled` and the
+   * per-device ceiling keep their defaults.
+   *
+   * The window has no default. A compiled-in one keeps working after the dashboard stops sending
+   * the field, and nobody notices until a node falls over, so an agent without one refuses to open
+   * a terminal at all.
+   */
+  configure(terminalEnabled, maxTerminalsPerDevice, terminalWindowBytes, maxFrameBytes, idleTimeoutSeconds, maxSessionSeconds) {
+    if (terminalEnabled !== void 0) this.enabled = terminalEnabled;
+    if (maxTerminalsPerDevice !== void 0) this.dependencies.registry.setMaxTerminals(maxTerminalsPerDevice);
+    this.windowBytes = terminalWindowBytes;
+    this.bundleBytes = rawBundleBytes(maxFrameBytes);
+    if (terminalWindowBytes === void 0) {
+      logger.info("Terminals unavailable: welcome carried no terminal_window_bytes");
+    }
+    this.idleTimeoutMillis = positiveMillis(idleTimeoutSeconds);
+    this.maxSessionMillis = positiveMillis(maxSessionSeconds);
+    this.startExpiryTimer();
+  }
+  /**
+   * Ends every shell past its idle timeout or its max-session cap. Runs on a timer; public so a test
+   * decides when. The cap goes first: a shell both idle and too old is closed for the rule typing
+   * cannot reset.
+   */
+  expireShells() {
+    if (this.suspended) return;
+    const nowMillis = this.nowMillis();
+    for (const [terminalId, stream] of [...this.streams.entries()]) {
+      if (this.maxSessionMillis !== void 0 && nowMillis - stream.openedAtMillis >= this.maxSessionMillis) {
+        this.expire(terminalId, CLOSE_REASON_MAX_SESSION);
+      } else if (this.idleTimeoutMillis !== void 0 && nowMillis - stream.lastActivityMillis >= this.idleTimeoutMillis) {
+        this.expire(terminalId, CLOSE_REASON_IDLE_TIMEOUT);
+      }
+    }
+  }
+  handle(envelope) {
+    if (envelope.op === OP_OPEN) {
+      this.open(envelope);
+    } else if (envelope.op === OP_CLOSE) {
+      this.closeFromDashboard(envelope);
+    } else if (envelope.op === OP_ACK) {
+      this.acknowledge(envelope);
+    } else if (envelope.op === OP_RESIZE) {
+      this.resize(envelope);
+    } else if (envelope.op === OP_DATA) {
+      this.input(envelope);
+    } else if (envelope.op === OP_SIGNAL) {
+      this.signal(envelope);
+    } else if (envelope.op === OP_SNAPSHOT) {
+      void this.snapshot(envelope);
+    } else {
+      logger.debug("Ignoring unhandled terminal op", { op: envelope.op });
+    }
+  }
+  /**
+   * The agent is stopping: interrupted, revoked, or refused for good. Every shell dies with it.
+   * A dropped socket is not this; it is `suspend`.
+   */
+  closeAll() {
+    this.stopExpiryTimer();
+    this.stopContextTimer();
+    this.contextTracker.clear();
+    this.suspended = false;
+    for (const stream of this.streams.values()) {
+      stream.splitter.dispose();
+      stream.mirror?.dispose();
+    }
+    this.streams.clear();
+    this.dependencies.registry.killAll();
+  }
+  /**
+   * The socket dropped and the agent will redial. Every shell stops being read and keeps running.
+   * Whatever it prints waits in the kernel, and the shell blocks once that buffer is full.
+   */
+  suspend() {
+    if (this.suspended) return;
+    this.suspended = true;
+    for (const [terminalId, session] of this.dependencies.registry.entries()) {
+      try {
+        session.pause();
+      } catch (err) {
+        logger.warn("Terminal pause failed", { terminal_id: terminalId, error: errorName2(err) });
+      }
+    }
+    logger.info("Terminals suspended until the dashboard is back", { count: this.dependencies.registry.size() });
+  }
+  /**
+   * `welcome` arrived. Every shell the dashboard did not close is read again, except one whose
+   * window is still full. That one resumes on the `ack` that reopens it.
+   */
+  resumeAll() {
+    if (!this.suspended) return;
+    this.suspended = false;
+    for (const [terminalId, session] of this.dependencies.registry.entries()) {
+      const stream = this.streams.get(terminalId);
+      if (stream) {
+        for (const chunk of stream.heldBundles.splice(0)) {
+          this.sendData(terminalId, chunk);
+        }
+      }
+      if (stream?.paused) continue;
+      try {
+        session.resume();
+      } catch (err) {
+        logger.warn("Terminal resume failed", { terminal_id: terminalId, error: errorName2(err) });
+      }
+    }
+    for (const context of this.contextTracker.current()) {
+      if (this.streams.has(context.terminal_id)) {
+        this.dependencies.send(event(CHANNEL_TERMINAL, OP_CONTEXT, context));
+      }
+    }
+  }
+  /**
+   * Reads every open shell's directory and foreground program, and sends `context` for each that
+   * changed. Runs on a timer while any shell is open; public so a test decides when. Never throws,
+   * and never moves a shell's idle clock.
+   */
+  async pollShellContexts() {
+    const read = this.dependencies.readShellContexts;
+    if (!read || this.suspended || this.contextPollInFlight || this.streams.size === 0) return;
+    this.contextPollInFlight = true;
+    try {
+      const terminalIdsByPid = /* @__PURE__ */ new Map();
+      for (const [terminalId, stream] of this.streams) {
+        terminalIdsByPid.set(stream.session.pid, terminalId);
+      }
+      const contexts = await read([...terminalIdsByPid.keys()]);
+      if (this.suspended) return;
+      for (const [shellPid, raw] of contexts) {
+        const terminalId = terminalIdsByPid.get(shellPid);
+        if (!terminalId || !this.streams.has(terminalId)) continue;
+        const changed = this.contextTracker.observe(terminalId, raw, this.dependencies.resolvedHome ?? null);
+        if (changed) this.dependencies.send(event(CHANNEL_TERMINAL, OP_CONTEXT, changed));
+      }
+    } catch (err) {
+      logger.debug("Shell context poll failed", { error: errorName2(err) });
+    } finally {
+      this.contextPollInFlight = false;
+    }
+  }
+  /** What `hello` lists: every shell still held, so the dashboard can keep it. */
+  held() {
+    return this.dependencies.registry.entries().map(([terminalId, session]) => ({
+      terminal_id: terminalId,
+      pid: session.pid,
+      shell: session.shell,
+      cols: session.cols,
+      rows: session.rows
+    }));
+  }
+  open(envelope) {
+    const parsed = TerminalOpenSchema.safeParse(envelope.payload);
+    if (!parsed.success) {
+      this.refuse(envelope, null, ERROR_INVALID_PAYLOAD2, "open payload could not be read.");
+      return;
+    }
+    const request2 = parsed.data;
+    const { registry } = this.dependencies;
+    if (!this.enabled || this.windowBytes === void 0 || this.bundleBytes === void 0) {
+      this.refuse(envelope, request2.terminal_id, ERROR_TERMINAL_DISABLED, "Terminals are disabled.");
+      return;
+    }
+    if (registry.has(request2.terminal_id) || registry.isFull()) {
+      this.refuse(
+        envelope,
+        request2.terminal_id,
+        ERROR_TERMINAL_LIMIT_REACHED,
+        "Too many terminals are already open on this machine."
+      );
+      return;
+    }
+    const resolution = this.dependencies.resolveShell(request2.shell);
+    if ("error" in resolution) {
+      this.refuse(envelope, request2.terminal_id, ERROR_SHELL_NOT_ALLOWED, resolution.error);
+      return;
+    }
+    const cols = clampGrid(request2.cols, DEFAULT_COLS);
+    const rows = clampGrid(request2.rows, DEFAULT_ROWS);
+    let session;
+    try {
+      session = this.dependencies.spawn({ shell: resolution.shell, cwd: request2.cwd, cols, rows });
+    } catch (err) {
+      logger.warn("Terminal spawn failed", { terminal_id: request2.terminal_id, error: errorName2(err) });
+      this.refuse(envelope, request2.terminal_id, ERROR_SPAWN_FAILED, "The shell could not be started.");
+      return;
+    }
+    if (!registry.add(request2.terminal_id, session)) {
+      session.kill();
+      this.refuse(
+        envelope,
+        request2.terminal_id,
+        ERROR_TERMINAL_LIMIT_REACHED,
+        "Too many terminals are already open on this machine."
+      );
+      return;
+    }
+    this.startStream(request2.terminal_id, session, this.windowBytes, this.bundleBytes);
+    logger.info("Terminal opened", { terminal_id: request2.terminal_id, pid: session.pid });
+    const opened = {
+      terminal_id: request2.terminal_id,
+      pid: session.pid,
+      shell: session.shell,
+      cols,
+      rows
+    };
+    this.dependencies.send(response(envelope, OP_OPENED, opened));
+  }
+  startStream(terminalId, session, windowBytes, bundleBytes) {
+    const openedAtMillis = this.nowMillis();
+    const stream = {
+      session,
+      window: new FlowWindow(windowBytes),
+      splitter: new FrameSplitter((chunk) => this.sendData(terminalId, chunk), bundleBytes),
+      mirror: ScreenMirror.create(session.cols, session.rows),
+      paused: false,
+      sentSeq: 0,
+      heldBundles: [],
+      openedAtMillis,
+      lastActivityMillis: openedAtMillis
+    };
+    this.streams.set(terminalId, stream);
+    this.startContextTimer();
+    session.onData((chunk) => {
+      stream.lastActivityMillis = this.nowMillis();
+      stream.splitter.push(chunk);
+    });
+    session.onExit((exitCode, signal) => {
+      if (this.dependencies.registry.remove(terminalId) === void 0) return;
+      stream.splitter.flush();
+      stream.splitter.dispose();
+      this.forgetStream(terminalId);
+      logger.info("Terminal shell exited", { terminal_id: terminalId, exit_code: exitCode, signal });
+      const exit = signal ? { terminal_id: terminalId, exit_code: null, signal: signalName(signal) } : { terminal_id: terminalId, exit_code: exitCode, signal: null };
+      this.dependencies.send(event(CHANNEL_TERMINAL, OP_EXIT, exit));
+      this.dependencies.send(event(
+        CHANNEL_TERMINAL,
+        OP_CLOSE,
+        { terminal_id: terminalId, reason: CLOSE_REASON_USER_CLOSED }
+      ));
+    });
+  }
+  /**
+   * 1 bundle leaves, and the window narrows by what it carried.
+   *
+   * The pause happens after the send rather than before. These bytes are already out of the pty,
+   * and holding them is the buffering this whole mechanism exists to avoid.
+   *
+   * While the socket is down the bundle is held instead, and neither counts against the window nor
+   * takes a seq. Sent into no socket, it would be a seq the dashboard never sees and bytes nobody
+   * can ack, and the window would never reopen.
+   *
+   * The mirror is fed here, in the same tick as the seq, and nowhere else. A snapshot then holds
+   * exactly the bundles up to its `after_seq`. Fed when the pty is read, a bundle still being cut
+   * would be in the screen and drawn a second time when it is sent.
+   */
+  sendData(terminalId, chunk) {
+    const stream = this.streams.get(terminalId);
+    if (!stream) return;
+    if (this.suspended) {
+      stream.heldBundles.push(chunk);
+      return;
+    }
+    stream.sentSeq += 1;
+    stream.mirror?.feed(chunk);
+    const data = { terminal_id: terminalId, data: chunk.toString("base64") };
+    this.dependencies.send({ ...event(CHANNEL_TERMINAL, OP_DATA, data), seq: stream.sentSeq });
+    stream.window.recordSent(chunk.length);
+    if (!stream.window.isOpen() && !stream.paused) {
+      stream.paused = true;
+      stream.session.pause();
+      logger.debug("Terminal window full, reads paused", { terminal_id: terminalId });
+    }
+  }
+  acknowledge(envelope) {
+    const parsed = TerminalAckSchema.safeParse(envelope.payload);
+    if (!parsed.success) return;
+    const stream = this.streams.get(parsed.data.terminal_id);
+    if (!stream) return;
+    stream.window.recordAck(parsed.data.ack_bytes);
+    if (stream.paused && stream.window.isOpen()) {
+      stream.paused = false;
+      if (this.suspended) return;
+      stream.session.resume();
+      logger.debug("Terminal window reopened, reads resumed", { terminal_id: parsed.data.terminal_id });
+    }
+  }
+  closeFromDashboard(envelope) {
+    const parsed = TerminalCloseSchema.safeParse(envelope.payload);
+    if (!parsed.success) return;
+    const session = this.dependencies.registry.remove(parsed.data.terminal_id);
+    if (!session) return;
+    const stream = this.streams.get(parsed.data.terminal_id);
+    this.forgetStream(parsed.data.terminal_id);
+    stream?.splitter.dispose();
+    logger.info("Terminal closed by the dashboard", { terminal_id: parsed.data.terminal_id, pid: session.pid });
+    try {
+      session.kill();
+    } catch {
+    }
+  }
+  /**
+   * The tabs watching this shell changed size. Clamped like `open`, and a gone shell is ignored.
+   * The pty is resized only on an actual change: every call is a `TIOCSWINSZ` and a SIGWINCH, and
+   * a full-screen program redraws on each one.
+   */
+  resize(envelope) {
+    const parsed = TerminalResizeSchema.safeParse(envelope.payload);
+    if (!parsed.success) return;
+    const session = this.dependencies.registry.get(parsed.data.terminal_id);
+    if (!session) return;
+    this.markActive(parsed.data.terminal_id);
+    const cols = clampGrid(parsed.data.cols, session.cols);
+    const rows = clampGrid(parsed.data.rows, session.rows);
+    if (cols === session.cols && rows === session.rows) return;
+    try {
+      session.resize(cols, rows);
+      this.streams.get(parsed.data.terminal_id)?.mirror?.resize(cols, rows);
+    } catch (err) {
+      logger.debug("Terminal resize failed", { terminal_id: parsed.data.terminal_id, error: errorName2(err) });
+    }
+  }
+  /** Keystrokes, written as raw bytes. A gone shell is ignored. Never logged: this is what a person typed. */
+  input(envelope) {
+    const parsed = TerminalInputSchema.safeParse(envelope.payload);
+    if (!parsed.success) return;
+    const session = this.dependencies.registry.get(parsed.data.terminal_id);
+    if (!session) return;
+    this.markActive(parsed.data.terminal_id);
+    try {
+      session.write(Buffer.from(parsed.data.data, "base64"));
+    } catch (err) {
+      logger.debug("Terminal write failed", { terminal_id: parsed.data.terminal_id, error: errorName2(err) });
+    }
+  }
+  /** 1 allowlisted signal to the foreground process group. Anything else fails to parse and is dropped. */
+  signal(envelope) {
+    const parsed = TerminalSignalSchema.safeParse(envelope.payload);
+    if (!parsed.success) {
+      logger.debug("Ignoring a terminal signal outside the allowlist");
+      return;
+    }
+    const session = this.dependencies.registry.get(parsed.data.terminal_id);
+    if (!session) return;
+    this.markActive(parsed.data.terminal_id);
+    session.signalForeground(parsed.data.signal);
+  }
+  markActive(terminalId) {
+    const stream = this.streams.get(terminalId);
+    if (stream) stream.lastActivityMillis = this.nowMillis();
+  }
+  /**
+   * Removed from the registry before the kill, so its exit callback finds nothing and sends no
+   * `user_closed`. The output already read goes out first, then `close` with the reason.
+   */
+  expire(terminalId, reason) {
+    const session = this.dependencies.registry.remove(terminalId);
+    const stream = this.streams.get(terminalId);
+    this.forgetStream(terminalId);
+    stream?.splitter.flush();
+    stream?.splitter.dispose();
+    if (!session) return;
+    logger.info("Terminal expired", { terminal_id: terminalId, pid: session.pid, reason });
+    try {
+      session.kill();
+    } catch {
+    }
+    this.dependencies.send(event(CHANNEL_TERMINAL, OP_CLOSE, { terminal_id: terminalId, reason }));
+  }
+  /**
+   * A tab attached and asked for the screen it missed (slice T6). Answered in parts, each 1 frame,
+   * which the dashboard routes to that tab alone.
+   *
+   * `after_seq` and `after_bytes` are read in the same tick as the request, before the mirror is
+   * asked, so they name exactly the bundles the screen holds. The parts go out even with the window
+   * closed: they are not pty output, so they take no seq and the window never counts them. A request
+   * for a shell that is gone, or a screen too big to send, is not answered; the tab falls back.
+   */
+  async snapshot(envelope) {
+    const parsed = TerminalSnapshotRequestSchema.safeParse(envelope.payload);
+    if (!parsed.success || this.bundleBytes === void 0) return;
+    const { terminal_id: terminalId, snapshot_id: snapshotId } = parsed.data;
+    const stream = this.streams.get(terminalId);
+    if (!stream?.mirror) return;
+    const afterSeq = stream.sentSeq;
+    const afterBytes = stream.window.sent;
+    const screen = await stream.mirror.snapshot();
+    if (!screen || this.suspended || this.streams.get(terminalId) !== stream) return;
+    const parts = splitIntoParts(Buffer.from(screen.text, "utf-8"), this.bundleBytes);
+    parts.forEach((part, index) => {
+      const payload = {
+        terminal_id: terminalId,
+        snapshot_id: snapshotId,
+        part: index,
+        last: index === parts.length - 1,
+        after_seq: afterSeq,
+        after_bytes: afterBytes,
+        cols: screen.cols,
+        rows: screen.rows,
+        data: part.toString("base64")
+      };
+      this.dependencies.send(event(CHANNEL_TERMINAL, OP_SNAPSHOT, payload));
+    });
+    logger.debug("Terminal screen sent", { terminal_id: terminalId, parts: parts.length, after_seq: afterSeq });
+  }
+  /** A shell is gone. The context poll stops with the last one, so an idle agent spawns nothing. */
+  forgetStream(terminalId) {
+    this.streams.get(terminalId)?.mirror?.dispose();
+    this.streams.delete(terminalId);
+    this.contextTracker.forget(terminalId);
+    if (this.streams.size === 0) this.stopContextTimer();
+  }
+  startContextTimer() {
+    if (this.contextTimer || !this.dependencies.readShellContexts) return;
+    this.contextTimer = setInterval(() => void this.pollShellContexts(), SHELL_CONTEXT_POLL_MILLIS);
+    this.contextTimer.unref();
+  }
+  stopContextTimer() {
+    if (this.contextTimer) {
+      clearInterval(this.contextTimer);
+      this.contextTimer = null;
+    }
+  }
+  startExpiryTimer() {
+    if (this.expiryTimer || this.idleTimeoutMillis === void 0 && this.maxSessionMillis === void 0) {
+      return;
+    }
+    this.expiryTimer = setInterval(() => this.expireShells(), EXPIRY_CHECK_MILLIS);
+    this.expiryTimer.unref();
+  }
+  stopExpiryTimer() {
+    if (this.expiryTimer) {
+      clearInterval(this.expiryTimer);
+      this.expiryTimer = null;
+    }
+  }
+  nowMillis() {
+    return this.dependencies.now ? this.dependencies.now() : Date.now();
+  }
+  refuse(envelope, terminalId, code, message) {
+    logger.info("Terminal open refused", { terminal_id: terminalId, code });
+    const refused = { terminal_id: terminalId, error: { code, message } };
+    this.dependencies.send(response(envelope, OP_OPENED, refused));
+  }
+};
+function positiveMillis(seconds) {
+  return seconds !== void 0 && Number.isFinite(seconds) && seconds > 0 ? seconds * MILLIS_PER_SECOND : void 0;
+}
+function splitIntoParts(bytes, partBytes) {
+  const parts = [];
+  for (let offset = 0; offset < bytes.length; offset += partBytes) {
+    parts.push(bytes.subarray(offset, offset + partBytes));
+  }
+  return parts.length > 0 ? parts : [Buffer.alloc(0)];
+}
+function errorName2(err) {
+  return err instanceof Error ? err.name : typeof err;
+}
+function signalName(signal) {
+  for (const [name, number] of Object.entries(os6.constants.signals)) {
+    if (number === signal) return name.replace(/^SIG/, "");
+  }
+  return String(signal);
+}
+
+// src/devices/terminal/terminalRegistry.ts
+var DEFAULT_MAX_TERMINALS = 3;
+var TerminalRegistry = class {
+  constructor() {
+    this.handlesById = /* @__PURE__ */ new Map();
+    this.maxTerminals = DEFAULT_MAX_TERMINALS;
+  }
+  setMaxTerminals(maxTerminals) {
+    if (Number.isInteger(maxTerminals) && maxTerminals > 0) {
+      this.maxTerminals = maxTerminals;
+    }
+  }
+  has(terminalId) {
+    return this.handlesById.has(terminalId);
+  }
+  isFull() {
+    return this.handlesById.size >= this.maxTerminals;
+  }
+  /** False when the id is already taken or the ceiling is reached. The caller then kills the handle. */
+  add(terminalId, handle) {
+    if (this.handlesById.has(terminalId) || this.isFull()) return false;
+    this.handlesById.set(terminalId, handle);
+    return true;
+  }
+  get(terminalId) {
+    return this.handlesById.get(terminalId);
+  }
+  /** Removes and returns the handle. Undefined the second time, so a close runs at most once. */
+  remove(terminalId) {
+    const handle = this.handlesById.get(terminalId);
+    this.handlesById.delete(terminalId);
+    return handle;
+  }
+  /** Every held shell with its id, in the order it was added. */
+  entries() {
+    return [...this.handlesById.entries()];
+  }
+  size() {
+    return this.handlesById.size;
+  }
+  /** Removes every handle before killing any, so no exit callback finds itself still registered. */
+  killAll() {
+    const handles = [...this.handlesById.values()];
+    this.handlesById.clear();
+    for (const handle of handles) {
+      try {
+        handle.kill();
+      } catch {
+      }
+    }
+  }
+};
+
+// src/devices/terminal/ptySession.ts
+import { execFile as execFile2 } from "child_process";
+import fs6 from "fs";
+import os7 from "os";
+
+// src/devices/terminal/nodePtyRuntime.ts
+import fs5 from "fs";
+import path3 from "path";
+import { createRequire as createRequire2 } from "module";
+var require3 = createRequire2(import.meta.url);
+var PACKAGE_NAME = "node-pty";
+var NATIVE_FILE = "pty.node";
+var SPAWN_HELPER_FILE = "spawn-helper";
+var EXECUTABLE_MODE = 493;
+var EXECUTE_BITS = 73;
+var RUNTIME_DIR_NAME = "runtime";
+var ASAR_ARCHIVE_SUFFIX = ".asar";
+var NATIVE_DIRECTORIES = [
+  path3.join("build", "Release"),
+  path3.join("prebuilds", `${process.platform}-${process.arch}`)
+];
+function isPackagedBinary() {
+  return Boolean(process.pkg);
+}
+function isInsideAsarArchive(packageRoot) {
+  if (!process.versions.electron) return false;
+  return packageRoot.split(path3.sep).some((segment) => segment.endsWith(ASAR_ARCHIVE_SUFFIX));
+}
+function resolveNodePtyRoot() {
+  const resolvedRoot = path3.dirname(require3.resolve(`${PACKAGE_NAME}/package.json`));
+  if (!isPackagedBinary() && !isInsideAsarArchive(resolvedRoot)) return resolvedRoot;
+  return unpackNodePty(resolvedRoot);
+}
+function requireNodePty(packageRoot) {
+  return require3(packageRoot);
+}
+function spawnHelperPaths(packageRoot) {
+  if (process.platform === "win32") return [];
+  return NATIVE_DIRECTORIES.map((directory) => path3.join(packageRoot, directory, SPAWN_HELPER_FILE));
+}
+function hasExecutableSpawnHelper(packageRoot) {
+  const helpers = spawnHelperPaths(packageRoot);
+  if (helpers.length === 0) return true;
+  return helpers.some((helper) => {
+    try {
+      const stat = fs5.statSync(helper);
+      return stat.isFile() && (stat.mode & EXECUTE_BITS) !== 0;
+    } catch {
+      return false;
+    }
+  });
+}
+function makeSpawnHelperExecutable(packageRoot) {
+  for (const helper of spawnHelperPaths(packageRoot)) {
+    try {
+      const stat = fs5.statSync(helper);
+      if ((stat.mode & EXECUTE_BITS) === 0) {
+        fs5.chmodSync(helper, EXECUTABLE_MODE);
+      }
+    } catch {
+    }
+  }
+}
+function unpackNodePty(snapshotRoot) {
+  const unpackedRoot = unpackedRootPath(snapshotRoot);
+  if (isLoadable(unpackedRoot)) return unpackedRoot;
+  const stagingRoot = `${unpackedRoot}.${process.pid}`;
+  fs5.rmSync(stagingRoot, { recursive: true, force: true });
+  try {
+    copyRuntimeFiles(snapshotRoot, stagingRoot);
+    makeSpawnHelperExecutable(stagingRoot);
+    fs5.renameSync(stagingRoot, unpackedRoot);
+  } catch (error) {
+    fs5.rmSync(stagingRoot, { recursive: true, force: true });
+    if (!isLoadable(unpackedRoot)) throw error;
+  }
+  return unpackedRoot;
+}
+function unpackedRootPath(snapshotRoot) {
+  const version = readPackageVersion(snapshotRoot);
+  const directoryName = `${PACKAGE_NAME}-${version}-${process.platform}-${process.arch}`;
+  return path3.join(getPinggyConfigDir(), RUNTIME_DIR_NAME, directoryName);
+}
+function readPackageVersion(packageRoot) {
+  const manifest = JSON.parse(fs5.readFileSync(path3.join(packageRoot, "package.json"), "utf8"));
+  return String(manifest.version);
+}
+function isLoadable(packageRoot) {
+  if (!fs5.existsSync(path3.join(packageRoot, "package.json"))) return false;
+  return NATIVE_DIRECTORIES.some((directory) => fs5.existsSync(path3.join(packageRoot, directory, NATIVE_FILE)));
+}
+function copyRuntimeFiles(sourceRoot, targetRoot) {
+  fs5.mkdirSync(targetRoot, { recursive: true });
+  copyFile(path3.join(sourceRoot, "package.json"), path3.join(targetRoot, "package.json"));
+  copyDirectory(path3.join(sourceRoot, "lib"), path3.join(targetRoot, "lib"));
+  for (const directory of NATIVE_DIRECTORIES) {
+    const source = path3.join(sourceRoot, directory);
+    if (fs5.existsSync(source)) {
+      copyDirectory(source, path3.join(targetRoot, directory));
+    }
+  }
+}
+function copyDirectory(sourceDirectory, targetDirectory) {
+  fs5.mkdirSync(targetDirectory, { recursive: true });
+  for (const entry of fs5.readdirSync(sourceDirectory, { withFileTypes: true })) {
+    const source = path3.join(sourceDirectory, entry.name);
+    const target = path3.join(targetDirectory, entry.name);
+    if (entry.isDirectory()) {
+      copyDirectory(source, target);
+      continue;
+    }
+    copyFile(source, target);
+  }
+}
+function copyFile(source, target) {
+  fs5.writeFileSync(target, fs5.readFileSync(source));
+}
+
+// src/devices/terminal/ptySession.ts
+var loadedPty;
+var TERM_NAME = "xterm-256color";
+function foregroundProcessGroup(shellPid) {
+  return new Promise((resolve) => {
+    execFile2("ps", ["-o", "tpgid=", "-p", String(shellPid)], (err, stdout) => {
+      const processGroupId = err ? NaN : Number.parseInt(String(stdout).trim(), 10);
+      resolve(Number.isInteger(processGroupId) && processGroupId > 0 ? processGroupId : null);
+    });
+  });
+}
+async function signalForegroundGroup(shellPid, signal) {
+  if (process.platform === "win32") {
+    logger.debug("Terminal signal ignored on Windows", { pid: shellPid, signal });
+    return;
+  }
+  const processGroupId = await foregroundProcessGroup(shellPid) ?? shellPid;
+  try {
+    process.kill(-processGroupId, `SIG${signal}`);
+  } catch (err) {
+    logger.debug("Terminal signal not delivered", {
+      pid: shellPid,
+      signal,
+      error: err instanceof Error ? err.name : typeof err
+    });
+  }
+}
+function loadNodePty() {
+  if (loadedPty !== void 0) return loadedPty;
+  try {
+    const packageRoot = resolveNodePtyRoot();
+    const pty = requireNodePty(packageRoot);
+    ensureSpawnHelperExecutable(packageRoot);
+    loadedPty = hasExecutableSpawnHelper(packageRoot) ? pty : null;
+  } catch {
+    loadedPty = null;
+  }
+  return loadedPty;
+}
+function isTerminalSupported() {
+  return loadNodePty() !== null;
+}
+function ensureSpawnHelperExecutable(packageRoot) {
+  makeSpawnHelperExecutable(packageRoot ?? resolveNodePtyRoot());
+}
+function resolveCwd(requested) {
+  if (requested) {
+    try {
+      if (fs6.statSync(requested).isDirectory()) return requested;
+    } catch {
+    }
+  }
+  return os7.homedir();
+}
+function spawnPty(request2) {
+  const pty = loadNodePty();
+  if (!pty) {
+    throw new Error("node-pty is not available on this machine");
+  }
+  const process_ = pty.spawn(request2.shell, [], {
+    name: TERM_NAME,
+    cols: request2.cols,
+    rows: request2.rows,
+    cwd: resolveCwd(request2.cwd),
+    env: { ...process.env, TERM: TERM_NAME },
+    // Buffers rather than strings. node-pty decodes per read otherwise, and a read that ends
+    // mid-character yields a replacement character the browser can never recover.
+    encoding: null
+  });
+  return {
+    pid: process_.pid,
+    shell: request2.shell,
+    get cols() {
+      return process_.cols;
+    },
+    get rows() {
+      return process_.rows;
+    },
+    kill: () => process_.kill(),
+    onExit: (listener) => {
+      process_.onExit(({ exitCode, signal }) => listener(exitCode, signal));
+    },
+    onData: (listener) => {
+      process_.onData((chunk) => {
+        listener(typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk);
+      });
+    },
+    pause: () => process_.pause(),
+    resume: () => process_.resume(),
+    resize: (cols, rows) => process_.resize(cols, rows),
+    write: (bytes) => process_.write(bytes),
+    signalForeground: (signal) => {
+      void signalForegroundGroup(process_.pid, signal);
+    }
+  };
+}
+
+// src/devices/terminal/shellAllowlist.ts
+import fs7 from "fs";
+var FALLBACK_UNIX_SHELLS = ["/bin/bash", "/bin/zsh", "/bin/sh", "/usr/bin/bash", "/usr/bin/zsh"];
+var WINDOWS_SHELLS = ["powershell.exe", "cmd.exe"];
+var ETC_SHELLS_PATH = "/etc/shells";
+function readShellEnvironment() {
+  let etcShells = null;
+  try {
+    etcShells = fs7.readFileSync(ETC_SHELLS_PATH, "utf8");
+  } catch {
+    etcShells = null;
+  }
+  return {
+    platform: process.platform,
+    loginShell: process.env.SHELL,
+    etcShells,
+    exists: (path6) => {
+      try {
+        return fs7.statSync(path6).isFile();
+      } catch {
+        return false;
+      }
+    }
+  };
+}
+function parseEtcShells(contents) {
+  return contents.split(/\r?\n/).map((line) => line.trim()).filter((line) => line.startsWith("/"));
+}
+function allowedShells(environment) {
+  if (environment.platform === "win32") return WINDOWS_SHELLS;
+  const listed = environment.etcShells === null ? [] : parseEtcShells(environment.etcShells);
+  return listed.length > 0 ? listed : FALLBACK_UNIX_SHELLS;
+}
+function resolveShell(requested, environment) {
+  const allowed = allowedShells(environment);
+  const usable = (shell) => environment.platform === "win32" || environment.exists(shell);
+  if (requested !== null && requested !== void 0) {
+    if (allowed.includes(requested) && usable(requested)) {
+      return { shell: requested };
+    }
+    return { error: "That shell is not allowed on this machine." };
+  }
+  const loginShell = environment.loginShell;
+  if (loginShell && allowed.includes(loginShell) && usable(loginShell)) {
+    return { shell: loginShell };
+  }
+  const firstUsable = allowed.find(usable);
+  return firstUsable ? { shell: firstUsable } : { error: "No allowed shell exists on this machine." };
+}
+
+// src/devices/deviceAgent.ts
+var CLOSE_CODE_REVOKED = 4001;
+var CLOSE_CODE_NORMAL = 1e3;
+var CLOSE_TIMEOUT_MILLIS = 3e3;
+var TOKEN_HEADER = "X-Pinggy-Device-Token";
+var DEFAULT_SERVER = "dashboard.pinggy.io";
+var ERROR_ALREADY_CONNECTED = "already_connected";
+var AGENT_ERROR_UNAUTHORIZED = "unauthorized";
+var AGENT_ERROR_HANDSHAKE_REFUSED = "handshake_refused";
+var AGENT_ERROR_DISCONNECTED = "disconnected";
+var AGENT_ERROR_NOT_CONNECTED = "not_connected";
+var HANDSHAKE_TIMEOUT_MILLIS = 3e4;
+var PONG_GRACE_INTERVALS = 2;
+var BASE_CAPABILITIES = ["tunnel", "stats", "tunnel_control", "tunnel_update", "saved_config_update"];
+var CAPABILITY_TERMINAL = "terminal";
+var CAPABILITY_TERMINAL_SNAPSHOT = "terminal_snapshot";
+function buildCapabilities(terminalSupported, screenRestoreSupported = false) {
+  if (!terminalSupported) return BASE_CAPABILITIES;
+  return screenRestoreSupported ? [...BASE_CAPABILITIES, CAPABILITY_TERMINAL, CAPABILITY_TERMINAL_SNAPSHOT] : [...BASE_CAPABILITIES, CAPABILITY_TERMINAL];
+}
+function buildDeviceAgentWsUrl(manage) {
+  let baseUrl = (manage || DEFAULT_SERVER).trim();
+  if (!(baseUrl.startsWith("ws://") || baseUrl.startsWith("wss://"))) {
+    baseUrl = "wss://" + baseUrl;
+  }
+  return `${baseUrl.replace(/\/$/, "")}/backend/api/v1/device-agent/ws/connect`;
+}
+function sleep(millis, state) {
+  return new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      state.cancelPendingSleep = null;
+      resolve();
+    }, millis);
+    state.cancelPendingSleep = () => {
+      clearTimeout(timer);
+      state.cancelPendingSleep = null;
+      resolve();
+    };
+  });
+}
+function buildHello(terminalHandler) {
+  return {
+    agent_version: getVersion(),
+    os: os8.platform(),
+    hostname: os8.hostname(),
+    capabilities: buildCapabilities(isTerminalSupported(), isScreenMirrorSupported()),
+    terminals: terminalHandler.held()
+  };
+}
+function startMetricsReporting(intervalSeconds, collect, send) {
+  let stopped = false;
+  const report = () => {
+    collect().then((metrics) => {
+      if (!stopped) send(metrics);
+    }).catch((err) => logger.warn("Device metrics collection failed", { error: String(err) }));
+  };
+  report();
+  const timer = setInterval(report, intervalSeconds * 1e3);
+  return () => {
+    stopped = true;
+    clearInterval(timer);
+  };
+}
+function identityForRun(token, server, stored) {
+  if (stored?.token === token) {
+    return { ...stored, server };
+  }
+  return { device_agent_id: null, token, server, enrolled_at: null };
+}
+function startDeviceAgent(token, manage, options = {}) {
+  const server = manage || DEFAULT_SERVER;
+  const reporter = options.reporter ?? printingReporter;
+  const stored = readDeviceIdentity();
+  if (stored?.device_agent_id && stored.token !== token) {
+    reporter.replacingDevice(stored.device_agent_id);
+  }
+  const connection = { send: null, close: null };
+  const context = {
+    wsUrl: buildDeviceAgentWsUrl(manage),
+    server,
+    identity: identityForRun(token, server, stored),
+    reconnectPolicy: options.reconnectPolicy ?? new ReconnectPolicy(),
+    handshakeTimeoutMillis: options.handshakeTimeoutMillis ?? HANDSHAKE_TIMEOUT_MILLIS,
+    terminalHandler: new TerminalHandler({
+      send: (frame) => connection.send?.(frame),
+      spawn: spawnPty,
+      resolveShell: (requested) => resolveShell(requested, readShellEnvironment()),
+      registry: new TerminalRegistry(),
+      readShellContexts: processTableReader(),
+      resolvedHome: resolvedHomeDirectory()
+    }),
+    connection,
+    reporter,
+    writeIdentity: options.writeIdentity ?? writeDeviceIdentity,
+    options,
+    state: { stopRequested: false, cancelPendingSleep: null, error: null, welcomed: false }
+  };
+  const done = runLoop(context);
+  return {
+    done,
+    stop: () => {
+      context.state.stopRequested = true;
+      context.state.cancelPendingSleep?.();
+      connection.close?.();
+      return done;
+    }
+  };
+}
+async function runDeviceAgent(token, manage, options = {}) {
+  const run2 = startDeviceAgent(token, manage, options);
+  const sigintHandler = () => {
+    void run2.stop();
+  };
+  process.once("SIGINT", sigintHandler);
+  try {
+    await run2.done;
+  } finally {
+    process.removeListener("SIGINT", sigintHandler);
+  }
+}
+async function runLoop(context) {
+  const { state, reporter, reconnectPolicy } = context;
+  while (!state.stopRequested) {
+    reporter.connecting(context.server);
+    const outcome = await connectOnce(context);
+    if (outcome === "terminal" || state.stopRequested) {
+      break;
+    }
+    if (context.options.verifyOnly) {
+      state.error = {
+        code: AGENT_ERROR_NOT_CONNECTED,
+        message: `Could not connect to ${context.server}. Check the address and the network, then try again.`
+      };
+      break;
+    }
+    const delayMillis = reconnectPolicy.nextDelayMillis();
+    reporter.reconnecting(delayMillis, reconnectPolicy.attempt);
+    await sleep(delayMillis, state);
+  }
+  context.terminalHandler.closeAll();
+  return { error: state.error, welcomed: state.welcomed };
+}
+function fail(context, error) {
+  context.state.error = error;
+  context.reporter.failed(error);
+  return "terminal";
+}
+function connectOnce(context) {
+  const { identity, reconnectPolicy, terminalHandler, connection, reporter, state, options } = context;
+  return new Promise((resolve) => {
+    const ws = new WebSocket(context.wsUrl, { headers: { [TOKEN_HEADER]: identity.token } });
+    let heartbeat = null;
+    let stopMetrics = null;
+    let stopTunnels = null;
+    let pingTimer = null;
+    let pongDeadline = null;
+    let handshakeDeadline = null;
+    let closeDeadline = null;
+    let settled = false;
+    const stopTimers = () => {
+      if (heartbeat) clearInterval(heartbeat);
+      heartbeat = null;
+      stopMetrics?.();
+      stopMetrics = null;
+      stopTunnels?.();
+      stopTunnels = null;
+      if (pingTimer) clearInterval(pingTimer);
+      pingTimer = null;
+      if (pongDeadline) clearTimeout(pongDeadline);
+      pongDeadline = null;
+      if (handshakeDeadline) clearTimeout(handshakeDeadline);
+      handshakeDeadline = null;
+    };
+    const finish = (outcome) => {
+      if (settled) return;
+      settled = true;
+      stopTimers();
+      if (closeDeadline) clearTimeout(closeDeadline);
+      closeDeadline = null;
+      if (reconnectPolicy.markDisconnected()) {
+        logger.info("Connection held long enough to reset the reconnect schedule");
+      }
+      connection.send = null;
+      connection.close = null;
+      terminalHandler.suspend();
+      resolve(outcome);
+    };
+    const sendFrame = (frame) => {
+      if (ws.readyState === WebSocket.OPEN) {
+        ws.send(JSON.stringify(frame));
+      }
+    };
+    const dropDeadSocket = (message) => {
+      logger.warn(message);
+      reporter.warn(message);
+      ws.terminate();
+    };
+    connection.close = () => {
+      if (ws.readyState === WebSocket.CONNECTING) {
+        ws.terminate();
+        return;
+      }
+      ws.close(CLOSE_CODE_NORMAL);
+      closeDeadline = setTimeout(() => ws.terminate(), CLOSE_TIMEOUT_MILLIS);
+    };
+    ws.once("open", () => {
+      logger.info("Device agent socket open, sending hello");
+      connection.send = sendFrame;
+      sendFrame(request(CHANNEL_SYSTEM, OP_HELLO, buildHello(terminalHandler)));
+      handshakeDeadline = setTimeout(() => {
+        dropDeadSocket("No welcome from the dashboard. Reconnecting.");
+      }, context.handshakeTimeoutMillis);
+    });
+    const startPongWatchdog = (intervalSeconds) => {
+      const intervalMillis = intervalSeconds * 1e3;
+      const graceMillis = intervalMillis * PONG_GRACE_INTERVALS;
+      const armDeadline = () => {
+        if (pongDeadline) clearTimeout(pongDeadline);
+        pongDeadline = setTimeout(() => {
+          dropDeadSocket("Connection stopped answering. Reconnecting.");
+        }, graceMillis);
+      };
+      ws.on("pong", armDeadline);
+      pingTimer = setInterval(() => {
+        if (ws.readyState === WebSocket.OPEN) {
+          ws.ping();
+        }
+      }, intervalMillis);
+      armDeadline();
+    };
+    const startHeartbeat = (intervalSeconds) => {
+      heartbeat = setInterval(
+        () => sendFrame(
+          event(CHANNEL_SYSTEM, OP_HEARTBEAT, { uptime_seconds: Math.floor(os8.uptime()) })
+        ),
+        intervalSeconds * 1e3
+      );
+    };
+    const onWelcome = (welcome) => {
+      stopTimers();
+      if (options.verifyOnly) {
+        state.stopRequested = true;
+        connection.close?.();
+        return;
+      }
+      reconnectPolicy.markConnected();
+      terminalHandler.configure(
+        welcome.terminal_enabled,
+        welcome.max_terminals_per_device,
+        welcome.terminal_window_bytes,
+        welcome.max_frame_bytes,
+        welcome.terminal_idle_timeout_seconds,
+        welcome.terminal_max_session_seconds
+      );
+      terminalHandler.resumeAll();
+      startHeartbeat(welcome.heartbeat_interval_seconds);
+      startPongWatchdog(welcome.heartbeat_interval_seconds);
+      sendFrame(event(CHANNEL_DEVICE, OP_INFO, collectSystemInfo()));
+      stopMetrics = startMetricsReporting(
+        welcome.stats_interval_seconds,
+        collectMetrics,
+        (metrics) => sendFrame(event(CHANNEL_DEVICE, OP_METRICS, metrics))
+      );
+      stopTunnels = startTunnelReporting(
+        () => collectTunnelList(options.tunnelListSource),
+        (tunnels) => sendFrame(event(CHANNEL_DEVICE, OP_TUNNELS, tunnels))
+      );
+    };
+    ws.on("message", (data) => {
+      const envelope = parseEnvelope(data.toString("utf8"));
+      if (!envelope) {
+        logger.debug("Ignoring unparseable frame");
+        return;
+      }
+      if (envelope.ch === CHANNEL_TERMINAL) {
+        terminalHandler.handle(envelope);
+        return;
+      }
+      if (envelope.ch === CHANNEL_TUNNEL) {
+        void handleTunnelAction(envelope, (frame) => connection.send?.(frame), options.tunnelActions).then(() => stopTunnels?.pollNow());
+        return;
+      }
+      const outcome = handleFrame(envelope, context, onWelcome);
+      if (outcome === "terminal") {
+        finish("terminal");
+        ws.close();
+      }
+    });
+    ws.on("unexpected-response", (_req, res) => {
+      if (res.statusCode === 401) {
+        finish(fail(context, {
+          code: AGENT_ERROR_UNAUTHORIZED,
+          message: "Unauthorized. This device token is not valid. Re-enrol this machine with: pinggy device login"
+        }));
+      } else {
+        reporter.warn(`Unexpected HTTP ${res.statusCode}.`);
+        finish("retry");
+      }
+      ws.close();
+    });
+    ws.on("close", (code, reason) => {
+      logger.info("Device agent socket closed", { code, reason: reason.toString() });
+      finish(code === CLOSE_CODE_REVOKED ? "terminal" : "retry");
+    });
+    ws.on("error", (err) => {
+      logger.warn("Device agent socket error", { error: err.message });
+      if (!state.stopRequested) {
+        reporter.warn(err.message);
+      }
+      finish("retry");
+    });
+  });
+}
+function handleFrame(envelope, context, onWelcome) {
+  const { identity, reporter } = context;
+  if (envelope.ch !== CHANNEL_SYSTEM) {
+    logger.debug("Ignoring frame on unknown channel", { channel: envelope.ch });
+    return "retry";
+  }
+  if (envelope.op === OP_WELCOME) {
+    const error = ErrorPayloadSchema.safeParse(envelope.payload);
+    if (error.success) {
+      if (error.data.error.code === ERROR_ALREADY_CONNECTED) {
+        reporter.warn("This device is connected elsewhere. Retrying.");
+        return "retry";
+      }
+      return fail(context, {
+        code: AGENT_ERROR_HANDSHAKE_REFUSED,
+        message: `Handshake refused: ${error.data.error.message}`
+      });
+    }
+    const welcome = WelcomeSchema.safeParse(envelope.payload);
+    if (!welcome.success) {
+      logger.warn("Welcome payload could not be read");
+      return "retry";
+    }
+    identity.device_agent_id = welcome.data.device_agent_id;
+    identity.enrolled_at = identity.enrolled_at ?? (/* @__PURE__ */ new Date()).toISOString();
+    context.writeIdentity(identity);
+    context.state.welcomed = true;
+    reporter.connected(welcome.data);
+    onWelcome(welcome.data);
+    return "retry";
+  }
+  if (envelope.op === OP_DISCONNECT) {
+    const disconnect = DisconnectSchema.safeParse(envelope.payload);
+    const reason = disconnect.success ? disconnect.data.reason : "unknown";
+    const { outcome, message } = describeDisconnect(reason);
+    if (outcome === "retry") {
+      reporter.warn(message);
+      return "retry";
+    }
+    return fail(context, { code: disconnectErrorCode(reason), message });
+  }
+  logger.debug("Ignoring unhandled system op", { op: envelope.op });
+  return "retry";
+}
+var DISCONNECT_REASON_SHUTDOWN = "shutdown";
+var DISCONNECT_MESSAGES = {
+  revoked: "Credential revoked. Copy the new install command from the dashboard and run it to reconnect.",
+  deleted: "Device deleted from the dashboard. Add it again to reconnect this machine.",
+  replaced: "This device connected again from another session. Stopping this one."
+};
+function disconnectErrorCode(reason) {
+  return reason in DISCONNECT_MESSAGES ? reason : AGENT_ERROR_DISCONNECTED;
+}
+function describeDisconnect(reason) {
+  if (reason === DISCONNECT_REASON_SHUTDOWN) {
+    return { outcome: "retry", message: "Server is shutting down. Reconnecting." };
+  }
+  return {
+    outcome: "terminal",
+    message: DISCONNECT_MESSAGES[reason] ?? `Disconnected by the dashboard: ${reason}. Re-enrol this device to continue.`
+  };
+}
+
+// src/devices/login/deviceLogin.ts
+import os9 from "os";
+
+// src/devices/login/login_schema.ts
+import { z as z3 } from "zod";
+var LoginStartedSchema = z3.object({
+  device_code: z3.string().min(1),
+  match_code: z3.string().min(1).optional(),
+  expires_in_seconds: z3.number().int().positive(),
+  poll_interval_seconds: z3.number().int().positive()
+});
+var LoginStatus = {
+  Pending: "pending",
+  MfaRequired: "mfa_required",
+  Approved: "approved"
+};
+var LoginAnswerSchema = z3.object({
+  status: z3.enum([LoginStatus.Pending, LoginStatus.MfaRequired, LoginStatus.Approved]),
+  token: z3.string().min(1).optional(),
+  device_agent_id: z3.string().min(1).optional(),
+  device_name: z3.string().optional(),
+  open_url: z3.string().optional(),
+  device_url: z3.string().optional()
+});
+var LoginErrorSchema = z3.object({
+  error_type: z3.string(),
+  errors: z3.array(z3.string()).default([])
+});
+var LoginErrorType = {
+  /** A wrong code or authenticator code, with attempts left. Asked again. */
+  InvalidCode: "device_login_invalid_code",
+  /** Expired, ended after too many wrong codes, or already used. */
+  Expired: "device_login_expired",
+  RateLimited: "device_login_rate_limited",
+  InvalidClient: "device_login_invalid_client"
+};
+
+// src/devices/login/loginApi.ts
+var DEVICE_LOGIN_CLIENT_TOKEN = "pinggy-cli-1";
+var DEFAULT_DASHBOARD = "dashboard.pinggy.io";
+var LOGIN_PATH = "/backend/api/v1/device-agent/login";
+var SCHEME_PATTERN = /^(wss?|https?):\/\//i;
+var PLAIN_SCHEMES = /* @__PURE__ */ new Set(["ws", "http"]);
+function buildDashboardHttpUrl(manage) {
+  const address = (manage || DEFAULT_DASHBOARD).trim().replace(/\/+$/, "");
+  const match = SCHEME_PATTERN.exec(address);
+  const host = match ? address.slice(match[0].length) : address;
+  const scheme = match && PLAIN_SCHEMES.has(match[1].toLowerCase()) ? "http" : "https";
+  return `${scheme}://${host}${LOGIN_PATH}`;
+}
+var DeviceLoginApiError = class extends Error {
+  constructor(status, errorType, message) {
+    super(message);
+    this.status = status;
+    this.errorType = errorType;
+    this.name = "DeviceLoginApiError";
+  }
+};
+var UNREADABLE_ANSWER = "invalid_answer";
+function createDeviceLoginApi(manage, fetchImpl = fetch) {
+  const baseUrl = buildDashboardHttpUrl(manage);
+  async function post(path6, body, schema) {
+    const response2 = await fetchImpl(`${baseUrl}/${path6}`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json", Accept: "application/json" },
+      body: JSON.stringify(body)
+    });
+    const json = await readJson(response2);
+    if (!response2.ok) {
+      const refusal = LoginErrorSchema.safeParse(json);
+      if (refusal.success && refusal.data.errors.length > 0) {
+        throw new DeviceLoginApiError(response2.status, refusal.data.error_type, refusal.data.errors[0]);
+      }
+      throw new DeviceLoginApiError(
+        response2.status,
+        `http_${response2.status}`,
+        `The dashboard answered HTTP ${response2.status}.`
+      );
+    }
+    const answer = schema.safeParse(json);
+    if (!answer.success) {
+      throw new DeviceLoginApiError(
+        response2.status,
+        UNREADABLE_ANSWER,
+        "The dashboard sent an answer this pinggy cannot read. Update pinggy and try again."
+      );
+    }
+    return answer.data;
+  }
+  return {
+    start: (request2) => post("start", request2, LoginStartedSchema),
+    verifyCode: (deviceCode, code) => post("verify-code", { device_code: deviceCode, code }, LoginAnswerSchema),
+    verifyMfa: (deviceCode, totp) => post("verify-mfa", { device_code: deviceCode, totp }, LoginAnswerSchema),
+    poll: (deviceCode) => post("poll", { device_code: deviceCode }, LoginAnswerSchema)
+  };
+}
+async function readJson(response2) {
+  const text = await response2.text();
+  if (!text) {
+    return void 0;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+
+// src/devices/login/prompts.ts
+import { createInterface } from "readline/promises";
+import { Writable } from "stream";
+function createTerminalPrompter(input, output) {
+  return {
+    async ask(question, signal) {
+      const readline = createInterface({ input, output, terminal: true });
+      try {
+        return await readline.question(question, signal ? { signal } : {});
+      } finally {
+        readline.close();
+      }
+    },
+    async askHidden(question, signal) {
+      output.write(question);
+      const readline = createInterface({ input, output: discardingOutput(), terminal: true });
+      try {
+        const answer = await readline.question("", signal ? { signal } : {});
+        output.write("\n");
+        return answer;
+      } finally {
+        readline.close();
+      }
+    }
+  };
+}
+var terminalPrompter = createTerminalPrompter(process.stdin, process.stdout);
+function isInteractiveTerminal() {
+  return process.stdin.isTTY === true;
+}
+function discardingOutput() {
+  return new Writable({
+    write(_chunk, _encoding, callback) {
+      callback();
+    }
+  });
+}
+
+// src/devices/login/deviceLogin.ts
+var EXIT_OK = 0;
+var EXIT_FAILED = 1;
+var DEFAULT_SERVER2 = "dashboard.pinggy.io";
+var YES_ANSWER = /^y(es)?$/i;
+var SECONDS_PER_MINUTE = 60;
+var MILLIS_PER_SECOND2 = 1e3;
+var FIRST_SERVER_ERROR_STATUS = 500;
+var NO_TERMINAL_MESSAGE = "pinggy device login needs a terminal to type the email and the code. On a machine without one, add the device in the dashboard and run: pinggy device connect --token <TOKEN>";
+function machineDeviceLoginDependencies() {
+  return {
+    createApi: (manage) => createDeviceLoginApi(manage),
+    prompter: terminalPrompter,
+    isInteractive: isInteractiveTerminal,
+    readIdentity: readDeviceIdentity,
+    writeIdentity: writeDeviceIdentity,
+    runAgent: (token, manage) => runDeviceAgent(token, manage),
+    renderQr: async (url) => (await createQrCodes([url]))[0],
+    machine: () => ({
+      hostname: os9.hostname(),
+      os: os9.platform(),
+      arch: os9.arch(),
+      agent_version: getVersion()
+    }),
+    print: (message) => printer_default.print(message),
+    printError: (message) => printer_default.error(message),
+    sleep: sleepUnlessAborted
+  };
+}
+async function runDeviceLogin(options, dependencies = machineDeviceLoginDependencies()) {
+  if (!dependencies.isInteractive()) {
+    dependencies.printError(NO_TERMINAL_MESSAGE);
+    return EXIT_FAILED;
+  }
+  const stored = dependencies.readIdentity();
+  const manage = options.manage ?? stored?.server;
+  if (stored) {
+    const answer = await dependencies.prompter.ask(
+      `This machine is already enrolled as ${stored.device_agent_id ?? "a device"} on ${stored.server}. Add it again as a new device? [y/N] `
+    );
+    if (!YES_ANSWER.test(answer.trim())) {
+      return await dependencies.runAgent(stored.token, manage) ?? EXIT_OK;
+    }
+  }
+  const email = (await dependencies.prompter.ask("Email: ")).trim();
+  if (!email) {
+    dependencies.printError("An email is required.");
+    return EXIT_FAILED;
+  }
+  const api = dependencies.createApi(manage);
+  let approved;
+  let linkMinutes;
+  try {
+    const started = await api.start({
+      email,
+      client_token: DEVICE_LOGIN_CLIENT_TOKEN,
+      ...dependencies.machine(),
+      ...options.name ? { name: options.name } : {}
+    });
+    linkMinutes = Math.round(started.expires_in_seconds / SECONDS_PER_MINUTE);
+    dependencies.print(`We sent a 6-digit code to ${email}. It works for ${linkMinutes} minutes.`);
+    if (started.match_code) {
+      dependencies.print("Type it below, or click Approve sign-in in the email.");
+      dependencies.print(`If you use the email: approve only if the page shows ${started.match_code}. A different code is someone else's sign-in.`);
+    }
+    approved = await waitForApproval(api, started.device_code, started.poll_interval_seconds, dependencies);
+  } catch (err) {
+    dependencies.printError(messageOf(err, manage));
+    return EXIT_FAILED;
+  }
+  if (!approved.token || !approved.device_agent_id) {
+    dependencies.printError("The dashboard approved the sign-in without a device token. Update pinggy and try again.");
+    return EXIT_FAILED;
+  }
+  dependencies.writeIdentity({
+    device_agent_id: approved.device_agent_id,
+    token: approved.token,
+    server: manage || DEFAULT_SERVER2,
+    enrolled_at: null
+  });
+  dependencies.print(`Signed in as ${email}. Added device ${approved.device_name ?? approved.device_agent_id}.`);
+  await printDeviceLink(approved, linkMinutes, dependencies);
+  return await dependencies.runAgent(approved.token, manage) ?? EXIT_OK;
+}
+async function waitForApproval(api, deviceCode, pollIntervalSeconds, dependencies) {
+  const controller = new AbortController();
+  const prompt = { showing: false };
+  const typed = typeTheCode(api, deviceCode, controller.signal, prompt, dependencies);
+  const polled = pollUntilApproved(
+    api,
+    deviceCode,
+    pollIntervalSeconds * MILLIS_PER_SECOND2,
+    controller.signal,
+    dependencies
+  );
+  typed.catch(() => void 0);
+  polled.catch(() => void 0);
+  try {
+    return await Promise.race([typed, polled]);
+  } finally {
+    controller.abort();
+    if (prompt.showing) {
+      dependencies.print("");
+    }
+  }
+}
+async function typeTheCode(api, deviceCode, signal, prompt, dependencies) {
+  const ask = async (question, hidden = false) => {
+    prompt.showing = true;
+    try {
+      const answer2 = hidden ? dependencies.prompter.askHidden(question, signal) : dependencies.prompter.ask(question, signal);
+      return (await answer2).trim();
+    } finally {
+      prompt.showing = false;
+    }
+  };
+  let answer = null;
+  while (answer === null) {
+    const code = await ask("Code from the email: ");
+    if (code) {
+      answer = await askAgainOnWrongAnswer(() => api.verifyCode(deviceCode, code), dependencies);
+    }
+  }
+  while (answer.status === LoginStatus.MfaRequired) {
+    const totp = await ask("Authenticator code: ", true);
+    if (totp) {
+      answer = await askAgainOnWrongAnswer(() => api.verifyMfa(deviceCode, totp), dependencies) ?? answer;
+    }
+  }
+  if (answer.status === LoginStatus.Pending) {
+    dependencies.print("Approved from the email link. Waiting for the dashboard to finish.");
+    return waitUntilAborted(signal);
+  }
+  if (answer.status !== LoginStatus.Approved) {
+    throw new DeviceLoginApiError(
+      0,
+      "invalid_answer",
+      "The dashboard answered the code with something this pinggy cannot use. Update pinggy and try again."
+    );
+  }
+  return answer;
+}
+async function askAgainOnWrongAnswer(verify, dependencies) {
+  try {
+    return await verify();
+  } catch (err) {
+    if (err instanceof DeviceLoginApiError && err.errorType === LoginErrorType.InvalidCode) {
+      dependencies.printError(err.message);
+      return null;
+    }
+    throw err;
+  }
+}
+async function pollUntilApproved(api, deviceCode, intervalMillis, signal, dependencies) {
+  while (!signal.aborted) {
+    await dependencies.sleep(intervalMillis, signal);
+    if (signal.aborted) {
+      break;
+    }
+    try {
+      const answer = await api.poll(deviceCode);
+      if (answer.status === LoginStatus.Approved) {
+        return answer;
+      }
+    } catch (err) {
+      if (err instanceof DeviceLoginApiError && err.status > 0 && err.status < FIRST_SERVER_ERROR_STATUS) {
+        throw err;
+      }
+    }
+  }
+  throw signal.reason ?? new Error("The poll was stopped.");
+}
+async function printDeviceLink(approved, linkMinutes, dependencies) {
+  let link;
+  if (approved.open_url) {
+    link = approved.open_url;
+    dependencies.print(`Open the device in a browser. This link signs you in once, within ${linkMinutes} minutes:`);
+  } else if (approved.device_url) {
+    link = approved.device_url;
+    dependencies.print("Open the device in a browser:");
+  } else {
+    return;
+  }
+  dependencies.print(`  ${link}`);
+  try {
+    dependencies.print(await dependencies.renderQr(link));
+  } catch {
+  }
+}
+function messageOf(err, manage) {
+  if (err instanceof DeviceLoginApiError) {
+    return err.message;
+  }
+  const cause = err?.cause;
+  const causeText = cause instanceof Error ? `: ${cause.message}` : "";
+  const detail = err instanceof Error ? `${err.message}${causeText}` : String(err);
+  return `Could not reach the dashboard at ${buildDashboardHttpUrl(manage)} (${detail}).`;
+}
+function waitUntilAborted(signal) {
+  return new Promise((_resolve, reject) => {
+    const stop = () => reject(signal.reason ?? new Error("The wait was stopped."));
+    if (signal.aborted) {
+      stop();
+      return;
+    }
+    signal.addEventListener("abort", stop, { once: true });
+  });
+}
+function sleepUnlessAborted(millis, signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    const onAbort = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    const timer = setTimeout(() => {
+      signal.removeEventListener("abort", onAbort);
+      resolve();
+    }, millis);
+    signal.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/devices/backgroundAgent.ts
+var POLL_INTERVAL_MILLIS = 500;
+var CONNECT_WAIT_MILLIS = 15e3;
+var verifyingReporter = {
+  connecting: () => void 0,
+  connected: () => void 0,
+  reconnecting: () => void 0,
+  warn: (message) => printer_default.warn(message),
+  // The caller prints the error the run ends with.
+  failed: () => void 0,
+  replacingDevice: printingReporter.replacingDevice
+};
+function machineBackgroundAgentDependencies() {
+  return {
+    readIdentity: readDeviceIdentity,
+    findDaemon: getDaemonInfo,
+    ensureDaemon: ensureDaemonRunning,
+    client: (port) => new IPCClient(port, "cli"),
+    verify: (token, manage) => startDeviceAgent(token, manage, {
+      verifyOnly: true,
+      reporter: verifyingReporter
+    }).done,
+    sleep: (millis) => new Promise((resolve) => setTimeout(resolve, millis)),
+    now: () => Date.now(),
+    print: (message) => printer_default.print(message),
+    printSuccess: (message) => printer_default.success(message),
+    printWarning: (message) => printer_default.warn(message),
+    printError: (message) => printer_default.error(message),
+    daemonLogPath: getDaemonLogPath
+  };
+}
+function isAgentRunning(status) {
+  return status.state !== DeviceAgentState.Stopped;
+}
+function differsFromStored(target, stored) {
+  if (!stored?.token) return true;
+  return stored.token !== target.token || stored.server !== (target.manage || DEFAULT_SERVER);
+}
+function olderDaemonMessage(daemon) {
+  if (daemon.host === DaemonHost.APP) {
+    return "The Pinggy app runs an older daemon. Update the Pinggy app, or quit it and run this again.";
+  }
+  return "The running daemon predates background devices. Run pinggy daemon stop, then retry. This stops all running tunnels.";
+}
+async function readBackgroundAgent(dependencies) {
+  const daemon = dependencies.findDaemon();
+  if (!daemon || !isIpcCompatible(daemon)) {
+    return null;
+  }
+  try {
+    return { daemon, status: await dependencies.client(daemon.port).getDeviceAgentStatus() };
+  } catch (err) {
+    logger.debug("No background device agent to read", { error: errorMessage(err) });
+    return null;
+  }
+}
+async function startAgentInBackground(target, dependencies) {
+  if (differsFromStored(target, dependencies.readIdentity())) {
+    const verified = await dependencies.verify(target.token, target.manage);
+    if (verified.error || !verified.welcomed) {
+      dependencies.printError(verified.error?.message ?? "The device did not connect. Nothing changed.");
+      return EXIT_FAILED;
+    }
+  }
+  dependencies.print("Starting the device agent in the background.");
+  let daemon;
+  try {
+    daemon = await dependencies.ensureDaemon();
+  } catch (err) {
+    dependencies.printError(errorMessage(err));
+    return EXIT_FAILED;
+  }
+  const client = dependencies.client(daemon.port);
+  try {
+    const started = await client.startDeviceAgent();
+    if (isErrorResponse(started)) {
+      dependencies.printError(started.message);
+      return EXIT_FAILED;
+    }
+  } catch (err) {
+    dependencies.printError(daemonFailureMessage(err, daemon));
+    return EXIT_FAILED;
+  }
+  return waitUntilConnected(client, daemon, dependencies);
+}
+async function stopAgentInBackground(dependencies) {
+  const reading = await readBackgroundAgent(dependencies);
+  if (!reading || !isAgentRunning(reading.status)) {
+    dependencies.print("No device agent is running in the background.");
+    return EXIT_OK;
+  }
+  if (!await stopReadAgent(reading, dependencies)) {
+    return EXIT_FAILED;
+  }
+  dependencies.printSuccess("Stopped. The device shows offline in the dashboard.");
+  return EXIT_OK;
+}
+async function stopAgentBeforeRemove(dependencies) {
+  const reading = await readBackgroundAgent(dependencies);
+  if (!reading || !isAgentRunning(reading.status)) {
+    return true;
+  }
+  return stopReadAgent(reading, dependencies);
+}
+async function foregroundRefusal(dependencies) {
+  const reading = await readBackgroundAgent(dependencies);
+  if (!reading || !isAgentRunning(reading.status)) {
+    return null;
+  }
+  const device = reading.status.deviceAgentId ? `device ${reading.status.deviceAgentId}` : "a device";
+  return `This machine already runs as ${device} in the background. Stop it first: pinggy device stop`;
+}
+async function printBackgroundStatus(dependencies) {
+  const reading = await readBackgroundAgent(dependencies);
+  if (!reading) {
+    return;
+  }
+  dependencies.print(`  Background ${describeAgent(reading)}`);
+  if (reading.status.lastError) {
+    dependencies.print(`  Last error ${reading.status.lastError.message}`);
+  }
+}
+function describeAgentForDaemonStatus(status) {
+  switch (status.state) {
+    case DeviceAgentState.Connected:
+      return `connected as ${status.deviceAgentId}`;
+    case DeviceAgentState.Connecting:
+      return "connecting";
+    case DeviceAgentState.Reconnecting:
+      return "reconnecting";
+    default:
+      return "not running";
+  }
+}
+function describeAgent({ daemon, status }) {
+  const host = daemon.host === DaemonHost.APP ? "inside the Pinggy app" : `in the daemon, PID ${daemon.pid}`;
+  switch (status.state) {
+    case DeviceAgentState.Connected:
+      return `connected since ${status.connectedAt}, ${host}`;
+    case DeviceAgentState.Connecting:
+      return `connecting, ${host}`;
+    case DeviceAgentState.Reconnecting:
+      return `reconnecting, ${host}`;
+    default:
+      return "not running";
+  }
+}
+async function stopReadAgent(reading, dependencies) {
+  try {
+    await dependencies.client(reading.daemon.port).stopDeviceAgent();
+    return true;
+  } catch (err) {
+    dependencies.printError(`Could not stop the background device agent: ${errorMessage(err)}`);
+    return false;
+  }
+}
+function daemonFailureMessage(err, daemon) {
+  if (err instanceof IPCHttpError && err.statusCode === HTTP_NOT_FOUND) {
+    return olderDaemonMessage(daemon);
+  }
+  return `Could not reach the daemon: ${errorMessage(err)}`;
+}
+async function waitUntilConnected(client, daemon, dependencies) {
+  const deadline = dependencies.now() + CONNECT_WAIT_MILLIS;
+  for (; ; ) {
+    let status;
+    try {
+      status = await client.getDeviceAgentStatus();
+    } catch (err) {
+      dependencies.printError(daemonFailureMessage(err, daemon));
+      return EXIT_FAILED;
+    }
+    if (status.state === DeviceAgentState.Connected) {
+      printRunning(status, daemon, dependencies);
+      return EXIT_OK;
+    }
+    if (status.state === DeviceAgentState.Stopped) {
+      dependencies.printError(status.lastError?.message ?? "The device agent stopped before it connected.");
+      return EXIT_FAILED;
+    }
+    if (dependencies.now() >= deadline) {
+      dependencies.printWarning("Still connecting in the background. Check with: pinggy device status");
+      return EXIT_OK;
+    }
+    await dependencies.sleep(POLL_INTERVAL_MILLIS);
+  }
+}
+function printRunning(status, daemon, dependencies) {
+  dependencies.printSuccess(`Running in the background as device ${status.deviceAgentId}`);
+  if (status.email) {
+    dependencies.print(`Signed in as ${status.email}`);
+  }
+  if (status.deviceUrl) {
+    dependencies.print("Open the device in a browser:");
+    dependencies.print(`  ${status.deviceUrl}`);
+  }
+  if (daemon.host === DaemonHost.APP) {
+    dependencies.print("It runs inside the Pinggy app, and stops when the app quits.");
+  }
+  dependencies.print(`Logs: ${dependencies.daemonLogPath()}`);
+  dependencies.print("Stop it with: pinggy device stop");
+}
+
+// src/cli/subcommand/handlers/daemonCommandsHandler.ts
+async function handleDaemon(args) {
+  if (args.length === 0) {
+    printDaemonHelp();
+    return;
+  }
+  const verb = args[0];
+  switch (verb) {
+    case "start":
+      await handleDaemonStart();
+      return;
+    case "stop":
+      await handleDaemonStop();
+      return;
+    case "status":
+      await handleDaemonStatus();
+      return;
+    case "service-install":
+      installService();
+      return;
+    case "service-uninstall":
+      uninstallService();
+      return;
+    default:
+      printer_default.error(`Unknown daemon command: "${verb}"`);
+      printDaemonHelp();
+      return;
+  }
+}
+async function handleDaemonStart() {
+  const info = getDaemonInfo();
+  if (info) {
+    if (!isIpcCompatible(info)) {
+      printer_default.error(ipcMismatchMessage(info));
+      process.exit(1);
+    }
+    printer_default.print(pico2.yellow(`Daemon already running (PID ${info.pid}, port ${info.port}). Use: pinggy daemon status for details.`));
+    return;
+  }
+  const autoConfigs = getAutoStartConfigs();
+  if (autoConfigs.length > 0) {
+    printer_default.print(pico2.cyanBright(`Starting daemon with ${autoConfigs.length} auto-start tunnel(s):`));
+    for (const c of autoConfigs) {
+      printer_default.print(`  ${pico2.bold(c.name)} (${c.configId.slice(0, 8)})`);
+    }
+  } else {
+    printer_default.print(pico2.cyanBright("Starting daemon..."));
+  }
+  try {
+    const info2 = await startDaemon();
+    printer_default.success(`Daemon started PID ${info2.pid}.`);
+  } catch (err) {
+    printer_default.error(`Failed to start daemon: ${errorMessage(err)}`);
+    process.exit(1);
+  }
+}
+async function handleDaemonStop() {
+  if (!isDaemonRunning()) {
+    printer_default.print(pico2.yellow("No daemon is running."));
+    return;
+  }
+  const agent = await readBackgroundAgent(machineBackgroundAgentDependencies());
+  const result = await stopDaemon();
+  if (result.ok) {
+    printer_default.success("Daemon stopped.");
+    if (agent && isAgentRunning(agent.status)) {
+      printer_default.print("The background device agent stopped too. The device shows offline in the dashboard.");
+    }
+  } else if (result.reason === DaemonHost.APP) {
+    printer_default.print(pico2.yellow("The Pinggy daemon is running inside the Pinggy desktop app. Please quit the Pinggy app to stop it."));
+  } else {
+    printer_default.error(result.error);
+  }
+}
+async function handleDaemonStatus() {
+  const info = getDaemonInfo();
+  if (!info) {
+    printer_default.print(pico2.yellow("No daemon is running. Start with: pinggy daemon start"));
+    return;
+  }
+  const uptimeSec = Math.floor((Date.now() - new Date(info.startedAt).getTime()) / 1e3);
+  const h = Math.floor(uptimeSec / 3600);
+  const m = Math.floor(uptimeSec % 3600 / 60);
+  const s = uptimeSec % 60;
+  const uptimeStr = h > 0 ? `${h}h ${m}m ${s}s` : m > 0 ? `${m}m ${s}s` : `${s}s`;
+  printer_default.print(pico2.cyanBright("Daemon Status"));
+  printer_default.print(`  PID:       ${info.pid}`);
+  printer_default.print(`  Port:      ${info.port}`);
+  printer_default.print(`  Started:   ${info.startedAt}`);
+  printer_default.print(`  Uptime:    ${uptimeStr}`);
+  printer_default.print(`  Host:      ${info.host === DaemonHost.APP ? "Pinggy app (in-process)" : "standalone (CLI)"}`);
+  printer_default.print(`  IPC:       v${daemonIpcVersion(info)}`);
+  if (!isIpcCompatible(info)) {
+    printer_default.print(pico2.yellow(`  Warning:   ${ipcMismatchMessage(info)}`));
+  }
+  const agent = await readBackgroundAgent(machineBackgroundAgentDependencies());
+  if (agent) {
+    printer_default.print(`  Device:    ${describeAgentForDaemonStatus(agent.status)}`);
+  }
+}
+
+// src/cli/subcommand/handlers/psCommand.ts
+import pico3 from "picocolors";
+async function handlePs() {
+  const client = new TunnelClient();
+  try {
+    await client.ensureDaemon();
+  } catch (err) {
+    printer_default.error(`Cannot connect to daemon: ${errorMessage(err)}`);
+    return;
+  }
+  try {
+    const tunnels = await client.handleListV2();
+    if (isErrorResponse(tunnels)) {
+      printer_default.error(`Failed to list tunnels: ${tunnels.message}`);
+      return;
+    }
+    if (tunnels.length === 0) {
+      printer_default.print("No tunnels running.");
+      return;
+    }
+    const header = `${pad("ID", 14)} ${pad("NAME", 16)} ${pad("STATUS", 10)} ${pad("LOCAL", 20)} URL`;
+    printer_default.print(pico3.gray(header));
+    printer_default.print(pico3.gray("\u2500".repeat(90)));
+    for (const t of tunnels) {
+      const id = t.tunnelid.slice(0, 12);
+      const name = t.tunnelconfig?.name || "-";
+      const status = t.status.state;
+      const local = getLocalAddress(t.tunnelconfig);
+      const url = t.remoteurls?.[0] || "-";
+      const statusColor = status === "running" ? pico3.green : status === "starting" ? pico3.yellow : pico3.red;
+      printer_default.print(
+        `${pico3.cyan(pad(id, 14))} ${pad(name, 16)} ${statusColor(pad(status, 10))} ${pad(local, 20)} ${pico3.magentaBright(url)}`
+      );
+    }
+  } catch (err) {
+    printer_default.error(`Failed to list tunnels: ${errorMessage(err)}`);
+  } finally {
+    client.close();
+  }
+}
+function pad(str, len) {
+  return str.length >= len ? str.slice(0, len) : str + " ".repeat(len - str.length);
+}
+
+// src/cli/subcommand/handlers/stopCommand.ts
+async function handleStop(args) {
+  if (args.length === 0) {
+    printer_default.error("Usage: pinggy stop <name|id> [<name|id> ...]");
+    return;
+  }
+  const client = new TunnelClient();
+  try {
+    await client.ensureDaemon();
+  } catch (err) {
+    printer_default.error(`Cannot connect to daemon: ${errorMessage(err)}`);
+    return;
+  }
+  try {
+    const tunnels = await client.handleListV2();
+    if (isErrorResponse(tunnels)) {
+      printer_default.error(`Failed to list tunnels: ${tunnels.message}`);
+      return;
+    }
+    const targets = resolveTargets(tunnels, args);
+    if (targets.matched.length === 0) {
+      printer_default.error(`No tunnel found matching: ${args.join(", ")}. Use: pinggy ps`);
+      return;
+    }
+    for (const { input, tunnel } of targets.matched) {
+      const result = await client.handleStop(tunnel.tunnelid);
+      if (isErrorResponse(result)) {
+        printer_default.error(`Failed to stop "${input}": ${result.message}`);
+        continue;
+      }
+      const name = tunnel.tunnelconfig.name || tunnel.tunnelid.slice(0, 12);
+      printer_default.success(`Tunnel "${name}" stopped.`);
+    }
+    for (const m of targets.missing) {
+      printer_default.warn(`No tunnel found matching "${m}".`);
+    }
+  } catch (err) {
+    printer_default.error(`Failed to stop tunnel: ${errorMessage(err)}`);
+  } finally {
+    client.close();
+  }
+}
+function resolveTargets(tunnels, args) {
+  if (args.length > 1) {
+    const input = args.join(" ");
+    const tunnel = findTunnel(tunnels, input);
+    if (tunnel) return { matched: [{ input, tunnel }], missing: [] };
+  }
+  const matched = [];
+  const missing = [];
+  for (const input of args) {
+    const tunnel = findTunnel(tunnels, input);
+    if (tunnel) matched.push({ input, tunnel });
+    else missing.push(input);
+  }
+  return { matched, missing };
+}
+
+// src/cli/subcommand/handlers/attachCommand.ts
+import pico4 from "picocolors";
+async function handleAttach(args) {
+  if (args.length === 0) {
+    printer_default.error("Usage: pinggy attach <name|id>");
+    return;
+  }
+  const nameOrId = args[0];
+  const client = new TunnelClient();
+  try {
+    await client.ensureDaemon();
+  } catch (err) {
+    printer_default.error(`Cannot connect to daemon: ${errorMessage(err)}`);
+    return;
+  }
+  try {
     const tunnels = await client.handleListV2();
     if (isErrorResponse(tunnels)) {
       printer_default.error(`Failed to list tunnels: ${tunnels.message}`);
@@ -2010,7 +4868,7 @@ async function handleAttach(args) {
 }
 
 // src/cli/subcommand/handlers/logsCommand.ts
-import fs3 from "fs";
+import fs8 from "fs";
 async function handleLogs(args, follow) {
   const arg = args.find((a) => !a.startsWith("-"));
   const client = new TunnelClient();
@@ -2050,7 +4908,7 @@ async function handleLogs(args, follow) {
     return;
   }
   client.close();
-  if (!filePath || !fs3.existsSync(filePath)) {
+  if (!filePath || !fs8.existsSync(filePath)) {
     printer_default.error(`Log file not found: ${filePath}`);
     process.exit(1);
   }
@@ -2061,18 +4919,18 @@ async function handleLogs(args, follow) {
   }
 }
 function printTail(filePath, lines) {
-  const content = fs3.readFileSync(filePath, "utf-8");
+  const content = fs8.readFileSync(filePath, "utf-8");
   const allLines = content.split("\n");
   const tail = allLines.slice(-lines).join("\n");
   process.stdout.write(tail);
   if (!tail.endsWith("\n")) process.stdout.write("\n");
 }
 async function followFile(filePath) {
-  if (fs3.existsSync(filePath)) printTail(filePath, 20);
-  let fileSize = fs3.existsSync(filePath) ? fs3.statSync(filePath).size : 0;
+  if (fs8.existsSync(filePath)) printTail(filePath, 20);
+  let fileSize = fs8.existsSync(filePath) ? fs8.statSync(filePath).size : 0;
   let watcher = null;
   const openStream = () => {
-    const stream = fs3.createReadStream(filePath, { start: fileSize, encoding: "utf-8" });
+    const stream = fs8.createReadStream(filePath, { start: fileSize, encoding: "utf-8" });
     stream.on("data", (chunk) => {
       process.stdout.write(chunk);
       fileSize += Buffer.byteLength(chunk, "utf-8");
@@ -2080,9 +4938,9 @@ async function followFile(filePath) {
     stream.on("error", () => {
     });
   };
-  watcher = fs3.watch(filePath, { persistent: true }, (event) => {
-    if (event === "change") {
-      const stat = fs3.existsSync(filePath) ? fs3.statSync(filePath) : null;
+  watcher = fs8.watch(filePath, { persistent: true }, (event2) => {
+    if (event2 === "change") {
+      const stat = fs8.existsSync(filePath) ? fs8.statSync(filePath) : null;
       if (!stat || stat.size < fileSize) {
         fileSize = 0;
       }
@@ -2224,6 +5082,145 @@ async function handleRestart(args) {
   }
 }
 
+// src/cli/subcommand/handlers/deviceCommand.ts
+import pico5 from "picocolors";
+var DeviceVerb = {
+  Login: "login",
+  Connect: "connect",
+  Stop: "stop",
+  Status: "status",
+  Remove: "remove"
+};
+var DEVICE_AGENT_TOKEN_VARIABLE = "DEVICE_AGENT_TOKEN";
+function takeEnvironmentToken() {
+  const value = process.env[DEVICE_AGENT_TOKEN_VARIABLE]?.trim();
+  delete process.env[DEVICE_AGENT_TOKEN_VARIABLE];
+  return value || void 0;
+}
+function resolveConnectTarget(flagToken, environmentToken, manage, stored) {
+  if (flagToken) {
+    return { token: flagToken, manage: manage ?? stored?.server };
+  }
+  if (environmentToken) {
+    return { token: environmentToken, manage };
+  }
+  if (stored?.token) {
+    return { token: stored.token, manage: manage ?? stored.server };
+  }
+  return null;
+}
+async function handleDevice(args, background = machineBackgroundAgentDependencies()) {
+  const environmentToken = takeEnvironmentToken();
+  if (args.length === 0) {
+    printDeviceHelp();
+    return;
+  }
+  const verb = args[0];
+  const flagArgs = args.slice(1);
+  const { values } = parseCliArgs(cliOptions, flagArgs);
+  configureLogger(values);
+  const inBackground = Boolean(values.b);
+  switch (verb) {
+    case DeviceVerb.Login:
+      exitUnlessOk(await handleDeviceLogin(values.manage, values.name, inBackground, background));
+      return;
+    case DeviceVerb.Connect:
+      exitUnlessOk(await handleDeviceConnect(
+        values.token,
+        environmentToken,
+        values.manage,
+        inBackground,
+        background
+      ));
+      return;
+    case DeviceVerb.Stop:
+      exitUnlessOk(await stopAgentInBackground(background));
+      return;
+    case DeviceVerb.Status:
+      await handleDeviceStatus(background);
+      return;
+    case DeviceVerb.Remove:
+      exitUnlessOk(await handleDeviceRemove(background));
+      return;
+    default:
+      if (verb === "help" || verb === "--help" || verb === "-h") {
+        printDeviceHelp();
+        return;
+      }
+      printer_default.error(`Unknown command "${verb}". Valid commands: login, connect, stop, status, remove.`);
+      process.exit(1);
+  }
+}
+function exitUnlessOk(exitCode) {
+  if (exitCode !== EXIT_OK) {
+    process.exit(exitCode);
+  }
+}
+function refuseDevicesSpelling(args) {
+  printer_default.error(devicesSpellingMessage(args));
+  process.exit(1);
+}
+function devicesSpellingMessage(args) {
+  const verbs = Object.values(DeviceVerb);
+  const suggestion = verbs.includes(args[0]) ? args[0] : "--help";
+  return `"pinggy devices" is now "pinggy device". Run: pinggy device ${suggestion}`;
+}
+async function mayRunInForeground(background) {
+  const refusal = await foregroundRefusal(background);
+  if (refusal) {
+    printer_default.error(refusal);
+    return false;
+  }
+  return true;
+}
+async function handleDeviceLogin(manage, name, inBackground, background) {
+  if (!inBackground) {
+    if (!await mayRunInForeground(background)) return EXIT_FAILED;
+    return runDeviceLogin({ manage, name });
+  }
+  return runDeviceLogin({ manage, name }, {
+    ...machineDeviceLoginDependencies(),
+    runAgent: (token, agentManage) => startAgentInBackground({ token, manage: agentManage }, background)
+  });
+}
+async function handleDeviceConnect(flagToken, environmentToken, manage, inBackground, background) {
+  const target = resolveConnectTarget(flagToken, environmentToken, manage, background.readIdentity());
+  if (!target) {
+    printer_default.error("This machine is not enrolled. Sign it in with your email:\n  pinggy device login\nOr add a device in the dashboard, then run:\n  pinggy device connect --token <TOKEN>");
+    return EXIT_FAILED;
+  }
+  if (inBackground) {
+    return startAgentInBackground(target, background);
+  }
+  if (!await mayRunInForeground(background)) return EXIT_FAILED;
+  await runDeviceAgent(target.token, target.manage);
+  return EXIT_OK;
+}
+async function handleDeviceStatus(background) {
+  const identity = background.readIdentity();
+  if (!identity) {
+    printer_default.print("This machine is not enrolled. Run: pinggy device login");
+    return;
+  }
+  printer_default.print(`  Device id  ${identity.device_agent_id ?? pico5.gray("not yet assigned")}`);
+  printer_default.print(`  Server     ${identity.server}`);
+  printer_default.print(`  Token      ${maskToken(identity.token)}`);
+  printer_default.print(`  Enrolled   ${identity.enrolled_at ?? pico5.gray("never")}`);
+  await printBackgroundStatus(background);
+}
+async function handleDeviceRemove(background) {
+  if (!await stopAgentBeforeRemove(background)) {
+    return EXIT_FAILED;
+  }
+  if (clearDeviceIdentity()) {
+    printer_default.success("Local device credential removed.");
+    printer_default.print(pico5.gray("The device still exists in the dashboard. Delete it there to revoke it."));
+  } else {
+    printer_default.print("This machine is not enrolled.");
+  }
+  return EXIT_OK;
+}
+
 // src/cli/subcommand/subcommands.ts
 var SUBCOMMAND_SET = new Set(SUBCOMMANDS);
 function isSubcommand(rawArgs) {
@@ -2264,6 +5261,12 @@ async function handleSubcommand(rawArgs) {
     case Subcommand.Restart:
       await handleRestart(rest);
       return;
+    case Subcommand.Device:
+      await handleDevice(rest);
+      return;
+    case Subcommand.Devices:
+      refuseDevicesSpelling(rest);
+      return;
   }
 }
 function handleConfig(args) {
@@ -2486,17 +5489,17 @@ async function initRemoteManagementBackground(values) {
 }
 
 // src/daemon/lifecycle/daemonChild.ts
-import fs6 from "fs";
+import fs11 from "fs";
 
 // src/daemon/ipc/ipcServer.ts
 import http from "http";
-import fs5 from "fs";
-import path4 from "path";
-import { WebSocketServer, WebSocket } from "ws";
+import fs10 from "fs";
+import path5 from "path";
+import { WebSocketServer, WebSocket as WebSocket2 } from "ws";
 
 // src/daemon/ws/wsProtocol.ts
-function createTunnelEvent(tunnelId, event, payload) {
-  return { type: "tunnel_event", tunnelId, event, payload };
+function createTunnelEvent(tunnelId, event2, payload) {
+  return { type: "tunnel_event", tunnelId, event: event2, payload };
 }
 function parseClientMessage(raw) {
   try {
@@ -2518,17 +5521,17 @@ function parseClientMessage(raw) {
 }
 
 // src/daemon/lifecycle/stateStore.ts
-import fs4 from "fs";
-import path3 from "path";
+import fs9 from "fs";
+import path4 from "path";
 var STATE_FILENAME = "daemon-state.json";
 function getStatePath() {
-  return path3.join(getPinggyConfigDir(), STATE_FILENAME);
+  return path4.join(getPinggyConfigDir(), STATE_FILENAME);
 }
 function loadDaemonState() {
   const statePath = getStatePath();
   try {
-    if (!fs4.existsSync(statePath)) return null;
-    const raw = fs4.readFileSync(statePath, "utf-8");
+    if (!fs9.existsSync(statePath)) return null;
+    const raw = fs9.readFileSync(statePath, "utf-8");
     const state = JSON.parse(raw);
     if (!Array.isArray(state.tunnels)) return null;
     return state;
@@ -2542,8 +5545,8 @@ function persistDaemonState(state) {
   const tmpPath = statePath + ".tmp";
   try {
     state.lastUpdated = (/* @__PURE__ */ new Date()).toISOString();
-    fs4.writeFileSync(tmpPath, JSON.stringify(state, null, 2), "utf-8");
-    fs4.renameSync(tmpPath, statePath);
+    fs9.writeFileSync(tmpPath, JSON.stringify(state, null, 2), "utf-8");
+    fs9.renameSync(tmpPath, statePath);
   } catch (err) {
     logger.error("Failed to persist daemon state", { error: errorMessage(err) });
   }
@@ -2551,8 +5554,8 @@ function persistDaemonState(state) {
 function clearDaemonState() {
   const statePath = getStatePath();
   try {
-    if (fs4.existsSync(statePath)) {
-      fs4.unlinkSync(statePath);
+    if (fs9.existsSync(statePath)) {
+      fs9.unlinkSync(statePath);
     }
   } catch {
   }
@@ -2566,7 +5569,7 @@ function removeTunnelFromState(state, tunnelId) {
 }
 
 // src/daemon/ipc/ipcServer.ts
-var VALID_ORIGINS = ["app", "cli", "remote"];
+var VALID_ORIGINS = ["app", "cli", "remote", "device"];
 function parseOrigin(req) {
   const raw = req.headers["x-pinggy-origin"];
   const v = Array.isArray(raw) ? raw[0] : raw;
@@ -2599,6 +5602,7 @@ var IPCServer = class {
     this.sessionCounter = 0;
     this.onSessionDisconnect = null;
     this.sessionTracker = null;
+    this.deviceAgentHost = null;
     this.ops = new TunnelOperations();
     this.startedAt = Date.now();
     this.server = http.createServer(this.handleRequest.bind(this));
@@ -2616,6 +5620,13 @@ var IPCServer = class {
   setSessionTracker(st) {
     this.sessionTracker = st;
   }
+  setDeviceAgentHost(host) {
+    this.deviceAgentHost = host;
+  }
+  requireDeviceAgentHost() {
+    if (!this.deviceAgentHost) throw new Error("The device agent is not available in this daemon yet");
+    return this.deviceAgentHost;
+  }
   /**
    * Get all active sessions (for SessionTracker inspection).
    */
@@ -2720,8 +5731,8 @@ var IPCServer = class {
         const logDir = getTunnelLogDir();
         const daemonPath = getDaemonLogPath();
         const tunnels = [];
-        if (fs5.existsSync(logDir)) {
-          const files = fs5.readdirSync(logDir).filter((f) => f.endsWith(".log") && !/\.log\.\d+$/.test(f));
+        if (fs10.existsSync(logDir)) {
+          const files = fs10.readdirSync(logDir).filter((f) => f.endsWith(".log") && !/\.log\.\d+$/.test(f));
           const manager = TunnelManager.getInstance();
           const activeIds = manager.getActiveTunnelIds();
           const activeNames = /* @__PURE__ */ new Set();
@@ -2731,8 +5742,8 @@ var IPCServer = class {
             if (n) activeNames.add(n);
           }
           for (const file of files) {
-            const filePath = path4.join(logDir, file);
-            const stat = fs5.statSync(filePath);
+            const filePath = path5.join(logDir, file);
+            const stat = fs10.statSync(filePath);
             const parsed = parseTunnelLogFilename(file);
             if (!parsed) continue;
             const running = parsed.tunnelId ? activeIds.has(parsed.tunnelId) : parsed.name ? activeNames.has(parsed.name) : false;
@@ -2748,6 +5759,10 @@ var IPCServer = class {
         }
         return { daemon: daemonPath, tunnels };
       },
+      // The request body is never read: a token or a server in it must not reach the agent.
+      [Route.GetDeviceAgent]: () => this.requireDeviceAgentHost().status(),
+      [Route.StartDeviceAgent]: (_req, ctx) => this.requireDeviceAgentHost().start(ctx.origin),
+      [Route.StopDeviceAgent]: () => this.requireDeviceAgentHost().stop(),
       [Route.Shutdown]: () => {
         logger.info("Daemon shutdown requested via IPC");
         if (getDaemonHost() === DaemonHost.APP) {
@@ -2764,6 +5779,9 @@ var IPCServer = class {
             logger.error(`Shutdown step "${label}" failed`, { error: msg });
           }
         };
+        step("stopDeviceAgent", () => {
+          void this.deviceAgentHost?.close();
+        });
         step("removeDaemonInfo", removeDaemonInfo);
         step("clearDaemonState", clearDaemonState);
         step("stopAllTunnels", () => TunnelManager.getInstance().stopAllTunnels());
@@ -2796,8 +5814,8 @@ var IPCServer = class {
     if (paramMatch) {
       try {
         await this.readBody(req);
-        const response = await paramMatch.invoke();
-        this.sendJson(res, 200, response);
+        const response2 = await paramMatch.invoke();
+        this.sendJson(res, 200, response2);
       } catch (err) {
         const msg = errorMessage(err);
         logger.error("IPC handler error", { route: `${method} ${url}`, error: msg });
@@ -2844,8 +5862,8 @@ var IPCServer = class {
         return { status: "running", path: logPath, tunnelId: t.tunnelid, name, origin, running: true };
       }
     }
-    if (fs5.existsSync(logDir)) {
-      const files = fs5.readdirSync(logDir).filter((f) => f.endsWith(".log") && !/\.log\.\d+$/.test(f));
+    if (fs10.existsSync(logDir)) {
+      const files = fs10.readdirSync(logDir).filter((f) => f.endsWith(".log") && !/\.log\.\d+$/.test(f));
       const matches = [];
       for (const file of files) {
         const parsed = parseTunnelLogFilename(file);
@@ -2853,8 +5871,8 @@ var IPCServer = class {
         const nameMatch = parsed.name !== void 0 && parsed.name === q;
         const idMatch = parsed.tunnelId !== void 0 && (parsed.tunnelId === q || parsed.tunnelId.startsWith(q));
         if (nameMatch || idMatch) {
-          const filePath = path4.join(logDir, file);
-          const stat = fs5.statSync(filePath);
+          const filePath = path5.join(logDir, file);
+          const stat = fs10.statSync(filePath);
           matches.push({ path: filePath, mtime: stat.mtimeMs, tunnelId: parsed.tunnelId, name: parsed.name, origin: parsed.origin });
         }
       }
@@ -3030,9 +6048,9 @@ var IPCServer = class {
     session.subscriptions.clear();
     this.sessions.delete(session.id);
   }
-  sendEvent(session, tunnelId, event, payload) {
-    if (session.ws.readyState === WebSocket.OPEN) {
-      const msg = createTunnelEvent(tunnelId, event, payload);
+  sendEvent(session, tunnelId, event2, payload) {
+    if (session.ws.readyState === WebSocket2.OPEN) {
+      const msg = createTunnelEvent(tunnelId, event2, payload);
       session.ws.send(JSON.stringify(msg));
     }
   }
@@ -3209,6 +6227,196 @@ var SessionTracker = class {
   }
 };
 
+// src/daemon/deviceAgentHost.ts
+var NOT_ENROLLED_MESSAGE = "This machine is not enrolled. Sign it in first: pinggy device login";
+function stoppedStatus() {
+  return {
+    state: DeviceAgentState.Stopped,
+    deviceAgentId: null,
+    server: null,
+    email: null,
+    deviceUrl: null,
+    startedAt: null,
+    connectedAt: null,
+    startedBy: null,
+    lastError: null
+  };
+}
+var DeviceAgentHost = class {
+  constructor(dependencies) {
+    this.dependencies = dependencies;
+    this.current = null;
+    this.statusValue = stoppedStatus();
+    /** Bumped on every start and stop. A run's reporter whose number is old belongs to a run that ended. */
+    this.generation = 0;
+    /** Set once the daemon shuts down. Nothing starts and nothing more reaches daemon-state.json. */
+    this.closed = false;
+    /** Start and stop chain on this, so 1 finishes before the next begins. */
+    this.queue = Promise.resolve();
+  }
+  status() {
+    return { ...this.statusValue };
+  }
+  /**
+   * Starts the agent on what device.json holds now. A run on the same token and server is left alone.
+   * A run on another is stopped first.
+   */
+  start(startedBy) {
+    return this.exclusive(async () => {
+      if (this.closed) {
+        return this.status();
+      }
+      const identity = this.dependencies.readIdentity();
+      if (!identity?.token) {
+        return newErrorResponse(ErrorCode.DeviceNotEnrolled, NOT_ENROLLED_MESSAGE);
+      }
+      const current = this.current;
+      if (current && current.token === identity.token && current.server === identity.server) {
+        return this.status();
+      }
+      await this.stopCurrent();
+      this.launch(identity, startedBy);
+      return this.status();
+    });
+  }
+  /** Stops the run: the socket closes with 1000 and every shell ends. */
+  stop() {
+    return this.exclusive(async () => {
+      await this.stopCurrent();
+      return this.status();
+    });
+  }
+  /**
+   * The daemon is shutting down. Stops the run at once, outside the queue, and writes nothing to
+   * daemon-state.json: the shutdown deletes that file, and a write after it would bring the file back.
+   */
+  close() {
+    this.closed = true;
+    const current = this.current;
+    this.current = null;
+    this.generation += 1;
+    this.statusValue = { ...this.statusValue, state: DeviceAgentState.Stopped, connectedAt: null };
+    return current ? current.run.stop().then(() => void 0) : Promise.resolve();
+  }
+  exclusive(operation) {
+    const result = this.queue.then(operation);
+    this.queue = result.catch(() => void 0);
+    return result;
+  }
+  launch(identity, startedBy) {
+    this.generation += 1;
+    const generation = this.generation;
+    this.statusValue = {
+      state: DeviceAgentState.Connecting,
+      deviceAgentId: identity.device_agent_id,
+      server: identity.server,
+      email: null,
+      deviceUrl: null,
+      startedAt: this.dependencies.now().toISOString(),
+      connectedAt: null,
+      startedBy,
+      lastError: null
+    };
+    const run2 = this.dependencies.startRun(identity, this.reporterFor(generation));
+    this.current = { run: run2, token: identity.token, server: identity.server };
+    this.dependencies.recordRunning(startedBy);
+    logger.info("Device agent started in the daemon", { startedBy });
+    void run2.done.then((end) => this.onRunEnded(generation, end));
+  }
+  async stopCurrent() {
+    const current = this.current;
+    if (!current) {
+      return;
+    }
+    this.current = null;
+    this.generation += 1;
+    this.statusValue = { ...this.statusValue, state: DeviceAgentState.Stopped, connectedAt: null };
+    if (!this.closed) {
+      this.dependencies.recordStopped();
+    }
+    await current.run.stop();
+    logger.info("Device agent stopped in the daemon");
+  }
+  /** The run ended on its own: the dashboard refused the credential or ended the device. */
+  onRunEnded(generation, end) {
+    if (generation !== this.generation) {
+      return;
+    }
+    this.current = null;
+    this.statusValue = {
+      ...this.statusValue,
+      state: DeviceAgentState.Stopped,
+      connectedAt: null,
+      lastError: end.error
+    };
+    if (!this.closed) {
+      this.dependencies.recordStopped();
+    }
+  }
+  /** Logs every event, and keeps the latest for `GET /device`. Never logs the email or a payload. */
+  reporterFor(generation) {
+    const isCurrent = () => generation === this.generation;
+    let welcomedOnce = false;
+    const notConnected = () => welcomedOnce ? DeviceAgentState.Reconnecting : DeviceAgentState.Connecting;
+    return {
+      connecting: (server) => {
+        if (!isCurrent()) return;
+        this.statusValue = { ...this.statusValue, state: notConnected(), connectedAt: null };
+        logger.info("Device agent connecting", { server });
+      },
+      connected: (welcome) => {
+        if (!isCurrent()) return;
+        welcomedOnce = true;
+        this.statusValue = {
+          ...this.statusValue,
+          state: DeviceAgentState.Connected,
+          deviceAgentId: welcome.device_agent_id,
+          email: welcome.email ?? null,
+          deviceUrl: welcome.device_url ?? null,
+          connectedAt: this.dependencies.now().toISOString()
+        };
+        logger.info("Device agent connected", { deviceAgentId: welcome.device_agent_id });
+      },
+      reconnecting: (delayMillis, attempt) => {
+        if (!isCurrent()) return;
+        this.statusValue = { ...this.statusValue, state: notConnected(), connectedAt: null };
+        logger.warn("Device agent disconnected", { delayMillis, attempt });
+      },
+      warn: (message) => {
+        logger.warn("Device agent warning", { message });
+      },
+      failed: (error) => {
+        logger.error("Device agent ended", { code: error.code });
+      },
+      replacingDevice: (oldDeviceAgentId) => {
+        logger.info("Device agent connects a new device in place of a stored one", { oldDeviceAgentId });
+      }
+    };
+  }
+};
+function writeIdentityWhileOwned(identity) {
+  const stored = readDeviceIdentity();
+  if (stored && stored.token !== identity.token) {
+    logger.info("Device agent left a newer device.json in place");
+    return;
+  }
+  writeDeviceIdentity(identity);
+}
+function machineDeviceAgentHostDependencies(port, record) {
+  return {
+    readIdentity: readDeviceIdentity,
+    startRun: (identity, reporter) => startDeviceAgent(identity.token, identity.server, {
+      reporter,
+      tunnelListSource: selfTunnelListSource(port),
+      tunnelActions: selfTunnelActionDependencies(port),
+      writeIdentity: writeIdentityWhileOwned
+    }),
+    recordRunning: record.recordRunning,
+    recordStopped: record.recordStopped,
+    now: () => /* @__PURE__ */ new Date()
+  };
+}
+
 // src/daemon/lifecycle/daemonChild.ts
 var daemonState = { tunnels: [], lastUpdated: "" };
 var daemonHost = DaemonHost.CLI;
@@ -3223,13 +6431,13 @@ function writeDaemonInfo(info) {
   ensurePinggyConfigDir();
   const infoPath = getDaemonInfoPath();
   const tmpPath = infoPath + ".tmp";
-  fs6.writeFileSync(tmpPath, JSON.stringify(info, null, 2), "utf-8");
-  fs6.renameSync(tmpPath, infoPath);
+  fs11.writeFileSync(tmpPath, JSON.stringify(info, null, 2), "utf-8");
+  fs11.renameSync(tmpPath, infoPath);
 }
 function removeDaemonInfo() {
   try {
     const infoPath = getDaemonInfoPath();
-    if (fs6.existsSync(infoPath)) fs6.unlinkSync(infoPath);
+    if (fs11.existsSync(infoPath)) fs11.unlinkSync(infoPath);
   } catch {
   }
 }
@@ -3254,6 +6462,29 @@ function trackTunnelStop(tunnelId) {
   persistDaemonState(daemonState);
   sessionTrackerRef?.removeTunnel(tunnelId);
 }
+function trackDeviceAgentStart(startedBy) {
+  daemonState.deviceAgent = { startedAt: (/* @__PURE__ */ new Date()).toISOString(), startedBy };
+  persistDaemonState(daemonState);
+}
+function trackDeviceAgentStop() {
+  if (!daemonState.deviceAgent) return;
+  delete daemonState.deviceAgent;
+  persistDaemonState(daemonState);
+}
+async function restoreCrashedDeviceAgent(host, saved) {
+  try {
+    const result = await host.start(saved.startedBy);
+    if (isErrorResponse(result)) {
+      logger.warn("Crash recovery: device agent not restored", { reason: result.message });
+      trackDeviceAgentStop();
+      return;
+    }
+    logger.info("Crash recovery: device agent restored");
+  } catch (err) {
+    logger.error("Crash recovery: device agent failed to start", { error: errorMessage(err) });
+    trackDeviceAgentStop();
+  }
+}
 function trackIPCTunnelStart(tunnelId, origin, mode = SessionMode.Detached) {
   if (mode === SessionMode.Foreground) return;
   const manager = TunnelManager.getInstance();
@@ -3367,11 +6598,16 @@ async function runDaemonChild(opts = {}) {
   });
   ipcServer.setSessionTracker(sessionTracker);
   setDaemonSessionTracker(sessionTracker);
+  let deviceAgentHost = null;
   let cleanedUp = false;
   const cleanup = () => {
     if (cleanedUp) return;
     cleanedUp = true;
     logger.info("Daemon shutting down");
+    try {
+      void deviceAgentHost?.close();
+    } catch {
+    }
     try {
       removeDaemonInfo();
     } catch {
@@ -3417,6 +6653,15 @@ async function runDaemonChild(opts = {}) {
   }
   try {
     const port = await ipcServer.listen();
+    deviceAgentHost = new DeviceAgentHost(machineDeviceAgentHostDependencies(port, {
+      recordRunning: trackDeviceAgentStart,
+      recordStopped: trackDeviceAgentStop
+    }));
+    ipcServer.setDeviceAgentHost(deviceAgentHost);
+    const crashedDeviceAgent = loadDaemonState()?.deviceAgent;
+    if (crashedDeviceAgent) {
+      daemonState.deviceAgent = crashedDeviceAgent;
+    }
     const info = {
       pid: process.pid,
       port,
@@ -3440,6 +6685,9 @@ async function runDaemonChild(opts = {}) {
     } else {
       logger.info("No auto-start tunnels configured");
     }
+    if (crashedDeviceAgent) {
+      await restoreCrashedDeviceAgent(deviceAgentHost, crashedDeviceAgent);
+    }
     logger.info("Daemon ready", { pid: process.pid, port });
     return {
       pid: process.pid,
@@ -3463,7 +6711,7 @@ async function main() {
     const { values, positionals, hasAnyArgs } = parseCliArgs(cliOptions);
     configureLogger(values);
     if (values["_daemon-child"]) {
-      const { runDaemonChild: runDaemonChild2 } = await import("./daemonChild-VX7SCGVS.js");
+      const { runDaemonChild: runDaemonChild2 } = await import("./daemonChild-E73NFWKE.js");
       await runDaemonChild2();
       return;
     }
@@ -3502,6 +6750,8 @@ export {
   removeDaemonInfo,
   trackTunnelStart,
   trackTunnelStop,
+  trackDeviceAgentStart,
+  trackDeviceAgentStop,
   trackIPCTunnelStart,
   runDaemonChild
 };