Orchestration

Orchestration is the Decision plane that turns a CompiledContext into a typed DecisionRecord. It is a bounded triad — Planner, Executor, Critic — running under one Run Context with explicit budgets, isolated subagent lanes, and durable background sessions.

Definition

A control loop with three roles that advance only when required deterministic boundary checks pass. The Planner produces a typed plan; the Executor runs only verified plan steps through the Tool Gateway; the Critic verifies the plan, scores each completed step, and decides accept / retry / replan / escalate. Agreement among model roles cannot waive authority, approval, active boundaries, data policy or budget.

The compatible Execution Contract adds explicit run states, operation identity, checkpoints, current ownership and aggregate reservations. Its deterministic transitions describe intended updates; production durability, atomic stores, schedulers and target fencing require runtime evidence.

Why it exists

A single agentic loop conflates planning, execution, and judgment, making failures uninterpretable and replays unreliable. Splitting them gives the runtime three independently auditable artifacts (plan, transcript, verdict), enables replay without re-executing tools, and lets each role enforce its own budget.

How it works

1. Plan: the Planner reads the CompiledContext and produces a typed Plan with steps, tool intents, decision checkpoints, and dependencies. It cannot execute side effects.
2. Verify: the Critic checks the plan against tool allow-lists, evidence requirements, capability bindings, native-risk policy, the v1 safety ceiling, and decision rules.
3. Execute: the Executor runs only verified steps via the Tool Gateway, which re-evaluates actual arguments, authority, native risk, approval obligations, idempotency, and budget.
4. Score: the Critic scores each completed step and the run as a whole against evaluators.
5. Decide: the Critic emits one of accept / retry / replan / escalate. Replans return control to the Planner under a re-plan budget.

Bounded planner / executor / critic

The triad is the heart of the Decision plane:

• Planner — typed plan only; no side effects. Sees the full CompiledContext. Cap: planner timeout (5–30s by task class).
• Executor — runs verified plan steps only. Cannot extend the plan; if a step fails or returns unexpected evidence, control returns to the Planner with a structured reason. Cap: per-step timeout (adapter-specific).
• Critic — verifies plans, scores steps, and renders the final verdict. Operates on plan + transcripts; can re-derive its verdict offline during replay.

This separation makes the runtime debuggable by role and enables replay. Deterministic checks must reproduce exactly from pinned inputs. Model-based critique may vary, so its prompt/model lineage and original verdict are recorded and compared with declared properties or scorecards rather than assumed byte-identical.

Plan structure

{
  "plan_id": "plan_refund_01",
  "intent": "support.refund",
  "steps": [
    { "id": "s1", "tool": "adp_orders.lookup", "params": { "order_id": "ord_881" } },
    { "id": "s2", "tool": "adp_policy.eval", "depends_on": ["s1"] },
    { "id": "s3", "tool": "adp_payments.issue_refund",
      "depends_on": ["s2"],
      "approval_mode": "destructive",
      "requires": ["GATE_FINANCE_APPROVAL"] }
  ],
  "decision_checkpoints": [
    { "decision_id": "support.refund.execute", "after_step": "s2" }
  ]
}

Risk- and obligation-aware routing

The Orchestrator reads the capability’s native ActionRisk, v1 projection, and policy obligations:

• Calls execute inline only when policy, identity, evidence, data, destination, budget, and approval checks are satisfied.
• A named approval obligation creates a propose → approve → execute sub-sequence with a frozen evidence/argument snapshot.
• Network interaction alone does not imply human approval, and a low v1 mode does not waive a gate selected from another native-risk dimension.
• A model cannot remove a required gate or lower the registered risk by changing the plan label.

Subagent lanes

Long-horizon or parallelizable work runs in isolated lanes:

• Each lane is spawned with its own Run Context, token budget, tool surface, and trace span.
• The parent Run Context observes lane completion as a typed envelope; lane traces are stitched into the parent trace.
• Lanes cannot mutate the parent’s effects[]; they propose results that the parent’s Critic accepts or rejects.
• Lane-level loop guards trip independently from the parent.

Child authority narrows every ancestor’s current mandate, with exact parent/child/root binding, revocation and inherited deadline. reserveChildBudget reserves from the original parent’s pool before fan-out; root model calls, retries and replans use that same pool through reserveBudget. Verified cumulative terminal usage releases unused capacity; unknown usage retains it. Child credentials, output admission and cancellation propagation remain independent obligations, so an accepted result cannot expand the parent or another lane’s authority.

Context inheritance is separate from lane isolation

Lane isolation governs authority, budgets, mutable state, and effects. It does not require every worker to rediscover the parent’s evidence. A runtime may initialize a child with a fresh assignment, selected evidence, or eligible parent history. These are implementation profile choices, not new values in AgentDelegationEnvelope.effect_policy.

For every spawn, the runtime must:

• bind the existing delegation envelope and independently enforce the child’s scope, classification ceiling, expiry, tool surface, and sub-budget;
• apply context admission to copied material, preserving source, freshness, and trust labels; copied conversation and tool output cannot become authoritative policy;
• retain the selected context policy, parent checkpoint or artifact references, and admitted/omitted evidence in a locally versioned trace attachment;
• keep the child’s output and effect acceptance separate from context inheritance; sharing history grants no permission to mutate parent state.

Workers continuing a diagnosed task may benefit from eligible history. An independent reviewer should receive requirements, the fixed artifact, and testable evidence without the author’s proposed verdict by default. Any subsequent exposure to that interpretation must be recorded. Fresh context alone is not proof of independent assurance; measure missed defects, unsupported findings, and dependence on shared evidence or methods.

LangChain’s implemented context modes motivate this distinction. ContextOS adopts the separation of information and authority, not a requirement to use that framework or to copy its full state. Compare policies using the paired evaluation protocol.

Deliberation is not certification

Adding agents can increase search breadth, but agreement does not prove correctness. ContextOS uses a five-step coordination protocol for material decisions:

1. Isolate: independent lanes start with bounded contexts and do not see one another’s answer by default.
2. Deliberate over evidence: lanes exchange cited claims, counterexamples, uncertainties, and requested checks—not authority or mutable parent state.
3. Preserve the minority: dissenting evidence remains attached to the decision; a majority cannot erase it from the trace.
4. Certify externally: a verifier checks the proposed outcome against independent evidence, method, authority, or state. The assurance level scales with ActionRisk.
5. Decide once: one accountable parent runtime owns the final verdict, approval request, and external effect.

Consensus, voting, and self-critique are reasoning methods inside the Decision plane. They never replace policy, approval, source-of-truth checks, tool postconditions, or an evaluator outside the proposer failure domain.

Passive awareness channel

Parallel lanes may publish bounded evidence messages so useful findings arrive without forcing synchronous meetings. A message declares sender lane, parent run, subject, evidence references, confidence/uncertainty, sensitivity, TTL, and intended recipients. Delivery occurs only at orchestrator-defined safe points and is recorded in each recipient’s trajectory.

The channel is lane-isolated, size- and rate-bounded, deduplicated, and backpressured. Recipients can accept, reject, or ignore a message; the sender cannot mutate their context or plan. Messages inherit tenant and classification constraints and cannot carry delegated authority, approvals, or new capabilities.

Durable background sessions

Hour-scale workflows run as durable sessions that persist across process restarts.

Session contract

An implementation accepting mode: "long_running" needs a durable controller. The following Session object is an illustrative application view, not a replacement for the additive RunExecutionState/ExecutionCheckpoint attachments:

{
  "session_id": "sess_inv_22",
  "tenant_id": "tenant_acme_prod",
  "pack_pin": "ctxpack.finops@3.1.0",
  "snapshot_pin": "kg_2026_05_03_T0930",
  "intent": "finance.invoice.credit_adjust",
  "started_at": "2026-05-04T10:14:00Z",
  "heartbeat": { "interval_ms": 30000, "ttl_ms": 14400000, "last_seen": "2026-05-04T10:25:00Z" },
  "status": "running",
  "checkpoints": [
    { "checkpoint_id": "ck_inv_22_after_s2", "after_step": "s2", "critic_verdict": "ok", "saved_at": "2026-05-04T10:14:42Z" },
    { "checkpoint_id": "ck_inv_22_after_s3", "after_step": "s3", "critic_verdict": "accept", "saved_at": "2026-05-04T10:25:11Z" }
  ],
  "next_step": "s4",
  "owner_actor": "agt_finops"
}

Lifecycle states

Earlier session examples used in_progress, awaiting_gate and paused as display labels. Map those explicitly to running, waiting_approval and suspended in the additive run contract. An approval denial is evidence driving a controller event such as fail; it is not a new RunStatus value. Gate expiry blocks that approval and follows the workflow’s explicit failure/escalation policy; it does not itself prove the run’s absolute deadline expired.

Spawn

• Triggered by invokeAgent with mode: "long_running" and runtime.max_session_duration_ms ≥ 1 hour.
• Conversation Manager validates the envelope, materializes the Run Context, persists the initial session row before any plane runs.
• Planner picks up the session and emits the first Plan against the pinned pack + snapshot.

Checkpoint

• A checkpoint is persisted after every Critic verdict (ok / accept / replan).
• Checkpoint payload includes: plan_id, accumulated tool_transcripts[] IDs, accumulated evidence_refs[], RunBudget accumulators (atomic snapshot), Critic step scores, the next-step pointer.
• Checkpoint storage is append-only and content-addressed; checkpoints are immutable.

ExecutionCheckpoint pins contract, pack, policies, tool/profile registries, releases, operation/budget ledgers, pending work and cancellation state. The controller must atomically enforce expected revision and executor generation. A serialized checkpoint or a lease alone does not enforce a fence at an external target.

Resume

• A resumable session is reconstituted by session_id against the recorded pins and verified bytes. Missing or mismatched pinned artifacts block; publishing a newer registry version does not silently change the saved interpretation. Required policy changes need explicit migration and reauthorization.
• Resume matches the checkpoint budget/operation snapshot against current owned store state; it cannot reset later consumed or reserved capacity. Available capacity is original ceiling minus current used and reserved, with the inherited deadline unchanged.
• Resume uses next_step plus the durable tool/effect evidence; it must not redispatch an already confirmed effect. A dispatch whose outcome was not recorded is uncertain, not proof that no effect occurred.
• Before a new protected read or write, revalidate current identity, revocation, delegation expiry, approval binding, and external preconditions under the pinned policy. A checkpoint does not restore expired authority.
• Reconcile uncertain effects through the adapter’s declared lookup and idempotency contract before considering a retry. If the outcome cannot be established, preserve the evidence and pause or escalate; do not claim completion or issue a fresh logical operation to bypass uncertainty.
• Operator interruptions preserve confirmed progress and unresolved operations. A cancellation acknowledgement stops future work as supported by the runtime; it does not certify that an in-flight external effect was prevented or reversed.

Heartbeat and TTL

• The controller’s configured heartbeat watchdog can request suspended after its declared missed-heartbeat threshold. It fences stale ownership before another worker resumes; heartbeat loss is not proof that an external effect failed or a process stopped.
• Session TTL (max_session_duration_ms) is hard; on expiry the runtime emits Session expired and persists a terminal checkpoint.
• Approval gates have their own stored validity interval; gate expiry blocks that approval. The controller records the workflow’s explicit fail/escalation transition separately from absolute run expiry.

Progress envelopes

Sessions emit periodic typed progress envelopes consumable by external orchestrators:

{
  "session_id": "sess_inv_22",
  "progress_id": "prog_inv_22_0014",
  "emitted_at": "2026-05-04T10:25:11Z",
  "current_step": "s4",
  "completed_step_count": 3,
  "total_step_count": 4,
  "budget_remaining": { "tokens": 7280, "tool_calls": 8, "cost_cents": 24.0, "wall_clock_ms": 12830 },
  "awaiting_gate": null
}

Failure modes specific to background sessions

• Missing/mismatched pinned pack or snapshot on resume — the controller refuses restore when the recorded bytes cannot be verified; the operator decides whether to migrate or terminate. Application diagnostics may distinguish pack and snapshot mismatch; publication of a newer version alone does not invalidate intact historical pins.
• Heartbeat loss without operator pause — watchdog requests suspension/fencing; resume needs current ownership and all policy-required approvals/preconditions. Operator consent alone cannot restore expired authority.
• Checkpoint write fails — stop further dispatch and record failure where possible. An external effect may already have committed; reconcile it before resuming. A failed checkpoint cannot roll back a provider transaction.
• Long-running session over budget — no further reservation or protected dispatch; reconcile in-flight usage and escalate. A separately authorized budget migration must retain consumed/reserved capacity and produce new pinned evidence; resume cannot simply reset or enlarge the original ledger.

Replay

Any past run can be re-executed against:

• the recorded CompiledContext,
• the recorded Plan,
• the recorded tool transcripts,
• the policy, evaluator, and model-profile versions active during the run,
• the pinned Knowledge Graph, memory, and registry snapshots,

to re-derive the Critic verdict and the DecisionRecord without paying live tool cost. This is the substrate for evaluation, regression testing, and post-incident investigation.

Verification and guardrails

• Tool allow-lists — only permitted tools and arguments may appear in a plan.
• Evidence checks — decisions require resolved evidence_refs before execution.
• Approval gates — steps are blocked until approved, with frozen evidence snapshot.
• Conflict detection — plans that violate policy invariants are rejected before execution.
• Loop guard — repeated identical tool calls or no-progress reflection cycles short-circuit with a structured reason.

Autotune surfaces

Decision-plane autotune is higher risk than Context-plane tuning because it changes how work is sequenced. It is still useful when bounded to explicit orchestration surfaces and scored by replay.

The optimizer cannot propose direct tool execution, approval bypasses, or untyped free-form plans. A candidate that changes the loop must emit a replayable Plan, step transcript expectations, and a DecisionRecord diff for review.

Execution model

• Idempotency depends on the provider’s exact key/payload scope, retention and request-mismatch contract; a key alone prevents nothing at the remote target.
• Retry budgets are bounded per step and per workflow.
• Timeouts after possible dispatch preserve unknown outcome and enter the declared reconciliation/escalation path; no blind retry or weaker-boundary fallback follows from failure.
• Compensation steps are new governed operations when supported; they preserve the original confirmed/partial effect and are not a transactional rollback guarantee.
• Parallel steps within a plan use the Executor’s lane abstraction.

Error handling and recovery

• Step failure isolates the failing step and returns control to the Planner under the re-plan budget.
• Partial execution retains confirmed progress and unresolved effects; resume follows reconciliation and the adapter’s declared retry guarantees.
• Human handoff routes to approval or operator with the full Plan, transcript, and verdict so far.

Implementation mapping

Orchestration maps primarily to:

• Orchestrator (planning, verification, execution control, subagent lanes)
• Decision Catalog (typed decision validation)
• Policy Engine (approval gates and constraints)

Implementation references

• API Contracts
• Workflow Examples
• High-Risk Workflow
• Decision Catalog

Interfaces

Inputs

• CompiledContext from the Cognitive Core
• Run Context (with budgets, principal chain, and v1 safety-mode ceiling)
• Decision Spec from the Decision Catalog
• Tool registry with capability classes, native risk, and v1 mode projections

Outputs

• Typed Plan and step transcripts
• DecisionRecord with evidence_refs, approvals, controls_active
• Memory write proposals
• Trace bundle

Failure modes

• Plan contains disallowed tools or missing approvals (caught by the Critic at verify).
• Tool retries cause duplicate side effects when deduplication scope, retention, or uncertain-outcome handling violates the adapter contract.
• Missing evidence for claims (rejected at the decision checkpoint).
• Subagent lane modifies parent effects (must remain isolated).
• Correlated agents converge on the same unsupported claim and majority voting is mistaken for verification.
• Passive evidence traffic overwhelms lane budgets or silently changes a plan without a recorded decision.
• Background session resumes against a different Context Pack version than it was suspended on.
• Loop guard trips silently without a structured reason.

Operational concerns

• Planner latency vs. template coverage tradeoff per intent.
• Re-plan budgets per workflow; default 2, raised only with rationale.
• Verification cost and strictness scale with native-risk dimensions and assurance requirements.
• Workflow timeouts and SLA enforcement at the Run Context boundary.
• Subagent lane fan-out limits to bound cost and latency.
• Passive-awareness queue limits, TTLs, deduplication, safe-point delivery, and classification-aware backpressure.
• Verifier failure-domain review across evidence, method, authority, and external state.
• Background session checkpoint storage and TTL by tenant.

Evaluation metrics

• Plan-verification pass rate.
• Step completion rate.
• Retry and recovery rate.
• Escalation rate by risk tier.
• Subagent lane success rate vs. parent re-plan rate.
• Mean time to safe completion.
• Wrong-unanimous rate, disagreement rate, and minority-rescue versus minority-erasure rate.
• Effective agent count after evidence-overlap/correlation adjustment, not raw lane count.
• Counterfactual influence of each lane and cost per externally certified outcome.

Example

A Critic verdict envelope condensed:

{
  "run_id": "run_a1b2c3d4e5f60718",
  "plan_id": "plan_refund_01",
  "verdict": "accept",
  "step_scores": [
    { "step_id": "s1", "scores": { "policy": 1.0, "utility": 1.0 } },
    { "step_id": "s2", "scores": { "policy": 1.0, "utility": 1.0 } },
    { "step_id": "s3", "scores": { "policy": 1.0, "utility": 0.95 }, "approval_gate": "GATE_FINANCE_APPROVAL", "approver": "user_finance_lead" }
  ],
  "loop_guard_trips": 0,
  "replan_attempts": 0
}

Common misconceptions

• Orchestration is not a workflow engine alone. It includes verification and scoring gates that traditional engines lack.
• Guardrails are not optional. They are part of the runtime loop, not a release-gate add-on.
• Subagent lanes are not free parallelism. They consume budget from the parent Run Context’s accumulators.
• Replay is not optional. It is the property that makes evaluation honest.