@dev.sail.money/sailor 0.0.2

package/AGENTS.md

@@ -0,0 +1,111 @@
+# Sailor — Codebase Guide
+
+Sailor is the operator toolkit for Sail Protocol. It does **not** deploy the protocol or author
+permission templates — it targets already-deployed SailKernel instances and gives operators the
+tooling to create SMAs, register permission contracts, and run strategy agents.
+
+## Repo structure
+
+| Package / path | Name | Role |
+|---|---|---|
+| `packages/sdk` | `@sail/sdk` | SailorClient, LocalKeyring, kernel ABIs, EIP-712 builders, deployment registry |
+| `packages/cli` | `sailor` | CLI: init, keys, account, mandate, onboard, station, ui, run, session, scan, status, owner, doctor, capabilities |
+| `packages/chains` | `@sail/chains` | Per-chain address registry (kernel, mandateFactory, governance) |
+| `packages/ui` | `sailor-ui` | Local dashboard + browser-driven onboarding wizard at localhost:3333 |
+| `templates/dca-rebalancer` | — | Default project scaffold: DCA rebalancer + Foundry workspace |
+| `templates/custom-mandate` | — | Solidity reference: IPermission scaffold (not a project template) |
+
+## Protocol roles
+
+The code uses internal identifiers that differ from user-facing terms:
+
+| User-facing term | Code identifier | Meaning |
+|---|---|---|
+| Owner | `owner` | Holds the Safe; custody anchor; never touches the agent runtime |
+| Mandate signer | `permissionSigner` | Authorizes permission registration via EIP-712 |
+| Agent wallet | `manager` | Signs dispatches; key at `.sail/keys/manager.json` |
+
+Use the user-facing terms in all CLI output, prompts, and errors. The code identifiers are internal.
+
+## Dispatch model
+
+Active kernels vary by chain — verified on-chain via `DISPATCH_TYPEHASH()`:
+
+| Chain | Kernel | Model | DISPATCH_TYPEHASH |
+|---|---|---|---|
+| Base 8453 | `0x6319d3dfDDe3804ba93D65752b00c52bFb05a1ab` | **selective** | `0xbe50c539...` |
+| Base Sepolia 84532 | `0xf1D0F4C9893612627409948BAa9d82a01a373799` | **selective** | `0xbe50c539...` |
+| Arbitrum 42161 | `0x2716B12832DED0EF5688519c5Fe069EFc0374E02` | **selective** | `0xbe50c539...` |
+| Unichain 130 | `0xD985029960a9B7C2E7E38e102C448b8b8539B156` | **selective** | `0xbe50c539...` |
+
+All four kernels are live and bootstrapped (genesis allowlist set, `createAccount` verified working, zero fees). Unichain (130) additionally has the full permission-template suite deployed and source-verified (7 shared + 12 standalone) — it is the only chain with templates so far; the other three have core only. `packages/sdk/src/deployments.ts` is the canonical source of truth for kernel addresses, templates, and metadata.
+
+**Always use `detectKernelCapabilities` for the real model** — it reads the on-chain typehash and
+overrides the static label in `deployments.ts`. The static label is a fallback for offline use only.
+
+Type strings:
+```
+conjunctive: Dispatch(address account,address target,uint256 value,bytes32 dataHash,uint256 nonce,uint256 deadline)
+selective:   Dispatch(address account,address permission,address target,uint256 value,bytes32 dataHash,uint256 nonce,uint256 deadline)
+
+conjunctive RegisterPermission: RegisterPermission(address account,address permission,uint256 nonce)
+selective   RegisterPermission: RegisterPermission(address account,address permission,uint256 nonce,uint256 deadline)
+```
+
+`buildRegisterPermissionTypedData` accepts `hasDeadline` from `KernelCapabilities.registerPermissionHasDeadline`.
+Pass the detected value — never hardcode the type shape.
+
+## Active addresses
+
+All four chain records in `packages/sdk/src/deployments.ts` are live — no commented-out or pending
+addresses remain. This file is the source of truth this guide mirrors.
+
+- `packages/sdk/src/deployments.ts` — `SailDeployment` records; canonical source of truth
+- `packages/chains/src/index.ts` — `ChainConfig` per chainId; kept in sync with deployments
+
+## Key files
+
+| File | What it owns |
+|---|---|
+| `packages/sdk/src/deployments.ts` | Active + PENDING addresses, `dispatchModel` per chain |
+| `packages/sdk/src/capabilities.ts` | On-chain typehash detection; capability cache |
+| `packages/sdk/src/eip712.ts` | `buildRegisterPermissionTypedData`, `REGISTER_PERMISSION_TYPES` |
+| `packages/cli/src/commands/onboard.ts` | SMA creation + permission registration flow |
+| `packages/cli/src/commands/mandate-contracts.ts` | Deploy / attach / revoke permission contracts |
+| `packages/cli/src/lib/mandates.ts` | `MandateStore` — `.sail/state/mandates.json` source of truth |
+| `packages/ui/server.js` | Local API + WebSocket proxy; signing station relay |
+
+## Build
+
+```bash
+pnpm install
+pnpm build        # builds all packages; dependency order: sdk → chains → cli → ui
+```
+
+Build order matters — `cli` imports from `sdk` and `chains`.
+
+## Test
+
+```bash
+pnpm test         # vitest — no chain needed, ~1.3s
+pnpm test:ui      # playwright — requires pnpm build first
+```
+
+Test fixtures live in `packages/ui/test/fixtures/` — isolated directories with pre-canned `.sail/`
+state; no real RPC needed.
+
+## Conventions
+
+- `SAIL_DIR` — env var pointing to the project's `.sail/` directory (used by the UI server)
+- `SAIL_PASSPHRASE` — unlocks `.sail/keys/manager.json` headlessly; read from `.sail/.env.local`
+- `SERVE_DIST=1` — makes the UI server serve the built React app at `/`
+- All CLI commands support `--json` for machine-readable output
+- Addresses in `.sail/` files stored checksummed; bigints as decimal strings
+
+## What NOT to do
+
+- Do not change active kernel/mandateFactory/governance addresses without confirming on-chain state
+- Do not use conjunctive EIP-712 type strings in new code
+- Do not add new root-level markdown files to this repo
+- Always run `pnpm build` before `pnpm test:ui`
+- Do not commit `SAIL_PASSPHRASE` or private keys

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alejandro Dopico 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,337 @@
+# Sailor
+
+> A toolkit for building and operating Sail Protocol SMAs with AI agents.
+
+Sailor is the operator layer for [Sail Protocol](../SailProtocol): the tooling an agent builder uses to create a Separately Managed Account, bound it with permissions, and run a strategy against it. It wraps the on-chain primitives — SailKernel dispatch, MandateFactory registration, EIP-712 mandate signing — behind a TypeScript SDK, a CLI, and a local dashboard. An agent is an async function that receives context and returns intended transactions; Sailor previews each through the kernel, executes the approved ones, and records what happened. It does not deploy the protocol or author new permission templates — that lives in Sail Protocol. It sits one level up: turning a deployed SailKernel into something an operator can actually drive.
+
+---
+
+## What's inside
+
+| Package | Name | Role |
+|---|---|---|
+| `packages/sdk` | `@sail/sdk` | TypeScript library wrapping SailKernel and MandateFactory |
+| `packages/cli` | `sailor` | CLI for account setup, mandate signing, and agent execution |
+| `packages/chains` | `@sail/chains` | Per-chain address registry (EVM-compatible) |
+| `packages/ui` | `sailor-ui` | Local dashboard running on localhost:3333 |
+| `templates/dca-rebalancer` | — | Starter template: DCA portfolio rebalancer (default for `sailor init`) |
+| `templates/custom-mandate` | — | Solidity reference: allowlist mandate contracts (not a project template) |
+| `templates/lifi-permissions` | — | Solidity reference: LiFi clone permission contracts (not a project template) |
+
+---
+
+## How it works
+
+The path from nothing to a running agent is seven steps:
+
+1. **Generate keys** — a manager key (the agent's dispatch signer) and a permissionSigner key, both generated and encrypted on disk.
+2. **Deploy SMA** — a Safe registered with SailKernel, with the manager and permissionSigner addresses set at registration.
+3. **Write a strategy** — an async `tick` function that receives a context and returns a list of intended dispatches.
+4. **Sign a mandate** — a set of registered permissions that bound what the agent can do, authorized via EIP-712 by the permission signer through MetaMask or a local key.
+5. **Dry-run** — the kernel's `previewBatch` confirms the named permission passes before anything executes on-chain.
+6. **Run the agent** — locally on a cron schedule, or via GitHub Actions on a timer.
+7. **Monitor** — the local dashboard on localhost:3333 reflects live mandate state, agent status, and activity.
+
+---
+
+## Roles
+
+Sailor operates the three roles Sail Protocol separates:
+
+| Role | Authority | Held by |
+|---|---|---|
+| **Owner** | Holds the Safe. Custody anchor. | The LP (Safe owner) — same wallet as MetaMask |
+| **Permission Signer** | Signs mandate registration and revocation via EIP-712. | Same as Owner, or a separate key |
+| **Manager** | Executes dispatches within permitted bounds. Signs each dispatch. | The agent key — encrypted in `.sail/keys/manager.json` |
+
+---
+
+## Installation
+
+### Start a new agent project (recommended)
+
+Open your AI coding assistant and run in its terminal:
+
+```sh
+npx sailor init my-agent
+```
+
+Then say **"start"** — your assistant takes it from there.
+
+### Global CLI (for direct sailor commands)
+
+```sh
+npm install -g @sail.money/sailor
+sailor init my-agent
+```
+
+---
+
+## Quickstart
+
+Prerequisites:
+
+- Node.js 18+ (the CLI runs on 18; `pnpm install` needs Node 22+)
+- A wallet (MetaMask or Rabby)
+- An RPC URL (e.g. Alchemy free tier)
+- A supported chain: **Base, Base Sepolia, Arbitrum, or Unichain** — these use the verified deployments bundled in `@sail/sdk`, so no `@sail/chains` entry is needed. Other chains require kernel + mandateFactory addresses in `@sail/chains` (see [State of the project](#state-of-the-project)).
+
+```bash
+npx sailor init my-agent && cd my-agent
+npm install                    # or `pnpm install` (needs Node 22+)
+
+# 1. Ground yourself — read-only, no gas, no wallet:
+sailor capabilities            # what you can build on this chain
+sailor doctor                  # kernel model + RPC reachability + gas balances
+
+# 2. Set up the account in the browser wizard (choose chain, connect wallet,
+#    generate the agent key, deploy your SMA):
+sailor ui start                # open http://localhost:3333 and follow steps 1–4
+
+# 3. Back in the terminal: configure .sail/.env.local, fund the agent key for gas,
+sailor mandate prepare         # draft permissions → approve in the browser
+sailor run                     # start the agent (use --once for a single tick)
+```
+
+The SMA is deployed through the browser wizard (it submits from your wallet), not a
+terminal command — see the scaffolded project's `AGENTS.md` for the full 8-step flow.
+
+---
+
+## Templates
+
+`sailor init` scaffolds a new agent project from a template. By default it
+writes into the **current directory**; pass a name to create a subdirectory.
+
+```bash
+sailor init                              # scaffold into cwd
+sailor init my-agent                     # create ./my-agent/ and scaffold there
+sailor init --template dca-rebalancer    # explicit (same as default)
+sailor init my-agent --template <name>   # named subdirectory + specific template
+```
+
+### Available templates
+
+| Template | Description |
+|---|---|
+| `dca-rebalancer` | Dollar-cost-averaging portfolio rebalancer. Includes a full agent loop, Foundry workspace for permission contracts, GitHub Actions cron job, and the operator guide (`AGENTS.md`). **Default.** |
+
+### What makes a valid template
+
+A valid template is any directory under `templates/` that contains a
+`package.json`. Directories without one (e.g. `custom-mandate`,
+`lifi-permissions`) are Solidity reference sources, not project scaffolds, and
+are excluded from the available list.
+
+### Adding a template
+
+1. Create a directory under `templates/<your-template-name>/`.
+2. Add a `package.json` (the `name` field is patched to the project name on
+   init).
+3. Add a `.sail/` workspace structure if the agent needs local state.
+4. The template will appear automatically in `sailor init --template <name>`.
+
+Template files are bundled into the published `sailor` npm package via the
+`files` field in the root `package.json`.
+
+---
+
+## Dashboard (`sailor ui`)
+
+The Sailor dashboard is a local React app served at `http://localhost:3333`.
+It shows live account state, mandate health, signer balances, and recent
+activity — all read from the project's `.sail/` directory with no hosted
+backend.
+
+### Commands
+
+```bash
+sailor ui             # start the dashboard (same as sailor ui start)
+sailor ui start       # start the dashboard at http://localhost:3333
+sailor ui stop        # stop the running dashboard
+sailor ui status      # show whether the dashboard is running + pid
+```
+
+### How it works
+
+`sailor ui start` spawns a bundled Express server (`server.cjs`) that:
+
+- Serves the pre-built React UI as static files on `/`
+- Exposes a local API on `/api` that reads `.sail/` state from the current
+  working directory
+
+The server PID is written to `.sail/runtime/ui.json` on start. `sailor ui stop`
+reads that file, sends `SIGTERM` to the server process, and removes the file.
+This means you can start the dashboard in one terminal and stop it from another.
+
+### Running in the background
+
+```bash
+# macOS / Linux
+sailor ui start &
+sailor ui status      # ● running  http://localhost:3333  (pid 12345)
+sailor ui stop        # Stopped Sailor UI (pid 12345).
+
+# Windows (PowerShell)
+Start-Job { sailor ui start }
+sailor ui status
+sailor ui stop
+```
+
+---
+
+## Agent-driven onboarding & custom mandates
+
+For chains with a bundled Sail deployment (Base, Base Sepolia, Arbitrum, Unichain — shipped
+in `@sail/sdk`, no `@sail/chains` entry required), an agent can drive the whole
+setup through a browser **signing station**. The station is a local HTTP +
+WebSocket daemon that bridges the CLI and the owner's wallet: the agent never
+holds the owner key — it pushes signing requests, the owner approves them in the
+browser, and the agent submits the transactions it's allowed to.
+
+```bash
+sailor keys generate                       # manager (agent) key
+sailor station start &                      # signing daemon (serves the UI)
+# owner opens the printed URL once and connects their wallet
+sailor owner connect                        # detect & persist the owner
+sailor scan                                 # discover the owner's Safes + state
+sailor onboard --new-sma                    # create an SMA + (optionally) attach a mandate
+```
+
+Agents author their own permission contracts and deploy them from the scaffolded
+Foundry workspace (`mandates/`, with `@sail/interfaces/IPermission.sol` vendored
+under `.sail/contracts/`):
+
+```bash
+forge build
+sailor mandate deploy --contract MyMandate \
+  --args '["0xPermissionSigner", ["0xTarget"]]' \
+  --attach --sma 0xSafe
+```
+
+`deploy` emits a contract-creation signing request (the owner signs it in the
+browser); the deployed address is read from the receipt and tracked in
+`.sail/state/mandates.json`. `attach` reads the signer nonce, has the owner sign
+a `RegisterPermission` EIP-712 message, then the agent submits
+`kernel.registerPermission` with the exact registration fee. Every command takes
+`--json` for headless agent use; set `SAIL_PASSPHRASE` to unlock the manager key
+non-interactively.
+
+---
+
+## Architecture
+
+```
+   ┌────────────────────┐                          ┌────────────────────┐
+   │  Permission Signer │                          │    Manager/Agent   │
+   │  MetaMask / local  │                          │ .sail/keys/manager │
+   └─────────┬──────────┘                          └─────────┬──────────┘
+             │                                               │
+             │ EIP-712 mandate                               │ dispatch
+             ▼                                               ▼
+   ┌─────────────────────────────────────────────────────────────────────┐
+   │                            SailKernel                               │
+   │                          (Sail Protocol)                            │
+   └─────────┬───────────────────────┬───────────────────────┬───────────┘
+             │                       │                       │
+             │ registration          │ execution             │ evaluation
+             ▼                       ▼                       ▼
+   ┌────────────────────┐  ┌────────────────────┐  ┌────────────────────┐
+   │   MandateFactory   │  │         Safe       │  │     Permissions    │
+   │  (register perms)  │  │      (custody)     │  │  (named, per-call) │
+   └────────────────────┘  └────────────────────┘  └────────────────────┘
+
+          sailor CLI / @sail/sdk drive both signing paths above.
+          .sail/ (account · mandate · activity) ──→ sailor-ui (localhost:3333)
+```
+
+The CLI and SDK sit between the operator and SailKernel: they build the EIP-712 payloads, submit dispatches, and read kernel state via viem. The permission signer authorizes the mandate — registration runs through MandateFactory — while the manager key signs each dispatch the kernel evaluates against a named permission before executing it through the Safe. All local state — the deployed account, the signed mandate, and the agent's activity log — lives under `.sail/` on disk, which the dashboard reads through a small local server. Sailor never holds the Owner key and runs no hosted backend; the wallet talks to the chain directly.
+
+---
+
+## Security model
+
+- The agent signs dispatches; the kernel evaluates the named permission on every call. A permission returning false or exceeding its gas cap is treated as denial — fail-closed.
+- The Owner key controls the Safe and is never read by Sailor. Mandate signing requires a deliberate action by the permission signer.
+- The manager key is encrypted on disk using geth keystore v3 (scrypt + aes-128-ctr) and is never transmitted.
+- The session can be paused instantly via `sailor session pause` or the dashboard stop button; this does not affect Safe custody.
+
+---
+
+## State of the project
+
+Sailor is functional and published as [`@sail.money/sailor`](https://www.npmjs.com/package/@sail.money/sailor) on npm (v0.0.1). The SDK, CLI, keystore, mandate flows, agent runner, and dashboard are implemented and have been exercised end to end against Base Sepolia.
+
+The Sail Protocol trusted core is deployed on Base, Base Sepolia, Arbitrum, and Unichain as staging deployments for testing ahead of a formal launch. All four run the selective dispatch model, with verified deployments bundled in `@sail/sdk`. These deployments are under an ongoing external audit by [Octane Security](https://octane.security) and are not final — do not use them with funds you are not prepared to lose. Permission templates are not yet deployed against the Base, Arbitrum, and Base Sepolia kernels; **Unichain** ships the full template suite (7 shared + 12 standalone, source-verified) and its template registries in `@sail/sdk` are populated. `@sail/chains` and the remaining template registries will be filled in as templates are deployed on the other chains and at mainnet launch.
+
+---
+
+## Deployments
+
+The Sail Protocol trusted core is live on the following chains as **staging deployments** ahead of a formal launch, bundled in `@sail/sdk`. All run the selective dispatch model with zero fees. Permission templates are not yet deployed against the Base, Arbitrum, and Base Sepolia kernels; **Unichain** ships the full template suite (7 shared + 12 standalone, source-verified on uniscan.xyz) and has its onboarding allowlists seeded at genesis.
+
+### Base (8453)
+
+| Contract | Address |
+|---|---|
+| SailKernel | `0x6319d3dfDDe3804ba93D65752b00c52bFb05a1ab` |
+| SailGovernance | `0x7E897D919872b1587577617ffFC42113679d0C50` |
+| Timelock | `0x8eC3Ca951E193C6E3713A70022454d7A1f083281` |
+| PermissionFactory | `0x7724EACd97C8601d5AC244Aadbf76ad87353Ff31` |
+| StandardFeePolicy | `0x65850a8D5050aeAade68289ff96c4F119a24B82e` |
+| SafeModuleEnabler | `0xC84EdE78f93291A1fab19F51c4c7e938AB302Edf` |
+| Treasury | `0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6` |
+
+### Arbitrum (42161)
+
+| Contract | Address |
+|---|---|
+| SailKernel | `0x2716B12832DED0EF5688519c5Fe069EFc0374E02` |
+| SailGovernance | `0xd6AbB7A1036ADc7958Abffec9Da03450c5a2Ec8e` |
+| Timelock | `0x114CB7110C780f7E3a6093AfE0B52463a569857C` |
+| PermissionFactory | `0x23681A8A4C9819D8EaB37E46B858da6F3c85E683` |
+| StandardFeePolicy | `0xAdfB986D48480bC67a7cF3751d30599161632e0D` |
+| SafeModuleEnabler | `0xabe2a6D03F592BC602cA1dBDCD885ba2493274f9` |
+| Treasury | `0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6` |
+
+### Base Sepolia (84532)
+
+| Contract | Address |
+|---|---|
+| SailKernel | `0xf1D0F4C9893612627409948BAa9d82a01a373799` |
+| SailGovernance | `0xEaD44bC6999E7b00b9b2E11c1660248DC2a30993` |
+| Timelock | `0x97B863e392C9859336788D5Ec454527d33C95B74` |
+| PermissionFactory | `0xdfF6a2272F667cDf78Af4681b9c88A219998db95` |
+| StandardFeePolicy | `0x05570F7973b46Eb9Ed4518422891EFC26BD58b97` |
+| SafeModuleEnabler | `0xB2C2B52d94412e3472C9fb2B52186eA12a935869` |
+| Treasury | `0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6` |
+
+### Unichain (130)
+
+First chain to ship the full permission-template suite (7 shared + 12 standalone, source-verified on [uniscan.xyz](https://uniscan.xyz)). Genesis allowlist bootstrap — onboarding usable without the 48h timelock.
+
+| Contract | Address |
+|---|---|
+| SailKernel | `0xD985029960a9B7C2E7E38e102C448b8b8539B156` |
+| SailGovernance | `0xAb5C90ECfF2763f6f20f8E553E3b8778dD9C349A` |
+| Timelock | `0xd44FbBB37f01e235E0EE5386948F216d36D0CEf2` |
+| PermissionFactory | `0x8edDb62Aa49CeB837abf2653be2d93Ad9Fe6777D` |
+| StandardFeePolicy | `0x7bBA8BE3c01c972757aA4a230A00D58aB600A1F1` |
+| SafeModuleEnabler | `0xFE9227A9F2baf704060c604466df354a5A137b9B` |
+| Treasury | `0xB01dCE443d052e44b7D13726c0EC9fFB7f5815B6` |
+
+The 19 template addresses are in `@sail/sdk` (`knownTemplates` + `standaloneTemplates` for chain 130).
+
+Addresses are sourced from `@sail/sdk` (`packages/sdk/src/deployments.ts`), the canonical registry.
+
+---
+
+## Contributing
+
+Sailor and Sail Protocol are separate repositories with separate concerns. Protocol questions — SailKernel internals, permission templates, MandateFactory, fee policies — belong in the [SailProtocol](../SailProtocol) repository. Sailor questions — the SDK, CLI, dashboard, and agent templates — belong here.
+
+---
+
+## License
+
+MIT

package/docs/PERMISSION_MODEL.md

@@ -0,0 +1,93 @@
+# Sail permission model: conjunctive vs selective
+
+The deployed SailKernel ships in **two incompatible dispatch models**. Which one a
+chain runs changes how dispatches are signed *and* how permissions must be written.
+Get this wrong and every dispatch reverts with an opaque selector. This is the single
+most important thing to understand before operating an SMA.
+
+## TL;DR
+
+| | **Conjunctive** (older) | **Selective** (newer) |
+|---|---|---|
+| Chains today (bundled kernels) | None — all bundled kernels moved to selective | Base (8453), Base Sepolia (84532), Arbitrum (42161), Unichain (130) |
+| `dispatch(...)` | `(account, target, value, data, sig, deadline)` — **no `permission`** | `(account, permission, target, value, data, sig, deadline)` |
+| Which permissions are checked | **ALL** registered permissions; **all must return true** | only the **one** permission named in the call |
+| EIP-712 `Dispatch` struct | no `permission` field | includes `permission` |
+| Batch (`dispatchBatch`/`previewBatch`) | **not available** | available |
+| **Permission design rule** | **MUST pass through calls outside its domain** | may return false freely |
+
+Don't guess from a version string — **detect it on-chain** (see below).
+
+## The conjunctive pass-through rule (the big footgun)
+
+On a conjunctive kernel the kernel calls `evaluate(txData, ctx)` on **every**
+registered permission and ANDs the results. A single `false` blocks the whole
+dispatch (`PermissionDenied`).
+
+So a permission that only cares about, say, approvals **must still return `true` for
+every call it doesn't govern**:
+
+```solidity
+function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+    // Pass through calls outside this permission's domain (conjunctive model).
+    if (ctx.selector != APPROVE) return true;   // <-- without this line, this
+                                                 //     permission bricks swaps,
+                                                 //     transfers, everything.
+    // ...domain-specific checks for approve...
+}
+```
+
+A permission that returns `false` (or reverts, or runs out of gas — both treated as
+`false`) on unrelated calls **bricks the entire account**: no dispatch of any kind
+can pass. We hit exactly this during bring-up with permissions that "blocked each
+other." The fix was to redeploy every permission with pass-through semantics.
+
+Corollary: on a conjunctive kernel you **cannot** have two permissions that each
+enforce a different token's approve — each would reject the other's token. To support
+approving both DAI and USDC you need **one** approve permission that allows both (see
+`templates/lifi-permissions/`), not two narrow ones.
+
+Selective kernels don't have this problem: each dispatch names one permission and
+only that one is consulted.
+
+## Detect the model on-chain
+
+The SDK reads each kernel's public `DISPATCH_TYPEHASH` constant and matches it
+against the canonical hashes for each model. Never assume.
+
+```ts
+const caps = await client.capabilities();
+// caps.dispatchModel: "conjunctive" | "selective"
+// caps.dispatchTypehash, caps.source ("onchain-typehash" | "static-hint")
+```
+
+Verified typehashes:
+
+- conjunctive `DISPATCH_TYPEHASH` = `0x7510c80e…`
+  `Dispatch(address account,address target,uint256 value,bytes32 dataHash,uint256 nonce,uint256 deadline)`
+- selective `DISPATCH_TYPEHASH` =
+  `Dispatch(address account,address permission,address target,uint256 value,bytes32 dataHash,uint256 nonce,uint256 deadline)`
+
+`client.dispatch.single(...)` already signs the correct struct and uses the correct
+ABI for the detected model — you don't sign by hand. `client.dispatch.batch` /
+`preview` throw a clear error on conjunctive kernels (no `dispatchBatch`).
+
+## Roles (unchanged across models)
+
+| Role | Authority |
+|------|-----------|
+| **Owner** | Holds the Safe; custody anchor. |
+| **Permission Signer** | Authorizes which `IPermission` contracts apply (EIP-712 `RegisterPermissions` / `RevokePermissions`). Signed in the browser signing station — the agent never holds this key. |
+| **Manager** | Executes dispatches within the registered permissions (ECDSA / ERC-1271). The agent's hot key. |
+
+## Preflight before spending gas
+
+Run `sailor doctor` (read-only, no gas, no keys):
+
+- detects the dispatch model,
+- lists registered permissions,
+- on a conjunctive kernel, **probes each permission for pass-through** and flags any
+  that would brick dispatch.
+
+See [AGENTS.md](../AGENTS.md) for the operational decision tree and the
+revert failure-mode catalog.

package/examples/permissions/BoundedBet_Limitless_Base.sol

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: MIT
+pragma solidity 0.8.26;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Protocol : Limitless
+// Version  : CTF-based prediction market (on-chain settlement on Base)
+//            NOT Polymarket (Polymarket's CLOB matches orders off-chain on Polygon —
+//            a permission cannot bound the orders your agent signs off-chain.
+//            Limitless settles bets on-chain on Base, so the kernel sees every action.)
+// Chain    : Base mainnet
+//
+// ⚠ WARNING — ABI UNVERIFIED ⚠
+//   The Limitless exchange contract address and bet-placement function signature
+//   below are based on published CTF exchange patterns and public documentation.
+//   They have NOT been independently verified against the deployed contracts.
+//   YOU MUST verify these before deploying with real funds:
+//     1. Find the Limitless exchange contract address on Basescan.
+//     2. Read its verified ABI and confirm the buy/place function signature.
+//     3. Recompute the selector and update SEL_BUY.
+//     4. Confirm the parameter layout matches BetParams below.
+//   Deploying this contract with an unverified ABI may silently PASS or FAIL
+//   all dispatches depending on whether the selector matches.
+//
+// ENFORCED ON-CHAIN (assuming verified ABI — see warning above):
+//   buy(bytes32 conditionId, uint256 amount, uint256 outcomeIndex)
+//   • target must be LIMITLESS_EXCHANGE
+//   • conditionId must be in ALLOWED_CONDITIONS
+//   • amount ≤ MAX_STAKE
+//   • outcomeIndex must be in ALLOWED_OUTCOMES
+//
+// NOT ENFORCED:
+//   • Market price / odds (on-chain prediction market prices fluctuate)
+//   • Timing / frequency of bets
+//
+// VERIFY BEFORE USE:
+//   • Confirm Limitless exchange address on Base (Basescan).
+//   • Confirm buy function signature and compute selector:
+//     keccak256("buy(bytes32,uint256,uint256)")[0:4] == 0x??? — verify on-chain.
+//   • Confirm conditionId encoding matches the deployed market IDs.
+//   • Update this contract if the ABI or parameter order differs.
+// ─────────────────────────────────────────────────────────────────────────────
+
+import {IPermission, Context} from "@sail/interfaces/IPermission.sol";
+
+contract BoundedBet_Limitless_Base is IPermission {
+    bytes32 private constant DISCRIMINATOR = keccak256("BoundedBet_Limitless_Base");
+
+    /// @dev ⚠ UNVERIFIED — replace with verified Limitless exchange address on Base.
+    address public immutable LIMITLESS_EXCHANGE;
+    mapping(bytes32 => bool) public isAllowedCondition;
+    uint256 public immutable MAX_STAKE;
+    mapping(uint256 => bool) public isAllowedOutcome;
+
+    /// @dev ⚠ UNVERIFIED selector. Compute keccak256("buy(bytes32,uint256,uint256)")[0:4]
+    ///      and confirm it matches the deployed Limitless exchange contract before use.
+    bytes4 private constant SEL_BUY = bytes4(keccak256("buy(bytes32,uint256,uint256)"));
+
+    /// @param limitlessExchange  ⚠ VERIFY — Limitless CTF exchange address on Base
+    /// @param allowedConditions  conditionIds (bytes32) of markets the agent may bet on
+    /// @param maxStake           Per-bet stake cap in collateral base units
+    /// @param allowedOutcomes    Outcome indices the agent may select (e.g. [0] for YES only)
+    constructor(
+        address limitlessExchange,
+        bytes32[] memory allowedConditions,
+        uint256 maxStake,
+        uint256[] memory allowedOutcomes
+    ) {
+        LIMITLESS_EXCHANGE = limitlessExchange;
+        MAX_STAKE          = maxStake;
+        for (uint256 i = 0; i < allowedConditions.length; i++) {
+            isAllowedCondition[allowedConditions[i]] = true;
+        }
+        for (uint256 i = 0; i < allowedOutcomes.length; i++) {
+            isAllowedOutcome[allowedOutcomes[i]] = true;
+        }
+    }
+
+    function evaluate(bytes calldata txData, Context calldata ctx) external view returns (bool) {
+        if (ctx.target != LIMITLESS_EXCHANGE) return false;
+        if (ctx.selector != SEL_BUY)          return false;
+        if (txData.length < 4 + 3 * 32)       return false;
+
+        // ⚠ Assumes: buy(bytes32 conditionId, uint256 amount, uint256 outcomeIndex)
+        // Verify parameter order against deployed contract ABI before use.
+        (bytes32 conditionId, uint256 amount, uint256 outcomeIndex) =
+            abi.decode(txData[4:], (bytes32, uint256, uint256));
+
+        if (!isAllowedCondition[conditionId])  return false;
+        if (amount > MAX_STAKE)                return false;
+        if (!isAllowedOutcome[outcomeIndex])   return false;
+
+        return true;
+    }
+
+    function discriminator() external pure returns (bytes32) { return DISCRIMINATOR; }
+}