.env.example

# Example environment for ecaa-workflow.
# Copy to `.env` (gitignored) and fill in the values you need.
#
# Only the server loads `.env` automatically (via dotenvy in
# crates/server/src/main.rs). The harness and CLI read env vars
# from the live shell — `source .env` before invoking them, or rely
# on `make` targets that pass the vars through.
#
# =============================================================================
# Local production baseline (recommended active settings)
# =============================================================================
# A local production deployment should set only the following active values and
# leave everything else at its code default unless a specific operator need
# applies. The defaults below are durable, loopback-only, and avoid live test,
# eval, debug, remote-compute, and external-validator paths.
#
#   ECAA_ANTHROPIC_API_KEY=sk-ant-...  # optional for chat-side LLM; unset uses MockLlmBackend
#                                      # (legacy ANTHROPIC_API_KEY accepted with deprecation warning)
#   ECAA_EXECUTOR_MODE=local           # or `aws` / `slurm` (see below)
#   ECAA_HARNESS_CONCURRENCY=1         # or `auto` on a multi-core host
#   ECAA_SESSION_TOKEN_BUDGET=500000   # per-session uncached-input ceiling
#
# AWS or SLURM deployments additionally need the full required block from the
# matching section below. Dev/test knobs (`ECAA_LIVE_API`, `PLAYWRIGHT_LIVE`,
# `KEEP_PACKAGE`, `ECAA_DEBUG_TOKEN_BURN`, `ECAA_MOCK_DISCOVERY_BLOCK`) should
# NOT be set in production.

# =============================================================================
# LLM backend
# =============================================================================
# Required for the live Anthropic path (chat server, chat-llm CLI, nightly
# scorer, live Playwright specs). When unset the server falls back to
# MockLlmBackend and chat-llm / live tests SKIP.
#
# NOTE: This key is for the CHAT LLM only (the UX-shim conversation layer).
# The per-task Claude Code EXECUTOR agent defaults to SUBSCRIPTION billing
# at ~/.claude/.credentials.json (Max/Pro plan). The SWFC-prefixed name
# prevents accidental collisions with Claude Code CLI's ANTHROPIC_API_KEY
# scan. Legacy `ANTHROPIC_API_KEY` is still accepted (with a one-time
# stderr deprecation warning) to keep existing .env files working.
# See ECAA_AGENT_BILLING below.
# ECAA_ANTHROPIC_API_KEY=

# Override the Anthropic API base URL (proxy, staging). Default: https://api.anthropic.com
# ANTHROPIC_BASE_URL=https://api.anthropic.com

# Agent billing mode. Controls whether scripts/agent-claude.sh invokes
# `claude-code` against the subscription (default) or the API.
#   subscription — unset ECAA_ANTHROPIC_API_KEY for the agent; use
#                  ~/.claude/.credentials.json. Per-task cost: $0
#                  (subscription quotas apply). Default.
#   api          — forward ECAA_ANTHROPIC_API_KEY into the agent env; each
#                  task bills the API at token × rate. Use only for CI
#                  or hosts without a subscription.
ECAA_AGENT_BILLING=subscription

# Executor LLM backend. The harness invokes scripts/agent.sh (a dispatcher);
# this selects which wrapper it execs. The harness↔agent contract is
# file-based (the wrapper writes result.json/state.patch.json/.heartbeat), so
# the backend is invisible to the harness binary.
#   claude (default) → scripts/agent-claude.sh (Claude Code; production path)
#   codex            → scripts/agent-codex.sh  (Codex CLI, `codex exec --yolo`)
# Codex CLI delivery mirrors the Claude path: agent-codex.sh runs a host-side
# `npm install @openai/codex` into a cache dir and bind-mounts its node_modules
# into the container (the codex native binary is static musl → runs in bio-min;
# the image already has the node runtime). Codex auth: ECAA_OPENAI_API_KEY is
# the rotation-free headless path; absent that, a ChatGPT login at
# ECAA_CODEX_AUTH_DIR (default ~/.codex) is copied (writable, refreshable) into
# the per-task agent HOME. NOTE: a ChatGPT-login auth.json carries no usable
# OPENAI_API_KEY, so the key path needs a real platform API key.
# ECAA_AGENT_BACKEND=claude
# ECAA_AGENT_CODEX_EXPERIMENTAL=0            # 1 → opt in to the EXPERIMENTAL codex backend;
#                                            # agent-codex.sh refuses to run unless this is 1
#                                            # (no per-task images/GPU/cost-telemetry parity yet)
# ECAA_OPENAI_API_KEY=                       # platform API key (not the ChatGPT-login token)
# ECAA_CODEX_AUTH_DIR=~/.codex               # ChatGPT-login dir; default already ~/.codex
# ECAA_AGENT_CODEX_MODEL=gpt-5.5             # codex model; ECAA_AGENT_MODEL_OVERRIDE wins
# ECAA_AGENT_CODEX_VERSION=latest            # npm @openai/codex version to install
# ECAA_AGENT_CODEX_DISABLE=0                 # 1 → use the image's bundled codex
# ECAA_AGENT_CODEX_FORCE_REINSTALL=0         # 1 → reinstall even if cached
# ECAA_CODEX_INSTALL_DIR=                     # explicit cache dir (else session/agent cache)
# ECAA_AGENT_HOME_DIR=                        # override the per-task agent HOME (both wrappers).
#                                            # Default is an OUT-OF-PACKAGE cache dir so agent
#                                            # credentials never land inside the emitted package
#                                            # (artifact-served + git-committed). Overriding it
#                                            # back into $PACKAGE re-opens that exposure.
# ECAA_TASK_BUDGET_USD=                       # per-task soft dollar budget the codex wrapper passes
#                                            # into the container (the claude path uses the CLI's
#                                            # native --max-budget-usd instead); 0/unset disables.

# Per-task model tiering. With =1 (default), agent routes by task class:
#   discover_*    → Opus 4.8    (analytical scoring; depth pays off)
#   validate_*    → Sonnet 4.6  (stable codegen shape; 5× cheaper than Opus)
#   data_acq      → Sonnet 4.6
#   data_import   → Sonnet 4.6
#   everything else → Sonnet 4.6
# Quality safety net: validate_* still runs after every analytical task
# with explicit integrity checks; Sonnet writes stable validation
# scripts reliably. Subscription billing benefits too — Anthropic's
# quota meters token consumption regardless of mode. Set =0 to revert
# to all-Opus when maximum quality is required regardless of cost.
# ECAA_AGENT_MODEL_TIER=0

# Force every agent task to a single Claude model id, bypassing per-task
# model tiering. Intended for eval fairness or controlled operator
# calibration; unset in production so task-class tiering applies.
# ECAA_AGENT_MODEL_OVERRIDE=claude-sonnet-4-6

# Hard per-task cost ceiling (USD). claude CLI's --max-budget-usd
# terminates the agent session when running cost crosses the limit;
# this replaces the prior post-hoc enforce_turn_budget_limit (which
# only blocked AFTER the agent had already spent the tokens).
# Set above the cross-MODALITY p99 of each class's real cost distribution
# (on the model that runs the class) — a cap is a ceiling, and cost varies
# by modality, so calibrate from a variety of runs, not one workflow.
# Defaults below come from 1243 task runs across 12 modalities. discover_*
# (Opus) is the expensive class — bulk_rnaseq/variant_calling discover cost
# ~$2-2.7, so a low discover cap false-blocks ~30% of them.
#
# Per-class overrides (defaults in scripts/agent-claude.sh):
#   ECAA_AGENT_BUDGET_USD_VALIDATE=1.25
#   ECAA_AGENT_BUDGET_USD_DISCOVER=3.00
#   ECAA_AGENT_BUDGET_USD_DATA_ACQ=2.00
#   ECAA_AGENT_BUDGET_USD_ANALYTICAL=3.00   # also governs reporting/final_reporting
#
# Global override beats per-class. Set to 0 to disable the cap entirely.
# ECAA_AGENT_BUDGET_USD=3.00

# Verbose tracing inside scripts/agent-claude.sh (dispatch context, mount
# inspection, credential refresh). Default: 0.
# ECAA_AGENT_DEBUG=1

# =============================================================================
# Chat server
# =============================================================================
# Bind interface. Default 127.0.0.1 (loopback). 0.0.0.0 exposes on LAN;
# the server REFUSES TO BOOT on a non-loopback bind unless either
# ECAA_SERVER_AUTH_TOKEN is set or ECAA_SERVER_LAN_NO_AUTH=1 is the
# explicit opt-in.
# ECAA_BIND_ADDR=127.0.0.1

# HTTP listen port. Default 3000. Must match ECAA_SERVER_URL's port and
# the UI proxy's VITE_API_PORT — the `dev_port_drift` test guards this.
# ECAA_PORT=3000

# Bearer token required for every request when the server binds anything
# other than 127.0.0.1, and accepted as an opt-in shared secret on
# loopback. Generate with `openssl rand -hex 32` and pass via
# `Authorization: Bearer <token>` from the UI / curl. Unset on loopback
# = no auth required (single-user dev). Required for non-loopback bind.
# ECAA_SERVER_AUTH_TOKEN=

# Explicit opt-in to bind LAN-exposed (non-loopback) WITHOUT a token.
# Without this, the server fails closed on a non-loopback bind that
# lacks ECAA_SERVER_AUTH_TOKEN. Do not use in production — only for
# isolated dev VLANs.
# ECAA_SERVER_LAN_NO_AUTH=1

# Per-session harness self-token. NOT operator-set: the server mints a
# random token at /start_execution, stores only its SHA-256 on the
# ExecutionHandle, and injects the raw value into the harness child via
# this env var. The harness sends it back as `X-Harness-Token`, so its
# requests are principal'd as a session-scoped HarnessAgent rather than
# the global admin Owner. Documented here only to satisfy the env-var
# doc gate; setting it manually has no useful effect.
# ECAA_HARNESS_TOKEN=

# Allowed CORS Origins (comma-separated). Default covers the dev UI on
# :5173 + :3000 in both 127.0.0.1 and localhost forms. Override to the
# actual UI host(s) for production deployments.
# ECAA_CORS_ORIGINS=http://localhost:5173,http://127.0.0.1:5173,http://localhost:3000,http://127.0.0.1:3000

# Disable per-session owner authorization (debug only). With =1, any
# authenticated request can read/write any session. Used by the
# crates/server/tests/owner_authz.rs bypass branch. Never in production.
# ECAA_OWNER_AUTHZ_DISABLE=1

# Bypass the per-server flock (RC-22 multi-server tests). Default off;
# setting =1 lets a second server attach to a session already locked by
# another instance. Tests only.
# ECAA_SERVER_DEBUG_ALLOW_MULTI_PROCESS=1

# `offline` forces the server onto MockLlmBackend even if ECAA_ANTHROPIC_API_KEY is
# set. Kill switch for UI work when the LLM is unavailable.
# ECAA_CHAT_MODE=offline

# Directory where chat sessions are persisted. Default: ~/.ecaa-workflow/sessions.
# Keep production sessions on durable storage; /tmp is for disposable tests only.
ECAA_CHAT_SESSIONS_DIR=$HOME/.ecaa-workflow/sessions

# Config root used by the chat server (taxonomies, modality keywords, policies).
# Default: ./config (resolved relative to CWD).
# ECAA_CONFIG_DIR=./config

# Override the search root when the chat tools look up emitted packages by name.
# Default: ~/.ecaa-workflow/packages
ECAA_PACKAGE_ROOT=$HOME/.ecaa-workflow/packages

# Override the path to config/model-policy.yaml for ad-hoc experimentation.
# ECAA_MODEL_POLICY_PATH=/path/to/model-policy.yaml

# Override the confidence threshold at which the model policy escalates
# Sonnet → Opus. Default sourced from model-policy.yaml (0.3). Must be
# a float in [0.0, 1.0]; out-of-range or non-numeric values are ignored
# with a stderr warning.
# ECAA_MODEL_ROUTING_CONFIDENCE_THRESHOLD=0.3

# Session-store load mode. permissive (default) skips a corrupted file
# with a warning; strict fails the whole load. Test sites bias to strict.
# ECAA_SESSION_LOAD_MODE=strict

# Cadence of the session-store TTL prune sweep (seconds). Default 3600
# (1 hour). The prune removes sessions inactive longer than 30 days.
# ECAA_TTL_PRUNE_INTERVAL_SECS=3600

# Per-request body size cap (KiB). Default 256. Bumped automatically by
# the streaming upload code path (which has its own ECAA_UPLOAD_*
# bounds), so this cap is only the JSON-RPC ceiling.
# ECAA_REQUEST_BODY_LIMIT_KB=256

# Per-request wall-clock timeout (seconds). Default 60. SSE streams
# bypass this guard.
# ECAA_REQUEST_TIMEOUT_SECS=60

# Idempotency-Key cache TTL (seconds). Default 3600 (1 hour). Replays
# inside this window with the same body short-circuit to the cached
# response — see crates/server/src/chat_routes/_idempotency.rs.
# ECAA_IDEMPOTENCY_TTL_SECS=3600

# Per-endpoint LLM rate limits (requests / minute, per-IP via
# tower-governor). All have safe production defaults; bump in dev when
# the UI's polling endpoints saturate the global limit and need
# isolation. See crates/server/src/chat_routes/_rate_limits.rs.
#   ECAA_LLM_RATE_LIMIT_TURN          POST /turn                (default 30)
#   ECAA_LLM_RATE_LIMIT_SCORE         scoring side-call         (default 6)
#   ECAA_LLM_RATE_LIMIT_EXPLAIN       explain side-call         (default 30)
#   ECAA_LLM_RATE_LIMIT_SUMMARY       summary side-call         (default 6)
#   ECAA_LLM_RATE_LIMIT_REMEDIATION   remediation-proposer      (default 6)
#   ECAA_LLM_RATE_LIMIT_START_EXEC    POST /start-execution     (default 12)
#   ECAA_LLM_RATE_LIMIT_BRANCH        POST /branch              (default 6)
#   ECAA_LLM_RATE_LIMIT_SME_EDIT      SME task-param/bound edit (default 30)
# ECAA_LLM_RATE_LIMIT_TURN=30
# ECAA_LLM_RATE_LIMIT_SCORE=6
# ECAA_LLM_RATE_LIMIT_EXPLAIN=30
# ECAA_LLM_RATE_LIMIT_SUMMARY=6
# ECAA_LLM_RATE_LIMIT_REMEDIATION=6
# ECAA_LLM_RATE_LIMIT_START_EXEC=12
# ECAA_LLM_RATE_LIMIT_BRANCH=6
# ECAA_LLM_RATE_LIMIT_SME_EDIT=30

# Read-only shared-URL middleware. =1 honors session-share tokens for
# unauthenticated browsers. Default 0; without it the middleware is a
# no-op (every request passes through).
# ECAA_SHARED_URLS_ENABLED=1

# Disposition auto-apply (TEST ONLY). =1 auto-applies disposition decisions
# the agent emits, skipping SME confirmation. Do not set in production —
# the disposition unit tests intentionally clear it.
# ECAA_AUTO_APPLY_DISPOSITIONS=1

# Input listing + upload bounds (chat-routes inputs/upload routes).
# Tune when SMEs work with large cohort directories or upload-driven
# pipelines saturate the server's disk reserve.
# - ECAA_INPUT_ROOTS=<colon-separated>: allowlist of filesystem roots
#   SMEs may point local_path inputs at. Default user-home only.
# - ECAA_INPUT_MAX_FILES=<n>: max files listed (default 50000).
# - ECAA_INPUT_MAX_FILE_BYTES=<n>: per-file byte cap (default 50 GB).
# - ECAA_INPUT_MAX_TOTAL_BYTES=<n>: total bytes across listed files
#   (default 250 GB).
# - ECAA_UPLOAD_ROOT=<dir>: root for uploaded session files
#   (default ~/.ecaa-workflow/uploads).
# - ECAA_UPLOAD_MAX_BYTES=<n>: per-upload byte cap.
# - ECAA_UPLOAD_DISK_RESERVE_GB=<n>: bail out of new chunk writes when
#   free space on the upload root's filesystem falls below this (default 50).
# ECAA_INPUT_ROOTS=$HOME
# ECAA_INPUT_MAX_FILES=50000
# ECAA_INPUT_MAX_FILE_BYTES=53687091200
# ECAA_INPUT_MAX_TOTAL_BYTES=268435456000
# ECAA_UPLOAD_ROOT=~/.ecaa-workflow/uploads
# ECAA_UPLOAD_MAX_BYTES=53687091200
# ECAA_UPLOAD_DISK_RESERVE_GB=50

# Package import (upload & explore) bounds — zip/tar-bomb defense for the
# server package-import endpoint.
# Max uploaded package archive size in bytes (default 2 GiB).
ECAA_MAX_IMPORT_BYTES=2147483648
# Max entries in an uploaded package archive (default 200000).
ECAA_MAX_IMPORT_ENTRIES=200000
# Max total decompressed size of an uploaded package archive in bytes
# (default 8 GiB). Decompression-bomb defense: the compressed-upload cap
# above can't bound how large a tiny archive expands to, so the extractor
# caps the running decompressed total too.
ECAA_MAX_IMPORT_EXTRACTED_BYTES=8589934592

# Auto-register filesystem path hints extracted from intake prose
# (chat-side `append_intake_prose`). When `=1`, any path-shaped token
# in the SME's prose that resolves under ECAA_INPUT_ROOTS is promoted
# directly onto `session.inputs` — no follow-up confirmation prompt.
# Useful in non-interactive fixture runs where no SME is present to
# approve the registration. Default off (interactive flow surfaces the
# hint via get_session_state + the UI offers to register).
# ECAA_AUTO_REGISTER_PROSE_PATHS=1

# Anthropic client + token-burn knobs (chat side only; the per-task
# agent runs through scripts/agent-claude.sh's own credential path).
# - ECAA_ANTHROPIC_TIMEOUT_SECS=<n>: HTTP timeout for the Messages API
#   (default 180; was 120 pre plan §S2.7). Long generations on
#   Sonnet/Opus + tool loops can exceed 60–90s.
# - ECAA_ANTHROPIC_RPM=<n>: requests-per-minute cap on outbound calls.
#   Default unset (no cap). Set when the deployment hits a rate-limit.
# - ECAA_DISABLE_CONTEXT_EDITING=1: disables `context-management-2025-06-27`
#   (auto-clears stale tool_result blocks after 8 iterations; default on).
# - ECAA_SLIM_TAXONOMY=1: strips per-stage descriptions from the
#   taxonomy prompt to shrink uncached input.
# - ECAA_SESSION_TOKEN_BUDGET=<n>: soft-blocks the tool loop at this
#   many uncached input tokens (default 500000; cache-read doesn't
#   bill, so the budget tracks fresh content only).
# - ECAA_BUDGET_HARD_STOP=1: with ECAA_SESSION_TOKEN_BUDGET set, the
#   tool loop refuses to start a new turn once the soft-block ceiling
#   is crossed (default warn-only). CI fixtures use this to gate spend.
# - ECAA_DEFAULT_SESSION_BUDGET_USD=<n>: server-side default
#   session-level cost cap (USD). Per-session overrides via the
#   Settings UI; this is the fall-through default.
# - ECAA_ALLOW_1H_CACHE=1: permits ttl: "1h" on cache_control entries.
#   Default rejected (5m only).
# - ECAA_DEBUG_TOKEN_BURN=1: streams per-turn token/cache/cost to
#   stderr, warns at cache-hit <30% after ≥3 turns. Debug only.
# - ECAA_DEBUG=1: master debug gate. ECAA_DUMP_ANTHROPIC_PAYLOAD is
#   ignored unless this is set (refuses-by-default so a forgotten dump
#   path doesn't leak prompts into operator log directories).
# - ECAA_DUMP_ANTHROPIC_PAYLOAD=<file>: writes JSON of every outbound
#   Messages API request (mode 0600, appended). Use per-session paths
#   like /tmp/ecaa-payload-$SESSION.jsonl. Gated on ECAA_DEBUG=1.
# ECAA_ANTHROPIC_TIMEOUT_SECS=180
# ECAA_ANTHROPIC_RPM=50
# ECAA_DISABLE_CONTEXT_EDITING=1
# ECAA_SLIM_TAXONOMY=1
ECAA_SESSION_TOKEN_BUDGET=500000
# ECAA_BUDGET_HARD_STOP=1
# ECAA_DEFAULT_SESSION_BUDGET_USD=50
# ECAA_ALLOW_1H_CACHE=1
# ECAA_DEBUG_TOKEN_BURN=1
# ECAA_DEBUG=1
# ECAA_DUMP_ANTHROPIC_PAYLOAD=/tmp/ecaa-anthropic-payload.jsonl

# Git-backed provenance.
# - ECAA_GIT_ENABLED=0 hard-disables the feature regardless of the
#   Settings UI checkbox. Any other value (or absent) is config-driven
#   (default off in ~/.ecaa-workflow/git-config.json).
# - ECAA_GIT_CONFIG_PATH=<path>: override config-file path (default
#   ~/.ecaa-workflow/git-config.json).
# - ECAA_GIT_REPO_ROOT=<absolute-path>: operator escape hatch.
#   GitConfig::validate requires repo_path to canonicalize under $HOME;
#   set this to an additional absolute root that's also acceptable
#   (e.g., a shared /var/scripps/packages mount).
ECAA_GIT_ENABLED=1
# ECAA_GIT_CONFIG_PATH=~/.ecaa-workflow/git-config.json
# ECAA_GIT_REPO_ROOT=/var/scripps/packages

# ECAA_COMPOSER — planner selection. `semantic` and `proof-carrying` both
# select the v4 proof-carrying planner (emits runtime/proofs.jsonl +
# runtime/assumptions.jsonl; persisted onto Session::composer_version). Legacy
# values (`legacy`/`archetypes`/`backward-chain`) warn and route to v4. Default
# is the v4 planner when unset.
# ECAA_COMPOSER=proof-carrying

# ECAA_COMPOSE_STRICT — when set truthy, the v4 composer runs in
# RiskMode::Production: every composed-DAG edge that is not a typed data
# flow or adapter-mediated rejects, INCLUDING archetype-declared
# ordering-only edges. Default off (Draft) — clinical-tier emission that
# wants ordering exemptions re-justified sets this on.
ECAA_COMPOSE_STRICT=1

# ECAA_COMPOSE_INTERPRETATION — when set truthy, the v4 composer injects a
# grounded biological_interpretation atom (biology + method-justification,
# optionally literature-contextualized) before every reporting terminal, and a
# validate_interpretation companion. Feature-flagged (A/B-gated); default OFF,
# but opted IN here so the composer emits grounded interpretation. Unset (or =0)
# to revert to unchanged emitted DAGs.
ECAA_COMPOSE_INTERPRETATION=1

# ECAA_INTAKE_RESOLUTION — how intake resolves when NO specific analysis atom
# binds to the SME's question (the silent generic-fallback failure mode where a
# DAG finalises with only the descriptive scaffold and zero bound analysis).
#   auto-author  (DEFAULT) — splice an `agent_generated_analysis` node so the
#                run ATTEMPTS the requested analysis instead of emitting a
#                vacuous descriptive-only plan. Aliases: author, (unset/empty).
#   sme          — block at emit and wait for the human SME to author/confirm.
#   strict-block — refuse emit and record an unbindable-analysis failure.
#                Aliases: strict, block.
# Only acts when the question actually requests an analysis (an analysis verb is
# present); a genuinely descriptive ask is left on the generic scaffold.
# ECAA_INTAKE_RESOLUTION=auto-author

# ECAA_EXTERNAL_CURATED_DIRS — colon-separated operator-declared curated
# external-registry snapshot dirs (F3 federation). Dirs in this list
# resolve at RegistryTier::Curated (may reach StaticChecked after
# validate_for_executable); everything else is RegistryTier::Community
# (capped at Unverified). Empty by default. Imports never reach production
# execution until promoted regardless of tier (the execution gate is the
# backstop).
ECAA_EXTERNAL_CURATED_DIRS=

# =============================================================================
# Compute backend (harness)
# =============================================================================
# Which Executor to use.
#   local  — runs the agent as a subprocess on this host (default)
#   aws    — provisions EC2 via the aws CLI (see AWS section below)
#   slurm  — submits sbatch jobs over SSH to a SLURM cluster (see SLURM section below)
# `mock` exists as a test-only constructor; not dispatched from the factory.
ECAA_EXECUTOR_MODE=local

# =============================================================================
# Literature retrieval (literature_context tool + literature_* DAG tasks)
# =============================================================================
# Source-scope tier for evidence retrieval. Three values:
#   pmc_oa                  — PubMed Central Open Access subset (default)
#   pmc_oa_plus_abstracts   — also pulls PubMed/E-utilities abstracts
#   all_sources_local_only  — phase-2 stub (institutional access)
# Invalid values fall back to pmc_oa with a stderr warning.
# ECAA_LIT_SOURCE_SCOPE=pmc_oa_plus_abstracts

# Method-source authority for literature-grounded discovery. Values:
#   frozen     — rank only the already-curated candidate pool
#   bounded    — default; live discovery bounded by retrieval routes
#   open_ended — reserved wider mode; currently behaves like bounded
# ECAA_METHOD_SOURCE_AUTHORITY=bounded

# NCBI E-utilities API key. Unset = 3 req/s. Set = 10 req/s. Never logged.
# ECAA_LIT_NCBI_API_KEY=

# Per-task literature evidence size cap (MB). Default 200. On hit,
# result.json carries `truncated_at_storage_cap: true`. Soft-truncate,
# not a blocker.
# ECAA_LIT_EVIDENCE_MAX_MB=200

# Phase-2 stub for `all_sources_local_only`. No-op when set against any
# other scope. Not for production.
# ECAA_LIT_INSTITUTIONAL_ACCESS=1

# Disable the literature_context tool entirely. Used by external-eval
# adapters (Biomni, BioMedAgent) to force parity comparisons without
# the literature shim. Default off.
# ECAA_LITERATURE_CONTEXT_DISABLED=1

# Playwright literature.spec.ts live-API gate. Default off (the spec
# SKIPS without it).
# ECAA_LIT_LIVE_API=1

# =============================================================================
# AWS provisioning — required when ECAA_EXECUTOR_MODE=aws
# =============================================================================
# The required AWS variables are documented in this section. Every var below is
# no-op when ECAA_EXECUTOR_MODE=local.

# EC2 region for provisioning.
# ECAA_AWS_REGION=us-west-2

# AMI the harness launches. Produce with the Packer template in scripts/packer/.
# ECAA_AWS_AMI_ID=ami-0123456789abcdef0

# Security group attached to provisioned instances. Must allow outbound 443 for
# SSM and S3.
# ECAA_AWS_SECURITY_GROUP=sg-0123456789abcdef0

# IAM instance profile — required for SSM RunCommand + S3 access.
# ECAA_AWS_INSTANCE_PROFILE=ecaa-workflow-agent

# VPC subnet(s). Set either a single subnet OR a comma-separated list for
# multi-AZ failover (multi_az_policy rotates on InsufficientInstanceCapacity).
# ECAA_AWS_SUBNET_ID=subnet-0123456789abcdef0
# ECAA_AWS_SUBNET_IDS=subnet-aaa,subnet-bbb,subnet-ccc

# Optional EC2 key pair for SSH break-glass debugging. SSM is the primary
# control channel.
# ECAA_AWS_KEY_PAIR=scripps-ops

# S3 bucket + key prefix used to stage package inputs and collect outputs.
# Defaults: ecaa-workflow / ecaa-workflow/
# ECAA_AWS_S3_BUCKET=ecaa-workflow
# ECAA_AWS_S3_PREFIX=ecaa-workflow/

# Short SHA of the harness workspace. Tagged onto every provisioned instance
# so scan_orphans can correlate. Default: "unknown".
# ECAA_WORKSPACE_SHA=$(git rev-parse --short HEAD)

# =============================================================================
# AWS policy knobs
# =============================================================================
# true = request spot capacity with CapacityRebalance=true. Default: false.
# ECAA_AWS_SPOT=true

# REQUIRED when ECAA_EXECUTOR_MODE=aws. Hard USD cap — provision aborts if the
# estimated run cost exceeds the ceiling. Phase 9 (Task 9.1, closes F-EXEC-C-02):
# the harness now fails closed without an explicit positive ceiling. Operators
# that don't want a ceiling at all should run the non-AWS executors (local /
# slurm) which use NoopCostModel.
# ECAA_AWS_COST_CEILING_USD=10.00

# Phase 9 (Task 9.2) — optional comma-separated allowlist of EC2 instance
# types the harness is permitted to launch. Unset = any instance type the
# sizing layer chooses. Recommended starting set covers the workloads the
# default sizing tables emit; tighten further for prod operators.
# ECAA_AWS_INSTANCE_TYPE_ALLOWLIST=t3.medium,m6i.large,m6i.xlarge,m6i.2xlarge,r6i.large,r6i.xlarge,c6i.large,c6i.xlarge,g5.xlarge,g5.2xlarge

# What to do when a task exceeds its sizing high-water mark.
#   block    — halt the task
#   resize   — upgrade to the next shape that fits (default)
#   continue — warn and run anyway
# ECAA_AWS_HIGH_WATER_POLICY=resize

# Orphan instance policy.
#   warn — log orphaned i-XXXX without terminating (default)
#   reap — actively terminate orphans
# Any other value is treated as warn. CI lanes should set =reap so a
# leaked instance from a prior flaky run is terminated automatically.
# ECAA_AWS_ORPHAN_POLICY=warn

# Per-task SSM command timeout (seconds). Default: 3600. Per-stage overrides
# come from policies/compute-resource-policy.json inside each emitted package.
# ECAA_AWS_SSM_TIMEOUT_SECS=3600

# Verified-orphan sweep deadline (seconds). The harness times out the
# secondary describe-instances confirmation step after this long.
# Default: 300.
# ECAA_AWS_ORPHAN_VERIFY_TIMEOUT_SECS=300

# Regional pricing multiplier applied to the bundled instance-type
# pricing table. Default 1.0 (us-west-2 reference). Validated as a
# finite float in [0.5, 5.0] at config load.
# ECAA_AWS_PRICING_REGION_MULT=1.10

# Override the bundled pricing table. Accepts EITHER inline JSON OR a
# path to a JSON file. Schema: { "instance-type": <USD/hr>, ... }.
# Unspecified types continue to use bundled × ECAA_AWS_PRICING_REGION_MULT.
# ECAA_AWS_PRICING_OVERRIDES_JSON=/etc/scripps/aws-pricing.json
# ECAA_AWS_PRICING_OVERRIDES_JSON={"r6i.8xlarge":2.10}

# Spot bid price as a fraction of on-demand. Default 0.30. Higher
# values reduce spot-loss probability at higher cost.
# ECAA_AWS_SPOT_DISCOUNT_FRACTION=0.30

# Cumulative spend cap across the entire harness run (USD). Default
# 100. Differs from ECAA_AWS_COST_CEILING_USD which gates a single
# dispatch. On breach the harness halts and surfaces
# BlockerKind::CostCeilingExceeded.
# ECAA_AWS_RUN_TOTAL_CEILING_USD=100.00

# Security group for tasks whose atom carries `safety.network: none`.
# Required when the DAG contains any such task — the harness refuses
# dispatch otherwise. The SG should drop all outbound traffic.
# ECAA_AWS_RESTRICTED_SG_ID=sg-0fedcba9876543210

# =============================================================================
# Agent-side (used by scripts/agent-claude-aws.sh on the provisioned host)
# =============================================================================
# AWS credential profile for the CloudWatch MCP server. Default: default
# ECAA_AWS_PROFILE=default

# Populated by the AwsExecutor at dispatch time so the agent can tag
# CloudWatch queries with the right InstanceId dimension. Do not set by hand.
# ECAA_AWS_INSTANCE_ID=i-0123456789abcdef0

# Test-only handles into the AWS executor's command-cache. Not for
# production use; the integration tests set these to pin behavior.
# ECAA_AWS_ENV_LOCK=1
# ECAA_AWS_COMMAND_ID=cmd-XXXX

# Toggle MCP-server blocks in the agent's .mcp.json. All default to 0.
# Set =1 to enable the corresponding MCP server for an AWS-side agent.
# ECAA_MCP_AWS_AGENT_REGISTRY=1
# ECAA_MCP_BIO=1
# ECAA_MCP_GITHUB=1

# =============================================================================
# Harness scheduler
# =============================================================================
# Parallel-dispatch budget for the harness scheduler. `1` (default) is
# serial behavior. `auto` resolves to `nproc / max(tool_thread_curves)`
# so each task saturates its own thread budget without oversubscription.
# Integers > 1 cap the pool at that size. See crates/harness/src/scheduler.rs.
ECAA_HARNESS_CONCURRENCY=1

# Validation-lane parallelism (numeric 0/1). `1` = primary executor
# advances processing/analysis tasks while a secondary executor
# independently runs any ready validate_* task. `0` (or any other
# value) keeps validators serial. Overrides ECAA_HARNESS_CONCURRENCY
# when set to `1`. True parallel execution requires
# ECAA_EXECUTOR_MODE=local; aws/slurm keep the lane picker correctness
# but serialise execution through one backend handle (avoids
# double-provisioning a remote instance / submitting two batch jobs
# for one logical lane).
# ECAA_HARNESS_VALIDATION_LANE=1

# Harness loop tuning (advanced — leave at defaults unless diagnosing).
# - ECAA_HARNESS_AMEND_CANCEL=1 kills an in-flight task whose stage was
#   just amended, instead of letting it finish (default off; finishing
#   the prior attempt is usually cheaper than re-running from scratch).
# - ECAA_HARNESS_SETTLE_SECS controls the quiet period the harness
#   waits between iterations after a task completes (default 1s; bump
#   on slow filesystems where the agent's output write isn't visible
#   to the harness scanner immediately).
# - ECAA_HARNESS_BATCH_WINDOW_SECS — chat-side debounce window before
#   the HarnessBatcher flushes accumulated harness-progress events as
#   one synthetic assistant turn (default 10s; out-of-range / 0 /
#   non-numeric values fall back to default; values >600 are rejected
#   so blockers stay visible).
# - ECAA_TASK_HEARTBEAT_STALL_SECS — heartbeat stall threshold
#   (default 300 = 5 min, per DEFAULT_TASK_HEARTBEAT_STALL_SECS in
#   crates/core/src/config.rs:57; set 0 to disable). On breach the
#   harness flips the Running task to Blocked { HeartbeatStalled }.
# - ECAA_HEARTBEAT_LIVENESS_SECS — orphan-by-crash recovery liveness
#   window (default 60s, clamped [0, 600]).
# - ECAA_HARNESS_FINALIZE_PROBE_MIN_INTERVAL_SECS / _TIMEOUT_SECS —
#   finalize-probe cadence + per-probe deadline for silent-completion
#   detection (defaults 30s / 10s).
# - ECAA_HARNESS_MAX_NOPROGRESS_DISPATCHES — consecutive dispatches that
#   produce no progress before the crash-loop guard force-blocks the task
#   (default 8; set 0 to disable).
# - ECAA_HARNESS_VALIDATION_RECOVERY — DEFAULT OFF. When truthy
#   (1/true/yes/on), a task that a `required` validation-contract assertion
#   re-blocked is re-dispatched to the SAME agent a bounded number of times
#   after the harness writes a METHOD-NEUTRAL domain-correctness signal
#   (the failed assertion id + the design's operator-authored bound vs the
#   number recomputed from the agent's OWN result.json — never a tool, flag,
#   or threshold value) into runtime/inputs/<task>/domain-correctness-signal.json.
#   Off by default so the production / SME path keeps its human checkpoint
#   (a blocked task stays blocked for the SME). Intended for the unattended
#   operator-run eval arm; the per-task signal file records the recovery
#   budget so the scorecard meta can disclose that the bare arm has no
#   retry loop. The budget is durable on disk so it stays bounded across
#   the server's harness auto-relaunch.
# - ECAA_HARNESS_VALIDATION_RECOVERY_MAX — per-task recovery attempt budget,
#   clamped to [0, 2] (default 2). 0 disables recovery even when the flag
#   above is on.
# - ECAA_HARNESS_CONTRACT_ADVISORY — DEFAULT OFF. When truthy
#   (1/true/yes/on), ALL domain-correctness gates become NON-BLOCKING
#   advisory diagnostics: the task stays in its completed state so the DAG
#   proceeds and no validation-recovery re-dispatch fires. Covers three
#   gates — (1) the harness `required` validation-contract assertions and
#   (2) the harness Phase-13 post-completion validator bundle (both append
#   one JSON line per failure — task_id, assertion_id, severity, reason —
#   to a per-package runtime/validation-warnings.jsonl sidecar) and (3) the
#   server-side claim_coverage recall-gap re-verify gate (the gap is already
#   persisted into the signed verdict sink + audit-proof report, so the
#   Blocked/ValidationFailed transition is simply suppressed). Takes
#   PRECEDENCE over ECAA_HARNESS_VALIDATION_RECOVERY — when both are set,
#   advisory wins (no block, no re-dispatch). Off by default so the
#   production / SME path keeps its human checkpoint (a failed required
#   assertion or recall gap blocks the task for the SME). Intended for a
#   fair single-shot eval arm that runs the strict domain-correctness checks
#   as diagnostics without dead-stalling tasks or triggering recovery retries.
# ECAA_HARNESS_AMEND_CANCEL=1
# ECAA_HARNESS_SETTLE_SECS=1
# ECAA_HARNESS_BATCH_WINDOW_SECS=10
# ECAA_TASK_HEARTBEAT_STALL_SECS=300
# ECAA_HEARTBEAT_LIVENESS_SECS=60
# ECAA_HARNESS_FINALIZE_PROBE_MIN_INTERVAL_SECS=30
# ECAA_HARNESS_FINALIZE_PROBE_TIMEOUT_SECS=10
# ECAA_HARNESS_MAX_NOPROGRESS_DISPATCHES=8
# ECAA_HARNESS_VALIDATION_RECOVERY=0
# ECAA_HARNESS_VALIDATION_RECOVERY_MAX=2
# ECAA_HARNESS_CONTRACT_ADVISORY=0

# Offline end-of-run repair pass.
# - ECAA_AUTO_REPAIR — DEFAULT ON (in code; set to 0/false/no/off to opt out).
#   When enabled, the harness runs the OFFLINE repair loop ONCE at its loop-exit
#   convergence point (the `after.is_complete()` block in main.rs), which
#   BOTH run paths reach: the standalone/CLI run (no --session-id) and the
#   session/web-UI run (the server spawns this same harness WITH a
#   --session-id as the execution engine). The repair call sits OUTSIDE the
#   `progress.is_none()` gate that scopes the standalone self-finalize, so it
#   fires on both paths; the repair loop re-runs finalize internally and is
#   idempotent. It auto-corrects deterministic prose-vs-table counts and
#   re-seals BagIt manifests in place, and routes any agentic /
#   offline-unverifiable gap to the signed review list
#   (runtime/repair-status.json — the FullyPassing/MostlyPassing/Failing
#   tri-state verdict the UI can read — plus runtime/repair-requests.jsonl).
#   STRICTLY best-effort: any error or panic is logged and dropped, so it
#   never changes the run outcome. It NEVER re-executes an agent at
#   end-of-run; agentic re-runs remain the manual
#   `ecaa-workflow repair --agent` path.
ECAA_AUTO_REPAIR=1

# Bypass the harness multi-process flock (RC-22). The harness refuses
# to start when another harness holds the per-session flock at
# ~/.ecaa-workflow/locks/<session_id>.lock (exit code 2). Setting
# =1 lets a second harness attach — concurrent harnesses race on the
# dispatch WAL, so tests only.
# ECAA_HARNESS_DEBUG_ALLOW_MULTI_PROCESS=1

# Preserve per-task scratch directories (runtime/scratch/<task_id>/)
# on Completed / Failed transitions for forensic debugging. Default
# off (the cleanup runs as soon as the task reaches a terminal state).
# ECAA_SCRATCH_KEEP=1

# Per-agent-invocation guardrails honored by all three agent wrappers.
# - ECAA_AGENT_MEMORY_CAP_GB=<n>: per-agent memory ceiling. Unset = no
#   cap. When set, agent-claude.sh wraps the host-path `claude`
#   subprocess tree in `systemd-run --user --scope -p MemoryMax=<n>G`
#   (falls back to `prlimit --as`); docker/apptainer paths add
#   `--memory=<n>g`. Only the agent cgroup is reaped on breach;
#   harness/server/dev UIs stay alive.
# - ECAA_AGENT_WALLCLOCK_SECS=<n>: per-agent wallclock cap. Unset =
#   no cap. The harness kills the agent subprocess group at the
#   deadline and flips the task to Blocked { TimeExceeded }.
# - ECAA_AGENT_CMD=<path>: override the agent executable (default
#   ./scripts/agent-claude.sh). Used by integration tests +
#   alternative-agent experiments.
# - ECAA_AGENT_SCRIPT=<path>: eval-adapters alias for ECAA_AGENT_CMD.
#   Honoured by crates/eval-adapters/* runners; identical semantics.
# - ECAA_DISABLE_BLAS_PRELOAD=1: opt out of the libopenblas LD_PRELOAD
#   interpose for sites whose R install ships a parallel libRblas
#   natively (Conda forge R, MKL-built builds).
# ECAA_AGENT_MEMORY_CAP_GB=64
# ECAA_AGENT_WALLCLOCK_SECS=14400
# ECAA_AGENT_CMD=./scripts/agent-claude.sh
# ECAA_DISABLE_BLAS_PRELOAD=1
# Max retries on transient API-transport failures (socket reset / 429 /
# 502-504) inside a single agent invocation before the harness marks the
# task Blocked. Default: 2. Must be >= 1; non-numeric or < 1 clamps to 1.
# ECAA_AGENT_TRANSIENT_MAX_ATTEMPTS=2

# Dynamic per-agent resource allocation. Default ON. When active, each
# agent's ECAA_HW_VCPUS_AVAILABLE / ECAA_HW_MEMORY_GB envelope reflects
# the host's live free budget minus an overhead reserve, split across
# concurrent picks proportional to their per-stage high-water
# requirements (compute_high_water in executor/sizing.rs). Set to 0 to
# revert to the legacy "agent sees the full host" envelope.
ECAA_HW_DYNAMIC_ALLOCATION=0

# Overhead margin held back from agents for the harness, server, UI,
# and OS. The larger of (absolute, pct of total) wins per dimension.
# Defaults: 1 vCPU, 2 GB, 10%. ECAA_HW_OVERHEAD_PCT is capped at 50.
ECAA_HW_OVERHEAD_VCPUS=1
ECAA_HW_OVERHEAD_MEMORY_GB=2
ECAA_HW_OVERHEAD_PCT=10

# Fill idle host capacity. By default dynamic allocation grants each picked
# task exactly its per-stage high-water (e.g. 8 vCPU / 64 GB), which can leave a
# large host mostly idle on a serial run (ECAA_HARNESS_CONCURRENCY=1). With this
# ON, under-subscribed picks scale UP to fill the usable budget (host free minus
# overhead), so a single heavy task (e.g. Harmony/PCA on ~1M cells) gets ~all
# free cores + RAM and finishes faster; K concurrent picks split the budget
# proportionally, so it never over-subscribes. Local executor only (AWS/SLURM
# size by instance type). Set to 0 to keep exact-high-water allocation.
ECAA_HW_FILL_HEADROOM=1

# Advisory CPU/thread floor from remediation or site policy. The agent
# bootstrap applies it to BLAS/OpenMP thread env vars and container
# `--cpus`. Unset = use scheduler's recommended thread count.
# ECAA_HW_NPROC_HINT=8

# Note: ECAA_HW_VCPUS_AVAILABLE / ECAA_HW_MEMORY_GB / ECAA_HW_GPU /
# ECAA_HW_RECOMMENDED_THREADS / ECAA_HW_TOOL_THREAD_CURVES /
# ECAA_HW_TASK_RESOURCE_CLASS / ECAA_HW_CONCURRENT_PEERS_BY_CLASS /
# ECAA_HW_INTAKE_FACTS / ECAA_HW_ENV_OVERRIDES / ECAA_HW_GPU_CAPABILITY_REF
# are RUNTIME-SET by the harness onto each agent's env at dispatch.
# Setting them in your shell will be silently overwritten — only override
# when reproducing a specific allocation in isolation.

# =============================================================================
# Pilot sizing
# =============================================================================
# Runs a small pilot against representative tasks before the main
# provisioning call, then feeds the projected high-water requirements
# into local allocation, AWS instance selection, and SLURM class
# selection. AWS defaults pilot on; local/SLURM require explicit opt-in
# and SLURM consumes an existing report when present.

# Gate for the pilot pathway. Default: 1 on AWS, 0 elsewhere.
# ECAA_PILOT_ENABLED=1

# Number of pilot tasks to sample before projecting. Default: 3.
# ECAA_PILOT_TASKS=3

# Multiplier applied to the pilot's measured high-water when projecting
# the full-run shape. Default: 1.5.
# ECAA_PILOT_MULTIPLIER=1.5

# Pilot instance type override. When set, the pilot runs on this shape
# regardless of DAG contents (useful for forcing a cheap shape like
# t3.medium). Cleared after pilot release.
# ECAA_PILOT_INSTANCE=t3.medium

# Measurement interval during the pilot (seconds). Default: 5.
# ECAA_PILOT_INTERVAL_SECS=5

# Long-form aliases accepted by the pilot config loader. Short names
# above remain canonical.
#   ECAA_PILOT_INSTANCE_TYPE              ≡ ECAA_PILOT_INSTANCE
#   ECAA_PILOT_TASK_COUNT                 ≡ ECAA_PILOT_TASKS
#   ECAA_PILOT_PROJECTION_MULT            ≡ ECAA_PILOT_MULTIPLIER
#   ECAA_PILOT_MEASUREMENT_INTERVAL_SECS  ≡ ECAA_PILOT_INTERVAL_SECS
# ECAA_PILOT_INSTANCE_TYPE=t3.medium
# ECAA_PILOT_TASK_COUNT=3
# ECAA_PILOT_PROJECTION_MULT=1.5
# ECAA_PILOT_MEASUREMENT_INTERVAL_SECS=5

# =============================================================================
# Stall monitor — opt-in (default on for AWS; off elsewhere)
# =============================================================================
# Samples CPU/memory/GPU from /proc/<pid>/ (local) or CloudWatch (AWS)
# and emits a StallSignal when a threshold is breached. The harness
# translates signals into Blocked { Stalled } sessions.

# Gate for the stall monitor. Defaults to on when ECAA_EXECUTOR_MODE=aws,
# off otherwise. Accepts 1/0/true/false.
# ECAA_STALL_ENABLED=1

# CPU below this percentage counts as starvation. Default: 5.0.
# ECAA_STALL_CPU_MIN_PCT=5.0

# Sustained CPU-starvation duration before a stall signal fires (minutes).
# Default: 30.
# ECAA_STALL_CPU_WINDOW_MINS=30

# Memory above this percentage counts as pressure. Default: 90.0.
# ECAA_STALL_MEM_MAX_PCT=90.0

# Sustained memory-pressure duration before a stall signal fires (minutes).
# Default: 5.
# ECAA_STALL_MEM_WINDOW_MINS=5

# GPU-idle threshold while the envelope declares training (minutes).
# Default: 15.
# ECAA_STALL_GPU_IDLE_MINS=15

# Multiplier on expected task runtime before a runtime-overrun signal
# fires. Default: 3.0.
# ECAA_STALL_RUNTIME_MULT=3.0

# Sampling cadence (seconds). Default: 30. CloudWatch native granularity
# caps at 60s.
# ECAA_STALL_SAMPLE_INTERVAL_SECS=30

# =============================================================================
# Chat server → harness dispatch
# =============================================================================
# URL the harness POSTs progress events back to. Must match the chat
# server's actual listening port (the server's `--port` flag, default
# 3000). A mismatch silently breaks the UI's harness-progress events
# because the SSE bus never receives the POSTs (the harness logs
# `Connection refused` after retries) — WORKFLOW.json still updates,
# but the "running" pill in the inspector never lights up.
#
# The canonical dev port is 3000 across:
#   - `crates/server/src/lib.rs` `--port` default
#   - Makefile `DEV_SERVER_PORT`
#   - `ui/vite.config.ts` VITE_API_PORT fallback
# The `dev_port_drift` test (crates/server/tests/dev_port_drift.rs)
# fails CI if these three drift apart. Default: http://127.0.0.1:3000.
ECAA_SERVER_URL=http://127.0.0.1:3000

# Vite reads this and uses it as the `/api/*` proxy target for the
# dev UI server. Must match ECAA_SERVER_URL's port above; the
# Makefile's `make up` recipe exports it automatically to keep the
# vite proxy and the server's `--port` aligned. Default: 3000.
VITE_API_PORT=3000

# Per-IP global rate-limit (tower-governor). Production defaults from
# crates/server/src/lib.rs are 2000ms interval / burst 30 → 0.5 req/s
# sustained — fine for proxied prod traffic where each SME is a
# distinct peer IP. In LOCAL DEV every UI session shares 127.0.0.1
# and the UI polls /dag, /proposals, /dispositions, /compose-outcome,
# /metrics every few seconds; that burns through the 30-token burst
# within a single chat turn and 429s the polling endpoints. The
# source comment at crates/server/src/lib.rs:240 explicitly
# recommends these dev overrides.
# ECAA_RATE_LIMIT_INTERVAL_MS=10
# ECAA_RATE_LIMIT_BURST=10000

# Absolute path to the ecaa-workflow-harness binary. The chat server
# spawns this as a subprocess for post-emit execution. Default: resolved
# via `which ecaa-workflow-harness`.
# ECAA_HARNESS_BIN_PATH=/usr/local/bin/ecaa-workflow-harness

# Default agent script the chat server passes as --agent when spawning
# the harness. Operators set this to the path of agent-claude.sh /
# agent-claude-aws.sh / agent-claude-slurm.sh. Default: ./scripts/agent-claude.sh
# ECAA_DEFAULT_AGENT_PATH=./scripts/agent-claude.sh

# Override the agent-scripts root for path-jail validation. Default
# ./scripts/. The server refuses to spawn an --agent that doesn't
# resolve under this directory.
# ECAA_SCRIPTS_DIR=./scripts

# Server-side default for harness `--max-iterations` when the chat
# server spawns it via /start-execution. Default: 20. Bump to e.g.
# 1000 for long-running detached compute so the harness lives across
# the workload instead of churning at iteration boundaries. The
# standalone `make ivd-execute` Make target reads its own MAX_ITER
# knob (default 30) and does NOT honor this variable.
ECAA_DEFAULT_MAX_ITERATIONS=20

# =============================================================================
# SLURM provisioning — required when ECAA_EXECUTOR_MODE=slurm
# =============================================================================
# The required SLURM variables are documented in this section. Every var below
# is no-op when ECAA_EXECUTOR_MODE=local|aws.
#
# Transport: system `ssh` + `rsync` via duct (ControlMaster multiplexing).
# Cost model: NoopCostModel — HPC fairshare/QoS quotas, not $/hr.

# Login/submit node hostname. REQUIRED.
# ECAA_SLURM_HOST=login.cluster.example.org

# Shared-FS path on the cluster where packages + wrappers get staged.
# REQUIRED. Typical: /scratch/$USER/scripps
# ECAA_SLURM_STAGING_DIR=/scratch/alan/scripps

# Fallback partition when the sizing mapping has nothing that fits.
# REQUIRED. Also used when the operator doesn't ship a slurm-mapping.yaml.
# ECAA_SLURM_DEFAULT_PARTITION=normal

# SSH user. Defaults to the shell's `$USER` via `ssh`'s own fallback.
# ECAA_SLURM_USER=alan

# Private key path. Omit to let `ssh` use ssh-agent / default keys.
# ECAA_SLURM_SSH_KEY=~/.ssh/id_ed25519_cluster

# Bastion host (`ssh -J <host>` flag). Omit for direct SSH.
# ECAA_SLURM_PROXY_JUMP=bastion.corp.example.org

# Billing / project account (`#SBATCH --account=`). Omit when the site
# derives it from the user.
# ECAA_SLURM_ACCOUNT=lotz-lab

# Default QoS (`#SBATCH --qos=`). Overridden per-class when a
# resource_class specifies its own qos in slurm-mapping.yaml.
# ECAA_SLURM_DEFAULT_QOS=normal

# Comma-separated `module load` list prepended to every sbatch script
# body. Leave unset when the site's default environment is sufficient.
# ECAA_SLURM_MODULES=python/3.11,singularity/3.8

# `sacct` poll rate (seconds). Default: 20. Lower wastes SSH round-trips;
# higher delays staleness detection.
# ECAA_SLURM_POLL_INTERVAL_SECS=20

# Abort + scancel a job that's still PENDING after this many seconds.
# Default: 21600 (6 hours).
# ECAA_SLURM_MAX_QUEUE_WAIT_SECS=21600

# Fallback `--time=` when the sizing mapping's resolver falls back
# (no named resource_class satisfied the requirement). Default: 04:00:00.
# ECAA_SLURM_DEFAULT_TIME_LIMIT=04:00:00

# Container runtime for the SLURM agent wrapper (agent-claude-slurm.sh).
# Accepted: singularity | apptainer | podman. Unset = agent runs on the
# host's Python/R/etc. directly. Sites that enforce rootless containers
# on compute nodes should pick one here.
# ECAA_SLURM_CONTAINER_RUNTIME=singularity

# Concurrent CPU-class task budget on the SLURM lane. Default 1 (serial).
# Bump to fan out independent CPU tasks across multiple sbatch
# submissions in parallel.
# ECAA_SLURM_MAX_PARALLEL_TASKS=1

# Concurrent GPU-class task budget. Default 0 (refuse GPU tasks on the
# SLURM lane entirely). Set to a positive value to permit GPU dispatch
# up to that ceiling; the resource_class → partition mapping must
# also resolve.
# ECAA_SLURM_MAX_GPU_TASKS=0

# Emit per-job sacct usage stats on completion (cputime, MaxRSS, etc.)
# into runtime/slurm-usage.json. Default off; opt in for capacity
# planning runs.
# ECAA_SLURM_EMIT_USAGE=1

# =============================================================================
# Container mode (Stage 15) — local agent
# =============================================================================
# Operator-level default container image used by scripts/agent-claude.sh
# when neither the per-task `container.image` field nor the package's
# policies/container.json::image is set. Per-task and package-level
# pins still win — this is the lowest-priority source. With this set,
# every agent invocation runs inside the named image by default; unset
# (or set to empty) to fall back to host execution.
#
# `bio-min:local` (built by scripts/build-bio-min.sh) ships R 4.5 +
# Python 3.11 + numpy/pandas/scipy + OpenBLAS + OpenMP + TBB + OpenMPI
# + samtools/bcftools/STAR/salmon/GATK4/fastqc + Node + claude-code CLI
# so the dispatched agent can `apt install` / `pip install` /
# `Rscript -e 'BiocManager::install("…")'` whatever analysis package
# the SME-confirmed method requires at runtime.
# The older `ecaa-workflow-agent:local` baseline shipped only
# Python+pip+node and forced agents to reimplement DESeq2 etc. in
# pure Python (2026-05-24 S1 finding).
# ECAA_DEFAULT_CONTAINER_IMAGE=bio-min:local

# Replay image-drift fallback. When an agent-free `replay` cannot find the exact
# recorded per-task snapshot image locally (e.g. it was garbage-collected), fall
# back to the current base image (ECAA_DEFAULT_CONTAINER_IMAGE, default
# `bio-min:local`) so old packages remain re-executable — logging a loud IMAGE
# DRIFT warning and tagging the report's `env_tier`. Enabled by default; set to
# 0 to REQUIRE the exact recorded image (fail loudly instead of drifting).
# ECAA_REPLAY_IMAGE_FALLBACK=1

# Pin the local-host runtime (skip the apptainer → docker → podman
# auto-probe). Accepted: apptainer | docker | podman. Unset = harness
# probes apptainer → docker → podman in priority order.
# ECAA_CONTAINER_RUNTIME=docker

# Optional non-root identity for containerized execution agents. Set both
# values together to positive integers. When unset, the wrapper resolves the
# invoking user, writable mount owner, image user, or a safe unprivileged
# fallback in that order. Root (0) is rejected.
# ECAA_AGENT_CONTAINER_UID=1000
# ECAA_AGENT_CONTAINER_GID=1000

# GPU vendor for container passthrough on a GPU-required task. Accepted:
# auto | nvidia | amd | none. Default auto. NVIDIA uses the container
# toolkit (`--gpus`/`--nv`); AMD/ROCm uses raw device flags
# (`--device=/dev/kfd --device=/dev/dri` + the video/render GIDs +
# seccomp=unconfined / apptainer `--rocm`). On `auto` the agent script
# picks amd when /dev/kfd or rocminfo is present, then nvidia when
# nvidia-smi is present, else none.
# ECAA_CONTAINER_GPU_VENDOR=auto

# ROCm gfx ISA override exported into the container on the AMD path
# (HSA_OVERRIDE_GFX_VERSION). Default 10.3.0 — required by many ROCm
# libraries for gfx1030 (RDNA2, e.g. RX 6800 XT). Set to another ISA
# (e.g. 11.0.0 for gfx1100) to match a different card, or set EMPTY to
# emit no override at all.
# ECAA_ROCM_GFX_OVERRIDE=10.3.0

# Per-session container cache mount root. Default: ~/.ecaa-workflow/
# agent-cache/<session_id>. Set to a directory on a high-capacity volume
# when running on a host whose system disk is small.
# ECAA_AGENT_CACHE_DIR=$HOME/.ecaa-workflow/agent-cache

# Per-task scratch mount root. Default: <package>/runtime/scratch/<task_id>/.
# Override when the package volume is too small for large intermediates.
# ECAA_AGENT_SCRATCH_DIR=$HOME/.ecaa-workflow/agent-scratch

# Soft ceiling on per-session cache size (default 50 GB).
# ECAA_AGENT_CACHE_MAX_GB=50

# LRU cache-eviction sweep cadence (seconds). Default 600 (10 min);
# clamped to [60, 3600]. Out-of-range or non-numeric values fall back
# to default with a stderr warning.
# ECAA_CACHE_EVICTION_PERIOD_SECS=600

# Opt out of the per-session cache mount entirely.
# ECAA_AGENT_CACHE_DISABLE=1

# Share the agent cache (pip/conda/R-libs) ACROSS sessions instead of
# the default per-session subdir. Default = 0 (per-session isolation,
# prevents cross-session cache poisoning per D-R13). Setting = 1
# switches the cache layout to a single shared `agent-cache/global/`
# directory so a heavy compile (e.g. DESeq2 from Bioconductor,
# 15-30 min the first run) installs once and is reused by every later
# session that picks the same method. Designed for testing campaigns +
# dev environments; production deployments should leave it off so
# session isolation holds. Per-package R/Python installs are atomic
# (tmp + rename), so concurrent agents installing the same package
# don't corrupt each other.
# ECAA_AGENT_CACHE_GLOBAL=1

# Per-task background credential refresh interval (seconds). The agent
# script polls $HOME/.claude/.credentials.json and re-copies it into
# the per-session bind-mount when the host is newer, so an operator
# `claude /login` to a different account propagates to in-flight
# agents within this window. Default 15. Set to 0 to disable. Values
# <5 or non-numeric clamp to default with a stderr warning.
# ECAA_AGENT_CRED_REFRESH_SECS=15

# Per-session @anthropic-ai/claude-code version. The container image's
# baked-in claude CLI lags Anthropic's deployed minor version
# (e.g. 2.1.131 in image vs 2.1.132 on host); older minors get
# silently 429'd on /v1/messages with no stderr. The agent script
# npm-installs the requested version into the per-session cache
# (~30s one-time per session) and bind-mounts it into the container,
# preempting the image's bundled binary via PATH. Default `latest`.
# ECAA_AGENT_CLAUDE_VERSION=latest

# Force re-install on every dispatch (default 0 = reuse the cached
# install for the lifetime of the session). Set to 1 to pick up new
# Anthropic releases mid-session without restarting.
# ECAA_AGENT_CLAUDE_FORCE_REINSTALL=1

# Opt out of the per-session install entirely; falls back to the
# container's baked-in claude. Use only when the image was just
# rebuilt with a known-good claude-code or when the host has no npm.
# ECAA_AGENT_CLAUDE_DISABLE=1

# Local-mode sandbox layer. Default: off. With `bubblewrap`, the
# host-mode agent invocation is wrapped in `bwrap` for filesystem +
# network containment without container overhead. Requires `bwrap` on
# PATH; falls back to unsandboxed host with a stderr warning.
# ECAA_LOCAL_SANDBOX=bubblewrap

# Deposit profile of the execution run. Value: `re-executable`. When set
# (and ECAA_LOCAL_SANDBOX is left unset), the harness defaults bwrap
# filesystem-view enforcement ON so a re-executable deposit can't read
# outside its declared inputs; escape hatch ECAA_LOCAL_SANDBOX=off. Set
# automatically by `ecaa-workflow replay --tier execute|all` for the
# re-execution verification run; the INITIAL harness execution still relies
# on the operator setting this in the server/harness environment.
# ECAA_DEPOSIT_PROFILE=re-executable

# Fallback network policy when the atom's `ContainerSpec.network` is
# unset. Default: bridge. Use `none` to drop networking inside
# containers/sandboxes (offline analysis runs).
# ECAA_CONTAINER_NETWORK_DEFAULT=bridge

# Opt-in for the Wave / Seqera on-demand image build resolver (S15.13).
# ECAA_WAVE_RESOLVER=1

# Bearer token for the digest-resolver against private registries.
# ECAA_CONTAINER_REGISTRY_AUTH=<token>

# When 1 (default), AwsExecutor refuses dispatches whose
# `preferred_container` requires a runtime newer than the AMI's baked
# RUNTIME_VERSIONS.json. Set to 0 only on hosts where you intentionally
# bypass the strict gate.
# ECAA_AMI_RUNTIME_STRICT=1

# Extends `verify-reproducibility` to re-resolve emitted ContainerSpec
# digests against the registry.
# ECAA_CONTAINER_VERIFY=1

# Opt-in for SLURM 25.11's --container directive (off by default;
# honored only when the detected SLURM is ≥ 25.11).
# ECAA_SLURM_NATIVE_CONTAINER=1

# Kill switch: Stage 15 container plumbing is bypassed entirely.
# Falls through to host environment path (no runtime probe, no image
# pull). Use when a host has no runtime and the SME accepts the lower
# reproducibility floor.
# ECAA_DISABLE_CONTAINERS=1

# Toggle Syft SBOM emit at task completion. Default: 1. Set to 0 to
# skip the supply-chain attestation step when Syft is unavailable or
# the site doesn't require SBOMs.
# ECAA_SBOM_EMIT=0

# Toggle the libRblas LD_PRELOAD interpose performed by the
# _agent-blas-bootstrap.sh helper. Set to 1 to OPT OUT of the
# interpose on sites whose R install ships a parallel libRblas
# natively (Conda forge R, MKL-built builds). Default: off (preload on).
# ECAA_DISABLE_BLAS_PRELOAD=1

# Override path to the mock claim-emitter binary used by the
# contract-adequacy adapter. Default: scripts/agent-mock-claim-emitter.sh
# ECAA_AGENT_MOCK_CLAIM_EMITTER=/path/to/custom-claim-emitter.sh

# Agent log rotation cap (bytes). When the agent's output log exceeds
# this size, agent-claude.sh rotates it. Default 209715200 (200 MiB);
# set 0 to disable rotation.
# ECAA_AGENT_LOG_MAX_BYTES=209715200

# Agent heartbeat cadence (seconds). Default 30.
# ECAA_HEARTBEAT_INTERVAL_SECS=30

# Memory high-water percentage. The agent trips an early warning when
# its memory exceeds MEM_MAX_MB × ECAA_AGENT_MEMORY_HIGH_WATER_PCT / 100.
# Default 85.
# ECAA_AGENT_MEMORY_HIGH_WATER_PCT=85

# Credential-rotation grace window (seconds). When the agent script
# refreshes Claude credentials, it skips host→container copy if the
# container-side file's mtime advanced within this many seconds.
# Default 2.
# ECAA_AGENT_CRED_ROTATION_GRACE_SECS=2

# Docker run hardening (consumed by scripts/agent-claude*.sh wrappers).
# All have safe defaults from scripts/agent-claude-common.sh:
#   ECAA_DOCKER_TMPFS_TMP_SIZE     /tmp tmpfs size           (default 1g)
#   ECAA_DOCKER_TMPFS_VARTMP_SIZE  /var/tmp tmpfs size       (default 512m)
#   ECAA_DOCKER_PIDS_LIMIT         --pids-limit              (default 2048)
# ECAA_DOCKER_TMPFS_TMP_SIZE=1g
# ECAA_DOCKER_TMPFS_VARTMP_SIZE=512m
# ECAA_DOCKER_PIDS_LIMIT=2048

# Library version pins (ECAA_LIB_PIN_<NAME>=<version>). Every var
# matching this prefix is forwarded into the agent's environment and
# read by the install-proxy to pin a specific library version.
# Examples:
#   ECAA_LIB_PIN_SCANPY=1.9.6
#   ECAA_LIB_PIN_ANN_DATA=0.10.0
#   ECAA_LIB_PIN_BLAS=openblas-0.3.27
#   ECAA_LIB_PIN_BWA=0.7.17

# Bypass the agent sandbox environment-clearing pass. Default off (the
# harness clears all but allowlisted vars before invoking the agent).
# With =1 the agent inherits the full parent environment — debug only;
# leaks secrets that the clearing pass is precisely there to scrub.
# ECAA_DISABLE_ENV_CLEAR=1

# Capture the agent's assembled compute environment into a content-addressed
# image at end-of-run, so the package re-executes byte-identically via
# `ecaa-workflow replay --tier execute`. Runs only when the agent installed
# packages; non-fatal. Default: on. Set =0 to skip (faster eval/dev runs).
# ECAA_ENV_SNAPSHOT=1

# Registry-host allowlist gating the replay install-from-lock tier
# (comma-separated). When a package logs a pinned conda EXPLICIT lock instead
# of shipping its env, `ecaa-workflow replay --tier execute` materializes it by
# running `conda create --file <lock>`, which FETCHES every package URL in the
# lock. An untrusted, imported package could point those URLs at
# attacker-controlled hosts, so every URL's host must match (exact or
# dotted-subdomain) an entry here or the install is REFUSED (the replay degrades
# to unprovisionable → a clean PARTIAL verdict, never a silent fetch). Enforced
# regardless of package trust (defense-in-depth). Unset → the default conda
# registry set: conda.anaconda.org, repo.anaconda.com, anaconda.org (covering
# conda-forge / bioconda / defaults). Override only to point at an internal
# mirror.
# ECAA_REPLAY_LOCK_REGISTRY_ALLOWLIST=conda.anaconda.org,repo.anaconda.com,anaconda.org

# Container registry to push the per-run environment snapshot to (by digest),
# enabling byte-identical re-execution by a reviewer who downloads the package
# elsewhere. Unset → snapshot kept in the local content-addressed image store
# (re-execution only on the same host). e.g. ghcr.io/<org>/ecaa-snapshots
# ECAA_IMAGE_REGISTRY=

# Test/CI gate for the env-snapshot build→replay integration test
# (crates/harness/tests/env_snapshot_integration.rs): the test no-ops unless
# this is set, because the live path needs docker + the bio-min base image.
# Leave UNSET in production. # ECAA_ENV_SNAPSHOT_TEST=1

# =============================================================================
# Derived-image warm-up (Plan §S15.x — local agent)
# =============================================================================
# When the compiler emits a buildable runtime-prereqs manifest
# (policies/runtime-prereqs.json + runtime/derived-image.Dockerfile),
# the local-executor pre-flight runs scripts/build-derived-image.sh
# before the first agent dispatch. The script content-hashes the
# manifest, checks the local docker registry for a cached
# scripps-derived:<hash> image, and either re-uses it (cheap) or
# builds it fresh.

# Skip the local-cache check and always rebuild. Use after a base-image
# upgrade or while debugging the renderer.
# ECAA_FORCE_IMAGE_REBUILD=1

# Build-time source-commit override baked into the emitted crate metadata
# (#ecaa-workflow softwareVersion). Read by crates/core/build.rs; when unset the
# build resolves `git rev-parse --short=12 HEAD` (+ `-dirty`), falling back to
# "unknown" outside a git checkout. Set in CI to pin the exact release commit.
# ECAA_SOURCE_COMMIT=abcdef012345

# Buildkit cache root for derived-image layer reuse across sessions.
# Default: $ECAA_AGENT_CACHE_DIR/buildkit if ECAA_AGENT_CACHE_DIR is
# set, else ~/.ecaa-workflow/buildkit-cache.
# ECAA_BUILDX_CACHE_DIR=$HOME/.ecaa-workflow/agent-cache/buildkit

# Wall-clock cap on a single derived-image build. Default 1800 (30 min).
# Exceeding it surfaces as a typed BlockerKind::ImageBuildFailed.
# ECAA_IMAGE_BUILD_TIMEOUT_SECS=1800

# Image-tag prefix for derived images. Default: scripps-derived. Set
# to a private-registry path like "registry.example.com/scripps/derived"
# when pre-pushing for cluster reuse.
# ECAA_DERIVED_IMAGE_TAG_PREFIX=scripps-derived

# Override the path to the build-derived-image.sh helper (default
# `scripts/build-derived-image.sh` resolved relative to the harness CWD).
# ECAA_IMAGE_BUILDER_PATH=/usr/local/bin/build-derived-image.sh

# Per-atom isolated derived images keyed by content_hash_from_file.
# Default on (1). With =0 the harness reverts to the legacy union-build
# path that bakes every prereq into one image. Flip off only when
# debugging a per-task image build failure.
# ECAA_PER_TASK_IMAGES=1

# Per-atom image build directory. Default ~/.ecaa-workflow/per-atom-builds/.
# Point at a high-capacity volume when running large fan-outs.
# ECAA_PER_ATOM_BUILD_ROOT=/mnt/big/ecaa-per-atom-builds

# Override the install-proxy library path. The emitter normally walks
# up from CWD looking for lib/install-proxy/. Set when running outside
# the repo checkout.
# ECAA_INSTALL_PROXY_LIB=/opt/scripps/lib/install-proxy

# Per-task provisioning policy JSON path. The harness stamps this onto
# every dispatch envelope so the agent script can enforce atom safety
# policy + container plumbing. Default
# /etc/ecaa-workflow/provisioning.json (falls back to the
# package-local policies/provisioning-policy.json when absent).
# ECAA_PROVISIONING_POLICY=/etc/ecaa-workflow/provisioning.json

# Bypass install-proxy provisioning policy check inside the agent.
# Debug-only — the check gates implicit `pip install` / `apt-get install`.
# ECAA_PROVISIONING_DISABLE=1

# Skip the shim smoke-test that build-derived-image.sh runs after each
# successful build (verifies install-proxy + LD_PRELOAD shim load).
# ECAA_SKIP_SHIM_SMOKE=1

# =============================================================================
# Test / script knobs
# =============================================================================
# Opt-in flag for Make targets that hit the live Anthropic API
# (ivd-chat-llm, ivd-web-execute). When unset, those targets SKIP with a
# pointer to the mock variant.
# ECAA_LIVE_API=1

# Enable the Haiku-powered session auto-title feature. `=1` surfaces the
# "Auto-name" button in the UI title bar and enables
# POST /api/chat/session/:id/auto-title. One Haiku 4.5 call per session
# lifetime (~$0.0006, billed to `side_call_cost_usd`); idempotent — once set,
# the route short-circuits without re-invoking the LLM. Unset = feature off
# (button hidden, route returns 503).
# ECAA_AUTO_TITLE=1

# Preserve test output packages under /tmp/scripps-*-latest symlinks so you
# can inspect them after `make ivd*` runs.
# KEEP_PACKAGE=1

# Iteration cap for `make ivd-execute`. Default: 30.
# MAX_ITER=30

# Fixture-runner latency budget (ms). `make latency-baseline` gates on this.
# Default: 8000.
# ECAA_FIXTURE_TIMEOUT_MS=8000

# Port for `scripts/test-ivd-web-execute.sh`. Default: 3737.
# ECAA_TEST_PORT=3737

# Enable Playwright live-API tier. `=1` boots the real server + UI and runs
# every `e2e/tests/live/**` spec; otherwise those specs skip. Also requires
# ECAA_ANTHROPIC_API_KEY. See e2e/playwright.config.ts.
# PLAYWRIGHT_LIVE=1

# Attach the `ivd-observer.live.spec.ts` Playwright spec to an existing
# session rather than creating a fresh one. Used to watch a long-running
# lotz calibration in-flight without restarting intake.
# ECAA_OBSERVE_SESSION=abcd-1234-ef56

# SME backend selector for live Playwright specs
# (e2e/helpers/smeBackend.ts + ivd-full-lifecycle-headed.live.spec.ts).
#   scripted — fixture-driven (default; no API key needed)
#   fm       — Anthropic-backed FM SME (requires ECAA_ANTHROPIC_API_KEY
#              or legacy ANTHROPIC_API_KEY)
# ECAA_SPEC_SME_MODE=fm

# e2e supervisor harness (e2e/supervisor.mjs) inputs. The supervisor
# wraps a live Playwright run with a safety gate that refuses to
# auto-advance unless explicitly told to.
#   ECAA_SUPERVISOR_SESSION_ID  target session UUID         (required)
#   ECAA_SUPERVISOR_PKG_DIR     emitted package directory   (required)
#   ECAA_SUPERVISOR_OUT_DIR     supervisor output directory (required)
#   ECAA_SUPERVISOR_BASE_URL    chat-server URL             (default http://127.0.0.1:3737)
#   ECAA_SUPERVISOR_FORCE_AUTO  skip safety gate (=1; DESTRUCTIVE)
# ECAA_SUPERVISOR_SESSION_ID=
# ECAA_SUPERVISOR_PKG_DIR=
# ECAA_SUPERVISOR_OUT_DIR=
# ECAA_SUPERVISOR_BASE_URL=http://127.0.0.1:3737
# ECAA_SUPERVISOR_FORCE_AUTO=1

# Probe output directory for e2e/dark-mode-drawer-probe.mjs. The
# baked-in default is an alan-specific path
# (/home/a/mounts/wadmin/home/a/ecaa-e2e-results/dark-mode-drawer-probe)
# — set this when running on any other host.
# ECAA_PROBE_OUT_DIR=/tmp/ecaa-dark-mode-probe

# Mock-agent fixture knob. When `true`, scripts/agent-mock-blocker.sh
# forces a discover_* task to Blocked so the fixture-runner tests the
# blocker path without touching real data. Test-only — do not set in
# production.
# ECAA_MOCK_DISCOVERY_BLOCK=true

# Scripted-iteration budget for the dry-run MockExecutor when the harness is
# built with the `dry-run` feature. Test-only.
# ECAA_MOCK_TASK_BUDGET=100

# Ignored local smoke for claim verification against a real emitted package.
# Test-only; run manually with `cargo test -p ecaa-workflow-server
# real_package_smoke -- --ignored`.
# ECAA_REAL_PKG=/path/to/emitted/package

# =============================================================================
# Plotting library overrides
# =============================================================================
# Override the path to the shared Python plotting library (lib/plotting/).
# The emitter normally walks up from CWD looking for lib/plotting/core.py;
# set this when running outside the repo checkout.
# ECAA_PLOTTING_LIB=/opt/scripps/lib/plotting

# Analogous override for the R plotting library used by R-renderer atoms.
# ECAA_PLOTTING_R_LIB=/opt/scripps/lib/plotting-r

# Pinned R version surfaced into emitted plotting tasks. Mirrored by the
# plotting_version_sync test gate. Default: tracked in core::emitter.
# ECAA_PLOTTING_R_VERSION=4.4.1

# Override the default plot-preset id when emitting figure-resolver
# scaffolds. Consumed by the plotting smoke harness only.
# ECAA_PLOT_PRESET=default

# =============================================================================
# Telemetry / OpenTelemetry
# =============================================================================
# tracing_subscriber output format. json emits structured logs the
# collector picks up directly. Default: text.
# ECAA_LOG_FORMAT=json

# =============================================================================
# Dev sandbox paths (Makefile-driven `make dev-*` targets)
# =============================================================================
# The Make `dev-*` targets point the chat server at separate session/
# upload/package roots so a dev run doesn't trample production session
# data on the same machine.
# ECAA_DEV_STORAGE_ROOT=$HOME/.scripps-dev
# ECAA_DEV_SESSIONS_DIR=$HOME/.scripps-dev/sessions
# ECAA_DEV_UPLOAD_ROOT=$HOME/.scripps-dev/uploads
# ECAA_DEV_PACKAGE_ROOT=$HOME/.scripps-dev/packages
# ECAA_DEV_AGENT_CACHE_DIR=$HOME/.scripps-dev/agent-cache
# ECAA_DEV_AGENT_SCRATCH_DIR=$HOME/.scripps-dev/agent-scratch
# ECAA_SESSION_CACHE_DIR=$HOME/.scripps-dev/session-cache

# =============================================================================
# Doc-gate + repo hygiene
# =============================================================================
# When 1, local documentation gates exit non-zero on drift (every user-facing
# ECAA_* in source must be documented here or in CLAUDE.md). Default 0
# (warn-only).
# ECAA_DOC_GATE_STRICT=1

# Scope selector for scripts/check_repo_hygiene.sh. Default: full.
# ECAA_HYGIENE_SCOPE=quick

# Drift-mode for scripts/check-modality-manifest-drift.sh. Default warn;
# CI flips to fail once the legacy keyword file is deleted (planned per A.S5).
# ECAA_MODALITY_DRIFT_MODE=fail

# Developer doc/fixture gates. Default warn/soft; set to 1 locally when
# refreshing plot fixtures or workflow-stranding checks.
# ECAA_PLOT_SMOKE_STRICT=1
# ECAA_STRANDED_NODES_STRICT=1

# ECAA emit-time schema validation. When 1, crates/conversation/src/emit/
# validation.rs returns Err on any ECAA-sidecar schema-validation failure,
# propagating through emit_package to fail the calling test or request.
# When unset / 0, validation runs and reports but mismatches are warn-only
# (production default). There is no GitHub CI in this OSS repo; instead the
# `make conformance` target — run by the installed pre-push hook — sets this
# to 1, so schema drift fails the local gate instead of landing silently.
# Production deployments leave it unset so a single drifted package never
# blocks an SME's session — the validation report is still written for review.
# ECAA_VALIDATION_BLOCK_ON_FAIL=1

# =============================================================================
# Local enforcement gate (pre-push hook) — no GitHub CI in this OSS repo
# =============================================================================
# scripts/hooks/pre-push (installed via `make install-hooks`) is the REAL gate:
# it runs `make lint` + `make test` + `make conformance` and aborts the push on
# any failure. `make conformance` runs the ECAA conformance suite block-on-fail
# (it sets ECAA_CONFORMANCE_MODE=1 + ECAA_VALIDATION_BLOCK_ON_FAIL=1 inline).
#
# Emergency opt-out: skip the slow `make test` + `make conformance` stages
# (`make lint` still always runs). Use only when you know what you are doing.
# ECAA_SKIP_PREPUSH_TESTS=1
#
# Force ECAA conformance/validation to block-on-fail. Normally set inline by
# `make conformance`; do NOT export globally or every plain emit starts
# blocking. Documented here for reference.
# ECAA_CONFORMANCE_MODE=1
#
# Opt-out for the CLAUDE.md-as-contract doc gates (documented_constants.rs). When
# CLAUDE.md is ABSENT (the default in a fresh OSS clone), the doc-contract gates now
# HARD-FAIL instead of silently passing — set this to 1|true|yes|on to turn that into
# a loud skip for OSS clones that legitimately ship without the internal CLAUDE.md.
# ECAA_ALLOW_MISSING_CLAUDE_MD=1

# =============================================================================
# Evaluation / benchmarking — scripts/eval/ (Python harness)
# =============================================================================
# The canonical value-add eval is the Python harness under scripts/eval/
# (BiomniBench-DA + Nekrutenko mtDNA; arms: ecaa vs claude-direct; Gemini judge).
# None of these are read by the production server. NOTE: the legacy
# crates/eval-baselines / crates/eval-adapters crates were removed in the OSS
# slim-down; the vars below are retained only where the Python harness still
# reads them — see the "scripts/eval harness (Python)" block lower down for the
# authoritative, code-verified list.

# Output roots.
# ECAA_EVAL_RUNS_DIR=$HOME/.ecaa-workflow/eval/runs
# ECAA_EVAL_CACHE_DIR=$HOME/.ecaa-workflow/eval/cache
# ECAA_METRICS_SNAPSHOT_DIR=$HOME/.ecaa-workflow/eval/metrics-snapshots
# ECAA_SCORECARDS_DIR=runtime/scorecards

# Eval harness tuning.
# ECAA_EVAL_MAX_TASKS=100
# ECAA_EVAL_THROTTLE_BACKOFF_SECS=2

# Benchmark / external corpora.
# ECAA_BENCHMARK_DATA_DIR=$HOME/.ecaa-workflow/eval/benchmark-data
# ECAA_BIOMNI_PYTHON=/opt/biomni/bin/python
# ECAA_LONG_ARC_PACKAGE_DIR=$HOME/.scripps-eval/long-arc-packages
# ECAA_PACKAGE_DIR=$HOME/.scripps-eval/inspect-package

# Per-tier live-API gates + cost caps. =1 routes through live APIs;
# unset = use mock fixtures.
# ECAA_BUCKET_A_LIVE=1
# ECAA_BUCKET_A_COST_CAP_USD=10
# ECAA_BUCKET_A_DOCS_BASELINE=baseline-id
# ECAA_TIER_2_5_REAL_AGENT=1
# ECAA_TIER_7_4_HARNESS_RUNS=3
# ECAA_TIER_17_3_LIVE=1
# ECAA_TIER_17_3_PORT=19173
# ECAA_TIER_19_1_LIVE=1
# ECAA_TIER_19_2_LIVE=1
# ECAA_TIER_19_3_LIVE=1

# Live-mode gates for external-eval smoke wrappers
# (scripts/smoke-biomni.sh, scripts/smoke-biomedagent.sh). Default off
# — the runners emit RunnerSkipped without these.
# ECAA_BIOMNI_LIVE=1
# ECAA_BIOMEDAGENT_LIVE=1

# Biomni smoke-test input/output paths.
# ECAA_BIOMNI_SMOKE_INTAKE=testdata/wrroc-fixtures/01-encode-ctcf-k562/intake.json
# ECAA_BIOMNI_SMOKE_OUT=runtime/smoke-biomni

# Modality-stratum YAML override for eval-baselines.
# ECAA_STRATA_YAML=/path/to/custom-strata.yaml

# Backend selector for eval-baselines runners
# (legacy adapter compatibility). Set per-arm by the harness; accepted
# values: biomni, biomedagent, scripps. Do not normally set in a shell.
# ECAA_AGENT_BACKEND=biomni

# Eval-only schema-gate ungating. Honored only when ECAA_EVAL_LIVE=1 is also
# set; inert otherwise.
# ECAA_EVAL_UNGATE_SCHEMA_GATE=1

# Emit a warning row in scripts/audit-emitted-dag.py output when ECAA
# sidecars fail their schema checks. Independent from
# ECAA_VALIDATE_ON_EMIT (which runs at emit time inside the server).
# ECAA_VALIDATE_ECAA=1

# Determinism harness overrides.
# ECAA_DETERMINISM_BIN=/path/to/custom-differ
# ECAA_DETERMINISM_LIVE=1

# Nekrutenko fault-injection shim directory mounted into eval containers.
# Set by the eval harness; leave unset in production.
# ECAA_EVAL_SHIM_DIR=/abs/path/to/scripts/eval/_eval_shim

# Default-on. Set to 0 to disable the deterministic seed/locale envelope
# (PYTHONHASHSEED=0, SOURCE_DATE_EPOCH=<run-id-derived>, TZ=UTC,
# LANG=C.UTF-8, LC_ALL=C.UTF-8) that the harness stamps onto each task's
# container env. Values derive deterministically from the stamped
# ECAA_HARNESS_RUN_ID/ECAA_DISPATCH_EPOCH — never wall-clock.
# ECAA_DETERMINISM_SEEDS=1

# Aggregator debug.
# ECAA_AGGREGATE_DEBUG=1

# ── scripts/eval harness (Python) — code-verified env vars (scripts/eval/) ───
# Live-API gate: unset/≠1 = offline SKIP; =1 runs the real agent + real judge
# (also requires GEMINI_API_KEY + ECAA_ANTHROPIC_API_KEY). (eval_runner.py:308)
# ECAA_EVAL_LIVE=1
# BiomniBench judge key — judge.py hard-requires it in live mode; no default.
# GEMINI_API_KEY=
# Optional Hugging Face token for gated BiomniBench dataset pulls (datasets.py).
# HF_TOKEN=
# Output / cache / scratch roots (datasets.py; module-internal defaults if unset).
# ECAA_EVAL_RUNS_DIR=$HOME/.ecaa-workflow/eval/runs
# ECAA_EVAL_CACHE_DIR=$HOME/.ecaa-workflow/eval/cache
# ECAA_EVAL_SCRATCH_DIR=$HOME/.ecaa-workflow/eval/scratch
# Keep per-run package scratch for post-mortem (default: cleaned). (eval_runner.py:351)
# ECAA_EVAL_KEEP_SCRATCH=1
# Agent model BOTH arms run; default claude-sonnet-4-6. (agent_runner.py:30)
# ECAA_EVAL_MODEL=claude-sonnet-4-6
# Per-task / per-harness wall-clock ceilings in seconds; defaults 600 / 7200.
# ECAA_EVAL_TASK_TIMEOUT=600
# ECAA_EVAL_HARNESS_TIMEOUT=7200      # both arms now read this ceiling (H2 timeout parity)
# Narrative-augmentation toggle. Default 0 = OFF so scored runs feed BOTH arms the
# same RAW narrative (the ECAA-only structured-claims block is augmentation the bare
# arm cannot get — H1 fairness). =1 re-enables it for diagnostics only. (flatten.py)
# ECAA_EVAL_NARRATIVE_AUGMENT=0
# Relaunch-budget opt-in. Default OFF pins ECAA_EVAL_MAX_RELAUNCH to 0 for scored runs
# (H2: the bare arm has no relaunch loop). =1 honors ECAA_EVAL_MAX_RELAUNCH for
# diagnostics. (agent_runner.py)
# ECAA_EVAL_ALLOW_RELAUNCH=0
# Execution caps: BOTH arms run UNCAPPED in the same bio-min container (canonical
# eval) so the ecaa-vs-bare delta isolates the scaffolding, not a resource gap.
# ECAA-arm intake path: "chat" (default, server chat-intake) or "cli" (no-LLM). (eval_runner.py:175)
# ECAA_EVAL_INTAKE=chat
# Override the bare-arm agent script (default scripts/eval/_bare_agent.sh).
# ECAA_EVAL_BARE_AGENT_SCRIPT=
# Gemini judge batches at/above this request count; default 16. (judge.py:458)
# ECAA_EVAL_JUDGE_BATCH_MIN=16
# Nekrutenko PATH-shim fault injection (error-matrix cells) — set by the runner,
# not by hand: EVAL_INJECT_PATTERN / EVAL_INJECT_TARGET / EVAL_INJECT_STATE /
# EVAL_REAL_BIN_DIR / EVAL_SLOW_SECONDS (scripts/eval/_eval_shim/shim.py).
#
# SME-gate bypass (harness — crates/harness/src/sme_skip.rs). DANGER: =1
# bypasses EVERY SME gate — the discovery review gate AND the silent-completion,
# missing-artifact, and claim-verification correctness guards. The eval no
# longer sets this: it now auto-clears ONLY the discovery review gate and keeps
# the correctness guards active and SCORED. Leave UNSET for evals and normal
# runs; set only for operator debugging.
# ECAA_SME_AUTO_APPROVE_ALL=1

# =============================================================================
# ECAA emit-time validation
# =============================================================================
# `ecaa-workflow-audit-proof --secret` fallback for signing the audit-proof
# verdict sink. Must be a 64-hex-character secret. Never set in a shared
# committed env file.
# ECAA_AUDIT_SECRET=

# After every successful emit, crates/conversation/src/emit/validation.rs
# runs the configured validators against the just-emitted ECAA sidecars
# and writes results to `runtime/validation-summary.json`. Warn-only by
# default — a validation failure does NOT block the emit.
#
# Production default (unset or schema_only): pure-Rust JSON Schema (draft-07)
# validation of the 8 sidecars. No Python runtime dep. Fast (~ms).
#
# `full` adds external Python validators:
#   - SHACL via pyshacl
#   - OWL DL satisfiability via HermiT (owlready2)
#   - runcrate validate (WRROC v0.5 round-trip)
# Each gracefully degrades to "Unavailable" if its deps aren't installed.
# Install once: pip install --user --break-system-packages pyshacl pyld owlready2 rdflib jsonschema runcrate
#
# ECAA_VALIDATE_ON_EMIT=full
# ECAA_VALIDATE_ON_EMIT=schema_only   # default
# ECAA_VALIDATE_ON_EMIT=off           # escape hatch — skip all validation

# Override scripts/spec-check/ location if running from a non-default layout.
# ECAA_SPEC_SCRIPTS_DIR=/abs/path/to/ecaa-workflow/scripts/spec-check

# ECAA_FRESH_EXECUTED_CRATE_OUT — test/debug only. When set, the provenance
# integration test (crates/core/tests/provenance/fresh_executed_crate.rs) dumps
# the finalized RO-Crate it builds to this path BEFORE running its in-process
# structural assertions, so an out-of-process SHACL validator can be pointed at
# the same crate. Unset in normal operation.
# ECAA_FRESH_EXECUTED_CRATE_OUT=/abs/path/to/crate-dump-dir

# Per-validator subprocess wall-clock cap (seconds; default 120). Under
# ECAA_VALIDATE_ON_EMIT=full + ECAA_CONFORMANCE_MODE the external SHACL/OWL
# Python validators run during emit; this bounds them so a hung pyshacl/HermiT
# can never wedge emit_package (a timeout is recorded non-blockingly as
# `unavailable`). The two validators also run concurrently.
# ECAA_VALIDATOR_TIMEOUT_SECS=120

# Content-addressed cache for the external SHACL/OWL validators (OPT-IN). When
# set, scripts/spec-check/{project_package,owl_consistency}.py memoize their
# verdict keyed by a blank-node-invariant digest of the package ABox + content
# hashes of the static ontology/shapes — so an IDENTICAL re-validation (CI
# fixture re-runs, re-emit/amendment, repeated emits of the same package)
# replays the cached verdict and skips the ~0.8s pyshacl run / ~1s HermiT pass
# (measured ~1.4s -> ~0.45s per validator on a hit). Unset (default) = always
# re-reason. The key invalidates automatically when the ontology, shapes, or
# package change.
# ECAA_SPEC_CACHE_DIR=/abs/path/to/.ecaa-spec-cache

# Block emit on schema-validation failure (default warn-only).
# Useful for strict CI gates where a malformed sidecar should fail loudly.
# ECAA_VALIDATION_BLOCK_ON_FAIL=1

# Per-subprocess timeout for external Python validators (default 180s).
# ECAA_VALIDATION_EXTERNAL_TIMEOUT_SECS=180

# Interpreter used to run the external SHACL/OWL validator scripts under
# scripts/spec-check/ (default `python3` from PATH). Point it at the interpreter
# whose environment actually has pyshacl + owlrl installed. The server image
# ships them in a dedicated venv, so a containerized deployment sets this to
# that venv's interpreter rather than relying on the base image's python3 —
# otherwise `ECAA_VALIDATE_ON_EMIT=full` degrades to schema-only with the
# external checks recorded as unavailable.
# ECAA_VALIDATION_PYTHON=/opt/validator-venv/bin/python3

# =============================================================================
# Ablation flags (Aim 3A Arm B′ — eval harness only, never in production)
# =============================================================================
# Each flag downgrades a single ECAA capability so the eval harness can
# measure its independent contribution. AblationFlag::all_flags()
# returns the canonical 6.
# ECAA_ABLATE_DECISION_RECORDS=1     # skip runtime/decisions.jsonl
# ECAA_ABLATE_AMENDMENT_PROVENANCE=1 # omit prov:wasDerivedFrom edges
# ECAA_ABLATE_CLAIM_CONSISTENCY=1    # skip runtime/claim-verification.json
# ECAA_ABLATE_TYPED_BLOCKERS=1       # downgrade typed blockers to generic
# ECAA_ABLATE_REEXECUTION_CLASS=1    # skip reexecution / determinism tracking
# ECAA_ABLATE_AUDIT_PROOF=1          # skip audit-proof-report emission
#
# There is no separate ECAA mode switch in v0.2. These ablation flags are the
# only code-backed way to emit non-conformant ECAA control artifacts.

# =============================================================================
# Harness watchdog + output guards
# =============================================================================
# Wall-clock watchdog that fires BlockerKind::TimeExceeded when a task
# runs longer than expected_wall_seconds × multiplier.

# Watchdog polling cadence (seconds). Default tracked in
# crates/harness/src/constants.rs; out-of-range values are clamped with
# a stderr warning.
# ECAA_WATCHDOG_PERIOD_SECS=30

# Per-task wall-clock multiplier. Default ~6× (tracked in constants.rs).
# A task expected to run for 60s is killed at 60×multiplier seconds.
# ECAA_WATCHDOG_MULTIPLIER=6.0

# Per-task output-directory size ceiling (MB). Unset = no cap; set a
# positive value to refuse dispatch of tasks whose accumulated outputs
# exceed the cap (surfaces as BlockerKind::OutputSizeExceeded).
# ECAA_TASK_OUTPUT_MAX_MB=10240

# Per-file size guard for ecaa:// transport reads (MB). Default 100.
# ECAA_AGENT_FILE_MAX_MB=100

# Maximum tolerated clock skew between harness and agent host (seconds).
# Default 60. On breach the harness refuses dispatch and surfaces
# BlockerKind::ClockSkewExceeded.
# ECAA_CLOCK_SKEW_THRESHOLD_SECS=60

# Internal: harness sets this to 1 when re-running a task for
# determinism validation. Do not set manually.
# ECAA_DETERMINISM_RERUN=1

# =============================================================================
# Renderer-validator (Stage 12 — harness-set)
# =============================================================================
# Populated by crates/harness/src/renderer_validators.rs at dispatch
# time when an atom carries a renderer_module output. The harness
# exports them onto the validator subprocess and the bwrap allowlist
# threads them through. Do not set in your shell.
#   ECAA_RENDERER_MODULE  — Python module name (e.g. lib.plotting.stages.heatmap)
#   ECAA_RENDERER_OUT_DIR — output directory for renderer-validator scratch

# =============================================================================
# Runtime-set vars (populated by harness / server — DO NOT set manually)
# =============================================================================
# These are exported onto subprocess environments at dispatch time. Any
# shell-level value is silently overwritten on the next dispatch; only
# set them when reproducing a specific dispatch in isolation.
#
#   ECAA_TASK_ID                  — current task identity
#   ECAA_TASK_SCRATCH_DIR         — per-task scratch root visible to agent
#   ECAA_TASK_NETWORK             — per-task network policy (bridge | none)
#   ECAA_HARNESS_RUN_ID           — dispatch identity for WAL + heartbeat
#   ECAA_DISPATCH_EPOCH           — dispatch epoch timestamp
#   ECAA_HARNESS_BIN              — resolved harness binary path
#   ECAA_SERVER_BIN               — resolved server binary path
#   ECAA_SESSION_ID               — chat session identifier
#   ECAA_CHAT_SESSION_ID          — alias for ECAA_SESSION_ID (legacy)
#   ECAA_PACKAGE_ID               — currently-emitted package identifier
#   ECAA_S3_PACKAGE_URI           — S3 package rsync source (AWS)
#   ECAA_S3_OUTPUT_URI            — S3 output rsync destination (AWS)
#   ECAA_AWS_INSTANCE_ID          — EC2 instance ID (AWS)
#   ECAA_GIT_SHA                  — workspace SHA propagated into dispatch
#   ECAA_REMEDIATION_RATIONALE    — server-set rationale for retry/remediation
#   ECAA_HW_VCPUS_AVAILABLE       — per-agent CPU budget
#   ECAA_HW_MEMORY_GB             — per-agent memory budget
#   ECAA_HW_GPU                   — GPU envelope JSON
#   ECAA_HW_GPU_CAPABILITY_REF    — CUDA capability reference
#   ECAA_HW_RECOMMENDED_THREADS   — recommended thread count
#   ECAA_HW_TOOL_THREAD_CURVES    — tool → thread-curve coefficients
#   ECAA_HW_TASK_RESOURCE_CLASS   — resource-class label
#   ECAA_HW_CONCURRENT_PEERS_BY_CLASS — map of class → peer count
#   ECAA_HW_INTAKE_FACTS          — frozen intake facts for adaptive parallelism
#   ECAA_HW_ENV_OVERRIDES         — force-set BLAS/OpenMP env vars
#   ECAA_PY                       — canonical Python interpreter selected by agent wrappers

# =============================================================================
# External integrations
# =============================================================================
# Hugging Face hub token. Required only when tasks declare a Hugging
# Face dataset/model in runtime_prereqs. Read by data_fetch.rs,
# biomystery/data.rs, and external/hf_fetcher.rs. Never logged.
# HF_TOKEN=hf_...

# Alternate name read by crates/eval-adapters/src/external/hf_fetcher.rs
# as a fallback when HF_TOKEN is unset. Pick one — setting both is
# redundant; HF_TOKEN takes precedence.
# HUGGINGFACE_TOKEN=hf_...

# Google Gemini API key. Required by the eval-adapters BiomniBench
# judge (crates/eval-adapters/src/external/judge.rs) which uses
# Gemini 3.1 Pro for rubric scoring. The eval harness skips judging
# when unset. Never logged.
# GEMINI_API_KEY=

# Cargo build artifact root. Redirect off the system disk when home is
# space-constrained.
# CARGO_TARGET_DIR=$HOME/.cargo-target

# XDG state directory. Read by the upload route as a fallback for the
# upload root when ECAA_UPLOAD_ROOT is unset and $HOME is also missing.
# Standard XDG variable; most systems leave it unset.
# XDG_STATE_HOME=$HOME/.local/state

# =============================================================================
# Nekrutenko depth-eval (crates/eval-adapters/src/bin/eval-runner.rs)
# =============================================================================
# Selects modality for the 21-modality Nekrutenko depth-eval matrix.
# REQUIRED — the binary errors out with "NEKRUTENKO_MODALITY must be
# set for this suite" when unset.
# NEKRUTENKO_MODALITY=bulk-rnaseq

# Optional subset overrides forwarded onto the spawned adapter
# subprocess by apply_nekrutenko_subset_env in eval-runner.rs. Leave
# unset to run the full matrix.
# NEKRUTENKO_LEVELS=Track-B,v1g,v1.5
# NEKRUTENKO_PATTERNS=PATH-shim,missing-ref
# NEKRUTENKO_SEEDS=1,2,3

# =============================================================================
# Schema regeneration (developer-only)
# =============================================================================
# Regenerate JSON schemas in crates/conversation/tests/schemars_generation.rs
# instead of asserting against the committed schema. Set when a
# #[derive(JsonSchema)] struct changes and the test needs to write the
# new expected output to disk.
# SCHEMARS_REGEN=1

# =============================================================================
# Test / CI gates (developer-only — leave UNSET in production)
# =============================================================================
# Opt into the replay execute-tier integration test
# (crates/core/tests/provenance/replay_himes.rs), which re-executes the
# Himes fixture's deterministic compute and needs R/DESeq2 available. Unset
# by default so normal `cargo nextest` skips it; set =1 in a CI lane that
# provisions the compute environment.
# ECAA_REPLAY_EXEC_TEST=1

# Test-only: skip the /readyz writability probe's unwritable-dir assertion
# (crates/server/src/chat_routes/health.rs) so the health test can run in a
# sandbox where the probe path is not writable. Never set in production.
# ECAA_TEST_SKIP_READYZ_UNWRITABLE=1

# Locate the shared literature-contextualization library (`lib/literature/`)
# that `emit` copies into `<package>/runtime/literature/`. Honored before the
# walk-up search from CWD; point it at a checkout when emitting from outside
# the repo tree. Mirrors ECAA_PLOTTING_LIB / ECAA_PLOTTING_R_LIB.
# ECAA_LITERATURE_LIB=/path/to/lib/literature

# Override the bundled literature helper root used by relocated deposit
# scripts. Unset resolves to the deposit's own `lib/` directory.
# ECAA_LITERATURE_HELPER_DIR=/path/to/extracted/package/lib

# --- Relocated-deposit script contract (read by the EMITTED scripts, not by
# the compiler). `export` rewrites absolute host paths in a sealed package's
# task scripts into an env-indirection resolved relative to the script's own
# location, so an extracted deposit runs from any directory. Override them
# only to point a relocated deposit at a different tree.
# PKG_ROOT=/path/to/extracted/package
# ECAA_INPUT_0=/path/to/first/registered/input/root

# NOT environment variables — generated identifiers. `export`'s relocation
# prologue emits these as script-LOCAL variables inside the sealed R/Python
# task scripts (`.ECAA_SELF_DIR`, `_ECAA_DEPOSIT_ROOT`, `.ECAA_PKG_ROOT`) so a
# relocated deposit can resolve its own root from the script's location.
# Listed here only so the ECAA_* documentation gate can see them; setting them
# in the environment has no effect.
#   ECAA_SELF_DIR      — dir of the running script, computed at script start
#   ECAA_DEPOSIT_ROOT  — deposit root, walked up from ECAA_SELF_DIR
#   ECAA_PKG_ROOT      — package root the script binds its paths against