viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions 1
beadboard/skills/beadboard-driver/references/failure-modes.md
zenchantlive 18fbafdce4 refactor: extract agent bounded context + fix SSE comments + cleanup unused 
- Extract src/lib/agent/ bounded context with types, registry, messaging
- Add comments_count to BeadIssue for SSE comment detection
- Create batch endpoints for mail/reservations APIs
- Add memory validation to session-preflight
- Remove unused empty dirs (mockup, sessions, timeline)
- Move stashes to docs/references, gitignore them
2026-03-04 22:06:40 -08:00

3.5 KiB
Raw Blame History

Failure Modes

This document tracks high-impact coordination and environment failures for the BeadBoard driver skill.

BD_NOT_FOUND

  • Signal: preflight or scripts fail with BD_NOT_FOUND.
  • Cause: bd is not installed or not on PATH.
  • Recovery:
    • Install beads CLI.
    • Re-open shell so PATH updates apply.
    • Re-run node skills/beadboard-driver/scripts/session-preflight.mjs.

BB_NOT_FOUND

  • Signal: session-preflight.mjs or bb-mail-shim.mjs reports bb command missing.
  • Cause: global BeadBoard CLI not installed, or not discoverable.
  • Recovery:
    • Install BeadBoard globally (bb/beadboard on PATH) — see Bootstrap Step C in SKILL.md.
    • Run node {baseDir}/scripts/setup-mail-delegate.mjs to reconfigure the mail delegate after bb is installed.
    • Re-run preflight: node {baseDir}/scripts/session-preflight.mjs.

MAIL_DELEGATE_MISSING / BD_MAIL_DELEGATE_NOT_SET

  • Signal: bd mail ... returns delegate-not-configured or shim not invoked.
  • Cause: neither env delegate (BEADS_MAIL_DELEGATE/BD_MAIL_DELEGATE) nor mail.delegate config is set.
  • Recovery:
    • bd config set mail.delegate "node <abs-path>/skills/beadboard-driver/scripts/bb-mail-shim.mjs"
    • export BB_AGENT=<agent-id>
    • node skills/beadboard-driver/scripts/ensure-bb-mail-configured.mjs

BB_MAIL_NOT_CONFIGURED

  • Signal: ensure-bb-mail-configured.mjs fails contract checks.
  • Cause: delegate points to wrong command, missing shim path, or invalid BB_AGENT context.
  • Recovery (in order):
    1. Check delegate is set: bd config get mail.delegate
    2. Verify shim path: the path shown must be absolute and the bb-mail-shim.mjs file must exist on disk
    3. Reconfigure if wrong/missing: node {baseDir}/scripts/setup-mail-delegate.mjs
    4. Verify BB_AGENT is set: echo $BB_AGENT (must be non-empty)
    5. Re-run verification: node {baseDir}/scripts/ensure-bb-mail-configured.mjs — expected: ok: true

DOLT_NOT_RUNNING

  • Signal: bd reads stale/fallback data, API routes return Dolt connection failures, or status checks report backend unavailable.
  • Cause: Dolt SQL server not started for this workspace.
  • Recovery:
    • From repo root: bd dolt start
    • Verify backend health before proceeding (beadboard status --json or project-specific health checks).

AGENT_HEARTBEAT_MISSED (Witness liveness degradation)

  • Signal: agent appears stale/dead in liveness surfaces after inactivity window.
  • Cause: agent is not sending bd agent heartbeat <agent-bead-id> during active work.
  • Recovery:
    • Resume periodic heartbeat (typically every 30-120 seconds while active).
    • Set explicit state transitions: running -> working -> stuck|done|stopped.
    • If work was interrupted, post a coordination note/message before resuming.

Mail Lifecycle Errors

  • UNKNOWN_SENDER / UNKNOWN_RECIPIENT: register agent identities before sending.
  • MESSAGE_NOT_FOUND: incorrect message id or wrong inbox context.
  • ACK_FORBIDDEN: only the message recipient can acknowledge.

Local Workspace Repair Signals

  • GIT_INDEX_LOCK_PRESENT: stale git lock blocks writes.
  • Recovery:
    • Confirm no active git process is still using the repo.
    • Run node skills/beadboard-driver/scripts/heal-common-issues.mjs --project-root <repo> --apply --fix-git-index-lock.

Policy Guardrails

  • Do not write .beads/issues.jsonl directly.
  • Do not close beads without fresh evidence.
  • Do not bypass a misconfigured mail delegate; fix configuration with {baseDir}/scripts/setup-mail-delegate.mjs first.