Chapter 5 — Tasks, dispatch, and runs

A Task is what you ask for in the composer. A Run is what actually happened—live terminal output plus history. This chapter covers sending tasks, optional Playbook and folder settings, honest progress UI, and follow-ups like Run again and continue conversation.

Background: Chapter 0 vocabulary · Dispatch mechanics (Q&A): harness, workflow, agent runs to Mac.

This chapter is where three pillars meet daily work: easy authoring (composer + More options), learn from usage (Run again, Save as playbook, honest outcomes), and efficient memory (continue conversation, search past Runs). See four pillars and north star vs today.

#Task composer — minimum viable send

Open a project, then choose New task.
Assign to a bot on that project.
Write what needs doing — concrete scope beats vague “fix everything.”
Click Send task when enabled.

Project folders, playbooks, and writer CLI choices still apply when a bot runs work on a linked computer. Marketplace Start a task after install should open New task on the project you just installed into.

If Send is disabled, fix what the Send readiness banner says first—empty prompt, Mac offline, update needed, reconnecting, etc. (reason codes). The product blocks bad sends instead of dropping tasks silently.

When the banner says a coding tool is not signed in on the project computer, use Sign in to … on the same notice. That asks AgentWitch on this computer to open the tool’s login flow (same path as Setup → AI tools). On the Mac app, Computer → AI tools and the menu bar popover also show Sign in per tool.

#More options (progressive disclosure)

Expand More options when you need more than Mac + prompt:

Option	User meaning	Honest limits
Repository / code folder	Where the writer CLI runs on the computer	Browser cannot pick a real POSIX path via native dialog—type a path you know, use defaults, or set folder in AgentWitch on this computer (folder picker Q&A).
Playbook	Rules/skills/templates installed on the computer	Files live under `~/.agent-witch/harness/`; installing from Marketplace is a separate flow (dispatch Q&A).
Writer	Which local CLI (Cursor, Claude Code, …)	Must exist on the computer. A missing writer API key that still runs the CLI shows Completed with fallback. If the CLI cannot start, the run shows Failed — Writer API key missing and Claude CLI can’t run.

Company-only hints (run on behalf, policy) appear when org rules exist—not on every solo Home.

#What happens when you Send (user-level)

Console creates an agent run record in the cloud.
It builds a prompt payload (plus optional folder, playbook/capability id, writer).
It delivers command.claude.run (name is historical) to your computer over the AgentWitch WebSocket—or queues it in the outbox if the computer is fresh but not live on this server (ADR 0005).
Your computer runs the writer in a real shell; output streams to the browser.
Terminal outcome is stored for Runs / reports.

Workflows with multiple steps and human checkpoints reuse the same computer path per agent step; checkpoints pause in the browser, not on the computer (official workflow checkpoints Q&A).

Optional Cursor Cloud dispatch (when configured) targets cloud agents instead of your computer— not a hidden substitute for local execution (Chapter 0 — misconceptions).

#Queued vs failed (honest copy)

Message theme	Meaning
Mac is reconnecting. Your task will send when it checks in.	HTTP accepted; outbox will flush when hub socket is live—common right after Console deploy.
Try again in a few seconds.	Interactive retry path—not the same as queued writer ack.
Mac offline	No dispatch; fix connect chapter—not “wait silently forever.”
This computer is not linked	No row is This computer. Connect this computer on Home links the computer you are using.

Details: Reconnecting vs local live · No Connect button · Duplicate computers from Connect · Deleting a Mac.

Seen recently means that computer checked in within the last minute or so. Opening Connect this computer does not count as a check-in. Clicking it again replaces the unused link instead of adding Mac 2.

#Watching a Run — progress honesty

Live UI uses locked outcome chips—do not show Success while still connecting (run UX honesty):

Chip	When
Connecting	Log not attached yet (`starting`).
In progress	Streaming output (`streaming`).
Waiting on you	Agent emitted `[[AWAITING_INPUT]]`—answer in UI; Mac waits.
Success	Finished cleanly.
Completed with fallback	Finished with degraded path (e.g. CLI fallback when writer API key missing).
Failed / Stopped / Timed out	Terminal failure modes.

One primary log surface per run—avoid duplicate “success” chrome elsewhere.

#Git check on the computer (git repos only)

When your code folder is a git repository, the computer records a short git verdict after the writer finishes—before/after dirty paths and a summary of tracked changes vs HEAD. It is stored in the computer run report details (alongside the agent’s own summary), not as a separate Console screen.

You might see in details	Meaning
`clean before run` / `clean after run`	Working tree had no uncommitted paths (porcelain empty).
`N dirty path(s)`	Uncommitted or untracked paths counted at snapshot time.
`diff vs HEAD: …`	Short `git diff --shortstat` after the run (may be empty if nothing tracked changed).
`Git: not a repository`	Folder is not a git checkout—no worktree verdict beyond that line.

This supports learn from usage (pillar 2): Success in the Console can still mean “CLI exited cleanly” while the verdict shows whether files actually changed. It does not block Send or replace Runs history in the cloud by itself.

#Runs list and actions

Open Runs to:

Action	Use
Inspect output	Audit what the agent did.
Run again	Repeat task with edits—core learn from usage loop after a rough or good Run.
Save as playbook	Reuse instructions you approve (Chapter 7)—nothing changes on the Mac until you accept install/save flows.
Continue conversation	Follow-up messages while session is warm—or Continue from history with `sourceRunId` (delegate local CLI context Q&A).

Search past runs (when offered) pulls useful context from earlier Runs (efficient memory)—UI avoids the word “Knowledge.” Not every prior run is replayed automatically; scope improves over time (north star vs today).

On the Mac, the writer may also receive project snippets and “avoid repeating” notes from past failures before it runs—the Knowledge page on AgentWitch on this computer shows what was saved and how often it was reused (Chapter 4 — Local knowledge). That stays on your machine until you explicitly promote or publish something in the Console.

Team filters (who, which Mac, playbook, date) support audit—not required for solo makers.

#Project Reports tab (your turns + auto skills)

Inside a project, Reports lists work your coding tools filed from this account (often after a Cursor/Claude chat turn on a linked computer). Each row can show what auto skills decided:

Label	Meaning
Skill suggested	A reusable procedure was drafted; the owner can save it from Library.
One-off work / Routine work	Judged not worth a new skill (or already routine).
Judge could not answer	The auto-skills judge (your pinned CLI, or auto: CLI then local Ollama) could not finish. Open the hint (ⓘ) for the reason when your Mac reported one (usage limit, timeout, Ollama down).
Skipped: hourly limit	Live judging hit the hourly cap; not the same as judge failure.

Retry (owner, on this Mac only) re-runs the judge for that turn. The button appears only when this browser can read the full turn from AgentWitch on this computer—that requires project computer history on for that project. If history is off, there is no Retry button; the hint explains that you need history on (or Scan past tasks for older work stored on the Mac). Pick the judge above the list (Cursor, Ollama, or auto) if Cursor is out of usage.

#Announcements (people and assistants)

Announcements are short-lived notices at global, team, or project scope (for example a model promo or maintenance window). Authors post from Admin → Announcements for everyone, Admin → Groups → Team announcements, or Project → Overview when they have permission.

Surface	Behavior
Project → Overview	Live list; Got it records server read state for you.
Notifications (header)	Join/run approvals, announcement cards, and other notes; unread count is per browser (see below).
Assistant inbox	On create, each active assistant seat gets a system `announcement` message (wake + delete-on-read) so bots see it in project context and in `get_project_briefing`.

#Header notifications (bell)

Open Notifications from the header bell or /notifications. Filter All, Unread, or Approvals.

Action you take	What happens
Approve, Allow, or Decline on a card	The card is marked read right away (unread dot and bell badge update). Resolved approvals may still appear under All until the list refreshes.
A row link (for example Open billing, Also on This computer, Also in … › Access)	Marked read when you follow the link.
Mark as read	Marks read without taking the main action.
Mark all read	Clears unread for every card in the list.

Home Needs you uses the same read state: Open project on a run approval marks that notification read when you click it.

Announcements are not writer Tasks—they do not start a Run by themselves. Feature detail: src/features/announcements/README.md.

#Continue conversation (follow-up Tasks)

Two paths users feel as “same chat”:

Situation	Behavior
Second message while live panel still open	Hot `--continue` on supported writers when session is warm.
Continue from job detail / history	Cold start may inject truncated prior transcript from Mac storage (`~/.agent-witch/writer-sessions/`) or built continuation prompt from a prior run id.

Ending a writer session on the computer clears hot continue until the next fresh dispatch. Details: delegate local CLI Q&A.

#Mid-run input

When output shows Waiting on you, respond in the Console—the computer stores pending checkpoints and resumes the shell when you answer. Do not expect the agent to guess passwords or ambiguous choices. Engineers: mid-run input protocol in .cursor/rules/agent-run-input-protocol.mdc and src/features/agent-witch/.

#Project chat and inbox (local CLI assistants)

Codex, Cursor, Claude Code, and Gemini seats on a project wake through AgentWitch Local (agent run on the project Mac)—not through “check inbox on demand” polling.

What you see	What to do
Assistant Offline in chat	Connect the project computer; keep AWL running and start the assistant with `agent run` for that seat.
Message saved but not signed in (warning after send)	Click Sign in to … on the warning, finish login on the Mac, then send again.
Inbox dispatch Waiting on you — sign in	Same Sign in control on the toast when the computer blocks dispatch for a signed-out writer.
Failed task with a not signed in hint	Use Sign in to … in the task detail box, or pick another writer in More options.

Access → People lists each coding tool on a linked computer; Sign in needed includes the same one-click sign-in when you are in the browser on that Mac (or when AWC can reach it over the WebSocket).

#Writer routing (advanced, still user-relevant)

If your org configures cascade routing, the Console may pick among writers by policy—that affects which CLI runs, not whether work stays on the computer. See writer dispatch cascade Q&A when troubleshooting “wrong tool ran.”

#Practical task patterns

Pattern	Tip
Repo work	Set folder on computer first; reference repo name in prompt.
Small verification	Short prompt + explicit “list only, do not delete.”
Long jobs	Watch In progress; session limits may time out with honest stop chip.
Team visibility	Same run appears in shared Runs once dispatched under team account.

Test dispatch without Home: developer ws-test UI (local bridge).

#Sending a Task from an external AI

After the AI opens /for-agents from the homepage prompt and registers (method none or agentmail), it runs get_install_command on its computer, saves a workflow with create_workflow, and installs the Playbook with install_harness. Before send_task, it runs the prompt optimizer on this computer (http://127.0.0.1:43347/prompt-optimizer/agent) in the project folder, so the judge and improver can read the Playbook and the code. It does not ask you to paste the prompt into a different optimizer. run_workflow and send_task use the same Run pipeline as the composer. If list_macs is empty, the install command has not finished. Read status with list_runs and get_run. The home page section Prompt optimizer states why that local score is the one to trust. That section stays in the main Home column. The extra onboarding column is omitted once getting-started hints are hidden, so the welcome panel and this section use the full content width.

#Query aliases

send task AgentWitch, dispatch run, composer Send blocked
run again continue conversation, waiting on you AWAITING_INPUT
gui task AgentWitch, xem run, terminal honesty Connecting In progress
thuc thi task tren Mac, dispatch outbox reconnecting
git verdict run report details Mac repository dirty paths
project folder playbook writer more options New task
learn from usage run again save playbook, efficient memory continue conversation
hoc tu loi run lai, luu playbook, tiet kiem ngữ cảnh task truoc
Reports Judge could not answer Retry auto skills project history
bao cao auto skills khong danh gia duoc, nut Retry may