Implement Phase 4 Task 12: add --queue-db CLI arg and wire TaskQueue

Add --queue-db argument to the start subcommand so users can override the
queue database path without changing config. Priority: --queue-db > config
db_path > ~/.agent-harness/queue.db default. Update plan.md to mark Tasks
11, 12, 13 and Phase 4 checkpoint complete.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: coordt

docs/specs/02-messaging-update/plan.md

@@ -362,17 +362,17 @@ The `Dispatcher` constructor gains a `task_queue: TaskQueue` parameter.
 
 **Acceptance criteria:**
 
-- [ ] `dispatch()` calls `task_queue.enqueue()` with correct `TaskMessage` and `agent_url`
-- [ ] `dispatch()` sends `POST <agent_url>/task` with body `{"task_id": ...}` and returns 202
-- [ ] `dispatch()` does not await agent response or parse `DecisionMessage`
-- [ ] Nudge HTTP errors are logged and swallowed (fire-and-forget)
-- [ ] All synchronous response-parsing code is deleted
-- [ ] `Dispatcher.__init__` accepts `task_queue: TaskQueue`
+- [x] `dispatch()` calls `task_queue.enqueue()` with correct `TaskMessage` and `agent_url`
+- [x] `dispatch()` sends `POST <agent_url>/task` with body `{"task_id": ...}` and returns 202
+- [x] `dispatch()` does not await agent response or parse `DecisionMessage`
+- [x] Nudge HTTP errors are logged and swallowed (fire-and-forget)
+- [x] All synchronous response-parsing code is deleted
+- [x] `Dispatcher.__init__` accepts `task_queue: TaskQueue`
 
 **Verification:**
 
-- [ ] `uv run pytest --agent-digest=term tests/test_server.py`
-- [ ] `pre-commit run --all-files`
+- [x] `uv run pytest --agent-digest=term tests/test_server.py`
+- [x] `pre-commit run --all-files`
 
 **Dependencies:** Tasks 2, 6
 
@@ -399,17 +399,17 @@ Both tasks are cancelled cleanly on shutdown.
 
 **Acceptance criteria:**
 
-- [ ] `drain_loop` calls `drain_completed()` and passes each `(TaskMessage, DecisionMessage)` to
+- [x] `drain_loop` calls `drain_completed()` and passes each `(TaskMessage, DecisionMessage)` to
   `executor.execute()` and `memory.upsert_memory_summary()`
-- [ ] `drain_loop` wakes immediately when `drain_event` is set
-- [ ] `requeue_loop` calls `requeue_stale()` and `fail_exhausted(max_retries=config.queue.max_retries)`
-- [ ] Both tasks log structured events on each cycle
-- [ ] Both tasks are cancelled without error on SIGINT/shutdown
+- [x] `drain_loop` wakes immediately when `drain_event` is set
+- [x] `requeue_loop` calls `requeue_stale()` and `fail_exhausted(max_retries=config.queue.max_retries)`
+- [x] Both tasks log structured events on each cycle
+- [x] Both tasks are cancelled without error on SIGINT/shutdown
 
 **Verification:**
 
-- [ ] `uv run pytest --agent-digest=term tests/test_server.py`
-- [ ] `pre-commit run --all-files`
+- [x] `uv run pytest --agent-digest=term tests/test_server.py`
+- [x] `pre-commit run --all-files`
 
 **Dependencies:** Task 10
 
@@ -429,16 +429,16 @@ Add `--queue-db` CLI argument (overrides `config.queue.db_path`).
 
 **Acceptance criteria:**
 
-- [ ] `TaskQueue` is constructed with the resolved `db_path` and `claim_timeout_seconds`
-- [ ] `Dispatcher` receives the `task_queue` instance
-- [ ] `app.state.task_queue` and `app.state.drain_event` are set before the server starts
-- [ ] Default `db_path` is `~/.agent-harness/queue.db` when not set in config
-- [ ] Existing `--db` arg for `memory.db` is unchanged
+- [x] `TaskQueue` is constructed with the resolved `db_path` and `claim_timeout_seconds`
+- [x] `Dispatcher` receives the `task_queue` instance
+- [x] `app.state.task_queue` and `app.state.drain_event` are set before the server starts
+- [x] Default `db_path` is `~/.agent-harness/queue.db` when not set in config
+- [x] Existing `--db` arg for `memory.db` is unchanged
 
 **Verification:**
 
-- [ ] `uv run pytest --agent-digest=term tests/test_main.py`
-- [ ] `pre-commit run --all-files`
+- [x] `uv run pytest --agent-digest=term tests/test_main.py`
+- [x] `pre-commit run --all-files`
 
 **Dependencies:** Tasks 10, 11
 
@@ -457,17 +457,17 @@ Test the drain loop by injecting a mocked `drain_completed()` return and verifyi
 
 **Acceptance criteria:**
 
-- [ ] `dispatch()` test: `enqueue()` called with correct task + agent_url; nudge POST is fire-and-forget
-- [ ] `dispatch()` test: nudge HTTP error is swallowed and logged; no exception propagated
-- [ ] Drain loop test: `drain_completed()` returning one task → `executor.execute()` called once
-- [ ] Drain loop test: `drain_event` set → drain loop wakes immediately
-- [ ] Requeue loop test: `requeue_stale()` and `fail_exhausted()` called on schedule
-- [ ] No test directly touches `queue.db`
+- [x] `dispatch()` test: `enqueue()` called with correct task + agent_url; nudge POST is fire-and-forget
+- [x] `dispatch()` test: nudge HTTP error is swallowed and logged; no exception propagated
+- [x] Drain loop test: `drain_completed()` returning one task → `executor.execute()` called once
+- [x] Drain loop test: `drain_event` set → drain loop wakes immediately
+- [x] Requeue loop test: `requeue_stale()` and `fail_exhausted()` called on schedule
+- [x] No test directly touches `queue.db`
 
 **Verification:**
 
-- [ ] `uv run pytest --agent-digest=term tests/test_server.py`
-- [ ] `pre-commit run --all-files`
+- [x] `uv run pytest --agent-digest=term tests/test_server.py`
+- [x] `pre-commit run --all-files`
 
 **Dependencies:** Tasks 10, 11, 12
 
@@ -479,9 +479,9 @@ Test the drain loop by injecting a mocked `drain_completed()` return and verifyi
 
 ### Checkpoint: Phase 4
 
-- [ ] `uv run pytest --agent-digest=term` — all tests pass
-- [ ] Synchronous dispatch path is fully deleted from `server.py`
-- [ ] `pre-commit run --all-files` — clean
+- [x] `uv run pytest --agent-digest=term` — all tests pass
+- [x] Synchronous dispatch path is fully deleted from `server.py`
+- [x] `pre-commit run --all-files` — clean
 - [ ] Human review before proceeding
 
 ### Phase 5: Agent Update

foreman/__main__.py

@@ -60,6 +60,12 @@ def _build_parser() -> argparse.ArgumentParser:
         metavar="DB_PATH",
         help="Path to the SQLite memory database (default: ~/.agent-harness/memory.db)",
     )
+    start.add_argument(
+        "--queue-db",
+        default=None,
+        metavar="QUEUE_DB_PATH",
+        help="Path to the SQLite task queue database (default: ~/.agent-harness/queue.db)",
+    )
     start.add_argument(
         "--host",
         default="0.0.0.0",
@@ -147,7 +153,12 @@ def _run_start(args: Any) -> None:
     memory = MemoryStore(db_path)
 
     # 3. Create core components.
-    queue_db_path = config.queue.db_path if config.queue.db_path is not None else _DEFAULT_QUEUE_DB_PATH
+    if args.queue_db is not None:
+        queue_db_path = Path(args.queue_db)
+    elif config.queue.db_path is not None:
+        queue_db_path = config.queue.db_path
+    else:
+        queue_db_path = _DEFAULT_QUEUE_DB_PATH
     task_queue = TaskQueue(queue_db_path, claim_timeout_seconds=config.queue.claim_timeout_seconds)
     dispatcher = Dispatcher(config=config, memory=memory, task_queue=task_queue)
 

tests/test_main.py

@@ -143,6 +143,70 @@ def test_start_creates_dispatcher(self, tmp_path: Path, mocker) -> None:
 
         mock_dispatcher_cls.assert_called_once()
 
+    def test_start_creates_task_queue(self, tmp_path: Path, mocker) -> None:
+        """main() instantiates a TaskQueue and passes it to Dispatcher."""
+        config_path = tmp_path / "config.yaml"
+        _write_minimal_config(config_path)
+
+        mocker.patch("foreman.__main__.MemoryStore")
+        mocker.patch("foreman.__main__.GitHubPoller")
+        mocker.patch("foreman.__main__.Dispatcher")
+        mock_queue_cls = mocker.patch("foreman.__main__.TaskQueue")
+        mocker.patch("foreman.__main__.asyncio.run", side_effect=lambda c: c.close())
+
+        main(["start", "--config", str(config_path)])
+
+        mock_queue_cls.assert_called_once()
+
+
+# ---------------------------------------------------------------------------
+# --queue-db CLI argument
+# ---------------------------------------------------------------------------
+
+
+class TestQueueDbArg:
+    """--queue-db overrides config.queue.db_path for TaskQueue construction."""
+
+    def test_queue_db_arg_overrides_config_path(self, tmp_path: Path, mocker) -> None:
+        """--queue-db path is passed to TaskQueue when provided."""
+        config_path = tmp_path / "config.yaml"
+        _write_minimal_config(config_path)
+        custom_db = tmp_path / "custom_queue.db"
+
+        mocker.patch("foreman.__main__.MemoryStore")
+        mocker.patch("foreman.__main__.GitHubPoller")
+        mocker.patch("foreman.__main__.Dispatcher")
+        mock_queue_cls = mocker.patch("foreman.__main__.TaskQueue")
+        mocker.patch("foreman.__main__.asyncio.run", side_effect=lambda c: c.close())
+
+        main(["start", "--config", str(config_path), "--queue-db", str(custom_db)])
+
+        call_args = mock_queue_cls.call_args
+        assert (
+            call_args[0][0] == custom_db
+            or call_args.args[0] == custom_db
+            or call_args.kwargs.get("db_path") == custom_db
+        )
+
+    def test_queue_db_defaults_to_default_path_when_config_has_none(self, tmp_path: Path, mocker) -> None:
+        """TaskQueue uses _DEFAULT_QUEUE_DB_PATH when --queue-db is absent and config has no db_path."""
+        from foreman.__main__ import _DEFAULT_QUEUE_DB_PATH
+
+        config_path = tmp_path / "config.yaml"
+        _write_minimal_config(config_path)
+
+        mocker.patch("foreman.__main__.MemoryStore")
+        mocker.patch("foreman.__main__.GitHubPoller")
+        mocker.patch("foreman.__main__.Dispatcher")
+        mock_queue_cls = mocker.patch("foreman.__main__.TaskQueue")
+        mocker.patch("foreman.__main__.asyncio.run", side_effect=lambda c: c.close())
+
+        main(["start", "--config", str(config_path)])
+
+        call_args = mock_queue_cls.call_args
+        actual_path = call_args[0][0] if call_args[0] else call_args.kwargs.get("db_path")
+        assert actual_path == _DEFAULT_QUEUE_DB_PATH
+
 
 # ---------------------------------------------------------------------------
 # Helpers for container-related tests