cyberdyne-mcp 0.6.3 → 0.6.5

package/README.md

@@ -2,8 +2,15 @@
 
 This is the **agent-facing** side of CYBERDYNE. The app at
 [app.cyberdyne-os.xyz](https://app.cyberdyne-os.xyz) is what a human sees; this is
-the door an AI agent walks through to **discover, hire, verify and pay** that
-human — no human clicking buttons required.
+the door an AI agent walks through to **post bounties, verify and pay** verified
+humans — no human clicking buttons required.
+
+CYBERDYNE is **one non-custodial FCFS bounty rail**. There is **no direct hire**.
+Every task is an open first-come-first-served bounty: you freeze a budget, **any**
+eligible human submits, and you approve (pay one unit) or reject (reopen the slot)
+each submission. If CYBERDYNE's operator is ever down, you can **`reclaim`** your
+unfilled budget directly from the audited escrow yourself — the deepest
+non-custodial guarantee.
 
 It's a [Model Context Protocol](https://modelcontextprotocol.io) server. Any
 MCP-capable agent (Claude Desktop, Claude Code, or a custom client) connects over
@@ -17,26 +24,46 @@ An agent can go from **nothing** to **wallet + API key + ready to post/pay** wit
 one command — no web dashboard, no manual key copy/paste:
 
 ```bash
-npx -y cyberdyne-mcp onboard      # generates a wallet + mints your cyb_ API key (no dashboard)
+npx -y cyberdyne-mcp onboard      # create a wallet (or import yours) + mint your cyb_ API key (no dashboard)
 claude mcp add cyberdyne -- npx -y cyberdyne-mcp   # the MCP now auto-uses the saved key
 ```
 
-`onboard` resolves a wallet (uses `CYBERDYNE_EVM_PRIVATE_KEY` if set, else a wallet
-it generated on a prior run, else it **generates a fresh one**), signs in to
-CYBERDYNE with it (SIWE — just a signature, no gas, no transaction), mints your
-`cyb_` agent key, and saves **both** to `~/.cyberdyne/config.json` (mode `0600`).
-It prints your wallet address and the `cyb_` key **once**. The same generated
-wallet is then used automatically for pool-budget signing — zero env vars.
+`onboard` resolves a wallet, signs in to CYBERDYNE with it (SIWE — just a
+signature, no gas, no transaction), mints your `cyb_` agent key, and saves **both**
+to `~/.cyberdyne/config.json` (mode `0600`). It prints your wallet address and the
+`cyb_` key **once**. The same wallet is then used automatically for pool-budget
+signing and `reclaim` — zero env vars.
+
+**Import your own wallet, or create a fresh one:**
+
+```bash
+# Import a private key or a BIP-39 mnemonic — pipe it (most private, off shell history):
+echo 0xYOUR_PRIVATE_KEY            | npx -y cyberdyne-mcp onboard --import
+echo "twelve word mnemonic …"      | npx -y cyberdyne-mcp onboard --import
+CYBERDYNE_IMPORT_KEY=0xYOUR_KEY      npx -y cyberdyne-mcp onboard --import   # or via env
+npx -y cyberdyne-mcp onboard --import 0xYOUR_KEY    # works too, but lands in shell history (you'll be warned)
+
+# Generate a brand-new wallet:
+npx -y cyberdyne-mcp onboard --create
+```
+
+With **no flag in a terminal**, `onboard` asks: paste an existing key/mnemonic, or
+press enter to create a fresh wallet. In a non-interactive/CI shell with no flag or
+`CYBERDYNE_IMPORT_KEY`, it defaults to **create**. A mnemonic derives account index
+0 (`m/44'/60'/0'/0/0`). An imported key is validated (0x + 64 hex, or a valid BIP-39
+mnemonic) before any network call. `CYBERDYNE_EVM_PRIVATE_KEY` (env) still works as a
+no-flag default and overrides the saved wallet.
 
 An agent already running inside an LLM with this MCP connected can **self-onboard
 with zero web interaction** by calling the `onboard` tool — it's the one tool that
-works without an existing key and bootstraps everything else. After that it can
-fund (`get_deposit_address` → send USDC on Base → `deposit`) and `post_task` — and
-`withdraw_treasury` to recover unspent treasury to your wallet.
+works without an existing key and bootstraps everything else. (The `onboard` tool
+generates/reuses a wallet; to **import** your own, use the `--import` CLI.) After
+that it can fund (`get_deposit_address` → send USDC on Base → `deposit`) and
+`post_task` — and `withdraw_treasury` to recover unspent treasury to your wallet.
 
 > Mirrors the Bankr CLI UX (`bankr login` → wallet + API key in one shot). The
 > human **submit-proof** step is intentionally still in the app (human-only); every
-> agent-side action — onboard, fund, post, assign, authorize, review, close — is
+> agent-side action — onboard, fund, post, authorize, review, close, reclaim — is
 > headless.
 
 ## CLI
@@ -80,43 +107,41 @@ No key is hardcoded anywhere. `list_categories` and `onboard` work without a tok
 (`onboard` mints one); every other tool returns a clear error until a key is set —
 via `CYBERDYNE_IDENTITY_TOKEN`, a saved `onboard`/`login`, or the `onboard` tool.
 
-## The flows
+## The flow
 
 An agent cannot submit proof on a human's behalf — the **submit-proof step is
-human-only and happens in the app/UI**. Funding is the same for both flows: on the
-**live** rail fund with real USDC — `get_deposit_address` returns where to send,
-then `deposit` credits your treasury from the tx hash. (`fund_treasury` is a
-**testnet/demo** top-up and is disabled when the platform is live.)
-
-There are two settlement flows:
+human-only and happens in the app/UI**. On the **live** rail fund with real USDC —
+`get_deposit_address` returns where to send, then `deposit` credits your treasury
+from the tx hash. (`fund_treasury` is a **testnet/demo** top-up and is disabled when
+the platform is live.)
 
-### Flow A — direct hire (the path live today)
-
-Real USDC on Base via the **custodial rail** (deposit → escrow → withdraw). You
-pick one human, open the hold, then pay on a valid proof.
+There is **one** settlement model: the **non-custodial FCFS pool bounty**. You
+freeze a budget once; **any** eligible human submits first-come-first-served; you
+approve each unit (pay one) or reject it (the slot reopens). `post_task` returns an
+`authIntent` (the whole-budget authorization to sign) plus a separate `deployFee`
+(a non-refundable 2.5% USDC / 5% other-token fee tx).
 
 ```
-get_deposit_address → send USDC → deposit          (fund the treasury)
-  → post_task → search_humans → assign_task         (pick a human)
-  → authorize_task                                  (open the escrow hold; custodial = just task_id)
-  → poll get_task until a submission is pending
-  → release_payment                                 (approve → capture/pay; else reject → refund)
+get_deposit_address → send USDC → deposit          (optional, fund the treasury)
+  → post_task ({ …, quantity })                      → { task, authIntent, deployFee }
+  → authorize_task ({ task_id, auth_intent, deploy_fee })   (sign the budget + pay the deploy fee; freeze the whole budget on the audited escrow)
+  → humans submit FCFS → poll get_task
+  → review_submission per pending submission          (approve → capture one unit, full reward in-token; reject → slot reopens)
+  → close_task                                        (operator voids the unfilled budget back to you; the deploy fee is non-refundable)
 ```
 
-### Flow B — pool / FCFS bounty
+### Trustless backstop — `reclaim`
 
-One frozen budget, many humans claim and submit first-come-first-served; you
-approve each unit. This **non-custodial pool escrow rail is built but gated off**
-on the server today (env `ESCROW_POOL` is not enabled), pending certification —
-so real-money non-custodial pool payouts are **not live yet**. When the operator
-enables it, `post_task` returns an `authIntent` plus a separate `deployFee`:
+`close_task` asks CYBERDYNE's operator to void the unfilled budget. If the operator
+is ever **down**, you don't need it: after the on-chain **authorization deadline**,
+your own wallet (the budget's `payer`) calls the audited escrow's payer-only
+`reclaim(paymentInfo)` **directly**, with zero platform involvement, and recovers
+the unfilled budget itself. This is the deepest non-custodial guarantee.
 
 ```
-post_task (quantity > 1)                            → { task, authIntent, deployFee }
-  → authorize_task ({ auth_intent, deploy_fee })    (sign the budget + pay the deploy fee; freeze the whole budget)
-  → humans claim + submit FCFS → poll get_task
-  → review_submission per pending submission         (approve → capture one unit; reject → slot reopens)
-  → close_task                                       (refund unfilled units; the deploy fee is non-refundable)
+reclaim ({ task_id })   → your MCP wallet reads escrow_payment_info, reconstructs the exact
+                          PaymentInfo struct, and calls reclaim() on the audited escrow on Base.
+                          Errors clearly if it's too early, already settled, or you're not the payer.
 ```
 
 ## Tools → live endpoints
@@ -131,20 +156,20 @@ post_task (quantity > 1)                            → { task, authIntent, depl
 | `get_deposit_address` | `GET /api/treasury/deposit` | Where to send real USDC to fund the treasury (live rail). |
 | `deposit` | `POST /api/treasury/deposit` | Credit the treasury from a real on-chain USDC deposit (tx hash). |
 | `withdraw_treasury` | `POST /api/treasury/withdraw` | Recover unspent treasury to your wallet — pull USDC back to your own verified deposit wallet on Base (live rail; no destination param, so funds can only go to you). |
-| `post_task` | `POST /api/tasks` | Open a task. `reward_usd` is the budget; not charged until authorize. Pool/FCFS response also carries `authIntent` + `deployFee`. |
-| `assign_task` | `POST /api/tasks/[id]/assign` | Direct hire: assign to a human; returns `{ task, authIntent }` (authIntent is `null` on the custodial/manual rail). |
-| `authorize_task` | `POST /api/tasks/[id]/authorize` | Open the escrow hold. Custodial/manual: just `task_id`. On-chain direct hire: `auth_intent`/`signed_payment`. Pool/FCFS: also `deploy_fee`/`fee_tx_hash`. |
+| `post_task` | `POST /api/tasks` | Open an FCFS pool bounty. `reward_usd` is the total budget; `quantity` units; not charged until authorize. Response carries `authIntent` + `deployFee`. |
+| `authorize_task` | `POST /api/tasks/[id]/authorize` | Freeze the whole budget on the audited escrow. With a signing wallet: pass `auth_intent` + `deploy_fee` (the MCP signs + pays the fee); or pre-made `signed_payment` + `fee_tx_hash`. |
 | `get_task` | `GET /api/tasks/[id]` | Task + the submissions/claims the poster may see. Poll for a `pending` submission. |
-| `release_payment` | `POST /api/tasks/[id]/release` | **Direct hire** settle: `approve:true` → capture (pay net of fee); `approve:false` → reject/refund. Auto-resolves the pending `submission_id` if omitted. |
-| `review_submission` | `POST /api/submissions/[id]/review` | **Pool/FCFS** settle: `approve:true` → capture one unit; `approve:false` → reject (slot reopens). |
-| `close_task` | `POST /api/tasks/[id]/close` | Close a (multi-unit) bounty; refund still-held units. |
-
-The live rail today is the **custodial USDC escrow** (real deposit → escrow →
-withdraw on Base mainnet): at `authorize_task` the budget is held; on
-`release_payment` it is captured to the human (net of the platform fee) or
-refunded. The **non-custodial pool/FCFS rail** (deploy-fee + `review_submission`)
-is built but gated off on the server until certification. `search_humans` goes
-through the a2a JSON-RPC gateway because the REST `GET /api/humans` is session-only.
+| `review_submission` | `POST /api/submissions/[id]/review` | Settle one submission: `approve:true` → capture one unit (full reward in-token); `approve:false` → reject (slot reopens). This is how you pay humans. |
+| `close_task` | `POST /api/tasks/[id]/close` | Close the bounty; the operator voids the unfilled remainder back to you. The deploy fee is non-refundable. |
+| `reclaim` | on-chain `reclaim(paymentInfo)` | **Trustless backstop.** After the authorization deadline, your wallet (the payer) recovers the unfilled budget directly from the audited escrow — no CYBERDYNE operator. Returns `{ ok, tx_hash, reclaimed }`. |
+
+The settlement model is the **non-custodial FCFS pool escrow** (freeze-at-deploy on
+the audited base/commerce-payments `AuthCaptureEscrow`): at `authorize_task` the whole
+budget is frozen; `review_submission` captures one unit to the human (full reward,
+in-token); `close_task` voids the unfilled remainder via the operator, and `reclaim`
+is your own payer-only on-chain recovery if the operator is ever unavailable.
+`search_humans` (discovery only — there is no direct hire) goes through the a2a
+JSON-RPC gateway because the REST `GET /api/humans` is session-only.
 
 ## Run it
 
@@ -207,28 +232,24 @@ Bundles the MCP gateway **and** the usage skill. Once connected, run
 
 Then ask the agent, e.g.:
 
-> *Find a Spanish-speaking human who can record audio, post a $3.50 task to read
-> 10 phrases, assign it, authorize the hold, then verify and pay.*
+> *Post a $3.50 FCFS bounty for a human to record 10 phrases, freeze the budget,
+> then verify the first valid submission and pay it.*
 
-The agent chains `search_humans → post_task → assign_task → authorize_task →
-get_task → release_payment` on its own (Flow A, direct hire). For an open
-first-come bounty it instead posts with `quantity > 1` and settles each unit with
-`review_submission` (Flow B, pool/FCFS — active once the pool rail is enabled).
+The agent chains `post_task → authorize_task → get_task → review_submission →
+close_task` on its own. If CYBERDYNE's operator is ever down, it can `reclaim` the
+unfilled budget directly from the escrow after the authorization deadline. There is
+**no direct hire** — every task is an open FCFS pool bounty.
 
 ## Honesty / accuracy
 
 State only what is independently verifiable. This repository, its code, and the
 fact that the tools run and call the documented endpoints are verifiable. The
-backend is **pre-launch**. The live settlement rail today is the **custodial USDC
-rail** (real deposit → escrow → withdraw on Base mainnet). The **non-custodial
-pool/FCFS rail** (deploy-fee + `review_submission`) is built but **gated off** on
-the server pending certification — so real-money non-custodial pool payouts are
-**not live yet**. Do **not** assert funding, valuation, investors, revenue or user
-metrics, any token/airdrop, named individuals, partnerships, or compliance status
-— none are established.
+backend is **pre-launch**. The settlement model is the **non-custodial FCFS pool
+escrow** (freeze-at-deploy on the audited base/commerce-payments `AuthCaptureEscrow`,
+with the agent's own payer-only `reclaim` backstop). Do **not** assert funding,
+valuation, investors, revenue or user metrics, any token/airdrop, named individuals,
+partnerships, or compliance status — none are established.
 
 ## Follow-ups (not in this server)
 
-- The **paid `hire` path** (x402 402→pay→200 over `POST /api/a2a`) is implemented
-  on the platform but not surfaced here — it needs an x402 signing client.
 - A **remote/HTTP MCP** variant (vs. stdio) for hosted agents.

package/dist/cli.js

@@ -160,9 +160,9 @@ export async function runPost(argv) {
         const res = await c.rest("POST", "/api/tasks", { body });
         const taskId = res.task?.id;
         console.error(`  ✓ posted — task ${taskId}`);
-        // Custodial rail (no authIntent): nothing else to do; the hold opens later.
+        // Custodial/testnet rail (no authIntent): nothing else to do; the hold opens later.
         if (!res.authIntent || !res.deployFee) {
-            console.error(`\n✓ Task ${taskId} is open (custodial rail). Next: assign a human + authorize, then release on a valid proof.`);
+            console.error(`\n✓ Task ${taskId} is open. Humans submit FCFS; review each submission to capture a unit (review_submission), then close_task.`);
             process.exit(0);
         }
         // POOL rail — the autonomous `bankr launch` path. Sign the budget with the saved

package/dist/evm-signer.js

@@ -13,7 +13,7 @@
  * Nothing here moves funds or pays gas; it only produces a signature.
  */
 import { privateKeyToAccount } from "viem/accounts";
-import { createPublicClient, createWalletClient, http, parseUnits } from "viem";
+import { createPublicClient, createWalletClient, getAddress, http, parseUnits } from "viem";
 import { base, baseSepolia } from "viem/chains";
 import { AuthCaptureEvmScheme, toClientEvmSigner } from "@x402/evm";
 import { readSavedWalletKey } from "./client.js";
@@ -99,3 +99,115 @@ export async function signAuthCapture(requirements) {
     const result = await scheme().createPaymentPayload(2, requirements);
     return Buffer.from(JSON.stringify(result)).toString("base64");
 }
+// ── Trustless self-recovery: reclaim ────────────────────────────────────────
+// The deepest non-custodial guarantee. The AGENT (payer) calls the AUDITED
+// AuthCaptureEscrow `reclaim(paymentInfo)` DIRECTLY — no CYBERDYNE operator. The
+// contract requires `msg.sender == paymentInfo.payer` and `block.timestamp >=
+// authorizationExpiry`, then returns the uncaptured remainder to the payer. This
+// is the same PaymentInfo tuple shape used by authorize/capture/void.
+/** The canonical audited base/commerce-payments AuthCaptureEscrow on Base. */
+export const AUTH_CAPTURE_ESCROW_ADDRESS = "0xBdEA0D1bcC5966192B070Fdf62aB4EF5b4420cff";
+/** PaymentInfo tuple components — EXACTLY the order the escrow hashes/expects. */
+const PAYMENT_INFO_COMPONENTS = [
+    { name: "operator", type: "address" },
+    { name: "payer", type: "address" },
+    { name: "receiver", type: "address" },
+    { name: "token", type: "address" },
+    { name: "maxAmount", type: "uint120" },
+    { name: "preApprovalExpiry", type: "uint48" },
+    { name: "authorizationExpiry", type: "uint48" },
+    { name: "refundExpiry", type: "uint48" },
+    { name: "minFeeBps", type: "uint16" },
+    { name: "maxFeeBps", type: "uint16" },
+    { name: "feeReceiver", type: "address" },
+    { name: "salt", type: "uint256" },
+];
+const paymentInfoArg = { name: "paymentInfo", type: "tuple", components: PAYMENT_INFO_COMPONENTS };
+/** Minimal ABI: just `reclaim(PaymentInfo)` — payer-callable after authorizationExpiry. */
+export const reclaimAbi = [
+    { type: "function", name: "reclaim", stateMutability: "nonpayable", inputs: [paymentInfoArg], outputs: [] },
+];
+/** Decode the base64 signed payment → { payer (authorization.from), validBefore, salt }. */
+function decodeSignedPayment(signedPayment) {
+    let payload;
+    try {
+        const decoded = JSON.parse(Buffer.from(signedPayment, "base64").toString("utf8"));
+        payload = (decoded.payload ?? decoded);
+    }
+    catch {
+        throw new Error("malformed_signed_payment");
+    }
+    const auth = payload.authorization;
+    const permit = payload.permit2Authorization;
+    const from = auth?.from ?? permit?.from;
+    const validBefore = auth?.validBefore ?? permit?.deadline;
+    const salt = payload.salt;
+    if (!from || !validBefore || !salt)
+        throw new Error("incomplete_signed_payment (need authorization.from + validBefore + salt)");
+    return { payer: from, preApprovalExpiry: Number(validBefore), salt, value: auth?.value };
+}
+/**
+ * Reconstruct the on-chain PaymentInfo struct EXACTLY like the platform's
+ * `structFor` (lib/payments/escrow-pool.ts) — the contract recomputes the hash, so
+ * every field must match the one signed at deploy or `reclaim` reverts.
+ */
+function structFor(info, payer, preApprovalExpiry, salt, value) {
+    const x = info.extra;
+    return {
+        operator: getAddress(x.captureAuthorizer),
+        payer: getAddress(payer),
+        receiver: getAddress(info.payTo),
+        token: getAddress(info.asset),
+        maxAmount: BigInt(value ?? info.amount),
+        preApprovalExpiry,
+        authorizationExpiry: x.captureDeadline,
+        refundExpiry: x.refundDeadline,
+        minFeeBps: x.minFeeBps ?? 0,
+        maxFeeBps: x.maxFeeBps ?? 0,
+        feeReceiver: getAddress(x.feeRecipient),
+        salt: BigInt(salt),
+    };
+}
+/**
+ * TRUSTLESS SELF-RECOVERY. The agent (payer) calls `reclaim(paymentInfo)` on the
+ * audited escrow directly to recover its OWN unfilled budget — no operator. Asserts
+ * the MCP wallet == payer (reclaim is payer-only on-chain) and that the authorization
+ * deadline has passed, then signs+sends from the agent wallet and waits for the receipt.
+ * Returns { ok, tx_hash, reclaimed } (reclaimed = the human-readable atomic maxAmount).
+ */
+export async function reclaimBudget(info) {
+    const signed = info.signedPayment;
+    if (!signed)
+        throw new Error("no signedPayment on this task — it was never frozen on the escrow (nothing to reclaim)");
+    const { payer, preApprovalExpiry, salt, value } = decodeSignedPayment(signed);
+    // reclaim is payer-only on-chain — assert this wallet IS the payer before sending.
+    const me = evmAddress();
+    if (me.toLowerCase() !== payer.toLowerCase()) {
+        throw new Error(`wallet ${me} is not the payer (${payer}) of this budget — reclaim is payer-only on-chain. ` +
+            "Use the same wallet that authorized/froze the budget.");
+    }
+    const paymentInfo = structFor(info, payer, preApprovalExpiry, salt, value);
+    // reclaim requires block.timestamp >= authorizationExpiry — check first for a clear error.
+    const now = Math.floor(Date.now() / 1000);
+    if (now < paymentInfo.authorizationExpiry) {
+        const when = new Date(paymentInfo.authorizationExpiry * 1000).toISOString();
+        throw new Error(`too_early: the authorization deadline has not passed yet (reclaim opens at ${when}, ` +
+            `in ~${Math.ceil((paymentInfo.authorizationExpiry - now) / 60)} min). ` +
+            "Until then, close_task asks CYBERDYNE's operator to void the unfilled budget back to you.");
+    }
+    const wallet = createWalletClient({ account: account(), chain: chain(), transport: http(process.env.CYBERDYNE_RPC_URL) });
+    const pub = createPublicClient({ chain: chain(), transport: http(process.env.CYBERDYNE_RPC_URL) });
+    const hash = await wallet.writeContract({
+        address: AUTH_CAPTURE_ESCROW_ADDRESS,
+        abi: reclaimAbi,
+        functionName: "reclaim",
+        args: [paymentInfo],
+        chain: chain(),
+    });
+    const receipt = await pub.waitForTransactionReceipt({ hash });
+    if (receipt.status !== "success") {
+        throw new Error("reclaim reverted on-chain — the budget may already be fully captured/settled, already reclaimed, " +
+            "or the deadline window is wrong. Nothing was recovered.");
+    }
+    return { ok: true, tx_hash: hash, reclaimed: String(paymentInfo.maxAmount) };
+}

package/dist/onboard.js

@@ -16,33 +16,81 @@
  * Nothing here moves funds or pays gas — onboarding is just a SIWE signature and
  * a DB row. The wallet private key is persisted but NEVER logged to stdout.
  */
-import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { readFileSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { generatePrivateKey, privateKeyToAccount, mnemonicToAccount } from "viem/accounts";
+import { bytesToHex } from "viem";
+import { validateMnemonic } from "@scure/bip39";
+import { wordlist } from "@scure/bip39/wordlists/english";
 import { readConfig, readSavedWalletKey, saveTokenAndWallet } from "./client.js";
 /** Normalise a private key to the 0x-prefixed form viem expects. */
 function normalizeKey(pk) {
     return (pk.startsWith("0x") ? pk : `0x${pk}`);
 }
+/** A 0x-prefixed (or bare) 32-byte hex private key. */
+function isHexPrivateKey(s) {
+    return /^(0x)?[0-9a-fA-F]{64}$/.test(s.trim());
+}
+/** Word-count-shaped (12/15/18/21/24 alpha words) — full BIP-39 checksum is validated on use. */
+function looksLikeMnemonic(s) {
+    const words = s.trim().split(/\s+/);
+    return [12, 15, 18, 21, 24].includes(words.length) && words.every((w) => /^[a-zA-Z]+$/.test(w));
+}
+/**
+ * Resolve a user-provided wallet secret (hex private key OR BIP-39 mnemonic) into
+ * the raw 0x private key. For a mnemonic we VALIDATE the BIP-39 checksum (scure) and
+ * derive account index 0 (m/44'/60'/0'/0/0). Throws a clear error if the secret is
+ * neither a valid key nor a checksum-valid mnemonic.
+ */
+export function privateKeyFromSecret(secret) {
+    const s = secret.trim();
+    if (isHexPrivateKey(s))
+        return normalizeKey(s);
+    if (looksLikeMnemonic(s)) {
+        const phrase = s.split(/\s+/).join(" ").toLowerCase();
+        if (!validateMnemonic(phrase, wordlist)) {
+            throw new Error("invalid BIP-39 mnemonic — the words or checksum don't validate. Check the phrase and try again.");
+        }
+        const pk = mnemonicToAccount(phrase, { addressIndex: 0 }).getHdKey().privateKey;
+        if (!pk)
+            throw new Error("could not derive a private key from that mnemonic");
+        return bytesToHex(pk);
+    }
+    throw new Error("malformed wallet secret — expected a 0x-prefixed 64-hex-char private key, or a valid BIP-39 mnemonic (12–24 words).");
+}
 /**
  * Resolve the onboarding wallet, most-explicit first:
+ *   0. an explicitly IMPORTED secret (key/mnemonic) from the CLI/env/stdin/prompt
  *   1. CYBERDYNE_EVM_PRIVATE_KEY (env)   — operator-supplied
  *   2. saved walletKey in config         — generated on a prior onboard
- *   3. generate a fresh key              — first run, zero config
+ *   3. CREATE a fresh key                — first run, zero config
  * Always returns a usable account + the private key. Persisting a freshly
- * generated key is the caller's job (onboard() does it atomically with the token).
+ * generated/imported key is the caller's job (onboard() does it atomically with the token).
+ *
+ * `opts.importSecret` (hex key or mnemonic) forces import; `opts.forceCreate` forces a
+ * brand-new wallet even if env/config already has one (used by `onboard --create`).
  */
-export function resolveWallet(env = process.env) {
+export function resolveWallet(env = process.env, opts = {}) {
+    if (opts.importSecret) {
+        const privateKey = privateKeyFromSecret(opts.importSecret);
+        return { account: privateKeyToAccount(privateKey), privateKey, generated: false, imported: true };
+    }
+    if (opts.forceCreate) {
+        const privateKey = generatePrivateKey();
+        return { account: privateKeyToAccount(privateKey), privateKey, generated: true, imported: false };
+    }
     const fromEnv = env.CYBERDYNE_EVM_PRIVATE_KEY?.trim();
     if (fromEnv) {
         const privateKey = normalizeKey(fromEnv);
-        return { account: privateKeyToAccount(privateKey), privateKey, generated: false };
+        return { account: privateKeyToAccount(privateKey), privateKey, generated: false, imported: false };
     }
     const saved = readSavedWalletKey();
     if (saved) {
         const privateKey = normalizeKey(saved);
-        return { account: privateKeyToAccount(privateKey), privateKey, generated: false };
+        return { account: privateKeyToAccount(privateKey), privateKey, generated: false, imported: false };
     }
     const privateKey = generatePrivateKey();
-    return { account: privateKeyToAccount(privateKey), privateKey, generated: true };
+    return { account: privateKeyToAccount(privateKey), privateKey, generated: true, imported: false };
 }
 /** Pull every Set-Cookie off a response into a `name=value; name=value` Cookie header. */
 function collectCookies(res, jar) {
@@ -66,11 +114,12 @@ function cookieHeader(jar) {
 /**
  * Run the full SIWE → mint chain and persist the credentials. Throws on any
  * non-2xx step (with the endpoint + status) so the caller can surface a clear error.
+ * Pass `opts.importSecret` to bring your own wallet, or `opts.forceCreate` for a fresh one.
  */
-export async function onboard(env = process.env) {
+export async function onboard(env = process.env, opts = {}) {
     const { apiUrl } = readConfig(env);
     const HOST = new URL(apiUrl).host;
-    const { account, privateKey, generated } = resolveWallet(env);
+    const { account, privateKey, generated, imported } = resolveWallet(env, opts);
     const address = account.address;
     const jar = new Map();
     // 1. nonce
@@ -131,15 +180,127 @@ export async function onboard(env = process.env) {
     }
     // 5. persist BOTH the token and the wallet key atomically (0600)
     const configPath = saveTokenAndWallet(apiKey, privateKey);
-    return { address, apiKey, generated, configPath };
+    return { address, apiKey, generated, imported, configPath };
 }
 /** The multi-line "next steps" block shared by the CLI + the MCP tool. */
 export function nextStepsText() {
     return [
         "Next steps (no dashboard needed):",
         "  1. fund: get_deposit_address → send USDC on Base to that address from this wallet → deposit({ tx_hash }).",
-        "  2. post_task({ title, category, reward_usd, duration_min, difficulty }).",
-        "  3. search_humans → assign_task → authorize_task → poll get_task → release_payment.",
-        "The same generated wallet auto-signs pool budgets (no env vars needed).",
+        "  2. post_task({ title, category, reward_usd, quantity, duration_min, difficulty }).",
+        "  3. authorize_task (sign budget + pay deploy fee + freeze) → humans submit FCFS → poll get_task.",
+        "  4. review_submission per pending submission (approve pays a unit; reject reopens it) → close_task refunds the rest.",
+        "The same wallet auto-signs pool budgets (no env vars needed). Trustless backstop: `reclaim` recovers an unfilled budget yourself after the deadline.",
     ].join("\n");
 }
+// ── CLI front-end for `onboard` (import / create / prompt) ───────────────────
+// Resolves the wallet secret to import (if any), most-private first, then runs
+// onboard(). Non-interactive-safe: with no flag/env in a non-TTY (CI), defaults to
+// create — exactly the prior behaviour.
+//   --import <secret>          import an explicit key/mnemonic (lands in shell history)
+//   --import  (no value)       read the secret from stdin (piped) or CYBERDYNE_IMPORT_KEY
+//   --create                   force a fresh wallet
+//   (none, interactive TTY)    prompt: paste a key/mnemonic, or press enter to create
+/** Tiny flag reader for the onboard args (supports `--import`, `--import=x`, `--create`). */
+function parseOnboardFlags(argv) {
+    let importFlag = false;
+    let importValue;
+    let create = false;
+    for (let i = 0; i < argv.length; i++) {
+        const tok = argv[i];
+        if (tok === "--create")
+            create = true;
+        else if (tok === "--import") {
+            importFlag = true;
+            const next = argv[i + 1];
+            if (next !== undefined && !next.startsWith("--")) {
+                importValue = next;
+                i++;
+            }
+        }
+        else if (tok.startsWith("--import=")) {
+            importFlag = true;
+            importValue = tok.slice("--import=".length);
+        }
+    }
+    return { importFlag, importValue, create };
+}
+/** Read a single line from stdin (used for the interactive import/create prompt). */
+function promptLine(question) {
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: process.stderr });
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+export const ONBOARD_USAGE = [
+    "Usage: cyberdyne-mcp onboard [--import <0xPRIVATEKEY | mnemonic words> | --create]",
+    "",
+    "  --import <secret>   bring your OWN wallet — a 0x 64-hex private key or a BIP-39 mnemonic.",
+    "                      Most private: omit the value and pipe it, or set CYBERDYNE_IMPORT_KEY:",
+    "                        echo 0x<key> | npx cyberdyne-mcp onboard --import",
+    "                        CYBERDYNE_IMPORT_KEY=0x<key> npx cyberdyne-mcp onboard --import",
+    "                      (passing it as an argument leaves the secret in your shell history.)",
+    "  --create            generate a fresh wallet (default in a non-interactive / CI shell).",
+    "  (no flag, in a terminal)  you'll be prompted: paste a key/mnemonic, or press enter to create.",
+    "",
+    "Either way: SIWE sign-in → mint your cyb_ key → save wallet + key to ~/.cyberdyne/config.json (0600).",
+].join("\n");
+/**
+ * Resolve the onboard mode from argv/env/stdin/prompt and run onboard().
+ * Precedence for an IMPORT secret (most private first):
+ *   piped stdin (with --import) → CYBERDYNE_IMPORT_KEY → --import <value> argv → TTY prompt.
+ */
+export async function onboardCli(argv, env = process.env) {
+    const { importFlag, importValue, create } = parseOnboardFlags(argv);
+    if (create)
+        return onboard(env, { forceCreate: true });
+    // Determine the import secret, if the user asked to import.
+    let secret;
+    let fromArgv = false;
+    if (importFlag) {
+        // 1. piped stdin (echo … | onboard --import) — most private
+        if (!process.stdin.isTTY) {
+            try {
+                const piped = readFileSync(0, "utf8").trim();
+                if (piped)
+                    secret = piped;
+            }
+            catch {
+                /* nothing piped */
+            }
+        }
+        // 2. env  3. argv value
+        secret = secret || env.CYBERDYNE_IMPORT_KEY?.trim() || importValue?.trim() || undefined;
+        if (importValue && secret === importValue.trim()) {
+            fromArgv = true;
+        }
+        if (!secret) {
+            throw new Error("--import needs a key/mnemonic. Pipe it (echo 0x<key> | npx cyberdyne-mcp onboard --import), " +
+                "set CYBERDYNE_IMPORT_KEY, or pass it after --import.");
+        }
+    }
+    else if (env.CYBERDYNE_IMPORT_KEY?.trim()) {
+        // Env-only import (no flag) — convenient + private.
+        secret = env.CYBERDYNE_IMPORT_KEY.trim();
+    }
+    else if (process.stdin.isTTY) {
+        // 3. Interactive: ask. Empty → create; else → import the pasted secret.
+        const answer = (await promptLine("Import an existing wallet (paste private key / mnemonic) or press enter to create a new one: ")).trim();
+        if (answer)
+            secret = answer;
+    }
+    // else: non-TTY, no flag, no env → default to create (unchanged CI behaviour).
+    if (fromArgv) {
+        console.error("⚠  Heads-up: passing the wallet secret as an argument leaves it in your shell history.\n" +
+            "   Next time, pipe it instead:  echo 0x<key> | npx cyberdyne-mcp onboard --import");
+    }
+    if (secret) {
+        // Validate early with a clear error before any network call.
+        privateKeyFromSecret(secret);
+        return onboard(env, { importSecret: secret });
+    }
+    return onboard(env); // create / reuse-saved, as before
+}