KB: hivemind create non-commit quirk — silent non-persist

Symptom

hivemind create projects (or epics) returns with empty output and exit 0, but the row never lands in Postgres — no error, no {"spooled":true}. It looks like success; it is not. (Historic workaround: direct PG INSERT — no longer required.)

Root cause

Two silent gaps in scripts/agent/hivemind:

  1. call() only spooled an exactly-empty response ([[ -z "$resp" ]]). When Phoenix flaps (restart/recompile under multi-agent load) and the connection resets mid-flight, curl returns whitespace / a partial reply — not empty — so the spool branch is skipped and the blank reply prints as a "success" with exit 0.
  2. The create verb only checked for {"error":…}. A spooled write ({"spooled":true}) or a partial/no-id reply passed the error check → exit 0 → caller assumes it persisted.

Fix (shipped 2026-06-14, scripts/agent/hivemind)

  1. call() trims whitespace before the empty-test (tr -d '[:space:]') and spools any blank/partial write — never mistaking it for success.
  2. create adds a persistence guard: a real create must return a row id (.data.id). {"spooled":true} or no-id → loud ⚠ NOT PERSISTED + exit 7. Exit 0 + quiet only when a real id came back.

How to recognize / handle

  • Exit 7 + ⚠ NOT PERSISTED → the API was flapping; the write did NOT persist (may be spooled). Confirm Phoenix is up, re-run, and verify with hivemind get / search-all.
  • The spool (/tmp/hm_spool) auto-replays on the next reachable call (hivemind spool flush).
  • Net: a flap can no longer masquerade as a committed write.
  • ADR-0015 documentation:ahG9mKZHCg, ADR-0016 documentation:uqun6Cctgf.
  • Obsoletes the "CLI create projects silently non-persists → use direct PG INSERT" guidance. Direct INSERT remains a valid fallback, not a requirement.
© 2026 DRO Platform