Skip to main content

Workflows and Today

mecha workflow today brings urgent work, decisions, verified results and waiting work into one readout. It includes pending drafts and unanswered questions even when you have not created a workflow. A source that cannot be read is reported as unavailable.

In the web interface the workflows themselves are a view of the task board — Tasks → workflows — and the home page's Follow-through line opens it. Drafts and questions stay where they are answered: the outbox under Review, and the board's waiting view.

Delegating a task creates a workflow automatically. The same record follows its web conversation, background work and answered questions. It links the existing task and conversation to drafts, questions and completion checks. After a crash, partial drafts remain discoverable and the workflow shows the interruption. The workflow retains its latest 128 lifecycle events; session transcripts keep the full conversations. Reminder deduplication survives history pruning and restarts.

Track a commitment​

For work outside a delegated task, create a workflow and use the returned ID:

mecha workflow add "Prepare the grant reply" --workspace ./grant
mecha workflow commit FLOW_ID --party "Priya" --source "owner instruction" \
  --due 2026-10-15T17:00:00Z --follow-up 2026-10-14T09:00:00Z
mecha workflow today
mecha workflow show FLOW_ID

Two optional flags say what the commitment means to the other party, in your words: --expectation "the tracked-changes version before the panel meets" and --consequence "the panel reviews the old draft". They are recorded on the commitment and shown by workflow show. Each must be 1–4096 bytes; an empty or longer value is refused and nothing is recorded.

A commitment you state in appraisal evidence uses the same record. It carries only the dates you wrote in it: none in the original beneficiary shape, and whatever due_at / follow_up_at you include in the record shape. mecha never supplies a date. An undated commitment has no deadline stated: it is never marked overdue, never raises a follow-up reminder, and both workflow today and the web workflows view say "no deadline stated" rather than showing a date.

Commitments are entered by you. Messages are not automatically treated as promises. Neither appraisal nor its per-commitment guilt reads workflow commitments or checks yet; they are tracked here, not scored there. Times must include a timezone or UTC offset.

Check the result​

Specify what would establish completion:

mecha workflow check FLOW_ID --artifact reply.md --contains "tracked-changes version"
mecha workflow check FLOW_ID --delivered OUTBOX_ID
mecha workflow verify FLOW_ID
mecha workflow close FLOW_ID

Artifact paths are confined to the workflow's recorded workspace. Checks read regular UTF-8 files up to 4 MiB. A delivery check requires a recorded successful send; a staged draft or unknown delivery cannot pass. workflow today rereads the evidence, and closing checks it again. A workflow with no checks is not marked verified. A content check proves the specified text exists, not that an entire document is correct. Rejected drafts and abandoned questions count as resolved decisions, so they do not block corrected work forever. Rejection never satisfies a delivery check: remove or replace an obsolete check explicitly with workflow uncheck and workflow check.

workflow uncheck FLOW_ID 1 removes the first check. workflow cancel FLOW_ID --reason "Plans changed" cancels tracking and blocks further runs on its task — mecha tasks work, a web chat on the task, an answered question resuming it, and workflow resume — until you run mecha workflow reopen FLOW_ID. Triggers are not tied to a task, so a cancelled workflow does not stop one. Cancellation does not claim success and requires an active runner to be stopped first. Closing a workflow leaves graph task closure to mecha tasks set.

In the web interface, open Tasks → workflows, expand Finished workflows at the bottom and choose Reopen workflow to continue a finished or cancelled task conversation. This preserves the launch gates while making completion reversible from a phone.

Each of these is also your verdict on the session that did the work, and appraisal reads it: closing counts for that session, cancelling and reopening a closed workflow count against it, and a verify whose artifact check fails counts against it once. mecha keeps every verify you run, with the session it checked, so a failure is not lost when the task is resumed. Nothing here asks you for anything extra.

If a crash or reboot leaves a task blocked by a stale running process ID, first confirm the previous run has stopped, then record that evidence:

mecha workflow recover FLOW_ID --reason "Host rebooted; previous run ended"
mecha workflow resume FLOW_ID

Recovery clears the stale runner record. It does not stop a process or resolve pending drafts, questions or uncertain deliveries; review those before resuming.

Continue work in order​

mecha workflow depend FOLLOWUP_ID PREPARATION_ID
mecha workflow resume FOLLOWUP_ID

Dependencies must exist, cannot form cycles, and must be completed before a successor starts. Resume continues the recorded task conversation in its workspace, retaining approval and taint rules. Resolve outstanding questions and drafts first.

Reminders that respect your day​

mecha workflow attention --timezone America/New_York \
  --quiet-start 22 --quiet-end 8 --digest-hour 8
mecha workflow tick --dry-run
mecha workflow tick
mecha workflow snooze FLOW_ID 2026-10-16T09:00:00-04:00
mecha workflow ack FLOW_ID

The trigger daemon also runs the follow-up tick. Reminders are coalesced in-app, deduplicated across restarts, and withheld during quiet hours. Unconfigured timing uses UTC. A missed day produces the current digest, not a backlog of old notices. Overdue work stays visible when its reminders are snoozed. The tick observes linked changes and produces reminders; it does not start a model or send external messages.

Resolve an uncertain delivery​

If a send loses its response or its process stops, the outbox retains an unknown attempt and blocks resending. Check the destination's history, then record what you established in the outbox's web detail or the CLI:

mecha outbox reconcile DRAFT_ID --outcome delivered --evidence "Sent message m-123"
mecha outbox reconcile DRAFT_ID --outcome not-delivered --evidence "Destination check established no delivery"

Run only the command matching your finding. Reconciliation never sends. Confirming non-delivery enables a fresh review and retry; confirming delivery resolves the draft.

Choose a smaller tool set​

mecha --tool-profile assistant chat
mecha --tool-profile research run "Research the public documentation"
mecha --tool-profile coding run "Fix the failing build"

Profiles narrow the actual registry once, compose with --tool and are inherited by subagents. Research retains public readers; coding adds workspace/code tools; assistant retains readers, selected private-work tools and configured staged actions. The assistant profile excludes shell. Profiles can also be saved by trigger add. They retain all existing approval, sandbox and taint protections.

Structured extraction​

After verifying support on your endpoint, set the provider's structured_output to json_schema (OpenAI-shaped or Anthropic schema format) or llama_json (the llama-server JSON-object/schema format). The default is disabled. Frontdoor and mail classification then request constrained responses while keeping their tools and conversation history absent. Semantic validation still runs.

The wire contracts follow OpenAI structured outputs, Anthropic structured outputs, and the llama-server documentation. Endpoint compatibility alone does not establish schema enforcement.

Evaluate follow-through​

eval/assistant-lifetime.toml runs five sequential fixture tasks over three seeds. It checks delivered reply content, thread identity, calendar time and attendees, and duplicate effects after the simulated owner reviews drafts. Trial output also records requested owner-action counts. These counts include unsuccessful requests and do not measure human time.

mecha exp new eval/assistant-lifetime.toml
mecha exp run assistant-follow-through
mecha exp export assistant-follow-through

The fixture world is isolated from live mail and calendar accounts. Restart, ambiguous-delivery, stale-artifact and reminder-timing scenarios also have deterministic workspace tests.

The assistant lifetime manifest also sets [fixtures.clock]: each task gets an explicit simulated instant shared by the model's date prompt and the fixture mail and board servers. The follow-up now occurs on the next simulated day. This does not change the machine clock or audit timestamps.

Cases with expect.judge require an explicit [judge] provider and model in an experiment manifest. The judge receives recorded tool evidence, and a failed or unavailable judge fails its check. These checks supplement artifact checks; model verdicts still need review. The assistant manifest uses the local Qwen model as its judge, so its verdict is not independent of the model under test: read a judged score beside the transcripts it graded, not on its own.

The assistant's date prompt includes a computed local calendar reference from yesterday through the coming week. It supplies weekday/date pairs across daylight saving, month and year boundaries. Grounded rubric checks receive this recorded context as well as tool evidence.