Summary

gbrain autopilot and gbrain jobs supervisor both have worker-lifecycle behavior today, which can make the intended production deployment shape ambiguous.

From local docs/code, the clean split seems to be:

• gbrain autopilot: schedules/dispatches maintenance cycles, e.g. autopilot-cycle jobs.
• gbrain jobs supervisor: owns the durable gbrain jobs work process, restart semantics, pid file, and doctor health signal.

Why this matters

If an operator runs autopilot in default worker-spawning mode and also runs a standalone/systemd supervisor, they can accidentally create duplicate workers. If they only run autopilot with its child worker, gbrain doctor may warn that the supervisor is not running even though there is a worker process.

Proposed docs / behavior clarification

Document or enforce one recommended production shape:

gbrain autopilot --repo <brain-repo> --no-worker
gbrain jobs supervisor --concurrency <n> --max-rss <mb>

In that shape:

• autopilot dispatches maintenance cycles;
• supervisor owns the worker;
• doctor's supervisor check maps to the actual worker owner;
• duplicate worker lanes are avoided.

Potential code/doc improvements:

1. Make gbrain autopilot --install optionally install dispatch-only mode when a supervisor service is present.
2. Add docs warning not to run autopilot's managed child worker and standalone supervisor simultaneously.
3. Consider doctor messaging that distinguishes "no supervisor, but autopilot has a child worker" from "no worker owner at all".

Local validation

A local systemd setup using this split produced:

gbrain jobs supervisor --concurrency 2 --max-rss 2048
gbrain jobs work --concurrency 2 --queue default --max-rss 2048
gbrain autopilot --repo /home/shan/brain/knowledge --no-worker

gbrain doctor then reports:

supervisor: ok
queue_health: ok