beads tracker: `getNextTask` silently returns `no_tasks` when tracker data lives outside the cwd

[seniorquico]

System Information

ralph-tui: 0.12.0
runtime: bun 1.3.14
os: win32 10.0.26200 (x64)
agent: opencode v1.17.15
tracker: beads
global-config: yes
project-config: no
templates: beads-bv.hbs, beads-rust-bv.hbs, beads-rust.hbs, beads.hbs, default.hbs, jira.hbs, json.hbs
bundled-skills: 4
skills-installed: claude:0, opencode:0, droid:0, gemini:0, codex:0, kiro:0, cursor:0, github-copilot:0, kimi:0, pi:0

Steps to reproduce

Setup:

• bd 1.1.0 with a Dolt-server backend, located via the BEADS_DIR env var.
• The working directory has NO local .beads/ directory (tracker data is on the
  Dolt server, not in the repo/worktree).
• A global ~/.config/ralph-tui/config.toml (below); no project .ralph-tui/config.toml.
• An epic with two open child tasks.

1. From the working directory, confirm bd resolves ready work via BEADS_DIR:

   $ bd ready --parent <epic-id> --json
   # -> returns both open child tasks (see logs)

2. Run ralph-tui headless, scoped to the epic, from that same directory:

   $ ralph-tui run --epic <epic-id> --cwd /path/to/workdir --headless --no-setup --iterations 0 --serial

Expected:

Ralph selects a ready task and runs an iteration (bd shows the tasks as ready from the same cwd/env).

Actual:

Ralph resolves the epic and reports "Total tasks: 2", then immediately stops with reason "no_tasks" and 0 iterations. No task is ever selected.

Root cause (source @ commit 8191b80):

In src/plugins/trackers/builtin/beads/index.ts, getNextTask() starts with if (!(await this.isReady())) return undefined;. isReady() -> detect() requires access(join(this.workingDir, this.beadsDir /* ".beads" */), R_OK), i.e. a local <cwd>/.beads directory. With BEADS_DIR set there is no local .beads/, so detect() returns available:false and getNextTask() returns undefined (with no log). getTasks() and getEpics() do NOT call isReady(), so enumeration works while selection silently yields nothing — hence "Total tasks: 2" followed by "no_tasks". The engine (src/engine/index.ts) emits reason "no_tasks" when getNextTask returns null.

Relevant logs / terminal output

### ralph-tui run (headless):


Epic: <epic-id>
[INFO] [session] Session <session-id> created. Agent: opencode, Tracker: beads
[INFO] [engine] Ralph started. Total tasks: 2
[INFO] [engine] Ralph stopped. Reason: no_tasks. Iterations: 0, Tasks completed: 0
[INFO] [engine] Ralph stopped. Reason: interrupted. Iterations: 0, Tasks completed: 0
  Tasks: 0/2 completed


### .ralph-tui/session.json shows both tasks WERE loaded (so the tracker resolved):


"trackerState": {
  "plugin": "beads",
  "epicId": "<epic-id>",
  "totalTasks": 2,
  "tasks": [
    { "id": "<epic-id>.1", "title": "…", "status": "open", "completedInSession": false },
    { "id": "<epic-id>.2", "title": "…", "status": "open", "completedInSession": false }
  ]
}


### For contrast, `bd ready` from the SAME cwd + env returns those tasks:


$ bd ready --parent <epic-id> --json
[
  { "id": "<epic-id>.1", "status": "open", "issue_type": "task", ... },
  { "id": "<epic-id>.2", "status": "open", "issue_type": "task", ... }
]

Configuration (if relevant)

agent = "opencode"
tracker = "beads"
configVersion = "2.1"
maxIterations = 10
autoCommit = true

[agentOptions]
provider = "<provider>"
model = "<model>"
variant = "<variant>"

Additional context

• Inconsistency: getNextTask() gates on isReady(); getTasks()/getEpics() do not. Same tracker, same run — enumeration works, selection doesn't.
• Silent failure: the isReady() false path is an unlogged return undefined, while the other getNextTask failure branches (non-zero exit, JSON parse error) do log. So the one path that trips a valid config emits no diagnostics.
• Wrong readiness signal: bd is explicitly designed to locate its tracker outside the cwd via BEADS_DIR (and --db). detect() using filesystem presence of <cwd>/.beads rejects a configuration that bd fully supports.
• The adapter has a beadsDir config option, but detect() does join(workingDir, beadsDir), so pointing it at an absolute/external path doesn't work.

Suggested fixes (any one):

1. In detect(), treat BEADS_DIR / an absolute beadsDir / a configured --db as sufficient (don't join those with cwd).
2. Drop the isReady() gate in getNextTask for parity with getTasks/getEpics (let bd be the source of truth).

Workaround (works today): create an empty <cwd>/.beads/ directory. It satisfies detect() and does NOT shadow the Dolt server — with BEADS_DIR set, bd still uses the server even when an empty local .beads is present.

Why it matters: this blocks using ralph-tui with a shared/remote beads (Dolt) tracker that lives independently of each git repo/worktree — a setup that avoids committing tracker files into repos you don't own.

[djbclark]

Thanks for filing this and doing the legwork on root-causing it, @seniorquico — the diagnosis matches what I found reading getNextTask()/detect()/isReady() in src/plugins/trackers/builtin/beads/index.ts myself: detect() only does access(join(workingDir, beadsDir), R_OK), so it never inspects contents, which is exactly why an empty local .beads/ placeholder should satisfy the readiness check while bd/bv still resolve the real store via BEADS_DIR (tracker spawns pass the full unfiltered env, per execCommand()). Planning to lean on that workaround myself, so wanted to add a data point and a vote.

My use case: orchestrating a handful of independent git repos (a mix of personal ops tooling and an Android app fork) with one shared Beads DB as a control-plane for cross-repo task routing, run as one Ralph "controller" instance per repo (since Ralph's cwd/lock/worktree-manager/merge-queue are all correctly single-repo — not asking for that to change) but with each controller's tracker pointed at the shared DB via BEADS_DIR/an external workingDir, not a repo-local one. Hit exactly this silent-no_tasks behavior working through that setup.

+1 for whichever of your two suggested fixes is less invasive — treating a configured BEADS_DIR/absolute beadsDir/--db as sufficient without requiring the local join, or dropping the isReady() gate in getNextTask for parity with getTasks/getEpics. More broadly, external/shared Beads stores for multi-repo task routing feels like it'd be a genuinely useful first-class capability rather than something each user has to work around individually — happy to help test if a fix lands.

[djbclark]

Follow-up with something that might save others a step: while actually wiring this up (multi-repo setup, one shared external Beads store), I found there's a cleaner path than the BEADS_DIR + empty-placeholder workaround for this specific case — set trackers[].options.workingDir directly to the external store's absolute path in config.toml, rather than relying on BEADS_DIR + an implicit local .beads/.

Confirmed in source (src/plugins/trackers/builtin/beads-bv/index.ts): getWorkingDir() returns this.config.workingDir when set, and detect()'s readiness check is access(join(getWorkingDir(), beadsDir)) — so pointing workingDir at the real external store makes that check pass against the actual directory, with no local placeholder needed at all:

[[trackers]]
name = "beads-bv"
plugin = "beads-bv"

  [trackers.options]
  workingDir = "/absolute/path/to/external/.beads-parent-dir"
  beadsDir = ".beads"

This doesn't fix the underlying bug for the BEADS_DIR-env-var case (which is still real and still worth fixing per the two suggestions above), but if anyone else hits this via an external/shared store rather than a Dolt-server backend specifically, workingDir is a no-workaround-needed option that was already there, just not obviously the fix for this symptom.