appduct 0.13.0 → 0.15.0

package/dist/cli/routes/daemon/run.js

@@ -2,131 +2,209 @@
 import { rm as rm5 } from "node:fs/promises";
 import {
   MAX_TOOLS_FILTER_LENGTH,
-  RPC_METHODS,
+  RPC_METHODS as RPC_METHODS3,
   isValidToolGroup,
   summarizeToolGroups,
   toolGroupMatches,
   EVENT_KINDS
 } from "@appduct/shared";
 
-// src/package-version.ts
-import { readFileSync as readFileSync2 } from "node:fs";
-import { join as join2 } from "node:path";
-
-// src/package-root.ts
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-var PACKAGE_NAME = "appduct";
-var cached;
-var getPackageRoot = () => {
-  if (cached !== void 0) {
-    return cached;
-  }
-  let dir = dirname(fileURLToPath(import.meta.url));
-  for (; ; ) {
-    const candidate = join(dir, "package.json");
-    if (existsSync(candidate)) {
-      let name;
-      try {
-        name = JSON.parse(readFileSync(candidate, "utf8")).name;
-      } catch {
-      }
-      if (name === PACKAGE_NAME) {
-        cached = dir;
-        return dir;
-      }
-    }
-    const parent = dirname(dir);
-    if (parent === dir) {
-      throw new Error(`Could not locate the "${PACKAGE_NAME}" package root above ${import.meta.url}.`);
+// src/devtools-relay/relay.ts
+import { decodeBootstrap } from "@appduct/shared";
+var linkPayload = (link) => {
+  const payload = new URLSearchParams(new URL(link.url).hash.slice(1)).get("appduct");
+  if (payload === null) throw new Error('The link has no #appduct= payload: pass the result of link({ target: "web", url }).');
+  return payload;
+};
+var parseLink = (link) => {
+  const bootstrap = decodeBootstrap(linkPayload(link));
+  if (!bootstrap) throw new Error("The link's #appduct= payload is not a valid Appduct link.");
+  return bootstrap;
+};
+var GOING_AWAY = 1001;
+var relayPage = (page, link, openDaemonSocket) => {
+  const bootstrap = parseLink(link);
+  const host = bootstrap.address.includes(":") ? `[${bootstrap.address}]` : bootstrap.address;
+  const url = `ws://${host}:${bootstrap.port}`;
+  let current;
+  const tellPage = (message) => {
+    page.evaluate(`window.__APPDUCT__.receive(${JSON.stringify(JSON.stringify(message))})`).catch(() => void 0);
+  };
+  const closeCurrent = (code, reason) => {
+    const socket = current;
+    current = void 0;
+    socket?.close(code, reason);
+  };
+  page.onBindingCall((json) => {
+    const message = JSON.parse(json);
+    if (message.kind === "open") {
+      closeCurrent(GOING_AWAY, "superseded");
+      const socket = openDaemonSocket(url, {
+        open: () => current === socket && tellPage({ kind: "open" }),
+        message: (text) => current === socket && tellPage({ kind: "message", text }),
+        close: (code, reason) => {
+          if (current !== socket) return;
+          current = void 0;
+          tellPage({ kind: "close", code, reason });
+        }
+      });
+      current = socket;
+    } else if (message.kind === "send") {
+      current?.send(message.text ?? "");
+    } else if (message.kind === "close") {
+      closeCurrent(message.code ?? 1e3, message.reason ?? "");
     }
-    dir = parent;
-  }
+  });
+  page.onContextReset(() => closeCurrent(GOING_AWAY, "page_gone"));
 };
 
-// src/package-version.ts
-var DAEMON_VERSION_OVERRIDE_ENV = "APPDUCT_DAEMON_VERSION_OVERRIDE";
-var isTestRuntime = (env) => {
-  return Boolean(env.VITEST) || env.NODE_ENV === "test";
-};
-var cached2;
-var getPackageVersion = () => {
-  cached2 ??= JSON.parse(readFileSync2(join2(getPackageRoot(), "package.json"), "utf8")).version;
-  return cached2;
-};
-var getDaemonReportedVersion = (env = process.env) => {
-  if (!isTestRuntime(env)) {
-    return getPackageVersion();
+// src/devtools-relay/attach-tab.ts
+var listTabs = (tabs) => tabs.length === 0 ? "  (none)" : tabs.map((tab) => `  ${tab.id}  ${tab.url}`).join("\n");
+var pickTab = (tabs, url, targetId) => {
+  if (targetId !== void 0) {
+    const byId = tabs.find((tab) => tab.id === targetId);
+    if (byId) return byId;
+    throw new Error(`No open tab has target id "${targetId}". Open tabs:
+${listTabs(tabs)}`);
+  }
+  const matching = tabs.filter((tab) => tab.url.startsWith(url));
+  if (matching.length === 1) return matching[0];
+  if (matching.length === 0) throw new Error(`No open tab starts with "${url}". Open tabs:
+${listTabs(tabs)}`);
+  throw new Error(`${matching.length} open tabs start with "${url}"; pass the target id of the one you want. Matching tabs:
+${listTabs(matching)}`);
+};
+var WAIT_FOR_WEB = `new Promise((resolve, reject) => {
+  const ready = () => typeof window.__APPDUCT__?.connect === 'function';
+  if (ready()) return resolve(true);
+  const timer = setInterval(() => { if (ready()) { clearInterval(timer); clearTimeout(giveUp); resolve(true); } }, 50);
+  const giveUp = setTimeout(() => { clearInterval(timer); reject(new Error('@appduct/web did not load')); }, 5000);
+})`;
+var attachBrowserTab = async (options) => {
+  const tab = pickTab(await options.browser.targets(), options.url, options.targetId);
+  const link = await options.mintLink();
+  const page = await options.browser.openPage(tab.id);
+  options.relayedTabs.get(tab.id)?.close();
+  options.relayedTabs.set(tab.id, page);
+  try {
+    relayPage(page, link, options.openDaemonSocket);
+    await page.evaluate(WAIT_FOR_WEB).catch(() => {
+      throw new Error(`The tab ${tab.id} (${tab.url}) does not load @appduct/web. Add it to the page, then try again.`);
+    });
+    await page.evaluate(`window.__APPDUCT__.connect(${JSON.stringify(linkPayload(link))}, { transport: "devtools" })`);
+  } catch (error) {
+    page.close();
+    if (options.relayedTabs.get(tab.id) === page) options.relayedTabs.delete(tab.id);
+    throw error;
   }
-  const override = env[DAEMON_VERSION_OVERRIDE_ENV];
-  return override !== void 0 && override.length > 0 ? override : getPackageVersion();
+  return { sessionId: link.sessionId, url: tab.url, targetId: tab.id, expiresAt: link.expiresAt };
 };
 
-// src/daemon/address.ts
-import { networkInterfaces } from "node:os";
-import {
-  isLinkLocalIpv6Address,
-  isPrivateIpv4Address,
-  isUniqueLocalIpv6Address
-} from "@appduct/shared";
-var isDockerDefaultBridgeAddress = (address) => {
-  return address.startsWith("172.17.");
-};
-var isCgnatIpv4Address = (address) => {
-  const parts = address.split(".");
-  if (parts.length !== 4) {
-    return false;
-  }
-  const first = Number(parts[0]);
-  const second = Number(parts[1]);
-  return first === 100 && Number.isInteger(second) && second >= 64 && second <= 127;
+// src/devtools-relay/node-devtools-browser.ts
+import WebSocket from "ws";
+var BINDING = "__appductBinding";
+var listTargets = async (browserUrl) => {
+  let listed;
+  try {
+    listed = await (await fetch(new URL("/json/list", browserUrl))).json();
+  } catch (error) {
+    throw new Error(`Could not reach a browser at ${browserUrl}: ${error.message}. Launch Chrome with --remote-debugging-port and its own --user-data-dir.`);
+  }
+  return listed.filter((target) => target.type === "page");
+};
+var openTab = async (target, browserUrl) => {
+  const endpoint = new URL(browserUrl);
+  const socketUrl = new URL(target.webSocketDebuggerUrl);
+  socketUrl.protocol = endpoint.protocol === "https:" ? "wss:" : "ws:";
+  socketUrl.host = endpoint.host;
+  const socket = new WebSocket(socketUrl);
+  await new Promise((resolve2, reject) => {
+    socket.once("open", () => resolve2());
+    socket.once("error", reject);
+  });
+  const pending = /* @__PURE__ */ new Map();
+  const bindingHandlers = [];
+  const resetHandlers = [];
+  let nextId = 0;
+  const send = (method, params) => new Promise((resolve2, reject) => {
+    nextId += 1;
+    pending.set(nextId, { resolve: resolve2, reject });
+    socket.send(JSON.stringify({ id: nextId, method, params }));
+  });
+  socket.on("message", (data) => {
+    const message = JSON.parse(data.toString());
+    if (message.id !== void 0) {
+      const call = pending.get(message.id);
+      pending.delete(message.id);
+      if (message.error) call?.reject(new Error(message.error.message));
+      else call?.resolve(message.result);
+    } else if (message.method === "Runtime.bindingCalled" && message.params?.name === BINDING) {
+      bindingHandlers.forEach((handler) => handler(message.params.payload));
+    } else if (message.method === "Runtime.executionContextsCleared") {
+      resetHandlers.forEach((handler) => handler());
+    }
+  });
+  socket.on("error", () => void 0);
+  socket.on("close", () => {
+    pending.forEach((call) => call.reject(new Error("The tab's debugging connection closed.")));
+    pending.clear();
+    resetHandlers.forEach((handler) => handler());
+  });
+  await send("Runtime.enable", {});
+  await send("Runtime.addBinding", { name: BINDING });
+  return {
+    onBindingCall: (handler) => void bindingHandlers.push(handler),
+    onContextReset: (handler) => void resetHandlers.push(handler),
+    evaluate: async (expression) => {
+      const result = await send("Runtime.evaluate", { expression, awaitPromise: true, returnByValue: true });
+      const failure = result?.exceptionDetails;
+      if (failure) throw new Error(failure.exception?.description ?? failure.text);
+    },
+    close: () => socket.close()
+  };
 };
-var isExcludedIpv4Address = (address) => {
-  return isDockerDefaultBridgeAddress(address) || isCgnatIpv4Address(address);
+var connectNodeDevtoolsBrowser = (browserUrl) => {
+  const open4 = /* @__PURE__ */ new Map();
+  return {
+    targets: async () => (await listTargets(browserUrl)).map(({ id, url, title }) => ({ id, url, title })),
+    openPage: async (targetId) => {
+      const target = (await listTargets(browserUrl)).find((candidate) => candidate.id === targetId);
+      if (!target?.webSocketDebuggerUrl) throw new Error(`The browser at ${browserUrl} has no tab ${targetId}.`);
+      const page = await openTab(target, browserUrl);
+      open4.get(targetId)?.close();
+      open4.set(targetId, page);
+      return page;
+    },
+    close: () => {
+      open4.forEach((page) => page.close());
+      open4.clear();
+    }
+  };
 };
-var detectAdvertisedAddress = (options = {}) => {
-  if (options.override) {
-    return {
-      family: options.override.includes(":") ? 6 : 4,
-      address: options.override
-    };
-  }
-  const ipv4Candidates = [];
-  const ipv6Candidates = [];
-  for (const entries of Object.values(networkInterfaces())) {
-    for (const entry of entries ?? []) {
-      if (entry.internal) {
-        continue;
-      }
-      if (entry.family === "IPv4") {
-        if (isExcludedIpv4Address(entry.address)) {
-          continue;
-        }
-        ipv4Candidates.push(entry.address);
-      } else if (entry.family === "IPv6") {
-        if (isLinkLocalIpv6Address(entry.address)) {
-          continue;
-        }
-        ipv6Candidates.push(entry.address);
-      }
+
+// src/devtools-relay/node-daemon-socket.ts
+import WebSocket2 from "ws";
+var openNodeDaemonSocket = (url, events) => {
+  const socket = new WebSocket2(url);
+  socket.on("open", () => events.open());
+  socket.on("message", (data, isBinary) => {
+    if (isBinary) {
+      socket.close(4008, "binary_frame_not_supported");
+      return;
     }
-  }
-  const preferredIpv4 = ipv4Candidates.find((address) => isPrivateIpv4Address(address)) ?? ipv4Candidates[0];
-  if (preferredIpv4) {
-    return { family: 4, address: preferredIpv4 };
-  }
-  const preferredIpv6 = ipv6Candidates.find((address) => isUniqueLocalIpv6Address(address)) ?? ipv6Candidates[0];
-  if (preferredIpv6) {
-    return { family: 6, address: preferredIpv6 };
-  }
-  return { family: 4, address: "127.0.0.1" };
+    events.message(data.toString());
+  });
+  socket.on("error", () => void 0);
+  socket.on("close", (code, reason) => events.close(code, reason.toString()));
+  return { send: (text) => socket.send(text), close: (code, reason) => socket.close(code, reason) };
 };
 
-// src/daemon/audit.ts
-import { createHash } from "node:crypto";
-import { chmod, mkdir, open, readdir, rm, stat } from "node:fs/promises";
-import { join as join3 } from "node:path";
+// src/link.ts
+import { RPC_METHODS as RPC_METHODS2 } from "@appduct/shared";
+
+// src/rpc/client.ts
+import { join as join4 } from "node:path";
+import { RPC_METHODS } from "@appduct/shared";
 
 // src/daemon/config.ts
 import { readFile } from "node:fs/promises";
@@ -141,6 +219,7 @@ var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
   "daemonLogMaxBytes",
   "eventsLogMaxBytes",
   "policy",
+  "webOrigins",
   "advertisedIp",
   "scheme",
   "restartDaemonOnVersionMismatch"
@@ -201,6 +280,7 @@ var defaultConfig = (paths) => {
     daemonLogMaxBytes: DEFAULT_DAEMON_LOG_MAX_BYTES,
     eventsLogMaxBytes: 10 * 1024 * 1024,
     restartDaemonOnVersionMismatch: false,
+    webOrigins: [],
     policy: {
       default: "allow",
       destructive: "allow"
@@ -265,43 +345,461 @@ var loadConfig = async (paths, options = {}) => {
   if (parsed.eventsLogMaxBytes !== void 0) {
     config.eventsLogMaxBytes = requirePositiveInteger(parsed.eventsLogMaxBytes, "eventsLogMaxBytes");
   }
-  if (parsed.restartDaemonOnVersionMismatch !== void 0) {
-    config.restartDaemonOnVersionMismatch = requireBoolean(
-      parsed.restartDaemonOnVersionMismatch,
-      "restartDaemonOnVersionMismatch"
-    );
+  if (parsed.restartDaemonOnVersionMismatch !== void 0) {
+    config.restartDaemonOnVersionMismatch = requireBoolean(
+      parsed.restartDaemonOnVersionMismatch,
+      "restartDaemonOnVersionMismatch"
+    );
+  }
+  if (parsed.webOrigins !== void 0) {
+    if (!Array.isArray(parsed.webOrigins)) {
+      throw configError("webOrigins", "must be an array of origin strings.");
+    }
+    config.webOrigins = parsed.webOrigins.map((origin) => requireNonEmptyString(origin, "webOrigins"));
+  }
+  if (parsed.policy !== void 0) {
+    if (typeof parsed.policy !== "object" || parsed.policy === null || Array.isArray(parsed.policy)) {
+      throw configError("policy", "must be an object.");
+    }
+    const policy = parsed.policy;
+    for (const key of Object.keys(policy)) {
+      if (!KNOWN_POLICY_KEYS.has(key)) {
+        warn(`Unknown Appduct config key "policy.${key}" is ignored.`);
+      }
+    }
+    if (policy.default !== void 0) {
+      config.policy.default = requirePolicyDecision(policy.default, "policy.default");
+    }
+    if (policy.destructive !== void 0) {
+      config.policy.destructive = requirePolicyDecision(policy.destructive, "policy.destructive");
+    }
+    if (policy.tools !== void 0) {
+      if (typeof policy.tools !== "object" || policy.tools === null || Array.isArray(policy.tools)) {
+        throw configError("policy.tools", "must be an object.");
+      }
+      const tools = {};
+      for (const [toolKey, toolValue] of Object.entries(policy.tools)) {
+        tools[toolKey] = requirePolicyDecision(toolValue, `policy.tools["${toolKey}"]`);
+      }
+      config.policy.tools = tools;
+    }
+  }
+  return config;
+};
+
+// src/daemon/pidfile.ts
+import { readFileSync } from "node:fs";
+import { open, readFile as readFile2, rm } from "node:fs/promises";
+var DaemonAlreadyRunningError = class extends Error {
+  constructor(pid) {
+    super(`Appduct daemon is already running (pid ${pid}).`);
+    this.pid = pid;
+    this.name = "DaemonAlreadyRunningError";
+  }
+};
+var readProcStatus = (pid) => {
+  try {
+    return readFileSync(`/proc/${pid}/status`, "utf8");
+  } catch {
+    return void 0;
+  }
+};
+var isZombie = (pid, readStatus) => {
+  const status = readStatus(pid);
+  if (status === void 0) {
+    return false;
+  }
+  return /^State:\s*Z\b/mu.test(status);
+};
+var isProcessAlive = (pid, readStatus = readProcStatus) => {
+  try {
+    process.kill(pid, 0);
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+  return !isZombie(pid, readStatus);
+};
+var readPidFromFile = async (pidFilePath) => {
+  let contents;
+  try {
+    contents = await readFile2(pidFilePath, "utf8");
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return void 0;
+    }
+    throw error;
+  }
+  const pid = Number.parseInt(contents.trim(), 10);
+  return Number.isInteger(pid) && pid > 0 ? pid : void 0;
+};
+var acquirePidfile = async (pidFilePath, options = {}) => {
+  const pid = options.pid ?? process.pid;
+  for (let attempt = 0; attempt < 5; attempt += 1) {
+    try {
+      const handle = await open(pidFilePath, "wx", 384);
+      try {
+        await handle.writeFile(String(pid), "utf8");
+      } finally {
+        await handle.close();
+      }
+      let released = false;
+      return {
+        pid,
+        release: async () => {
+          if (released) {
+            return;
+          }
+          released = true;
+          await rm(pidFilePath, { force: true });
+        }
+      };
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+      const existingPid = await readPidFromFile(pidFilePath);
+      if (existingPid !== void 0 && isProcessAlive(existingPid)) {
+        throw new DaemonAlreadyRunningError(existingPid);
+      }
+      await rm(pidFilePath, { force: true });
+      await options.onStaleTakeover?.();
+    }
+  }
+  throw new Error(`Failed to acquire the Appduct daemon pidfile at "${pidFilePath}".`);
+};
+
+// src/daemon/state-dir.ts
+import { join } from "node:path";
+import { mkdir, chmod } from "node:fs/promises";
+var getStateDirPaths = (stateDir) => {
+  return {
+    root: stateDir,
+    socketPath: join(stateDir, "daemon.sock"),
+    pidFilePath: join(stateDir, "daemon.pid"),
+    logFilePath: join(stateDir, "daemon.log"),
+    eventsLogPath: join(stateDir, "events.log"),
+    keyPath: join(stateDir, "key.pem"),
+    configPath: join(stateDir, "config.json"),
+    auditDir: join(stateDir, "audit"),
+    spawnLockPath: join(stateDir, "daemon.spawn.lock")
+  };
+};
+var getSocketPath = (paths) => {
+  return paths.socketPath;
+};
+var ensureStateDir = async (stateDir) => {
+  const paths = getStateDirPaths(stateDir);
+  await mkdir(paths.auditDir, { recursive: true });
+  await chmod(paths.root, 448);
+  await chmod(paths.auditDir, 448);
+  return paths;
+};
+
+// src/package-root.ts
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
+import { dirname, join as join2 } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_NAME = "appduct";
+var cached;
+var getPackageRoot = () => {
+  if (cached !== void 0) {
+    return cached;
+  }
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (; ; ) {
+    const candidate = join2(dir, "package.json");
+    if (existsSync(candidate)) {
+      let name;
+      try {
+        name = JSON.parse(readFileSync2(candidate, "utf8")).name;
+      } catch {
+      }
+      if (name === PACKAGE_NAME) {
+        cached = dir;
+        return dir;
+      }
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      throw new Error(`Could not locate the "${PACKAGE_NAME}" package root above ${import.meta.url}.`);
+    }
+    dir = parent;
+  }
+};
+
+// src/package-version.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { join as join3 } from "node:path";
+var DAEMON_VERSION_OVERRIDE_ENV = "APPDUCT_DAEMON_VERSION_OVERRIDE";
+var isTestRuntime = (env) => {
+  return Boolean(env.VITEST) || env.NODE_ENV === "test";
+};
+var cached2;
+var getPackageVersion = () => {
+  cached2 ??= JSON.parse(readFileSync3(join3(getPackageRoot(), "package.json"), "utf8")).version;
+  return cached2;
+};
+var getDaemonReportedVersion = (env = process.env) => {
+  if (!isTestRuntime(env)) {
+    return getPackageVersion();
+  }
+  const override = env[DAEMON_VERSION_OVERRIDE_ENV];
+  return override !== void 0 && override.length > 0 ? override : getPackageVersion();
+};
+
+// src/rpc/client.ts
+var defaultBinPath = join4(getPackageRoot(), "bin.js");
+var DaemonRpcError = class extends Error {
+  constructor(code, message, data) {
+    super(message);
+    this.code = code;
+    this.data = data;
+    this.name = "DaemonRpcError";
+  }
+};
+var DaemonUnavailableError = class extends Error {
+  constructor(message, reason = "unreachable") {
+    super(message);
+    this.reason = reason;
+    this.name = "DaemonUnavailableError";
+  }
+};
+var describeLiveState = (state) => {
+  const parts = [];
+  if (state.sessions > 0) {
+    parts.push(`${state.sessions} connected session(s)`);
+  }
+  if (state.pendingLinks > 0) {
+    parts.push(`${state.pendingLinks} unclaimed link(s)`);
+  }
+  return parts.join(" and ");
+};
+var DaemonVersionMismatchError = class extends Error {
+  constructor(daemonVersion, clientVersion, live, message) {
+    super(
+      message ?? `The running Appduct daemon is version ${daemonVersion}, but this client is version ${clientVersion}. It was not restarted automatically because ${describeLiveState(live)} would be lost. Run "appduct daemon stop" once that state is expendable, or force it with "--daemon-restart".`
+    );
+    this.daemonVersion = daemonVersion;
+    this.clientVersion = clientVersion;
+    this.name = "DaemonVersionMismatchError";
+    this.sessionCount = live.sessions;
+    this.pendingLinkCount = live.pendingLinks;
+  }
+  sessionCount;
+  pendingLinkCount;
+};
+var isConnectionMissingError = (error) => {
+  const code = error.code;
+  return code === "ENOENT" || code === "ECONNREFUSED";
+};
+var isDaemonUnreachableError = (error) => {
+  return error instanceof DaemonUnavailableError || isConnectionMissingError(error);
+};
+
+// src/errors.ts
+var EXIT_CODE_BY_ERROR_TYPE = {
+  usage_error: 64,
+  validation_error: 65,
+  // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
+  // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
+  // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
+  // assertion failure.
+  inspection_error: 66,
+  connection_error: 70,
+  session_error: 71,
+  tool_error: 72,
+  permission_error: 77,
+  internal_error: 1,
+  // `doctor --assert-present`/`--assert-absent`: the artifact was inspected successfully and the
+  // assertion did not hold. Distinct from `inspection_error` (66) — this means the answer is known
+  // and it's "no", not "couldn't tell" — and distinct from `internal_error` (1) so a caller can't
+  // conflate a normal assertion failure with an unexpected crash.
+  assertion_error: 3
+};
+var RPC_ERROR_EXIT_CLASS = {
+  no_session: "session_error",
+  ambiguous_session: "session_error",
+  unknown_session: "session_error",
+  session_not_active: "session_error",
+  session_suspended: "session_error",
+  tool_not_found: "tool_error",
+  tool_input_validation_error: "tool_error",
+  tool_output_validation_error: "tool_error",
+  tool_execution_error: "tool_error",
+  tool_serialization_error: "tool_error",
+  tool_timeout: "tool_error",
+  tool_cancelled: "tool_error",
+  policy_denied: "permission_error",
+  invalid_request: "validation_error"
+};
+var AppductCliError = class extends Error {
+  type;
+  details;
+  constructor(type, message, details) {
+    super(message);
+    this.name = "AppductCliError";
+    this.type = type;
+    this.details = details;
+  }
+};
+var connectionError = (message, details) => {
+  return new AppductCliError("connection_error", message, details);
+};
+var isAppductCliError = (value) => {
+  return value instanceof AppductCliError;
+};
+var rpcErrorClass = (error) => {
+  const type = error.data?.type;
+  return type ? RPC_ERROR_EXIT_CLASS[type] : void 0;
+};
+var toCliError = (error) => {
+  if (isAppductCliError(error)) {
+    return {
+      type: error.type,
+      message: error.message,
+      details: error.details
+    };
+  }
+  if (error instanceof DaemonVersionMismatchError) {
+    return {
+      type: "connection_error",
+      message: error.message,
+      details: {
+        daemon_version: error.daemonVersion,
+        client_version: error.clientVersion,
+        session_count: error.sessionCount,
+        pending_link_count: error.pendingLinkCount
+      }
+    };
+  }
+  if (error instanceof DaemonRpcError && error.data?.type) {
+    return {
+      type: error.data.type,
+      message: error.message,
+      details: error.data.details
+    };
+  }
+  if (isDaemonUnreachableError(error)) {
+    return {
+      type: "connection_error",
+      message: error instanceof Error ? error.message : "The Appduct daemon is unreachable."
+    };
+  }
+  if (error instanceof Error) {
+    return {
+      type: "internal_error",
+      message: error.message
+    };
+  }
+  return {
+    type: "internal_error",
+    message: "An unexpected error occurred.",
+    details: error
+  };
+};
+var getExitCodeForError = (error) => {
+  if (isAppductCliError(error)) {
+    return EXIT_CODE_BY_ERROR_TYPE[error.type];
+  }
+  if (error instanceof DaemonVersionMismatchError) {
+    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
+  }
+  if (error instanceof DaemonRpcError) {
+    const cliErrorClass = rpcErrorClass(error);
+    return EXIT_CODE_BY_ERROR_TYPE[cliErrorClass ?? "internal_error"];
+  }
+  if (isDaemonUnreachableError(error)) {
+    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
+  }
+  return EXIT_CODE_BY_ERROR_TYPE.internal_error;
+};
+
+// src/scheme.ts
+import { dirname as dirname2, join as join5, resolve } from "node:path";
+
+// src/native-scheme.ts
+var MAX_PROBE_FILE_BYTES = 2 * 1024 * 1024;
+
+// src/scheme.ts
+var PROJECT_CONFIG_DIR = ".appduct";
+var PROJECT_CONFIG_FILENAME = "config.json";
+var PROJECT_CONFIG_RELATIVE_PATH = join5(PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+
+// src/link.ts
+var composeWebLink = (pageUrl, result) => {
+  const payload = result.deepLinkPayload;
+  return {
+    sessionId: result.sessionId,
+    url: `${pageUrl.split("#")[0]}#appduct=${payload}`,
+    script: `window.__APPDUCT__.connect("${payload}")`,
+    expiresAt: result.expiresAt
+  };
+};
+
+// src/daemon/address.ts
+import { networkInterfaces } from "node:os";
+import {
+  isLinkLocalIpv6Address,
+  isPrivateIpv4Address,
+  isUniqueLocalIpv6Address
+} from "@appduct/shared";
+var isDockerDefaultBridgeAddress = (address) => {
+  return address.startsWith("172.17.");
+};
+var isCgnatIpv4Address = (address) => {
+  const parts = address.split(".");
+  if (parts.length !== 4) {
+    return false;
+  }
+  const first = Number(parts[0]);
+  const second = Number(parts[1]);
+  return first === 100 && Number.isInteger(second) && second >= 64 && second <= 127;
+};
+var isExcludedIpv4Address = (address) => {
+  return isDockerDefaultBridgeAddress(address) || isCgnatIpv4Address(address);
+};
+var detectAdvertisedAddress = (options = {}) => {
+  if (options.override) {
+    return {
+      family: options.override.includes(":") ? 6 : 4,
+      address: options.override
+    };
   }
-  if (parsed.policy !== void 0) {
-    if (typeof parsed.policy !== "object" || parsed.policy === null || Array.isArray(parsed.policy)) {
-      throw configError("policy", "must be an object.");
-    }
-    const policy = parsed.policy;
-    for (const key of Object.keys(policy)) {
-      if (!KNOWN_POLICY_KEYS.has(key)) {
-        warn(`Unknown Appduct config key "policy.${key}" is ignored.`);
-      }
-    }
-    if (policy.default !== void 0) {
-      config.policy.default = requirePolicyDecision(policy.default, "policy.default");
-    }
-    if (policy.destructive !== void 0) {
-      config.policy.destructive = requirePolicyDecision(policy.destructive, "policy.destructive");
-    }
-    if (policy.tools !== void 0) {
-      if (typeof policy.tools !== "object" || policy.tools === null || Array.isArray(policy.tools)) {
-        throw configError("policy.tools", "must be an object.");
+  const ipv4Candidates = [];
+  const ipv6Candidates = [];
+  for (const entries of Object.values(networkInterfaces())) {
+    for (const entry of entries ?? []) {
+      if (entry.internal) {
+        continue;
       }
-      const tools = {};
-      for (const [toolKey, toolValue] of Object.entries(policy.tools)) {
-        tools[toolKey] = requirePolicyDecision(toolValue, `policy.tools["${toolKey}"]`);
+      if (entry.family === "IPv4") {
+        if (isExcludedIpv4Address(entry.address)) {
+          continue;
+        }
+        ipv4Candidates.push(entry.address);
+      } else if (entry.family === "IPv6") {
+        if (isLinkLocalIpv6Address(entry.address)) {
+          continue;
+        }
+        ipv6Candidates.push(entry.address);
       }
-      config.policy.tools = tools;
     }
   }
-  return config;
+  const preferredIpv4 = ipv4Candidates.find((address) => isPrivateIpv4Address(address)) ?? ipv4Candidates[0];
+  if (preferredIpv4) {
+    return { family: 4, address: preferredIpv4 };
+  }
+  const preferredIpv6 = ipv6Candidates.find((address) => isUniqueLocalIpv6Address(address)) ?? ipv6Candidates[0];
+  if (preferredIpv6) {
+    return { family: 6, address: preferredIpv6 };
+  }
+  return { family: 4, address: "127.0.0.1" };
 };
 
 // src/daemon/audit.ts
+import { createHash } from "node:crypto";
+import { chmod as chmod2, mkdir as mkdir2, open as open2, readdir, rm as rm2, stat } from "node:fs/promises";
+import { join as join6 } from "node:path";
 var canonicalize = (value) => {
   if (Array.isArray(value)) {
     return value.map(canonicalize);
@@ -338,13 +836,13 @@ var oldestRetainedStamp = (now, retentionDays) => {
   return Number.isNaN(cutoff.getTime()) ? "0000-00-00" : dayStamp(cutoff);
 };
 var auditFilePathForDate = (auditDir, date) => {
-  return join3(auditDir, `${dayStamp(date)}.jsonl`);
+  return join6(auditDir, `${dayStamp(date)}.jsonl`);
 };
 var appendLine = async (filePath, line) => {
-  const handle = await open(filePath, "a", 384);
+  const handle = await open2(filePath, "a", 384);
   try {
     await handle.appendFile(line);
-    await chmod(filePath, 384);
+    await chmod2(filePath, 384);
   } finally {
     await handle.close();
   }
@@ -397,7 +895,7 @@ var createAuditLogger = (options) => {
         continue;
       }
       try {
-        await rm(join3(options.auditDir, file.name), { force: true });
+        await rm2(join6(options.auditDir, file.name), { force: true });
         deleted += 1;
       } catch (error) {
         failed += 1;
@@ -415,7 +913,7 @@ var createAuditLogger = (options) => {
     const filePath = auditFilePathForDate(options.auditDir, now);
     queue = queue.then(async () => {
       try {
-        await mkdir(options.auditDir, { recursive: true });
+        await mkdir2(options.auditDir, { recursive: true });
         await appendLine(filePath, line);
       } catch (error) {
         failedWrites += 1;
@@ -425,8 +923,8 @@ var createAuditLogger = (options) => {
   };
   const prune = () => {
     let settle;
-    const result = new Promise((resolve) => {
-      settle = resolve;
+    const result = new Promise((resolve2) => {
+      settle = resolve2;
     });
     queue = queue.then(async () => {
       try {
@@ -448,7 +946,7 @@ var createAuditLogger = (options) => {
     let bytes = 0;
     for (const file of listing.files) {
       try {
-        bytes += (await stat(join3(options.auditDir, file.name))).size;
+        bytes += (await stat(join6(options.auditDir, file.name))).size;
         files += 1;
       } catch {
       }
@@ -484,6 +982,8 @@ var RpcApplicationError = class extends Error {
     this.name = "RpcApplicationError";
   }
 };
+var appBackgroundedMessage = (alias) => `Session "${alias}" is suspended because the app is in the background. Bring the app to the foreground to resume it.`;
+var appReconnectedMessage = (alias) => `Session "${alias}" reconnected while the call was pending, so its result was lost. The call can be retried.`;
 
 // src/daemon/timers.ts
 var systemTimers = {
@@ -504,6 +1004,7 @@ var clampTimeout = (timeoutMs) => {
 };
 var TERMINATING_KIND_ERROR_TYPES = {
   session_suspended: "session_suspended",
+  session_resumed: "session_suspended",
   session_revoked: "unknown_session",
   session_expired: "unknown_session"
 };
@@ -525,7 +1026,7 @@ var createCallsManager = (options) => {
   };
   const call = (session, name, args, timeoutMs) => {
     const callId = generateCallId();
-    const result = new Promise((resolve, reject) => {
+    const result = new Promise((resolve2, reject) => {
       const effectiveTimeoutMs = clampTimeout(timeoutMs);
       const timer = timers.setTimeout(() => {
         const pending = takePending(session.sessionId, callId);
@@ -538,7 +1039,7 @@ var createCallsManager = (options) => {
         sessionMap = /* @__PURE__ */ new Map();
         pendingBySession.set(session.sessionId, sessionMap);
       }
-      sessionMap.set(callId, { alias: session.alias, resolve, reject, timer });
+      sessionMap.set(callId, { alias: session.alias, resolve: resolve2, reject, timer });
       const message = {
         type: "tool_call",
         session_id: session.sessionId,
@@ -586,7 +1087,7 @@ var createCallsManager = (options) => {
     const message = { type: "tool_cancel", session_id: sessionId, id: callId, reason };
     return options.sendCancel(sessionId, message);
   };
-  const rejectSession = (sessionId, errorType) => {
+  const rejectSession = (sessionId, errorType, options2 = {}) => {
     const sessionMap = pendingBySession.get(sessionId);
     if (!sessionMap) {
       return;
@@ -594,13 +1095,20 @@ var createCallsManager = (options) => {
     pendingBySession.delete(sessionId);
     for (const pending of sessionMap.values()) {
       timers.clearTimeout(pending.timer);
-      pending.reject(new RpcApplicationError(errorType, `Session transitioned while the call was pending.`));
+      pending.reject(
+        new RpcApplicationError(
+          errorType,
+          options2.message?.(pending.alias) ?? "Session transitioned while the call was pending."
+        )
+      );
     }
   };
   const unsubscribeFromEventBus = options.eventBus.subscribe((event) => {
     const errorType = TERMINATING_KIND_ERROR_TYPES[event.kind];
     if (errorType && event.sessionId) {
-      rejectSession(event.sessionId, errorType);
+      const backgrounded = event.kind === "session_suspended" && event.data.reason === "app_backgrounded";
+      const message = event.kind === "session_resumed" ? appReconnectedMessage : backgrounded ? appBackgroundedMessage : void 0;
+      rejectSession(event.sessionId, errorType, { message });
     }
   });
   const disposeAll = () => {
@@ -781,8 +1289,14 @@ var createEventsLog = (options) => {
 };
 
 // src/daemon/listener.ts
+import { createServer as createHttpServer } from "node:http";
 import { createServer as createHttpsServer } from "node:https";
-import { isSessionClaimMessage, isSessionResumeMessage, isSessionBoundMessage } from "@appduct/shared";
+import { createServer as createNetServer } from "node:net";
+import {
+  isSessionClaimMessage,
+  isSessionResumeMessage,
+  isSessionBoundMessage
+} from "@appduct/shared";
 import { WebSocketServer } from "ws";
 
 // src/daemon/sessions.ts
@@ -791,6 +1305,8 @@ import {
   isEventMessage,
   isToolCallProgressMessage,
   isToolErrorMessage,
+  isEventRegistryDeltaMessage,
+  isEventRegistrySnapshotMessage,
   isToolRegistryDeltaMessage,
   isToolRegistrySnapshotMessage,
   isToolResultMessage,
@@ -821,13 +1337,13 @@ var createPendingLinkRegistry = (options) => {
     options.eventBus.drop(sessionId);
   };
   return {
-    create: (ttlSeconds, addressOverride) => {
+    create: (ttlSeconds, addressOverride, transport = "native") => {
       const sessionId = generateSessionId();
       const token = randomBytes2(TOKEN_BYTES);
       const createdAt = options.clock.now();
       const expiresAt = new Date(createdAt.getTime() + ttlSeconds * 1e3);
-      const detectedEndpoint = options.getEndpoint();
-      const endpoint = addressOverride ? {
+      const detectedEndpoint = options.getEndpoint(transport);
+      const endpoint = addressOverride && transport === "native" ? {
         family: addressOverride.includes(":") ? 6 : 4,
         address: addressOverride,
         port: detectedEndpoint.port
@@ -839,7 +1355,7 @@ var createPendingLinkRegistry = (options) => {
           record.timer = options.timers.setTimeout(() => discard(sessionId), ttlSeconds * 1e3);
         }
       }, ttlSeconds * 1e3);
-      const link = { sessionId, token, createdAt, expiresAt };
+      const link = { sessionId, token, createdAt, expiresAt, transport };
       records.set(sessionId, { link, attempts: 0, timer });
       const deepLinkPayload = encodeBootstrap({
         ...endpoint,
@@ -888,7 +1404,7 @@ var createPendingLinkRegistry = (options) => {
 };
 
 // src/daemon/registry.ts
-var createToolRegistry = (onChange) => {
+var createRegistry = (onChange) => {
   let tools = /* @__PURE__ */ new Map();
   const notify = () => {
     onChange?.();
@@ -918,6 +1434,8 @@ var RESUME_TOKEN_BYTES = 32;
 var POST_CLAIM_MESSAGE_TYPES = /* @__PURE__ */ new Set([
   "tool_registry_snapshot",
   "tool_registry_delta",
+  "event_registry_snapshot",
+  "event_registry_delta",
   "tool_result",
   "tool_error",
   "tool_call_progress",
@@ -988,6 +1506,7 @@ var createSessionManager = (options) => {
       createdAt: session.createdAt.toISOString(),
       claimedAt: session.claimedAt.toISOString(),
       ...session.suspendedAt ? { suspendedAt: session.suspendedAt.toISOString() } : {},
+      ...session.suspendReason ? { suspendReason: session.suspendReason } : {},
       toolCount: session.registry.count()
     };
   };
@@ -1024,7 +1543,8 @@ var createSessionManager = (options) => {
       alias: session.alias,
       resume_token: session.resumeToken.toString("base64url"),
       keepalive_interval_s: options.keepaliveIntervalSeconds,
-      grace_s: options.graceSeconds
+      grace_s: options.graceSeconds,
+      event_registry: true
     };
     socket.send(JSON.stringify(ack), (error) => {
       if (error) {
@@ -1032,17 +1552,18 @@ var createSessionManager = (options) => {
       }
     });
   };
-  const suspend = (sessionId) => {
+  const suspend = (sessionId, reason) => {
     const session = sessions.get(sessionId);
     if (!session || session.state !== "active") {
       return;
     }
     session.state = "suspended";
     session.suspendedAt = clock.now();
+    session.suspendReason = reason;
     session.socket = void 0;
     session.missedPongs = 0;
     session.graceTimer = timers.setTimeout(() => expire(sessionId), options.graceSeconds * 1e3);
-    emit("session_suspended", session.sessionId, session.alias, {});
+    emit("session_suspended", session.sessionId, session.alias, { reason });
   };
   const expire = (sessionId) => {
     const session = sessions.get(sessionId);
@@ -1059,9 +1580,10 @@ var createSessionManager = (options) => {
     socket.on("pong", () => {
       session.missedPongs = 0;
     });
-    socket.on("close", () => {
+    socket.on("close", (code, reason) => {
       if (session.socket === socket) {
-        suspend(session.sessionId);
+        const backgrounded = code === 1001 && reason.toString("utf8") === "app_backgrounded";
+        suspend(session.sessionId, backgrounded ? "app_backgrounded" : "connection_lost");
       }
     });
   };
@@ -1073,7 +1595,7 @@ var createSessionManager = (options) => {
       if (session.missedPongs >= 2) {
         const staleSocket = session.socket;
         session.socket = void 0;
-        suspend(session.sessionId);
+        suspend(session.sessionId, "connection_lost");
         staleSocket.terminate();
         continue;
       }
@@ -1084,10 +1606,11 @@ var createSessionManager = (options) => {
       }
     }
   }, options.keepaliveIntervalSeconds * 1e3);
-  const createLink = (ttlSeconds, addressOverride) => {
+  const createLink = (ttlSeconds, addressOverride, transport) => {
     const { link, deepLinkPayload, endpoint } = pendingLinks.create(
       ttlSeconds ?? options.linkTtlSeconds,
-      addressOverride
+      addressOverride,
+      transport
     );
     return {
       sessionId: link.sessionId,
@@ -1096,7 +1619,7 @@ var createSessionManager = (options) => {
       expiresAt: Math.floor(link.expiresAt.getTime() / 1e3)
     };
   };
-  const handleClaim = (socket, message) => {
+  const handleClaim = (socket, message, transport) => {
     const pending = pendingLinks.get(message.session_id);
     if (!pending) {
       if (sessions.has(message.session_id)) {
@@ -1106,6 +1629,10 @@ var createSessionManager = (options) => {
       }
       return null;
     }
+    if (pending.transport !== transport) {
+      closeSocket(socket, 1008, "wrong_transport");
+      return null;
+    }
     const nowMs = clock.now().getTime();
     if (pending.expiresAt.getTime() <= nowMs) {
       pendingLinks.discard(pending.sessionId);
@@ -1135,11 +1662,15 @@ var createSessionManager = (options) => {
       device,
       createdAt: pending.createdAt,
       claimedAt: clock.now(),
+      transport,
       resumeToken: randomBytes3(RESUME_TOKEN_BYTES),
       socket,
       missedPongs: 0,
-      registry: createToolRegistry(() => {
+      registry: createRegistry(() => {
         emit("tools_changed", sessionId, alias, { toolCount: session.registry.count() });
+      }),
+      eventRegistry: createRegistry(() => {
+        emit("events_changed", sessionId, alias, { eventCount: session.eventRegistry.count() });
       })
     };
     sessions.set(sessionId, session);
@@ -1148,12 +1679,16 @@ var createSessionManager = (options) => {
     emit("session_claimed", sessionId, alias, { device });
     return sessionId;
   };
-  const handleResume = (socket, message) => {
+  const handleResume = (socket, message, transport) => {
     const session = sessions.get(message.session_id);
     if (!session) {
       closeSocket(socket, 1008, "unknown_session");
       return null;
     }
+    if (session.transport !== transport) {
+      closeSocket(socket, 1008, "wrong_transport");
+      return null;
+    }
     const candidateToken = decodeFixedLengthToken(message.resume_token, session.resumeToken.length);
     if (!tokensMatch(candidateToken, session.resumeToken)) {
       closeSocket(socket, 1008, "invalid_resume_token");
@@ -1171,6 +1706,7 @@ var createSessionManager = (options) => {
     session.resumeToken = randomBytes3(RESUME_TOKEN_BYTES);
     session.state = "active";
     session.suspendedAt = void 0;
+    session.suspendReason = void 0;
     session.socket = socket;
     session.missedPongs = 0;
     attachSocketHandlers(session);
@@ -1184,6 +1720,9 @@ var createSessionManager = (options) => {
       closeSocket(socket, 1008, "unknown_session");
       return;
     }
+    if (socket !== session.socket) {
+      return;
+    }
     switch (message.type) {
       case "tool_registry_snapshot": {
         if (!isToolRegistrySnapshotMessage(message)) {
@@ -1205,6 +1744,26 @@ var createSessionManager = (options) => {
         }
         return;
       }
+      case "event_registry_snapshot": {
+        if (!isEventRegistrySnapshotMessage(message)) {
+          closeSocket(socket, 1008, "invalid_registry");
+          return;
+        }
+        session.eventRegistry.snapshot(message.events);
+        return;
+      }
+      case "event_registry_delta": {
+        if (!isEventRegistryDeltaMessage(message)) {
+          closeSocket(socket, 1008, "invalid_registry");
+          return;
+        }
+        if (message.operation === "upsert") {
+          session.eventRegistry.upsert(message.event);
+        } else {
+          session.eventRegistry.remove(message.name);
+        }
+        return;
+      }
       case "tool_result": {
         if (!isToolResultMessage(message)) {
           closeSocket(socket, 1008, "invalid_message");
@@ -1272,7 +1831,14 @@ var createSessionManager = (options) => {
   };
   const resolveForTools = (selector) => {
     const session = resolveSession(selector);
-    return { sessionId: session.sessionId, alias: session.alias, state: session.state, registry: session.registry };
+    return {
+      sessionId: session.sessionId,
+      alias: session.alias,
+      state: session.state,
+      suspendReason: session.suspendReason,
+      registry: session.registry,
+      eventRegistry: session.eventRegistry
+    };
   };
   const sendToApp = (sessionId, message) => {
     const session = sessions.get(sessionId);
@@ -1306,19 +1872,12 @@ var createSessionManager = (options) => {
 // src/daemon/listener.ts
 var DEFAULT_PRE_CLAIM_TIMEOUT_MS = 1e4;
 var MAX_PAYLOAD_BYTES = 256 * 1024;
+var MAX_PORT_ATTEMPTS = 5;
 var isRecord = (value) => {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 };
-var startListener = async (options) => {
-  const timers = options.timers ?? systemTimers;
-  const preClaimTimeoutMs = options.preClaimTimeoutMs ?? DEFAULT_PRE_CLAIM_TIMEOUT_MS;
-  const material = options.tls.current();
-  const httpsServer = createHttpsServer({ key: material.keyPem, cert: material.certPem });
-  httpsServer.on("error", () => {
-  });
-  const wss = new WebSocketServer({ server: httpsServer, maxPayload: MAX_PAYLOAD_BYTES });
-  wss.on("error", () => {
-  });
+var attachFrameGate = (wss, options) => {
+  const { timers, preClaimTimeoutMs } = options;
   wss.on("connection", (socket) => {
     socket.on("error", () => {
     });
@@ -1349,7 +1908,7 @@ var startListener = async (options) => {
       }
       if (claimedSessionId === null) {
         if (isSessionClaimMessage(parsed)) {
-          const result = options.sessionManager.handleClaim(socket, parsed);
+          const result = options.sessionManager.handleClaim(socket, parsed, options.transport);
           if (result) {
             claimedSessionId = result;
             timers.clearTimeout(preClaimTimer);
@@ -1357,7 +1916,7 @@ var startListener = async (options) => {
           return;
         }
         if (isSessionResumeMessage(parsed)) {
-          const result = options.sessionManager.handleResume(socket, parsed);
+          const result = options.sessionManager.handleResume(socket, parsed, options.transport);
           if (result) {
             claimedSessionId = result;
             timers.clearTimeout(preClaimTimer);
@@ -1378,39 +1937,138 @@ var startListener = async (options) => {
       options.sessionManager.handlePostClaimMessage(claimedSessionId, socket, parsed);
     });
   });
-  await new Promise((resolve, reject) => {
+};
+var listen = (server, port, host) => {
+  return new Promise((resolve2, reject) => {
     const onError = (error) => {
-      httpsServer.off("listening", onListening);
+      server.off("listening", onListening);
       reject(error);
     };
     const onListening = () => {
-      httpsServer.off("error", onError);
-      resolve();
+      server.off("error", onError);
+      resolve2();
     };
-    httpsServer.once("error", onError);
-    httpsServer.once("listening", onListening);
-    httpsServer.listen(options.port);
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, host);
+  });
+};
+var closeServer = (wss, server) => {
+  return new Promise((resolve2) => {
+    for (const client of wss.clients) {
+      client.terminate();
+    }
+    wss.close(() => {
+      server.closeAllConnections();
+      server.close(() => resolve2());
+    });
+  });
+};
+var boundPort = (server) => {
+  const address = server.address();
+  return address && typeof address !== "string" ? address.port : void 0;
+};
+var isAddressInUse = (error) => {
+  return error.code === "EADDRINUSE";
+};
+var portInUseError = (port) => {
+  return new Error(
+    `Port ${port} is already in use by another program. Stop that program, or set a different wssPort in config.json.`
+  );
+};
+var startListener = async (options) => {
+  const timers = options.timers ?? systemTimers;
+  const preClaimTimeoutMs = options.preClaimTimeoutMs ?? DEFAULT_PRE_CLAIM_TIMEOUT_MS;
+  const material = options.tls.current();
+  const httpsServer = createHttpsServer({ key: material.keyPem, cert: material.certPem });
+  httpsServer.on("error", () => {
+  });
+  const wss = new WebSocketServer({ server: httpsServer, maxPayload: MAX_PAYLOAD_BYTES });
+  wss.on("error", () => {
   });
+  attachFrameGate(wss, { sessionManager: options.sessionManager, transport: "native", preClaimTimeoutMs, timers });
+  let loopbackServer;
+  for (let attempt = 1; ; attempt += 1) {
+    try {
+      await listen(httpsServer, options.port);
+    } catch (error) {
+      throw isAddressInUse(error) ? portInUseError(options.port) : error;
+    }
+    if (!options.bindLoopback) {
+      break;
+    }
+    const port = boundPort(httpsServer);
+    const candidate = createNetServer((socket) => httpsServer.emit("connection", socket));
+    candidate.on("error", () => {
+    });
+    try {
+      await listen(candidate, port, "127.0.0.1");
+      loopbackServer = candidate;
+      break;
+    } catch (error) {
+      await new Promise((resolve2) => httpsServer.close(() => resolve2()));
+      if (!isAddressInUse(error)) {
+        throw error;
+      }
+      if (options.port !== 0) {
+        throw portInUseError(port);
+      }
+      if (attempt === MAX_PORT_ATTEMPTS) {
+        throw new Error(`Could not find a free port: ${MAX_PORT_ATTEMPTS} ports in a row were in use on 127.0.0.1.`);
+      }
+    }
+  }
   return {
     httpsServer,
     wss,
-    port: () => {
-      const address = httpsServer.address();
-      return address && typeof address !== "string" ? address.port : void 0;
-    },
+    port: () => boundPort(httpsServer),
     applyTls: (nextMaterial) => {
       const server = httpsServer;
       server.setSecureContext?.({ key: nextMaterial.keyPem, cert: nextMaterial.certPem });
     },
-    close: () => new Promise((resolve) => {
-      for (const client of wss.clients) {
-        client.terminate();
+    close: () => {
+      loopbackServer?.close();
+      return closeServer(wss, httpsServer);
+    }
+  };
+};
+var LOOPBACK_HOSTNAMES = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "[::1]"]);
+var isLoopbackOrigin = (origin) => {
+  try {
+    const url = new URL(origin);
+    return (url.protocol === "http:" || url.protocol === "https:") && LOOPBACK_HOSTNAMES.has(url.hostname);
+  } catch {
+    return false;
+  }
+};
+var startWebListener = async (options) => {
+  const timers = options.timers ?? systemTimers;
+  const preClaimTimeoutMs = options.preClaimTimeoutMs ?? DEFAULT_PRE_CLAIM_TIMEOUT_MS;
+  const allowed = new Set(options.origins);
+  const httpServer = createHttpServer((_request, response) => {
+    response.writeHead(426, { "content-type": "text/plain" });
+    response.end("Appduct web listener: WebSocket upgrades only.");
+  });
+  httpServer.on("error", () => {
+  });
+  const wss = new WebSocketServer({
+    server: httpServer,
+    maxPayload: MAX_PAYLOAD_BYTES,
+    verifyClient: ({ origin }, callback) => {
+      if (origin === void 0 || isLoopbackOrigin(origin) || allowed.has(origin)) {
+        callback(true);
+      } else {
+        callback(false, 403, "Forbidden");
       }
-      wss.close(() => {
-        httpsServer.closeAllConnections();
-        httpsServer.close(() => resolve());
-      });
-    })
+    }
+  });
+  wss.on("error", () => {
+  });
+  attachFrameGate(wss, { sessionManager: options.sessionManager, transport: "web", preClaimTimeoutMs, timers });
+  await listen(httpServer, 0, "127.0.0.1");
+  return {
+    port: () => boundPort(httpServer),
+    close: () => closeServer(wss, httpServer)
   };
 };
 
@@ -1424,88 +2082,7 @@ var evaluate = (descriptor, session, policy) => {
   if (descriptor.annotations?.destructiveHint === true) {
     return policy.destructive;
   }
-  return policy.default;
-};
-
-// src/daemon/pidfile.ts
-import { readFileSync as readFileSync3 } from "node:fs";
-import { open as open2, readFile as readFile2, rm as rm2 } from "node:fs/promises";
-var DaemonAlreadyRunningError = class extends Error {
-  constructor(pid) {
-    super(`Appduct daemon is already running (pid ${pid}).`);
-    this.pid = pid;
-    this.name = "DaemonAlreadyRunningError";
-  }
-};
-var readProcStatus = (pid) => {
-  try {
-    return readFileSync3(`/proc/${pid}/status`, "utf8");
-  } catch {
-    return void 0;
-  }
-};
-var isZombie = (pid, readStatus) => {
-  const status = readStatus(pid);
-  if (status === void 0) {
-    return false;
-  }
-  return /^State:\s*Z\b/mu.test(status);
-};
-var isProcessAlive = (pid, readStatus = readProcStatus) => {
-  try {
-    process.kill(pid, 0);
-  } catch (error) {
-    return error.code === "EPERM";
-  }
-  return !isZombie(pid, readStatus);
-};
-var readPidFromFile = async (pidFilePath) => {
-  let contents;
-  try {
-    contents = await readFile2(pidFilePath, "utf8");
-  } catch (error) {
-    if (error.code === "ENOENT") {
-      return void 0;
-    }
-    throw error;
-  }
-  const pid = Number.parseInt(contents.trim(), 10);
-  return Number.isInteger(pid) && pid > 0 ? pid : void 0;
-};
-var acquirePidfile = async (pidFilePath, options = {}) => {
-  const pid = options.pid ?? process.pid;
-  for (let attempt = 0; attempt < 5; attempt += 1) {
-    try {
-      const handle = await open2(pidFilePath, "wx", 384);
-      try {
-        await handle.writeFile(String(pid), "utf8");
-      } finally {
-        await handle.close();
-      }
-      let released = false;
-      return {
-        pid,
-        release: async () => {
-          if (released) {
-            return;
-          }
-          released = true;
-          await rm2(pidFilePath, { force: true });
-        }
-      };
-    } catch (error) {
-      if (error.code !== "EEXIST") {
-        throw error;
-      }
-      const existingPid = await readPidFromFile(pidFilePath);
-      if (existingPid !== void 0 && isProcessAlive(existingPid)) {
-        throw new DaemonAlreadyRunningError(existingPid);
-      }
-      await rm2(pidFilePath, { force: true });
-      await options.onStaleTakeover?.();
-    }
-  }
-  throw new Error(`Failed to acquire the Appduct daemon pidfile at "${pidFilePath}".`);
+  return policy.default;
 };
 
 // src/daemon/node-append-only-file.ts
@@ -1541,7 +2118,7 @@ var NodeAppendOnlyFile = class {
 
 // src/daemon/rpc-server.ts
 import { createServer } from "node:net";
-import { chmod as chmod2, rm as rm3 } from "node:fs/promises";
+import { chmod as chmod3, rm as rm3 } from "node:fs/promises";
 var MAX_LINE_BYTES = 1024 * 1024;
 var MAX_NOTIFY_BUFFERED_BYTES = 4 * 1024 * 1024;
 var isPlainObject = (value) => {
@@ -1679,20 +2256,20 @@ var startRpcServer = async (options) => {
   });
   server.on("error", () => {
   });
-  await new Promise((resolve, reject) => {
+  await new Promise((resolve2, reject) => {
     const onError = (error) => {
       server.off("listening", onListening);
       reject(error);
     };
     const onListening = () => {
       server.off("error", onError);
-      resolve();
+      resolve2();
     };
     server.once("error", onError);
     server.once("listening", onListening);
     server.listen(options.socketPath);
   });
-  await chmod2(options.socketPath, 384);
+  await chmod3(options.socketPath, 384);
   return {
     server,
     notify: (connection, payload) => {
@@ -1706,42 +2283,15 @@ var startRpcServer = async (options) => {
       writeLine(connection.socket, { jsonrpc: "2.0", method: "event", params: payload });
     },
     connections: () => Array.from(connections.values()),
-    close: () => new Promise((resolve) => {
+    close: () => new Promise((resolve2) => {
       for (const connection of connections.values()) {
         connection.socket.destroy();
       }
-      server.close(() => resolve());
+      server.close(() => resolve2());
     })
   };
 };
 
-// src/daemon/state-dir.ts
-import { join as join4 } from "node:path";
-import { mkdir as mkdir2, chmod as chmod3 } from "node:fs/promises";
-var getStateDirPaths = (stateDir) => {
-  return {
-    root: stateDir,
-    socketPath: join4(stateDir, "daemon.sock"),
-    pidFilePath: join4(stateDir, "daemon.pid"),
-    logFilePath: join4(stateDir, "daemon.log"),
-    eventsLogPath: join4(stateDir, "events.log"),
-    keyPath: join4(stateDir, "key.pem"),
-    configPath: join4(stateDir, "config.json"),
-    auditDir: join4(stateDir, "audit"),
-    spawnLockPath: join4(stateDir, "daemon.spawn.lock")
-  };
-};
-var getSocketPath = (paths) => {
-  return paths.socketPath;
-};
-var ensureStateDir = async (stateDir) => {
-  const paths = getStateDirPaths(stateDir);
-  await mkdir2(paths.auditDir, { recursive: true });
-  await chmod3(paths.root, 448);
-  await chmod3(paths.auditDir, 448);
-  return paths;
-};
-
 // src/daemon/tls.ts
 import { stat as stat3, readFile as readFile3 } from "node:fs/promises";
 
@@ -1919,7 +2469,7 @@ var generateHostCertificate = async (keyPem, advertisedIp) => {
 
 // src/key-material.ts
 import { generateKeyPairSync } from "node:crypto";
-import { dirname as dirname2 } from "node:path";
+import { dirname as dirname3 } from "node:path";
 import { mkdir as mkdir3, rename as rename2, rm as rm4, writeFile } from "node:fs/promises";
 var generatePrivateKeyPem = () => {
   const { privateKey } = generateKeyPairSync("rsa", {
@@ -1933,7 +2483,7 @@ var generatePrivateKeyPem = () => {
 };
 var writePrivateKeyAtomically = async (path, keyPem) => {
   const temporaryPath = `${path}.${process.pid}.${Date.now()}.tmp`;
-  await mkdir3(dirname2(path), { recursive: true });
+  await mkdir3(dirname3(path), { recursive: true });
   try {
     await writeFile(temporaryPath, keyPem, {
       encoding: "utf8",
@@ -2006,13 +2556,14 @@ var toAgentEndpoint = (address, port) => {
 var KNOWN_EVENT_KINDS = new Set(EVENT_KINDS);
 var packageVersion = () => getDaemonReportedVersion();
 var AUDIT_PRUNE_INTERVAL_MS = 24 * 60 * 60 * 1e3;
-var buildStatusResult = async (config, boundWssPort, startedAt, tls, sessionManager, auditLogger, auditDir) => {
+var buildStatusResult = async (config, boundWssPort, boundWebPort, startedAt, tls, sessionManager, auditLogger, auditDir) => {
   const stats = await auditLogger.stats();
   return {
     version: packageVersion(),
     pid: process.pid,
     startedAt: startedAt.toISOString(),
     wssPort: boundWssPort,
+    webPort: boundWebPort,
     pinnedKeys: tls.pinnedKeys(),
     sessions: sessionManager.list(),
     pendingLinks: sessionManager.pendingLinkCount(),
@@ -2040,6 +2591,26 @@ var asSelectorParams = (params) => {
   }
   return { selector };
 };
+var asPageParams = (record) => {
+  const limit = record.limit;
+  if (limit !== void 0 && (typeof limit !== "number" || !Number.isInteger(limit) || limit <= 0)) {
+    throw new RpcApplicationError("invalid_request", '"limit" must be a positive integer.');
+  }
+  const offset = record.offset;
+  if (offset !== void 0 && (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0)) {
+    throw new RpcApplicationError("invalid_request", '"offset" must be a non-negative integer.');
+  }
+  return { limit, offset };
+};
+var asEventsListParams = (params) => {
+  const { selector } = asSelectorParams(params);
+  const record = asRecordParams(params);
+  const name = record.name;
+  if (name !== void 0 && typeof name !== "string") {
+    throw new RpcApplicationError("invalid_request", '"name" must be a string.');
+  }
+  return { selector, name, ...asPageParams(record) };
+};
 var asToolsListParams = (params) => {
   const { selector } = asSelectorParams(params);
   const record = asRecordParams(params);
@@ -2057,14 +2628,7 @@ var asToolsListParams = (params) => {
       `"filter" must be a string of at most ${MAX_TOOLS_FILTER_LENGTH} characters.`
     );
   }
-  const limit = record.limit;
-  if (limit !== void 0 && (typeof limit !== "number" || !Number.isInteger(limit) || limit <= 0)) {
-    throw new RpcApplicationError("invalid_request", '"limit" must be a positive integer.');
-  }
-  const offset = record.offset;
-  if (offset !== void 0 && (typeof offset !== "number" || !Number.isInteger(offset) || offset < 0)) {
-    throw new RpcApplicationError("invalid_request", '"offset" must be a non-negative integer.');
-  }
+  const { limit, offset } = asPageParams(record);
   return {
     selector,
     group,
@@ -2213,11 +2777,51 @@ var asLinkCreateParams = (params) => {
   if (addressOverride !== void 0 && (typeof addressOverride !== "string" || addressOverride.length === 0)) {
     throw new RpcApplicationError("invalid_request", '"addressOverride" must be a non-empty string.');
   }
-  return { ttlSeconds, addressOverride };
+  const transport = record.transport;
+  if (transport !== void 0 && transport !== "native" && transport !== "web") {
+    throw new RpcApplicationError("invalid_request", '"transport" must be "native" or "web".');
+  }
+  return { ttlSeconds, addressOverride, transport };
+};
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["127.0.0.1", "[::1]", "localhost"]);
+var asWebAttachParams = (params) => {
+  if (typeof params !== "object" || params === null || Array.isArray(params)) {
+    throw new RpcApplicationError("invalid_request", "Params must be an object.");
+  }
+  const { url, browserUrl, targetId, ttlSeconds } = params;
+  for (const [field, value] of [["url", url], ["browserUrl", browserUrl], ["targetId", targetId]]) {
+    if (value !== void 0 && (typeof value !== "string" || value.length === 0)) {
+      throw new RpcApplicationError("invalid_request", `"${field}" must be a non-empty string.`);
+    }
+  }
+  if (url === void 0 || browserUrl === void 0) {
+    throw new RpcApplicationError("invalid_request", '"url" and "browserUrl" are required.');
+  }
+  let parsedBrowserUrl;
+  try {
+    parsedBrowserUrl = new URL(browserUrl);
+  } catch {
+  }
+  if (parsedBrowserUrl === void 0 || parsedBrowserUrl.protocol !== "http:" && parsedBrowserUrl.protocol !== "https:") {
+    throw new RpcApplicationError("invalid_request", `"browserUrl" must be an http(s) URL such as http://127.0.0.1:9222 (got "${browserUrl}").`);
+  }
+  if (!LOOPBACK_HOSTS.has(parsedBrowserUrl.hostname)) {
+    throw new RpcApplicationError(
+      "invalid_request",
+      `"browserUrl" must be a loopback address (127.0.0.1, [::1] or localhost), because a debugging port gives full control of the browser (got "${browserUrl}").`
+    );
+  }
+  if (ttlSeconds !== void 0 && (typeof ttlSeconds !== "number" || !Number.isInteger(ttlSeconds) || ttlSeconds <= 0)) {
+    throw new RpcApplicationError("invalid_request", '"ttlSeconds" must be a positive integer.');
+  }
+  return { url, browserUrl, targetId, ttlSeconds };
 };
 var startDaemon = async (options) => {
   const clock = options.clock ?? { now: () => /* @__PURE__ */ new Date() };
   const timers = options.timers ?? systemTimers;
+  const connectDevtoolsBrowser = options.connectDevtoolsBrowser ?? connectNodeDevtoolsBrowser;
+  const devtoolsBrowsers = /* @__PURE__ */ new Map();
+  const relayedTabs = /* @__PURE__ */ new Map();
   const paths = getStateDirPaths(options.stateDir);
   await ensureStateDir(options.stateDir);
   const config = await loadConfig(paths, { warn: options.warn });
@@ -2240,15 +2844,17 @@ var startDaemon = async (options) => {
   let pidfile;
   let server;
   let listener;
+  let webListener;
   let tlsManager;
   let sessionManager;
   let callsManager;
   let eventBus;
   let boundWssPort = config.wssPort;
+  let boundWebPort = 0;
   let shuttingDown = false;
   let resolveExited;
-  const exited = new Promise((resolve) => {
-    resolveExited = resolve;
+  const exited = new Promise((resolve2) => {
+    resolveExited = resolve2;
   });
   const shutdown = async () => {
     if (shuttingDown) {
@@ -2261,8 +2867,10 @@ var startDaemon = async (options) => {
         auditPruneInterval = void 0;
       }
       callsManager?.disposeAll();
+      devtoolsBrowsers.forEach((browser) => browser.close());
       sessionManager?.disposeAll(1001, "daemon_shutdown");
       await listener?.close();
+      await webListener?.close();
       await server?.close();
       await pidfile?.release();
       await rm5(getSocketPath(paths), { force: true });
@@ -2294,7 +2902,8 @@ var startDaemon = async (options) => {
       linkTtlSeconds: config.linkTtlSeconds,
       // `boundWssPort`, not `config.wssPort`: a link minted by a daemon on an OS-assigned port
       // must advertise the port the app can actually reach, not the `0` that asked for one.
-      getEndpoint: () => toAgentEndpoint(tls.current().advertisedAddress, boundWssPort),
+      // A web link points at the loopback web listener, never the advertised LAN address.
+      getEndpoint: (transport) => transport === "web" ? { family: 4, address: "127.0.0.1", port: boundWebPort } : toAgentEndpoint(tls.current().advertisedAddress, boundWssPort),
       eventBus: activeEventBus,
       clock,
       onToolFrame: (message) => {
@@ -2327,11 +2936,14 @@ var startDaemon = async (options) => {
     const activeCallsManager = callsManager;
     listener = await startListener({
       port: config.wssPort,
+      bindLoopback: process.platform === "darwin",
       tls,
       sessionManager
     });
     const activeListener = listener;
     boundWssPort = activeListener.port() ?? config.wssPort;
+    webListener = await startWebListener({ sessionManager, origins: config.webOrigins, timers });
+    boundWebPort = webListener.port() ?? 0;
     activeEventBus.subscribe((event) => {
       for (const connection of server?.connections() ?? []) {
         const subscription = connection.state.eventSubscription;
@@ -2354,13 +2966,22 @@ var startDaemon = async (options) => {
         server?.notify(connection, projected);
       }
     });
+    const mintLink = async (ttlSeconds, addressOverride, transport) => {
+      const previousMaterial = tls.current();
+      const nextMaterial = await tls.refresh();
+      if (nextMaterial !== previousMaterial) {
+        activeListener.applyTls(nextMaterial);
+      }
+      return { ...activeSessionManager.createLink(ttlSeconds, addressOverride, transport), pin: tls.pinnedKeys()[0] };
+    };
     server = await startRpcServer({
       socketPath: getSocketPath(paths),
       dispatch: {
-        [RPC_METHODS.daemonStatus]: async () => {
+        [RPC_METHODS3.daemonStatus]: async () => {
           return buildStatusResult(
             config,
             boundWssPort,
+            boundWebPort,
             startedAt,
             tls,
             activeSessionManager,
@@ -2368,34 +2989,60 @@ var startDaemon = async (options) => {
             paths.auditDir
           );
         },
-        [RPC_METHODS.daemonShutdown]: (_params, context) => {
+        [RPC_METHODS3.daemonShutdown]: (_params, context) => {
           context.afterSend(() => {
             void shutdown();
           });
           return { ok: true };
         },
-        [RPC_METHODS.linkCreate]: async (params) => {
-          const { ttlSeconds, addressOverride } = asLinkCreateParams(params);
-          const previousMaterial = tls.current();
-          const nextMaterial = await tls.refresh();
-          if (nextMaterial !== previousMaterial) {
-            activeListener.applyTls(nextMaterial);
+        [RPC_METHODS3.linkCreate]: async (params) => {
+          const { ttlSeconds, addressOverride, transport } = asLinkCreateParams(params);
+          return mintLink(ttlSeconds, addressOverride, transport);
+        },
+        [RPC_METHODS3.webAttach]: async (params) => {
+          const { url, browserUrl, targetId, ttlSeconds } = asWebAttachParams(params);
+          let browser = devtoolsBrowsers.get(browserUrl);
+          if (browser === void 0) {
+            browser = connectDevtoolsBrowser(browserUrl);
+            devtoolsBrowsers.set(browserUrl, browser);
+          }
+          try {
+            return await attachBrowserTab({
+              browser,
+              relayedTabs,
+              url,
+              targetId,
+              openDaemonSocket: openNodeDaemonSocket,
+              mintLink: async () => composeWebLink(url, await mintLink(ttlSeconds, void 0, "web"))
+            });
+          } catch (error) {
+            throw new RpcApplicationError("invalid_request", error instanceof Error ? error.message : String(error));
           }
-          return { ...activeSessionManager.createLink(ttlSeconds, addressOverride), pin: tls.pinnedKeys()[0] };
         },
-        [RPC_METHODS.sessionsList]: () => {
+        [RPC_METHODS3.sessionsList]: () => {
           return activeSessionManager.list();
         },
-        [RPC_METHODS.sessionsDescribe]: (params) => {
+        [RPC_METHODS3.sessionsDescribe]: (params) => {
           const { selector } = asSelectorParams(params);
           return activeSessionManager.describe(selector);
         },
-        [RPC_METHODS.sessionsRevoke]: (params) => {
+        [RPC_METHODS3.sessionsRevoke]: (params) => {
           const { selector } = asSelectorParams(params);
           activeSessionManager.revoke(selector);
           return { ok: true };
         },
-        [RPC_METHODS.toolsList]: (params) => {
+        [RPC_METHODS3.eventsList]: (params) => {
+          const { selector, name, limit, offset } = asEventsListParams(params);
+          const registered = activeSessionManager.resolveForTools(selector).eventRegistry.list();
+          const sorted = registered.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+          const matching = name === void 0 ? sorted : sorted.filter((event) => matchesNameGlob(name, event.name));
+          const start = offset ?? 0;
+          return {
+            events: limit === void 0 ? matching.slice(start) : matching.slice(start, start + limit),
+            total: matching.length
+          };
+        },
+        [RPC_METHODS3.toolsList]: (params) => {
           const { selector, group, filter, limit, offset } = asToolsListParams(params);
           const resolved = activeSessionManager.resolveForTools(selector);
           const entries = resolved.registry.list().map((descriptor) => ({
@@ -2420,7 +3067,7 @@ var startDaemon = async (options) => {
         // This handler is the single seam every `tools.call` passes through: policy (ARCHITECTURE.md
         // §12) is evaluated once the target tool descriptor is known, and one audit record is
         // written for every attempt that reaches a resolved session, across ok/error/denied.
-        [RPC_METHODS.toolsCall]: async (params, context) => {
+        [RPC_METHODS3.toolsCall]: async (params, context) => {
           const { selector, name, args, timeoutMs, caller, consent } = asToolsCallParams(params);
           const effectiveCaller = caller ?? "cli";
           const resolved = activeSessionManager.resolveForTools(selector);
@@ -2442,7 +3089,10 @@ var startDaemon = async (options) => {
           if (resolved.state !== "active") {
             const errorType = resolved.state === "suspended" ? "session_suspended" : "session_not_active";
             writeAudit("error", errorType);
-            throw new RpcApplicationError(errorType, `Session "${resolved.alias}" is not active.`);
+            throw new RpcApplicationError(
+              errorType,
+              resolved.suspendReason === "app_backgrounded" ? appBackgroundedMessage(resolved.alias) : `Session "${resolved.alias}" is not active.`
+            );
           }
           const tool = resolved.registry.get(name);
           if (!tool) {
@@ -2523,13 +3173,13 @@ var startDaemon = async (options) => {
             unregisterOnClose();
           }
         },
-        [RPC_METHODS.toolsCancel]: (params) => {
+        [RPC_METHODS3.toolsCancel]: (params) => {
           const { selector, callId, reason } = asToolsCancelParams(params);
           const resolved = activeSessionManager.resolveForTools(selector);
           const cancelled = activeCallsManager.cancel(resolved.sessionId, callId, reason ?? "client_cancelled");
           return { cancelled };
         },
-        [RPC_METHODS.eventsSubscribe]: (params, context) => {
+        [RPC_METHODS3.eventsSubscribe]: (params, context) => {
           const { sessionSelector, kinds, name, payloadMaxBytes } = asEventsSubscribeParams(params);
           context.connection.state.eventSubscription = {
             sessionSelector,
@@ -2539,7 +3189,7 @@ var startDaemon = async (options) => {
           };
           return { ok: true };
         },
-        [RPC_METHODS.eventsSince]: (params) => {
+        [RPC_METHODS3.eventsSince]: (params) => {
           const { selector, since, limit, name, payloadMaxBytes } = asEventsSinceParams(params);
           const resolved = activeSessionManager.describe(selector);
           return activeEventBus.since(resolved.sessionId, { since, limit, name, payloadMaxBytes });
@@ -2558,6 +3208,7 @@ var startDaemon = async (options) => {
     callsManager?.disposeAll();
     sessionManager?.disposeAll(1001, "daemon_startup_failed");
     await listener?.close();
+    await webListener?.close();
     await pidfile?.release();
     throw error;
   }
@@ -2568,6 +3219,7 @@ var startDaemon = async (options) => {
     startedAt,
     server,
     listener,
+    webListener,
     tls: tlsManager,
     eventBus,
     exited,
@@ -2575,175 +3227,6 @@ var startDaemon = async (options) => {
   };
 };
 
-// src/rpc/client.ts
-import { join as join5 } from "node:path";
-import { RPC_METHODS as RPC_METHODS2 } from "@appduct/shared";
-var defaultBinPath = join5(getPackageRoot(), "bin.js");
-var DaemonRpcError = class extends Error {
-  constructor(code, message, data) {
-    super(message);
-    this.code = code;
-    this.data = data;
-    this.name = "DaemonRpcError";
-  }
-};
-var DaemonUnavailableError = class extends Error {
-  constructor(message, reason = "unreachable") {
-    super(message);
-    this.reason = reason;
-    this.name = "DaemonUnavailableError";
-  }
-};
-var describeLiveState = (state) => {
-  const parts = [];
-  if (state.sessions > 0) {
-    parts.push(`${state.sessions} connected session(s)`);
-  }
-  if (state.pendingLinks > 0) {
-    parts.push(`${state.pendingLinks} unclaimed link(s)`);
-  }
-  return parts.join(" and ");
-};
-var DaemonVersionMismatchError = class extends Error {
-  constructor(daemonVersion, clientVersion, live, message) {
-    super(
-      message ?? `The running Appduct daemon is version ${daemonVersion}, but this client is version ${clientVersion}. It was not restarted automatically because ${describeLiveState(live)} would be lost. Run "appduct daemon stop" once that state is expendable, or force it with "--daemon-restart".`
-    );
-    this.daemonVersion = daemonVersion;
-    this.clientVersion = clientVersion;
-    this.name = "DaemonVersionMismatchError";
-    this.sessionCount = live.sessions;
-    this.pendingLinkCount = live.pendingLinks;
-  }
-  sessionCount;
-  pendingLinkCount;
-};
-var isConnectionMissingError = (error) => {
-  const code = error.code;
-  return code === "ENOENT" || code === "ECONNREFUSED";
-};
-var isDaemonUnreachableError = (error) => {
-  return error instanceof DaemonUnavailableError || isConnectionMissingError(error);
-};
-
-// src/errors.ts
-var EXIT_CODE_BY_ERROR_TYPE = {
-  usage_error: 64,
-  validation_error: 65,
-  // EX_NOINPUT (66): "an input file did not exist or was not readable" — `doctor` throws this for a
-  // missing external tool or an unreadable/corrupt artifact, deliberately distinct from every other
-  // code here so a release pipeline can't mistake "we couldn't tell" for either a clean pass or an
-  // assertion failure (docs/tasks/08-appduct-doctor.md).
-  inspection_error: 66,
-  connection_error: 70,
-  session_error: 71,
-  tool_error: 72,
-  permission_error: 77,
-  internal_error: 1,
-  // `doctor --assert-present`/`--assert-absent`: the artifact was inspected successfully and the
-  // assertion did not hold. Distinct from `inspection_error` (66) — this means the answer is known
-  // and it's "no", not "couldn't tell" — and distinct from `internal_error` (1) so a caller can't
-  // conflate a normal assertion failure with an unexpected crash.
-  assertion_error: 3
-};
-var RPC_ERROR_EXIT_CLASS = {
-  no_session: "session_error",
-  ambiguous_session: "session_error",
-  unknown_session: "session_error",
-  session_not_active: "session_error",
-  session_suspended: "session_error",
-  tool_not_found: "tool_error",
-  tool_input_validation_error: "tool_error",
-  tool_output_validation_error: "tool_error",
-  tool_execution_error: "tool_error",
-  tool_serialization_error: "tool_error",
-  tool_timeout: "tool_error",
-  tool_cancelled: "tool_error",
-  policy_denied: "permission_error",
-  invalid_request: "validation_error"
-};
-var AppductCliError = class extends Error {
-  type;
-  details;
-  constructor(type, message, details) {
-    super(message);
-    this.name = "AppductCliError";
-    this.type = type;
-    this.details = details;
-  }
-};
-var connectionError = (message, details) => {
-  return new AppductCliError("connection_error", message, details);
-};
-var isAppductCliError = (value) => {
-  return value instanceof AppductCliError;
-};
-var rpcErrorClass = (error) => {
-  const type = error.data?.type;
-  return type ? RPC_ERROR_EXIT_CLASS[type] : void 0;
-};
-var toCliError = (error) => {
-  if (isAppductCliError(error)) {
-    return {
-      type: error.type,
-      message: error.message,
-      details: error.details
-    };
-  }
-  if (error instanceof DaemonVersionMismatchError) {
-    return {
-      type: "connection_error",
-      message: error.message,
-      details: {
-        daemon_version: error.daemonVersion,
-        client_version: error.clientVersion,
-        session_count: error.sessionCount,
-        pending_link_count: error.pendingLinkCount
-      }
-    };
-  }
-  if (error instanceof DaemonRpcError && error.data?.type) {
-    return {
-      type: error.data.type,
-      message: error.message,
-      details: error.data.details
-    };
-  }
-  if (isDaemonUnreachableError(error)) {
-    return {
-      type: "connection_error",
-      message: error instanceof Error ? error.message : "The Appduct daemon is unreachable."
-    };
-  }
-  if (error instanceof Error) {
-    return {
-      type: "internal_error",
-      message: error.message
-    };
-  }
-  return {
-    type: "internal_error",
-    message: "An unexpected error occurred.",
-    details: error
-  };
-};
-var getExitCodeForError = (error) => {
-  if (isAppductCliError(error)) {
-    return EXIT_CODE_BY_ERROR_TYPE[error.type];
-  }
-  if (error instanceof DaemonVersionMismatchError) {
-    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
-  }
-  if (error instanceof DaemonRpcError) {
-    const cliErrorClass = rpcErrorClass(error);
-    return EXIT_CODE_BY_ERROR_TYPE[cliErrorClass ?? "internal_error"];
-  }
-  if (isDaemonUnreachableError(error)) {
-    return EXIT_CODE_BY_ERROR_TYPE.connection_error;
-  }
-  return EXIT_CODE_BY_ERROR_TYPE.internal_error;
-};
-
 // src/commands/daemon/run.ts
 var handleDaemonRunCommand = async (context) => {
   let daemon;
@@ -2786,6 +3269,7 @@ var formatJson = (value, flags) => {
 import pc from "picocolors";
 import {
   formatAgentWebSocketUrl,
+  renderEventSignature,
   renderToolSignature,
   summarizeToolDescription
 } from "@appduct/shared";
@@ -2881,6 +3365,13 @@ var formatDevice = (device) => {
   const label = parts.length > 0 ? parts.join(" ") : "unknown device";
   return device.os ? `${label} (${device.os})` : label;
 };
+var SUSPEND_REASON_LABELS = {
+  app_backgrounded: "app in background",
+  connection_lost: "connection lost"
+};
+var formatSessionState = (session) => {
+  return session.suspendReason ? `${session.state} (${SUSPEND_REASON_LABELS[session.suspendReason]})` : session.state;
+};
 var renderLsData = (colors, data, now) => {
   if (data.length === 0) {
     return [colors.dim("Sessions"), "  No Appduct sessions are registered."];
@@ -2889,7 +3380,7 @@ var renderLsData = (colors, data, now) => {
   const headers = ["Alias", "State", "Device", "Tools", "Age"];
   const rows = data.map((session) => [
     session.alias,
-    session.state,
+    formatSessionState(session),
     formatDevice(session.device),
     String(session.toolCount),
     formatAge(session.claimedAt ?? session.createdAt, nowIso)
@@ -3063,10 +3554,87 @@ var renderToolsListData = (colors, data, flags, full) => {
   }
   return full ? renderToolsFullListing(colors, data, flags) : renderToolSummaryTable(colors, data);
 };
+var renderEventsTruncationLine = (data) => {
+  const offset = data.offset ?? 0;
+  if (data.events.length >= data.total) {
+    return [];
+  }
+  return [
+    "",
+    `Showing ${data.events.length} of ${data.total} events (offset ${offset}). Narrow with --name <glob> or page with --offset <n>.`
+  ];
+};
+var renderEventsListData = (colors, data, flags) => {
+  const [only] = data.events;
+  if (data.name !== void 0 && !data.name.includes("*") && only !== void 0) {
+    return renderFields(
+      colors.green(`Event: ${only.name}`),
+      [
+        ["Signature", renderEventSignature(only)],
+        ["Description", only.description],
+        ["Payload schema", only.payload_schema]
+      ],
+      flags
+    );
+  }
+  if (data.events.length === 0 && data.total > 0) {
+    return [
+      colors.green("Events"),
+      `  No events at offset ${data.offset ?? 0}; ${data.total} matching event${data.total === 1 ? "" : "s"} in total.`
+    ];
+  }
+  if (data.events.length === 0) {
+    return [
+      colors.green("Events"),
+      data.name === void 0 ? "  No events declared." : `  No events match ${JSON.stringify(data.name)}.`
+    ];
+  }
+  const lines = data.events.flatMap((event) => [
+    `  ${renderEventSignature(event)}`,
+    `    ${summarizeToolDescription(event.description)}`
+  ]);
+  return [
+    colors.green("Events"),
+    ...lines,
+    ...renderEventsTruncationLine(data),
+    "",
+    "Run `appduct events ls --name <name>` for an event's full payload schema."
+  ];
+};
 var renderInvokeData = (colors, data, flags) => {
   return [colors.green("Result"), formatScalar(data, flags)];
 };
 var renderLinkData = (colors, data, flags, qr) => {
+  if ("attached" in data) {
+    return [
+      colors.green("Page Attached"),
+      ...renderFields(
+        "Page",
+        [
+          ["Session", data.sessionId],
+          ["Tab", data.targetId],
+          ["URL", data.url],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
+  if ("script" in data) {
+    return [
+      colors.green("Link Created"),
+      ...renderFields(
+        "Link",
+        [
+          ["Session", data.sessionId],
+          ["URL", data.url],
+          ["Script", data.script],
+          ["Expires", new Date(data.expiresAt * 1e3).toISOString()]
+        ],
+        flags
+      )
+    ];
+  }
   const lines = [
     colors.green("Link Created"),
     ...renderFields(
@@ -3187,6 +3755,7 @@ var renderDaemonStatusData = (colors, data, flags) => {
         ["PID", data.daemon.pid],
         ["Started at", data.daemon.started_at],
         ["WSS port", data.daemon.wss_port],
+        ["Web port", data.daemon.web_port],
         ["Pinned keys", data.daemon.pinned_keys.length],
         ["Sessions", data.daemon.session_count]
       ],
@@ -3254,6 +3823,8 @@ var renderSuccessData = (colors, command, data, options) => {
       return renderToolsListData(colors, data, flags, options.full);
     case "tools describe":
       return renderToolDetail(colors, data, flags);
+    case "events ls":
+      return renderEventsListData(colors, data, flags);
     case "tools call":
       return renderInvokeData(colors, data, flags);
     case "sessions revoke":