Configuration

The conductor reads one JSON config, overlays a few environment variables, and fills every unset field with a default. conductor.example.json at the repo root is a complete, valid file to copy and trim.

Nothing here is required except the projects: a file with only a projects array and each project's tenant, project and repo_dir runs on defaults.

Where the file lives and how it is found

• **conductor serve -config <path>** — an explicit path. It is used as-is and never relocates the state dir.
• Workspace discovery — with no -config, the conductor walks up from the working directory for a conductor.json. A config found this way makes its own folder the state dir, so two workspaces on one host never share state.
• Default — ~/.switchyard-conductor/config.json when neither applies.

conductor doctor prints every resolved fact — the path, the state dir, each default — and prints no secret. **Read the config through doctor or one named field (jq -r '.state_dir' <config>), never by cat**: the file is what agents are pointed at to orient themselves, and anything printed into a transcript is outside what the conductor can redact or rotate. See the-config-is-read-through-doctor.

Credentials are references, never values

Five fields carry credentials — faultline_dsn, faultline_api_token, github_token, the key of each entry of callboard_forks, and rails.token — and every one of them holds a reference to where the secret is kept, never the secret itself. The loader refuses a config that holds one inline.

• env:NAME — read from environment variable NAME.
• file:/path — read from a file (mode 600). ~ expands.

Each refusal names the login that repairs that field — or, where no command writes the field, the sources that are supported — because a remedy that reports success and leaves the field as it was is worse than none. conductor faultline login also seals each project's own faultline_dsn. A bare Faultline collector address with no ingest key is not a secret and may be written inline; a GitHub token has no such harmless form — the whole value is the credential. See a-credential-the-conductor-holds-never and credentials-in-transcripts.

Top-level settings

Launchers

launchers overrides launcher per role. A value is either a bare command string or an object naming a transport, an escalate_to and/or alternates:

"launchers": {
  "judge": { "command": "opencode run", "alternates": ["claude -p --dangerously-skip-permissions"] },
  "reviewer": { "command": "claude -p --dangerously-skip-permissions", "transport": "pty" },
  "brakeman": { "command": "codex exec", "escalate_to": "claude -p --model opus" }
}

transport is "" (the direct process runtime on pipes, the default) or pty (a pseudo-terminal, which also writes raw.log). Any other value fails the config to load. A per-role entry that carries only a transport still runs the global command.

escalate_to (PRD #487) is the command a claimed bead's session runs on the LAST attempt its claim's guardrail allows — the try whose failure parks the bead for a person — and on no other. It names what runs, never when: no setting moves escalation to an earlier attempt, and it fires at most once per bead (a last attempt whose earlier escalated try already failed is parked without a session). Only the builder resolves its launcher this way (through Config.LauncherForItem, which asks the escalation first and the routing table only when the claim is not the escalating attempt); every other role, and rework, ignores the field. conductor doctor fails its escalate check when a builder's escalate_to resolves to the validator's runtime label. The behaviour is in the launcher section of names, launchers, DeepSeek; why the last attempt and not an earlier one is in escalation-threshold.md.

alternates (PRD #638) is the ordered list of launchers this role falls through to when its primary cannot serve AT ALL — the API refusing the session for capacity, or a launcher that cannot start — each a full command line of the same shape as command. Empty, the default, is a role that waits out the retry window exactly as it did before the field existed. The fall-through is bounded and returns to command on its own, it never reroutes a session that ran and then failed, and the role currently serving on an alternate is on GET /health as serving_alternate: launcher-fallthrough.md.

The model a launcher declares (--model/-m, else the CLI's own default) is part of the runtime label every claim and verdict carries, and switchyard's judge_independence decides whether a validator on the builder's binary with another model is independent. doctor warns about a claude launcher that names no model. The label, the comparison and a recommended launchers block: runtime-labels.md.

Routing

routing picks a launcher per WORK ITEM, the direction launchers cannot. It is an ORDERED list of rules; the FIRST rule matching an item wins, and an absent table routes nothing — a host that declares none resolves every launcher exactly as it did before the field existed.

"routing": [
  {"role": "pr-reviewer", "when": {"docs_only": true},                    "launcher": "codex exec --model gpt-5.6-sol"},
  {"role": "pr-reviewer", "when": {"diff_lines_max": 60, "files_max": 3}, "launcher": "codex exec --model gpt-5.6-sol"},
  {"role": "brakeman",    "when": {"attempt_max": 1, "artifacts_max": 1}, "launcher": "codex exec --model gpt-5.6-sol"}
]

A rule's when may name ONLY these signals, and every *_max is an inclusive ceiling: attempt_max, handoffs_max, artifacts_max and phase_shape (the builder, off its claim and its classified phase), and diff_lines_max, files_max and docs_only (the reviewer and the validator, off one diffstat of the tree they read). A rule naming a signal the item does not measure never fires, so an item nobody could size runs the role's own launcher.

A rule's launcher must be one the config already names — the global launcher, a role's command, its escalate_to, one of its alternates, or the built-in default. The loader refuses a rule naming anything else, a when naming an unknown signal, and a rule with no role or no launcher, each refusal naming the rule's index and the offending key.

Precedence is fixed: escalate_to on the last attempt the budget allows (the table is not consulted at all there), then the PRD's preferred model from model_launchers, then the first matching rule, then launchers. conductor doctor fails its routing check when a builder rule resolves to the validator's runtime label, and reports the table on a clean host. Every routed run names its rule on the run ledger and the feed as routing_rule, and runs.Summarize groups a window's runs by it on the Statistics page. The whole of it — the signals, the precedence, the rule that routing never changes a brief — is routing.md.

Model launchers

model_launchers (PRD #1058) maps a model name to a FULL launcher command line, the runtime a PRD runs on when it names that model as its preferred_model (served on the claim's prd_context):

"model_launchers": {
  "claude-fable-5-1": "claude -p --dangerously-skip-permissions --model claude-fable-5-1"
}

The loader refuses an entry with an empty key, and one whose command declares a different model than its key (as runtime.Model reads --model/-m), each refusal naming the key. Absent, the default, no preference is served and every launcher resolves as before.

Config.LauncherForItem resolves in four rungs: escalate_to on the last attempt the claim's budget allows (the preference is ignored there), then the claim's preferred model from model_launchers, then the routing table, then the role's launcher. A preference the map does not serve FALLS THROUGH to the table and the role's launcher — nothing is refused or parked — and the run records preferred_model with preferred_model_served: false on its run-ledger row and feed line (a served one records true), so an operator can see which PRDs asked for a model this host cannot run; runs.Summarize groups a window's runs by preferred model with served and unserved counts on the Statistics page and in conductor spend. The builder and the swarm's sessions for a PRD resolve through it.

conductor doctor's model_launchers check fails when an entry's runtime label collides with the validator's under judge_independence's model mode, and reports each entry (key and runtime label) on a clean host. An entry picks the runtime and never changes a brief. The whole of it: routing.md.

merge_lane

The merge and promote lane's tunables. Note the shape: top-level merge_lane is this object; a project's merge_lane is a boolean that turns the lane on for that project.

The object is the one non-scalar key switchyard may serve as a machine setting (PRD #664): a served merge_lane applies onto Config.MergeLane, owner included, and a dotted merge_lane.owner is refused. merge_lane is a FLEET key (PRD #700): a served value wins over this machine's own conductor.json block (and over IRONWAY_CONDUCTOR_MERGE_LANE_OWNER (was SWITCHYARD_CONDUCTOR_MERGE_LANE_OWNER)), the local value is reported as overridden, and conductor doctor warns naming the key (machine-settings-live.md).

rework

Bounds the answer to a request_changes review, a merge conflict, a red CI run or unresolved review threads (PRD #768) on a conductor PR.

patrol

The host-wide patrol (patrol.md): one pass for the whole host that raises one deduped human task per fault and repairs nothing.

criterion_diagnosis

The criterion-diagnosis lane (PRD #671, criterion-diagnosis.md): the pass that reads each FAILED builder attempt from evidence — the attempt ledger, the handoff chain, the validator verdicts, the requests declaring the criterion, the branch and wip refs, the failing lines of the whole verify output and the host load the run was written under — before the next attempt starts, and records what it concluded through switchyard's criterion-diagnosis endpoint. It is ON by default, for the reason the stall lane is: before it existed the next attempt on a failed criterion started from a truncated verify tail, and a lane that has to be switched on is one nobody switches on. It is a READER: the one verdict that changes what a builder does is resume_from_commit, which starts the next worktree from a commit the gate has already checked against the bundle.

The session is the criterion-diagnose role: read-only, briefed from internal/instructions/roles/criterion-diagnose.md with the bundle and nothing else, and resolved through launcher/launchers like every other role.

stationmaster

The stall lane (PRD #651, stalled-work.md) and, under it, the inbox pass (inbox-pass.md). Both are ON by default: the stalls the lane finds were all invisible before it existed, and the inbox entries the pass resolves each waited on a person for a lookup the conductor could make.

stationmaster.inbox:

The pass acts only on an action the server listed on that exact entry, re-read immediately before the write; everything else on the inbox is left for a person.

update

The self-update pass. On channel: "source" (the default) serve fetches the tracked ref and, on a new commit, builds it in a throwaway worktree, proves it, swaps bin/conductor and re-execs. On channel: "release" it needs no checkout and no Go toolchain: it downloads a published binary, verifies its sha256, swaps it in and restarts. Off unless enabled — a conductor that replaces itself is an operator's decision.

Both channels swap the same way: the outgoing binary is parked as <binary>.prev — the rollback point, which an operator moves back by hand — and the replacement arrives by ONE rename from a temp file in the same directory, so the binary path never holds a half-written file. Nothing that fails its gate is renamed anywhere near that path: on source the gate is the build/vet/test/smoke run, on release it is the sha256.

**The source test stage reads CI's verdict first (PRD #1007).** The target commit is a push to the tracked ref, and the forge's gate checks — the same gate_checks set every other lane on this host counts — already judged that exact sha on a clean runner. So the pass asks the forge before it runs anything: a rollup that is WHOLLY GREEN on the exact target commit stands in for go test ./..., and the outcome and the pass log then name the commit and the checks that decided it (local suite skipped — the forge's gate checks passed: green at <sha> (…)). It is asked after build and vet, so a commit that does not compile spends no forge read, and build, vet, smoke and check-config stay local and unconditional — nothing CI says about a commit says anything about the binary this host just linked from it.

A check that FAILED on that exact commit is the verdict's other half, and the pass acts on it rather than deferring: the clean runner has already run, on these bytes, the suite this host would spend timeout_seconds on, so **the update is refused without go test running at all**. The refusal lands at its own stage, ci, and names the checks that failed — update failed at stage ci (3.1s): the forge's gate checks failed on the target commit <sha> (CI / build & test); refusing to install it, and not running the local suite to learn the same thing — because a refusal reported at stage test would send an operator to read a local run that never happened. The outcome carries the same verdict (Outcome.CI, with failed naming the checks), and the pass logs it at WARN. A failure beside a run still in progress is still a failure: waiting cannot turn it green.

What remains no verdict at all is everything that judged nothing, and there the local suite decides exactly as before: a pending run, a commit nothing evaluated, a rollup of nothing but skips, a forge that cannot be read, and an answer about a different sha than the target — a red rollup read for a ref that has since moved refuses nothing, because it is not about the commit being built. A check the forge CANCELLED is in that list and not in the refusal (GitHub's CANCELLED and STALE, GitLab's canceled and canceling, which vcs reduces to a bad check so the merge lane holds, and which vcs.PRCheck.Cancelled marks as no evidence about the code it ran on, as rework's red-CI trigger and the base-fault pass already read it): a concurrency-group pre-emption or an operator stopping a hung job says nothing about whether the commit builds, and because the forge does not re-run a rollup for a fixed sha, refusing on one would hold this host on a stale binary every pass thereafter. It is no answer in the other direction too — it never finished, so it cannot make the gate green or stand in for the suite — and a cancelled check sitting beside a real failure changes nothing: the failure still refuses, naming only the check that failed. A host whose checkout has no forge remote, or whose provider cannot read a branch head's checks, asks nothing and runs the suite exactly as it always did; skip_tests drops the forge read with the suite.

The point is the failure all of this removes: a loaded host whose suite times out at timeout_seconds was failing its gate on the host's load rather than on the commit, retrying every interval_seconds, and holding serve on a stale build — 167 commits behind on 2026-10-21 — while spending a full uncached suite of CPU per attempt to learn nothing.

**trust_ci: false keeps the local-only gate, and unset is on.** The one case the gate cannot judge for itself is whether this project's CI is this project's suite — a fork whose gate checks are not this repository's, a ref CI does not run on — and that is a judgement about the forge, not about the commit, so update.trust_ci is where an operator makes it. Off, the pass runs exactly the gate it ran before any forge was consulted: no rollup is read at all, the local suite runs and decides alone, and the outcome names no CI verdict. Unset is ON, because the hosts this PRD is for are the loaded ones that configured nothing, and a switch they had to set would reach none of them.

The suite that is still local is not started into a held host (PRD #1007). Some passes reach the local go test ./... anyway: a commit CI has not judged yet, a forge that cannot be read, trust_ci off. That run is the largest thing a pass can start, and on the host this is all for it is the pass's whole failure mode — so serve hands its own spawn hold to the pass (internal/selfupdate/hostload.go). While spawn_hold_on_host_load STANDS — the host at or over patrol.load_per_core with more of its CPU going to work the conductor did not start than to its own sessions — a pass whose gate would be that suite is deferred rather than started, at its own stage, deferred, carrying the hold's own sentence: host overloaded: load 36.0 per core (threshold 2.0), …. It defers before the fetch and the build, not at the test stage, because a build spent on the way to a suite that will not run is spent for nothing either; a hold that engages DURING a pass still defers the suite at the test stage. A pass the forge's verdict decides runs in full under the same hold — green installs the commit, red refuses it at stage ci — because neither spends the host, and waiting for a quieter machine cannot make a failed commit installable.

A deferral is not a failure: nothing is refused, the binary is untouched, update carries no error, and the next pass at interval_seconds decides again — the hold has hysteresis of its own and lifts on the host's load easing. The stall detector's consecutive-failure run (PRD #651) counts it as no failure, and a run already standing is CLEARED by it, exactly as by any other pass that ends without an error: finishUpdate counts the run off Outcome.Err alone, so a deferred pass resets it rather than leaving it where it was. It is serve's hold and not the pass's, so a hand-run conductor update — an operator standing at the machine, who can see the load for themselves — is never deferred by it; a remote Upgrade now is, and answers refused with that same sentence (docs/remote-control.md).

**Where a release build comes from (PRD #797). switchyard is the version authority, and the release channel's origin is switchyard.work's public download** — the version-pinned binary at https://switchyard.work/api/v1/conductor/download/{version}/{os}/{arch}, the build switchyard publishes for this platform. **The latest GitHub Release of release.repo is its fallback**, and there is no third origin: a checkout is the source channel's origin and never this one's.

The addresses in this section are the pre-rename instance's, switchyard.work, because that is where conductor builds are published today: on 2026-10-26 https://ironway.work/api/v1/conductor/version named no build ({"pointer":null}), so a host whose base_url is ironway.work takes the GitHub Release fallback until builds are published there too.

GET /api/v1/conductor/version?os=&arch=&version= names the build this platform should run (URL and sha256) and returns switchyard's verdict on the running build; the URL it names is that version-pinned download on base_url's origin. A conductor sends its switchyard token with the fetch — attached only to requests whose scheme and host match the configured base URL, and stripped from any redirect that leaves that origin — and on that route the token is what makes it answer at all: **a tokenless GET of that route answers 401**.

That origin publishes ONE build and serves it over two routes on one origin, so do not read the authenticated one as the only way to it. The public install path takes the same build anonymously: https://switchyard.work/install/conductor.sh reads the same pointer — which needs no token either — and then fetches https://switchyard.work/download/conductor/{version}/{os}/{arch}, which answers with no credential at all. The two routes are not two builds: what that anonymous route returns verifies against the same sha256 the pointer publishes for that version, OS and arch, which is the check a conductor applies to its own fetch. Serving that download anonymously is switchyard's own to do, and switchyard PRD #795 has shipped it — on the /download/conductor/… route, not by opening the /api/v1/ one, whose 401 is that route's design and not a deployment still owed. So a machine with no switchyard token installs from that public route, from the GitHub Release or from source, and none of it changes which origin this channel updates from.

The fallback is reached when switchyard names no build — an older server, or nothing published. Then the latest GitHub Release of release.repo decides and its checksums.txt verifies the asset. Neither origin may skip that check: a pointer with no usable sha256 is never downloaded.

The out-of-date report runs **whether or not enabled is set**. serve asks the authority at startup and then every interval_seconds, logs one WARN per newly published build it is behind, and publishes the answer as /health's conductor_version and as a banner on the dashboard. A build switchyard could not judge (a local or dev build) is reported as undetermined and is never flagged. conductor update -check and conductor doctor print the same verdict.

Both of them end an outdated line with the remedy, and the remedy follows the channel. On any host that can run its own pass it is conductor update. On the source channel with no go on PATH it is the public install one-liner — curl -fsSL https://switchyard.work/install/conductor.sh | sh — because the source pass builds the tracked ref and has nothing to build it with, so naming conductor update there names a command that fails. That combination is not hypothetical: it is exactly what the one-liner produces, since channel is unset on a machine that configured nothing and therefore source. That one-liner's host is the conductor site switchyard PRD #796 builds, and it is not serving yet (switchyard PRD #796) — a GET of it answers 404 — so the install path live today is the https://switchyard.work/install/conductor.sh named above, which resolves the same pointer and installs the same build.

Keeping Forge current. Forge ships a forge update that answers current already at <v> as a cheap no-op and updated <old> → <new> when it installs, so it is a companion like any other:

"update": {"enabled": true, "companions": [
  {"name": "forge", "command": "forge update", "binary": "/usr/local/bin/forge"}
]}

Name the installed forge path as binary (the same file forge.binary resolves to). Replacing that file reaches every NEW forge process — each join, heartbeat and leave — but not a running forge daemon, which keeps the build it was started from. That half is forge.restart_stale, below.

A missing companion fails nowhere — the tool just stays at the build copied onto the host, and forge.restart_stale then compares daemons against that stale binary and finds them current. So conductor doctor prints a companions line: for each fleet tool installed here that can update itself (doctor.SelfUpdating: switchyard-mcp, forge; faultline has no update verb yet), it warns when no companion's binary — binary, else the command's first word, by base name — is that tool, names the entry to add, and warns for all of them when update.enabled is off. The name is a log label and covers nothing.

Publishing releases to switchyard. .github/workflows/release.yml builds conductor_{linux,darwin}_{amd64,arm64} and checksums.txt on every push to main (a prerelease tagged with the short sha) and on every v* tag. It publishes them as a GitHub Release, then POSTs the release record (version, commit time, and each asset's os, arch, name, sha256 and size) to {IRONWAY_BASE_URL}/api/v1/conductor/releases (was SWITCHYARD_BASE_URL). That step needs no secret: it authenticates with the run's GitHub OIDC token (the job grants id-token: write), minted fresh for each run with the switchyard base URL as its audience. Ironway verifies GitHub's signature and that the token names this repository's release.yml on main or a v* tag, so nothing has to be created, stored or rotated. The step is continue-on-error: a switchyard that is down or not yet deployed leaves an annotation on the run and never fails the GitHub release. Optional settings:

• the repository variable IRONWAY_BASE_URL (was SWITCHYARD_BASE_URL) (default https://switchyard.work), which is also the OIDC audience. The workflow still reads the old name when the new one is unset, so a repository on the old name keeps publishing where it did.
• the repository secret IRONWAY_CONDUCTOR_PUBLISH_TOKEN (was SWITCHYARD_CONDUCTOR_PUBLISH_TOKEN), a fallback sent only when the job cannot mint an OIDC token. It never overrides OIDC: a stale copy of it once made every publish a 401. The workflow still reads the old name when the new one is unset.

Hosts download the published binaries from switchyard with their own switchyard token; switchyard fetches the bytes from this repository's release through the GitHub connection of the software-factory/switchyard-conductor project, so no GitHub token has to be configured anywhere either.

forge

Whether roles run their sessions inside an Ironway Tower session. enabled is the host-wide default every project inherits; a project's own forge overrides it either way.

Stale daemons. A daemon reports the build its PROCESS runs (version and revision in forge status -json), and conductor doctor's forge line prints it beside the binary's: daemon runs X, the binary's build, daemon runs X, binary is Y — stale, or daemon build unknown with the reason (a daemon too old to report it, or a binary with no readable vcs.revision). Unknown is never read as a match and never acted on.

On every project tick, serve restarts a stale daemon when ALL of these hold: the project runs in Forge, autostart is on (the conductor is the daemon's supervisor — a daemon an operator started by hand under autostart: false is never touched), restart_stale is not false, both builds are known and the daemon's differs from the installed binary, the daemon has reported zero sessions under the same revision and pid on every tick for 2 minutes (ForgeStaleIdleWindow, a constant), and the installed binary is KNOWN usable: its build info reads, and the verb probe both answered and found every verb the conductor runs. A build not known to work is refused, logged once per binary revision, and the working daemon kept.

That includes a probe that answered NOTHING. The probe asks the binary for each verb's usage and reads the verbs it does not know off what it printed, so a probe killed by its own 5s deadline — a loaded host, a binary that will not start — prints no unknown command and names no missing verb. Before issue 6583 that empty answer read as "every verb is there", which meant the same broken install was refused on a quiet host and, on a busy one, cost a working daemon: it was stopped and started again on a build nothing had checked. Such verbs come back on forge.Binary.Unprobed instead and refuse the restart just as a missing verb does, with the daemon that is already running left serving — it is this pass's only evidence of a build that works. A verdict is kept per installed binary (path, revision, size and mtime) so the probe's four execs are paid once rather than on every tick of every project for as long as a refused build stays installed; an answer that concluded nothing is never kept, so the next tick asks again, and a rebuilt binary is a new file and is asked about afresh. "Differs", not "older": revisions have no reliable order, so a daemon started from a newer or dev build is moved to the installed one too once idle.

The window exists because zero sessions is not proof of an idle tree: Forge drops a session whose 90s lease has expired from its answer, so a build whose heartbeats lapsed (a host that slept, a stalled conductor) reads as idle until its next beat rejoins. Two minutes is several 30s heartbeats plus a rejoin; any tick that sees a session, a new pid or a new revision starts the window over.

Once due, serve sends SIGTERM to the pid the daemon reports — re-checked, under the lock below, to be the pid it watched — waits up to 10s for it to exit (never SIGKILL), starts the daemon again on the installed binary, and logs one line naming both builds. A daemon with a live session is never stopped — under required that would fail an agent mid-build. Every conductor join and Ensure holds a lock beside the repository's git directory that the restart holds exclusively from its last probe to the new daemon's start, so no conductor role can join the daemon being stopped; a session joined by anything else in the few milliseconds between that probe and the signal is not covered.

teamclaude

Route every LLM session through a local TeamClaude proxy; fail-closed when the proxy is unreachable.

When enabled, serve reads GET /teamclaude/status once per tick and derives an availability verdict from it; disabled, the port is never dialled at all. While that verdict cannot serve a session, every LLM-backed role on every project is refused as teamclaude-paused and starts nothing — including on a single unreachable or unparseable read, which fails closed for that tick. Only a repeated failure (two in a row, the count persisted across a restart) or an explicit all-blocked verdict enters the durable pause recorded at <state_dir>/teamclaude-pause.json. Throughout, running sessions and their leases, the merge lane, the attach sweep, the session ledger, the verifier and the patrol carry on: only starting is gated. Availability is re-read every tick while paused and the first read that can serve clears the record whole, so the lanes resume on that tick with no restart.

The pause surfaces as a dashboard banner, as /health's top-level teamclaude object (enabled, paused, error, record, plus reason/since/for while paused), and as doctor's availability line — which warns and never fails, a spent pool being transient capacity rather than a misconfiguration. Each transition files exactly one host-wide feed event, teamclaude.paused or teamclaude.resumed, never one per tick. See internal/teamclaude.

callboard_forks

The Callboard orgs that forked the base this host publishes, and which serve brings back up to that base right after it publishes it (PRD #775). Pure Go: no LLM session, no claim. Empty — the default — runs no step at all.

"callboard_forks": [
  {"org": "software-factory", "key": "env:CALLBOARD_FORK_KEY_SF"},
  {"org": "another-workspace", "key": "file:~/.switchyard-conductor/secrets/callboard-fork-another"}
]

When the step runs: only after the release-gated base publish both ran and landed. A build that is not the release, an unreadable version pointer and a dev build publish no base, and a publish that did not land — a document Callboard refused, a role left unbound — published half of one; in all of those the step is skipped and nothing is pulled. A publish that LANDED and failed its post-publish CHECK is pulled over: that check says nothing about whether the base is whole, and gating on it left a fork 27 of 27 roles behind for two days (switchyard issue #5082). The failed check is reported instead — briefs-publish on the patrol, and the briefs line in conductor doctor. The one exception is per ROLE and not a skip: a role in the publish's unresolved — one the base does not serve as this build renders it — is withheld from the pull while every other role follows the base, since pulling it hands each fork the same divergence.

What it pulls: exactly the conductor's own roles (instructions.Roles()) that base_status reports behind with no local edit — the fork's text is an older base edition, verbatim, so taking the newest discards nothing.

What it never touches: a role the fork edited (diverged, or behind with no matched base edition), which is reported with both editions and left alone; unbound, missing, local-only and no-document, which are decisions and not drift; a role the conductor does not run; a role the base does not serve as this build renders it (the publish's unresolved); and any fork whose key names another org. It never forces a pull.

Each fork runs under its own two-minute timeout in the publish's background goroutine, so neither a slow nor a failing fork delays or fails serve's start. The result is callboard-forks.json under the state dir, read back by GET /health as callboard_forks and by conductor doctor, which prints one line per configured fork (tracking N · pulled M · edited K) and never calls Callboard itself for one.

With the list EMPTY the step says so once per serve start, and a callboard-fork-<org> file in this host's sealed store that no entry names makes that a warning naming the org: a fork somebody installed a key for and did not finish wiring up. conductor doctor prints the same state and how far behind it is (fork not configured — 27 of 27 conductor roles behind the base), which is the one fork reading that calls Callboard — GET /api/v1/org then base_status, never pull_base, since a fork with no entry has no record to read. The whole step is callboard-integration.

callboard_publish_org

The Callboard org a brief publish from this host may write into (switchyard issue #5578). Empty — the default — names none.

"callboard_publish_org": "switchyard"

Why the setting exists. A publish writes as the OPERATOR and never as the org key (PRD #794), and Callboard's document, snippet, role and binding routes carry no org at all — the org is read off the bearer. So the target of a publish was never chosen by anybody: it was whichever workspace Callboard resolves for the login auth.Resolve happened to find, and the cbk_ key in callboard.env has no say in it. On one host that login resolved to software-factory, a fork of switchyard: every release from 2026-10-06 landed in the fork, the base kept its 10-06 text, pointing IRONWAY_CONDUCTOR_CALLBOARD_TOKEN (was SWITCHYARD_CONDUCTOR_CALLBOARD_TOKEN) at the base's key changed nothing, and no reader said a word.

It is a HOLD, not a route. Naming an org here cannot send a write somewhere else — there is no route that takes one, which is the companion Callboard issue. What it does is refuse: the publish resolves the org the write WOULD land in (GET /api/v1/org under the same operator bearer every write presents) and, when that is not this slug, writes nothing — not a document, not a snippet, not a binding, and not even the read of a body that decides whether anything changed — and names both slugs with the remedy. To release to another org, publish from a host whose operator login is an operator of it.

Unset still says where it went. Every publish names the org it writes into, configured or not: conductor instructions publish prints publishing into callboard org <slug>, and serve's publish at start logs callboard briefs publish target. That half needed no setting, because the fault was a host that could not say which workspace its release reached.

conductor instructions publish --org <slug> is the same hold for one run, and it outranks this field in both directions — the narrower statement wins.

conductor doctor prints the standing on its own callboard-pub line: the org a publish writes into, and, when that org is a fork, how many of the conductor's roles read behind the base and how many read diverged (which a pull would discard). A warning, never a fail, and it never pulls — it is the drift this host is creating, which no other fork reading can see, since this host holds neither a callboard_forks entry nor a key file for it.

rails

Ironway Roundhouse is a self-hosted, Buildkite-shaped CI. It reports to GitHub as commit statuses — roundhouse/<pipeline> for a build, roundhouse/<pipeline>/<step> per step — and every lane already reads those through the forge's rollup with no configuration. This block adds the two things the rollup cannot give:

"rails": {
  "url": "https://ci.example.com",
  "token": "file:~/.switchyard-conductor/rails-token",
  "native_checks": ["outdoorsea/switchyard-conductor"]
}

• Reruns. A base-ci patrol finding whose failing check links to a build under url names its run rails-<build id>, and the "Re-run failed checks" remedy (and the flake warden's rerun) calls Ironway Roundhouse's retry-failed for it — the failed jobs only, as the forges' reruns do. Without this block an Ironway Roundhouse check has no run id, as any external CI's.
• Native reads. For a listed repository HeadChecks asks Ironway Roundhouse first, and uses its answer only when Ironway Roundhouse vouches for the head's SHA (it saw the push, or the caller named the SHA); anything else — an error, a guessed SHA — falls back to GitHub, exactly as before. Checks read either way carry the same names and verdicts, so one fault is one fault.
• Failed test names. The flake warden reads WHICH tests a red rails-<build id> run reported off the build itself: the jobs that ran and failed for themselves (GET /api/v1/builds/<id>), each of their logs (GET /api/v1/jobs/<id>/log) read for the runner's own --- FAIL: verdicts by the same reader that reads an Actions run's. A retried attempt, a soft failure (Rails posts one as success) and a job that never ran are not read. Anything short of a whole reading — no block configured, a server that serves neither route, a log it will not give or one over 16 MiB, a failed job whose log names no test — answers NO test, on which the warden holds nothing and the red goes to rework as it did before (flake-warden). This is the conductor half of the cutover gate below: what the required status has to carry before it may move, and the half a server that serves no readable log still holds.
• The shadow comparison. conductor rails-shadow compares a week of a repository's roundhouse/<pipeline>/<label> statuses with its Actions check runs head by head, naming every disagreement by label and whether the Rails build was head-only while the Actions run was the merge ref (PRD #1053, the shadow report). It needs NONE of this block to read the verdicts — both CIs' entries are on the head's rollup — and it uses the block for one thing: with a server armed it can ask which ref a build checked out (GET /api/v1/builds/<id>), and without one every line's merge-ref answer reads unknown rather than being assumed either way. Nothing it reports moves a required check; the cutover is a person's call.
• The agent roster (GET /api/v1/agents) is what conductor doctor's ci-tools line reads to name the hosts a job will run on: one ok/fail line per agent host, saying whether the tools a project's factory-ui step needs (node and python3, read from the clone's own ci.yml) are there — probed on PATH for the host doctor runs on, and from the agent's declared tags for every other host. Without this block only this host is reported. It fails no host: see internal/doctor.

The cutover — the two stages, and what the required status carries. This repository's own CI is translated to Rails as the pipeline conductor: .swrails.yml runs every .github/workflows/ci.yml job the fleet can execute through one scripts/swrails-ci.sh (which refuses a step ci.yml does not define, so the two cannot drift silently), each step labelled with the Actions check name so Rails reports it as the commit status roundhouse/conductor/<label> and the two sides pair by label. The move is in two stages — the shape Ironway itself took, a shadow pipeline beside Actions before any required check moves — and only the first has shipped:

1. The shadow stage, shipped. Both CIs build every head, and conductor rails-shadow compares a week of them label by label (the shadow report). Actions is still the gate: the staging ruleset's one required status check is Actions' build & test, which is also what the merge lane reads, and the required status has not moved — no ruleset on this repository names a roundhouse/ context, and nothing in this repository changes that by itself, because a required check is a forge setting a person makes. (main requires no status check at all: it takes what the promotion carries across, which is why the promotion gate rather than a ruleset is what reads a head there.)
2. The required status, not shipped and gated rather than scheduled. The second stage makes roundhouse/conductor the required check on staging, points this project's gate_checks at it (roundhouse/, the prefix form, names the whole CI without listing its pipelines), lists this repository under native_checks, and leaves Actions running only the jobs Rails cannot: every job needing contents: write — release.yml's publishing job, on a push to main and a v* tag — and promote-only-main.yml, whose checker runs only on a pull request targeting main. It is taken after a week of the shadow stage's report, on a person's reading of every disagreement in it, and not before the four readings below hold. **native_checks is the one of those edits that is not symmetric**: the native read sees Ironway Roundhouse's checks and nothing else, and after the cutover Actions still reports head-ref on a pull request targeting main — the gate that keeps a branch that is not a promotion out of main, which Rails cannot run and which the promotion's own lanes read off the rollup. Listing this repository would drop it from what they read, so the cutover's native_checks entry is a separate call from its required check, not part of the same edit.

Stage 2, written down and not applied (read back 2026-10-26). A session was asked to take stage 2. It made none of the changes, because none of the preconditions hold. This host's config has no rails block at all (url unset, no native_checks), so no Rails server builds this repository. No shadow week exists. internal/flake now reads a rails-<build id> run's failed tests off the armed server as well as an Actions run's off gh run view --log-failed, so what that half of the gate still waits on is the server's log (SR-1052) and not the conductor's read of it. The staging-2 ruleset still requires only build & test, and staging-1 and Main Protection require no status check. Requiring roundhouse/conductor today would hold every staging merge on a status that nothing reports. When the gate above clears, a person applies these edits and reads each one back:

• Host configs. Add a rails block (url, and token as an env:/file: reference) to every host config that serves this repository. After that, as the separate call described above, list outdoorsea/switchyard-conductor under native_checks.
• Required status. In ruleset staging-2, replace the required context build & test with roundhouse/conductor. In this project's gate_checks, set roundhouse/.
• **What roundhouse/conductor then carries.** It is the build-level status of the conductor pipeline. It is green only when every .swrails.yml step is green: build & test, race, integration, factory interactions & assets, gofmt, added code has a caller, CLAUDE.md budget, AGENTS.md budget, config keys, promote-only-main gate and rules index. Each step also reports as roundhouse/conductor/<label>. That covers the verdict. It also carries the run id rails-<build id>, but only on an armed host. It carries the failed test names once the server serves a build's failed-step log over the API (SR-1052): the warden's read of one is already here.
• Actions trimmed. Delete .github/workflows/ci.yml, whose jobs roundhouse/conductor now carries. Keep release.yml, whose publish the release assets job needs contents: write to publish a release. Keep promote-only-main.yml as well. That is the one exception to "only contents: write": it needs only contents: read, but it runs on a pull request targeting main, which Rails cannot run, and it reports the head-ref check.

**The shadow is reporting, under roundhouse/ (read back 2026-10-29).** The Rails server now builds this repository and posts its statuses as roundhouse/conductor and roundhouse/conductor/<label>. It took the Ironway Roundhouse name, so no live context starts with rails/ any more. Every rails/ above that names this pipeline's status now reads roundhouse/, and conductor rails-shadow reads both prefixes. While stage 2 is not applied, those statuses are a shadow, and a shadow must not hold a merge. Before idea-261747, the merge lane counted every rollup entry under an unset gate_checks. A red roundhouse/conductor (a Pipeline upload exiting 127 on an agent host) then held every green, approved request on checks failing on any host that runs the lane. .conductor/project.json therefore lists roundhouse/ under advisory_checks. The statuses still count for rework, the stationmaster and the shadow report, and they never hold the merge. Applying stage 2 means removing that entry in the same edit that sets gate_checks.

What the required status carries. Naming a check required names the one artefact this repository's lanes reason from, and only the first of the four readings they take off it is the verdict:

• The verdict, off the head's status-check rollup. Rails carries this with no configuration at all — every lane already reads roundhouse/<pipeline> and roundhouse/<pipeline>/<step> through the forge — and gate_checks is what decides which rollup entries count for a project.
• A run id, for the re-run. An Actions check run carries its own; a Rails commit status carries one only through its target URL, decoded as rails-<build id>, and only on a host where this block is armed. So the precondition is the rails block in EVERY host config that serves this repository rather than one: an unarmed host reads a roundhouse/conductor red as any external status with no run id, and the "Re-run failed checks" remedy has nothing to call.
• The failed test names, for the flake warden — this is the gate. internal/flake holds a red out of rework only when it can name WHICH tests failed, keyed by package and test, which it reads out of the failing run's own log (verifyfail.FailedTests, over gh run view --log-failed for an Actions run and over the Rails API for a rails-<build id> one). The conductor half of this reading is now in place: a red Rails build's failed jobs and their logs are read for the runner's own verdicts (§rails above, the flake warden), so the run id no longer answers no tests by construction. What it answers is only as good as the log the server gives it, and a reading short of a whole one answers NO test — the same silence as before. While Actions is required every red is read off ITS run and the warden is unaffected; on the day roundhouse/conductor is the required check, that silence would cost this repository its flake warden, and every flake on its own CI would buy a rework session whose whole output is "re-ran, green" (about 1.8M input tokens in the measured window — the flake warden). Rails SR-1052 is the server half the cutover still waits on: a build's failed-step log, readable over the API as go test's own output, carrying both the --- FAIL: <test> lines and the per-package FAIL\t<pkg> verdict lines the register keys by. Until a measured Rails red names its failed tests through that route, the gate holds and PRD #1053 with it.
• The ref it built. Actions builds a pull request as the merge ref while Rails fetches the head (Rails pitch #1133), so a disagreement between them may be about the code or only about the ref. The shadow report measures it per head rather than assuming it either way, and reports a server that does not say as unknown.

The block is armed at process start beside the GitHub identity, so a change needs a restart.

retro

The retro role's block (see prd-retro).

attach

conductor agent attach, an operator's terminal on a pty session.

model_prices

Prices reported token usage for the registry's daily_spend_cap, in USD per million tokens by kind. A key matches a model exactly or as a prefix (claude-opus-5 covers both the dated claude-opus-5-20260115 and the context-tier claude-opus-5[1m] a launcher reports); the longest match wins. A model with no row is never capped — the conductor will not stop a role on a number it cannot compute — and the dashboard says so.

Price every model the host's launchers can reach, not just the default one: a per-role launcher names its own (launchers.judge = "opencode run"), and a single missing row leaves that model's whole registry role uncapped while the cap still reads as satisfied — daily_spend_cap reports $0.00 spent for an unpriced model and never fires.

"model_prices": {
  "claude-opus-5":    { "input": 5, "cache_creation": 6.25, "cache_read": 0.5, "output": 25 },
  "claude-sonnet-5":  { "input": 2, "cache_creation": 2.5,  "cache_read": 0.2, "output": 10 },
  "claude-haiku-4-5": { "input": 1, "cache_creation": 1.25, "cache_read": 0.1, "output": 5 },
  "deepseek/deepseek-v4-pro": { "input": 0.28, "cache_read": 0.028, "output": 0.42 }
}

Per-project settings

Each entry of projects. Only tenant, project and repo_dir are required.

Text budgets

A gate that measures a file's SIZE fails every open pull request at once and none of them can fix it — the fault is the base's. text_budgets names such gates so the conductor may answer one with a bounded whitespace trim instead of a repair item (PRD #500):

"text_budgets": [
  {"check": "CI / claude-md-budget", "file": "CLAUDE.md", "max_bytes": 40960}
]

check is the check's name exactly as the rollup reports it, file is the one file it measures, and max_bytes is the ceiling it enforces. All three are required — a half-written marking fails the config to load rather than sitting there looking armed.

Marked, and only marked, a base fault on that check — or an unguarded base measured over the budget — may cost ONE trim pull request against the integration branch, on conductor/<install-id>/base-trim/<check>, whose only edits collapse runs of intra-line whitespace to a single space and strip trailing whitespace in that file. It is taken only when it actually lands the file under the budget; a trim that would not clear it opens nothing and the ordinary repair item is raised instead. Indentation, fenced blocks and line breaks are never touched, no other file is edited, the budget itself is never raised, and there is at most one open trim per gate — a trim that does not clear the fault escalates to the repair item rather than to a second trim.

Unset (the default) is no auto-fix at all: every base fault takes the repair item, exactly as it did before.

Roles

Implemented as sessions: brakeman, judge, pr-reviewer, rework, validator (the contract lane; opt-in), dedup-scout, idea-scout, security-scout and refactor-scout (propose-only, off unless listed — scouts), steward, retro, answerer, triager, replier, directive (the @Conductor answerer; needs a bound Buzz channel), pr-fixer (works an escalated pull request; off unless listed — internal/prfixer), swarm (builds one PRD's queued plan as several sessions on one branch — swarm), issue-fixer (a batch of issue-N beads → a verified fix PR, a question or a coded close — issue-fixer), idea-builder (the same engine on a batch of approved idea-N beads → a built PR, a question, a coded close, or a CHECKED PRD draft for an idea too large for one bead — the idea build lane), doc-scout (the one cadence role that pushes — doc-scout), fresh-audit (a weekly fresh-session measurement whose answers land on the Triage tab — fresh-audit), yardmaster (a pure-Go pass that proposes acts and, under its lane lease, nudges stalled work through the lanes that own it — never merges — yardmaster), meta (one VR-factory conversation turn, read-only tools — internal/meta), combination (trial-merges the held set and runs the suite over it — combination lane) and harness-read (measures an open harness-edit pull request against the regression set — harness-edit read). Every one of these is off unless listed — except yardmaster, which is ON by default, and is turned off per project with yardmaster: false rather than by leaving it unlisted (its acts switch off per kind in yardmaster_nudges). shipper runs in-process (pure Go, no LLM). dedup-scout, idea-scout, retro, doc-scout, fresh-audit, combination, harness-read and the two scouts are cadence-gated rather than queue-gated.

Some lanes run without being listed. The swarm assessment assesses each newly approved PRD and, through decompose, queues a plan for the swarm lane. A project that does not list swarm still gets those plans queued, and nothing builds them. The host-wide patrol is in no project's roles and runs on its own clock.

dm is retired (PRD #654). A project still listing it loads with one warning and starts no listener: the role polled the relay with a buzz-key PRD #586 stopped minting, and switchyard PRD #585 decrypts a direct message to the Conductor server-side and serves it as a directive the directive lane already claims, so a listener here could only double-answer that lane. Drop dm from roles and dm from the buzz block to clear the warning; nothing else changes.

Buzz binding

"buzz": {
  "community_host": "software-factory.switchyard.work",
  "channel_id": "abc123",
  "events": "important",
  "dm": true
}

The shared build directory (IRONWAY_CONDUCTOR_BUILD_DIR (was SWITCHYARD_CONDUCTOR_BUILD_DIR))

Every project has a build directory the conductor creates at <state_dir>/<tenant>/<project>/build/ (PRD #828). Its path is exported as IRONWAY_CONDUCTOR_BUILD_DIR (was SWITCHYARD_CONDUCTOR_BUILD_DIR) to every run the builder starts for the project (the setup, the LLM session, the off-turn waits and the verify) and to BOTH of the contract lane's runs — a criterion's verify_command, and the system-level run a criterion tagged [smoke] or [journey: <name>] owes after it, which goes through the same runner and so the same environment. It is not a config key: there is nothing to set, and a project that never reads the variable is unaffected.

It exists so that build output which does not depend on the branch can live outside the checkout. A checkout then holds source, and the session-end rule (a checkout whose commits are on origin leaves when its session ends) and the hourly sweep have little to remove. Whether a project uses it is the project's own choice, made in its setup_command and verify_command; the conductor creates and exports the directory and never writes into it. Many checkouts of one project run at once, so key anything that must not be shared off the checkout, as the examples do.

conductor doctor reports what the directory holds on the project's worktrees line, and says nothing about it while it is empty. conductor gc -build-dir empties every project's directory and keeps the directory itself; -dry-run measures without removing. The whole run is refused while a serve is up on the state dir (it can start a build there at any moment), and a project with any session running is refused, naming the sessions, because a running setup, session or verify may be reading or writing there; the other projects are still emptied, and the command exits non-zero while any project was refused. The hourly maintenance pass never empties it: doing so costs every checkout of the project its cached output, which is a person's call.

Go already shares one build cache across checkouts (-trimpath, see one build cache across worktrees); the directory is for what the cache does not hold, such as built binaries:

go build -o "$IRONWAY_CONDUCTOR_BUILD_DIR/bin/$(basename "$PWD")/" ./cmd/...

Node: point the package store at it, so each checkout links packages instead of downloading and unpacking its own copy:

pnpm install --store-dir "$IRONWAY_CONDUCTOR_BUILD_DIR/pnpm-store"
# or, with npm, share the download cache:
npm ci --cache "$IRONWAY_CONDUCTOR_BUILD_DIR/npm-cache"

Rust: Cargo's target directory is the largest thing a checkout grows. A target per checkout keeps builds from contending on Cargo's lock while still moving the bytes out of the tree, and sccache can share compiled crates across them:

export CARGO_TARGET_DIR="$IRONWAY_CONDUCTOR_BUILD_DIR/cargo-target/$(basename "$PWD")"
cargo test

The checkout's own tools on PATH

A contract is written the way its author runs it: a Python project whose setup_command builds a .venv declares pytest tests/test_recap.py, a Node project whose setup runs npm ci declares vitest run. A builder's verify script activates the venv or goes through npm run, which put the checkout's own tool directories first on PATH; a lane running the same line with sh -c does not, and pytest was exit 127 (command not found) on every contract run. So every run the conductor makes of a verify_command or a setup_command in a checkout — the contract lane, the post-merge check, the combination verify, the validator's issue-fix contract, and the setup every lane runs in a fresh worktree — prepends to PATH, in this order and each only while it exists as a directory in that checkout at run time:

<checkout>/.venv/bin
<checkout>/node_modules/.bin

The rest of PATH is left as it was. A checkout holding neither runs with PATH untouched, nothing outside the checkout is consulted, and nothing is activated or sourced: a venv at another path, or a tool the project installs elsewhere, is still the project's own verify_command to reach. It is not a config key. The LLM session's own environment is not touched by this; the session's brief tells it the project's standard paths. Where the rule lives: the contract lane.

The .noindex heavy roots and conductor gc -noindex

The state dir's heavy roots are real directories named <name>.noindex, each with a relative symlink at <name>: every project's worktrees, lanes and build, every sessions root (the host's and each project's), and session-archives. Spotlight skips any directory whose name ends in .noindex, so a macOS host does not index what the fleet writes, with no sudo and no operator step. Nothing in the config names the suffix and there is nothing to set: every path the conductor derives (the work root, the session roots, the build dir a session is handed) is the unsuffixed one and resolves through the link. serve makes a missing root this way on its start; it never renames one that exists. The layout is the same on Linux, where it costs nothing.

An install whose roots predate this has plain directories. conductor gc -noindex moves them: each plain root is renamed to <name>.noindex with the link left at the old name, every git checkout under a moved worktrees or lanes root gets git worktree repair (its clone records it by the path it resolves to), and any missing root is made suffixed. -dry-run lists what would move and what would be repaired. The whole migration is refused, naming each session, while any recorded session is running: a session holds paths under the roots it would move. It is also refused, naming its pid, while a serve is up on the state dir, idle or not, since serve can cut a checkout under a root mid-rename; a dry run still reports and says so. Stop serve, run it, start serve again. It exits non-zero when refused or when a root did not end up suffixed. conductor doctor's spotlight line lists the roots still plain. See Spotlight on a macOS host.

Registering a project from its repository

A repository can carry its own conductor defaults in .conductor/project.json: a project block in the same shape as a projects[] entry above.

{
  "tenant": "acme",
  "project": "widget",
  "default_base": "staging",
  "roles": ["brakeman", "judge", "pr-reviewer", "rework"],
  "max_brakemen": 2
}

The file may not set verify_command or doc_scout.verify_command (PRD #627), nor preflight (PRD #1006) — projectsettings.CommandKeys: each names a command this host RUNS, and a repository that could set it could make every host that serves it run anything. A copy that sets any of the three is refused whole, so doctor -preflight fails and serve does not start. Set them in the host's conductor.json entry, which is laid over the copy; a project that declares no preflight still gets one, derived from the commands that entry carries.

conductor project add registers the project by name, from a checkout, from a clone URL, or — given no argument — from a pick on ironway.work (it opens the connect page, prints the URL when no browser opens, and waits for the pick):

conductor project add                                    # pick it on ironway.work
conductor project add acme/widget                        # switchyard names the repository
conductor project add ~/src/widget                       # an existing checkout
conductor project add git@github.com:acme/widget.git     # clones into ./widget
conductor project add <url> --into ~/GitHub/widget --project acme/widget --mode local

It copies the file to <state_dir>/<tenant>/<project>/settings.json and writes a conductor.json entry that holds only this host's facts:

{ "tenant": "acme", "project": "widget", "repo_dir": "/Users/me/src/widget",
  "vcs": "github", "settings": {} }

Roles come from switchyard's Governance. For a NEW entry, add reads the project's role registry (GET {P}/roles, the read serve and doctor use) and writes roles as the conductor roles that serve each row switched on there, printing builder → brakeman, rework, swarm for each row it used. A row brings in the standard roles a fully configured project runs — builder: brakeman, rework, swarm; reviewer: pr-reviewer; validator: judge, validator; answerer: answerer; shaper: replier, meta; triager: triager, idea-scout, dedup-scout, retro; steward: steward; shipper: shipper — and never the lanes a project opts into one at a time (pr-fixer, issue-fixer, idea-builder, decompose, doc-scout, the two propose-only scouts, fresh-audit). directive is ungoverned and needs a bound Buzz channel, so it is added by hand. --roles a,b,c writes exactly those instead, without reading Governance. A settings file that declares roles keeps them: the entry writes none, so the file stays the source. If the registry cannot be read, or switches on nothing this host runs, the entry writes no roles, the default applies, and add says why in one line. An existing entry's roles are never rewritten.

The loader lays that entry over the copy, key by key. A key in the entry wins, including an explicit false or 0. Every key it leaves out comes from the repository. To override one setting on one host, add that key to the entry.

With no --base or --ref, add looks for the file on the remote's default branch, then on main, master, staging and develop, and uses the first branch that has it. A settings file merged to staging is found before it is promoted. A repository with no origin is read at HEAD. If no branch has the file, add registers the project anyway and prints the branch sync will watch.

add refuses a duplicate registration. It also refuses a settings file that sets a host-owned key — repo_dir, dolt_data_dir, faultline_dsn, settings or settings_shadow_apply (an authority knob, PRD #1076, which only an operator grants) — or a command key — verify_command, doc_scout.verify_command: the host owns those keys, and the credential rule above still applies. tenant and project in the file only name the project when --project is not given. If the resulting config does not load, add restores the config and removes the copy.

Ironway fills in what the command line and the repository leave out:

• A name alone (add acme/widget, which a directory of that name overrides): add reads GET {P}/repository, clones its https URL into <state_dir>/repos/<tenant>/<project> (or --into), and writes the project's integration branch as default_base unless --base or --ref is given. A project with no connected repository, or a switchyard that predates the read, is refused with the remedy: connect one, or pass a checkout or URL.
• A checkout that names no project: add reads GET /api/v1/scope/by-repo?remote=<origin>, which matches only projects the credential can reach. No match, or more than one, is refused and says so.

Neither lookup runs when the command line or the file already answers it, so registering a named local repository still needs no network.

The settings binding

A sync reads a commit on the remote-tracking ref after git fetch, never the working tree. Only a merged change reaches the host, and an agent's uncommitted edit in the checkout never does. A commit whose file fails the checks above is refused, and the host keeps its last good copy. A failed sync is retried after 30 minutes. If the repository deletes the file, the copy is removed too. serve checks for due copies every 5 minutes and reloads itself when one changed.

conductor project list                      # each project, its mode, the ref@commit it was read at
conductor project sync [acme/widget] [--force]
conductor project mode acme/widget local    # keep and edit the copy
conductor project mode acme/widget sync     # follow the repository again (re-reads at once)
conductor project remove acme/widget        # drop the entry (refused while a session of it runs); checkout and state dir kept

Environment overrides

A few keys can be set from IRONWAY_CONDUCTOR_* (was SWITCHYARD_CONDUCTOR_*) variables, which override the file: BASE_URL, STATE_DIR, CALLBOARD_URL, CALLBOARD_TOKEN, LAUNCHER, JUDGE_LAUNCHER, POLL_SECONDS, LEASE_SECONDS, RELEASE_COOLDOWN_SECONDS, AGENT_PREFIX, MERGE_LANE_OWNER (outranked by a merge_lane switchyard serves — a fleet key, see merge_lane), DM_POLL_SECONDS, DEDUP_INTERVAL_SECONDS, DASHBOARD_ADDR, and the FORGE_* and TEAMCLAUDE_* knobs. A one-project host can be given entirely from IRONWAY_CONDUCTOR_TENANT (was SWITCHYARD_CONDUCTOR_TENANT) / PROJECT / REPO_DIR (plus optional VERIFY_COMMAND, DEFAULT_BASE, VCS, BUZZ_COMMUNITY_HOST, BUZZ_CHANNEL_ID).

The two credential env vars use their unprefixed documented names — FAULTLINE_DSN, FAULTLINE_API_TOKEN, FORGE_FILE_KEYSTORE — because those are what the collector and Forge already document, and an exported DSN always outranks the file.

Applying a change to a running conductor

conductor refresh — or Reload config in the dashboard, which POSTs the loopback-only /reload — re-reads the config file and the IRONWAY_CONDUCTOR_* env, rebuilds the client if base_url changed, re-resolves each project against the new server, recomputes prefixes and drops removed projects. The swap itself happens inside the serve loop, and the call answers with the outcome of that swap (PRD #547) rather than with a bare 204.

It answered 204 until #547, and 204 meant only "the request was posted". On 2026-09-17 an operator raised max_judges (4→8 on one project, 4→6 on another) and max_validators and called POST /reload. The call returned 204, /health still reported judge=4/4 two minutes later, and the new caps appeared about five minutes on, when serve restarted itself for an unrelated update. The file had been right the whole time: the running process had either refused the swap or never applied it, and the answer could not say which.

There are four answers, and only the first reports the change as live:

What cannot change live. A few settings are read once, before the loop begins, and a reload KEEPS them rather than half-applying them: dashboard_addr (the listener is already bound) and state_dir (every session root, ledger, catalog and sealed-secret path was derived from it at start). They are named in the applied answer, on the kept side, so an edit that will need a restart says so when it is made rather than when somebody notices it did nothing. That set is ONE table in internal/orchestrator, walked by a test against Config's own fields: a setting added to the config and named in neither the live set nor the restart-only set fails the test, so a new key is classified by whoever adds it instead of defaulting silently to either side.

Is the file on disk the one running? GET /health carries the live config's loaded-at time and a digest of its content (config_loaded_at, config_digest), and the dashboard shows both. The digest moves on an applied reload and does not move on a refused one, so "is my edit live?" is a read: same digest as before the call and the running config is the old one, whatever the call said.

A reload never touches a running session. No session is killed, restarted or re-briefed by a swap. A changed cap is read by the next spawn decision, so a max_brakemen lowered below the number of live builders leaves every one of them to finish and gates only the next spawn — trimming a cap is "start fewer from here on", never "stop what is running", which is what conductor pause is for. detail

**A project registered while serve runs is on the event feed from the swap (PRD #627).** The feed watchers are started once, before the loop's select, over the projects the config held at startup — so a project added by conductor project add (which writes the file and then POSTs /reload) or by a settings sync used to be polled only until somebody restarted the process, and every role on it waited out a whole poll_seconds for work the feed had already announced. The swap now starts the watcher the new project is missing, on the same context serve cancels on its way out, so the stream opens within seconds and still stops with the process. It is idempotent by project: a reload that registered nothing starts nothing, which is what keeps config_watch — a reload per saved edit — from accumulating a watcher per save. Arming the feed itself is still a restart (base_url is restart-only), and a project that LEAVES the config keeps the watcher it has until the process ends.

Without a call at all. config_watch (above, default off) watches the config file and applies a saved change through this same path after a short debounce, reporting each application the way an explicit reload does. The debounce is why one save is one application rather than one per write, and a file that does not parse or does not load leaves the running config in place and is reported rather than applied. A file that reads as a save still in progress — it moved while it was read, or it is empty or its JSON ends early, what an os.WriteFile-style save looks like between its truncate and its write — is given up to two more debounces to finish before it is reported, so a slow save puts no spurious refusal on the log or the dashboard; a file that stays cut off is still refused, and a malformed one that is not cut off is refused at once.

Runtime overrides (not the config)

Per-role caps can be nudged at runtime from the dashboard's Balance panel or the loopback POST /balance endpoint. Those writes go FIRST to this machine's settings on switchyard (PRD #627, a round trip) and then to a balance.json marker in the project's state dir, and never the config file, so they survive a config reload and are cleared independently. A host with no credential, no install id or an unreachable switchyard answers 503 and writes nothing. A lever can only lower a lane to its configured cap; raising a ceiling is a config edit. See internal-balance.

What the page shows and moves (PRD #493). Each project row carries a Role caps section: one row per capped lane — every max_* cap the config carries, plus steward and swarm, whose caps are fixed at 1 in code — with the configured max beside any override in force and the effective cap the spawn gates actually read. GET /health carries the same per project as role_caps ([{role, configured, override, effective, auto}], always a list; override is absent when the balance names no number for that lane) and the override itself as balance ({set, summary, damaged, holds, auto}, plus since, reason and by when one is set). Each lane has a lever: a numeric control whose ceiling is the configured cap, POSTing {"project": …, "roles": {"<role>": n}, "merge": true} to /balance so moving one lane leaves the others as they stand. The panel's one-click shortcuts stay beside the levers — hold new work, favour review & rework, clear — each sending the whole shape (or clearing the marker) rather than merging one lane. The handler refuses any count above the configured cap with a 400, so no page write can raise a role above its ceiling; a lane the config does not cap is disabled on the page and named as a config edit.

Who set it. Every override records an owner: an operator (a lever, a preset, POST /balance, a hand-written marker) or the auto-balancer (auto_balance above). The row and /health badge the two apart (balance.auto, and auto per lane) and carry the reason for an auto move, e.g. favouring review & rework: 6 PR(s) open at the cap of 6 with 4 unreviewed and 1 in rework — holding new builds until they drain. Auto-balance clears only an override it set itself; an operator's stands until a person clears it — from the page or with conductor balance <project> -clear; removing balance.json does not, since the settings row on switchyard is the tuning of record.