GLIMPSE2 continuation, caller compatibility, Docker and FFPE repair

Complete Illumina runs require bcftools 1.23.1 linked to HTSlib 1.24 in both
Conda and Docker. environments/native-variants.yml pins that pair and samtools
1.23.1. Both controller and workflow preflight report the selected executable
and linked-library version and reject mismatched or unreported versions before
analysis. Conda and Poetry installation create and verify a canonical managed
variant environment before saving installation settings. Managed Illumina setup
and runs select it and report replacement of stale variant_tool_prefix values.
Run oncotracer install --conda to repair an older installation. Docker users
rebuild/select the current image; installation checks its own variant toolchain.

The low-level traits helper still detects supported flags for compatibility
testing, but that does not authorize older callers for complete workflow runs.
Depth and genotype-quality gates remain: missing or low-confidence reference
evidence is never promoted to a call. ClinVar contig headers are repaired in a
separate cached resource before jobs.

Version/library changes invalidate incompatible variant tasks, including shared
reference preparation. The runtime records the linked bcftools HTSlib version;
a previous task without that information cannot certify the same runtime.
Existing outputs remain intact and each stage is checked again for reuse.

From a source checkout, open visual setup explicitly:

  python3 ./oncotracer --interactive --backend conda
  nextflow run ./main.nf --interactive --backend conda

Choose the sequencing platform, then Fresh or FFPE in the browser. The launch
commands are the same for both specimen types. Select a project, enable Small
variants when required, and review the settings before pressing Run analysis.
These entry points require an explicit interactive or configured run request.
For a saved configuration, run only after reviewing it:

  python3 ./oncotracer run --backend conda --config /path/to/project/config/run.yml
  nextflow run ./main.nf --analysis full --backend conda --config /path/to/project/config/run.yml

Add --dry-run to the Python command or --dry_run to the Nextflow command for
configuration validation. Complete variant execution additionally checks every
sample's continuation candidates before scheduling sample workflows, printing
the summary in the foreground terminal and browser job log.

Keep force: false. Retain work directories, completion receipts, runtime/code
snapshots and native state. Reuse requires compatible inputs, settings and code,
completed tasks and unchanged output metadata. Candidates also receive BAM/BCF/
VCF header, sample, BGZF-end and index checks, JSON parsing, and full gzip-report
CRC validation. Native ledger outputs check recorded hashes where available.
The BAM/BCF checks are structural checks, not a full byte-by-byte read of every
alignment or genotype. Failed, interrupted, incompatible and rejected tasks run
again. Some aggregate reports and conservatively gated downstream preparations
also run again. The summary lists retained task counts and rejected candidates;
zero rejected candidates does not mean every historical output was retained.

The bundled workflow treats --continue and native -resume as validated
continuation. Nextflow's existence-only task cache is disabled so it cannot
restore an output rejected by this gate. No old completion/ownership receipt is
rewritten to force acceptance. Changed native runtime identity still requires a
new output directory. An existing project may retain its authenticated native
runtime and select the repaired variant_workflow_source; native FFPE and other
controller repairs require the new runtime in a separate project.

Docker

The Dockerfile now includes the bundled workflow and pinned Nextflow 26.04.2,
including its framework jar for offline startup. Existing registry tags are not
changed by publishing this source repair. Build a new image and select its tag
in browser setup (or --image for a configured Python run):

  oncotracer_commit="$(git rev-parse HEAD)"
  oncotracer_source_sha256="$(git -c tar.umask=0002 archive --format=tar "$oncotracer_commit" | sha256sum | awk '{print $1}')"
  docker build --build-arg SOURCE_COMMIT="$oncotracer_commit" --build-arg SOURCE_SHA256="$oncotracer_source_sha256" -t oncotracer:glimpse2-repair .
  python3 ./oncotracer --interactive --backend docker
  nextflow run ./main.nf --interactive --backend docker

The image preflight checks its own scientific tools, local reporting model and
FFPE runtime when selected before alignment. Explicit workflow/resources and
model paths are mounted read-only; output and selected resource caches are
writable. Host tool prefixes are replaced by image tool prefixes in memory.
A host Conda project must not switch runtime into the same owned output tree.
Use a separate Docker project/output and review compatible imports explicitly.

FFPE

Open the same setup used for fresh specimens:

  oncotracer --interactive --backend conda
  python3 ./oncotracer --interactive --backend conda
  nextflow run ./main.nf --interactive --backend conda

Use --backend docker for Docker. These commands open browser setup; they do not
start analysis. Choose the sequencing platform, then FFPE in the browser. For
Illumina FFPE variant analysis, enable Small variants and supply the required
FFPErase resources. Choose inputs and a new project, then Save and check before
Run analysis. Selecting FFPE does not accept model licenses or start downloads.
No separate FFPE launcher or specimen flag is needed for browser setup.

The optional --ffpe preset remains supported only with --interactive. Terminal
setup records preservation with setup --terminal --variant-specimen-type ffpe.

The native command accepts --project, --input-folder, --image and the existing
--variant-ffperase-root/models/sif/prefix and --variant-tool-prefix options.
Nextflow accepts their underscore forms, such as --input_folder and
--variant_ffperase_models. Supplied values prefill the same browser form.

Choose FFPE specimen preservation and required FFPErase assessment in a new
project. Provide the pinned upstream source and both licensed model files.
For Conda/host use a compatible FFPErase environment prefix or a supported SIF
plus Apptainer. Docker uses its own FFPErase environment: clear any host SIF
selection and mount the source and models read-only. Model download still needs
the user's explicit license acknowledgement; locally supplied models need no
new download. Fresh samples retain fresh handling.

Preflight loads both models and predicts artificial feature rows. The actual
adapter keeps work directories writable even when input BAMs are beside them.
It computes measured depth without inflation: when the upstream log-depth
feature is undefined, assessment returns not_assessed and preserves the calls
with explicit NOT_EVALUATED evidence instead of assigning artifact certainty.

Validation included artificial paired reads through real SNP and indel pileup,
feature extraction and both random-forest models, with SIF on the Conda backend
and native environments in Docker. The 9x fixture completed; the 0.15x fixture
remained not_assessed. These smoke checks do not establish clinical accuracy or
constitute a patient FFPE cohort run. Reproduce with tests/run_ffpe_smoke.py and
user-supplied source/models/runtime, or tests/run_traits_compat_smoke.py with the
selected real bcftools and samtools. Standard regression tests run in native CI.