Campaign workflow

A Campaign is local orchestration around the existing Pretorin workflow, Plan, MCP, and platform surfaces. Use it when a bounded set is too large for one agent session—for example an entire control family or framework.

CLI campaign start --dry-run OR MCP check_campaign_runtime
  -> local execution-dependency gate (before external reads or local writes)
  -> for MCP, launch_ready=true -> preview_campaign
  -> ordinary Pretorin source preflight (once for the target workspace and scope)
      -> frozen resolver verdicts + active recipe pins
  -> local draft parent Campaign Plan + deterministic child drafts
  -> CLI confirmation OR MCP start_campaign(plan ID + digest + confirmed=true)
      -> recheck execution dependencies
      -> embedded Hatchet dispatch
          -> deterministic local child Plan per item
              -> selected workflow + read-only preflight snapshot + recipes
              -> existing typed MCP platform writes
              -> existing platform review only when explicitly configured
      -> deterministic local aggregate + platform review handoff

check_campaign_runtime reports execution and observer dependencies, selected agent and embedded Hatchet runtimes, blocking failures, and native setup that may be deferred until confirmed start. It never contacts the platform, downloads or installs software, reserves an idempotency key, or writes a Plan. For a configured or PATH agent executable, the check freezes its resolved path and content identity without launching it; version and capability validation are reported separately as deferred_validation and occur only after explicit start confirmation. When it returns launch_ready=false, stop. Apply its remediation outside MCP, restart the server, and check again before preview.

Pretorin does not run a Campaign-specific LLM. Each isolated child session uses the Codex or OpenCode harness selected through the shared agent configuration. Recipes and workflows are markdown playbooks that agent reads; they are not server-side runtimes.

Authority boundaries

The shared transport-neutral coordinator creates the local parent Plan and freezes Campaign type, selector, ordered item/objective roster, harness/model/provider/reasoning effort, the Codex model endpoint or effective OpenAI/Anthropic OpenCode provider endpoint, exact executable source, managed status, and SHA-256 identity, plus the maintained version when known, Hatchet engine/SDK version, concurrency and retry settings, publication policy, and review policy. The CLI and MCP adapters both ask the coordinator to prepare the ordinary Pretorin preflight once and freeze its resolver verdicts, active recipe pins, and content digest on the Campaign. The coordinator creates or strictly reconciles a deterministic child draft before dispatch. That draft binds one item’s exact scope, expected outputs, and mandatory workflow/process milestones; it does not prescribe the agent’s full execution sequence. The child authors that sequence from the selected MCP workflow when it activates the Plan. The activated structure then becomes the stable retry contract. Bounded Campaign state tracks attempts, Hatchet correlation IDs, process facts, resource receipts, and aggregate progress.

CLI/MCP adapter fields are excluded from that semantic definition. In particular, MCP’s durable preview idempotency key lives only in a sidecar reservation; it cannot change Campaign identity, Plans, effects, or the confirmation digest. All new parent/child creation and transitions use the surface-neutral campaign-coordinator actor and v2 launch contract.

The portable reasoning-effort values are low, medium, and high. An explicit campaign start --reasoning-effort wins over the selected harness’s saved setting; if neither is present, the provider/harness default is used. Once prepared, the effective optional value is part of the frozen assignment, so retry and resume cannot follow a later configuration change. Codex consumes the setting natively. OpenCode consumes it as --variant; each attempt checks the exact authenticated model metadata first and rejects an unsupported portable variant instead of silently falling back.

The existing platform remains authoritative for evidence, mappings, narratives, objective implementations, Issues, review jobs/findings, and human approval. The local store never copies those artifact bodies and cannot approve a control. No platform Campaign API, Campaign database model, shared Plan repository, or Campaign-specific UI is required.

Execution protocol

Hatchet assigns a frozen item to an isolated process for the selected harness. The child calls start_task with its trusted parent_plan_id and campaign_context, adopts the selected workflow and assigned child draft, and reads both. The child then authors and activates its own ordered Plan with campaign-preflight first, the final mandatory anchor last, and its concrete work between the anchors exposed by that workflow and draft. Campaign choreography cannot replace the workflow’s evidence contract or discard the child’s additional steps. The child advances its activated Plan, reads the coordinator-owned preflight snapshot and active recipe pins, completes evidence discovery and applicable recipe work, then records an authoritative expectation-mapping checkpoint before assessment. It publishes through existing typed Plan-scoped writers, records resource receipts and objective dispositions, writes every frozen objective’s truthful agent draft plus exact evidence roster as in_progress through the existing objective API, requests platform review only when the Campaign explicitly authorizes it, and completes its Plan. The worker never calls objective approval or parent-control approval.

The worker MCP profile limits reads and writes to the assignment and validates the current attempt before dispatching any handler or recipe. A child may read only its own Plan; Issue- and evidence-ID children use exact inspectors instead of enumerating sibling records. It withholds Campaign finalization, generic proposal/apply, destructive evidence operations, human approval, and cross-item access. Required workflow/Plan steps cannot be removed, reordered, or weakened, but the child can add its own steps and completion criteria when activating the Plan. The selected harness receives one ephemeral home/config, the assigned Pretorin MCP server only, a read-only workspace, and no edit/write, web, or delegated-task tools. OpenCode denies its native shell; Codex permits sandboxed read-only commands whose environment excludes all model, platform, and source credentials.

Model-provider credentials, the Pretorin platform key, and evidence-source credentials are separate trust domains. Source values are resolved fresh for the exact system/framework attempt only when its authoritative preflight artifact authorizes that source; credential values are not copied into Plans, Campaign records, harness config, or observer events.

Preflight is one shared input to the work, not a per-child Campaign phase. The coordinator prepares it through the same implementation used before an interactive agent task. Each child and retry receives a private read-only copy; it cannot verify, refresh, mutate, reprovision, or record preflight again. Source coverage and limitations inform the best-effort assessment but do not act as a readiness gate. Recipe IDs must be trusted package built-ins, and a selected recipe must match the exact active content pin. No source is a valid process condition. An empty platform evidence search is not enough when the shared preflight exposes an applicable pinned recipe backed by a ready source; the worker must complete that recipe attempt before disposition. The attempt may truthfully produce no evidence, and no runnable source remains a valid specific limitation:

• grounded requires persisted platform evidence;
• gap requires governed Issue admission plus either pre-existing scoped evidence or a server-verified workspace path, bounded line range, and whole-file SHA-256; free-form observation prose is insufficient;
• needs_input requires a coverage limitation or evidence request and is not itself an execution failure; and
• an evidence request remains a next action, never an evidence artifact.

Durability and replay

Embedded Hatchet owns dispatch, per-Campaign concurrency, retry/backoff, cancellation, and run IDs. Local code does not add another queue or concurrency limiter. Duplicate delivery of a succeeded item returns its saved state without starting an agent.

Parent and child Plan IDs are the recovery identities. Retry and restart reuse the same deterministic child Plan. Resume adopts a persisted non-terminal Hatchet run when one exists and submits only work without a live run; an explicit resume from completed_with_errors reopens failed children only. The frozen harness/model and exact runtime source/version/identity are revalidated on each attempt, so configuration or PATH changes cannot redirect an existing Campaign. The preflight snapshot is reused verbatim across retry and restart; later canonical preflight changes apply only to newly prepared work. Resume authenticates the frozen Campaign and complete parent/child Plan hierarchy before it reopens Plans, reconciles orphan attempts, installs a runtime, or dispatches anything. Logical platform-write identities make a committed response loss replay-safe, and local finalization is atomic and exactly once. A cancellation command first persists the request; a live worker may acknowledge the terminal state only after Hatchet stops outstanding runs. Recovery is supported on the same host; multi-host execution is deferred until Plans are shared.

Preparation and Campaign state use schema v2. It freezes resolved system/framework IDs, coordinator and launch-contract versions, roster, hierarchy, template and effect-policy hashes, exact authorized effects, the launch-definition SHA-256, and durable confirmation time. CLI and MCP reject v0.29.3 Plan-backed state with campaign_state_version_unsupported; listing skips and counts it. This does not affect the separate deprecated checkpoint records and compatibility tools.

Observe and hand off

campaign status <campaign-plan-id> reports persisted execution, assessment, evidence-requirement coverage from each child Plan’s verified mapping step, and last-recorded review aggregates without querying the platform. Coverage reports active requirements as covered or uncovered and counts intentionally unbound evidence separately; it never implies objective or control approval. Partial aggregates are labeled as known coverage. Pending, loading, or unavailable mappings are explicit instead of appearing as zero requirements. Legacy mapping records without the current authority-verification marker remain readable, but their coverage is reported as unavailable rather than trusted. campaign watch <campaign-plan-id> is a read-only projection that additionally refreshes recorded queued/running review jobs and overlays their live state without mutating the Campaign record. It keeps execution, assessment, evidence-requirement coverage, and review separate while showing Plan steps, attempt and Hatchet IDs, objective-disposition progress, shared preflight context, recipes, resource IDs, and platform review identity. Press q to detach without cancellation.

get_campaign returns the same persisted projection in an MCP-safe bounded form: immutable item pages default to 10 and cap at 20; Campaign-list pages default to 20 and cap at 50. Its execution, assessment, verified-coverage, and review fields match the overlapping CLI fields exactly. Local get/list/cancel continue to work during a platform auth or consent outage; preview/start/resume still require current platform and frozen-authority validation.

Every MCP response for one Campaign includes the exact same-host watch command and a version-matched registry fallback:

pretorin campaign watch <campaign-plan-id>
uvx --from "pretorin==0.29.10" pretorin campaign watch <campaign-plan-id>

The MCP server never runs these strings or streams a terminal over JSON-RPC. The operator launches one on the MCP server’s host; q safely detaches.

After automated work finishes, continue review in the existing Pretorin control and review experience. A completed Campaign says that its declared process ran; it does not say a human approved the controls.

See Campaign CLI for commands, runtime management, and the legacy checkpoint migration.