minion-orchestrator

Minion Orchestrator

Contract

Minions is a Postgres-native job queue for durable, observable background work. This single skill handles two lanes:

• Deterministic shell jobs (gbrain jobs submit shell ...)
• LLM subagent jobs (gbrain agent run ...)

When to route to Minions: durable, observable work that must survive restarts, fan out across many parallel tasks, or persist across sessions. Routing policy is defined in skills/conventions/subagent-routing.md — the project default is pain_triggered (native subagents first, Minions after specific pain signals fire); Mode A (all-through-Minions) is opt-in.

Guarantees:

• Jobs survive gateway restart (Postgres-backed)
• Every job has structured progress, token accounting, and session transcripts
• Running agents can be steered mid-flight via inbox messages
• Jobs can be paused, resumed, or cancelled at any time
• Parent-child DAGs with configurable failure policies

Route the Request: Shell Job vs Subagent

Condition	Action
User asks for deterministic command/script run	Shell job (CLI: gbrain jobs submit shell ...)
User asks to "run in minions" + explicit command/argv	Shell job (CLI, --params with cmd or argv)
User asks for research/reasoning/iterative agent	Subagent job (CLI: gbrain agent run)
User asks to steer/pause/resume an agent	Subagent job lifecycle tools (MCP-callable)
Single simple operation under ~30s	Consider inline execution first
Needs restart durability/observability	Submit as Minion job
Parallel work (2+ streams)	gbrain agent run --fanout-manifest or parent + child subagents

If intent is ambiguous, ask one clarification: "Do you want a deterministic shell command job, or an LLM agent job?"

Shell Jobs (Deterministic Scripts)

Use for reproducible command execution, ETL steps, cron work, and scriptable tasks where no LLM reasoning loop is needed.

Preconditions (read before submitting your first shell job)

• GBRAIN_ALLOW_SHELL_JOBS=1 must be set on the worker environment. Without it, the shell handler refuses to register and submissions sit in waiting silently. Gate lives in src/core/minions/handlers/shell.ts.
• Security: flipping GBRAIN_ALLOW_SHELL_JOBS=1 authorizes arbitrary command execution on the worker. On a shared queue, this is a remote code execution surface. Treat as privileged infrastructure authorization.
• Execution mode — pick one:
  • Postgres + daemon: gbrain jobs work runs a persistent worker that claims and executes jobs from the queue.
  • PGLite + --follow: gbrain jobs submit ... --follow runs inline. The daemon mode is not available on PGLite (exclusive file lock). See docs/guides/minions-shell-jobs.md.
• MCP boundary: shell-job submission is CLI-only. submit_job name="shell" over MCP throws an OperationError with code permission_denied ("'shell' jobs cannot be submitted over MCP") because shell is in PROTECTED_JOB_NAMES. Agents CAN observe shell jobs via get_job / list_jobs / get_job_progress (not protected), but cannot submit them. Operator or autopilot submits; agent observes.
• Verify setup: after configuration, run gbrain jobs stats (CLI) to confirm the worker is registered and consuming the queue.