steerdev 1.1.6__tar.gz → 1.1.14__tar.gz

{steerdev-1.1.6 → steerdev-1.1.14}/.github/workflows/publish.yml

@@ -1,6 +1,9 @@
 name: Publish to PyPI
 
 on:
+  push:
+    branches:
+      - main
   workflow_dispatch:
 
 permissions:

{steerdev-1.1.6 → steerdev-1.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: steerdev
-Version: 1.1.6
+Version: 1.1.14
 Summary: Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting
 Project-URL: Homepage, https://github.com/pentoai/steerdev-agent
 Project-URL: Repository, https://github.com/pentoai/steerdev-agent

steerdev-1.1.14/docs/superpowers/plans/2026-06-05-wave-id-implies-unlimited-max-tasks.md

@@ -0,0 +1,253 @@
+# `--wave-id` implies unlimited `--max-tasks` — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Make `steerdev run --wave-id X` (with no `--max-tasks`) process the whole wave, while keeping every other `--max-tasks` case unchanged.
+
+**Architecture:** Make the `--max-tasks` CLI option nullable (`None` = unspecified), add a pure `resolve_max_tasks(max_tasks, wave_id)` helper in `runner.py` that returns the effective int (unspecified + wave → 0/unlimited; unspecified + no wave → 1; explicit value always honored), and use it in `cli.py:run` for both the `run_agent(...)` call and the "Max Tasks" banner. `AgentRunner`/`run_agent` are unchanged (still take a concrete int, `0` = unlimited).
+
+**Tech Stack:** Python 3.12, Typer CLI, pytest, uv. Lint/format: ruff. Type check: basedpyright. (Repo pre-commit runs ruff + basedpyright + an auto version bump.)
+
+**Spec:** `docs/superpowers/specs/2026-06-05-wave-id-implies-unlimited-max-tasks-design.md`
+**Branch:** `feat/wave-id-implies-unlimited` (already created; the spec is committed there).
+
+---
+
+## File Structure
+
+- `src/steerdev_agent/runner.py` — add pure `resolve_max_tasks(max_tasks: int | None, wave_id: str | None) -> int` next to the other pure resolvers (`resolve_merge_flow` is at ~line 139). One clear responsibility: resolve the effective max-tasks. No I/O.
+- `src/steerdev_agent/cli.py` — in the `run` command: change the `--max-tasks` option to `int | None = None`, call `resolve_max_tasks` to get `resolved_max_tasks`, and use it for both the `max_tasks_display` banner (~line 1824) and the `max_tasks=` argument to `run_agent` (~line 1875).
+- `tests/test_resolve_max_tasks.py` — new pure unit tests for `resolve_max_tasks`.
+
+---
+
+## Task 1: Pure `resolve_max_tasks` helper (TDD)
+
+**Files:**
+- Modify: `src/steerdev_agent/runner.py` (add the function near `resolve_merge_flow`, ~line 139)
+- Test: `tests/test_resolve_max_tasks.py` (new)
+
+- [ ] **Step 1: Write the failing test**
+
+Create `tests/test_resolve_max_tasks.py` with exactly:
+
+```python
+"""Tests for resolve_max_tasks: --wave-id implies unlimited when --max-tasks is unset."""
+
+from steerdev_agent.runner import resolve_max_tasks
+
+
+def test_unspecified_with_wave_is_unlimited():
+    # Bare `steerdev run --wave-id X` → pull the whole wave (0 = unlimited).
+    assert resolve_max_tasks(None, "wave-1") == 0
+
+
+def test_unspecified_without_wave_is_one():
+    # Historical single-task default is preserved.
+    assert resolve_max_tasks(None, None) == 1
+
+
+def test_explicit_zero_is_honored_with_wave():
+    # The sandbox bootstrap passes --max-tasks 0 explicitly; still 0.
+    assert resolve_max_tasks(0, "wave-1") == 0
+
+
+def test_explicit_cap_is_honored_with_wave():
+    # An explicit cap wins even when a wave is scoped.
+    assert resolve_max_tasks(2, "wave-1") == 2
+
+
+def test_explicit_is_honored_without_wave():
+    assert resolve_max_tasks(5, None) == 5
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `uv run pytest tests/test_resolve_max_tasks.py -q`
+Expected: FAIL — `ImportError: cannot import name 'resolve_max_tasks' from 'steerdev_agent.runner'`.
+
+- [ ] **Step 3: Implement the helper**
+
+In `src/steerdev_agent/runner.py`, add this function immediately ABOVE `def resolve_merge_flow(` (around line 139), as a module-level function:
+
+```python
+def resolve_max_tasks(max_tasks: int | None, wave_id: str | None) -> int:
+    """Resolve the effective --max-tasks for a run.
+
+    - An explicit value (including 0 = unlimited) always wins.
+    - Unspecified (None) with a wave scope → 0 (unlimited): a wave run pulls
+      every task of the wave, then stops. This makes a bare
+      `steerdev run --wave-id X` behave like the sandbox's
+      `steerdev run --wave-id X --max-tasks 0`.
+    - Unspecified (None) with no wave scope → 1 (the historical single-task
+      default).
+    """
+    if max_tasks is not None:
+        return max_tasks
+    return 0 if wave_id else 1
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `uv run pytest tests/test_resolve_max_tasks.py -q`
+Expected: PASS (5 passed).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/steerdev_agent/runner.py tests/test_resolve_max_tasks.py
+git commit -m "feat: add resolve_max_tasks (--wave-id implies unlimited)"
+```
+
+Note: the repo pre-commit runs ruff, basedpyright, and an auto version bump. If ruff reformats, re-add and re-commit. If basedpyright complains about the new function, fix the typing (signature is fully annotated, so it should pass). The version-bump hook modifying a version file is expected — let it include that change.
+
+---
+
+## Task 2: Wire `resolve_max_tasks` into the `run` CLI command
+
+**Files:**
+- Modify: `src/steerdev_agent/cli.py` (the `run` command — the `max_tasks` option definition ~line 1646-1652; the `max_tasks_display` line ~1824; the `run_agent(... max_tasks=max_tasks ...)` call ~1875)
+
+This task has no new unit test of its own (the logic is the Task 1 helper; the CLI wiring is thin glue). It is verified by a manual `--help`/dry-run check and the full suite.
+
+- [ ] **Step 1: Make the `--max-tasks` option nullable**
+
+In `src/steerdev_agent/cli.py`, find the `max_tasks` parameter in the `run` command (currently):
+
+```python
+    max_tasks: Annotated[
+        int,
+        typer.Option(
+            "--max-tasks",
+            help="Maximum number of tasks to process (default: 1, use 0 for unlimited)",
+        ),
+    ] = 1,
+```
+
+Replace it with:
+
+```python
+    max_tasks: Annotated[
+        int | None,
+        typer.Option(
+            "--max-tasks",
+            help=(
+                "Maximum number of tasks to process (default: 1, or unlimited "
+                "when --wave-id is set; use 0 for unlimited)"
+            ),
+        ),
+    ] = None,
+```
+
+- [ ] **Step 2: Import and call `resolve_max_tasks`**
+
+In `src/steerdev_agent/cli.py`, the `run` command already imports from the runner at the top of its body:
+`from steerdev_agent.runner import run_agent`.
+Change that import to also bring in the helper:
+
+```python
+    from steerdev_agent.runner import resolve_max_tasks, run_agent
+```
+
+Then, BEFORE the `console.print(Panel(...))` banner block (i.e. before the `max_tasks_display` line ~1824), add:
+
+```python
+    resolved_max_tasks = resolve_max_tasks(max_tasks, wave_id)
+```
+
+- [ ] **Step 3: Use `resolved_max_tasks` in the banner**
+
+Change the display line (~1824) from:
+
+```python
+    max_tasks_display = "unlimited" if max_tasks == 0 else str(max_tasks)
+```
+
+to:
+
+```python
+    max_tasks_display = "unlimited" if resolved_max_tasks == 0 else str(resolved_max_tasks)
+```
+
+- [ ] **Step 4: Use `resolved_max_tasks` in the run_agent call**
+
+In the `run_agent(...)` call (~line 1875), change:
+
+```python
+                max_tasks=max_tasks,
+```
+
+to:
+
+```python
+                max_tasks=resolved_max_tasks,
+```
+
+- [ ] **Step 5: Verify the CLI resolves correctly (dry run + help)**
+
+Run these and read the "Max Tasks" line in the Starting panel (use `--dry` so nothing executes; `--project-id x` satisfies the required arg):
+
+```bash
+uv run steerdev run --project-id x --wave-id w1 --dry 2>&1 | grep -i "max tasks"
+```
+Expected: `Max Tasks: unlimited`
+
+```bash
+uv run steerdev run --project-id x --dry 2>&1 | grep -i "max tasks"
+```
+Expected: `Max Tasks: 1`
+
+```bash
+uv run steerdev run --project-id x --wave-id w1 --max-tasks 2 --dry 2>&1 | grep -i "max tasks"
+```
+Expected: `Max Tasks: 2`
+
+If `--dry` exits before printing the panel or requires more args, instead run `uv run steerdev run --help` to confirm the `--max-tasks` help text now mentions "unlimited when --wave-id is set", and rely on Task 1's unit tests + the full suite for the resolution logic. Report which verification path you used.
+
+- [ ] **Step 6: Run the full suite + type check**
+
+Run: `uv run pytest -q`
+Expected: all pass (the new 5 tests included; no regressions).
+
+Run: `uv run basedpyright src/steerdev_agent/cli.py src/steerdev_agent/runner.py`
+Expected: no new errors. (`max_tasks` is now `int | None`; `resolved_max_tasks` is `int`, matching `run_agent`'s `max_tasks: int` param — so no type error at the call site.)
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add src/steerdev_agent/cli.py
+git commit -m "feat: steerdev run --wave-id pulls the whole wave by default"
+```
+
+(Pre-commit ruff/basedpyright/version-bump as in Task 1.)
+
+---
+
+## Task 3: Full verification
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Full test suite**
+
+Run: `uv run pytest -q`
+Expected: all pass.
+
+- [ ] **Step 2: Lint + format check**
+
+Run: `uv run ruff check . && uv run ruff format --check .`
+Expected: clean. If format check fails, run `uv run ruff format .`, then `git add -A && git commit -m "chore: ruff format"`.
+
+- [ ] **Step 3: Type check (whole package)**
+
+Run: `uv run basedpyright`
+Expected: no NEW errors introduced by this change. (Pre-existing errors elsewhere, if any, are out of scope — report them but don't fix.)
+
+---
+
+## Notes for the implementer
+
+- **Why nullable:** Typer can't distinguish "user typed `--max-tasks 1`" from "default 1" if the default is `1`. Making it `None` lets `resolve_max_tasks` apply the wave-aware default only when the user didn't specify.
+- **`run_agent` is unchanged:** it still takes `max_tasks: int` where `0` means unlimited (`runner.py`: `self.max_tasks = max_tasks if max_tasks != 0 else None`). We only change what value the CLI computes and passes.
+- **Sandbox bootstrap is unaffected:** it passes `--max-tasks 0` explicitly, which `resolve_max_tasks(0, waveId)` returns as `0` — identical to today.
+- **Do NOT** change `runner.py`'s loop, `run_agent`'s signature, or the server. Scope is the helper + the CLI wiring only.
+- **Version-bump hook:** committing in this repo auto-bumps a version file via pre-commit. That extra change landing in your commit is expected; don't fight it.

steerdev-1.1.14/docs/superpowers/specs/2026-06-05-wave-id-implies-unlimited-max-tasks-design.md

@@ -0,0 +1,130 @@
+# `steerdev run --wave-id` should pull the whole wave (imply unlimited max-tasks)
+
+**Date:** 2026-06-05
+**Status:** Design — awaiting review
+**Scope:** `steerdev-agent` CLI only (`cli.py` option resolution). No server change.
+
+## Problem
+
+`steerdev run --wave-id <id>` is meant to "process every task of a specific wave,
+then stop" (its own `--wave-id` help text). But `--max-tasks` defaults to `1`, and
+the run loop is governed solely by `max_tasks` (`runner.py`: `tasks_remaining =
+self.max_tasks`; `0 → None → unlimited`). So a bare `steerdev run --wave-id X`
+runs exactly **one** task and exits — contradicting the help text and surprising
+the user.
+
+Today the only way to get whole-wave behavior is `steerdev run --wave-id X
+--max-tasks 0`, which the sandbox bootstrap passes explicitly. A human running it
+locally must remember `--max-tasks 0`.
+
+## Goal
+
+`steerdev run --wave-id X` (no `--max-tasks`) pulls **the whole wave** — the run
+process requests the wave's next task from `/api/v1/tasks/next?wave_id=…` after
+each one, until the wave is exhausted (404 → stop). This is the SAME behavior as
+the sandbox; local and sandbox `run --wave-id` are identical. An explicit
+`--max-tasks N` still caps the run if the user wants.
+
+## Key context: one shared behavior, local or sandbox
+
+`steerdev run --wave-id` is a single code path. The run process is the puller:
+it loops `get_next_wave(wave_id=…)` and executes each task. The only difference
+between environments is who starts it and whether anything is pre-seeded:
+
+- **Sandbox:** the dispatch seeds the first task as a Run row (for tracking), then
+  the VM runs `steerdev run --wave-id --max-tasks 0` which pulls the rest.
+- **Local CLI:** nothing is dispatched; the human runs `steerdev run --wave-id X`
+  and it starts pulling from the first task immediately.
+
+Standalone (no `--agent-id`) works: the server's no-agent path
+(`getNextWaveTask(projectId, waveId)`) returns the wave's next task without
+conflict-claiming, and the runtime marks each task `started` itself, so the
+state-ordered selection advances correctly on each pull.
+
+## Design
+
+Distinguish "user gave `--max-tasks`" from "default" by making the option
+nullable, then resolve the effective value with a pure helper.
+
+### 1. Make `--max-tasks` nullable in `cli.py:run`
+
+Change:
+```python
+max_tasks: Annotated[int, typer.Option("--max-tasks", help="...default: 1...")] = 1,
+```
+to:
+```python
+max_tasks: Annotated[
+    int | None,
+    typer.Option(
+        "--max-tasks",
+        help="Maximum number of tasks to process (default: 1, or unlimited when --wave-id is set; use 0 for unlimited)",
+    ),
+] = None,
+```
+
+### 2. Pure resolution helper
+
+In `runner.py` (next to the other pure resolvers like `resolve_merge_flow`),
+add:
+```python
+def resolve_max_tasks(max_tasks: int | None, wave_id: str | None) -> int:
+    """Resolve the effective --max-tasks.
+
+    - Explicit value (incl. 0 = unlimited) wins.
+    - Unspecified + a wave scope → 0 (unlimited): a wave run pulls the whole wave.
+    - Unspecified + no wave scope → 1 (the historical single-task default).
+    """
+    if max_tasks is not None:
+        return max_tasks
+    return 0 if wave_id else 1
+```
+
+### 3. Use it in `cli.py:run`
+
+Before the `run_agent(...)` call, resolve:
+```python
+resolved_max_tasks = resolve_max_tasks(max_tasks, wave_id)
+```
+Pass `max_tasks=resolved_max_tasks` to `run_agent`, and use `resolved_max_tasks`
+for the `max_tasks_display` panel line (so the "Max Tasks: unlimited" banner is
+correct).
+
+`run_agent`/`AgentRunner` are unchanged — they still take a concrete `int`
+(`0 → unlimited` as today).
+
+## Behavior matrix (after change)
+
+| Command | Effective max_tasks | Result |
+|---|---|---|
+| `run --wave-id X` | 0 (unlimited) | whole wave |
+| `run --wave-id X --max-tasks 0` | 0 | whole wave (sandbox bootstrap; unchanged) |
+| `run --wave-id X --max-tasks 2` | 2 | first 2 wave tasks then stop |
+| `run` (no wave) | 1 | one task (unchanged) |
+| `run --max-tasks 0` (no wave) | 0 | unlimited single-task queue drain (unchanged) |
+| `run --task-id T` | (loop breaks after 1 by `_target_task_id` guard) | one task (unchanged) |
+
+## Tests
+
+Pure unit tests for `resolve_max_tasks` (in `tests/`, e.g. `test_runner_merge_modes.py`
+style or a new `test_resolve_max_tasks.py`):
+- `resolve_max_tasks(None, "wave-1") == 0` (wave + unspecified → unlimited)
+- `resolve_max_tasks(None, None) == 1` (no wave + unspecified → 1)
+- `resolve_max_tasks(0, "wave-1") == 0` (explicit 0 honored)
+- `resolve_max_tasks(2, "wave-1") == 2` (explicit cap honored, even with a wave)
+- `resolve_max_tasks(5, None) == 5` (explicit honored, no wave)
+
+(The CLI wiring + display are thin and covered by the helper; no full CliRunner
+test required, matching the repo's pure-resolver test pattern.)
+
+## Out of scope
+
+- No server change. No sandbox dispatch change (it already passes `--max-tasks 0`
+  explicitly, which `resolve_max_tasks` honors unchanged).
+- The sandbox bootstrap can KEEP passing `--max-tasks 0` (explicit, still correct)
+  or later drop it (now redundant) — not required by this change.
+
+## Decisions to confirm in review
+
+1. Unspecified `--max-tasks` + `--wave-id` → unlimited (0). (The core ask.)
+2. The historical no-wave default stays `1` (unchanged single-task behavior).

{steerdev-1.1.6 → steerdev-1.1.14}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "steerdev"
-version = "1.1.6"
+version = "1.1.14"
 description = "Backend task runner for steerdev.com - orchestrates CLI coding agents with activity reporting"
 readme = "README.md"
 authors = [

{steerdev-1.1.6 → steerdev-1.1.14}/src/steerdev_agent/api/tasks.py

@@ -108,6 +108,7 @@ class TasksClient(SteerDevClient):
         self,
         project_id: str | None = None,
         agent_id: str | None = None,
+        wave_id: str | None = None,
     ) -> dict[str, Any] | None:
         """Fetch the next task with wave-aware scheduling.
 
@@ -117,6 +118,11 @@ class TasksClient(SteerDevClient):
         When agent_id is provided, the server uses conflict-aware scheduling
         to avoid assigning tasks that overlap files with in-flight tasks.
 
+        When wave_id is provided, scheduling is scoped to that wave: the server
+        returns tasks only from that wave and a 404 (→ None) once it is
+        exhausted, so the caller's loop stops instead of bleeding into another
+        wave or an unrelated task.
+
         Returns either:
         - A wave response dict (has "wave" and "context" keys) with full wave context
         - A plain task dict (no wave keys) when no waves exist for the project
@@ -125,6 +131,7 @@ class TasksClient(SteerDevClient):
         Args:
             project_id: Filter by project ID. Falls back to STEERDEV_PROJECT_ID env var.
             agent_id: Agent ID for conflict-aware scheduling.
+            wave_id: Scope scheduling to a single wave (sandbox wave dispatch).
 
         Returns:
             Wave response, plain task, or None.
@@ -136,6 +143,8 @@ class TasksClient(SteerDevClient):
             params["project_id"] = effective_project_id
         if agent_id:
             params["agent_id"] = agent_id
+        if wave_id:
+            params["wave_id"] = wave_id
 
         console.print(f"Fetching next task from {self.api_base}/tasks/next")
         response = self.get("/tasks/next", params=params)

{steerdev-1.1.6 → steerdev-1.1.14}/src/steerdev_agent/cli.py

@@ -1644,12 +1644,15 @@ def run(
         ),
     ] = None,
     max_tasks: Annotated[
-        int,
+        int | None,
         typer.Option(
             "--max-tasks",
-            help="Maximum number of tasks to process (default: 1, use 0 for unlimited)",
+            help=(
+                "Maximum number of tasks to process (default: 1, or unlimited "
+                "when --wave-id is set; use 0 for unlimited)"
+            ),
         ),
-    ] = 1,
+    ] = None,
     timeout: Annotated[
         int | None,
         typer.Option(
@@ -1745,6 +1748,16 @@ def run(
             help="Run a specific task by ID (bypasses queue/wave scheduling)",
         ),
     ] = None,
+    wave_id: Annotated[
+        str | None,
+        typer.Option(
+            "--wave-id",
+            help=(
+                "Process every task of a specific wave, then stop. Scopes wave "
+                "scheduling to this wave (used by sandbox wave dispatch)."
+            ),
+        ),
+    ] = None,
 ) -> None:
     """Run the agent for a project!
 
@@ -1766,7 +1779,7 @@ def run(
         steerdev run --project-id abc123 --workflow-id wf-abc123
         steerdev run --config custom.yaml --project-id abc123
     """
-    from steerdev_agent.runner import run_agent
+    from steerdev_agent.runner import resolve_max_tasks, run_agent
 
     # Get config from context (loaded in app callback)
     config: SteerDevConfig = ctx.obj or SteerDevConfig()
@@ -1811,9 +1824,11 @@ def run(
     dry_run_status = "enabled" if dry_run else "disabled"
     waves_status = "enabled" if waves else "disabled"
     canals_status = "enabled" if canals else "disabled"
-    max_tasks_display = "unlimited" if max_tasks == 0 else str(max_tasks)
+    resolved_max_tasks = resolve_max_tasks(max_tasks, wave_id)
+    max_tasks_display = "unlimited" if resolved_max_tasks == 0 else str(resolved_max_tasks)
     workflow_status = resolved_workflow_id or "auto (per-task)"
     agent_name_display = agent_name or "(auto from env)"
+    wave_scope_display = wave_id or "(all waves)"
 
     console.print(
         Panel(
@@ -1826,6 +1841,7 @@ def run(
             f"Timeout: {resolved_timeout}s\n"
             f"Workflow: {workflow_status}\n"
             f"Waves: {waves_status}\n"
+            f"Wave Scope: {wave_scope_display}\n"
             f"Canals: {canals_status}\n"
             f"Worktrees: {worktree_status}\n"
             f"Evidence: {evidence_status}\n"
@@ -1860,7 +1876,7 @@ def run(
                 agent_name=agent_name,
                 model=resolved_model,
                 max_turns=resolved_max_turns,
-                max_tasks=max_tasks,
+                max_tasks=resolved_max_tasks,
                 timeout_seconds=resolved_timeout,
                 enable_waves=waves,
                 enable_canals=canals,
@@ -1872,6 +1888,7 @@ def run(
                 branch_config=resolved_branch_config,
                 task_id=task_id,
                 agent_id=agent_id,
+                wave_id=wave_id,
             )
         )
 

{steerdev-1.1.6 → steerdev-1.1.14}/src/steerdev_agent/runner.py

@@ -136,6 +136,22 @@ def extract_task_and_wave_context(
     return wave_response, None, suggested_workflow_id
 
 
+def resolve_max_tasks(max_tasks: int | None, wave_id: str | None) -> int:
+    """Resolve the effective --max-tasks for a run.
+
+    - An explicit value (including 0 = unlimited) always wins.
+    - Unspecified (None) with a wave scope → 0 (unlimited): a wave run pulls
+      every task of the wave, then stops. This makes a bare
+      `steerdev run --wave-id X` behave like the sandbox's
+      `steerdev run --wave-id X --max-tasks 0`.
+    - Unspecified (None) with no wave scope → 1 (the historical single-task
+      default).
+    """
+    if max_tasks is not None:
+        return max_tasks
+    return 0 if wave_id else 1
+
+
 def resolve_merge_flow(
     waves_enabled: bool,
     canals_enabled: bool,
@@ -288,6 +304,7 @@ class Runner:
         shutdown_event: asyncio.Event | None = None,
         agent_id: str | None = None,
         task_id: str | None = None,
+        wave_id: str | None = None,
     ) -> None:
         """Initialize the runner.
 
@@ -310,6 +327,9 @@ class Runner:
             dry_run: If True, print the command without executing it.
             retry_config: Retry configuration for failed tasks.
             agent_id: Database agent ID for conflict-aware scheduling.
+            task_id: Run a single specific task (bypasses queue/wave scheduling).
+            wave_id: Scope scheduling to a single wave; the loop processes every
+                task of that wave and stops when it is exhausted.
         """
         self.project_id = project_id
         self.working_directory = Path(working_directory or Path.cwd())
@@ -336,6 +356,7 @@ class Runner:
         self._enable_canals = enable_canals
         self._agent_id = agent_id
         self._target_task_id = task_id
+        self._target_wave_id = wave_id
 
         # State
         self._state = RunState.STOPPED
@@ -1144,6 +1165,7 @@ class Runner:
                                         client.get_next_wave(
                                             project_id=self.project_id,
                                             agent_id=self._agent_id,
+                                            wave_id=self._target_wave_id,
                                         )
                                     )
                                 )
@@ -1153,7 +1175,10 @@ class Runner:
                                     exc_info=True,
                                 )
 
-                        if not task:
+                        # When scoped to a wave, never fall back to single-task
+                        # mode — an empty wave response means the wave is done, so
+                        # the loop should stop rather than pull an unrelated task.
+                        if not task and not self._target_wave_id:
                             task = client.get_next_task(
                                 project_id=self.project_id,
                                 agent_id=self._agent_id,
@@ -1412,6 +1437,7 @@ async def run_agent(
     branch_config: BranchConfig | None = None,
     task_id: str | None = None,
     agent_id: str | None = None,
+    wave_id: str | None = None,
 ) -> dict[str, Any]:
     """Run the steerdev agent.
 
@@ -1461,6 +1487,7 @@ async def run_agent(
         branch_config=branch_config,
         task_id=task_id,
         agent_id=agent_id,
+        wave_id=wave_id,
     )
 
     # Install signal handler that kills the subprocess immediately on Ctrl+C

steerdev-1.1.14/tests/test_resolve_max_tasks.py

@@ -0,0 +1,27 @@
+"""Tests for resolve_max_tasks: --wave-id implies unlimited when --max-tasks is unset."""
+
+from steerdev_agent.runner import resolve_max_tasks
+
+
+def test_unspecified_with_wave_is_unlimited():
+    # Bare `steerdev run --wave-id X` → pull the whole wave (0 = unlimited).
+    assert resolve_max_tasks(None, "wave-1") == 0
+
+
+def test_unspecified_without_wave_is_one():
+    # Historical single-task default is preserved.
+    assert resolve_max_tasks(None, None) == 1
+
+
+def test_explicit_zero_is_honored_with_wave():
+    # The sandbox bootstrap passes --max-tasks 0 explicitly; still 0.
+    assert resolve_max_tasks(0, "wave-1") == 0
+
+
+def test_explicit_cap_is_honored_with_wave():
+    # An explicit cap wins even when a wave is scoped.
+    assert resolve_max_tasks(2, "wave-1") == 2
+
+
+def test_explicit_is_honored_without_wave():
+    assert resolve_max_tasks(5, None) == 5

steerdev-1.1.14/tests/test_wave_scoped_fetch.py

@@ -0,0 +1,60 @@
+"""Tests for wave-scoped task fetching (sandbox wave dispatch).
+
+`steerdev run --wave-id <id>` scopes scheduling to a single wave: the client
+passes `wave_id` to GET /tasks/next, and the server returns tasks only from that
+wave (404 → None once exhausted) so the run loop stops instead of bleeding into
+another wave or an unrelated task.
+"""
+
+from typing import Any
+from unittest.mock import MagicMock, patch
+
+import httpx
+
+from steerdev_agent.api.tasks import TasksClient
+
+
+def _make_response(
+    status_code: int,
+    json_body: dict[str, Any] | None = None,
+    text: str = "",
+) -> MagicMock:
+    resp = MagicMock(spec=httpx.Response)
+    resp.status_code = status_code
+    resp.text = text or (str(json_body) if json_body else "")
+    if json_body is not None:
+        resp.json.return_value = json_body
+    return resp
+
+
+class TestGetNextWaveScoping:
+    def test_wave_id_is_forwarded_as_param(self):
+        with TasksClient(api_key="test-key") as client:
+            mock_resp = _make_response(200, {"wave": {"id": "wave-1"}, "context": {}})
+            with patch.object(client, "get", return_value=mock_resp) as mock_get:
+                client.get_next_wave(
+                    project_id="proj-1",
+                    agent_id="agent-1",
+                    wave_id="wave-1",
+                )
+                params = mock_get.call_args.kwargs["params"]
+                assert params["wave_id"] == "wave-1"
+                assert params["waves"] == "true"
+                assert params["project_id"] == "proj-1"
+                assert params["agent_id"] == "agent-1"
+
+    def test_wave_id_omitted_when_not_scoped(self):
+        with TasksClient(api_key="test-key") as client:
+            mock_resp = _make_response(200, {"id": "task-1"})
+            with patch.object(client, "get", return_value=mock_resp) as mock_get:
+                client.get_next_wave(project_id="proj-1")
+                params = mock_get.call_args.kwargs["params"]
+                assert "wave_id" not in params
+
+    def test_exhausted_wave_returns_none_on_404(self):
+        # A wave-scoped request 404s once the wave is done — the loop stops.
+        with TasksClient(api_key="test-key") as client:
+            mock_resp = _make_response(404, text="No tasks available")
+            with patch.object(client, "get", return_value=mock_resp):
+                result = client.get_next_wave(project_id="proj-1", wave_id="wave-1")
+                assert result is None