foreman harness for Grok Bot crews

foreman is an open-source command-line harness for hosted Grok Bot crews, published under the Archive228 GitHub account. Crews are declared in git and reconciled against gbot --json, with a single write path to the account and shift reports that avoid inventing numbers such as cost.

What It Is

Grok Bot is a hosted product, and the README notes that it has no dry run, no per-bot spend data, no rollback after an approval, and one shared VM for every bot on an account. foreman adds an owned layer on top: a read-only board, a pinned spec file, declared grants, and a hash-chained audit log. It requires Node 18+ and an authenticated gbot on the PATH for live collection, and has zero runtime dependencies.

The board and indicators

foreman board serves a read-only page on loopback showing one card per bot, ordered worst state first: waiting on you, stopped mid-task, repeating itself, went quiet, age unknown, then no indicator fired. Clicking a card shows the detections and the transcript path behind it. The shift report uses twelve transcript-derived indicators, including stall, loop, silent bot, handoff drop, roster drift, unverified claim, VM collision and silent routine. Each is documented with what it is not proof of. Token counts and dollar costs are deliberately not reported because Grok Bot does not expose them.

Spec-gated completion

Each spec.json entry is pinned with a hash over category, description, steps and prerequisites. foreman dispatch requires --spec <id> or an explicit --no-spec, which writes a spec-waived audit row. foreman spec pass succeeds only when a bound run has an approve verdict from a checker that is not the worker. Partial verdicts, where verification failed open, and needs-attention verdicts are refused.

Grants, exposure and audit

Grants record what each bot is meant to reach, using references such as env:, file:, keychain: or op:// and never raw secrets. foreman exposure prints the gap between declared grants and the shared VM. foreman gate returns allowed, held or denied as an advisory decision. Every grant, revoke and gate decision is appended to data/audit.jsonl, and foreman audit --verify names the first altered row.

Crew changes

foreman sync plan and apply form the only write path to hosted bots and groups. crew status parses cron schedules and shows the next run for each routine. pack add fetches, scans and pins packs, and pack deploy --trust materializes them into the repo.