> ## Documentation Index
> Fetch the complete documentation index at: https://mx-6c34bcc6.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# wattswarm task — Task Submission and Lifecycle Commands

> Reference for all wattswarm task subcommands: submit contracts, watch lifecycle state, fetch decisions, and run complete end-to-end flows.

The `task` command group lets you submit task contracts to the kernel, observe their lifecycle as they move through execution and verification rounds, and retrieve the finalized decision. The `task run-real` subcommand combines all of these steps into a single end-to-end flow that drives a real HTTP runtime through the full WattSwarm task lifecycle.

***

## `task submit`

Submit a `TaskContract` JSON file to the local node.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] task submit <file>
```

**Arguments**

| Argument | Description                         |
| -------- | ----------------------------------- |
| `<file>` | Path to a `TaskContract` JSON file. |

**Description**

Reads the JSON file, parses it as a `TaskContract`, and emits a `TASK_CREATED` event into the local event log. The task enters the `pending` state and is now eligible for claim by an executor. Call `task watch <task_id>` to observe its progress, or use `task run-real` to execute the full lifecycle immediately.

**Example**

```bash theme={null}
wattswarm --state-dir ./.ws-dev task submit ./task.json
# Output: submitted task-abc-001
```

### Sample `task.json`

```json theme={null}
{
  "protocol_version": "v0.1",
  "task_id": "task-abc-001",
  "task_type": "swarm",
  "inputs": {
    "prompt": "Analyse the risks in the attached proposal and return a structured summary.",
    "document_ref": "https://storage.example.com/proposal-v3.pdf"
  },
  "output_schema": {
    "type": "object",
    "required": ["answer", "confidence"],
    "properties": {
      "answer":     { "type": "string" },
      "confidence": { "type": "number" }
    }
  },
  "budget": {
    "time_ms": 30000,
    "max_steps": 10,
    "cost_units": 1000,
    "explore_cost_units": 350,
    "verify_cost_units": 450,
    "finalize_cost_units": 200,
    "reuse_verify_time_ms": 20000,
    "reuse_verify_cost_units": 200,
    "reuse_max_attempts": 1
  },
  "assignment": {
    "mode": "CLAIM",
    "claim": { "lease_ms": 5000, "max_concurrency": { "propose": 1, "verify": 1 } },
    "explore": { "max_proposers": 1, "topk": 3 },
    "verify":   { "max_verifiers": 1 },
    "finalize": { "max_finalizers": 1 }
  },
  "acceptance": {
    "quorum_threshold": 1,
    "verifier_policy": {
      "policy_id": "vp.schema_only.v1",
      "policy_version": "1",
      "policy_hash": "sha256:...",
      "policy_params": {}
    },
    "vote": { "commit_reveal": true, "reveal_deadline_ms": 10000 },
    "settlement": {
      "window_ms": 86400000,
      "implicit_weight": 0.1,
      "implicit_diminishing_returns": { "W": 10, "K": 50 },
      "bad_penalty": { "P": 3 },
      "feedback": { "mode": "CAPABILITY", "authority_pubkey": "ed25519:..." }
    },
    "da_quorum_threshold": 1
  },
  "expiry_ms": 1718030000000,
  "evidence_policy": {
    "max_inline_evidence_bytes": 65536,
    "max_inline_media_bytes": 0,
    "inline_mime_allowlist": ["application/json", "text/plain"]
  }
}
```

<Tip>
  Use the kernel UI at `http://127.0.0.1:7788/` and click **Task → SAMPLE** to generate a valid task contract template you can save and customise.
</Tip>

***

## `task watch`

Poll task status until the task reaches a terminal state.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] task watch <task_id>
```

**Arguments**

| Argument    | Description                                                              |
| ----------- | ------------------------------------------------------------------------ |
| `<task_id>` | The task ID to observe (must match `task_id` in the submitted contract). |

**Description**

Reads the current task view from the local projection and prints the task state, committed candidate ID, and finalised candidate ID. For a live polling loop, call this command in a shell loop or use `task run-real --task-id` which blocks until the task is complete.

**Example**

```bash theme={null}
wattswarm --state-dir ./.ws-dev task watch task-abc-001
# Output:
# task=task-abc-001 state=Some("FINALIZED") committed=Some("cand-7a3f") finalized=Some("cand-7a3f")
```

***

## `task decision`

Fetch the finalized decision for a completed task.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] task decision <task_id>
```

**Arguments**

| Argument    | Description                            |
| ----------- | -------------------------------------- |
| `<task_id>` | The task ID to fetch the decision for. |

**Description**

Reads the task view from the local projection and prints the committed and finalised candidate IDs. Use `task watch` first to confirm the task has reached a terminal state before calling `task decision`.

**Example**

```bash theme={null}
wattswarm --state-dir ./.ws-dev task decision task-abc-001
# Output:
# task=task-abc-001 committed=Some("cand-7a3f") finalized=Some("cand-7a3f")
```

***

## `task run-real`

Run the complete task lifecycle end-to-end against a registered executor runtime.

**Synopsis**

```bash theme={null}
wattswarm [--state-dir <path>] [--store <name>] task run-real \
  --executor <name> \
  --profile <profile> \
  [--task-id <id>] \
  [--file <path>]
```

**Flags**

| Flag         | Default        | Description                                                                                                               |
| ------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `--executor` | (required)     | Name of the registered executor runtime to use (as added with `executors add`).                                           |
| `--profile`  | `default`      | Execution profile to pass to the runtime in every `/execute` and `/verify` request.                                       |
| `--task-id`  | auto-generated | Task ID to use. If the task does not already exist in the store, WattSwarm creates a default contract for it.             |
| `--file`     | —              | Path to a `TaskContract` JSON file. When provided, the contract is loaded from this file instead of the default template. |

**Description**

`task run-real` drives the full WattSwarm task lifecycle in a single blocking call:

```
TASK_CREATED
  → TASK_CLAIMED (propose)
  → CANDIDATE_PROPOSED
  → TASK_CLAIMED (verify)
  → EVIDENCE_AVAILABLE
  → VERIFIER_RESULT_SUBMITTED
  → VOTE_COMMIT
  → VOTE_REVEAL
  → DECISION_COMMITTED
  → DECISION_FINALIZED
```

All HTTP calls go directly to the registered executor via `POST /execute` and `POST /verify`. When the flow completes, the command prints the full decision result as pretty-printed JSON.

**Examples**

```bash theme={null}
# Run with the default task template
wattswarm --state-dir ./.ws-dev task run-real \
  --executor rt \
  --profile default \
  --task-id task-real-1

# Run with a custom task contract file
wattswarm --state-dir ./.ws-dev task run-real \
  --executor rt \
  --profile default \
  --file ./task.json
```

```json theme={null}
// Example output
{
  "task_id": "task-real-1",
  "status": "FINALIZED",
  "finalized_candidate_id": "cand-7a3f",
  "output": {
    "answer": "default::Analyse the risks...",
    "confidence": 0.93
  }
}
```

<Warning>
  The executor runtime must be running and reachable at its registered `base_url` before you call `task run-real`. Use `executors check <name>` to verify connectivity first.
</Warning>