conductor

# AGENTS.md

## Project Overview

Conductor is a CLI tool for defining and running multi-agent workflows with the GitHub Copilot SDK. Workflows are defined in YAML and support parallel execution, conditional routing, loop-back patterns, and human-in-the-loop gates.

## Common Commands

```bash
# Install dependencies
make install          # or: uv sync
make dev              # install with dev dependencies

# Run tests
make test                                           # all tests
uv run pytest tests/test_engine/test_workflow.py   # single file
uv run pytest -k "test_parallel"                   # pattern match

# Run tests with coverage
make test-cov

# Lint and format
make lint             # check only
make format           # auto-fix and format

# Type check
make typecheck

# Run all checks (lint + typecheck)
make check

# Run a workflow
uv run conductor run workflow.yaml --input question="What is Python?"

# Run with web dashboard
uv run conductor run workflow.yaml --web --input question="What is Python?"

# Run in background (prints dashboard URL and exits)
uv run conductor run workflow.yaml --web-bg --input question="What is Python?"

# Stop a background workflow
uv run conductor status                 # list background workflows, never stops one
uv run conductor status --json          # machine-readable
uv run conductor stop                  # auto-stop if one running, list if multiple
uv run conductor stop --port 8080      # stop specific port
uv run conductor stop --all            # stop all background workflows

# Update conductor
uv run conductor update                # check for updates and print the install-script command
uv run conductor update --apply        # launch the installer automatically (conductor exits to release file locks)

# Resume a failed workflow from checkpoint
uv run conductor resume workflow.yaml                  # resume from latest checkpoint
uv run conductor resume workflow.yaml --web            # resume with dashboard
uv run conductor resume workflow.yaml --web-bg         # resume with background dashboard
uv run conductor resume workflow.yaml --provider copilot
uv run conductor resume workflow.yaml -m tracker=ado
uv run conductor checkpoint list       # list available checkpoints

# Acquire and inspect a workflow's git-backed plugins
uv run conductor plugin fetch workflow.yaml   # prime the cache (the CI step)
uv run conductor plugin list workflow.yaml    # what a run would load; cache-only

# Validate a workflow
uv run conductor validate examples/simple-qa.yaml
make validate-examples    # validate all examples
```

## Changelog

Conductor uses [towncrier](https://towncrier.readthedocs.io/) to manage changelog entries without merge conflicts. Fragment files are collected in `changelog.d/` and compiled during releases. Five normative rules apply to every agent and contributor:

1. **Add a fragment for user-facing changes.** Every PR with a user-facing change MUST add exactly one fragment file under `changelog.d/` following the contract in [`changelog.d/README.md`](changelog.d/README.md).
2. **NEVER edit `CHANGELOG.md` in feature or fix PRs.** Towncrier compiles `CHANGELOG.md` only during release preparation.
3. **Naming is free-form.** Use the issue number when known (e.g. `392.added.md`, which towncrier renders as clickable `(#392)`), or any descriptive slug starting with `+` (e.g. `+otel-mcp-spans.added.md`). NEVER rename a fragment after opening the PR because the filename is cosmetic once validated. The only hard rule is towncrier syntax: non-numeric names must start with `+`, and the category must be one of `added`, `fixed`, `changed`, or `removed`.
4. **CI enforces the contract.** The `Changelog` CI workflow validates fragment presence and syntax on every pull request, reporting actionable instructions on failure.
5. **Exemptions require a maintainer label.** Trivial, internal, or bootstrap changes without user-facing impact are exempted by a maintainer applying the `changelog-not-required` label (not by author judgment). The label provides a full exemption that waives both the fragment requirement and the `CHANGELOG.md` edit prohibition, but any fragments present are still validated.

## Releasing

Releases are tag-triggered: pushing a `v*` tag runs
[`.github/workflows/release.yml`](.github/workflows/release.yml), which lints,
typechecks, tests (Python 3.12 + 3.13), builds the package, and creates a GitHub
Release with artifacts and curated release notes extracted from `CHANGELOG.md`.
The maintainer prepares a release-prep PR (`chore(release): cut X.Y.Z`) that bumps
`version` in `pyproject.toml`, runs `make changelog-build VERSION=X.Y.Z` to compile
`changelog.d/` fragments into `CHANGELOG.md`, and re-locks `uv.lock` (`uv lock`).
After it merges, tag the merge commit on `main` and push the tag. The version lives
only in `pyproject.toml` (read at runtime via `importlib.metadata`); there is no
separate `__version__` to edit. The default bump is the patch ("build") number.
See [`docs/release-checklist.md`](docs/release-checklist.md) for the full
step-by-step checklist.

## Architecture

### Core Package Structure (`src/conductor/`)

- **cli/**: Typer-based CLI. Hot-path verbs stay flat (`run`, `resume`, `validate`, `show`, `stop`, `replay`, `update`, `doctor`, `guide`); the long tail is grouped under noun sub-apps registered via `app.add_typer(...)` — `registry`, `plugin` (→ `list` / `fetch`), `mcp` (→ `serve`), `checkpoint` (→ `list`), and `gate` (→ `respond`) — with `rich_help_panel=` organising the root `--help` into *Run & Recover* / *Author & Inspect* / *Environment* / *Interact* / *State* sections (rendered order; determined by first-occurrence order of commands in the Click command list). The old flat commands `checkpoints` and `gate-respond` remain as **hidden deprecated aliases** that print a stderr deprecation warning (noting removal in a future release) and forward to the new grouped commands via a shared impl (issue #275).
  - `app.py` - Main entry point, defines the Typer application, flat commands (including `guide`, rich_help_panel="Interact"), and the hidden `checkpoints`/`gate-respond` deprecation aliases. `run`, `resume`, and `validate` accept `--environment` (resolved environment name or file path). **`status` also lists recently-completed runs, not just live ones (R1)** — see the fleet.py bullet below for the identical change to `fleet list`; `status --json` keeps its existing `running` array unchanged and adds a sibling `completed` array, and `--live` restores the exact pre-change scope on both the table and the JSON payload.
  - `guide.py` - `guide_impl(text, port, token)` behind `conductor guide` (issue #400): resolves the dashboard port via `pid.py::scan_pid_files()` when `--port` is omitted (read-only, matching `app.py::status`'s reasoning), POSTs `{"text": ...}` to `POST /api/guidance`, and maps 403/409/422/connect-error the same way `cli/gate.py::_gate_respond_impl` does. `guide` is a flat top-level command (not a `guide respond` sub-app) since there is exactly one verb
  - `checkpoint.py` - `checkpoint` group (`checkpoint list`) + shared `_list_checkpoints_impl` (modeled on `registry.py`)
  - `gate.py` - `gate` group (`gate respond`) + shared `_gate_respond_impl` (modeled on `registry.py`). Also consumed directly by the Fleet Manager TUI's gate-resolve action (`conductor.fleet.tui.actions.resolve_gate`) — see the fleet bullet below.
  - `registry.py` - `registry` group (`list` / `add` / `remove` / `set-default` / `update` / `show`)
  - `plugin.py` - `plugin` group (`list` / `fetch`). Deliberately no `update`: a floating ref self-updates and a pinned one is meant not to. `fetch` existing as a separate verb is what keeps `conductor validate` off the network
  - `mcp.py` - `mcp` group (`mcp serve`, issue #432): starts an MCP server over stdio exposing every configured registry's workflows as tools (`--registry`/`--allow`/`--deny`/`--workflow-dir` narrow the exposed set; `--toolsets`/`--max-direct-tools`/`--max-wait-seconds`/`--tool-prefix`/`--max-concurrent-runs`/`--introspect-full` control behavior). `no_args_is_help=True` like `checkpoint`/`gate` — this group has no bare-invocation default, unlike `fleet`. Every reference to `conductor.mcp.*` is a **lazy import inside `serve()`'s body**, deliberately: `conductor.mcp.__init__` (the existing MCP *client* package, `mcp/manager.py`) eagerly imports the full `mcp` SDK as a side effect of its own `__init__.py`, and `cli/app.py` imports every `cli/*.py` sub-app module on every `conductor` invocation — so a top-level import here would pay that SDK-import cost for every command, not just `mcp serve`. See `docs/mcp-server.md` for the user-facing guide and `src/conductor/mcp/serve/` below for the server itself.
  - `fleet.py` - `fleet` group (`list`, `prune`). The **one deliberate deviation** from the `checkpoint`/`gate`/`registry` sub-app pattern: `fleet_app` sets `invoke_without_command=True` rather than `no_args_is_help=True`, because the bare `conductor fleet` (no subcommand) launches the interactive Textual TUI (Fleet Manager E7) — the TUI *is* the feature here, not a missing default. Do not "fix" this to match the other three sub-apps. The TUI is behind the optional `tui` extra; a `TEXTUAL_AVAILABLE` flag (checked only in the bare-invocation callback, mirroring `providers/aca.py`'s `AZURE_IDENTITY_AVAILABLE`) prints an install hint and exits non-zero rather than raising `ImportError` when `textual` isn't installed. That hint comes from `install_hint.py::install_command("tui")` and is printed with `soft_wrap=True` so rich never breaks the copy-pasteable command across lines — do not re-hardcode `pip install 'conductor-cli[tui]'`, which cannot work (issue #441). `fleet list`/`fleet prune` need no optional dependency. **`fleet list` also lists recently-completed runs, not just live ones (R1)** — a contract change to what the command means, bounded by `[fleet.retention].keep_last` and sourced from `fleet/records.py::read_terminal_records`; `--live` restores the exact pre-change scope. See `src/conductor/fleet/` below for the TUI itself.
  - `doctor.py` - `doctor` diagnostics rendering (thin presentation layer over `providers/diagnostics.py`)
  - `run.py` - Workflow execution command with verbose logging helpers. Forwards `--environment` through `resolve_environment` to engine constructors and dry-run preflight.
  - `bg_runner.py` - Background process forking for `--web-bg` mode. Forwards `--environment` (expanding `~` and absolutizing path-like values before building child argv). Captures the detached child's stdout/stderr to `$TMPDIR/conductor/conductor-<name>-<ts>-<runid>.bg.{stderr,stdout}.log` so silent crashes (uncaught Python exceptions, `faulthandler` dumps) leave a forensic trail — DEVNULL is **not** used for stdout/stderr. Passes `CONDUCTOR_RUN_ID`, `CONDUCTOR_BG_STDERR_LOG`, and `CONDUCTOR_BG_STDOUT_LOG` to the child via env so the child's `EventLogSubscriber` shares a run id with the bg log files and surfaces both paths in `workflow_started` system metadata. Returns a `BackgroundLaunch` dataclass (`url`, `stderr_log`, `stdout_log`, `run_id`, `workflow_started`, `still_running`, `run_record_written`). **The launch health gate's run-record poll is a readiness signal, not a kill switch** (Fleet Manager D2, hardened by issue #435): `_finalize_background_launch` waits for the dashboard to become reachable and then polls `conductor.fleet.records.read_run_record(run_id)` until the **child** has written its own record (matched on `mode`/`port`, and either `pid` equality or freshness — see below). If that poll's own 15s deadline passes while the child is confirmed alive and its dashboard is still reachable (a fresh 1s `_wait_for_server` re-probe), the gate logs a warning naming the run id and stderr log and lets the launch proceed with `run_record_written=False` rather than terminating a healthy workflow over a failed diagnostic write — `cli/app.py::_print_web_bg_no_run_record_notice` surfaces this to the user (verbose mode only, alongside the other `--web-bg` notices) and the `fleet` TUI's New Run screen does the same via a warning `notify()`. Only a child that is actually dead, or whose dashboard has gone unreachable, still fails the launch (terminate + raise), unchanged from before. The parent no longer writes a `.pid` file itself — `write_pid_file` (`cli/pid.py`) was removed as part of the original D2 change, since that was its only call site. Do not restore parent-side PID writing; a future bg-launch change belongs in this poll gate, not a reinstated `write_pid_file`. `launch_background_resume` adopts the run id from the resolved checkpoint (`_peek_resume_run_id`) instead of minting a fresh one, so the run record, `/api/info`, the events JSONL, and the capture-log filenames all agree on one id across a resume. **Readiness is three-staged.** Stage one, `_wait_for_server`, checks `proc.poll()` on every iteration of its socket-connect loop (keyword-only `proc` param), so a child that dies before binding the port is reported in well under a second instead of after the full 15s timeout. Stage one-and-a-half is the run-record poll above — a *stronger* signal than the `write_pid_file` it replaced, since the child only writes the record once it is executing. Stage two, `_wait_for_workflow_start`, polls `GET /api/info` for up to `CONDUCTOR_WEB_BG_START_TIMEOUT` seconds (default 30, `0` disables the probe) until the payload carries a `started_at` **key** (not truthiness — it can legitimately be `0`), proving the engine actually emitted `workflow_started` rather than just its HTTP server coming up (issue #410). `StartProbe` enumerates the four outcomes (`STARTED` / `CHILD_EXITED` / `PORT_CONFLICT` / `TIMED_OUT`), mirroring the `Liveness`/`Identity` enum pattern in `cli/pid.py`/`cli/app.py`. A `CHILD_EXITED` with a non-zero code (or `PORT_CONFLICT`, when `/api/info` reports an identity that positively does not match this launch's *confirmed* identity — see below) removes the child's run record via `_remove_dead_child_record` (identity-checked on `pid`, since a resumed launch can carry a checkpoint's original `run_id`) and raises `RuntimeError` with a bounded stderr-log tail (`_tail_log`); a clean exit-0 or a `TIMED_OUT` with the child still alive both return normally — the latter as `workflow_started=False`, which `cli/app.py` surfaces as a "still initializing" note rather than a failure. `still_running` is re-polled after the gate returns so a sub-second run is never advertised with a live dashboard URL. **Identity, not `Popen.pid`, is what stage two compares against (issue #444).** `Popen.pid` is not always the pid of the process that ends up running the workflow: a trampoline `sys.executable` (e.g. a Windows `uv tool install`, the documented install path) re-execs into a different one, so comparing stage two's `/api/info` payload against `proc.pid` produced a false `PORT_CONFLICT` on *every* port under that install path — and, one stage earlier, made the run-record poll's `pid == proc.pid` check never match the child's own record either, which is why the two symptoms (the spurious "did not report a run record" note, then the bogus port error) appeared together. `_confirmed_pid_from_record` accepts a record whose `pid` differs from `proc.pid` when the record is *fresh* (`_record_is_fresh`: its `started_at` parses to a timezone-aware timestamp at or after `launched_at`, captured immediately before `_spawn_detached`) — freshness is what a stale-record concern actually needs, and `proc.pid` equality was never it under a trampoline. Once a record is confirmed, its `pid` (not `proc.pid`) is carried forward as `confirmed_child_pid` and handed to `_wait_for_workflow_start`, which classifies the dashboard's reported identity (pid first, `run_id` as fallback) via `_classify_dashboard_identity`/`_DashboardIdentity` (mirroring `cli/app.py`'s `Identity`/`_confirm_identity`). A mismatch (`FOREIGN`) is only fatal when `confirmed_child_pid` is not `None`; an *unconfirmed* mismatch (`confirmed_child_pid is None` — the issue #435 downgrade path, or a resume whose predicted run id never matched) keeps polling instead of killing a possibly-healthy run on unproven suspicion, degrading at worst to the existing non-fatal `TIMED_OUT` note. The `PORT_CONFLICT` error message now names the foreign pid captured *before* `_terminate_child` runs (via the probe loop's own last-seen payload) rather than probing `/api/info` after the child is already dead, which previously always rendered `(PID unknown)`. **Termination reaches the whole process tree, not just `Popen.pid` (issue #447).** On Windows, `_spawn_detached_windows` creates the child suspended (`CREATE_SUSPENDED`) and assigns it to a fresh job object (`_create_job_object`, `JOB_OBJECT_LIMIT_BREAKAWAY_OK` set, deliberately **not** `JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE` so the tree outlives the launcher) *before* resuming its primary thread (`ResumeThread`, always called from a `finally` so a failed job assignment can never leave the child permanently suspended) — this closes the window a trampoline `sys.executable` could otherwise re-exec through before the job could be created. `_WindowsDetachedProcess` (the `Popen`-shaped wrapper this requires, since CPython's own `Popen` closes the child's thread handle before `__init__` returns, making suspend-then-assign impossible on top of it) exposes `terminate_tree()` (`TerminateJobObject`, reaching every process in the job regardless of exec depth). On POSIX, `start_new_session=True` already makes the child a process-group leader, so `os.killpg` is the equivalent — gated by `_SPAWNED_GROUP_LEADERS`, a registry of pids this module actually spawned, so it is never called against an arbitrary pid. `_terminate_child` now returns a `_TerminationOutcome` (`confirmed: bool`, `surviving_pids: tuple[int, ...]`) rather than a bare `None`: after the tree kill and the original single-handle terminate/wait/kill ladder, a final identity-checked sweep (`conductor.cli.pid.is_process_alive`/`terminate_process`) over every pid this call knows about (`proc.pid` and, if different, `confirmed_child_pid`) actually confirms the outcome instead of assuming it. `_remove_dead_child_record` is now keyed on the confirmed pid (via the shared `_cleanup_record_after_termination` helper) — but only fires once that pid is confirmed dead by the sweep, so a surviving orphan keeps the run record that is `conductor stop`'s only remaining handle on it. `_finalize_background_launch` has five terminate-and-raise branches; only the three with a pid to key on (dashboard-unreachable, `CHILD_EXITED`, `PORT_CONFLICT`) call `_cleanup_record_after_termination`. The other two — both inside the run-record-poll wait, one on a read failure and one on the poll's own 15s deadline going fatal — terminate without removing anything, because neither ever had a confirmed pid to begin with: no record was ever read successfully (or ever confirmed) on those paths, so there is nothing yet keyed to a pid for the helper to clean up. `_termination_note` renders the corresponding half of each failure message: "The background process was terminated." only when `confirmed` is true; otherwise a warning naming the surviving pid(s) and pointing at `conductor status` / `conductor stop --port`. A keyword-only `cwd: Path | None = None` (issue #477, default `None`) threads through `_spawn_detached_posix`/`_spawn_detached_windows`/`_spawn_detached`/`_spawn_bg_child`/`launch_background`/`launch_background_resume` to `subprocess.Popen(cwd=...)` (POSIX) / `_winapi.CreateProcess`'s `current_directory` argument (Windows, both call sites) -- the child's own `os.getcwd()` is what `engine/workflow.py` stamps as `system.cwd`. `None` on every existing CLI path, so `--web-bg`/`resume --web-bg` are unaffected; only the Fleet TUI's New Run screen (`fleet/launch.py`) supplies one. `_spawn_bg_child` validates `cwd` is an existing directory *before* opening the bg log files, raising a named `RuntimeError` rather than letting a bad path reach `Popen` as an indistinguishable `FileNotFoundError`. Both `launch_background` and `launch_background_resume` always invoke the child with `-P` (not a conditional env var), so the interpreter never puts the child's cwd on `sys.path[0]` -- a chosen directory containing a stray `conductor/` package would otherwise shadow the installed one -- without leaking a `PYTHONSAFEPATH` env var to the workflow's own `type: script` steps, which rebuild their environment from `os.environ` (see `executor/script.py`). The workflow path reaching `launch_background` must be absolute once a caller sets `cwd` -- see `fleet/launch.py` below, which is what actually absolutises it.
  - `pid.py` - **Legacy** PID file utilities, retained only so a still-running pre-upgrade background process (one that wrote its `.pid` file before Fleet Manager D2 removed `write_pid_file`) can still be discovered and cleaned up by `stop`/`fleet list`. Every current run path uses `conductor.fleet.records` (`run_id`-keyed JSON records) instead — see `fleet/records.py` below.
  - `self_run.py` - Answers "is this run record the run I am executing inside?" for `conductor stop`'s self-exclusion (issue #399: an agent smoke-testing `stop` must not terminate its own workflow). Three signals, first match wins: (1) `CONDUCTOR_RUN_ID` **or** `CONDUCTOR_SELF_RUN_ID` matching the record's `run_id` — the former is set on a `--web-bg` child, the latter is exported by *every* run (`cli/run.py`) into its own environment so descendants inherit it, which is the only working signal for a foreground run off Linux (no port for signal 2, no `/proc` for signal 3); the two are separate names because `engine/event_log.py` reads `CONDUCTOR_RUN_ID` as "adopt this run id", which a nested `conductor run` must not do; (2) `CONDUCTOR_WEB_BG`/`CONDUCTOR_WEB_PORT` matching the record's port, but *only* when the record has no `run_id` (the pre-#411 compatibility path — a record with a present-but-different id never falls back to this signal); (3) process ancestry (`/proc/<pid>/status` `PPid:` walk + `os.getsid(0)`), POSIX-only — Windows relies on signals 1–2 alone. `partition_own_run` splits run records into `others`/`own`; `stop` targets `others` unless `--allow-self` is passed. Since the Fleet Manager it operates on `RunRecord`s rather than PID-file dicts (`read_run_records()` already surfaces legacy `.pid` files in that shape), and `reasons` is keyed by PID rather than port because a foreground run has no port.
  - `update.py` - Update check and version comparison. Upgrades are delegated to the install script (`install.ps1`/`install.sh`); in-process self-upgrade was removed because on Windows the running Python interpreter sits inside the venv `uv tool install --force` is trying to recreate, which fails with "Access is denied". `conductor update` prints the OS-appropriate install-script one-liner; `conductor update --apply` spawns the installer detached (Windows: new console window; POSIX: `os.execvpe` replace) and exits the current process so file locks release. It also prints `_print_extras_note` — the extras `install_hint.py::installed_extras()` reads out of the uv receipt — because `--force` rewrites the tool's entire requirement set and an upgrade that named no extras used to silently uninstall `[tui]`/`[aca]` (issue #441); both install scripts read the same receipt and rebuild the source as `conductor-cli[<extras>] @ <source>`. The startup hint is suppressed by `CONDUCTOR_NO_UPDATE_CHECK=1`, `--silent`, `--help`/`--version`, and the `update` subcommand itself.

- **config/**: YAML loading and Pydantic schema validation
  - `schema.py` - Pydantic models for all workflow YAML structures (WorkflowConfig, AgentDef, ParallelGroup, ForEachDef, StepExecutionConfig, ExecutableStepBase, WorkflowDefaults, etc.)
  - `loader.py` - YAML parsing with environment variable resolution (${VAR:-default}) and `!file` tag support
  - `validator.py` - Cross-reference validation (agent names, routes, parallel groups, execution profile references)
  - `environment.py` - Execution environment documents: loading, discovery, and resolution. Discovers `.conductor/environments/<name>.yaml` (project ancestor walk up to git root) and `$CONDUCTOR_HOME/environments/<name>.yaml`. Whole-document shadowing (no merge, no inheritance). Plain YAML loading with no `${VAR}` expansion.

- **plugins/**: Plugin resolution — the *plugin* as the unit of opt-in (issue #378)
  - `manifest.py` - The one definition of what a plugin root looks like. Recognises **both** `.claude-plugin/plugin.json` and `.github/plugin/plugin.json` (the latter was the gap: 12 of 13 plugins on an ordinary machine use it, and both resolve at runtime, so recognising only the former was Conductor's own bug). Also parses `mcpServers` in all three forms — a **string path** like `".mcp.json"` (what every MCP-shipping plugin actually writes, so handling only the inline object would find zero servers on all of them), an inline object, or a conventional root `.mcp.json`. Deliberately a **leaf** (imports only `plugins/errors.py`) so `skills/registry.py` can import it without closing a cycle
  - `agents.py` - Parses `agents/*.agent.md` into `PluginAgent` specs named `<plugin>:<agent>`. `tools:` entries are the *host CLI's* vocabulary (`read`, `ado/*`) and are forwarded verbatim; `user-invocable` is deliberately not mapped (it gates a human menu, not model dispatch)
  - `registry.py` - `resolve_plugins(entries, base_dir, home, marketplaces, declared_sources)` → `ResolvedPlugin` (skills, agents, mcp_servers, dropped, disabled). Reuses `skills/registry.py::is_path_entry` and `expand_skills_root` so plugins add no second opinion about what a path entry or a skill directory is. Entry classification is three-way and **ordered**: path first (so `./tools/my@plugin` stays a path), then `plugin@marketplace`, then a bare installed name
  - `sources.py` - Parses the `plugin_sources:` source grammar (issue #380) into a `PluginSource`. Deliberately does **not** reuse `is_path_entry`: that returns `True` for anything containing `/`, so `owner/repo` would silently become a relative directory lookup. A local path is recognised by *prefix* (`~`, `.`, absolute) instead. Derives the three-segment `<host>/<owner>/<repo>` cache key, stripping credentials and ports so a token in a URL never becomes a directory name. A leaf module
  - `marketplace.py` - Reads a marketplace *catalog* out of a checkout. Recognises both `.claude-plugin/marketplace.json` and `.github/plugin/marketplace.json`, which — verified against a real repository shipping both — **anchor their per-plugin `source` differently** (repo-root-relative vs `pluginRoot`-relative), so both anchors are tried and whichever holds a plugin manifest wins. Catalog vs single-plugin is auto-detected; a repository that is both needs `plugin:` rather than having one picked for it. A catalog is fetched content, so a `source` or `pluginRoot` escaping the checkout is refused
  - `fetch.py` - Acquisition (issue #380). `git ls-remote` to resolve a floating ref, `git clone --depth 1` into a temp dir published by atomic rename, readiness sentinel written **last** so a concurrent reader never sees a half-clone. Cache at `$CONDUCTOR_HOME/cache/plugins/<host>/<owner>/<repo>/<sha[:12]>/`, matching `registry/cache.py::get_cache_base` rather than the `$XDG_CACHE_HOME` the issue sketched, so there is one cache root. The `_refs/<slug>.json` pointer is load-bearing: without a record of what a floating ref last meant, the offline fallback has no checkout to choose. Ref patterns include the `^{}` variants because git only emits the dereferenced line when asked — without them an annotated tag resolves to the tag *object*, a SHA no checkout ever equals
  - `resolution.py` - The single composition point between acquisition and resolution, analogous to `skills/discovery.py::resolve_effective_skills`. Both `conductor run` and `conductor validate` come through it and differ only in `allow_network`
  - `errors.py` - `PluginError(ValueError)` base + `PluginNotFoundError` / `PluginManifestError` / `PluginSourceError` / `PluginFetchError` / `PluginSourceUnavailableError`, mirroring `skills/errors.py`. The last is its own class because it is the one plugin failure that is *not* a problem with the workflow — the source is declared and well-formed and `conductor run` will fetch it — so `config/validator.py` downgrades it to a warning instead of an error
  - `conductor/plugins/__init__.py` re-exports **nothing** on purpose — `skills.registry` → `plugins.manifest` and `plugins.registry` → `skills.registry`, so an eager re-export would close that loop at import time
- **frontmatter.py**: `split_frontmatter(text)` — the shared `---` fenced-YAML splitter used by both `SKILL.md` and `agents/*.agent.md`. A leaf module (like `duration.py`) raising plain `ValueError` subclasses, so each caller phrases its own message. Exists because *both* formats are silently skipped by the downstream CLIs when the block fails to parse
- **skills/**: Skill registry and loader (opt-in, bundled skill content)
  - `registry.py` - Resolves `skills:` entries to on-disk directories — built-in names (probing editable-install + wheel-install layouts) and filesystem paths, including expanding a `skills/` root into its children. Also `resolve_skill_plugin`, which maps a directory to the Claude Code plugin that owns it
  - `discovery.py` - Scans well-known locations for installed skills (`runtime.skill_discovery`) and `resolve_effective_skills`, the single composition point for declared + discovered skills used by both `AgentExecutor` and `conductor validate`
  - `frontmatter.py` - Parses and validates `SKILL.md` YAML frontmatter with **ruamel.yaml**, requiring `name` + `description`. Exists because both downstream CLIs skip an unparseable skill *silently*; called from `resolve_skills` so `conductor run` is covered too, not just `conductor validate`
  - `loader.py` - Reads `SKILL.md` + `references/*.md` for providers that require eager preamble injection; wraps each skill in `<skill name="...">` tags inside a `<skills>` envelope. Bounded by `runtime.skill_injection`. `_read_file` **raises** `SkillManifestError` rather than logging and skipping — and since `lru_cache` never memoizes a raising call, a transient read error is retried instead of frozen for the run
  - `errors.py` - `SkillError(ValueError)`, the shared base for `SkillNotFoundError` / `SkillPluginError` / `SkillManifestError`. Its own module so `registry` and `frontmatter` can both use it without a cycle. Resolution and manifest failures originate in different modules but reach the same handlers, so call sites catch the one base rather than enumerating subclasses (`_check_skill_injection_budget` forgot one, and an unreadable `references/*.md` escaped `conductor validate` as a traceback)
  - Built-in skills live under `plugins/conductor/skills/<name>/` (bundled into the wheel via hatchling `force-include`)

- **engine/**: Workflow execution orchestration
  - `workflow.py` - Main `WorkflowEngine` class that orchestrates agent execution, parallel groups, for-each groups, and routing
  - `context.py` - `WorkflowContext` manages accumulated agent outputs with three modes: accumulate, last_only, explicit
  - `router.py` - Route evaluation with Jinja2 templates and simpleeval expressions
  - `limits.py` - Safety enforcement (max iterations, timeout)
  - `checkpoint.py` - Checkpoint save/load/list/cleanup + resume support. `save_checkpoint(error=..., trigger=...)` writes a top-level `trigger` typed `CheckpointTrigger = Literal["failure", "periodic"]`; `error=None` (periodic) writes null `failure.error_type`/`message`. No `CHECKPOINT_VERSION` bump — `trigger` is additive and any unknown/missing on-disk value normalizes to `"failure"` on load. `rotate_periodic_checkpoints` / `cleanup_periodic_for_run` both delegate to `_delete_periodic_checkpoints(..., keep_last, action)` (cleanup == rotate with `keep_last=0`), scoped to `trigger == "periodic"` **and** an exact `run_id` match so failure checkpoints and other runs' files are never touched. `find_latest_checkpoint` returns `list_checkpoints(...)[0]` (newest by microsecond `created_at`, not filename) so resume-latest isn't fooled by same-second periodic checkpoints. The engine saves a checkpoint inside its main-loop exception handlers; for a dashboard Stop/Kill that *cancels* the engine task from the CLI wrapper (bypassing those handlers), `WorkflowEngine.handle_dashboard_stop(message)` is invoked from `cli/run.py::_execute_with_stop_signal` after the cancelled task is drained — it writes a best-effort checkpoint and emits a single `workflow_failed` (flagged `stopped_by_user: true`, plus `checkpoint_path` or `checkpoint_unavailable_reason`). `handle_dashboard_stop` is idempotent via a dedicated `_dashboard_stop_handled` flag (not `_last_checkpoint_path`, which periodic checkpoints also set). Issues #244, #245. The listing command is `conductor checkpoint list` (the flat `conductor checkpoints` is a hidden deprecated alias, issue #275).
  - `validator.py` - `OutputValidator` runs the optional per-agent `validator:` block (issue #220): a second LLM call (synthetic agent via `provider.execute`, no tools, `{passed, issues}` schema) that grades the primary output against `criteria`. Fail-open on error/parse failure. The engine helper `WorkflowEngine._apply_validator` (in `workflow.py`) wires it into the main loop, parallel groups, and for-each loops; emits `agent_validator_start` / `agent_validator_complete` / `agent_validation_failed`; records a separate `"<agent> (validator)"` usage row; and re-runs the primary once with a `## Validation feedback` section on failure (`max_retries` hard-capped at 1), continuing the provider's in-memory conversation when the primary output carries a `continuation_state` and rebuilding the prompt statelessly otherwise (see the Validator block pattern bullet).
  - `guidance.py` - `GuidanceChannel` (issue #400): a `list[str]` buffer + `asyncio.Event`, the inbound half of the existing outbound guidance machinery (`WorkflowContext.user_guidance` → `get_guidance_prompt_section()` → `AgentExecutor.execute(guidance_section=...)`). `submit(text)` appends and sets the event (returns pending count); `drain()` pops everything and clears the event. Also `MAX_GUIDANCE_CHARS` + `validate_guidance_text(text)` — the shared "non-empty after stripping, at most 10,000 characters" check, called from both `POST /api/guidance` (`web/server.py`) and `resume --guidance` (`cli/run.py::parse_guidance_flags`) so a CLI-supplied entry can't skip the bound the HTTP path enforces. A leaf module with no conductor imports (like `duration.py`), so `web/server.py` never imports from `engine/` to hand the engine a sink callable.
  - `execution_resolution.py` - `ExecutionResolverSession` manages run-shared runner backends and workspace leases; `ExecutionResolver` provides per-engine views for root and sub-workflows.
  - `run_manifest.py` - `compile_run_manifest` resolves every executable step of the root workflow configuration against an execution environment document and pins the result in a run-invariant, byte-deterministic `ResolvedRunManifest` audit record.

- **execution/**: Stdlib-only execution-backend seam. Frozen contract types carry data-shaped command outcomes: a non-zero exit remains `completed` data for routing, while cancellation is not an outcome and propagates only after the backend kills and reaps its child. `RunnerBackend` exposes batch execution and run-scoped workspace lifecycle; `LocalRunnerBackend` is the reference subprocess implementation. In `run_command` the child is drained by a **shielded** `communicate()` task (`asyncio.wait_for(asyncio.shield(task), timeout)`), and both teardown paths (per-command timeout and outer cancellation) go through `_kill_and_reap`, which kills the child and then awaits the still-draining `communicate()` task and a shielded `process.wait()` task before returning — cancelling `communicate()` pauses the pipe transports, and a bare kill+`wait()` can otherwise wedge behind flooded pipe buffers even after the child is dead (PR #541 review, observed on the Windows CI fleet). A cancellation absorbed by that cleanup is re-raised afterward (or converted from a `timed_out` result back into `CancelledError`), never swallowed into a data-shaped outcome. A neutral diagnostics callback preserves verbose output without importing the CLI, and `ScriptExecutor` consumes the backend's `batch` capability at construction. The executor module intentionally retains `os`/`shutil` patch anchors so legacy tests patch the same module singletons used by the local backend. `WorkflowEngine` owns the `ExecutionResolverSession` (which manages backends and prepared workspace leases for the run) and creates an `ExecutionResolver` view for itself and child engines. The root engine prepares leases in `run()`/`resume()` (root-only, mirroring `_periodic_checkpoints_active`) and finalizes all leases in the matching `finally` with the succeeded/failed/cancelled outcome via `ExecutionResolverSession.finalize_leases()`. Finalization **detaches leases from session state first** — a repeated `run()`/`resume()` on the same engine instance must prepare fresh leases rather than reuse finalized handles — and runs `backend.finalize_run` as shielded tasks that absorb racing cancellations until teardown completes and then re-raise them. Sub-workflow child constructors inherit the session view, and `_execute_script` passes the per-step resolved backend and lease through.

- **executor/**: Agent execution
  - `agent.py` - `AgentExecutor` handles prompt rendering, tool resolution, and output validation for single agents
  - `script.py` - `ScriptExecutor` renders command fields, validates and counts UTF-8 stdin, delegates process execution to a per-call `RunnerBackend` resolved from the step's execution profile, and maps data-shaped outcomes back to the existing `ScriptOutput` / `ExecutionError` contract.
  - `set_step.py` - `SetExecutor` evaluates Jinja2 expressions for `type: set` steps and binds typed values into the workflow context (no LLM, no subprocess). Supports single `value:` and multi `values:` forms with auto / explicit `output_type:` coercion.
  - `wait.py` - `WaitExecutor` pauses workflow execution for a parsed duration via `asyncio.sleep`. Races the sleep against the engine's `interrupt_event` so Esc/Ctrl+G cancels in-flight waits immediately; the workflow-level `limits.timeout_seconds` also cancels it via `LimitEnforcer.wait_for_with_timeout`. Output contract is strictly `{"waited_seconds": float}` per issue #218.
  - `template.py` - Jinja2 template rendering
  - `output.py` - JSON output parsing and schema validation. `validate_output` is deliberately **strict with no coercion** — it also validates `set` and `script` step output, where silently reshaping an authored value would be surprising. Response normalization belongs in `providers/_output_shape.py` instead. Note `parse_json_output` raises `ValidationError` for JSON *syntax* errors, so callers cannot distinguish syntax from schema failures by exception type alone.

- **runner/**: The serialized wire contract between the CLI host and a remote agent runtime (issue #527) — `protocol.py` holds the Pydantic models (`RunnerAgentRequest`/`RunnerAgentPayload`, `RunnerEventFrame`, `RunnerAgentResult`, `RunnerErrorData`, `RunnerHealthResponse`), `RUNNER_TOKEN_HEADER`, `RUNNER_PROTOCOL_VERSION`, and the `request_to_wire_body` wire-serialization step (the only place credential plaintext exists — `inner_provider_settings` secrets are `SecretStr` everywhere else). Boundary: `conductor.execution` is the in-process Python backend seam (stdlib-only); `conductor.runner.protocol` is the serialized contract for a *remote* runtime whose version deploys independently of the host (response-side models `extra="ignore"`, request-side `extra="forbid"`, evolution additive-only). `__init__.py` re-exports nothing (precedent: `plugins/__init__.py`) — imports go via `from conductor.runner.protocol import ...`. Lifted de-ACA'd from `providers/aca_protocol.py`; the reference remote runtime is `conductor-agent-runner` (`docker/aca-runner/Dockerfile`).

- **duration.py**: `parse_duration(value)` shared helper. Accepts plain `int`/`float` seconds, or strings with `ms`/`s`/`m`/`h` suffix. Raises `ValueError` (nests cleanly inside Pydantic `ValidationError`). Rejects booleans. Bounds enforcement (e.g. > 0, 24h cap) lives in callers so the parser can be reused.

- **filesystem.py**: `stat_or_none()` / `exists_strict()` / `is_dir_strict()` / `is_file_strict()` — path probes with pre-3.14 `pathlib` error semantics (issue #540). Python 3.14 rewrote `pathlib` so `Path.exists()`/`is_dir()`/`is_file()` delegate to `os.path` and swallow *every* `OSError` — including `PermissionError` — returning `False`; on 3.13 and earlier they re-raised anything outside a small allowlist (`ENOENT`/`ENOTDIR`/`EBADF`/`ELOOP`, plus winerrors 21/123/1921, mirrored here from `Lib/pathlib/_abc.py::_ignore_error`). Conductor's path diagnostics distinguish "does not exist" from "could not be read", which requires the older semantics on every interpreter — without these probes an unreadable skill/plugin path is misreported as missing, and an unreadable skills-root subdirectory is silently misfiled as a near-miss. The probes follow symlinks (matching their pathlib counterparts) and swallow `ValueError` (non-encodable path) into `None`, exactly as pathlib did. A stdlib-only leaf (like `duration.py`, `console.py`, `rundir.py`) so `skills/`, `plugins/` and `cli/` can all depend on it without an import cycle.

- **run_id.py**: `RUN_ID_PATTERN_SOURCE` / `is_valid_run_id()` / `new_run_id()` — the single fleet `run_id` contract (issue #435). A stdlib-only leaf (like `duration.py`/`rundir.py`) with no conductor imports, so `engine/event_log.py` (an always-on module) can depend on it without importing `conductor.fleet.records`, which would drag in `conductor.cli.pid` and, via `conductor.cli.__init__`'s `from conductor.cli.app import app`, close an import cycle — the same hazard `rundir.py`'s docstring documents. Before this module existed, `fleet/records.py` and `engine/event_log.py` each enforced their own copy of the rule (a broad path-safe pattern vs. a narrower hex-only one that also lowercased its input), so a checkpoint `run_id` the fleet accepted could be silently folded into a different value by the event log, making a parent's launch-gate poll (`cli/bg_runner.py::_finalize_background_launch`) look for a key a resumed child never wrote and kill an otherwise-healthy run. `RUN_ID_PATTERN_SOURCE` is exported as a source string (not just a compiled pattern) so filename parsers that need to anchor a `run_id` inside a larger regex (`fleet/history.py`, `fleet/retention.py`, `fleet/records.py`'s own `_LOG_STEM_TIMESTAMP_RE`) interpolate it directly instead of restating the charset. `fleet/records.py` re-exports `is_valid_run_id` for backward compatibility with existing importers (`cli/bg_runner.py`, the test suite) rather than owning the contract itself.

- **console.py**: `make_console()` / `styled()` / `join()` — the markup-safety primitives (issue #406). A leaf module (like `duration.py`) with no conductor imports, deliberately **top-level rather than under `cli/`** because `gates/` and `providers/` need it and must not import from `cli/`. `make_console` locks `markup=False`, inverting Rich's default so an interpolated runtime value is literal unless it asks to be styled; it *rejects* a `markup=` kwarg rather than allowing an override — on the constructor and on `print`/`log`, since rich's per-call `markup=True` would otherwise reopen the defect from a single line. `styled("<template>", ...)` parses the template's markup — conductor's own literal — while inserting values verbatim. It works by replacing each field with a **length-matched filler run**, parsing once, then locating each run to substitute the value back: matching the width keeps the parsed template's spans valid, which is what makes nested styling around a placeholder (`[bold][red]{}[/red][/bold]`) come out right. Reading `spans[0].style` and re-applying it — the obvious alternative — collapses the nesting. A value that is already a `Text` is spliced in with its own spans re-anchored, so pre-styled fragments compose (`styled("{} {}", CHECK, name)`); without that, `format()` would flatten it and silently drop the colour from every doctor table cell. `join(sep, parts)` exists because `Text.join` requires every part to already be a `Text`, while the common shape here is a `content_lines` list mixing conductor-styled fragments with plain runtime values. `rich.markup.escape` is deliberately unused throughout: the parser treats `\[` as an escaped bracket, so `\[0-9\]+` renders as `[0-9\]+` whether escaped or not, whereas a `Text` is byte-exact. See the Console Output section under Code Style.

- **providers/**: SDK provider abstraction
  - `base.py` - `AgentProvider` ABC defining `execute()`, `validate_connection()`, `close()`
  - `_output_shape.py` - `normalize_agent_output(content, schema)` — the single entry point providers call before `validate_output` (issue #343). It raises `ValidationError` when the parsed response is not a JSON object (a bare `42`/`null`/array), because `validate_output` would otherwise either raise `TypeError` from a membership test (numbers, booleans, null) or report a misleading "missing required field" (strings, arrays). It then applies `unwrap_scalar_wrappers`: fires only when the schema declares `string`/`number`/`boolean`, a `dict` arrived, and **exactly one** candidate slot has the expected type. Candidate slots are the field's own name plus the generic `value`/`result` keys, deduped so a field literally named `value` or `result` isn't rejected as ambiguous against itself. Two matches count as ambiguous; any other key shape is ignored. Both are left untouched (same object identity) so the caller re-prompts rather than guessing — this is what stops `{"answer": {"error": "..."}}` being laundered into an answer. Every unwrap logs a warning, naming discarded sibling keys when there are any. Kept out of `executor/output.py` on purpose — see the note there.
  - `_recovery_prompt.py` - `build_parse_recovery_prompt(...)` — the plain-text re-prompt shared by Copilot and Hermes (issue #343). Both providers correct an unusable response the same way (error + truncated response + rendered schema, with distinct schema-failure vs syntax-failure wording), and that text is covered by the provider-parity rule, so it lives in one place instead of two copies free to drift. Claude is deliberately not a caller: it re-prompts through its `emit_output` tool and never echoes the schema, so its instruction text stays in `claude.py::_build_recovery_instruction`.
  - `copilot.py` - GitHub Copilot SDK implementation. By default spawns a nested `copilot` runtime via `CopilotClient()` (in `_build_client`, called from `_ensure_client_started`). When a runtime connection is resolved (`runtime.provider.runtime_url` or `COPILOT_PROVIDER_RUNTIME_URL`, optional `runtime_token` / `COPILOT_PROVIDER_RUNTIME_TOKEN`), it instead builds `CopilotClient(connection=RuntimeConnection.for_uri(url, connection_token=token))` to connect to an already-running `copilot --headless` process; the SDK skips spawning for URI connections and its `stop()` leaves the externally-owned server running. `_resolve_runtime_connection()` reads YAML first, then the namespaced env var (env activates on its own — the zero-YAML path for external orchestrators). Runtime transport can be combined with custom model-provider routing. `_ensure_client_started()` also detects a spawned runtime whose child process has died (issue #483, `_runtime_is_dead()` polling the SDK's private `_cli_process` handle) and rebuilds the client under `_start_lock` (`_restart_spawned_runtime`) before returning, so the next SDK call lands on a fresh runtime; the rebuild invalidates `_client`/`_started` before constructing and starting the replacement, so a failed rebuild (e.g. OOM at spawn) cannot leave the provider believing a never-started client is started. A fixed, non-configurable cap (`_MAX_CONSECUTIVE_RUNTIME_RESTARTS`) on consecutive restarts with no intervening successful call prevents an infinite crash loop; a broken connection to an externally-owned runtime is never respawned. `_spawned_runtime_process` reads `_cli_process` (the spawned-child handle, `None` for URI and FFI connections) while `_fix_pipe_blocking_mode` reads `_process` (the transport handle — a `SocketWrapper` in TCP mode, an `_FfiProcessAdapter` with its own `poll()` in FFI mode); both are correct for their own purpose, and unifying the two reads onto `_process` would make FFI mode look like a killable child process.
  - `claude.py` - Anthropic Claude API provider using `pydantic-ai` (`AnthropicModel`) and the internal `_pydantic_ai` package (`converters`, `events`, `mcp_toolset`, `agent_builder`, `interrupt`, `retry`, `structured_output`, `usage`)
  - `claude_agent_sdk.py` - Claude Agent SDK implementation (uses `claude-agent-sdk` package)
  - `factory.py` - Provider instantiation

- **gates/**: Human-in-the-loop support
  - `human.py` - Rich terminal UI for human gate interactions. `read_multiline_lines(console, sentinel)` is the shared blocking multi-line stdin reader behind both the human gate's `.` sentinel (`MULTILINE_SENTINEL`) and the dialog gate's `/send` (`DIALOG_SUBMIT_SENTINEL`); it returns `(text, hit_eof)` because an EOF that yielded no text is a deliberate dismissal while the sentinel with no text is an empty submission. `sentinel` is keyword-only and required, since the two gates use different ones
  - `dialog.py` - Dialog-mode gate. On a tty the main turn reads through `read_multiline_lines`, so a pasted block is one turn rather than one turn per line; off a tty it falls back to single-line `Prompt.ask`, where the sentinel has no effect — the `_reads_multiline_turn()` predicate states that rule once, and `_display_dialog_start` gates its sentinel hint on it so the banner never advertises a keystroke the reader ignores. Both submission guards compare against stripped text: the reader drops trailing newlines but keeps a whitespace-only line, so an exact `== ""` check would dispatch whitespace as a turn and turn Ctrl-D into a submission

- **interrupt/**: Interactive workflow interruption (Esc/Ctrl+G to pause)
  - `listener.py` - Keyboard listener daemon thread for Esc/Ctrl+G detection

- **fleet/**: The Fleet Manager (`conductor stop` run-record scope, `conductor fleet`) — see `docs/fleet.md` for the user-facing guide. Fixes the bug where a plain `conductor run` (no `--web-bg`) was invisible to `conductor stop`/discovery: every run path now writes a `run_id`-keyed JSON record (not the legacy port-keyed `.pid` file `cli/pid.py` used to write) describing its mode/PID/workflow/port, so foreground, `--web-bg`, and `--web` runs are all discoverable the same way.
  - `records.py` - `RunRecord` (nine fields, no more — a tenth `tty` field was considered and rejected as POSIX-only with `pid` already sufficient; `mode` is a `RunMode = Literal["fg", "fg-web", "bg"]` so the single write site is checked by `ty`, and an *unrecognised* mode read from disk normalises to `"bg"` rather than raising — a raise reaches `_read_and_prune` as `corrupt`, which deletes **without checking liveness**, so a newer Conductor's mode would make an older one delete a live run's record) + `write_run_record` / `read_run_records` / `read_run_record` / `remove_run_record` / `remove_run_record_for_current_process`. `read_run_records()` filters to processes that pass `cli.pid.is_process_alive` and tolerates legacy port-keyed `.pid` files (surfaced as `mode="bg"` records) alongside corrupt/partial JSON. Every Windows sharing-violation-prone operation — `os.replace` on write, `os.unlink` on remove (`_safe_unlink`), `os.rename` into quarantine on self-cleanup (`_delete_if_unchanged`), and `os.link` on quarantine restore (`_restore_if_absent`) — goes through one bounded retry helper (`_retry_on_windows_sharing_violation`, issue #486), so a transient reader no longer makes a delete fail outright; a violation that outlasts the retry budget is still logged and reported as `False` rather than silently succeeding. Also defines `TerminalRunRecord` (R1, DD1, P3, G5): a small tombstone `cli/run.py`'s `finally` block writes to `terminal_records_dir()/<run_id>.json` — a dedicated subdirectory of the run-records directory, deliberately **not** alongside the live record, since `read_run_records()`'s and `remove_run_record_for_current_process()`'s non-recursive `*.json` globs would otherwise treat a same-directory tombstone as a corrupt live record (deleted regardless of liveness) or race it against the record it is meant to replace. It carries terminal status (`success`/`failed`), rendered `output:`, error type/message on failure, usage totals, and the run's event-log/capture-log paths, so a `run_id` answers "how did that run finish" after its process has exited — the artifact both `conductor status`/`conductor fleet list`'s completed-runs section (R1, see `cli/app.py`/`cli/fleet.py` below) and the MCP server's `conductor_run_status`/`conductor_run_events`/`conductor_run_logs` tools (`mcp/serve/`, below) read from. `write_terminal_record` / `read_terminal_record` / `read_terminal_records` / `remove_terminal_record` mirror the live-record API; pruning is `fleet/retention.py`'s job (DD13), matched by `run_id` to the same event log so a record never outlives — or is outlived by — the log it points at.
  - `resume.py` - The fleet layer's first checkpoint consumer (issue #460): `correlate_checkpoints(entries)` joins History's `HistoryEntry` rows against `engine/checkpoint.py::CheckpointManager.list_checkpoints`'s on-disk checkpoints for the History screen's Resume action. The join key is the **event log path** (normalized via `os.path.realpath`, since both sides ultimately derive from `tempfile.gettempdir()`), with `run_id` as a documented fallback that is refused whenever that id is ambiguous across the scanned entries (a nested `conductor` invocation inherits `CONDUCTOR_RUN_ID`, so two logs can share one id). Gating a row's Resume availability is **checkpoint existence + the checkpoint's recorded `workflow_path` existing on disk — never `outcome`**: an `unknown` row from a crash is exactly the case a periodic checkpoint exists for, and a `completed` row can correlate to a stale checkpoint too (re-executing already-finished work is accepted, mitigated only by surfacing the checkpoint's provenance in the UI, not by hiding the key). Kept out of `fleet/history.py` deliberately — that module's docstring is emphatic that History is derived from event logs alone, and `build_history_entries` is patched by name in several existing tests.
  - `summary.py` - Derives a `RunSummary` (status/current-step/elapsed/tokens/cost/gate) from a **streamed, uncapped** read of a run's JSONL event log (issue #485) — `stream_event_log` is bounded only by the longest single line, not by file size or event count, replacing three separate bounded windows (a 512 KiB tail, a 512 KiB head recovery read, and an 8 MiB full-log cap) that a long or resumed run had already outgrown in production (a real 9.72 MB / 20,361-line log lost its current step, its token/cost totals, and — via the head window never firing for a *resumed* run's second `workflow_started` — reported the wrong topology). The Runs screen's ~2s poll passes `keep_types=_SUMMARY_EVENT_TYPES` so the reader skips an uninteresting line via a cheap regex prefilter without JSON-parsing it (12.5 ms measured against that same 9.72 MB log, vs. 65 ms unfiltered); the run-detail/step-detail screens read unfiltered since they need every event type. `_scan_events` is **generation-aware**: a resumed run always writes a second root `workflow_started` into the same log (the engine's own re-emit, or the dashboard-seeding path's synthesized copy), and reaching one resets `status`/`gate`/open steps and overwrites `topology`/`workflow_name`/`cwd`/`inputs` with the new generation's own — but does **not** reset token/cost totals, which accumulate across every generation (a resumed run's lifetime usage, not just its latest attempt's). Status is derived from explicit event markers (`gate_presented`/`gate_resolved`/`workflow_completed`/`workflow_failed`), never inferred from timing alone — the design's own measurement found that unreliable (228 false positives, 0 true positives). `gate_resolvable` (Fleet Manager D4) is computed once here: `True` whenever the record has a dashboard port (`fg-web`/`bg`), `False` for `mode == "fg"`.
  - `history.py` - Enumerates every retained run directly from `$TMPDIR/conductor/*.events.jsonl` files (not run records, which are already gone by the time a run is history) for the History screen, regardless of outcome. Classifies each log by its terminal event (`workflow_completed`/`workflow_failed`); a log with neither is `"unknown"`, **never** `"running"` — the same non-inference constraint `summary.py` follows, sharpened here since there is no run record to fall back on at all. The returned list is bounded by `[fleet.retention].keep_last` and, independently, by a fixed 200-entry display cap (so a `keep_last` configured below 1 — "unbounded" for the pruning sweep — still cannot grow the History screen without limit). `_read_full_log` (a single-pass generator feeding `_scan_history_events`) now delegates its actual line-reading to `summary.stream_event_log` (issue #485), which generalized the uncapped-streaming approach History pioneered first; it re-derives its own corrupt-vs-empty distinction from `path.stat().st_size` rather than a raw non-blank-line count, since the shared reader has no reason to track that for a live run's cheap repeated poll. `_scan_history_events` takes the **latest** root `workflow_started`'s timestamp as `started_at` (issue #485, Q2) — mirroring `summary.py`'s generation-reset — so a resumed run's `duration_seconds` fallback (`ended_at - started_at`, used absent an engine-reported `elapsed`) measures the current attempt, not the idle gap since the original one; `_scan_history_events` must therefore stay a single forward pass over its `Iterable` argument (issue #436). Each `HistoryEntry` is then enriched (`_enrich_with_terminal_record`, R1) with its rendered `output:` and failure error type/message from `records.py::read_terminal_record(run_id)` when one exists — the two fields the design named History as lacking — leaving them unset for a pre-upgrade log with no matching terminal record rather than treating a missing enrichment as corrupt data.
  - `launch.py` - Resolves a file path or registry reference (reusing `registry/resolver.py::resolve_ref` + `registry/cache.py::resolve_and_fetch`, the same pair `conductor show` uses) and calls `cli.bg_runner.launch_background()` directly for the New Run screen — never re-implements detached process spawning, per the design's explicit warning that doing so would make a TUI-launched run die with the TUI. `launch_resume(checkpoint_path, ...)` (issue #460) is the same pattern for the History screen's Resume action: it calls `cli.bg_runner.launch_background_resume(workflow_path=None, checkpoint_path=...)` directly rather than re-implementing detached spawning, since a `HistoryEntry` carries no workflow path of its own and the checkpoint is the only route to one. Both `resolve_workflow` and `launch_workflow`/`launch_resume` take the Fleet Manager's launch directory as an explicit argument (issue #477) -- `base_dir` on the former, `cwd` on the latter two, forwarded to `cli.bg_runner.launch_background()`/`launch_background_resume()` -- rather than ever reading the process cwd, so this module stays a pure function of its arguments; `fleet/tui/app.py::FleetApp.launch_dir` is the one place that directory is actually decided. `resolve_workflow` joins a relative *file* reference onto `base_dir` (a registry reference and an absolute reference both ignore it) and always returns an absolute `ResolvedWorkflow.path` -- `Path(os.path.abspath(...))`, not `.resolve()`, matching `_resolve_agent_working_dir`'s "normpath, not resolve" convention so a symlinked project directory stays the alias the user typed. Absolutising is not optional: `launch_background` puts `str(workflow_path)` straight into a detached child's argv, and a relative path there resolves against whatever cwd that child happens to inherit, not the directory it was typed against.
  - `retention.py` - `prune_event_logs(keep_last, dry_run)` bounds `$TMPDIR/conductor/*.events.jsonl` (Fleet Manager D3), mirroring `CheckpointManager.rotate_periodic_checkpoints`'s `keep_last` vocabulary. Never deletes the `checkpoints/` subdirectory or an event log a live/resuming run still references; a retained/live log's `.bg.stderr.log`/`.bg.stdout.log` companions are kept or pruned alongside it. `maybe_prune_event_logs()` is the opportunistic-startup-sweep wrapper `cli/run.py` calls, gated by `[fleet.retention].enabled` and never raising.
  - `tui/` - The Textual app (`app.py`, `Screen` push/pop stack) and its screens (`screens/runs.py` home; `screens/run_detail.py`; `screens/step_detail.py`; `screens/providers.py`; `screens/registries.py`; `screens/new_run.py`; `screens/history.py`; `screens/splash.py`), plus `actions.py` (shared stop/kill/gate-respond logic, reusing `cli/app.py::stop_records` and `cli/gate.py::_gate_respond_impl` rather than duplicating either), `theme.py` (the single status glyph/label/colour vocabulary — screens must not define local glyph maps), `dag.py` (step-status chips), `anim.py` (pure frame→glyph functions; animation is off by explicit `CONDUCTOR_FLEET_NO_ANIM`, on by explicit `CONDUCTOR_FLEET_ANIM`, off by default on a detected RDP session (`SESSIONNAME` starting `RDP-Tcp`) via `is_remote_session()`, and on otherwise — `CONDUCTOR_FLEET_NO_ANIM` always wins. **SSH is deliberately not detected**: it ships the ANSI byte stream for the local terminal to render (a few hundred bytes per frame), where RDP renders remotely and diffs/encodes/ships changed *pixel regions*, so only the latter is costly — and the real trigger is a *slow* link, for which there is no signal, only "SSH at all", which is usually fast. `CONDUCTOR_FLEET_NO_ANIM` is the remedy there and for VNC/Citrix/xrdp; a negative test pins this so it is not re-added as an oversight; any path that disables animation — explicit `CONDUCTOR_FLEET_NO_ANIM` or detection — also sets Textual's own `App.animation_level = "none"` in `app.py::on_mount`, issue #462), `art.py`, `widgets.py`, and `notify.py` (terminal bell / OSC 9 notifications, debounced to fire once per status transition). Optional: imported only by `conductor fleet`'s bare invocation, gated behind the `tui` extra (floor `textual>=8.0` — `widgets.py::BlockFooter` is written against 8.x `Footer` group rendering). The install command for that extra is resolved per install context by `install_hint.py`, never hardcoded. **No blocking I/O on the event loop** (issue #437): every screen that reads the filesystem *on a timer, or on a path that can be slow*, does it in a worker (`@work async def` + `await asyncio.to_thread(<collector>)`), with the render half running on the event loop after the `await` — the pattern `screens/new_run.py::action_resolve`/`action_launch`, `screens/step_detail.py::load_step` and `screens/registries.py::load_workflows` established first, now also `screens/runs.py::_refresh_worker`/`_open_dashboard_worker`, `screens/run_detail.py::_refresh_worker`, `screens/history.py::load_history`, and (not a screen, but the same reasoning) `actions.py::kill_runs`. Two deliberate exceptions, both documented at their definition: `registries.py::load_registries` reads one local `registries.toml` inline, and `providers.py::load_providers` is a `@work` method awaiting a natively async `gather()` — note that `gather()` still does its offline SDK-availability imports synchronously, so it is *not* yet an instance of this pattern. The **two polled** screens (`runs.py`, `run_detail.py`) additionally keep their `refresh_runs()`/`refresh_detail()` entry point as a **synchronous dispatcher** (still callable from `on_mount`, `set_interval`, and action handlers) guarded by a plain `_refreshing` boolean, so a tick arriving mid-scan is **dropped** rather than started alongside the in-flight one — deliberately not `@work(exclusive=True)`, which would cancel the in-flight worker ("newest wins") instead of skipping the newer tick. Load-once screens (`history.py::load_history`) need no guard and are `@work` methods directly. The flag is set in the *dispatcher*, not as the worker's first line, because a `@work` body doesn't start until Textual schedules it; and it is released in a `finally`, because without that one transient error stops the screen refreshing for the rest of the session, silently and indistinguishably from a calm fleet. An **explicit** refresh (`_kill_and_refresh`, `action_resolve_gate`'s `finally`) passes `explicit=True` and is *coalesced* via `_refresh_pending` rather than dropped: those callers promise the table reflects what they just did, and the scan they collide with started before it. Every screen shows `theme.py::loading_text()` in `compose()` until its first result lands. **A failed load is surfaced, never degraded into an empty state** — rendering "No runs" or "No run history yet" for an unreadable directory is a positive claim of absence that reads as success, so `runs.py` distinguishes an empty fleet from one whose summaries all failed (`RunScan.failed`/`seen_run_ids`) and `history.py` follows `step_detail.py`/`registries.py`'s red-error-line convention. `RunScan.seen_run_ids` carries *every* record read, not just the rows that rendered, because the notifier is pruned against it — pruning against the rendered rows made a run whose summary briefly failed look brand-new and re-fire its gate notification. Test caution: a pilot test that presses a key opening a modal (kill confirm, gate options), or that deliberately suspends a worker on a `threading.Event`, and then needs a second keypress to resolve it, must use a plain `await pilot.pause()` between the two, never `tests/test_fleet/conftest.py::settle` — `settle` awaits `app.workers.wait_for_complete()`, and the suspended `@work` method won't finish until that second keypress, so awaiting it first deadlocks the test. `history.py` also correlates checkpoints in the same `load_history` worker as a second thread hop (issue #460, `conductor.fleet.resume.correlate_checkpoints`), gating its `r`/Resume binding via `check_action` the same way `runs.py` gates `g`/Gate -- hidden outright when the highlighted row has no correlated checkpoint, refreshed on `on_data_table_row_highlighted` so the footer never shows yesterday's answer as the cursor moves. **The frame timer (~10fps, `runs.py::_tick`) may only repaint what actually moves** (issue #462): the animated table cells and the preview pane's `#run-preview-score` widget. Everything else in the preview pane (the gate section, the `Progress N/M` header), and the footer's `refresh_bindings()`, belong to the ~2s data poll (`_update_gate_detail`) and to selection changes — that is the invariant a future edit is most likely to break by re-adding a convenient `_update_gate_detail()` call to `_tick`. `app.py::FleetApp.launch_dir` is an app-level, **process-lifetime-only** Textual `reactive[Path]` (issue #477) -- no `config.toml` key, no state file, reset to the process's cwd on the next `conductor fleet` -- read by `screens/new_run.py` (the base a relative workflow reference resolves against, and the `cwd` a launched run's detached child inherits) and mutated only through `FleetApp.set_launch_dir`, matching this module's `push_*`/`return_to_runs` one-named-mutation-site convention. `actions.py::DirectoryPickerModal` (opened via the shared `change_launch_directory`, bound to `d` on Runs and `ctrl+d` -- `priority=True`, since `Input` binds it first -- on New Run) is the only way to change it; a bad path is rejected in place (a red message line, modal stays on the stack) rather than dismissed. Its tree→input mirror (`on_tree_node_highlighted`) fires **only while the tree has focus** (issue #486): Textual posts a `NodeHighlighted` for the tree's own root as soon as the background `DirectoryTree` load lands, with no user interaction at all, and mirroring that automatic highlight silently replaced the prefilled launch directory with its *parent* before the user ever touched the tree. `widgets.py::BlockFooter` passes `show_command_palette=False` to `Footer.__init__` (a real 8.x kwarg) so the Runs footer's docked `^p palette` key -- not `ctrl+p` itself, which still opens it -- is hidden, reclaiming the columns `d Dir` needed once `Providers`/`Registries` were also shortened to `Prov`/`Regs`.

- **mcp/**: `manager.py` is the existing MCP *client* (Conductor calling MCP tools, `runtime.mcp_servers`) — untouched by the server work below, though `pyproject.toml`'s `mcp>=1.28.1,<2` bound protects it too (a `mcp` 2.0.0 lock refresh renames the camelCase attributes it reads, e.g. `Tool.inputSchema` -> `input_schema`, turning every MCP tool connection into a runtime `AttributeError` with no import error to catch it).
  - `serve/` - `conductor mcp serve` (issue #432, `cli/mcp.py` above): exposes Conductor workflows as MCP tools to any MCP-compatible host over stdio. The organising principle is that **the server owns no execution state** — it is a protocol adapter over three existing subsystems it never duplicates: the registry (catalogue), `cli/bg_runner.py::launch_background` (every invocation forks a real detached `conductor run`, never executing a workflow in-process), and `fleet/` (every status/event/log query reads the same records and event logs the TUI does). `options.py` (`ServeOptions`, frozen) holds every startup argument — the single place NFR3 ("no tool accepts a filesystem path, URL, or registry source") is checkable at all, since any value not on it did not come from the operator. `catalogue.py` (`build_catalogue`) turns configuration into an immutable, byte-identical-per-connection list of `mcp.types.Tool`s (DD3): the four-rung exposure ladder (`--deny` > `--allow` > workflow `mcp.expose` > default-on, DD4), a three-tier schema resolution ladder with a permissive `degraded` fallback rather than a silent drop (NFR2), and pinning every exposed workflow to an immutable identity (commit SHA or content hash, DD6). `naming.py` / `sanitize.py` / `toolgen.py` are the catalogue's naming (bare names, registry-qualified only on collision, DD10), description-sanitizing (NFR4), and JSON-Schema-generation (from `WorkflowDef.input`; **no `outputSchema`**, DD5) helpers. `pinning.py` computes and re-checks the DD6 identity. `server.py` wires the frozen catalogue onto `mcp.server.lowlevel.Server` and runs it over `mcp.server.stdio.stdio_server()`, prints the FR10 startup summary to a **stderr-bound** console (stdout is the JSON-RPC transport, DD9 — nothing else may touch it), and — for the `introspect`/`diagnose` toolsets, decided once at startup and never per-request (DD3) — dispatches to `introspect.py` (`conductor_run_events` with tool payloads reduced to `{name, status, byte_size}` unless `--introspect-full`, R4; `conductor_node_detail`; `conductor_plan_tree`) and `diagnose.py` (`conductor_doctor`, `conductor_validate_workflow`, and `conductor_run_logs` — `ResourceLink`s and bounded metadata **only**, never file contents, DD12). `invoke.py` launches a generated workflow tool's run and resolves its reserved `_wait_seconds` parameter (FR5) — **never** passes `skip_gates=True` to `launch_background` (DD11, asserted in a code comment naming the decision), and enforces `--max-concurrent-runs` via an in-process `LaunchTracker` (R3; resets on restart, consistent with "the server owns no execution state"). **Non-blocking is the intended path and the tool schema has to say so**: a model reading the original `_wait_seconds` description — three equally-weighted options with no recommendation — passed `_wait_seconds: 300` unprompted and held its turn open for a five-minute run that was detached the whole time, which reads to a user as "the MCP server runs workflows in the foreground". So the description leads with *leave this unset*, states that the run is detached either way, and says setting it blocks only the caller's own call; the returned handle carries `port`, an `observe` block of terminal commands, and the capture-log paths so the caller has something to report instead of a reason to wait; and the immediate `next` action names `conductor fleet` before `conductor_await_run`, which it conditions on the user having actually asked to block. `server.py::_DISCOVERY_TOOLS` hand-writes a second copy of that same parameter's schema, so `tests/test_mcp/test_serve_toolgen.py::TestWaitSecondsSteersTowardBackground` asserts both copies steer identically. Every command in `observe` is resolved against the real Typer app by `tests/test_mcp/test_serve_invoke.py::test_every_observe_command_actually_exists_in_the_cli` — a plausible-looking invented one (`conductor fleet list --json`, which shipped in a draft and does not exist) fails in front of the user at the exact moment they were told how to watch their run. The operator-side hard guarantee is `--max-wait-seconds 0`: the ceiling applies to every blocking path including the `mode: sync` branch, so no invocation can block at all. `runs.py` is the `runs` toolset (`conductor_run_status`/`conductor_await_run`/`conductor_cancel_run`/`conductor_list_runs`), resolving a `run_id` through a live record, else the `fleet/records.py::TerminalRunRecord`, else an event-log fallback for a crashed run — the same three sources named which one answered. `discovery.py` is the two-tool fallback (`conductor_find_workflow`/`conductor_run_workflow`) served instead of per-workflow tools above `--max-direct-tools` (FR9, G7).

- **web/**: Real-time web dashboard for workflow visualization
  - `auth.py` - `OriginHostGuard` (issue #397): a pure-ASGI middleware (not Starlette's `BaseHTTPMiddleware` / `@app.middleware("http")`, neither of which ever sees WebSocket scopes — a decorator-style middleware would leave `/ws` completely unguarded) registered via `app.add_middleware(...)` on both `server.py` and `replay.py`. Enforces `Host`/`Origin` validation on every `http`/`websocket` scope (a present `Origin` must match; an *absent* one is allowed, since httpx/curl/`conductor gate respond` send none), then token auth + a JSON `Content-Type` on mutating HTTP routes, then token auth on the `/ws` handshake — closing it via `websocket.close` in reply to `websocket.connect`, before `accept()`, so a rejected socket can never send any message type (`gate_response`, `dialog_message`, `dialog_decline`, `iteration_limit_response` all included). `CONDUCTOR_WEB_ALLOW_ORIGINS` (comma-separated full origins) extends the allowlist for a dev server (e.g. Vite's `http://localhost:5173`) without disabling the check for anything else. A per-run token is minted automatically (`mint_token()`) so the protected configuration is the default; `resolve_expected_token(minted)` lets `CONDUCTOR_GATE_TOKEN` override it, preserving the pre-#397 escape hatch. `write_token_file`/`read_token_file`/`remove_token_file` persist that token at `~/.conductor/runs/dashboard-<port>.token` (mode `0600` on POSIX, atomic temp-file + `os.replace`; on Windows the mode bits are not honoured, so the file is protected by the user-profile NTFS ACL instead, issue #425) so a separate CLI invocation (`conductor gate respond`, `conductor guide`, `conductor stop`'s graceful-kill rung) can discover it without a flag or env var; `resolve_cli_token(port, token)` is the shared `--token` > `CONDUCTOR_GATE_TOKEN` > token-file resolver all three call. `token_from_scope(scope)` reads `Authorization: Bearer` first, then the `token` query param — the latter exists only because a browser cannot set handshake headers, and is an acceptable exposure only because both dashboard apps run uvicorn with `log_level="warning"` (no access logs to leak the query string into).
  - `server.py` - FastAPI + uvicorn server with WebSocket broadcasting, late-joiner state replay, and `POST /api/stop` + `POST /api/kill` endpoints. `/api/stop` interrupts/pauses the current agent (a user can then Resume or Kill); if it arrives before the engine binds its interrupt event, it is latched via `_pending_stop` and drained by `set_interrupt_event` so the startup window takes the graceful pause path instead of a progress-losing hard stop. `/api/kill` hard-stops the run. Whenever a stop/kill actually *terminates* the run (cancels the engine task), it routes through `handle_dashboard_stop` so a best-effort checkpoint is written (or its absence explained) — see `handle_dashboard_stop` above (issue #245). `start()` mints and writes the run's token file once `_actual_port` resolves (works for both `--web` and `--web-bg`, since `cli/run.py` calls `start()`/`stop()` on both the run and resume paths and the `--web-bg` child goes through the same code); `stop()` removes it. `GET /` reads `static/index.html` and injects `<script>window.__CONDUCTOR_TOKEN__="...">` before `</head>` (`HTMLResponse` rather than the old plain `FileResponse`), keeping the existing `Cache-Control: no-cache`. `_gate_token_ok` now always requires a match against the resolved token (env override else minted) — the pre-#397 "allow everything when the env var is unset" branch is gone. The WebSocket handler's per-message gate-response check no longer re-checks the token: the handshake (via `OriginHostGuard`) already authenticated the connection, so an unauthenticated socket never reaches the loop that reads `gate_response`/`dialog_message`/`dialog_decline`/`iteration_limit_response` at all.
  - `frontend/` - React 19 + TypeScript dashboard source (Vite + Tailwind). Renders the workflow DAG with **React Flow** (`@xyflow/react`) laid out via dagre, a Zustand store (`stores/workflow-store.ts`), an agent detail panel, and streaming activity. Build with `make build-frontend` (outputs to `static/`); unit tests via `make test-frontend` (Vitest). Subworkflow nodes support inline expand/collapse (nested React Flow containers, collapsed by default) in addition to double-click drill-down — see issue #314. `lib/auth.ts` (issue #397) reads `window.__CONDUCTOR_TOKEN__` (`getToken()`), builds the `Authorization` header for mutating fetches (`authHeaders()`), and appends `?token=` to the `/ws` URL (`withToken()`, since the WebSocket handshake can't carry custom headers). `ReplayDashboard`'s `/` injects nothing, so `getToken()` returning `undefined` there is expected and harmless — that app has no mutating routes or `/ws` to authenticate. In dev, `vite.config.ts`'s `transformIndexHtml` hook (scoped to `apply: 'serve'`, not the production build) injects `process.env.CONDUCTOR_GATE_TOKEN` the same way, and the `/ws` proxy entry needs `changeOrigin: true` (the `/api` proxy already had it) or the handshake arrives with `Host: localhost:5173` and fails `OriginHostGuard`'s host check.
  - `static/` - Built dashboard assets served by `server.py` (generated from `frontend/` by `make build-frontend`; committed to the repo). Not edited by hand.

- **install_hint.py**: `install_command(extra)` — resolves a working install command for an optional extra (`tui` / `aca` / `claude-agent-sdk`) from the *detected* install context, plus `read_receipt()` / `installed_extras()` which parse `<sys.prefix>/uv-receipt.toml`. A stdlib-only leaf (like `duration.py`, `console.py`, `rundir.py`) deliberately **top-level rather than under `cli/`**, because `providers/` needs it and must not import from `cli/`. Three branches: a uv receipt → `uv tool install --force '<spec>'`; an editable `direct_url.json` → `uv sync --inexact --extra <extra>`; neither → `pip install 'conductor-cli[<extra>]'`. The receipt is checked **first** because a uv tool install writes *both* files. Every hint used to hardcode the pip form, which cannot work on the documented install path — a uv tool venv is not pip-managed and `conductor-cli` is not on PyPI, so pip has nothing to resolve against unless the distribution is already installed in the target environment (issue #441). It survives as the last-resort fallback, rendered as `<sys.executable> -m pip install` (a bare `pip` does not manage a pipx venv, where it would *succeed* while installing a second copy the user never runs) with the git URL from `direct_url.json` appended when there is one, so a `pip`/`pipx`-from-git install — which is what actually lands in the `UNKNOWN` branch — still resolves. PEP 610's `archive_info` is deliberately *not* used as a source: a wheel or sdist is one artifact, usually a download since cleaned up, so pinning to it emits a command that fails. Four things are load-bearing: already-recorded extras are **unioned** with the requested one (`--force` rewrites the tool's whole requirement set, and `uv sync` is exact unless given `--inexact`, so naming only the new extra uninstalls the others); the **recorded install source is reused** (the receipt's `git`/`directory`/`url` key, else `direct_url.json`, else upstream pinned to `v<version>`) so the hint never redirects a fork or a locally-built install at upstream's released tag; a receipt that exists but **cannot be read or understood** is `readable=False` rather than an empty extras set, because the two would otherwise render the same command and one of them silently uninstalls the user's extras — that case appends an inline `# WARNING` shell comment naming the receipt (carried on `InstallEnvironment` so the renderer stays pure); the two install scripts draw the same line and **warn and continue** rather than aborting, since a broken receipt is exactly the state a reinstall repairs; and `install_command` **never raises**, since it runs inside a `ProviderError(...)` argument expression where an exception deletes the diagnosis instead of degrading the hint. Branch logic lives in the pure `render_install_command(extra, InstallEnvironment)` so all three contexts are unit-testable without a real install; `detect_environment()` is the impure half, and `InstallEnvironment.__post_init__` drops extras/source on the editable branch so the type cannot hold state the renderer ignores. `install.sh`/`install.ps1` parse the same receipt in shell for the same reason — see `receipt_extras` / `Get-ReceiptExtras`, whose agreement with this module is asserted by a shared-oracle test rather than assumed.

- **rundir.py**: `runs_dir() -> Path` — the single definition of `~/.conductor/runs/` (`mkdir(parents=True, exist_ok=True)`). A stdlib-only leaf (like `duration.py`, `console.py`) so `web/auth.py` can depend on it without importing `conductor.cli.pid`, which would drag in the whole Typer app (`conductor/cli/__init__.py` does `from conductor.cli.app import app`, and `app.py` itself reaches `conductor.web.server` — a genuine import cycle). `cli/pid.py::pid_dir()` delegates to it too, so both the PID-file registry and the dashboard token files (issue #397) share one directory and one home-isolation seam for tests. Callers reference it via `from conductor import rundir; rundir.runs_dir()` rather than importing the bare name, so a test can monkeypatch the one attribute (`conductor.rundir.runs_dir`) and every caller sees the patch — importing the name directly would bind a separate reference that a patch on the defining module can't reach.

- **events.py**: Pub/sub event system decoupling workflow execution from rendering (console, web dashboard)

- **exceptions.py**: Custom exception hierarchy (ConductorError, ValidationError, ExecutionError, etc.)

- **settings.py**: `ConductorSettings` / `FleetSettings` / `FleetRetentionSettings` (Pydantic models) + `load_settings()` — the machine-wide `~/.conductor/config.toml` (honors `$CONDUCTOR_HOME`, mirroring `registry/config.py::get_config_path`), read with stdlib `tomllib`. **Read-only in v1**: no `conductor config set`, no in-process writer — hand-edited, documented in `docs/configuration.md`. A missing file yields defaults; a malformed file raises for an explicit reader (`conductor fleet prune` with no `--keep-last` override) but is swallowed by the opportunistic startup sweep (`conductor.fleet.retention.maybe_prune_event_logs`), since a machine-wide settings file must never break `conductor run`.

- **telemetry/**: Safe optional initialization and event-driven OpenTelemetry tracing. Activated via the standard `OTEL_EXPORTER_OTLP_ENDPOINT` environment variable. It builds a unified trace tree by nesting native provider spans directly under Conductor's orchestration spans, checking each provider's `native_otel_spans` capability to prevent duplicate tool spans, and registers a delegating global tracer provider (`_DelegatingTracerProvider`) to dispatch spans to the active workflow run. Native Copilot spans are captured from the CLI child process when using the `http/protobuf` or `http/json` OTLP protocol. Standard gRPC (the default protocol) disables native Copilot spans and triggers a single per-run warning. The dynamic `native_otel_spans_active` field on agent start events signals if native spans are active. Conductor uses a run-latched OTLP protocol and endpoint shared by the engine and the Copilot client to prevent changes mid-run.

### Workflow Execution Flow

1. CLI parses YAML via `config/loader.py` → `WorkflowConfig`
2. `WorkflowEngine` initializes with config and provider
3. Engine loops: find agent/parallel/for-each/script/set/wait → execute → evaluate routes → next
4. Parallel groups execute agents concurrently with context isolation (deep copy snapshot)
5. For-each groups resolve source arrays at runtime, inject loop variables (`{{ item }}`, `{{ _index }}`, `{{ _key }}`)
6. Script steps run shell commands via asyncio subprocess, expose stdout/stderr/exit_code to context
7. Set steps render Jinja2 expressions and bind typed values to context (no LLM, no subprocess) via the shared `WorkflowEngine._run_set_step` helper, which enforces `output:` schema in all three positions (main loop, parallel group, for-each iteration) and emits `set_started` / `set_completed` / `set_failed`
8. Wait steps pause via `asyncio.sleep` (cancellable by interrupt or workflow timeout); expose `{"waited_seconds": float}` to context
9. Routes evaluated via `Router` using Jinja2 or simpleeval expressions
10. Final output built from templates in `output:` section

### Key Patterns

- **Context modes**: `accumulate` (all prior outputs), `last_only` (previous only), `explicit` (only declared inputs)
- **Failure modes** for parallel/for-each: `fail_fast`, `continue_on_error`, `all_or_nothing`
- **Route evaluation**: First matching `when` condition wins; no `when` = always matches
- **Tool resolution**: `null` = all workflow tools, `[]` = none, `[list]` = subset
- **Set step typing**: `output_type` defaults to `auto` (safe YAML parse with `_to_json_safe` normalisation — `datetime`/`date`/`time` → ISO 8601, non-string dict keys and other non-JSON-safe values raise `ExecutionError`). Explicit `string`/`number`/`integer`/`boolean`/`list`/`dict` only valid on single `value:`. `WorkflowContext.store` accepts any JSON-safe value (scalars/lists from `set` steps in addition to the dicts produced by LLM / script / gate / parallel-group outputs); `_add_agent_input` returns the scalar verbatim for `step.output` and raises a clear `KeyError` for `step.output.field` shorthand on non-dict outputs.
- **Reasoning effort**: `runtime.default_reasoning_effort` sets a workflow-wide default; per-agent `reasoning.effort` overrides it. Allowed values: `low`, `medium`, `high`, `xhigh`, `max`. Each provider translates the unified value to its native API (Copilot: `reasoning_effort` on the session, validated against the model's `supported_reasoning_efforts`; Claude: extended thinking with budget mapping low=2048, medium=8192, high=16384, xhigh=32768, max=59904 tokens, with `temperature` coerced to 1.0 and `max_tokens` bumped to fit the budget). `max` is Copilot/Claude-only — the Hermes provider advertises only the first four levels in `CAPABILITIES.reasoning_effort` and re-checks the resolved effort against that tuple at execute time (in addition to the static `conductor validate` cross-check), so `max` is rejected on Hermes both statically and at runtime, including when it only resolves to `max` after Jinja template rendering. See `examples/reasoning-effort.yaml`.
- **Context-window bar** (`context_window_used`/`context_window_max` on `agent_completed`/`parallel_agent_completed`, issue #412): `context_window_used` is sourced from `AgentOutput.last_call_input_tokens` (a single call's prompt size), never `input_tokens` (a billing total summed across every call) — reusing the billing figure produced a false ">100%" red bar on any multi-turn agent. `WorkflowEngine._context_window_fields()` is the single place both LLM-agent emission sites build the pair; when `used > max` (impossible for one real API call), it drops both to `None`, logs at debug on every occurrence, and also logs at warning once per run (via a `_context_window_anomaly_warned` latch, matching the `_pricing_hook_failed_warned`/`_budget_unpriced_warned` pattern) — a debug-only record would never reach an operator, and this anomaly means either the provider-reported token count or the looked-up context-window cap is wrong. Copilot's `assistant.usage` dedup (below) keys on `api_call_id`, falling back to `provider_call_id` then `service_request_id` when the SDK omits it, since all three are independently optional per the SDK schema.
- **Periodic checkpoints** (`runtime.checkpoint`, issue #244): opt-in `CheckpointConfig` (`every_agent: bool`, `every_seconds: int|None`, `keep_last: int=5`; `is_enabled = every_agent or every_seconds is not None`). Off by default → failure-only behavior preserved. `WorkflowEngine._maybe_save_periodic_checkpoint()` is called once at the **top of `_execute_loop`** (single choke point), where prior outputs are committed and `_current_agent_name` is the step *about to run* — so a periodic checkpoint reuses failure-checkpoint `current_agent` semantics and resume continues forward with no special-casing. Gated via the `_periodic_checkpoints_active` property (**root engine only**, `_subworkflow_depth == 0`, + `is_enabled`) and skips the first iteration (`limits.current_iteration == 0`). The save decision is `_periodic_checkpoint_due(now)` (`every_agent` OR `every_seconds` throttle; first save always fires). `_save_checkpoint_on_failure` and the periodic path share `_write_checkpoint(error, trigger)` (which best-effort-guards provider `get_session_ids()` so it never raises). The periodic save wraps write+emit+rotate; on any failure it calls `_record_periodic_checkpoint_failure()` which emits a **`checkpoint_save_failed`** event (consecutive-failure count; surfaced by `ConsoleEventSubscriber` + JSONL + dashboard) so a recovery-reliant user isn't silently left without checkpoints. After a save the engine calls `rotate_periodic_checkpoints`; at a terminal **non-resumable** outcome (clean completion via `run()`/`resume()`, or an explicit `status: failed` terminate) `_cleanup_run_periodic_checkpoints()` deletes the run's periodic checkpoints (an unexpected failure leaves them in place alongside the failure checkpoint). `conductor checkpoint list` shows a `Trigger` column and `—` for periodic rows' error type. See `examples/periodic-checkpoints.yaml` and `docs/workflow-syntax.md` (Periodic Checkpoints section).
- **Skills**: `runtime.skills: [entry, ...]` sets a workflow-wide default list enabled for every provider-backed agent; per-agent `skills: [entry, ...]` overrides it (tri-state via list presence: omitted = inherit, `skills: []` = explicit opt-out, `skills: [entry, ...]` = explicit set). **Each entry is either a registered built-in name or a filesystem path** (issue #350). Classification is *syntactic* — path when it starts with `~`/`.` or contains `/` or `\`, otherwise a built-in name — so a bare `conductor` can never be shadowed by a same-named local directory and resolution never depends on what happens to exist. A path may be a single skill directory (holds `SKILL.md`) or a root of them, which expands to every immediate child holding one (not recursive); `skills/registry.py::resolve_skills(entries, base_dir)` does the expansion centrally rather than passing roots through, because eager injection needs a name per skill and claude-agent-sdk needs a `<plugin>:<skill>` name. Relative paths resolve against the workflow file's directory (`AgentExecutor(workflow_dir=...)`, threaded from `WorkflowEngine._workflow_dir`), mirroring `_resolve_agent_working_dir` — `normpath`, not `resolve()`, so symlink aliases stay distinct. Paths are **trusted input**: the same YAML can already run arbitrary shell via `type: script`, so no allowlist applies. `AgentDef.validate_skills` only shape-checks path entries (the schema has no base dir) but keeps the eager built-in-name check, so an unknown *name* still fails at load time as before. Every resolved `SKILL.md` must have valid YAML frontmatter declaring `name` and `description` — checked inside `resolve_skills` (via `skills/frontmatter.py`, parsed with **ruamel.yaml**, not PyYAML) rather than only in `conductor validate`, because `conductor run` never calls the static validator; both CLIs skip an unparseable skill *silently*, which is the bug this closes. The observable contract is the same across providers — *"the agent has access to the named skill"* — but the mechanism differs via `AgentProvider.supports_native_skills` (readable without instantiating a provider via `providers/capabilities.py::uses_native_skills`, which returns `None` when it cannot be determined so callers skip rather than guess): **Copilot** (`True`) registers the skill directory on the SDK session via `skill_directories` (progressive disclosure via `SKILL.md` frontmatter); **Claude Agent SDK** (`True`) is also native but goes through the Claude Code *plugin* surface — `providers/claude_agent_sdk.py::_resolve_skill_plugins` maps each resolved directory back to the plugin that owns it (`skills/registry.py::resolve_skill_plugin` walks up for `.claude-plugin/plugin.json`), registers that root via `ClaudeAgentOptions.plugins` and enables the skill by its `<plugin>:<skill>` name via `ClaudeAgentOptions.skills`. Because that SDK has **no bare skill-directory option**, a path skill outside a plugin is unreachable there — `config/validator.py` now refuses it statically (naming both remedies) instead of letting it fail as a runtime `ProviderError`; the identical skill works on `copilot` untouched. **Claude** and **Hermes** (`False`) eagerly inject every enabled skill's `SKILL.md` plus `references/*.md` into the rendered prompt inside `<skills><skill name="...">...</skill></skills>` tags. That is expensive — the bundled `conductor` skill alone is ~132KB (~33K tokens), paid on every call and every retry — so `runtime.skill_injection` (`SkillInjectionConfig`: `warn_bytes` default 64KB, `max_bytes` default 160KB, either nullable) bounds it, enforced both in `AgentExecutor` and statically in `conductor validate`, measured against the exact string prepended and reported with a per-skill breakdown. The defaults deliberately straddle the bundled skill so enabling it on `claude` warns rather than breaking — `max_bytes` was raised from 128KB to 160KB when the skill outgrew the original ceiling, and must keep tracking it; a `warn_bytes` above `max_bytes` is rejected as unreachable. Native providers are exempt. Providers also declare `skills: bool` on their `ProviderCapabilities` descriptor so `conductor validate` catches skills-against-unsupported-provider mismatches — `hermes` declares `True` (it reaches skills through the provider-agnostic eager-injection path in `AgentExecutor`; it previously omitted the field, defaulting to `False`, while its own `execute()` docstring described injection working), and `aca` is the one `False` (skill directories are host paths the in-sandbox runner cannot read). `AgentExecutor._reject_unsupported_skills` now enforces a `skills=False` declaration at run time too, because `conductor run` never calls the static validator — otherwise the declaration held only at validate time while the eager-injection path happily injected anyway. Built-in skills live under `plugins/conductor/skills/<name>/` and are bundled into the wheel via the hatchling `force-include` entries in `pyproject.toml` — both the skill body **and** `plugins/conductor/.claude-plugin/`, because without the manifest no plugin root resolves and every skills-enabled agent on `claude-agent-sdk` fails with a `ProviderError`. Skills are rejected on non-provider-backed step types (script, wait, set, terminate, workflow, human_gate). **Discovery** (`runtime.skill_discovery`, issue #362) is the opt-in alternative to enumerating entries: `sources: [personal, project]` maps onto `~/.copilot/skills` + `~/.claude/skills`, and `.github/skills` + `.claude/skills` walked from the workflow file's directory to the repo root (first ancestor with `.git`; only the workflow file's own directory is used when none is found, so an unversioned tree cannot sweep in whatever sits above it). A third source, `plugins`, was **removed with issue #378** — it reached into a plugin and took exactly one of the three things it ships, which is the bug `runtime.plugins` fixes rather than a feature with a gap; it was also wrong more often than it looked (of 13 installed plugins, 3 were silently degraded and the 3 most plugin-like, shipping `agents/` + MCP but no `skills/`, were never discovered at all). Every mapped location is a *skills root*, so both expand through the same `registry.py::expand_skills_root` — discovery adds no second opinion about what a skill directory is, and a child that cannot be read is contained there so one stray directory cannot discard its readable siblings. **Conductor scans centrally rather than enabling each provider's own discovery**, and that is the whole point of the feature: locations are provider-specific, so one flag asking each provider to find its own would surface *different skill sets to different agents inside one run*. It also keeps `enable_config_discovery` off on Copilot (it would additionally auto-load MCP servers from `.mcp.json`) and `setting_sources` empty by default on claude-agent-sdk (opt-in per workflow via `runtime.provider.setting_sources`, see **Providers** below). Sources scan in a fixed canonical order (`project` → `personal`) independent of YAML order, so reordering cannot change which of two same-named skills wins. Discovery joins the **workflow-level default set**, so the existing tri-state is unchanged and `skills: []` remains the one opt-out; note the inherited case can produce skills from an *empty* `runtime.skills`. The organising principle is a **strict/lenient asymmetry — the user wrote the explicit entries and did not write the discovered ones**: broken frontmatter, a claimed name, an unreadable directory, or a skill `claude-agent-sdk` cannot load are an *error* for a declared skill and a *warning + skip* for a discovered one — with a provider that has no native skill surface at all as the one exception, which errors either way. That last case is not theoretical — only 1 of 13 installed Copilot plugins on a real machine ships `.claude-plugin/plugin.json`, so erroring would bury a claude-agent-sdk user in failures for content they never wrote. `claude`/`hermes` refuse discovery outright (measured 260KB ≈ 65K tokens, well over the default `max_bytes`, and machine-dependent — there is no limit to tune). That refusal is enforced **twice**, in `config/validator.py` and again in `AgentExecutor._reject_discovery_without_native_skills`, because `conductor run` never calls the static validator — the same reason `_reject_unsupported_skills` exists. Explicit entries beat discovered ones on a name collision, which fires immediately in practice because installing Conductor's own plugin puts a second `conductor` skill on the machine. `ResolvedSkill.discovered: bool` carries the provenance so callers branch on a field rather than sniffing a string. `discover_skills(..., home=...)` takes the home directory as a parameter specifically so no test reads the developer's real `~`. `cli/validate.py::_report_skill_discovery` lists the *effective* set — it resolves rather than merely scanning, so a skill the run would drop is not listed or billed, and it forwards any diagnostic the validator did not already print (the validator only resolves skills for agents that *inherit*, so a workflow whose agents all declare their own `skills:` is reported nowhere else) — an ambient set is the one part of a workflow the YAML does not capture, so making it inspectable is part of the feature, not a debugging aid. See `examples/skills-self-improving-workflow.yaml`, `examples/skills-discovery.yaml`, and `docs/workflow-syntax.md` (Skills section).
- **Plugins** (`runtime.plugins` / per-agent `plugins:`, issue #378): the **plugin** is the unit of opt-in. A plugin ships up to three things Conductor can use — `skills/`, `agents/*.agent.md` subagents, and MCP servers — and they are written to work together, so a plugin's `SKILL.md` routinely dispatches to `prs:code-reviewer` or calls an `ado` MCP tool. Loading only the skills produced an agent that read those instructions correctly and then reached for something never registered, silently. Entries take a string shorthand or a `PluginDef` object with per-component switches (`skills` / `agents` / `mcp`), coerced by the same string→object pattern as `_coerce_provider`; all three default **on**, because defaulting one off recreates the partial load the feature exists to fix. Tri-state inheritance matches `skills:` exactly (omitted = inherit `runtime.plugins`, `[]` = opt out, list = override). An entry is an **installed plugin name** (globbed under `~/.copilot/installed-plugins/*/<name>` and `~/.claude/plugins/*/<name>` — the `*` is the marketplace) or a **path**, classified by the same syntactic `is_path_entry` rule as skills; an uninstalled name errors naming the searched roots, and an *ambiguous* one errors rather than picking a winner (two marketplaces shipping `git` are different plugins, and choosing silently is how a workflow drifts between machines). **Conductor deconstructs a plugin rather than registering its root**, and that is the central decision: both SDKs have a whole-plugin surface (Copilot's `plugin_directories`, `ClaudeAgentOptions.plugins`) and both are all-or-nothing. Empirically, Copilot's `excluded_tools` **hides an MCP tool from the model but does not stop the server subprocess launching** (proved with a startup marker file), so `mcp: false` built on it would be a cosmetic filter sold as a guarantee — and for `ado --authentication azcli` the credential use happens at process start, not at tool call. Registering the root also inverts the providers against each other (plugin MCP unavoidable on Copilot, suppressed on claude-agent-sdk by its unconditional `strict_mcp_config=True`). Deconstructed, each component rides the surface Conductor already uses for it, so plugin MCP inherits `runtime.tool_output` limits, dashboard tool events, and the same credential/env resolution workflow servers get (`mcp_auth.resolve_mcp_servers` — skipping it handed the SDK a literal `${VAR}` and an unauthenticated URL, so the server attached and then did not work). A plugin server is not an `MCPServerDef`, so it carries no per-server `tools:` filter; `mcp: false` is the control. Two new `execute()` kwargs carry the non-skill components — `custom_agents` and `extra_mcp_servers` — accepted by every provider and honored by the native ones, mirroring how `skill_directories` already works; they are **per-execute** because `plugins:` is per-agent while providers are cached per type and `self._mcp_servers` is construction-time. Plugin skills merge into the existing `skill_directories` channel via `executor/agent.py::_merge_skills`, deduped by **name** (not directory) with declared entries winning — which fires immediately in practice, since installing Conductor's own plugin puts a second `conductor` skill on the machine. `custom_agents` accepts the qualified `<plugin>:<agent>` name — **verified against a live Copilot session**, where `myplug:quokka` appeared among launchable agent types — so namespacing survives deconstruction and two plugins shipping a `review` agent do not collide. On `claude-agent-sdk` the same specs become inline `ClaudeAgentOptions.agents` (`AgentDefinition` is keyed by name and has no `name` field; Copilot's `infer` has no counterpart and is dropped). `CAPABILITIES.plugins` gates the feature — `copilot` and `claude-agent-sdk` `True`, `claude`/`hermes`/`aca` `False`, because unlike skills there is **no eager-injection fallback**: text in a prompt cannot become a subagent or an MCP server. That refusal is enforced **twice**, in `config/validator.py` and again in `AgentExecutor._reject_unsupported_plugins`, because `conductor run` never calls the static validator — the same reason `_reject_unsupported_skills` exists. **One declared carve-out:** on `claude-agent-sdk`, reaching a plugin's skills *requires* registering the plugin root, which the SDK documents as also providing "custom commands, agents, skills, and hooks" — with a `skills` filter and none for the rest. So `agents: false` alongside `skills: true` for one plugin is **refused** rather than quietly granting more than the YAML declared (the same reasoning that refuses a narrowed per-server `tools:` filter there); the identical config works on `copilot`. Both the refusal and the matching `hooks/` wording (*exposed to the CLI* rather than the false *not loaded*) branch on `AgentProvider.skills_require_plugin_root`, which is a truthful description of the mechanism rather than a provider-name check, and both are enforced **twice** — `config/validator.py` and `AgentExecutor._reject_unfilterable_agents` — because `conductor run` never calls the validator. `hooks/` and `commands/` are otherwise **dropped loudly** via a `conductor validate` warning — hooks are arbitrary shell on tool events with no per-hook filter in either SDK and nothing in Conductor's model to map onto, so silently loading or silently dropping them would both reproduce the invisible divergence this feature removes. MCP server names are **never rewritten** (Copilot prefixes tool names with them, and a plugin's `SKILL.md` names those tools), so a collision between two plugins, or with `runtime.mcp_servers`, is an error naming `mcp: false` as the remedy — refused in the provider merge helpers as well as in `config/validator.py`, since `conductor run` skips the validator and a dropped server would be exactly the silent omission this feature removes. Two plugins shipping a same-named *skill* are refused for the same reason (skills arrive as one flat name-keyed list, matching `resolve_skills`' own two-directories-one-name error); a plugin skill losing to a **declared** one is allowed but reported, not logged at debug where nothing would reach the user. Plugins are **never discovered** — `plugins: [prs]` reads the installed roots, but that is *resolution* (the author wrote the name, a miss is a hard error) not *discovery*; `enable_config_discovery` stays off on Copilot and `setting_sources` empty by default on claude-agent-sdk. `cli/validate.py::_report_plugins` prints each plugin's component counts and every subagent by name, so a change in what a plugin ships surfaces at validate rather than at run time. **Flavor resolution (issue #497):** a plugin can be built for either CLI — Claude Code writes `.claude-plugin/plugin.json` with `agents/*.md`; Copilot writes `.github/plugin/plugin.json` with `agents/*.agent.md` — and the candidate-file rule used to be hardcoded to the Copilot suffix regardless of which manifest actually matched, so a `provider: copilot` workflow silently got zero subagents from a Claude-built plugin (a real, confirmed configuration: a Copilot build can sit inside a `~/.claude/plugins/` tree via a symlink the Claude CLI never inspects). `PluginFlavor = Literal["copilot", "claude"]` (`plugins/manifest.py`) is read off whichever manifest convention actually matched — never guessed from location — and `read_plugin_agents(..., flavor=manifest.flavor)` picks the candidate rule from that, so parsing is manifest-driven and an agent handed the "wrong" build still gets every subagent it ships. Flavor is threaded as a separate, optional axis (`resolve_plugin(..., flavor=...)`) that only ever **breaks a tie** where a genuine choice exists: a dual-catalog `plugin_sources` marketplace (`Marketplace.flavored`, populated per catalog convention actually present under a checkout) and a bare name installed once per CLI under one marketplace directory name (`_resolve_name_entry`'s Q3 tie-break) — two *different* marketplace names sharing a plugin name stay an ambiguity error regardless of flavor. Provider → flavor is a static declaration on `ProviderCapabilities.plugin_flavor` (required whenever `plugins=True`, enforced by a `model_validator`) — `copilot` declares `"copilot"`, `claude-agent-sdk` declares `"claude"` — resolved via `plugin_flavor_for(provider_name)` at the two name-keyed call sites (`config/validator.py`, `cli/plugin.py`, `cli/validate.py`) and via `type(self.provider).CAPABILITIES` at the one instance-holding call site (`executor/agent.py`, not added to `_plugin_cache`'s key since flavor is constant per executor instance). `config/validator.py`'s plugin-resolution cache is keyed by `(entries, flavor)`, not entries alone — the real cross-agent bug the issue named, since two agents on different providers naming one entry list previously shared one cached (and therefore one provider's) resolution. `~/.copilot/settings.json`'s `extraKnownMarketplaces` (`plugins/copilot_settings.py::read_copilot_marketplaces`, directory-source entries only, scoped to `flavor == "copilot"`) is consulted last in `_resolve_marketplace_entry` — after a declared source and the installed glob — so it can only turn a hard error into a resolution, never override an existing one, and it comes with a printed advisory naming `plugin_sources` as the standalone remedy. A frontmatter-less agent candidate is a hard error when its name ends `.agent.md` (an explicit claim to be an agent) and a warn-and-skip otherwise (`PluginAgentFrontmatterError`, a `PluginManifestError` subclass) — this keeps the Claude build's broader `*.md` candidate rule strictly additive, since no file that already errored under the old Copilot-only rule can newly start warning. See `examples/plugins.yaml` (with the self-contained `examples/demo-plugin/`) and `docs/workflow-syntax.md` (Plugins section, "Flavor" subsection).
- **Git-backed plugin sources** (`runtime.plugin_sources`, issue #380): what makes a plugin-using workflow **standalone**. `plugins:` alone resolves against machine state, so a shared workflow still needed "first install these" in a README. `plugin_sources` maps a marketplace name to a source and `plugins:` references it as `prs@acme`. The split (acquisition vs activation) is **not invented** — the Copilot CLI's own `settings.json` separates `extraKnownMarketplaces` from `enabledPlugins`, and the reason is structural: 11 of 13 plugins on an ordinary machine come from one repository, so a URL per entry would either clone it 11 times or silently dedupe 11 refs to one. The **load-bearing property** is that `prs@acme` means the same thing whether `acme` was declared, installed via a CLI, or is a local directory — a declared source registers into the *same* resolution table the installed roots populate, so git is a source *feeding* resolution rather than a second code path, and declared beats installed on a name clash. It also gives #378's ambiguity error a second remedy: qualify `git@acme` instead of falling back to a path. Entry classification is three-way and **ordered** — path, then `plugin@marketplace`, then bare name — so `./tools/my@plugin` stays a path. Source classification is *separate* from `is_path_entry` on purpose: that helper returns `True` for anything containing `/`, so reusing it would turn every `owner/repo` into a relative directory lookup; a source is local only by *prefix*. Both repository shapes resolve — a `marketplace.json` catalog or a `plugin.json` single plugin, with `plugin:` for one that is both — and the two catalog conventions **anchor their per-plugin `source` differently** (`.claude-plugin` repo-root-relative, `.github/plugin` `pluginRoot`-relative, verified against a real repo shipping both), so both anchors are tried. **No lockfile — the YAML is the lock.** A full 40-char SHA is *pinned* (fetched once, never re-checked); a tag, branch, or absent ref *floats* and is re-resolved every run via `git ls-remote`, matching `registry/version_resolver.py`'s existing treatment of workflow registries. This deliberately drops the issue's sketched `conductor.lock` and its component-count review signal — an unpinned source can gain a subagent or an MCP server between two runs with nothing to diff — so pinning is the remedy and `conductor plugin list` prints the counts on demand. Network posture: `conductor run`/`resume` acquire up front and **in parallel** (`cli/run.py::_prefetch_plugin_sources`, threaded because it shells out to git — an agent must never block mid-run on a clone, and a failure is a *configuration* error rather than an agent one); `conductor plugin fetch` primes the cache as its own step, which is the entire reason `conductor validate` can stay **off the network**; `conductor plugin list` reads the cache. An unreachable remote with a warm cache **warns and reuses the checkout** so offline runs keep working; a cold cache errors naming the fetch verb. Sources are resolved **one at a time**, not as a batch: resolving them together meant one unfetched source discarded the whole table, so a local directory sitting on disk was reported as "has not been acquired" *and* the per-agent MCP-clash and dropped-component checks were silently skipped — reinstating the invisible divergence the feature removes. At validate time an *unfetched* source is a **warning, not an error** (`PluginFetchError` → `_DeferredPluginCheck`), because the workflow is not wrong and `conductor run` heals it — but the warning names the checks it had to skip, since reporting "valid" when whole categories never ran would be the worse lie. A source that is *itself* broken (a path that does not exist, a `path:` that escapes the checkout, an unparseable catalog) is an **error**: no amount of fetching fixes it, and reporting it as a warning blamed the network for the author's typo and then prescribed a command that fails on the same input. A declared source that shadows an installed marketplace of the same name warns, since the two can ship different subagents or a different MCP server. An unreferenced `plugin_sources` entry is reported as dead config. There is **no `plugin update`**: floating refs self-update and pinned ones are meant not to. `WorkflowEngine._ensure_plugin_marketplaces` resolves sources at `run()`/`resume()` when no caller supplied a table, so a directly-constructed engine (as the class docstring's own example shows) is not silently CLI-only; a sub-workflow inherits the parent table and resolves any source it declares itself, which wins on a clash. Plugins remain **never discovered** — resolving a declared source is *resolution* (author wrote it, a miss is a hard error), not discovery. Trust: declaring a source **is** the consent (no prompt, no allowlist), matching #378's treatment of a plugin path, but the docs say plainly that the code is not in the reviewer's tree. See `examples/plugin-sources.yaml` and `docs/workflow-syntax.md` (Plugins section).
- **Terminate steps** (`type: terminate`): explicit terminal step with `status` (`success` | `failed`), Jinja2 `reason`, and optional `output_template` (a `dict[str, str]` that replaces `workflow.output:` when set; each value is rendered then passed through `_maybe_parse_json` so `"true"` becomes `True`, `"42"` becomes `42`, JSON literals are parsed). Reaching a terminate step ends the workflow immediately (no routes evaluated after). `success` → CLI exit 0, dashboard ✅, `workflow_completed { termination_reason, terminated_by, is_explicit: true, status }`. `failed` → CLI exit 1 (with rendered output JSON still printed to stdout for downstream tooling), dashboard ❌, raises `WorkflowTerminated` (subclass of `ExecutionError`), emits `workflow_failed { error_type: "WorkflowTerminated", is_explicit: true, status, output }`, and **does not** save an on-failure checkpoint (explicit terminations are intentionally non-resumable). Terminate steps cannot have `routes`, `tools`, `output`, `prompt`, `model`, etc.; cannot be used as parallel-group members or as a for_each inline agent (route to one from those groups' `routes:` instead). Inside a sub-workflow, a `status: failed` terminate is downgraded at the parent boundary to `SubworkflowTerminatedError` (also a subclass of `ExecutionError`) preserving the child's rendered `terminated_output` / `terminated_reason` / `terminated_by` as structured attributes — the parent treats it as a normal sub-workflow failure (its own `workflow_failed` does NOT inherit `is_explicit: true`). For more detail see `examples/terminate.yaml`, `docs/workflow-syntax.md` (Terminate Steps section), and `plugins/conductor/skills/conductor/references/authoring.md`.
- **Structured `runtime.provider` (Copilot custom routing)**: `runtime.provider` accepts either the bare string shorthand (`provider: copilot`) or a structured `ProviderSettings` object that routes the Copilot SDK at OpenAI-compatible / Azure / Anthropic endpoints (Ollama, vLLM, LM Studio, Azure OpenAI, etc.). Object fields: `name` (defaults to `copilot`), `type` (`openai`|`azure`|`anthropic`), `wire_api` (`completions`|`responses`), `base_url`, `api_key`, `bearer_token`, `headers`, `azure.api_version`. `api_key` and `bearer_token` are `SecretStr` (redacted in `model_dump` / dashboard / event logs). The model is frozen after construction. Custom routing activates only when at least one non-`name` field is set in YAML — ambient `OPENAI_*` env vars never divert default routing on their own. Once activated, missing fields fall back from env vars in this order: `base_url` ← `COPILOT_PROVIDER_BASE_URL` → `OPENAI_BASE_URL`; `api_key` ← `COPILOT_PROVIDER_API_KEY` (only — ambient `OPENAI_API_KEY` is intentionally NOT a fallback to avoid credential leaks); `bearer_token` ← `COPILOT_PROVIDER_BEARER_TOKEN`. The schema rejects every non-`name` field when `name != "copilot"` (structured config for other providers is a follow-up). It also rejects anchorless / broken combinations that would silently no-op at the SDK boundary: `wire_api` / `type` / `headers` / `azure` cannot stand alone without `base_url` / `api_key` / `bearer_token`; empty `headers`, empty `SecretStr`, and `azure: {api_version: null}` are rejected. The resolver raises `ProviderError` when custom routing is activated but every resolved field is falsy (e.g. expected env vars all unset). Custom routing applies to both agent execution and dialog turns so all sessions hit the same endpoint. `--provider <name>` CLI override replaces the whole `ProviderSettings` (logs a notice when YAML had structured fields). See `examples/copilot-local-llm.yaml`.
- **Connect to an existing Copilot runtime (Copilot)**: `runtime.provider.runtime_url` (Copilot-only) points the provider at an already-running `copilot --headless` process instead of spawning a nested one. Agents share the authenticated runtime process while retaining separate SDK sessions. Optional `runtime_token` (`SecretStr`, redacted, requires `runtime_url`) is the socket connection secret. Both fields fall back to env vars (`COPILOT_PROVIDER_RUNTIME_URL` / `COPILOT_PROVIDER_RUNTIME_TOKEN`) which activate the connection on their own (zero-YAML path for external orchestrators). `has_external_runtime()` is a separate axis from `has_custom_routing()`; the two can be combined because runtime transport and per-session model routing are independent. `has_structured_config()` keeps either mode from collapsing to bare-string serialization. Schema rejects: `runtime_token` without `runtime_url`; empty or whitespace-only runtime values; either field when `name != "copilot"`. Provider layer: `_resolve_runtime_connection()` (YAML then env) and `_build_client()` (in `copilot.py`). See `examples/copilot-existing-runtime.yaml` and `docs/configuration.md` (Connecting to an Existing Copilot Runtime).
- **Validator block** (`validator:` on a provider-backed agent, issue #220): semantic output validation with retry-once. After the primary agent completes, `WorkflowEngine._apply_validator` runs `OutputValidator` (`engine/validator.py`) — a second LLM call (synthetic agent via `provider.execute`, `tools=[]`, `{passed, issues}` output schema) grading the output against `validator.criteria`. Fields: `criteria` (required, non-empty), `model` (defaults to the agent's model), `max_retries` (`Field(1, ge=0, le=1)` — hard-capped at 1; `0` = report-only). On `passed: false` and `max_retries > 0`, the primary re-runs **once** via `executor.execute` with a `## Validation feedback` section (the issues) appended to `guidance_section`; the second output is final (no second validation loop). When the primary output carries a `continuation_state`, the re-run instead **continues the completed conversation**: `_apply_validator` passes the state back with the feedback alone as the next user turn, and `AgentExecutor` skips re-rendering the prompt and the skills/instructions prefix. `continuation_state` is provider-opaque and in-memory only (never serialized to checkpoints or event logs); today the Pydantic AI-based providers (`claude`, `openai`) set it to `outcome.result.all_messages()` and `hermes` sets it to the run's `result["messages"]`, while `copilot` / `claude-agent-sdk` / `aca` leave it `None` and keep the stateless rebuilt-prompt re-run. **Fail-open**: validator errors / unparseable responses → treated as pass with a logged warning. Wired into the main loop, parallel groups, and for-each loops (guarded by `agent.validator and not output.partial`; for-each passes a `usage_label` so the row matches `<group>[<key>]`). Emits `agent_validator_start` / `agent_validator_complete { passed, issues, errored, tokens, cost_usd }` / `agent_validation_failed { issues, will_retry }` through the per-agent `event_callback` (so for-each events carry `item_key`). Cost: the validation call and any discarded first attempt are recorded as a separate `"<agent> (validator)"` usage row (primary row = effective output). Rejected on `script` / `human_gate` / `workflow` / `wait` / `set` / `terminate` types. Frontend: event types in `web/frontend/src/types/events.ts`, store handlers + `NodeData.validator_*` fields in `web/frontend/src/stores/workflow-store.ts`, detail UI in `web/frontend/src/components/detail/ValidatorDetail.tsx` (rebuild with `make build-frontend`). See `examples/validator.yaml` and `docs/workflow-syntax.md` (Validator section).
- **Mid-run guidance** (issue #400): one channel — `engine/guidance.py::GuidanceChannel` — feeds every inbound guidance source into the existing outbound machinery (`WorkflowContext.user_guidance` → `get_guidance_prompt_section()` → `AgentExecutor.execute(guidance_section=...)`), which previously only the TTY Esc/Ctrl+G interrupt could reach. `WorkflowEngine` owns one channel (`self._guidance`), created fresh unless `_guidance_channel=` is passed; both sub-workflow constructors thread the **parent's** channel into the child (`_execute_subworkflow` / `_execute_subworkflow_with_inputs`), so a paused sub-workflow agent can be corrected too. `submit_guidance(text)` is the sink handed to `WebDashboard.set_guidance_sink()` (the exact mirror of `set_interrupt_event()` — pushed into the engine rather than polled, because the engine's `_web_dashboard` is duck-typed and stubbed across the test suite); `resume --guidance` does **not** go through it — it calls `add_user_guidance` directly at the CLI layer (see below), applying before the dashboard is seeded rather than queuing for a later drain. `add_user_guidance(text, source=...)` is the single entry point that actually applies text to `self.context` and emits `guidance_applied` — the TTY interrupt path (`_handle_interrupt_result`, `_handle_partial_output`) was rewritten onto it too, so an Esc/Ctrl+G correction is now visible in the dashboard and JSONL log, not just in the next prompt. **Two drain points**: (1) `_drain_pending_guidance()` at the top of `_execute_loop`'s `while True`, right after `_maybe_save_periodic_checkpoint()` — the one choke point every step type passes through, so guidance reaches the next agent, parallel group, for-each group, script, set, or wait step alike; it is **root-only** (`_subworkflow_depth == 0`, mirroring `_periodic_checkpoints_active`) because draining at every depth would let concurrent for-each sub-workflows race for the same queued sentence. (2) a fourth wait-arm (`self._guidance.event.wait()`) in `_handle_web_pause`, alongside resume/kill/disconnect — unlike those three it is deliberately **not** cleared before the wait, so guidance already queued before the pause began resolves the arm immediately instead of requiring a second submission. Since concurrent for-each sub-workflows share one channel and all wake on the same broadcast event, `drain()` there only reports guidance as applied when it actually returned non-empty text for that caller — a sibling that loses the race (finds nothing left to drain) falls through to the plain-resume outcome instead of emitting a misleading `with_guidance: true`. `_handle_web_pause` returns `WebPauseOutcome(handled, guidance)` (replacing a bare `bool`) so the caller in the main loop can try `_send_guidance_followup` (the Copilot-session-resume branch lifted out of `_handle_partial_output`, shared by both paths) before falling back to a full re-execution; `agent_resumed` gains `with_guidance: bool`. `POST /api/guidance` (`web/server.py`) validates (`CONDUCTOR_GATE_TOKEN` via the same `_gate_token_ok` check as `/api/gate-respond`; 409 after `workflow_completed`; 422 for empty-after-strip or over `engine/guidance.py::MAX_GUIDANCE_CHARS`=10,000, shared with `resume --guidance` via `engine/guidance.py::validate_guidance_text`) and calls the sink, latching a pre-sink submission in `_pending_guidance` (mirroring `_pending_stop`) for the startup race. `conductor guide --text "..."` (`cli/guide.py`) auto-discovers the port via `scan_pid_files()` and POSTs with the same token header as `conductor gate respond`. **Replay asymmetry**: `guidance_received` is added to `_REPLAY_INTERACTIVE_SKIP_TYPES` (it is the opening half of a pair whose closer is `guidance_applied` — replaying a still-pending submission would show a phantom "pending" entry forever), but `guidance_applied` is deliberately **not** filtered, since `WorkflowContext.from_dict` restores `user_guidance` and that correction really is still in effect on the resumed run. Parallel and for-each group members now also render with the current `guidance_section` (previously always `None`), so a correction submitted mid-run reaches every subsequent member too. See `docs/cli-reference.md` (`conductor guide`) and `plugins/conductor/skills/conductor/references/execution.md`.
- **Tool output limits** (`runtime.tool_output`): per-result MCP tool output size limiting. Controls character-size truncation and spill-to-file behavior for individual MCP tool result payloads. Config fields are `enabled` (defaults to `true`), `max_chars` (defaults to `50000`, minimum `1000`), `spill_to_file` (defaults to `true`), and `spill_dir` (defaults to `null` to resolve to OS temp directory `/conductor/tool-output`). Crucially, this limit is a **per-result** cap applied to each tool result independently, not a cumulative context window budget. Multiple truncated results, combined with prompt and conversation history, can still exceed the model's context window. Tuning should be done via `max_chars` or `max_agent_iterations` to keep context consumption in check; cumulative context budgeting is out of scope. Spill files contain the raw tool output (which may include secrets) and are not deleted by Conductor (they persist in the OS temp directory). For Claude, truncation is handled conductor-side via `MCPManagerToolset`, which applies character-limit truncation and spill-to-file logic while emitting `agent_tool_output_truncated` events. Copilot uses its native SDK `large_output` capability, mapping `max_chars` to bytes (meaning multibyte UTF-8 characters like CJK/emoji may truncate earlier). The `agent_tool_output_truncated` event is Claude-only because the Copilot SDK doesn't expose a truncation hook. This config is ignored by `claude-agent-sdk` (managed via native CLI `MAX_MCP_OUTPUT_TOKENS`) and doesn't apply to `hermes` (no MCP tools). See `examples/tool-output-limits.yaml` and `docs/mcp-tools.md` (Tool output limits section).
- **Dashboard stuck-reconnecting warning** (issue #330): the dashboard's WebSocket client (`web/frontend/src/hooks/use-websocket.ts`) retries forever with exponential backoff on disconnect — it drops through `wsStatus` `'disconnected'` momentarily, then oscillates between `'connecting'`/`'reconnecting'` on every retry cycle, never sitting continuously in any single non-connected status, so a naive "reconnecting for N seconds" timer would reset every cycle. Instead `workflow-store.ts`'s `setWsStatus` tracks `wsDisconnectedSince`: a timestamp set only on a *fresh* drop from `'connected'`, preserved through that churn, and cleared once reconnected. `lib/reconnect.ts`'s pure `isReconnectStuck()` (unit-tested) compares that timestamp against `RECONNECT_WARNING_THRESHOLD_MS` (60s), gated on `workflowStatus === 'running'` and not `replayMode`. `hooks/use-reconnect-warning.ts` ticks this once a second (mirroring `StatusBar`'s `idleSeconds` pattern; itself untested per the existing convention for timer-dependent hooks) and `components/layout/ReconnectWarningBanner.tsx` renders an amber banner telling the user the Conductor process may have silently crashed, pointing at whatever log location is available — `system.bg_stderr_log`/`bg_stdout_log` (captured from the root `workflow_started` event, `--web-bg` runs only) falling back to `system.log_file` (the always-on structured `*.events.jsonl` event log written by `EventLogSubscriber` for every run, unrelated to the separate `--log-file` debug-output flag), falling back to a generic hint to check the launching terminal. The banner only clears on an actual reconnect, not on a timer, so a page refresh isn't the only way to dismiss the stale "running" impression.
- **Dashboard viewport anchoring across graph re-layout** (issue #375): expanding an inline subworkflow used to make the whole graph appear to jump. The layout was never wrong — `graph-layout.ts`'s `layoutTopLevel` normalizes each rebuild's bounding box to origin, so growing one container shifts `minX`/`minY` and therefore every node's position on the canvas, while the camera is never touched (the `fitView` prop is initial-render only; React Flow's `fitViewQueued` is diff-guarded and cleared after the first fit). The world slid under a fixed viewport. `lib/graph-anchor.ts` compensates the camera instead: `toAbsolutePositions` resolves each node's canvas-absolute top-left by folding `parentId` chains — load-bearing because React Flow stores a nested node's `position` relative to its parent, so a node inside an expanded container keeps a byte-identical `position` while its container moves — and `anchoredViewport` pans by the negated delta of a node present in both layouts, at unchanged zoom, instantly. Anchor preference is the container owning the single toggled expansion key (matched on both `data.childContextKey` and `data.groupExpansionKey`, on either side of the rebuild, since a group only carries the latter once expandable), else the shared node nearest the pane center, tie-broken on node id for determinism. `nextAnchorHint` is the pure state machine deciding that hint; it holds the last clicked container for at most `MAX_STICKY_ANCHOR_REBUILDS` (2) rebuilds that toggle nothing, because an expanded child's DAG arrives a beat later and grows the same container again — but a replay scrub also rebuilds without resetting `expandedContexts`, so the budget is bounded. `WorkflowGraph` is split behind a `ReactFlowProvider` (there was none before; every `useReactFlow()` call site was a child of `<ReactFlow>`) so the rebuild effect, which lives outside `<ReactFlow>`, can reach `setViewport`. `lib/camera-authority.ts` keeps the two camera owners from fighting: an instant `setViewport` takes d3-zoom's non-transition path, which calls `interrupt()`, so a rebuild landing inside an animated `fitView` would cancel it mid-flight *and* leave its promise permanently unsettled — every animated fit therefore calls `claimCameraForAnimation(duration)` and the rebuild effect yields while `isCameraAnimating()`. Note `anchoredViewport` returning `null` on a zero delta is load-bearing, not merely informative: it suppresses the no-op `setViewport` that would otherwise interrupt an animation on every status-driven rebuild. Known limitation, documented in the module: expanding several subworkflows individually then collapsing them all at once leaves ~20px of horizontal pan that accumulates per repeat, because no single node carries the summed delta needed to invert several separate pins; fit-view clears it. See `examples/subworkflow-inline.yaml`.
- **Hardened dashboard request surface** (issue #397): three independent layers, none individually load-bearing. (1) `web/auth.py::OriginHostGuard`, a pure-ASGI middleware (`app.add_middleware(...)`, not `BaseHTTPMiddleware`/`@app.middleware("http")` — neither sees WebSocket scopes) validating `Host` (required, must name the bound machine) and `Origin` (only checked when present — httpx/curl/`conductor gate respond` send none, and that path must keep working with no extra setup) on every HTTP and WebSocket request. `CONDUCTOR_WEB_ALLOW_ORIGINS` (comma-separated full origins) is the dev-server escape hatch, additive only. (2) A per-run token, minted automatically (`mint_token()`) so the protected configuration is the default; `CONDUCTOR_GATE_TOKEN` overrides it (`resolve_expected_token`). Required on every mutating route (`/api/stop`, `/api/kill`, `/api/resume`, `/api/gate-respond`, `/api/guidance`) and on the `/ws` handshake — the single auth point for the socket, since an unauthenticated connection is closed (`websocket.close`, code 1008) in reply to `websocket.connect`, before `accept()`, so it can never send *any* message type. This is strictly stronger than the pre-#397 per-message check, which browsers could never satisfy at all. Read-only routes (`/api/state`, `/api/info`, `/api/logs`, `/api/gate-status`, `/api/files/*`, the whole replay app) stay unauthenticated, protected by origin/host only. (3) `Content-Type: application/json` required on every mutating route (415 otherwise), including the bodyless control POSTs. **Token discovery:** `WebDashboard.start()` writes a `0600` file (POSIX; on Windows the mode is not honoured and the file relies on the user-profile NTFS ACL instead) at `~/.conductor/runs/dashboard-<port>.token` once the port resolves (works for both `--web` and `--web-bg`, since `cli/run.py` calls `start()`/`stop()` on both the run and resume paths); `stop()` removes it. `conductor gate respond`, `conductor guide`, and `conductor stop`'s graceful-kill rung all resolve a token via the shared `resolve_cli_token(port, token)`: `--token` > `CONDUCTOR_GATE_TOKEN` > the token file. See `docs/cli-reference.md` (Environment Variables, and the Authentication sections under `conductor gate respond` / `conductor guide`) and the `web/` bullets above for the full mechanism.
- **MCP server exposure** (`mcp:` workflow block, `conductor mcp serve`, issue #432): `workflow.mcp` (`config/schema.py::McpConfig`) is a typed, `extra="forbid"` block — `expose` (default `true`; every workflow is a candidate for MCP tool exposure with no editing required, DD4), `mode` (`async`/`sync`/`auto`; the default a generated tool's omitted `_wait_seconds` resolves to), `read_only` / `destructive` (surfaced as the generated tool's `readOnlyHint`/`destructiveHint` annotations), and `estimated_minutes` (a client-side hint, must be positive). `conductor validate` reports an unknown key inside it as a schema error, not silence (FR11) — it cannot ride on the existing untyped `metadata: dict`. See `examples/mcp-serve.yaml` and `docs/mcp-server.md` (the user-facing guide: host configuration, the exposure ladder, toolsets, the run lifecycle, and a dedicated *Limits* section for DD5/DD9/DD11/DD12/R4) and `src/conductor/mcp/serve/` above for the server that reads it. **R1 — this feature's terminal run record is a scope change to `conductor status` and `conductor fleet list`, not an MCP-only addition**: every run — MCP-launched or not — now writes a completion tombstone, so both commands (and the Fleet TUI's History screen) gained a completed-runs section as a side effect, with `--live` restoring the exact pre-change scope. See the `fleet/records.py` (`TerminalRunRecord`) bullet above and the `CHANGELOG.md` entry for the full description of what changed.

- **Context compaction**: Always-on client-side context window compaction for the `claude` and `openai` providers. Compaction is triggered proactively using the reserve-based formula `trigger = window - (output_limit + buffer)` and targets a clamped 55% hysteresis ceiling. In this formula, the `output_limit` resolves to the minimum of the effective `max_tokens` sent to the API (from settings or defaults) and the model output cap (from provider-cap). The tool-output-derived `buffer` is calculated as `2 * ceil(max_chars / 4) + 15,000` tokens as a heuristic for worst-case tool results. Resolution prioritizes cascades: provider-advertised metadata (with full pagination for Anthropic and a vendor-field parser for OpenAI-compatible endpoints), public registry, and conservative fallback. A second, density-calibrated estimate guards the hard window against token-dense content (CJK, base64, minified data) the ~4-chars-per-token heuristic undercounts: it matches the heuristic on ordinary prose, so it never compacts a history that is merely large, and when it fires the tier chain is driven directly against that measurement rather than delegated to the inner strategy's own (heuristic) gate. Token telemetry stays on the primary scale — the density value travels as `density_tokens` and `trigger_reason` on the start event, with `degraded_estimators` / `still_over_window` on the complete event and an `agent_compaction_skipped` event when both estimators fail. The wrapper operates in a fail-open manner, disabling itself for the rest of the agent execution upon outer failure. Compaction events are emitted to the dashboard and console. A summarizing compaction step runs a nested model call that consumes a request slot from the agent's `max_agent_iterations` budget, which doesn't get refunded. The dashboard context bar relies on provider-only limits and may disagree with the compaction window.

### Debugging `--web-bg` failures

When a `conductor run --web-bg` (or `resume --web-bg`) child dies before
the dashboard becomes reachable, or crashes mid-run, look at:

1. The child's captured stderr log, printed alongside the dashboard URL
   on a successful launch and included in every `RuntimeError` message
   on a failed launch (with a bounded tail of its contents inlined via
   `_tail_log`). The path is also stamped into the child's
   `workflow_started` event under `system.bg_stderr_log` and surfaced
   in the web dashboard.
2. The matching `.events.jsonl` file in the same directory — same
   timestamp and 8-hex run id in the filename, so the three artefacts
   (`.events.jsonl`, `.bg.stderr.log`, `.bg.stdout.log`) sort together.
3. For an apparent silent crash, search the events JSONL for a
   `workflow_failed` event; the `is_base_exception` flag tells you
   whether the failure escaped the engine's normal `Exception` handling
   (e.g. a `SystemExit` from a misbehaving library).
4. If the CLI printed a "workflow has not reported starting yet" note
   (issue #410) instead of a failure: the launcher's process is alive
   and listening, but `GET /api/info` hadn't yet reported a
   `workflow_started` event when the (default 30s)
   `CONDUCTOR_WEB_BG_START_TIMEOUT` deadline passed. This is not a
   failure — check the dashboard or stderr log for slow startup causes
   (plugin fetch, MCP server startup, provider connection), or raise the
   timeout / set it to `0` to disable the wait entirely.
5. If a launch-gate `RuntimeError` reads "could not confirm termination
   of PID(s) ..." instead of "The background process was terminated."
   (issue #447): the launcher's process-tree kill and its final
   liveness sweep could not confirm every pid it knew about is actually
   dead — usually a permission error or a process that outlived a job
   object the launcher failed to create. Use `conductor status` or
   `conductor stop --port <port>` (named in the message) to find and
   stop the survivor manually; it is not silently left running.

`faulthandler` is enabled at import time in `conductor/__init__.py`, so
a native crash also dumps a Python stack trace to the captured stderr
log. See issue #116.

## Tests Structure

Tests mirror source structure in `tests/`:
- `test_cli/` - CLI command tests, e2e tests. `test_markup_guards.py` is the one that keeps issue #406 closed: it reads `src/conductor` with `ast` and fails with file:line across eight rules — a bare `Console` or a `Console` subclass (A), an interpolated `Panel` title or `Prompt` (B), an f-string into `Text.from_markup` (C), a markup literal at a print/cell sink (D), a `Text` through the builtin `print` (E) or into an f-string (F), unescaped brackets in `typer` help text (G), and any use of `rich.markup.escape` (H). Each rule is a shared predicate called by both the source scan and its negative control, so a control cannot pass against a drifted rule — that had already happened once. Each rule has a negative control, because a source-scanning check that quietly matches nothing reports "all clear" forever. `test_markup_injection.py` covers the same ground behaviourally, driving the real commands — the two layers are not redundant: the guard alone cannot prove `styled` renders correctly, and the behavioural tests alone cannot stop the *next* call site, which is the actual failure mode here
- `test_config/` - Schema validation, loader tests
- `test_engine/` - Workflow, router, context, limits tests
- `test_executor/` - Agent, template, output tests
- `test_providers/` - Provider implementation tests
- `test_integration/` - Full workflow execution tests
- `test_gates/` - Human gate tests
- `test_skills/` - Skill registry, frontmatter parsing, path entries, injection budget, loader, schema field, and executor/engine-integration tests. `test_engine_integration.py` is load-bearing: an `AgentExecutor` built directly in a test is handed `workflow_dir` and `skill_injection` by the test itself, so only an engine-level test can catch the engine failing to supply them
- `test_plugins/` - Manifest parsing (both conventions, all three `mcpServers` forms), agent-definition parsing, name/path/`@marketplace`/ambiguous resolution, component tri-state, schema, validator cross-checks, and provider wiring. Source grammar, catalog anchoring, and fetching live in `test_sources.py` / `test_marketplace.py` / `test_fetch.py` — the fetch tests run **real git against `file://` repositories** built by a fixture, because mocking `subprocess` would test the mock: annotated-tag dereferencing, shallow SHA fetch, and the unreachable-remote fallback are all properties of git itself. `conftest.py` builds every plugin tree on disk and takes `home` as a fixture, so no test reads the developer's real `~`. `test_executor_integration.py` and `test_engine_integration.py` are load-bearing for the same reason as their skills counterparts, and more so: a plugin's subagents and MCP servers have **no fallback delivery path**, so if they do not arrive at `execute` they are simply gone — a negative assertion could not tell a working path from a dropped one
- `test_install_hint.py` - The optional-extra install resolver (issue #441). The three context branches are covered against the pure `render_install_command`, so no test needs a real install; receipt parsing is covered against fixture `uv-receipt.toml` files. `tests/test_integration/test_install_script_extras.py` is its shell counterpart and **executes the real `install.sh` helpers** (sourcing the script with its trailing `main` stripped) rather than grepping them — the failure mode there is a quoting or `sed`-pattern mistake that reading the file does not catch; `install.ps1`'s helpers are extracted with PowerShell's own parser and executed wherever a native `pwsh` exists, with a parity class feeding both implementations the same receipt
- `test_fleet/` - Fleet Manager tests: run-record read/write/prune tolerance (`test_records.py`), event-log retention (`test_retention.py`), `RunSummary`/status-derivation and gate payload (`test_summary.py`), History enumeration (`test_history.py`), New Run resolve/launch (`test_launch.py`), the run-record-writing integration into `cli/run.py` (`test_run_record_wiring.py`), terminal bell/OSC 9 notification debouncing (`test_notify.py`), and Textual `App.run_test()` pilot tests per screen (`test_tui_runs.py`, `test_tui_run_detail.py`, `test_tui_step_detail.py`, `test_tui_drilldown.py` for Providers/Registries, `test_tui_new_run.py`, `test_tui_history.py`, `test_tui_splash.py`) plus shared actions (`test_tui_actions.py` — stop/kill/gate-resolve) and the presentation helpers (`test_tui_theme.py`, `test_tui_anim.py`, `test_tui_dag.py`)
- `test_mcp/` - The MCP *client* (`test_manager.py`, `test_manager_truncation.py`) and the `mcp` SDK version bound (`test_sdk_bound.py`, issue #432/DD0) alongside `conductor mcp serve`'s own suite (issue #432): naming/sanitizing (`test_serve_naming.py`), tool generation and the catalogue's exposure ladder/schema resolution/pinning (`test_serve_toolgen.py`, `test_serve_catalogue.py`, `test_serve_pinning.py`), the stdio server and `tools/list` stability across connections (`test_serve_server.py`), invocation and the always-detached launch/wait/concurrency-cap behavior (`test_serve_invoke.py`), the run-lifecycle tools (`test_serve_runs.py`), the discovery-mode fallback pair (`test_serve_discovery.py`), and the `introspect`/`diagnose` toolsets including R4's default tool-payload reduction (`test_serve_introspect.py`, `test_serve_diagnose.py`). `conftest.py` provides the shared fixture registry every catalogue/server test builds against.

Use `pytest.mark.performance` for performance tests (exclude with `-m "not performance"`).

### Test Fixture Patterns

When writing integration tests that construct `WorkflowConfig` programmatically, follow these conventions (see `tests/test_engine/test_limits.py` for canonical examples):

- `AgentDef` uses `prompt=` (not `instructions=`), `output={"key": OutputField(type="string")}` (dict, not list), and `routes=[RouteDef(...)]` (not raw dicts).
- `WorkflowDef` requires `entry_point=` and places `limits=` inside `workflow=`. `agents=` and `output=` are top-level on `WorkflowConfig`.
- The engine entry point is `await engine.run({})` (not `execute`).
- To test with controlled token/cost data, patch `provider.execute` to return a custom `AgentOutput` with explicit `input_tokens`, `output_tokens`, and `model` fields.

### Resume / Checkpoint Parity

When adding new fields to `LimitEnforcer`:

- **Transient fields** (reset each run): add to `from_dict()` as parameters sourced from the current workflow config, like `timeout_seconds`, `budget_usd`, `budget_mode`. Update the call site in `cli/run.py` → `resume_workflow_async()`.
- **Persistent fields** (survive across resume): add to both `to_dict()` and `from_dict()` deserialization, like `max_iterations`, `current_iteration`, `execution_history`.

## Code Style

- Python 3.12+
- Ruff for linting/formatting (line length 100)
- Google-style docstrings
- Type hints required, checked with ty (Red Knot)
- Pydantic v2 for data validation
- async/await for all provider operations

### Console Output

**Never put a runtime value into a string that Rich will parse as markup.**
Rich reads `[...]` in a plain `str` as a style tag, so a workflow name, an
agent name, a plugin name from a cloned repo, a path, or an `str(e)` that
happens to contain a bracketed token is interpreted as styling. In rich a
token is a tag when its **first character** is lowercase, `#`, `/` or `@`,
which splits three ways: `[0]` renders literally, `[task1]` is **silently
deleted**, and `[/etc/x]` raises `MarkupError` out of the print call. The
quiet half is the dangerous one — a listing that drops half a name looks
like it worked. Note `style=` does **not** disable parsing (issues #382,
#387, #406).

Each rule below is enforced by a matching rule in
`tests/test_cli/test_markup_guards.py`, which reads the source and reports
file:line:

- **Build every console with `conductor.console.make_console()`** (rule A).
  It locks `markup=False`, so a plain string is literal unless it asks to be
  styled. This covers plain prints, `Panel` bodies, `Table` cells, headers,
  titles and captions, and `Rule` titles. `markup` is not overridable —
  passing it to the constructor, to `print` or to `log` raises `TypeError`,
  because rich's per-call `markup=True` would otherwise reopen the whole
  defect from one line. Subclass `MarkupFreeConsole` rather than rich's
  `Console` so the refusal is inherited (see `cli/run.py::_SilentAwareConsole`).
- **Style with `conductor.console.styled("<template>", value, ...)`.** The
  template is conductor's own literal and is parsed; values are inserted
  verbatim and never reach the parser. A value that is already a `Text` is
  spliced in with its styling intact, so pre-styled fragments compose. Use
  `Text.from_markup("...")` when there is nothing to interpolate, and
  `conductor.console.join(sep, parts)` to join a list mixing `str` and
  `Text` (`Text.join` requires every part to be a `Text` already).
- **`Panel(title=)`, `Panel(subtitle=)` and `Prompt`/`Confirm`/`IntPrompt`
  prompts must be handed a `Text`** (rule B). Rich calls `Text.from_markup`
  on those unconditionally (`rich/panel.py`, `rich/prompt.py`), so
  `markup=False` never reaches them. This is the trap that made #387
  incomplete: it fixed the panel *body* and left the `title=` f-string one
  line away.
- **Never let a `Text` reach a plain-string context** — an f-string (rule F),
  `str()`, or the builtin `print` (rule E). `str(Text)` is its *plain* form,
  so styling is dropped and any text rich already parsed as a tag is gone
  outright. This one has the worst record in the codebase: it shipped four
  separate times during #406 alone, twice destroying data rather than
  colour. Use `styled("{}{}", ...)` or `join(...)` instead.
- **Do not use `rich.markup.escape`** (rule H). It is not
  byte-exact — the parser treats `\[` as an escaped bracket, so an ordinary
  regex like `\[0-9\]+` renders as `[0-9\]+` whether or not it was escaped
  first. Building a `Text` avoids the parser entirely.
- **Typer's `help=` / `epilog=` must escape their brackets** as `\[ ... ]`
  (rule G). These are outside the *console* convention — Typer renders them
  through its own rich console — but they are still markup-parsed. Escaping
  is the remedy here rather than a `Text`, because Typer takes a `str`.
  Forgetting cost `conductor run --help` the entire `[@registry][@version]`
  syntax, which appears nowhere else in the help output.

The worst outcome of forgetting is now a visible literal `[green]` in the
output rather than a crash or a silent deletion, and rule D of the guard
catches that statically. Each rule is a shared predicate called by both the
source scan and its negative control, so a control cannot pass while the rule
it guards has drifted.

### Provider Parity

All providers must maintain feature parity where applicable. Any change to one provider's behavior, contract, or capabilities must be applied to all providers. This includes:

- **Event callbacks**: Same event types emitted at the same semantic points
  - `agent_turn_start` with `{"turn": "awaiting_model"}` — immediately before each API call
  - `agent_turn_start` with `{"turn": N}` — at the start of each agentic loop iteration
  - `agent_message` — for text content in responses
  - `agent_reasoning` — for reasoning/thinking content
  - `agent_tool_start` / `agent_tool_complete` — around tool executions
- **Retry and error handling**: Same retry semantics, error classification (retryable vs. fatal), and timeout behavior
- **Structured-output recovery** (issue #343): every provider with an in-session recovery loop must validate the parsed content against the declared schema **inside** that loop, not after returning. `executor/agent.py:318` is only a backstop — by the time it runs, Copilot has already disconnected its SDK session, so a schema-shape failure there is unrecoverable by construction. The loop catches both JSON syntax errors and `ValidationError`, applies `providers/_output_shape.py::unwrap_scalar_wrappers` before validating, and re-prompts via a schema-specific correction message distinct from the syntax one (Copilot and Hermes share `providers/_recovery_prompt.py::build_parse_recovery_prompt`; Claude has its own tool-oriented wording). On budget exhaustion, re-raise the original `ValidationError` (it names the field and expected type); reserve `ProviderError` for syntax failures. Each attempt emits `agent_parse_recovery` via `providers/_event_format.py::emit_parse_recovery_event`. Two traps: `parse_json_output` wraps *syntax* errors in `ValidationError` too, so the two kinds cannot be told apart by exception type (Hermes splits them by which call failed); and Claude must not validate the `_has_mcp_tool_use` path, which returns to the agentic loop rather than being a final answer.
- **Plugin components** (issue #378): `execute()` accepts `custom_agents` and `extra_mcp_servers` alongside `skill_directories`. Every provider takes all three; a provider declaring `CAPABILITIES.plugins=True` must honor all three, since there is no eager-injection fallback for a subagent or an MCP server. A provider that accepts them and drops one reinstates exactly the silent partial load the feature removed.
- **Output contract**: Same `AgentOutput` structure with consistent field population (model, tokens, input_tokens, output_tokens, content)
- **Tool execution**: Same MCP tool calling interface and result handling
- **Session management**: Same lifecycle (`validate_connection()`, `execute()`, `close()`)
- **Reasoning effort**: All providers must accept the unified `reasoning.effort` field (`low` | `medium` | `high` | `xhigh` | `max`), translate it to the native API (Copilot `reasoning_effort` on the session; Claude extended `thinking` budget), validate that the selected model supports the requested effort, and raise `ValidationError` with a clear message when it does not. The one declared exception is Hermes, whose `CAPABILITIES.reasoning_effort` omits `max` (unverified upstream support) — this is not a parity violation because the provider both declares the narrower tuple and enforces it at execute time, matching the "declare the weaker value and honor it" rule in the Experimental Providers section below. Any reasoning/thinking content the model returns must be surfaced via `agent_reasoning` events so the dashboard, JSONL logger, and console subscriber render it consistently.
- **Model pricing hook** (issue #265): `AgentProvider.get_model_pricing(model) -> ModelPricing | None` is an **optional** hook (base default returns `None`) that lets a provider supply live per-model rates. Cost resolution order in `engine/pricing.py::get_pricing` is workflow `cost.pricing` override → provider hook → `DEFAULT_PRICING` → `None`. The engine bridges the async hook to the sync `UsageTracker.record` via `WorkflowEngine._ensure_pricing_resolved(agent, model)` (called before every `record()`; resolves each model once, caches on the tracker). Only Copilot implements it (derives USD from the SDK's `billing.token_prices` in AI Credits, `100 credits = $1` via `_COPILOT_USD_PER_CREDIT`); it must **never raise** (fall back to the table). `WorkflowUsage` exposes `unpriced_agents` / `unpriced_models` / `has_unpriced` so the CLI summary and dashboard surface `~$X (N agents unpriced)` instead of presenting a partial as a complete total.
- **Max token-limit hooks**: `AgentProvider.get_max_prompt_tokens` / `get_max_output_tokens` are **optional** hooks (base default returns `None`) that let a provider supply its SDK-reported per-model input/output caps; compaction uses the output cap to size its output reserve. `claude`, `openai`, and `copilot` implement both; `hermes`, `aca`, and `claude-agent-sdk` legitimately return `None` from the default (no SDK model-listing surface), which the compaction resolution cascade treats as a first-class "fall through to the registry/fallback" signal rather than an error.
- **Context-window measurement** (issue #412): every provider must populate `AgentOutput.last_call_input_tokens` with the prompt-token size of the most recent *single* API call in the execution, or leave it `None` — it must never be an aggregate. This is distinct from `input_tokens`, which sums every call for billing and is not comparable to a model's context-window cap. Per-provider asymmetry: Copilot's `assistant.usage` event and pydantic-ai's `RequestUsage.input_tokens` already include cache reads/writes, so the field is the raw per-call value; the Claude Agent SDK's Anthropic-shaped usage dict reports cached prompt tokens separately, so the provider must sum `input_tokens + cache_read_input_tokens + cache_creation_input_tokens`. A provider that cannot isolate one call (e.g. Hermes after a parse-recovery run, which spins up a fresh `AIAgent` whose usage never reaches the outer result) reports `None` rather than guessing, which is a first-class "hide the bar" signal, not a fallback to the wrong number.
- **Cache-inclusive token accounting**: `AgentOutput.input_tokens` is the **total** prompt across every call and must always *include* `cache_read_tokens` and `cache_write_tokens` — the cache fields are subsets of it, never additions to it. Copilot and pydantic-ai report it that way natively (pydantic-ai's own `UsageBase` documents the identical convention and normalizes the providers that don't); the Claude Agent SDK's Anthropic-shaped usage dict reports cached tokens *outside* its own `input_tokens`, so that provider folds them in via `claude_agent_sdk.py::_read_usage` — the same summation the context figure above uses — and surfaces both buckets alongside. Parsing those three keys in one helper is deliberate: reading them inline at each accumulation site is what let the `.get()` defaults drift apart and double-count the cache. `engine/pricing.py::calculate_cost` then subtracts the buckets back out before applying the input rate, so each physical token is priced exactly once — but **only subtracts a bucket that has a rate to be charged at**, because a `0.0` cache rate in `DEFAULT_PRICING` means "no published rate" (20 of its entries — every GPT, o-series and Gemini model) rather than "free", and subtracting unconditionally would price a cached prompt at nothing. Both halves match `genai_prices.types.ModelPrice.calc_price`; the one deliberate divergence is that it *raises* on a negative residual where conductor clamps and logs once per model, since a cost annotation must never abort a run. Billing the buckets additively instead overstates a cached tool-calling run by roughly an order of magnitude. A provider that populates the cache fields but leaves `input_tokens` exclusive under-bills instead; a provider that populates neither reports cache-free totals and is unaffected (`hermes`), and `aca` satisfies it transitively by relaying its in-sandbox provider's already-compliant figures.
- **In-memory continuation** (`AgentOutput.continuation_state`, `AgentProvider.supports_continuation`): a provider that can resume a completed execution in memory declares `supports_continuation=True`, populates `AgentOutput.continuation_state` on every completed (non-partial) output, and when handed that state back on `execute()` continues the completed conversation, treating `rendered_prompt` as the sole next user turn. A provider that cannot must ignore the kwarg (with an "Ignored." docstring entry and a `del`, matching the other unused kwargs) and leave the field at `None` — the first-class "rebuild the prompt statelessly" signal the executor branches on. Today the Pydantic AI-based providers (`claude`, `openai`) declare it with `outcome.result.all_messages()` as the value, and `hermes` declares it with the run's `result["messages"]` (the same list its checkpoint-resume path already persists; withheld when a parse-recovery call produced the output, since that output lives in the recovery conversation the outer result never carries). Three invariants hold everywhere: the value is provider-opaque and typed `object` at the boundary (providers re-narrow it themselves); it must never be handed to a different provider; and it is never serialized to checkpoints or event logs. The executor refuses state from a provider that does not declare support, since continuing there would send the model the follow-up turn with no task prompt.
- **MCP-free executions** (`execute(suppress_mcp_servers=...)`): a keyword-only `bool` defaulting to `False`, so every authored call keeps its current behavior. When `True` the execution runs with **no** MCP servers at all — neither the provider's workflow-level `runtime.mcp_servers` nor the per-call `extra_mcp_servers`. Every provider declaring `mcp_tools` MUST honor it (`copilot` skips the merge, `claude`/`openai` skip the MCP manager entirely, `claude-agent-sdk` empties the session map before the `tools: []` refusal and the config write, `aca` forwards no servers to the runner); `hermes` declares `mcp_tools=False` and ignores it with a `del` plus an "Ignored." docstring entry, matching the other unused kwargs. The only caller is `engine/validator.py::OutputValidator`, whose synthetic grading agent asks for `tools: []`: on an MCP-capable provider that list does not describe what the session gets, so the grader would either hold workflow tools it was never granted or — on `claude-agent-sdk`, where `tools: []` plus attached servers is refused — be rejected and swallowed by the validator's fail-open, silently passing every graded output. The signal is **execution-level rather than agent-shaped** on purpose: nothing in YAML can set it, so the `tools: []`-plus-MCP refusal stays load-bearing for authored agents. `tests/test_providers/test_base.py::TestSuppressMcpServersContract` pins the signature across all six providers (a provider that accepted and dropped it would make the base contract untrue), and `tests/test_engine/test_validator_integration.py::TestValidatorRunsWithoutMcpServers` drives the real `OutputValidator` — a helper-level test would miss exactly the fail-open swallow this exists to fix.

When modifying any provider, check all other providers for the same change. The dashboard, JSONL logger, console subscriber, and workflow engine all depend on consistent behavior across providers.

#### `openai.py` parity notes

The OpenAI provider (`openai.py`) implements `AgentProvider` on the shared
Pydantic AI execution loop (`src/conductor/providers/_pydantic_ai/runner.py::run_agent_pipeline`).
It shares toolset bridges, event callbacks, interrupts, and retry contracts with `ClaudeProvider`,
with the following backend specifics:

- **Shared runner**: Delegates `execute()` to `run_agent_pipeline()` with an `OpenAIChatModel` backend.
- **Env-resolution rule**: YAML `api_key` and `base_url` take precedence over `OPENAI_API_KEY` and `OPENAI_BASE_URL`. Ambient env vars never reroute an unconfigured provider (e.g. `provider: copilot` is never diverted by `OPENAI_*` variables). Once a custom `base_url` is in effect — from YAML **or** from `OPENAI_BASE_URL` — the ambient `OPENAI_API_KEY` is **not** forwarded to it and construction raises `ValidationError` unless `api_key` was passed explicitly, so a personal credential never reaches an endpoint the author did not pair it with (the same reasoning behind `copilot.py` refusing ambient `OPENAI_API_KEY`). `self._api_key` is deliberately left `None` on the ambient path rather than being written back, which keeps `agent_builder.py`'s own guard reachable in production instead of only under its unit test.
- **Chat-Completions-only**: Exclusively uses the OpenAI Chat Completions API; the OpenAI Responses API is not supported. This is also why `CAPABILITIES.agent_reasoning_events` is `False`: pydantic-ai only builds a `ThinkingPart` from `reasoning`/`reasoning_content`, a DeepSeek/Moonshot field, so `api.openai.com` never emits `agent_reasoning` on this backend. It would become `True` on an `OpenAIResponsesModel` backend.
- **Reasoning effort**: Declares `("low", "medium", "high")` and rejects `xhigh`/`max` with a `ValidationError`. `xhigh` arrived with a later model generation than the o-series and is unverified against arbitrary OpenAI-compatible endpoints, so the provider declares the narrower tuple (matching the way `hermes.py` omits `max`). Effort is additionally validated *per model* at agent-build time via `pydantic_ai.profiles.openai.openai_model_profile(...).openai_supports_reasoning`, so a non-reasoning model like `gpt-4o` fails before the request instead of returning a 400 mid-run; an unavailable profile attribute yields `None`, which skips the check rather than guessing.
- **Temperature 0..2**: The per-provider ceiling lives on `ProviderCapabilities.max_temperature` (`1.0` for copilot/claude/hermes/aca/claude-agent-sdk, `None` for openai) and is enforced by `factory.py::_enforce_temperature`, the choke point `run`, `resume` and `validate` all share — the schema bound alone would not cover `conductor run`, which never calls the cross-reference validator.

#### `claude_agent_sdk.py` parity notes

The Claude Agent SDK provider (`claude_agent_sdk.py`) is the canonical
**experimental** provider — see the "Experimental Providers" section
below for the carve-out policy. It delegates the agentic loop to the
`claude` CLI via the `claude-agent-sdk` package. This achieves **event
and output parity** but the following are managed by the SDK rather than
Conductor:

- **Retry and error handling**: The `claude-agent-sdk` package does **not** retry API failures (429s, 5xx, network errors) internally — its built-in retry logic covers only filesystem operations. Conductor wraps SDK errors in `ProviderError` and uses `stop_reason` / error subtype to set `is_retryable`, so workflow-level `retry:` configuration drives all retry behavior. Plan for transient failures with explicit `retry:` blocks in your workflow.
- **MCP servers** (issue #335): workflow-level `runtime.mcp_servers` **are** supported. `_translate_mcp_servers` maps each `MCPServerDef`-derived dict onto the SDK's `McpStdioServerConfig` / `McpHttpServerConfig` / `McpSSEServerConfig` shapes, and the provider passes them via `ClaudeAgentOptions`. Four details are load-bearing:
  - Translation runs once in `__init__` rather than per `execute` call. Note providers are constructed **lazily** (`ProviderRegistry.get_provider` ← `WorkflowEngine._get_executor_for_agent`), so a bad server config surfaces when the first agent on this provider runs, **not** at `conductor validate` — which does not inspect per-server `tools:` filters at all.
  - The config is written to a `0600` temp file (`_write_mcp_config`) and passed **by path**. Passing the dict would make the SDK serialize it into a `--mcp-config <json>` argv element, publishing resolved stdio `env` values and http/sse `Authorization` headers to anything that can read `/proc/<pid>/cmdline`. The write happens **inside** `execute`'s `try`, so the `finally` reclaims the file on every exit path; the finally also `aclose()`s the SDK iterator first, so the `claude` subprocess is gone before its config file is. The file must use the `{"mcpServers": {...}}` envelope — the CLI rejects a bare mapping.
  - `strict_mcp_config=True` is set **unconditionally**, including when the workflow declares no servers: otherwise the CLI loads project `.mcp.json`, user-global, and plugin-provided servers, and `permission_mode` bypasses approval for whatever they expose.
  - A narrowing per-server `tools:` filter (anything other than the default `["*"]`) is **refused**, not ignored: forwarding the server unfiltered would grant more tools than declared, the same security regression that justifies refusing the per-agent allowlist. A dropped `timeout` only warns, since losing it cannot widen tool access.
- **Tool execution**: Per-agent `tools:` allowlists remain unsupported (`workflow_tools_passthrough=False`). The provider refuses any non-empty per-agent list because workflow tool names do not translate to CLI tool IDs. Note the SDK's `tools` option governs **built-in** tools only, and `allowed_tools` is a permission auto-approve list rather than an availability filter — so honoring an allowlist would require a permission-mode redesign, not just a name mapping. An explicit `tools: []` means **no tools**: no built-in tools beyond the `Skill` loader when skills are enabled, and it is rejected — at validate and at run time — whenever workflow or plugin MCP servers would attach, since the SDK has no per-agent MCP switch. The supported MCP-only form is an omitted `tools:` under `native_tools: none`. What an **omitted** `tools:` grants is chosen by `runtime.provider.native_tools` (see **Native tools** below), not by the provider.
- **Native tools** (`runtime.provider.native_tools`): `ProviderSettings.native_tools` (`"none"` default, `"claude_code"`) selects which *built-in* Claude Code tools an agent that omits `tools:` receives. `_resolve_tool_config` implements the matrix off the raw `agent.tools` field (the executor erases omitted-vs-`[]`): omitted + `none` → `tools=[]` (or `["Skill"]` when skills are enabled), `permission_mode="dontAsk"`; omitted + `claude_code` → the `claude_code` preset with `bypassPermissions`; explicit `tools: []` → `[]`/`["Skill"]` with `dontAsk` under **either** value (an explicit opt-out outranks a workflow-level grant); non-empty → refused as before. `workflow_tools_passthrough` stays `False` and no workflow↔CLI tool-name translation exists. The default used to be the preset, implicitly — every agent on this provider was a filesystem/shell/web agent without the workflow saying so. The string shorthand resolves to `none` (stamped by `ProviderSettings._check_field_compatibility`, like `auth_mode`'s `auto`, so YAML `null`/`~` also land there), and `has_structured_config()` counts only `== "claude_code"`, so the default keeps the bare-string serialization while the opt-in forces the object form. The field is rejected on every other provider. `create_provider` falls back to `"none"` when `provider_settings` is `None` (a bare `--provider` override, or a per-agent override onto this provider — `ProviderRegistry` passes settings only on a name match), and `ClaudeAgentSdkProvider.__init__` refuses any value outside the two literals (`ProviderError`, fail-closed). **Why `dontAsk`, not `None`:** `None` leaves the CLI on `default`, which *prompts* for anything unapproved, and a non-interactive run cannot answer; `dontAsk` denies instead (in the SDK's `PermissionMode` literal since 0.1.51, below the `>=0.2.82` floor). **MCP under `none`:** after the workflow and plugin server maps are merged in `execute` (so both are covered), `_mcp_permission_rules` sets `allowed_tools` to one `mcp__<server>__*` rule per declared server — never `*`, `mcp__*` or anything unanchored — and only on the `dontAsk` path (under `bypassPermissions` nothing needs approving, and adding rules there would only widen more places). It *assigns* the option: the SDK copies `allowed_tools` and appends its own `Skill`/`Skill(<name>)` grants (`_internal/transport/subprocess_cli.py`), so those survive. Server names are validated, never escaped or normalised, against `plugins/manifest.py::MCP_PERMISSION_SAFE_NAME` — `SAFE_NAME`'s charset minus `.`, `__` anywhere, and a leading/trailing `_`. `__` is the rule's own delimiter (`a__b` would read as server `a`) and rules are `,`-joined into one `--allowedTools` value (`a__*,Bash` would add a rule); `.` is excluded because the CLI builds tool names as `mcp__${W1(server)}__${tool}` with `W1 = s.replace(/[^a-zA-Z0-9_-]/g, "_")` (read from the CLI bundled with claude-agent-sdk 0.2.87), so a configured `fs.tools-2` exposes `mcp__fs_tools-2__…` and the literal rule `mcp__fs.tools-2__*` never matches — every call denied under `dontAsk`. Hyphens and single underscores survive that normalization, which is why they stay allowed. Neither the schema nor `_translate_mcp_servers` constrains server names, so this check is load-bearing; it is enforced **twice** — `ProviderError` at run time and `config/validator.py::_check_mcp_permission_names` at validate (workflow *and* plugin servers), both only when the agent runs with no built-ins. An MCP tool that requires interactive approval may be denied under `dontAsk`; that is a documented limitation, not a reason to fall back to `bypassPermissions`. `strict_mcp_config=True`, the `0600` config file and its cleanup order are unchanged; explicit `tools: []` + MCP servers is refused (`tools: []` means no tools) — enforced **twice**: `config/validator.py::_check_agent_tools` at validate, and `_refuse_explicit_no_tools_with_mcp` at run time against the *merged* workflow + plugin map, under either `native_tools` value. The run-time refusal (like the server-name check) runs **before** `_write_mcp_config` and before the SDK is invoked, so a refused configuration never puts resolved credentials on disk even transiently. Omitted `tools:` + `none` + declared servers is the supported MCP-only configuration. **Plugin subagents under `none`** are refused before any SDK session starts: with no built-ins there is no dispatch tool, and the SDK exposes no verified identifier to grant back (unlike `Skill`); the remedy names the cause — the agent's own `tools: []`, or the workflow's `native_tools: none` — and suggests `native_tools: claude_code`; or `agents: false` **plus `skills: false` when that plugin's skills are enabled** — `agents: false` alone is itself refused there, because registering the root to reach the skills exposes the subagents again (the carve-out in **Plugins** below), so recommending it unconditionally sent authors straight into the next error; or `copilot`. The validator names the exact switches per plugin (it knows which ship subagents and which have skills on); the run-time message, which does not, states the conditional. Subagents never implicitly enable the preset. Enforced twice: `_resolve_tool_config` at run time and `config/validator.py::_check_claude_agent_sdk_subagent_dispatch` at validate (which now also catches the pre-existing `tools: []` + subagents case statically). **Warning:** `claude_code` is surfaced through the existing experimental-provider banner rather than a constructor log line — `engine/workflow.py::build_workflow_started_data` adds `native_tools` to the `claude-agent-sdk` entry of the `providers` block (mirroring `ProviderRegistry`'s name-match rule), and `cli/run.py::_maybe_print_experimental_banner` appends one fixed line (`_native_tools_claude_code_warning`, a fresh `Text.from_markup` of a literal, since `Text` is mutable and the panel is `join`ed) when it reads `claude_code`. It therefore inherits the banner's `f"{run_id}:{provider_name}"` latch in `_PRINTED_EXPERIMENTAL_BANNERS` (once per run, including across a resume's re-seeded `workflow_started`) and its `--silent` gating via `_verbose_console`.
- **Runtime config**: `temperature` and `max_tokens` are rejected at the factory — the CLI controls sampling behavior.
- **Working directory** (issue #348): the engine-resolved `agent.working_dir` / `runtime.working_dir` **is** forwarded, as `ClaudeAgentOptions.cwd`.
  - The SDK applies it as the `claude` subprocess's cwd (`_internal/transport/subprocess_cli.py` as of 0.2.87 passes it to `open_process` and sets `PWD`), so stdio MCP servers pick it up by **inheriting** it from that subprocess. There is deliberately no per-server stamping as in `copilot.py::_mcp_servers_for_cwd`: the SDK's `McpStdioServerConfig` has no cwd field, so `_translate_mcp_servers` is left alone. Inheritance is a property of the CLI binary, not of the SDK, so it is documented rather than asserted by a test.
  - The path is passed **verbatim** — `WorkflowEngine._resolve_agent_working_dir` has already rendered, absolutized, normalised, and existence-checked it, and re-resolving here would collapse the symlink aliases the engine preserves on purpose. The `ClaudeAgentOptions(...)` construction lives **inside** `execute`'s `try` so the `os.getcwd()` fallback can't escape as a bare `OSError` when the process cwd has been deleted (`copilot.py` resolves its cwd inside its try for the same reason).
  - There is no provider-side `is_dir()` guard: a directory that vanishes after the engine's check surfaces as the SDK's `CLIConnectionError("Working directory does not exist: <path>")`, wrapped in `ProviderError`. That is only defensible because `_classify_startup_failure` special-cases it — `CLIConnectionError` otherwise yields firewall/binary advice and `is_retryable=True`, which is wrong for all three launch failures (missing dir; path is a file → `ENOTDIR`; unreadable dir → `EACCES`; the latter two reach the SDK's generic "Failed to start Claude Code" arm, not its dedicated one).
  - Knock-on effects: cwd is the project key for the CLI's on-disk transcript directory, and it is where a project `.mcp.json` and `.claude/` tree would be looked for. The unconditional `strict_mcp_config=True` stops a `.mcp.json` there from injecting undeclared servers, and `setting_sources=[]` (empty by default; see **Skills** below) stops the CLI loading `CLAUDE.md`, project settings, and hooks from it — so cwd no longer drags ambient instructions in unless the workflow opts in via `runtime.provider.setting_sources`, which is exactly a request to load them from that directory. `add_dirs` (the SDK's `--add-dir` passthrough) is a separate axis, carrying the per-agent `settings_dir` and nothing else — see **Target-repository skills** below.
- **Target-repository skills** (`settings_dir`): the per-agent `AgentDef.settings_dir` is the **only** source of `ClaudeAgentOptions.add_dirs`, and it selects which directory's *project* settings tier contributes skills. It exists because cwd was doing two conflicting jobs on this provider. The CLI supports the MCP Roots protocol and advertises exactly one root — its cwd — so `@modelcontextprotocol/server-filesystem` **discards the directories in its own argv** and permits cwd alone; cwd is simultaneously what the `project` tier resolves against. Narrowing cwd onto a target repository to reach its skills therefore narrowed the agent's only MCP root below any sibling path the step still had to read. Do not derive `add_dirs` from a server's directory arguments to compensate: `--add-dir` takes no part in Roots negotiation, it widens the CLI's own file tools, and doing so would also silently widen skill discovery to directories the author named as data. What `add_dirs` *does* do, measured: a named directory's `.claude/skills` become listed and invocable with cwd elsewhere entirely — and only those, not `CLAUDE.md`, `.claude/rules/*.md`, `.claude/settings.json` (so no `env` and no `hooks` — the hooks negative is measured with a side-effect probe whose control fires) or `.claude/agents`, which all keep following cwd. That makes it the *skills third* of what a cwd-resolved `project` tier loads, not a replacement for it. It carries a second effect the skills framing hides, independent of any settings tier but **dependent on the tool policy**: `add_dirs` is "additional directories Claude can access" per the SDK's own contract, so whenever the session carries built-in file tools (`native_tools: claude_code`, agent omitting `tools:`), a `settings_dir` widens the model's built-in `Read`/`Edit`/`Bash` to that tree with no settings tier enabled at all (measured against `claude` CLI 2.1.263 at `permission_mode: "default"` with `setting_sources` unset: a read outside cwd is refused without it and succeeds with it; an agent omitting `tools:` under `native_tools: claude_code` runs under `bypassPermissions`, where the grant is unobservable because reads already succeed, and under the default `native_tools: none` there are no built-in file tools for the grant to widen at all). It does not widen what an MCP server permits. `capabilities.py::settings_dir` gates the field and `config/validator.py` errors against a provider that cannot apply it — enforced **twice**, with `AgentExecutor._reject_unsupported_settings_dir` repeating it at run time, because `conductor run` never calls the static validator — warning when the agent's session will not enable the `project` tier (also twice: `config/validator.py` at validate, and `claude_agent_sdk.py::_warn_settings_dir_without_project_tier` at run time, because `conductor run` would otherwise be silent about the no-op). Both say what the directory *still* does, which depends on the tool policy: under the `claude_code` preset it remains a grant to the built-in file tools; under `native_tools: none` or an explicit `tools: []` there is no built-in file tool to use it, so it has no effect — and claiming a grant there would send the author to remove something that does nothing. The run-time half reads this off the `sdk_tools` actually being sent (`== _DEFAULT_TOOL_PRESET`), so it runs after `_resolve_tool_config`; the static half uses `validator.py::_claude_agent_sdk_native_tools`, which also makes the per-agent-override arm stop offering "keep `settings_dir` for the filesystem grant" (an overriding agent receives no settings, so it always runs under `none`). The run-time half is latched per `(resolved directory, cause, built-in file tools)` — not per agent, because a `for_each` member is renamed per item and would otherwise warn once per iteration; not per directory alone, because the remedy differs by cause; and not per cause alone, because one line's grant claim would be false for an agent under the other tool policy. Agents sharing all three do collapse to one line. The opt-out remedy assumes the `project` tier is otherwise present: an agent with `skills: []` under a `user`/`local`-only tier is told to remove the opt-out, which is necessary but not sufficient, so that author reaches a working config in two steps rather than one. Deliberate -- distinguishing it needs a third cause value and a wider latch key to serve a combination requiring two unusual settings at once. `WorkflowEngine._resolve_agent_directory` resolves both fields so they cannot drift, and `settings_dir` is per-agent only (no `runtime.` counterpart: the repository whose conventions apply is what varies between steps). `tests/test_integration/test_mcp_roots_negotiation.py` pins the negotiation rule itself against the real server with no LLM — two runs differing only in whether the client advertises `roots` — since every option here rests on it (marked `real_api`: it fetches the server from npm and pins *upstream's* behaviour, not Conductor's). The resolved value is emitted on `agent_started` / `parallel_agent_started` / `for_each_agent_started` alongside `working_dir`, because it is a trust decision — another repository's conventions, plus a filesystem grant whenever the agent has built-in file tools — and one the run output would otherwise never mention.
- **Skills** (issue #352): `supports_native_skills=True`. Skills are enabled through the SDK, not prompt injection, and three options move together in `execute`:
  - `plugins=[{"type": "local", "path": <plugin root>}]` + `skills=["<plugin>:<skill>"]`. The SDK has no skill-*directory* surface, so `_resolve_skill_plugins` maps each directory back to the plugin that owns it via `skills/registry.py::resolve_skill_plugin`. That resolver is deliberately strict, because every one of these mistakes otherwise produces a name the CLI silently resolves to nothing: it bounds the upward walk (`_PLUGIN_SEARCH_DEPTH`), requires the skill to actually live under the candidate's `skills/` directory, requires `SKILL.md` to exist and its frontmatter `name` to equal the directory name (the CLI resolves by frontmatter name; Conductor sends the directory name), and rejects names outside `[A-Za-z0-9_.-]+` since they are joined into a comma-delimited `--allowedTools` value. A skill under no plugin root returns `None`; a plugin that is present but unusable raises `SkillPluginError`, which the provider re-raises as a `ProviderError` carrying the real reason rather than a blanket "not part of a plugin". Two plugins claiming one qualified name are refused too — deduping the clash away would drop a declared skill. All of it is `is_retryable=False`: these never become valid on a retry, and a checkout path containing "connection" would otherwise trip the retryability heuristic. Note providers are constructed lazily, so this surfaces when the first agent on this provider runs, **not** at `conductor validate`.
  - `setting_sources=[]` **by default**, for the same reason `strict_mcp_config=True` is unconditional a few lines away — but opt-in per workflow via `runtime.provider.setting_sources` (`user`/`project`/`local`, issue #501). Left unset, the CLI loads user, project, and local settings, which between them bring in ambient skills, `CLAUDE.md`, and hooks the workflow never declared, varying by machine and launch directory. Conductor surfaces instruction files through its own opt-in `--workspace-instructions`; settings and hooks have no equivalent. `skills=[]` and `skills=None` are **not** interchangeable upstream: `None` means "CLI defaults apply", and setting `skills` while leaving `setting_sources` at `None` makes the SDK re-default it to `["user", "project"]` — so the two options are coupled and dropping either re-opens the issue. The `[]` is also invisible in argv (it travels in the SDK's `initialize` control request), which is why the argv-based tests are paired with options-level assertions. The list is a context filter, not a sandbox: undeclared skills are hidden from the model's listing and rejected by the `Skill` tool, but their files stay readable. Opting a workflow in (`runtime.provider.setting_sources: [project]`, the motivating case being an agent whose `working_dir` is a *target* repo shipping its own `.claude/skills` — the CLI has `--plugin-dir` but no `--skill-dir`) loads that tier **with its hooks**, so it is only for repositories trusted as much as the workflow itself, and the field is workflow-global while `working_dir` is per agent. Two couplings follow: `_resolve_skill_filter` resolves `skills` to `"all"` when a tier is enabled and the workflow named none itself (tier-discovered skills never pass through `skill_names`, so `[]` would load the repo's skills and then hide every one), and a per-agent `skills: []` opts that agent out of the tier entirely — hooks included — keeping it the one opt-out.
  - An explicit `tools: []` sends `--tools ""` (empty base tool set), which would leave a declared skill unreachable; `_resolve_tool_config` therefore grants back the single `Skill` tool when skills are enabled. No permission bypass is needed — the SDK auto-allows it via `allowed_tools`: `Skill(<name>)` per declared skill, or the bare `Skill` on the settings-tier path, where the skill names are discovered by the CLI and Conductor has none to scope the grant to (a broader auto-approve, which is part of what enabling a tier asks for).
  - The executor→provider seam (`executor/agent.py`) is the only thing carrying the feature now that eager injection no longer backs it up on this provider, so `tests/test_skills/test_executor_integration.py::TestSkillDirectoriesReachTheProvider` asserts directories actually arrive at `execute`. A negative "no `<skills>` in the prompt" assertion cannot tell a working native path from one that dropped the skills entirely.
- **Plugins** (issue #378): `plugins=True`, `supports_native_plugins=True`. A plugin's subagents become inline `ClaudeAgentOptions.agents` (`_build_sdk_agents` maps the shared `CustomAgentConfig`-shaped specs onto `AgentDefinition`, which is keyed by name and so has no `name` field of its own; Copilot's `infer` has no counterpart and is dropped). Returns `None` rather than `{}` when there are none — unlike `skills`, an empty mapping has no opt-out meaning here, so the option stays out of the request entirely. Plugin MCP servers go through the same `_write_mcp_config` temp-file path as the workflow's own, translated per call rather than in `__init__` because `plugins:` is per-agent; the unconditional `strict_mcp_config=True` suppresses whatever a registered plugin root would otherwise contribute, which is precisely what makes `mcp: false` mean something here. **The one declared carve-out:** reaching a plugin's skills requires registering its root via the `plugins` option, which the SDK documents as providing "custom commands, agents, skills, and hooks" — with a `skills` filter and none for the rest. So `agents: false` alongside `skills: true` for the same plugin is refused in `config/validator.py` rather than silently granting more than the workflow declared, and the `hooks/` warning here says *exposed to the CLI* rather than *not loaded*, which would be false. The identical config works untouched on `copilot`.
- **Session continuity** (`session_key`): `session_continuity=True`. A per-agent `AgentDef.session_key` reuses one Claude session across executions, so an intra-run loop-back keeps the context it already built; without a key every execution starts fresh. User-facing docs live in `docs/workflow-syntax.md` (Session Continuity), with `examples/claude-agent-sdk-session-key.yaml`.
  - `_session_ids` is keyed by `(session_key, cwd)` — by the authored key rather than the agent name, because sharing one session between agents is the point, and by cwd because the CLI stores transcripts per working directory, so one key under two directories is two sessions. `_resolve_resume_session` prefers an id recorded this run over a checkpoint-restored one and passes it as `ClaudeAgentOptions.resume`; `fork_session=False` is explicit because a fork would issue a new id and strand the map on a dead session. Only `AssistantMessage` / `ResultMessage` (`_SESSION_ID_MESSAGES`) update the map — hook, task, and stream frames carry `session_id`s of their own, and recording one would shadow the real session with a transcript-less id.
  - **The transcript guard is load-bearing.** `--resume` against a transcript the CLI cannot find aborts it with `ProcessError` *before running the agent*, so a naive passthrough would turn an ordinary first iteration, a pruned transcript, or a moved `working_dir` into a hard failure. `_session_transcript_exists` checks the exact path the CLI uses, `<CLAUDE_CONFIG_DIR or ~/.claude>/projects/<project_key_for_directory(cwd)>/<id>.jsonl`. `get_session_info` answers a different question — it derives a *summary* and returns `None` when it cannot, so a resumable session can look absent, and it resolves through sibling git worktrees and a global project scan, which is wider than the `(session_key, cwd)` scoping we promise authors. (The CLI itself resolves `--resume` through those same fallbacks, so it is more permissive than this guard, not less: a cross-directory resume succeeds. The gate is deliberately stricter, to hold the scoping contract.) It is consulted only as a fallback — it tolerates a hash mismatch for very long paths — and only when its recorded `cwd` `realpath`-matches ours. Any exception degrades to "start fresh".
  - Checkpointing reuses the duck-typed `get_session_ids` / `set_resume_session_ids` hooks from `copilot.py`, so no CLI or checkpoint-schema change was needed. `copilot_session_ids` is a flat dict shared by every provider and our author-chosen keys genuinely collide with Copilot's agent names, so ours are namespaced and carry the cwd: `claude-agent-sdk:["<key>", "<cwd>"]`. Unrecognised entries are skipped rather than raised on, and the engine merges every active provider's map instead of stopping at the first (`copilot` and `hermes` still shadow each other — pre-existing). `checkpoint_resume` stays `False`: that flag is a blanket promise the startup banner reads out, and agents without a key — the default — carry nothing across.
  - `session_key` is rejected on `script` / `human_gate` / `questions` / `workflow` / `wait` / `set` / `terminate`, is whitespace-stripped with `min_length=1`, and is never Jinja2-rendered — `validate_session_key_is_literal` rejects `{{ ... }}` rather than letting it become one literal key shared by every `for_each` iteration. `_check_agent_capabilities` gates it on `session_continuity`, and `config/validator.py` rejects a key shared by concurrent executions (two parallel members, or a keyed for-each agent with `max_concurrent > 1`), which would leave two `claude` processes appending to one transcript.
- **Authentication mode** (`runtime.provider.auth_mode`): `ProviderSettings.auth_mode` (`"auto"` default, `"subscription"`, `"api_key"`) selects which credential the spawned `claude` child process uses — never endpoint routing (`has_custom_routing()` is unaffected), and never a mutation of Conductor's own `os.environ`. **`EffectiveAuthContext` is the single source of truth.** `execute()` and `validate_connection()` each call `_capture_auth_context(cwd, agent)` once, which snapshots `os.environ`, cwd, the **effective** `setting_sources` (`_effective_setting_sources`: `()` for an agent with `skills: []`, the provider's tiers otherwise and for `validate_connection()`), the provider's `configured_setting_sources`, and the non-spawning `_find_claude_cli()` result; `__post_init__` copies the inputs into a `MappingProxyType` / `tuple` (so immutability never depends on the caller wrapping them) and derives `finalized_child_env` from `_NEUTRALIZED_BY_MODE`. Both environment fields are `repr=False` — nothing may log, serialize, or render them. `_check_auth_readiness(context)` reads mode, env, cwd, sources, and CLI path **only** from the context; `_run_auth_status_subprocess(cli_path, child_env, cwd, setting_sources)` takes all four as required arguments (a default would reintroduce live process state) and runs `claude --setting-sources=<csv> auth status --json` — the flag is always sent, `--setting-sources=` for no tiers, in the exact form the SDK derives from `ClaudeAgentOptions.setting_sources`, and **before** the subcommand because the CLI's root parser uses positional options (the CLI applies it for every command in `eagerLoadSettings`, before dispatch — verified statically against the CLI bundled with SDK 0.2.87; omitting the flag would load every ambient tier and let a settings-file credential the session never sees make readiness pass); and `_execute_session` passes `env=dict(finalized_child_env)`, `cwd`, `cli_path`, and `setting_sources` from the same context to `ClaudeAgentOptions`, so the probe and the session cannot diverge. The **full** environment is passed rather than a sparse override because the SDK spreads `options.env` over a *live* copy of `os.environ` (0.2.87, `_internal/transport/subprocess_cli.py`): only keys present in `options.env` are pinned, so explicit modes write their neutralized keys as `""` **unconditionally**, even when absent from the snapshot; a key first set in the parent after capture can still pass through, a documented upstream limitation. The matrix: `auto` — no neutralization; requires CLI availability (non-spawning) in every case, then is ready without a probe when `ANTHROPIC_API_KEY` is non-blank, otherwise runs `claude auth status --json` in the context's env/cwd/tiers. `subscription` — blanks `ANTHROPIC_API_KEY` plus the five `_EXPLICIT_MODE_NEUTRALIZED` variables (`ANTHROPIC_AUTH_TOKEN`, `CLAUDE_CODE_OAUTH_TOKEN`, `CLAUDE_CODE_USE_BEDROCK`/`_VERTEX`/`_FOUNDRY`), requires the CLI, then probes. `api_key` — blanks the five, requires CLI availability and a non-blank key, and **never** runs the probe. **Both explicit modes refuse an inherited non-blank cloud-backend selector** (`_CLOUD_BACKEND_SELECTORS`, read from the snapshot via `EffectiveAuthContext.inherited_cloud_selectors()`), right after the `setting_sources` refusal and before any CLI check or probe, with an error naming the variable but never its value and pointing at `auto`; Conductor has no deterministic support for an explicit mode on Bedrock/Vertex/Foundry, so refusing makes the conflict visible instead of silently dropping the backend. The three selectors also stay in the pinned-blank set, which covers one the parent sets only after capture. `auto` passes them through unchanged. Stdout is parsed **before** the exit code, so `{"loggedIn": false}` with a nonzero exit is the specific logged-out failure, never a success. Readiness itself still requires **both** `loggedIn: true` **and** `returncode == 0`: a success payload contradicted by a failing exit code is reported as the generic unreadable-status failure, which never echoes stdout, stderr, or a credential. `_find_claude_cli` tolerates an unresolvable home (`RuntimeError`/`OSError` from `Path.home()`, as on Windows under a cleared environment) by skipping only the home-anchored fallbacks — the bundled CLI and `PATH` need no home — so discovery degrades to the actionable "Claude CLI not found" result instead of raising. **Explicit modes refuse a non-empty `setting_sources`** because a settings file's `env` block is applied by the CLI after the child environment is configured and the SDK has no override verified to outrank it; the refusal is enforced twice with one shared message (`config/schema.py::explicit_auth_mode_setting_sources_error`) — in `ProviderSettings` and again in `_check_auth_readiness`, because `conductor run` never calls the static validator — and it is checked before any success path, against `configured_setting_sources` rather than the effective tiers, so an agent's `skills: []` cannot let a contradictory configuration through. `execute()` logs the *names* (never values) of inherited credentials it blanked (`EffectiveAuthContext.overridden_credentials`). The probe is a readiness check, **not billing attribution**. Its output is filtered through `_AUTH_STATUS_WHITELIST`; `auth_status_diagnostic` keeps Conductor's `requested_mode`/`inferred_mode` separate from the CLI-observed `authMethod`/`apiProvider`/`apiKeySource`/`subscriptionType`, and `apiProvider` (a backend) is never presented as `authMethod`. `validate_connection()` returns `False` rather than raising; `execute()` raises `ProviderError(is_retryable=False)`. Doctor (`providers/diagnostics.py::gather_provider`) builds the provider with **default settings** and never reads a workflow, so it appends `AUTH_DIAGNOSTIC_SCOPE` to the diagnostic and `cli/doctor.py` renders it as a `Scope:` line — do not document doctor output as reflecting a workflow's explicit mode. Non-`auto` modes survive checkpoint serialization. **Hermetic tests:** `tests/conftest.py::_stub_claude_auth_readiness` is autouse and stubs `_check_auth_readiness` to ready for every test; a test marked `@pytest.mark.claude_auth_readiness_mocked` gets the real method instead, with `asyncio.create_subprocess_exec` replaced by a guard that fails the test, so an opted-in test must mock process creation itself and cannot silently probe the developer's real CLI. Opted-in tests also clear the environment (`patch.dict(os.environ, ..., clear=True)`) or build an `EffectiveAuthContext` explicitly.

#### `aca.py` parity notes

The ACA (Azure Container Apps) provider (`aca.py`) is an **experimental**
provider (issue #284) — see the "Experimental Providers" section below for
the carve-out policy. Unlike `claude_agent_sdk.py`, which delegates the
loop to a local CLI subprocess, `aca.py` delegates the **entire agentic
loop to a remote sandbox**: `AcaRuntimeProvider` is a thin host-side
transport shim that derives a session identifier, authenticates via
`DefaultAzureCredential`, and relays NDJSON event frames from an
in-container `conductor-agent-runner` (which itself wraps a real
`CopilotProvider`) verbatim to `event_callback`. The wire contract lives
in `conductor.runner.protocol` (issue #527), with
`conductor.providers.aca_protocol` retained as a deprecated re-export shim
(emits `DeprecationWarning` on import; will be removed in a future major
release). Because the runner re-emits Conductor's own event vocabulary and
forwards a real `CopilotProvider`'s output, this achieves **full event and
output parity** (`mcp_tools`, `streaming_events`, `agent_reasoning_events`, and
`reasoning_effort` are all declared `True`) — with the following carve-outs:

**Inner Copilot credential (DD4).** The sandbox's Copilot session can't do
interactive OAuth, so the host resolves a credential per request and
forwards it in-memory: `COPILOT_PROVIDER_BASE_URL` (BYOK) →
`COPILOT_GITHUB_TOKEN`/`GH_TOKEN`/`GITHUB_TOKEN` → **`gh auth token`** →
`ProviderError`. The `gh` step (`_resolve_gh_cli_token`) is what makes the
zero-setup path work and mirrors the Copilot CLI's own documented chain;
every failure mode (not installed, not signed in, timeout, empty output)
means "no token" and falls through rather than raising. Reading the
Copilot editor plugins' `~/.config/github-copilot/auth.db` is
**deliberately not implemented** — that store belongs to the Copilot
Language Server (not the CLI/SDK the runner drives), has changed format
twice, and is slated for encryption at rest. Note for tests: any test
asserting the "no credential" error **must** stub the `gh` subprocess, or
it will pick up the developer's real token (see
`TestAcaCredentialPrecedence._clear_credential_env`).

- **`workflow_tools_passthrough=False`**: the per-agent `tools:` allowlist
  is forwarded to the runner in the request body, but the in-container
  `CopilotProvider` it wraps never applies that list to the SDK session —
  every tool/MCP server available to the session is callable regardless of
  the declared allowlist. Combined with `mcp_tools=True` (the full
  configured `mcp_servers` set is always forwarded), there is no allowlist
  value the runner can honor — not even `tools: []` — so
  `config/validator.py` rejects **any** explicit `tools:` on an
  `aca`-backed agent, not just a non-empty one (review follow-up, #284
  E7). This mirrors the same declared carve-out on `claude_agent_sdk.py`
  and `hermes.py`. `hermes.py` declares `mcp_tools=False` (nothing is ever
  forwarded regardless of the list), so `tools: []` genuinely disables all
  tools and stays valid for it. `claude_agent_sdk.py` now behaves like
  `aca` whenever the workflow declares `mcp_servers`, and like `hermes`
  when it does not.
- **`working_dir=False`**: this capability field means "applies the
  generic, host-resolved `agent.working_dir` / `runtime.working_dir`" — a
  host filesystem path the engine resolves against the workflow file's
  directory. `aca` never reads that field; it only honors the separate,
  container-relative `sandbox.working_dir` block (documented in
  `docs/providers/aca.md#workflow-configuration`), which has no meaning as
  a host path and is not gated by this capability.
- **`interrupt`/`max_session_seconds` are declared `True` host-side but
  not fully backed by the shipped runner MVP (epic E4)**: the runner has
  no `/interrupt` endpoint yet (the host's in-stream interrupt POST has
  nowhere to land, so the host falls back to a best-effort session-delete
  call, itself unsupported for custom-container pools, before giving up
  waiting — not instantaneous; both cleanup calls use an explicit
  10-second per-call timeout), and `max_session_seconds` enforcement is only a
  best-effort, Copilot-internal timeout (the wrapped `CopilotProvider`'s
  own `IdleRecoveryConfig` check) — there is no independent runner-level
  guard. Stopping an `aca`-backed agent today eventually stops the host
  from *waiting*, not the sandbox from *computing*. See
  `docs/providers/aca.md#known-gaps-runner-mvp`.
- **`plugins=False`**: same reason as `skills=False` above — a plugin's
  skill directories, `agents/*.agent.md` files, and `.mcp.json` are all
  host filesystem paths the in-sandbox runner cannot read.
- **`checkpoint_resume=False`**: ACA dynamic-sessions sessions are
  ephemeral with no volume mount, so there is nothing in-sandbox for
  `conductor resume` to restore. A resumed workflow re-runs the
  `aca`-backed agent from scratch rather than continuing an interrupted
  sandbox session — the same posture `claude_agent_sdk.py` and `hermes.py`
  declare, but for a different underlying reason (remote ephemeral
  filesystem vs. local CLI process state).
- **Runner hardening (issue #396):** the MVP runner's posture depended
  entirely on the session-gateway network boundary; five independent,
  none-load-bearing layers now defend in depth, mirroring
  `web/auth.py`'s issue #397 framing. (1) `aca_runner/__main__.py` binds
  `127.0.0.1` by default (the container image's `Dockerfile` sets
  `ACA_RUNNER_HOST=0.0.0.0` explicitly, so it is unaffected). (2)
  `aca_runner/auth.py::resolve_runner_token` reads the opt-in
  `ACA_RUNNER_AUTH_TOKEN`; when set, `/execute` requires a matching
  `X-Conductor-Runner-Token` header (compared via the existing
  `web/auth.py::constant_time_match`, reused rather than re-derived) and
  rejects with 401 otherwise — checked *before* the inner Copilot provider
  is constructed. `X-Conductor-Runner-Token` is chosen over `Authorization`
  because the ACA session gateway consumes that header itself (it carries
  the AAD token). `GET /health` stays unauthenticated (the image's own
  `HEALTHCHECK` sends no header) but reports `auth_required` and
  `auth_token_present` — the latter is header *presence* only, never
  validity, so it cannot become a brute-force oracle — letting
  `AcaRuntimeProvider._warn_on_auth_skew` (alongside the existing
  `_warn_on_version_skew`, both inside `validate_connection()`'s
  `contextlib.suppress(Exception)` block) warn when a gateway is silently
  stripping the header, or when the host has a token configured but the
  runner doesn't enforce one. (3) `aca_runner/auth.py
  ::check_inner_provider_settings` rejects any `inner_provider_settings`
  key outside `ALLOWED_INNER_PROVIDER_SETTINGS_KEYS` (`base_url`/`api_key`/
  `bearer_token`/`github_token` — the four `AcaRuntimeProvider
  ._resolve_inner_provider_settings` actually produces), closing off
  `runtime_url`/`headers` injection that no `base_url` allowlist alone
  would catch; `ACA_RUNNER_ALLOWED_BASE_URLS` additionally restricts which
  BYOK `base_url` values are accepted. (4) The runner token header is
  merged into the `Authorization` headers dict at the three
  runner-forwarded call sites only (`execute()`, `_send_interrupt()`,
  `validate_connection()`) — **not** `_stop_session()`, whose `DELETE
  {endpoint}/session` is an ACA management-plane operation that never
  reaches the runner, so adding the header there would leak the runner
  credential to the Azure control plane instead. (5) `identifier` is
  reconciled by documentation rather than code: it remains gateway
  routing metadata the runner never inspects as an authentication signal
  (the runner has no independent source of truth for which identifier it
  should be serving, and the container `HEALTHCHECK` sends none at all) —
  see `docs/projects/aca/aca-provider.design.md`'s *Identifier as a
  capability* bullet and `docs/providers/aca.md#security`.

Full architecture, the runner `/execute`/`/health` contract, the wire
protocol (`conductor.runner.protocol` design at `docs/design/runner-protocol.md`;
`conductor.providers.aca_protocol` is a deprecated shim), the NDJSON frame
schema, and the credential/security model are documented in
`docs/providers/aca.md` and the source design at
`docs/projects/aca/aca-provider.design.md`.

### Experimental Providers

Some providers delegate part of the agentic loop to an upstream SDK or
framework and cannot honor every parity rule above. Rather than reject
them or let parity silently erode, Conductor formalizes an
**experimental tier** with explicit allowed carve-outs and a static
validator that catches workflow ↔ provider mismatches at `conductor
validate` time. See `docs/providers/experimental.md` for the full
stability policy.

**Capability declaration.** Every provider — stable or experimental —
declares a class-level `CAPABILITIES: ProviderCapabilities` attribute
(see `src/conductor/providers/capabilities.py`). The descriptor is a
contract: behavior must match what the provider declares. Lying in the
descriptor undermines the framework.

**Allowed carve-outs** for experimental providers (declared as `False` /
`None` on the descriptor):

- `mcp_tools` — workflow-level `runtime.mcp_servers` is not forwarded
- `workflow_tools_passthrough` — per-agent `tools:` allowlist is not enforced
- `streaming_events` — events emitted only at completion (not incrementally)
- `agent_reasoning_events` — no thinking/reasoning event surfacing
- `reasoning_effort` — provider has no reasoning-effort concept
- `structured_output: "prompt_injection"` — schema enforced via prompt injection only
- `interrupt` — mid-call interrupt not honored (still cancels between iterations)
- `max_session_seconds` — wall-clock session timeout silently ignored
- `checkpoint_resume` — session state does not survive `conductor resume`
- `session_continuity` — per-agent `session_key` not honored (every execution starts a fresh session)

**Non-negotiable rules** experimental providers MUST uphold:

- `AgentProvider` lifecycle (`validate_connection` / `execute` / `close`).
- `AgentOutput` shape on every successful execution (fields may be `None`).
- Raise real exceptions on real errors — no silent failure swallowing.
- Declare accurate `ProviderCapabilities` matching observed behavior.
- Declare `skills` accurately. Skills are **not** an allowed carve-out — a
  provider reaches `skills=True` either natively (`supports_native_skills=True`,
  forwarding the resolved skill directories to its SDK in whatever shape that
  SDK accepts) or via `AgentExecutor`'s eager preamble injection, which is
  provider-agnostic. Declare `False` only when
  neither path can work (e.g. `aca`, where skill directories are host paths the
  in-sandbox runner cannot read). `config/validator.py` cross-checks per-agent
  `skills:` and inherited `runtime.skills` against this flag, so an inaccurate
  `False` turns into a spurious validate error and an inaccurate `True` silently
  drops the skill content at run time.
- Declare `plugins` accurately. Unlike `skills`, this one **is** an allowed
  carve-out, because there is no provider-agnostic fallback: eager injection
  can carry a skill's text into a prompt but cannot produce a subagent the
  model dispatches to or an MCP server it calls. A provider reaches
  `plugins=True` only by honoring all three of `skill_directories`,
  `custom_agents` and `extra_mcp_servers` on `execute()`. Declaring `True`
  while dropping one is the worst outcome available — it reinstates exactly
  the silent partial load issue #378 removed.
- Provide a smoke test that exercises construct + execute paths against
  a mocked SDK.
- Maintain `concurrent_safe: true`, or fail validation when used in
  parallel/for_each groups with `max_concurrent > 1`.

**Promotion criteria** (experimental → stable) are documented in
`docs/providers/experimental.md` — full parity capabilities, named
maintainer, real-API integration test, ≥6 months stable upstream,
end-to-end example workflow.

### Run / Resume Parity

The `run` and `resume` commands must accept the same flags wherever a flag is meaningful for a resumed run. When adding a new flag to `run`, add it to `resume` too unless there's a specific reason it cannot apply.

Flags that **must** be mirrored on both:

- `--provider` / `-p` — runtime provider override
- `--metadata` / `-m` — CLI metadata merged on top of YAML metadata
- `--skip-gates` — auto-select first option at human gates
- `--log-file` / `-l` — debug log file path (`auto` or explicit)
- `--no-interactive` — disable Esc-to-pause keyboard listener
- `--web` — start the real-time web dashboard
- `--web-port` — dashboard port (0 = auto-select)
- `--web-bg` — fork a detached process running the workflow + dashboard

Flags intentionally **not** mirrored on `resume` (and why):

- `--input` / `-i` — workflow inputs are restored from the checkpoint context; supplying them at resume would conflict.
- `--workspace-instructions`, `--instructions` — the `instructions_preamble` is persisted in the checkpoint and restored verbatim; re-supplying would be ambiguous.
- `--dry-run` — resume executes from a saved point and is incompatible with planning-only output.
- `--guidance` — resume-only (issue #400); there is no equivalent "mid-run" moment on a fresh `run` to apply it before, so it has no `run` counterpart to mirror.

Implementation parity rules:

- The async helpers (`run_workflow_async` and `resume_workflow_async` in `cli/run.py`) must wire up the same event emitter, JSONL event log subscriber, console event subscriber, and `WebDashboard` lifecycle.
- The `WorkflowEngine` constructor receives the same kwargs in both paths (`event_emitter`, `web_dashboard`, `run_context`, `interrupt_event`, `keyboard_listener`, `instructions_preamble`).
- Background-process forking lives in `cli/bg_runner.py`. `run --web-bg` calls `launch_background()` and `resume --web-bg` calls `launch_background_resume()`. Both must forward equivalent options and write a PID file via `cli/pid.py`.
- Note: on resume, the dashboard is seeded with prior events before it starts accepting clients. The CLI prepends a fresh `workflow_started` event built from the **current** workflow YAML (via `WorkflowEngine.build_workflow_started_data()`) so historical events apply to the correct topology; it then either replays the original JSONL event log (`WebDashboard.replay_events_from_jsonl()` — when the checkpoint records an `event_log_path` and the file exists) or synthesises minimal `*_started` / `*_completed` pairs from the restored `WorkflowContext` (`replay_synthetic_from_context()`). The resumed engine's own `workflow_started` emit is suppressed via `engine.suppress_workflow_started_emit()` so the dashboard sees exactly one root `workflow_started` (no `wfDepth` double-count). Two disjoint sets of events are filtered on replay. `_REPLAY_ROOT_SKIP_TYPES` (`workflow_started` / `workflow_completed` / `workflow_failed` / `checkpoint_saved` / `checkpoint_save_failed`) is filtered **only at root depth** — subworkflow-level lifecycle events are preserved so frontend `wfDepth` stays balanced. `_REPLAY_INTERACTIVE_SKIP_TYPES` (`agent_paused` / `agent_resumed` / `iteration_limit_reached` / `iteration_limit_resolved` / `dialog_started` / `dialog_completed`) is filtered at **every depth**, because the control channel is the root dashboard's `resume_event` / `kill_event` / gate id no matter which engine emitted the event. Each of those sets a *global* store latch (`isPaused`, `iterationLimitGate`, `activeDialog`) that only its counterpart event can clear — plus, for `isPaused`/`iterationLimitGate` only, a root terminal event, which the first set filters — so replaying the opening half of an unresolved pair latches it on for the whole resumed run. Concretely, a run stopped then killed from the dashboard logs `agent_paused` with no `agent_resumed`, so replaying it renders Resume/Kill instead of Stop on the live resumed run, hiding the only graceful stop behind a Kill that hard-stops a healthy workflow. A pause or gate the resumed run genuinely re-enters emits its own fresh event; `dialog_message` is left unfiltered only because it is *inert* once `dialog_started` is filtered — both renderers of `node.dialog_messages` (`DialogEngagementPrompt` via `DetailPanel`, `DialogDetail` via `DialogOverlay`) gate on `dialog_active`/`activeDialog`, which only `dialog_started` sets, so replayed dialog transcripts are **not** visible on a resumed dashboard. `components/layout/Header.tsx` additionally hides all live-control buttons when `replayMode` is set, since `ReplayDashboard` serves no `/api/stop`|`/api/resume`|`/api/kill`; `replayMode` is latched in `hooks/use-replay.ts` on mount (that hook only mounts once `App`'s `/api/replay/info` probe confirmed replay) rather than when `/api/state` resolves, so a slow or failed event fetch cannot leave the live controls rendered. The resumed `EventLogSubscriber` opens the original JSONL in append mode (when available) so a multi-resume session produces one continuous log file and `run_id` stays stable for log-correlation tools.

## Pydantic AI Runner Extraction

The shared Pydantic AI execution loop from `ClaudeProvider.execute()` was extracted into `src/conductor/providers/_pydantic_ai/runner.py::run_agent_pipeline()`. `ClaudeProvider.execute()` is now a thin wrapper that:

1. Resolves the MCP manager for the agent's working directory.
2. Builds a backend-specific `build_agent_fn(toolsets, *, max_parse_recovery_attempts)` closure.
3. Converts the provider-level `RetryConfig` to the internal `PydanticRetryConfig` representation.
4. Delegates to `run_agent_pipeline(...)`.

The runner owns the toolset wiring, retry/interrupt/extract pipeline, partial-output construction, and model-name resolution. To keep existing tests green, the runner imports its Pydantic-AI seam helpers (`run_with_interrupt`, `execute_with_retry`, `extract_content`, etc.) **inside** `run_agent_pipeline()` rather than at module scope. This preserves the historical patching surface (`conductor.providers._pydantic_ai.interrupt.run_with_interrupt`, etc.) that tests rely on.

## Provider registration and validation notes

- **Provider-aware temperature bounds**: `RuntimeConfig.temperature` widens the schema upper bound to `2.0` because OpenAI supports it, but most providers (copilot, claude, hermes, aca, claude-agent-sdk) cap at `1.0`. `config/validator.py` enforces the per-provider bound at `conductor validate` time so high temperatures do not fail mysteriously at the SDK boundary. Only the `openai` provider is exempt; override agents to `openai` or keep `temperature <= 1.0` for the others.
- **Provider registration completeness**: adding a new provider requires updating `providers/factory.py::ProviderType` and `providers/diagnostics.py::_CREDENTIAL_SPECS` (and `providers/capabilities.py::_PROVIDER_CLASS_PATHS` for validate-time capability checks). Latent forwarding bugs happen when `ProviderRegistry.get_or_create_provider` does not pass new runtime fields to `create_provider`.
- **Provider creation is serialized per registry**: providers are cached per type, and `ProviderRegistry._get_or_create_provider` holds one per-registry `asyncio.Lock` across `create_provider(...)`, re-checking the cache inside it, so concurrent agents resolving one type share a single instance rather than each building one and the last write winning — which matters for any provider holding per-instance state. Cached reads stay lock-free.
- **OpenAI provider routing restrictions**: `ProviderSettings` for `name="openai"` rejects `type`, `wire_api`, `bearer_token`, `headers`, `azure`, and Copilot runtime fields with targeted messages because the native OpenAI provider always speaks Chat Completions and does not support Copilot custom routing.