Configuration

Detent separates machine settings, instance settings and project workflows:

• global.yaml contains machine settings only for an enrolled runner, which reads ~/.config/detent-runner/global.yaml.
• Cloud stores project membership, allowed projects, project rank and organization/project model selection in its database.
• Each project has a checked-in detent.yaml machine contract, with optional machine-local overrides in detent.local.yaml. The project contract can also live in legacy WORKFLOW.md YAML frontmatter.

An enrolled runner reads its current allowed projects from Cloud, clones linked repositories under workspace_root (default ~/detent-runner), and loads their committed default-branch detent.yaml, WORKFLOW.md and AGENTS.md. It uses the host's Git authentication. One project's missing repository binding or failed clone is an instance setup failure; it does not stop valid projects or revoke its Cloud grant. An empty allowed-project list runs nothing.

The runner file may set the Hub URL, identity file, organization, display name, capacity, heartbeat and lease timing, provider-capacity file, CPU/memory/IO pressure limits, startup pacing, port, log level, cache and workspace root:

apiVersion: detent/v1
kind: GlobalConfig
service_name: detent.runner
workspace_root: /absolute/path/to/detent-runner
client:
  hub_url: https://cloud.detent.build/organizations/org_example
  identity_file: /absolute/private/runner/identity.json
  organization_id: org_example
  display_name: Build host
  capacity: 4
  heartbeat_interval_seconds: 30
  lease_ttl_seconds: 90
global:
  max_concurrent_agents: 4

Enrolled runners reject unknown keys at startup, including nested machine-setting keys. Errors name each unsupported key path. Removed keys include projects, weight, priority, scheduling, fair_share, global.agents.model_selection, client.native_projects and other local project policy defaults, even when their values are malformed. Remove these keys before upgrading; the one-release warning-and-ignore transition has ended. Before releasing this transition, the release owner must confirm the compatibility release shipped, verify that no live runner file still contains removed keys, and authorize the subsequent release. An unchanged legacy file will fail startup and may leave its service restarting. Cloud supplies project membership, rank and model selection; runners have no file-defined project or model-selection fallback. Local instances store these settings in SQLite.

Existing checkouts under workspace_root are matched by Git origin to Cloud-allowed repositories. They do not supply workflow paths or policy. Matching checkouts retain their project aliases and directories. With no repository workspace root, Git's registered Detent issue worktrees preserve a distinct retained worktree root, branch and dirty source. Explicit repository workspace roots remain authoritative. Multiple matching checkouts or retained roots require the operator to select the retained source; existing files remain untouched.

This page is the reference for machine and project configuration. Each project's workflow continues to come from its repository.

agent.no_progress_timeout_ms remains readable for older project files but is ignored. Worker sessions use their absolute duration bound, and local validation waits use the gate lock deadline.

Priority settings order ready work (INV-10). Stored project rank and dispatch_priority_by_state, dispatch_priority_by_label, and prioritize_unblockers choose the next eligible request. They never reserve idle slots or cancel running workers. max_concurrent_agents and max_concurrent_agents_by_state remain independent capacity ceilings.

Host Go caches

Workers inherit Go's host cache paths and operator environment settings. They retain per-attempt temporary directories. Startup removes legacy project caches under each configured workspace root; doctor and status report host cache paths and sizes.

global:
  cache:
    max_age: 48h
    # max_bytes: 53687091200 # optional explicit 50 GiB size target

When omitted, max_bytes is 10% of the total capacity of the volume holding GOCACHE, capped at 40 GiB (20 GiB fallback if capacity is unavailable). It is a retained-size budget for the managed runner cache, not a hard filesystem limit or a claim brake. Native Cloud runners admit new work while each cache and workspace volume has enough free space for its reserve: 10% of total volume capacity, capped at 40 GiB. Insufficient free space or an unavailable storage observation reports zero capacity for new work. Existing jobs keep their leases and recent cache files. Free space does not change the cache target. Doctor reports the fallback, last size eviction, and a target above 10% of total volume capacity.

The existing workspace reaper expires build-cache entries older than max_age. The effective age is at least 25 hours, preserving Go's last-day cache reuse and its one-hour access-time granularity for native operator caches. When the runner-owned cache exceeds max_bytes, that same cleanup waits under the existing admission lock for protected consumers to finish, then reclaims eligible entries oldest first under the exclusive consumer lock. New consumers resume after cleanup. Metadata (trim.txt, README, and ownership locks) is never removed. The module cache is reported and shared but is not trimmed. Concurrent builds can grow the managed cache between sweeps and exceed the budget while active. Unrelated host processes and native operator caches are not controlled by managed cache reclamation.

GitHub completion CI policy

Omitting gate.required_status_checks retains aggregate CI evaluation. Explicit gate.required_status_checks: [] uses the PR base branch's native required checks. If the branch requires none, absent or pending optional CI does not block promotion or merging. Reported failed CI always blocks. Native missing, pending, and failed checks still block. A nonempty list retains the existing configured-check behavior.

Issue session allowance

Code and rework share a fixed allowance of three sessions without a merged PR. The next code dispatch runs one read-only triage pass, publishes its explanation, and leaves the issue in Human Review. An operator move out of Human Review renews the allowance, as does a merged PR. Detent-instance moves, new PR heads, changed CI signatures, ordinary lane moves, and acknowledgements alone do not renew it; instance-attributed failures do not consume it. Completed, successful PR deliveries without a recorded error also do not consume it; waiting on the completion gate is not a failed delivery. The existing triage comment records the operator reset timestamp when comment updates are supported.

The former agent.auto_promote.rework_limit and agent.auto_promote.no_progress_limit keys are retired and have no effect. Remove them from existing configuration. There is no replacement tuning key. See INV-3 for the consolidation and historical-reader compatibility contract.

Session limits by complexity level

Model selection is configured in Cloud organization settings. Projects inherit that default and may override it in their Cloud project settings. Runners receive the effective selection from the Hub. global.agents.model_selection and agents.model_selection in detent.yaml or legacy workflow frontmatter are ignored with a compatibility warning for one release; the next release rejects them. Remove those keys from runner and repository files.

Cloud complexity levels may include max_session_duration_ms and max_session_tokens alongside model and effort. The selected level (stage override, matching rule, then default) supplies these limits once at session start. An omitted limit inherits agent's flat value; explicit 0 disables that limit. Values must be non-negative. Selection disabled or an ineligible backend uses the flat values. Per-issue detent-agent model and effort blocks retain their existing behavior, including clamping effort to the stage's ceiling.

The running session keeps its resolved values across turns, checkpoints, and fallbacks. Later label or configuration changes do not change its limits or reset attempt counts or lifetime usage. Turn inactivity, no-progress limits, context multipliers, and token exemption settings retain their existing behavior. detent doctor reports each level's effective limits for the project, plus the flat limits used by ineligible backends.

An issue without a detent-agent effort uses the default level (subject to existing stage and role rules).

Terminal attempt recovery

Set recovery.terminal_attempt_retry_limit in detent.yaml or detent.local.yaml to control recovery from consecutive terminal attempts without a pushed work product or linked pull request:

recovery:
  terminal_attempt_retry_limit: 0

The default is 3. The value preserves the existing consecutive-failure threshold for values of 2 or greater; 1 explicitly permits one recovery attempt, and 0 disables automatic recovery for a qualifying failure.

Thus 1 and 2 both park on the second qualifying failure. Higher values park on that numbered failure. Negative values are rejected. This compatibility rule keeps the existing default at two redispatches before parking.

The zero policy persists an operator-owned hold, including the latest failure evidence. It also enforces the hold from the current completion when saving the attempt fails or no durable attempt record is available. Restarting Detent or waiting for the breaker cooldown does not release that hold. If the tracker rejects the Blocked transition, Detent holds the issue locally and retries that transition during reconciliation without starting a worker. Changing the setting alone does not authorize release of an existing operator-owned hold. Retry counts are reconstructed from durable issue attempt history after restart; successful attempts and pushed work reset the sequence. Service-restart recovery remains resumable and does not consume this limit.

Durable provider capacity, GitHub REST capacity, and forge availability waits retain their existing handling and do not consume generic terminal retries. Transient overload failures remain qualifying terminal failures. Workspace preparation retains its separate fixed threshold of three failures. This policy is independent of automatic promotion, validators, and Rework limits.

detent doctor reports the effective setting, the qualifying failure on which Detent parks, and whether parking requires external review or uses cooldown recovery. Local overlays preserve an explicit zero.

Repository policy with Hub execution

The customer host resolves the project files and an administrator explicitly approves the resulting descriptor. For native projects, that approved revision stores the shared behavior and instructions consumed by every authorized runner. Credentials, host paths, capacity, isolation hooks and backend routing stay local. Repository compatibility projects retain their file-based approval semantics. Use detent hub policy inspect --config /path/global.yaml --project orders to review the resolved descriptor. Authenticated native inspection reads the approved shared configuration; offline inspection resolves the local proposal.

Configuration precedence and authorization are applied in this order:

Use an administrator-selected workflow_ref to read shared files from a trusted Git commit. The loader resolves the ref once and reads shared files at that commit; edits to the working branch do not change it. Shared behavior changes in local overlays still need approval. An external definition is authorized by reviewing its resolved content digest through the same approval command. Approvals must be performed outside the implementation worker; do not give workers the Hub administrator credential.

hub policy inspect prints schema 1, the source revision, source/configuration digests, a content-derived policy_id, selected runner requirements and gate metadata. Native descriptors also contain shared configuration, workflow prose, commands and admission guidance. Their digests identify portable behavior rather than host-specific source bytes or Git revisions. Host paths, credentials and transport settings are excluded. Compatibility descriptors contain only digests and bounded metadata; their underlying content stays on customer infrastructure.

After reviewing the files and descriptor, an administrator runs:

detent hub policy approve --config /path/global.yaml --project orders

The command reads DETENT_HUB_ADMIN_TOKEN (or --admin-token-env), resolves the selected local definition and uploads its descriptor. Replacement requires --expected-policy-id policy_... to prevent a stale approval from overwriting another administrator's decision. For repository-controlled native workflows, an enrolled runner automatically applies definitions committed on the bound repository's default-branch history through the same Hub approval transaction. It verifies the configured origin, committed contents and Git ancestry before reporting provenance. Feature-branch commits and uncommitted edits still require explicit administrator approval. Other native shared behavior or instruction changes require one reviewed approval for the project. Planning, validation and automatic promotion can be enabled together; the existing workflow refresh applies the approved combination to idle runners without copying files. Host configuration changes do not produce competing native approvals. Existing native approvals without shared configuration adopt this model through the same replacement approval path. Compatibility projects still require new approval for effective file, permitted local adjustment, environment or trusted source revision changes on each host.

Active leases retain their policy, and Hub refuses a replacement while they remain active. Finish or cancel those attempts, approve the new descriptor, and let native runners refresh the shared revision. Compatibility processes still require restart or the existing managed configuration application to adopt a different approved identity. Invalid or unapproved reloads retain the last-known-good configuration and report an actionable error. Resumed provider sessions must match the policy stored with their original attempt, including after Hub is disabled; missing or mismatched recovery identities are rejected. Automatic thread reuse falls back to a fresh attempt under the current policy. Standalone sessions that never had a Hub policy retain legacy recovery.

Administrators can revoke the current approval through the policy API. This immediately denies claims, lease renewal and new run events. Worker heartbeat checks observe the revocation and stop work through existing lease-loss handling; release remains available. Historical revisions and lease pins are retained.

Plan-review stops, gate kinds, human approval, automatic-promotion opt-outs, CI/check requirements, validators, security audits and merge methods remain project-specific. Two repositories sharing a runner retain separate approvals and gates. Hub approval is not a human plan/PR approval. GitHub's repository automatic-merge setting remains owned by that repository; onboarding inspection reports it without changing it. Host restrictions and revoked authority win over an approved policy or a Hub allowance. Hub has no browser setting that silently relaxes repository policy.

Effective policy appears in project settings, work-attempt receipts, health workflow provenance and detent doctor output. Policy mismatches leave work waiting without creating an execution attempt or consuming execution retries.

Named runner requirements

Declare profiles in the existing shared or legacy configuration and select one with runners.profile:

runners:
  profile: build
  profiles:
    build:
      required_tags: [linux, go]
      machine_id: machine_0123456789abcdef
      runner_id: runner_0123456789abcdef

Profiles and tags use ASCII letters/digits with -, _ and ., up to 64 characters. Tags are trimmed, lowercased, sorted and deduplicated; profile names must already be lowercase. At most 32 profiles and 32 tags per profile are accepted. Selectors are optional stable IDs with machine_ or runner_ prefixes; display names are not selectors. Every required tag and every explicit selector must match. Unknown selectors never widen to another host. An empty profile selection has no extra routing requirements. Explicit empty lists and selector strings in local overlays retain their existing clearing semantics and require approval as part of the effective definition.

Profiles declare requirements, never enrollment or capabilities. Machine registration still happens on an authorized physical host. The Hub checks machine pins and matches runner IDs only against authenticated enrolled runner identities. Legacy worker tokens cannot assert an enrolled runner ID. Required tags return selector_no_match until the authorized tag-placement deliverable #2185 is available. Self-reported machine capabilities never satisfy privileged tags. See runner enrollment for the separate host authorization path.

Host configuration

At startup, Detent resolves global.yaml in this order. The first matching rule wins.

os.UserConfigDir() maps to %AppData%\detent\global.yaml on Windows, ~/Library/Application Support/detent/global.yaml on macOS, and ~/.config/detent/global.yaml on Linux while honoring XDG_CONFIG_HOME.

DETENT_CONFIG and DETENT_HOME remain deprecated fallbacks for one release. Detent uses CONFIG_HOME instead of HOME because HOME is standard process state, not Detent configuration.

Use detent config path to print the resolved config path and the rule that selected it.

Runtime settings resolve in this order: explicit flag, environment variable, global.yaml, then built-in default.

Automatic apply waits for an idle runtime until update.max_deferral_hours elapses, then pauses new dispatches and lets in-flight attempts finish within their configured session ceilings before applying and restarting. Add [detent-critical] to a GitHub release body to bypass the idle wait and start that drain immediately.

detent cloud serve and detent hub serve read no global.yaml; they resolve the log level from --log-level, then LOG_LEVEL, then DETENT_LOG_LEVEL, default to info, reject any value other than debug, info, warn or error, and write JSON logs to stderr for journald.

The web host resolves from --host, then the first registered workflow's server.host, then the built-in 127.0.0.1 default. It is not a top-level global.yaml key.

Host pressure admission

On Linux, Detent refreshes Pressure Stall Information (PSI) at admission time, subject to each signal's configured poll interval. Pressure above any configured threshold holds new dispatches; it does not cancel or reap agents that are already running.

global:
  memory:
    max_agent_rss_bytes: 8589934592
    pressure_some_avg60_threshold: 10
    poll_interval_ms: 1000
  io:
    pressure_full_avg10_threshold: 5
    degraded_max_concurrent_agents: 0
    poll_interval_ms: 1000
  cpu:
    pressure_some_avg10_threshold: 80
    degraded_max_concurrent_agents: 0
    poll_interval_ms: 1000
    go_build_budget: 0

go_build_budget is the host-wide number of Go compile, link, asm, cgo, and vet processes that all worker attempts may run at once. The default of 0 uses the host's CPU count. For workers whose workspace root has a go.mod, Detent sets GOFLAGS=-toolexec=<detent go budget wrapper>, so every go build, go test, go vet, and go install a worker runs, including commands the agent types itself, waits for a free slot before each tool process starts. The same environment sets -p and GOMAXPROCS to a quarter of the budget (at least 1) so each go command's package parallelism and test binaries stay within the host's share. Flags the host environment already sets in GOFLAGS are kept, and an explicit -p or -toolexec wins. The budget only queues tool processes; it never fails, parks, or cancels work, and it runs unqueued if its slot directory cannot be prepared. Workspaces without a go.mod keep their environment unchanged. The shared GOCACHE is unchanged and build and test cache hits are preserved. Changing this value requires a restart.

degraded_max_concurrent_agents is an opt-in host-wide progress floor for IO and CPU pressure. Its default of 0 preserves the conservative hard stop. Set it to 1 to allow one worker across all named pools while that signal remains constrained. If IO and CPU pressure are active together, the lower configured floor wins. The pressure ceiling only blocks new admissions; it never preempts running workers, and pool, project/state, worker-host, startup pacing, and backend limits can reduce capacity further.

A guard engages only above its configured threshold. Once engaged, IO and CPU guards stay constrained until the measured average falls to 80% of the trigger threshold, which prevents dispatch from flapping when PSI hovers around the boundary. For example, an IO threshold of 5 engages above 5 and recovers at or below 4.

The defaults shown above are starting points, not universal safe values. With the default degraded capacity of 0, the sample IO threshold of 5 is a fleet-wide hard stop whenever IO full avg10 stays above 5%, including when an unrelated host process creates the pressure. IO full is the strongest build host signal because it measures time when every non-idle task is stalled on IO. CPU uses some, because system-level CPU full is defined to report zero. Memory some remains useful for reclaim and swap pressure, but a compile-heavy host can be IO- or CPU-saturated while memory PSI stays at zero. See the Linux PSI interface for the kernel definitions.

Treat configured pool capacity as the hard ceiling and use PSI as the dynamic admission brake. Before enabling a low threshold, observe /proc/pressure/io and /proc/pressure/cpu during representative Detent and unrelated compile, test, browser, database, and media workloads. Calibrate the trigger above the host's acceptable sustained baseline, then lower it if the interactive host becomes unresponsive before the guard engages. Raising the hard ceiling based only on free memory can overload a build host.

The ten-second IO and CPU windows respond faster than the sixty-second memory window. Keep global.startup.jitter_seconds and max_spawn_per_second conservative enough for those averages to react during service startup; PSI then constrains and restores admission as contention changes. On systems without PSI, or when a pressure file cannot be read, Detent fails open and reports the unsupported or unavailable signal rather than inventing a zero reading.

detent state, /api/v1/state, and /health expose the current values, thresholds, read errors, configured degraded capacity, effective pressure capacity, constraint start time and duration, and whether each signal is holding dispatch under memory_pressure, io_pressure, and cpu_pressure. Durable scheduler decisions include pressure capacity, usage, availability, reason, and duration. Work-attempt capacity snapshots include the active pressure capacity, reason, and duration.

When Detent starts inside tmux, it renames the current window to a compact running, ready, waiting, and blocked count summary. It restores the original name on clean shutdown. Set ops.tmux_window_status: false to disable this behavior; Detent never invokes tmux when $TMUX is absent.

Use github_token: gh in global.yaml to resolve the token from gh auth token at startup. Literal token values also work but should not be committed. github_token: gh-auth, ${gh auth token}, and $(gh auth token) are accepted aliases. If neither GITHUB_TOKEN nor github_token is set, Detent falls back to existing per-workflow tracker.api_key handling.

Set trust_loopback_peer_read: true to grant tokenless read-scope API access to direct loopback TCP peers even when Detent binds a non-loopback address or has an api_token. The setting hot-reloads and applies only to GET routes; admin routes and mutations still require credentials. Authentication uses only the request's direct peer address and never trusts forwarded-client headers. Do not enable this setting when a reverse proxy runs on the same host: every request relayed by that proxy has a loopback direct peer, including requests that originally came from remote clients.

Use instance_name to distinguish browser tabs and the dashboard navbar when several Detent instances are open at once. Detent resolves the display name from the first non-empty value in this order: top-level instance_name in global.yaml, global.identity.name, the short hostname, then empty. Names are trimmed, must be a single line, and are capped at 40 characters in the web UI.

service_name names the background service: the launchd job com.digitaldrywood.NAME and the systemd user unit NAME.service. It defaults to detent; detent hub runner register writes service_name: detent.runner. Give each configuration on one host its own name. Names use lowercase letters, digits, dots and hyphens.

A project listed under client.native_projects whose committed detent.yaml uses the GitHub tracker (github or github_local) uses the Hub instead (tracker.kind: hub_native), so a runner host can use a repository checkout as it is. Any other tracker kind is treated as a deliberate local choice and kept.

Configure client.hub_url to move candidate discovery and claiming to a Detent Hub. The machine registers its identity, project and pool capabilities, capacity, operating system, architecture, and binary version. It then heartbeats while polling the Hub and renewing fenced work leases. The token is read from the environment variable named by client.token_env in legacy mode; the token is never stored in the configuration file. For scoped native runners, use client.identity_file instead: an absolute path to the private host-generated identity created by detent hub runner init and enrolled with detent hub runner enroll. The client renews this credential automatically. Its organization, machine ID and explicit native projects must match enrollment. See runner onboarding and migration.

Enrolled native runners can opt into provider-aware dispatch with client.provider_capacity_file, an absolute path to a bounded JSON report file. The runner reads it on heartbeats and again before starting provider work. See provider capacity reports for its safe schema, shared-account declarations and reservation semantics. This setting does not change backend credentials, model routes, effort defaults or fallback policy.

client:
  hub_url: https://hub.example.com
  token_env: DETENT_HUB_TOKEN
  machine_id: build-mac-01
  display_name: Build Mac 01
  capacity: 4
  heartbeat_interval_seconds: 30
  lease_ttl_seconds: 90
  request_timeout_ms: 10000

In legacy mode, machine_id defaults to the configured global identity, instance name, or hostname. Enrolled mode uses the immutable host-generated machine ID. capacity defaults to global.max_concurrent_agents. The heartbeat interval must be shorter than the lease TTL. Hub outages mark project refresh health degraded and back off with the normal scheduling loop; they do not consume issue retry, no-progress, or work-failure budgets. GitHub remains in use for event ingestion, reconciliation, write-back, and fresh safety checks, but the scheduling claim cycle does not depend on a GitHub read.

Native issue projects use tracker.kind: hub_native in their repository workflow configuration. Enrolled runners obtain the stable project IDs and organization through their identity and current Cloud grants. No local client.native_projects mapping is needed. Native issue creation, full-body refresh, discussion, history and scheduling use the Hub v2 API. There is no fallback scheduler. The Hub API documents project provisioning, workflow states and typed operations.

A native project reuses the repository WORKFLOW.md as its prompt. Detent appends a native completion contract to every native run prompt that overrides tracker-specific steps in that file: the agent commits on the attempt branch, never pushes or opens pull requests on the forge, never runs gh or calls the GitHub API, and does not post Workpad or issue comments or change issue state. The runner records the Change Request from those commits. Native projects make no GitHub REST or GraphQL calls by default: workers do not receive the instance GitHub credential, and checkpoints do not look up or open pull requests. No separate key turns this on; an explicit worker.github_token is the only opt-in for worker GitHub access. The contract is added at render time, so it does not change the approved policy digest. detent doctor (check Project <id> native workflow instructions) and detent hub policy inspect warn when a native project's WORKFLOW.md still mentions GitHub-only steps such as Codex Workpad, a gh command, pull request, detent-status or the GitHub API.

Health notifications deliver fleet and project needs-attention transitions to one generic webhook. They are disabled when notifications.health.webhook.url is absent, preserving the silent default. Configure the host-wide channel in global.yaml:

notifications:
  health:
    debounce_seconds: 300
    webhook:
      url: https://alerts.example.com/detent
      headers:
        Authorization: Bearer replace-me
      timeout_ms: 5000

The five-minute default debounce applies independently to entry and recovery. Project identities are stable per project and cause, currently ci_unavailable and dispatch_stall; a separate fleet identity represents the aggregate transition while any project cause remains active. A flap that clears before the debounce expires emits neither entry nor recovery. Once an entry is emitted, exactly one recovery is emitted after the identity remains healthy for the debounce window.

Webhook payloads use event name detent.health.transition and include a stable event ID, host and instance names, scope, optional project ID, entered state, causes, optional wait reasons, and entry timestamps. Delivery state and pending events are stored in the runtime SQLite database before sending, so a restart does not re-fire active conditions or discard unsent transitions. Failed sends retry at most five times with exponential backoff starting at 30 seconds and capped at 15 minutes. Every failure is logged and appears in health_notification_failures on /health; detent doctor reports both retrying and exhausted deliveries. Notification configuration changes require a restart. Treat configured headers as secrets and keep host-specific values out of checked-in project configuration.

Automatic update checks and apply are enabled by default when client.hub_url is configured. These runners check the Hub's running version through its authenticated native capabilities response at the configured heartbeat interval, unless update.check_interval_hours is set. They fetch that exact published release rather than GitHub latest. A runner ahead of the Hub stays on its installed version; an unreachable Hub, missing version or unpublished target does not trigger a fallback update. Explicit auto_check_enabled: false or auto_apply_enabled: false settings opt out and survive configuration writes.

Detent reports the last check, available or applied version, and next check on /health. detent doctor surfaces the last and next check times and reports whether the host is opted in. Automatic apply only replaces release-installer binaries; other install sources remain notification-only. A successful apply uses the normal graceful drain path, then re-executes the replaced binary on POSIX systems or exits cleanly for an external supervisor to restart it on other platforms.

detent doctor prints the resolved runtime values and their sources, with the GitHub token redacted.

Choose a starting point

The root detent.yaml and WORKFLOW.md configure the Detent project itself. They are not templates for other projects. Use the documentation samples below when configuring another repository.

• docs/templates contains paired detent.*.yaml and WORKFLOW.*.md presets for supported tracker and deliverable setups.
• config.example.yaml is the smallest working project config.
• config.annotated.yaml is a realistic GitHub setup with explanations beside each deliberate choice.
• config.reference.yaml contains every supported project key. It is fully commented so you can copy only what you need.

Keep detent.yaml portable and checked in. Put machine-specific paths or secrets in detent.local.yaml, a credential reference, or host configuration. The local file overlays the shared file recursively and is not a second, independent configuration.

How the subsystems fit together

Identity, tracker, and polling

identity names the Detent persona that owns work. tracker connects that persona to its work source; native projects use tracker.kind: hub_native, which keeps issues in the Hub. The tracker declares workflow states in one ordered tracker.lanes list; state maps, transition automation, admission, planning, stop behavior, and routing all refer back to those names. polling controls how often Detent refreshes the tracker when no event gives it a fresher signal. Its refresh_failure_threshold controls how many consecutive failures after a successful refresh promote project and fleet health to needs_attention; a project whose first refresh fails needs attention immediately.

Each lane has a name and a role: active means dispatchable, holding means non-dispatchable and non-terminal, and terminal means finished. File order is the order on Cloud boards and lists, lane pickers, and approved repository workflow policies.

tracker:
  lanes:
    - {name: Backlog, role: holding}
    - {name: Todo, role: active}
    - {name: In Progress, role: active}
    - {name: Rework, role: active}
    - {name: Merging, role: active}
    - {name: Blocked, role: holding}
    - {name: Human Review, role: holding}
    - {name: Done, role: terminal}
    - {name: Cancelled, role: terminal}

tracker.observed_states, tracker.active_states, and tracker.terminal_states are rejected in detent.yaml, legacy WORKFLOW.md frontmatter, and Cloud Workflow settings, including empty and null values. Use tracker.lanes for all new and updated workflow configuration. Run detent config migrate detent.yaml (or detent config migrate WORKFLOW.md for legacy frontmatter) to rewrite the file in place. The command preserves lane semantics, comments outside the replaced lists, and the Markdown prompt; running it again leaves the file unchanged. An explicit local lanes list replaces the shared lane list in full. Cloud-authored Markdown is migrated automatically by the Hub, preserving each project's stored lane order and approval provenance. Historical policies and approvals remain readable.

dependency_auto_unblock, blocked_recovery, and blocker_auto_promote are opt-in tracker automations: the first advances work whose dependencies cleared, the second revives agent-recoverable PR maintenance, and the third promotes blockers when they enter configured states.

GitHub and Linear trackers also receive a default Statuspage base URL through tracker.status_page_url; set that key to override the provider endpoint. Detent follows redirects and polls the unauthenticated Statuspage summary and unresolved-incident feeds at a low-frequency baseline, increasing freshness only while a Detent-observed tracker_unavailable condition is active. These feeds decorate health output only: malformed, slow, or unreachable status pages never create a condition or influence dispatch and recovery. Statuspage incident webhooks are a possible future optimization, not part of the current polling integration.

The tracker setting github_rest_min_remaining_reserve is an absolute reserve for the REST core resource (default 1000). It does not reserve requests in smaller resources such as search; those resources still enforce GitHub's primary and secondary rate limits and shared backoff. Recovery probes, reserve diagnostics, and scheduler lookup gates use the same resource rule. The aggregate REST quota snapshot retains core capacity; resource-specific budgets continue to report search usage separately. Responses without a resource name retain the core reserve for compatibility. No configuration migration or new setting is required; the worker's separate core-budget policy is unchanged.

Workspace, deliverable, and worker placement

workspace controls isolation, source and output roots, branch creation, cache sharing, and cleanup. deliverable selects pull requests or file artifacts and their review destination. worker distributes sessions across optional SSH hosts; per-state and global concurrency limits remain under agent.

SSH workers run the installed detent binary on each selected host over an SSH stdio channel. Workspace setup, hooks, provider processes, gates, and Git pushes execute there; session records, Workpads, lane decisions, and merge coordination stay with the orchestrator. Hosts use normal SSH configuration and host-key verification, with noninteractive authentication and no agent forwarding.

worker:
  # Per runner host; omitted prices inherit Sprites public rates.
  compute_rates:
    local:
      cpu_hour_usd: 0.07
      memory_gb_hour_usd: 0.04375
  ssh_hosts: [example-laptop, example-build-host, local]
  host_selection: preference
  max_concurrent_agents_per_host: 2
  host_caps:
    example-laptop: 2
    example-build-host: 6
    local: 1

Sandboxed workers can opt into localhost servers and connections for HTTP tests with worker.allow_local_binding. It defaults to false. Set the instance default in the global config:

global:
  worker:
    allow_local_binding: true

Override that default in a project's detent.yaml or machine-local detent.local.yaml:

worker:
  allow_local_binding: false

An omitted project value inherits the instance default; explicit false disables it even when the instance default is true. The effective grant participates in Cloud policy approval. It keeps the sandbox tier and file restrictions, but permits connections to other localhost services as well as temporary test servers. Codex also skips its proxy's private-network destination check with this grant; proxy domain rules still apply. Restricted Codex turns keep networking disabled.

A project can grant additional exact DNS hosts through worker.extra_network_domains in detent.yaml or detent.local.yaml:

worker:
  extra_network_domains:
    - fonts.googleapis.com
    - fonts.gstatic.com

The list adds to Detent's dependency/provider hosts. It defaults to empty and participates in Cloud policy approval. Wildcards, URLs, IP addresses, ports, duplicates and uppercase hosts are rejected. Filesystem restrictions and the sandbox tier remain in effect; restricted Codex turns keep networking disabled.

preference fills hosts in list order to their project-specific cap. The default least_loaded selects the least busy available host and retains retry affinity when that host has capacity. host_caps overrides the fallback max_concurrent_agents_per_host for individual configured hosts. Include local where local execution belongs in the order; an empty list means local execution. The existing project and instance agent limits still apply.

Install matching Detent binaries, Git, gh, and the configured provider on every remote host. Provider subscription authentication must already be available there. The noninteractive SSH environment must provide a writable TMPDIR, TMP, or TEMP; workers never fall back to host scratch space. Paths below the orchestrator's home directory are mapped below the remote user's home directory; other absolute paths must exist on that host. Hook references to the home path are mapped too. Provision the source checkout there, or allow Detent to clone its HTTPS origin into the mapped source root on first use.

Detent checks SSH reachability and the worker protocol before dispatch, caches the result for 15 seconds, and skips unavailable hosts. A lost channel cancels the remote lifecycle and uses the existing instance retry path. A retry on a different host starts a fresh provider session. Existing workspace reaping and reconciliation also visit configured remote hosts. GitHub credentials cross only the encrypted channel and use the same private temporary GH_CONFIG_DIR as local workers; they are removed when the worker exits and never written to the source checkout or persistent Git configuration.

Remote workers support GitHub, Linear, and hub_native trackers. Native runs capture artifacts and attempt diffs on the selected host through SSH; upload journals, credentials, lease fencing, Change Request publication, landing reports, and provider reservations remain central. Interrupted transfers retain their journals for existing recovery. Both endpoints must support SSH protocol version 2.

GitHub-capable workers never inherit GITHUB_TOKEN, GH_TOKEN, their enterprise variants, or the host's GitHub CLI configuration. When omitted or empty, worker.github_token defaults to the resolved top-level github_token (including github_token: gh), except for tracker.kind: hub_native projects, which never inherit the instance credential. An explicit project worker credential overrides that default; with neither credential configured, the worker policy is disabled. For native landing pushes, HTTPS uses the runner host's GitHub CLI login when no worker token is handed off; SSH uses the host's SSH key. An explicitly handed off worker token remains the Git credential for HTTPS operations in that worker. worker.github_token controls agent GitHub access; it is not required for native landing. Agent GitHub CLI calls retain their private GH_CONFIG_DIR in both cases. detent doctor includes a named landing push credential check that runs a noninteractive dry run without changing remote refs. Set the worker override to gh to resolve gh auth token in the Detent process and copy only the resolved token into the worker's isolated GH_CONFIG_DIR. An environment reference remains available when permission or revocation isolation is useful:

worker:
  github_token: gh
  github_token_resolution_timeout_ms: 15000
  github_rest_min_remaining_reserve: 1250
  github_rest_poll_interval_ms: 60000

The token-resolution timeout applies to each gh auth token invocation. Detent tries the command up to three times with short backoff before recording a same-attempt infrastructure wait; these failures do not consume issue attempt or failure-breaker budgets. Increase the timeout when the host credential store can legitimately take longer than 15 seconds.

After resolving gh, Detent classifies an exact orchestrator token or any token that resolves to the same GitHub user as shared_budget: GitHub's primary REST limit is per user, so a second token changes permissions and revocation without creating another rate-limit pool. Shared-pool telemetry uses consumer: shared_pool and reports usage attribution as indeterminate rather than assigning the pool's global usage to workers. A different GitHub user or App installation is distinct_principal, the true rate-limit-isolation mode.

The default worker reserve is 1250, above the default orchestrator dispatch floor of 1000. Shared-mode workers therefore brake first so dispatch can continue. Detent probes the worker credential at launch and no more often than the configured interval, and stops or refuses a worker at its reserve. Keep literal tokens out of checked-in project files.

workpad.structured_only requires machine-readable workpad status instead of accepting legacy narrative signals. GitHub native blocked-by relations and recognized current issue-body dependency lines form one blocker list. Native metadata wins for duplicate references; an empty native list does not discard body declarations. Fenced examples never add blockers. Historical comments are diagnostic only, with unmatched references reported as ignored in issue explanations. Unsupported repositories use body declarations alone. Failed blocker-state lookups propagate errors rather than returning dispatch candidates.

The existing dependencies.source values (merged and native_only) are deprecated compatibility aliases for this same behavior; neither disables current body declarations. Remove a body declaration to remove its blocker (and remove the native relation as well if one exists).

Agents, backends, and routing

agent is the orchestration policy: concurrency, turn and session limits, retry brakes, spend limits, shutdown, dispatch priority, automatic promotion, state-specific instructions, learned context, skill drafts, and follow-up work. agents.backends defines pluggable Codex, Claude Code, or Pi processes, while agents.routes selects a backend and model by role or issue selector.

codex is the legacy/default Codex backend configuration and remains the fallback when agents.backends is empty. A Codex backend inherits omitted values from it. Claude Code backend options are interpreted only when the backend kind is claude_code.

Pi uses kind: pi_agent, protocol: rpc, and command: pi by default. The backend provider and existing routes select its provider and exact model ID. Pi requires native-trusted isolation; sandboxed/read-only turns, resume, Detent dynamic tools and persisted history hydration are unsupported in this initial integration. See Pi backend configuration and limitations for a complete route example, authentication and an opt-in smoke test.

Implementation workers on automatically owned Git branches request a bounded recovery checkpoint when a duration, turn, or no-progress limit stops them. agent.checkpoint_interval_ms also enables periodic checkpoints; 0 disables the periodic trigger. Each checkpoint allows up to two minutes for a read-only worker to select reviewed issue files and for Detent to commit and publish them with lease and remote checks. Periodic checkpoints retain the session deadline and accumulated budget usage. Identical work does not create new commits.

Checkpoint publication may associate a draft PR and never satisfies completion, review, or CI gates. If delivery is unavailable, the owned workspace remains recoverable. Its Git metadata contains detent-checkpoint.json, written before worker execution, so an interrupted or killed worker does not imply that a checkpoint epilogue ran. Human branches and backends without the handshake continue to rely on local workspace recovery.

agent.auto_promote and gate work together. Auto-promotion decides when an item may leave its source state; the gate decides whether CI, automated review, human approval, a validator, or an artifact status is sufficient. plan optionally inserts a plan-review stop before implementation.

The validator records evidence for each acceptance criterion on the immutable Change round. gate.validator.unverified_criteria defaults to rework: any gap returns the work for evidence, with the criterion named. Set it to pass-with-disclosure to allow a pass while retaining the unverified list for review. Minimum score and blocked finding severities still apply. Criteria come from the issue contract's Acceptance criteria section, or its first required section when a project uses a custom contract without that heading.

Operations, budgets, and observability

active_hours optionally limits new agent dispatches to recurring weekday and wall-clock spans in a required IANA timezone. Use window values such as Mon-Fri 22:00-06:00; ranges that end before their start wrap past midnight, and 00:00-24:00 covers a full day. A project entry in global.yaml overrides global.active_hours, and either host-local value overrides the project's checked-in setting. Window close drains existing agents instead of stopping them.

Detent evaluates membership on each scheduler tick, preserving local wall-clock hours through daylight-saving changes and restarts. Spring forward can shorten a wrapping window by one hour, while fall back can lengthen it by one hour. detent doctor previews opening and closing times in both the named timezone and UTC. A temporary detent resume <id> --for <duration> override admits work outside the window until its persisted expiry; manual pause remains the stronger, independent gate.

observability controls dashboard refresh, efficiency anomaly thresholds, and optional OTLP export. budget is the project-wide spend policy; agent.budget can further constrain agent sessions. release enables release-readiness automation after merged work accumulates.

Release automation requires tracker.kind: github, tracker.repository: owner/repository, and release.enabled: true. It is unavailable for hub_native with either plain git delivery (deliverable.github_pull_request: false, the default) or GitHub pull request delivery (deliverable.github_pull_request: true). Config validation rejects release.enabled: true for native projects, including the release-unavailable warning in the returned error so creation and reload failures surface it. Leave release.enabled: false when migrating to hub_native. Opting into GitHub pull requests does not enable release automation.

observability.stranded_active_threshold_seconds controls when Health and detent doctor report an issue that remains in In Progress without a live worker and when Detent recovers it automatically. Issues with an open pull request or recoverable workspace work move to Rework; issues confirmed to have no recovery artifacts move to Todo. Detent holds the issue in place when artifact evidence is unavailable. The default is 600 seconds, which tolerates normal gaps between a completed session and prompt re-dispatch.

hooks run lifecycle commands around worktree creation, agent execution, and cleanup. Treat them as trusted code: they run with the Detent process permissions and should be short, deterministic, and safe to retry.

hooks.runner_setup names a repository-relative script for project tools on a registered runner. It runs from the project's source checkout during runner preparation, before any work is claimed, and is checked before subsequent dispatch. It uses hooks.shell and hooks.timeout_ms (60 seconds by default; increase this for installers). The script need not have executable permission.

hooks:
  runner_setup: scripts/runner-setup.sh
  shell: bash
  timeout_ms: 300000

Each runner records the successful SHA-256 of the script content, shell and source checkout path in its local store, scoped to its runner identity and project. When the checkout is a Git clone, the runner also writes the hash to .git/detent-runner-setup inside it. Unchanged setup does not run for later attempts or after restarting with the same store. Changing the script, shell or checkout path, or recreating the checkout, runs setup again before the next dispatch. With workflow_ref, the script comes from the same Git revision as the project's configuration; otherwise it comes from the source checkout, including local edits. Paths must remain inside the repository. Keep setup self-contained: changes to files sourced by the script do not change its recorded hash.

Setup is trusted host code. Make it idempotent, non-interactive, and free of secrets; the runner closes standard input and inherits its host environment, including native tool caches and supplied scratch directories. Install CLIs into a directory already on the runner's PATH. Shell exports do not persist into later agent turns. Setup failures are instance-owned for that project on that runner, appear in runner logs and the project's local-check API report, and prevent claims and dispatch without consuming an issue failure allowance. The existing project polling retries setup until it succeeds. Other projects and runners remain eligible.

Use workspace hooks for worktree or attempt preparation. Move project tool installation from hooks.after_create, hooks.before_run, or Sprite pool customer bootstrap into this script. Pool bootstrap is reserved for prerequisites that cannot live in a readable repository file, such as fetching credentials through a customer's secret service or obtaining the checkout.

Intake, retrospectives, routines, and admission

intake.sources, retro, routines, and backlog_admission are scheduled features of repository trackers. tracker.kind: hub_native rejects intake.sources and routines, retro requires a github or memory tracker, and backlog_admission needs candidate selectors that native trackers do not provide. Native cutover refuses a workflow that still enables any of them.

Fleet staleness warnings

observability.staleness detects work items that exceed lane-specific aging thresholds, non-empty dispatch or merge queues that stop advancing, and repeated identical scheduler decisions. Lane residency starts at the most recent entry. Repeated entries can still raise a cumulative warning when their residency exceeds the lane threshold within observability.staleness.lane_reentry_window_hours. Human-gate lanes emit one reminder at their threshold, then remain quiet until the lane changes or observability.staleness.human_gate_rearm_hours passes. Sticky breaker and operator parks with a recorded cause are excluded from lane aging because the Blocked lane already carries their operator signal. A park_cause_stale warning replaces lane aging when recorded evidence is cleared or can no longer be verified.

Operator-facing warnings use the same authorization selector as board and runtime rows. Item warnings outside that selector are excluded before they are logged, delivered, or counted. Project-level liveness warnings are computed from authorized dispatch and merge queues. Repeated decisions about the authorization boundary itself, including authorization_selector_declined, remain visible even when the affected item is out of scope because the selector decision is the condition the operator must correct.

A Blocked item observed from tracker state without a recorded blocker cause is classified as blocked, cause unrecorded. The card keeps that classification beside its lane provenance, and an eventual lane-aging warning names the missing cause and the remedy instead of presenting an unexplained generic Blocked age.

The repeated-decision detector considers only current, non-terminal items. Closed and merged items and items in a configured terminal state are excluded. observability.staleness.repeated_decision_benign_reasons lists scheduler reasons that represent healthy waits rather than operator-actionable stalls. Its defaults cover active workers, dependency waits, global-capacity waits, and GitHub REST pacing. Set the list explicitly to replace those defaults for a project. Values must exactly match a scheduler-emitted reason. Configuration validation reports the configured value and the emitted reason set when they do not match; for example, unauthorized does not match authorization_selector_declined. This validation is also surfaced by detent doctor during config resolution.

The detector evaluates decisions inside observability.staleness.repeated_window_hours, but the orchestrator retains only the 500 most recent scheduler decisions. Its effective history is therefore whichever is smaller: the configured time window or the retained 500-decision sample.

Warnings appear in the dashboard, /health, and detent doctor. Configure observability.staleness.webhook.url to push each newly active warning as a detent.staleness.warning JSON event. The payload includes a stable warning ID, the affected project or item, the reason, and age and threshold values in seconds. A delivered warning is not sent again on every scheduler tick. A dashboard dismissal persists until the warning condition changes, such as a new lane entry or a new scheduler cause.

Unstarted GitHub checks

tracker.github_unstarted_check_threshold_seconds controls when a GitHub check that remains queued without a started_at timestamp appears as unstarted. The 15-minute default is intentionally non-zero because a cold or busy runner pool can legitimately take several minutes to pick up a job; setting the threshold too low would turn ordinary queueing into an operator-facing signal.

Codex deliverable elicitation

codex.deliverable_elicitation_allowlist declares exact MCP mutation tuples that an unattended Codex worker may confirm for its configured deliverable. The same field is available under agents.backends[].options for a routed Codex backend. It defaults to an empty list. Each entry requires server, tool, and repository; server-only entries are invalid.

codex:
  approval_policy: never
  deliverable_elicitation_allowlist:
    - server: codex_apps
      tool: github.create_pull_request
      repository: digitaldrywood/detent
    - server: codex_apps
      tool: github.update_pull_request
      repository: digitaldrywood/detent
    - server: codex_apps
      tool: github.add_comment_to_issue
      repository: digitaldrywood/detent
    - server: codex_apps
      tool: github.update_issue_comment
      repository: digitaldrywood/detent
    - server: codex_apps
      tool: github.update_issue
      repository: digitaldrywood/detent
    - server: codex_apps
      tool: github.create_issue
      repository: digitaldrywood/detent

The allowlist is a narrow exception to codex.approval_policy, not a broader approval mode. With either never or on-request, Detent accepts an MCP elicitation only when it correlates to exactly one pending tool call on the same server, thread, and turn; the correlated tool is a supported workflow deliverable mutation; and both its repository argument and the corresponding active work-item repository match the configured tuple. Pull-request mutations match the linked pull-request repository. Issue and Workpad mutations match the tracked issue repository and are accepted only when it is also the deliverable repository. Detent declines these direct Codex issue mutations when the linked pull request belongs to another repository because MCP elicitation cannot rewrite the already-pending arguments through the visibility-aware publication protector. Connector-backed issue writes remain available and apply that protector before sending content. Pull-request and issue creation and updates use repository_full_name; issue comment creation and updates use repo_full_name. Missing or ambiguous correlation, other mutation tools including github.delete_issue, and repository mismatches are declined. Command, file-change, permission, and user-input requests retain their existing handling.

Allowlisting github.create_issue authorizes issue creation only on the workflow's own tracked repository. This supports workers filing scoped issues they discover while delivering the current work item; it does not authorize issue deletion, transfer, or creation in any other repository. Those mutations remain non-deliverable.

Allowlisting github.update_issue permits its full exposed mutation surface: title, body, state, assignees, milestone, and labels may all be replaced. The allowlist correlates and constrains the repository, but does not constrain the other approved arguments.

With approval_policy: never and an empty allowlist, non-browser MCP elicitations are declined exactly as before. chrome-devtools empty-form tool approval remains a separate built-in behavior and is unchanged by this list.

Generated field reference

The generated block reflects the YAML-tagged Go structs reachable from the project config. It reads effective defaults through the real normalization path and derives validation text by exercising boundary values through the real loader and validators. “None” means no field-level rule was surfaced; subsystem interactions can still constrain a value.

Run go generate ./... after changing the config structs, defaults, or validators. make check compares the committed generated artifacts with fresh rendering and fails on drift.

budget.per_issue_max_usd and agent.budget.per_issue_max_usd are estimate-based admission backstops, not mid-session spend ceilings. Detent checks cumulative issue spend plus a preflight session estimate before starting the agent. Actual session cost can exceed that estimate and the configured backstop. Once the next projected dispatch would exceed the backstop, Detent parks the issue on a hard hold until an operator raises or disables the cap, or explicitly retries after resetting the hold. refusal_cooldown_seconds applies only to resettable budget pacing and never clears a per-issue hard hold.

Per-change security audit

gate.security_audit.enabled defaults to true for every tracker. The audit reviews each immutable base/head before merge. P1/P2 findings send the change to Rework when confirmed; non-blocking findings remain recorded on the Change or pull request. A potentially P1/P2 lead that cannot be established from the supplied evidence has certainty undetermined, no severity, and an explicit unresolved fact. The same stage verifies it once using the effective model selection's complex model in a fresh session, with all supplied evidence and the original deadline and capacity reservation. Confirmed findings go to Rework; disproved leads remain recorded as rejected with their reasoning. If verification still cannot decide, native completion uses the existing Blocked human_action park, naming the lead, both verdicts and the unresolved fact. Both audit verdicts are retained on the Change. Prior unresolved findings remain blocking when their context is absent; their unresolved severity cannot change. Backend and runner failures are instance failures and do not become findings.

For tracker.kind: hub_native, audits run for both plain git delivery (deliverable.github_pull_request: false, the default) and GitHub pull request delivery (deliverable.github_pull_request: true). Migrating to the native tracker requires no audit opt-in: keep the default or explicitly set gate.security_audit.enabled: true in the approved project policy. GitHub pull request delivery is not required for the audit.

The effective model selection's stages.security_audit selects the backend, model and effort. Codex and Claude use their ordinary authentication, including subscription and metered accounts. Each audit consumes provider tokens and runtime, reported with other stage usage; metered accounts incur their usual provider charges. Native direct landing also audits the integrated base/head before push. A rebase, an earlier batch member or a concurrent base update requires fresh evidence for the resulting commit and incurs another audit.

To disable it, explicitly set the existing project gate policy in detent.yaml (or update that policy through the project's existing configuration API/MCP owner):

gate:
  security_audit:
    enabled: false

An explicit false wins over the default. Repository-owned native policy changes still require approval through the existing trusted-revision policy owner.