Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
4.9 KB
Raw Blame

Exit codes

Every gbrain command exits with one of these statuses. An agent branches on the exit code first, then reads the JSON document (--json) for the details: code, class, retryable and fix. The protocol page is AGENT_OPERATOR_v1; error codes are listed in error codes.

Say to your agent: "The gbrain command exited 3. What does it need from me?"

Exit Meaning --json document What the agent does
0 ok the result continue
1 failed error envelope with class and retryable follow fix.next; retry only when retryable is true
2 usage error or invalid input error envelope (invalid_params, unknown_flag) correct the command; gbrain <command> --help
3 confirmation_required: nothing ran consent payload (effects, user_message, fix) stop, relay user_message to the user, run fix.command only after they agree
10 the write was accepted and is still pending write receipt poll the receipt (gbrain write-request -- <id>); --accept-pending maps this to 0, except a receipt whose diagnostic.owner names a stale owner (stale owner)
11 partial, resumable budget stop result with remaining_* and resume_command run resume_command (it is safe to re-run)
12 no_results: gbrain recall (an entity, text, --grep, --question or --query lookup) or gbrain entity matched nothing. Opt-in: only with GBRAIN_FAIL_ON_EMPTY=1; otherwise a miss exits 0 recall's list output: status: "no_results"; entity: found: false treat it as a miss, not a failure; a script that filters stdout can branch on it
13 pending_verify: gbrain bootstrap harness --token wired a PGLite brain while no serve answered; nothing failed, nothing verified yet the harness result with status: "pending_verify" and fix tell the user to start gbrain serve --http, then run fix.command with the same token; bootstrap harness --status stays partial until it passes (pending verify)
14 bootstrap_cleanup_pending: gbrain bootstrap harness (or --status) wired and verified the harness, but earlier shared-skills enrollments or carried token ids are not cleaned up yet the harness result with status: "cleanup_pending", a per-id cleanup list and fix follow fix.next: run re-runs the same command; tell_user_to_run relays the owner's revoke or restore step, then re-run (cleanup pending)
15 gbrain get --as-of: no edition in force on that date the result with valid_time read status and why; quote nothing as in force (valid time)
16 host_upgrade_required: the host is too old to read by date; nothing printed error envelope relay gbrain upgrade on the brain host (details)
17 doctor_alert_act: gbrain doctor --alert found a page-class check that needs someone now (database, writes, migrations, builds, sync or maintenance stalls, corrupt rows, schema exposure, paid-loop breaker) the doctor report; alert.level: "act", alert.items with each check's fix follow each item's fix.next (doctor alert)
18 doctor_alert_unknown: gbrain doctor --alert found nothing to act on, but at least one page-class check did not run fresh (budget, error, last known result, tier) the doctor report; alert.level: "unknown", alert.unknown naming each check, its budget and a fix, and alert.consecutive_unknown run each fix; an agent cron pages only from the second unknown run in a row (doctor alert)
69 gbrain serve exited on its own after its persistence consumer reported restart_required for GBRAIN_SERVE_RESTART_REQUIRED_EXIT_SECONDS (serve_unhealthy_exit; opt-in) [gbrain serve] error code=serve_unhealthy_exit line on stderr nothing: the supervisor (the installed service restarts on failure) starts a fresh serve; if it repeats, follow the unhealthy exit
75 another runner holds the migration lock, or an engine graduation owns the brain (graduation_in_progress) error envelope wait for the other runner, then retry
124 the command's own deadline elapsed error envelope inspect what is still running (the message names the status command)
130 interrupted (SIGINT) error envelope ask the user whether to re-run

class and retryable live only in the JSON document; the exit code stays coarse so shell scripts can branch on it.

Under contract v1, gbrain mcp expose and gbrain google exit 2 when they need the user's confirmation (documented legacy; changing it is a v2 item).

The per-command exit changes that came with contract v1 (v0.60.46.0) are in the CHANGELOG.