feat(web): fully web-managed control plane via a DB command queue

Make credentials/hosts, projects, agents, and approvals manageable from the
dashboard. The API and control layer are separate containers, so the API can't
run control actions directly (no git/tmux/claude, doesn't own the tmux
sessions). Instead the API enqueues a command and a worker in the control
container executes it and writes the result back.

Data model (migration 0003):
- `commands` queue/audit table; `forge_hosts` registry; `approvals` gains a
  nullable approver id + `actor` so operator verdicts are first-class.

Control worker:
- `control/worker.py` claims commands and dispatches to the existing control
  functions (spawn/kill/resume/record_approval/write_skills/poller.sweep),
  plus a periodic CI sweep. New `handler worker` CLI subcommand; it becomes the
  control image's default command (subsumes `poll-ci --watch`).

API:
- `require_admin` gate + `ADMIN_TOKEN`; project GET/PATCH/DELETE; agent
  spawn/kill/delete; resume now enqueues (fixes a cross-container bug where the
  API tried to send tmux keys to a session in the control container); new
  approvals/commands/hosts routes; forge-init and poll-ci enqueue endpoints.

Credentials/hosts:
- host->token-env lookup consults the `forge_hosts` registry first (built-in
  map is the fallback); `resolve()` refactored to a scheme dispatch reserving
  `db:` for a future encrypted store. Web input restricts credential_ref to
  env:/file:/db: (cmd: stays CLI-only — it would run arbitrary commands).

Dashboard:
- New tabs for projects, agents (spawn/kill with live command-status polling),
  approvals, hosts, and an activity/audit view; shared context is now writable.

Tests: +33 (queue atomicity, worker dispatch, CRUD, hosts, admin gating,
cmd: rejection, host-aware credentials, and an API->queue->worker->spawn
end-to-end). README gains a Web management section.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01CrhrBToauu4L2qG6jdnuFP

tests/test_api_interaction.py

@@ -1,8 +1,9 @@
-"""Answer + resume routes, including the mocked control seam."""
+"""Answer + resume routes. Resume now enqueues a command for the control worker (the tmux
+session lives in the control container), so we assert on the queued command, not an
+in-process seam call."""
 
 from __future__ import annotations
 
-from handler.control import spawn
 from handler.db import repository as repo
 from handler.db.engine import get_engine
 
@@ -43,34 +44,29 @@ def test_answer_with_no_open_question_is_404(client, auth, env):
     assert r.status_code == 404
 
 
-def test_resume_calls_control_seam(client, auth, env, monkeypatch):
+def test_resume_enqueues_command_with_the_answer(client, auth, env):
     _seed_agent_with_question(env)
     client.post(
         "/projects/proj/agents/api/answer", json={"answer": "Postgres"}, headers=auth
     )
 
-    calls = []
-
-    def fake_resume(agent, answer):
-        calls.append((agent["name"], answer))
-        return True, "delivered"
-
-    monkeypatch.setattr(spawn, "resume", fake_resume)
-
     r = client.post("/projects/proj/agents/api/resume", json={}, headers=auth)
-    assert r.status_code == 200
-    assert r.json()["resumed"] is True
-    assert calls == [("api", "Postgres")]
+    assert r.status_code == 202
+    body = r.json()
+    assert body["type"] == "resume"
+    assert body["agent_name"] == "api"
+    assert body["status"] == "queued"
+    # The API resolves the stored answer and hands it to the worker via the payload.
+    assert body["payload"]["answer"] == "Postgres"
 
     with get_engine().begin() as conn:
-        a = repo.get_agent_by_name(conn, "proj", "api")
-        assert a["status"] == "working"
+        commands = repo.list_commands(conn, project_id="proj")
+        assert [c["type"] for c in commands] == ["resume"]
 
 
-def test_resume_without_answer_is_400(client, auth, env, monkeypatch):
+def test_resume_without_answer_is_400(client, auth, env):
     with get_engine().begin() as conn:
         repo.create_project(conn, "proj", "/tmp/proj")
         repo.create_agent(conn, "proj", "api", "/tmp/proj/api")
-    monkeypatch.setattr(spawn, "resume", lambda a, ans: (True, "x"))
     r = client.post("/projects/proj/agents/api/resume", json={}, headers=auth)
     assert r.status_code == 400

tests/test_api_web_management.py

@@ -0,0 +1,155 @@
+"""Web-management API surface: project/host CRUD, enqueue endpoints, and admin gating.
+
+The conftest sets AUTH_TOKEN=test-token and SHARED_CONTEXT_WRITE_TOKEN=shared-token with no
+ADMIN_TOKEN, so the effective admin token is the global test-token. The shared-token is a
+valid-but-not-admin bearer: it passes require_auth (reads) but not require_admin (writes),
+which is exactly what we use to prove the gate."""
+
+from __future__ import annotations
+
+import pytest
+
+
+@pytest.fixture
+def lowpriv(env):
+    """A valid bearer that is NOT the admin token (the shared-context write token)."""
+    return {"Authorization": f"Bearer {env['shared_token']}"}
+
+
+def _mk_project(client, auth, pid="proj"):
+    return client.post("/projects", json={"id": pid, "root_dir": "/tmp/proj"}, headers=auth)
+
+
+# --- project CRUD ---------------------------------------------------------------------
+
+
+def test_get_update_delete_project(client, auth):
+    _mk_project(client, auth)
+    assert client.get("/projects/proj", headers=auth).json()["id"] == "proj"
+
+    remote = "https://github.com/me/p.git"
+    r = client.patch("/projects/proj", json={"git_remote": remote}, headers=auth)
+    assert r.status_code == 200 and r.json()["git_remote"] == remote
+
+    assert client.delete("/projects/proj", headers=auth).status_code == 200
+    assert client.get("/projects/proj", headers=auth).status_code == 404
+
+
+def test_credential_ref_cmd_scheme_rejected(client, auth):
+    r = client.post(
+        "/projects",
+        json={"id": "x", "root_dir": "/tmp/x", "credential_ref": "cmd:cat /etc/passwd"},
+        headers=auth,
+    )
+    assert r.status_code == 422
+    # env:/file:/db: are accepted.
+    ok = client.post(
+        "/projects",
+        json={"id": "y", "root_dir": "/tmp/y", "credential_ref": "env:TOK"},
+        headers=auth,
+    )
+    assert ok.status_code == 201
+
+
+def test_patch_project_cmd_scheme_rejected(client, auth):
+    _mk_project(client, auth)
+    r = client.patch("/projects/proj", json={"credential_ref": "cmd:whoami"}, headers=auth)
+    assert r.status_code == 422
+
+
+# --- admin gating ---------------------------------------------------------------------
+
+
+def test_reads_allowed_but_writes_need_admin(client, auth, lowpriv):
+    _mk_project(client, auth)
+    # low-priv token can read...
+    assert client.get("/projects", headers=lowpriv).status_code == 200
+    assert client.get("/hosts", headers=lowpriv).status_code == 200
+    # ...but not perform admin actions.
+    patch = client.patch("/projects/proj", json={"root_dir": "/x"}, headers=lowpriv)
+    assert patch.status_code == 403
+    assert client.delete("/projects/proj", headers=lowpriv).status_code == 403
+    host = client.post("/hosts", json={"hostname": "h", "forge_type": "gitea"}, headers=lowpriv)
+    assert host.status_code == 403
+    spawn = client.post("/projects/proj/agents/spawn", json={"name": "j"}, headers=lowpriv)
+    assert spawn.status_code == 403
+
+
+# --- enqueue endpoints ----------------------------------------------------------------
+
+
+def test_spawn_enqueues_command(client, auth):
+    _mk_project(client, auth)
+    r = client.post(
+        "/projects/proj/agents/spawn",
+        json={"name": "junior", "role": "junior", "worktree": "feat/x", "task": "do it"},
+        headers=auth,
+    )
+    assert r.status_code == 202
+    body = r.json()
+    assert body["type"] == "spawn" and body["status"] == "queued"
+    assert body["agent_name"] == "junior"
+    assert body["payload"]["role"] == "junior" and body["payload"]["worktree"] == "feat/x"
+    # visible on the commands feed
+    assert any(c["id"] == body["id"] for c in client.get("/commands", headers=auth).json())
+
+
+def test_kill_enqueues_command(client, auth):
+    _mk_project(client, auth)
+    client.post(
+        "/projects/proj/agents",
+        json={"name": "api", "working_dir": "/tmp/proj/api"},
+        headers=auth,
+    )
+    r = client.post("/projects/proj/agents/api/kill", headers=auth)
+    assert r.status_code == 202 and r.json()["type"] == "kill"
+
+
+def test_approval_enqueues_correct_command_type(client, auth):
+    _mk_project(client, auth)
+    r = client.post(
+        "/projects/proj/approvals",
+        json={"branch": "feat/x", "status": "rejected", "note": "nit"},
+        headers=auth,
+    )
+    assert r.status_code == 202
+    # verdict 'rejected' maps to command type 'reject'
+    assert r.json()["type"] == "reject"
+    assert r.json()["payload"]["branch"] == "feat/x"
+
+
+def test_forge_init_and_poll_ci_enqueue(client, auth):
+    _mk_project(client, auth)
+    assert client.post("/projects/proj/forge-init", headers=auth).json()["type"] == "forge_init"
+    assert client.post("/projects/proj/poll-ci", headers=auth).json()["type"] == "poll_ci"
+    assert client.post("/poll-ci", headers=auth).json()["project_id"] is None
+
+
+def test_command_status_polling(client, auth):
+    _mk_project(client, auth)
+    cmd = client.post("/projects/proj/poll-ci", headers=auth).json()
+    got = client.get(f"/commands/{cmd['id']}", headers=auth)
+    assert got.status_code == 200 and got.json()["id"] == cmd["id"]
+    assert client.get("/commands/999999", headers=auth).status_code == 404
+
+
+# --- hosts ----------------------------------------------------------------------------
+
+
+def test_host_crud(client, auth):
+    r = client.post(
+        "/hosts",
+        json={"hostname": "git.corp", "forge_type": "gitea", "token_env_var": "GITEA_TOKEN"},
+        headers=auth,
+    )
+    assert r.status_code == 201
+    assert client.get("/hosts/git.corp", headers=auth).json()["token_env_var"] == "GITEA_TOKEN"
+    patch = client.patch("/hosts/git.corp", json={"base_url": "https://git.corp"}, headers=auth)
+    assert patch.status_code == 200
+    assert client.delete("/hosts/git.corp", headers=auth).status_code == 200
+    assert client.get("/hosts/git.corp", headers=auth).status_code == 404
+
+
+def test_host_bad_forge_type_422(client, auth):
+    r = client.post("/hosts", json={"hostname": "h", "forge_type": "svn"}, headers=auth)
+    assert r.status_code == 422

tests/test_credentials_hosts.py

@@ -0,0 +1,53 @@
+"""Host-aware credential resolution: the forge_hosts registry overrides the built-in map
+when a connection is supplied, and behaviour is unchanged when it isn't (regression)."""
+
+from __future__ import annotations
+
+from handler.control import credentials
+from handler.db import repository as repo
+from handler.db.engine import get_engine
+
+
+def test_registry_host_overrides_builtin_env_var(env):
+    with get_engine().begin() as conn:
+        repo.create_host(conn, "github.com", "github", token_env_var="CORP_GH_TOKEN")
+        e = credentials.credential_env("tok", "https://github.com/me/repo.git", conn)
+    # Registry wins over the built-in GITHUB_TOKEN mapping.
+    assert e["CORP_GH_TOKEN"] == "tok"
+    assert e["FORGE_TOKEN"] == "tok"
+    assert "GITHUB_TOKEN" not in e
+
+
+def test_registry_enables_self_hosted_host(env):
+    with get_engine().begin() as conn:
+        repo.create_host(conn, "git.corp.internal", "gitea", token_env_var="CORP_TOKEN")
+        e = credentials.credential_env("tok", "https://git.corp.internal/me/repo.git", conn)
+    assert e["CORP_TOKEN"] == "tok"
+
+
+def test_fallback_to_builtin_when_no_row(env):
+    with get_engine().begin() as conn:
+        e = credentials.credential_env("tok", "https://github.com/me/repo.git", conn)
+    # No forge_hosts row -> built-in map still applies.
+    assert e["GITHUB_TOKEN"] == "tok"
+
+
+def test_no_conn_behaviour_is_unchanged():
+    # The 2-arg form (no registry) must match the pre-existing built-in behaviour.
+    e = credentials.credential_env("tok", "https://github.com/me/repo.git")
+    assert e == {"FORGE_TOKEN": "tok", "GITHUB_TOKEN": "tok"}
+
+
+def test_credential_config_uses_registry_base_url(env):
+    with get_engine().begin() as conn:
+        repo.create_host(conn, "git.corp", "gitea", base_url="https://git.corp:8443")
+        key, value = credentials.git_credential_config("https://git.corp/me/repo.git", conn)
+    assert key == "credential.https://git.corp:8443.helper"
+    assert "$FORGE_TOKEN" in value
+
+
+def test_db_scheme_is_reserved_not_yet_resolvable():
+    import pytest
+
+    with pytest.raises(credentials.CredentialError, match="reserved"):
+        credentials.resolve("db:42")

tests/test_integration_web_spawn.py

@@ -0,0 +1,60 @@
+"""End-to-end web management: the dashboard's HTTP calls -> command queue -> worker ->
+real ``spawn.spawn`` -> tmux seam. Proves the full container-split flow works with only the
+tmux/claude boundary faked, not the control layer itself."""
+
+from __future__ import annotations
+
+from handler.control import worker
+from handler.db import repository as repo
+from handler.db.engine import get_engine
+
+
+def _spawnable_project(root):
+    root.mkdir(parents=True, exist_ok=True)
+    (root / ".mise.toml").write_text("[tasks.test]\nrun = 'pytest'\n")
+    with get_engine().begin() as conn:
+        repo.create_project(conn, "proj", str(root))
+
+
+def test_spawn_via_api_then_worker_creates_agent_and_session(client, auth, env, fake_tmux):
+    _spawnable_project(env["tmp"] / "proj")
+
+    # 1. The dashboard enqueues a spawn (202 + a queued command).
+    r = client.post(
+        "/projects/proj/agents/spawn",
+        json={"name": "api", "task": "build the thing"},
+        headers=auth,
+    )
+    assert r.status_code == 202
+    command_id = r.json()["id"]
+    assert r.json()["status"] == "queued"
+
+    # No agent yet — the worker hasn't run.
+    assert client.get("/projects/proj/agents", headers=auth).json() == []
+
+    # 2. The control worker drains the queue (runs the real spawn.spawn).
+    assert worker.drain("test-worker") == 1
+
+    # 3. The command is done and the agent + tmux session now exist.
+    got = client.get(f"/commands/{command_id}", headers=auth).json()
+    assert got["status"] == "done"
+    assert got["result"]["name"] == "api"
+
+    agents = client.get("/projects/proj/agents", headers=auth).json()
+    assert [a["name"] for a in agents] == ["api"]
+    assert fake_tmux["calls"]["new_session"][0]["name"] == "proj__api"
+
+
+def test_kill_via_api_then_worker(client, auth, env, fake_tmux):
+    _spawnable_project(env["tmp"] / "proj")
+    client.post("/projects/proj/agents/spawn", json={"name": "api"}, headers=auth)
+    worker.drain("w")
+
+    r = client.post("/projects/proj/agents/api/kill", headers=auth)
+    assert r.status_code == 202
+    worker.drain("w")
+
+    assert client.get(f"/commands/{r.json()['id']}", headers=auth).json()["status"] == "done"
+    assert "proj__api" in fake_tmux["calls"]["kill_session"]
+    with get_engine().begin() as conn:
+        assert repo.get_agent_by_name(conn, "proj", "api")["status"] == "done"

tests/test_repository_web.py

@@ -0,0 +1,85 @@
+"""DAL for web management: project/agent mutation, the command queue, and hosts."""
+
+from __future__ import annotations
+
+from handler.db import repository as repo
+
+
+def test_update_and_delete_project(conn):
+    repo.create_project(conn, "p", "/tmp/p", git_remote="https://github.com/me/p.git")
+    updated = repo.update_project(conn, "p", git_remote="https://gitea.corp/me/p.git",
+                                  credential_ref="env:TOK")
+    assert updated["git_remote"] == "https://gitea.corp/me/p.git"
+    assert updated["credential_ref"] == "env:TOK"
+    # An unknown field is ignored, not applied.
+    repo.update_project(conn, "p", nonsense="x")
+    assert repo.delete_project(conn, "p") is True
+    assert repo.get_project(conn, "p") is None
+
+
+def test_delete_agent_row(conn):
+    repo.create_project(conn, "p", "/tmp/p")
+    repo.create_agent(conn, "p", "api", "/tmp/p/api")
+    assert repo.delete_agent(conn, "p", "api") is True
+    assert repo.get_agent_by_name(conn, "p", "api") is None
+
+
+def test_enqueue_get_and_list_command(conn):
+    repo.create_project(conn, "p", "/tmp/p")
+    cmd = repo.enqueue_command(
+        conn, "spawn", project_id="p", agent_name="junior",
+        payload={"role": "junior"}, requested_by="operator:web",
+    )
+    assert cmd["status"] == "queued"
+    assert cmd["type"] == "spawn"
+    assert cmd["payload"] == {"role": "junior"}
+    assert repo.get_command(conn, cmd["id"])["agent_name"] == "junior"
+    assert [c["id"] for c in repo.list_commands(conn, project_id="p")] == [cmd["id"]]
+
+
+def test_claim_is_atomic_and_fifo(conn):
+    repo.enqueue_command(conn, "poll_ci")
+    second = repo.enqueue_command(conn, "poll_ci")
+
+    first_claim = repo.claim_next_command(conn, "worker-1")
+    assert first_claim["status"] == "running"
+    assert first_claim["claimed_by"] == "worker-1"
+
+    # Oldest-first: the second claim gets the later row, never the same one twice.
+    second_claim = repo.claim_next_command(conn, "worker-2")
+    assert second_claim["id"] == second["id"]
+    assert second_claim["id"] != first_claim["id"]
+
+    # Queue drained -> None.
+    assert repo.claim_next_command(conn, "worker-3") is None
+
+
+def test_finish_command_records_result(conn):
+    cmd = repo.enqueue_command(conn, "poll_ci")
+    repo.claim_next_command(conn, "w")
+    repo.finish_command(conn, cmd["id"], "done", result={"checked": 3})
+    done = repo.get_command(conn, cmd["id"])
+    assert done["status"] == "done"
+    assert done["result"] == {"checked": 3}
+    assert done["finished_at"] is not None
+
+
+def test_hosts_crud(conn):
+    created = repo.create_host(conn, "git.corp", "gitea", token_env_var="GITEA_TOKEN")
+    assert created["forge_type"] == "gitea"
+    assert repo.get_host(conn, "git.corp")["token_env_var"] == "GITEA_TOKEN"
+    repo.update_host(conn, "git.corp", base_url="https://git.corp")
+    assert repo.get_host(conn, "git.corp")["base_url"] == "https://git.corp"
+    assert [h["hostname"] for h in repo.list_hosts(conn)] == ["git.corp"]
+    assert repo.delete_host(conn, "git.corp") is True
+    assert repo.get_host(conn, "git.corp") is None
+
+
+def test_operator_approval_has_no_agent_and_lists(conn):
+    repo.create_project(conn, "p", "/tmp/p")
+    ap = repo.record_approval(conn, "p", "feat/x", "approved", actor="operator:web")
+    assert ap["approved_by_agent_id"] is None
+    assert ap["actor"] == "operator:web"
+    listed = repo.list_approvals(conn, "p")
+    assert [a["id"] for a in listed] == [ap["id"]]
+    assert repo.list_approvals(conn, "p", branch="other") == []

tests/test_worker.py

@@ -0,0 +1,126 @@
+"""The control worker: command dispatch + the claim/finish plumbing.
+
+Uses the same mock seams as the CLI tests (tmux/gitops/forge/spawn.resume) plus direct
+monkeypatching of spawn.spawn/kill so we exercise the worker's routing, not the full spawn
+machinery (already covered by test_control_spawn)."""
+
+from __future__ import annotations
+
+from handler.control import poller, spawn, worker
+from handler.db import repository as repo
+from handler.db.engine import get_engine
+
+
+def _seed_project(agent=None):
+    with get_engine().begin() as conn:
+        repo.create_project(conn, "p", "/tmp/p")
+        if agent:
+            repo.create_agent(conn, "p", agent, f"/tmp/p/{agent}", status="paused_for_input")
+
+
+def _enqueue(**kw):
+    with get_engine().begin() as conn:
+        return repo.enqueue_command(conn, **kw)
+
+
+def _get(cmd_id):
+    with get_engine().begin() as conn:
+        return repo.get_command(conn, cmd_id)
+
+
+def test_spawn_command_calls_spawn_and_records_result(env, monkeypatch):
+    _seed_project()
+    calls = {}
+
+    def fake_spawn(project_id, name, **kw):
+        calls.update(project_id=project_id, name=name, **kw)
+        return {"id": 42, "name": name, "working_dir": "/tmp/p/j", "forge_note": None}
+
+    monkeypatch.setattr(spawn, "spawn", fake_spawn)
+    cmd = _enqueue(
+        type="spawn", project_id="p", agent_name="j",
+        payload={"role": "junior", "worktree": "feat/x"},
+    )
+
+    assert worker.drain("w") == 1
+    done = _get(cmd["id"])
+    assert done["status"] == "done"
+    assert done["result"]["agent_id"] == 42
+    assert calls["project_id"] == "p" and calls["name"] == "j"
+    assert calls["role"] == "junior" and calls["worktree_branch"] == "feat/x"
+
+
+def test_kill_command_calls_kill(env, monkeypatch):
+    _seed_project("api")
+    killed = {}
+    monkeypatch.setattr(spawn, "kill", lambda p, n: killed.update(project=p, name=n))
+    cmd = _enqueue(type="kill", project_id="p", agent_name="api")
+
+    worker.drain("w")
+    assert _get(cmd["id"])["status"] == "done"
+    assert killed == {"project": "p", "name": "api"}
+
+
+def test_resume_command_feeds_answer_and_sets_working(env, monkeypatch):
+    _seed_project("api")
+    seen = {}
+
+    def fake_resume(agent, ans):
+        seen.update(name=agent["name"], ans=ans)
+        return True, "ok"
+
+    monkeypatch.setattr(spawn, "resume", fake_resume)
+    cmd = _enqueue(type="resume", project_id="p", agent_name="api", payload={"answer": "Postgres"})
+
+    worker.drain("w")
+    assert _get(cmd["id"])["status"] == "done"
+    assert seen == {"name": "api", "ans": "Postgres"}
+    with get_engine().begin() as conn:
+        assert repo.get_agent_by_name(conn, "p", "api")["status"] == "working"
+
+
+def test_approve_command_records_operator_verdict_with_head_sha(env, fake_gitops):
+    _seed_project("senior")
+    cmd = _enqueue(
+        type="approve", project_id="p", agent_name="senior", payload={"branch": "feat/x"}
+    )
+
+    worker.drain("w")
+    assert _get(cmd["id"])["status"] == "done"
+    with get_engine().begin() as conn:
+        ap = repo.get_latest_approval(conn, "p", "feat/x")
+    assert ap["status"] == "approved"
+    assert ap["actor"] == "operator:web"
+    assert ap["approved_by_agent_id"] is None
+    assert ap["approved_sha"] == fake_gitops["sha"]  # read from the agent's working dir
+
+
+def test_poll_ci_command_returns_summary(env, monkeypatch):
+    _seed_project()
+    summary = {"checked": 0, "resolved": 0, "pending": 0}
+    monkeypatch.setattr(poller, "sweep", lambda project_id=None: summary)
+    cmd = _enqueue(type="poll_ci", project_id="p")
+
+    worker.drain("w")
+    done = _get(cmd["id"])
+    assert done["status"] == "done"
+    assert done["result"] == {"checked": 0, "resolved": 0, "pending": 0}
+
+
+def test_bad_command_is_recorded_failed_not_raised(env):
+    # spawn with no agent name -> CommandError -> the worker records 'failed', keeps going.
+    _seed_project()
+    cmd = _enqueue(type="spawn", project_id="p")
+    assert worker.drain("w") == 1
+    failed = _get(cmd["id"])
+    assert failed["status"] == "failed"
+    assert "agent name" in failed["error"]
+
+
+def test_drain_processes_multiple_then_stops(env, monkeypatch):
+    _seed_project()
+    monkeypatch.setattr(poller, "sweep", lambda project_id=None: {"checked": 0})
+    _enqueue(type="poll_ci", project_id="p")
+    _enqueue(type="poll_ci", project_id="p")
+    assert worker.drain("w") == 2
+    assert worker.drain("w") == 0  # queue now empty