# Migration: v0.4.11 → v0.4.12

> **Status (2026-05-24):** v0.4.12 closes the v0.4 arc. The web stack, the
> in-tree subject backends, the five in-tree provider mirrors, and the
> `llm-cli-wrapper` crate are all deleted from this repo. The replacements
> live as standalone plugins under [launchapp-dev](https://github.com/launchapp-dev)
> and must be installed before the daemon will start.

If you are upgrading from v0.4.11 (or any earlier v0.4.x) this is the patch
where the daemon stops shipping with bundled providers, subjects, and a web
server. You will need to run **one** post-upgrade command
(`animus plugin install-defaults`) before the daemon will boot. After that,
day-to-day operation is unchanged.

> **TL;DR:** stop the daemon → upgrade the binary →
> `animus plugin install-defaults --include-subjects --include-transports` →
> `animus daemon preflight` → `animus daemon start --autonomous`.

## What changed

| Change | Impact |
|---|---|
| In-tree web stack deleted (~9K LOC) | `animus web serve` now spawns installed `transport_backend` + `web_ui` plugins and errors out if none are present |
| In-tree subject backends deleted (~1000 LOC) | Daemon will refuse to start without at least one subject_backend plugin installed; install `animus-subject-default` for `kind=task` and `animus-subject-requirements` for `kind=requirement` |
| In-tree provider mirrors deleted (5 providers) | Daemon will refuse to start without at least one provider plugin installed |
| `llm-cli-wrapper` crate deleted (~5,882 LOC) | Internal refactor; user-visible only if you path-depended on the crate |
| Daemon preflight on startup | `animus daemon start` runs a plugin-presence check before booting. Default posture: refuse to start, with the exact `animus plugin install ...` fix command in the error |
| Phase-level `idempotency` field | Crash recovery for phases without an explicit `idempotency: idempotent` annotation now lands as `Blocked` with an actionable hint rather than silently re-running |
| `ANIMUS_DAEMON_DISABLE_BUILTIN_TASK_ADAPTER` + `_REQUIREMENTS_ADAPTER` env vars | Now no-ops. Use `ANIMUS_DAEMON_DISABLE_SUBJECT_PLUGINS=1` if you need to disable subject discovery entirely |
| `animus web serve` no longer boots an in-process axum server | Requires `animus-transport-http`, `animus-transport-graphql`, and `animus-web-ui` plugins installed |

This is the largest single-release surface change since the v0.3 → v0.4
rename. It is intentional: every backend is now a plugin, and the daemon
treats them uniformly.

---

## Migration steps

### 1. Stop the running daemon

```bash
animus daemon stop
```

Stop the daemon in every project where you have it running before upgrading
the binary. The v0.4.11 daemon and the v0.4.12 daemon do not share state
about plugin requirements; running a stale daemon against a new CLI will
surface confusing errors.

### 2. Upgrade the `animus` binary

Pick whichever path matches how you installed v0.4.11:

```bash
# Upstream installer (macOS)
curl -fsSL https://raw.githubusercontent.com/launchapp-dev/animus-cli/main/scripts/install.sh | bash

# Or pin to v0.4.12 explicitly
ANIMUS_VERSION=v0.4.12 curl -fsSL https://raw.githubusercontent.com/launchapp-dev/animus-cli/main/scripts/install.sh | bash
```

If you built from source:

```bash
cd path/to/animus-cli
git fetch origin
git checkout v0.4.12
cargo install --path crates/orchestrator-cli --locked
```

> **No Homebrew formula or crates.io publish yet** — `cargo install animus`
> from crates.io is not wired up. Track the [animus-cli releases page](https://github.com/launchapp-dev/animus-cli/releases)
> for whichever distribution channel ends up canonical.

Verify:

```bash
animus --version    # should print v0.4.12
```

### 3. Install the default plugin set

This is the one new step that v0.4.12 introduces. Without it, the daemon
will refuse to start.

```bash
animus plugin install-defaults --include-subjects --include-transports
```

What this installs:

| Group | Plugins | Required for |
|---|---|---|
| Providers (always) | `animus-provider-{claude,codex,gemini,opencode,oai}` v0.2.1 | Any daemon start — at least one provider must be installed |
| `--include-subjects` | `animus-subject-{default,requirements,linear,sqlite,markdown}` v0.1.0 | `animus subject --kind <kind>` for `task`, `requirement`, and the three plug-in backends |
| `--include-transports` | `animus-transport-{http,graphql}` + `animus-web-ui` | `animus web serve` and `animus web open` |

The command is idempotent: it skips plugins that are already installed. It
uses the same install pipeline as `animus plugin install`, so cosign
signature verification and integrity checks apply uniformly.

If you only use a subset of providers (e.g. Claude only) and want a leaner
install, install them one at a time instead:

```bash
animus plugin install launchapp-dev/animus-provider-claude
animus plugin install launchapp-dev/animus-subject-default
animus plugin install launchapp-dev/animus-subject-requirements
```

### 4. (Optional) Install the OAI Responses API agent provider

If you use the OpenAI Responses API agent loop (not the plain chat completions
endpoint), pull in the agent-shaped provider as well:

```bash
animus plugin install launchapp-dev/animus-provider-oai-agent@v0.1.1
```

Or include it in the bulk install:

```bash
animus plugin install-defaults --include-oai-agent --include-subjects --include-transports
```

### 5. Verify with `daemon preflight`

```bash
animus daemon preflight
```

This prints the installed-vs-required matrix and exits non-zero if any
required role is unsatisfied. The error message includes the exact
`animus plugin install ...` command to fix each gap. JSON envelope is
`animus.daemon.preflight.v1` if you want to script around it
(`animus daemon preflight --json`).

Expected output when everything is satisfied:

```
Daemon preflight OK
  provider:      5 installed (claude, codex, gemini, opencode, oai)
  subject:       5 installed (default, requirements, linear, sqlite, markdown)
  transport+ui:  3 installed (transport-http, transport-graphql, web-ui)
```

### 6. Start the daemon

```bash
animus daemon start --autonomous
```

`animus daemon start` runs the same preflight check before booting. If
preflight already passed in step 5, no plugins will be downloaded here.

If you want the daemon to install missing plugins on its own (less
deterministic, but useful for one-shot dev boxes):

```bash
animus daemon start --autonomous --auto-install
```

Escape hatch for dev iteration when you're knowingly running without the
required plugins:

```bash
animus daemon start --autonomous --skip-preflight
```

`--skip-preflight` is **not** recommended for production — you will get
runtime errors from the first request that needs a missing backend.

---

## What auto-resume does for in-flight workflows

If you upgrade while a workflow is mid-execution (rare but real for
long-running phases), v0.4.12 will try to resume it on the new daemon:

- The daemon writes `<phase>.session.json` for every in-flight phase
  (`{ provider, session_id, status }`).
- On restart, the scheduler attempts `provider.resume_agent` through the
  plugin that originally ran the phase.
- If the provider plugin supports session resume (Claude, Codex, OpenCode),
  the phase picks up where it left off.
- If the provider does not support session resume, or the plugin is not
  installed on the new daemon, the workflow is marked **Blocked** with an
  explicit reason. You can then inspect, re-run, or cancel it manually.

The default posture is "block and ask the operator" rather than "silently
re-run and burn API credits". To force-resume a blocked workflow after you've
decided it's safe:

```bash
animus workflow resume <workflow-id> --force
```

## Idempotency annotations on workflow YAML

v0.4.12 adds a new phase-level field:

```yaml
phases:
  implementation:
    mode: agent
    agent: default
    directive: "Implement production code."
    idempotency: idempotent      # or: sideeffecting, unknown
```

| Value | Meaning | Crash-recovery behavior |
|---|---|---|
| `idempotent` | Safe to retry; re-running produces the same observable effect | Auto-retried on daemon restart |
| `sideeffecting` | Mutates external state (push, merge, deploy, webhook fire) | Blocked on crash; operator must decide |
| `unknown` (default) | Not yet classified | Blocked on crash; operator must decide |

**Existing workflow YAML without an `idempotency:` field defaults to
`unknown` and will be Blocked on the first crash-recovery cycle.** This is
deliberate: the v0.4.11 behavior was to silently re-run any phase on restart,
which burned API credits and occasionally double-pushed branches.

Options:

1. **Annotate.** Walk each phase in your custom workflows and mark
   `idempotent` (most agent phases, most read-only command phases) or
   `sideeffecting` (anything that pushes, merges, opens a PR, fires a
   webhook). One-time edit per workflow.
2. **Leave unannotated.** Phases default to `unknown` → blocked on crash.
   Use `animus workflow resume <id> --force` when you decide it's safe.
3. **Mix.** Annotate the safe phases, leave the risky ones as `unknown`.
   Recommended for production pipelines.

Bundled workflow templates (`task-queue`, `conductor`, `direct-workflow`)
ship with sensible defaults already in place. No action needed if you only
use the bundled templates.

## Env var deprecations

| Env var | v0.4.11 behavior | v0.4.12 behavior |
|---|---|---|
| `ANIMUS_DAEMON_DISABLE_BUILTIN_TASK_ADAPTER` | Skipped the in-tree task subject adapter | **No-op.** The in-tree adapter no longer exists. Install or remove `animus-subject-default` instead |
| `ANIMUS_DAEMON_DISABLE_BUILTIN_REQUIREMENTS_ADAPTER` | Skipped the in-tree requirements subject adapter | **No-op.** Install or remove `animus-subject-requirements` instead |
| `ANIMUS_DAEMON_DISABLE_SUBJECT_PLUGINS` | (did not exist) | **New.** Set to `1` to skip subject discovery entirely (escape hatch for debugging plugin issues; daemon will refuse most subject operations) |
| `ANIMUS_DAEMON_DISABLE_TRIGGERS` | Same | Unchanged |
| `ANIMUS_PROVIDER_DISABLE_PLUGIN` | Forced fallback to in-tree provider backends | **Removed (silently ignored).** The in-tree provider backends are gone and the env var no longer affects dispatch in any way. Install missing provider plugins, remove a bad plugin with `animus plugin uninstall --name <name>`, or move its binary out of discovery |

If you have any of the deprecated env vars set in your shell config, CI,
systemd unit, or Docker compose file, remove them. They will not cause
errors — they are silently ignored — but they will mislead the next
operator who reads the file.

## `animus web` behavior

v0.4.11: `animus web serve` booted an embedded axum HTTP server with the
React UI compiled in.

v0.4.12: `animus web serve` discovers installed `transport_backend` and
`web_ui` plugins, spawns them, and opens the browser. If the required
plugins are not installed, you get:

```
error: web serve requires transport + UI plugins
  run: animus plugin install-defaults --include-transports
```

To install:

```bash
animus plugin install-defaults --include-transports
```

This installs `animus-transport-http`, `animus-transport-graphql`, and
`animus-web-ui` from their respective releases. After install:

```bash
animus web serve
animus web open       # also opens the browser
```

The user-facing UX is unchanged once the plugins are installed.

## Rollback procedure

If v0.4.12 surfaces a blocker you need to work around, you can roll back
to v0.4.11. The plugin-extraction work is **not** reversible at the data
layer in the sense that installed plugins keep working under v0.4.11 too —
v0.4.11 simply prefers the in-tree backends when both are available.

```bash
# Stop the v0.4.12 daemon
animus daemon stop

# Reinstall v0.4.11
ANIMUS_VERSION=v0.4.11 curl -fsSL https://raw.githubusercontent.com/launchapp-dev/animus-cli/main/scripts/install.sh | bash

# Verify
animus --version    # should print v0.4.11

# Start the v0.4.11 daemon — no preflight on this version
animus daemon start --autonomous
```

The installed plugins under `~/.animus/plugins/` remain in place and will
be re-used when you upgrade back to v0.4.12. The v0.4.11 daemon ignores
the new `idempotency` field on workflow YAML (forward-compatible).

If rollback is needed because of a workflow that the v0.4.12 daemon
Blocked on crash recovery, the recommended path is:

1. `animus workflow resume <id> --force` under v0.4.12 (the explicit
   override exists for exactly this).
2. Only roll back if `--force` resume itself surfaces a bug.

---

## Quick smoke test after migration

```bash
animus --version                                         # v0.4.12
animus plugin list                                       # at least 1 provider + 2 subjects + (optional) transports
animus daemon preflight                                  # all required roles satisfied
animus daemon start --autonomous
animus daemon health                                     # responds Healthy
animus subject list --kind task                          # routes through animus-subject-default plugin
animus web serve                                         # spawns transport + ui plugins, opens browser
```

If any step fails, `animus doctor` runs a broader environment check and
prints actionable remediation.

## Where to ask for help

- **Animus core repo:** [launchapp-dev/animus-cli](https://github.com/launchapp-dev/animus-cli)
- **Previous migration guide:** [`v0.3-to-v0.4.md`](./v0.3-to-v0.4.md)
- **Plugin ecosystem index:** [launchapp-dev plugin repos](https://github.com/launchapp-dev) (18 repos as of v0.4.12)
- **CHANGELOG:** [`CHANGELOG.md`](../../CHANGELOG.md) for the full v0.4.12 entry
- **Upgrade guide (cross-version):** [`docs/guides/upgrading.md`](../guides/upgrading.md)