Your first task

This page walks one real task end to end. Each step says what you should see, and where to look when something goes wrong.

Before you start

Three things need to be true: the model gateway is configured and usable, your account has membership rights in the current workspace, and you have saved a personal access token for the Git service you are targeting.

The task creation page will not let you type a repository URL by hand. The platform lists the Git services you have configured a personal token for, then has the server query — using your decrypted token — the repositories you are entitled to. Once you pick a repository it queries the branches, and prefers the default branch the provider reports.

The point of this indirection is that an invalid token, or one without repository access, fails the task during preflight rather than halfway through execution.

Step 1: Submit the requirement

Task creation is requirement-first, in that order, and the ordering is deliberate.

Requirement sources is a multi-line field, and the lines together make up one requirement: Markdown documents, Git issues, enterprise document links, enterprise messaging links. Each line is independent — switching the source type of one line affects only that line, and editing one line does not rewrite the content of another.

Online sources need a URL. The platform reads the issue title server-side using the current user's credentials and validates the link against the configured connector. The browser never talks to the provider's API directly.

Task name is filled in automatically to cut down on repeated typing. The name walks the source lines in order and takes the first usable title: for Markdown it extracts the first level-one heading that is not inside a code fence, falling back to the file name; for an issue it reads the real title through the provider, and keeps a placeholder while continuing the creation flow if that fails. The automatic value follows your sources only while you have not edited the name yourself; once you have typed a non-empty name, later source changes will not overwrite it.

Flow mode defaults to smart orchestration. On submit, preflight retrieves, evaluates and prefers to reuse an existing flow, and generates a task-scoped temporary flow only when nothing fits.

Advanced users can switch to using an existing flow, choosing from a compact selector a published version visible in the current workspace. Doing so expands only those dynamic fields of that version's input contract that cannot be derived.

Creating a flow opens a separate authoring page; long-lived asset editing is deliberately kept out of the task form.

Step 2: Read the preflight

On submit, the task is persisted and an identifier returned first, after which it enters the user-visible preflight stage. At this point no sandbox resource has been created.

Preflight does the following, in order:

1. resolves identity, workspace, requirement, repository, branch and available capabilities;
2. freezes the existing version you chose, or runs retrieval, evaluation, adaptation and generation;
3. normalises the flow through the shared deterministic compiler, validating the dependency graph, schemas, artefacts, capabilities, permissions and risk;
4. persists the risk, confidence and approval-required assessment;
5. freezes the initial execution flow snapshot, the execution specification and the exact capability lock;
6. creates a sandbox only if everything above passed.

While preflight runs you can watch flow retrieval, generation, risk and freezing progress. On failure the task keeps its structured check results and a repair entry point: no runtime resource is created, and there is no silent fallback to broader permissions.

The most common causes of a preflight failure are an unreachable repository or branch, a missing or expired personal token, and a flow declaring a capability that is unavailable in your current workspace.

Step 3: Watch execution

Once preflight passes, provisioning begins: repository clone, requirement materialisation, runtime preparation and agent start-up, in that order.

The task detail view keeps a stable two-column relationship, with the agent session on the left and the evidence rail on the right. The rail is a single-level state machine: by default it shows the whole dependency graph, and selecting a node replaces the entire rail with that node's overview, from which you switch between code, artefacts, trace and agent. The top of the detail view gives you an explicit way back to the flow.

Node detail discloses progressively, in the order conclusion → contract → evidence → source:

• Overview leads with a skimmable execution conclusion, then shows the input and output contract, the task context, and the frozen code and artefact evidence;
• Code shows the code revision and the full code tree as frozen when that attempt completed; it does not read the final task branch;
• Artefacts shows the frozen result summary, the artefact manifest and the declared handoff artefacts; it does not expose arbitrary runtime files;
• Trace shows a summary of the node's calls;
• Agent shows the runtime, model and capabilities with their versions and lock information.

The file reader shows the original path, byte size, media type and content identifier. Text is read page by page with encoding boundaries preserved; binary content is offered only as an original-file download.

Step 4: Confirm the artefacts

Whether a node succeeded is deterministic, and does not rest on a natural-language claim:

• every required artefact declared by the flow has been produced;
• the artefact manifest exists, is non-empty, and can enumerate the actual artefacts;
• the result summary exists with valid content;
• every unit gate passes.

A unit gate is a shell command you declare on the node — a build, a test, a static check. The runner executes it only in this attempt's own worktree and judges the result by exit code. On failure it first sends the command, the exit code and the controlled output back to the current agent session, and runs a bounded number of repair reruns within the same attempt.

Every successful attempt freezes its own code revision under a dedicated ref. After the worktree is released, that revision can still be listed and read page by page.

Step 5: Take delivery

Once the delivery node's artefact contract and all upstream gates have passed, the runner enters a controlled completion step: it pushes the final checkpoint branch and idempotently creates or resolves a change request keyed by task identifier.

The node is marked complete only after the real provider, number, branch and URL have been written into its result. The Git credentials used by this step are never visible to the agent session, the prompt, the tool environment or the artefacts.

If the change-request creation response is lost, a retry must look up the original change request rather than create a second one. A branch of the same name that lacks the matching task marker is refused instead of overwritten.

The delivery summary aggregates the final result, the tests and the change request. It reports the outcome of artefact verification; it does not restate lifecycle state.

Failure and recovery

Failures come in several kinds, and they are handled differently.

Execution-level failures — gateway timeouts, process crashes, command timeouts, a missing protocol — count towards retry. The platform prefers to resume the original session, and creates a new one only when reliable resumption is not possible.

Semantic rework deals with an upstream artefact defect that a downstream node has confirmed. Rework always creates a new session, a new attempt and a new artefact version, and its target must be a legitimate producer node of the artefact in question — it cannot be chosen mechanically as the previous node in execution order.

A terminally failed task can be rerun for a single failed node. A rerun does not rewrite the failure record: it appends the current attempt to history and creates a new one. Artefacts and code revisions from completed upstream nodes are reused as frozen evidence rather than recomputed.

When the model returns an empty response, the runner classifies it by type and starts a bounded number of recovery sessions. Once those are exhausted it keeps an explicit node failure, so you can rerun that node on its own after updating the model or the connector; an empty response is never dressed up as a completion.

Every limit — maximum attempts per node, maximum reworks per target, total reworks, maximum gate repairs per attempt — is frozen explicitly by the flow, and nodes cannot override them. Once any limit trips, the task fails.