Foreman

Foreman keeps toryo's background services running. It understands service dependencies, probes live state, starts what is needed, and reconciles failures from its watch supervisor.

Reading service state#

Foreman reports several independent dimensions:

• Healthy or unhealthy says whether an applicable service is working.
• Unavailable says an optional service does not apply on this host. Ollama may be unavailable without making the overall stack red. In local mode, explicitly asking Foreman to start unavailable Ollama fails and explains how to install it. An external Ollama that is not answering is also unavailable rather than failed, and toryo foreman up still exits 0. Naming it, as in toryo foreman up ollama, still fails.
• Code freshness compares the running process with the installed code. A stale service can still be healthy; it needs a restart to pick up new code. The supervisor gets the same check. A stale supervisor usually restarts itself within a few minutes; if Board's supervisor: stale code chip stays, restart it (see below).
• Supervisor liveness says whether foreman watch is present to reconcile future failures.
• Schema drift says an app database is missing migrations its binary expects. It never turns the stack red, because no restart fixes it. check names the app and the fix, usually toryo <app> migrate, or toryo update when the installed migration files are themselves stale. Board shows a yellow schema chip.
• Maintenance says a Foreman command or the supervisor is starting, restarting or stopping the stack right now. Services it has not reached yet read red until it finishes, so Board shows starting or restarting instead of a down count and holds back its lifecycle controls.
• Queued restart records a per-service restart that will run after the service or supervisor becomes quiescent.

Board renders these separately so an unavailable optional dependency or stale binary is not mistaken for a crashed service.

What it supervises#

Foreman manages local Postgres (Docker or pglite), Dispatch, Messaging, Scheduler, Sequence, Relay, and local optional Ollama. Acceptance commands run as ordinary Dispatch jobs, not as a service of their own; see Local acceptance. A running acceptance command counts as active Dispatch work, so a restart waits for it. For externally owned PostgreSQL or Ollama it checks connectivity but does not start or stop the service. Dependencies are respected in both directions: starts bring prerequisites up first, and stops include dependents whose open connections would otherwise become stale.

With pglite, every app database runs in one server process sized to stay under 1 GiB. An existing install picks up the smaller footprint the next time Postgres restarts. A first pglite start can take a minute or two; Foreman keeps waiting as long as databases are still coming up.

toryo setup installs foreman watch as a launchd agent on macOS or a user systemd unit where available on Linux. In normal use you do not start it by hand.

Checking and repairing#

toryo foreman check
toryo doctor

check reports service health, availability, schema drift, the maintenance state, freshness, start times, supervisor liveness and code freshness, and queued restarts. It reads each daemon's own health report, so it is cheap to run often. A daemon that holds its lock but does not answer within 5 seconds reads red, never green.

doctor checks the wider host contract: tools, configuration, database access, migrations, models, license, and registrations. doctor treats agent harnesses as one requirement: it passes when any harness enabled in Worker settings works, and lists disabled ones as disabled, with no install hint. Run doctor first when the cause is unclear.

A normal restart protects active work. If the target cannot reach quiescence, Foreman leaves it running, queues a service restart when possible, names the blocker, and exits 75. Retry after the work drains.

--force skips the wait and bounces the service now, with one exception: a Dispatch that is draining in-flight jobs is not killed, so the restart exits 1 and Dispatch comes back once its jobs finish.

To restart the supervisor itself on macOS, run toryo supervisor restart, or use Restart on Board's Foreman pill. Avoid stop followed by start, which can leave it stopped while both commands report success. restart waits for the old agent to leave and exits 1 if it cannot confirm the new one. On Linux, run systemctl --user restart toryo-foreman-watch.service. Restarting the supervisor can restart the services it launched.

Exact commands, flags, exit codes, and JSON report schemas live in the CLI & contract reference.

Common symptoms#

• A service repeatedly becomes red. Its start time keeps resetting while watch retries it. Read ~/.toryo/foreman/logs/ and run toryo doctor.
• A service is green but stale. Restart it when work is quiet. A queued badge means Foreman already holds that intent.
• Ollama is unavailable. For local mode, install Ollama and its models. For external mode, check the configured host and its models. Core services remain healthy while semantic enrichment degrades.
• The supervisor is down. Current services may remain green, but future failures will not be reconciled. Re-run toryo setup to reinstall it.