@dev.sail.money/sailor 1.3.0-206 → 1.3.0-209

package/packages/cli/dist/index.cjs

@@ -22626,7 +22626,7 @@ var require_websocket = __commonJS({
     var EventEmitter = require("events");
     var https = require("https");
     var http2 = require("http");
-    var net2 = require("net");
+    var net3 = require("net");
     var tls = require("tls");
     var { randomBytes: randomBytes4, createHash } = require("crypto");
     var { Duplex, Readable } = require("stream");
@@ -23360,12 +23360,12 @@ var require_websocket = __commonJS({
     }
     function netConnect(options) {
       options.path = options.socketPath;
-      return net2.connect(options);
+      return net3.connect(options);
     }
     function tlsConnect(options) {
       options.path = void 0;
       if (!options.servername && options.servername !== "") {
-        options.servername = net2.isIP(options.host) ? "" : options.host;
+        options.servername = net3.isIP(options.host) ? "" : options.host;
       }
       return tls.connect(options);
     }
@@ -33756,7 +33756,7 @@ var require_websocket2 = __commonJS({
     var EventEmitter = require("events");
     var https = require("https");
     var http2 = require("http");
-    var net2 = require("net");
+    var net3 = require("net");
     var tls = require("tls");
     var { randomBytes: randomBytes4, createHash } = require("crypto");
     var { Duplex, Readable } = require("stream");
@@ -34500,12 +34500,12 @@ var require_websocket2 = __commonJS({
     }
     function netConnect(options) {
       options.path = options.socketPath;
-      return net2.connect(options);
+      return net3.connect(options);
     }
     function tlsConnect(options) {
       options.path = void 0;
       if (!options.servername && options.servername !== "") {
-        options.servername = net2.isIP(options.host) ? "" : options.host;
+        options.servername = net3.isIP(options.host) ? "" : options.host;
       }
       return tls.connect(options);
     }
@@ -37445,18 +37445,12 @@ var LocalKeyring = class _LocalKeyring {
       this.account = account2;
       this.address = account2.address;
       this.privateKey = options.privateKey;
-    } else if (options.type === "mnemonic") {
+    } else {
       const account2 = mnemonicToAccount(options.mnemonic, options.derivationPath ? { path: options.derivationPath } : void 0);
       this.account = account2;
       this.address = account2.address;
-    } else {
-      throw new Error("keystore decryption not implemented \u2014 use type: 'privateKey' or type: 'mnemonic' instead");
     }
   }
-  /** Returns a lightweight signer stub for read-only contexts where the key is not available. */
-  static fromAddress(address) {
-    return { address };
-  }
   /** Generates a brand-new keyring backed by a random private key. */
   static generate() {
     return new _LocalKeyring({ type: "privateKey", privateKey: generatePrivateKey() });
@@ -38497,15 +38491,58 @@ function upsertAccountInList(account2, name, baseSailDir = sailDir()) {
 }
 
 // src/signing/client.ts
-var import_node_fs6 = require("node:fs");
+var import_node_fs7 = require("node:fs");
 var import_node_path5 = require("node:path");
 
 // src/signing/server.ts
 var import_node_crypto2 = require("node:crypto");
-var import_node_fs5 = require("node:fs");
+var import_node_fs6 = require("node:fs");
 var import_node_http = require("node:http");
-var import_node_net = require("node:net");
 var import_node_path4 = require("node:path");
+
+// src/lib/process.ts
+var import_node_fs5 = __toESM(require("node:fs"), 1);
+var import_node_net = __toESM(require("node:net"), 1);
+function agentPidPath(chainId) {
+  return chainId != null ? sailPath(`agent-${chainId}.pid`) : sailPath("agent.pid");
+}
+function writeAgentPid(chainId) {
+  import_node_fs5.default.mkdirSync(sailPath(), { recursive: true });
+  import_node_fs5.default.writeFileSync(agentPidPath(chainId), `${process.pid}
+`);
+}
+function clearAgentPid(chainId) {
+  try {
+    import_node_fs5.default.rmSync(agentPidPath(chainId));
+  } catch {
+  }
+}
+function readAgentPid(chainId) {
+  try {
+    const pid = Number.parseInt(import_node_fs5.default.readFileSync(agentPidPath(chainId), "utf-8").trim(), 10);
+    return Number.isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === "EPERM";
+  }
+}
+function findFreePort(from14) {
+  return new Promise((resolve3, reject) => {
+    const server = import_node_net.default.createServer();
+    server.unref();
+    server.on("error", () => findFreePort(from14 + 1).then(resolve3, reject));
+    server.listen(from14, "127.0.0.1", () => server.close(() => resolve3(from14)));
+  });
+}
+
+// src/signing/server.ts
 init_esm2();
 
 // ../../node_modules/.pnpm/ws@8.21.0_bufferutil@4.1.0_utf-8-validate@5.0.10/node_modules/ws/wrapper.mjs
@@ -38545,7 +38582,7 @@ function findUiDist() {
     (0, import_node_path4.join)(process.cwd(), "..", "ui", "dist")
   ];
   for (const c of candidates) {
-    if ((0, import_node_fs5.existsSync)((0, import_node_path4.join)(c, "index.html"))) return c;
+    if ((0, import_node_fs6.existsSync)((0, import_node_path4.join)(c, "index.html"))) return c;
   }
   return null;
 }
@@ -38593,7 +38630,7 @@ var SigningServer = class {
     return this.httpServer?.listening ?? false;
   }
   async start() {
-    this.port = await findAvailablePort(this.port);
+    this.port = await findFreePort(this.port);
     this._url = `http://localhost:${this.port}`;
     this.requestSecret = (0, import_node_crypto2.randomBytes)(16).toString("hex");
     const http2 = (0, import_node_http.createServer)((req, res) => this.handleHttp(req, res));
@@ -38773,13 +38810,13 @@ var SigningServer = class {
       const path11 = this.sailFile("config.json");
       let config = {};
       try {
-        config = JSON.parse((0, import_node_fs5.readFileSync)(path11, "utf-8"));
+        config = JSON.parse((0, import_node_fs6.readFileSync)(path11, "utf-8"));
       } catch {
       }
       if (Number(config.chainId) === Number(chainId)) return;
       config.chainId = Number(chainId);
-      (0, import_node_fs5.mkdirSync)(this.sailFile(), { recursive: true });
-      (0, import_node_fs5.writeFileSync)(path11, `${JSON.stringify(config, null, 2)}
+      (0, import_node_fs6.mkdirSync)(this.sailFile(), { recursive: true });
+      (0, import_node_fs6.writeFileSync)(path11, `${JSON.stringify(config, null, 2)}
 `);
     } catch {
     }
@@ -38787,7 +38824,7 @@ var SigningServer = class {
   /** Stream a JSON file back, or a fallback body when it is missing/invalid. */
   sendJsonFile(res, filePath, fallback2) {
     try {
-      const raw = (0, import_node_fs5.readFileSync)(filePath, "utf-8");
+      const raw = (0, import_node_fs6.readFileSync)(filePath, "utf-8");
       JSON.parse(raw);
       res.writeHead(200, { "Content-Type": "application/json" });
       res.end(raw);
@@ -38854,8 +38891,8 @@ var SigningServer = class {
       };
       const baseSailDir = this.sailFile();
       upsertAccountInList(record, void 0, baseSailDir);
-      (0, import_node_fs5.mkdirSync)(baseSailDir, { recursive: true });
-      (0, import_node_fs5.writeFileSync)(this.sailFile("account.json"), `${JSON.stringify(record, null, 2)}
+      (0, import_node_fs6.mkdirSync)(baseSailDir, { recursive: true });
+      (0, import_node_fs6.writeFileSync)(this.sailFile("account.json"), `${JSON.stringify(record, null, 2)}
 `);
       this.syncConfigChainId(chainId);
       res.writeHead(200, { "Content-Type": "application/json" });
@@ -38870,12 +38907,12 @@ var SigningServer = class {
     res.writeHead(200, { "Content-Type": "application/json" });
     let active = null;
     try {
-      active = JSON.parse((0, import_node_fs5.readFileSync)(this.sailFile("account.json"), "utf-8")).safe;
+      active = JSON.parse((0, import_node_fs6.readFileSync)(this.sailFile("account.json"), "utf-8")).safe;
     } catch {
     }
     try {
       const accounts = JSON.parse(
-        (0, import_node_fs5.readFileSync)(this.sailFile("state", "accounts.json"), "utf-8")
+        (0, import_node_fs6.readFileSync)(this.sailFile("state", "accounts.json"), "utf-8")
       );
       res.end(
         JSON.stringify(
@@ -38888,7 +38925,7 @@ var SigningServer = class {
     } catch {
       try {
         const a = JSON.parse(
-          (0, import_node_fs5.readFileSync)(this.sailFile("account.json"), "utf-8")
+          (0, import_node_fs6.readFileSync)(this.sailFile("account.json"), "utf-8")
         );
         res.end(JSON.stringify([{ ...a, name: "My SMA", active: true, addedAt: null }]));
       } catch {
@@ -39011,16 +39048,16 @@ var SigningServer = class {
         res.end();
         return;
       }
-      if ((0, import_node_fs5.existsSync)(filePath)) {
+      if ((0, import_node_fs6.existsSync)(filePath)) {
         const mime = MIME[(0, import_node_path4.extname)(filePath)] ?? "application/octet-stream";
         res.writeHead(200, { "Content-Type": mime });
-        res.end((0, import_node_fs5.readFileSync)(filePath));
+        res.end((0, import_node_fs6.readFileSync)(filePath));
         return;
       }
       const indexHtml = (0, import_node_path4.join)(this.uiDist, "index.html");
-      if ((0, import_node_fs5.existsSync)(indexHtml)) {
+      if ((0, import_node_fs6.existsSync)(indexHtml)) {
         res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
-        res.end((0, import_node_fs5.readFileSync)(indexHtml));
+        res.end((0, import_node_fs6.readFileSync)(indexHtml));
         return;
       }
     }
@@ -39107,15 +39144,15 @@ var SigningServer = class {
   }
   writeRuntimeState() {
     const path11 = (0, import_node_path4.join)(this.runtimeDir, SERVER_STATE_FILE);
-    if ((0, import_node_fs5.existsSync)(path11)) {
+    if ((0, import_node_fs6.existsSync)(path11)) {
       try {
-        const existing = JSON.parse((0, import_node_fs5.readFileSync)(path11, "utf8"));
-        if (existing.pid != null && existing.pid !== process.pid && pidAlive(existing.pid)) return;
+        const existing = JSON.parse((0, import_node_fs6.readFileSync)(path11, "utf8"));
+        if (existing.pid != null && existing.pid !== process.pid && isProcessAlive(existing.pid)) return;
       } catch {
       }
     }
-    if (!(0, import_node_fs5.existsSync)(this.runtimeDir)) (0, import_node_fs5.mkdirSync)(this.runtimeDir, { recursive: true });
-    (0, import_node_fs5.writeFileSync)(
+    if (!(0, import_node_fs6.existsSync)(this.runtimeDir)) (0, import_node_fs6.mkdirSync)(this.runtimeDir, { recursive: true });
+    (0, import_node_fs6.writeFileSync)(
       (0, import_node_path4.join)(this.runtimeDir, SERVER_STATE_FILE),
       JSON.stringify(
         {
@@ -39134,43 +39171,25 @@ var SigningServer = class {
   removeRuntimeState() {
     const path11 = (0, import_node_path4.join)(this.runtimeDir, SERVER_STATE_FILE);
     try {
-      if (!(0, import_node_fs5.existsSync)(path11)) return;
-      const state = JSON.parse((0, import_node_fs5.readFileSync)(path11, "utf8"));
+      if (!(0, import_node_fs6.existsSync)(path11)) return;
+      const state = JSON.parse((0, import_node_fs6.readFileSync)(path11, "utf8"));
       if (state.pid != null && state.pid !== process.pid) return;
-      (0, import_node_fs5.unlinkSync)(path11);
+      (0, import_node_fs6.unlinkSync)(path11);
     } catch {
     }
   }
 };
-function pidAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch (err) {
-    return err.code === "EPERM";
-  }
-}
 function reapStaleRuntimeState(projectRoot = process.cwd()) {
   const path11 = (0, import_node_path4.join)(projectRoot, RUNTIME_SUBDIR, SERVER_STATE_FILE);
   try {
-    if (!(0, import_node_fs5.existsSync)(path11)) return;
-    const state = JSON.parse((0, import_node_fs5.readFileSync)(path11, "utf8"));
-    if (state.pid != null && state.pid !== process.pid && !pidAlive(state.pid)) {
-      (0, import_node_fs5.unlinkSync)(path11);
+    if (!(0, import_node_fs6.existsSync)(path11)) return;
+    const state = JSON.parse((0, import_node_fs6.readFileSync)(path11, "utf8"));
+    if (state.pid != null && state.pid !== process.pid && !isProcessAlive(state.pid)) {
+      (0, import_node_fs6.unlinkSync)(path11);
     }
   } catch {
   }
 }
-async function findAvailablePort(startPort) {
-  return new Promise((res) => {
-    const probe = (0, import_node_net.createServer)();
-    probe.listen(startPort, "127.0.0.1", () => {
-      const addr = probe.address();
-      probe.close(() => res(addr.port));
-    });
-    probe.on("error", () => res(findAvailablePort(startPort + 1)));
-  });
-}
 
 // src/signing/client.ts
 var RUNTIME_SERVER_FILE = (0, import_node_path5.join)(".sail", "runtime", "server.json");
@@ -39252,14 +39271,14 @@ function toLoopbackIPv4(url) {
 }
 function readRuntimeServerState(projectRoot) {
   const file = (0, import_node_path5.join)(projectRoot, RUNTIME_SERVER_FILE);
-  if (!(0, import_node_fs6.existsSync)(file)) return null;
+  if (!(0, import_node_fs7.existsSync)(file)) return null;
   try {
-    return JSON.parse((0, import_node_fs6.readFileSync)(file, "utf8"));
+    return JSON.parse((0, import_node_fs7.readFileSync)(file, "utf8"));
   } catch {
     return null;
   }
 }
-function signingPageUrl(_channel, dashboardPort) {
+function signingPageUrl(dashboardPort) {
   return `http://localhost:${dashboardPort}/#/station`;
 }
 async function discoverDaemon(projectRoot = process.cwd()) {
@@ -39530,7 +39549,7 @@ Deploying SMA on ${getChainById(targetChainId).name} (chain ${targetChainId})\u2
   const channel = await createSigningChannel(process.cwd());
   try {
     await channel.start();
-    const stationUrl = signingPageUrl(channel, projectPort(process.cwd()));
+    const stationUrl = signingPageUrl(projectPort(process.cwd()));
     if (json) {
       console.log(
         JSON.stringify(
@@ -39667,100 +39686,6 @@ function emit(json, human, payload) {
 
 // src/lib/project.ts
 init_esm2();
-
-// src/lib/keys.ts
-init_esm2();
-var ROLES = ["manager", "permissionSigner"];
-function normalizeRole(input) {
-  const n = input.trim().toLowerCase().replace(/[-_\s]/g, "");
-  if (n === "manager" || n === "mgr" || n === "m" || n === "agent" || n === "agentwallet") {
-    return "manager";
-  }
-  if (n === "permissionsigner" || n === "signer" || n === "ps" || n === "permission" || n === "mandatesigner" || n === "mandate") {
-    return "permissionSigner";
-  }
-  return null;
-}
-function roleLabel(role) {
-  return role === "manager" ? "agent wallet" : "mandate signer";
-}
-function safeHex(safe) {
-  return safe.toLowerCase().replace(/^0x/, "").replace(/[^0-9a-f]/g, "");
-}
-function keyPath(role, safe) {
-  if (safe) {
-    return sailPath("keys", `${role}-0x${safeHex(safe)}.json`);
-  }
-  return sailPath("keys", `${role}.json`);
-}
-function legacyKeyPath(role, safe) {
-  return sailPath("keys", `${role}-${safeHex(safe)}.json`);
-}
-function resolveKeyPath(role, safe) {
-  if (safe) {
-    const perSma = keyPath(role, safe);
-    if (fileExists(perSma)) return perSma;
-    const legacy = legacyKeyPath(role, safe);
-    if (fileExists(legacy)) return legacy;
-  }
-  return keyPath(role);
-}
-function keyExists(role, safe) {
-  return fileExists(resolveKeyPath(role, safe));
-}
-async function loadKeyring(role, safe) {
-  const keystore = readJsonFile(resolveKeyPath(role, safe));
-  if (!keystore) {
-    throw new Error(
-      `No ${roleLabel(role)} found.
-Run "sailor keys generate" and choose "${roleLabel(role)}" first.`
-    );
-  }
-  const password = await promptHidden(`Password for ${roleLabel(role)} key`);
-  try {
-    return await LocalKeyring.fromKeystore(keystore, password);
-  } catch {
-    throw new Error("Invalid password.");
-  }
-}
-async function loadManagerSigner(safe) {
-  const passphrase = process.env.SAIL_PASSPHRASE;
-  if (passphrase) {
-    const keystore = readJsonFile(resolveKeyPath("manager", safe));
-    if (!keystore) {
-      throw new Error(
-        'No agent wallet found.\nRun "sailor keys generate" and choose "agent wallet".'
-      );
-    }
-    try {
-      return await LocalKeyring.fromKeystore(keystore, passphrase);
-    } catch {
-      throw new Error(
-        "SAIL_PASSPHRASE does not match this keystore.\nCheck the value in .sail/.env.local (or the SAIL_PASSPHRASE CI secret) \u2014 it must be the passphrase the agent wallet was encrypted with."
-      );
-    }
-  }
-  if (process.stdin.isTTY !== true && keyExists("manager", safe)) {
-    throw new Error(
-      'Agent keystore found but SAIL_PASSPHRASE is not set.\nIf you created the key in the dashboard, add SAIL_PASSPHRASE to .sail/.env.local, or run "sailor keys generate".\nFor CI, set the SAIL_PASSPHRASE GitHub Actions secret.'
-    );
-  }
-  return loadKeyring("manager", safe);
-}
-function managerKeystorePath(managerAddr) {
-  if (!isAddress(managerAddr, { strict: false })) {
-    throw new Error(`managerKeystorePath: invalid address "${managerAddr}"`);
-  }
-  const hex = managerAddr.toLowerCase().replace(/^0x/, "");
-  return sailPath("keys", "managers", `${hex}.json`);
-}
-async function loadAnySigner() {
-  if (keyExists("permissionSigner")) return loadKeyring("permissionSigner");
-  if (keyExists("manager")) return loadKeyring("manager");
-  throw new Error('No signing key found.\nRun "sailor keys generate" first.');
-}
-
-// src/lib/project.ts
 function nonEmpty(value) {
   return typeof value === "string" && value.trim().length > 0;
 }
@@ -39819,24 +39744,6 @@ var ProjectContext = class {
     });
   }
 };
-async function loadManagerSigner2() {
-  if (!process.env.SAIL_PASSPHRASE) {
-    try {
-      const env = parseEnvFile(sailPath(".env.local"));
-      if (env.SAIL_PASSPHRASE) process.env.SAIL_PASSPHRASE = env.SAIL_PASSPHRASE;
-    } catch {
-    }
-  }
-  const passphrase = process.env.SAIL_PASSPHRASE;
-  if (passphrase) {
-    const keystore = readJsonFile(keyPath("manager"));
-    if (!keystore) {
-      throw new Error('No manager key found.\nRun "sailor keys generate" and choose "manager".');
-    }
-    return LocalKeyring.fromKeystore(keystore, passphrase);
-  }
-  return loadKeyring("manager");
-}
 
 // src/commands/capabilities.ts
 function chainName(chainId) {
@@ -40044,6 +39951,101 @@ function checkSelectorRoutes(calldata, bytecode) {
   return { selector, routes: body.includes(selector) };
 }
 
+// src/lib/keys.ts
+init_esm2();
+var ROLES = ["manager", "permissionSigner"];
+function normalizeRole(input) {
+  const n = input.trim().toLowerCase().replace(/[-_\s]/g, "");
+  if (n === "manager" || n === "mgr" || n === "m" || n === "agent" || n === "agentwallet") {
+    return "manager";
+  }
+  if (n === "permissionsigner" || n === "signer" || n === "ps" || n === "permission" || n === "mandatesigner" || n === "mandate") {
+    return "permissionSigner";
+  }
+  return null;
+}
+function roleLabel(role) {
+  return role === "manager" ? "agent wallet" : "mandate signer";
+}
+function safeHex(safe) {
+  return safe.toLowerCase().replace(/^0x/, "").replace(/[^0-9a-f]/g, "");
+}
+function keyPath(role, safe) {
+  if (safe) {
+    return sailPath("keys", `${role}-0x${safeHex(safe)}.json`);
+  }
+  return sailPath("keys", `${role}.json`);
+}
+function legacyKeyPath(role, safe) {
+  return sailPath("keys", `${role}-${safeHex(safe)}.json`);
+}
+function resolveKeyPath(role, safe) {
+  if (safe) {
+    const perSma = keyPath(role, safe);
+    if (fileExists(perSma)) return perSma;
+    const legacy = legacyKeyPath(role, safe);
+    if (fileExists(legacy)) return legacy;
+  }
+  return keyPath(role);
+}
+function keyExists(role, safe) {
+  return fileExists(resolveKeyPath(role, safe));
+}
+async function loadKeyring(role, safe) {
+  const keystore = readJsonFile(resolveKeyPath(role, safe));
+  if (!keystore) {
+    throw new Error(
+      `No ${roleLabel(role)} found.
+Run "sailor keys generate" and choose "${roleLabel(role)}" first.`
+    );
+  }
+  const passphrase = process.env.SAIL_PASSPHRASE;
+  if (passphrase) {
+    try {
+      return await LocalKeyring.fromKeystore(keystore, passphrase);
+    } catch {
+      throw new Error(
+        `SAIL_PASSPHRASE does not match the ${roleLabel(role)} keystore.
+Check the value in .sail/.env.local (or the SAIL_PASSPHRASE CI secret) \u2014 it must be the passphrase this key was encrypted with.`
+      );
+    }
+  }
+  if (process.stdin.isTTY !== true) {
+    throw new Error(
+      `${roleLabel(role)} keystore found but SAIL_PASSPHRASE is not set.
+Set SAIL_PASSPHRASE in .sail/.env.local (or as a CI secret) to run non-interactively.`
+    );
+  }
+  const password = await promptHidden(`Password for ${roleLabel(role)} key`);
+  try {
+    return await LocalKeyring.fromKeystore(keystore, password);
+  } catch {
+    throw new Error("Invalid password.");
+  }
+}
+async function loadManagerSigner(safe) {
+  if (!process.env.SAIL_PASSPHRASE) {
+    try {
+      const env = parseEnvFile(sailPath(".env.local"));
+      if (env.SAIL_PASSPHRASE) process.env.SAIL_PASSPHRASE = env.SAIL_PASSPHRASE;
+    } catch {
+    }
+  }
+  return loadKeyring("manager", safe);
+}
+function managerKeystorePath(managerAddr) {
+  if (!isAddress(managerAddr, { strict: false })) {
+    throw new Error(`managerKeystorePath: invalid address "${managerAddr}"`);
+  }
+  const hex = managerAddr.toLowerCase().replace(/^0x/, "");
+  return sailPath("keys", "managers", `${hex}.json`);
+}
+async function loadAnySigner() {
+  if (keyExists("permissionSigner")) return loadKeyring("permissionSigner");
+  if (keyExists("manager")) return loadKeyring("manager");
+  throw new Error('No signing key found.\nRun "sailor keys generate" first.');
+}
+
 // src/lib/permission-resolver.ts
 var IPERMISSION_ABI = [
   {
@@ -40439,11 +40441,11 @@ Probe is heuristic: an unknown selector (${PROBE_SELECTOR}) to a neutral target
 }
 
 // src/commands/init.ts
-var import_node_fs9 = __toESM(require("node:fs"), 1);
+var import_node_fs10 = __toESM(require("node:fs"), 1);
 var import_node_path8 = __toESM(require("node:path"), 1);
 
 // src/lib/foundry.ts
-var import_node_fs7 = require("node:fs");
+var import_node_fs8 = require("node:fs");
 var import_node_path6 = require("node:path");
 var FOUNDRY_TOML = `[profile.default]
 src = "mandates"
@@ -40592,7 +40594,7 @@ Compiled artifacts are written to \`out/\` and the deployed address is tracked i
 function scaffoldFoundryWorkspace(root) {
   const dirs = [(0, import_node_path6.join)(root, "mandates"), (0, import_node_path6.join)(root, ".sail", "contracts", "interfaces")];
   for (const d of dirs) {
-    if (!(0, import_node_fs7.existsSync)(d)) (0, import_node_fs7.mkdirSync)(d, { recursive: true });
+    if (!(0, import_node_fs8.existsSync)(d)) (0, import_node_fs8.mkdirSync)(d, { recursive: true });
   }
   writeIfMissing((0, import_node_path6.join)(root, "foundry.toml"), FOUNDRY_TOML);
   writeIfMissing(
@@ -40607,11 +40609,11 @@ function scaffoldFoundryWorkspace(root) {
   writeIfMissing((0, import_node_path6.join)(root, "mandates", "README.md"), MANDATES_README);
 }
 function writeIfMissing(path11, content) {
-  if (!(0, import_node_fs7.existsSync)(path11)) (0, import_node_fs7.writeFileSync)(path11, content, "utf8");
+  if (!(0, import_node_fs8.existsSync)(path11)) (0, import_node_fs8.writeFileSync)(path11, content, "utf8");
 }
 
 // src/lib/template.ts
-var import_node_fs8 = __toESM(require("node:fs"), 1);
+var import_node_fs9 = __toESM(require("node:fs"), 1);
 var import_node_path7 = __toESM(require("node:path"), 1);
 var TEMPLATE_COPY_EXCLUDES = /* @__PURE__ */ new Set([
   "node_modules",
@@ -40622,8 +40624,8 @@ var TEMPLATE_COPY_EXCLUDES = /* @__PURE__ */ new Set([
   ".git"
 ]);
 function copyDirSync(src, dest) {
-  import_node_fs8.default.mkdirSync(dest, { recursive: true });
-  for (const entry of import_node_fs8.default.readdirSync(src, { withFileTypes: true })) {
+  import_node_fs9.default.mkdirSync(dest, { recursive: true });
+  for (const entry of import_node_fs9.default.readdirSync(src, { withFileTypes: true })) {
     if (TEMPLATE_COPY_EXCLUDES.has(entry.name)) continue;
     const srcPath = import_node_path7.default.join(src, entry.name);
     const destName = entry.name.startsWith("_") ? `.${entry.name.slice(1)}` : entry.name;
@@ -40631,24 +40633,24 @@ function copyDirSync(src, dest) {
     if (entry.isDirectory()) {
       copyDirSync(srcPath, destPath);
     } else {
-      import_node_fs8.default.copyFileSync(srcPath, destPath);
+      import_node_fs9.default.copyFileSync(srcPath, destPath);
     }
   }
 }
 function writeIfMissing2(file, content) {
-  if (!import_node_fs8.default.existsSync(file)) import_node_fs8.default.writeFileSync(file, content, "utf-8");
+  if (!import_node_fs9.default.existsSync(file)) import_node_fs9.default.writeFileSync(file, content, "utf-8");
 }
 function copyDirSyncIfMissing(src, dest, added = [], base2 = dest) {
-  import_node_fs8.default.mkdirSync(dest, { recursive: true });
-  for (const entry of import_node_fs8.default.readdirSync(src, { withFileTypes: true })) {
+  import_node_fs9.default.mkdirSync(dest, { recursive: true });
+  for (const entry of import_node_fs9.default.readdirSync(src, { withFileTypes: true })) {
     if (TEMPLATE_COPY_EXCLUDES.has(entry.name)) continue;
     const srcPath = import_node_path7.default.join(src, entry.name);
     const destName = entry.name.startsWith("_") ? `.${entry.name.slice(1)}` : entry.name;
     const destPath = import_node_path7.default.join(dest, destName);
     if (entry.isDirectory()) {
       copyDirSyncIfMissing(srcPath, destPath, added, base2);
-    } else if (!import_node_fs8.default.existsSync(destPath)) {
-      import_node_fs8.default.copyFileSync(srcPath, destPath);
+    } else if (!import_node_fs9.default.existsSync(destPath)) {
+      import_node_fs9.default.copyFileSync(srcPath, destPath);
       added.push(import_node_path7.default.relative(base2, destPath));
     }
   }
@@ -40674,7 +40676,7 @@ var DEV_PKG = "@dev.sail.money/sailor";
 function cliPackageInfo() {
   try {
     const pkg = JSON.parse(
-      import_node_fs9.default.readFileSync(import_node_path8.default.join(packageRoot(), "package.json"), "utf-8")
+      import_node_fs10.default.readFileSync(import_node_path8.default.join(packageRoot(), "package.json"), "utf-8")
     );
     return {
       name: pkg.name ?? CANONICAL_PKG,
@@ -40691,13 +40693,13 @@ function scaffoldProjectWorkspace(dest, name, options) {
     return n;
   })() : null;
   const sailDir2 = import_node_path8.default.join(dest, ".sail");
-  import_node_fs9.default.mkdirSync(import_node_path8.default.join(sailDir2, "keys"), { recursive: true });
-  import_node_fs9.default.mkdirSync(import_node_path8.default.join(sailDir2, "runtime"), { recursive: true });
-  import_node_fs9.default.mkdirSync(import_node_path8.default.join(sailDir2, "state"), { recursive: true });
+  import_node_fs10.default.mkdirSync(import_node_path8.default.join(sailDir2, "keys"), { recursive: true });
+  import_node_fs10.default.mkdirSync(import_node_path8.default.join(sailDir2, "runtime"), { recursive: true });
+  import_node_fs10.default.mkdirSync(import_node_path8.default.join(sailDir2, "state"), { recursive: true });
   const installMode = process.env.SAILOR_INSTALL_MODE === "docker" ? "docker" : "local";
   const _rawContainerName = process.env.SAILOR_CONTAINER_NAME ?? "agent";
   const containerName = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(_rawContainerName) ? _rawContainerName : "agent";
-  import_node_fs9.default.writeFileSync(
+  import_node_fs10.default.writeFileSync(
     import_node_path8.default.join(sailDir2, "config.json"),
     `${JSON.stringify(
       {
@@ -40724,7 +40726,7 @@ function scaffoldProjectWorkspace(dest, name, options) {
   const chainEntries = Object.values(chains);
   const perChainVarLines = chainEntries.map((c) => `# ${c.rpcEnvVar}=https://your-${c.name.toLowerCase().replace(/\s+/g, "-")}-endpoint`).join("\n");
   const chainIdExample = chainId != null ? `CHAIN_ID=${chainId}` : `# CHAIN_ID=8453   # set after choosing your chain in Stage 1`;
-  import_node_fs9.default.writeFileSync(
+  import_node_fs10.default.writeFileSync(
     import_node_path8.default.join(dest, ".env.example"),
     `# Sailor agent environment
 #
@@ -40750,7 +40752,7 @@ ${perChainVarLines}
     const val = isActive && options.rpcUrl ? options.rpcUrl : `https://your-${c.name.toLowerCase().replace(/\s+/g, "-")}-endpoint`;
     return isActive && options.rpcUrl ? `${c.rpcEnvVar}=${val}` : `# ${c.rpcEnvVar}=${val}`;
   }).join("\n");
-  import_node_fs9.default.writeFileSync(
+  import_node_fs10.default.writeFileSync(
     import_node_path8.default.join(sailDir2, ".env.local"),
     `# Real values \u2014 never commit this file.
 #
@@ -40777,8 +40779,8 @@ async function initCommand(dir, options = {}) {
     throw new Error(`Invalid template name: "${templateName}"`);
   }
   const templateSrc = import_node_path8.default.join(templatesDir, templateName);
-  const availableTemplates = () => import_node_fs9.default.existsSync(templatesDir) ? import_node_fs9.default.readdirSync(templatesDir).filter((e) => import_node_fs9.default.existsSync(import_node_path8.default.join(templatesDir, e, "package.json"))).join(", ") || "none" : "none";
-  if (!import_node_fs9.default.existsSync(templateSrc) || !import_node_fs9.default.existsSync(import_node_path8.default.join(templateSrc, "package.json"))) {
+  const availableTemplates = () => import_node_fs10.default.existsSync(templatesDir) ? import_node_fs10.default.readdirSync(templatesDir).filter((e) => import_node_fs10.default.existsSync(import_node_path8.default.join(templatesDir, e, "package.json"))).join(", ") || "none" : "none";
+  if (!import_node_fs10.default.existsSync(templateSrc) || !import_node_fs10.default.existsSync(import_node_path8.default.join(templateSrc, "package.json"))) {
     const available = availableTemplates();
     const hint = available === "none" ? `
 No templates found under ${templatesDir}.
@@ -40791,19 +40793,19 @@ run from the repo root.` : ` Available: ${available}`;
   if (!inPlace && !dest.startsWith(cwd + import_node_path8.default.sep) && dest !== cwd) {
     throw new Error(`Directory must be inside the current working directory`);
   }
-  if (!inPlace && import_node_fs9.default.existsSync(dest) && !options.force) {
+  if (!inPlace && import_node_fs10.default.existsSync(dest) && !options.force) {
     throw new Error(`Directory already exists: ${dest}
 Pass --force to scaffold into it anyway (existing files with the same name are overwritten).`);
   }
-  if (inPlace && import_node_fs9.default.existsSync(import_node_path8.default.join(dest, ".sail", "config.json")) && !options.force) {
+  if (inPlace && import_node_fs10.default.existsSync(import_node_path8.default.join(dest, ".sail", "config.json")) && !options.force) {
     throw new Error(
       "This project is already initialized.\nRun `sailor update` to re-sync template files, or `sailor init --force` to re-initialize (overwrites scaffold files; your .sail/keys/ and .sail/state/ are left in place)."
     );
   }
   const existingConfigPath = import_node_path8.default.join(dest, ".sail", "config.json");
-  const previousConfig = import_node_fs9.default.existsSync(existingConfigPath) ? (() => {
+  const previousConfig = import_node_fs10.default.existsSync(existingConfigPath) ? (() => {
     try {
-      return JSON.parse(import_node_fs9.default.readFileSync(existingConfigPath, "utf-8"));
+      return JSON.parse(import_node_fs10.default.readFileSync(existingConfigPath, "utf-8"));
     } catch {
       return null;
     }
@@ -40811,37 +40813,37 @@ Pass --force to scaffold into it anyway (existing files with the same name are o
   copyDirSync(templateSrc, dest);
   const pkgRoot = packageRoot();
   const examplesPermSrc = import_node_path8.default.join(pkgRoot, "examples", "permissions");
-  if (import_node_fs9.default.existsSync(examplesPermSrc)) {
+  if (import_node_fs10.default.existsSync(examplesPermSrc)) {
     copyDirSync(examplesPermSrc, import_node_path8.default.join(dest, "examples", "permissions"));
   }
   const customMandateSrc = import_node_path8.default.join(pkgRoot, "examples", "custom-mandate");
-  if (import_node_fs9.default.existsSync(customMandateSrc)) {
+  if (import_node_fs10.default.existsSync(customMandateSrc)) {
     copyDirSync(customMandateSrc, import_node_path8.default.join(dest, "examples", "custom-mandate"));
   }
   const permModelSrc = import_node_path8.default.join(pkgRoot, "docs", "PERMISSION_MODEL.md");
-  if (import_node_fs9.default.existsSync(permModelSrc)) {
-    import_node_fs9.default.mkdirSync(import_node_path8.default.join(dest, "docs"), { recursive: true });
-    writeIfMissing2(import_node_path8.default.join(dest, "docs", "PERMISSION_MODEL.md"), import_node_fs9.default.readFileSync(permModelSrc, "utf-8"));
+  if (import_node_fs10.default.existsSync(permModelSrc)) {
+    import_node_fs10.default.mkdirSync(import_node_path8.default.join(dest, "docs"), { recursive: true });
+    writeIfMissing2(import_node_path8.default.join(dest, "docs", "PERMISSION_MODEL.md"), import_node_fs10.default.readFileSync(permModelSrc, "utf-8"));
   }
   const pkgPath = import_node_path8.default.join(dest, "package.json");
-  if (import_node_fs9.default.existsSync(pkgPath)) {
-    const pkg = JSON.parse(import_node_fs9.default.readFileSync(pkgPath, "utf-8"));
+  if (import_node_fs10.default.existsSync(pkgPath)) {
+    const pkg = JSON.parse(import_node_fs10.default.readFileSync(pkgPath, "utf-8"));
     pkg.name = name;
     const devDeps = pkg.devDependencies ?? {};
     const { name: cliName, version: cliVer } = cliPackageInfo();
     devDeps[CANONICAL_PKG] = cliName === DEV_PKG ? `npm:${DEV_PKG}@^${cliVer}` : `^${cliVer}`;
     pkg.devDependencies = devDeps;
-    import_node_fs9.default.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}
+    import_node_fs10.default.writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}
 `);
   }
   const tsconfigPath = import_node_path8.default.join(dest, "tsconfig.json");
-  if (import_node_fs9.default.existsSync(tsconfigPath)) {
-    const tsconfig = JSON.parse(import_node_fs9.default.readFileSync(tsconfigPath, "utf-8"));
+  if (import_node_fs10.default.existsSync(tsconfigPath)) {
+    const tsconfig = JSON.parse(import_node_fs10.default.readFileSync(tsconfigPath, "utf-8"));
     const co = tsconfig.compilerOptions;
     if (co && "paths" in co) {
       delete co.paths;
       delete co.baseUrl;
-      import_node_fs9.default.writeFileSync(tsconfigPath, `${JSON.stringify(tsconfig, null, 2)}
+      import_node_fs10.default.writeFileSync(tsconfigPath, `${JSON.stringify(tsconfig, null, 2)}
 `);
     }
   }
@@ -40879,20 +40881,20 @@ function chainLabel(chainId) {
 }
 function detectState(dest) {
   try {
-    const configRaw = import_node_fs9.default.readFileSync(import_node_path8.default.join(dest, ".sail", "config.json"), "utf-8");
+    const configRaw = import_node_fs10.default.readFileSync(import_node_path8.default.join(dest, ".sail", "config.json"), "utf-8");
     const config = JSON.parse(configRaw);
     const projectName = config.name ?? import_node_path8.default.basename(dest);
     const accountPath = import_node_path8.default.join(dest, ".sail", "account.json");
-    if (!import_node_fs9.default.existsSync(accountPath)) {
+    if (!import_node_fs10.default.existsSync(accountPath)) {
       return { kind: "B", projectName, chain: chainLabel(config.chainId ?? 0) };
     }
-    const accountRaw = import_node_fs9.default.readFileSync(accountPath, "utf-8");
+    const accountRaw = import_node_fs10.default.readFileSync(accountPath, "utf-8");
     const account2 = JSON.parse(accountRaw);
     const sma = account2.safe ?? "";
     const chain2 = chainLabel(account2.chainId ?? config.chainId ?? 0);
     let permissionCount = 0;
     try {
-      const mandatesRaw = import_node_fs9.default.readFileSync(
+      const mandatesRaw = import_node_fs10.default.readFileSync(
         import_node_path8.default.join(dest, ".sail", "state", "mandates.json"),
         "utf-8"
       );
@@ -40981,7 +40983,7 @@ Created ${name}/`);
 }
 
 // src/commands/update.ts
-var import_node_fs10 = __toESM(require("node:fs"), 1);
+var import_node_fs11 = __toESM(require("node:fs"), 1);
 var import_node_path9 = __toESM(require("node:path"), 1);
 var UPDATE_PATHS = [
   ".agents",
@@ -40997,18 +40999,18 @@ var STALE_PATHS = [
 ];
 async function updateCommand() {
   const dest = process.cwd();
-  if (!import_node_fs10.default.existsSync(import_node_path9.default.join(dest, ".sail", "config.json"))) {
+  if (!import_node_fs11.default.existsSync(import_node_path9.default.join(dest, ".sail", "config.json"))) {
     throw new Error("Not a sailor project \u2014 .sail/config.json not found. Run `sailor init` first.");
   }
   const templateSrc = import_node_path9.default.join(packageRoot(), "templates", "default");
-  if (!import_node_fs10.default.existsSync(templateSrc)) {
+  if (!import_node_fs11.default.existsSync(templateSrc)) {
     throw new Error(`Template directory not found at ${templateSrc}`);
   }
   const removed = [];
   for (const p of STALE_PATHS) {
     const target = import_node_path9.default.join(dest, p);
-    if (import_node_fs10.default.existsSync(target)) {
-      import_node_fs10.default.rmSync(target, { recursive: true, force: true });
+    if (import_node_fs11.default.existsSync(target)) {
+      import_node_fs11.default.rmSync(target, { recursive: true, force: true });
       removed.push(p);
     }
   }
@@ -41016,13 +41018,13 @@ async function updateCommand() {
   for (const p of UPDATE_PATHS) {
     const src = import_node_path9.default.join(templateSrc, p);
     const dst = import_node_path9.default.join(dest, p);
-    if (!import_node_fs10.default.existsSync(src)) continue;
-    const stat = import_node_fs10.default.statSync(src);
+    if (!import_node_fs11.default.existsSync(src)) continue;
+    const stat = import_node_fs11.default.statSync(src);
     if (stat.isDirectory()) {
       copyDirSync(src, dst);
     } else {
-      import_node_fs10.default.mkdirSync(import_node_path9.default.dirname(dst), { recursive: true });
-      import_node_fs10.default.copyFileSync(src, dst);
+      import_node_fs11.default.mkdirSync(import_node_path9.default.dirname(dst), { recursive: true });
+      import_node_fs11.default.copyFileSync(src, dst);
     }
     updated.push(p);
   }
@@ -41030,7 +41032,7 @@ async function updateCommand() {
   copyDirSyncIfMissing(templateSrc, dest, added);
   const configPath = import_node_path9.default.join(dest, ".sail", "config.json");
   try {
-    const config = JSON.parse(import_node_fs10.default.readFileSync(configPath, "utf-8"));
+    const config = JSON.parse(import_node_fs11.default.readFileSync(configPath, "utf-8"));
     const newMode = process.env.SAILOR_INSTALL_MODE === "docker" ? "docker" : "local";
     const _rawContainerName = process.env.SAILOR_CONTAINER_NAME ?? "agent";
     const containerName = /^[a-zA-Z0-9][a-zA-Z0-9_.-]*$/.test(_rawContainerName) ? _rawContainerName : "agent";
@@ -41043,7 +41045,7 @@ async function updateCommand() {
       } else {
         delete config.containerName;
       }
-      import_node_fs10.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
+      import_node_fs11.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
 `, "utf-8");
       if (previousMode === "docker" && newMode === "local") {
         const prev = previousContainer ?? "agent";
@@ -41057,7 +41059,7 @@ Switched to Docker install (container: ${containerName}).`);
       }
     } else if (newMode === "docker" && config.containerName !== containerName) {
       config.containerName = containerName;
-      import_node_fs10.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
+      import_node_fs11.default.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}
 `, "utf-8");
     }
   } catch {
@@ -41086,7 +41088,7 @@ Added (new in template):`);
 }
 
 // src/commands/keys.ts
-var import_node_fs11 = __toESM(require("node:fs"), 1);
+var import_node_fs12 = __toESM(require("node:fs"), 1);
 var import_node_path10 = __toESM(require("node:path"), 1);
 function readStdin() {
   return new Promise((resolve3, reject) => {
@@ -41193,14 +41195,14 @@ async function keysExportCi() {
     );
   }
   const dest = import_node_path10.default.resolve(process.cwd(), "ci-keystore.json");
-  import_node_fs11.default.copyFileSync(src, dest);
+  import_node_fs12.default.copyFileSync(src, dest);
   console.log(`\u2713 Keystore copied to ci-keystore.json`);
   console.log(`  Source: ${src}`);
   const gitignorePath = import_node_path10.default.resolve(process.cwd(), ".gitignore");
-  if (import_node_fs11.default.existsSync(gitignorePath)) {
-    const content = import_node_fs11.default.readFileSync(gitignorePath, "utf-8");
+  if (import_node_fs12.default.existsSync(gitignorePath)) {
+    const content = import_node_fs12.default.readFileSync(gitignorePath, "utf-8");
     if (!content.includes("ci-keystore.json")) {
-      import_node_fs11.default.appendFileSync(
+      import_node_fs12.default.appendFileSync(
         gitignorePath,
         "\n# CI keystore \u2014 encrypted agent wallet, safe to commit\n!ci-keystore.json\n"
       );
@@ -41238,10 +41240,125 @@ async function keysShow() {
 
 // src/commands/mandate-contracts.ts
 var import_node_child_process = require("node:child_process");
-var import_node_fs12 = require("node:fs");
-var import_node_path11 = require("node:path");
+var import_node_fs14 = require("node:fs");
+var import_node_path12 = require("node:path");
 init_esm2();
 
+// src/lib/permission-explainer.ts
+var import_node_fs13 = require("node:fs");
+var import_node_path11 = require("node:path");
+function explainPermission(name, sourcePath) {
+  const resolved = sourcePath ?? (0, import_node_path11.join)(process.cwd(), "mandates", `${name}.sol`);
+  let src;
+  try {
+    src = (0, import_node_fs13.readFileSync)(resolved, "utf8");
+  } catch {
+    return null;
+  }
+  return parseStructured(src) ?? parseNatSpec(src) ?? parseRequires(src);
+}
+var ENFORCED_HEADER = /ENFORCE[SD]\s+ON-CHAIN/i;
+var NOT_ENFORCED_HEADER = /NOT\s+(ENFORCED|BOUNDED)/i;
+function parseStructured(src) {
+  if (!ENFORCED_HEADER.test(src)) return null;
+  const lines = src.split("\n");
+  const result = {
+    source: "structured",
+    enforced: [],
+    notEnforced: []
+  };
+  const headerLines = [];
+  for (const line of lines) {
+    const t = line.trim();
+    if (t.startsWith("import ") || t.startsWith("contract ") || t.startsWith("abstract contract ")) break;
+    if (t.startsWith("//")) headerLines.push(t.slice(2));
+  }
+  let section = null;
+  for (const raw of headerLines) {
+    const trimmed = raw.trim();
+    if (/^─+$/.test(trimmed)) continue;
+    if (NOT_ENFORCED_HEADER.test(trimmed)) {
+      section = "notEnforced";
+      continue;
+    }
+    if (ENFORCED_HEADER.test(trimmed)) {
+      section = "enforced";
+      continue;
+    }
+    if (trimmed.includes("VERIFY BEFORE USE")) {
+      section = null;
+      continue;
+    }
+    if (section === null) {
+      const kv = trimmed.match(/^(Protocol|Version|Chain|Target)\s*:\s*(.+)$/i);
+      if (kv) {
+        const key = kv[1].toLowerCase();
+        result[key] = kv[2].trim();
+      }
+    }
+    if (section && trimmed.startsWith("\u2022")) {
+      const bullet = trimmed.slice(1).trim();
+      if (bullet) result[section].push(bullet);
+    }
+  }
+  if (result.enforced.length === 0 && !result.protocol) return null;
+  return result;
+}
+function parseNatSpec(src) {
+  const enforced = [];
+  const notEnforced = [];
+  let current = null;
+  let buf = [];
+  const flush = () => {
+    if (current && buf.length) {
+      const text = buf.join(" ").replace(/\s+/g, " ").trim();
+      if (text) (current === "enforced" ? enforced : notEnforced).push(text);
+    }
+    buf = [];
+  };
+  for (const line of src.split("\n")) {
+    const t = line.trim();
+    const tagged = t.match(/^\/\/\/\s*@(\w+)\s+(.+)$/);
+    if (tagged) {
+      const [, tag, text] = tagged;
+      if (tag === "notice") {
+        flush();
+        current = "enforced";
+        buf.push(text.trim());
+      } else if (tag === "dev") {
+        flush();
+        current = "notEnforced";
+        buf.push(text.trim());
+      } else {
+        flush();
+        current = null;
+      }
+      continue;
+    }
+    const cont = t.match(/^\/\/\/\s?(.*)$/);
+    if (cont && current) {
+      const text = cont[1].trim();
+      if (text) buf.push(text);
+      continue;
+    }
+    if (!t.startsWith("///")) {
+      flush();
+      current = null;
+    }
+  }
+  flush();
+  if (enforced.length === 0 && notEnforced.length === 0) return null;
+  return { source: "natspec", enforced, notEnforced };
+}
+function parseRequires(src) {
+  const enforced = [];
+  const re = /require\s*\([^,)]+,\s*["']([^"']+)["']\)/g;
+  let m;
+  while ((m = re.exec(src)) !== null) enforced.push(m[1]);
+  if (enforced.length === 0) return null;
+  return { source: "require-only", enforced, notEnforced: [] };
+}
+
 // src/lib/mandates.ts
 var MandateStore = class {
   filePath;
@@ -41370,7 +41487,7 @@ Project: ${project.name}`));
   if (!keyExists("manager")) {
     throw new Error('No agent wallet found. Run "sailor keys generate" and choose "agent wallet" first.');
   }
-  const agentSigner = await loadManagerSigner2();
+  const agentSigner = await loadManagerSigner();
   const agentAddress = agentSigner.address;
   say(() => console.log("\u2713", `Agent wallet: ${agentAddress}`));
   const chain2 = getChainById(project.chainId);
@@ -41383,7 +41500,7 @@ Project: ${project.name}`));
     () => console.log(
       `
 \u2192 Open the Sailor dashboard to approve signing requests:
-  ${signingPageUrl(channel, projectPort(process.cwd()))}
+  ${signingPageUrl(projectPort(process.cwd()))}
 `
     )
   );
@@ -41706,6 +41823,8 @@ Pushing signing request for "${template.label}" permission\u2026`));
       `  The mandate signer (${permissionSigner}) must sign in the browser \u2014 not the agent wallet.`
     )
   );
+  const permRecord = new MandateStore().find(templateAddress);
+  const permExplanation = (permRecord ? explainPermission(permRecord.name, permRecord.sourcePath) : explainPermission(template.label)) ?? void 0;
   const response = await channel.requestSignature({
     type: "typed-data",
     kind: "register-permission",
@@ -41718,6 +41837,7 @@ Pushing signing request for "${template.label}" permission\u2026`));
       { label: "Permission", value: template.label },
       { label: "Mandate signer", value: permissionSigner }
     ],
+    explanation: permExplanation,
     typedData
   });
   if (response.status === "rejected") {
@@ -41884,7 +42004,7 @@ Mandate command failed: ${msg}`), {
   process.exit(1);
 }
 function announceSigningUrl(json) {
-  const url = signingPageUrl(void 0, projectPort(process.cwd()));
+  const url = signingPageUrl(projectPort(process.cwd()));
   if (json) {
     process.stdout.write(`${JSON.stringify({ status: "waiting_for_signature", url })}
 `);
@@ -41932,12 +42052,12 @@ async function runDeploy(project, channel, options) {
       )
     );
   }
-  const { abi: abi2, bytecode, contractName, artifactPath } = resolveArtifact(options);
+  const { abi: abi2, bytecode, contractName, artifactPath, sourcePath } = resolveArtifact(options);
   let argsJson;
   if (options.argsFile) {
-    const argsFilePath = (0, import_node_path11.resolve)(options.argsFile);
+    const argsFilePath = (0, import_node_path12.resolve)(options.argsFile);
     try {
-      argsJson = (0, import_node_fs12.readFileSync)(argsFilePath, "utf8").trim();
+      argsJson = (0, import_node_fs14.readFileSync)(argsFilePath, "utf8").trim();
     } catch {
       throw new Error(`Cannot read --args-file: ${argsFilePath}`);
     }
@@ -41950,6 +42070,7 @@ async function runDeploy(project, channel, options) {
   const publicClient = publicClientFor(project);
   announceSigningUrl(json);
   say(() => console.log(`Pushing deploy request for "${contractName}"\u2026`));
+  const explanation = explainPermission(contractName, sourcePath) ?? void 0;
   const response = await channel.requestSignature({
     type: "transaction",
     kind: "deploy-mandate",
@@ -41964,7 +42085,8 @@ async function runDeploy(project, channel, options) {
         label: options.argsFile ? "Constructor args (from file)" : "Constructor args",
         value: argsJson ? argsJson : "(none)"
       }
-    ]
+    ],
+    explanation
   });
   if (response.status === "rejected") {
     throw new Error(`User rejected permission deployment: ${response.reason ?? "no reason given"}`);
@@ -41984,6 +42106,7 @@ async function runDeploy(project, channel, options) {
     address: deployed,
     txHash: response.txHash,
     chainId,
+    sourcePath,
     artifactPath,
     constructorArgs: parseArgsRaw(options.args),
     deployedAt: (/* @__PURE__ */ new Date()).toISOString()
@@ -42145,7 +42268,7 @@ async function runDeployClone(project, channel, options) {
   }
   const chain2 = getChainById(project.chainId);
   const publicClient = publicClientFor(project);
-  const agentSigner = await loadManagerSigner2();
+  const agentSigner = await loadManagerSigner();
   const registered = await publicClient.readContract({
     address: project.contracts.kernel,
     abi: SailKernelAbi,
@@ -42489,7 +42612,7 @@ Connect the owner wallet (mandate signer) in the browser \u2014 the agent wallet
   } catch (err) {
     if (err.message.startsWith("Security:")) throw err;
   }
-  const agentSigner = await loadManagerSigner2();
+  const agentSigner = await loadManagerSigner();
   const walletClient = createWalletClient({
     account: agentSigner.viemAccount,
     chain: getChainById(project.chainId),
@@ -42531,7 +42654,7 @@ async function attachToSma(project, channel, publicClient, sma, mandate2, label,
   const say = (fn) => {
     if (!json) fn();
   };
-  const agentSigner = await loadManagerSigner2();
+  const agentSigner = await loadManagerSigner();
   const registered = await publicClient.readContract({
     address: project.contracts.kernel,
     abi: SailKernelAbi,
@@ -42572,7 +42695,7 @@ async function attachBatchToSma(project, channel, publicClient, sma, permissions
   const say = (fn) => {
     if (!json) fn();
   };
-  const agentSigner = await loadManagerSigner2();
+  const agentSigner = await loadManagerSigner();
   const registered = await publicClient.readContract({
     address: project.contracts.kernel,
     abi: SailKernelAbi,
@@ -42618,6 +42741,15 @@ async function attachBatchToSma(project, channel, publicClient, sma, permissions
 Attaching ${permissions.length} permissions in one signature \u2014 the mandate signer (${permissionSigner}) signs in the browser\u2026`
     )
   );
+  const permStore = new MandateStore();
+  const permExplanations = permissions.map((addr) => {
+    const rec = permStore.find(addr);
+    return {
+      label: rec?.name ?? addr,
+      address: addr,
+      explanation: (rec ? explainPermission(rec.name, rec.sourcePath) : null) ?? void 0
+    };
+  });
   const response = await channel.requestSignature({
     type: "typed-data",
     kind: "register-permission",
@@ -42629,6 +42761,7 @@ Attaching ${permissions.length} permissions in one signature \u2014 the mandate
       { label: "Permissions", value: String(permissions.length) },
       { label: "Mandate signer", value: permissionSigner }
     ],
+    permissions: permExplanations,
     typedData
   });
   if (response.status === "rejected") {
@@ -42776,11 +42909,11 @@ function resolveArtifact(options) {
   let contractName = options.contract ?? options.name ?? "";
   if (!artifactPath) {
     if (!options.contract) throw new Error("Provide --artifact <path> or --contract <name>");
-    artifactPath = (0, import_node_path11.join)(options.out, `${options.contract}.sol`, `${options.contract}.json`);
+    artifactPath = (0, import_node_path12.join)(options.out, `${options.contract}.sol`, `${options.contract}.json`);
   }
-  const resolved = (0, import_node_path11.resolve)(artifactPath);
-  const projectRoot = (0, import_node_path11.resolve)(process.cwd());
-  if (!resolved.startsWith(projectRoot + import_node_path11.sep) && resolved !== projectRoot) {
+  const resolved = (0, import_node_path12.resolve)(artifactPath);
+  const projectRoot = (0, import_node_path12.resolve)(process.cwd());
+  if (!resolved.startsWith(projectRoot + import_node_path12.sep) && resolved !== projectRoot) {
     throw new Error(
       `Artifact path must be inside the project directory.
 Resolved: ${resolved}`
@@ -42788,14 +42921,14 @@ Resolved: ${resolved}`
   }
   artifactPath = resolved;
   if (options.build) runForgeBuild();
-  if (!(0, import_node_fs12.existsSync)(artifactPath)) {
+  if (!(0, import_node_fs14.existsSync)(artifactPath)) {
     ensureForgeHint();
     throw new Error(
       `Artifact not found: ${artifactPath}
 Compile your mandate first (e.g. \`forge build\`), or pass --build.`
     );
   }
-  const artifact = JSON.parse((0, import_node_fs12.readFileSync)(artifactPath, "utf8"));
+  const artifact = JSON.parse((0, import_node_fs14.readFileSync)(artifactPath, "utf8"));
   const abi2 = artifact.abi;
   const bytecodeRaw = artifact.bytecode?.object ?? artifact.bytecode;
   if (!bytecodeRaw || typeof bytecodeRaw !== "string") {
@@ -42806,7 +42939,16 @@ Compile your mandate first (e.g. \`forge build\`), or pass --build.`
     const m = artifactPath.match(/([^/\\]+)\.json$/);
     contractName = m ? m[1] : "Mandate";
   }
-  return { abi: abi2, bytecode, contractName, artifactPath };
+  let sourcePath;
+  const compilationTarget = artifact.metadata?.settings?.compilationTarget;
+  if (compilationTarget && typeof compilationTarget === "object") {
+    sourcePath = Object.keys(compilationTarget)[0];
+  }
+  sourcePath = sourcePath ?? artifact.ast?.absolutePath;
+  if (sourcePath && !sourcePath.startsWith("/")) {
+    sourcePath = (0, import_node_path12.resolve)(projectRoot, sourcePath);
+  }
+  return { abi: abi2, bytecode, contractName, artifactPath, sourcePath };
 }
 function parseArgsRaw(argsJson) {
   if (!argsJson) return void 0;
@@ -42876,88 +43018,6 @@ function runForgeBuild() {
 
 // src/commands/mandate.ts
 init_esm2();
-
-// src/lib/permission-explainer.ts
-var import_node_fs13 = require("node:fs");
-var import_node_path12 = require("node:path");
-function explainPermission(name, sourcePath) {
-  const resolved = sourcePath ?? (0, import_node_path12.join)(process.cwd(), "mandates", `${name}.sol`);
-  let src;
-  try {
-    src = (0, import_node_fs13.readFileSync)(resolved, "utf8");
-  } catch {
-    return null;
-  }
-  return parseStructured(src) ?? parseNatSpec(src) ?? parseRequires(src);
-}
-function parseStructured(src) {
-  if (!src.includes("ENFORCED ON-CHAIN")) return null;
-  const lines = src.split("\n");
-  const result = {
-    source: "structured",
-    enforced: [],
-    notEnforced: []
-  };
-  const headerLines = [];
-  for (const line of lines) {
-    const t = line.trim();
-    if (t.startsWith("import ") || t.startsWith("contract ") || t.startsWith("abstract contract ")) break;
-    if (t.startsWith("//")) headerLines.push(t.slice(2));
-  }
-  let section = null;
-  for (const raw of headerLines) {
-    const trimmed = raw.trim();
-    if (/^─+$/.test(trimmed)) continue;
-    if (trimmed.includes("ENFORCED ON-CHAIN")) {
-      section = "enforced";
-      continue;
-    }
-    if (trimmed.includes("NOT ENFORCED")) {
-      section = "notEnforced";
-      continue;
-    }
-    if (trimmed.includes("VERIFY BEFORE USE")) {
-      section = null;
-      continue;
-    }
-    if (section === null) {
-      const kv = trimmed.match(/^(Protocol|Version|Chain|Target)\s*:\s*(.+)$/i);
-      if (kv) {
-        const key = kv[1].toLowerCase();
-        result[key] = kv[2].trim();
-      }
-    }
-    if (section && trimmed.startsWith("\u2022")) {
-      const bullet = trimmed.slice(1).trim();
-      if (bullet) result[section].push(bullet);
-    }
-  }
-  if (result.enforced.length === 0 && !result.protocol) return null;
-  return result;
-}
-function parseNatSpec(src) {
-  const enforced = [];
-  const notEnforced = [];
-  for (const line of src.split("\n")) {
-    const t = line.trim();
-    const notice = t.match(/^\/\/\/\s*@notice\s+(.+)$/);
-    if (notice) enforced.push(notice[1].trim());
-    const dev = t.match(/^\/\/\/\s*@dev\s+(.+)$/);
-    if (dev) notEnforced.push(dev[1].trim());
-  }
-  if (enforced.length === 0 && notEnforced.length === 0) return null;
-  return { source: "natspec", enforced, notEnforced };
-}
-function parseRequires(src) {
-  const enforced = [];
-  const re = /require\s*\([^,)]+,\s*["']([^"']+)["']\)/g;
-  let m;
-  while ((m = re.exec(src)) !== null) enforced.push(m[1]);
-  if (enforced.length === 0) return null;
-  return { source: "require-only", enforced, notEnforced: [] };
-}
-
-// src/commands/mandate.ts
 function resolveActiveChain(account2) {
   try {
     const project = new ProjectContext();
@@ -43033,7 +43093,9 @@ ${permissions.length} permission(s) tracked for SMA ${account2.safe}:
   const draft = {
     account: account2.safe,
     chainId,
-    permissions: permissions.filter((p) => !p.revokedOnChain).map((p) => {
+    // Only permissions not already registered on this SMA belong in the signing
+    // draft — re-registering an already-registered permission reverts on-chain.
+    permissions: permissions.filter((p) => !p.revokedOnChain && !p.registeredOnSma).map((p) => {
       const mandate2 = store.find(p.address);
       const explanation = explainPermission(p.label, mandate2?.sourcePath) ?? void 0;
       return { address: p.address, label: p.label, explanation };
@@ -43106,7 +43168,7 @@ ${unregistered.length} permission(s) are not yet registered on this SMA. Initiat
 }
 
 // src/commands/mandate-simulate.ts
-var import_node_fs14 = require("node:fs");
+var import_node_fs15 = require("node:fs");
 init_esm2();
 function parseExpect(raw, where) {
   if (raw === void 0) return void 0;
@@ -43122,7 +43184,7 @@ function resolveSampleCalls(options) {
   if (options.calls) {
     let raw;
     try {
-      raw = JSON.parse((0, import_node_fs14.readFileSync)(options.calls, "utf8"));
+      raw = JSON.parse((0, import_node_fs15.readFileSync)(options.calls, "utf8"));
     } catch (err) {
       throw new Error(`Could not read --calls file "${options.calls}": ${err.message}`);
     }
@@ -43338,7 +43400,7 @@ async function mandateSimulate(options) {
 }
 
 // src/commands/rotate-signer.ts
-var import_node_fs15 = require("node:fs");
+var import_node_fs16 = require("node:fs");
 init_esm2();
 var PENDING_REATTACH_FILE = ["state", "pending-reattach.json"];
 async function rotateSigner(options) {
@@ -43468,7 +43530,7 @@ SMA:            ${smaAddress}`);
     console.log(
       `
 \u2192 Open the Sailor dashboard to approve signing requests:
-  ${signingPageUrl(channel, projectPort(process.cwd()))}
+  ${signingPageUrl(projectPort(process.cwd()))}
 `
     );
   });
@@ -43726,7 +43788,7 @@ ensure the agent that signs dispatches holds this key.`
   const keystore = await keyring.exportKeystore(password);
   writeJsonFile(target, keystore, 384);
   const perManagerPath = managerKeystorePath(keyring.address);
-  (0, import_node_fs15.mkdirSync)(sailPath("keys", "managers"), { recursive: true });
+  (0, import_node_fs16.mkdirSync)(sailPath("keys", "managers"), { recursive: true });
   writeJsonFile(perManagerPath, keystore, 384);
   say(
     () => console.log(
@@ -43738,7 +43800,7 @@ ensure the agent that signs dispatches holds this key.`
 function promoteManagerKeystore(newManager, say) {
   const stored = readJsonFile(managerKeystorePath(newManager));
   if (!stored) return;
-  (0, import_node_fs15.mkdirSync)(sailPath("keys", "managers"), { recursive: true });
+  (0, import_node_fs16.mkdirSync)(sailPath("keys", "managers"), { recursive: true });
   const activeTarget = keyPath("manager");
   const displaced = readJsonFile(activeTarget);
   if (displaced?.address) {
@@ -43790,7 +43852,7 @@ function writePending(pending) {
 }
 function clearPending() {
   try {
-    (0, import_node_fs15.rmSync)(sailPath(...PENDING_REATTACH_FILE), { force: true });
+    (0, import_node_fs16.rmSync)(sailPath(...PENDING_REATTACH_FILE), { force: true });
   } catch {
   }
 }
@@ -43844,7 +43906,7 @@ async function ownerConnect(options) {
     await channel.start();
     if (!options.json) {
       console.log("\u2192 Open the Sailor dashboard and connect your wallet:");
-      console.log(`  ${signingPageUrl(channel, projectPort(projectRoot))}`);
+      console.log(`  ${signingPageUrl(projectPort(projectRoot))}`);
       if (channel.remote) console.log("  (using the running signing station)");
       console.log("\nWaiting for a wallet connection\u2026");
     }
@@ -43893,41 +43955,6 @@ var import_node_fs17 = __toESM(require("node:fs"), 1);
 var import_node_path13 = __toESM(require("node:path"), 1);
 var import_node_url = require("node:url");
 init_esm2();
-
-// src/lib/process.ts
-var import_node_fs16 = __toESM(require("node:fs"), 1);
-function agentPidPath(chainId) {
-  return chainId != null ? sailPath(`agent-${chainId}.pid`) : sailPath("agent.pid");
-}
-function writeAgentPid(chainId) {
-  import_node_fs16.default.mkdirSync(sailPath(), { recursive: true });
-  import_node_fs16.default.writeFileSync(agentPidPath(chainId), `${process.pid}
-`);
-}
-function clearAgentPid(chainId) {
-  try {
-    import_node_fs16.default.rmSync(agentPidPath(chainId));
-  } catch {
-  }
-}
-function readAgentPid(chainId) {
-  try {
-    const pid = Number.parseInt(import_node_fs16.default.readFileSync(agentPidPath(chainId), "utf-8").trim(), 10);
-    return Number.isNaN(pid) ? null : pid;
-  } catch {
-    return null;
-  }
-}
-function isProcessAlive(pid) {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-// src/commands/run.ts
 var DEFAULT_INTERVAL_SEC = 60;
 var sleep2 = (ms) => new Promise((resolve3) => setTimeout(resolve3, ms));
 var ERC20_READ_ABI = [
@@ -44972,7 +44999,7 @@ function requireAccount() {
   }
   return account2;
 }
-async function sessionPause() {
+async function sessionPause(opts = {}) {
   const account2 = requireAccount();
   const signer = await loadAnySigner();
   const client = makeClient(account2.chainId);
@@ -44987,9 +45014,10 @@ async function sessionPause() {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   writeJsonFile(sailPath("session.json"), session2);
-  console.log("Session paused \u2014 agent dispatch rights revoked.");
+  if (opts.json) console.log(JSON.stringify(session2));
+  else console.log("Session paused \u2014 agent dispatch rights revoked.");
 }
-async function sessionResume() {
+async function sessionResume(opts = {}) {
   const account2 = requireAccount();
   const signer = await loadAnySigner();
   const client = makeClient(account2.chainId);
@@ -45004,7 +45032,8 @@ async function sessionResume() {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   writeJsonFile(sailPath("session.json"), session2);
-  console.log("Session resumed \u2014 agent dispatch rights restored.");
+  if (opts.json) console.log(JSON.stringify(session2));
+  else console.log("Session resumed \u2014 agent dispatch rights restored.");
 }
 
 // src/commands/station.ts
@@ -45122,7 +45151,11 @@ async function status() {
   const hasManager = keyExists("manager");
   const hasPermissionSigner = keyExists("permissionSigner");
   const account2 = readJsonFile(sailPath("account.json"));
-  const mandate2 = readJsonFile(sailPath("mandate.json"));
+  const mandateRaw = readJsonFile(sailPath("mandate.json"));
+  const mandates = (Array.isArray(mandateRaw) ? mandateRaw : mandateRaw ? [mandateRaw] : []).filter(
+    Boolean
+  );
+  const hasMandate = mandates.length > 0;
   const session2 = readJsonFile(sailPath("session.json"));
   console.log("Sailor status");
   console.log("\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500");
@@ -45138,9 +45171,12 @@ async function status() {
     console.log('  \u2717 not deployed   run "sailor onboard --new-sma"');
   }
   console.log("Mandate:");
-  if (mandate2) {
-    const n = mandate2.permissions.length;
-    console.log(`  \u2713 signed   ${n} permission${n === 1 ? "" : "s"}`);
+  if (hasMandate) {
+    const n = mandates.reduce((sum, m) => sum + (m?.permissions?.length ?? 0), 0);
+    const permLabel = `${n} permission${n === 1 ? "" : "s"}`;
+    console.log(
+      mandates.length > 1 ? `  \u2713 signed   ${mandates.length} mandates, ${permLabel}` : `  \u2713 signed   ${permLabel}`
+    );
   } else {
     console.log('  \u2717 not signed   run "sailor mandate sign"');
   }
@@ -45150,7 +45186,7 @@ async function status() {
   let agentState;
   if (running) {
     agentState = `running (PID ${pid})`;
-  } else if (!mandate2) {
+  } else if (!hasMandate) {
     agentState = "not configured";
   } else if (session2 && session2.active === false) {
     agentState = "stopped (session paused)";
@@ -45161,10 +45197,55 @@ async function status() {
 }
 
 // src/commands/ui.ts
-var import_node_child_process4 = require("node:child_process");
+var import_node_child_process5 = require("node:child_process");
 var import_node_fs20 = __toESM(require("node:fs"), 1);
 var import_node_net2 = __toESM(require("node:net"), 1);
 var import_node_path16 = __toESM(require("node:path"), 1);
+
+// src/lib/tailscale.ts
+var import_node_child_process4 = require("node:child_process");
+function tailscaleAvailable() {
+  try {
+    return (0, import_node_child_process4.spawnSync)("tailscale", ["version"], { stdio: "ignore" }).status === 0;
+  } catch {
+    return false;
+  }
+}
+function tailnetDnsName() {
+  const r = (0, import_node_child_process4.spawnSync)("tailscale", ["status", "--json"], { encoding: "utf-8" });
+  if (r.status !== 0 || !r.stdout) return null;
+  try {
+    const j = JSON.parse(r.stdout);
+    if (j.BackendState && j.BackendState !== "Running") return null;
+    const dns = j.Self?.DNSName;
+    if (typeof dns !== "string" || dns.length === 0) return null;
+    return dns.replace(/\.$/, "");
+  } catch {
+    return null;
+  }
+}
+function tailscaleServeUp(port) {
+  const r = (0, import_node_child_process4.spawnSync)(
+    "tailscale",
+    ["serve", "--bg", "--https=443", `http://127.0.0.1:${port}`],
+    { encoding: "utf-8" }
+  );
+  const out = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+  if (r.status !== 0) {
+    throw new Error(out.trim() || `exit ${r.status ?? "?"}`);
+  }
+  if (/serve is not enabled/i.test(out)) {
+    throw new Error(out.trim());
+  }
+}
+function tailscaleServeDown() {
+  try {
+    (0, import_node_child_process4.spawnSync)("tailscale", ["serve", "--https=443", "off"], { stdio: "ignore" });
+  } catch {
+  }
+}
+
+// src/commands/ui.ts
 var UI_STATE_FILE = import_node_path16.default.join(".sail", "runtime", "ui.json");
 function readState2(projectRoot) {
   const file = import_node_path16.default.join(projectRoot, UI_STATE_FILE);
@@ -45175,21 +45256,33 @@ function readState2(projectRoot) {
     return null;
   }
 }
-function isAlive(pid) {
+function installedCliVersion() {
   try {
-    process.kill(pid, 0);
-    return true;
+    const pkg = JSON.parse(
+      import_node_fs20.default.readFileSync(import_node_path16.default.join(packageRoot(), "package.json"), "utf-8")
+    );
+    return pkg.version ?? null;
   } catch {
-    return false;
+    return null;
   }
 }
-function findFreePort(from14) {
-  return new Promise((resolve3, reject) => {
-    const server = import_node_net2.default.createServer();
-    server.unref();
-    server.on("error", () => findFreePort(from14 + 1).then(resolve3, reject));
-    server.listen(from14, "127.0.0.1", () => server.close(() => resolve3(from14)));
-  });
+async function warnIfVersionSkew(port) {
+  const cli = installedCliVersion();
+  if (!cli) return;
+  try {
+    const res = await fetch(`http://127.0.0.1:${port}/api/version`, {
+      signal: AbortSignal.timeout(500)
+    });
+    if (!res.ok) return;
+    const { running } = await res.json();
+    if (running && running !== cli) {
+      console.warn(
+        `\u26A0 Version skew: the running dashboard is v${running}, but the installed CLI is v${cli}.
+  Restart it to load the new version:  sailor ui stop && sailor ui start`
+      );
+    }
+  } catch {
+  }
 }
 function waitForPort(port, timeoutMs) {
   const deadline = Date.now() + timeoutMs;
@@ -45209,7 +45302,7 @@ function waitForPort(port, timeoutMs) {
     attempt();
   });
 }
-async function uiCommand() {
+async function uiCommand(opts = {}) {
   const distDir = cliDistDir();
   const uiDistDir = import_node_path16.default.join(packageRoot(), "packages", "ui", "dist");
   const serverBundle = import_node_path16.default.resolve(distDir, "server.cjs");
@@ -45223,19 +45316,49 @@ async function uiCommand() {
   if (!import_node_fs20.default.existsSync(import_node_path16.default.join(uiDistDir, "index.html"))) {
     throw new Error(`UI dist not found at ${uiDistDir}. Re-run the sailor build.`);
   }
+  let tailnetUrl = null;
+  if (opts.expose) {
+    if (opts.expose !== "tailscale") {
+      throw new Error(`Unknown --expose mode "${opts.expose}". Supported: tailscale.`);
+    }
+    if (!tailscaleAvailable()) {
+      throw new Error(
+        "tailscale CLI not found. Install Tailscale and run `tailscale up`, or start the dashboard without --expose to keep it local-only."
+      );
+    }
+    const dns = tailnetDnsName();
+    if (!dns) {
+      throw new Error(
+        "Could not resolve this node's tailnet name. Is tailscale running and logged in? Run `tailscale status` to check."
+      );
+    }
+    tailnetUrl = `https://${dns}`;
+  }
   const existing = readState2(projectRoot);
-  if (existing && isAlive(existing.pid)) {
+  if (existing && isProcessAlive(existing.pid)) {
     console.log(`Sailor UI is already running (pid ${existing.pid}) at http://localhost:${existing.port}`);
+    if (opts.expose) {
+      console.log("To expose it on the tailnet, stop it first: sailor ui stop && sailor ui start --expose tailscale");
+    }
+    await warnIfVersionSkew(existing.port);
     return;
   }
   const runtimeDir = import_node_path16.default.join(projectRoot, ".sail", "runtime");
   import_node_fs20.default.mkdirSync(runtimeDir, { recursive: true });
   const logFile = import_node_path16.default.join(runtimeDir, "ui.log");
   const logFd = import_node_fs20.default.openSync(logFile, "a");
-  const child = (0, import_node_child_process4.spawn)(process.execPath, [serverBundle], {
+  const corsOrigins = [process.env.SAILOR_CORS_ORIGINS, tailnetUrl].filter(Boolean).join(",");
+  const child = (0, import_node_child_process5.spawn)(process.execPath, [serverBundle], {
     detached: true,
     stdio: ["ignore", logFd, logFd],
-    env: { ...process.env, SAIL_DIR: sailDir2, SERVE_DIST: "1", PORT: String(port), SAILOR_UI_DIST: uiDistDir }
+    env: {
+      ...process.env,
+      SAIL_DIR: sailDir2,
+      SERVE_DIST: "1",
+      PORT: String(port),
+      SAILOR_UI_DIST: uiDistDir,
+      ...corsOrigins ? { SAILOR_CORS_ORIGINS: corsOrigins } : {}
+    }
   });
   child.unref();
   import_node_fs20.default.closeSync(logFd);
@@ -45243,7 +45366,7 @@ async function uiCommand() {
   const deadline = Date.now() + READY_TIMEOUT_MS;
   let ready = false;
   while (Date.now() < deadline) {
-    if (!isAlive(child.pid)) break;
+    if (!isProcessAlive(child.pid)) break;
     if (await waitForPort(port, 500)) {
       ready = true;
       break;
@@ -45262,17 +45385,31 @@ Server output:
 ${tail}` : ` See ${import_node_path16.default.relative(projectRoot, logFile)}.`)
     );
   }
+  let exposed = false;
+  if (tailnetUrl) {
+    try {
+      tailscaleServeUp(port);
+      exposed = true;
+    } catch (err) {
+      console.warn(
+        `\u26A0 Could not expose on the tailnet: ${err.message}
+  The dashboard is still running locally.`
+      );
+    }
+  }
   import_node_fs20.default.writeFileSync(
     import_node_path16.default.join(projectRoot, UI_STATE_FILE),
-    JSON.stringify({ pid: child.pid, port, startedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
+    JSON.stringify({ pid: child.pid, port, startedAt: (/* @__PURE__ */ new Date()).toISOString(), exposed }, null, 2)
   );
   console.log(`Sailor UI started at http://localhost:${port}  (pid ${child.pid})`);
+  if (exposed) console.log(`Exposed on your tailnet at ${tailnetUrl}/`);
   console.log(`Stop it with: sailor ui stop`);
 }
-function uiStatus() {
+async function uiStatus() {
   const state = readState2(process.cwd());
-  if (state && isAlive(state.pid)) {
+  if (state && isProcessAlive(state.pid)) {
     console.log(`\u25CF running  http://localhost:${state.port}  (pid ${state.pid})`);
+    await warnIfVersionSkew(state.port);
   } else {
     if (state) import_node_fs20.default.rmSync(import_node_path16.default.join(process.cwd(), UI_STATE_FILE), { force: true });
     console.log("\u25CB Sailor UI is not running");
@@ -45285,12 +45422,16 @@ function uiStop() {
     console.log("Sailor UI is not running.");
     return;
   }
-  if (!isAlive(state.pid)) {
+  if (!isProcessAlive(state.pid)) {
     import_node_fs20.default.rmSync(import_node_path16.default.join(projectRoot, UI_STATE_FILE), { force: true });
     console.log("Sailor UI is not running (stale state file removed).");
     return;
   }
   process.kill(state.pid, "SIGTERM");
+  if (state.exposed) {
+    tailscaleServeDown();
+    console.log("Tailnet exposure removed.");
+  }
   import_node_fs20.default.rmSync(import_node_path16.default.join(projectRoot, UI_STATE_FILE), { force: true });
   console.log(`Stopped Sailor UI (pid ${state.pid}).`);
 }
@@ -45342,7 +45483,7 @@ program2.command("init [dir]").description("Scaffold a new Sail agent into the c
 );
 program2.command("update").description("Re-sync agent tooling files (skills, AGENTS.md, Dockerfile) from the latest template").action(action(updateCommand));
 var ui = program2.command("ui").description("Manage the local Sailor dashboard");
-ui.command("start").description("Start the dashboard at localhost:3333 (default)").action(action(uiCommand));
+ui.command("start").description("Start the dashboard at localhost:3333 (default)").option("--expose <mode>", "Expose the dashboard over HTTPS on your tailnet (mode: tailscale)").action(actionWith(uiCommand));
 ui.command("stop").description("Stop the running dashboard").action(() => uiStop());
 ui.command("status").description("Show whether the dashboard is running").action(() => uiStatus());
 ui.action(action(uiCommand));
@@ -45407,8 +45548,8 @@ program2.command("run").description("Run the agent execution loop (use --once fo
 var trigger = program2.command("trigger").description("Wake the agent on demand from an external system");
 trigger.command("github").description("Fire the agent's GitHub Actions workflow_dispatch (the same job the cron runs)").option("--workflow <file>", "Workflow file to dispatch", "agent-tick.yml").option("--ref <branch>", "Git ref to run the workflow on", "main").option("--reason <text>", "Why this run fired \u2014 recorded as the workflow's reason input").option("--repo <owner/repo>", "Override the repository (default: from the git origin remote)").option("--json", "Emit machine-readable JSON").action(actionWith(triggerGithub));
 var session = program2.command("session").description("Control the agent session");
-session.command("pause").description("Pause the agent session (revoke dispatch rights)").action(action(sessionPause));
-session.command("resume").description("Resume a paused session").action(action(sessionResume));
+session.command("pause").description("Pause the agent session (revoke dispatch rights)").option("--json", "Emit machine-readable JSON").action(actionWith(sessionPause));
+session.command("resume").description("Resume a paused session").option("--json", "Emit machine-readable JSON").action(actionWith(sessionResume));
 program2.command("doctor").description(
   "Preflight (read-only): kernel model, permission health, RPC + gas balances, before spending gas"
 ).option("--json", "Output machine-readable JSON").option("--account <address>", "SMA to check (defaults to .sail/account.json)").action(actionWith(doctor));