Tasks & the queue

The task queue is Forven's universal record of work. Every action an agent takes, every MCP call, and every scheduled routine run becomes a task with its own lifecycle and audit trail. When something stalls, errors, or behaves unexpectedly, the queue is where you go to read exactly what happened — tool call by tool call.

This page is for operators. It covers the /tasks queue, the /tasks/[id] detail view, and how to recover stalled work safely.

What a task is

A task is an atomic unit of work assigned to an agent or an MCP server. It carries a status, an assigned agent and model, timestamps, and a full audit log of everything it did. Tasks are created by the agents layer, by scheduled routines, and by MCP clients — you do not usually create them by hand.

Tasks move through a fixed lifecycle:

pending → running → (done | failed | blocked | rejected)

A task that is paused can be resumed in place. A task that has already reached done or failed is terminal — it cannot be re-run from the queue (see Recovering stalled work below).

The queue (/tasks)

Open Tasks from the sidebar to reach the queue at /tasks. It lists work across the whole system, newest activity first.

Filtering by bucket

A bucket is a grouping of tasks by status. The queue exposes one tab per bucket:

Status is colour-coded in the list so you can scan a bucket at a glance. Alongside the bucket tabs you can:

• Search by task ID or text.
• Filter by agent or model using the toggle controls.
• Paginate through long histories.

What you'll see

The queue is a list of task rows with bucket tabs across the top and agent-filter toggles. Each row shows the task's status (colour-coded), its agent, and timing. The list refreshes in real time: Forven listens for task_completed and related WebSocket events and falls back to polling if the socket drops, so a running task updates without a manual reload.

The task detail page (/tasks/[id])

Click any row to open its detail page at /tasks/[id]. This is the audit record for a single task, organised into tabs.

Overview

Status, assigned agent and model, timestamps, duration, and headline metrics. Start here to see whether the task succeeded and how long it took.

Audit Log

The lifecycle timeline — events emitted as the task's execution container is created, execution starts, and execution completes or errors. Entries are timestamped, and failures carry an error badge so you can find the moment things went wrong.

Tool Calls

Every tool the task invoked, in order, with:

• the tool's input and output,
• its duration,
• and any error it raised.

This is the most useful tab when debugging an agent: it shows the exact sequence of actions and the precise call that broke.

Task Data

The task's input and output payloads as JSON.

Raw

The complete raw JSON record for the task, for when you need the underlying fields the structured tabs don't surface.

Motion Log

A separate tab that tracks promotions and demotions — strategy movements through the pipeline. You can filter the motion log by scope (pipeline versus live trading) and by type, which makes it a quick way to answer "what got promoted, and by which task?"

Inspecting a failed task

When a task lands in the failed bucket, the detail page gives you a clean path to the root cause.

Steps

1. Open /tasks and select the Failed bucket, or search for the task ID or agent.
2. Click the task row to open /tasks/[id].
3. Read the Overview tab: status, assigned agent, timestamps, and duration.
4. Open the Audit Log tab to follow the lifecycle events — container created, execution started, execution completed or errored — and find the failing step by its error badge.
5. Open the Tool Calls tab to see each tool invocation with its input, output, and the specific error.
6. Check the Task Data tab for the input/output JSON if the failure is data-shaped.
7. If the work can be re-attempted by a different agent, assign the error to an agent and let it retry.
8. If it is not fixable, mark it dismissed so it clears from the dashboard's alert counts.

What you'll see

The detail page opens on Overview with five tabs (Overview, Audit, Tools, Data, Raw) plus the Motion Log tab. The Audit Log and Tool Calls tabs render as timelines with timestamps and red error badges on the entries that failed — your eye goes straight to the break.

Pausing and resuming

A running task can be paused, which moves it to the paused bucket, and a paused task can be resumed in place. This is for work that is actively executing.

Terminal tasks are different. Once a task is done or failed it cannot be restarted from the queue. To re-attempt completed-but-incomplete work, use the resumable tasks list on the /diagnostics page, which re-triggers stalled or partial executions explicitly.

Recovering stalled work

Resuming a stalled task can re-run real side effects. Read this before you click resume.

The /diagnostics page surfaces a resumable tasks list: executions that stopped partway and can be re-triggered. Most are safe to resume. A few are not, and Forven asks for confirmation before resuming external-mutating task types — notably:

• trade_execution — re-running this can place real orders.
• phantom_repair — this reconciles position state against the exchange.

Treat these the way you would any other live action: confirm only when you understand what the original task was doing and what re-running it will repeat. When in doubt, inspect the task's Tool Calls tab first to see exactly which side-effecting calls it made.

Caveats

• Stages are immutable. A strategy's pipeline stage (for example quick_screen, gauntlet, paper, live_graduated) only changes through a promotion or demotion task. You cannot edit a stage directly; the Motion Log records every transition.
• Terminal means terminal. done and failed tasks are not resumable from the queue — go through /diagnostics.
• Realtime is best-effort. The queue prefers WebSocket events and falls back to polling. If a panel looks stale during a socket drop, it will reconcile on the next poll.
• Confirm external-mutating resumes. trade_execution and phantom_repair resumes touch real positions; the confirmation prompt exists for a reason.

Forven is a research tool. The task queue records what the system did, not what markets will do — results are not predictive, and nothing here is financial advice.

Related

• Agents — the layer that creates and runs most tasks.
• Scheduled routines — cron workflows whose runs appear here.
• Troubleshooting & recovery — stuck schedulers, stale locks, and deeper recovery.