octostore

Coordinate agent work with OctoStore

Use OctoStore only when two or more independent processes might act on the same role or work item.

Choose exactly one primitive:

• Election — one live coordinator for a group. The hosted path needs no login.
• Lock — one temporary owner for one exact item. Locks require an authenticated hosted or self-hosted OctoStore.

Acquire authority before creating a branch, changing files, calling a side-effecting tool, deploying, or merging. Treat lost, uncertain, a missing response, or an unexpected hold-process exit as not owned. Stop issuing side effects and ask the supervisor to cancel or fence the worker.

First result: one shared hosted election

Create one room outside the candidates:

octostore election create --json

Take the returned election_id and pass the same ID to every candidate. Never let each candidate create its own room for the same role.

Each candidate provides an executable worker and starts the installed supervisor with a unique candidate ID:

octostore-supervisor election "$OCTOSTORE_ELECTION" "$AGENT_ID" "$AGENT_WORKER" -- \
  octostore election hold "$OCTOSTORE_ELECTION" \
    --candidate "$AGENT_ID" --ttl 30 \
    --acquire-timeout 60 --json

Set AGENT_WORKER to the protected executable before running this command. The supervisor starts it only after a leader event and does not publish terminal lifecycle output until group containment completes. A waiting event means another candidate leads. On lost, uncertain, malformed output, or unexpected exit, stop work immediately. A hold process never reacquires after it has lost authority; start a new supervised attempt only under host policy.

The hosted authority defaults to https://api.octostore.io. Use --server or OCTOSTORE_URL only when all candidates intentionally share another authority. Election hold receives a secret leader capability, so custom authorities must use HTTPS or loopback HTTP; only an explicitly approved development setup may use --allow-insecure-http.