Struct SettingsSupervisor 

pub struct SettingsSupervisor {

    pub auto_start: bool,
    pub cleanup_orphans: bool,
    pub container: bool,
    pub cpu_violation_threshold: i64,
    pub cron_check_interval: String,
    pub file_watch_debounce: String,
    pub health_check_interval: String,
    pub health_check_retries: i64,
    pub health_cmd_timeout: String,
    pub health_http_timeout: String,
    pub health_port_timeout: String,
    pub http_client_timeout: String,
    pub log_flush_interval: String,
    pub orphan_policy: String,
    pub port_bump_attempts: i64,
    pub ready_check_interval: String,
    pub restart_delay: String,
    pub oneshot_timeout: String,
    pub stop_timeout: String,
    pub user: String,
    pub watch_interval: String,
    pub watch_poll_interval: String,
}

The supervisor.* settings.

Fields

auto_start: bool

Automatically start the supervisor when a client command needs it

When enabled (default), commands such as pitchfork start, pitchfork list, the TUI, and shell activation start a background supervisor automatically when one is not already running.

Disable this when the supervisor is managed by systemd, launchd, or another service manager:

[settings.supervisor]
auto_start = false

With auto-start disabled, client commands wait for the configured IPC connection attempts and then fail with an actionable error instead of spawning an unmanaged supervisor. Explicit pitchfork supervisor start and pitchfork supervisor run commands are unaffected.

cleanup_orphans: bool

Reconcile orphaned daemon processes when supervisor starts

When enabled, the supervisor scans the state file on startup for daemon processes left behind by a previous supervisor instance that was killed unexpectedly (for example, with kill -9) and reconciles them according to supervisor.orphan_policy (re-adopt by default, or terminate).

Before acting, the recorded process identity (PID plus kernel start time) is verified so that a PID recycled by the OS to an unrelated process is never adopted or killed — in that case only the stale state entry is cleared. When terminating, Linux and Windows also pin that identity with a pidfd or open process handle, so a recycled PID cannot be signaled. If the identity cannot be verified or pinned, reconciliation fails closed: the live process and its running state are retained rather than risk acting on the wrong process or allowing a duplicate instance to start.

Disabling this leaves orphaned processes and their state entries completely untouched. This is a legacy escape hatch; prefer orphan_policy = "adopt" (the default), which keeps daemons running across a supervisor crash while resuming supervision.

container: bool

Enable container/PID1 mode for running inside Docker containers

When enabled, pitchfork operates as a proper PID 1 process inside a container:

• Installs a SIGCHLD handler to reap all orphaned/zombie child processes
• Routes SIGTERM/SIGINT through the graceful shutdown sequence

This is essential when running pitchfork as the entrypoint of a Docker container, where PID 1 must reap zombie processes to prevent process table exhaustion.

Can also be enabled via the --container CLI flag on pitchfork supervisor run.

cpu_violation_threshold: i64

Consecutive CPU-over-limit samples before killing a daemon

When a daemon has cpu_limit configured, the supervisor checks CPU usage at each interval tick. To avoid killing daemons during transient spikes (e.g. JIT warm-up, burst responses), the process is only killed after this many consecutive samples exceed the limit. A single sample below the limit resets the counter.

Examples:

• 1 - Kill immediately on first over-limit sample (no grace period)
• 3 - Require 3 consecutive over-limit samples (default)
• 5 - More tolerant of short bursts

With the default interval of 10s, a threshold of 3 means a daemon must exceed its CPU limit for ~30 seconds before being killed.

cron_check_interval: String

Interval for checking cron schedules

How often to check if any cron-scheduled daemons should be triggered.

The default of 10 seconds supports sub-minute cron schedules. Increase for lower resource usage if you don’t need fine-grained scheduling.

file_watch_debounce: String

File watch debounce duration

When using watch patterns to auto-restart daemons on file changes, this controls how long to wait after the last change before triggering a restart.

This prevents rapid restart cycles when many files change at once (e.g., during a build or git checkout).

health_check_interval: String

Default time between health probes

When a daemon has health_cmd, health_http or health_port configured but does not set its own interval, the supervisor probes it this often.

health_check_retries: i64

Default consecutive health-check failures before killing a daemon

When a daemon’s health_cmd, health_http or health_port fails this many times in a row, the daemon is killed as a crash so the retry logic restarts it. Individual daemons can override this with retries in their health check configuration.

health_cmd_timeout: String

Default per-probe timeout for health_cmd

Maximum time to wait for a health_cmd shell command to finish before counting the probe as failed and cancelling it.

health_http_timeout: String

Default per-request timeout for health_http

Maximum time to wait for a response from a health_http endpoint before counting the probe as failed.

health_port_timeout: String

Default per-connect timeout for health_port

Maximum time to wait for a TCP connection to a health_port to establish before counting the probe as failed.

http_client_timeout: String

Timeout for HTTP ready checks

Maximum time to wait for a response when checking ready_http endpoints.

Increase if your services take a while to respond during startup.

log_flush_interval: String

Daemon log buffer flush interval

How often daemon log output is flushed to disk. Lower values mean logs appear faster in the UI but may impact performance.

orphan_policy: String

What to do with live orphaned daemons on supervisor startup: adopt or kill

When the supervisor starts and finds daemons in the state file whose processes are still alive from a previous supervisor instance that died uncleanly, this policy decides what happens (after the process identity is verified via PID plus kernel start time):

• adopt (default): keep the process running and resume supervision. The daemon keeps its state (status, ports, proxy routing) and is monitored by polling. Log capture is unaffected, because a daemon’s output is read by a sibling sink process rather than by the supervisor, so it continues uninterrupted across the crash. Exit codes of adopted daemons cannot be observed, though; an adopted daemon that dies unexpectedly is marked errored with an unknown exit code, which makes it eligible for its configured retries.
• kill: terminate the orphaned process group so the new supervisor starts with a clean slate, matching pre-adoption behavior.

Daemons whose recorded PID is dead, or whose PID now belongs to a different process, have their state reset under either policy. If the process identity cannot be verified, reconciliation fails closed and retains the running state without adopting or killing.

The same policy applies when the interval watcher finds a running daemon that has lost its monitor at runtime.

This setting has no effect when cleanup_orphans is disabled.

port_bump_attempts: i64

Maximum port increment attempts when auto_bump_port is enabled

When auto_bump_port = true is set on a daemon, pitchfork will try incrementing all of the daemon’s ports by the same offset to find a free range. This setting controls how many offsets are tried before giving up with an error.

For example, with port = [3000] and port_bump_attempts = 10, pitchfork will try ports 3000, 3001, 3002, … up to 3009 before reporting failure.

This is a global default; individual daemons can override it with port_bump_attempts in their daemon configuration.

ready_check_interval: String

Interval between ready checks (HTTP, TCP, command)

How often to poll when checking if a daemon is ready using:

• ready_http - HTTP health endpoint
• ready_port - TCP port listening
• ready_cmd - Shell command exit code

Lower values detect readiness faster but use more resources.

restart_delay: String

Delay between stop and start during restart

Brief pause after stopping a daemon before starting it again. Helps ensure resources (like ports) are fully released.

oneshot_timeout: String

Maximum time to wait for a oneshot daemon to finish

A oneshot = true daemon is ready when its process exits 0, so there is no readiness check to bound the wait. pitchfork start gives up after this long and reports a timeout; the task itself keeps running and is still recorded as completed if it later exits successfully. A nonzero exit remains a failure.

Set to 0 for no limit. Raise it for long migrations, backfills, or seeds.

stop_timeout: String

Maximum time to wait for daemon to stop gracefully

When stopping a daemon, pitchfork sends its configured signal (SIGTERM by default) and waits this long for the process to exit gracefully before sending SIGKILL.

Increase for daemons that need time to clean up (e.g., flush data).

user: String

Default user to run daemon processes as

Default Unix user for daemon processes spawned by the supervisor.

When set, all daemons run as this user unless an individual daemon sets user = "...". The value may be a username (for example "postgres") or a numeric UID (for example "501").

If unset and the supervisor is running as root via sudo, daemons default to the sudo-calling user from SUDO_UID/SUDO_GID instead of running as root.

watch_interval: String

File watcher config refresh interval

How often the supervisor refreshes file watch configuration when using watch patterns.

This controls how quickly newly started/stopped daemons with watch patterns are reflected in the active watcher set.

For polling watcher cadence, use supervisor.watch_poll_interval.

Lower values react faster to configuration/runtime changes but use more CPU. The default "10s" is appropriate for most environments.

watch_poll_interval: String

Polling watcher filesystem scan interval

How often polling-based file watchers scan for changes.

This applies when daemon watch_mode is poll, or when watch_mode = "auto" falls back to polling because native watchers are unavailable.

Lower values detect changes faster but use more CPU and I/O. "100ms" is useful for highly interactive workflows; "500ms" is a practical default for remote/networked filesystems.

Implementations

impl SettingsSupervisor

pub const SETTINGS_PROPS: &'static [PropMeta] = <Self as ::usage_config::Props>::PROPS

Every setting this struct declares, one entry per field, flattened groups included. The registry a build.rs used to generate, generated from the struct instead — there is no second declaration to keep in step.

pub const SETTINGS_REGISTRY: Registry

The registry over Self::SETTINGS_PROPS, for resolve, drift, and the layers.

pub const SETTINGS_SPEC: ConfigSpec

Metadata used only when lowering this declaration into a usage spec.

pub fn read(__usage_resolved: &Resolved) -> Result<Self, ReadErrors>

This resolution’s values, as the struct.

Every field is read before anything is returned, so the error is the whole list of what is wrong rather than the first thing found.

pub fn read_lossy(__usage_resolved: &Resolved) -> (Option<Self>, ReadErrors)

This resolution’s values, keeping every setting that reads.

Self::read is all or nothing, which leaves a CLI two moves when one field is bad: refuse to start, or fall back to a struct of declared defaults and lose the environment and every config file along with the offending value. Neither is a choice this crate should be making.

So: a field that will not read falls back to its own declared default and the rest keep what the merge gave them, with every failure returned alongside for the CLI to raise, log, or ignore as it sees fit. The errors are the same ::usage_config::ReadErrors Self::read returns, so a caller that decides a bad value is fatal has lost nothing by asking.

None only where a setting has no value and no declared default — a hole in the declaration rather than a bad value, and nothing to fall back to.

pub fn spec_kdl() -> String

The spec config block for these settings, as KDL.

What documents, JSON schema and completions read. A CLI deriving usage::Cli names this type in #[usage(config = ...)] instead of calling this, and its to_kdl carries the block.

Trait Implementations

impl Clone for SettingsSupervisor

fn clone(&self) -> SettingsSupervisor

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SettingsSupervisor

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl PartialEq for SettingsSupervisor

fn eq(&self, other: &SettingsSupervisor) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl Props for SettingsSupervisor

const PROPS: &'static [PropMeta]

This group’s settings, in declaration order.

const PROP_SPECS: &'static [PropSpec]

Spec-only metadata parallel to Props::PROPS.

impl StructuralPartialEq for SettingsSupervisor