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.

campaign start
  -> ordinary Pretorin preflight (once for the target workspace and scope)
      -> frozen resolver verdicts + active recipe pins
  -> local parent Campaign Plan
      -> 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

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 local parent Plan 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/version/managed status/SHA-256 identity, Hatchet engine/SDK version, concurrency and retry settings, publication policy, and review policy. The CLI also prepares the ordinary Pretorin preflight once and freezes its resolver verdicts, active recipe pins, and content digest on the Campaign. The CLI creates or strictly reconciles every deterministic child Plan before dispatch; each child Plan freezes one item’s exact scope and expected outputs. Bounded Campaign state tracks attempts, Hatchet correlation IDs, process facts, resource receipts, and aggregate progress.

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 Plan, reads that child Plan, activates and advances the required steps, reads the coordinator-owned preflight snapshot and active recipe pins, selects and runs recipes, 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 or weakened. 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:

• 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.

Observe and hand off

campaign status <campaign-plan-id> reports persisted execution, assessment, and last-recorded review aggregates without querying the platform. 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 the three axes separate and shows Plan steps, attempt and Hatchet IDs, objective coverage, shared preflight context, recipes, resource IDs, and platform review identity. Press q to detach without cancellation.

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.