Changelog

This page lists the recent product releases, features, and fixes for the Verfix runtime and CLI.

For the full detailed commit history and changes, visit the full CHANGELOG on GitHub.

v0.4.0 (2026-07-11) — Failure synthesis

A field review concluded Verfix “did the capture work correctly — the gap is entirely in synthesis”: runs already recorded the right artifacts, but hints were generic and nothing connected them. This release closes that gap — deterministically, no LLM anywhere in the pipeline.

Added

findings[] — deterministic post-failure analysis. Pure functions over the evidence a run already captured; each emits a typed finding (code, hypothesis-language summary, triggering evidence, a concrete suggestion) only when the evidence clearly supports one — silent when unsure, capped at 3, top finding rendered into fix_hint. Shipped analyzers: stale_session (a restored session met a 401/403 on an auth-ish endpoint), blocking_overlay (the selector was fine — an open dialog/overlay was covering the page, named by its accessible name), prior_console_errors (earlier console errors correlated with a later UI-shaped failure, with first/third-party detection).
page_state — failure-time facts. Every failure now reports what was observably true on the page when it happened: URL, title, open dialogs/overlays, and counts of prior console errors / failed requests. Facts only, no interpretation.
verfix show --timeline [--last N] [--filter type] — steps, console lines, and network requests interleaved chronologically around the failure.
verfix show --dom '<selector>' — query the run’s saved DOM snapshot (also plain-text search).
selector_count assertion — assert an exact number of matches.
verfix run --base-url <url> — per-invocation base-URL override for preview deploys and per-PR environments.
Diagnosis playbook in generated instructions. .verfix/INSTRUCTIONS.md now teaches the escalation ladder — JSON facts/findings first, then --timeline, then --dom + open_dialogs, then full logs, and only then project source.

Changed

@verfix/engine bumped to 0.2.0.

Fixed

Intermittent second JSON document on stdout (#80) that could corrupt --output json on first runs under a timing race with the bounded AI failure-summary call.
third_party console-error labeling — now hostname-based (with loopback/sibling-subdomain awareness) instead of origin-based, so an app’s own API on a different localhost port is no longer mislabeled third-party.

v0.3.6 (2026-07-07)

Added

Auth state reuse (saveState / useState flow fields) — a login flow can persist cookies (incl. httpOnly), localStorage, and IndexedDB under a name; other flows restore it and start already authenticated.
select_option, check, uncheck, hover flow steps.
upload_file flow step — fixture path or inline { name, content, mimeType, encoding }, CI-safe.
wait_for_url and wait_for_network_idle flow steps.
frame step field for targeting elements inside an <iframe> (payment widgets, embedded editors).
Scoped text_visible — optional selector narrows the text search to one element.
verfix show --console / --network — print a run’s captured console log and network requests without hand-parsing files in .verfix/runs/.
verfix probe — dry-run selectors/text against a run’s saved DOM snapshot (~1s) instead of a full run.
AI rate-limit circuit breaker — after 3 consecutive 429s, AI calls disable for the rest of the run instead of retrying and failing on every step.

Changed

JSON output is now a summary by default; --full restores the raw event timeline. The full timeline was ~93% of the payload and agents paid for it on every fix-loop iteration. The summary stays lossless for anything non-nominal — failures carry flow/assertion, skipped optional steps are always listed, source_changes always appears when non-clean.

v0.3.5 (2026-07-06)

Added

press flow step — sends a keyboard key on a target or at the page level, for UIs that submit on keydown rather than form submission.

v0.3.4 (2026-07-06)

Added

${VAR} environment variable interpolation in flow step value/url, assertion value, and baseUrl — resolved from process.env (including .verfix/.env) at run time, so secrets never need to live in verfix.config.json.
Optional flow steps ("optional": true) — skipped instead of aborting the flow if they fail within their timeout.
Flow clearState — clears cookies and storage before a flow runs, for flows that must start logged-out.
network_request_success acceptStatuses and no_console_errors exclude — handle endpoints/errors with more than one valid outcome without branching the flow.

v0.3.3 (2026-07-05)

Added

verfix validate — checks verfix.config.json for structural and semantic errors without running anything.
Flow skip / skipReason — quarantine a known-broken flow from a full run without deleting it.

Fixed

Per-flow mode override was silently dropped when running multiple flows together — now correctly applies for any number of flows in one run.
Exploratory mode now fails fast with ai_key_required before launching a browser if no AI key is configured, instead of failing after.
Chromium headless-shell install self-repairs on a partial/interrupted install instead of crashing.

v0.3.1 (2026-07-04) — Verfix is now local-first

Changed

verfix run executes in-process by default — no Docker, no Redis, no API server. The verification engine was extracted as @verfix/engine; a clean machine needs only Node 20+, and the first run downloads Chromium once (~130MB, cached). Existing verfix.config.json files need zero changes.
Strict mode needs no AI key. verfix init defaults to strict and only asks for a provider/key when you pick assisted/exploratory.
Results live in .verfix/runs/ — each run persists a JSON summary plus a full Playwright trace zip (newest 20 kept). New commands: verfix show opens the trace viewer, verfix list lists recent runs.
The Docker server runtime is now opt-in via --server (or VERFIX_RUNNER=server) — the foundation of a future hosted CI product, not the default path.
Config-First Source Guard introduced — verfix run snapshots a git baseline each verify cycle and reports source_changes; sourceCodePolicy (warn/block/off) controls enforcement. See Config-First Verification.
Agent files consolidated around the AGENTS.md standard — a compact stub plus a full .verfix/INSTRUCTIONS.md reference; .cursorrules/CODEX.md generation dropped (Cursor/Codex read AGENTS.md natively).

Removed

Hybrid host/container browser mode and the slim server image auto-selection — local mode covers the same use case natively.

Fixed

npm install verfix now resolves its engine dependency correctly — previously shipped a broken local-path reference that left a dead symlink in consumers’ installs.

v0.2.10 (2026-06-27)

Added

Redis Queue for Job Processing: Replaced in-memory job queue with Redis-backed queue for reliable, persistent job processing across container restarts.
Broker Pattern in Go API: Introduced a pluggable Broker interface supporting both in-memory and Redis queue backends, providing resilience and future extensibility.

Changed

Updated base Docker images for both the full (verfix-server) and slim (verfix-server-slim) images with the latest security patches.

Fixed

Cross-Platform Worker Extraction: Fixed worker extraction from Docker images on macOS and Windows — now correctly extracts and runs workers natively on the host with proper Playwright Chromium installation.
Redis Connection Stability: Fixed MaxRetriesPerRequestError in Redis adapter connection handling, improving reliability during host Redis detection.
localhost Resolution Bug: Fixed an IPv6 binding issue where localhost could resolve to ::1 on certain macOS/Windows configurations, causing connection failures to host services.

v0.2.9 (2026-06-22)

Fixed

Minor bug fixes and documentation updates.

v0.2.8 (2026-06-22)

Added

Hybrid Browser Mode (Host/Container): Introduced a dual browser execution model with two modes: host (default on macOS/Windows) — runs Playwright workers directly on the host machine with native localhost access, and container (default on Linux) — keeps workers inside Docker with --network=host. Users can override via VERFIX_BROWSER_MODE=host|container.
- On container start, the CLI automatically extracts worker files from the Docker image, installs Playwright Chromium locally, and spawns a dedicated local worker process.
- New --show-browser flag on verfix start and verfix run enables visible browser window for debugging (headful mode).
Slim Server Image (verfix-server-slim): A new lightweight Docker image built on SQLite (no PostgreSQL dependency) that the CLI automatically selects when running in host browser mode on macOS/Windows, reducing resource overhead.
Pluggable Database Backend: Refactored the Go API to a Store interface with two implementations — PostgreSQL (full image) and SQLite (slim image).
Local Worker Lifecycle Management: The CLI now manages local worker processes with proper PID tracking, auto-detection of stale workers, headful/headless mode switching, graceful shutdown (verfix stop), and artifact directory bind-mounting.
Update Checker Browser-Mode Awareness: The NPM and Docker image update-checker now queries the correct image tag based on the active browser mode (slim vs. full).

Fixed

Localhost Networking on macOS/Windows: Replaced the previous CLI TCP proxy approach with hybrid browser mode for a more robust and maintainable solution.
Port Conflicts on Host Redis Detection: The CLI now detects if Redis is already running on the host at port 6379 before mapping container ports, preventing “port is already allocated” errors.

v0.2.7 (2026-06-20)

Added

Anonymous Telemetry & Analytics: Integrated privacy-first telemetry with PostHog to track usage metrics for CLI initialization, diagnostic checking, container startups, and verification runs.
- Automatically respects standard DO_NOT_TRACK and VERFIX_TELEMETRY=off environment variables.
- Uses an anonymous tracking identifier generated once and stored in ~/.verfix/.machine-id (no PII, hostname, or system paths collected).
- Shows a clear, transparent, one-time privacy notice on first execution.
- Telemetry works completely asynchronously on lazy-loaded paths, ensuring zero execution block.
Telemetry Documentation: Added a comprehensive Telemetry & Privacy developer documentation guide.

v0.2.6 (2026-06-20)

Added

Non-Interactive Setup Wizard Mode: Added --yes / -y flag to verfix init for unattended execution using flags or environment variables. Particularly useful for automated environments, CI/CD pipelines, and AI coding agents.
Provider Auto-Detection: Automatically detects AI providers (OpenAI, Anthropic, Gemini, OpenRouter) based on the format of the provided API key.
Agent Setup Command: Added verfix agent-setup command that outputs machine-readable JSON instructions for AI coding agents to bootstrap Verfix.
Graceful Docker Degradation: Init wizard now warns and continues configuring if Docker is not installed or running, instead of hard failing.
Dry-run Mode: Added --dry-run flag to preview what would be configured as JSON without writing any files.

Changed

verfix init now supports --ai-provider, --ai-model, --ai-key, --base-url, --mode, --skip-runtime, --skip-agent-files, and --dry-run flags.
Environment variable fallbacks: VERFIX_AI_PROVIDER, VERFIX_AI_MODEL, VERFIX_AI_KEY, VERFIX_BASE_URL, VERFIX_MODE are now recognized.

v0.2.5 (2026-06-16)

Added

CLI Local Proxy: Transparent TCP proxy for Docker networking on Windows/macOS. Automatically forwards traffic from the container to the host machine, fixing ERR_CONNECTION_REFUSED errors on Windows Firewall and macOS.

Fixed

Docker networking for Windows/macOS when targeting localhost services
Worker connection error messages now clearly indicate host server connectivity issues

v0.2.2 (2026-06-14)

Added

CLI update notifications for both npm package and Docker server image
verfix start and verfix status now show update banners when newer version available
Background version checks with 24-hour caching — zero blocking I/O

Changed

Redesigned dashboard workspace with Postman-inspired shell, responsive split panels, and unified light/dark theme tokens
Flaky task display switched from URL-level to execution-level granularity
Improved dashboard keyboard navigation, ARIA labels, and validation feedback

Fixed

Docker build failure from .dockerignore excluding cli/ directory
Database performance with composite index for flaky URL queries
Database resource leak with deferred row close in handleFlaky

v0.2.1 (2026-06-10)

Key Highlights

AI Agent Context File: Added .github/agents.md containing coding standards, monorepo architecture, testing instructions, and critical networking guardrails for AI coding assistants.
2026 Model Support: Updated static model lists for OpenAI (gpt-5.4-mini/gpt-5.5), Anthropic (claude-sonnet-4-6/claude-opus-4-8), and Gemini (gemini-3.5-flash/gemini-3.5-pro), and added support for the new Gemini AQ key prefix.

v0.2.0 (2026-06-10)

Key Highlights

Multi-provider AI Support: Implemented custom HTTP-based adapters in the AI runtime to support OpenAI, Anthropic, Gemini, and OpenRouter, completely eliminating the external openai SDK dependency.
API Key Connectivity Testing: Added an interactive connectivity test step for AI API keys during the verfix init setup wizard.
Config Migration & Validation: Added schema validation and automated configuration migration support for legacy configurations.
Docker Networking: Improved Docker networking resolving logic in CLI and workers to handle platform-specific URLs (host.docker.internal vs. host networking) across multiple AI providers.

v0.1.5 (2026-06-07)

Key Highlights

Programmatic SDK: Introduced programmatic SDK for integration scenarios with a class-based API.
Flow Scaffold Changes: Updated verfix init to no longer scaffold empty flows — replaced with verfix create flow <name> for on-demand flow creation.
CLI Automation Support: Added clean JSON output mode and predictable exit code contracts for machine-driven integration.
Disk Optimization: Improved the screenshot/image capturing system to save disk space in execution artifacts.

v0.1.4 (2026-05-25)

Key Highlights

Port Management: Introduced runtime port management with new defaults (Dashboard 3610, API 3611) and automatic port fallback (3612/3613, etc.).
Self-Healing Ports: Configured container-to-CLI runtime port sync and API health-based fallback discovery for robust local runs.
Init Wizard Fixes: Corrected app-port auto-detection to prevent selecting runtime/API ports as the user’s app port.