Configuration

Worker launch defaults, presets, and the capacity schema. .sum/settings.json is the one owner of executable admission values, worker launch defaults, named presets, and the evidence publication switch.

Worker harness and model

--harness is optional. The precedence is fixed: an explicit instruction (--harness, --model, --reasoning, or --same-as-you), then the saved worker default in .sum/settings.json, then the reliably known root harness, then the disclosed native default.

./bin/sumctl settings set --worker-harness codex --worker-model gpt-5-codex --worker-reasoning high
./bin/sumctl settings set --worker-harness claude        # switching harness drops the old harness's model
./bin/sumctl settings set --clear-worker                 # back to the coordinator's harness
./bin/sumctl dispatch --repo R --brief B --approved --model o4-mini      # this task only
./bin/sumctl dispatch --repo R --brief B --approved --same-as-you        # coordinator's harness and native model

A model or reasoning value is translated only through a flag verified from the installed CLI's own help. A harness without a verified flag refuses --model/--reasoning instead of guessing; pass the native argument yourself with --arg. Saving a default affects future dispatches only.

Named launch presets

A preset is a named, validated harness/model/argv shortcut in the same .sum/settings.json, so you can say "use deep for this task" instead of repeating launch arguments. It is not an agent, a role, a credential store, or a default until you save it as one.

./bin/sumctl preset set deep --harness codex --model gpt-5-codex --reasoning high --arg=--search
./bin/sumctl preset list
./bin/sumctl preset show deep
./bin/sumctl dispatch --repo R --brief B --approved --preset deep
./bin/sumctl settings set --worker-preset deep
./bin/sumctl settings set --reviewer-preset review
./bin/sumctl preset delete deep                  # refused while a default still references it

Capacity

Admission is unlimited until a capacity block is configured. An execution slot belongs to a recorded worker attempt or an independent verification run, not to the unfinished task itself. A refused admission launches nothing. Nothing schedules or dispatches work because a slot is free; a dispatch is always an explicit approved instruction. An enrolled project can declare its own limit under capacity.projects; admission resolves the project override when one exists, otherwiseper_repository, and always enforces globalfirst, at preparation, resume, and independent verification alike. A project's held count includes tasks at its enrolled clone path and its linked worktrees, so a path alias never gets its own writer; an unenrolled --repo path keeps its own path scope and theper_repository default.

./bin/sumctl settings show
./bin/sumctl settings set --global 12 --per-repository 1
./bin/sumctl settings set --project-limit docs=3 --project-limit app=1
./bin/sumctl settings set --clear-project-limit docs
./bin/sumctl settings set --clear-capacity
./bin/sumctl execution show TASK_ID
./bin/sumctl execution park TASK_ID --attempt ATTEMPT_ID     # inspect stopped execution; preserve unfinished work
./bin/sumctl execution resume TASK_ID --attempt ATTEMPT_ID   # reacquire capacity and launch approved work

The settings file shape:

{
  "schema": 1,
  "capacity": {"global": N, "per_repository": M, "projects": {"NAME": K}},  # 1–64; per_repository and each project ≤ global
  "worker": {"harness": "codex", "model": "...", "reasoning": "..."} | {"preset": "deep"},
  "presets": {"deep": {"harness": "codex", "model": "...", "reasoning": "...", "args": [...], "revision": 1}},
  "reviewer": {"preset": "review"},
  "evidence": {"auto_publish": false},
  "usage": {"enabled": true}  # opt-in per-task Claude Code usage ledger; absent means off
}

An invalid file is refused with the exact defect before any side effect. Lowering a limit affects future admission only. Raising global never raises per_repository: one checkout gets one writer unless you say otherwise. With a capacity block, settings show andstatus list the effective limit, its source, enrollment, and held attempts per declared override and occupied scope. The settings file travels with sumctl backup.

usage.enabled turns on per-task usage accounting, off by default. While it is off nothing reads a Claude Code transcript and no usage record exists. While it is on, usage collect TASK_ID,report, and cleanup fold the transcripts of the panes sum bound to the task (the conversation id Herdr reports for the worker and the reviewer) into the task's privateusage.json: one invocation and one token set per distinctmessage.id, resumed from a recorded byte offset so repeated collection never double counts, with a token field the source never reported kept null. usage show TASK_ID prints totals by category (implementation, review, repair, unknown) and a coverage label: complete, partial with reasons, or unavailable. Collection failures are warnings and never change delivery, reservation release, or cleanup. The ledger travels withsumctl backup; an older sumctl refuses a settings file carrying the usage key, so remove it before a rollback. Totals are counts, not a bill.