[bug] beads-ui background polling contends for embedded Dolt lock and breaks concurrent bd workflows

[luketych]

Summary

When beads-ui is running against a project that uses the default embedded Dolt backend, the UI's background polling appears to spawn frequent
bd --sandbox ... subprocesses that acquire the embedded lock often enough to break concurrent bd usage from another tool/process.

I first noticed this because a Pi / Luke Wiggum loop could not advance with luke_wiggum_done, but the root issue seems more general: beads-ui
polling and another bd client contend for the same embedded lock.

Environment

• beads-ui: 0.12.0
• bd: 1.0.0 (Homebrew)
• macOS: 15.6 (24G84)
• Node: v25.8.2
• backend mode: embedded Dolt
• project was initialized with normal embedded mode (bd init, not server mode)

Actual behavior

While beads-ui is open/running, concurrent bd commands from another process intermittently fail with:

failed to open database: embeddeddolt: another process holds the exclusive lock on .../.beads/embeddeddolt; the embedded backend supports only one
writer at a time — use the dolt server backend for concurrent access

What I observed

While the failure was happening, I monitored the lock file and saw two sources acquiring it:

1. My active workflow process running commands like:

  bd show ... --json
  bd children ... --json
  bd ready ... --json

2. beads-ui running background polling commands like:

  bd --sandbox ready --limit 1000 --json
  bd --sandbox list --json --tree=false --status in_progress
  bd --sandbox list --json --tree=false --status closed --limit 1000

So it looks like beads-ui polling is contending with another active bd client in embedded mode.

Expected behavior

Ideally, running beads-ui should not make embedded-mode bd usage fail for another active client/process.

At minimum, it would help if beads-ui either:

• used a less lock-heavy polling strategy in embedded mode,
• backed off/retried more gracefully,
• or clearly documented that embedded mode is effectively single-client while the UI is open.

[luketych]

Lock monitor script

This is the exact script I used to sample lock holders:

  cat >/tmp/lockmon.py <<'PY'
  import subprocess, time

  lock = '/ABSOLUTE/PATH/TO/PROJECT/.beads/embeddeddolt/.lock'
  out = '/tmp/lockmon.log'
  end = time.time() + 20

  with open(out, 'w') as f:
      while time.time() < end:
          try:
              pids = subprocess.check_output(
                  ['lsof', '-t', lock],
                  text=True,
                  stderr=subprocess.DEVNULL
              ).strip().split()
          except subprocess.CalledProcessError:
              pids = []

          if pids:
              for pid in pids:
                  try:
                      ps = subprocess.check_output(
                          ['ps', '-p', pid, '-o', 'pid=,ppid=,pgid=,stat=,etime=,command='],
                          text=True,
                          stderr=subprocess.DEVNULL
                      ).strip()
                  except subprocess.CalledProcessError:
                      ps = '(ps miss)'

                  f.write(f'{time.time():.3f}\tPID={pid}\t{ps}\n')
                  f.flush()

          time.sleep(0.05)
  PY

  nohup python3 /tmp/lockmon.py >/tmp/lockmon.nohup 2>&1 &

Then I triggered the failing workflow and inspected:

  sed -n '1,200p' /tmp/lockmon.log

A second version that groups simultaneous holders into one line:

  cat >/tmp/lockmon2.py <<'PY'
  import subprocess, time

  lock = '/ABSOLUTE/PATH/TO/PROJECT/.beads/embeddeddolt/.lock'
  out = '/tmp/lockmon2.log'
  end = time.time() + 15

  with open(out, 'w') as f:
      while time.time() < end:
          try:
              pids = subprocess.check_output(
                  ['lsof', '-t', lock],
                  text=True,
                  stderr=subprocess.DEVNULL
              ).strip().split()
          except subprocess.CalledProcessError:
              pids = []

          if pids:
              line = [f'{time.time():.4f}', 'holders=' + ','.join(pids)]
              for pid in pids:
                  try:
                      ps = subprocess.check_output(
                          ['ps', '-p', pid, '-o', 'pid=,ppid=,stat=,etime=,command='],
                          text=True,
                          stderr=subprocess.DEVNULL
                      ).strip()
                  except subprocess.CalledProcessError:
                      ps = '(ps miss)'
                  line.append(ps)

              f.write(' || '.join(line) + '\n')
              f.flush()

          time.sleep(0.02)
  PY

  nohup python3 /tmp/lockmon2.py >/tmp/lockmon2.nohup 2>&1 &

Then inspect:

  sed -n '1,200p' /tmp/lockmon2.log