Module queue 

The task queue: what magi should do next, and who asked for it.

The queue is what lets magi run unattended. magi serve takes the next task, runs the graph on it, records the outcome, and takes the next one.

It is also the reason an agent can ask for work. magi task add is the whole interface, and it is the same command whether a human types it at a prompt, a phone posts it through the web UI, or an implementer inside a run shells out to it because it noticed something worth doing but out of scope. magi’s CLI is the operating surface for both kinds of user; the queue is where their intentions meet.

One task is one JSON file under Queue’s root. Files rather than a database because the operator has to be able to read, edit, and delete the backlog with the tools already on the machine, and because a crashed daemon must leave a queue the next one can pick up without recovery ceremony.

Shape

Task is data plus pure state transitions - Task::fail decides whether an attempt was the last one, and touches no disk. Queue owns all I/O and is constructed with its root, so a test drives a real queue in a temp directory without setting a process-global home. Splitting them this way is why the retry policy below can be asserted directly.

Bounded by construction

An autonomous loop that retries forever is a way to spend money on a task that cannot succeed. Every claim increments Task::attempts; a task that has burned its attempts becomes TaskStatus::Held and waits for a human rather than for another agent.

Structs

AnsweredQuestion

One question crate::conduct asked about a task, and what the operator said back. See Task::answers.

ChatNotice

The final state of a chat-filed task that was already reported (or skipped).

Claim

Exclusive ownership of a task, released on drop.

FollowUp

What a follow-up task came from. See Task::followup.

NoticeCause

Facts a producer can independently attest about a held outcome.

OperatorResume

A triage “resume” answer and what became of it. See Task::resume_override.

Queue

A queue on disk.

Removal

What Queue::remove did, beyond deleting the named task’s own file.

Resumption

Durable scope of an explicit operator resumption, surviving run startup.

RunOverrides

Command-line choices carried by a task. See Task::overrides.

Task

One unit of work.

TaskCounts

How many tasks sit in each TaskStatus, for a dashboard tile — never a per-task view, so it carries no ids.

TaskPass

One settled pass over a run. See Task::passes.

Enums

ChatNoticeOutcome

What became of a completion notice. See Task::chat_notice.

Dependency

Unknown and ambiguous dependencies stay waiting; neither is evidence that the operator deleted a prerequisite or needs to supply its replacement.

HoldSource

Who placed the current hold.

PassCost

What a settled pass did to the attempt budget.

Source

Where a task came from. Recorded because “who asked for this” is the first question about an autonomous run, and the answer is not recoverable later.

TaskStatus

Where a task is in its life.

Constants

CHAT_NODE

The node a Source::Agent carries when the asker is a chat conversation (its run is then the conversation’s id).

SCHEMA

On-disk format for a queued task. Bumped when a field’s meaning changes.

Functions

deleted_blockers

Return the original references, so legacy short ids are removed by the same Task transition as full ids.

dependency

Resolve against authoritative task, question and deletion record names.

dependency_facts

Live queue facts for decision and deputy prompts. Historical hold reasons and question text are claims, never an inventory of existing prerequisites.

missing_blocker_hold_reason

The hold_reason text for a task quarantined because one or more of its blocked_by ids no longer exist. Shared by crate::daemon::resolve_blockers, crate::triage::run_once, and Queue::remove’s own dependent quarantine, so the three call sites read as the same event to an operator looking at magi task show rather than three different wordings for it.

missing_blocker_hold_reason_in

missing_blocker_hold_reason in language (Japanese, else English).

missing_blockers

Only a successful directory scan with no matching record proves absence.

normalize_blockers

Canonicalize only proven dependencies, preserving unknown legacy references.

short

The last dash-separated part of an id, the form people say aloud.

title_from

The first line of a task, trimmed to a title. Used when the caller gives a body but no title, which is the normal case for an agent piping a file in.