Snipara Orchestrator

Production-first agentic orchestrator with Snipara integration for context-aware validation.

Overview

Snipara Orchestrator implements the prod-first validation pattern for AI agents. It ensures that no task is marked "done" until it passes live production checks.

Key Features:

• Production-first validation - Tasks aren't done until live_check passes
• Proof-based verification - Standard proof contract (endpoint, user, result)
• Single gatekeeper - One authority for validation decisions
• Automatic cutover checklists - Generated and executed automatically
• Fail-fast on drift - Stops if route/schema drift detected
• Snipara integration - Context-aware with memory persistence
• Explicit htask coordination - Create, inspect, recommend, and complete hosted hierarchical tasks with evidence; it does not spawn Codex or Claude workers automatically
• Policy-controlled routing - Adaptive Work Routing returns an auditable policyDecision for dry_run, approval_required, and approved auto_low_risk handoffs without broadening project policy from CLI flags
• Engineering Lead Plan input - route --dry-run --lead-plan-file can derive routing requirements from Project Health or Companion Engineering Lead Contract V1 exports while keeping execution behind explicit approval and proof receipts
• Execution receipt gates - agents coordinate --lead-plan-file and agents check-receipt dry-run lead-plan coordination and verify claim, approval, proof, outcome, and Project Brain update evidence without spawning workers
• Gated local worker execution - agents execute-gated --plan turns an approved low-risk local handoff into an explicit dry-run or --execute local runtime call, then returns review-pending receipts without applying changes automatically
• Execution receipt ledger - agents execute-gated writes a stable gated execution receipt under .snipara/orchestrator/executions/ by default. V1 attributes the receipt to a worker/category, routing card, and stable workflow fingerprint, and fails closed when required receipt families are missing. agents review-gated persists its supervisor review under .snipara/orchestrator/reviews/ by default, and agents review-gated fails closed until receipts, scope, and source-backed proof are acceptable
• Source-backed proof review - agents verify-proof produces a separate proof review artifact from local source files, bounded scope, declared commands, and receipt fields, so agents review-gated no longer accepts self-attested proof
• Append-only execution ledger - agents ledger-append and agents ledger-verify keep a local chained JSONL ledger for receipt/proof review pairs and fail closed on tampering
• Brain-update review packs - agents brain-update-pack extracts proposed Brain-update candidates from gated execution receipts as review-pending packs with memoryWriteAllowed=false, so workers never write durable memory automatically
• Explicit Brain-update approval plans - agents brain-update-approve and agents brain-update-apply convert source-backed candidates into dry-run apply plans without writing durable memory automatically
• Companion-aware status - status --json reads local .snipara/companion/config.json project bindings and reports configuration state without exposing API keys
• Companion Session Snapshot V0 - companion-session --json reads .snipara/activity/session.json, and Team Sync gates include that snapshot while keeping hard_routing_allowed=false unless explicit policy and receipts permit routing
• Advisory Intent Detection V0 - companion-session displays the Companion snapshot intent, confidence, and suggested workflow mode as context only; it never turns intent into worker execution or hard routing by itself
• Host-native orchestration - host discover/run/status/steer/cancel supervises Codex App Server, Claude Code CLI, and loopback OpenAI-compatible inference through their native protocols, with explicit execution, bounded scope, redacted receipts, resume identifiers, and fail-closed cancellation
• Autonomous Project Controller - controller commands reconcile Companion Feature/Task state into capability-routed host dispatch, bounded recovery, proof gates, isolated worktrees, and review-required integration proposals. Dispatch needs both a stored autonomy policy, remaining controller-wide budget, and explicit --execute. Ready low-risk repo-only candidates may move only an allowlisted local branch ref through compare-and-swap; push, PR merge, publish, and production effects remain separate authority surfaces. Attempt worktrees are removed deterministically, process ownership survives restarts through PID/start-time/PGID verification, and state heartbeats do not wait behind Git worktree or patch operations. Tasks declare effectScope, which defaults to repo_only; deploy, database, external-message, and financial effects require an expiring externally issued contract with scope, cost, duration, invocation, and compensation ceilings. Operators can append landed/rejected/ abandoned/superseded/reverted observations to an idempotent proposal outcome ledger for later acceptance and earned-authority analysis, and outcome scan fills that ledger on its own by probing whether each proposal patch is already present in the target ref. Executing controllers also require policy-owned proof commands that tasks can extend but never replace; completed receipts must prove the exact effective command list. An optional immutable Feature contract first judges a complete, content-addressed IntegrationCandidate on the current target HEAD and later evaluates the integrated Git target independently of task completion, so neither a finished DAG nor a synthetic candidate is mistaken for an achieved objective. Plan changes are immutable successor revisions, earned authority is shadow-only, always-on executors use monotonic fencing leases, and normalized GitHub/CI outcomes require bounded HMAC-authenticated delivery receipts

Opt-in candidate review floor

Existing controllers remain compatible: requireIndependentReview defaults to false. An operator can enable the floor and pin a reviewer allowlist without replacing controller history:

snipara-orchestrator controller candidate review-policy \
  --controller-id my-feature --reviewer-id independent-review-worker
snipara-orchestrator controller candidate review-show --controller-id my-feature
snipara-orchestrator controller candidate review-record \
  --controller-id my-feature --receipt-file reviewed-candidate.json

Repeat --reviewer-id to declare additional identities. Once enabled, this command cannot disable the floor or replace the allowlist. These are trusted operator assertions, not authenticated reviewer identities: output reports authoritySource=operator_asserted and identityAuthenticated=false. An import does not attest that a human or host actually performed the review. Never describe synthetic receipts as human approvals.

The imported JSON uses schemaVersion: snipara.candidate_review.v1 and contains receiptId, controllerId, candidateId, candidateTreeSha, combinedPatchSha256, reviewerId, verdict (accepted or refused), reviewedAt, expiresAt, and nonempty evidenceRefs. Copy candidate hashes from candidate show; do not derive them from a different checkout. Review validity must be positive and at most 30 days. Future-dated or expired reviews fail closed.

The last imported immutable receipt for the candidate governs the floor. It must bind the exact tree and combined patch hashes, use an allowlisted identity, and differ from every producer identity and attempt captured in the immutable candidate. Older candidates lacking producer attribution cannot pass this floor. The controller checks it before candidate evaluation, after proof execution before persisting readiness, and before landing; a missing, refused, stale or expired receipt also blocks reuse of an existing ready evaluation. This floor does not grant execution, integration, push, release, or production authority.

Installation

pip install snipara-orchestrator

Or with all optional dependencies:

pip install snipara-orchestrator[all]

Quick Start

CLI Usage

# Initialize configuration
snipara-orchestrator init --project my-project --prod-url https://api.example.com

# Show secret-safe status, including Companion workspace config when present
snipara-orchestrator status --json

# Discover native hosts without executing work
snipara-orchestrator host discover --adapter all

# Turn an objective into a Feature, plan, tasks, and durable controller state
snipara-orchestrator controller bootstrap \
  --goal "Implement OAuth" \
  --slug oauth \
  --acceptance "Users can authorize through the supported provider" \
  --acceptance-proof "pytest tests/test_oauth.py" \
  --autonomy observe

# Executing autonomy requires an operator-owned, non-overridable proof floor
snipara-orchestrator controller init \
  --plan docs/specs/oauth/workflow-plan.json \
  --controller-id oauth \
  --autonomy execute_low_risk \
  --required-proof "pytest tests" \
  --required-proof "ruff check src tests" \
  --budget-json '{"maxCostMicros":5000000,"maxInputTokens":100000,"maxOutputTokens":20000,"maxDurationMs":900000,"maxTaskStarts":8,"maxAttempts":12,"maxReplans":2,"reserveCostMicrosPerAttempt":500000,"reserveInputTokensPerAttempt":10000,"reserveOutputTokensPerAttempt":2000}'

# Migrate a controller created before the policy proof floor existed.
# This preserves tasks, proposals, and append-only integration outcomes.
snipara-orchestrator controller policy set \
  --controller-id oauth \
  --required-proof "pytest tests" \
  --required-proof "ruff check src tests"

# Preview assignments, then explicitly run within the stored autonomy ceiling
snipara-orchestrator controller reconcile --controller-id oauth
snipara-orchestrator controller run --controller-id oauth --execute

# After the human integration action, record and inspect its durable outcome
snipara-orchestrator controller proposal outcome record \
  --controller-id oauth \
  --proposal-id proposal-oauth-api-a1-abc123 \
  --status landed \
  --target-ref refs/heads/dev \
  --landed-sha "$LANDED_COMMIT_SHA" \
  --pull-request 42
snipara-orchestrator controller proposal outcome show \
  --controller-id oauth \
  --proposal-id proposal-oauth-api-a1-abc123

# Or let the controller observe landings and reverts by itself
snipara-orchestrator controller proposal outcome scan \
  --controller-id oauth \
  --target-ref refs/heads/dev \
  --record

# Evaluate the Feature objective only after every completed task proposal landed
snipara-orchestrator controller acceptance evaluate \
  --controller-id oauth \
  --target-ref refs/heads/dev
snipara-orchestrator controller acceptance show --controller-id oauth

# Add the immutable contract in place for a legacy controller; history is preserved
snipara-orchestrator controller acceptance set \
  --controller-id legacy-oauth \
  --criterion "Users can authorize through the supported provider" \
  --evaluator "pytest tests/test_oauth.py"

# Compose every completed proposal on the real dev HEAD without moving that ref
snipara-orchestrator controller candidate compose \
  --controller-id oauth \
  --target-ref refs/heads/dev

# Run the policy proof floor and Feature contract on that exact composed tree
snipara-orchestrator controller candidate evaluate --controller-id oauth
snipara-orchestrator controller candidate show --controller-id oauth

# For an explicitly allowlisted, low-risk, repo-only target, land with CAS,
# observe proofs, and let policy create an owned revert commit on regression.
snipara-orchestrator controller candidate land --controller-id oauth --execute
snipara-orchestrator controller candidate observe --controller-id oauth --execute

# Inspect non-enforcing earned-authority history. It never grants permission.
snipara-orchestrator controller authority evaluate --controller-id oauth
snipara-orchestrator controller authority show --controller-id oauth

# Inspect the always-on executor fence and sanitized authenticated event receipts.
snipara-orchestrator controller executor show --controller-id oauth
snipara-orchestrator controller event show --controller-id oauth

# Plan a bounded Codex App Server run; add --execute only after review
snipara-orchestrator host run \
  --adapter codex_app_server \
  --task "Update one bounded documentation file" \
  --workspace . \
  --write-scope docs/README.md \
  --acceptance "documentation matches shipped behavior" \
  --proof "git diff --check"

# Read the local Companion Activity Timeline / Session Snapshot dogfood surface
snipara-companion workflow session --json
snipara-orchestrator companion-session --json

# Run a validation task
snipara-orchestrator run "Deploy Auth Feature" \
  --test "pnpm test" \
  --test "pnpm lint" \
  --endpoint "https://api.example.com/health" \
  --endpoint "https://api.example.com/api/auth/session" \
  --minimum-proof-count 3

# Check for environment drift
snipara-orchestrator check-drift --route /api/users --route /api/auth

# Validate a single endpoint
snipara-orchestrator validate https://api.example.com/health

# Recall memories from previous sessions
snipara-orchestrator recall "deployment failures" --limit 5

# Store a memory
snipara-orchestrator remember "Chose Redis for rate limiting" --type decision

# Bootstrap an autonomous htask tree for workers
snipara-orchestrator htask-bootstrap "Auth Overhaul" \
  --swarm-name default-agent-orchestrator \
  --description "Move auth to OAuth and JWT" \
  --owner coordinator \
  --workstream API \
  --workstream QA \
  --custom-workstream DEPLOY_PROD_VERIFY

# Create an htask feature and workstreams
snipara-orchestrator htask-create-feature "Auth Overhaul" \
  --swarm-id swarm_abc123 \
  --description "Move auth to OAuth and JWT" \
  --owner codex \
  --workstream API \
  --workstream QA

# Create a leaf htask under a workstream
snipara-orchestrator htask-create "Add refresh endpoint" \
  --swarm-id swarm_abc123 \
  --parent-id htask_ws_api \
  --description "Implement token rotation" \
  --owner codex \
  --evidence-required '{"type":"test","description":"targeted tests passed"}'

# Pull or claim the next ready htasks and inspect the hierarchy
snipara-orchestrator htask-next \
  --swarm-name default-agent-orchestrator \
  --claim-for-agent hermes-worker-1 \
  --limit 1
snipara-orchestrator htask-tree --swarm-id swarm_abc123 --task-id htask_feature

# Complete an N3 htask with proof
snipara-orchestrator htask-complete htask_task_001 \
  --swarm-id swarm_abc123 \
  --evidence "test:pytest packages/agentic-orchestrator" \
  --result "Implemented and verified htask wrapper"

# Dry-run Adaptive Work Routing against a runtime catalog
snipara-orchestrator route --dry-run \
  --work-profile-json '{"taskType":"documentation","risk":"low"}' \
  --requirements-json '{"workerRole":"coding","plannerRetainsReasoning":true,"preferredEndpointTypes":["local"]}' \
  --catalog-file runtime-catalog.json

# Build a local LM Studio/Qwen docs and architecture runtime catalog
snipara-orchestrator local-model-catalog \
  --base-url http://127.0.0.1:1234 \
  --model qwen/qwen3-30b-a3b-2507 \
  --worker-role documentation \
  --capability documentation \
  --capability architecture_review \
  --capability planning \
  --json > .snipara/local-qwen-docs-runtime-catalog.json

# Dry-run against that local OpenAI-compatible endpoint
snipara-orchestrator route --dry-run \
  --work-profile-json '{"taskType":"documentation","risk":"low","scope":["docs/**"],"contextBudget":"small","reasoningDepth":"low"}' \
  --requirements-json '{"workerRole":"documentation","plannerRetainsReasoning":true,"preferredEndpointTypes":["local"],"allowedEndpointTypes":["local"],"writeScope":["docs/**"],"capabilities":["documentation"]}' \
  --catalog-file .snipara/local-qwen-docs-runtime-catalog.json \
  --json

# Dry-run routing from an Engineering Lead Plan V1 export
snipara-orchestrator route --dry-run \
  --lead-plan-file project-health-lead-plan.json \
  --work-package-id wp_docs \
  --catalog-file runtime-catalog.json

# Dry-run coordination and evidence gates from an Engineering Lead receipt
snipara-orchestrator agents coordinate \
  --lead-plan-file project-health-lead-plan.json \
  --work-package-id wp_docs \
  --json

snipara-orchestrator agents check-receipt \
  --receipt-file lead-execution-receipt.json \
  --evidence "proof:pytest docs passed" \
  --claim-id claim_docs \
  --approval-receipt-id approval_docs \
  --outcome-receipt-id outcome_docs \
  --brain-update-applied \
  --json

# Inspect a gated local worker launch contract without contacting the runtime
snipara-orchestrator agents execute-gated \
  --plan .snipara/orchestrator/handoff.json \
  --json

# Explicitly contact the selected local OpenAI-compatible runtime.
# Output is review_pending; Snipara does not auto-apply worker changes.
snipara-orchestrator agents execute-gated \
  --plan .snipara/orchestrator/handoff.json \
  --execute \
  --json

# Verify claimed proof against local source artifacts before review-gated
snipara-orchestrator agents verify-proof \
  --receipt-file .snipara/orchestrator/executions/gated-exec-abc123.json \
  --repo-root . \
  --output .snipara/orchestrator/proof/proof-review-abc123.json \
  --json

# Append and verify the receipt/proof pair in the local execution ledger
snipara-orchestrator agents ledger-append \
  --receipt-file .snipara/orchestrator/executions/gated-exec-abc123.json \
  --proof-review-file .snipara/orchestrator/proof/proof-review-abc123.json \
  --ledger-file .snipara/orchestrator/ledger/execution-ledger.jsonl \
  --json
snipara-orchestrator agents ledger-verify \
  --ledger-file .snipara/orchestrator/ledger/execution-ledger.jsonl \
  --json

# Review the persisted gated execution receipt before any follow-on action
snipara-orchestrator agents review-gated \
  --receipt-file .snipara/orchestrator/executions/gated-exec-abc123.json \
  --proof-review-file .snipara/orchestrator/proof/proof-review-abc123.json \
  --ledger-file .snipara/orchestrator/ledger/execution-ledger.jsonl \
  --json

# The accepted or blocked supervisor review is persisted under
# .snipara/orchestrator/reviews/ unless --no-review is passed.

# Extract proposed Brain updates for supervising-agent review.
# This does not write durable memory.
snipara-orchestrator agents brain-update-pack \
  --receipt-file .snipara/orchestrator/executions/gated-exec-abc123.json \
  --proof-review-file .snipara/orchestrator/proof/proof-review-abc123.json \
  --output .snipara/orchestrator/brain-updates/brain-pack-abc123.json \
  --json

# Approve source-backed candidates and emit a dry-run apply plan.
# This still does not write durable memory.
snipara-orchestrator agents brain-update-approve \
  --pack-file .snipara/orchestrator/brain-updates/brain-pack-abc123.json \
  --candidate-id brain-candidate-abc123 \
  --reviewer lead-agent \
  --output .snipara/orchestrator/brain-updates/approved-pack-abc123.json \
  --json
snipara-orchestrator agents brain-update-apply \
  --pack-file .snipara/orchestrator/brain-updates/approved-pack-abc123.json \
  --output .snipara/orchestrator/brain-updates/apply-plan-abc123.json \
  --json

Python API

import asyncio
from snipara_orchestrator import Orchestrator, Task, ValidationCriteria
from snipara_orchestrator.models import LiveCheck, OrchestratorConfig

async def main():
    # Configuration
    config = OrchestratorConfig(
        snipara_api_key="snp-your-api-key",
        snipara_project="my-project",
        prod_url="https://api.example.com",
        repo_path="/path/to/repo",
        test_user="test@example.com",
    )

    # Create orchestrator
    orchestrator = Orchestrator(config)
    await orchestrator.initialize()

    # Define task with validation criteria
    task = Task(
        id="deploy-auth",
        title="Deploy Authentication Feature",
        description="Deploy OAuth2 authentication to production",
        criteria=ValidationCriteria(
            local_tests=["pnpm test", "pnpm lint"],
            live_checks=[
                LiveCheck(url="https://api.example.com/health"),
                LiveCheck(
                    url="https://api.example.com/api/auth/login",
                    method="POST",
                    expected_status=200,
                    body={"email": "test@test.com", "password": "test"},
                ),
            ],
            required_proofs=3,
        ),
    )

    # Execute the task
    result = await orchestrator.execute_task(task)

    print(f"Status: {result.status.value}")
    print(f"Proofs: {len(result.passing_proofs())}/{len(result.proofs)}")

asyncio.run(main())

Task Lifecycle

PENDING → IN_PROGRESS → LOCAL_OK → VALIDATING → PROD_OK → DONE
                             ↓           ↓
                         LOCAL_FAIL   PROD_FAIL → ENV_DRIFT?

Proof Contract

Every validation produces a proof with three required fields:

@dataclass
class Proof:
    endpoint: str      # URL or test identifier
    user_tested: str   # Test user email
    result: str        # "pass" or "fail"

    # Optional
    response_code: int
    response_body: dict
    error_message: str

Tasks require a minimum number of passing proofs (default: 3) to reach PROD_OK.

Adaptive Work Routing

snipara-orchestrator route --dry-run resolves provider-neutral work requirements against a runtime worker catalog. It returns a fail-closed policyDecision with one of three modes: dry_run, approval_required, or auto_low_risk when explicit policy, risk, and candidate gates allow execution. Routing itself does not spawn Codex, Claude, CI workers, local LLMs, or any other execution worker. The separate host command family can explicitly dispatch a reviewed work package through a native adapter.

The resolver deliberately avoids hardcoded model-name lists. Stable inputs are:

• WorkProfile: task type, risk, scope, and context budget
• ModelRequirements: worker role, reasoning, cost, speed, endpoint type, capabilities, write scope, and fallback
• runtime candidates returned by Snipara's BYOM gateway or another trusted runtime catalog

Use this pattern when a strong planner retains deep reasoning but a scoped worker can perform the edit, test, or documentation task. Local endpoints such as Ollama, LM Studio, AnythingLLM, or other OpenAI-compatible servers must be reachable from the worker runtime. If no candidate satisfies the requirements, the resolver fails closed to main_agent.

In the Codex workflow, Codex remains the chief architect, lead orchestrator, and quality verifier. Local LM Studio models are bounded worker candidates: Codex plans the work, issues the handoff, reviews the output, and owns the final quality gate.

For an explicit local handoff, host run --strong-repair adds one strong-host repair pass after a failed output or proof gate. The repair adapter receives a redacted failure receipt, preserves the original write scope and approval envelope, reruns the same proof, and can only finish as completed after every gate passes. Scope violations, unavailable hosts, skipped proof, or a failed repair escalate to the main agent; there is no automatic retry loop.

For LM Studio or another OpenAI-compatible local server, generate a runtime catalog first. If multiple coding models are loaded, prefer the one you want by matching the model id returned by /v1/models:

snipara-orchestrator local-model-catalog \
  --base-url http://127.0.0.1:1234 \
  --prefer-model devstral \
  --worker-role coding \
  --capability code_edit \
  --capability refactor \
  --json > .snipara/local-devstral-runtime-catalog.json

Use an exact model id when you want to pin Qwen for documentation, architecture, or planning work:

snipara-orchestrator local-model-catalog \
  --base-url http://127.0.0.1:1234 \
  --model qwen/qwen3-30b-a3b-2507 \
  --worker-role documentation \
  --capability documentation \
  --capability architecture_review \
  --capability planning \
  --json > .snipara/local-qwen-docs-runtime-catalog.json

The catalog records the base URL, model id, and standard OpenAI-compatible routes: /v1/models, /v1/responses, /v1/chat/completions, /v1/completions, and /v1/embeddings. For one-off routing experiments, append the local endpoint directly:

snipara-orchestrator route --dry-run \
  --openai-compatible-local-url http://127.0.0.1:1234 \
  --openai-compatible-model qwen/qwen3-30b-a3b-2507 \
  --work-profile-json '{"taskType":"documentation","risk":"low","scope":["docs/**"]}' \
  --requirements-json '{"workerRole":"documentation","plannerRetainsReasoning":true,"preferredEndpointTypes":["local"],"allowedEndpointTypes":["local"],"writeScope":["docs/**"],"capabilities":[]}' \
  --json

This still resolves and proves the handoff contract only. Use host run to dispatch explicitly after the required review boundary exists.

Host-Native Orchestration

The host runtime normalizes lifecycle state without replacing the underlying agent host:

• Codex uses the stable App Server JSON-RPC protocol over local stdio, including thread start/resume, turn start, in-flight steer when supported, and native interrupt.
• Claude Code uses structured print mode and its native session resume id. In-flight steering remains unavailable on this CLI path; use the Agent SDK when a long-lived embedded Claude lifecycle is required.
• LM Studio and other OpenAI-compatible runtimes are inference-only workers. Loopback URLs are the default; credential-bearing URLs, embedding/reranker models, and remote endpoints without an explicit opt-in are rejected.
• Managed Agents discovery is feature-flagged and reports unavailable instead of pretending to execute an unvalidated beta contract.

Every real run requires --execute and at least one --proof, stores a private receipt under .snipara/orchestrator/host-runs/, captures provider usage when the host exposes it, and compares actual Git changes with the declared write scope. Scope violations fail the run even when the host reports success. Use repeatable --output-fragment values when a response must retain exact lines (for example both sides of a unified diff); missing fragments fail the run and are persisted in evidence.outputValidation.

Declared proof commands run automatically after dispatch with shell=False, an executable allowlist, bounded output, and a per-command timeout. Use --no-run-proof only to hand the receipt to a reviewer; that run is recorded as verification_required, not completed. For unattended execution, add --require-approval --approval-receipt-id <id> --approval-receipt-file <json>. The local supervisor requires the full adaptive-routing-approval-v1 JSON and rechecks its endpoint, write scope, decision, and expiry before contacting the host; an id by itself is never treated as approval.

snipara-orchestrator host discover --adapter all

snipara-orchestrator host run \
  --adapter openai_compatible \
  --base-url http://127.0.0.1:1234 \
  --model qwen/qwen3-coder-next \
  --task "Return a bounded patch for parser.py" \
  --workspace . \
  --write-scope parser.py \
  --acceptance "targeted parser test passes" \
  --proof "pytest tests/test_parser.py" \
  --output-fragment "return old_value" \
  --output-fragment "return new_value" \
  --execute

Provider credentials are declared by environment-variable name, never by value:

snipara-orchestrator host run \
  --adapter openai_compatible \
  --base-url https://provider.example.com \
  --allow-remote \
  --api-key-env PROVIDER_API_KEY \
  --api-key-header authorization \
  --model provider/coder \
  --task "Run one bounded task" --workspace . \
  --write-scope docs/** --proof "git diff --check" --execute

For the Companion worker registry, use snipara-companion workers local add --base-url <url> --api-key-env PROVIDER_API_KEY (--api-key-header x-api-key is also supported). Native Codex and Claude profiles use their host-managed authentication; a generic CLI declaration is rejected unless its command maps to the supported Codex or Claude adapter.

The 2026-07-17 live smoke did not justify unreviewed automatic local delegation: strong-only verified 3/3 tasks, while Codex planning plus LM Studio verified 2/3 and was slower at the median. Host-native infrastructure now supports an explicit supervised local handoff with one strong repair attempt; automatic routing remains policy-gated while broader paired samples validate the routing-quality gate.

The comparative ten-repetition study (30 samples per condition) separates local model quality from orchestration handoff quality. LM Studio local-only matched Codex strong-only at 30/30 semantic completion and was 5,362.5 ms faster at the median (2,418 ms vs 7,780.5 ms). The raw Codex-plan-plus-LM-Studio path passed 28/30 and added 3,935 ms of median latency; a strong-host repair pass recovered both failures (30/30, with 2/30 supervisor recoveries). The planner stage alone had a 9,542 ms median, so the observed loss is a handoff problem rather than evidence that the local model is intrinsically incapable. Semantic validators and exact output-fragment contracts are reported separately, scope violations were zero, and these samples remain ineligible for Worker Trust promotion with frontier cost data still unavailable. In this setup, LM Studio runs on an existing Mac and the strong cloud host is subscription-covered, so neither path adds an incremental per-call charge; hardware, electricity, subscription allocation, and quota are outside the benchmark rather than counted as zero.

Policy decisions keep approval receipts explicit. approval_required requires a human or project-owned approval receipt before a worker launcher may continue; auto_low_risk can only be emitted for low-risk work when approval is not required and a measured accepted candidate satisfies the budget and capability constraints.

Configuring MCP Tool Surfaces

The MCP server advertises different tool surfaces depending on the SNIPARA_EXPOSED_SURFACES environment variable. Hosted MCP defaults to the lean agent contract and routes specialist work behind simple Snipara verbs. To expose orchestration tools directly in the advertised manifest, set SNIPARA_EXPOSED_SURFACES=inline,orchestrator on the MCP server. This is optional: orchestration tools remain discoverable via snipara_help, marked as opt-in specialist surfaces, and can be executed by direct JSON-RPC or clients/server configurations that expose those surfaces. Standard MCP agents only receive schemas for tools returned by tools/list.

Configuration

Create .snipara-orchestrator.json in your project root:

{
  "snipara_api_key": "snp-your-api-key",
  "snipara_project": "my-project",
  "prod_url": "https://api.example.com",
  "repo_path": "/path/to/repo",
  "test_user": "test@example.com",
  "fail_fast_on_drift": true,
  "auto_remember": true,
  "verbose": true
}

Or use environment variables:

export SNIPARA_API_KEY=snp-your-api-key
export SNIPARA_PROJECT=my-project
export PROD_URL=https://api.example.com
export REPO_PATH=/path/to/repo

Snipara Integration

The orchestrator uses Snipara for:

Context Retrieval

# Get relevant documentation
context = await orchestrator.snipara.query_context(
    query="deployment checklist production",
    max_tokens=6000,
)

Memory Persistence

# Remember decisions
await orchestrator.snipara.remember(
    content="Chose Redis for rate limiting due to distributed nature",
    type="decision",
    category="architecture",
    ttl_days=30,
)

# Recall previous context
memories = await orchestrator.snipara.recall(
    query="deployment failures",
    limit=5,
)

Multi-Agent Coordination

# Create a swarm
swarm = await orchestrator.snipara.create_swarm(
    name="deployment-coordination",
    description="Multi-agent deployment workflow",
)

# Store shared state
await orchestrator.snipara.set_state(
    swarm_id=swarm["swarm_id"],
    agent_id="coordinator",
    key="deployment_status",
    value={"phase": "validating", "progress": 75},
)

Hierarchical Tasks

These methods wrap the hosted snipara_htask_* tools. They coordinate work and proofs; worker execution is still manual and explicit.

feature = await orchestrator.snipara.create_htask_feature(
    title="Auth Overhaul",
    description="Move auth to OAuth and JWT",
    owner="codex",
    auto_create_swarm=True,
    swarm_name="default-agent-orchestrator",
    create_initiative=True,
    workstreams=["API", "QA"],
    custom_workstreams=["DEPLOY_PROD_VERIFY"],
    create_actionable_tasks=True,
)

task = await orchestrator.snipara.create_htask(
    swarm_id=swarm["swarm_id"],
    parent_id=feature["workstream_ids"]["API"],
    title="Add refresh endpoint",
    description="Implement token rotation",
    owner="codex",
    evidence_required=[
        {"type": "test", "description": "targeted tests passed"},
    ],
)

ready = await orchestrator.snipara.recommend_htask_batch(
    swarm_id=swarm["swarm_id"],
    limit=5,
    owner="codex",
    claim_for_agent="hermes-worker-1",
)

tree = await orchestrator.snipara.get_htask_tree(
    swarm_id=swarm["swarm_id"],
    task_id=feature["feature_id"],
)

await orchestrator.snipara.complete_htask(
    swarm_id=swarm["swarm_id"],
    task_id=task["task_id"],
    evidence=[
        {"type": "test", "description": "pytest package suite passed"},
    ],
    result={"files_modified": ["src/auth.py"]},
)

Components

Gatekeeper

Single authority for validation decisions:

from snipara_orchestrator.gates import Gatekeeper

gatekeeper = Gatekeeper(
    snipara=snipara_client,
    validator=validator,
    drift_detector=drift_detector,
    fail_fast_on_drift=True,
)

# Gate 1: LOCAL_OK → VALIDATING
result = await gatekeeper.gate_local_to_validation(task)

# Gate 2: VALIDATING → PROD_OK
result = await gatekeeper.gate_validation_to_prod(task)

Drift Detector

Detect environment drift:

from snipara_orchestrator.drift_detector import DriftDetector

detector = DriftDetector(
    prod_url="https://api.example.com",
    repo_path="/path/to/repo",
)

report = await detector.full_drift_check(
    routes=["/api/users", "/api/auth"],
    check_schema=True,
    check_health=True,
)

if report.has_drift:
    print(f"Issues: {report.issues}")
    print(f"Recommendations: {report.recommendations}")

Validator

Collect proofs from live checks:

from snipara_orchestrator.validator import Validator
from snipara_orchestrator.models import LiveCheck

validator = Validator(test_user="test@example.com")

proof = await validator.run_live_check(
    LiveCheck(
        url="https://api.example.com/health",
        expected_status=200,
    )
)

print(f"Result: {proof.result}")
print(f"Status: {proof.response_code}")

Executor

Run commands and tests:

from snipara_orchestrator.executor import Executor

executor = Executor(working_dir="/path/to/repo")

result = await executor.run_command("pnpm test")
print(f"Success: {result.success}")
print(f"Output: {result.stdout}")

Architecture

┌─────────────────────────────────────────────────────────────────┐
│                        ORCHESTRATOR                             │
│                                                                 │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  SNIPARA (Context Layer)                                 │  │
│  │  • snipara_context_query → Documentation context             │  │
│  │  • snipara_remember/recall → Memory persistence              │  │
│  │  • snipara_swarm_* → Multi-agent coordination                │  │
│  └──────────────────────────────────────────────────────────┘  │
│                              │                                  │
│                              ▼                                  │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │  GATEKEEPER (Single Authority)                           │  │
│  │  • gate_local_to_validation() → LOCAL_OK → VALIDATING    │  │
│  │  • gate_validation_to_prod() → VALIDATING → PROD_OK      │  │
│  │  • generate_cutover_checklist() → Auto checklist         │  │
│  └──────────────────────────────────────────────────────────┘  │
│                              │                                  │
│        ┌─────────────────────┼─────────────────────┐           │
│        ▼                     ▼                     ▼           │
│  ┌───────────┐        ┌───────────┐        ┌───────────┐       │
│  │ EXECUTOR  │        │ VALIDATOR │        │ DRIFT     │       │
│  │ • Tests   │        │ • Live    │        │ DETECTOR  │       │
│  │ • Deploy  │        │ • UI      │        │ • Routes  │       │
│  │ • Bash    │        │ • Proofs  │        │ • Schema  │       │
│  └───────────┘        └───────────┘        └───────────┘       │
└─────────────────────────────────────────────────────────────────┘

Snipara Ecosystem

Best Practices

1. Always define validation criteria - Don't rely on defaults
2. Use meaningful test users - Helps with debugging
3. Set appropriate proof requirements - 3 is a good minimum
4. Enable fail-fast on drift - Catch issues early
5. Use auto-remember - Preserve learnings across sessions
6. Check drift before deployment - Run snipara-orchestrator check-drift

Documentation

• Full Documentation
• API Reference
• Examples

License

MIT

Built with ❤️ by Snipara

Native Qwen coder through Codex

Version 1.9.0 exposes a loopback Responses model through the native Codex tool host. Native Qwen coding remains experimental and unqualified for code quality and bounded repair. The release provides opt-in governed execution with Codex as producer and Qwen as an optional inference-only adviser. Exposed installed-journey, repair and host-boundary checks cover the documented capabilities; general A/B reliability and an advantage from Qwen advice remain unestablished.

Example of the opt-in experimental route:

snipara-orchestrator host run --adapter codex_app_server \
  --codex-executable /absolute/path/to/codex \
  --codex-local-provider --base-url http://127.0.0.1:1234/v1 \
  --model loaded-qwen-instance --model-context-window 65536 \
  --disable-host-integrations --codex-work-package-only --forbid-python-bytecode \
  --sandbox workspace-write --approval-policy never \
  --max-tool-calls 40 --max-repeated-tool-calls 6 \
  --workspace /disposable/repo --write-scope records.py \
  --task 'Repair ownership checks. Include applicable repository rules here.' \
  --proof 'python3 /external/validator.py' --timeout-seconds 180 --execute

The selected model must already be loaded with the specified context. Flags apply only to this process; they do not install models or mutate global configuration. Explicit cloud and local models require confirmation from the native thread before turn dispatch; local routing also confirms the selected provider. Receipts record actual native providerModel and modelProvider observations, without claiming provider authentication. Resume repeats model, provider and native permission settings.

--disable-host-integrations disables configured MCP servers and hooks; built-in apps may remain. --codex-work-package-only sets the project-document budget to zero; global inherited instructions may still appear. Callers must package applicable project instructions. For these isolated delegated workers only, the adapter supplies fixed developerInstructions on both AppServer thread start and resume: the parent handles hosted project context, and the worker follows the work package and the exposed terminal schema. When a local provider, --disable-host-integrations, --codex-work-package-only and sealed denyWorkspaceStateRead=true are all selected, the process instead uses a private, persistent CODEX_HOME outside the worktree under ~/.snipara/codex-local-worker-homes, with additional native denials for the entire private worker-home namespace and that exact home. The home is bound to the canonical workspace by a private runtime marker; unmarked preexisting homes are refused. No AGENTS, configuration or authentication files from the global Codex home are inherited; provider, model, permissions and approval settings are supplied explicitly. Codex may install its built-in skills, and other user or administratively managed skill roots remain applicable. No configuration or secrets are copied or linked. Start and resume use the same home; private rollouts survive Controller worktree cleanup and are referenced as local diagnostics, without uploading their contents. Codex may persist only the exact trusted-workspace entry in a bounded private TOML file for resume; additional configuration is refused. Unexpected instruction/auth files, links or unsafe ownership/modes cause refusal before dispatch. Other local combinations, cloud routes, baseInstructions, global files and the default contextual mode remain unchanged. --forbid-python-bytecode sets the native Python environment and instructs the worker to use python -B, including with -I or -E (which ignore PYTHON* variables). On macOS, the flag also denies reads and writes for standard cache directories and bytecode extensions through the scoped native filesystem profile described below; unsupported platforms refuse the opt-in flag. Scope checks continue to reject observed out-of-scope artifacts. Native guidance also requires available tools and valid terminal arguments, and prohibits fabricating Controller state or review/proof receipts. The guidance itself does not change permissions, declared proofs, scopes or tool budgets and does not guarantee model compliance; the bytecode flag adds only the filesystem restrictions described above. Tool caps opt into experimental raw AppServer events and count model-emitted tool attempts, including rejected arguments, by turn-bound call ID. Admitted execution notifications do not count a second time. Bounded runs disable features.code_mode_host for that process so tool attempts use direct tools: code-mode execution parents do not expose a verifiable identity link to their nested command executions. Uncapped runs retain their existing configuration. Structured bounded cloud runs require an explicit model. A zero-inference config/read bootstrap resolves the effective configured model catalog, or the current Codex home cache when none is configured. The adapter creates a private per-run catalog preserving the selected model metadata except for omitting tool_mode=code_mode_only, then supplies process-local catalog and tool-mode overrides. Unknown models, unsupported modes or unsafe catalog paths fail before inference. Global catalogs, configuration and authentication remain unchanged; temporary catalog bytes are removed after the native process and only content hashes appear in receipts. Uncapped, local-provider and custom-command routes retain their catalog behavior. A missing raw counterpart, conflicting call identity, unsupported attempted-call schema, or observation storage exceeding 1,000 IDs or a 64 KiB signature fails closed. Reaching a cap overrides a concurrent completed turn. This is interruption after emission, not a pre-execution permission boundary; the native sandbox remains that boundary. Bounded resume is refused until raw-event subscription on resumed threads is verified; uncapped resume retains its existing behavior. The inference-only openai_compatible adapter is a separate route.

Explicit native read policy and host-owned proofs

The Codex route accepts repeatable --deny-read-path /canonical/absolute/path and --host-owned-proof. Paths must already exist, be canonical without symlink aliases, contain no control characters or glob metacharacters, and fit the bounds of 64 paths and 4096 characters per path. Registered runtime profiles carry the same caller-owned policy as metadata.denyReadPaths (list of strings) and metadata.proofExecutionOwner: "host"; transport metadata may also declare it, but conflicting declarations are rejected. Task text and model output do not grant or alter this policy. Without these options, existing behavior remains unchanged.

Read denial selects a process-local named native permission profile extending the requested workspace-write or read-only base, with network disabled and explicit filesystem read denials. Start, resume and turn dispatch retain that profile; a missing or mismatched active profile fails before turn execution. The policy requires the supported Codex native permission interface: incompatible adapters fail closed instead of silently ignoring it. This scope is the native filesystem and shell boundary; it is not a general guarantee about every built-in app, external integration, alternate client or already-exposed source. Real denied-read probes are required before qualifying a corpus boundary.

--deny-workspace-state-read seals metadata.denyWorkspaceStateRead: true into the registered profile. The Codex adapter safely creates or verifies its own canonical .snipara directory and adds that directory to the effective native denial profile without rewriting denyReadPaths in the work package. This keeps the base policy stable across repair workspaces; the actual derived path appears in the command preview. Existing symlinks or non-directory collisions fail closed, and the combined effective paths remain limited to 64. An absent or false flag creates no implicit denial or directory. The intent is Codex-only and does not grant execution, change proofs, or relax a repair profile seal.

--host-owned-proof requires a declared proof and host proof execution, and cannot be combined with --no-run-proof. It instructs the worker to leave proof execution to the host after the native turn. Exact external commands remain in the work package and receipt; this option does not hide them, change their bytes, substitute an evaluator or manufacture proof evidence. The host runs the original commands outside the worker's read-denial profile and records their actual results. A reviewer can carry its own explicit denied paths and read-only base.

Six exposed development cases have functional and scope evidence across an initial five-pass run plus a preserved dev05 bytecode failure and fresh successful retry. Same-session read-only resume denied a real write; cancellation remained interrupted. These checks do not establish heldout acceptance or publication of 1.9.0. Existing installed or public packages may still expose an older surface; verify delivery versions before use.

For a Companion bridge, initialize with its reviewed policy rather than relying on compatible defaults:

snipara-orchestrator controller init --plan /workspace/exports/bridge-id/workflow-plan.json \
  --workspace /workspace --controller-id my-feature \
  --required-proof 'git diff --check' --require-independent-review \
  --independent-reviewer-id independent-review-worker

Repeat proof and reviewer flags to match the exported policy exactly. Initialization reconstructs tasks from the bound Lead Plan and policy, rejecting modified scopes, proofs, dependencies or runtime bindings even when workflow bytes are rehashed. It preserves observe-only authority. Review identities remain explicit operator assertions.

Opt-in bounded proof and review repairs

controller init --bounded-proof-repairs enables verified feedback for at most three producer admissions per repair ancestry (initial attempt plus two repairs). Every admitted worker must specify metadata.model; implicit model defaults are rejected. The existing default remains disabled. Failed proofs can retry only from the exact Controller-owned native receipt, unchanged scope and proof floor, and unchanged runtime profile. Scope and receipt mismatches escalate.

A refused completed candidate requires an explicit immutable successor plan via controller plan propose --repair-of-task-id <task> --review-receipt-id <receipt> --review-host-receipt-file <file> and activation. Its feedback is bound to the actual independent review source and sealed producer receipt; legacy unsealed proposals cannot enter this path. Dependencies retain the original proposal so the repair composes against its candidate. Feedback grants no approval or land authority. A new exact candidate must pass independent review, READY evaluation and compare-and-swap integration. These controls do not establish model quality.

Repair prompts carry the verified refusal's structured findings and receipt identities. Earlier verified findings from the exact proposal ancestry are included as regression checks, with the latest refusal taking priority. Review commentary is excluded; redaction and explicit omission counts retain the 4,000-character combined prompt limit, including any subsequent proof feedback. Workers must check the original contract and prior fixes within their unchanged scope. This context does not guarantee that a repair will succeed.

Explicit autonomy transition after a Companion bridge

A Companion bridge initializes the Controller with observe authority. Changing that authority is a separate operator action; importing a plan never grants it. Configure the existing proof floor and Controller budget first, then run:

snipara-orchestrator controller policy autonomy \
  --workspace /absolute/project --controller-id my-controller \
  --autonomy execute_low_risk --execute

Accepted ceilings are observe, coordinate, execute_low_risk, and execute_approved. The command refuses missing --execute, active dispatches, and executing ceilings without a policy proof and budget. It preserves the proofs, scope, budget ledger, task history, review policy, and approval receipts. It starts no workers and does not resume a stopped Controller. Only tasks blocked solely by the prior autonomy ceiling become ready when the new ceiling and their existing approvals allow execution. Non-low-risk and sensitive work still need the existing external approval gates; external effects retain their separate contracts. The recorded operator assertion is not authenticated reviewer identity.

Use controller reconcile --execute separately to request actual execution. Candidate review, evaluation, local land, and Feature acceptance remain separate commands and retain their existing exact-candidate gates.

When --forbid-python-bytecode is enabled, the Codex native route additionally uses a scoped filesystem profile denying __pycache__ directories and recursive contents, *.pyc, and *.pyo, including paths that do not yet exist. These absolute recursive rules deny reads as well as writes across all filesystem roots, including allowed temporary roots and symlink targets. Code depending on bytecode-only packages may therefore fail. The policy recognizes these standard cache paths and extensions; it does not detect bytecode stored under arbitrary names. This enforcement is currently qualified on macOS Seatbelt only; other platforms refuse the opt-in flag before starting the native process. The default flag-off route is unchanged. The profile preserves its read-only or workspace base and network denial. Syntax checks should use in-memory compile or ast.parse: -B does not prevent explicit py_compile or compileall writes. No cache deletion or scope exemption is granted.

Companion source context compatibility

Companion 3.7.1 exports optional hash-bound taskContextVersion: source-context-v1. Orchestrator 1.9.1 reconstructs the bounded task query from its reviewed sources, including expected result and contextual evidence references. References remain untrusted data, not permissions. Older bridge exports retain title-only queries. New rich-context exports require this compatible initializer; use matching package versions before executing them. See Companion's portable workflow guide for the local-checkpoint campaign and the distinction between completion, source-verified task proofs and independently evaluated Feature acceptance.