Skip to main content

​
Minions fix — repairing a half-migrated install

tl;dr: on v0.11.1+ everything should self-heal. If Minions is partially set up (no ~/.modusbrain/preferences.json, autopilot still inline, cron jobs still on agentTurn), run:
It’s idempotent. On v0.11.1 installs that already migrated it’s a cheap no-op.

​
Context

v0.11.0 shipped the Minions schema, queue, worker, and migration skill — but the migration skill itself never fired on upgrade. runPostUpgrade printed the feature pitch and stopped. v0.11.0 was never released publicly; v0.11.1 is the first public Minions ship and fixes the mega-bug (migration fires automatically on modusbrain upgrade and via the postinstall hook). If you’re on a pre-v0.11.1 branch build (e.g. running the minions-jobs branch before v0.11.1 tagged), Minions may be installed but not wired: schema is v7, but no ~/.modusbrain/preferences.json, autopilot still runs inline, cron jobs still call agentTurn. This guide covers both paths: the canonical v0.11.1+ fix, and the stopgap for pre-v0.11.1 binaries that don’t have apply-migrations.

​
Detecting the half-migrated state

If the install is half-migrated, you’ll see:
or
For a machine-readable report (cron-friendly):

​
The fix (v0.11.1 or later)

Reads ~/.modusbrain/migrations/completed.jsonl, diffs against the TS migration registry, runs whatever’s pending. Seven phases:
If Phase E emits TODOs for host-specific handlers (e.g. your OpenClaw’s ~29 non-modusbrain crons), the migration finishes with status: "partial". Your host agent walks the TODOs using skills/migrations/v0.11.0.md + docs/guides/plugin-handlers.md, ships handler registrations in the host repo, then re-runs modusbrain apply-migrations --yes. Newly registerable cron entries get rewritten and the JSONL rows mark status: "complete".

​
The stopgap (pre-v0.11.1 binary, no apply-migrations yet)

If you’re stuck on a branch build that doesn’t have apply-migrations:
This bash script does what apply-migrations does from a shell environment:
  1. modusbrain init --migrate-only — schema v7.
  2. modusbrain jobs smoke — verify Minions health.
  3. Prompt for minion_mode (defaults pain_triggered on non-TTY).
  4. Write ~/.modusbrain/preferences.json atomically.
  5. Append ~/.modusbrain/migrations/completed.jsonl with status: "partial" and apply_migrations_pending: true. That partial record is the signal to v0.11.1’s apply-migrations to pick up remaining phases after the user upgrades.
  6. Detect host agent repos and PRINT rewrite instructions (never auto-edits from a curl-piped script).
  7. Print the next step: Run: modusbrain autopilot --install.
Once v0.11.1 is installed, re-run modusbrain apply-migrations --yes to finish the remaining phases (host rewrites + autopilot install). The stopgap’s status: "partial" record is designed to resume cleanly (it doesn’t poison the permanent migration path).

​
Verify the fix landed

​
If the fix fails

Each phase is idempotent. Re-running is safe. Common failure modes:
  • Phase B smoke fails: the schema didn’t apply. Check ~/.modusbrain/config.json has a valid database_url (or database_path for PGLite). Run modusbrain init --migrate-only directly and look at the error.
  • Phase F install fails: your host environment doesn’t match any detected target. Pass --target <macos|linux-systemd|ephemeral-container|linux-cron> explicitly.
  • Pending host work never clears: your host agent hasn’t shipped handler registrations yet. Read ~/.modusbrain/migrations/pending-host-work.jsonl, open skills/migrations/v0.11.0.md, and follow the host-agent instruction manual.
  • skills/migrations/v0.11.0.md — full migration skill for host agents.
  • skills/skillpack-check/SKILL.md — when and how to run the health check.
  • docs/guides/plugin-handlers.md — plugin contract for host-specific handlers.
  • skills/conventions/cron-via-minions.md — the canonical cron rewrite pattern.