Changelog

User-visible changes to nf-claw, newest first, by pull request. Each release is a tag vX.Y.Z on main with release notes. Pipeline releases the maintenance workflows pin, bump or add are recorded in sources.tsv, the generated skill.md files and the git history, not here. Audit records, with the evidence behind each change, are in docs/audit/.

Unreleased

Changed

• The documentation is rewritten in plain language. The README, AGENTS.md, CONTRIBUTING.md, llms.txt, the website README and the guides in docs/ lose promotional wording, title-case labels, box diagrams and repetition; every fact, command and limit is kept. The README's quickstart links to AGENTS.md instead of repeating it, and its workflow diagram is now a table of each workflow's real triggers. On the website, "Pipeline universe" is now "Pipelines by domain" (#265).

[1.0.0] — 2026-11-08

The first release: the runner and the 95 pipeline pins at tag v1.0.0. Its release notes describe the library as a whole; the entries below are what changed after those notes were first drafted, on 2026-10-22.

Added

• nfclaw status --json and nfclaw chain status --json print one machine-readable object (state, outcome, times, pids, logs, caveats, recorded error, last output, and the human report) with the same exit codes; the MCP run_status tool returns it as run (#227).
• docs/replay.md: what a provenance bundle carries, the replay guard, dependency stability, resume of changed local inputs, and what nfclaw verify and nfclaw assess establish (#227).
• The website's search palette finds documentation sections by their headings, not only documents by title, and opens the page at the section; below the widest layout, a document opens with a folded table of contents (#227).
• nfclaw --version, nfclaw list <keywords>, run manifests that record which nfclaw ran them, and a security policy (SECURITY.md) (#218).
• An accessibility check of every website page in the browser tests (#219).
• MCP read_doc(guide, search): an nf-claw guide, or only its sections that hold every word searched. Agents checking a warning against known-issues (about 120 KB) get its section (under 1 KB); the server's instructions now say so (#234).
• nfclaw jobs list, nfclaw jobs status and nfclaw jobs cancel manage MCP's persisted jobs from a shell, with shared reports, bounded output tails and versioned --json responses (#238).

Changed

• The documentation was checked against the code and reorganized for release: the README leads with what nf-claw does and groups its guides by purpose, docs/known-issues.md and docs/mcp.md are arranged by topic, docs/audit/ has an index, and contributors have documentation conventions. Corrected: the verdict an unexpected preview timeout gets, releases still called pinned after a bump, the validation dates, and the generation matrix's evidence for five bumped pins. Tests now check every relative link and anchor, the guide listings and the MCP tool table (#258).
• AGENTS.md, which every agent session loads, is half its size (45 KB → 24 KB): it keeps every operating instruction and links the guarantees behind them to focused guides (#227).
• Inputs and outputs are hashed several files at once (up to eight threads): one core hashed 314 MB/s on the validation server, eight threads 7.7× faster on cached data (#227).
• nfclaw run and nfclaw chain run refuse a Python without POSIX file locks (native Windows) instead of running without their writer locks; use WSL 2 there (#227).
• Both maintenance bots hand their frozen candidate to one shared gate and publisher (maintenance-gate.yml) instead of repeating its jobs (#235).
• Generated parameter tables write patterns, defaults and allowed values as code spans, so they render as the values nf-schema enforces (#219).
• Each CI test lane runs the complete suite on all of its runner's cores (pytest -n auto --dist worksteal, pytest-xdist in the dev extra) and still reports every case; the suite ran one test at a time for 16–34 minutes a lane. On the validation server, four workers took 9 minutes instead of 29 (#234).
• A new push to a pull request cancels that pull request's previous, now superseded CI run; it had stayed queued for hours behind the macOS runners. Runs for main, schedules, dispatches and the maintenance gate are never cancelled (#234).
• The smoke workflow checks each pin's demo on the engine its skill.md advises, which now also has that engine parse the configuration, and reports beside it — without failing — which pins the launcher's default Nextflow refuses when no --nxf-ver is given (#248).

Fixed

• A built wheel lists runner.output_contracts as a package, so it keeps the two output contracts without relying on a setuptools fallback that warned they "would be ignored" (#260).
• A failed run's error, and nfclaw status, quote an exception Nextflow printed without ERROR ~ (hgtseq 1.1.0's intermittent Cannot invoke "java.util.Map.get(Object)" because "self" is null); they used to quote only nf-core's Pipeline completed with errors banner below it. (#259)
• --resume after a nfclaw that vanished (SIGKILL, out of memory, a host restart) or could not write its bundle (a full disk) reuses the finished tasks. A launch now records what it consumes before Nextflow starts; it used to recompute every task, while nfclaw status and the full-disk error promised otherwise. A killed replay is no longer told to --resume. (#257)
• A documented --outdir results run leaves the checkout clean: its writer lock, replay and the previous run --resume preserves are ignored by Git. (#257)
• --check, or a run, with a large existing directory as --outdir no longer walks all of it looking for links into the inputs (--outdir / never finished): a run refuses a non-empty directory without --resume anyway. (#257)
• --check names a profile the release does not define, instead of suggesting another engine. (#257)
• A run whose task records are gone, because a config set cleanup = true, now warns that no container was identified or pinned for its replay, instead of recording no gap. (#257)
• --check on a host that cannot fetch a release's remote configuration says so and names the network remedies, instead of suggesting another engine and parser. (#257)
• A Fast5 directory in a bacass 2.7.0 samplesheet is part of the run's input identity again: the bump had changed the schema its audited roles are keyed by. (#257)
• python3 -m runner on a Python older than 3.11 names the Python it needs instead of an ImportError; a ~ naming no user, or a report a terminal's encoding cannot show, is no traceback. (#257)
• provenance: warnings about gaps in a run's recorded environment reached only stderr, which a background run usually loses. They are now also in the run log, and nfclaw status lists them under provenance gaps (provenance_gaps with --json), and nfclaw chain status beside each stage. A task that ran with no container now counts as such a gap. (#257)
• A stop while the container engine is still creating a task container removes it once it appears, instead of leaving it behind, never started. nfclaw waits up to 30 s; one that takes longer is named on stderr and in the run log, with how to find and remove it. The group is looked through throughout the stop, so a client that started as the stop began is covered too. A container its task wrapper is already removing is no longer reported as one that could not be removed. (#257)
• Python bytecode caches that tasks write into the pipeline source (bin/__pycache__ in circdna, reportho and viralmetagenome) no longer fail a successful run or its archived replay as a source change, and symlink modes are recorded portably so a macOS bundle replays from its archive on Linux. A previous run whose live Nextflow, nfclaw or replay process cannot be identified is no longer moved aside by --resume. A slow process inventory no longer stops a foreground MCP command; foreground output redacts inherited NXF_* secrets as job views do (#252).
• A stop that arrives while a metadata probe is being launched no longer leaves its helpers running: the probe's process group is cleaned up however early the signal lands (#256).
• New ordinary runs authenticate source permissions, links, empty directories and untracked/ignored source files as well as bytes. Source archives preserve that identity. Resume preserves the old run and recomputes when complete source identity changed or was never recorded; unchanged source keeps normal cache reuse. Legacy bundles retain their original evidence scope (#249).
• Redact sensitive environment values from shell/MCP job reports and keep execution records private. Stop foreground MCP descendants on timeout or cancellation; recover and safely cancel commands that survive a killed job supervisor. Reserve MCP control workers and bound slow-work admission. Offline release listings retain and label the committed pipeline pin (#249).
• Apply supported scalar, required-field, relationship and uniqueness checks to flat JSON/YAML samplesheets as well as CSV/TSV. Report unreadable process identities as unknown, and unreadable task-container inventories as unconfirmed cleanup (#249).
• Distinguish macOS zombie-only process groups from genuine signal permission failures during replay and metadata cleanup; retain failure when live members or unreadable inventory remain (#249).
• Foreground MCP work reports unconfirmed cleanup if process inspection becomes unreadable after launch or an authenticated descendant survives; a successful command cannot hide that outcome (#249).
• Resolve verified current-product audit findings in process cancellation, completion caveats, environment attribution/deadlines, scientific validity/reference handoffs, private frozen-stage identity, website navigation/guidance/static counts, manifest parsing and MCP/job error handling (#247). Evidence and limitations: follow-through audit.
• A run whose pinned release Nextflow 26.04+'s strict parser rejects (methylseq 4.2.0, atacseq 2.1.2, viralrecon 3.0.0 among the pins) fails with the fix that works — the legacy parser, --nxf-env NXF_SYNTAX_PARSER=v1, or --nxf-ver 25.10.4 — instead of "re-run the same command with --resume", which cannot get past a configuration that does not compile; nfclaw chain run names the legacy parser too (#246).
• nfclaw run --check (and MCP run_pipeline(check=true)) asks the run's engine to parse the release's configuration, as nfclaw chain run --check already did for each stage: a pin the engine rejects is refused with its remedy before anything launches, instead of passing the check and failing at launch; its preflight lines report profile_config as checked (#248).
• Samplesheet integer and number cells written with digit separators (1_000) are refused before launch: the check accepted them, and nf-schema's Groovy casts then rejected the sheet at launch (#248).
• nfclaw chain status reports a chain still running on another host as unknown here, naming that host, as nfclaw status does for a run, instead of running with exit status 1 (#248).
• A run closes the container-events pipe it follows, a replay its console pipe, and nfclaw assess its record database; Python reported each as an unclosed resource (#248).
• The website renders a link in a parameter description (upstream schema text) only to a relative, web or mail target; any other scheme is shown as its label (#248).
• The website's search palette finds a long heading by words near its end (major version 61 finds its Java 17 known issue); such a match ranked below zero and was dropped (#248).
• The website words a workflow schedule only when it can word it correctly (a step, range or list is shown as written), groups the release timeline by UTC month as it labels it, and steps back to the last pipeline in the constellation from no selection (#248).
• The package metadata declares its MIT licence and ships LICENSE and NOTICE; building it needs setuptools 77 or newer (#248).
• --limit-memory and --limit-time (and a chain's limits) accept only spellings Nextflow parses. 1.5.TB, 100.B, 15.gb, 5.secs, 5.mins or 1.H passed the check and the run then died at its first task (Caused by: multiple points), in a chain after every earlier stage had run (#246).
• A job refused before launch into a fresh --outdir (an invalid parameter, a missing samplesheet) no longer reports "could not freeze this job's run status: FileNotFoundError" beside the real refusal in get_job and nfclaw jobs status; nfclaw jobs status names shell commands (nfclaw status <outdir>, --resume) instead of MCP tools and fields (#246).
• show_pipeline(grep=…) reads a # comment inside a code block as code: every skill.md's # raw equivalent … line can be found, and no longer relabels the lines after it (#246).
• Release tags are read whole from git ls-remote by nfclaw versions, --pipeline-version and the update bot: a tag such as release/9.9.9 is no longer mistaken for the release 9.9.9 (#246).
• Job records live in one absolute place: a relative XDG_STATE_HOME is ignored, as the XDG specification requires, and a relative NFCLAW_STATE_DIR is resolved where it is read (#246).
• docs/replay.md states the replay host's real requirement, Python 3.9 or newer as python3; a test keeps the bundled scripts within it (#246).
• A --resume that preserves the previous run in a sibling archive no longer leaves the new run directory private to the user who resumed it (0700): it keeps the permissions of the run it replaces (#235).
• Provenance bundle files are created like the rest of a run's files (0666 less the umask) instead of 0600, so the group a run's results are shared with can verify and replay it (#235).
• MCP refuses a tool or prompt call whose arguments is given but is not an object (null, false, a list) instead of running it without arguments, answers a request id that JSON-RPC does not allow (a boolean, an object, NaN) with an error, and no longer queues a ping behind long-running tool calls (#237).
• nfclaw verify and a replay's own environment check report an empty, damaged or incomplete environment record as unverified instead of identical, and compare image identities in both directions, so two names for one recorded image cannot hide a different image in the replay. A bundle from before environment records is still compared by its files. Reproductions and limits: the boundary-integrity audit (#237).
• A chain spec's config entries must be non-empty paths, and a null nxf_env keeps the default, as a null nxf_ver, limits or config already did (#237).
• A stopped run (Ctrl-C, kill, --timeout, MCP cancel_job) and a stopped replay remove the Docker/Podman task containers their processes started. Task wrappers killed while docker stop waited on a container's PID 1 had left every container behind, exited, and with a shorter shutdown grace still running (#227).
• nfclaw verify no longer fails every replay of a resumed run: the run metadata that a stopped or failed earlier attempt left in the original's pipeline_info/ is listed as earlier attempts instead of as missing results (#227).
• nfclaw verify pairs the random names kraken2-build gives library files when they contain _ (createtaxdb's Kraken2 and Bracken databases): such a replay had been reported as missing them (#226).
• The createtaxdb, bamtofastq and funcscan demos stage their sample sheets from immutable test-datasets commits, recorded in provenance, instead of the moving branches their test profiles validate, so nfclaw verify --require-environment accepts their replays (#226).
• On the website, a tap on the menu or on Search right after a page loaded was undone or reached no listener, and did nothing (#221).
• Handoffs no longer drop samples silently (bamtofastq → rnaseq single-end files, detaxizer → mag single-end sheets), and resuming a chain stage keeps its unchanged handoff and Nextflow cache (#218, #219).
• The daily pipeline update gives each changed pipeline's bundled analysis 90 minutes instead of 30. ampliseq 3.1.0's test, still running at 30 minutes, had failed the update since 2026-10-29 and held back every other release with it (variantbenchmarking 1.6.0). A release that cannot pass the gate can be set to the hold policy in sources.tsv so that the others publish (maintenance.md) (#228).
• The acceptance gate and the maintenance publisher run their Python helpers on $PYTHON (default python3, as in the Makefile) and refuse an interpreter older than 3.11 with a message naming it. On macOS, whose python3 is 3.9, every preview had failed with an ImportError reported as a rejected pipeline. Without GNU timeout or gtimeout, the gate bounds each preview with the bundled scripts/run_with_timeout.py instead of refusing to run (#233).
• A params file path given to parameters.merge that does not exist is an error, not an empty set of parameters (nfclaw run already refused it) (#233).
• nfclaw mcp answers a message nested too deeply to parse instead of stopping (#219).
• nfclaw chain edges <name> refuses a pipeline the library lacks (exit 1) instead of printing nothing, which read as "no handoff exists"; for a pipeline without rules it says so (#234).
• nfclaw chain status --json gives a missing chain the same keys as a found one, with error a list as in nfclaw status --json (#234).
• On Linux, Nextflow is launched without Python code between fork and exec (preexec_fn), which can deadlock a parent running threads, as nfclaw's container watch does: a single-threaded launcher requests the parent-death signal and execs Nextflow in place (#234).
• Stopping a run or replay whose process group has already ended no longer searches or signals that group's number, which another process group may hold by then (#234).
• CITATION.cff no longer gives 1.0.0 a release date (2026-06-15) that no release had (#234).
• Robustness of nfclaw status with unreadable logs and damaged records, the job supervisor and the container watcher (#218).
• A replay runs with the Nextflow settings its run recorded: NXF_* variables that the replaying shell sets but the run did not see are removed, and a recorded secret, kept only as <redacted>, must be exported again. A bundle with an incomplete pipeline identity or checksum record is refused (#229).
• --pipeline-version no longer deletes a partly materialized checkout under pipelines/<name>/.versions/ to start again: it may hold local work, so nfclaw refuses and names the directory to move aside (#229).
• A run refused before launch redacts secret NXF_* values from the command and error it prints and logs (#229).
• A chain spec whose nxf_env, nxf_ver or limits value has the wrong type (a number for a memory value, a list for an object) is refused with an error that names the field (#229).
• nfclaw status finds the latest attempt in a run log from an index the log's writer keeps (in older logs, by searching backward from the end) instead of reading the whole log (#229).
• The pipeline updater takes the lock runs take to fetch or initialize a pipeline and, when an update fails or is interrupted, restores only the checkout, pin and generated files it changed; the drift check refuses a pin whose source or checkout does not match its record (#229).
• On the website, arrow keys in the skills list move from the row that has focus, not from the selected one (#229).

Earlier pull requests, in brief

• #217 Post-merge fixes: palette race, kraken2 verify pairing, sarek 3.11.0 re-audit, docker probe limit.
• #216 Audit remediation: verified defect fixes, scientific output contracts (nfclaw assess), verify --require-environment, structured MCP parameters, replay_run and read_artifact, gated maintenance publication.
• #215 Stop repeating checks that Nextflow and nf-core already make.
• #213 fastqrepair: run the recorded corrections under the legacy config parser.
• #212 Remove duplicated files, code and documentation.
• #209, #211 MCP verified end to end in Claude Code, Codex and Antigravity; Antigravity loads every tool up front.
• #205 Report runs stubbed by a --config; stub-run seqsubmit's test without ENA.
• #203 Review of the whole codebase: three bug fixes, dead code removed, 100-column lint.
• #202 Next.js 15.5.28 for the website (GHSA-2464-fhr4-w9xw, GHSA-p3m5-59mp-jv5r).
• #200, #206, #207 Maintenance publication without organization PR permissions.
• #195 Name the release a failed chain stage ran; correct engine and network notes.
• Pipelines added or validated since: bacmodel, plasmodiumdrugres, provenancereport, stableexpression, magmap 1.3.1, rnasplice 2.0.0, rnastructurome 1.1.0, genomeassembler 2.0.1 (#197, #198, #204, #208, #214).