diff --git a/docs/guides/cron-schedule.md b/docs/guides/cron-schedule.md index a96609f2d..19dbbe15d 100644 --- a/docs/guides/cron-schedule.md +++ b/docs/guides/cron-schedule.md @@ -41,7 +41,9 @@ fixed. You wake up and the brain is smarter than when you went to sleep. # Calendar sync — Sundays at 10 AM 0 10 * * 0 cd /path/to/calendar-sync && node calendar-sync.mjs --start $(date -v-7d +%Y-%m-%d) --end $(date +%Y-%m-%d) -# Brain health — weekly Mondays at 6 AM +# Brain health — weekly DEEP pass, Mondays at 6 AM (doctor + embed backfill). +# This complements — does not replace — the DAILY `gbrain doctor` heartbeat +# from operational-disciplines.md Discipline 4: heartbeat=daily, deep pass=weekly. 0 6 * * 1 gbrain doctor --json >> /tmp/gbrain-health.log 2>&1 && gbrain embed --stale # Dream cycle — nightly at 2 AM diff --git a/docs/guides/minions-deployment.md b/docs/guides/minions-deployment.md index d7115e5d8..fd8369863 100644 --- a/docs/guides/minions-deployment.md +++ b/docs/guides/minions-deployment.md @@ -26,11 +26,25 @@ with exponential backoff (1s → 60s cap), emits lifecycle events to an audit file, and drains gracefully on SIGTERM (35s worker-drain window before SIGKILL). Exit codes are documented so agents can branch on them. +**Concurrency defaults (single source of truth):** + +| Command | Default | Flag / env | +|---|---|---| +| `gbrain jobs work` | **1** | `--concurrency N` / `GBRAIN_WORKER_CONCURRENCY` | +| `gbrain jobs supervisor` | **2** | `--concurrency N` (passed through to the worker) | + +Every snippet in this guide (systemd, Fly, Procfile) pins `--concurrency 2` +explicitly — the recommended baseline. Why not 1: at concurrency 1 a job that +submits and waits on its own subagent job (e.g. an autopilot cycle) can never +have that subagent claimed — the single slot is already occupied (#2782). Why +not more: each slot holds a DB connection and can fan out an LLM subagent, so +scale to 4 only when throughput demands it and your Postgres pool has headroom. + **Typical commands:** ```bash # Start in the foreground (blocks; Ctrl-C to stop). -gbrain jobs supervisor --concurrency 4 +gbrain jobs supervisor --concurrency 2 # Start detached — returns {"event":"started","supervisor_pid":…} on stdout. gbrain jobs supervisor start --detach --json @@ -66,10 +80,10 @@ isn't: ```bash # Full concurrency, low priority. Propagates to the spawned worker and its # children (shell jobs, subagents) via OS niceness inheritance. -gbrain jobs supervisor --concurrency 4 --nice 10 +gbrain jobs supervisor --concurrency 2 --nice 10 # Equivalent for a bare worker, or set it durably in the environment. -GBRAIN_NICE=10 gbrain jobs work --concurrency 4 +GBRAIN_NICE=10 gbrain jobs work --concurrency 2 ``` `--nice` takes a POSIX value from `-20` (highest priority) to `19` diff --git a/docs/guides/operational-disciplines.md b/docs/guides/operational-disciplines.md index 75012f56a..92749f65b 100644 --- a/docs/guides/operational-disciplines.md +++ b/docs/guides/operational-disciplines.md @@ -57,6 +57,9 @@ on daily_schedule("09:00"): # Checks: database connectivity, embedding health, sync status, # page count, stale pages, broken links # If doctor reports issues, fix them before doing anything else. + # Cadence: this daily heartbeat is intentional alongside the WEEKLY + # deep maintenance pass (doctor + embed --stale) in cron-schedule.md — + # heartbeat=daily, deep pass=weekly. # DISCIPLINE 5: Nightly Dream Cycle on nightly_schedule("02:00"): diff --git a/docs/guides/queue-operations-runbook.md b/docs/guides/queue-operations-runbook.md index 639cadee8..04d1c4380 100644 --- a/docs/guides/queue-operations-runbook.md +++ b/docs/guides/queue-operations-runbook.md @@ -98,7 +98,9 @@ If the list is empty AND your submissions keep piling up, no worker is claiming. Start one: ```bash -GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs work --concurrency 4 +# Bare default is --concurrency 1, which starves jobs that wait on their own +# subagent jobs — use 2 (the supervisor's default; see minions-deployment.md). +GBRAIN_ALLOW_SHELL_JOBS=1 gbrain jobs work --concurrency 2 ``` ## Follow-ups tracked for v0.20+ diff --git a/llms-full.txt b/llms-full.txt index 4de2b11e4..88d2a18c3 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -2910,7 +2910,9 @@ fixed. You wake up and the brain is smarter than when you went to sleep. # Calendar sync — Sundays at 10 AM 0 10 * * 0 cd /path/to/calendar-sync && node calendar-sync.mjs --start $(date -v-7d +%Y-%m-%d) --end $(date +%Y-%m-%d) -# Brain health — weekly Mondays at 6 AM +# Brain health — weekly DEEP pass, Mondays at 6 AM (doctor + embed backfill). +# This complements — does not replace — the DAILY `gbrain doctor` heartbeat +# from operational-disciplines.md Discipline 4: heartbeat=daily, deep pass=weekly. 0 6 * * 1 gbrain doctor --json >> /tmp/gbrain-health.log 2>&1 && gbrain embed --stale # Dream cycle — nightly at 2 AM diff --git a/src/commands/jobs.ts b/src/commands/jobs.ts index 31aa24e14..ed06836b1 100644 --- a/src/commands/jobs.ts +++ b/src/commands/jobs.ts @@ -253,7 +253,7 @@ USAGE 3 PID file unwritable (permission / path error) EXAMPLES - gbrain jobs supervisor --concurrency 4 # foreground (Ctrl-C stops) + gbrain jobs supervisor --concurrency 2 # foreground (Ctrl-C stops; 2 is the default) gbrain jobs supervisor start --detach --json # agent-friendly: fork + return JSON gbrain jobs supervisor status --json # machine-readable health check gbrain jobs supervisor stop # graceful stop