list_tasks

List tasks with pagination, projection, filters, and cron-spam exclusion.

list_tasks

List tasks registered in VantagePeers, newest-updated first, with pagination, projection (lite|full), status filters, and the excludeAutoGenerated cron-spam filter introduced in PR-E.

Args

Arg	Type	Default	Description
`assignedTo`	string	—	Filter by assignee (e.g. `"pi"`).
`status`	string \| string[] \| alias	—	Single status, array, or alias (`"open"`, `"active"`, `"all"`).
`missionId`	string	—	Filter to tasks belonging to a specific mission.
`createdBy`	string	—	Filter by creator (e.g. `"sigma"`).
`updatedSince`	number	—	Epoch ms. Returns tasks with `updatedAt >= this`.
`createdBefore`	number	—	Epoch ms. Pagination anchor (legacy; prefer `cursor`).
`limit`	number 1-200	`50`	Page size.
`cursor`	string	—	Opaque pagination token returned as `nextCursor` from prior call.
`fields`	`"lite" \| "full"`	`"full"`	`"lite"` returns compact projection (7 keys). `"full"` returns complete task object.
`excludeAutoGenerated`	boolean	`false`	When `true`, filters out cron-generated tasks. Default `false` — backward-compatible.

Returns

{
  items: Task[] | TaskLite[],
  nextCursor: string | null
}

nextCursor is null when the current page is the last one; non-null when more rows exist.

Examples

Default query (all open tasks for an agent)

// call
{ "assignedTo": "pi", "status": "open", "fields": "lite", "limit": 30 }

// response
{
  "items": [
    {
      "_id": "k17xxx...",
      "_creationTime": 1782050000000,
      "title": "Review PR-E docs",
      "status": "review",
      "priority": "high",
      "assignedTo": "pi",
      "missionId": "k571gcctka8mq5jbkgpj0a0b2n892ctg"
    }
  ],
  "nextCursor": null
}

Exclude cron-generated tasks (`excludeAutoGenerated=true`)

// call — Pi queue cleaned of cron-spam (audit §13: 152 cron tasks)
{ "assignedTo": "pi", "status": "open", "excludeAutoGenerated": true, "limit": 50 }

// response — only human-dispatched tasks; cron-bot + check-messages rows absent
{
  "items": [
    {
      "_id": "k17yyy...",
      "_creationTime": 1782050100000,
      "title": "Validate VP-MCP PR-E",
      "status": "todo",
      "priority": "high",
      "assignedTo": "pi",
      "missionId": "k571gcctka8mq5jbkgpj0a0b2n892ctg"
    }
  ],
  "nextCursor": "eyJ0aW1lIjoxNzgyMDUwMDAwMDAwLCJpZCI6Ims1eHh4In0="
}

Paginate through results

// page 1
{ "assignedTo": "pi", "status": "open", "excludeAutoGenerated": true, "limit": 50 }
// → { items: [...], nextCursor: "..." }

// page 2 (use nextCursor)
{ "assignedTo": "pi", "status": "open", "excludeAutoGenerated": true, "limit": 50, "cursor": "<nextCursor from page 1>" }

`excludeAutoGenerated` cron contract

The excludeAutoGenerated filter removes tasks that match either of these predicates:

Predicate	Pattern	Example matches	Example non-matches
`createdBy`	`/^cron-/i` (dash mandatory)	`cron-bot`, `cron-daily`	`cronus`, `cron` (no dash)
`title`	`/^\/?check-messages$/i` (whole-string, optional leading slash)	`check-messages`, `/check-messages`, `CHECK-MESSAGES`	`check-messages-v2`, `run check-messages`

Filter placement: applied in-memory in the list query handler, after createdBy / updatedSince / createdBefore filters, before filterByOrgScope and envelope assembly.

Post-filter pages may be smaller than limit because filtered rows do not count toward the page fill. This is by design — the cron-spam catalog is small and narrowly targeted, so pages will rarely shrink significantly. If you need exactly N human tasks, over-fetch with a larger limit and truncate client-side.

`fields=lite` projection

"lite" returns 7 stable keys: _id, _creationTime, title, status, priority, assignedTo, missionId.

Full task object ("full") includes: description, createdBy, completionNote, dependsOn, blockedBy, startedAt, completedAt, updatedAt, tags, and all other schema fields.

Status aliases

Alias	Expands to
`"open"`	`["todo", "in_progress", "review", "blocked"]`
`"active"`	`["todo", "in_progress"]`
`"all"`	No filter — returns all statuses

Why this matters

Before PR-E: list_tasks had no way to hide automatically-generated tasks (cron-dispatched tasks, check-messages entries). Pi's queue accumulated 152 cron-spawned tasks (audit §13), making it difficult to see human-dispatched work without manual filtering.

excludeAutoGenerated=true hides these rows server-side with zero API surface change — existing callers are unaffected. Audit ref: analysis/mcp-crud-baseline-vp-audit-2026-06-14.md section 13. Mission k571gcctka8mq5jbkgpj0a0b2n892ctg (VP-MCP top level Bloc A), RED eb78cfa, GREEN 74dea44.

list_tasks

On this page