/minion-orchestrator

name: minion-orchestrator
version: 1.1.0
description: |
  Unified Minions skill for both deterministic shell jobs and LLM subagent
  orchestration. Replaces the older `gbrain-jobs` routing intent. Use when:
  submitting gbrain jobs, shell/background tasks, spawning subagents,
  checking progress, steering running work, pausing/resuming, parallel
  fan-out. One durable, observable, steerable queue interface. Also carries
  the durable-execution doctrine for any operation expected to exceed ~2
  minutes: capability ladder, deadman checks that verify the result was
  reported, and content-addressed stage checkpoints for expensive pipelines.
triggers:
  - "gbrain jobs submit"
  - "submit a gbrain job"
  - "submit a shell job"
  - "shell job"
  - "run shell command in background"
  - "deterministic background task"
  - "spawn agent"
  - "background task"
  - "run in background"
  - "check on agent"
  - "agent progress"
  - "what's running"
  - "steer agent"
  - "change direction"
  - "tell the agent"
  - "pause agent"
  - "stop agent"
  - "resume agent"
  - "parallel tasks"
  - "fan out"
  - "do these in parallel"
  - "long operation"
  - "durable execution"
  - "arm a deadman"
  - "the job went silent"
  - "operation died in the background"
  - "make this pipeline resumable"
tools:
  - submit_job
  - get_job
  - list_jobs
  - cancel_job
  - pause_job
  - resume_job
  - replay_job
  - send_job_message
  - get_job_progress
mutating: true
upstream: long-ops@fc834ee, subagent-deadman@fc834ee, pipeline-stage-cache@fc834ee

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

Durable-execution doctrine (routing convention the agent follows — nothing mechanically enforces it; see "Durable execution" below):

• Operations expected to exceed ~2 minutes route through the capability

ladder, never a bare background shell that dies with the session.

• A deadman check verifies the result was REPORTED to the user, not merely

that the process exited — a swallowed completion event looks identical to a dead job from the user's side.

• The deadman is second-line insurance, not a delivery guarantee: it can

itself die before firing (scheduler restart, deleted entry). Backstop: on the next turn, sweep `gbrain jobs list --status active` and recent completions for overdue work whose result never reached the user.

• Deadman checks are idempotent. A double-fire, or a fire that races the

normal completion report, produces silence — it checks reported-state first and tags any recovery report with the job ID so duplicates are detectable.

• A checkpoint or progress file is trusted only with a freshness check.

A stale checkpoint reads as "still running" forever; compare its timestamp against the expected progress interval and against `gbrain jobs get <id>`.

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 | | Operation expected to exceed ~2 minutes | Route through the Durable execution ladder (below) | | 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)

• **The worker must be started with `gbrain jobs work --allow-shell-jobs`** (equivalently `GBRAIN_ALLOW_SHELL_JOBS=1` exported on the worker; a `.env` in the worker's directory cannot set it).

The shell handler is always registered but guarded: an unflagged worker that claims a shell job dead-letters it immediately (`UnrecoverableError`, straight to `dead`, no retries) with the flag named in `error_text`. A job that sits in `waiting` means NO worker is running at all — check `gbrain jobs supervisor status`. 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:**