18fbafdce4
- 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
77 lines
3.5 KiB
Markdown
77 lines
3.5 KiB
Markdown
# 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.
|