@haven_ai/cli 0.1.33-alpha.0 → 0.1.35-alpha.0

package/dist/index.js

@@ -1,6 +1,7 @@
 import { rm, mkdir, writeFile, chmod, readFile } from 'fs/promises';
 import { homedir } from 'os';
 import { join, resolve } from 'path';
+import { spawn } from 'child_process';
 
 // src/args.ts
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
@@ -14,24 +15,53 @@ var VALUE_FLAGS = /* @__PURE__ */ new Set([
   "--format",
   "--from",
   "--to",
-  "--company"
+  "--company",
+  "--name",
+  "--budget",
+  "--token",
+  "--period",
+  "--status",
+  "--amount",
+  "--recipient",
+  "--expires"
 ]);
 function parseArgs(argv) {
   const positionals = [];
-  const flags = { json: false, help: false, version: false, yes: false };
+  const flags = {
+    json: false,
+    help: false,
+    version: false,
+    yes: false,
+    noWait: false,
+    run: false,
+    wait: false,
+    hashes: false
+  };
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
     if (arg === "--json") flags.json = true;
     else if (arg === "--help" || arg === "-h") flags.help = true;
     else if (arg === "--version" || arg === "-v") flags.version = true;
     else if (arg === "--yes" || arg === "-y") flags.yes = true;
+    else if (arg === "--no-wait") flags.noWait = true;
+    else if (arg === "--run") flags.run = true;
+    else if (arg === "--wait") flags.wait = true;
+    else if (arg === "--hashes") flags.hashes = true;
     else if (VALUE_FLAGS.has(arg)) {
       const value = argv[++i];
       if (value === void 0 || value.startsWith("--")) {
         throw new Error(`Missing value for ${arg}`);
       }
       if (arg === "--api") flags.api = value;
-      else if (arg === "--email") flags.email = value;
+      else if (arg === "--name") flags.name = value;
+      else if (arg === "--budget") flags.budget = value;
+      else if (arg === "--token") flags.token = value;
+      else if (arg === "--status") flags.status = value;
+      else if (arg === "--period") {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n < 0) throw new Error("--period must be a whole number of minutes");
+        flags.period = n;
+      } else if (arg === "--email") flags.email = value;
       else if (arg === "--safe") flags.safe = value;
       else if (arg === "--agent") flags.agent = value;
       else if (arg === "--limit") {
@@ -45,6 +75,14 @@ function parseArgs(argv) {
       } else if (arg === "--direction") {
         if (value !== "in" && value !== "out") throw new Error('--direction must be "in" or "out"');
         flags.direction = value;
+      } else if (arg === "--recipient") {
+        flags.recipient = value;
+      } else if (arg === "--amount") {
+        flags.amount = value;
+      } else if (arg === "--expires") {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n <= 0) throw new Error("--expires must be a unix timestamp in seconds");
+        flags.expires = n;
       } else if (arg === "--format") {
         if (value !== "csv" && value !== "sie") throw new Error('--format must be "csv" or "sie"');
         flags.format = value;
@@ -62,21 +100,35 @@ function parseArgs(argv) {
 }
 function helpText() {
   return [
-    "haven \u2014 terminal-native companion to the Haven dashboard",
+    "haven \u2014 set up and run a Haven agent from the terminal. It never signs.",
     "",
     "Usage: haven <command> [subcommand] [options]",
     "",
     "Auth:",
-    "  login [--email <e>]     Sign in (password via prompt or HAVEN_PASSWORD)",
+    "  login                   Sign in. Opens a browser device-code approval by default \u2014",
+    "                          it prints a code and a link, and never asks for a password",
+    "  login --email <e>       Password path instead (prompt, or HAVEN_PASSWORD)",
     "  logout                  Clear the saved session",
-    "  whoami                  Show the signed-in user",
+    "  whoami                  Show the signed-in user, session expiry and API URL",
+    "",
+    "For agents:",
+    "  guide                   Print the agent onboarding runbook (same text as /for-agents.md)",
+    "  agents connect --name <n> --budget <amount> --token USDC --period <minutes>",
+    "                          Create a connection setup; prints the connector command and",
+    "                          the approval link for your human. --run executes it here.",
+    "  agents connect --status <setupId> [--wait]   Read one setup's status",
     "",
     "Read:",
     "  wallets list            List your Haven wallets",
     "  wallets balances [--safe <id|address>]   Token balances for a wallet",
+    "  wallets funding [--safe <id|address>] [--wait]   The paste-ready funding",
+    "                          instruction: what to send, where, on which chain.",
+    "                          --wait polls until the account counts as funded.",
     "  agents list             List your agents",
     "  agents show <id>        Show one agent + its budget",
     "  budget show <agentId>   Show an agent's configured budget",
+    "  budget show <agentId> --hashes   Its delegation hashes \u2014 the second",
+    "                          argument `budget revoke` takes, printed nowhere else",
     "  activity list [--safe <id|address>] [--agent <id>] [--direction in|out] [--limit <n>] [--offset <n>]",
     "  activity export [filters]   Emit CSV to stdout (--format csv, default)",
     "  activity export --format sie [--from <ISO>] [--to <ISO>] [--company <name>]",
@@ -85,19 +137,33 @@ function helpText() {
     "  contacts list           List your address book",
     "",
     "Manage (backend-only \u2014 no on-chain signing):",
-    "  agents pause|resume <id>",
+    "  agents pause <id>             Stop the agent spending; keeps its budget",
+    "  agents resume <id>            Let it spend again",
     "  agents revoke <id> --yes      Permanently revoke an agent",
     "  agents rotate-key <id>        Issue a new API key (shown once)",
     "  agents rename <id> <name>",
     "  wallets rename <id> <name>",
-    "  contacts add <name> <address> | contacts remove <id>",
+    "  contacts add <name> <address>  Save an address under a name",
+    "  contacts remove <id>          Forget one",
+    "",
+    "Budgets (construct-and-hand-off \u2014 the CLI never signs, #2539):",
+    "  budget grant <agentId> --amount <n> --token USDC --period <minutes>",
+    "          [--recipient <address>] [--expires <unix-s>] [--wait]",
+    "        Prints a signing link; the human signs in the dashboard.",
+    "  budget revoke <agentId> <delegationHash> [--wait]",
+    "        Prints a revocation link; the human signs in the dashboard.",
     "",
     "Options:",
-    "  --json                  Machine-readable output (for scripting)",
+    "  --json                  One JSON value on stdout, prose on stderr, on every",
+    "                          command including refusals: { ok: false, error: { code, message, hint? } }",
     "  --yes, -y               Skip the confirmation prompt for destructive actions",
-    "  --api <url>             Backend URL (default: HAVEN_API_URL or http://localhost:3001)",
+    "  --api <url>             Backend URL. Default: HAVEN_API_URL, else Haven's hosted",
+    "                          production backend \u2014 NOT localhost. On any other",
+    "                          deployment an omitted flag connects to production.",
     "  --help, --version",
     "",
+    "Exit codes: 0 ok \xB7 1 failed \xB7 2 usage \xB7 3 not authenticated \xB7 4 refused \xB7 5 network",
+    "",
     "On-chain actions (deploy, budgets, approvers, send) are signed in the",
     "dashboard \u2014 this CLI reads and manages; it never holds your keys."
   ].join("\n");
@@ -106,10 +172,20 @@ function helpText() {
 // src/api.ts
 var CliApiError = class extends Error {
   status;
-  constructor(message, status) {
+  /**
+   * The parsed response body, when there was one (#2526).
+   *
+   * The message is built FROM `body.error` for humans, and the device flow
+   * needs the same value as DATA: `authorization_pending` and `slow_down` are
+   * control signals in a poll loop, and branching on them by matching the
+   * message string would make the loop depend on prose that is free to change.
+   */
+  body;
+  constructor(message, status, body) {
     super(message);
     this.name = "CliApiError";
     this.status = status;
+    this.body = body;
   }
 };
 function createCliApi({ baseUrl, token, fetchImpl = fetch }) {
@@ -138,7 +214,7 @@ function createCliApi({ baseUrl, token, fetchImpl = fetch }) {
     const payload = text ? safeParse(text) : void 0;
     if (!res.ok) {
       const message = (payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string" ? payload.error : null) ?? `Request failed (HTTP ${res.status}).`;
-      throw new CliApiError(message, res.status);
+      throw new CliApiError(message, res.status, payload);
     }
     return payload;
   }
@@ -240,63 +316,344 @@ function toCsv(headers, rows) {
   return lines.join("\r\n");
 }
 
+// src/errors.ts
+var EXIT = {
+  ok: 0,
+  /** Something failed and none of the specific codes below describe it. */
+  failed: 1,
+  /** The command line was wrong: unknown command, missing argument, bad flag. */
+  usage: 2,
+  /** No stored session, or the backend rejected the one we have. Log in again. */
+  notAuthenticated: 3,
+  /** Authenticated, and the backend refused anyway (403, 410, other 4xx). */
+  refused: 4,
+  /** The backend could not be reached at all. */
+  network: 5
+};
+var UsageError = class extends Error {
+  hint;
+  constructor(message, hint) {
+    super(message);
+    this.name = "UsageError";
+    this.hint = hint;
+  }
+};
+var HavenCliError = class extends Error {
+  exit;
+  hint;
+  constructor(message, exit, hint) {
+    super(message);
+    this.name = "HavenCliError";
+    this.exit = exit;
+    this.hint = hint;
+  }
+};
+function toFailure(err) {
+  if (err instanceof UsageError) {
+    return { code: "usage", exit: EXIT.usage, message: err.message, hint: err.hint };
+  }
+  if (err instanceof HavenCliError) {
+    const code = err.exit === EXIT.notAuthenticated ? "not_authenticated" : err.exit === EXIT.refused ? "refused" : err.exit === EXIT.network ? "network" : "failed";
+    return { code, exit: err.exit, message: err.message, hint: err.hint };
+  }
+  if (err instanceof CliApiError) {
+    if (err.status === 0) {
+      return {
+        code: "network",
+        exit: EXIT.network,
+        message: err.message,
+        hint: "Check the network and `--api`, then retry."
+      };
+    }
+    if (err.status === 401) {
+      return {
+        code: "not_authenticated",
+        exit: EXIT.notAuthenticated,
+        message: err.message,
+        hint: "Run `haven login` (or set HAVEN_EMAIL and HAVEN_PASSWORD)."
+      };
+    }
+    if (err.status >= 400 && err.status < 500) {
+      return { code: "refused", exit: EXIT.refused, message: err.message };
+    }
+    return { code: "failed", exit: EXIT.failed, message: err.message };
+  }
+  return { code: "failed", exit: EXIT.failed, message: err instanceof Error ? err.message : String(err) };
+}
+
+// src/output.ts
+function createOutput(json, out, err) {
+  return {
+    json,
+    data(payload, human) {
+      out(json ? JSON.stringify(payload, null, 2) : human());
+    },
+    text(content, meta) {
+      out(json ? JSON.stringify({ ok: true, ...meta, content }, null, 2) : content);
+    },
+    note(line) {
+      if (json) err(line);
+      else out(line);
+    },
+    failure(failure) {
+      const body = {
+        ok: false,
+        error: {
+          code: failure.code,
+          message: failure.message,
+          ...failure.hint ? { hint: failure.hint } : {}
+        }
+      };
+      if (json) out(JSON.stringify(body, null, 2));
+      else err(failure.hint ? `${failure.message}
+${failure.hint}` : failure.message);
+    }
+  };
+}
+
+// src/agent-guidance-text.ts
+var HAVEN_AGENT_RUNBOOK_MD = "# Haven for agents \u2014 set your user up to let you pay\n\nYou are an AI agent whose user has no Haven account yet, or has one but has not connected you.\n\n> Links below are paths on this same host: resolve them against the URL you fetched this file from.\n\n## What Haven is, in three sentences\n\nYour user gives you a **budget on their own account** \u2014 not their wallet, and not a key to their funds. The budget is a delegation they sign, enforced on-chain: a payment over it, to the wrong recipient, or past its expiry is refused at execution time, not by a dashboard promise. Haven constructs and relays the payments; you get an agent credential and a signing key made on your machine, and your user can revoke the budget without you and without Haven.\n\n## The sequence\n\nFour of the six steps are your user's \u2014 each needs a human signature or a human decision. The rest is yours. If they already have a funded account, start at step 3.\n\n1. **HUMAN \u2014 create the account.** Name, email, password, then a passkey (Face ID / Touch ID) or a wallet. Never offer to enter any of it: you must not have their password, and the passkey is bound to their device. With a terminal, `npx @haven_ai/cli login --api <api-url>` afterwards gets you a scoped session for steps 3-4 (that flag or `HAVEN_API_URL`, on the first command \u2014 the session then remembers the backend; **the CLI's built-in default is Haven's hosted production backend**, so on any other deployment an omitted flag connects you somewhere real and wrong rather than failing) \u2014 they approve a code in the browser, you never hold their password. It can set up agents and read the account; it cannot sign, approve a budget, move funds, or rotate any agent's keys.\n2. **HUMAN \u2014 fund it.** USDC only, no ETH: Haven sponsors the gas. `haven wallets funding` prints the address, the amount **and which chain** in one place; without a CLI session, the dashboard's funding card shows the address and amount and its Receive-funds screen names the chain. Read the chain off whichever you used and put it in your message \u2014 never assume one: a testnet deployment and production both call themselves Haven.\n3. **HUMAN \u2014 create the agent, set its budget**, and paste you the **setup prompt** it hands back. With a CLI session (step 1) you can do this step yourself: `haven agents connect --name <n> --budget <amount> --token USDC --period <minutes>` prints the same connector command and approval link; add `--run` to do step 4 too.\n4. **YOU \u2014 run the connector command** in that prompt (below). It makes your signing key locally, registering only the public address.\n5. **HUMAN \u2014 approve the budget** with their passkey, in the Haven tab they created the agent in: it advances to the approval step by itself once your run registers.\n6. **YOU \u2014 verify, then pay.**\n\n## Budget changes later (second token, raise, revoke)\n\nThe first budget rides the setup above. After the agent exists, a CLI session can construct the LATER changes \u2014 a second token, a bigger amount, a recipient pin, a stop \u2014 and hand your user a link; the human still signs, every time:\n\n```\nhaven budget grant <agentId> --amount <n> --token USDC --period <minutes> [--recipient <address>] [--wait]\nhaven budget revoke <agentId> <delegationHash> [--wait]\n```\n\nThe CLI never signs: it prints a dashboard link, your user opens it and signs with their passkey or wallet. `--wait` polls until the human's signature lands. The hash for `revoke` is in `haven agents show <agentId>`.\n\n## Hand-off scripts\n\nSend these as your own message, `<host>` replaced by the host you fetched this file from. Say what you cannot do, not only what they must.\n\n**Before signup** (step 1):\n\n> I can do everything except the parts that need your signature. Please open `<host>/signup?next=/agents&via=agent` \u2014 name, email, password, then a passkey (Face ID / Touch ID) or a wallet. That is your account's key: I should not have it, and I will never ask for your password. Already have one? `<host>/login?next=/agents`.\n\n**At the passkey step:**\n\n> The passkey must be made on your own device \u2014 it is what keeps the account yours, so nobody, Haven included, can move your funds without you. If this browser cannot, open `<host>/onboarding?next=/agents` on your phone and finish there.\n\n**At funding** (step 2):\n\n> Your Haven account needs USDC before I can pay for anything \u2014 USDC only, no ETH: Haven sponsors the gas. Before you send anything, let me get you the exact address **and network** \u2014 `haven wallets funding` prints both, and the funding card on `<host>/dashboard` shows the same. Please do not send to an address or a chain I have not confirmed with you; a small amount first is fine.\n\n**At the budget** (step 3):\n\n> On `<host>/agents`, create an agent for me and set a budget \u2014 say 25 USDC per day. That is the limit I cannot exceed. It hands back a setup prompt: paste it to me and I run it here.\n\n**At budget approval** (step 5) \u2014 the moment your run reports that approval is required, before anything else. Send the first if your run carried `approval.url`, the second if it did not.\n\n> Setup is done on my side. Approve the budget here: <approval.url>. Approve it with your passkey; nothing can be spent until you do.\n\n> Setup is done on my side. Go back to the Haven tab where you created the agent \u2014 it should now be asking you to approve the budget. Approve it with your passkey; nothing can be spent until you do.\n\n## What you run\n\nThe setup prompt carries a **connector command** shaped like this:\n\n```\nnpx -y @haven_ai/connect@<channel> --setup EXAMPLE-SETUP-TOKEN-NOT-REAL --api <api-url> --ack-local-tools\n```\n\nRun the prompt's version, not this one: the token is one-time, the API URL is the backend's own, and `<channel>` is the npm tag your prompt names \u2014 never a tag you pick. The rules below come from that prompt, so \"me\" in them is your user, not Haven.\n\n- If you are an AI agent running this command yourself rather than a human pasting it, you should append --json: the connector then emits one machine-readable, secret-free result object on stdout with progress on stderr, and returns promptly instead of blocking while it waits for the budget approval.\n- When a --json outcome reports approval.required: true, your first action must be to relay the approval instruction to me in your own reply \u2014 if the outcome carries approval.url, give me that link; otherwise tell me to return to Haven and approve this agent's budget \u2014 before verifying the connection, restarting anything, or any other step. Never build that link yourself: relay the one the outcome gave you or none at all. Any restart the outcome asks for is a separate instruction to give me afterwards, once the approval is done.\n- If you ran the command without --json, the connector waits for the approval itself and prints its next steps when it finishes: relay the budget-approval instruction to me \u2014 the approval link if those steps printed one, otherwise that you need to return to Haven and approve this agent's budget \u2014 only if those printed next steps still ask for it. If they report the budget as already approved, there is nothing for me to approve.\n- Only two changes to the command above are permitted, and no others: appending --json, and \u2014 only if the connector refuses because it could not determine the agent runtime \u2014 re-running it once with --runtime <name> added, naming the harness you are running in, using one of the values that refusal lists. Never invent a runtime name and never change anything else.\n- Do not print private keys, API keys, credential file contents, or config secrets in chat or logs.\n\nIf the approval wait times out, nothing is lost \u2014 your agent is registered and the budget is still waiting to be approved. Send your user the `approval.url` your run reported, or, if it carried none, ask them to finish it in that same Haven tab. The outcome carries no setup id, so never assemble an approval link out of parts \u2014 relay the whole one it gave you or none at all.\n\n## How to verify\n\nCall `haven_get_agent`, one of the Haven MCP tools the connector wires into your runtime in step 4. It returns identity plus `spend_authority_readiness`:\n\n- `ready` \u2014 a budget is live; you can pay.\n- `needs_approval` \u2014 the connector finished, nobody approved yet. Ask your user again, in their Haven tab; there is no queue to wait in.\n- `revoked` \u2014 the credential is not active; ask your user to create a new agent.\n\n`ready` covers hosted identity and the budget only, not your local signer. Check that with `npx -y @haven_ai/connect@<channel> --doctor`, the same tag your prompt named \u2014 a separate command, so the two-changes rule does not bind it.\n\n## If you cannot open a browser\n\nNothing here needs you to. Steps 1-3 are links: hand your user the full `<host>/\u2026` URL and ask them to say when it is done. Step 5 is a link only when your run reported one in `approval.url` \u2014 otherwise it is the tab they already have open, as above. Then poll `haven_get_agent` until it reads `ready`. Do not route around the sign-in wall \u2014 it makes the account theirs, not yours.\n\n## Vocabulary\n\n| Term | What it is |\n|---|---|\n| **setup prompt** | The text the dashboard hands your user to paste to you. Carries the command and its rules. |\n| **connector command** | The `npx -y @haven_ai/connect@\u2026` line you run. One-time token, one use. |\n| **agent credential** | Your API key (`sk_agent_\u2026`), written to `~/.haven`. It identifies you; alone it cannot move money. |\n| **delegate key** | Your signing key, made on this machine and never sent anywhere. |\n| **budget** | The on-chain delegation your user signed. It authorises the payment; Haven constructs and relays it. |\n\nNext: [your agent hit a 402](/402.md) \xB7 [everything agent-readable](/llms.txt)\n";
+
+// src/token.ts
+function sessionExpiry(token) {
+  const segment = token.split(".")[1];
+  if (!segment) return null;
+  try {
+    const json = Buffer.from(segment.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
+    const claims = JSON.parse(json);
+    if (typeof claims.exp !== "number" || !Number.isFinite(claims.exp)) return null;
+    return new Date(claims.exp * 1e3).toISOString();
+  } catch {
+    return null;
+  }
+}
+
+// src/amount.ts
+function decimalLabel(decimals) {
+  return decimals === 1 ? "1 decimal place" : `${decimals} decimal places`;
+}
+function parseTokenAmount(input, decimals, tokenSymbol) {
+  if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+    return { ok: false, message: `Unusable token decimals: ${String(decimals)}` };
+  }
+  const trimmed = String(input ?? "").trim();
+  const human = trimmed.startsWith(".") ? `0${trimmed}` : trimmed;
+  const label = tokenSymbol ? ` ${tokenSymbol}` : "";
+  if (human === "") return { ok: false, message: "Enter an amount greater than 0" };
+  if (!/^\d+(?:\.\d+)?$/.test(human)) {
+    return { ok: false, message: `Enter a valid${label} amount \u2014 digits, with an optional decimal point` };
+  }
+  const [whole, fraction = ""] = human.split(".");
+  if (fraction.length > decimals) {
+    return {
+      ok: false,
+      message: `${tokenSymbol ?? "This token"} supports up to ${decimalLabel(decimals)}`
+    };
+  }
+  const atomic = BigInt(`${whole}${fraction.padEnd(decimals, "0")}`);
+  if (atomic === 0n) return { ok: false, message: "Enter an amount greater than 0" };
+  return { ok: true, human, atomic: atomic.toString() };
+}
+function splitConnectorCommand(command) {
+  const argv = [];
+  let current = "";
+  let quoted = false;
+  let started = false;
+  for (let i = 0; i < command.length; i += 1) {
+    const ch = command[i];
+    if (quoted) {
+      if (ch === "'") quoted = false;
+      else current += ch;
+      continue;
+    }
+    if (ch === "'") {
+      quoted = true;
+      started = true;
+      continue;
+    }
+    if (ch === " " || ch === "	") {
+      if (started) argv.push(current);
+      current = "";
+      started = false;
+      continue;
+    }
+    if (ch === "\\") {
+      if (command[i + 1] === "'") {
+        current += "'";
+        started = true;
+        i += 1;
+        continue;
+      }
+      throw new Error("Refusing to run a connector command with a backslash escape");
+    }
+    if (ch === '"' || ch === "`" || ch === "$" || ch === "|" || ch === "&" || ch === ";" || ch === ">" || ch === "<" || ch === "(" || ch === ")" || ch === "\n") {
+      throw new Error(`Refusing to run a connector command containing ${JSON.stringify(ch)}`);
+    }
+    current += ch;
+    started = true;
+  }
+  if (quoted) throw new Error("Refusing to run a connector command with an unterminated quote");
+  if (started) argv.push(current);
+  if (argv.length === 0) throw new Error("The backend returned an empty connector command");
+  return argv;
+}
+var nodeSpawner = (command, args, onStderr) => new Promise((resolve2, reject) => {
+  const child = spawn(command, args, { shell: false, stdio: ["ignore", "pipe", "pipe"] });
+  let stdout = "";
+  let stderr = "";
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  child.stdout.on("data", (chunk) => {
+    stdout += chunk;
+  });
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk;
+    onStderr(chunk);
+  });
+  child.on("error", reject);
+  child.on("close", (code) => resolve2({ stdout, stderr, exitCode: code ?? 1 }));
+});
+function parseOutcome(stdout) {
+  const noise = [];
+  let outcome = null;
+  let depth = 0;
+  let start = -1;
+  let inString = false;
+  let escaped = false;
+  let plain = "";
+  for (let i = 0; i < stdout.length; i += 1) {
+    const ch = stdout[i];
+    if (depth === 0) {
+      if (ch === "{") {
+        depth = 1;
+        start = i;
+        inString = false;
+        escaped = false;
+      } else {
+        plain += ch;
+      }
+      continue;
+    }
+    if (inString) {
+      if (escaped) escaped = false;
+      else if (ch === "\\") escaped = true;
+      else if (ch === '"') inString = false;
+      continue;
+    }
+    if (ch === '"') inString = true;
+    else if (ch === "{") depth += 1;
+    else if (ch === "}") {
+      depth -= 1;
+      if (depth === 0) {
+        const candidate = stdout.slice(start, i + 1);
+        try {
+          outcome = JSON.parse(candidate);
+        } catch {
+          plain += candidate;
+        }
+        start = -1;
+      }
+    }
+  }
+  if (depth > 0 && start >= 0) plain += stdout.slice(start);
+  for (const line of plain.split("\n")) {
+    const text = line.trim();
+    if (text) noise.push(text);
+  }
+  return { outcome, noise: noise.join("\n") };
+}
+function isRefusal(outcome) {
+  return Boolean(outcome?.error);
+}
+function relayLine(outcome) {
+  if (!outcome) return null;
+  if (outcome.error) {
+    const message = outcome.error.message?.trim();
+    const next = outcome.error.next_action ?? outcome.next_action;
+    return message ? `${message}${next ? ` (next: ${next})` : ""}` : `The connector refused${next ? `: ${next}` : "."}`;
+  }
+  if (outcome.approval?.required) {
+    return outcome.approval.url ? `Approve the budget to finish: ${outcome.approval.url}` : "Approve the budget in your Haven tab to finish.";
+  }
+  return null;
+}
+async function runConnector(connectorCommand, spawner, onStderr) {
+  const argv = splitConnectorCommand(connectorCommand);
+  const args = [...argv.slice(1), "--json"];
+  const { stdout, stderr, exitCode } = await spawner(argv[0], args, onStderr);
+  const { outcome, noise } = parseOutcome(stdout);
+  return { outcome, exitCode, stderr, stdoutNoise: noise };
+}
+
 // src/commands.ts
 var DEFAULT_API = "https://havenbackend-production-8a00.up.railway.app";
-var CLI_VERSION = "0.1.33-alpha.0";
+var CLI_VERSION = "0.1.35-alpha.0";
 async function run(argv, deps = {}) {
+  const out = deps.out ?? ((l) => process.stdout.write(`${l}
+`));
+  const err = deps.err ?? ((l) => process.stderr.write(`${l}
+`));
+  const json = argv.includes("--json");
+  const o = createOutput(json, out, err);
   const d = {
     sessionStore: deps.sessionStore ?? createSessionStore(),
     makeApi: deps.makeApi ?? ((baseUrl, token) => createCliApi({ baseUrl, token })),
     promptPassword: deps.promptPassword ?? (() => Promise.reject(new Error("No password input available"))),
-    out: deps.out ?? ((l) => process.stdout.write(`${l}
-`)),
-    err: deps.err ?? ((l) => process.stderr.write(`${l}
-`)),
-    env: deps.env ?? process.env
+    sleep: deps.sleep ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms))),
+    spawner: deps.spawner ?? nodeSpawner,
+    out,
+    err,
+    env: deps.env ?? process.env,
+    o
   };
   let args;
   try {
     args = parseArgs(argv);
   } catch (e) {
-    d.err(e instanceof Error ? e.message : String(e));
-    return 1;
+    return fail(d, new UsageError(e instanceof Error ? e.message : String(e), "Run `haven --help`."));
   }
   if (args.flags.version) {
-    d.out(CLI_VERSION);
-    return 0;
+    o.data({ version: CLI_VERSION }, () => CLI_VERSION);
+    return EXIT.ok;
   }
   if (args.flags.help || !args.command) {
-    d.out(helpText());
-    return 0;
+    o.data({ help: helpText() }, () => helpText());
+    return EXIT.ok;
   }
   try {
     return await dispatch(args, d);
   } catch (e) {
-    if (e instanceof CliApiError) {
-      d.err(e.message);
-      return e.status === 401 ? 2 : 1;
-    }
-    d.err(e instanceof Error ? e.message : String(e));
-    return 1;
+    return fail(d, e);
   }
 }
+function fail(d, err) {
+  const failure = toFailure(err);
+  d.o.failure(failure);
+  return failure.exit;
+}
 async function dispatch(args, d) {
   const key = args.sub ? `${args.command} ${args.sub}` : args.command;
   switch (key) {
+    case "guide":
+      return cmdGuide(args, d);
     case "login":
       return cmdLogin(args, d);
     case "logout":
-      return cmdLogout(d);
+      return cmdLogout(args, d);
     case "whoami":
       return cmdWhoami(args, d);
     case "wallets list":
       return cmdWalletsList(args, d);
     case "wallets balances":
       return cmdWalletsBalances(args, d);
+    case "wallets funding":
+      return cmdWalletsFunding(args, d);
     case "agents list":
       return cmdAgentsList(args, d);
     case "agents show":
       return cmdAgentsShow(args, d);
+    case "agents connect":
+      return cmdAgentsConnect(args, d);
     case "agents pause":
       return cmdAgentLifecycle(args, d, "pause");
     case "agents resume":
@@ -309,6 +666,10 @@ async function dispatch(args, d) {
       return cmdAgentRename(args, d);
     case "budget show":
       return cmdBudgetShow(args, d);
+    case "budget grant":
+      return cmdBudgetGrant(args, d);
+    case "budget revoke":
+      return cmdBudgetRevoke(args, d);
     case "wallets rename":
       return cmdWalletRename(args, d);
     case "activity list":
@@ -324,8 +685,7 @@ async function dispatch(args, d) {
     case "contacts remove":
       return cmdContactsRemove(args, d);
     default:
-      d.err(`Unknown command: ${key}. Run \`haven --help\`.`);
-      return 1;
+      throw new UsageError(`Unknown command: ${key}.`, "Run `haven --help` for the command list.");
   }
 }
 function baseUrlFor(args, d, session) {
@@ -333,40 +693,109 @@ function baseUrlFor(args, d, session) {
 }
 async function authed(args, d) {
   const session = await d.sessionStore.load();
-  if (!session) throw new CliApiError("Not authenticated. Run `haven login` first.", 401);
+  if (!session) throw new CliApiError("Not authenticated.", 401);
   return { session, api: d.makeApi(baseUrlFor(args, d, session), session.token) };
 }
-function emit(d, json, data, human) {
-  d.out(json ? JSON.stringify(data, null, 2) : human());
+function emit(d, _json, data, human) {
+  d.o.data(data, human);
+}
+async function cmdGuide(_args, d) {
+  d.o.data({ ok: true, format: "markdown", content: HAVEN_AGENT_RUNBOOK_MD }, () => HAVEN_AGENT_RUNBOOK_MD);
+  return EXIT.ok;
+}
+async function deviceLogin(args, d, baseUrl) {
+  const api = d.makeApi(baseUrl);
+  const label = d.env.HAVEN_CLIENT_LABEL ?? `Haven CLI on ${d.env.HOSTNAME ?? "this machine"}`;
+  const start = await api.post("/auth/device/start", { client_label: label });
+  const deadline = Date.now() + start.expires_in * 1e3;
+  d.o.data(
+    {
+      ok: true,
+      verification_url: start.verification_url,
+      user_code: start.user_code,
+      expires_at: new Date(deadline).toISOString()
+    },
+    () => `Open ${start.verification_url}
+and approve the code ${start.user_code}.
+It expires in ${Math.round(start.expires_in / 60)} minutes.`
+  );
+  if (args.flags.noWait) return EXIT.ok;
+  let interval = start.interval * 1e3;
+  for (; ; ) {
+    if (Date.now() >= deadline) {
+      throw new HavenCliError("The code expired before it was approved.", EXIT.notAuthenticated);
+    }
+    await d.sleep(interval);
+    let res = null;
+    try {
+      res = await api.post("/auth/device/token", {
+        device_code: start.device_code
+      });
+    } catch (err) {
+      const code = deviceErrorCode(err);
+      if (code === "authorization_pending") continue;
+      if (code === "slow_down") {
+        interval += 5e3;
+        continue;
+      }
+      if (code === "access_denied") {
+        throw new HavenCliError("The request was denied.", EXIT.refused);
+      }
+      if (code === "expired_token") {
+        throw new HavenCliError("The code expired before it was approved.", EXIT.notAuthenticated);
+      }
+      throw err;
+    }
+    await d.sessionStore.save({ token: res.token, apiBaseUrl: baseUrl, user: res.user });
+    emit(
+      d,
+      args.flags.json,
+      { ok: true, email: res.user.email, expires_at: sessionExpiry(res.token), user: res.user, apiBaseUrl: baseUrl },
+      () => `Signed in as ${res.user.email}.`
+    );
+    return EXIT.ok;
+  }
+}
+function deviceErrorCode(err) {
+  const body = err?.body;
+  return typeof body?.error === "string" ? body.error : null;
 }
 async function cmdLogin(args, d) {
   const email = args.flags.email ?? d.env.HAVEN_EMAIL;
   if (!email) {
-    d.err("Provide an email with --email (or HAVEN_EMAIL).");
-    return 1;
+    return deviceLogin(args, d, baseUrlFor(args, d, null));
   }
   const password = d.env.HAVEN_PASSWORD ?? await d.promptPassword();
   if (!password) {
-    d.err("A password is required.");
-    return 1;
+    throw new UsageError("A password is required.", "Set HAVEN_PASSWORD for a non-interactive run.");
   }
   const baseUrl = baseUrlFor(args, d, null);
   const api = d.makeApi(baseUrl);
   const res = await api.post("/auth/login", { email, password });
   await d.sessionStore.save({ token: res.token, apiBaseUrl: baseUrl, user: res.user });
-  emit(d, args.flags.json, { user: res.user, apiBaseUrl: baseUrl }, () => `Signed in as ${res.user.email}.`);
-  return 0;
+  emit(
+    d,
+    args.flags.json,
+    { ok: true, email: res.user.email, expires_at: sessionExpiry(res.token), user: res.user, apiBaseUrl: baseUrl },
+    () => `Signed in as ${res.user.email}.`
+  );
+  return EXIT.ok;
 }
-async function cmdLogout(d) {
+async function cmdLogout(args, d) {
   await d.sessionStore.clear();
-  d.out("Signed out.");
-  return 0;
+  emit(d, args.flags.json, { ok: true, signed_out: true }, () => "Signed out.");
+  return EXIT.ok;
 }
 async function cmdWhoami(args, d) {
-  const { api } = await authed(args, d);
+  const { session, api } = await authed(args, d);
   const user = await api.get("/auth/me");
-  emit(d, args.flags.json, user, () => `${user.email}${user.name ? ` (${user.name})` : ""}`);
-  return 0;
+  emit(
+    d,
+    args.flags.json,
+    { ...user, id: user.id, email: user.email, expires_at: sessionExpiry(session.token), api_url: session.apiBaseUrl },
+    () => `${user.email}${user.name ? ` (${user.name})` : ""}`
+  );
+  return EXIT.ok;
 }
 async function cmdWalletsList(args, d) {
   const { api } = await authed(args, d);
@@ -380,15 +809,15 @@ async function cmdWalletsList(args, d) {
       safes.map((s) => [s.name, chainName(s.chain_id), truncateAddress(s.safe_address), s.is_default ? "\u2713" : ""])
     )
   );
-  return 0;
+  return EXIT.ok;
 }
 async function cmdWalletsBalances(args, d) {
   const { api } = await authed(args, d);
   const { safes } = await api.get("/user/safes");
   const safe = pickSafe(safes, args.flags.safe);
   if (!safe) {
-    d.err(args.flags.safe ? `No wallet matches "${args.flags.safe}".` : "No Haven wallet found.");
-    return 1;
+    if (args.flags.safe) throw new UsageError(`No wallet matches "${args.flags.safe}".`);
+    throw new CliApiError("No Haven wallet found.", 404);
   }
   const { balances } = await api.get(
     `/balances/${safe.safe_address}?chain_id=${safe.chain_id}`
@@ -402,13 +831,72 @@ async function cmdWalletsBalances(args, d) {
       balances.length === 0 ? "  (no balances)" : table(["TOKEN", "BALANCE"], balances.map((b) => [b.symbol, b.formatted]))
     ].join("\n")
   );
-  return 0;
+  return EXIT.ok;
 }
 function pickSafe(safes, ref) {
   if (!ref) return safes.find((s) => s.is_default) ?? safes[0];
   const lower = ref.toLowerCase();
   return safes.find((s) => s.id === ref || s.safe_address.toLowerCase() === lower);
 }
+async function cmdWalletsFunding(args, d) {
+  const { api } = await authed(args, d);
+  const { safes } = await api.get("/user/safes");
+  const safe = pickSafe(safes, args.flags.safe);
+  if (!safe) {
+    if (args.flags.safe) throw new UsageError(`No wallet matches "${args.flags.safe}".`);
+    throw new CliApiError("No Haven wallet found.", 404);
+  }
+  const funding = await api.get(`/user/safes/${safe.id}/funding`);
+  if (!args.flags.wait) {
+    emitFunding(d, funding);
+    return EXIT.ok;
+  }
+  const started = Date.now();
+  const pollMs = Number(d.env.HAVEN_FUNDING_POLL_MS ?? "5000");
+  const waitMs = Number(d.env.HAVEN_FUNDING_WAIT_MS ?? String(2 * 60 * 60 * 1e3));
+  if (!Number.isFinite(pollMs) || pollMs <= 0 || !Number.isFinite(waitMs) || waitMs <= 0) {
+    throw new UsageError("HAVEN_FUNDING_POLL_MS / HAVEN_FUNDING_WAIT_MS must be positive numbers of milliseconds");
+  }
+  let current = funding;
+  for (; ; ) {
+    const spent = Date.now() - started;
+    if (spent >= waitMs) {
+      throw new HavenCliError(
+        `Still not funded after ${elapsedLabel(spent)} \u2014 the transfer may not have landed yet. Check the explorer link, then re-run.`,
+        EXIT.failed
+      );
+    }
+    await d.sleep(pollMs);
+    current = await api.get(`/user/safes/${safe.id}/funding`);
+    if (current.funded) break;
+    d.o.note(`Still waiting after ${elapsedLabel(Date.now() - started)} \u2014 funded: no.`);
+  }
+  d.o.note(`Account shows funded after ${elapsedLabel(Date.now() - started)}.`);
+  emitFunding(d, current);
+  return EXIT.ok;
+}
+function emitFunding(d, funding) {
+  emit(d, d.o.json, funding, () => {
+    const token = funding.tokens.find((t) => t.minimum_useful_human !== null);
+    const asset = token ? `at least ${token.minimum_useful_human} ${token.symbol}` : funding.native.needed ? funding.native.symbol : "USDC";
+    const gas = funding.native.needed ? ` plus ${funding.native.symbol} for gas` : " \u2014 no gas token needed; Haven sponsors it";
+    const faucet = funding.faucet_url !== void 0 ? ` faucet: ${funding.faucet_url},` : "";
+    return [
+      `Send ${asset} on ${funding.chain.name} to ${funding.account_address}${gas}.`,
+      `Explorer: ${funding.chain.explorer_url}.${faucet ? faucet.slice(0, -1) : ""}`,
+      funding.funded ? "The account already counts as funded." : "Nothing has arrived yet."
+    ].join("\n");
+  });
+}
+function elapsedLabel(ms) {
+  const total = Math.floor(ms / 1e3);
+  const h = Math.floor(total / 3600);
+  const m = Math.floor(total % 3600 / 60);
+  const s = total % 60;
+  if (h > 0) return `${h}h${String(m).padStart(2, "0")}m`;
+  if (m > 0) return `${m}m${String(s).padStart(2, "0")}s`;
+  return `${s}s`;
+}
 async function cmdAgentsList(args, d) {
   const { api } = await authed(args, d);
   const { agents } = await api.get("/agents");
@@ -421,14 +909,11 @@ async function cmdAgentsList(args, d) {
       agents.map((a) => [a.id, a.name, a.status, budgetSummary(a.allowances)])
     )
   );
-  return 0;
+  return EXIT.ok;
 }
 async function cmdAgentsShow(args, d) {
   const id = args.positionals[0];
-  if (!id) {
-    d.err("Usage: haven agents show <id>");
-    return 1;
-  }
+  if (!id) throw new UsageError("Usage: haven agents show <id>");
   const { api } = await authed(args, d);
   const agent = await api.get(`/agents/${id}`);
   emit(
@@ -441,15 +926,26 @@ async function cmdAgentsShow(args, d) {
       `budget: ${budgetSummary(agent.allowances)}`
     ].join("\n")
   );
-  return 0;
+  return EXIT.ok;
 }
+var HASH_DISCOVERY_HINT = "haven budget show <agentId> --hashes";
 async function cmdBudgetShow(args, d) {
   const id = args.positionals[0];
-  if (!id) {
-    d.err("Usage: haven budget show <agentId>");
-    return 1;
-  }
+  if (!id) throw new UsageError("Usage: haven budget show <agentId> [--hashes]");
   const { api } = await authed(args, d);
+  if (args.flags.hashes) {
+    const { delegations } = await api.get(`/agents/${id}/delegations`);
+    emit(
+      d,
+      args.flags.json,
+      delegations,
+      () => delegations.length === 0 ? `No delegations on agent ${id}.` : table(
+        ["DELEGATION HASH", "STATUS", "VERSION"],
+        delegations.map((r) => [r.delegation_hash, r.status, String(r.version)])
+      )
+    );
+    return EXIT.ok;
+  }
   const agent = await api.get(`/agents/${id}`);
   const allowances = agent.allowances ?? [];
   emit(
@@ -461,12 +957,148 @@ async function cmdBudgetShow(args, d) {
       allowances.map((a) => [a.token_symbol, a.allowance_amount, resetLabel(a.reset_period_min)])
     )
   );
-  return 0;
+  return EXIT.ok;
 }
 function budgetSummary(allowances) {
   if (!allowances || allowances.length === 0) return "\u2014";
   return allowances.map((a) => `${a.allowance_amount} ${a.token_symbol}`).join(", ");
 }
+var BUDGET_WAIT_TIMEOUT_S = 15 * 60;
+var BUDGET_WAIT_INTERVAL_MS = 5e3;
+async function cmdBudgetGrant(args, d) {
+  const id = args.positionals[0];
+  if (!id) {
+    throw new UsageError("Usage: haven budget grant <agentId> --amount 25 --token USDC --period <minutes> [--recipient <address>] [--expires <unix-seconds>] [--wait]");
+  }
+  if (!args.flags.amount || !args.flags.token || args.flags.period === void 0) {
+    throw new UsageError("--amount, --token and --period are required (period is whole minutes, at least 1)");
+  }
+  if (args.flags.period < 1) {
+    throw new UsageError("--period must be at least 1 minute for a budget grant. A recurring budget is the only shape this rail has; `haven agents connect --period 0` is a different field on a different route.");
+  }
+  const { api } = await authed(args, d);
+  const agent = await api.get(`/agents/${id}`);
+  if (agent.account_type !== "delegator_hybrid") {
+    throw new HavenCliError(
+      `Agent ${id} is not on the delegation rail \u2014 budgets are managed from the dashboard for this account.`,
+      EXIT.refused
+    );
+  }
+  if (!agent.safe_address || !agent.safe_chain_id) {
+    throw new HavenCliError(`Agent ${id} has no wallet assigned yet \u2014 connect it first.`, EXIT.refused);
+  }
+  const { balances } = await api.get(
+    `/balances/${agent.safe_address}?chain_id=${agent.safe_chain_id}`
+  );
+  const wanted = args.flags.token.trim().toUpperCase();
+  const token = balances.find((b) => b.symbol.toUpperCase() === wanted);
+  if (!token || !token.address) {
+    const known = balances.map((b) => b.symbol).join(", ");
+    throw new UsageError(`Unknown token ${args.flags.token} on this wallet's chain. Available: ${known || "none"}`);
+  }
+  const amount = parseTokenAmount(args.flags.amount, token.decimals, token.symbol);
+  if (!amount.ok) throw new UsageError(amount.message);
+  const built = await api.post(`/agents/${id}/delegations/build`, {
+    token_address: token.address,
+    recipient_address: args.flags.recipient ?? null,
+    budget_atomic: amount.atomic,
+    period_seconds: args.flags.period * 60,
+    ...args.flags.expires !== void 0 ? { expires_at: args.flags.expires } : {}
+  });
+  const emitGrant = (status) => emit(
+    d,
+    args.flags.json,
+    { ...built, agent_id: id, status: status ?? "pending" },
+    () => [
+      `Budget of ${args.flags.amount} ${token.symbol} per ${args.flags.period} minutes built for agent ${id}.`,
+      args.flags.recipient ? `Recipient pin: ${args.flags.recipient}` : null,
+      "Open this link and sign \u2014 the budget goes live the moment you do:",
+      built.signing_url,
+      `Delegation: ${built.delegation_hash} (version ${built.version})`,
+      status === "active" ? "Signed and active." : "Waiting for your signature. Run the same command with --wait to poll until it is active."
+    ].filter((line) => line !== null).join("\n")
+  );
+  emitGrant();
+  if (!args.flags.wait) return EXIT.ok;
+  const deadline = Date.now() + BUDGET_WAIT_TIMEOUT_S * 1e3;
+  while (Date.now() < deadline) {
+    await d.sleep(BUDGET_WAIT_INTERVAL_MS);
+    const { delegations } = await api.get(`/agents/${id}/delegations`);
+    const mine = delegations.find((row) => row.delegation_hash === built.delegation_hash);
+    if (mine?.status === "active") {
+      emitGrant("active");
+      return EXIT.ok;
+    }
+    if (mine?.status === "revoked" || mine?.status === "replaced") {
+      throw new HavenCliError(
+        `Delegation ${built.delegation_hash} is now ${mine.status} without being signed.`,
+        EXIT.refused
+      );
+    }
+  }
+  throw new HavenCliError(
+    `Timed out waiting for delegation ${built.delegation_hash} to go active (${BUDGET_WAIT_TIMEOUT_S / 60} minutes). The signing link stays valid until it expires \u2014 sign it, or rerun with --wait.`,
+    EXIT.failed
+  );
+}
+async function cmdBudgetRevoke(args, d) {
+  const [id, hash] = args.positionals;
+  if (!id || !hash) throw new UsageError("Usage: haven budget revoke <agentId> <delegationHash> [--wait]");
+  if (!/^0x[0-9a-fA-F]{64}$/.test(hash)) {
+    throw new UsageError(`The delegation hash must be 0x followed by 64 hex characters \u2014 \`${HASH_DISCOVERY_HINT}\` lists them, or the dashboard.`);
+  }
+  const { api } = await authed(args, d);
+  const { delegations } = await api.get(`/agents/${id}/delegations`);
+  const row = delegations.find((r) => r.delegation_hash.toLowerCase() === hash.toLowerCase());
+  if (!row) {
+    throw new HavenCliError(`No delegation ${hash} on agent ${id}.`, EXIT.refused);
+  }
+  if (row.status === "revoked") {
+    throw new HavenCliError(`Delegation ${hash} is already revoked.`, EXIT.refused);
+  }
+  if (row.status === "replaced") {
+    throw new HavenCliError(
+      `Delegation ${hash} was already replaced by a newer grant \u2014 nothing to revoke.`,
+      EXIT.refused
+    );
+  }
+  const prepared = await api.post(`/agents/${id}/delegations/${hash}/revoke`, {});
+  const revokeUrl = prepared.revocation_url;
+  if (!revokeUrl) {
+    throw new HavenCliError(
+      "The backend did not return a revocation link \u2014 it may be older than #2539. Finish the revocation in the dashboard.",
+      EXIT.failed
+    );
+  }
+  const emitRevoke = (status) => emit(
+    d,
+    args.flags.json,
+    { agent_id: id, delegation_hash: hash, status, ...prepared },
+    () => [
+      "Revocation prepared \u2014 one signature, sponsored (no gas).",
+      "Open this link and sign to stop this budget:",
+      revokeUrl,
+      `Delegation: ${hash}`,
+      status === "revoked" ? "Revoked." : "The budget keeps working until you sign. Run the same command with --wait to poll until it is revoked."
+    ].filter((line) => line !== null).join("\n")
+  );
+  emitRevoke("pending_revoke");
+  if (!args.flags.wait) return EXIT.ok;
+  const deadline = Date.now() + BUDGET_WAIT_TIMEOUT_S * 1e3;
+  while (Date.now() < deadline) {
+    await d.sleep(BUDGET_WAIT_INTERVAL_MS);
+    const { delegations: after } = await api.get(`/agents/${id}/delegations`);
+    const mine = after.find((r) => r.delegation_hash.toLowerCase() === hash.toLowerCase());
+    if (mine?.status === "revoked") {
+      emitRevoke("revoked");
+      return EXIT.ok;
+    }
+  }
+  throw new HavenCliError(
+    `Timed out waiting for delegation ${hash} to be revoked (${BUDGET_WAIT_TIMEOUT_S / 60} minutes). The link stays valid \u2014 sign it, or rerun with --wait.`,
+    EXIT.failed
+  );
+}
 function resetLabel(mins) {
   if (mins === 0) return "one-time";
   if (mins === 1440) return "daily";
@@ -476,75 +1108,64 @@ function resetLabel(mins) {
 }
 async function cmdAgentLifecycle(args, d, action) {
   const id = args.positionals[0];
-  if (!id) {
-    d.err(`Usage: haven agents ${action} <id>`);
-    return 1;
-  }
+  if (!id) throw new UsageError(`Usage: haven agents ${action} <id>`);
   const { api } = await authed(args, d);
   await api.post(`/agents/${id}/${action}`);
-  d.out(`Agent ${id} ${action === "pause" ? "paused" : "resumed"}.`);
-  return 0;
+  const status = action === "pause" ? "paused" : "resumed";
+  emit(d, args.flags.json, { ok: true, agent_id: id, status }, () => `Agent ${id} ${status}.`);
+  return EXIT.ok;
 }
 async function cmdAgentRevoke(args, d) {
   const id = args.positionals[0];
-  if (!id) {
-    d.err("Usage: haven agents revoke <id> --yes");
-    return 1;
-  }
+  if (!id) throw new UsageError("Usage: haven agents revoke <id> --yes");
   if (!args.flags.yes) {
-    d.err(`This permanently revokes agent ${id}. Re-run with --yes to confirm.`);
-    return 1;
+    throw new UsageError(
+      `This permanently revokes agent ${id}.`,
+      "Re-run with --yes to confirm. Revoke is terminal \u2014 the agent cannot go back to active."
+    );
   }
   const { api } = await authed(args, d);
   await api.post(`/agents/${id}/revoke`);
-  d.out(`Agent ${id} revoked. To also remove its on-chain allowance, use the dashboard.`);
-  return 0;
+  emit(
+    d,
+    args.flags.json,
+    { ok: true, agent_id: id, status: "revoked" },
+    () => `Agent ${id} revoked. To also remove its on-chain allowance, use the dashboard.`
+  );
+  return EXIT.ok;
 }
 async function cmdAgentRotateKey(args, d) {
   const id = args.positionals[0];
-  if (!id) {
-    d.err("Usage: haven agents rotate-key <id>");
-    return 1;
-  }
+  if (!id) throw new UsageError("Usage: haven agents rotate-key <id>");
   const { api } = await authed(args, d);
   const res = await api.post(`/agents/${id}/rotate-key`);
-  if (args.flags.json) {
-    d.out(JSON.stringify(res, null, 2));
-  } else {
-    d.out("New API key (shown once \u2014 store it now; the old key stops working):");
-    d.out(res.api_key);
-  }
-  return 0;
+  d.o.note("New API key (shown once \u2014 store it now; the old key stops working):");
+  emit(d, args.flags.json, res, () => res.api_key);
+  return EXIT.ok;
 }
 async function cmdAgentRename(args, d) {
   const [id, ...nameParts] = args.positionals;
   const name = nameParts.join(" ").trim();
-  if (!id || !name) {
-    d.err("Usage: haven agents rename <id> <name>");
-    return 1;
-  }
+  if (!id || !name) throw new UsageError("Usage: haven agents rename <id> <name>");
   const { api } = await authed(args, d);
   await api.put(`/agents/${id}`, { name });
-  d.out(`Agent ${id} renamed to "${name}".`);
-  return 0;
+  emit(d, args.flags.json, { ok: true, agent_id: id, name }, () => `Agent ${id} renamed to "${name}".`);
+  return EXIT.ok;
 }
 async function cmdWalletRename(args, d) {
   const [id, ...nameParts] = args.positionals;
   const name = nameParts.join(" ").trim();
-  if (!id || !name) {
-    d.err("Usage: haven wallets rename <id> <name>");
-    return 1;
-  }
+  if (!id || !name) throw new UsageError("Usage: haven wallets rename <id> <name>");
   const { api } = await authed(args, d);
   await api.put(`/user/safes/${id}`, { name });
-  d.out(`Wallet ${id} renamed to "${name}".`);
-  return 0;
+  emit(d, args.flags.json, { ok: true, safe_id: id, name }, () => `Wallet ${id} renamed to "${name}".`);
+  return EXIT.ok;
 }
 async function resolveSafeId(args, api) {
   if (!args.flags.safe) return void 0;
   const { safes } = await api.get("/user/safes");
   const safe = pickSafe(safes, args.flags.safe);
-  if (!safe) throw new CliApiError(`No wallet matches "${args.flags.safe}".`, 1);
+  if (!safe) throw new UsageError(`No wallet matches "${args.flags.safe}".`);
   return safe.id;
 }
 async function cmdActivityList(args, d) {
@@ -573,7 +1194,7 @@ async function cmdActivityList(args, d) {
       ])
     )
   );
-  return 0;
+  return EXIT.ok;
 }
 async function cmdActivityExport(args, d) {
   if (args.flags.format === "sie") return exportSie(args, d);
@@ -615,8 +1236,8 @@ async function cmdActivityExport(args, d) {
     t.hash,
     t.chainId != null ? String(t.chainId) : ""
   ]);
-  d.out(toCsv(headers, rows));
-  return 0;
+  d.o.text(toCsv(headers, rows), { format: "csv", rows: rows.length });
+  return EXIT.ok;
 }
 function exportType(t) {
   if (t.activityType === "delegate_sweep") return "allowance funding";
@@ -636,8 +1257,8 @@ async function exportSie(args, d) {
   if (args.flags.to) params.set("to", args.flags.to);
   if (args.flags.company) params.set("company", args.flags.company);
   const content = await api.getText(`/accounting/export?${params.toString()}`);
-  d.out(content);
-  return 0;
+  d.o.text(content, { format: "sie" });
+  return EXIT.ok;
 }
 async function cmdCatalogList(args, d) {
   const { api } = await authed(args, d);
@@ -651,7 +1272,127 @@ async function cmdCatalogList(args, d) {
       entries.map((e) => [e.name, e.category, e.rail, e.price_display ?? "\u2014", e.status])
     )
   );
-  return 0;
+  return EXIT.ok;
+}
+async function resolveWalletAndToken(args, api, symbol) {
+  const { safes } = await api.get("/user/safes");
+  if (safes.length === 0) {
+    throw new HavenCliError("No wallet on this account yet \u2014 finish onboarding first.", EXIT.refused);
+  }
+  const safe = args.flags.safe ? safes.find((s) => s.id === args.flags.safe || s.safe_address === args.flags.safe) : safes.find((s) => s.is_default) ?? safes[0];
+  if (!safe) throw new UsageError(`No wallet matches --safe ${args.flags.safe}`);
+  const { balances } = await api.get(
+    `/balances/${safe.safe_address}?chain_id=${safe.chain_id}`
+  );
+  const wanted = symbol.trim().toUpperCase();
+  const token = balances.find((b) => b.symbol.toUpperCase() === wanted);
+  if (!token) {
+    const known = balances.map((b) => b.symbol).join(", ");
+    throw new UsageError(`Unknown token ${symbol} on this wallet's chain. Available: ${known || "none"}`);
+  }
+  return { safeId: safe.id, token };
+}
+var SETTLED = /* @__PURE__ */ new Set(["active", "expired", "cancelled", "failed"]);
+async function pollSetup(api, setupId, d, wait) {
+  let status = await api.get(`/agent-connection-setups/${setupId}`);
+  if (!wait) return status;
+  const deadline = new Date(status.expires_at).getTime();
+  while (!SETTLED.has(status.status) && Date.now() < deadline) {
+    await d.sleep(5e3);
+    status = await api.get(`/agent-connection-setups/${setupId}`);
+  }
+  return status;
+}
+async function cmdAgentsConnect(args, d) {
+  const { api } = await authed(args, d);
+  if (args.flags.status) {
+    const status = await pollSetup(api, args.flags.status, d, args.flags.wait);
+    emit(
+      d,
+      args.flags.json,
+      status,
+      () => [
+        `setup ${status.setup_id}: ${status.status}`,
+        status.agent_id ? `agent: ${status.agent_id}` : null,
+        SETTLED.has(status.status) ? null : `approve: ${status.approval_url}`
+      ].filter(Boolean).join("\n")
+    );
+    return EXIT.ok;
+  }
+  const name = args.flags.name?.trim();
+  if (!name) throw new UsageError("Usage: haven agents connect --name <name> --budget <amount> --token USDC --period <minutes>");
+  if (!args.flags.budget || !args.flags.token || args.flags.period === void 0) {
+    throw new UsageError("--budget, --token and --period are required (period is whole minutes; 0 means one-time)");
+  }
+  const { safeId, token } = await resolveWalletAndToken(args, api, args.flags.token);
+  const amount = parseTokenAmount(args.flags.budget, token.decimals, token.symbol);
+  if (!amount.ok) throw new UsageError(amount.message);
+  const setup = await api.post("/agent-connection-setups", {
+    name,
+    safe_id: safeId,
+    allowances: [
+      {
+        token_address: token.address ?? "0x0000000000000000000000000000000000000000",
+        token_symbol: token.symbol,
+        // ATOMIC on the way in, human on the way back (#2295). Converted here
+        // exactly once, from the decimals the backend just told us.
+        allowance_amount: amount.atomic,
+        reset_period_min: args.flags.period
+      }
+    ],
+    // How this setup was made, for connect attribution (#2302). The route
+    // already accepts any slug, so nothing backend-side had to change.
+    source: "cli",
+    // #2522: the hand-off marker, set only when an agent is driving this CLI
+    // and says so. Never inferred — a guess here mislabels a human's own run.
+    ...d.env.HAVEN_AGENT_DRIVEN === "1" ? { via: "agent" } : {}
+  });
+  if (!args.flags.run) {
+    emit(
+      d,
+      args.flags.json,
+      setup,
+      () => [
+        "Run this where the agent runs:",
+        "",
+        setup.connector_command,
+        "",
+        `Then approve the budget: ${setup.approval_url}`,
+        `Setup ${setup.setup_id} expires ${setup.expires_at}.`
+      ].join("\n")
+    );
+    return EXIT.ok;
+  }
+  const run2 = await runConnector(setup.connector_command, d.spawner, (chunk) => d.err(chunk.trimEnd()));
+  const relay = relayLine(run2.outcome);
+  const merged = {
+    setup_id: setup.setup_id,
+    approval_url: setup.approval_url,
+    connector_command: setup.connector_command,
+    connector_exit_code: run2.exitCode,
+    outcome: run2.outcome,
+    relay
+  };
+  if (isRefusal(run2.outcome)) {
+    emitConnectResult(d, args.flags.json, merged, relay);
+    return EXIT.refused;
+  }
+  if (!run2.outcome) {
+    throw new HavenCliError(
+      `The connector produced no outcome (exit ${run2.exitCode}).${run2.stdoutNoise ? ` Output: ${run2.stdoutNoise}` : ""}`,
+      run2.exitCode === 0 ? EXIT.failed : EXIT.failed
+    );
+  }
+  emitConnectResult(d, args.flags.json, merged, relay);
+  return EXIT.ok;
+}
+function emitConnectResult(d, json, merged, relay) {
+  emit(
+    d,
+    json,
+    merged,
+    () => [relay, relay ? "" : null, `setup ${merged.setup_id}: ${merged.outcome?.outcome ?? "unknown"}`].filter((line) => line !== null).join("\n")
+  );
 }
 async function cmdContactsList(args, d) {
   const { api } = await authed(args, d);
@@ -662,30 +1403,24 @@ async function cmdContactsList(args, d) {
     contacts,
     () => contacts.length === 0 ? "No contacts yet." : table(["ID", "NAME", "ADDRESS"], contacts.map((c) => [c.id, c.name, truncateAddress(c.address)]))
   );
-  return 0;
+  return EXIT.ok;
 }
 async function cmdContactsAdd(args, d) {
   const [address, ...nameParts] = [...args.positionals].reverse();
   const name = nameParts.reverse().join(" ").trim();
-  if (!name || !address) {
-    d.err("Usage: haven contacts add <name> <address>");
-    return 1;
-  }
+  if (!name || !address) throw new UsageError("Usage: haven contacts add <name> <address>");
   const { api } = await authed(args, d);
   const contact = await api.post("/contacts", { name, address });
   emit(d, args.flags.json, contact, () => `Added contact "${contact.name}" (${truncateAddress(contact.address)}).`);
-  return 0;
+  return EXIT.ok;
 }
 async function cmdContactsRemove(args, d) {
   const id = args.positionals[0];
-  if (!id) {
-    d.err("Usage: haven contacts remove <id>");
-    return 1;
-  }
+  if (!id) throw new UsageError("Usage: haven contacts remove <id>");
   const { api } = await authed(args, d);
   await api.del(`/contacts/${id}`);
-  d.out(`Contact ${id} removed.`);
-  return 0;
+  emit(d, args.flags.json, { ok: true, contact_id: id, removed: true }, () => `Contact ${id} removed.`);
+  return EXIT.ok;
 }
 
 export { CliApiError, createCliApi, createSessionStore, helpText, parseArgs, run, sessionPath };