taskfast-cli 0.19.4

`taskfast` CLI: worker + poster hot-loop operations, JSON-envelope output.
Documentation
// SPDX-License-Identifier: MIT
//! `taskfast settle` — poster signs an EIP-712 `DistributionApproval` and
//! POSTs it to `/tasks/{id}/settle` to release escrowed funds.
//!
//! Pairs with server bead am-iyp6. The signing surface is identical to the
//! one pinned in `taskfast_chains::tempo::sign_distribution`. The domain
//! (`chain_id`, `verifying_contract`) prefers the task's per-task
//! `settlement_domain` (venue-scoped — a Tempo Zone escrow for a zone-bound
//! task; gh#865, ADR 0011 §5) and falls back to the global
//! `GET /agents/me/readiness` domain when the task carries none, so the same
//! binary signs correctly on L1 testnet/mainnet and in a zone without
//! client-side chain config.
//!
//! Flow: parse UUID → `get_task` (pull `escrow_id` + `settlement_deadline` +
//! `settlement_domain`) → readiness only if no per-task domain → sign →
//! `POST /tasks/{id}/settle`. Dry-run skips the final POST but still signs
//! so the envelope carries a real signature the caller can audit.
//!
//! Error mapping delegates to the shared `map_api_error` (401|403→Auth,
//! 409|422→Validation); signing/keystore failures surface as `Wallet`
//! (exit 5) via `SigningError`/`KeystoreError` → `CmdError`.

use std::path::PathBuf;
use std::str::FromStr;

use alloy_primitives::{Address, B256, U256};
use clap::Parser;
use serde_json::json;
use uuid::Uuid;

use super::{CmdError, CmdResult, Ctx};
use crate::envelope::Envelope;

use taskfast_agent::bootstrap;
use taskfast_chains::tempo::{sign_distribution, DistributionDomain};
use taskfast_client::api::types::SettleTaskBody;
use taskfast_client::map_api_error;

#[derive(Debug, Parser)]
pub struct Args {
    /// Task UUID to settle. Task must have `escrow_id` + `settlement_deadline`
    /// populated (i.e. escrow was created) and be in `:complete` or
    /// `:disbursement_pending` on the server.
    pub task_id: String,

    /// Override the deadline signed into the approval. Defaults to the task's
    /// `settlement_deadline` returned by `GET /tasks/{id}`. Unix seconds.
    #[arg(long)]
    pub deadline_unix: Option<u64>,

    /// Keystore reference. Accepts a bare path (`/.../wallet.json`) or the
    /// `file:/path` form written by `taskfast init` to `TEMPO_KEY_SOURCE`.
    /// Mirrors `taskfast post`'s flag so a single keystore serves both verbs.
    #[arg(long, env = "TEMPO_KEY_SOURCE")]
    pub keystore: Option<String>,

    /// Path to a file holding the keystore password (mode-0400 recommended).
    /// `TASKFAST_WALLET_PASSWORD` env wins over this when both are set so CI
    /// workflows can keep using the env-var form.
    #[arg(long, env = "TASKFAST_WALLET_PASSWORD_FILE")]
    pub wallet_password_file: Option<PathBuf>,

    /// Poster's wallet address (0x-prefixed). When present, we fail early if
    /// the keystore decrypts to a different address — otherwise the server
    /// would 422 after the round-trip. Purely a UX preflight.
    #[arg(long, env = "TEMPO_WALLET_ADDRESS")]
    pub wallet_address: Option<String>,

    /// Acknowledge oversized budgets. Required when the task's budget
    /// exceeds `confirm_above_budget` in the config. Mirrors the same
    /// gate on `taskfast post`; both fail closed before any keystore
    /// prompt or signing.
    #[arg(long)]
    pub yes: bool,
}

pub async fn run(ctx: &Ctx, args: Args) -> CmdResult {
    // 1. Validate UUID upfront — bad input must not cost a round-trip.
    let task_id = Uuid::parse_str(&args.task_id)
        .map_err(|e| CmdError::Usage(format!("task id must be a UUID: {e}")))?;

    let client = ctx.client()?;

    // 2. Fetch task detail — we need escrow_id + settlement_deadline.
    let task = match client.inner().get_task(&task_id).await {
        Ok(v) => v.into_inner(),
        Err(e) => return Err(map_api_error(e).await.into()),
    };

    // Fail-closed budget gate before keystore prompt or signing — a
    // fat-finger settle on a huge task should die immediately.
    ctx.enforce_budget_gate(task.budget_max.as_deref(), args.yes, "settle this task")?;

    let escrow_id_hex: String = match task.escrow_id.as_ref().map(|e| e.to_string()) {
        Some(e) => e,
        None => {
            // gh#143: dev auto-disburse settles without waiting for the
            // poster's explicit `settle`, clearing the escrow data. When the
            // task already reached (or is passing through) the settle target,
            // report success with a note instead of the "no escrow_id" usage
            // error — the goal the caller wanted is met. Missing escrow in
            // any other state is a genuine not-ready error.
            if let Some(note) = task.status.as_deref().and_then(settlement_note) {
                return Ok(Envelope::success(
                    ctx.environment,
                    ctx.dry_run,
                    json!({
                        "task_id": task_id.to_string(),
                        "status": task.status,
                        "note": note,
                    }),
                ));
            }
            return Err(CmdError::Usage(
                "task has no escrow_id; settle requires an initialized escrow \
                 (task must be in :complete or :disbursement_pending)"
                    .into(),
            ));
        }
    };

    // 3. Resolve deadline: explicit override wins; otherwise require the
    //    server-stored value. Either can be absent but not both.
    let deadline_unix: u64 = match args.deadline_unix {
        Some(n) => n,
        None => {
            let dt = task.settlement_deadline.ok_or_else(|| {
                CmdError::Usage(
                    "task has no settlement_deadline; either wait for escrow \
                     creation or pass --deadline-unix explicitly"
                        .into(),
                )
            })?;
            // `timestamp()` is i64; clamp to u64 for the uint256. A negative
            // server-side deadline is nonsensical; treat as decode.
            u64::try_from(dt.timestamp()).map_err(|_| {
                CmdError::Decode(format!(
                    "task settlement_deadline is before epoch: {}",
                    dt.to_rfc3339()
                ))
            })?
        }
    };

    // 4. EIP-712 domain. Prefer the task's per-task `settlement_domain` — the
    //    venue-scoped domain (a Tempo Zone escrow + chain_id for a zone-bound
    //    task) that this task's escrow actually verifies against. Fall back to
    //    the global `GET /agents/me/readiness` domain only when the task carries
    //    none — a default-venue task, whose venue IS the readiness L1 domain, so
    //    the two are identical. Signing a zone task against the L1 domain would
    //    verify against the wrong escrow and the server would reject it (gh#865,
    //    ADR 0011 §5; mirrors the `escrow sign` fix in gh#111).
    let (raw_chain_id, verifying_contract_str): (i64, String) =
        match task.settlement_domain.as_ref() {
            Some(d) => (d.chain_id, d.verifying_contract.to_string()),
            None => {
                let readiness = bootstrap::get_readiness(&client)
                    .await
                    .map_err(CmdError::from)?;
                let d = readiness.settlement_domain;
                (d.chain_id, d.verifying_contract.to_string())
            }
        };
    let verifying_contract: Address = verifying_contract_str.parse().map_err(|e| {
        CmdError::Decode(format!(
            "settlement domain has invalid verifying_contract `{verifying_contract_str}`: {e}"
        ))
    })?;
    let chain_id: u64 = u64::try_from(raw_chain_id).map_err(|_| {
        CmdError::Decode(format!(
            "settlement domain has negative chain_id: {raw_chain_id}"
        ))
    })?;
    let domain = DistributionDomain::new(chain_id, verifying_contract);

    // 5. Parse escrow_id. The server's schema already regex-validates the
    //    shape; we re-parse locally to produce a `B256` for signing. A parse
    //    failure here would be a server contract violation.
    let escrow_id: B256 = B256::from_str(&escrow_id_hex).map_err(|e| {
        CmdError::Decode(format!(
            "server returned invalid escrow_id `{escrow_id_hex}`: {e}"
        ))
    })?;
    let deadline = U256::from(deadline_unix);

    // 6. Load keystore. Bead spec calls for the signature to appear in the
    //    dry-run envelope, so we sign even in dry-run and never short-circuit
    //    before keystore resolution.
    let keystore_ref = args.keystore.as_deref().map(str::to_string).or_else(|| {
        ctx.keystore_path
            .as_deref()
            .and_then(|p| p.to_str().map(str::to_string))
    });
    let signer = super::wallet_args::load_signer(
        keystore_ref.as_deref(),
        args.wallet_password_file.as_deref(),
        "settlement approval",
    )?;

    // 7. Optional preflight: keystore must match --wallet-address if given.
    //    Without this, a mismatch surfaces as a server 422 after the full
    //    round-trip (including the get_task + readiness calls above).
    let wallet_address_for_check = args
        .wallet_address
        .as_deref()
        .or(ctx.wallet_address.as_deref());
    if let Some(expected) = wallet_address_for_check {
        let expected_addr: Address = expected.parse().map_err(|e| {
            CmdError::Usage(format!("--wallet-address is not a valid EVM address: {e}"))
        })?;
        if signer.address() != expected_addr {
            return Err(CmdError::Usage(format!(
                "keystore address {:#x} does not match --wallet-address {}",
                signer.address(),
                expected
            )));
        }
    }

    // 8. Sign the DistributionApproval. `sign_distribution` returns the
    //    132-char 0x-prefixed `r||s||v` shape the server's verifier expects.
    let signature_hex = sign_distribution(&signer, &domain, escrow_id, deadline)?;

    // 9. Dry-run fork — envelope carries the real signature so callers can
    //    audit it (e.g., `cast wallet verify` or the Elixir verifier fixture)
    //    before committing the live POST.
    if ctx.dry_run {
        return Ok(Envelope::success(
            ctx.environment,
            ctx.dry_run,
            json!({
                "action": "would_settle",
                "task_id": task_id.to_string(),
                "escrow_id": escrow_id_hex,
                "deadline": deadline_unix,
                "domain": {
                    "chain_id": chain_id,
                    "verifying_contract": verifying_contract_str,
                },
                "signature": signature_hex,
            }),
        ));
    }

    // 10. Live POST. `signature` is a plain string in the current spec; the
    //     `0x`-prefixed 65-byte EIP-712 shape is validated server-side. A
    //     malformed value here would mean `sign_distribution` regressed
    //     (crypto-layer bug), not a network/server issue.
    let body = SettleTaskBody {
        signature: signature_hex,
    };
    let resp = match client.inner().settle_task(&task_id, &body).await {
        Ok(v) => v.into_inner(),
        Err(e) => {
            let err = map_api_error(e).await;
            // gh#143: auto-disburse can win the race between our preflight
            // GET and this signed POST — a 409 `task_not_eligible` /
            // `escrow_not_ready` then describes a task that already settled.
            // Re-check the status and report success with a note. Genuine
            // rejections (deadline_expired, signer_mismatch, …) and a
            // re-check that finds no advancement stay errors.
            if matches!(&err, taskfast_client::Error::Validation { code, .. }
                if matches!(code.as_str(), "task_not_eligible" | "escrow_not_ready"))
            {
                if let Ok(advanced) = client.inner().get_task(&task_id).await {
                    let advanced = advanced.into_inner();
                    if let Some(note) = advanced.status.as_deref().and_then(settlement_note) {
                        return Ok(Envelope::success(
                            ctx.environment,
                            ctx.dry_run,
                            json!({
                                "task_id": task_id.to_string(),
                                "status": advanced.status,
                                "note": note,
                            }),
                        ));
                    }
                }
            }
            return Err(err.into());
        }
    };

    Ok(Envelope::success(
        ctx.environment,
        ctx.dry_run,
        json!({
            "task_id": resp.task_id,
            "status": resp.status,
        }),
    ))
}

/// gh#143 note for a task whose settlement already happened (or is in
/// flight) without this poster's explicit settle — the dev auto-disburse
/// race. Every other status returns `None`: a settle problem there is a
/// genuine failure, not an idempotent replay.
fn settlement_note(status: &str) -> Option<&'static str> {
    match status {
        "settled" => Some("already settled"),
        "disbursement_pending" => Some("settlement underway"),
        _ => None,
    }
}