From "Run" to delivery

This page walks the entire path a mission takes from a user clicking Run in the app to the delivered work landing on the review surface — every hop, and what data moves at each one. Architecture gives the seven-step summary; this is the expansion, with file-level detail for anyone debugging or extending the launch path. The agent protocol covers steps 6–9 from the agent’s point of view; this page covers the same ground from the system’s point of view, plus everything before and after.

1. The user clicks Run

   The web app calls POST /api/objectives/:id/launch with the chosen agent, model, and reasoning effort. This is a request to run one objective — one agent pass — not the whole mission.

2. The backend validates and queues

   In a single transaction, the backend:

   • Confirms the objective is in a launchable state (draft, submitted, or launching). By default no other objective on the same mission may already be active — only one objective per mission runs at a time. When the mission has allowParallelObjectives on, a second objective may queue whatever its resource_key: two objectives on the same checkout are separated later, at branch preparation, rather than being refused here.
   • Resolves the execution target: which of the project’s linked resources (repos/checkouts) this objective runs against, and confirms that resource is actually connected on some runner.
   • Persists the chosen assigned_agent / model / reasoning_effort onto the objective and flips its state to launching.
   • Resolves the effective launch config (any project-level pre-command or agent flags).
   • Writes a new execution request row with status queued, plus the corresponding mission-event and entity-change records.

   Nothing has started running yet — an execution request is a job sitting in a queue, scoped to a workspace/project.

3. A runner claims the request

   A runner (a small process running wherever you want missions to execute — your laptop, a dedicated box, a pod) polls POST /api/runner/claim with its project scope and a device fingerprint. The backend atomically claims the oldest matching queued request for that runner so two runners can never grab the same request. The runner immediately reports back launching status for the claimed request.

4. The branch is prepared (if enabled)

   If worktree/branch automation is on for the project, the runner prepares a branch or worktree for the objective before starting the agent, then records the prepared branch back to the mission (active_branch).

   When the mission allows parallel objectives and a sibling on the same resource is already running, the runner does not drop this objective into the sibling’s dirty checkout. It cuts a per-objective branch — <mission branch>-<objective display key>, e.g. objective-centric-execution-756-k7xm — off the branch it would otherwise have shared and adds a second worktree for it, exactly as it would for a mission whose branch has already been merged. That branch is recorded on the objective and leaves the mission’s active_branch alone. Missions that run without worktrees have one checkout, and concurrent objectives share it.

5. The runner builds and sends the launch payload

   This is the step where the most data gets assembled, all inside the CLI’s launchAgent / buildLaunchPlan:

   • Mission context. The runner fetches the mission, its event history, artifacts, and any objective attachments, and assembles a markdown briefing — including an explicit directive to start the objective immediately and only stop to ask a question when genuinely blocked. This is written to a temp file (.overlord/tmp/objective-<mission>-<key>.md) that gets passed to the agent as its system-prompt file.

   • Project resources. The runner calls the protocol’s load-context endpoint to resolve every logical resource linked to the project for this execution target — not just the one being launched into. Each resource carries a resourceKey, a path (populated only if that resource is actually checked out on this machine, otherwise explicitly marked unavailable), and a connection state.

   • Environment variables. The spawned process inherits the runner’s full environment (which is how the ambient OVERLORD_USER_TOKEN reaches the agent) plus these launch-specific vars:

     Variable	Contents
     MISSION_ID / OVERLORD_MISSION_ID	The mission being worked.
     OVERLORD_OBJECTIVE_ID	Objective display id (e.g. coo:756.k7xm). Forwarded on attach as --objective-id so the session cannot rediscover a different objective.
     OVERLORD_BACKEND_URL	Which backend the agent’s CLI/MCP calls should hit.
     OVERLORD_EXECUTION_REQUEST_ID	Set when the launch is execution-request-driven; forwarded on attach so the resulting session links back to this exact request. If --objective-id is omitted, this id also pins the objective.
     OVERLORD_WORKING_DIRECTORY	Absolute path the agent terminal cds into.
     OVERLORD_CONTEXT_FILE	Absolute path of the markdown briefing under .overlord/tmp/.
     OVERLORD_TMPDIR / TMPDIR / TMP / TEMP	Project-scoped scratch directory.
     OVERLORD_PROJECT_RESOURCES	JSON array of every linked resource and its resolved path/state, set only when the project has resources. This is the plural manifest — see Project resources at launch below.
     OVERLORD_PROJECT_RESOURCES_PATHS	Comma-separated connected resource paths with explicit :rw/:ro permission suffixes.
     OVERLORD_PROJECT_RESOURCES_PATHS_CSV	Alias of OVERLORD_PROJECT_RESOURCES_PATHS (same :rw/:ro-suffixed CSV list for agent-pod allowlists).
     OVERLORD_PRIMARY_RESOURCE_PATH	Path of the primary (else current) connected resource, or empty.
     project launchEnvVars	User-defined NAME=value pairs from Project Settings, with {VAR} placeholders already substituted.

   • Launch preparation. After cd and env exports, the terminal runs the project’s preLaunchCommands (also with {VAR} already substituted), then starts the agent. See Launch variable library for what {VAR} can resolve to at this step versus later at attach.

   • The command itself. The runner maps the chosen agent key to a concrete CLI invocation (for example, Claude Code becomes claude --append-system-prompt-file <context-file> [--model] [--effort] <launch-message>) and spawns it — either inline or via a terminal-launcher script, in the working directory of the resolved execution-target resource.

   On success the runner reports launched back to the backend; on failure it reports failed with the error, and the objective does not proceed.

6. The agent attaches

   The freshly launched agent runs ovld protocol attach --mission-id … --objective-id … (directly, or via the MCP overlord_attach_session tool, which shells to the same command). The CLI also forwards OVERLORD_OBJECTIVE_ID and OVERLORD_EXECUTION_REQUEST_ID from the launch environment. Attaching is itself the transactional go-ahead to start work: the backend pins the named objective (or the execution request’s objective, or today’s active-objective picker if neither pin is present), sets it to executing, ensures the next draft objective exists, moves the mission into execute phase, opens an agent_sessions row, and — if OVERLORD_EXECUTION_REQUEST_ID was forwarded — links that session back to the execution request from step 2. Latch session name/title use the objective display id (coo:756.k7xm — title).

   The attach response is the full context payload described in The agent protocol: the current objective, previous/future objectives, history, artifacts, attachments, shared state, the same projectResources array from step 5, and agentInstructions. Attach also records the exact objective/session binding used by local connector evidence; it does not inspect Git or snapshot the worktree.

7. The agent works and reports

   The agent posts narrative updates (ovld protocol update) or lightweight heartbeats while it works, and can post a blocking question (ovld protocol ask) and stop if it needs a human decision. None of this changes the objective’s terminal state.

8. The agent delivers

   ovld protocol deliver closes out the objective in one transaction:

   • Best-effort drains every bounded batch from the objective/session change ledger. Per-item warnings and unavailable sync never reject delivery.
   • Validates the summary and writes deliveries, optional artifacts and rationale annotations, and a delivery-type mission event.
   • Normalizes optional delivery evidence (human actions, tradeoffs, risks, deferred work, and assumptions), stores a deterministic presentation, and queues optional AI composition without delaying the delivery transaction.
   • Enqueues the mission.delivered webhook event.
   • Moves the objective to complete and enqueues objective.completed.
   • Moves the agent_sessions row to delivered / review phase, and the mission to review.

9. Auto-advance (optional)

   Immediately after delivery, if the mission has auto_advance enabled and a next draft objective exists, the backend inherits the agent/model/effort from the objective that just delivered (where unset), sets the next objective to launching, and calls the same execution-request creation used in step 2 — re-entering this whole chain for the next objective. If auto_advance is off, the next objective is left awaiting_approval instead.

10. Webhooks fan out the delivery

    Each enqueued webhook event (mission.delivered, objective.completed, and any others matching the mission’s transitions) is written to a durable outbox table, not sent synchronously from the request that created it. A separate dispatcher polls the outbox roughly every second, claims a batch, signs each payload (HMAC), and POSTs it to every subscription that matches the event type and project. Failed deliveries retry with backoff and auto-disable after repeated failures. See Webhooks for the payload shape and how to consume it.

11. Review reads the durable records back

    Nothing in review is derived live from the agent’s session — the review surface reads the deliveries, artifacts, optional change_rationales, and changed-file observations written in step 8. File observations remain visible without prose.

Launch variable library

Project Settings → Launch exposes two launch-preparation editors (preLaunchCommands and launchEnvVars) and an Available launch variables library. Both editors accept {VAR_NAME} placeholders. Substitution runs once inside buildLaunchPlan — after the working directory, context file, tmp dir, and project resources are known, and before the terminal exports env or runs prep commands.

Stage	What exists	Usable in {VAR}?
Queue / claim (steps 2–3)	Execution request, agent/model, project settings snapshot (preLaunchCommands, launchEnvVars)	No — values are still templates
Branch / worktree prep (step 4)	Resolved working directory (checkout or worktree)	Not yet — substitution has not run
Plan build (start of step 5)	Mission briefing file, resource manifest, Overlord launch env, derived path helpers	Yes — this is when {VAR} resolves
Terminal env export (step 5)	All plan-build vars + substituted user launchEnvVars exported into the process	N/A — already resolved; shell uses $NAME for user vars
Pre-launch commands (step 5)	Same env; commands run with literals (placeholders already gone)	No further {VAR} pass
Attach (step 6)	Full attach payload: objective, history, artifacts, attachments, projectResources, sessionKey, …	No — attach fields are not launch-prep placeholders

Syntax rules:

• {VAR} always means Overlord launch context (see LAUNCH_VARIABLES in @overlord/contract).
• User-defined launch env vars are referenced with shell $NAME after export — not with {NAME}.
• Unknown {VAR} tokens are left verbatim so mistypes stay visible in the launched command/env.

The built-in catalog (also shown in the Project Settings library) includes mission/backend ids, working directory, context file, tmp paths, the JSON resource manifest, space- and comma-separated resource paths, and the primary resource path. The set is intentionally open-ended and grows as more plan-build context is wired in.

Project resources at launch

A mission’s project can span more than one linked resource (for example, a backend repo and a separate frontend repo). Two things are true at once:

• The working directory is single-valued. The agent’s terminal only ever cds into the one resource resolved as the execution target for this objective.
• The data available to the agent is plural. Both OVERLORD_PROJECT_RESOURCES (env var, set at launch) and the projectResources field of the attach response (set at attach) list every resource linked to the project, each with its own resourceKey and path — not just the one being launched into.

Caution

A sibling resource’s path is only populated if that resource is actually checked out/connected on the same machine running the launch. If it’s linked in the project but not present locally, its entry comes through with a null path and a state marking it unavailable, rather than a real filesystem path. Treat siblings as read-only context unless a future objective explicitly launches into them.

Related

• Architecture — the condensed, seven-step version of this same flow, with links to the contract-pinned specs each step is drawn from (modules 4 and 3 cover launch and protocol in full).
• The agent protocol — steps 6–9 above, written for the agent following them rather than the system executing them.
• Webhooks — the payload envelope and delivery guarantees for step 10.