# Upgrading Most releases need no action beyond the standard upgrade: 1. `bento update` — replaces the binary (the running daemon stays on its current version). 2. Apply any configuration migration listed for your target version below. 3. `bento doctor` — resolve any configuration errors. 4. `bento daemon restart` — then confirm `bento daemon status` is reachable. See [CLI setup](/cli/setup) for the full command reference. The sections below list only releases that require a manual change, newest first. A version not listed needs no action beyond the standard upgrade. ## Unreleased **`observability.phoenix` is gone.** The Arize Phoenix trace sink was removed; Langfuse is the only tracing sink. A leftover `phoenix:` block in `daemon.yaml` is ignored rather than rejected, so remove it by hand — and drop the `PHOENIX_API_KEY` it referenced. The in-process orchestrator loop is no longer traced; spawned agent runs still reach Langfuse unchanged. ## 0.7.1 **Every pipeline needs a `version`.** A pipeline inherits it from its governing skill when its skill closure resolves to exactly one skill. A pipeline with no skill (agent-only), or with more than one — a governing `skill` plus `companions` — must declare `version:` explicitly as a SemVer string. Startup validation hard-fails otherwise: `pipelines/.yaml: no single-skill version to inherit — declare an explicit "version" field`, and a non-SemVer value gives `"version" must be a SemVer version`. Add `version: 1.0.0` to each affected `.bento/pipelines/*.yaml`, and bump it when you change the pipeline — posted comments carry it for traceability. **`retain_checkout` must be a boolean.** A non-boolean value is now rejected at startup with `pipelines/.yaml: "retain_checkout" must be a boolean`. Previous releases accepted any value without checking it. **`bento trace` now requires a running daemon.** Lineage resolution (trigger → workload → invocations → tasks) moved from a direct Postgres connection to a `GET /trace/:id` call on the daemon. `bento trace` previously worked with only Postgres reachable; it now needs the daemon running and fails with the standard "daemon not reachable" message if it is not. It resolves against whichever daemon `BENTO_DAEMON_URL` points at, local or remote. `bento trace --json`'s top-level keys (`trigger`/`workload`/`invocations`/`tasks`) are unchanged, but `agent_logs`/`attempt_logs`/`sub_tasks` are replaced by a single `artifacts` object keyed by invocation id, each entry mirroring the artifacts manifest plus per-artifact rendered text. Any script parsing the old keys needs to read `artifacts` instead. ## 0.7.0 Apply these to `daemon.yaml` and every `.bento/pipelines/*.yaml` before restarting the daemon — config validation hard-errors on the old shapes until migrated. 1. **Orchestrator `strategy` is required; `assess` and `orchestrator: false` are removed.** In each `orchestrator:` block (top-level and per-pipeline): * `orchestrator: false` → **remove the field**. Omission now means direct execution (no orchestrator). * Any `orchestrator: { … }` object → add `strategy: { type: auto }` (mandatory; `type` must be `auto`). This includes `orchestrator: { targets: [...] }` and `orchestrator: {}`. * `assess:` → **`guidance:`**. * Remove any other keys under `orchestrator` — unknown fields now error. 2. **Skill principal bindings are enforced.** The built-in skills declare required principals: `agentic-review` requires `pull-request-reviewer`, `pr-approved-merge` requires `pull-request-author`. Any pipeline whose `skill:` or `companions:` reference such a skill must declare matching bindings, e.g. `principals: { pull-request-reviewer: github.principal. }` (form `.principal.`). For direct (non-orchestrated) execution with such a skill, also set `principal: `. Observer/read-only pipelines must **not** select a `principal`. Remove any `sandbox.mounts` that mount a shared `~/.config/gh` — it is rejected when principals are configured. 3. **MCP tool calls are now scope-gated.** MCP write tools require `mcp:write`, read tools require `mcp:read`, `*` satisfies both. Ensure every MCP client token — `daemon.yaml` `tokens[].scopes` and any OAuth-issued tokens — carries the scope it needs; under-scoped clients now get `Forbidden`. Loopback and anonymous local clients are unaffected (`*`). 4. **`GET /events` is removed; use `GET /triggers`.** Repoint any integration calling `/events`, `/events/stats`, `/events/:id`, or `/events/:id/fields` to the `/triggers` equivalents (or `bento trigger list`). List rows omit the payload — fetch `/triggers/:id` for it. The `POST /events` webhook receiver is unchanged. ## 0.6.5 Pipeline and orchestrator routing fields `runtime`, `model`, `effort`, `credential`, and `fallbacks` were replaced by named **targets**. Define reusable targets under a top-level `targets:` map in `daemon.yaml`, then reference them with `targets: [name]` on the pipeline or orchestrator. Validation hard-errors until migrated. ## 0.6.1 `sandboxes.forwardEnv` and per-pipeline `sandbox.forwardEnv` were removed. Declare any secret a run needs in that pipeline's `env:` manifest; skill and agent frontmatter `env:` no longer injects on its own. ## 0.5.1 `knowledge.mode` split into `knowledge.method` + `knowledge.delivery`. Migrate: * `mode: qmd` → `method: bm25, delivery: prompt` * `mode: mount` → `method: none, delivery: file` * `mode: ambient` → `method: none, delivery: search` * `mode: catalog` → `method: none, delivery: browse` ## 0.5.0 * `prompt:` → `instructions:` in every `.bento/pipelines/*.yaml`. Hard rename, no alias; validation hard-errors until changed. * Custom agents only: rename each authored `agents//SOUL.md` to `PERSONA.md`. ## 0.3.7 The `lifecycle.retrieve` pipeline block was removed. Move retrieval tuning (`topK`, `minScore`, `rewrite.*`) to `knowledge.retrieval` in `daemon.yaml`; a leftover `lifecycle.retrieve` key fails at startup. ## 0.2.4 Pipeline output type `inline_review` → `upsert_comment`. Rename it in any `output:` block that used it. ## 0.2.3 The `BENTO_MANAGEMENT_TOKEN` env-var fallback for CLI-to-daemon auth was removed. If you relied on it, authenticate with `bento auth setup` instead.