cyberdyne-mcp 0.5.0 → 0.5.2

package/README.md

@@ -23,23 +23,44 @@ stdio MCP servers take their credentials from the environment. Set:
 No key is hardcoded anywhere. `list_categories` works without a token; every other
 tool returns a clear error until `CYBERDYNE_IDENTITY_TOKEN` is set.
 
-## The flow
+## The flows
 
 An agent cannot submit proof on a human's behalf — the **submit-proof step is
-human-only and happens in the app/UI**. So the agent's end-to-end flow 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:
+
+### 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.
 
 ```
-(live) get_deposit_address → send USDC → deposit   (fund with real USDC)
-   → post_task → (humans claim, or you assign one)
-   → assign_task → authorize_task         (open the escrow hold)
-   → poll get_task until a submission appears
-   → release_payment                       (approve → capture/pay; else reject → refund)
+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)
 ```
 
-> **Funding:** 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 B — pool / FCFS bounty
+
+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`:
+
+```
+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)
+```
 
 ## Tools → live endpoints
 
@@ -51,17 +72,20 @@ human-only and happens in the app/UI**. So the agent's end-to-end flow is:
 | `fund_treasury` | `POST /api/treasury/fund` | **Testnet/demo** top-up (disabled on the live rail). |
 | `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). |
-| `post_task` | `POST /api/tasks` | Open a task. `reward_usd` is the budget; not charged until authorize. |
-| `assign_task` | `POST /api/tasks/[id]/assign` | Assign to a human; returns `{ task, authIntent }` (authIntent is `null` on the manual rail). |
-| `authorize_task` | `POST /api/tasks/[id]/authorize` | Open the escrow hold (manual rail: empty body; on-chain: pass `signed_payment`). |
+| `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`. |
 | `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` | `approve:true` → capture (pay net of fee); `approve:false` → reject/refund. Auto-resolves the pending `submission_id` if omitted. |
+| `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 settle rail is escrow auth-capture: at `authorize_task` the agent's funds are
-held; on `release_payment` they're captured to the human (net of the platform fee)
-or refunded to the agent. `search_humans` goes through the a2a JSON-RPC gateway
-because the REST `GET /api/humans` is session-only.
+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.
 
 ## Run it
 
@@ -90,34 +114,28 @@ then releases payment on verify. The pattern behind x402-native traders like
 CYBERDYNE_IDENTITY_TOKEN=cyb_… npm run build && npm run founder-check
 ```
 
-## Install — one line
-
-Published on [npm](https://www.npmjs.com/package/cyberdyne-mcp), so `npx` runs it
-instantly. You only need Node 18+ and your `cyb_…` agent key (mint one in the app's
-Agent Console).
+## Install
 
-**Claude Code:**
+Published on [npm](https://www.npmjs.com/package/cyberdyne-mcp). Mint your `cyb_…`
+agent key in the app's Agent Console, then:
 
 ```bash
-claude mcp add cyberdyne -e CYBERDYNE_IDENTITY_TOKEN=cyb_… -- npx -y cyberdyne-mcp
+npx cyberdyne-mcp login cyb_YOURKEY            # save your key once (~/.cyberdyne/config.json, 0600)
+claude mcp add cyberdyne -- npx -y cyberdyne-mcp
 ```
 
-**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json` and restart:
-
-```json
-{
-  "mcpServers": {
-    "cyberdyne": {
-      "command": "npx",
-      "args": ["-y", "cyberdyne-mcp"],
-      "env": { "CYBERDYNE_IDENTITY_TOKEN": "cyb_…" }
-    }
-  }
-}
+*(Prefer not to save a login? Skip step 1 and pass it inline instead:
+`claude mcp add cyberdyne -e CYBERDYNE_IDENTITY_TOKEN=cyb_… -- npx -y cyberdyne-mcp`.)*
+
+### …or install the plugin (skill + MCP together)
+
+```
+/plugin marketplace add Cyberdyne-OS/cyberdyne-mcp
+/plugin install cyberdyne@cyberdyne-os
 ```
 
-Once connected, run **`/mcp__cyberdyne__quickstart`** for the full fund → post →
-pay walkthrough. *(Local dev from a clone: `npm install && npm run build`, then point at `node /abs/path/dist/server.js`.)*
+Bundles the MCP gateway **and** the usage skill. Once connected, run
+**`/mcp__cyberdyne__quickstart`** for the full fund → post → pay walkthrough.
 
 Then ask the agent, e.g.:
 
@@ -125,14 +143,19 @@ Then ask the agent, e.g.:
 > 10 phrases, assign it, authorize the hold, then verify and pay.*
 
 The agent chains `search_humans → post_task → assign_task → authorize_task →
-get_task → release_payment` on its own.
+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).
 
 ## 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 a pre-launch MVP; testnet-first, with the on-chain settle rail behind
-the manual rail. Do **not** assert funding, valuation, investors, revenue or user
+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.
 

package/dist/client.js

@@ -19,38 +19,55 @@
  */
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { readFileSync, mkdirSync, openSync, writeSync, closeSync, fchmodSync, constants as FS } from "node:fs";
 export const DEFAULT_API_URL = "https://app.cyberdyne-os.xyz";
 /** Path to the persisted login (mode 600). */
 export function configPath() {
     return join(homedir(), ".cyberdyne", "config.json");
 }
-function readConfigFile() {
+// Only the key is persisted. The API endpoint is intentionally NOT read from this
+// file — a tampered config must never be able to redirect the agent's key to a
+// hostile host (credential exfiltration). The endpoint overrides via env only.
+function readSavedToken() {
     try {
-        return JSON.parse(readFileSync(configPath(), "utf8"));
+        const parsed = JSON.parse(readFileSync(configPath(), "utf8"));
+        return typeof parsed?.identity_token === "string" ? parsed.identity_token.trim() : undefined;
     }
     catch {
-        return {};
+        return undefined;
     }
 }
-/** Persist the agent key to ~/.cyberdyne/config.json (0600). Returns the path. */
+/** Persist the agent key to ~/.cyberdyne/config.json. Returns the path. */
 export function saveToken(token) {
-    mkdirSync(join(homedir(), ".cyberdyne"), { recursive: true });
+    // Owner-only dir + atomic 0600 create (no world-readable window / TOCTOU), and
+    // O_NOFOLLOW so a planted symlink at the path can't redirect the write.
+    mkdirSync(join(homedir(), ".cyberdyne"), { recursive: true, mode: 0o700 });
     const p = configPath();
-    writeFileSync(p, JSON.stringify({ ...readConfigFile(), identity_token: token.trim() }, null, 2));
+    const contents = JSON.stringify({ identity_token: token.trim() }, null, 2);
+    let flags = FS.O_WRONLY | FS.O_CREAT | FS.O_TRUNC;
+    if (typeof FS.O_NOFOLLOW === "number")
+        flags |= FS.O_NOFOLLOW;
+    let fd;
     try {
-        chmodSync(p, 0o600);
+        fd = openSync(p, flags, 0o600);
     }
     catch {
-        /* best-effort on platforms without POSIX modes */
+        // Platforms without O_NOFOLLOW semantics — fall back without it.
+        fd = openSync(p, FS.O_WRONLY | FS.O_CREAT | FS.O_TRUNC, 0o600);
+    }
+    try {
+        fchmodSync(fd, 0o600); // tighten perms on the open fd (covers a pre-existing file), race-free
+        writeSync(fd, contents);
+    }
+    finally {
+        closeSync(fd);
     }
     return p;
 }
-/** Resolve config: env first, then the saved login. `token` may be undefined. */
+/** Resolve config: token from env first, then the saved login. URL from env only. */
 export function readConfig(env = process.env) {
-    const file = readConfigFile();
-    const apiUrl = (env.CYBERDYNE_API_URL || file.api_url || DEFAULT_API_URL).replace(/\/+$/, "");
-    const token = env.CYBERDYNE_IDENTITY_TOKEN?.trim() || file.identity_token?.trim() || undefined;
+    const apiUrl = (env.CYBERDYNE_API_URL || DEFAULT_API_URL).replace(/\/+$/, "");
+    const token = env.CYBERDYNE_IDENTITY_TOKEN?.trim() || readSavedToken() || undefined;
     return { apiUrl, token };
 }
 /** An API error surfaced to the caller — carries the HTTP status + the API's error code. */

package/dist/evm-signer.js

@@ -0,0 +1,82 @@
+/**
+ * Agent-side EVM signing for the CYBERDYNE non-custodial escrow (x402 auth-capture).
+ *
+ * When a task is funded, the agent signs ONE auth-capture authorization for the
+ * whole budget (EIP-3009). CYBERDYNE (operator) then `authorize`s it on-chain,
+ * freezing the funds in the AUDITED escrow — the agent's funds, never ours.
+ *
+ * Two ways the agent can sign (the platform's `authorize` route accepts either):
+ *  (a) MCP-held wallet — set CYBERDYNE_EVM_PRIVATE_KEY; this module signs via the
+ *      x402 SDK (AuthCaptureEvmScheme, the exact path certified on Base mainnet).
+ *  (b) external/Bankr signer — produce the base64 payload elsewhere and pass it in.
+ *
+ * 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 { base, baseSepolia } from "viem/chains";
+import { AuthCaptureEvmScheme, toClientEvmSigner } from "@x402/evm";
+function account() {
+    const pk = process.env.CYBERDYNE_EVM_PRIVATE_KEY;
+    if (!pk)
+        throw new Error("CYBERDYNE_EVM_PRIVATE_KEY not set");
+    return privateKeyToAccount((pk.startsWith("0x") ? pk : `0x${pk}`));
+}
+function chain() {
+    return Number(process.env.CYBERDYNE_CHAIN_ID ?? 8453) === 8453 ? base : baseSepolia;
+}
+const ERC20_TRANSFER_ABI = [
+    {
+        name: "transfer",
+        type: "function",
+        stateMutability: "nonpayable",
+        inputs: [
+            { name: "to", type: "address" },
+            { name: "amount", type: "uint256" },
+        ],
+        outputs: [{ type: "bool" }],
+    },
+];
+/**
+ * Pay the SEPARATE deploy fee (2.5%/5%, pure revenue) from the MCP-held wallet:
+ * a plain ERC-20 transfer to the fee recipient. Returns the tx hash to pass to
+ * authorize_task as `fee_tx_hash`. Only used on the POOL rail; the agent pays
+ * this gas (CYBERDYNE absorbs none). USDC is 6-dp (v1 pool settles in USDC).
+ */
+export async function payDeployFee(params) {
+    const wallet = createWalletClient({ account: account(), chain: chain(), transport: http(process.env.CYBERDYNE_RPC_URL) });
+    return wallet.writeContract({
+        address: params.token,
+        abi: ERC20_TRANSFER_ABI,
+        functionName: "transfer",
+        args: [params.recipient, parseUnits(params.amountUsd.toFixed(6), 6)],
+        chain: chain(),
+    });
+}
+export function hasEvmKey() {
+    return !!process.env.CYBERDYNE_EVM_PRIVATE_KEY;
+}
+function scheme() {
+    const pk = process.env.CYBERDYNE_EVM_PRIVATE_KEY;
+    if (!pk)
+        throw new Error("CYBERDYNE_EVM_PRIVATE_KEY not set — cannot sign the escrow authorization");
+    const chainId = Number(process.env.CYBERDYNE_CHAIN_ID ?? 8453);
+    const chain = chainId === 8453 ? base : baseSepolia;
+    const account = privateKeyToAccount((pk.startsWith("0x") ? pk : `0x${pk}`));
+    const pub = createPublicClient({ chain, transport: http(process.env.CYBERDYNE_RPC_URL) });
+    // toClientEvmSigner(account, PUBLIC client) — account first, public client second.
+    return new AuthCaptureEvmScheme(toClientEvmSigner(account, pub));
+}
+/** The agent's signing wallet address (so the platform can verify payer == this). */
+export function evmAddress() {
+    const pk = process.env.CYBERDYNE_EVM_PRIVATE_KEY;
+    return privateKeyToAccount((pk.startsWith("0x") ? pk : `0x${pk}`)).address;
+}
+/**
+ * Sign the auth-capture requirements (the `authIntent.requirements` the platform
+ * returns) → base64 payload the platform's authorize route consumes as `signedPayment`.
+ */
+export async function signAuthCapture(requirements) {
+    const result = await scheme().createPaymentPayload(2, requirements);
+    return Buffer.from(JSON.stringify(result)).toString("base64");
+}

package/dist/server.js

@@ -16,7 +16,8 @@
  *   assign_task      — POST /api/tasks/[id]/assign        → pick a human (→ authIntent)
  *   authorize_task   — POST /api/tasks/[id]/authorize     → open the escrow hold
  *   get_task         — GET  /api/tasks/[id]               → status + submissions/claims
- *   release_payment  — POST /api/tasks/[id]/release       → capture (pay) or reject
+ *   release_payment  — POST /api/tasks/[id]/release       → direct-hire: capture (pay) or reject
+ *   review_submission — POST /api/submissions/[id]/review → pool/FCFS: approve/reject one submission
  *   close_task       — POST /api/tasks/[id]/close         → close a (multi-unit) bounty
  *
  * Auth: every networked tool sends the agent's `cyb_…` key. The REST routes take
@@ -25,31 +26,65 @@
  * `identity_token`.
  *
  * The HUMAN submit-proof step happens in the app/UI (human-only — agents cannot
- * submit on a human's behalf). So an agent's end-to-end flow is:
- *   (live: get_deposit_address → send USDC → deposit) → post_task
- *     → (humans claim, or assign_task picks one)
- *     → assign_task → authorize_task (open the hold)
- *     → poll get_task until a submission appears
- *     → release_payment (approve → capture; else reject → refund)
+ * submit on a human's behalf). There are TWO settlement flows:
+ *
+ *   FLOW A — DIRECT HIRE (the path that works TODAY on the live custodial USDC
+ *   rail: real deposit → escrow → withdraw on Base mainnet). You pick one human:
+ *     get_deposit_address → send USDC → deposit  (fund the treasury)
+ *       → post_task → search_humans → assign_task (→ authIntent)
+ *       → authorize_task (open the escrow hold)
+ *       → poll get_task until a submission is pending
+ *       → release_payment (approve → capture/pay; else reject → refund)
+ *
+ *   FLOW B — POOL / FCFS BOUNTY (non-custodial pool escrow). Post a multi-unit
+ *   bounty, freeze the whole budget once, and let any eligible human claim+submit
+ *   first-come-first-served; you approve each unit. This rail is BUILT but GATED
+ *   OFF today (server env ESCROW_POOL is not enabled), pending certification — so
+ *   real-money non-custodial pool payouts are NOT live yet. When the server
+ *   enables it, post_task returns an `authIntent` + a separate `deployFee`:
+ *     post_task (quantity>1) → authorize_task (sign the budget + pay the deploy fee)
+ *       → humans claim+submit FCFS → poll get_task
+ *       → review_submission per pending submission (approve → capture one unit;
+ *         reject → the slot reopens) → close_task to refund unfilled units.
  *
  * Config comes from the environment (see src/client.ts):
  *   CYBERDYNE_API_URL         default "https://app.cyberdyne-os.xyz"
  *   CYBERDYNE_IDENTITY_TOKEN  the agent's cyb_ key (required for networked tools)
  */
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { CATEGORIES, TASK_CATEGORIES } from "./registry.js";
 import { ApiError, CyberdyneClient, MissingTokenError, readConfig, saveToken } from "./client.js";
-// `cyberdyne-mcp login cyb_…` — persist the key so the MCP add line can omit it
-// (short DFM-style install). Runs before the server boots, then exits.
+// `cyberdyne-mcp login` — persist the key so the MCP add line can omit it (short
+// one-time-login install). Runs before the server boots, then exits. The key is read
+// (most-private first) from: piped stdin → CYBERDYNE_LOGIN_TOKEN env → argv. argv
+// works but lands the secret in shell history / `ps`, so we steer to the others.
 if (process.argv[2] === "login") {
-    const token = process.argv[3]?.trim();
-    if (!token || !token.startsWith("cyb_")) {
-        console.error("Usage: npx cyberdyne-mcp login cyb_<your-key>\n" +
+    const fromArg = process.argv[3]?.trim();
+    let token = "";
+    if (!process.stdin.isTTY) {
+        try {
+            token = readFileSync(0, "utf8").trim(); // piped: echo cyb_… | npx cyberdyne-mcp login
+        }
+        catch {
+            /* nothing piped */
+        }
+    }
+    token = token || process.env.CYBERDYNE_LOGIN_TOKEN?.trim() || fromArg || "";
+    if (!token.startsWith("cyb_")) {
+        console.error("Save your CYBERDYNE key (most private first):\n" +
+            "  echo cyb_<key> | npx cyberdyne-mcp login\n" +
+            "  CYBERDYNE_LOGIN_TOKEN=cyb_<key> npx cyberdyne-mcp login\n" +
+            "  npx cyberdyne-mcp login cyb_<key>      (key is left in shell history / process list)\n" +
             "Get your key at https://app.cyberdyne-os.xyz → Agent Console → Generate API key.");
         process.exit(1);
     }
+    if (fromArg && token === fromArg) {
+        console.error("⚠  Heads-up: passing the key as an argument leaves it in your shell history.\n" +
+            "   Next time, pipe it instead:  echo cyb_<key> | npx cyberdyne-mcp login");
+    }
     const path = saveToken(token);
     console.error(`✓ Saved your CYBERDYNE key to ${path}.\n` +
         "Now run:  claude mcp add cyberdyne -- npx -y cyberdyne-mcp");
@@ -102,7 +137,7 @@ server.tool("deposit", "Credit your treasury from a REAL on-chain USDC deposit (
         .regex(/^0x[0-9a-fA-F]{64}$/)
         .describe("The Base tx hash of your USDC transfer to the deposit address."),
 }, async ({ tx_hash }) => guard(() => client.rest("POST", "/api/treasury/deposit", { body: { tx_hash } })));
-server.tool("post_task", "Open a task on the marketplace. Funds are NOT charged at post — the escrow hold opens later at authorize_task. On the manual rail the platform only checks the treasury can cover the budget (402 insufficient_treasury otherwise). `reward_usd` is the total budget; with quantity>1 each unit holds reward_usd/quantity. Returns the created task (with its id).", {
+server.tool("post_task", "Open a task on the marketplace. Funds are NOT charged at post — the escrow hold opens later at authorize_task. `reward_usd` is the total budget; with quantity>1 each unit holds reward_usd/quantity (each unit must be >= $0.01). Returns the created task (with its id). DIRECT-HIRE / custodial rail (the path live today): the platform checks the prefunded treasury can cover the budget (402 insufficient_treasury otherwise); response is { task }. POOL/FCFS rail (only when the server enables it): response also includes `authIntent` (the budget authorization to sign) and `deployFee` { usd, bps, recipient, token } (a SEPARATE non-refundable fee tx) — pass both to authorize_task.", {
     title: z.string().min(2).max(160).describe("Short task title."),
     category: z.enum(TASK_CATEGORIES),
     description: z.string().max(4000).optional().describe("What you need the human to do."),
@@ -118,17 +153,40 @@ server.tool("assign_task", "Assign an open task to a chosen human (poster-only)
     task_id: z.string().uuid(),
     human_id: z.string().uuid().describe("The human profile id (from search_humans / get_task claims)."),
 }, async ({ task_id, human_id }) => guard(() => client.rest("POST", `/api/tasks/${task_id}/assign`, { body: { human_id } })));
-server.tool("authorize_task", "Open the escrow hold for an assigned task (poster-only). On the manual rail the body is empty (logical treasury debit). On an on-chain rail pass `signed_payment` — the base64 agent-signed auth-capture payload from the authIntent returned by assign_task. Idempotent once held.", {
+server.tool("authorize_task", "Open the escrow hold for a task. CUSTODIAL/MANUAL rail (the path live today): call with just { task_id } — the prefunded treasury is debited into a logical escrow hold, no signature needed. TRUSTLESS on-chain DIRECT-HIRE rail: the agent signs an auth-capture authorization — if CYBERDYNE_EVM_PRIVATE_KEY is set pass `auth_intent` (the authIntent from assign_task) and the MCP signs automatically, else pass a pre-signed `signed_payment`. POOL/FCFS rail (only when the server enables it): pass BOTH `auth_intent` (from post_task) AND `deploy_fee` (the deployFee object from post_task) — the MCP signs the budget and pays the separate 2.5% USDC / 5% other-token fee tx from its wallet, then submits both; or pass a pre-signed `signed_payment` and a pre-paid `fee_tx_hash`. Idempotent once held.", {
     task_id: z.string().uuid(),
-    signed_payment: z
-        .string()
+    signed_payment: z.string().optional().describe("Pre-signed base64 auth-capture payload (external/Bankr signer)."),
+    auth_intent: z.unknown().optional().describe("The authIntent from assign_task/post — required for MCP wallet auto-signing."),
+    deploy_fee: z
+        .unknown()
         .optional()
-        .describe("On-chain rail only: base64-encoded signed auth-capture payload."),
-}, async ({ task_id, signed_payment }) => guard(() => client.rest("POST", `/api/tasks/${task_id}/authorize`, {
-    body: signed_payment ? { signedPayment: signed_payment } : {},
-})));
+        .describe("POOL rail: the deployFee object {usd,recipient,token} from post_task — the MCP auto-pays it."),
+    fee_tx_hash: z.string().optional().describe("POOL rail: hash of an already-paid deploy-fee tx (skips auto-pay)."),
+}, async ({ task_id, signed_payment, auth_intent, deploy_fee, fee_tx_hash }) => guard(async () => {
+    let payload = signed_payment;
+    let feeTx = fee_tx_hash;
+    if ((!payload && auth_intent) || (!feeTx && deploy_fee)) {
+        const { hasEvmKey, signAuthCapture, payDeployFee } = await import("./evm-signer.js");
+        if (hasEvmKey()) {
+            if (!payload && auth_intent) {
+                const requirements = auth_intent.requirements ?? auth_intent;
+                payload = await signAuthCapture(requirements);
+            }
+            if (!feeTx && deploy_fee) {
+                const f = deploy_fee;
+                feeTx = await payDeployFee({ amountUsd: f.usd, recipient: f.recipient, token: f.token });
+            }
+        }
+    }
+    return client.rest("POST", `/api/tasks/${task_id}/authorize`, {
+        body: {
+            ...(payload ? { signedPayment: payload } : {}),
+            ...(feeTx ? { fee_tx_hash: feeTx } : {}),
+        },
+    });
+}));
 server.tool("get_task", "Get the live state of a task: the task row plus the submissions and per-unit claims the agent (as poster) may see. Poll this after authorize_task until a submission with status 'pending' appears — that is the human's proof, ready for release_payment.", { task_id: z.string().uuid() }, async ({ task_id }) => guard(() => client.rest("GET", `/api/tasks/${task_id}`)));
-server.tool("release_payment", "Settle a submitted proof (poster-only). approve:true → CAPTURE: pay the human net of platform fee. approve:false → REJECT/REFUND the held escrow. Requires the `submission_id` to act on; if omitted, the gateway fetches the task and uses the latest pending submission (and errors if none is pending yet — poll get_task first).", {
+server.tool("release_payment", "DIRECT-HIRE settle (poster-only): settle a submitted proof for a single-human task (the custodial-rail path live today). approve:true → CAPTURE: pay the human net of the platform fee. approve:false → REJECT/REFUND the held escrow. Requires the `submission_id` to act on; if omitted, the gateway fetches the task and uses the latest pending submission (and errors if none is pending yet — poll get_task first). For POOL/FCFS bounties use review_submission instead (this path captures the whole task hold, not one unit).", {
     task_id: z.string().uuid(),
     approve: z.boolean().describe("true = proof meets criteria → pay; false = reject/refund."),
     submission_id: z
@@ -159,6 +217,20 @@ server.tool("release_payment", "Settle a submitted proof (poster-only). approve:
         },
     });
 }));
+server.tool("review_submission", "POOL / FCFS settle (poster-only): approve or reject ONE submission on a pool bounty. approve:true → CAPTURE one unit from the frozen pool budget to the human and consume a slot; approve:false → reject (the slot reopens for the next submitter — no spot-blocking). For single-human direct-hire tasks use release_payment instead. Poll get_task for pending submissions. NOTE: the pool/FCFS rail is gated off on the server until certification — this tool acts on pool tasks once the operator enables that rail.", {
+    submission_id: z.string().uuid().describe("The pending submission to review (from get_task)."),
+    approve: z.boolean().describe("true = proof meets criteria → capture one unit; false = reject (slot reopens)."),
+    score: z.number().int().min(1).max(5).optional().describe("Rating of the human's work (1–5)."),
+    comment: z.string().max(280).optional().describe("Optional feedback note on the human."),
+    reject_reason: z.string().max(1000).optional().describe("Why the proof was rejected (approve:false)."),
+}, async ({ submission_id, approve, score, comment, reject_reason }) => guard(() => client.rest("POST", `/api/submissions/${submission_id}/review`, {
+    body: {
+        approve,
+        ...(score != null ? { score } : {}),
+        ...(comment ? { comment } : {}),
+        ...(reject_reason ? { reject_reason } : {}),
+    },
+})));
 server.tool("close_task", "Close a (multi-unit) bounty (poster-only): refund every still-held unit to the agent, mark unclaimed units done, and stop further claims. Idempotent on an already-closed task.", { task_id: z.string().uuid() }, async ({ task_id }) => guard(() => client.rest("POST", `/api/tasks/${task_id}/close`)));
 // ---- Self-onboarding prompt -----------------------------------------------
 // Surfaces as /mcp__cyberdyne__quickstart — the agent (or user) runs it once to
@@ -166,7 +238,7 @@ server.tool("close_task", "Close a (multi-unit) bounty (poster-only): refund eve
 // shipped inside the MCP: guidance travels with the tools.
 server.registerPrompt("quickstart", {
     title: "CYBERDYNE quickstart",
-    description: "How to fund, post a campaign, and pay humans end-to-end (live rail).",
+    description: "How to fund, post a task, and pay humans end-to-end — both the direct-hire and pool/FCFS flows.",
 }, () => ({
     messages: [
         {
@@ -174,22 +246,28 @@ server.registerPrompt("quickstart", {
             content: {
                 type: "text",
                 text: [
-                    "You are connected to CYBERDYNE — hire and pay verified humans for tasks AI can't do alone. Settlement is REAL USDC on Base.",
+                    "You are connected to CYBERDYNE — hire and pay verified humans for tasks AI can't do alone. The live settlement rail is REAL USDC on Base (custodial: deposit -> escrow -> withdraw). The human submit-proof step is human-only, in the app; you drive everything else.",
+                    "",
+                    "FUND (real money, custodial rail):",
+                    "1. get_deposit_address -> the platform deposit address on Base.",
+                    "2. Send USDC to it FROM your own verified wallet (the one you signed in with).",
+                    "3. deposit({ tx_hash }) -> credits your treasury by the verified amount (idempotent).",
+                    "   (fund_treasury is demo/testnet only and is disabled on the live rail.)",
+                    "Check get_treasury anytime for your balance.",
                     "",
-                    "FUND (live rail, real money):",
-                    "1. get_deposit_address → returns the platform deposit address on Base.",
-                    "2. Send USDC to that address FROM your own verified wallet (the one you signed in with).",
-                    "3. deposit({ tx_hash }) → credits your treasury by the verified amount (idempotent).",
-                    "   (fund_treasury is demo-only and is disabled on the live rail.)",
+                    "FLOW A - DIRECT HIRE (works today): pick one human, hold, then pay.",
+                    "4. post_task({ title, category, reward_usd, duration_min, difficulty }). Returns { task }. Use reward_usd >= 0.50 so the 2.5% fee is visible; each unit must be >= $0.01.",
+                    "5. search_humans({ skills, min_reputation }) -> assign_task({ task_id, human_id }) -> authorize_task({ task_id }) to open the escrow hold (custodial rail = no signature; just task_id).",
+                    "6. Poll get_task until a submission is pending (the human's proof).",
+                    "7. release_payment({ task_id, approve: true, score }) -> CAPTURE: net USDC to the human, the 2.5% fee to the protocol wallet. approve:false rejects and refunds the hold.",
                     "",
-                    "RUN A CAMPAIGN:",
-                    "4. post_task({ title, category, reward_usd, quantity, duration_min, difficulty }) — reward_usd is the TOTAL budget; with quantity>1 each unit holds reward_usd/quantity. Use reward_usd ≥ 0.50 so the 2.5% fee is visible.",
-                    "5. Humans claim units and submit proof (the submit step is human-only, in the app — you cannot submit for them). Poll get_task until a submission is pending.",
-                    "   - Or pick someone yourself: search_humans({ skills, min_reputation }) → assign_task({ task_id, human_id }) → authorize_task({ task_id }) to open the hold.",
-                    "6. release_payment({ task_id, approve: true, score }) → captures: net USDC is paid to the human, the 2.5% fee goes to the protocol wallet. approve:false refunds the hold.",
-                    "7. close_task({ task_id }) → refund any still-unclaimed units of a multi-unit bounty.",
+                    "FLOW B - POOL / FCFS BOUNTY: one frozen budget, many humans claim+submit first-come-first-served. NOTE: this non-custodial pool rail is BUILT but GATED OFF on the server today (pending certification) - real-money pool payouts are not live yet. When the operator enables it:",
+                    "8. post_task({ ..., quantity: N }) -> returns { task, authIntent, deployFee }. authIntent is the budget authorization; deployFee is a SEPARATE non-refundable fee tx (2.5% USDC / 5% other token).",
+                    "9. authorize_task({ task_id, auth_intent, deploy_fee }) -> with CYBERDYNE_EVM_PRIVATE_KEY set, the MCP signs the budget AND pays the deploy fee, then freezes the whole budget (or pass pre-made signed_payment + fee_tx_hash).",
+                    "10. Humans claim+submit FCFS. Poll get_task; for each pending submission call review_submission({ submission_id, approve, score }) -> approve captures one unit; reject reopens the slot.",
+                    "11. close_task({ task_id }) -> refund any still-unfilled units (the deploy fee is non-refundable).",
                     "",
-                    "Check get_treasury anytime for your balance. Every payout and fee is a real on-chain tx.",
+                    "Every payout and fee on the live rail is a real on-chain transaction.",
                 ].join("\n"),
             },
         },
@@ -200,4 +278,4 @@ const transport = new StdioServerTransport();
 await server.connect(transport);
 console.error(`CYBERDYNE MCP server running on stdio → ${config.apiUrl}` +
     (config.token ? "" : " (no key — run `npx cyberdyne-mcp login cyb_…` or set CYBERDYNE_IDENTITY_TOKEN; networked tools error until then)") +
-    ". Tools: list_categories, search_humans, get_treasury, fund_treasury, get_deposit_address, deposit, post_task, assign_task, authorize_task, get_task, release_payment, close_task.");
+    ". Tools (13): list_categories, search_humans, get_treasury, fund_treasury, get_deposit_address, deposit, post_task, assign_task, authorize_task, get_task, release_payment, review_submission, close_task.");

package/llms.txt

@@ -25,30 +25,43 @@ License: MIT
 - CYBERDYNE_API_URL — base URL of the platform API. Default
   https://app.cyberdyne-os.xyz
 
-## Tools → live endpoints
+## Tools → live endpoints (13)
 
 - list_categories — static; the seven task categories (no network)
 - search_humans — POST /api/a2a {search_humans}; query by skills[], min_reputation, location
 - get_treasury — GET /api/treasury; the agent's own treasury
-- fund_treasury — POST /api/treasury/fund; demo top-up
-- post_task — POST /api/tasks; open a task (reward_usd is the budget; not charged until authorize)
-- assign_task — POST /api/tasks/[id]/assign; pick a human, returns {task, authIntent}
-- authorize_task — POST /api/tasks/[id]/authorize; open the escrow hold
+- fund_treasury — POST /api/treasury/fund; demo/testnet top-up (disabled on the live rail)
+- get_deposit_address — GET /api/treasury/deposit; where to send real USDC (live rail)
+- deposit — POST /api/treasury/deposit; credit the treasury from a real on-chain USDC tx hash
+- post_task — POST /api/tasks; open a task (reward_usd is the budget; not charged until authorize). Pool/FCFS response also returns authIntent + deployFee
+- assign_task — POST /api/tasks/[id]/assign; direct hire: pick a human, returns {task, authIntent}
+- authorize_task — POST /api/tasks/[id]/authorize; open the escrow hold (custodial: just task_id; on-chain: auth_intent/signed_payment; pool: also deploy_fee/fee_tx_hash)
 - get_task — GET /api/tasks/[id]; task + submissions/claims; poll for a pending submission
-- release_payment — POST /api/tasks/[id]/release; approve→capture(pay), else reject→refund
-- close_task — POST /api/tasks/[id]/close; close a multi-unit bounty
+- release_payment — POST /api/tasks/[id]/release; DIRECT HIRE settle: approve→capture(pay), else reject→refund
+- review_submission — POST /api/submissions/[id]/review; POOL/FCFS settle: approve→capture one unit, else reject (slot reopens)
+- close_task — POST /api/tasks/[id]/close; close a multi-unit bounty, refund unfilled units
 
-## Flow
+## Flows
 
-The human submit-proof step is human-only (in the app/UI). The agent's flow is:
-fund_treasury → post_task → (humans claim, or assign_task) → assign_task →
-authorize_task → poll get_task until a submission appears → release_payment.
+The human submit-proof step is human-only (in the app/UI). Funding both flows:
+get_deposit_address → send real USDC → deposit. There are two settlement flows:
+
+- Flow A — DIRECT HIRE (live today, custodial USDC rail): post_task →
+  search_humans → assign_task → authorize_task (open the hold) → poll get_task
+  until a submission is pending → release_payment (approve→capture / reject→refund).
+- Flow B — POOL / FCFS BOUNTY: post_task(quantity>1) → authorize_task
+  (sign the budget + pay the deploy fee, freeze the whole budget) → humans
+  claim+submit FCFS → review_submission per unit → close_task for unfilled units.
+  This non-custodial pool rail is BUILT but GATED OFF on the server until
+  certification — real-money pool payouts are not live yet.
 
 ## Settlement model
 
-Escrow auth-capture. At authorize_task the agent's funds are held; on
-release_payment they are captured to the human (net of the platform fee) or
-refunded to the agent. search_humans uses the a2a JSON-RPC gateway because the
+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 until certification. search_humans uses the a2a JSON-RPC gateway because the
 REST GET /api/humans is session-only.
 
 ## For diligence (what is independently verifiable today)
@@ -59,7 +72,10 @@ documented platform endpoints with the agent's key; the live landing
 
 NOT established — do NOT assert: funding, valuation, investors, revenue or user
 metrics, any token or airdrop, named individuals, partnerships, or compliance
-status. None are real. The backend is a pre-launch MVP, testnet-first.
+status. None are real. 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 is built but gated off pending certification, so
+real-money non-custodial pool payouts are not live yet.
 
 ## Contact
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cyberdyne-mcp",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "publishConfig": {
     "access": "public"
   },
@@ -23,6 +23,11 @@
     "agent-marketplace",
     "human-in-the-loop",
     "agentic-payments",
+    "x402",
+    "usdc",
+    "base",
+    "escrow",
+    "bounty",
     "cyberdyne",
     "get-paid-by-ai"
   ],
@@ -49,6 +54,8 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.0.4",
+    "@x402/evm": "^2.14.0",
+    "viem": "^2.52.0",
     "zod": "^3.23.8"
   },
   "devDependencies": {

package/src/client.ts

@@ -20,7 +20,7 @@
 
 import { homedir } from "node:os";
 import { join } from "node:path";
-import { readFileSync, writeFileSync, mkdirSync, chmodSync } from "node:fs";
+import { readFileSync, mkdirSync, openSync, writeSync, closeSync, fchmodSync, constants as FS } from "node:fs";
 
 export const DEFAULT_API_URL = "https://app.cyberdyne-os.xyz";
 
@@ -34,32 +34,47 @@ export function configPath(): string {
   return join(homedir(), ".cyberdyne", "config.json");
 }
 
-function readConfigFile(): { identity_token?: string; api_url?: string } {
+// Only the key is persisted. The API endpoint is intentionally NOT read from this
+// file — a tampered config must never be able to redirect the agent's key to a
+// hostile host (credential exfiltration). The endpoint overrides via env only.
+function readSavedToken(): string | undefined {
   try {
-    return JSON.parse(readFileSync(configPath(), "utf8"));
+    const parsed = JSON.parse(readFileSync(configPath(), "utf8")) as { identity_token?: unknown };
+    return typeof parsed?.identity_token === "string" ? parsed.identity_token.trim() : undefined;
   } catch {
-    return {};
+    return undefined;
   }
 }
 
-/** Persist the agent key to ~/.cyberdyne/config.json (0600). Returns the path. */
+/** Persist the agent key to ~/.cyberdyne/config.json. Returns the path. */
 export function saveToken(token: string): string {
-  mkdirSync(join(homedir(), ".cyberdyne"), { recursive: true });
+  // Owner-only dir + atomic 0600 create (no world-readable window / TOCTOU), and
+  // O_NOFOLLOW so a planted symlink at the path can't redirect the write.
+  mkdirSync(join(homedir(), ".cyberdyne"), { recursive: true, mode: 0o700 });
   const p = configPath();
-  writeFileSync(p, JSON.stringify({ ...readConfigFile(), identity_token: token.trim() }, null, 2));
+  const contents = JSON.stringify({ identity_token: token.trim() }, null, 2);
+  let flags = FS.O_WRONLY | FS.O_CREAT | FS.O_TRUNC;
+  if (typeof FS.O_NOFOLLOW === "number") flags |= FS.O_NOFOLLOW;
+  let fd: number;
   try {
-    chmodSync(p, 0o600);
+    fd = openSync(p, flags, 0o600);
   } catch {
-    /* best-effort on platforms without POSIX modes */
+    // Platforms without O_NOFOLLOW semantics — fall back without it.
+    fd = openSync(p, FS.O_WRONLY | FS.O_CREAT | FS.O_TRUNC, 0o600);
+  }
+  try {
+    fchmodSync(fd, 0o600); // tighten perms on the open fd (covers a pre-existing file), race-free
+    writeSync(fd, contents);
+  } finally {
+    closeSync(fd);
   }
   return p;
 }
 
-/** Resolve config: env first, then the saved login. `token` may be undefined. */
+/** Resolve config: token from env first, then the saved login. URL from env only. */
 export function readConfig(env: NodeJS.ProcessEnv = process.env): CyberdyneConfig {
-  const file = readConfigFile();
-  const apiUrl = (env.CYBERDYNE_API_URL || file.api_url || DEFAULT_API_URL).replace(/\/+$/, "");
-  const token = env.CYBERDYNE_IDENTITY_TOKEN?.trim() || file.identity_token?.trim() || undefined;
+  const apiUrl = (env.CYBERDYNE_API_URL || DEFAULT_API_URL).replace(/\/+$/, "");
+  const token = env.CYBERDYNE_IDENTITY_TOKEN?.trim() || readSavedToken() || undefined;
   return { apiUrl, token };
 }
 

package/src/evm-signer.ts

@@ -0,0 +1,94 @@
+/**
+ * Agent-side EVM signing for the CYBERDYNE non-custodial escrow (x402 auth-capture).
+ *
+ * When a task is funded, the agent signs ONE auth-capture authorization for the
+ * whole budget (EIP-3009). CYBERDYNE (operator) then `authorize`s it on-chain,
+ * freezing the funds in the AUDITED escrow — the agent's funds, never ours.
+ *
+ * Two ways the agent can sign (the platform's `authorize` route accepts either):
+ *  (a) MCP-held wallet — set CYBERDYNE_EVM_PRIVATE_KEY; this module signs via the
+ *      x402 SDK (AuthCaptureEvmScheme, the exact path certified on Base mainnet).
+ *  (b) external/Bankr signer — produce the base64 payload elsewhere and pass it in.
+ *
+ * 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 { base, baseSepolia } from "viem/chains";
+import { AuthCaptureEvmScheme, toClientEvmSigner } from "@x402/evm";
+
+function account() {
+  const pk = process.env.CYBERDYNE_EVM_PRIVATE_KEY;
+  if (!pk) throw new Error("CYBERDYNE_EVM_PRIVATE_KEY not set");
+  return privateKeyToAccount((pk.startsWith("0x") ? pk : `0x${pk}`) as `0x${string}`);
+}
+function chain() {
+  return Number(process.env.CYBERDYNE_CHAIN_ID ?? 8453) === 8453 ? base : baseSepolia;
+}
+
+const ERC20_TRANSFER_ABI = [
+  {
+    name: "transfer",
+    type: "function",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "to", type: "address" },
+      { name: "amount", type: "uint256" },
+    ],
+    outputs: [{ type: "bool" }],
+  },
+] as const;
+
+/**
+ * Pay the SEPARATE deploy fee (2.5%/5%, pure revenue) from the MCP-held wallet:
+ * a plain ERC-20 transfer to the fee recipient. Returns the tx hash to pass to
+ * authorize_task as `fee_tx_hash`. Only used on the POOL rail; the agent pays
+ * this gas (CYBERDYNE absorbs none). USDC is 6-dp (v1 pool settles in USDC).
+ */
+export async function payDeployFee(params: {
+  amountUsd: number;
+  recipient: string;
+  token: string;
+}): Promise<string> {
+  const wallet = createWalletClient({ account: account(), chain: chain(), transport: http(process.env.CYBERDYNE_RPC_URL) });
+  return wallet.writeContract({
+    address: params.token as `0x${string}`,
+    abi: ERC20_TRANSFER_ABI,
+    functionName: "transfer",
+    args: [params.recipient as `0x${string}`, parseUnits(params.amountUsd.toFixed(6), 6)],
+    chain: chain(),
+  });
+}
+
+export function hasEvmKey(): boolean {
+  return !!process.env.CYBERDYNE_EVM_PRIVATE_KEY;
+}
+
+function scheme() {
+  const pk = process.env.CYBERDYNE_EVM_PRIVATE_KEY;
+  if (!pk) throw new Error("CYBERDYNE_EVM_PRIVATE_KEY not set — cannot sign the escrow authorization");
+  const chainId = Number(process.env.CYBERDYNE_CHAIN_ID ?? 8453);
+  const chain = chainId === 8453 ? base : baseSepolia;
+  const account = privateKeyToAccount((pk.startsWith("0x") ? pk : `0x${pk}`) as `0x${string}`);
+  const pub = createPublicClient({ chain, transport: http(process.env.CYBERDYNE_RPC_URL) });
+  // toClientEvmSigner(account, PUBLIC client) — account first, public client second.
+  return new AuthCaptureEvmScheme(toClientEvmSigner(account, pub));
+}
+
+/** The agent's signing wallet address (so the platform can verify payer == this). */
+export function evmAddress(): string {
+  const pk = process.env.CYBERDYNE_EVM_PRIVATE_KEY!;
+  return privateKeyToAccount((pk.startsWith("0x") ? pk : `0x${pk}`) as `0x${string}`).address;
+}
+
+/**
+ * Sign the auth-capture requirements (the `authIntent.requirements` the platform
+ * returns) → base64 payload the platform's authorize route consumes as `signedPayment`.
+ */
+export async function signAuthCapture(requirements: unknown): Promise<string> {
+  const result = await scheme().createPaymentPayload(
+    2,
+    requirements as Parameters<AuthCaptureEvmScheme["createPaymentPayload"]>[1],
+  );
+  return Buffer.from(JSON.stringify(result)).toString("base64");
+}

package/src/server.ts

@@ -16,7 +16,8 @@
  *   assign_task      — POST /api/tasks/[id]/assign        → pick a human (→ authIntent)
  *   authorize_task   — POST /api/tasks/[id]/authorize     → open the escrow hold
  *   get_task         — GET  /api/tasks/[id]               → status + submissions/claims
- *   release_payment  — POST /api/tasks/[id]/release       → capture (pay) or reject
+ *   release_payment  — POST /api/tasks/[id]/release       → direct-hire: capture (pay) or reject
+ *   review_submission — POST /api/submissions/[id]/review → pool/FCFS: approve/reject one submission
  *   close_task       — POST /api/tasks/[id]/close         → close a (multi-unit) bounty
  *
  * Auth: every networked tool sends the agent's `cyb_…` key. The REST routes take
@@ -25,34 +26,69 @@
  * `identity_token`.
  *
  * The HUMAN submit-proof step happens in the app/UI (human-only — agents cannot
- * submit on a human's behalf). So an agent's end-to-end flow is:
- *   (live: get_deposit_address → send USDC → deposit) → post_task
- *     → (humans claim, or assign_task picks one)
- *     → assign_task → authorize_task (open the hold)
- *     → poll get_task until a submission appears
- *     → release_payment (approve → capture; else reject → refund)
+ * submit on a human's behalf). There are TWO settlement flows:
+ *
+ *   FLOW A — DIRECT HIRE (the path that works TODAY on the live custodial USDC
+ *   rail: real deposit → escrow → withdraw on Base mainnet). You pick one human:
+ *     get_deposit_address → send USDC → deposit  (fund the treasury)
+ *       → post_task → search_humans → assign_task (→ authIntent)
+ *       → authorize_task (open the escrow hold)
+ *       → poll get_task until a submission is pending
+ *       → release_payment (approve → capture/pay; else reject → refund)
+ *
+ *   FLOW B — POOL / FCFS BOUNTY (non-custodial pool escrow). Post a multi-unit
+ *   bounty, freeze the whole budget once, and let any eligible human claim+submit
+ *   first-come-first-served; you approve each unit. This rail is BUILT but GATED
+ *   OFF today (server env ESCROW_POOL is not enabled), pending certification — so
+ *   real-money non-custodial pool payouts are NOT live yet. When the server
+ *   enables it, post_task returns an `authIntent` + a separate `deployFee`:
+ *     post_task (quantity>1) → authorize_task (sign the budget + pay the deploy fee)
+ *       → humans claim+submit FCFS → poll get_task
+ *       → review_submission per pending submission (approve → capture one unit;
+ *         reject → the slot reopens) → close_task to refund unfilled units.
  *
  * Config comes from the environment (see src/client.ts):
  *   CYBERDYNE_API_URL         default "https://app.cyberdyne-os.xyz"
  *   CYBERDYNE_IDENTITY_TOKEN  the agent's cyb_ key (required for networked tools)
  */
+import { readFileSync } from "node:fs";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { CATEGORIES, TASK_CATEGORIES } from "./registry.js";
 import { ApiError, CyberdyneClient, MissingTokenError, readConfig, saveToken } from "./client.js";
 
-// `cyberdyne-mcp login cyb_…` — persist the key so the MCP add line can omit it
-// (short DFM-style install). Runs before the server boots, then exits.
+// `cyberdyne-mcp login` — persist the key so the MCP add line can omit it (short
+// one-time-login install). Runs before the server boots, then exits. The key is read
+// (most-private first) from: piped stdin → CYBERDYNE_LOGIN_TOKEN env → argv. argv
+// works but lands the secret in shell history / `ps`, so we steer to the others.
 if (process.argv[2] === "login") {
-  const token = process.argv[3]?.trim();
-  if (!token || !token.startsWith("cyb_")) {
+  const fromArg = process.argv[3]?.trim();
+  let token = "";
+  if (!process.stdin.isTTY) {
+    try {
+      token = readFileSync(0, "utf8").trim(); // piped: echo cyb_… | npx cyberdyne-mcp login
+    } catch {
+      /* nothing piped */
+    }
+  }
+  token = token || process.env.CYBERDYNE_LOGIN_TOKEN?.trim() || fromArg || "";
+  if (!token.startsWith("cyb_")) {
     console.error(
-      "Usage: npx cyberdyne-mcp login cyb_<your-key>\n" +
+      "Save your CYBERDYNE key (most private first):\n" +
+        "  echo cyb_<key> | npx cyberdyne-mcp login\n" +
+        "  CYBERDYNE_LOGIN_TOKEN=cyb_<key> npx cyberdyne-mcp login\n" +
+        "  npx cyberdyne-mcp login cyb_<key>      (key is left in shell history / process list)\n" +
         "Get your key at https://app.cyberdyne-os.xyz → Agent Console → Generate API key.",
     );
     process.exit(1);
   }
+  if (fromArg && token === fromArg) {
+    console.error(
+      "⚠  Heads-up: passing the key as an argument leaves it in your shell history.\n" +
+        "   Next time, pipe it instead:  echo cyb_<key> | npx cyberdyne-mcp login",
+    );
+  }
   const path = saveToken(token);
   console.error(
     `✓ Saved your CYBERDYNE key to ${path}.\n` +
@@ -154,7 +190,7 @@ server.tool(
 
 server.tool(
   "post_task",
-  "Open a task on the marketplace. Funds are NOT charged at post — the escrow hold opens later at authorize_task. On the manual rail the platform only checks the treasury can cover the budget (402 insufficient_treasury otherwise). `reward_usd` is the total budget; with quantity>1 each unit holds reward_usd/quantity. Returns the created task (with its id).",
+  "Open a task on the marketplace. Funds are NOT charged at post — the escrow hold opens later at authorize_task. `reward_usd` is the total budget; with quantity>1 each unit holds reward_usd/quantity (each unit must be >= $0.01). Returns the created task (with its id). DIRECT-HIRE / custodial rail (the path live today): the platform checks the prefunded treasury can cover the budget (402 insufficient_treasury otherwise); response is { task }. POOL/FCFS rail (only when the server enables it): response also includes `authIntent` (the budget authorization to sign) and `deployFee` { usd, bps, recipient, token } (a SEPARATE non-refundable fee tx) — pass both to authorize_task.",
   {
     title: z.string().min(2).max(160).describe("Short task title."),
     category: z.enum(TASK_CATEGORIES),
@@ -183,20 +219,41 @@ server.tool(
 
 server.tool(
   "authorize_task",
-  "Open the escrow hold for an assigned task (poster-only). On the manual rail the body is empty (logical treasury debit). On an on-chain rail pass `signed_payment` — the base64 agent-signed auth-capture payload from the authIntent returned by assign_task. Idempotent once held.",
+  "Open the escrow hold for a task. CUSTODIAL/MANUAL rail (the path live today): call with just { task_id } — the prefunded treasury is debited into a logical escrow hold, no signature needed. TRUSTLESS on-chain DIRECT-HIRE rail: the agent signs an auth-capture authorization — if CYBERDYNE_EVM_PRIVATE_KEY is set pass `auth_intent` (the authIntent from assign_task) and the MCP signs automatically, else pass a pre-signed `signed_payment`. POOL/FCFS rail (only when the server enables it): pass BOTH `auth_intent` (from post_task) AND `deploy_fee` (the deployFee object from post_task) — the MCP signs the budget and pays the separate 2.5% USDC / 5% other-token fee tx from its wallet, then submits both; or pass a pre-signed `signed_payment` and a pre-paid `fee_tx_hash`. Idempotent once held.",
   {
     task_id: z.string().uuid(),
-    signed_payment: z
-      .string()
+    signed_payment: z.string().optional().describe("Pre-signed base64 auth-capture payload (external/Bankr signer)."),
+    auth_intent: z.unknown().optional().describe("The authIntent from assign_task/post — required for MCP wallet auto-signing."),
+    deploy_fee: z
+      .unknown()
       .optional()
-      .describe("On-chain rail only: base64-encoded signed auth-capture payload."),
+      .describe("POOL rail: the deployFee object {usd,recipient,token} from post_task — the MCP auto-pays it."),
+    fee_tx_hash: z.string().optional().describe("POOL rail: hash of an already-paid deploy-fee tx (skips auto-pay)."),
   },
-  async ({ task_id, signed_payment }) =>
-    guard(() =>
-      client.rest("POST", `/api/tasks/${task_id}/authorize`, {
-        body: signed_payment ? { signedPayment: signed_payment } : {},
-      }),
-    ),
+  async ({ task_id, signed_payment, auth_intent, deploy_fee, fee_tx_hash }) =>
+    guard(async () => {
+      let payload = signed_payment;
+      let feeTx = fee_tx_hash;
+      if ((!payload && auth_intent) || (!feeTx && deploy_fee)) {
+        const { hasEvmKey, signAuthCapture, payDeployFee } = await import("./evm-signer.js");
+        if (hasEvmKey()) {
+          if (!payload && auth_intent) {
+            const requirements = (auth_intent as { requirements?: unknown }).requirements ?? auth_intent;
+            payload = await signAuthCapture(requirements);
+          }
+          if (!feeTx && deploy_fee) {
+            const f = deploy_fee as { usd: number; recipient: string; token: string };
+            feeTx = await payDeployFee({ amountUsd: f.usd, recipient: f.recipient, token: f.token });
+          }
+        }
+      }
+      return client.rest("POST", `/api/tasks/${task_id}/authorize`, {
+        body: {
+          ...(payload ? { signedPayment: payload } : {}),
+          ...(feeTx ? { fee_tx_hash: feeTx } : {}),
+        },
+      });
+    }),
 );
 
 server.tool(
@@ -208,7 +265,7 @@ server.tool(
 
 server.tool(
   "release_payment",
-  "Settle a submitted proof (poster-only). approve:true → CAPTURE: pay the human net of platform fee. approve:false → REJECT/REFUND the held escrow. Requires the `submission_id` to act on; if omitted, the gateway fetches the task and uses the latest pending submission (and errors if none is pending yet — poll get_task first).",
+  "DIRECT-HIRE settle (poster-only): settle a submitted proof for a single-human task (the custodial-rail path live today). approve:true → CAPTURE: pay the human net of the platform fee. approve:false → REJECT/REFUND the held escrow. Requires the `submission_id` to act on; if omitted, the gateway fetches the task and uses the latest pending submission (and errors if none is pending yet — poll get_task first). For POOL/FCFS bounties use review_submission instead (this path captures the whole task hold, not one unit).",
   {
     task_id: z.string().uuid(),
     approve: z.boolean().describe("true = proof meets criteria → pay; false = reject/refund."),
@@ -251,6 +308,29 @@ server.tool(
     }),
 );
 
+server.tool(
+  "review_submission",
+  "POOL / FCFS settle (poster-only): approve or reject ONE submission on a pool bounty. approve:true → CAPTURE one unit from the frozen pool budget to the human and consume a slot; approve:false → reject (the slot reopens for the next submitter — no spot-blocking). For single-human direct-hire tasks use release_payment instead. Poll get_task for pending submissions. NOTE: the pool/FCFS rail is gated off on the server until certification — this tool acts on pool tasks once the operator enables that rail.",
+  {
+    submission_id: z.string().uuid().describe("The pending submission to review (from get_task)."),
+    approve: z.boolean().describe("true = proof meets criteria → capture one unit; false = reject (slot reopens)."),
+    score: z.number().int().min(1).max(5).optional().describe("Rating of the human's work (1–5)."),
+    comment: z.string().max(280).optional().describe("Optional feedback note on the human."),
+    reject_reason: z.string().max(1000).optional().describe("Why the proof was rejected (approve:false)."),
+  },
+  async ({ submission_id, approve, score, comment, reject_reason }) =>
+    guard(() =>
+      client.rest("POST", `/api/submissions/${submission_id}/review`, {
+        body: {
+          approve,
+          ...(score != null ? { score } : {}),
+          ...(comment ? { comment } : {}),
+          ...(reject_reason ? { reject_reason } : {}),
+        },
+      }),
+    ),
+);
+
 server.tool(
   "close_task",
   "Close a (multi-unit) bounty (poster-only): refund every still-held unit to the agent, mark unclaimed units done, and stop further claims. Idempotent on an already-closed task.",
@@ -266,7 +346,7 @@ server.registerPrompt(
   "quickstart",
   {
     title: "CYBERDYNE quickstart",
-    description: "How to fund, post a campaign, and pay humans end-to-end (live rail).",
+    description: "How to fund, post a task, and pay humans end-to-end — both the direct-hire and pool/FCFS flows.",
   },
   () => ({
     messages: [
@@ -275,22 +355,28 @@ server.registerPrompt(
         content: {
           type: "text",
           text: [
-            "You are connected to CYBERDYNE — hire and pay verified humans for tasks AI can't do alone. Settlement is REAL USDC on Base.",
+            "You are connected to CYBERDYNE — hire and pay verified humans for tasks AI can't do alone. The live settlement rail is REAL USDC on Base (custodial: deposit -> escrow -> withdraw). The human submit-proof step is human-only, in the app; you drive everything else.",
+            "",
+            "FUND (real money, custodial rail):",
+            "1. get_deposit_address -> the platform deposit address on Base.",
+            "2. Send USDC to it FROM your own verified wallet (the one you signed in with).",
+            "3. deposit({ tx_hash }) -> credits your treasury by the verified amount (idempotent).",
+            "   (fund_treasury is demo/testnet only and is disabled on the live rail.)",
+            "Check get_treasury anytime for your balance.",
             "",
-            "FUND (live rail, real money):",
-            "1. get_deposit_address → returns the platform deposit address on Base.",
-            "2. Send USDC to that address FROM your own verified wallet (the one you signed in with).",
-            "3. deposit({ tx_hash }) → credits your treasury by the verified amount (idempotent).",
-            "   (fund_treasury is demo-only and is disabled on the live rail.)",
+            "FLOW A - DIRECT HIRE (works today): pick one human, hold, then pay.",
+            "4. post_task({ title, category, reward_usd, duration_min, difficulty }). Returns { task }. Use reward_usd >= 0.50 so the 2.5% fee is visible; each unit must be >= $0.01.",
+            "5. search_humans({ skills, min_reputation }) -> assign_task({ task_id, human_id }) -> authorize_task({ task_id }) to open the escrow hold (custodial rail = no signature; just task_id).",
+            "6. Poll get_task until a submission is pending (the human's proof).",
+            "7. release_payment({ task_id, approve: true, score }) -> CAPTURE: net USDC to the human, the 2.5% fee to the protocol wallet. approve:false rejects and refunds the hold.",
             "",
-            "RUN A CAMPAIGN:",
-            "4. post_task({ title, category, reward_usd, quantity, duration_min, difficulty }) — reward_usd is the TOTAL budget; with quantity>1 each unit holds reward_usd/quantity. Use reward_usd ≥ 0.50 so the 2.5% fee is visible.",
-            "5. Humans claim units and submit proof (the submit step is human-only, in the app — you cannot submit for them). Poll get_task until a submission is pending.",
-            "   - Or pick someone yourself: search_humans({ skills, min_reputation }) → assign_task({ task_id, human_id }) → authorize_task({ task_id }) to open the hold.",
-            "6. release_payment({ task_id, approve: true, score }) → captures: net USDC is paid to the human, the 2.5% fee goes to the protocol wallet. approve:false refunds the hold.",
-            "7. close_task({ task_id }) → refund any still-unclaimed units of a multi-unit bounty.",
+            "FLOW B - POOL / FCFS BOUNTY: one frozen budget, many humans claim+submit first-come-first-served. NOTE: this non-custodial pool rail is BUILT but GATED OFF on the server today (pending certification) - real-money pool payouts are not live yet. When the operator enables it:",
+            "8. post_task({ ..., quantity: N }) -> returns { task, authIntent, deployFee }. authIntent is the budget authorization; deployFee is a SEPARATE non-refundable fee tx (2.5% USDC / 5% other token).",
+            "9. authorize_task({ task_id, auth_intent, deploy_fee }) -> with CYBERDYNE_EVM_PRIVATE_KEY set, the MCP signs the budget AND pays the deploy fee, then freezes the whole budget (or pass pre-made signed_payment + fee_tx_hash).",
+            "10. Humans claim+submit FCFS. Poll get_task; for each pending submission call review_submission({ submission_id, approve, score }) -> approve captures one unit; reject reopens the slot.",
+            "11. close_task({ task_id }) -> refund any still-unfilled units (the deploy fee is non-refundable).",
             "",
-            "Check get_treasury anytime for your balance. Every payout and fee is a real on-chain tx.",
+            "Every payout and fee on the live rail is a real on-chain transaction.",
           ].join("\n"),
         },
       },
@@ -305,5 +391,5 @@ await server.connect(transport);
 console.error(
   `CYBERDYNE MCP server running on stdio → ${config.apiUrl}` +
     (config.token ? "" : " (no key — run `npx cyberdyne-mcp login cyb_…` or set CYBERDYNE_IDENTITY_TOKEN; networked tools error until then)") +
-    ". Tools: list_categories, search_humans, get_treasury, fund_treasury, get_deposit_address, deposit, post_task, assign_task, authorize_task, get_task, release_payment, close_task.",
+    ". Tools (13): list_categories, search_humans, get_treasury, fund_treasury, get_deposit_address, deposit, post_task, assign_task, authorize_task, get_task, release_payment, review_submission, close_task.",
 );