Beads doesn't work in the sandbox out of box

[rkern]

I've tried setting up a simple git repo with Beads (1.0.3, plain bd init, auto-export enabled as default) and Sandcastle (0.5.8, simple-loop). It does not appear that the Beads database is available to the workers.

  Sandbox: docker
  Max iterations: 3
  Branch: sandcastle/worker/20260506-200112
Iteration 1/3
Copying to worktree...
Copying to worktree done (0.2s)
Setting up sandbox
  npm install
Setting up sandbox done (0.8s)
Expanding shell expressions
Failed to resolve prompt: Command `bd ready --json` exited with code 1: Error: no beads database found
Hint: run 'bd where' to inspect the resolved workspace, or 'bd init' to create a new database
      or set BEADS_DIR to point to your .beads directory

Is there a worked example for setting up Sandcastle with Beads, end-to-end? Is there more setup to do (like a hook to reconstruct the Dolt database in the worktree)? I'm iterating on workarounds, but it's getting involved. It seems to me that either there's a lot more ceremony around exporting/importing .beads/issues.jsonl between host and worker or setting up the worker container to network out back to the host to access the Dolt server.

Thank you!

[AustinHellerRepo]

Do we need to have the worktree set up to point to a volume that contains the parent scope's beads database? I'm still trying to get this working myself.

[rkern]

AFAICT, you don't want to use embedded-mode Dolt with multiple concurrent writers, so simply sharing the same files across containers is not advised. I believe that you're supposed to run the Dolt server and point all of the containers to it.

[rkern]

FWIW, here's the outline of how I got Beads working:

• I have to install Beads in --stealth mode to avoid having to deal with having the git-tracked .beads/ files appearing as modified in my root checkout. This would interfere with the final merging in parallel-planner-with-review workflow that I want to use.
• Beads must be in --server mode rather than the default embedded mode. In main.mts, I run bd dolt start to ensure the Dolt server is running, and I capture the port to pass to the sandbox containers. I have to set the Docker instance's network mode to host to be able to share the port directly (I suspect a Docker compose provider might give me more options to avoid that).
• I have to copy over the .beads/metadata.json file over to the containers so they know how to access the Dolt server. Because copyToWorktree does not make parent directories (I want just .beads/metadata.json, not the entire .beads/ directory), I have to do this with an onWorktreeReady shell command.
• CLOSE_TASK_COMMAND for Beads is wrong. The reason is provided by an option flag, not a positional argument: bd close <ID> --reason="Completed by Sandcastle"

async function ensureDoltServer(): Promise<{ port: number }> {
  // `bd dolt start` is idempotent: already-running server exits 0.
  await execFileAsync("bd", ["dolt", "start"]);
  const { stdout } = await execFileAsync("bd", ["dolt", "status", "--json"]);
  const status = JSON.parse(stdout) as { port: number; running: boolean };
  if (!status.running) {
    throw new Error(`bd dolt status reports server not running: ${stdout}`);
  }
  return { port: status.port };
}

const { port: doltPort } = await ensureDoltServer();
console.log(`Dolt server ready on 127.0.0.1:${doltPort}`);

const sb = () =>
  docker({
    network: "host",
    env: { BEADS_DOLT_SERVER_PORT: String(doltPort) },
  });

const workerHooks = {
  host: {
    onWorktreeReady: [
      {
        command:
          'mkdir -p .beads && ' +
          'cp "$(git rev-parse --git-common-dir)/../.beads/metadata.json" ' +
          '.beads/metadata.json',
      },
    ],
  },
  sandbox: sandboxHooks,
};

[rkern]

Oh, the current release Beads 1.0.4 is buggy, so I had to use 1.0.3.