Module config 

Run configuration: the agent roster, the shape of the graph, and the blindness / verification policy.

Layers, lowest precedence first: <config_dir>/magi/config.toml (machine), .magi/config.toml, magi.toml. With none, built-in defaults apply, the agent roster derived from the agent CLIs actually installed on this machine. --config <path> replaces the whole stack with that one file.

The repository layers are read from <remote>/<base>, never from the working tree. A primary checkout is often stale or on a detached HEAD, so a gate read from it can be older than the one the branch under review is cut from (run ce6e failed on a gate step origin/main had already dropped). git show <sha>:magi.toml of the remote-tracking ref’s commit is written to a content-addressed directory under the git common dir (<common>/magi/config/<sha>-<hash of repo>/, temp dir when that is not writable) and loaded from there. Reviewed branches may additionally enable literal owner-hold switches; these never weaken base policy or load other branch settings, includes or templates.

remote and base are themselves in the file, so they are resolved in a fixed order, first hit wins:

1. [merge] base / remote of the machine layer, rendered as a real load would (env templates, includes);
2. the same keys, read minimally (only [merge], nothing deserialized into Config) from the checkout’s magi.toml, then .magi/config.toml - only to locate the ref; an unreadable file is ignored;
3. remote defaults to origin, base to what refs/remotes/<remote>/HEAD points at.

Config::discover is synchronous and reads the remote-tracking ref as it is (daemon::fetch_loop keeps it fresh); Config::discover_fetched runs git fetch first and is what every path that starts work uses. A failed fetch, a missing ref or an unresolvable base is an error, never a silent fall back to the working tree or a local branch. Two cases are not that: an explicit --config, and a repo that is not a git working tree at all (no branch exists, so nothing can be stale).

A repository layer that declares include = [...] gets the whole tree of that commit extracted, so relative includes resolve against the same commit. The directory is built beside its name and renamed in, so a concurrent discover never reads a half-written layer.

Structs

AgentSpec

One addressable agent in the roster.

Blind

Blindness policy.

Config

Top-level configuration.

Coordination

Optional contract with an external repository updater.

Daemon

How the daemon loop itself behaves, as opposed to what one run does.

Disk

Disk hygiene: how hard magi is allowed to press on the machine’s free space.

Graph

Graph shape and limits.

Merge

Merge policy.

Notify

How the operator is told that a run is waiting on them.

PersonaSpec

One [[talk.personas]] entry: a tone for the standing chat, nothing more.

Prompts

Project-specific text appended to each node’s prompt.

Release

[release]: releasing without GitHub Actions. Opt-in per repository.

Repos

Where magi repos and GET /api/repos look for local checkouts.

ResolvedRoles

Roles resolved to concrete agent specs for one run.

Roles

Explicit role assignment. Empty lists are filled in by Config::resolve_roles by rotating the roster.

SetupStep

One setup step: exactly one of copy / run.

Talk

Policy for crate::talk, the standing conversation.

Update

Self-update policy.

Verify

Shell commands that gate the winner.

VersionFile

One entry of Release::version_files.

Worktree

Per-repository worktree preparation, run right after magi creates a worktree.

Enums

AgentChoice

A standalone seat’s agent: one roster id, or an ordered fallback chain.

AgentKind

Which CLI drives an agent.

Delivery

How the prompt reaches the agent process.

IncompleteReviewPolicy

What a review round does when a reviewer seat never answered.

LeakPolicy

What to do when vendor-identifying text is found in material shown to judges.

MergeCi

Whether pull request landing requires readable CI results.

MergeMode

What to do with the winning branch.

MergeStyle

How the winning branch is attached to the base branch: what mode = "local" runs, and what mode = "none"’s printed guidance tells the operator to run by hand.

OwnerHold

Approval switches whose reviewed-branch values can only add owner holds. Keep the allowlist and base-value lookup together when adding a switch.

ReleaseMode

Who performs the release after a chore/release-vX.Y.Z pull request merges.

UpdateMode

How magi keeps itself current.

VersionKind

How a VersionFile is read and rewritten.

Constants

OPERATOR_NAME_MAX

Longest accepted [talk] operator_name, in characters.

Functions

branch_owner_holds

Literal true values only: no defaults, includes, rendering or other config. Both repository files contribute monotonically, independent of precedence.

find_program

The file a bare program name resolves to on PATH, the way the OS shell would find it.

find_program_on

find_program against an explicit PATH, for a child whose environment overrides it.

primary

The first id of an optional choice: what a single-seat caller resolves.

which

Is program on PATH?