Known Limitations

Honest documentation of known constraints, their practical impact, and our plans to address them.

Agent Communication Latency

What	Commands sent to running agents are delivered via file-based signal polling with up to 60-second delay.
Impact	When you issue a broadcast command or stop signal, agents may not respond for up to a minute. Work in progress during that window continues unsupervised.
Workaround	Use bernstein stop which writes SHUTDOWN signals and waits up to 30s. For immediate termination: bernstein stop --force.
Plan	Replace file polling with stdin pipe IPC for supported adapters (Claude Code first). Target: sub-2-second command delivery.

Single-Machine Orchestration

What	Bernstein currently runs on a single machine. All agents, the task server, and the orchestrator share one host.
Impact	Parallelism is bounded by local CPU, memory, and API rate limits. For 50+ tasks, a single machine may bottleneck.
Workaround	Increase --max-agents cautiously (default: 6). Most workflows complete well within single-machine capacity.
Plan	Distributed cluster mode with multi-node orchestration, worker heartbeats, and task stealing.

Rate Limit Detection is Reactive

What	Bernstein detects rate limits by scanning agent logs for 429 patterns after the agent fails. It cannot predict limits before they occur.
Impact	The first task on a rate-limited provider will fail before cascading to alternatives. One task’s worth of time and tokens is lost.
Workaround	Set conservative --budget limits. The cascade fallback system automatically reassigns subsequent tasks to other available agents.
Plan	Investigating adapter-level quota detection via provider APIs where available.

Context Window Boundaries

What	Each agent spawns fresh with no memory of previous tasks. Context is limited to the system prompt, task description, and relevant file content.
Impact	Agents cannot reference decisions from earlier tasks. Related tasks may produce inconsistent approaches.
Workaround	Write detailed task descriptions with relevant context. Use depends_on to order tasks so later agents see earlier commits.
Plan	Context compression engine and cross-session knowledge propagation.

No Real-Time Progress Streaming

What	Agent progress is observed via log files, not real-time streaming. The TUI dashboard reads logs on a polling interval.
Impact	Brief delay between an agent completing work and the dashboard reflecting it.
Workaround	Use bernstein logs -f <task-id> for near-real-time log tailing.
Plan	Agent heartbeat frequency improvements and event-driven TUI updates.

Verification Depends on Test Quality

What	The janitor verifies output by running tests and linting. If the project has poor test coverage, verification is weaker.
Impact	On low-coverage projects, the janitor may mark tasks “done” even when the implementation has subtle bugs.
Workaround	Ensure reasonable test coverage before running Bernstein. Add completion_signals to bernstein.yaml with specific verification commands.
Plan	Mutation testing validation to verify tests actually catch bugs, not just achieve coverage.

File-Based State Storage

What	All state lives in .sdd/ as flat files. No database.
Impact	Concurrent access is coordinated via file locks but is less robust than a database. Very large backlogs (1000+ tasks) may experience slower reads.
Workaround	This is deliberate — simpler, more portable, no infrastructure. Works well for most projects.
Plan	Optional database adapter for Bernstein Cloud. File-based remains the default for self-hosted.

Budget Estimation is Approximate

What	Cost estimates are based on token count projections, which can vary 2-3x from actual usage.
Impact	Pre-execution cost projections may be significantly off for complex tasks where agents iterate.
Workaround	Always set a --budget cap. Budget enforcement is exact — it tracks actual spend and stops at the limit.
Plan	ML-based cost prediction using historical task data.

Last updated: 2026-03-30