Skip to main content
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 
wattswarm [--state-dir <path>] [--store <name>] task submit <file>
Arguments
ArgumentDescription
<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 
wattswarm --state-dir ./.ws-dev task submit ./task.json
# Output: submitted task-abc-001

​
Sample task.json

{
  "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"]
  }
}
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.

​
task watch

Poll task status until the task reaches a terminal state. Synopsis 
wattswarm [--state-dir <path>] [--store <name>] task watch <task_id>
Arguments
ArgumentDescription
<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 
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 
wattswarm [--state-dir <path>] [--store <name>] task decision <task_id>
Arguments
ArgumentDescription
<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 
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 
wattswarm [--state-dir <path>] [--store <name>] task run-real \
  --executor <name> \
  --profile <profile> \
  [--task-id <id>] \
  [--file <path>]
Flags
FlagDefaultDescription
--executor(required)Name of the registered executor runtime to use (as added with executors add).
--profiledefaultExecution profile to pass to the runtime in every /execute and /verify request.
--task-idauto-generatedTask 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 
# 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

// Example output
{
  "task_id": "task-real-1",
  "status": "FINALIZED",
  "finalized_candidate_id": "cand-7a3f",
  "output": {
    "answer": "default::Analyse the risks...",
    "confidence": 0.93
  }
}
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.