v3.3.2

Full Changelog: v3.3.1...v3.3.2

v3.3.1

What's Changed

• docs: landing install tabs, agent setup, exit codes, llms.txt and drift fixes by @abdul-hamid-achik in #7
• docs: real example runs, /compare, /ci, landing 3.x sections and a docs YAML guard by @abdul-hamid-achik in #8

Full Changelog: v3.3.0...v3.3.1

v3.3.0

Full Changelog: v3.2.0...v3.3.0

v3.2.0

Full Changelog: v3.1.2...v3.2.0

v3.1.2

What's Changed

• fix: 3.1.2 bounded teardown after a browser wedge; keep Playwright evidence by @abdul-hamid-achik in #6

Full Changelog: v3.1.1...v3.1.2

v3.1.1

What's Changed

• fix: 3.1.1 never lose piped output to process.exit by @abdul-hamid-achik in #5

Full Changelog: v3.1.0...v3.1.1

v3.1.0

What's Changed

• feat: 3.1.0 suites, run policy, delegated runners, Playwright export v2 by @abdul-hamid-achik in #4

Full Changelog: v3.0.1...v3.1.0

v3.0.1

First npm publish of the 3.0 line: the v3.0.0 tag's publish verify failed on
the flaky test fixed below, so 3.0.0 exists on GitHub and Homebrew only.
Everything in [3.0.0] applies.

Fixed

• latest / previous run references (cairn logs, context, diff,
  stash, MCP) resolve deterministically when two run directories share an
  mtime (same clock tick or a coarse filesystem clock): the timestamped run
  name breaks the tie, so the newer run always wins.
• MCP cairn_run_status for an invocation this server started resolves its
  journal from the artifact root when the registry does not know the
  journal directory yet, and a just-settled invocation briefly re-reads the
  journal until its final state and summary are visible, so status no longer
  returns a settled verdict without the summary and run list.
• Examples: the demo database's readiness check and compose healthcheck use
  pg_isready -h 127.0.0.1 (TCP). The image's init-time server answers on
  the unix socket and then restarts, so the socket check let the seed connect
  into that restart (ECONNRESET).
• CI: the desktop job installs the root dependencies its cairn --help
  parity test needs; the test skips with a clear reason when they are missing.

See the v3.0.0 release for everything in the 3.0 line and the Upgrading from 2.x guide.

v3.0.0

Major release. Full details are in CHANGELOG.md.

Highlights

• One run engine for the CLI and MCP. cairn run and MCP cairn_run share one engine and one options schema (config, browser.*, services, hooks, stash parity). Background MCP runs with cairn_run_status, cairn_run_cancel and cairn_logs; hooks over MCP require cairn mcp --allow-hooks.
• Live observability. Versioned events.v1, phases and heartbeats, an invocation journal, live redacted logs, a progress channel and cairn logs --follow.
• Evidence safety. Stash/publish gate (traces excluded or sanitized), richer receipts, cairn pin/unpin, cairn publish with a RunIndexV1 sidecar.
• Environment policy and safer lifecycles. requires / environments.<n>.policy with a refused status (exit 7), action-relative files, real cancellation, scoped checkpoints and signal-safe teardown.
• Agent authoring loop. Discovery with setup and session journals, cairn catalog, convention-aware export, cairn spec lint / finish / promote, the author-flow MCP prompt and cairn services up/down.
• Data verification without scripts. Datasources with mongo / temporal / http / value / table verifiers, poll on every verifier, expect / capture steps, gates and cairn wait, teardown / run steps, a fixtures registry and the @thelacanians/cairntrace/verifier SDK.
• Playwright export correctness and a Cairntrace Studio overhaul (Live, Invocations, Sessions, Catalog, Stashes, failure-first run detail).

Upgrading from 2.x

This release changes defaults that CI scripts, MCP clients and
remote-provisioned stacks rely on. Check the items below before upgrading.
Specs and configs that use none of them run as they did in 2.15.

1. An unknown --env is an error (exit 4). When a config exists,
   cairn run|spec verify|spec heal|discover|snapshot --env X fails before
   anything starts if environments: has no X. cairn wait,
   services up|down, fixtures and login reject it too. To check, run
   cairn config validate, then cairn run <specs> --env <name> --select-only.
   Add the missing environment or fix the name. A spec environment: or a
   defaultEnvironment that the config lacks only warns.
2. URL readiness needs a 2xx/3xx answer. This covers webServer.url, the
   webServer's baseUrl fallback and tmux windows[].readyOn.url. A 401, 404
   or 503 no longer counts as ready. Point the probe at a health route, or add
   anyResponse: true to get the 2.x any-answer rule back. If you keep the
   probe, the symptom is a readiness timeout that names the last status. The
   config schema is strict, so a config that uses anyResponse no longer
   loads in 2.x. A config shared with 2.x should switch to a health route or
   a readyOn.text / gate instead.
3. New run status refused, exit 7. A spec whose requires.env or
   environment policy forbids the resolved environment is refused before
   secrets, services or hooks run. Its result has status: refused, a
   refusal block and synthetic: true, and it has no run directory. Update
   anything that parses run.json or --format json (status, exitCode),
   and never open a synthetic runDir. cairn run exits 7 when every
   spec was refused; --strict-requires fails a mixed batch on any refusal.
   cairn spec heal and MCP cairn_spec_heal exit 7 on a refused spec.
   Specs without requires: on environments without policy: are not
   affected.
4. MCP cairn_run runs the cairn run lifecycle, and config services are
   gated. cairn_run now boots the config webServer and stops it
   afterwards. Pass noWebServer: true when you run the dev server yourself.
   Config services (docker/seed/tmux) and their teardown start over MCP only
   on a server started as cairn mcp --allow-services (or with
   CAIRN_MCP_ALLOW_SERVICES=1). Without the flag, cairn_run,
   cairn_spec_finish and cairn_audit fail with exit 4 when their config
   would start services. They fail before anything starts, and the error says
   what to do: pass noServices: true when the stack is already up, or
   reuseServices: true after a cairn services up from a shell.
   cairn_services_up and cairn_services_down refuse outright without the
   flag. Only grant the flag where an agent may provision and tear down that
   stack. Environments whose services cost money should never get it. The
   CLI is not gated.
5. MCP hooks are opt-in. before and after hooks over MCP are refused
   unless the server runs as cairn mcp --allow-hooks (or with
   CAIRN_MCP_ALLOW_HOOKS=1).
6. Child processes get a filtered environment. Preconditions, hooks,
   docker/seed/tmux commands, services teardown commands (the SIGINT/SIGTERM
   teardown included, which got the raw environment in 2.x) and webServer
   commands no longer inherit CAIRN_TVAULT_ENV, TVAULT_* keys that were
   not selected, or FILECHEAP_INGEST_TOKEN. To find what breaks, run
   grep -rn 'CAIRN_TVAULT_ENV\|TVAULT_' across your config commands and
   provisioning scripts. Read CAIRN_ENV instead, pass --env explicitly, or
   select the key as a secret. A guard written ${CAIRN_TVAULT_ENV:-local}
   now silently reads local. A key a services phase or the webServer sets
   in its own config env: is still passed as written. One example is a
   provisioner that needs TVAULT_DIR for a non-default vault. Another fix is
   to set the key inline: TVAULT_DIR=… ./provision.sh.
7. Evidence that leaves the run directory carries text and
   screenshots by default. This covers stash, auto-stash, pin --stash,
   investigate, clip and the retention archive. To keep the 2.x contents, set
   stash.include: [text, screenshots, traces, videos, downloads] and
   retention.publish.include, or pass cairn stash save --include traces --include videos. With retention.archiveToStash, pruned runs lose their
   traces, videos and downloads unless they are included. Traces are
   sanitized first. Unsanitized traces need stash.unsafeIncludeRawTraces: true. publish never sends traces.
8. The agent-browser trace is renamed. traces/agent-browser-trace.zip
   is now traces/agent-browser-trace.json, a Chrome trace-event JSON file.
   Open it in Perfetto, not playwright show-trace. Update your globs and
   scripts. Old runs are still read.
9. The package has an exports map. Only
   @thelacanians/cairntrace/verifier and /package.json resolve, so a deep
   import such as @thelacanians/cairntrace/src/... fails. Move verifiers to
   defineVerifier from the SDK. Verifiers that cairn runs need no local
   install. The cairn binary is unchanged.
10. session.resume is enforced. A missing, expired or other-origin
    checkpoint now fails the run (failure.phase: "session") instead of
    running unauthenticated, and a failed loadState fails the step.
    Remote-provisioned environments can hit this: their tunnel or port
    origin can differ from the one the checkpoint was captured on. To check,
    run cairn checkpoint list --json (its health should be ok or
    unscoped) and cairn spec verify --env <env>. To recapture, run
    cairn login <name> --env <env> --ttl 12h. A checkpoint that a
    precondition rewrites reads as unscoped and still loads.
11. Directory runs skip _ folders. cairn run flows/ no longer runs
    specs under flows/_drafts/ or _smoke/. cairn run <dir> --select-only
    lists them under skipped (draft), and a directory that holds only
    drafts is an error (exit 2). Rename those folders, or name the specs
    explicitly.
12. cairn spec verify is stricter (exit 4). It fails on missing files
    that a spec or its actions reference, on unknown preconditions.wait
    gates or fixtures:, and on an --env the policy refuses. Run it before
    CI does.
13. The MCP discovery defaults changed. Snapshots default to diff
    mode, so an unchanged page returns no elements, and they are capped at
    maxBytes: 16384. Sessions close after 30 minutes idle, and each one gets
    its own browser daemon. Pass snapshotMode: "full" (and a larger
    maxBytes) where the agent expects whole trees. Every open session keeps
    its own Chrome alive for up to 30 minutes, so close sessions with
    cairn_discover_close, or lower discovery.sessionTtlMs on machines
    with little memory.
14. Teardown commands run detached, and the SIGINT/SIGTERM teardown
    changed. Services teardown commands (normal, failure cleanup and
    signal path) now run in their own process group and session, with no
    terminal and their output in a private temp file. The Ctrl-C, Studio
    Stop or group SIGTERM that stops cairn no longer kills a provisioner's
    down halfway. A teardown command that prompts on the terminal fails
    now; make it non-interactive. On a signal, the teardown first waits up
    to CAIRN_SERVICES_SIGNAL_GRACE_MS (default 5000) for a boot command
    that is still running (a provisioner's up) to exit. It sends no
    signal of its own, and it waits for the command's whole process tree,
    so a long-lived child that survives the Ctrl-C (a tunnel supervisor)
    holds the teardown for the whole grace. Then it runs the teardown
    commands that have not run yet, each capped at
    CAIRN_SERVICES_SIGNAL_TEARDOWN_TIMEOUT_MS (default 10000, as before).
    For the command the normal teardown is running, it waits up to the same
    cap and never starts a second copy while that one is alive; one still
    running after the wait finishes in the background, and one that is gone
    runs again, as in 2.x. For a remote up / down that takes minutes,
    raise both budgets in the environment of the cairn run, for example
    `CAIRN_SERVICES_SIG...

v2.13.1

Full Changelog: v2.13.0...v2.13.1