appduct 0.10.0 → 0.11.1

package/dist/cli/routes/mcp.js

@@ -0,0 +1,3929 @@
+// src/commands/mcp.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/daemon/config.ts
+import { readFile } from "node:fs/promises";
+var KNOWN_TOP_LEVEL_KEYS = /* @__PURE__ */ new Set([
+  "wssPort",
+  "keyPath",
+  "graceSeconds",
+  "linkTtlSeconds",
+  "keepaliveIntervalSeconds",
+  "eventBufferSize",
+  "auditRetentionDays",
+  "daemonLogMaxBytes",
+  "policy",
+  "advertisedIp",
+  "scheme",
+  "restartDaemonOnVersionMismatch"
+]);
+var KNOWN_POLICY_KEYS = /* @__PURE__ */ new Set(["default", "destructive", "tools"]);
+var POLICY_DECISIONS = /* @__PURE__ */ new Set(["allow", "deny", "prompt"]);
+var DEFAULT_AUDIT_RETENTION_DAYS = 30;
+var DEFAULT_DAEMON_LOG_MAX_BYTES = 10 * 1024 * 1024;
+var AppductConfigError = class extends Error {
+  constructor(key, message) {
+    super(message);
+    this.key = key;
+    this.name = "AppductConfigError";
+  }
+};
+var configError = (key, message) => {
+  return new AppductConfigError(key, `Invalid Appduct config value for "${key}": ${message}`);
+};
+var requireWssPort = (value, key) => {
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0 || value > 65535) {
+    throw configError(key, "must be a port number between 0 and 65535 (0 binds an OS-assigned port).");
+  }
+  return value;
+};
+var requirePositiveInteger = (value, key) => {
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw configError(key, "must be a positive integer.");
+  }
+  return value;
+};
+var requireNonEmptyString = (value, key) => {
+  if (typeof value !== "string" || value.length === 0) {
+    throw configError(key, "must be a non-empty string.");
+  }
+  return value;
+};
+var requireBoolean = (value, key) => {
+  if (typeof value !== "boolean") {
+    throw configError(key, "must be a boolean.");
+  }
+  return value;
+};
+var requirePolicyDecision = (value, key) => {
+  if (typeof value !== "string" || !POLICY_DECISIONS.has(value)) {
+    throw configError(key, 'must be "allow", "deny", or "prompt".');
+  }
+  return value;
+};
+var defaultConfig = (paths) => {
+  return {
+    wssPort: 8443,
+    keyPath: paths.keyPath,
+    graceSeconds: 600,
+    linkTtlSeconds: 300,
+    keepaliveIntervalSeconds: 15,
+    eventBufferSize: 256,
+    auditRetentionDays: DEFAULT_AUDIT_RETENTION_DAYS,
+    daemonLogMaxBytes: DEFAULT_DAEMON_LOG_MAX_BYTES,
+    restartDaemonOnVersionMismatch: false,
+    policy: {
+      default: "allow",
+      destructive: "allow"
+    }
+  };
+};
+var loadConfig = async (paths, options = {}) => {
+  const warn = options.warn ?? (() => {
+  });
+  const config = defaultConfig(paths);
+  let raw;
+  try {
+    raw = JSON.parse(await readFile(paths.configPath, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return config;
+    }
+    throw configError("config.json", `could not be read/parsed (${error.message}).`);
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw configError("config.json", "must be a JSON object.");
+  }
+  const parsed = raw;
+  for (const key of Object.keys(parsed)) {
+    if (!KNOWN_TOP_LEVEL_KEYS.has(key)) {
+      warn(`Unknown Appduct config key "${key}" is ignored.`);
+    }
+  }
+  if (parsed.wssPort !== void 0) {
+    config.wssPort = requireWssPort(parsed.wssPort, "wssPort");
+  }
+  if (parsed.keyPath !== void 0) {
+    config.keyPath = requireNonEmptyString(parsed.keyPath, "keyPath");
+  }
+  if (parsed.advertisedIp !== void 0) {
+    config.advertisedIp = requireNonEmptyString(parsed.advertisedIp, "advertisedIp");
+  }
+  if (parsed.scheme !== void 0) {
+    config.scheme = requireNonEmptyString(parsed.scheme, "scheme");
+  }
+  if (parsed.graceSeconds !== void 0) {
+    config.graceSeconds = requirePositiveInteger(parsed.graceSeconds, "graceSeconds");
+  }
+  if (parsed.linkTtlSeconds !== void 0) {
+    config.linkTtlSeconds = requirePositiveInteger(parsed.linkTtlSeconds, "linkTtlSeconds");
+  }
+  if (parsed.keepaliveIntervalSeconds !== void 0) {
+    config.keepaliveIntervalSeconds = requirePositiveInteger(
+      parsed.keepaliveIntervalSeconds,
+      "keepaliveIntervalSeconds"
+    );
+  }
+  if (parsed.eventBufferSize !== void 0) {
+    config.eventBufferSize = requirePositiveInteger(parsed.eventBufferSize, "eventBufferSize");
+  }
+  if (parsed.auditRetentionDays !== void 0) {
+    config.auditRetentionDays = requirePositiveInteger(parsed.auditRetentionDays, "auditRetentionDays");
+  }
+  if (parsed.daemonLogMaxBytes !== void 0) {
+    config.daemonLogMaxBytes = requirePositiveInteger(parsed.daemonLogMaxBytes, "daemonLogMaxBytes");
+  }
+  if (parsed.restartDaemonOnVersionMismatch !== void 0) {
+    config.restartDaemonOnVersionMismatch = requireBoolean(
+      parsed.restartDaemonOnVersionMismatch,
+      "restartDaemonOnVersionMismatch"
+    );
+  }
+  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/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"),
+    keyPath: join(stateDir, "key.pem"),
+    configPath: join(stateDir, "config.json"),
+    auditDir: join(stateDir, "audit"),
+    spawnLockPath: join(stateDir, "daemon.spawn.lock")
+  };
+};
+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/mcp/server.ts
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+  ReadResourceRequestSchema
+} from "@modelcontextprotocol/sdk/types.js";
+import { RPC_METHODS as RPC_METHODS6 } from "@appduct/shared";
+
+// src/daemon/calls.ts
+import {
+  clampToolTimeoutMs,
+  DEFAULT_TOOL_TIMEOUT_MS,
+  MAX_TOOL_TIMEOUT_MS,
+  MIN_TOOL_TIMEOUT_MS
+} from "@appduct/shared";
+var DEFAULT_CALL_TIMEOUT_MS = DEFAULT_TOOL_TIMEOUT_MS;
+var CALL_TRANSPORT_TIMEOUT_SLACK_MS = 5e3;
+var clampTimeout = (timeoutMs) => {
+  if (timeoutMs === void 0 || !Number.isFinite(timeoutMs)) {
+    return DEFAULT_CALL_TIMEOUT_MS;
+  }
+  return clampToolTimeoutMs(timeoutMs);
+};
+var deriveCallTransportTimeoutMs = (timeoutMs) => {
+  return clampTimeout(timeoutMs) + CALL_TRANSPORT_TIMEOUT_SLACK_MS;
+};
+
+// src/package-version.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { join as join3 } from "node:path";
+
+// src/package-root.ts
+import { existsSync, readFileSync } 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(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}.`);
+    }
+    dir = parent;
+  }
+};
+
+// src/package-version.ts
+var DAEMON_VERSION_OVERRIDE_ENV = "APPDUCT_DAEMON_VERSION_OVERRIDE";
+var cached2;
+var getPackageVersion = () => {
+  cached2 ??= JSON.parse(readFileSync2(join3(getPackageRoot(), "package.json"), "utf8")).version;
+  return cached2;
+};
+
+// src/rpc/client.ts
+import { connect as connect2 } from "node:net";
+import { spawn as spawnChildProcess } from "node:child_process";
+import { open as open2, readFile as readFile3, rm as rm2, stat as stat2 } from "node:fs/promises";
+import { join as join4 } from "node:path";
+import { RPC_METHODS } from "@appduct/shared";
+
+// src/daemon/log-rotation.ts
+import { chmod as chmod2, rename, stat } from "node:fs/promises";
+
+// src/daemon/pidfile.ts
+import { readFileSync as readFileSync3 } from "node:fs";
+import { open, readFile as readFile2, rm } from "node:fs/promises";
+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;
+};
+
+// src/daemon/socket-probe.ts
+import { connect } from "node:net";
+var isSocketConnectable = (socketPath) => {
+  return new Promise((resolve2) => {
+    const socket = connect(socketPath);
+    socket.once("connect", () => {
+      socket.destroy();
+      resolve2(true);
+    });
+    socket.once("error", () => {
+      socket.destroy();
+      resolve2(false);
+    });
+  });
+};
+
+// src/daemon/log-rotation.ts
+var STATE_FILE_MODE = 384;
+var daemonLogBackupPath = (logFilePath) => `${logFilePath}.1`;
+var isDaemonHoldingLog = async (pidFilePath) => {
+  try {
+    const pid = await readPidFromFile(pidFilePath);
+    return pid !== void 0 && isProcessAlive(pid);
+  } catch {
+    return false;
+  }
+};
+var rotateDaemonLogIfNeeded = async (options) => {
+  const warn = options.warn ?? ((message) => {
+    process.stderr.write(`${message}
+`);
+  });
+  try {
+    const stats = await stat(options.logFilePath);
+    if (!stats.isFile() || stats.size <= options.maxBytes) {
+      return { rotated: false };
+    }
+    const held = options.pidFilePath !== void 0 && await isDaemonHoldingLog(options.pidFilePath) || options.socketPath !== void 0 && await isSocketConnectable(options.socketPath);
+    if (held) {
+      warn(
+        `appduct: "${options.logFilePath}" is over its size cap but a daemon still holds it; leaving it in place.`
+      );
+      return { rotated: false, skipped: "daemon_running" };
+    }
+    const backupPath = daemonLogBackupPath(options.logFilePath);
+    await rename(options.logFilePath, backupPath);
+    try {
+      await chmod2(backupPath, STATE_FILE_MODE);
+    } catch (error) {
+      warn(`appduct: rotated "${options.logFilePath}" but could not set 0600 on "${backupPath}": ${error.message}`);
+    }
+    return { rotated: true, rotatedBytes: stats.size };
+  } catch (error) {
+    if (error.code === "ENOENT") {
+      return { rotated: false };
+    }
+    warn(`appduct: failed to rotate "${options.logFilePath}": ${error.message}`);
+    return { rotated: false };
+  }
+};
+var ensureDaemonLogMode = async (logFilePath, warn = (message) => process.stderr.write(`${message}
+`)) => {
+  try {
+    await chmod2(logFilePath, STATE_FILE_MODE);
+    return true;
+  } catch (error) {
+    warn(`appduct: could not set 0600 on "${logFilePath}": ${error.message}`);
+    return false;
+  }
+};
+var resolveDaemonLogMaxBytes = async (stateDir) => {
+  try {
+    return (await loadConfig(getStateDirPaths(stateDir))).daemonLogMaxBytes;
+  } catch {
+    return DEFAULT_DAEMON_LOG_MAX_BYTES;
+  }
+};
+
+// 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 isRequestTimeoutError = (error) => {
+  return error instanceof DaemonUnavailableError && error.reason === "timeout";
+};
+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 DaemonVersionRestartIneffectiveError = class extends DaemonVersionMismatchError {
+  constructor(daemonVersion, clientVersion, live) {
+    super(
+      daemonVersion,
+      clientVersion,
+      live,
+      `The Appduct daemon was restarted to match this client (version ${clientVersion}), but the daemon now answering still reports version ${daemonVersion}. Either the old daemon never exited (compare "daemon.pid" with what "appduct daemon status" reports), or another process spawned an older daemon in the meantime. Run "appduct daemon stop", then retry.`
+    );
+    this.name = "DaemonVersionRestartIneffectiveError";
+  }
+};
+var parseVersion = (value) => {
+  const match = /^(\d+(?:\.\d+)*)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/u.exec(value.trim());
+  if (!match) {
+    return void 0;
+  }
+  return {
+    numbers: match[1].split(".").map(Number),
+    // Build metadata (`+…`) is dropped, per semver: it never affects precedence, so two versions
+    // differing only there are the same version and neither restarts nor warns about the other.
+    prerelease: match[2]?.split(".")
+  };
+};
+var isNumericIdentifier = (identifier) => /^\d+$/u.test(identifier);
+var comparePrerelease = (left, right) => {
+  const length = Math.max(left.length, right.length);
+  for (let index = 0; index < length; index += 1) {
+    const a = left[index];
+    const b = right[index];
+    if (a === void 0) {
+      return -1;
+    }
+    if (b === void 0) {
+      return 1;
+    }
+    if (a === b) {
+      continue;
+    }
+    const aNumeric = isNumericIdentifier(a);
+    const bNumeric = isNumericIdentifier(b);
+    if (aNumeric && bNumeric) {
+      return Number(a) < Number(b) ? -1 : 1;
+    }
+    if (aNumeric !== bNumeric) {
+      return aNumeric ? -1 : 1;
+    }
+    return a < b ? -1 : 1;
+  }
+  return 0;
+};
+var compareVersions = (a, b) => {
+  const left = parseVersion(a);
+  const right = parseVersion(b);
+  if (!left || !right) {
+    return void 0;
+  }
+  const length = Math.max(left.numbers.length, right.numbers.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = (left.numbers[index] ?? 0) - (right.numbers[index] ?? 0);
+    if (difference !== 0) {
+      return difference < 0 ? -1 : 1;
+    }
+  }
+  if (left.prerelease === void 0 && right.prerelease === void 0) {
+    return 0;
+  }
+  if (left.prerelease === void 0) {
+    return 1;
+  }
+  if (right.prerelease === void 0) {
+    return -1;
+  }
+  return comparePrerelease(left.prerelease, right.prerelease);
+};
+var isSameVersion = (a, b) => {
+  return a === b || compareVersions(a, b) === 0;
+};
+var isConnectionMissingError = (error) => {
+  const code = error.code;
+  return code === "ENOENT" || code === "ECONNREFUSED";
+};
+var isDaemonUnreachableError = (error) => {
+  return error instanceof DaemonUnavailableError || isConnectionMissingError(error);
+};
+var nextRequestId = 1;
+var sendRequest = (socketPath, method, params, timeoutMs) => {
+  return new Promise((resolve2, reject) => {
+    const id = nextRequestId;
+    nextRequestId += 1;
+    let socket;
+    let settled = false;
+    let buffer = "";
+    const finish = (fn) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      socket.destroy();
+      fn();
+    };
+    const timeout = setTimeout(() => {
+      finish(
+        () => reject(new DaemonUnavailableError(`Timed out waiting for a response to "${method}".`, "timeout"))
+      );
+    }, timeoutMs);
+    socket = connect2(socketPath);
+    socket.on("error", (error) => {
+      finish(() => reject(error));
+    });
+    socket.on("connect", () => {
+      socket.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}
+`);
+    });
+    socket.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      let newlineIndex = buffer.indexOf("\n");
+      while (newlineIndex !== -1) {
+        const line = buffer.slice(0, newlineIndex);
+        buffer = buffer.slice(newlineIndex + 1);
+        newlineIndex = buffer.indexOf("\n");
+        if (line.length === 0) {
+          continue;
+        }
+        let message;
+        try {
+          message = JSON.parse(line);
+        } catch {
+          continue;
+        }
+        if (message.id !== id) {
+          continue;
+        }
+        if (message.error) {
+          finish(
+            () => reject(new DaemonRpcError(message.error.code, message.error.message, message.error.data))
+          );
+          return;
+        }
+        finish(() => resolve2(message.result));
+        return;
+      }
+    });
+    socket.on("close", () => {
+      finish(
+        () => reject(new DaemonUnavailableError("Connection to the Appduct daemon closed.", "closed"))
+      );
+    });
+  });
+};
+var sleep = (ms) => new Promise((resolve2) => setTimeout(resolve2, ms));
+var pollForSocket = async (socketPath, timeoutMs, pollIntervalMs) => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isSocketConnectable(socketPath)) {
+      return true;
+    }
+    await sleep(pollIntervalMs);
+  }
+  return isSocketConnectable(socketPath);
+};
+var unlinkStaleSocketIfDaemonDead = async (paths) => {
+  let pid;
+  try {
+    pid = Number.parseInt((await readFile3(paths.pidFilePath, "utf8")).trim(), 10);
+  } catch {
+    pid = void 0;
+  }
+  if (pid === void 0 || Number.isNaN(pid) || !isProcessAlive(pid)) {
+    await rm2(paths.socketPath, { force: true });
+  }
+};
+var defaultSpawn = async (args, context) => {
+  const paths = getStateDirPaths(context.stateDir);
+  await rotateDaemonLogIfNeeded({
+    logFilePath: context.logFilePath,
+    maxBytes: await resolveDaemonLogMaxBytes(context.stateDir),
+    pidFilePath: paths.pidFilePath,
+    socketPath: paths.socketPath
+  });
+  const logFd = await open2(context.logFilePath, "a", 384);
+  try {
+    await ensureDaemonLogMode(context.logFilePath);
+    const childEnv = { ...process.env, APPDUCT_STATE_DIR: context.stateDir };
+    delete childEnv[DAEMON_VERSION_OVERRIDE_ENV];
+    const child = spawnChildProcess(process.execPath, [defaultBinPath, ...args], {
+      detached: true,
+      stdio: ["ignore", logFd.fd, logFd.fd],
+      env: childEnv
+    });
+    child.unref();
+  } finally {
+    await logFd.close();
+  }
+};
+var SPAWN_LOCK_STALE_MS = 3e4;
+var pollUntilLockReleased = async (lockPath, timeoutMs, pollIntervalMs) => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!await pathExists(lockPath)) {
+      return true;
+    }
+    await sleep(pollIntervalMs);
+  }
+  return !await pathExists(lockPath);
+};
+var readPidfilePid = async (paths) => {
+  try {
+    const pid = Number.parseInt((await readFile3(paths.pidFilePath, "utf8")).trim(), 10);
+    return Number.isNaN(pid) ? void 0 : pid;
+  } catch {
+    return void 0;
+  }
+};
+var pathExists = async (target) => {
+  try {
+    await stat2(target);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var acquireSpawnLock = async (lockPath) => {
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const lockHandle = await open2(lockPath, "wx", 384);
+      await lockHandle.close();
+      return true;
+    } catch (error) {
+      if (error.code !== "EEXIST") {
+        throw error;
+      }
+    }
+    let heldForMs;
+    try {
+      heldForMs = Date.now() - (await stat2(lockPath)).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (heldForMs < SPAWN_LOCK_STALE_MS) {
+      return false;
+    }
+    await rm2(lockPath, { force: true });
+  }
+  return false;
+};
+var spawnDaemonAndWait = async (paths, spawn, waitTimeoutMs, pollIntervalMs, options = {}) => {
+  await ensureStateDir(paths.root);
+  const acquiredLock = await acquireSpawnLock(paths.spawnLockPath);
+  let lockWaitTimedOut = false;
+  if (acquiredLock) {
+    try {
+      const shouldSpawn = options.beforeSpawn ? await options.beforeSpawn() : true;
+      if (shouldSpawn) {
+        await unlinkStaleSocketIfDaemonDead(paths);
+        await spawn(["daemon", "run"], { stateDir: paths.root, logFilePath: paths.logFilePath });
+      }
+    } finally {
+      await rm2(paths.spawnLockPath, { force: true });
+    }
+  } else if (options.awaitLockRelease) {
+    lockWaitTimedOut = !await pollUntilLockReleased(paths.spawnLockPath, waitTimeoutMs, pollIntervalMs);
+  }
+  const ready = await pollForSocket(paths.socketPath, waitTimeoutMs, pollIntervalMs);
+  if (!ready) {
+    const lockHint = await pathExists(paths.spawnLockPath) ? ` Another process holds the spawn-lock at "${paths.spawnLockPath}"; if no "appduct daemon" is starting, delete it and retry.` : "";
+    throw new DaemonUnavailableError(
+      `Timed out waiting for the Appduct daemon socket at "${paths.socketPath}".${lockHint}`
+    );
+  }
+  return { ownedLock: acquiredLock, lockWaitTimedOut };
+};
+var versionChecks = /* @__PURE__ */ new Map();
+var RESTART_REQUEST_TIMEOUT_MS = 3e3;
+var readStatusSpawningIfNeeded = async (context) => {
+  try {
+    return await sendRequest(
+      context.paths.socketPath,
+      RPC_METHODS.daemonStatus,
+      {},
+      context.requestTimeoutMs
+    );
+  } catch (error) {
+    if (!isConnectionMissingError(error)) {
+      throw error;
+    }
+    if (!context.autoSpawn) {
+      return void 0;
+    }
+    await spawnDaemonAndWait(context.paths, context.spawn, context.waitTimeoutMs, context.pollIntervalMs);
+    return sendRequest(
+      context.paths.socketPath,
+      RPC_METHODS.daemonStatus,
+      {},
+      context.requestTimeoutMs
+    );
+  }
+};
+var readStatusIfReachable = async (context) => {
+  try {
+    return await sendRequest(
+      context.paths.socketPath,
+      RPC_METHODS.daemonStatus,
+      {},
+      RESTART_REQUEST_TIMEOUT_MS
+    );
+  } catch (error) {
+    if (isConnectionMissingError(error)) {
+      return void 0;
+    }
+    if (isRequestTimeoutError(error)) {
+      throw new DaemonUnavailableError(
+        `The Appduct daemon at "${context.paths.socketPath}" did not answer "daemon.status" within ${RESTART_REQUEST_TIMEOUT_MS}ms, so it was not replaced. It is running but unresponsive \u2014 run "appduct daemon stop" and retry.`,
+        "timeout"
+      );
+    }
+    throw error;
+  }
+};
+var isDaemonGone = async (paths) => {
+  if (await isSocketConnectable(paths.socketPath)) {
+    return false;
+  }
+  let pid;
+  try {
+    pid = Number.parseInt((await readFile3(paths.pidFilePath, "utf8")).trim(), 10);
+  } catch {
+    return true;
+  }
+  return pid === void 0 || Number.isNaN(pid) || !isProcessAlive(pid);
+};
+var readLiveState = (status) => {
+  return {
+    sessions: Array.isArray(status.sessions) ? status.sessions.length : 0,
+    pendingLinks: typeof status.pendingLinks === "number" ? status.pendingLinks : 0
+  };
+};
+var isSafeToRestart = (live) => {
+  return live.sessions === 0 && live.pendingLinks === 0;
+};
+var pollUntilDaemonGone = async (paths, timeoutMs, pollIntervalMs) => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await isDaemonGone(paths)) {
+      return true;
+    }
+    await sleep(pollIntervalMs);
+  }
+  return isDaemonGone(paths);
+};
+var restartDaemon = async (context) => {
+  const pidBefore = await readPidfilePid(context.paths);
+  const outcome = await spawnDaemonAndWait(
+    context.paths,
+    context.spawn,
+    context.waitTimeoutMs,
+    context.pollIntervalMs,
+    {
+      awaitLockRelease: true,
+      beforeSpawn: async () => {
+        const status = await readStatusIfReachable(context);
+        if (status === void 0) {
+          return true;
+        }
+        if (isSameVersion(status.version, context.check.clientVersion)) {
+          return false;
+        }
+        const live = readLiveState(status);
+        if (!isSafeToRestart(live) && !context.check.forceRestart) {
+          throw new DaemonVersionMismatchError(status.version, context.check.clientVersion, live);
+        }
+        try {
+          await sendRequest(
+            context.paths.socketPath,
+            RPC_METHODS.daemonShutdown,
+            {},
+            RESTART_REQUEST_TIMEOUT_MS
+          );
+        } catch (error) {
+          if (isRequestTimeoutError(error)) {
+            throw new DaemonUnavailableError(
+              `The Appduct daemon at "${context.paths.socketPath}" did not acknowledge "daemon.shutdown" within ${RESTART_REQUEST_TIMEOUT_MS}ms, so it was left running. Run "appduct daemon stop" and retry.`,
+              "timeout"
+            );
+          }
+          if (!isDaemonUnreachableError(error)) {
+            throw error;
+          }
+        }
+        if (!await pollUntilDaemonGone(context.paths, context.waitTimeoutMs, context.pollIntervalMs)) {
+          throw new DaemonUnavailableError(
+            `The Appduct daemon at "${context.paths.socketPath}" did not shut down in time; run "appduct daemon stop" and retry.`
+          );
+        }
+        return true;
+      }
+    }
+  );
+  if (!outcome.ownedLock && outcome.lockWaitTimedOut && await readPidfilePid(context.paths) === pidBefore) {
+    throw new DaemonUnavailableError(
+      `The Appduct daemon at "${context.paths.socketPath}" did not shut down in time: another process has held the spawn-lock at "${context.paths.spawnLockPath}" for longer than this command waited. Retry, or run "appduct daemon stop" if nothing is starting a daemon.`
+    );
+  }
+};
+var warnOlderClient = (context, daemonVersion) => {
+  const message = `appduct: the running daemon is version ${daemonVersion}, newer than this client (${context.check.clientVersion}). Continuing without restarting it \u2014 a newer daemon serves an older client, and replacing it would downgrade whatever started it. Run "appduct daemon stop" if you want this client's daemon instead.
+`;
+  const warn = context.check.onWarning ?? ((text) => void process.stderr.write(text));
+  warn(message);
+};
+var runVersionCheck = async (context) => {
+  const status = await readStatusSpawningIfNeeded(context);
+  if (status === void 0) {
+    return;
+  }
+  if (isSameVersion(status.version, context.check.clientVersion)) {
+    return;
+  }
+  if ((compareVersions(context.check.clientVersion, status.version) ?? -1) <= 0) {
+    warnOlderClient(context, status.version);
+    return;
+  }
+  const live = readLiveState(status);
+  if (!isSafeToRestart(live) && !context.check.forceRestart) {
+    throw new DaemonVersionMismatchError(status.version, context.check.clientVersion, live);
+  }
+  await restartDaemon(context);
+  const replacement = await readStatusIfReachable(context);
+  if (replacement === void 0) {
+    throw new DaemonUnavailableError(
+      `The Appduct daemon was restarted but nothing is listening at "${context.paths.socketPath}"; check "${context.paths.logFilePath}".`
+    );
+  }
+  if (isSameVersion(replacement.version, context.check.clientVersion)) {
+    return;
+  }
+  if ((compareVersions(context.check.clientVersion, replacement.version) ?? -1) <= 0) {
+    warnOlderClient(context, replacement.version);
+    return;
+  }
+  throw new DaemonVersionRestartIneffectiveError(
+    replacement.version,
+    context.check.clientVersion,
+    readLiveState(replacement)
+  );
+};
+var ensureDaemonVersion = async (paths, options, spawn) => {
+  const check = options.checkVersion;
+  if (!check) {
+    return;
+  }
+  const cached3 = versionChecks.get(paths.socketPath);
+  if (cached3) {
+    return cached3;
+  }
+  const pending = runVersionCheck({
+    paths,
+    spawn,
+    autoSpawn: options.autoSpawn ?? true,
+    requestTimeoutMs: options.requestTimeoutMs ?? 1e4,
+    waitTimeoutMs: options.spawnWaitTimeoutMs ?? 5e3,
+    pollIntervalMs: options.spawnPollIntervalMs ?? 100,
+    check
+  }).catch((error) => {
+    if (!(error instanceof DaemonVersionMismatchError)) {
+      versionChecks.delete(paths.socketPath);
+    }
+    throw error;
+  });
+  versionChecks.set(paths.socketPath, pending);
+  return pending;
+};
+var openDaemonStream = async (options) => {
+  const paths = getStateDirPaths(options.stateDir);
+  const autoSpawn = options.autoSpawn ?? true;
+  const spawn = options.spawn ?? defaultSpawn;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 1e4;
+  const connectSocket = () => {
+    return new Promise((resolve2, reject) => {
+      const socket2 = connect2(paths.socketPath);
+      socket2.once("connect", () => {
+        socket2.off("error", onError);
+        resolve2(socket2);
+      });
+      const onError = (error) => {
+        reject(error);
+      };
+      socket2.once("error", onError);
+    });
+  };
+  await ensureDaemonVersion(paths, options, spawn);
+  let socket;
+  try {
+    socket = await connectSocket();
+  } catch (error) {
+    if (!autoSpawn || !isConnectionMissingError(error)) {
+      throw error;
+    }
+    await spawnDaemonAndWait(
+      paths,
+      spawn,
+      options.spawnWaitTimeoutMs ?? 5e3,
+      options.spawnPollIntervalMs ?? 100
+    );
+    socket = await connectSocket();
+  }
+  socket.on("error", () => {
+  });
+  const notificationListeners = /* @__PURE__ */ new Set();
+  const closeListeners = /* @__PURE__ */ new Set();
+  const pendingCalls = /* @__PURE__ */ new Map();
+  let buffer = "";
+  socket.on("data", (chunk) => {
+    buffer += chunk.toString("utf8");
+    let newlineIndex = buffer.indexOf("\n");
+    while (newlineIndex !== -1) {
+      const line = buffer.slice(0, newlineIndex);
+      buffer = buffer.slice(newlineIndex + 1);
+      newlineIndex = buffer.indexOf("\n");
+      if (line.length === 0) {
+        continue;
+      }
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      if (message.method === "event") {
+        for (const listener of notificationListeners) {
+          try {
+            listener(message.params);
+          } catch {
+          }
+        }
+        continue;
+      }
+      const pending = typeof message.id === "number" ? pendingCalls.get(message.id) : void 0;
+      if (!pending) {
+        continue;
+      }
+      pendingCalls.delete(message.id);
+      clearTimeout(pending.timeout);
+      if (message.error) {
+        pending.reject(new DaemonRpcError(message.error.code, message.error.message, message.error.data));
+      } else {
+        pending.resolve(message.result);
+      }
+    }
+  });
+  socket.on("close", () => {
+    for (const [, pending] of pendingCalls) {
+      clearTimeout(pending.timeout);
+      pending.reject(new DaemonUnavailableError("Connection to the Appduct daemon closed.", "closed"));
+    }
+    pendingCalls.clear();
+    for (const listener of closeListeners) {
+      listener();
+    }
+  });
+  return {
+    call: (method, params, timeoutMs) => {
+      return new Promise((resolve2, reject) => {
+        const id = nextRequestId;
+        nextRequestId += 1;
+        const timeout = setTimeout(() => {
+          pendingCalls.delete(id);
+          reject(new DaemonUnavailableError(`Timed out waiting for a response to "${method}".`, "timeout"));
+        }, timeoutMs ?? requestTimeoutMs);
+        pendingCalls.set(id, {
+          resolve: resolve2,
+          reject,
+          timeout
+        });
+        socket.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}
+`);
+      });
+    },
+    onNotification: (callback) => {
+      notificationListeners.add(callback);
+      return () => {
+        notificationListeners.delete(callback);
+      };
+    },
+    onClose: (callback) => {
+      closeListeners.add(callback);
+      return () => {
+        closeListeners.delete(callback);
+      };
+    },
+    close: () => {
+      socket.destroy();
+    }
+  };
+};
+
+// src/mcp/app-tools.ts
+import {
+  MAX_TOOLS_FILTER_LENGTH,
+  MAX_TOOL_TIMEOUT_MS as MAX_TOOL_TIMEOUT_MS2,
+  MIN_TOOL_TIMEOUT_MS as MIN_TOOL_TIMEOUT_MS2,
+  RPC_METHODS as RPC_METHODS4,
+  renderToolSignature,
+  summarizeToolDescription,
+  TOOL_GROUP_PATTERN
+} from "@appduct/shared";
+
+// src/mcp/connect-tool.ts
+import {
+  RPC_METHODS as RPC_METHODS3
+} from "@appduct/shared";
+
+// src/cli/open-target.ts
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile as readFile4, rm as rm3 } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+// 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 usageError = (message, details) => {
+  return new AppductCliError("usage_error", message, 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/cli/open-target.ts
+var isOpenTarget = (value) => {
+  return value === "android" || value === "ios-sim" || value === "ios-device";
+};
+var usesLoopbackAddress = (target) => {
+  return target === "android" || target === "ios-sim";
+};
+var platformOf = (target) => {
+  if (target === "android") {
+    return "android";
+  }
+  if (target === "ios-device") {
+    return "ios";
+  }
+  return void 0;
+};
+var isLoopbackAddress = (address) => {
+  const normalized = address.trim().toLowerCase().replace(/^\[|\]$/gu, "");
+  return normalized === "localhost" || normalized === "::1" || normalized === "0.0.0.0" || normalized === "::" || /^127\./u.test(normalized);
+};
+var loopbackAddressMessage = (address) => `The daemon advertised "${address}", which a physical device cannot reach \u2014 it would point the phone at itself and the session would never be claimed. No routable LAN address was detected; set "advertisedIp" in config.json to this machine's address on the network the device is on, and retry.`;
+var defaultExec = (command, args) => {
+  return new Promise((resolve2, reject) => {
+    execFile(command, args, { encoding: "utf8" }, (error, stdout, stderr) => {
+      if (error) {
+        reject(Object.assign(error, { stdout, stderr }));
+        return;
+      }
+      resolve2({ stdout, stderr });
+    });
+  });
+};
+var TOOL_INSTALL_HINT = {
+  adb: "the Android platform-tools (adb)",
+  xcrun: "the Xcode command line tools (xcrun)"
+};
+var run = async (exec, command, args) => {
+  try {
+    return await exec(command, args);
+  } catch (error) {
+    const err = error;
+    if (err.code === "ENOENT") {
+      throw connectionError(
+        `"${command}" was not found on PATH. Install ${TOOL_INSTALL_HINT[command] ?? command} and retry.`
+      );
+    }
+    const stderr = (err.stderr ?? "").trim();
+    throw connectionError(
+      `"${command} ${args.join(" ")}" failed${stderr ? `: ${stderr}` : `: ${err.message}`}`
+    );
+  }
+};
+var parseBootedSimulators = (stdout) => {
+  let parsed;
+  try {
+    parsed = JSON.parse(stdout);
+  } catch {
+    return [];
+  }
+  return Object.values(parsed.devices ?? {}).flat().filter(
+    (entry) => entry.state === "Booted" && typeof entry.udid === "string" && entry.udid.length > 0
+  ).map((entry) => ({ udid: entry.udid, name: entry.name ?? entry.udid }));
+};
+var listBootedSimulators = async (exec) => {
+  const preflight = await run(exec, "xcrun", ["simctl", "list", "devices", "booted", "--json"]);
+  return parseBootedSimulators(preflight.stdout);
+};
+var describeSimulator = (simulator) => `${simulator.name} (${simulator.udid})`;
+var deliverIosSim = async (exec, deepLink, device) => {
+  if (device) {
+    await run(exec, "xcrun", ["simctl", "openurl", device, deepLink]);
+    return;
+  }
+  const booted = await listBootedSimulators(exec);
+  if (booted.length === 0) {
+    throw usageError("No booted iOS simulator found. Boot a simulator (e.g. via Xcode) and retry.");
+  }
+  if (booted.length > 1) {
+    throw usageError(
+      `Multiple iOS simulators are booted (${booted.map(describeSimulator).join(", ")}); specify --device <udid>.`
+    );
+  }
+  await run(exec, "xcrun", ["simctl", "openurl", booted[0].udid, deepLink]);
+};
+var runDevicectlJson = async (exec, buildArgs) => {
+  let dir;
+  try {
+    dir = await mkdtemp(path.join(tmpdir(), "appduct-devicectl-"));
+  } catch (error) {
+    throw connectionError(
+      `A temporary directory for devicectl's --json-output could not be created in "${tmpdir()}" (${error.message}). Set TMPDIR to a writable directory and retry.`
+    );
+  }
+  const file = path.join(dir, "devicectl.json");
+  try {
+    await run(exec, "xcrun", buildArgs(file));
+    try {
+      return JSON.parse(await readFile4(file, "utf8"));
+    } catch {
+      return void 0;
+    }
+  } finally {
+    await rm3(dir, { force: true, recursive: true }).catch(() => {
+    });
+  }
+};
+var DELIVERABLE_PLATFORM = "ios";
+var UNREACHABLE_TUNNEL_STATE = "unavailable";
+var USABLE_PAIRING_STATE = "paired";
+var parsePairedIosDevices = (payload) => {
+  const devices = payload?.result?.devices;
+  if (!Array.isArray(devices)) {
+    return [];
+  }
+  return devices.map((entry) => {
+    const platform = entry?.hardwareProperties?.platform;
+    if (typeof platform === "string" && platform.toLowerCase() !== DELIVERABLE_PLATFORM) {
+      return void 0;
+    }
+    const tunnelState = entry?.connectionProperties?.tunnelState;
+    if (typeof tunnelState === "string" && tunnelState.toLowerCase() === UNREACHABLE_TUNNEL_STATE) {
+      return void 0;
+    }
+    const pairingState = entry?.connectionProperties?.pairingState;
+    if (typeof pairingState === "string" && pairingState.toLowerCase() !== USABLE_PAIRING_STATE) {
+      return void 0;
+    }
+    const hardwareUdid = entry?.hardwareProperties?.udid;
+    const udid = typeof hardwareUdid === "string" && hardwareUdid.length > 0 ? hardwareUdid : entry?.identifier;
+    return typeof udid === "string" && udid.length > 0 ? { udid, name: entry?.deviceProperties?.name ?? udid } : void 0;
+  }).filter((device) => device !== void 0);
+};
+var listPairedIosDevices = async (exec) => {
+  const payload = await runDevicectlJson(exec, (file) => [
+    "devicectl",
+    "list",
+    "devices",
+    "--timeout",
+    "5",
+    "--json-output",
+    file
+  ]);
+  return parsePairedIosDevices(payload);
+};
+var describeIosDevice = (device) => `${device.name} (${device.udid})`;
+var MISSING_APP_ID_MESSAGE = 'Delivering to a device needs the installed app\'s id (the Android package name, or the iOS bundle id): pass "--app-id <id>" (or "appId" over MCP), or record it as "appId.<platform>" in .appduct/config.json \u2014 run `appduct init --android-app-id <id> --ios-app-id <id>` to write it.';
+var APP_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+var isValidAppId = (value) => APP_ID_PATTERN.test(value);
+var invalidAppIdMessage = (value) => `"${value}" is not a valid app id (letters, digits, ".", "_" and "-", starting with a letter or digit).`;
+var resolveSingleIosDevice = async (exec) => {
+  const paired = await listPairedIosDevices(exec);
+  if (paired.length === 0) {
+    throw usageError(
+      'No connected iOS device was found ("xcrun devicectl list devices" listed none, ignoring disconnected devices and non-iOS ones such as a paired Watch or Vision Pro). Connect the device, trust this Mac, and enable Developer Mode on it, then retry.'
+    );
+  }
+  if (paired.length > 1) {
+    throw usageError(
+      `Multiple connected iOS devices were found (${paired.map(describeIosDevice).join(", ")}); specify --device <udid>.`
+    );
+  }
+  return paired[0].udid;
+};
+var deliverIosDevice = async (exec, deepLink, device, appId, relaunch) => {
+  if (!appId) {
+    throw usageError(MISSING_APP_ID_MESSAGE);
+  }
+  if (!isValidAppId(appId)) {
+    throw usageError(invalidAppIdMessage(appId));
+  }
+  const udid = device ?? await resolveSingleIosDevice(exec);
+  await run(exec, "xcrun", [
+    "devicectl",
+    "device",
+    "process",
+    "launch",
+    "--device",
+    udid,
+    // Opt-in only (`--relaunch` / `relaunch: true`). A plain `process launch` is what the vendored
+    // Expo CLI does, so it is the better-attested default; what it does when the app is *already
+    // running* is the one thing nobody here can verify without hardware. If that turns out to fail
+    // rather than deliver the URL, `--terminate-existing` is the escape hatch — it kills the
+    // running instance first, which Appduct copes with because a delivered link supersedes a
+    // held session.
+    ...relaunch ? ["--terminate-existing"] : [],
+    "--payload-url",
+    deepLink,
+    appId
+  ]);
+};
+var parseAdbDevices = (stdout) => {
+  return stdout.split("\n").slice(1).map((line) => line.trim()).filter((line) => line.length > 0).map((line) => {
+    const [serial = "", state = ""] = line.split(/\s+/u);
+    return { serial, state };
+  }).filter((entry) => entry.serial.length > 0);
+};
+var listAttachedAndroidDevices = async (exec) => {
+  const listing = await run(exec, "adb", ["devices"]);
+  return parseAdbDevices(listing.stdout).filter((entry) => entry.state === "device").map((entry) => entry.serial);
+};
+var resolveAndroidSerial = async (exec, device, env) => {
+  if (device) {
+    return device;
+  }
+  if (env.ANDROID_SERIAL) {
+    return void 0;
+  }
+  const attached = await listAttachedAndroidDevices(exec);
+  if (attached.length === 0) {
+    throw usageError('No Android device or emulator is attached ("adb devices" listed none).');
+  }
+  if (attached.length > 1) {
+    throw usageError(
+      `Multiple Android devices are attached (${attached.join(
+        ", "
+      )}); specify --device <serial> or set ANDROID_SERIAL.`
+    );
+  }
+  return void 0;
+};
+var withSerial = (args, serial) => {
+  return serial ? ["-s", serial, ...args] : args;
+};
+var AM_START_ERROR_PATTERN = /^(?:Error:|Exception occurred while executing|Security exception:)/mu;
+var deliverAndroid = async (exec, deepLink, wssPort, device, env, appId) => {
+  if (!isValidAppId(appId)) {
+    throw usageError(invalidAppIdMessage(appId));
+  }
+  const serial = await resolveAndroidSerial(exec, device, env);
+  await run(exec, "adb", withSerial(["reverse", `tcp:${wssPort}`, `tcp:${wssPort}`], serial));
+  const { stdout, stderr } = await run(
+    exec,
+    "adb",
+    withSerial(
+      [
+        "shell",
+        "am",
+        "start",
+        "-a",
+        "android.intent.action.VIEW",
+        "-d",
+        // `adb shell` reconstructs everything after "shell" into one string and re-parses it on the
+        // device's own shell; single-quoting the URL here (not just for local execFile, which never
+        // re-tokenizes argv) protects against that second, remote parse (ARCHITECTURE.md §8).
+        `'${deepLink}'`,
+        // Names the app explicitly: without this, more than one installed app declaring the same
+        // scheme makes Android show an "Open with" chooser, which `am start` still reports as a
+        // successful launch — see `AM_START_ERROR_PATTERN` below for the other half of the fix.
+        "-p",
+        appId
+      ],
+      serial
+    )
+  );
+  if (AM_START_ERROR_PATTERN.test(stdout) || AM_START_ERROR_PATTERN.test(stderr)) {
+    throw usageError(
+      `"adb shell am start" could not launch "${appId}": ${(stdout + stderr).trim() || "(no output)"} \u2014 the app is likely not installed on this device, or its installed build does not declare a matching deep-link scheme.`
+    );
+  }
+};
+var safeList = async (list) => {
+  try {
+    return await list();
+  } catch {
+    return [];
+  }
+};
+var detectBootedTargets = async (options = {}) => {
+  const exec = options.exec ?? defaultExec;
+  const env = options.env ?? process.env;
+  const [simulators, androidSerials] = await Promise.all([
+    safeList(() => listBootedSimulators(exec)),
+    env.ANDROID_SERIAL ? Promise.resolve([env.ANDROID_SERIAL]) : safeList(() => listAttachedAndroidDevices(exec))
+  ]);
+  const candidates = [
+    ...simulators.map((simulator) => ({
+      target: "ios-sim",
+      device: simulator.udid,
+      label: describeSimulator(simulator)
+    })),
+    ...androidSerials.map((serial) => ({
+      target: "android",
+      device: serial,
+      label: serial
+    }))
+  ];
+  if (candidates.length === 0) {
+    return { kind: "none" };
+  }
+  if (candidates.length === 1) {
+    return { kind: "single", detected: candidates[0] };
+  }
+  return { kind: "ambiguous", candidates };
+};
+var deliverToOpenTarget = async (options) => {
+  const exec = options.exec ?? defaultExec;
+  if (options.target === "ios-sim") {
+    await deliverIosSim(exec, options.deepLink, options.device);
+    return;
+  }
+  if (options.target === "ios-device") {
+    await deliverIosDevice(
+      exec,
+      options.deepLink,
+      options.device,
+      options.appId,
+      options.relaunch ?? false
+    );
+    return;
+  }
+  if (!options.appId) {
+    throw usageError(MISSING_APP_ID_MESSAGE);
+  }
+  await deliverAndroid(
+    exec,
+    options.deepLink,
+    options.wssPort,
+    options.device,
+    options.env ?? process.env,
+    options.appId
+  );
+};
+
+// src/link.ts
+import { RPC_METHODS as RPC_METHODS2 } from "@appduct/shared";
+
+// src/scheme.ts
+import { existsSync as existsSync2 } from "node:fs";
+import { readFile as readFile6 } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname as dirname2, join as join6, resolve } from "node:path";
+
+// src/native-scheme.ts
+import { readdir, readFile as readFile5, stat as stat3 } from "node:fs/promises";
+import { join as join5 } from "node:path";
+var MAX_PROBE_FILE_BYTES = 2 * 1024 * 1024;
+var MAX_PLIST_WALK_DEPTH = 2;
+var MAX_WALK_ENTRIES = 5e3;
+var EXCLUDED_WALK_DIRS = /* @__PURE__ */ new Set(["Pods", "build", "node_modules", "DerivedData"]);
+var readCappedText = async (path2) => {
+  const buffer = await readCappedBuffer(path2);
+  if (!buffer.ok) {
+    return buffer;
+  }
+  return { ok: true, text: buffer.data.toString("utf8") };
+};
+var readCappedBuffer = async (path2) => {
+  let size;
+  try {
+    const stats = await stat3(path2);
+    if (!stats.isFile()) {
+      return { ok: false, reason: "not-found" };
+    }
+    size = stats.size;
+  } catch {
+    return { ok: false, reason: "not-found" };
+  }
+  if (size > MAX_PROBE_FILE_BYTES) {
+    return { ok: false, reason: "too-large" };
+  }
+  try {
+    return { ok: true, data: await readFile5(path2) };
+  } catch {
+    return { ok: false, reason: "unreadable" };
+  }
+};
+var requireValidNativeScheme = (value, origin) => {
+  if (!isValidScheme(value)) {
+    throw usageError(
+      `Invalid deep-link scheme ${JSON.stringify(value)} from ${origin}: a scheme must start with a letter and contain only letters, digits, "+", "-" or "." (for example "myapp") \u2014 do not include "://".`
+    );
+  }
+  return value;
+};
+var GRADLE_PLACEHOLDER_PATTERN = /manifestPlaceholders\s*(?:\[\s*["']appductScheme["']\s*\]|\.\s*appductScheme)\s*=\s*["']([^"']*)["']/u;
+var extractGradleScheme = (text) => {
+  const match = GRADLE_PLACEHOLDER_PATTERN.exec(text);
+  const value = match?.[1];
+  return value !== void 0 && value.length > 0 ? value : void 0;
+};
+var probeAndroidGradle = async (root) => {
+  const candidates = [join5(root, "app", "build.gradle.kts"), join5(root, "app", "build.gradle")];
+  const notes = [];
+  for (const candidate of candidates) {
+    const read = await readCappedText(candidate);
+    if (!read.ok) {
+      if (read.reason === "too-large") {
+        notes.push(`${candidate} (too large, skipped)`);
+      }
+      continue;
+    }
+    const scheme = extractGradleScheme(read.text);
+    if (scheme !== void 0) {
+      requireValidNativeScheme(scheme, `"appductScheme" in ${candidate}`);
+      return {
+        result: {
+          source: "android-gradle",
+          scheme,
+          origin: `"appductScheme" in ${candidate}`
+        },
+        tried: [describeAndroidGradleTried(candidates, notes)]
+      };
+    }
+  }
+  return { tried: [describeAndroidGradleTried(candidates, notes)] };
+};
+var describeAndroidGradleTried = (candidates, notes) => {
+  const base = `${candidates.join(", ")} ("appductScheme" manifest placeholder)`;
+  return notes.length === 0 ? base : `${base} \u2014 ${notes.join(", ")}`;
+};
+var INTENT_FILTER_PATTERN = /<intent-filter\b[^>]*>([\s\S]*?)<\/intent-filter>/giu;
+var VIEW_ACTION_PATTERN = /<action\b[^>]*\bandroid:name\s*=\s*["']android\.intent\.action\.VIEW["']/iu;
+var DATA_SCHEME_PATTERN = /<data\b[^>]*\bandroid:scheme\s*=\s*["']([^"']*)["']/iu;
+var extractManifestScheme = (xml) => {
+  for (const match of xml.matchAll(INTENT_FILTER_PATTERN)) {
+    const block = match[1] ?? "";
+    if (!VIEW_ACTION_PATTERN.test(block)) {
+      continue;
+    }
+    const dataMatch = DATA_SCHEME_PATTERN.exec(block);
+    const scheme = dataMatch?.[1];
+    if (scheme !== void 0 && scheme.length > 0) {
+      return scheme;
+    }
+  }
+  return void 0;
+};
+var probeAndroidManifest = async (root) => {
+  const manifestPath = join5(root, "app", "src", "main", "AndroidManifest.xml");
+  const read = await readCappedText(manifestPath);
+  const description = `${manifestPath} (first <data android:scheme> in a VIEW intent-filter)`;
+  if (!read.ok) {
+    return {
+      tried: [read.reason === "too-large" ? `${description} \u2014 too large, skipped` : description]
+    };
+  }
+  const scheme = extractManifestScheme(read.text);
+  if (scheme === void 0) {
+    return { tried: [description] };
+  }
+  requireValidNativeScheme(scheme, `"android:scheme" in ${manifestPath}`);
+  return {
+    result: {
+      source: "android-manifest",
+      scheme,
+      origin: `"android:scheme" in ${manifestPath}`
+    },
+    tried: [description]
+  };
+};
+var XML_ENTITIES = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
+var decodeXmlEntities = (text) => {
+  return text.replace(/&(#x[0-9a-fA-F]+|#[0-9]+|[a-zA-Z]+);/gu, (whole, entity) => {
+    if (entity.startsWith("#x")) {
+      const code = Number.parseInt(entity.slice(2), 16);
+      return Number.isNaN(code) ? whole : String.fromCodePoint(code);
+    }
+    if (entity.startsWith("#")) {
+      const code = Number.parseInt(entity.slice(1), 10);
+      return Number.isNaN(code) ? whole : String.fromCodePoint(code);
+    }
+    return XML_ENTITIES[entity] ?? whole;
+  });
+};
+var tokenizePlistXml = (xml) => {
+  const cleaned = xml.replace(/<\?[\s\S]*?\?>/gu, "").replace(/<!DOCTYPE[\s\S]*?>/giu, "").replace(/<!--[\s\S]*?-->/gu, "");
+  const root = { tag: "#root", children: [], text: "" };
+  const stack = [root];
+  const tagOrTextPattern = /<(\/?)([a-zA-Z][\w.:-]*)\b[^>]*?(\/?)>|([^<]+)/gu;
+  for (const match of cleaned.matchAll(tagOrTextPattern)) {
+    const [, closing, name, selfClosing, text] = match;
+    const top = stack[stack.length - 1];
+    if (text !== void 0) {
+      top.text += decodeXmlEntities(text);
+      continue;
+    }
+    if (closing) {
+      if (stack.length > 1) {
+        stack.pop();
+      }
+      continue;
+    }
+    const node = { tag: name ?? "", children: [], text: "" };
+    top.children.push(node);
+    if (!selfClosing) {
+      stack.push(node);
+    }
+  }
+  return root;
+};
+var plistNodeToValue = (node) => {
+  switch (node.tag) {
+    case "true":
+      return true;
+    case "false":
+      return false;
+    case "integer": {
+      const value = Number.parseInt(node.text.trim(), 10);
+      return Number.isNaN(value) ? node.text.trim() : value;
+    }
+    case "real": {
+      const value = Number.parseFloat(node.text.trim());
+      return Number.isNaN(value) ? node.text.trim() : value;
+    }
+    case "array":
+      return node.children.map(plistNodeToValue);
+    case "dict": {
+      const result = {};
+      for (let index = 0; index < node.children.length; index += 2) {
+        const keyNode = node.children[index];
+        const valueNode = node.children[index + 1];
+        if (keyNode?.tag === "key" && valueNode !== void 0) {
+          result[keyNode.text.trim()] = plistNodeToValue(valueNode);
+        }
+      }
+      return result;
+    }
+    default:
+      return node.text.trim();
+  }
+};
+var parsePlistXml = (xml) => {
+  const root = tokenizePlistXml(xml);
+  const plistNode = root.children.find((child) => child.tag === "plist");
+  const valueNode = plistNode?.children[0];
+  return valueNode ? plistNodeToValue(valueNode) : void 0;
+};
+var isBinaryPlist = (buffer) => {
+  return buffer.length >= 6 && buffer.subarray(0, 6).toString("latin1") === "bplist";
+};
+var firstPlistUrlScheme = (cfBundleURLTypes) => {
+  if (!Array.isArray(cfBundleURLTypes)) {
+    return void 0;
+  }
+  for (const entry of cfBundleURLTypes) {
+    if (typeof entry !== "object" || entry === null || Array.isArray(entry)) {
+      continue;
+    }
+    const scheme = firstConfiguredScheme(entry.CFBundleURLSchemes);
+    if (scheme !== void 0) {
+      return scheme;
+    }
+  }
+  return void 0;
+};
+var walkForFilename = async (root, filename, maxDepth) => {
+  const hits = [];
+  let visited = 0;
+  const walk = async (dir, depth) => {
+    let entries;
+    try {
+      entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (visited >= MAX_WALK_ENTRIES) {
+        return;
+      }
+      visited += 1;
+      if (entry.isSymbolicLink()) {
+        continue;
+      }
+      if (entry.isDirectory()) {
+        if (EXCLUDED_WALK_DIRS.has(entry.name)) {
+          continue;
+        }
+        if (depth < maxDepth) {
+          await walk(join5(dir, entry.name), depth + 1);
+        }
+        continue;
+      }
+      if (entry.isFile() && entry.name === filename) {
+        hits.push({ path: join5(dir, entry.name), depth });
+      }
+    }
+  };
+  await walk(root, 0);
+  hits.sort((a, b) => a.depth - b.depth || a.path.localeCompare(b.path));
+  return hits;
+};
+var probeIosInfoPlist = async (root) => {
+  const files = await walkForFilename(root, "Info.plist", MAX_PLIST_WALK_DEPTH);
+  const describeSearch = (notes2) => {
+    const base = files.length === 0 ? `Info.plist up to ${MAX_PLIST_WALK_DEPTH} levels below ${root} (excluding Pods/build/node_modules/DerivedData) \u2014 none found` : `${files.map((file) => file.path).join(", ")} (first "CFBundleURLSchemes" entry)`;
+    return notes2.length === 0 ? base : `${base} \u2014 ${notes2.join(", ")}`;
+  };
+  const notes = [];
+  for (const file of files) {
+    const read = await readCappedBuffer(file.path);
+    if (!read.ok) {
+      notes.push(
+        `${file.path} (${read.reason === "too-large" ? "too large, skipped" : "unreadable"})`
+      );
+      continue;
+    }
+    if (isBinaryPlist(read.data)) {
+      notes.push(`${file.path} (binary plist \u2014 unreadable, use --scheme)`);
+      continue;
+    }
+    const value = parsePlistXml(read.data.toString("utf8"));
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+      continue;
+    }
+    const scheme = firstPlistUrlScheme(value.CFBundleURLTypes);
+    if (scheme === void 0) {
+      continue;
+    }
+    requireValidNativeScheme(scheme, `"CFBundleURLSchemes" in ${file.path}`);
+    return {
+      result: {
+        source: "ios-info-plist",
+        scheme,
+        origin: `"CFBundleURLSchemes" in ${file.path}`
+      },
+      tried: [describeSearch(notes)]
+    };
+  }
+  return { tried: [describeSearch(notes)] };
+};
+var PROJECT_YML_SCHEME_PATTERN = /CFBundleURLSchemes\s*:\s*(?:\[\s*["']?([^"'\],\r\n]*)["']?|\r?\n[ \t]*-[ \t]*["']?([^"'\r\n]*)["']?)/u;
+var extractProjectYmlScheme = (text) => {
+  const match = PROJECT_YML_SCHEME_PATTERN.exec(text);
+  const raw = (match?.[1] ?? match?.[2])?.trim();
+  return raw !== void 0 && raw.length > 0 ? raw : void 0;
+};
+var probeIosProjectYml = async (root) => {
+  const path2 = join5(root, "project.yml");
+  const description = `${path2} ("info.properties.CFBundleURLTypes" > "CFBundleURLSchemes")`;
+  const read = await readCappedText(path2);
+  if (!read.ok) {
+    return {
+      tried: [read.reason === "too-large" ? `${description} \u2014 too large, skipped` : description]
+    };
+  }
+  const scheme = extractProjectYmlScheme(read.text);
+  if (scheme === void 0) {
+    return { tried: [description] };
+  }
+  requireValidNativeScheme(scheme, `"CFBundleURLSchemes" in ${path2}`);
+  return {
+    result: { source: "ios-project-yml", scheme, origin: `"CFBundleURLSchemes" in ${path2}` },
+    tried: [description]
+  };
+};
+var PROBES = [
+  probeAndroidGradle,
+  probeAndroidManifest,
+  probeIosInfoPlist,
+  probeIosProjectYml
+];
+var discoverNativeScheme = async (root) => {
+  const tried = [];
+  const results = [];
+  for (const probe of PROBES) {
+    const outcome = await probe(root);
+    tried.push(...outcome.tried);
+    if (outcome.result !== void 0) {
+      results.push(outcome.result);
+    }
+  }
+  if (results.length === 0) {
+    return { tried };
+  }
+  const distinctSchemes = new Set(results.map((entry) => entry.scheme));
+  if (distinctSchemes.size > 1) {
+    throw usageError(
+      "Conflicting deep-link schemes found in this project: " + results.map((entry) => `${entry.origin} says ${JSON.stringify(entry.scheme)}`).join(", but ") + ". Appduct will not guess which one is right \u2014 pass --scheme <scheme> to pick one."
+    );
+  }
+  return { result: results[0], tried };
+};
+
+// src/scheme.ts
+var PROJECT_CONFIG_DIR = ".appduct";
+var PROJECT_CONFIG_FILENAME = "config.json";
+var PROJECT_CONFIG_RELATIVE_PATH = join6(PROJECT_CONFIG_DIR, PROJECT_CONFIG_FILENAME);
+var APP_JSON_FILENAME = "app.json";
+var SCHEME_ENV_VAR = "APPDUCT_SCHEME";
+var SCHEME_PATTERN = /^[a-zA-Z][a-zA-Z0-9+.-]*$/u;
+var isValidScheme = (value) => SCHEME_PATTERN.test(value);
+var requireValidScheme = (value, origin) => {
+  if (!isValidScheme(value)) {
+    throw usageError(
+      `Invalid deep-link scheme ${JSON.stringify(value)} from ${origin}: a scheme must start with a letter and contain only letters, digits, "+", "-" or "." (for example "myapp") \u2014 do not include "://".`
+    );
+  }
+  return value;
+};
+var isPlainObject = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var readJsonFile = async (path2) => {
+  let text;
+  try {
+    text = await readFile6(path2, "utf8");
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR" || code === "EISDIR") {
+      return void 0;
+    }
+    throw error;
+  }
+  try {
+    return { raw: JSON.parse(text) };
+  } catch (error) {
+    throw usageError(`Could not parse ${path2}: ${error.message}`);
+  }
+};
+var firstConfiguredScheme = (value) => {
+  if (Array.isArray(value)) {
+    return value.find((entry) => typeof entry === "string" && entry.length > 0);
+  }
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+};
+var discoverExpoScheme = async (dir) => {
+  const path2 = join6(resolve(dir), APP_JSON_FILENAME);
+  const file = await readJsonFile(path2);
+  if (!file || !isPlainObject(file.raw)) {
+    return void 0;
+  }
+  const expo = file.raw.expo;
+  if (!isPlainObject(expo)) {
+    return void 0;
+  }
+  const scheme = firstConfiguredScheme(expo.scheme);
+  return scheme === void 0 ? void 0 : requireValidScheme(scheme, `"expo.scheme" in ${path2}`);
+};
+var discoverStaticProjectScheme = async (cwd) => {
+  const appJsonPath = join6(resolve(cwd), APP_JSON_FILENAME);
+  const tried = [`${appJsonPath} ("expo.scheme")`];
+  const appJsonScheme = await discoverExpoScheme(cwd);
+  if (appJsonScheme !== void 0) {
+    return { scheme: appJsonScheme, source: "app-json", origin: appJsonPath, tried };
+  }
+  const native = await discoverNativeScheme(resolve(cwd));
+  tried.push(...native.tried);
+  if (native.result !== void 0) {
+    return {
+      scheme: native.result.scheme,
+      source: native.result.source,
+      origin: native.result.origin,
+      tried
+    };
+  }
+  return { tried };
+};
+var globalConfigDirs = (options = {}) => {
+  const excluded = /* @__PURE__ */ new Set([join6(resolve(options.homeDir ?? homedir()), PROJECT_CONFIG_DIR)]);
+  if (options.stateDirRoot !== void 0) {
+    excluded.add(resolve(options.stateDirRoot));
+  }
+  return excluded;
+};
+var findProjectConfigs = (startDir, options = {}) => {
+  const excluded = globalConfigDirs(options);
+  const found = [];
+  let dir = resolve(startDir);
+  for (; ; ) {
+    const projectDir = join6(dir, PROJECT_CONFIG_DIR);
+    if (!excluded.has(projectDir)) {
+      const candidate = join6(projectDir, PROJECT_CONFIG_FILENAME);
+      if (existsSync2(candidate)) {
+        found.push(candidate);
+      }
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) {
+      return found;
+    }
+    dir = parent;
+  }
+};
+var readProjectConfigScheme = async (path2) => {
+  const file = await readJsonFile(path2);
+  if (!file) {
+    return void 0;
+  }
+  if (!isPlainObject(file.raw)) {
+    throw usageError(`Invalid Appduct project config at ${path2}: must be a JSON object.`);
+  }
+  const scheme = file.raw.scheme;
+  if (scheme === void 0) {
+    return void 0;
+  }
+  if (typeof scheme !== "string" || scheme.length === 0) {
+    throw usageError(
+      `Invalid Appduct project config at ${path2}: "scheme" must be a non-empty string.`
+    );
+  }
+  return requireValidScheme(scheme, `"scheme" in ${path2}`);
+};
+var APP_ID_PLATFORMS = /* @__PURE__ */ new Set(["ios", "android"]);
+var readProjectConfigAppId = async (path2, platform) => {
+  const file = await readJsonFile(path2);
+  if (!file) {
+    return void 0;
+  }
+  if (!isPlainObject(file.raw)) {
+    throw usageError(`Invalid Appduct project config at ${path2}: must be a JSON object.`);
+  }
+  const appId = file.raw.appId;
+  if (appId === void 0) {
+    return void 0;
+  }
+  if (!isPlainObject(appId)) {
+    throw usageError(
+      `Invalid Appduct project config at ${path2}: "appId" must be an object with "ios" and/or "android" keys.`
+    );
+  }
+  for (const key of Object.keys(appId)) {
+    if (!APP_ID_PLATFORMS.has(key)) {
+      throw usageError(
+        `Invalid Appduct project config at ${path2}: unknown key "appId.${key}" (expected "ios" and/or "android").`
+      );
+    }
+  }
+  const value = appId[platform];
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || value.length === 0) {
+    throw usageError(
+      `Invalid Appduct project config at ${path2}: "appId.${platform}" must be a non-empty string.`
+    );
+  }
+  return value;
+};
+var resolveScheme = async (options = {}) => {
+  const env = options.env ?? process.env;
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const tried = [];
+  tried.push("the --scheme flag");
+  if (options.flagScheme !== void 0 && options.flagScheme.length > 0) {
+    return {
+      scheme: requireValidScheme(options.flagScheme, "the --scheme flag"),
+      source: "flag",
+      tried
+    };
+  }
+  tried.push(`the ${SCHEME_ENV_VAR} environment variable`);
+  const envScheme = env[SCHEME_ENV_VAR];
+  if (typeof envScheme === "string" && envScheme.length > 0) {
+    return {
+      scheme: requireValidScheme(envScheme, `the ${SCHEME_ENV_VAR} environment variable`),
+      source: "env",
+      tried
+    };
+  }
+  const projectConfigPaths = findProjectConfigs(cwd, {
+    stateDirRoot: options.stateDirRoot,
+    homeDir: options.homeDir
+  });
+  tried.push(
+    projectConfigPaths.length === 0 ? `${PROJECT_CONFIG_RELATIVE_PATH} (searched upwards from ${cwd})` : projectConfigPaths.join(", ")
+  );
+  for (const projectConfigPath of projectConfigPaths) {
+    const projectScheme = await readProjectConfigScheme(projectConfigPath);
+    if (projectScheme !== void 0) {
+      return { scheme: projectScheme, source: "project-config", tried };
+    }
+  }
+  tried.push(
+    options.stateConfigPath === void 0 ? `the state directory's config.json ("scheme")` : `${options.stateConfigPath} ("scheme")`
+  );
+  if (options.configScheme !== void 0 && options.configScheme.length > 0) {
+    return {
+      scheme: requireValidScheme(
+        options.configScheme,
+        options.stateConfigPath === void 0 ? `the state directory's config.json "scheme"` : `"scheme" in ${options.stateConfigPath}`
+      ),
+      source: "state-config",
+      tried
+    };
+  }
+  const discovered = await discoverStaticProjectScheme(cwd);
+  tried.push(...discovered.tried);
+  if (discovered.scheme !== void 0) {
+    return { scheme: discovered.scheme, source: discovered.source, tried };
+  }
+  return { tried };
+};
+var describeMissingScheme = (tried) => {
+  const locations = tried.length === 0 ? "" : `Looked in, in order:
+${tried.map((location, index) => `  ${index + 1}. ${location}`).join("\n")}
+`;
+  return "A deep-link scheme is required to compose the link, and none was found. " + locations + `Set one with --scheme <scheme>, ${SCHEME_ENV_VAR}=<scheme>, "expo.scheme" in ${APP_JSON_FILENAME}, or run \`appduct init\` in your app root to write ${PROJECT_CONFIG_RELATIVE_PATH}.`;
+};
+var resolveAppId = async (options) => {
+  const cwd = resolve(options.cwd ?? process.cwd());
+  const tried = [];
+  tried.push("the --app-id flag");
+  if (options.flagAppId !== void 0 && options.flagAppId.length > 0) {
+    return { appId: options.flagAppId, source: "flag", tried };
+  }
+  const projectConfigPaths = findProjectConfigs(cwd, {
+    stateDirRoot: options.stateDirRoot,
+    homeDir: options.homeDir
+  });
+  tried.push(
+    projectConfigPaths.length === 0 ? `${PROJECT_CONFIG_RELATIVE_PATH} (searched upwards from ${cwd})` : projectConfigPaths.join(", ")
+  );
+  for (const projectConfigPath of projectConfigPaths) {
+    const projectAppId = await readProjectConfigAppId(projectConfigPath, options.platform);
+    if (projectAppId !== void 0) {
+      return { appId: projectAppId, source: "project-config", tried };
+    }
+  }
+  return { tried };
+};
+var describeMissingAppId = (platform, tried) => {
+  const locations = tried.length === 0 ? "" : `Looked in, in order:
+${tried.map((location, index) => `  ${index + 1}. ${location}`).join("\n")}
+`;
+  const platformLabel = platform === "android" ? "Android" : "a physical iPhone/iPad";
+  const initFlag = platform === "android" ? "--android-app-id" : "--ios-app-id";
+  return `Delivering to ${platformLabel} needs the installed app's id, and none was found. ${locations}Set one with \`appduct init ${initFlag} <id>\`, --app-id <id>, or "appId.${platform}" in ${PROJECT_CONFIG_RELATIVE_PATH}.`;
+};
+
+// src/link.ts
+var composeDeepLink = (scheme, result) => `${scheme}:///?appduct=${result.deepLinkPayload}&pin=${encodeURIComponent(result.pin)}`;
+
+// src/qr-terminal.ts
+import { toQR } from "toqr";
+var HALF_UPPER = "\u2580";
+var HALF_LOWER = "\u2584";
+var FULL = "\u2588";
+var renderQrToTerminal = (content, options) => {
+  const margin = options?.margin ?? 0;
+  const ecLevel = options?.ecLevel ?? 1;
+  const modules = toQR(content, ecLevel);
+  const side = Math.sqrt(modules.length);
+  if (!Number.isInteger(side)) {
+    throw new Error("Invalid QR matrix size");
+  }
+  const dim = side + 2 * margin;
+  const isDark = (row, col) => {
+    if (row < margin || col < margin || row >= margin + side || col >= margin + side) {
+      return false;
+    }
+    const mr = row - margin;
+    const mc = col - margin;
+    return modules[mr * side + mc] === 1;
+  };
+  const lines = [];
+  for (let row = 0; row < dim; row += 2) {
+    let line = "";
+    for (let col = 0; col < dim; col++) {
+      const top = isDark(row, col);
+      const bottom = row + 1 < dim ? isDark(row + 1, col) : false;
+      line += top ? bottom ? FULL : HALF_UPPER : bottom ? HALF_LOWER : " ";
+    }
+    lines.push(line);
+  }
+  return lines.join("\n");
+};
+
+// src/mcp/connect-tool.ts
+var CONNECT_TOOL_NAME = "appduct_connect";
+var WAIT_FOR_SESSION_TOOL_NAME = "appduct_wait_for_session";
+var OPEN_TARGET_ADDRESS_OVERRIDE = "127.0.0.1";
+var DEFAULT_WAIT_TIMEOUT_MS = 12e4;
+var NO_TARGET = "none";
+var QR_INSTRUCTIONS = 'This link was NOT delivered to a device \u2014 a human has to open it. Before calling appduct_wait_for_session: show the user the "qr" field verbatim inside a fenced code block (it is pre-rendered terminal art \u2014 do not redraw, summarize, or describe it), show "deepLink" underneath it for a device that cannot scan, and ask the user to scan it with the target device. Only then call appduct_wait_for_session; it blocks until the device connects and gives no output while it waits, so calling it before you have asked will look like a hang.';
+var CONNECT_TOOL_DESCRIPTOR = {
+  name: CONNECT_TOOL_NAME,
+  description: 'Mint an Appduct session link and get it onto a device. With no "target", auto-detects a booted iOS simulator or attached Android device and delivers the link to it, returning { sessionId, delivered: true, autoDetected: true } \u2014 this is the normal agent path and needs no human. Pass target "android" or "ios-sim" (optionally with "device") to choose explicitly, or target "none" to force the human flow. Delivering to "android" (explicit or auto-detected) needs "appId" (the Android package name) \u2014 without it, more than one installed app declaring the same scheme would show an ambiguous "Open with" chooser on the device instead of failing loudly. Target "ios-device" is an experimental, never-auto-detected path that delivers to a paired physical iPhone/iPad via xcrun devicectl; it needs "appId" (the iOS bundle id), iOS 17+, Xcode 15+, a connected and trusted device with Developer Mode on, a dev-signed build installed, and the phone on the same network as this machine. An "appId" not supplied here falls back to "appId.<platform>" in the nearest .appduct/config.json (see "appduct init"); it is rejected outright with target "ios-sim" or "none", which need no app id. Pass "relaunch": true with ios-device if the app is already running and the delivery does not take. Only when no device is detected (or target is "none") does this return a QR code for a human to scan, along with an "instructions" field saying what to do with it. Follow up with appduct_wait_for_session to know when the device has connected.',
+  inputSchema: {
+    type: "object",
+    properties: {
+      target: { type: "string", enum: ["android", "ios-sim", "ios-device", NO_TARGET] },
+      device: { type: "string" },
+      appId: { type: "string" },
+      relaunch: { type: "boolean" },
+      ttlSeconds: { type: "number", exclusiveMinimum: 0 }
+    },
+    additionalProperties: false
+  }
+};
+var WAIT_FOR_SESSION_TOOL_DESCRIPTOR = {
+  name: WAIT_FOR_SESSION_TOOL_NAME,
+  description: "Wait for a session minted by appduct_connect to be claimed by a device. Resolves as soon as the device connects (or immediately if it already has); rejects with tool_timeout if timeoutMs elapses first. If appduct_connect returned a QR instead of delivering the link, show that QR to the user and ask them to scan it before calling this \u2014 it produces no output while it waits. Once it resolves, find the app's tools with appduct_list_tools.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      sessionId: { type: "string" },
+      timeoutMs: { type: "number", exclusiveMinimum: 0 }
+    },
+    required: ["sessionId"],
+    additionalProperties: false
+  }
+};
+var McpBuiltinToolError = class extends Error {
+  constructor(type, message) {
+    super(message);
+    this.type = type;
+    this.name = "McpBuiltinToolError";
+  }
+};
+var asRecord = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+};
+var asOptionalConnectTarget = (value) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || !(isOpenTarget(value) || value === NO_TARGET)) {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      '"target" must be "android", "ios-sim", "ios-device", or "none".'
+    );
+  }
+  return value;
+};
+var asOptionalNonEmptyString = (value, field) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || value.length === 0) {
+    throw new McpBuiltinToolError("invalid_request", `"${field}" must be a non-empty string.`);
+  }
+  return value;
+};
+var asOptionalBoolean = (value, field) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "boolean") {
+    throw new McpBuiltinToolError("invalid_request", `"${field}" must be a boolean.`);
+  }
+  return value;
+};
+var asOptionalPositiveNumber = (value, field) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new McpBuiltinToolError("invalid_request", `"${field}" must be a positive number.`);
+  }
+  return value;
+};
+var withResolvedAppId = async (base, flagAppId, deps) => {
+  const platform = platformOf(base.target);
+  if (platform === void 0) {
+    return { delivery: base };
+  }
+  const resolved = await resolveAppId({
+    platform,
+    flagAppId,
+    cwd: deps.cwd,
+    stateDirRoot: deps.stateDirRoot
+  });
+  return { delivery: { ...base, appId: resolved.appId }, appIdTried: resolved.tried };
+};
+var resolveDelivery = async (requested, device, appId, deps) => {
+  if (requested !== void 0 && requested !== NO_TARGET) {
+    return withResolvedAppId(
+      { target: requested, device, label: device ?? requested, autoDetected: false },
+      appId,
+      deps
+    );
+  }
+  if (requested === NO_TARGET) {
+    return {
+      note: 'Called with target: "none", so no device delivery was attempted.'
+    };
+  }
+  const detection = await detectBootedTargets({ exec: deps.exec, env: deps.env });
+  if (detection.kind === "single") {
+    return withResolvedAppId({ ...detection.detected, autoDetected: true }, appId, deps);
+  }
+  if (detection.kind === "ambiguous") {
+    return {
+      note: 'No "target" was given and several devices are available (' + detection.candidates.map((candidate) => `${candidate.target}: ${candidate.label}`).join("; ") + '), so none was picked automatically. Re-call with "target" and "device" to deliver to one of them, or use the QR below.'
+    };
+  }
+  return {
+    note: 'No "target" was given and no booted iOS simulator or attached Android device was detected, so the link could not be delivered automatically. A physical iPhone/iPad is never auto-detected: to deliver to one, re-call with target "ios-device" plus "appId" (needs iOS 17+, Xcode 15+ and a paired, trusted device with Developer Mode on) \u2014 otherwise use the QR flow below.'
+  };
+};
+var handleConnectTool = async (rawArgs, deps) => {
+  const args = asRecord(rawArgs);
+  const requestedTarget = asOptionalConnectTarget(args.target);
+  const device = asOptionalNonEmptyString(args.device, "device");
+  const appId = asOptionalNonEmptyString(args.appId, "appId");
+  const relaunch = asOptionalBoolean(args.relaunch, "relaunch");
+  const ttlSeconds = asOptionalPositiveNumber(args.ttlSeconds, "ttlSeconds");
+  if (device !== void 0 && (requestedTarget === void 0 || requestedTarget === NO_TARGET)) {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      '"device" requires an explicit "target" of "android", "ios-sim" or "ios-device" \u2014 a bare serial/udid does not say which platform it belongs to.'
+    );
+  }
+  if (appId !== void 0 && (requestedTarget === "ios-sim" || requestedTarget === NO_TARGET)) {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      '"appId" only applies with target "android", target "ios-device", or no target at all (auto-detection).'
+    );
+  }
+  if (relaunch !== void 0 && requestedTarget !== "ios-device") {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      '"relaunch" only applies with target "ios-device".'
+    );
+  }
+  if (!deps.scheme) {
+    throw new McpBuiltinToolError("invalid_request", describeMissingScheme(deps.schemeTried ?? []));
+  }
+  const scheme = deps.scheme;
+  const { delivery, note, appIdTried } = await resolveDelivery(requestedTarget, device, appId, deps);
+  const deliveryPlatform = delivery ? platformOf(delivery.target) : void 0;
+  if (deliveryPlatform !== void 0 && delivery?.appId === void 0) {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      describeMissingAppId(deliveryPlatform, appIdTried ?? [])
+    );
+  }
+  if (delivery?.appId !== void 0 && !isValidAppId(delivery.appId)) {
+    throw new McpBuiltinToolError("invalid_request", invalidAppIdMessage(delivery.appId));
+  }
+  const mint = (deliverLocally) => {
+    return deps.call(RPC_METHODS3.linkCreate, {
+      ttlSeconds,
+      addressOverride: deliverLocally ? OPEN_TARGET_ADDRESS_OVERRIDE : void 0
+    });
+  };
+  const asQrResult = (result2, qrNote) => {
+    const deepLink2 = composeDeepLink(scheme, result2);
+    return {
+      sessionId: result2.sessionId,
+      deepLink: deepLink2,
+      expiresAt: result2.expiresAt,
+      ...qrNote === void 0 ? {} : { note: qrNote },
+      qr: renderQrToTerminal(deepLink2),
+      instructions: QR_INSTRUCTIONS
+    };
+  };
+  if (!delivery) {
+    return asQrResult(await mint(false), note);
+  }
+  const result = await mint(usesLoopbackAddress(delivery.target));
+  if (delivery.target === "ios-device" && isLoopbackAddress(result.endpoint.address)) {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      loopbackAddressMessage(result.endpoint.address)
+    );
+  }
+  const deepLink = composeDeepLink(scheme, result);
+  try {
+    await deliverToOpenTarget({
+      target: delivery.target,
+      device: delivery.device,
+      appId: delivery.appId,
+      relaunch,
+      deepLink,
+      wssPort: result.endpoint.port,
+      exec: deps.exec,
+      env: deps.env
+    });
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : "Failed to deliver the deep link.";
+    if (!delivery.autoDetected) {
+      throw new McpBuiltinToolError("tool_execution_error", detail);
+    }
+    return asQrResult(
+      await mint(false),
+      `Auto-detected ${delivery.target} target ${delivery.label}, but delivering the link to it failed: ${detail}. Falling back to a QR code \u2014 pass an explicit "target" (and "device") if a different device is the right one.`
+    );
+  }
+  return {
+    sessionId: result.sessionId,
+    deepLink,
+    expiresAt: result.expiresAt,
+    delivered: true,
+    target: delivery.target,
+    ...delivery.device === void 0 ? {} : { device: delivery.device },
+    ...delivery.autoDetected ? {
+      autoDetected: true,
+      note: `No "target" was given; delivered to the only device found: ${delivery.label}.`
+    } : {}
+  };
+};
+var CONNECTION_LOST_CODES = /* @__PURE__ */ new Set(["ECONNRESET", "EPIPE"]);
+var describeCause = (error) => {
+  return error instanceof Error && error.message.length > 0 ? ` (${error.message})` : "";
+};
+var daemonClosedMessage = (sessionId) => `The connection to the Appduct daemon closed while waiting for session "${sessionId}".`;
+var daemonUnreachableMessage = (sessionId, error) => `The Appduct daemon is unreachable, so session "${sessionId}" cannot be waited on${describeCause(error)}.`;
+var isConnectionLost = (error) => {
+  if (isDaemonUnreachableError(error)) {
+    return true;
+  }
+  const code = error?.code;
+  return typeof code === "string" && CONNECTION_LOST_CODES.has(code);
+};
+var handleWaitForSessionTool = async (rawArgs, deps) => {
+  const args = asRecord(rawArgs);
+  if (typeof args.sessionId !== "string" || args.sessionId.length === 0) {
+    throw new McpBuiltinToolError("invalid_request", '"sessionId" must be a non-empty string.');
+  }
+  const sessionId = args.sessionId;
+  const timeoutMs = asOptionalPositiveNumber(args.timeoutMs, "timeoutMs") ?? DEFAULT_WAIT_TIMEOUT_MS;
+  let stream;
+  try {
+    stream = await openDaemonStream({ stateDir: deps.stateDir, spawn: deps.spawn });
+  } catch (error) {
+    if (isConnectionLost(error)) {
+      throw new McpBuiltinToolError(
+        "tool_execution_error",
+        daemonUnreachableMessage(sessionId, error)
+      );
+    }
+    throw error;
+  }
+  try {
+    return await new Promise((resolve2, reject) => {
+      let settled = false;
+      const settle = (fn) => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        unsubscribeNotification();
+        unsubscribeClose();
+        fn();
+      };
+      const timer = setTimeout(() => {
+        settle(
+          () => reject(
+            new McpBuiltinToolError(
+              "tool_timeout",
+              `Timed out after ${timeoutMs}ms waiting for session "${sessionId}" to be claimed.`
+            )
+          )
+        );
+      }, timeoutMs);
+      const connectionLost = () => new McpBuiltinToolError("tool_execution_error", daemonClosedMessage(sessionId));
+      const unsubscribeClose = stream.onClose(() => {
+        settle(() => reject(connectionLost()));
+      });
+      const unsubscribeNotification = stream.onNotification((payload) => {
+        const event = payload;
+        if (event.kind === "session_claimed" && event.sessionId === sessionId) {
+          settle(() => resolve2({ sessionId, claimed: true, alias: event.alias ?? "" }));
+        }
+      });
+      stream.call(RPC_METHODS3.eventsSubscribe, { sessionSelector: sessionId, kinds: ["session_claimed"] }).then(async () => {
+        if (settled) {
+          return;
+        }
+        const existing = await stream.call(RPC_METHODS3.sessionsDescribe, {
+          selector: sessionId
+        });
+        settle(() => resolve2({ sessionId, claimed: true, alias: existing.alias }));
+      }).catch((error) => {
+        if (error instanceof DaemonRpcError && error.data?.type === "unknown_session") {
+          return;
+        }
+        settle(() => reject(isConnectionLost(error) ? connectionLost() : error));
+      });
+    });
+  } finally {
+    stream.close();
+  }
+};
+
+// src/mcp/app-tools.ts
+var LIST_TOOLS_TOOL_NAME = "appduct_list_tools";
+var DESCRIBE_TOOL_TOOL_NAME = "appduct_describe_tool";
+var CALL_TOOL_TOOL_NAME = "appduct_call_tool";
+var DEFAULT_LIST_TOOLS_LIMIT = 50;
+var SELECTOR_PROPERTY = {
+  type: "string",
+  minLength: 1,
+  description: "Session alias or id. Omit to target the sole active/suspended session."
+};
+var NAME_PROPERTY = { type: "string", minLength: 1 };
+var LIST_TOOLS_TOOL_DESCRIPTOR = {
+  name: LIST_TOOLS_TOOL_NAME,
+  description: `List the tools the connected app registered, as one-line signatures (\`name(param: type, optional?: type) -> result\`) with the first line of each description, the tool's group and its effective policy. Start here: the app's tools are not MCP tools of their own. Every result also carries groups: the app's tool groups with counts, over all its tools. On a large app, list one area with group, copying the exact name from groups, parent path included ("diagnostics/progress", not "progress"); "checkout" includes "checkout/payment". filter is a case-insensitive substring match on name and description only, never on group names; limit (default ${DEFAULT_LIST_TOOLS_LIMIT}) and offset page the name-sorted list, and total counts every match before paging, so page on with offset when total is larger. Use appduct_describe_tool for one tool's full input/output schema, then appduct_call_tool to run it. A tool with policy "prompt" asks the user to approve each call; one with policy "deny" cannot be called.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      selector: SELECTOR_PROPERTY,
+      group: { type: "string", pattern: TOOL_GROUP_PATTERN.source },
+      filter: { type: "string", maxLength: MAX_TOOLS_FILTER_LENGTH },
+      limit: { type: "integer", exclusiveMinimum: 0 },
+      offset: { type: "integer", minimum: 0 }
+    },
+    additionalProperties: false
+  }
+};
+var DESCRIBE_TOOL_TOOL_DESCRIPTOR = {
+  name: DESCRIBE_TOOL_TOOL_NAME,
+  description: "Show one of the connected app's tools in full: description, group, input_schema (JSON Schema for appduct_call_tool's args), output_schema, annotations, timeout and effective policy. Find names with appduct_list_tools.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      selector: SELECTOR_PROPERTY,
+      name: NAME_PROPERTY
+    },
+    required: ["name"],
+    additionalProperties: false
+  }
+};
+var CALL_TOOL_TOOL_DESCRIPTOR = {
+  name: CALL_TOOL_TOOL_NAME,
+  description: `Call one of the connected app's tools by name. args must match the tool's input_schema (see appduct_describe_tool); omit it for a tool that takes no input. The call runs under the tool's own deadline (timeout_ms in appduct_describe_tool, 10000 ms if it declares none); timeoutMs can only shorten it, since the app stops the tool at its own deadline. Returns the tool's result as JSON. A tool with policy "prompt" asks the user to approve the call first, and fails if they decline or this client cannot ask.`,
+  inputSchema: {
+    type: "object",
+    properties: {
+      selector: SELECTOR_PROPERTY,
+      name: NAME_PROPERTY,
+      args: { type: "object" },
+      timeoutMs: { type: "integer", minimum: MIN_TOOL_TIMEOUT_MS2, maximum: MAX_TOOL_TIMEOUT_MS2 }
+    },
+    required: ["name"],
+    additionalProperties: false
+  }
+};
+var asRecord2 = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+};
+var rejectUnknownKeys = (args, tool, allowed) => {
+  const unknown = Object.keys(args).filter((key) => !allowed.includes(key));
+  if (unknown.length > 0) {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      `${tool} does not take ${unknown.map((key) => `"${key}"`).join(", ")}. It takes: ${allowed.join(", ")}.`
+    );
+  }
+};
+var asOptionalString = (value, field) => {
+  if (value === void 0 || value === null) {
+    return void 0;
+  }
+  if (typeof value !== "string" || value.length === 0) {
+    throw new McpBuiltinToolError("invalid_request", `"${field}" must be a non-empty string.`);
+  }
+  return value;
+};
+var asRequiredString = (value, field) => {
+  const parsed = asOptionalString(value, field);
+  if (parsed === void 0) {
+    throw new McpBuiltinToolError("invalid_request", `"${field}" is required.`);
+  }
+  return parsed;
+};
+var toDescriptor = (entry) => {
+  return {
+    name: entry.name,
+    description: entry.description,
+    input_schema: entry.input_schema,
+    output_schema: entry.output_schema,
+    annotations: entry.annotations,
+    timeout_ms: entry.timeout_ms,
+    // Normalised the same way the listing normalises it, so `appduct_describe_tool` never
+    // disagrees with `appduct_list_tools` about whether a tool has a group. The `?? null` also
+    // covers a daemon that predates groups and omits the key entirely.
+    group: entry.group ?? null
+  };
+};
+var resolveSession = async (call, selector) => {
+  const session = await call(RPC_METHODS4.sessionsDescribe, { selector });
+  return { sessionId: session.sessionId, alias: session.alias };
+};
+var findTool = async (call, selector, name) => {
+  const session = await resolveSession(call, selector);
+  const { tools } = await call(RPC_METHODS4.toolsList, { selector: session.sessionId });
+  const entry = tools.find((tool) => tool.name === name);
+  if (!entry) {
+    throw new McpBuiltinToolError(
+      "tool_not_found",
+      `Tool "${name}" is not registered on session "${session.alias}". Use ${LIST_TOOLS_TOOL_NAME} (optionally with filter) to find it.`
+    );
+  }
+  return { session, entry };
+};
+var handleListToolsTool = async (rawArgs, call) => {
+  const args = asRecord2(rawArgs);
+  rejectUnknownKeys(args, LIST_TOOLS_TOOL_NAME, ["selector", "group", "filter", "limit", "offset"]);
+  const selector = asOptionalString(args.selector, "selector");
+  const session = await resolveSession(call, selector);
+  const params = {
+    ...args.group !== void 0 && args.group !== null ? { group: args.group } : {},
+    ...args.filter !== void 0 && args.filter !== null ? { filter: args.filter } : {},
+    limit: args.limit ?? DEFAULT_LIST_TOOLS_LIMIT,
+    ...args.offset !== void 0 && args.offset !== null ? { offset: args.offset } : {}
+  };
+  const result = await call(RPC_METHODS4.toolsList, { selector: session.sessionId, ...params });
+  if (!Array.isArray(result.groups) && "group" in params) {
+    throw new McpBuiltinToolError(
+      "connection_error",
+      "The running Appduct daemon does not support tool groups. Restart it with a newer version (`appduct daemon stop`), then restart this MCP server."
+    );
+  }
+  return {
+    session: session.alias,
+    total: result.total,
+    ...params,
+    tools: result.tools.map((entry) => ({
+      name: entry.name,
+      signature: renderToolSignature(entry),
+      summary: summarizeToolDescription(entry.description),
+      // Always present: `null` for an ungrouped tool, mirroring `groups`. The `?? null` also covers
+      // a daemon that predates groups and omits the key from its entries entirely.
+      group: entry.group ?? null,
+      policy: entry.policy,
+      ...entry.annotations ? { annotations: entry.annotations } : {}
+    })),
+    ...Array.isArray(result.groups) ? { groups: result.groups } : {}
+  };
+};
+var handleDescribeToolTool = async (rawArgs, call) => {
+  const args = asRecord2(rawArgs);
+  rejectUnknownKeys(args, DESCRIBE_TOOL_TOOL_NAME, ["selector", "name"]);
+  const selector = asOptionalString(args.selector, "selector");
+  const name = asRequiredString(args.name, "name");
+  const { session, entry } = await findTool(call, selector, name);
+  return {
+    session: session.alias,
+    signature: renderToolSignature(entry),
+    policy: entry.policy,
+    ...toDescriptor(entry)
+  };
+};
+var parseCallToolArgs = (rawArgs) => {
+  const args = asRecord2(rawArgs);
+  rejectUnknownKeys(args, CALL_TOOL_TOOL_NAME, ["selector", "name", "args", "timeoutMs"]);
+  const selector = asOptionalString(args.selector, "selector");
+  const name = asRequiredString(args.name, "name");
+  const toolArgs = args.args ?? {};
+  if (typeof toolArgs !== "object" || Array.isArray(toolArgs)) {
+    throw new McpBuiltinToolError("invalid_request", '"args" must be an object.');
+  }
+  const timeoutMs = args.timeoutMs ?? void 0;
+  if (timeoutMs !== void 0 && (typeof timeoutMs !== "number" || !Number.isInteger(timeoutMs) || timeoutMs < MIN_TOOL_TIMEOUT_MS2 || timeoutMs > MAX_TOOL_TIMEOUT_MS2)) {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      `"timeoutMs" must be an integer number of milliseconds from ${MIN_TOOL_TIMEOUT_MS2} to ${MAX_TOOL_TIMEOUT_MS2}.`
+    );
+  }
+  return {
+    selector,
+    name,
+    args: toolArgs,
+    timeoutMs
+  };
+};
+var resolveCallDeadline = (tool, requestedTimeoutMs) => {
+  const toolDeadline = clampTimeout(tool.descriptor.timeout_ms);
+  if (requestedTimeoutMs !== void 0 && requestedTimeoutMs > toolDeadline) {
+    throw new McpBuiltinToolError(
+      "invalid_request",
+      `"timeoutMs" can only shorten "${tool.descriptor.name}"'s own deadline of ${toolDeadline} ms: the app stops the tool at that deadline. Raising it takes a larger timeoutMs in the tool's registration.`
+    );
+  }
+  return requestedTimeoutMs ?? toolDeadline;
+};
+var resolveAppTool = async (call, selector, name) => {
+  const { session, entry } = await findTool(call, selector, name);
+  return { ...session, descriptor: toDescriptor(entry), policy: entry.policy };
+};
+
+// src/mcp/events-tool.ts
+import {
+  RPC_METHODS as RPC_METHODS5,
+  EVENT_KINDS
+} from "@appduct/shared";
+var EVENTS_TOOL_NAME = "appduct_events";
+var WAIT_FOR_EVENT_TOOL_NAME = "appduct_wait_for_event";
+var DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS = 12e4;
+var MAX_WAIT_FOR_EVENT_TIMEOUT_MS = 25 * 60 * 1e3;
+var WAIT_FOR_EVENT_PROGRESS_INTERVAL_MS = 6e4;
+var KNOWN_EVENT_KINDS = new Set(EVENT_KINDS);
+var clampWaitForEventTimeoutMs = (requestedMs) => {
+  return Math.min(requestedMs ?? DEFAULT_WAIT_FOR_EVENT_TIMEOUT_MS, MAX_WAIT_FOR_EVENT_TIMEOUT_MS);
+};
+var EVENTS_TOOL_DESCRIPTOR = {
+  name: EVENTS_TOOL_NAME,
+  description: "Drain events retained in the daemon's per-session ring buffer since a cursor \u2014 the pull counterpart to a live subscription, for checking what happened after calling a tool or triggering app behavior. With no selector, targets the sole active/suspended session. Returns { events, cursor }; pass cursor back as since on the next call to avoid re-reading events you've already seen. limit (if given) keeps the OLDEST events in the window and advances cursor only past what was actually returned, so repeated calls page forward through everything retained rather than skipping ahead.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      selector: { type: "string" },
+      since: { type: "integer", minimum: 0 },
+      kinds: { type: "array", items: { type: "string", enum: EVENT_KINDS } },
+      limit: { type: "integer", exclusiveMinimum: 0 }
+    },
+    additionalProperties: false
+  }
+};
+var WAIT_FOR_EVENT_TOOL_DESCRIPTOR = {
+  name: WAIT_FOR_EVENT_TOOL_NAME,
+  description: "Wait for the connected app to push an event via postEvent(name, payload) matching name (and, if match is given, every one of its keys strictly-equal \u2014 primitives only, not objects/arrays \u2014 in the event's payload). Checks already-retained events first, so an event that already fired before this call still resolves immediately; pass since (a cursor from a previous appduct_events/appduct_wait_for_event call) to skip events you've already handled and wait only for a new one \u2014 omitting it can return an old match instantly on every call. Requires a claimed session to already exist (use appduct_wait_for_session first if not). Resolves with { sessionId, alias, name, payload, ts, seq }, or rejects with tool_timeout after timeoutMs (default 120000ms, capped server-side at 1500000ms). A call still running after about two minutes moves to a Claude Code background task, so the result may arrive well after this call returns.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      selector: { type: "string" },
+      name: { type: "string" },
+      match: { type: "object", additionalProperties: { type: ["string", "number", "boolean", "null"] } },
+      since: { type: "integer", minimum: 0 },
+      timeoutMs: { type: "number", exclusiveMinimum: 0 }
+    },
+    required: ["name"],
+    additionalProperties: false
+  }
+};
+var asRecord3 = (value) => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return {};
+  }
+  return value;
+};
+var asOptionalString2 = (value, field) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "string" || value.length === 0) {
+    throw new McpBuiltinToolError("invalid_request", `"${field}" must be a non-empty string.`);
+  }
+  return value;
+};
+var asOptionalNonNegativeInteger = (value, field) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+    throw new McpBuiltinToolError("invalid_request", `"${field}" must be a non-negative integer.`);
+  }
+  return value;
+};
+var asOptionalPositiveInteger = (value, field) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isInteger(value) || value <= 0) {
+    throw new McpBuiltinToolError("invalid_request", `"${field}" must be a positive integer.`);
+  }
+  return value;
+};
+var asOptionalPositiveNumber2 = (value, field) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+    throw new McpBuiltinToolError("invalid_request", `"${field}" must be a positive number.`);
+  }
+  return value;
+};
+var asOptionalEventKinds = (value) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (!Array.isArray(value) || !value.every((kind) => typeof kind === "string" && KNOWN_EVENT_KINDS.has(kind))) {
+    throw new McpBuiltinToolError("invalid_request", '"kinds" must be an array of known event kinds.');
+  }
+  return value;
+};
+var isMatchPrimitive = (value) => {
+  return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+};
+var asOptionalMatch = (value) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new McpBuiltinToolError("invalid_request", '"match" must be a JSON object.');
+  }
+  const record = value;
+  for (const [key, entry] of Object.entries(record)) {
+    if (!isMatchPrimitive(entry)) {
+      throw new McpBuiltinToolError(
+        "invalid_request",
+        `"match.${key}" must be a string, number, boolean, or null (objects/arrays can never match).`
+      );
+    }
+  }
+  return record;
+};
+var handleEventsTool = async (rawArgs, deps) => {
+  const args = asRecord3(rawArgs);
+  return deps.call(RPC_METHODS5.eventsSince, {
+    selector: asOptionalString2(args.selector, "selector"),
+    since: asOptionalNonNegativeInteger(args.since, "since"),
+    kinds: asOptionalEventKinds(args.kinds),
+    limit: asOptionalPositiveInteger(args.limit, "limit")
+  });
+};
+var payloadShallowMatches = (payload, match) => {
+  if (typeof payload !== "object" || payload === null || Array.isArray(payload)) {
+    return false;
+  }
+  const record = payload;
+  return Object.entries(match).every(([key, value]) => record[key] === value);
+};
+var handleWaitForEventTool = async (rawArgs, deps) => {
+  const args = asRecord3(rawArgs);
+  const selector = asOptionalString2(args.selector, "selector");
+  const name = asOptionalString2(args.name, "name");
+  if (!name) {
+    throw new McpBuiltinToolError("invalid_request", '"name" must be a non-empty string.');
+  }
+  const match = asOptionalMatch(args.match);
+  const since = asOptionalNonNegativeInteger(args.since, "since");
+  const timeoutMs = clampWaitForEventTimeoutMs(asOptionalPositiveNumber2(args.timeoutMs, "timeoutMs"));
+  const stream = await openDaemonStream({ stateDir: deps.stateDir, spawn: deps.spawn });
+  try {
+    const described = await stream.call(RPC_METHODS5.sessionsDescribe, { selector });
+    const sessionId = described.sessionId;
+    const alias = described.alias;
+    const toResult = (event) => {
+      if (event.kind !== "app_event" || event.sessionId !== sessionId) {
+        return void 0;
+      }
+      const data = event.data;
+      if (data.name !== name) {
+        return void 0;
+      }
+      if (match && !payloadShallowMatches(data.payload, match)) {
+        return void 0;
+      }
+      return { sessionId, alias, name, payload: data.payload, ts: event.ts, seq: event.seq };
+    };
+    let liveHandler = null;
+    const earlyEvents = [];
+    const unsubscribeNotification = stream.onNotification((payload) => {
+      const event = payload;
+      if (liveHandler) {
+        liveHandler(event);
+      } else {
+        earlyEvents.push(event);
+      }
+    });
+    let unsubscribeClose = () => {
+    };
+    try {
+      await stream.call(RPC_METHODS5.eventsSubscribe, { sessionSelector: sessionId, kinds: ["app_event"] });
+      const sinceResult = await stream.call(RPC_METHODS5.eventsSince, {
+        selector: sessionId,
+        since,
+        kinds: ["app_event"]
+      });
+      const seenSeqs = /* @__PURE__ */ new Set();
+      const backlog = [];
+      for (const event of [...sinceResult.events, ...earlyEvents]) {
+        if (event.sessionId === sessionId && !seenSeqs.has(event.seq)) {
+          seenSeqs.add(event.seq);
+          backlog.push(event);
+        }
+      }
+      backlog.sort((a, b) => a.seq - b.seq);
+      for (const event of backlog) {
+        const result = toResult(event);
+        if (result) {
+          return result;
+        }
+      }
+      const highestConsideredSeq = backlog.length > 0 ? backlog[backlog.length - 1].seq : sinceResult.cursor;
+      return await new Promise((resolve2, reject) => {
+        let settled = false;
+        const settle = (fn) => {
+          if (settled) {
+            return;
+          }
+          settled = true;
+          clearTimeout(timer);
+          if (progressTimer) {
+            clearInterval(progressTimer);
+          }
+          liveHandler = null;
+          fn();
+        };
+        const timer = setTimeout(() => {
+          settle(
+            () => reject(
+              new McpBuiltinToolError(
+                "tool_timeout",
+                `Timed out after ${timeoutMs}ms waiting for event "${name}".`
+              )
+            )
+          );
+        }, timeoutMs);
+        const startedAt = Date.now();
+        const progressTimer = deps.progress ? setInterval(() => {
+          deps.progress.sendNotification({
+            method: "notifications/progress",
+            params: {
+              progressToken: deps.progress.token,
+              progress: Date.now() - startedAt,
+              total: timeoutMs,
+              message: `Still waiting for event "${name}"...`
+            }
+          }).catch(() => {
+          });
+        }, WAIT_FOR_EVENT_PROGRESS_INTERVAL_MS) : void 0;
+        unsubscribeClose = stream.onClose(() => {
+          settle(
+            () => reject(
+              new McpBuiltinToolError(
+                "tool_execution_error",
+                `The connection to the Appduct daemon closed while waiting for event "${name}".`
+              )
+            )
+          );
+        });
+        liveHandler = (event) => {
+          if (settled) {
+            return;
+          }
+          if (event.sessionId === sessionId && event.seq <= highestConsideredSeq) {
+            return;
+          }
+          const result = toResult(event);
+          if (result) {
+            settle(() => resolve2(result));
+          }
+        };
+      });
+    } finally {
+      unsubscribeNotification();
+      unsubscribeClose();
+    }
+  } finally {
+    stream.close();
+  }
+};
+
+// src/mcp/server.ts
+var packageVersion = getPackageVersion();
+var SESSIONS_RESOURCE_URI = "appduct://sessions";
+var isPlainObject2 = (value) => {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+};
+var clientSupportsElicitation = (server) => {
+  return server.getClientCapabilities()?.elicitation !== void 0;
+};
+var ELICITATION_TIMEOUT_MS = 10 * 60 * 1e3;
+var ELICITATION_ARGS_PREVIEW_MAX_CHARS = 2048;
+var formatElicitationArgsPreview = (args) => {
+  const json = JSON.stringify(args);
+  if (json.length <= ELICITATION_ARGS_PREVIEW_MAX_CHARS) {
+    return json;
+  }
+  return `${json.slice(0, ELICITATION_ARGS_PREVIEW_MAX_CHARS)}\u2026 [truncated at ${ELICITATION_ARGS_PREVIEW_MAX_CHARS} of ${json.length} characters]`;
+};
+var buildElicitationMessage = (tool, args) => {
+  return `Appduct: allow the app tool "${tool.descriptor.name}" to run on session "${tool.alias}" (${tool.sessionId})? Arguments: ${formatElicitationArgsPreview(args)}`;
+};
+var ElicitationDeclinedError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ElicitationDeclinedError";
+  }
+};
+var requestElicitationConsent = async (server, tool, args, timeoutMs) => {
+  try {
+    const result = await server.elicitInput(
+      {
+        message: buildElicitationMessage(tool, args),
+        // The accept/decline/cancel action itself is the consent signal — nothing is actually being
+        // collected, so the schema asks for no fields. An empty `properties` record is a valid
+        // restricted-JSON-Schema object per the MCP spec (the SDK's request schema requires the key
+        // but not that it be non-empty), and renders as a plain confirm/decline prompt.
+        requestedSchema: { type: "object", properties: {} }
+      },
+      { timeout: timeoutMs }
+    );
+    if (result.action === "accept") {
+      return { type: "accepted" };
+    }
+    return {
+      type: "declined",
+      message: `The user ${result.action === "cancel" ? "cancelled" : "declined"} the request to call "${tool.descriptor.name}" on session "${tool.alias}".`
+    };
+  } catch (error) {
+    if (error instanceof McpError && error.code === ErrorCode.RequestTimeout) {
+      return {
+        type: "declined",
+        message: `Timed out after ${timeoutMs / 1e3}s waiting for a human to respond to the consent prompt for "${tool.descriptor.name}" on session "${tool.alias}".`
+      };
+    }
+    return { type: "no-channel" };
+  }
+};
+var toolSuccessContent = (result) => {
+  const content = [{ type: "text", text: JSON.stringify(result) }];
+  if (isPlainObject2(result)) {
+    return { content, structuredContent: result };
+  }
+  return { content };
+};
+var toolErrorContent = (type, message, details) => {
+  const suffix = details !== void 0 ? ` ${JSON.stringify(details)}` : "";
+  return {
+    isError: true,
+    content: [{ type: "text", text: `${type}: ${message}${suffix}` }]
+  };
+};
+var toolErrorContentFromError = (error) => {
+  if (error instanceof DaemonRpcError && error.data?.type) {
+    return toolErrorContent(error.data.type, error.message, error.data.details);
+  }
+  if (error instanceof McpBuiltinToolError) {
+    return toolErrorContent(error.type, error.message);
+  }
+  if (error instanceof ElicitationDeclinedError) {
+    return toolErrorContent("consent_declined", error.message);
+  }
+  if (error instanceof Error) {
+    return toolErrorContent("tool_execution_error", error.message);
+  }
+  return toolErrorContent("tool_execution_error", "An unexpected error occurred.");
+};
+var createMcpServer = async (options) => {
+  const openStream = options.openStream ?? openDaemonStream;
+  let stream;
+  try {
+    stream = await openStream({
+      stateDir: options.stateDir,
+      spawn: options.spawn,
+      checkVersion: options.checkVersion
+    });
+  } catch (error) {
+    if (error instanceof DaemonVersionMismatchError) {
+      console.error(`appduct mcp: refusing to start. ${error.message}`);
+    }
+    throw error;
+  }
+  const server = new Server(
+    { name: "appduct", version: packageVersion },
+    // `tools/list` is a fixed set of built-ins, so there is never a list change to announce.
+    { capabilities: { tools: {}, resources: {} } }
+  );
+  const resolveToolCallConsent = async (tool, args) => {
+    if (tool.policy !== "prompt" || !clientSupportsElicitation(server)) {
+      return void 0;
+    }
+    const outcome = await requestElicitationConsent(
+      server,
+      tool,
+      args,
+      options.elicitationTimeoutMs ?? ELICITATION_TIMEOUT_MS
+    );
+    if (outcome.type === "accepted") {
+      return "elicitation";
+    }
+    if (outcome.type === "declined") {
+      throw new ElicitationDeclinedError(outcome.message);
+    }
+    return void 0;
+  };
+  const callAppTool = async (tool, args, requestedTimeoutMs, progressToken, sendNotification, signal) => {
+    const timeoutMs = resolveCallDeadline(tool, requestedTimeoutMs);
+    const transportTimeoutMs = deriveCallTransportTimeoutMs(timeoutMs);
+    const consent = await resolveToolCallConsent(tool, args);
+    if (signal.aborted) {
+      throw new McpBuiltinToolError("tool_cancelled", `The call to "${tool.descriptor.name}" was cancelled before it started.`);
+    }
+    if (progressToken === void 0) {
+      const result = await stream.call(
+        RPC_METHODS6.toolsCall,
+        {
+          selector: tool.sessionId,
+          name: tool.descriptor.name,
+          args,
+          caller: "mcp",
+          timeoutMs,
+          ...consent ? { consent } : {}
+        },
+        transportTimeoutMs
+      );
+      return result.result;
+    }
+    const progressStream = await openStream({ stateDir: options.stateDir, spawn: options.spawn });
+    try {
+      await progressStream.call(RPC_METHODS6.eventsSubscribe, {
+        sessionSelector: tool.sessionId,
+        kinds: ["tool_call_started", "tool_call_progress"]
+      });
+      let callId;
+      let cancelRequested = signal.aborted;
+      const maybeCancel = () => {
+        if (callId === void 0 || !cancelRequested) {
+          return;
+        }
+        progressStream.call(RPC_METHODS6.toolsCancel, { selector: tool.sessionId, callId, reason: "mcp_client_cancelled" }).catch((error) => {
+          console.error("appduct mcp: failed to cancel an app tool call:", error);
+        });
+      };
+      const onAbort = () => {
+        cancelRequested = true;
+        maybeCancel();
+      };
+      signal.addEventListener("abort", onAbort);
+      const unsubscribe = progressStream.onNotification((payload) => {
+        const event = payload;
+        if (event.kind === "tool_call_started" && callId === void 0) {
+          const data = event.data;
+          if (data.name === tool.descriptor.name) {
+            callId = data.callId;
+            maybeCancel();
+          }
+          return;
+        }
+        if (event.kind === "tool_call_progress" && callId !== void 0) {
+          const data = event.data;
+          if (data.callId === callId) {
+            sendNotification({
+              method: "notifications/progress",
+              params: { progressToken, progress: data.progress ?? 0, message: data.message }
+            }).catch((error) => {
+              console.error("appduct mcp: failed to send a progress notification:", error);
+            });
+          }
+        }
+      });
+      try {
+        const result = await progressStream.call(
+          RPC_METHODS6.toolsCall,
+          {
+            selector: tool.sessionId,
+            name: tool.descriptor.name,
+            args,
+            caller: "mcp",
+            timeoutMs,
+            ...consent ? { consent } : {}
+          },
+          transportTimeoutMs
+        );
+        return result.result;
+      } finally {
+        unsubscribe();
+        signal.removeEventListener("abort", onAbort);
+      }
+    } finally {
+      progressStream.close();
+    }
+  };
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+      tools: [
+        CONNECT_TOOL_DESCRIPTOR,
+        WAIT_FOR_SESSION_TOOL_DESCRIPTOR,
+        LIST_TOOLS_TOOL_DESCRIPTOR,
+        DESCRIBE_TOOL_TOOL_DESCRIPTOR,
+        CALL_TOOL_TOOL_DESCRIPTOR,
+        EVENTS_TOOL_DESCRIPTOR,
+        WAIT_FOR_EVENT_TOOL_DESCRIPTOR
+      ]
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const name = request.params.name;
+    const args = request.params.arguments ?? {};
+    const progressToken = extra._meta?.progressToken;
+    try {
+      if (name === CONNECT_TOOL_NAME) {
+        return toolSuccessContent(
+          await handleConnectTool(args, {
+            call: stream.call,
+            scheme: options.scheme,
+            schemeTried: options.schemeTried,
+            cwd: options.cwd,
+            stateDirRoot: options.stateDirRoot,
+            exec: options.exec,
+            env: options.env
+          })
+        );
+      }
+      if (name === WAIT_FOR_SESSION_TOOL_NAME) {
+        return toolSuccessContent(
+          await handleWaitForSessionTool(args, { stateDir: options.stateDir, spawn: options.spawn })
+        );
+      }
+      if (name === EVENTS_TOOL_NAME) {
+        return toolSuccessContent(await handleEventsTool(args, { call: stream.call }));
+      }
+      if (name === WAIT_FOR_EVENT_TOOL_NAME) {
+        return toolSuccessContent(
+          await handleWaitForEventTool(args, {
+            stateDir: options.stateDir,
+            spawn: options.spawn,
+            progress: progressToken !== void 0 ? { token: progressToken, sendNotification: extra.sendNotification } : void 0
+          })
+        );
+      }
+      if (name === LIST_TOOLS_TOOL_NAME) {
+        return toolSuccessContent(await handleListToolsTool(args, stream.call));
+      }
+      if (name === DESCRIBE_TOOL_TOOL_NAME) {
+        return toolSuccessContent(await handleDescribeToolTool(args, stream.call));
+      }
+      if (name === CALL_TOOL_TOOL_NAME) {
+        const callArgs = parseCallToolArgs(args);
+        const tool = await resolveAppTool(stream.call, callArgs.selector, callArgs.name);
+        return toolSuccessContent(
+          await callAppTool(
+            tool,
+            callArgs.args,
+            callArgs.timeoutMs,
+            progressToken,
+            extra.sendNotification,
+            extra.signal
+          )
+        );
+      }
+      return toolErrorContent(
+        "tool_not_found",
+        `"${name}" is not an Appduct MCP tool. Use ${LIST_TOOLS_TOOL_NAME} to find the app's tools and ${CALL_TOOL_TOOL_NAME} to run one.`
+      );
+    } catch (error) {
+      return toolErrorContentFromError(error);
+    }
+  });
+  server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+      resources: [
+        {
+          uri: SESSIONS_RESOURCE_URI,
+          name: "sessions",
+          description: "Live Appduct device sessions (sessions.list passthrough), as JSON.",
+          mimeType: "application/json"
+        }
+      ]
+    };
+  });
+  server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    if (request.params.uri !== SESSIONS_RESOURCE_URI) {
+      throw new Error(`Unknown resource "${request.params.uri}".`);
+    }
+    const sessions = await stream.call(RPC_METHODS6.sessionsList);
+    return {
+      contents: [{ uri: SESSIONS_RESOURCE_URI, mimeType: "application/json", text: JSON.stringify(sessions) }]
+    };
+  });
+  const close = async () => {
+    stream.close();
+  };
+  return {
+    server,
+    connect: (transport) => server.connect(transport),
+    close
+  };
+};
+
+// src/commands/mcp.ts
+var resolveSchemeForServer = async (context, configScheme, paths) => {
+  try {
+    return await resolveScheme({
+      flagScheme: context.scheme,
+      env: context.schemeEnv,
+      cwd: context.cwd,
+      configScheme,
+      stateConfigPath: paths.configPath,
+      stateDirRoot: paths.root
+    });
+  } catch (error) {
+    const message = error.message;
+    (context.stderr ?? process.stderr).write(
+      `appduct mcp: could not resolve a deep-link scheme: ${message}
+The server is starting anyway; appduct_connect will fail until this is fixed.
+`
+    );
+    return { tried: [`(scheme resolution failed: ${message})`] };
+  }
+};
+var handleMcpCommand = async (context) => {
+  const paths = getStateDirPaths(context.stateDir);
+  const config = await loadConfig(paths);
+  const { scheme, tried } = await resolveSchemeForServer(context, config.scheme, paths);
+  const handle = await createMcpServer({
+    stateDir: context.stateDir,
+    spawn: context.spawn,
+    checkVersion: context.checkVersion,
+    scheme,
+    schemeTried: tried,
+    cwd: context.cwd,
+    stateDirRoot: paths.root,
+    exec: context.exec,
+    env: context.env
+  });
+  let resolveCompletion;
+  const completion = new Promise((resolve2) => {
+    resolveCompletion = resolve2;
+  });
+  let stopped = false;
+  const stop = () => {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    void handle.close().finally(resolveCompletion);
+  };
+  handle.server.onclose = stop;
+  handle.server.onerror = (error) => {
+    console.error("appduct mcp: transport error:", error);
+  };
+  try {
+    await handle.connect(new StdioServerTransport(context.stdin, context.stdout));
+  } catch (error) {
+    await handle.close();
+    throw error;
+  }
+  return {
+    // Never rendered: the dispatcher suppresses the bootstrap render for this command (see the
+    // doc comment above) so stdout carries only MCP protocol frames.
+    result: { ok: true, data: void 0 },
+    completion,
+    stop,
+    handle
+  };
+};
+
+// src/cli/global-flags.ts
+var formatJson = (value, flags) => {
+  return flags.pretty ? JSON.stringify(value, null, 2) : JSON.stringify(value);
+};
+
+// src/output.ts
+import pc from "picocolors";
+import {
+  formatAgentWebSocketUrl,
+  renderToolSignature as renderToolSignature2,
+  summarizeToolDescription as summarizeToolDescription2
+} from "@appduct/shared";
+var renderMetaLines = (meta) => {
+  if (!meta) {
+    return [];
+  }
+  return [
+    "Meta",
+    `  Command: ${meta.command}`,
+    `  Timestamp: ${meta.timestamp}`,
+    ...typeof meta.duration_ms === "number" ? [`  Duration: ${meta.duration_ms} ms`] : []
+  ];
+};
+var formatScalar = (value, flags) => {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  if (value === null || value === void 0) {
+    return "null";
+  }
+  return formatJson(value, flags);
+};
+var renderFields = (title, fields, flags) => {
+  const visibleFields = fields.filter(([, value]) => value !== void 0);
+  if (visibleFields.length === 0) {
+    return [];
+  }
+  const width = Math.max(...visibleFields.map(([label]) => label.length));
+  return [
+    title,
+    ...visibleFields.map(([label, value]) => `  ${label.padEnd(width)}  ${formatScalar(value, flags)}`)
+  ];
+};
+var formatAge = (fromIso, toIso) => {
+  const elapsedMs = Math.max(0, new Date(toIso).getTime() - new Date(fromIso).getTime());
+  const elapsedSeconds = Math.floor(elapsedMs / 1e3);
+  if (elapsedSeconds < 60) {
+    return `${elapsedSeconds}s`;
+  }
+  const elapsedMinutes = Math.floor(elapsedSeconds / 60);
+  if (elapsedMinutes < 60) {
+    return `${elapsedMinutes}m`;
+  }
+  const elapsedHours = Math.floor(elapsedMinutes / 60);
+  if (elapsedHours < 24) {
+    return `${elapsedHours}h`;
+  }
+  return `${Math.floor(elapsedHours / 24)}d`;
+};
+var formatDevice = (device) => {
+  const parts = [device.manufacturer, device.model].filter((part) => Boolean(part));
+  const label = parts.length > 0 ? parts.join(" ") : "unknown device";
+  return device.os ? `${label} (${device.os})` : label;
+};
+var renderLsData = (colors, data, now) => {
+  if (data.length === 0) {
+    return [colors.dim("Sessions"), "  No Appduct sessions are registered."];
+  }
+  const nowIso = now.toISOString();
+  const headers = ["Alias", "State", "Device", "Tools", "Age"];
+  const rows = data.map((session) => [
+    session.alias,
+    session.state,
+    formatDevice(session.device),
+    String(session.toolCount),
+    formatAge(session.claimedAt ?? session.createdAt, nowIso)
+  ]);
+  const widths = headers.map(
+    (header, index) => Math.max(header.length, ...rows.map((row) => row[index].length))
+  );
+  return [
+    colors.green("Sessions"),
+    `  ${headers.map((header, index) => header.padEnd(widths[index])).join("  ")}`,
+    ...rows.map((row) => `  ${row.map((cell, index) => cell.padEnd(widths[index])).join("  ")}`)
+  ];
+};
+var isToolsListing = (data) => {
+  return typeof data === "object" && data !== null && Array.isArray(data.tools);
+};
+var isToolGroupsListing = (data) => {
+  return typeof data === "object" && data !== null && Array.isArray(data.groups) && !Array.isArray(data.tools);
+};
+var UNGROUPED_LABEL = "(ungrouped)";
+var MAX_FOOTER_GROUPS = 10;
+var hasAnyGroup = (groups) => {
+  return (groups ?? []).some((entry) => entry.group !== null);
+};
+var topLevelGroups = (groups) => {
+  return (groups ?? []).filter((entry) => entry.group !== null && !entry.group.includes("/"));
+};
+var renderEmptyToolsLine = (data) => {
+  if (data.total > 0) {
+    return `  No tools at offset ${data.offset ?? 0}; ${data.total} matching tool${data.total === 1 ? "" : "s"} in total.`;
+  }
+  if (data.group !== void 0) {
+    const match = data.filter === void 0 ? "" : ` match ${JSON.stringify(data.filter)}`;
+    return `  No tools in group ${JSON.stringify(data.group)}${match}. Run \`appduct tools --groups\` to see the session's groups.`;
+  }
+  return data.filter === void 0 ? "  No tools registered." : `  No tools match ${JSON.stringify(data.filter)}.`;
+};
+var renderGroupHint = (data) => {
+  if (data.group !== void 0 || !hasAnyGroup(data.groups)) {
+    return void 0;
+  }
+  const top = topLevelGroups(data.groups);
+  const named = top.slice(0, MAX_FOOTER_GROUPS).map((entry) => `${entry.group} ${entry.total}`);
+  const more = top.length > MAX_FOOTER_GROUPS ? `, ... ${top.length - MAX_FOOTER_GROUPS} more; see --groups` : "";
+  return `--group <name> (groups: ${named.join(", ")}${more})`;
+};
+var renderTruncationLine = (data) => {
+  if (data.tools.length >= data.total) {
+    return [];
+  }
+  const groupHint = renderGroupHint(data);
+  const narrow = groupHint === void 0 ? "--filter <text> or" : `${groupHint} or --filter <text>, or`;
+  return [
+    "",
+    `Showing ${data.tools.length} of ${data.total} tools (offset ${data.offset ?? 0}). Narrow with ${narrow} page with --offset <n>.`
+  ];
+};
+var renderToolSummaryLines = (tool, indent) => {
+  const tag = tool.policy === "allow" ? "" : `  [${tool.policy}]`;
+  return [`${indent}${renderToolSignature2(tool)}${tag}`, `${indent}  ${summarizeToolDescription2(tool.description)}`];
+};
+var renderGroupedToolLines = (colors, tools) => {
+  const byGroup = /* @__PURE__ */ new Map();
+  for (const tool of tools) {
+    const key = tool.group ?? null;
+    const bucket = byGroup.get(key);
+    if (bucket) {
+      bucket.push(tool);
+    } else {
+      byGroup.set(key, [tool]);
+    }
+  }
+  const tops = /* @__PURE__ */ new Map();
+  for (const key of byGroup.keys()) {
+    if (key === null) {
+      continue;
+    }
+    const slash = key.indexOf("/");
+    const top = slash === -1 ? key : key.slice(0, slash);
+    const subs = tops.get(top) ?? [];
+    if (slash !== -1) {
+      subs.push(key);
+    }
+    tops.set(top, subs);
+  }
+  const byCodePoint = (a, b) => a < b ? -1 : a > b ? 1 : 0;
+  const lines = [];
+  for (const top of [...tops.keys()].sort(byCodePoint)) {
+    lines.push(`  ${colors.cyan(top)}`);
+    lines.push(...(byGroup.get(top) ?? []).flatMap((tool) => renderToolSummaryLines(tool, "    ")));
+    for (const sub of tops.get(top).sort(byCodePoint)) {
+      lines.push(`    ${colors.cyan(sub)}`);
+      lines.push(...byGroup.get(sub).flatMap((tool) => renderToolSummaryLines(tool, "      ")));
+    }
+  }
+  const ungrouped = byGroup.get(null);
+  if (ungrouped) {
+    lines.push(`  ${colors.cyan(UNGROUPED_LABEL)}`);
+    lines.push(...ungrouped.flatMap((tool) => renderToolSummaryLines(tool, "    ")));
+  }
+  return lines;
+};
+var renderToolsTitle = (colors, data) => {
+  return colors.green(data.group === void 0 ? "Tools" : `Tools in group ${data.group}`);
+};
+var renderToolSummaryTable = (colors, data) => {
+  if (data.tools.length === 0) {
+    return [renderToolsTitle(colors, data), renderEmptyToolsLine(data)];
+  }
+  const grouped = data.group === void 0 && hasAnyGroup(data.groups);
+  return [
+    renderToolsTitle(colors, data),
+    ...grouped ? renderGroupedToolLines(colors, data.tools) : data.tools.flatMap((tool) => renderToolSummaryLines(tool, "  ")),
+    ...renderTruncationLine(data),
+    "",
+    "Run `appduct tools <name>` for a tool's full schema."
+  ];
+};
+var renderToolDetail = (colors, tool, flags) => {
+  return renderFields(
+    colors.green(`Tool: ${tool.name}`),
+    [
+      ["Signature", renderToolSignature2(tool)],
+      ["Description", tool.description],
+      ["Input schema", tool.input_schema],
+      ["Output schema", tool.output_schema],
+      // `?? undefined` keeps an ungrouped tool's row hidden rather than printing a bare "null":
+      // `renderFields` drops undefined rows, and the machine form's `null` is for consumers, not
+      // for a human scanning one tool's schema.
+      ["Group", tool.group ?? void 0],
+      ["Annotations", tool.annotations],
+      // Only rendered for a tool that declares one; `renderFields` drops undefined rows, so a
+      // tool on the daemon's default deadline shows no line at all rather than a misleading
+      // "10000".
+      ["Timeout (ms)", tool.timeout_ms]
+    ],
+    flags
+  );
+};
+var renderToolsFullListing = (colors, data, flags) => {
+  if (data.tools.length === 0) {
+    return [renderToolsTitle(colors, data), renderEmptyToolsLine(data)];
+  }
+  return [
+    ...data.tools.flatMap((tool, index) => [
+      ...index > 0 ? [""] : [],
+      ...renderToolDetail(colors, tool, flags)
+    ]),
+    ...renderTruncationLine(data)
+  ];
+};
+var renderToolGroups = (colors, data) => {
+  if (data.groups.length === 0) {
+    return [colors.green("Groups"), "  No tools registered."];
+  }
+  const label = (entry) => {
+    if (entry.group === null) {
+      return UNGROUPED_LABEL;
+    }
+    return entry.group.includes("/") ? `  ${entry.group}` : entry.group;
+  };
+  const width = Math.max(...data.groups.map((entry) => label(entry).length));
+  const countWidth = Math.max(...data.groups.map((entry) => String(entry.total).length));
+  return [
+    colors.green("Groups"),
+    ...data.groups.map((entry) => `  ${label(entry).padEnd(width)}  ${String(entry.total).padStart(countWidth)}`),
+    "",
+    `${data.total} tool${data.total === 1 ? "" : "s"} in total. ` + (hasAnyGroup(data.groups) ? "Run `appduct tools --group <name>` to list one group's tools." : "No tool declares a group.")
+  ];
+};
+var renderToolsData = (colors, data, flags, full) => {
+  if (isToolGroupsListing(data)) {
+    return renderToolGroups(colors, data);
+  }
+  if (!isToolsListing(data)) {
+    return renderToolDetail(colors, data, flags);
+  }
+  return full ? renderToolsFullListing(colors, data, flags) : renderToolSummaryTable(colors, data);
+};
+var renderInvokeData = (colors, data, flags) => {
+  return [colors.green("Result"), formatScalar(data, flags)];
+};
+var renderLinkData = (colors, data, flags, qr) => {
+  const lines = [
+    colors.green("Link Created"),
+    ...renderFields(
+      "Link",
+      [
+        ["Session", data.sessionId],
+        ["Deep link", data.deepLink],
+        ["Endpoint", formatAgentWebSocketUrl(data.endpoint)],
+        ["Pin", data.pin],
+        ["Expires", new Date(data.expiresAt * 1e3).toISOString()],
+        ["Delivered", data.delivered ? `yes (${data.target})` : void 0]
+      ],
+      flags
+    )
+  ];
+  if (qr) {
+    lines.push("", "QR", renderQrToTerminal(data.deepLink));
+  }
+  return lines;
+};
+var renderRevokeData = (colors, _data) => {
+  return [colors.green("Session Revoked")];
+};
+var renderKeygenData = (colors, data, flags) => {
+  return [
+    colors.green("Key Ready"),
+    ...renderFields(
+      "Key",
+      [
+        ["Path", data.path],
+        ["Fingerprint", data.pin]
+      ],
+      flags
+    )
+  ];
+};
+var renderInitData = (colors, data, flags) => {
+  const snippet = JSON.stringify(
+    { mcpServers: { appduct: data.mcpServerEntry } },
+    null,
+    2
+  );
+  return [
+    colors.green(data.changed ? "Project Initialized" : "Project Already Initialized"),
+    ...renderFields(
+      "Config",
+      [
+        ["Path", data.path],
+        ["Scheme", data.scheme],
+        ["Source", data.source],
+        // Only present for a scheme discovery read off a static project file (app.json, or one of
+        // the native Android/iOS probes) — names the exact file/key, not just which platform.
+        ["Read from", data.origin],
+        ["Written", data.changed ? data.created ? "created" : "updated" : "unchanged"]
+      ],
+      flags
+    ),
+    ...data.note === void 0 ? [] : ["", colors.yellow(`Note: ${data.note}`)],
+    "",
+    "MCP server entry",
+    ...snippet.split("\n").map((line) => `  ${line}`),
+    "",
+    "Next",
+    ...data.nextSteps.map((step, index) => `  ${index + 1}. ${step}`)
+  ];
+};
+var renderDaemonRunData = (colors, data, flags) => {
+  return [
+    colors.green("Daemon Running"),
+    ...renderFields(
+      "Daemon",
+      [
+        ["PID", data.daemon.pid],
+        ["State dir", data.daemon.state_dir],
+        ["Socket", data.daemon.socket_path]
+      ],
+      flags
+    )
+  ];
+};
+var renderDaemonStartData = (colors, data, flags) => {
+  return [
+    colors.green("Daemon Started"),
+    ...renderFields(
+      "Daemon",
+      [
+        ["PID", data.daemon.pid],
+        ["WSS port", data.daemon.wss_port],
+        ["Started at", data.daemon.started_at]
+      ],
+      flags
+    )
+  ];
+};
+var renderDaemonStopData = (colors, data, flags) => {
+  return [
+    colors.green("Daemon Stopped"),
+    ...renderFields("Daemon", [["Method", data.daemon.method]], flags)
+  ];
+};
+var formatByteSize = (bytes) => {
+  const units = ["B", "KiB", "MiB", "GiB", "TiB"];
+  let value = bytes;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit += 1;
+  }
+  return `${unit === 0 ? value : value.toFixed(1)} ${units[unit]}`;
+};
+var renderDaemonStatusData = (colors, data, flags) => {
+  return [
+    colors.green("Daemon Status"),
+    ...renderFields(
+      "Daemon",
+      [
+        ["Version", data.daemon.version],
+        ["PID", data.daemon.pid],
+        ["Started at", data.daemon.started_at],
+        ["WSS port", data.daemon.wss_port],
+        ["Pinned keys", data.daemon.pinned_keys.length],
+        ["Sessions", data.daemon.session_count]
+      ],
+      flags
+    ),
+    "",
+    ...renderFields(
+      "Policy",
+      [
+        ["Default", data.policy.default],
+        ["Destructive", data.policy.destructive],
+        ["Overrides", data.policy.tools ? Object.keys(data.policy.tools).length : 0]
+      ],
+      flags
+    ),
+    "",
+    // The retention rows drop out entirely against a daemon that predates them (`renderFields`
+    // skips `undefined`), rather than printing "undefined" or an invented zero.
+    ...renderFields(
+      "Audit",
+      [
+        ["Path", data.audit.path],
+        ["Retention", data.audit.retention_days === void 0 ? void 0 : `${data.audit.retention_days} days`],
+        ["Files", data.audit.files],
+        ["Size", data.audit.bytes === void 0 ? void 0 : formatByteSize(data.audit.bytes)],
+        ["Failed writes", data.audit.failed_writes],
+        ["Failed prunes", data.audit.failed_prunes]
+      ],
+      flags
+    ),
+    // Version drift (issue #30) is the one thing here an operator has to act on, so it goes last
+    // — the line still on screen after the block scrolls — and in yellow, not a quiet field row.
+    ...data.warning ? ["", colors.yellow(`Warning: ${data.warning}`)] : []
+  ];
+};
+var renderDoctorData = (colors, data, flags) => {
+  return [
+    data.present ? colors.green("Appduct Present") : colors.yellow("Appduct Absent"),
+    ...renderFields(
+      "Artifact",
+      [
+        ["Path", data.artifact],
+        ["Platform", data.platform],
+        ["Format", data.format],
+        ["Present", data.present],
+        ["Signals", data.signals.length > 0 ? data.signals.join(", ") : "none"],
+        ["Assertion", data.assertion ? `${data.assertion.expected} (holds)` : void 0]
+      ],
+      flags
+    )
+  ];
+};
+var renderSuccessData = (colors, command, data, options) => {
+  const flags = options.flags;
+  switch (command) {
+    case "init":
+      return renderInitData(colors, data, flags);
+    case "keygen":
+      return renderKeygenData(colors, data, flags);
+    case "link":
+      return renderLinkData(colors, data, flags, options.qr);
+    case "ls":
+      return renderLsData(colors, data, options.now ?? /* @__PURE__ */ new Date());
+    case "tools":
+      return renderToolsData(colors, data, flags, options.full);
+    case "invoke":
+      return renderInvokeData(colors, data, flags);
+    case "revoke":
+      return renderRevokeData(colors, data);
+    case "daemon run":
+      return renderDaemonRunData(colors, data, flags);
+    case "daemon start":
+      return renderDaemonStartData(colors, data, flags);
+    case "daemon stop":
+      return renderDaemonStopData(colors, data, flags);
+    case "daemon status":
+      return renderDaemonStatusData(colors, data, flags);
+    case "doctor":
+      return renderDoctorData(colors, data, flags);
+    default:
+      return [colors.green("Command Complete"), formatJson(data, flags)];
+  }
+};
+var renderHumanError = (colors, error, flags, meta) => {
+  return [
+    colors.red("Command Failed"),
+    ...renderFields(
+      "Error",
+      [
+        ["Type", error.type],
+        ["Message", error.message],
+        ["Details", error.details]
+      ],
+      flags
+    ),
+    ...meta ? ["", ...renderMetaLines(meta)] : []
+  ].join("\n");
+};
+var renderResult = (result, options) => {
+  if (options.flags.json) {
+    return {
+      stdout: `${formatJson(result, options.flags)}
+`
+    };
+  }
+  const colors = pc.createColors(options.flags.color);
+  if (!result.ok) {
+    return {
+      stderr: `${renderHumanError(colors, result.error, options.flags, result.meta)}
+`
+    };
+  }
+  const lines = [
+    ...renderSuccessData(colors, options.command, result.data, options),
+    "",
+    ...renderMetaLines(result.meta)
+  ].filter((line, index, collection) => {
+    if (line !== "") {
+      return true;
+    }
+    return index > 0 && collection[index - 1] !== "" && index < collection.length - 1;
+  });
+  return {
+    stdout: `${lines.join("\n")}
+`
+  };
+};
+
+// src/cli/envelope.ts
+var createCommandMeta = (command, startedAt, finishedAt) => {
+  return {
+    command,
+    timestamp: finishedAt.toISOString(),
+    duration_ms: finishedAt.getTime() - startedAt.getTime()
+  };
+};
+var finalizeResult = (result, timing, flags) => {
+  if (!flags.verbose) {
+    return result;
+  }
+  return {
+    ...result,
+    meta: createCommandMeta(timing.command, timing.startedAt, timing.finishedAt)
+  };
+};
+
+// src/cli/runner.ts
+var writeRenderedOutput = (rendered, writers) => {
+  if (rendered.stdout) {
+    writers.stdout.write(rendered.stdout);
+  }
+  if (rendered.stderr) {
+    writers.stderr.write(rendered.stderr);
+  }
+};
+var executeHostedCommand = async (command, handler, env, reporter) => {
+  const startedAt = env.clock.now();
+  let renderedSuccess = false;
+  try {
+    const hosted = await handler();
+    const finishedAt = env.clock.now();
+    const finalized = finalizeResult(hosted.result, { command, startedAt, finishedAt }, env.flags);
+    const shouldRenderBootstrap = !reporter || reporter.kind === "plain";
+    if (shouldRenderBootstrap) {
+      writeRenderedOutput(
+        renderResult(finalized, { command, flags: env.flags, now: finishedAt }),
+        env
+      );
+      renderedSuccess = true;
+    }
+    let resolved = false;
+    const stop = () => {
+      if (resolved) {
+        return;
+      }
+      resolved = true;
+      hosted.stop();
+    };
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    try {
+      await hosted.completion;
+    } finally {
+      resolved = true;
+      process.off("SIGINT", stop);
+      process.off("SIGTERM", stop);
+      reporter?.dispose();
+    }
+    return 0;
+  } catch (error) {
+    reporter?.dispose();
+    const finishedAt = env.clock.now();
+    const cliError = toCliError(error);
+    const result = { ok: false, error: cliError };
+    const finalized = finalizeResult(result, { command, startedAt, finishedAt }, env.flags);
+    if (renderedSuccess && env.flags.json) {
+      env.stderr.write(`${formatJson(finalized, env.flags)}
+`);
+      return getExitCodeForError(error);
+    }
+    writeRenderedOutput(
+      renderResult(finalized, { command, flags: env.flags, now: finishedAt }),
+      env
+    );
+    return getExitCodeForError(error);
+  }
+};
+
+// src/cli/router.ts
+var commandName = (context) => {
+  return context.path.join(" ");
+};
+
+// src/cli/version-guard.ts
+var versionCheckOptions = async (context, onWarning = context.versionCheck.warn) => {
+  return {
+    clientVersion: context.versionCheck.clientVersion,
+    forceRestart: await context.versionCheck.forceRestart(),
+    onWarning
+  };
+};
+
+// src/cli/routes/mcp.ts
+var route = async (context) => {
+  const { options, stateDir, env } = context;
+  return executeHostedCommand(
+    commandName(context),
+    // Unlike every other command the check is threaded into the server itself, not run ahead
+    // of it: the MCP server is long-lived and auto-spawns its own daemon, so the check belongs
+    // on the startup stream that establishes the connection it keeps (ARCHITECTURE.md §9).
+    // The notice always goes to stderr here, `--json` or not: stdout carries MCP protocol
+    // frames, and stderr is this server's only log channel (ARCHITECTURE.md §9).
+    async () => handleMcpCommand({
+      stateDir,
+      scheme: typeof options.scheme === "string" ? options.scheme : void 0,
+      checkVersion: await versionCheckOptions(context, (message) => void env.stderr.write(message))
+    }),
+    env,
+    {
+      kind: "interactive",
+      onEvent: () => {
+      },
+      dispose: () => {
+      }
+    }
+  );
+};
+export {
+  route
+};