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

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

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

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

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

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

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

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

# 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.