@dev.sail.money/sailor 1.1.0-61 → 1.1.0-63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev.sail.money/sailor",
-  "version": "1.1.0-61",
+  "version": "1.1.0-63",
   "description": "Operator toolkit for Sail Protocol",
   "bin": {
     "sailor": "packages/cli/dist/index.cjs"

package/packages/cli/dist/index.cjs

@@ -966,8 +966,8 @@ var require_command = __commonJS({
   "../../node_modules/.pnpm/commander@12.1.0/node_modules/commander/lib/command.js"(exports2) {
     var EventEmitter = require("node:events").EventEmitter;
     var childProcess = require("node:child_process");
-    var path8 = require("node:path");
-    var fs9 = require("node:fs");
+    var path9 = require("node:path");
+    var fs10 = require("node:fs");
     var process2 = require("node:process");
     var { Argument: Argument2, humanReadableArgName } = require_argument();
     var { CommanderError: CommanderError2 } = require_error();
@@ -1899,11 +1899,11 @@ Expecting one of '${allowedValues.join("', '")}'`);
         let launchWithNode = false;
         const sourceExt = [".js", ".ts", ".tsx", ".mjs", ".cjs"];
         function findFile(baseDir, baseName) {
-          const localBin = path8.resolve(baseDir, baseName);
-          if (fs9.existsSync(localBin)) return localBin;
-          if (sourceExt.includes(path8.extname(baseName))) return void 0;
+          const localBin = path9.resolve(baseDir, baseName);
+          if (fs10.existsSync(localBin)) return localBin;
+          if (sourceExt.includes(path9.extname(baseName))) return void 0;
           const foundExt = sourceExt.find(
-            (ext) => fs9.existsSync(`${localBin}${ext}`)
+            (ext) => fs10.existsSync(`${localBin}${ext}`)
           );
           if (foundExt) return `${localBin}${foundExt}`;
           return void 0;
@@ -1915,21 +1915,21 @@ Expecting one of '${allowedValues.join("', '")}'`);
         if (this._scriptPath) {
           let resolvedScriptPath;
           try {
-            resolvedScriptPath = fs9.realpathSync(this._scriptPath);
+            resolvedScriptPath = fs10.realpathSync(this._scriptPath);
           } catch (err) {
             resolvedScriptPath = this._scriptPath;
           }
-          executableDir = path8.resolve(
-            path8.dirname(resolvedScriptPath),
+          executableDir = path9.resolve(
+            path9.dirname(resolvedScriptPath),
             executableDir
           );
         }
         if (executableDir) {
           let localFile = findFile(executableDir, executableFile);
           if (!localFile && !subcommand._executableFile && this._scriptPath) {
-            const legacyName = path8.basename(
+            const legacyName = path9.basename(
               this._scriptPath,
-              path8.extname(this._scriptPath)
+              path9.extname(this._scriptPath)
             );
             if (legacyName !== this._name) {
               localFile = findFile(
@@ -1940,7 +1940,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
           }
           executableFile = localFile || executableFile;
         }
-        launchWithNode = sourceExt.includes(path8.extname(executableFile));
+        launchWithNode = sourceExt.includes(path9.extname(executableFile));
         let proc;
         if (process2.platform !== "win32") {
           if (launchWithNode) {
@@ -2780,7 +2780,7 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @return {Command}
        */
       nameFromFilename(filename) {
-        this._name = path8.basename(filename, path8.extname(filename));
+        this._name = path9.basename(filename, path9.extname(filename));
         return this;
       }
       /**
@@ -2794,9 +2794,9 @@ Expecting one of '${allowedValues.join("', '")}'`);
        * @param {string} [path]
        * @return {(string|null|Command)}
        */
-      executableDir(path9) {
-        if (path9 === void 0) return this._executableDir;
-        this._executableDir = path9;
+      executableDir(path10) {
+        if (path10 === void 0) return this._executableDir;
+        this._executableDir = path10;
         return this;
       }
       /**
@@ -30772,9 +30772,9 @@ var init_defineKzg = __esm({
 });
 
 // ../../node_modules/.pnpm/viem@2.51.3_bufferutil@4.1.0_typescript@5.9.3_utf-8-validate@5.0.10_zod@4.4.3/node_modules/viem/_esm/utils/kzg/setupKzg.js
-function setupKzg(parameters, path8) {
+function setupKzg(parameters, path9) {
   try {
-    parameters.loadTrustedSetup(path8);
+    parameters.loadTrustedSetup(path9);
   } catch (e) {
     const error = e;
     if (!error.message.includes("trusted setup is already loaded"))
@@ -35190,8 +35190,8 @@ var require_websocket_server2 = __commonJS({
 });
 
 // src/index.ts
-var import_node_fs18 = require("node:fs");
-var import_node_path14 = require("node:path");
+var import_node_fs19 = require("node:fs");
+var import_node_path15 = require("node:path");
 
 // ../../node_modules/.pnpm/commander@12.1.0/node_modules/commander/esm.mjs
 var import_index = __toESM(require_commander(), 1);
@@ -37123,14 +37123,14 @@ var HDKey = class _HDKey {
     }
     this.pubHash = hash160(this.pubKey);
   }
-  derive(path8) {
-    if (!/^[mM]'?/.test(path8)) {
+  derive(path9) {
+    if (!/^[mM]'?/.test(path9)) {
       throw new Error('Path must start with "m" or "M"');
     }
-    if (/^[mM]'?$/.test(path8)) {
+    if (/^[mM]'?$/.test(path9)) {
       return this;
     }
-    const parts = path8.replace(/^[mM]'?\//, "").split("/");
+    const parts = path9.replace(/^[mM]'?\//, "").split("/");
     let child = this;
     for (const c of parts) {
       const m = /^(\d+)('?)$/.exec(c);
@@ -37462,8 +37462,8 @@ function privateKeyToAccount(privateKey, options = {}) {
 }
 
 // ../../node_modules/.pnpm/viem@2.51.3_bufferutil@4.1.0_typescript@5.9.3_utf-8-validate@5.0.10_zod@4.4.3/node_modules/viem/_esm/accounts/hdKeyToAccount.js
-function hdKeyToAccount(hdKey_, { accountIndex = 0, addressIndex = 0, changeIndex = 0, path: path8, ...options } = {}) {
-  const hdKey = hdKey_.derive(path8 || `m/44'/60'/${accountIndex}'/${changeIndex}/${addressIndex}`);
+function hdKeyToAccount(hdKey_, { accountIndex = 0, addressIndex = 0, changeIndex = 0, path: path9, ...options } = {}) {
+  const hdKey = hdKey_.derive(path9 || `m/44'/60'/${accountIndex}'/${changeIndex}/${addressIndex}`);
   const account2 = privateKeyToAccount(toHex(hdKey.privateKey), options);
   return {
     ...account2,
@@ -37564,8 +37564,8 @@ var LocalKeyring = class _LocalKeyring {
     return _LocalKeyring.fromPrivateKey(`0x${pkBytes.toString("hex")}`);
   }
   /** Loads a keyring from an encrypted JSON keystore file on disk. */
-  static async fromKeystoreFile(path8, password) {
-    const keystore = JSON.parse((0, import_node_fs.readFileSync)(path8, "utf-8"));
+  static async fromKeystoreFile(path9, password) {
+    const keystore = JSON.parse((0, import_node_fs.readFileSync)(path9, "utf-8"));
     return _LocalKeyring.fromKeystore(keystore, password);
   }
   /** Signs a raw 32-byte hash. Returns a 65-byte ECDSA signature. */
@@ -39141,9 +39141,9 @@ var SigningServer = class {
     );
   }
   removeRuntimeState() {
-    const path8 = (0, import_node_path4.join)(this.runtimeDir, SERVER_STATE_FILE);
+    const path9 = (0, import_node_path4.join)(this.runtimeDir, SERVER_STATE_FILE);
     try {
-      if ((0, import_node_fs5.existsSync)(path8)) (0, import_node_fs5.unlinkSync)(path8);
+      if ((0, import_node_fs5.existsSync)(path9)) (0, import_node_fs5.unlinkSync)(path9);
     } catch {
     }
   }
@@ -40557,8 +40557,8 @@ function scaffoldFoundryWorkspace(root) {
   writeIfMissing((0, import_node_path6.join)(root, "mandates", "BoundedCallPermission.sol"), EXAMPLE_MANDATE_SOL);
   writeIfMissing((0, import_node_path6.join)(root, "mandates", "README.md"), MANDATES_README);
 }
-function writeIfMissing(path8, content) {
-  if (!(0, import_node_fs7.existsSync)(path8)) (0, import_node_fs7.writeFileSync)(path8, content, "utf8");
+function writeIfMissing(path9, content) {
+  if (!(0, import_node_fs7.existsSync)(path9)) (0, import_node_fs7.writeFileSync)(path9, content, "utf8");
 }
 
 // src/commands/init.ts
@@ -43604,6 +43604,7 @@ async function runCommand(opts) {
   for (const [k, v] of Object.entries(env)) {
     if (v && !process.env[k]) process.env[k] = v;
   }
+  const runReason = opts.reason ?? process.env.SAIL_RUN_REASON ?? "manual";
   const configChainId = readJsonFile(sailPath("config.json"))?.chainId;
   const chainIdRaw = opts.chain != null ? String(opts.chain) : process.env.CHAIN_ID ?? env.CHAIN_ID ?? (configChainId != null ? String(configChainId) : void 0);
   if (!chainIdRaw) {
@@ -43733,7 +43734,7 @@ Configure the chain in the SDK chain registry or set KERNEL_ADDRESS in .sail/.en
     return d;
   };
   async function runTick() {
-    appendActivity({ ts: nowIso(), actor: "agent", type: "tick_start", chainId });
+    appendActivity({ ts: nowIso(), actor: "agent", type: "tick_start", chainId, reason: runReason });
     let blockInfo = { number: 0n, timestamp: 0n };
     try {
       const block = await publicClient.getBlock();
@@ -43896,6 +43897,7 @@ Configure the chain in the SDK chain registry or set KERNEL_ADDRESS in .sail/.en
   console.log(`Account: ${accountAddr}`);
   console.log(`Chain: ${chainName2} (${chainId})`);
   console.log(once ? "Mode: single tick (--once)" : `Interval: ${intervalSec}s`);
+  console.log(`Reason: ${runReason}`);
   console.log("Press Ctrl+C to stop");
   console.log("");
   writeAgentPid(chainId);
@@ -44042,6 +44044,525 @@ async function scan(options) {
   );
 }
 
+// src/commands/service.ts
+var import_node_child_process2 = require("node:child_process");
+var import_node_fs16 = __toESM(require("node:fs"), 1);
+var import_node_os = __toESM(require("node:os"), 1);
+var import_node_path12 = __toESM(require("node:path"), 1);
+function sanitizeName(raw) {
+  const s = raw.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+  return s || "agent";
+}
+function launchdLabel(projectName) {
+  return `money.sail.${projectName}`;
+}
+function systemdUnitName(projectName) {
+  return `sail-${projectName}.service`;
+}
+function windowsTaskName(projectName) {
+  return `Sail-${projectName}`;
+}
+function runArgs(cfg) {
+  const args = ["run"];
+  if (cfg.chain != null) args.push("--chain", String(cfg.chain));
+  return args;
+}
+function xmlEscape(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function buildLaunchdPlist(cfg) {
+  const label = launchdLabel(cfg.projectName);
+  const args = [cfg.nodePath, cfg.cliEntry, ...runArgs(cfg)];
+  const argXml = args.map((a) => `    <string>${xmlEscape(a)}</string>`).join("\n");
+  const intervalEnv = cfg.interval != null ? `  <key>EnvironmentVariables</key>
+  <dict>
+    <key>SAILOR_INTERVAL</key>
+    <string>${cfg.interval}</string>
+  </dict>
+` : "";
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${label}</string>
+  <key>ProgramArguments</key>
+  <array>
+${argXml}
+  </array>
+  <key>WorkingDirectory</key>
+  <string>${xmlEscape(cfg.projectDir)}</string>
+${intervalEnv}  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>${cfg.restartSec ?? 30}</integer>
+  <key>StandardOutPath</key>
+  <string>${xmlEscape(cfg.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xmlEscape(cfg.logPath)}</string>
+</dict>
+</plist>
+`;
+}
+function buildSystemdUnit(cfg) {
+  const exec = [cfg.nodePath, cfg.cliEntry, ...runArgs(cfg)].map((a) => /\s/.test(a) ? `"${a}"` : a).join(" ");
+  const intervalEnv = cfg.interval != null ? `Environment=SAILOR_INTERVAL=${cfg.interval}
+` : "";
+  return `[Unit]
+Description=Sail agent \u2014 ${cfg.projectName}
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+WorkingDirectory=${cfg.projectDir}
+${intervalEnv}ExecStart=${exec}
+Restart=on-failure
+RestartSec=${cfg.restartSec ?? 30}
+StandardOutput=append:${cfg.logPath}
+StandardError=append:${cfg.logPath}
+
+[Install]
+WantedBy=default.target
+`;
+}
+function buildWindowsTaskXml(cfg) {
+  const runTail = runArgs(cfg).join(" ");
+  const intervalSet = cfg.interval != null ? `set SAILOR_INTERVAL=${cfg.interval}&& ` : "";
+  const inner = `${intervalSet}"${cfg.nodePath}" "${cfg.cliEntry}" ${runTail} >> "${cfg.logPath}" 2>&1`;
+  const args = `/c "${inner}"`;
+  return `<?xml version="1.0" encoding="UTF-16"?>
+<Task version="1.2" xmlns="http://schemas.microsoft.com/windows/2004/02/mit/task">
+  <RegistrationInfo>
+    <Description>Sail agent \u2014 ${xmlEscape(cfg.projectName)}</Description>
+  </RegistrationInfo>
+  <Triggers>
+    <LogonTrigger>
+      <Enabled>true</Enabled>
+    </LogonTrigger>
+  </Triggers>
+  <Settings>
+    <RestartOnFailure>
+      <Interval>PT${cfg.restartSec ?? 30}S</Interval>
+      <Count>999</Count>
+    </RestartOnFailure>
+    <MultipleInstancesPolicy>IgnoreNew</MultipleInstancesPolicy>
+    <DisallowStartIfOnBatteries>false</DisallowStartIfOnBatteries>
+    <StopIfGoingOnBatteries>false</StopIfGoingOnBatteries>
+    <ExecutionTimeLimit>PT0S</ExecutionTimeLimit>
+  </Settings>
+  <Actions>
+    <Exec>
+      <Command>cmd.exe</Command>
+      <Arguments>${xmlEscape(args)}</Arguments>
+      <WorkingDirectory>${xmlEscape(cfg.projectDir)}</WorkingDirectory>
+    </Exec>
+  </Actions>
+</Task>
+`;
+}
+function isTccProtected(projectDir, home = import_node_os.default.homedir()) {
+  const rel = import_node_path12.default.relative(home, import_node_path12.default.resolve(projectDir));
+  if (rel.startsWith("..") || import_node_path12.default.isAbsolute(rel)) return false;
+  const top = rel.split(import_node_path12.default.sep)[0];
+  return ["Desktop", "Documents", "Downloads"].includes(top ?? "");
+}
+function resolveCliEntry() {
+  try {
+    return import_node_fs16.default.realpathSync(process.argv[1]);
+  } catch {
+    return import_node_path12.default.resolve(process.argv[1]);
+  }
+}
+function resolveProjectDir(explicit) {
+  const dir = import_node_path12.default.resolve(explicit ?? process.cwd());
+  if (!import_node_fs16.default.existsSync(import_node_path12.default.join(dir, ".sail"))) {
+    throw new Error(
+      `No .sail/ found in ${dir}.
+Run this from your Sailor project root, or pass --project <path>. (The installer does not search parent directories \u2014 that would risk targeting the wrong project.)`
+    );
+  }
+  return dir;
+}
+function passphraseReadiness(projectDir) {
+  const account2 = (() => {
+    try {
+      return JSON.parse(
+        import_node_fs16.default.readFileSync(import_node_path12.default.join(projectDir, ".sail", "account.json"), "utf-8")
+      );
+    } catch {
+      return null;
+    }
+  })();
+  const prevCwd = process.cwd();
+  let keystorePresent = false;
+  try {
+    process.chdir(projectDir);
+    keystorePresent = keyExists("manager", account2?.safe);
+  } catch {
+    keystorePresent = false;
+  } finally {
+    process.chdir(prevCwd);
+  }
+  const env = parseEnvFile(import_node_path12.default.join(projectDir, ".sail", ".env.local"));
+  const passphraseInEnvFile = Boolean(env.SAIL_PASSPHRASE);
+  return { keystorePresent, passphraseInEnvFile, ready: keystorePresent && passphraseInEnvFile };
+}
+function buildConfig(opts) {
+  const projectDir = resolveProjectDir(opts.project);
+  return {
+    projectName: sanitizeName(import_node_path12.default.basename(projectDir)),
+    projectDir,
+    nodePath: process.execPath,
+    cliEntry: resolveCliEntry(),
+    logPath: import_node_path12.default.join(projectDir, ".sail", "agent.log"),
+    interval: opts.interval != null ? Number(opts.interval) : void 0,
+    chain: opts.chain != null ? Number(opts.chain) : void 0,
+    restartSec: 30
+  };
+}
+function plistPath(projectName) {
+  return import_node_path12.default.join(import_node_os.default.homedir(), "Library", "LaunchAgents", `${launchdLabel(projectName)}.plist`);
+}
+function systemdPath(projectName) {
+  return import_node_path12.default.join(import_node_os.default.homedir(), ".config", "systemd", "user", systemdUnitName(projectName));
+}
+async function serviceInstall(opts = {}) {
+  const cfg = buildConfig(opts);
+  const platform = process.platform;
+  if (platform === "darwin" && isTccProtected(cfg.projectDir)) {
+    const msg = `Project is under a macOS TCC-protected folder (Desktop/Documents/Downloads):
+  ${cfg.projectDir}
+launchd services cannot read those folders, so the agent would silently fail to read .sail/.
+Move the project somewhere like ~/sail/<name>, or re-run with --force to install anyway.`;
+    if (!opts.force) throw new Error(msg);
+    console.warn(`\u26A0 ${msg}
+  Proceeding because --force was given.`);
+  }
+  const pp = passphraseReadiness(cfg.projectDir);
+  if (!pp.ready) {
+    const why = !pp.keystorePresent ? "no agent keystore found" : "SAIL_PASSPHRASE is not in .sail/.env.local";
+    const msg = `Passphrase not resolvable for an unattended service (${why}).
+A service does not inherit your shell env, so SAIL_PASSPHRASE must live in .sail/.env.local (0600).
+Run "sailor keys generate" (and save the passphrase) or set it in .sail/.env.local, then retry. Verify with "sailor doctor".`;
+    if (!opts.force) throw new Error(msg);
+    console.warn(`\u26A0 ${msg}
+  Proceeding because --force was given.`);
+  }
+  import_node_fs16.default.mkdirSync(import_node_path12.default.dirname(cfg.logPath), { recursive: true });
+  if (platform === "darwin") {
+    const plist = buildLaunchdPlist(cfg);
+    const dest = plistPath(cfg.projectName);
+    import_node_fs16.default.mkdirSync(import_node_path12.default.dirname(dest), { recursive: true });
+    import_node_fs16.default.writeFileSync(dest, plist);
+    const uid2 = process.getuid?.() ?? 0;
+    try {
+      try {
+        (0, import_node_child_process2.execFileSync)("launchctl", ["bootout", `gui/${uid2}/${launchdLabel(cfg.projectName)}`], {
+          stdio: "ignore"
+        });
+      } catch {
+      }
+      (0, import_node_child_process2.execFileSync)("launchctl", ["bootstrap", `gui/${uid2}`, dest], { stdio: "inherit" });
+    } catch (err) {
+      throw new Error(`launchctl bootstrap failed: ${err.message}`);
+    }
+    emit(opts.json, () => okInstall(cfg, dest), { status: "ok", platform, unit: dest, ...cfg });
+    return;
+  }
+  if (platform === "linux") {
+    const unit = buildSystemdUnit(cfg);
+    const dest = systemdPath(cfg.projectName);
+    import_node_fs16.default.mkdirSync(import_node_path12.default.dirname(dest), { recursive: true });
+    import_node_fs16.default.writeFileSync(dest, unit);
+    try {
+      (0, import_node_child_process2.execFileSync)("systemctl", ["--user", "daemon-reload"], { stdio: "inherit" });
+      (0, import_node_child_process2.execFileSync)("systemctl", ["--user", "enable", "--now", systemdUnitName(cfg.projectName)], {
+        stdio: "inherit"
+      });
+    } catch (err) {
+      throw new Error(`systemctl --user enable failed: ${err.message}`);
+    }
+    emit(opts.json, () => okInstall(cfg, dest), { status: "ok", platform, unit: dest, ...cfg });
+    return;
+  }
+  if (platform === "win32") {
+    const xml = buildWindowsTaskXml(cfg);
+    const dest = import_node_path12.default.join(import_node_os.default.tmpdir(), `${windowsTaskName(cfg.projectName)}.xml`);
+    import_node_fs16.default.writeFileSync(dest, xml, "utf-8");
+    try {
+      (0, import_node_child_process2.execFileSync)(
+        "schtasks",
+        ["/Create", "/TN", windowsTaskName(cfg.projectName), "/XML", dest, "/F"],
+        { stdio: "inherit" }
+      );
+    } catch (err) {
+      throw new Error(`schtasks /Create failed: ${err.message}`);
+    } finally {
+      try {
+        import_node_fs16.default.rmSync(dest, { force: true });
+      } catch {
+      }
+    }
+    emit(opts.json, () => okInstall(cfg, windowsTaskName(cfg.projectName)), {
+      status: "ok",
+      platform,
+      unit: windowsTaskName(cfg.projectName),
+      ...cfg
+    });
+    return;
+  }
+  throw new Error(`Unsupported platform for service install: ${platform}`);
+}
+function okInstall(cfg, unit) {
+  console.log(`\u2713 Installed Sail agent service for "${cfg.projectName}"`);
+  console.log(`  unit:    ${unit}`);
+  console.log(`  runs:    ${cfg.nodePath} ${cfg.cliEntry} ${runArgs(cfg).join(" ")}`);
+  console.log(`  workdir: ${cfg.projectDir}`);
+  console.log(`  logs:    ${cfg.logPath}   (sailor service logs -f)`);
+  console.log("  The loop runs unattended and restarts on crash.");
+  console.log(
+    "  This is one execution host; you can also wake the agent on demand with `sailor trigger github`."
+  );
+}
+async function serviceStatus(opts = {}) {
+  const projectName = sanitizeName(import_node_path12.default.basename(resolveProjectDir(opts.project)));
+  const platform = process.platform;
+  let installed = false;
+  let running = false;
+  let detail = "";
+  try {
+    if (platform === "darwin") {
+      installed = import_node_fs16.default.existsSync(plistPath(projectName));
+      const uid2 = process.getuid?.() ?? 0;
+      try {
+        detail = (0, import_node_child_process2.execFileSync)("launchctl", ["print", `gui/${uid2}/${launchdLabel(projectName)}`], {
+          encoding: "utf-8",
+          stdio: ["ignore", "pipe", "ignore"]
+        });
+        installed = true;
+        running = /state = running/.test(detail);
+      } catch {
+      }
+    } else if (platform === "linux") {
+      installed = import_node_fs16.default.existsSync(systemdPath(projectName));
+      try {
+        detail = (0, import_node_child_process2.execFileSync)("systemctl", ["--user", "is-active", systemdUnitName(projectName)], {
+          encoding: "utf-8",
+          stdio: ["ignore", "pipe", "ignore"]
+        }).trim();
+      } catch (err) {
+        detail = (err.stdout?.toString() ?? "").trim() || err.message;
+      }
+      running = detail === "active";
+    } else if (platform === "win32") {
+      try {
+        detail = (0, import_node_child_process2.execFileSync)("schtasks", ["/Query", "/TN", windowsTaskName(projectName)], {
+          encoding: "utf-8",
+          stdio: ["ignore", "pipe", "ignore"]
+        });
+        installed = true;
+        running = /Running/.test(detail);
+      } catch (err) {
+        detail = err.message;
+      }
+    }
+  } catch (err) {
+    detail = err.message;
+  }
+  const state = !installed ? "not installed" : running ? "running" : "installed \xB7 idle";
+  emit(
+    opts.json,
+    () => {
+      console.log(`Service "${projectName}": ${state}`);
+      if (detail) console.log(detail.split("\n").slice(0, 8).join("\n"));
+    },
+    { status: "ok", project: projectName, installed, running }
+  );
+}
+async function serviceStop(opts = {}) {
+  const projectName = sanitizeName(import_node_path12.default.basename(resolveProjectDir(opts.project)));
+  const platform = process.platform;
+  if (platform === "darwin") {
+    const uid2 = process.getuid?.() ?? 0;
+    (0, import_node_child_process2.execFileSync)("launchctl", ["bootout", `gui/${uid2}/${launchdLabel(projectName)}`], {
+      stdio: "inherit"
+    });
+  } else if (platform === "linux") {
+    (0, import_node_child_process2.execFileSync)("systemctl", ["--user", "stop", systemdUnitName(projectName)], { stdio: "inherit" });
+  } else if (platform === "win32") {
+    (0, import_node_child_process2.execFileSync)("schtasks", ["/End", "/TN", windowsTaskName(projectName)], { stdio: "inherit" });
+  }
+  emit(opts.json, () => console.log(`\u2713 Stopped service "${projectName}" (not removed).`), {
+    status: "ok",
+    project: projectName,
+    stopped: true
+  });
+}
+async function serviceUninstall(opts = {}) {
+  const projectName = sanitizeName(import_node_path12.default.basename(resolveProjectDir(opts.project)));
+  const platform = process.platform;
+  if (platform === "darwin") {
+    const uid2 = process.getuid?.() ?? 0;
+    try {
+      (0, import_node_child_process2.execFileSync)("launchctl", ["bootout", `gui/${uid2}/${launchdLabel(projectName)}`], {
+        stdio: "ignore"
+      });
+    } catch {
+    }
+    import_node_fs16.default.rmSync(plistPath(projectName), { force: true });
+  } else if (platform === "linux") {
+    try {
+      (0, import_node_child_process2.execFileSync)("systemctl", ["--user", "disable", "--now", systemdUnitName(projectName)], {
+        stdio: "ignore"
+      });
+    } catch {
+    }
+    import_node_fs16.default.rmSync(systemdPath(projectName), { force: true });
+    try {
+      (0, import_node_child_process2.execFileSync)("systemctl", ["--user", "daemon-reload"], { stdio: "ignore" });
+    } catch {
+    }
+  } else if (platform === "win32") {
+    (0, import_node_child_process2.execFileSync)("schtasks", ["/Delete", "/TN", windowsTaskName(projectName), "/F"], {
+      stdio: "inherit"
+    });
+  }
+  emit(opts.json, () => console.log(`\u2713 Uninstalled service "${projectName}".`), {
+    status: "ok",
+    project: projectName,
+    uninstalled: true
+  });
+}
+async function serviceLogs(opts = {}) {
+  const projectDir = resolveProjectDir(opts.project);
+  const logPath = import_node_path12.default.join(projectDir, ".sail", "agent.log");
+  if (!import_node_fs16.default.existsSync(logPath)) {
+    console.log(`No log yet at ${logPath}. The service writes here once it runs.`);
+    return;
+  }
+  if (opts.follow) {
+    if (process.platform === "win32") {
+      console.log(import_node_fs16.default.readFileSync(logPath, "utf-8"));
+      console.log("(follow mode is not supported on Windows here \u2014 re-run to refresh)");
+      return;
+    }
+    (0, import_node_child_process2.execFileSync)("tail", ["-f", logPath], { stdio: "inherit" });
+    return;
+  }
+  const lines = import_node_fs16.default.readFileSync(logPath, "utf-8").split("\n");
+  console.log(lines.slice(-200).join("\n"));
+}
+
+// src/commands/trigger.ts
+var import_node_child_process3 = require("node:child_process");
+var GH_API = "https://api.github.com";
+function parseRepoFromRemoteUrl(url) {
+  const trimmed = url.trim().replace(/\.git$/, "");
+  const m = trimmed.match(/github\.com[/:]([^/]+)\/([^/]+?)$/);
+  return m ? `${m[1]}/${m[2]}` : null;
+}
+function resolveRepo(explicit) {
+  if (explicit) {
+    if (!/^[^/\s]+\/[^/\s]+$/.test(explicit)) {
+      throw new Error(`--repo must be in "owner/repo" form \u2014 got: "${explicit}"`);
+    }
+    return explicit;
+  }
+  let url;
+  try {
+    url = (0, import_node_child_process3.execFileSync)("git", ["remote", "get-url", "origin"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    throw new Error(
+      'Could not read the git remote "origin".\nPass --repo <owner/repo> explicitly.'
+    );
+  }
+  const repo = parseRepoFromRemoteUrl(url);
+  if (!repo) {
+    throw new Error(
+      `Could not parse a GitHub owner/repo from the origin remote (${url}).
+Pass --repo <owner/repo>.`
+    );
+  }
+  return repo;
+}
+function resolveToken() {
+  const token = process.env.SAIL_GH_TOKEN ?? process.env.GITHUB_TOKEN;
+  if (!token) {
+    throw new Error(
+      "No GitHub token found. Set SAIL_GH_TOKEN (or GITHUB_TOKEN) in your environment.\nIt needs the `actions: write` permission on the repo (a fine-grained PAT or a GitHub App token).\nThe token is read from the environment only \u2014 it is never passed as an argument or stored."
+    );
+  }
+  return token;
+}
+function buildDispatchRequest(args) {
+  return {
+    url: `${GH_API}/repos/${args.repo}/actions/workflows/${encodeURIComponent(args.workflow)}/dispatches`,
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${args.token}`,
+      Accept: "application/vnd.github+json",
+      "X-GitHub-Api-Version": "2022-11-28",
+      "User-Agent": "sailor-cli",
+      "Content-Type": "application/json"
+    },
+    body: JSON.stringify({ ref: args.ref, inputs: { reason: args.reason } })
+  };
+}
+async function triggerGithub(options = {}) {
+  const workflow = options.workflow ?? "agent-tick.yml";
+  const ref = options.ref ?? "main";
+  const reason = options.reason ?? "manual";
+  const repo = resolveRepo(options.repo);
+  const token = resolveToken();
+  const req = buildDispatchRequest({ repo, workflow, ref, reason, token });
+  let res;
+  try {
+    res = await fetch(req.url, { method: req.method, headers: req.headers, body: req.body });
+  } catch (err) {
+    throw new Error(`Could not reach GitHub to fire workflow_dispatch: ${err.message}`);
+  }
+  if (res.status === 204) {
+    emit(
+      options.json,
+      () => {
+        console.log(`\u2713 Triggered ${workflow} on ${repo}@${ref}`);
+        console.log(`  reason: ${reason}`);
+        console.log(`  runs:   https://github.com/${repo}/actions/workflows/${workflow}`);
+      },
+      { status: "ok", repo, workflow, ref, reason }
+    );
+    return;
+  }
+  let detail = "";
+  try {
+    detail = await res.text();
+  } catch {
+  }
+  let message = `GitHub returned ${res.status}`;
+  if (res.status === 401) message += " \u2014 bad or expired token";
+  else if (res.status === 403) message += " \u2014 token lacks `actions: write` on this repo";
+  else if (res.status === 404)
+    message += ` \u2014 workflow "${workflow}" or repo "${repo}" not found (or the token can't see it)`;
+  if (detail) {
+    try {
+      const parsed = JSON.parse(detail);
+      if (parsed.message) message += `: ${parsed.message}`;
+    } catch {
+      message += `: ${detail.slice(0, 200)}`;
+    }
+  }
+  throw new Error(message);
+}
+
 // src/commands/session.ts
 function requireAccount() {
   const account2 = readJsonFile(sailPath("account.json"));
@@ -44088,14 +44609,14 @@ async function sessionResume() {
 }
 
 // src/commands/station.ts
-var import_node_fs16 = require("node:fs");
-var import_node_path12 = require("node:path");
-var RUNTIME_SERVER_FILE2 = (0, import_node_path12.join)(".sail", "runtime", "server.json");
+var import_node_fs17 = require("node:fs");
+var import_node_path13 = require("node:path");
+var RUNTIME_SERVER_FILE2 = (0, import_node_path13.join)(".sail", "runtime", "server.json");
 function readState(projectRoot) {
-  const file = (0, import_node_path12.join)(projectRoot, RUNTIME_SERVER_FILE2);
-  if (!(0, import_node_fs16.existsSync)(file)) return null;
+  const file = (0, import_node_path13.join)(projectRoot, RUNTIME_SERVER_FILE2);
+  if (!(0, import_node_fs17.existsSync)(file)) return null;
   try {
-    return JSON.parse((0, import_node_fs16.readFileSync)(file, "utf8"));
+    return JSON.parse((0, import_node_fs17.readFileSync)(file, "utf8"));
   } catch {
     return null;
   }
@@ -44167,9 +44688,9 @@ async function stationStop(options) {
   }
   const daemon = await discoverDaemon(projectRoot);
   if (!daemon) {
-    const file = (0, import_node_path12.join)(projectRoot, RUNTIME_SERVER_FILE2);
+    const file = (0, import_node_path13.join)(projectRoot, RUNTIME_SERVER_FILE2);
     try {
-      if ((0, import_node_fs16.existsSync)(file)) (0, import_node_fs16.rmSync)(file);
+      if ((0, import_node_fs17.existsSync)(file)) (0, import_node_fs17.rmSync)(file);
     } catch {
     }
     emit(options.json, () => console.log("Station process not found; cleared stale state."), {
@@ -44185,9 +44706,9 @@ async function stationStop(options) {
       pid: state.pid
     });
   } catch {
-    const file = (0, import_node_path12.join)(projectRoot, RUNTIME_SERVER_FILE2);
+    const file = (0, import_node_path13.join)(projectRoot, RUNTIME_SERVER_FILE2);
     try {
-      if ((0, import_node_fs16.existsSync)(file)) (0, import_node_fs16.rmSync)(file);
+      if ((0, import_node_fs17.existsSync)(file)) (0, import_node_fs17.rmSync)(file);
     } catch {
     }
     emit(options.json, () => console.log("Station process not found; cleared stale state."), {
@@ -44241,16 +44762,16 @@ async function status() {
 }
 
 // src/commands/ui.ts
-var import_node_child_process2 = require("node:child_process");
-var import_node_fs17 = __toESM(require("node:fs"), 1);
+var import_node_child_process4 = require("node:child_process");
+var import_node_fs18 = __toESM(require("node:fs"), 1);
 var import_node_net2 = __toESM(require("node:net"), 1);
-var import_node_path13 = __toESM(require("node:path"), 1);
-var UI_STATE_FILE = import_node_path13.default.join(".sail", "runtime", "ui.json");
+var import_node_path14 = __toESM(require("node:path"), 1);
+var UI_STATE_FILE = import_node_path14.default.join(".sail", "runtime", "ui.json");
 function readState2(projectRoot) {
-  const file = import_node_path13.default.join(projectRoot, UI_STATE_FILE);
-  if (!import_node_fs17.default.existsSync(file)) return null;
+  const file = import_node_path14.default.join(projectRoot, UI_STATE_FILE);
+  if (!import_node_fs18.default.existsSync(file)) return null;
   try {
-    return JSON.parse(import_node_fs17.default.readFileSync(file, "utf-8"));
+    return JSON.parse(import_node_fs18.default.readFileSync(file, "utf-8"));
   } catch {
     return null;
   }
@@ -44291,15 +44812,15 @@ function waitForPort(port, timeoutMs) {
 }
 async function uiCommand() {
   const distDir = cliDistDir();
-  const uiDistDir = import_node_path13.default.join(packageRoot(), "packages", "ui", "dist");
-  const serverBundle = import_node_path13.default.resolve(distDir, "server.cjs");
+  const uiDistDir = import_node_path14.default.join(packageRoot(), "packages", "ui", "dist");
+  const serverBundle = import_node_path14.default.resolve(distDir, "server.cjs");
   const projectRoot = process.cwd();
-  const sailDir2 = import_node_path13.default.join(projectRoot, ".sail");
+  const sailDir2 = import_node_path14.default.join(projectRoot, ".sail");
   const port = await findFreePort(projectPort(projectRoot));
-  if (!import_node_fs17.default.existsSync(serverBundle)) {
+  if (!import_node_fs18.default.existsSync(serverBundle)) {
     throw new Error(`Server bundle not found at ${serverBundle}. Re-run the sailor build.`);
   }
-  if (!import_node_fs17.default.existsSync(import_node_path13.default.join(uiDistDir, "index.html"))) {
+  if (!import_node_fs18.default.existsSync(import_node_path14.default.join(uiDistDir, "index.html"))) {
     throw new Error(`UI dist not found at ${uiDistDir}. Re-run the sailor build.`);
   }
   const existing = readState2(projectRoot);
@@ -44307,17 +44828,17 @@ async function uiCommand() {
     console.log(`Sailor UI is already running (pid ${existing.pid}) at http://localhost:${existing.port}`);
     return;
   }
-  const runtimeDir = import_node_path13.default.join(projectRoot, ".sail", "runtime");
-  import_node_fs17.default.mkdirSync(runtimeDir, { recursive: true });
-  const logFile = import_node_path13.default.join(runtimeDir, "ui.log");
-  const logFd = import_node_fs17.default.openSync(logFile, "a");
-  const child = (0, import_node_child_process2.spawn)(process.execPath, [serverBundle], {
+  const runtimeDir = import_node_path14.default.join(projectRoot, ".sail", "runtime");
+  import_node_fs18.default.mkdirSync(runtimeDir, { recursive: true });
+  const logFile = import_node_path14.default.join(runtimeDir, "ui.log");
+  const logFd = import_node_fs18.default.openSync(logFile, "a");
+  const child = (0, import_node_child_process4.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 }
   });
   child.unref();
-  import_node_fs17.default.closeSync(logFd);
+  import_node_fs18.default.closeSync(logFd);
   const READY_TIMEOUT_MS = 1e4;
   const deadline = Date.now() + READY_TIMEOUT_MS;
   let ready = false;
@@ -44331,18 +44852,18 @@ async function uiCommand() {
   if (!ready) {
     let tail = "";
     try {
-      tail = import_node_fs17.default.readFileSync(logFile, "utf-8").split("\n").filter(Boolean).slice(-15).join("\n");
+      tail = import_node_fs18.default.readFileSync(logFile, "utf-8").split("\n").filter(Boolean).slice(-15).join("\n");
     } catch {
     }
     throw new Error(
       `Sailor UI failed to start within ${READY_TIMEOUT_MS / 1e3}s on port ${port}.` + (tail ? `
 
 Server output:
-${tail}` : ` See ${import_node_path13.default.relative(projectRoot, logFile)}.`)
+${tail}` : ` See ${import_node_path14.default.relative(projectRoot, logFile)}.`)
     );
   }
-  import_node_fs17.default.writeFileSync(
-    import_node_path13.default.join(projectRoot, UI_STATE_FILE),
+  import_node_fs18.default.writeFileSync(
+    import_node_path14.default.join(projectRoot, UI_STATE_FILE),
     JSON.stringify({ pid: child.pid, port, startedAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
   );
   console.log(`Sailor UI started at http://localhost:${port}  (pid ${child.pid})`);
@@ -44353,7 +44874,7 @@ function uiStatus() {
   if (state && isAlive(state.pid)) {
     console.log(`\u25CF running  http://localhost:${state.port}  (pid ${state.pid})`);
   } else {
-    if (state) import_node_fs17.default.rmSync(import_node_path13.default.join(process.cwd(), UI_STATE_FILE), { force: true });
+    if (state) import_node_fs18.default.rmSync(import_node_path14.default.join(process.cwd(), UI_STATE_FILE), { force: true });
     console.log("\u25CB Sailor UI is not running");
   }
 }
@@ -44365,19 +44886,19 @@ function uiStop() {
     return;
   }
   if (!isAlive(state.pid)) {
-    import_node_fs17.default.rmSync(import_node_path13.default.join(projectRoot, UI_STATE_FILE), { force: true });
+    import_node_fs18.default.rmSync(import_node_path14.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");
-  import_node_fs17.default.rmSync(import_node_path13.default.join(projectRoot, UI_STATE_FILE), { force: true });
+  import_node_fs18.default.rmSync(import_node_path14.default.join(projectRoot, UI_STATE_FILE), { force: true });
   console.log(`Stopped Sailor UI (pid ${state.pid}).`);
 }
 
 // src/index.ts
 function cliVersion() {
   try {
-    const pkg = JSON.parse((0, import_node_fs18.readFileSync)((0, import_node_path14.join)(packageRoot(), "package.json"), "utf-8"));
+    const pkg = JSON.parse((0, import_node_fs19.readFileSync)((0, import_node_path15.join)(packageRoot(), "package.json"), "utf-8"));
     return pkg.version ?? "0.0.0";
   } catch {
     return "0.0.0";
@@ -44462,9 +44983,16 @@ owner.command("connect").description("Open the signing station, wait for your wa
 owner.command("show").description("Show the saved project owner").option("--json", "Emit machine-readable JSON").action(actionWith(ownerShow));
 program2.command("scan").description("Discover the owner's SMAs, their permissions, and local keys; save to context.json").option("--owner <address>", "Owner address to scan (defaults to the saved project owner)").option("--json", "Emit machine-readable JSON").action(actionWith(scan));
 program2.command("status").description("Show current account, permission, and session status").action(action(status));
-program2.command("run").description("Run the agent execution loop (use --once for a single tick)").option("--once", "Run a single tick then exit").option("--chain <chainId>", "Chain ID to run on (overrides CHAIN_ID env and .env.local)").action(async (opts) => {
+program2.command("run").description("Run the agent execution loop (use --once for a single tick)").option("--once", "Run a single tick then exit").option("--chain <chainId>", "Chain ID to run on (overrides CHAIN_ID env and .env.local)").option(
+  "--reason <text>",
+  "Label why this run fired (observability only; also read from SAIL_RUN_REASON)"
+).action(async (opts) => {
   try {
-    await runCommand({ once: opts.once, chain: opts.chain ? Number(opts.chain) : void 0 });
+    await runCommand({
+      once: opts.once,
+      chain: opts.chain ? Number(opts.chain) : void 0,
+      reason: opts.reason
+    });
   } catch (err) {
     console.error(`Error: ${err.message}`);
     closePrompts();
@@ -44472,6 +45000,8 @@ program2.command("run").description("Run the agent execution loop (use --once fo
   }
   closePrompts();
 });
+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));
@@ -44482,6 +45012,14 @@ program2.command("capabilities").description(
   "Feasibility map (read-only): chains, kernel model, mandate templates, strategy primitives"
 ).option("--json", "Emit machine-readable JSON").action(actionWith(capabilities));
 program2.command("chains").description("List supported chains and their SailKernel deployment addresses").option("--verify", "Verify each kernel is deployed via eth_getCode (one RPC call per chain)").option("--json", "Emit machine-readable JSON").action(actionWith(chainsCommand));
+var service = program2.command("service").description(
+  "Run the agent unattended as a local OS service (launchd/systemd/Task Scheduler).\nOne execution host among several \u2014 it runs the loop directly, and composes with\nthe external-trigger seam (`sailor trigger github`) and the cloud cron job."
+);
+service.command("install").description("Install + start the agent as a local service that restarts on crash").option("--interval <s>", "Loop interval in seconds (sets SAILOR_INTERVAL in the unit)").option("--project <path>", "Project root (must contain .sail/; default: current directory)").option("--chain <id>", "Chain ID to run on").option("--force", "Proceed despite a TCC-protected path or unresolved passphrase (with warning)").option("--json", "Emit machine-readable JSON").action(actionWith(serviceInstall));
+service.command("status").description("Show whether the agent service is installed and running").option("--project <path>", "Project root (default: current directory)").option("--json", "Emit machine-readable JSON").action(actionWith(serviceStatus));
+service.command("stop").description("Stop the service without removing it").option("--project <path>", "Project root (default: current directory)").option("--json", "Emit machine-readable JSON").action(actionWith(serviceStop));
+service.command("uninstall").description("Stop and remove the service unit entirely").option("--project <path>", "Project root (default: current directory)").option("--json", "Emit machine-readable JSON").action(actionWith(serviceUninstall));
+service.command("logs").description("Show the agent log (.sail/agent.log); -f to follow").option("--project <path>", "Project root (default: current directory)").option("-f, --follow", "Follow the log (tail -f)").action(actionWith(serviceLogs));
 program2.parse(process.argv);
 /*! Bundled license information:
 

package/packages/sdk/dist/intelligence.d.ts

@@ -5,7 +5,7 @@
  * Do not edit manually — run `pnpm build` to regenerate.
  *
  * Spec version : 1.2.0
- * Generated at : 2026-06-15T17:19:52.072Z
+ * Generated at : 2026-06-15T17:59:04.614Z
  */
 export declare const SAIL_INTELLIGENCE_BASE_URL = "https://api.sail.money";
 export declare const SAIL_INTELLIGENCE_DOCS_URL = "https://api.sail.money/docs";

package/packages/sdk/dist/intelligence.js

@@ -5,7 +5,7 @@
  * Do not edit manually — run `pnpm build` to regenerate.
  *
  * Spec version : 1.2.0
- * Generated at : 2026-06-15T17:19:52.072Z
+ * Generated at : 2026-06-15T17:59:04.614Z
  */
 export const SAIL_INTELLIGENCE_BASE_URL = "https://api.sail.money";
 export const SAIL_INTELLIGENCE_DOCS_URL = "https://api.sail.money/docs";

package/templates/default/.github/workflows/agent-tick.yml

@@ -1,10 +1,35 @@
 name: Agent Tick
 
+# ─────────────────────────────────────────────────────────────────────────────
+# WHEN does your agent run? Two mechanisms — you almost certainly need to tune
+# the first one for your strategy.
+#
+#   1. schedule (cron, below) — a heartbeat / backstop. GitHub Actions cron is
+#      NON-PUNCTUAL: it drifts and is SKIPPED under load, so it is the wrong
+#      PRIMARY driver for anything latency-sensitive. Tune the cadence to your
+#      strategy's volatility:
+#        • LP / perps / liquidations  → minutes — but don't rely on cron for it;
+#          use an external trigger (#2). Here cron is only a safety net.
+#        • DCA / periodic rebalance    → daily.
+#        • treasury / slow rebalances  → hourly to daily.
+#      The default below (hourly) is a GENERIC PLACEHOLDER — change it.
+#
+#   2. workflow_dispatch — an on-demand trigger. Anything that can make an HTTP
+#      call can wake this job the instant a condition is met (a price band, an
+#      on-chain event, a webhook). Fire it from the CLI:  sailor trigger github
+#      This is how you get low-latency reaction that cron cannot give you.
+# ─────────────────────────────────────────────────────────────────────────────
+
 on:
   schedule:
-    # Every Monday at 09:00 UTC
-    - cron: "0 9 * * 1"
+    # Generic placeholder — hourly. TUNE THIS to your strategy (see above).
+    - cron: "0 * * * *"
   workflow_dispatch:
+    inputs:
+      reason:
+        description: "Why this run fired (recorded in the run log for auditability)"
+        required: false
+        default: "manual"
 
 jobs:
   tick:
@@ -30,4 +55,6 @@ jobs:
           RPC_URL: ${{ secrets.RPC_URL }}
           SAIL_PASSPHRASE: ${{ secrets.SAIL_PASSPHRASE }}
           CHAIN_ID: ${{ vars.CHAIN_ID || '8453' }}
+          # Labels the run: the dispatch reason, or "scheduled" for cron runs.
+          SAIL_RUN_REASON: ${{ github.event.inputs.reason || 'scheduled' }}
         run: npx sailor run --once